本文例行收集各类应用中优秀 Skill 的设计原则、使用技巧、应用场景，以丰富大家的使用体验！

请收藏，文档每周都会刷新和维护！ 最新的更新信息：

版本：v1.03 更新：2026-08-07 收录：101

想象这样一个场景：

你请来了一位全能博士 OpenClaw，他知识渊博，非常聪明，但对你的小组、你的项目、你的公司一无所知。

而 Skills 就相当于你给他准备的"岗前培训手册"、“业务流程规范”，告诉这个博士，你们团队用什么技术栈、代码风格如何、如何部署项目……

有了这份手册，博士 OpenClaw 就能立刻进入状态，按照你们团队的做事方式快速开展。

1. Skill 结构回顾

Skill 包（技能包） 可以让智能体Agent（如 ClaudeCode、OpenCode、OpenClaw 等）学会某一特定领域的知识或工作流程，从而在处理相关任务时更专业、更高效。

是一种标准化的 AI 能力模块，本质是一个包含 SKILL.md 核心文件的文件夹，用于将特定任务的 SOP（标准作业程序）、知识、脚本和资源封装为可复用、可组合、可自动触发的单元。

AI Agent 的专项操作手册 + 执行工具包。AI Agent 的专项操作手册 + 执行工具包。纯文件、无服务、按需加载、跨平台、可组合。

1.0. Skill 发展

时间线回放

Skill 跟其他扩展机制的区别

先澄清一个常见混淆。一提到"让 AI 更聪明"，市面上有 5 种方案：

1.1. Skill 的核心结构

Skill技能包的目录结构，常见如下：

my-skill/    #（1）skill（包）根目录
├── SKILL.md    #（2）主文件（必须有），AI的大脑
|    ├── YAML头部    #(2.1) 决定 Skill 何时被触发
|    |    ├── name    # (2.1.1)
|    |    ├── description    # (2.1.2)
|    |    └── argument-hint    # (2.1.3)
|    ├── 角色设定    #(2.2)   
|    ├── 执行流程    #(2.3)
|    ├── 质量约束    #(2.4)
├── scripts/    #(3) 执行层（可选）：AI的手脚，用代码搞定确定性任务
├── assets/    #(4) 模板层（可选）：AI的素材库，骨架样式、图标、图片等静态资源。
├── references/    #(5) 知识层（可选）:AI的知识库，API文档、规则
├── templates/      # (6) 模板（可选）：AI的模具，输出模板（报告、代码、邮件）
|    ├──templates.md    #(6.1) 模板文件
├── examples/    # (7) 范例（可选）：AI的范例，输入/输出清晰展示示例（增强理解）
|    ├── examples-xx.md    #(7.1) 示例输出（可选）
├── hooks/     #(8) 约束与观测（可选）：记录调用、控制权限
└── _meta.json     # （9）可选：版本、作者、来源等元信息（管理用）

注：不同 Agent 的 Skill 结构稍有差别，但能兼容。以上蓝色为部分官方建议结构，但实际使用中可以自定义、优化和增强。

三层加载机制的官方定义在 Anthropic 的 SKILL Spec RFC 第 3.2 节。简化描述如下：

📣 三层加载不是 Anthropic 的工程小聪明，是 Skill 能在不爆上下文的前提下无限扩展的根本原因。description 决定 Skill 是否被看见，instructions 决定它是否被激活后做对事，resources 决定它能装下多少「重」内容而不污染 prompt。三者各司其职——这就是 Skill 区别于其他扩展机制的根本设计。

1.2. 加载原则/优先级

Skills 的逻辑很直接：在项目/或系统的目录下，集成一个 Skills 目录，里面写一个 SKILL.md 文件，告诉 Claude、OpenClaw 等智能体 Ahent 什么情况下该做什么，它会在合适的时机自动加载，你不需要每次重复提示。

Skill 在 Agent 中运作原理，请参考：【原理篇】理解 Skill 在 Agent 中运作原理，轻松实现 Skill 设计自由

不同的 Agent 定义的加载优先级稍微有区别：

skillpackage-SP-01：OpenClaw 加载规则

加载路径（优先级从高到低）：后写覆盖前写，优先级高的覆盖优先级低的。

1. <工作区>/skills（当前项目）
2. ~/.openclaw/skills（全局共享）
3. 内置 Skills（OpenClaw 默认）

skillpackage-SP-02：OpenCode 加载规则

加载路径（优先级从高到低）：

1. < 当前工作目录 >/.opencode/skills（当前项目级 Skill，仅作用于当前工作目录下的项目，优先级最高）
2. < 当前工作目录 >/.claude/skills（项目级兼容 Skill，兼容 Claude Code 格式的 Skill，优先级次之）
3. < 父目录 >/.opencode/skills（父目录项目 Skill，OpenCode 启动时会向上遍历父目录，加载所有符合条件的 Skill，优先级低于当前项目级）
4. < 父目录 >/.claude/skills（父目录兼容 Skill，优先级与父目录.opencode/skills 一致，按路径遍历顺序加载，后加载者覆盖先加载者）
5. \~/.config/opencode/skills（全局专属 Skill，适用于当前设备上所有 OpenCode 实例，优先级较低）
6. \~/.claude/skills（全局兼容 Skill，兼容 Claude Code 的全局 Skill，优先级最低）

skillpackage-SP-03：ClaudeCode 加载规则

加载路径（优先级从高到低）：

1. 通过--add-dir 参数指定的附加 Skill 目录（自定义共享 Skill 目录，可用于团队共享，优先级最高，需手动指定路径）
2. < 当前项目目录 >/.claude/skills（当前项目专属 Skill，仅在当前项目中生效，优先级次之）
3. \~/.claude/skills（用户级全局 Skill，适用于当前设备上所有 Claude Code 实例，跨项目生效，优先级较低）
4. 内置 Skills（Claude Code 默认自带 Skill，随软件安装一同部署，优先级最低）

skillpackage-SP-04：通用加载原则

• 所有 Agent 均遵循“同名覆盖”规则：若不同优先级路径中存在同名 Skill，优先级高的路径中的 Skill 会完全覆盖优先级低的，低优先级 Skill 不生效。
• 加载时均优先解析 SKILL.md 文件，仅包含该文件的目录会被识别为有效 Skill，缺失该文件的目录将被忽略。
• OpenCode、ClaudeCode 支持兼容加载，可共用部分格式规范的 Skill，无需重复开发。

Skill 包 = 标准化文件夹 + SKILL.md 核心指令 + 可选资源。它让 AI 从 “通用助手” 升级为 “领域专家”，一次编写，随处复用，是构建可靠 AI Agent 的核心单元。

1.3. Skill 设计原则

💡 要从"Agent 视⻆"写 Skill

大多数人写 Skill 的时候，脑子里想的是"我怎么给人解释这件事"。宝玉反复强调一个反直觉的操作——要从 Agent 的视角去写，不是从人的视角。

这个差异看起来微小，实际决定生死。

人视角的 Skill（错误示范）：

# 代码审查助手

这个 skill 帮你做代码审查。

## 怎么用

按需使用即可。

Agent 视角的 Skill（对的示范）：

---
name: code-review
description: Review code for bugs, style, and maintainability. 
  Use when: (1) user explicitly asks for code review, (2) user shares code 
  and says "look at this", (3) before any git commit / PR creation.
---

## Required Output Format

You MUST output a markdown table:

| File:Line | Severity | Issue | Suggested Fix |
| --- | --- | --- | --- |

Do NOT use prose. Do NOT use bullet lists. Use the table format above.

## Before You Start
1. Run `git diff HEAD` first to see what changed
2. If no diff, run `git log -5` to identify last 5 commits
3. Only review files that actually changed

两者的差异不是长度，是对"读者"的假设。

人写 Skill 时默认读者"会察言观色"——看到"按需使用"能自己推断什么是"按需"。Agent 不会。Agent 需要显式触发条件（when）、显式输出格式（MUST use table）、显式前置步骤（run git diff first）。

活案例 · emilkowalski/skill

2026 年 3 月出现的一个被低估的 skill——894 stars、1 个 SKILL.md、27KB。作者是 Sonner、Vaul、next-view-transitions 的作者 Emil Kowalski，React 设计工程圈的顶流。

他的 SKILL.md 里有一段让我停下来读三遍的东西：

## Review Format (Required)

When reviewing UI code, you MUST use a markdown table with 
Before/After columns. Do NOT use a list with "Before:" and "After:" 
on separate lines. Always output an actual markdown table like this:

| Before | After | Why |
| --- | --- | --- |
| `transition: all 300ms` | `transition: transform 200ms ease-out` 
  | Specify exact properties; avoid `all` |
| `transform: scale(0)` | `transform: scale(0.95); opacity: 0` 
  | Nothing in the real world appears from nothing |

注意几个细节：

1. Required 而不是 "recommended"——不给 Agent "看情况" 的余地
2. 示例 Before/After/Why 三列——强制结构
3. "Do NOT use prose"——明确排除 Agent 最容易堕落的回答方式（废话）
4. Nothing in the real world appears from nothing——给 "为什么" 附带可记忆的认知 anchor，帮 Agent 理解而不是死记

这份 SKILL.md 是"把人的 craft sensibility 翻译成 Agent 可读 enforce 规则"的经典样本。

skillpackage-PR-01：Skill 核心设计原则-单一、分层、清晰、明确、灵活、复用、工程化规范。

1. 单一职责：一个 Skill 专注完成一项任务。
2. 资源分层加载，SKILL.md 轻量化：元数据 → 指令 → 脚本 / 参考 / 资源（按需加载），复杂逻辑拆分到 scripts/、references/，大文档放 references/，保持 SKILL.md 简洁。
3. 清晰触发：description 精准描述何时调用。
4. 步骤明确：指令分步、可执行、无歧义。
5. 确定性脚本：重复 / 计算逻辑放入 scripts/，避免 AI 出错。
6. 确定性与灵活性分离：精确操作 →scripts/；判断生成 →SKILL.md
7. 可复用、可测试：示例 + 模板 + 脚本，独立验证、随处复用
8. 工程化规范：统一命名、目录结构、版本管理，团队协作友好

以下为持续积累的 Skill 写作技巧详细总结。

1.4. 公共技巧

如下是一些公共类的 Skill 设计技巧，可作为所有设计活动的参考

skillpackage-PR-02：单一职责优先原则

当开发一个综合性 AI 助手 Skill 时，需要处理多种不同类型的任务，优先将复杂的多功能 Skill 拆分为独立的专业 Skill。

每个 Skill 应该只负责一项特定功能，避免 "万能 Skill" 的设计。成功案例表明，将复杂功能拆分为专业 Skill 后，准确率可从 62% 提升到 90%。

💡原⼦化——⼀个 Skill 只做⼀件事，不要搞成⼤⽽全。但 ：原⼦化 ≠ 越短越好。

✅ 举例：开发一个客服系统需要同时处理订单查询、退货、产品咨询、投诉等功能的 Skill 时，

优先将复杂的多功能 Skill 拆分为独立的专业 Skill，如下：

• router-skill → 判断用户意图，派给对应的专家
• order-status-skill → 只管订单查询
• return-skill → 只管退货
• product-qa-skill → 只管产品咨询

这样做的好处是：

• 易于测试和维护
• 便于复用和分享
• 每个 Skill 的提示词都很简单，因为只需要处理一类问题
• 几天时间，准确率从 62% 提升到 90%

❌ 错误做法：

创建一个大而全的 "万能"Skill，试图一网打尽所有功能。

某电商平台客服 Agent 团队最初的做法是写一个包含订单查询、退货、产品咨询、投诉等所有功能的大 Skill，经过 80 多次迭代，3 周时间，团队凭感觉觉得 "挺好的"。

然后他们做了关键的事 —— 建了 100 个真实问题的评估集，实际准确率仅为 62%。

skillpackage--3：Skill 可传入参数，用 $ARGUMENTS 实现灵活输入

Skill 支持参数传入。你可以设计成：/test-case-design 需求描述 是直接输入文本，也可以是 /test-case-design 不加参数，让 Claude 主动问你要信息。

两种模式都支持，在 SKILL.md 里加一段判断：

## 输入处理

如果 $ARGUMENTS 不为空，直接基于它开始分析。
如果 $ARGUMENTS 为空，主动询问用户：
1. 要测试的功能是什么？
2. 有需求文档或接口文档吗？如果有，给我路径。
3. 有没有特别关注的测试维度？

当用户调用 /skill-name 时，可以传入参数，技能内用变量引用：

单参数示例

---
name: fix-issue
description: 修复 GitHub Issue
disable-model-invocation: true
---
 
修复 GitHub Issue #$ARGUMENTS，遵循以下步骤：
1. 阅读 Issue 描述
2. 分析根本原因
3. 实现修复
4. 编写测试
5. 提交代码

执行 /fix-issue 42 时，Claude 收到的指令变为 "修复 GitHub Issue #42，遵循以下步骤……"

多参数示例

---
name: migrate-component
description: 将组件从一个框架迁移到另一个框架
---
 
将 $0 组件从 $1 迁移到 $2。
保留所有现有功能和测试，不引入行为变更。

执行 /migrate-component SearchBar React Vue 时，Claude 收到："将 SearchBar 组件从 React 迁移到 Vue……"

skillpackage--4：给信息，别设限

Skill 会尽量遵循我们的指令，增大可重用性，指令太具体会限制适应性和重用性。

特别是给出的模板、示例等要求时，要注意限制度。

举例：

❌ 写一个”生成 API 文档“的 Skill 时，写死了输入输出格式、章节顺序、示例数量等太具体的要求，规定它必须怎么写（特殊情况除外）。

✅ 写一个”生成 API 文档“的 Skill 时，给出 API 的规范是什么”

skillpackage--5：拆解内容，用文件系统做渐进式披露

当设计一个包含大量专业知识的 Skill 时，如何让 AI 在需要时加载相关信息，而不是一次性加载所有内容。

借助于信息分层，做适当的层次化，不要把所有东西都塞进一个文件，大模型的上下文是有限的。

特别是有工具、接口、示例、附加信息、扩展信息等等情况下，尽可能的分层。

举例 1：

❌ 写一个”生成 API 文档“的 Skill 时，把所有相关的信息都塞进一个 Skill 里，文件有几 M 大。

✅ 写一个”生成 API 文档“的 Skill 时，强调要满足规范“，并把这个规范放进 References 下面。

举例 2：

✅ 当 Skill 包含大量内容时，设计加载机制以优化性能和用户体验。

技能使用三层加载架构，确保智能体只加载它们需要的内容：

• 触发阶段：当请求与技能描述匹配时，大模型加载完整的 SKILL.md 指令
• 执行阶段：仅在需要时，大模型读取额外的参考文件和脚本

这种渐进式披露是使 Agent Skills 灵活且可扩展的核心设计原则。

例如，品牌风格 Skill 的设计：

• 主文件只有基础配色和两行条件引用
• 创建演示文稿时 → 读 slide-decks.md
• 创建专业文档时 → 读 docs.md

做 PPT 不会被文档模板干扰，写文档不会加载 PPT 配色，两个场景互不污染，各自只用最小的上下文。

❌ 品牌风格 Skill 的设计：

将所有参考文档、脚本、模板都直接包含在 SKILL.md 中，导致文件大小超过 5000 词，加载时间增加 3-5 倍，用户体验严重下降。

一次性加载所有相关资源，导致初始加载时间过长。

举例 3：

❌ 错误做法：

某客服 Agent 在用户还没说第一句话之前，上下文就被塞了超过 2 万 tokens 的信息（完整知识库 8000 tokens、CRM 客户历史 5000 tokens、过往工单 4000 tokens、公司政策全文 3000 tokens），结果导致：

• 响应慢，成本高
• 经常答非所问
• 上下文窗口很快被填满(59)

一次性加载所有相关知识，导致上下文爆炸。

✅ 正确做法：

采用三层加载架构：

1. 元数据层（始终加载）— front matter 名称和描述决定技能是否激活
2. 指令层（激活时加载）— SKILL.md 主体包含核心工作流程
3. 资源层（按需加载）— 参考文件，根据任务上下文有条件地加载

例如，某客服 Agent 处理 Skill 设计：

• SKILL.md → 主入口，200 词左右，解决用户哪一类问题，清晰明确的列举
• reference.md → 高级参考文档，具体的场景
• forms.md → 用户意见的表单填写专项指南

SKILL.md 只有一个简单的概述和快速入门代码，然后写了关键的话："如果需要填写表单，读 forms.md"。

skillpackage--6：一致性原则**，一个 Skill 里，保持一致性的命名、格式、规范、术语等等

在整个 Skill 系统中保持一致的命名、格式和交互方式，提升用户体验的连贯性。

举例 1：

❌ 命名不规范或使用不一致的术语。

某团队在 Skill 开发中混用 "API endpoint"、"URL"、"API route"、"path" 等术语，导致 AI 理解混乱，行为不一致。

✅ 写一个 Skill 里，保持一致的命名、格式和交互方式，提升用户体验的连贯性：

1. 统一命名规范，使用短横线命名法（kebab-case）
2. 保持指令格式的一致性
3. 使用一致的术语和概念表达

Skill 命名必须遵循严格规则：

• 有效名称：git-release、docker-build、pr-review、test-123、my-cool-skill
• 无效名称：Git-Release（大写）、git\_release（下划线）、git release（空格）、-git-release（以短横线开头）、git-release-（以短横线结尾）、git--release（连续短横线）

除了 SKILL.md 文件内容风格要一致性外，相应的 scripts/references/assets/examples 等等，也要保持类似：多方拼凑的内容，需要开展检查或优化，不然导致准确率低下！

skillpackage--7：安全性原则，必须考虑安全性，防止恶意输入或意外操作造成的损害

在设计 Skill 时必须考虑安全性，防止恶意输入或意外操作造成的损害。

举例 1：

✅ 写一个 Skill 里，必须考虑安全性，防止恶意输入或意外操作造成的损害，如：

1. 使用 bash 时防止命令注入。
2. 实施最小权限原则。
3. 对敏感操作进行用户确认。

Anthropic 官方最佳实践强调：安全第一 - 使用 bash 时防止命令注入。

【极端情况】零信任架构的核心原则是 "永不信任，始终验证"：

• 每个 Skill 调用都必须经过身份验证和授权检查。
• 所有输入（包括用户输入、工具返回、第三方数据）都不可信。
• 只授予完成特定任务所需的最小权限。
• 所有操作都必须被记录和审计。

❌ 忽视安全防护，直接执行用户提供的命令或数据。

某生产环境的 AI Agent 在 4 天内用 Codex 构建了 29K 行代码，结果出现了凭证泄露、无声事件循环死亡等严重安全问题。

安全是 SKILL 的核心基本要求，不然导致严重安全问题！

skillpackage--8：性能优化原则，在保证功能完整性的前提下，通过技术手段优化 Skill 的执行性能

在设计 Skill 时必须考虑性能，防止执行效率低下。

举例 1：

✅ 写一个 Skill 里，常见的性能优化手段，举例 如：

1. 固定系统提示前缀，避免动态时间戳、随机 ID 导致缓存失效
2. 提示词压缩：用 "代码片段 + 问题描述" 的结构化提示，替代完整代码文件传输，Token 用量减少 60%
3. 智能路由：简单语法纠错用 Llama 3 8B，复杂功能开发用 GPT-4，成本降低 58%
4. 缓存策略：缓存常用函数示例、API 文档，查询响应速度提升 70%

❌ 忽视性能优化，导致执行效率低下。

某数据分析 Skill 每次执行都重新加载所有依赖库和数据，没有任何缓存机制，导致相同任务的执行时间是优化后版本的 10 倍。

skillpackage--9：版本控制原则，确保能够追踪变更历史和回滚到稳定版本

对 Skill 的开发过程进行版本控制，确保能够追踪变更历史和回滚到稳定版本。

举例 1：

✅ 正确做法，举例：

1. 使用 Git 进行版本控制
2. 为每个 Skill 创建独立的版本分支
3. 编写清晰的提交信息
4. 定期进行代码审查
5. ...

Anthropic 官方最佳实践强调：版本控制 - 使用 git 跟踪技能变更。

建议为每个 Skill 创建独立的 Git 仓库，或者在项目仓库中为 Skill 创建独立的目录结构，通过版本控制追踪所有变更历史。

❌ 没有版本控制，直接在生产环境中修改 Skill。

某团队直接在生产环境的服务器上修改 Skill 文件，没有任何版本控制，导致出现问题时无法回滚，也无法追踪问题产生的原因。

skillpackage--10：测试驱动原则，确保功能的正确性和稳定性

在 Skill 开发过程中实施全面的测试策略，确保功能的正确性和稳定性。

举例 1：

✅ 正确做法，举例：

1. 为每个 Skill 编写单元测试
2. 进行集成测试，验证 Skill 与其他组件的协作
3. 在生产部署前进行充分的测试
4. 建立自动化测试流程
5. ...

Anthropic 官方最佳实践强调：测试 - 在生产部署前始终测试技能。建议使用自动化测试框架对 Skill 进行全面测试，包括功能测试、边界测试、异常测试等。

❌ 没有测试或仅进行简单的手动测试。

某团队在开发一个关键业务 Skill 时，仅进行了简单的功能测试就部署到生产环境，结果在面对复杂输入时出现各种问题，导致业务中断。

skillpackage--11：Skill **约束条件写死，灵活空间留给输入

这项技巧的本质是在 Skill 内部固化 “规则与边界”，在运行时通过 “输入参数” 赋予 “弹性与变化”。

简单来说：

• 写死：把不可变的规则、阈值、标准、格式写死在代码或配置中（如 max_length=100、allowed_roles=["admin"]）。
• 留活：把会变的内容、个性化数据、外部变量，通过输入参数（Argument） 留给用户 / 调用方传递（如 --title "xxx"、--content "yyy"）。

这样做的最大价值是：Skill 不因为小变化而频繁改代码，保持高稳定性与复用性。

3 条黄金执行原则：

原则 1：凡是 “标准 / 底线”，写死；凡是 “内容 / 变量”，留输入**

• 写死（不可变）：业务规则、强制格式、权限白名单、阈值、错误码。
• 留活（可变）：用户输入、动态数据、时间戳、外部参数。

原则 2：参数化所有输入

• 在 SKILL.md 的 argument-hint 或脚本的 param() 中显式声明所有需要外部传入的变量。
• 禁止在脚本内部硬编码入参（除了常量）。

原则 3：约束集中管理

• 虽然写死，但不要分散写死。把所有常量 / 规则集中在一个文件或模块头部，便于统一修改。

案例 1：发送飞书 / 钉钉消息

❌ 把内容写死，把规则写活 → 灾难

脚本 send_msg.ps1（如下）

问题：

1. 想发 “内存已满”，得改代码。
2. 阈值 95 变了，得改代码。
3. AI 不知道该传什么，也没法编排。

# 糟糕！写死了消息内容，阈值写在逻辑里
# 每次想发不同消息都得改脚本
$webhook = "https://open.feishu.cn/xxx"
$msg = "磁盘已满！！！"  # 写死了，只能发这一条

# 规则写死在逻辑里，不灵活
if ($disk -gt 95) {
    Invoke-RestMethod -Uri $webhook -Body @{text=$msg}
}

✅ 正确做法，举例：规则写死，内容留输入

脚本 send_msg.py：（如下）

SKILL.md 调用方式：

执行流程：

1. 调用 scripts/get\_disk\_usage.py 获取值
2. 如果 > 95

→ 调用 scripts/send\_msg.py

--message "磁盘使用率已超限"

--value {{disk\_usage}}

优势：

• 换消息内容，不改脚本，只改输入。
• 改阈值，只改一处代码，不影响业务逻辑。

# 1. 规则写死（常量写在头部，集中管理）
WEBHOOK_URL = "https://open.feishu.cn/xxx"
ALERT_THRESHOLD = 95  # 阈值写死，不再变

# 2. 内容留输入（参数化）
parser = argparse.ArgumentParser()
parser.add_argument("--message", required=True, help="要发送的消息内容")
parser.add_argument("--value", required=True, type=int, help="当前检测值")
args = parser.parse_args()

# 3. 逻辑使用死规则 + 活输入
if args.value > ALERT_THRESHOLD:
    requests.post(WEBHOOK_URL, json={"content": args.message})

案例 2：生成报告（templates 结合）

❌ 把标题、作者写死

脚本（如下）

问题：

每天生成日报，标题都要改，脚本得天天改。

# 坏写法：报告标题写死
title = "2024年第一季度工作总结"
author = "张三"

# 读取模板
with open("templates/report.md", "r", encoding="utf-8") as f:
    content = f.read().replace("{{title}}", title).replace("{{author}}", author)

✅ 正确做法：把标题、作者留输入

脚本（如下）

SKILL.md 调用方式：

执行流程：

1. 调用 scripts/gen\_report.py

   --title "{{user\_input}}"

   --author "{{username}}"

优势：

传入什么标题，就生成什么报告，脚本永远不变。

# 好写法：规则写死（模板路径固定）
TEMPLATE_PATH = "templates/report.md"

# 输入留活
parser = argparse.ArgumentParser()
parser.add_argument("--title", required=True)
parser.add_argument("--author", required=True)
args = parser.parse_args()

# 读取
with open(TEMPLATE_PATH, "r") as f:
    content = f.read().replace("{{title}}", args.title).replace("{{author}}", args.author)

skillpackage-RE-01 ：Skill 自我迭代：把踩过的坑写进文件

💡Skill 应该具备自我迭代能力**。

翻译成人话：当 Agent 在某个任务上踩了坑，应该把这次踩坑的经验写回 Skill，下次不再踩。

这个看似简单，但 Hub 里真正这么做的 Skill 不到 3%。

活案例 · cclank/news-aggregator-skill

1,001 stars、Python、MIT license 缺失但代码质量高。这个 skill 的独特之处是——作者在 repo 根目录放了一个 MISTAKES.md，长达 6,319 字节。

内容摘录：

## 📌 Issue: WallStreetCN Timestamp Ambiguity (2026-01-24)

### 1. The Error
"OpenAI Revenue... 1h ago"（但实际事件 12h 前）

### 2. Root Cause
Data Loss: 把 Unix timestamp 转成 "HH:MM" 破坏日期信息。
Context Dependent: "09:35" 只在你知道是今天时有意义。

### 3. Fix
ALWAYS use full date-time format:
datetime.fromtimestamp(ts).strftime('%Y-%m-%d %H:%M')

### 4. Lesson
Don't format for "Human Readability" in the raw data layer. 
Let the UI decide how to display.

这份 MISTAKES.md 里有 7 个这样的 case，每个都是错误现场 → 根本原因 → 修复方案 → 预防教训的四段式结构。

这是真正的自我迭代——作者不只是修了 bug，还把 bug 的元信息写进 skill 能读到的地方。下次 Agent 处理 timestamp 时会看到这条规则，不再犯同样的错。

为什么这种做法很稀有

Hub Top 500 里，repo 根目录含有 MISTAKES.md、LESSONS.md、POSTMORTEM.md 这类文件的 skill 只有 14 个（2.8%）。其中 8 个是 fork 或模板，真正主动记录的只有 6 个。

为什么这么少？三个原因：

1. 反直觉：写 Skill 时大多数人想"展示成功"，不是"承认失败"
2. 看似无用：MISTAKES.md 不直接让 Agent 更聪明，是"第二阶元数据"
3. 要求作者有工程习惯：不是 vibe coder 能持续做的

但有意思的是——这 6 个主动记 MISTAKES 的 skill，平均 quality\_score 是 55.8，比 Top 500 整体平均（47.2）高 8.6 分。

样本小，但信号清晰：愿意写 MISTAKES.md 的作者，整体工程素养也更高。

这解释了为什么宝玉把 "自我迭代" 列为四条之一——它不是技术动作，是一种工程品性的外化。

2. SKILL.md 主文件

SKILL.md 是 skill（包）中的主文件，唯一必需文件，是 AI 的 “大脑”，是对本 skill 的导入性索引，定义技能名称、触发条件、执行步骤、输入输出、约束，让 Agent 知道有什么技能，AI 据此判断何时调用、如何执行。

Skill 设计理念：

「Skill 越多越好」 vs 「上下文越短越好」——这两件事天然冲突。

如果你只装 1 个 Skill，体验也许不错；装 10 个，每个都把完整 instructions 塞进 system prompt，模型还能扛；装 100 个，token 数直接爆炸——而且大多数 Skill 这次任务根本用不上。

这是一个看似无解的问题。直到三层渐进加载（three-stage progressive loading）方案出现，它的核心洞察很简单：

不是所有 Skill 内容都需要在每次对话开始时就被加载。Agent 只需要先看到「索引」，决定要不要展开「正文」，再在执行时按需 fetch「资源」。

这跟数据库设计里的「索引 vs 表」、跟 IDE 的「Lazy Loading」、跟操作系统的「Virtual Memory」是同一个思想——先描述，后加载。

但 Anthropic 的特殊在于：他们把这套机制烧进了 SKILL.md 的格式里，让所有作者必须遵守，于是这个分层加载变成了生态级的资产。

Hub 数据里的 SKILL.md 大小分布印证了这个设计——Top 500 中 86% 的 SKILL.md 体积在 5-30KB。这不是巧合：5KB 是「能装下 description + 简短 instructions」的下限，30KB 是「instructions 全部塞下还不爆 8K context window」的上限。

2.1. YAML元数据（头部/顶部）

KILL.md 文件第一部分为使用YAML*格式定义 的frontmatter（前言/头部）——决定 Skill 何时被触发。

name: test-case-design
description: >
  根据需求描述设计测试用例。综合运用等价类划分、
  边界值分析、场景法等方法，生成结构化的测试用例
  文档。当用户提到"设计用例""写测试用例""帮我
  出用例""测试点分析"时触发。
argument-hint: [需求描述或功能名称]
------
version: "2.1.0"
author: "Dev Team"
tags: ["办公", "PDF", "自动化"]

frontmatter（前言/头部）完整配置参考表：

2.1.1. name 技能名 章节

以关键字 name 为首定义的技能名称，唯一、清晰，格式如下：

name: test-case-design  # 短横线命名，小写

name--12：严格命名冲突，后写覆盖前写，优先级高的覆盖优先级低的

OC/CC 等启动时，会扫描所有可用的 Skills 的YAML元数据，记忆起来。后面有业务决策时会触发判断“这个请求该不该触发。严格遵守加载原则/优先级，不然失效。

2.1.2. description 章节

以关键字 description 为首定义的触发关键词（AI 匹配意图的核心），格式如下：

name: ...
description: >
  根据需求描述设计测试用例。综合运用等价类划分、
  边界值分析、场景法等方法，生成结构化的测试用例
  文档。当用户提到"设计用例""写测试用例""帮我
  出用例""测试点分析"时触发。
argument-hint: [需求描述或功能名称]

这里有个关键细节：description 写得好不好，直接决定 Skill 能不能被自动触发。

Agent 根据 description 来判断当前对话是否匹配这个 Skill。

所以你要把用户可能说的话都列进去——"设计用例""写测试用例""出用例"等等。

description 的原则：

•前置关键词：最重要的触发关键词放在最前面，因为超过 250 字符会被截断（不同 Agent 有差异）

•描述使用场景：明确说明"何时使用"，如 "当用户问……时使用"

•避免过于宽泛：太宽泛会导致技能频繁被触发，影响性能

description-SP-01：Description 长度在 80tokens内，过长会被截断

description 的 50 token 限制

Anthropic SDK 实际上对 description 字段有一个软限制：\~80 tokens（约 50 中文字 / 60 英文词）。超过会被截断展示给 Agent。这意味着 description 不只是一句话，是一句话能装下多少有用信号。

陷阱 1 · description 写成 instructions 的复制

🚯 最常见的错误：作者把 instructions 的第一段直接搬到 description 里。结果 description 长达 200+ token，被 SDK 截断后剩下的就是「碎片」。

修法：description 要重写，不能复制。它的功能跟 instructions 不⼀样——它是「⽬录条⽬」，不是 「正⽂摘要」。

description-PR-01：Description是触发器，写给"机器"看，要精准，列清触发词，简洁明了，避免模糊

OC/CC 等启动时，会扫描所有可用的 Skills 的 Description 字段，记忆起来。后面有业务决策时会触发判断“这个请求该不该触发这个 Skill"。

Description 要回答的是：什么时候用这个 Skill，而不是“这个 Skill 是做什么的”。

description 精准：用动词 + 名词，列清触发词，避免模糊

最经济的 description 公式：

[这个 Skill 解决什么问题] + [何时该激活] + [输出形态预告]

⚠️ description 写得不好，Skill 永远不会被打开，这句话决定了 Skill 的命运。

典型案例：

❌ 人类风的 description（来自 Hub uncategorized 类的常见样本）：

description: A helpful skill for code review

✅ Agent 风的 description（来自 emilkowalski/skill）：

description: |
  Review UI code for animation timing, transition smoothness,
  and motion design taste. ALWAYS use when the user shares
  React component code involving CSS transitions, framer-motion,
  view-transitions, or asks "review this animation".
  Output format: markdown table with Before/After/Why columns.

差别不在长度，在信息密度：

其他举例：

举例 1：避免模糊

❌ ”这是一个帮助生成周报的 Skill“

✅ ”当用户要求写周报、生成站报、输出工作汇报时触发“

举例 2：避免模糊

❌ ”处理文档“

✅ "提取 PDF 文本 / 表格、合并拆分、OCR 识别，用户说 PDF 时触发"。

举例 3：简洁明了，避免模糊

❌ 使用复杂的描述或包含过多技术细节。

某法律文档分析 Agent 的工具描述过于模糊：

• 工具 1: search\_docs-- "Search documents"
• 工具 2: get\_info -- "Get information"
• 工具 3: analyze-- "Analyze content"

这样的描述让 AI 无法准确判断何时使用哪个工具，导致准确率低下。

✅ Skill 的描述和指令需要让 AI 能够快速理解和执行，同时保持用户体验的简洁性：

1. 告诉模型做什么，不是如何成为 AI
2. 使用简洁的语言，避免冗余描述
3. 重点突出核心功能和使用场景

Anthropic 官方最佳实践强调：简洁明了 - 告诉模型做什么，不是如何成为 AI。

例如，一个优秀的 Git 提交信息生成 Skill 描述："Create consistent releases and changelogs. Use when committing code changes, writing commit messages, or formatting git history"。

Skill 描述要简洁，告诉模型做什么而不是如何做，使用用户实际会说的语言

举例 4：精准描述设计

❌ 错误示例：

• "A helpful skill for code quality"（过于模糊，没有触发短语）
• "Runs a Python script that parses AST and generates reports"（技术性过强，不是用户语言）
• "Code review"（太简短，缺乏上下文）

有效描述的模式：. Use when . .

✅ 优秀示例：

• "Create commit messages following Sentry conventions. Use when committing code changes, writing commit messages, or formatting git history"
• "Security code review for vulnerabilities. Use when asked to 'security review', 'find vulnerabilities', 'check for security issues', 'audit security', 'OWASP review'"

description-PR-02：能力边界清晰，Description 描述的触发范围容易判断

当设计需要与其他 Skill 或工具协作的 Skill 时，必须明确界定其职责边界。

举例 1：

✅ 正确做法：

每个 Skill 必须有明确的触发条件和退出条件：

• 明确该 Skill 应该处理什么任务
• 明确该 Skill 不应该处理什么任务
• 避免在其他 Skill 的子步骤中调用（除非明确需要）

❌ 错误做法：

职责边界模糊，导致多个 Skill 之间产生冲突或重复。

微软 Azure SRE 团队最初设计自动排查 Agent 时，创建了 100 多个工具和 50 多个子代理，结果超过 4 次代理间移交的操作几乎全部失败，编排器找不到深层的子代理，两个代理互相踢皮球，陷入无限循环。

description-PR-03：负样本，Description 明确说明不应该触发该 Skill 的情况

通过设计负样本来防止 Skill 被错误触发。

举例 1：

✅ 在 description 中包含负触发条件，明确说明不应该触发该 Skill 的情况。例如：

Process Excel files and generates reports. Use when working with spreadsheets.

Do not use for CSV files or database exports.

OpenAI 建议从 10-20 个提示词开始测试，覆盖以下几类场景：

• ✅ 显式调用：直接指定 Skill 名称
• ✅ 隐式调用：描述符合场景但不提名称
• ✅ 场景调用：加入业务背景的真实提示词
• ❌ 负样本：不应该触发这个 Skill 的请求

❌ 没有负样本设计，导致 Skill 被错误触发。

某 PDF 处理 Skill 因为描述过于宽泛，导致在处理 Word 文档时也被触发，造成错误的处理结果。

description-PR-04：多场景触发设计，Description 包含多种用户可能使用的触发短语和表达方式

设计能够适应多种用户表达方式的 Skill 触发机制。

举例 1：

✅ 在 description 中包含多种用户可能使用的触发短语和表达方式。

例如，一个安全审查 Skill 的描述应该包含：

"Security code review for vulnerabilities. Use when asked to'security review', 'find vulnerabilities', 'check for security issues', 'audit security', 'OWASP review'."

❌ 只包含单一触发短语，限制了 Skill 的使用场景。

某代码审查 Skill 的描述只写了 "Code review"，导致用户使用 "Review code" 或 "Check code" 等其他表达方式时无法触发该 Skill。

description-PR-05 ：description 不写“何时不该激活”

只写「何时激活」是新手错。专业的 description 也写「何时不要激活」。

例：

description: |
  Review TypeScript code for type-safety issues. Use when:
  reviewing .ts/.tsx files. Do NOT use when: file is .py/.go/.rs;
  or when user only asks about runtime errors (use debug-skill instead).

这条「Do NOT use when」给 Agent 一个主动放弃的合法理由，避免它在不擅长的场景硬接活。

2.2. instructions章节

Agent 处理 Skill 时的逻辑大致是：

对话启动
  ↓
扫描所有可用 Skill 的 description
  ↓
拼成一个「Skill 目录」放进 system prompt
  ↓
Agent 收到用户消息后，根据 description 判断
  「这个任务需要哪些 Skill 激活」
  ↓
对激活的 Skill 才加载完整 instructions（L2）

instructions：被激活之后才加载的「正文」

description 让 Skill 进入 Agent 的视野，instructions 决定它能不能把任务做漂亮。

instructions 的设计有 4 条普遍规律（基于 Hub Top 500 的 instructions 文本聚类得出）：

instructions-SP-01 : 必须在前 200 字内回答 5 个问题

Agent 加载 instructions 的第一段时，是先扫一眼判断「这个 Skill 真的能做我要的事吗」，没耐心看 5KB 才知道答案。所以前 200 字必须回答：

1. 这个 Skill 准确做什么（不是 description 那种概括）
2. 它的输入是什么（文件？文本？URL？）
3. 它的输出是什么（结构化 JSON？markdown 表？修改文件？）
4. 它有什么前置依赖（某个 CLI 工具？某个 API key？）
5. 失败时该怎么办（重试？fallback？ask user？）

Hub Top 500 里 74% 的 instructions 前 200 字至少答了其中 4 个问题。剩 26% 把这些答案散在 instructions 各处——这 26% 平均 quality\_score 低 6.8 分。

instructions-PR-01 : [instructions风格和作用是指导，决策树 > 散文

instructions 不是教程，是决策树。Agent 不需要你讲清楚「为什么要这样做」，需要你讲清楚「在 X 情况下做 Y」。

对比两段同主题的 instructions（来自不同的 code-review skill）：

❌ 散文版：

代码审查时应该综合考虑代码质量、可读性、性能、安全性等多个方面。
对于复杂的 PR，建议先理解整体架构再 deep-dive 细节。注释和命名也很重要。

✅ 决策树版：

1. If diff has > 200 lines:
     a. Run `git log -10 --oneline` for context
     b. Read CHANGELOG.md for in-flight features
     c. Skim full diff before scoring
2. For each changed file:
     a. If file has tests/ → check test diff first
     b. If file has SQL → MUST flag injection risks
     c. If file has any URL → MUST check for credential leaks
3. Severity rubric:
     CRITICAL: security issue / data loss
     HIGH: regression risk / wrong abstraction
     MED: style / naming / minor refactor
4. Output: table grouped by severity

Agent 处理「散文版」时会自由发挥；处理「决策树版」时会逐条执行，结果方差小一个数量级。

instructions-PR-02 : 把 anti-pattern 显式 ban 掉

Agent 比人更容易陷入 hallucination 模式（「我应该展示我的能力」），所以好的 instructions 会显式列出禁止动作。

Anthropic 官方 Skill 模板里有一段值得抄的范本：

## DO NOT

- Do NOT modify files outside the user's explicit request scope.
- Do NOT install npm packages without first asking permission.
- Do NOT run `npm test` if it's already known to be broken
  (check the user's last message for "tests are red" / "fix later").
- Do NOT make up file paths if you can grep for them instead.

这些规则单独看都是常识，但写在 instructions 里给了 Agent 不那么发挥的合法理由。

instructions-PR-03 : instructions 大小的 sweet spot 是 5-20KB

instructions < 2KB 的 SKILL.md 平均 quality 36.3，10-20KB 的 51.4，> 40KB 的 45.2。

instructions 太短信息不足，太长 Agent 难以全部 retain。5-20KB 是 Agent 能 fully retain + 行为收敛的范围。

instructions-PR-04 ：instructions把 resources应该装的内容硬塞进来

很多 Skill 把模板代码、查表数据、⻓示例都直接写进 SKILL.md 的 instructions，结果 instructions 体积膨胀到 50KB+，性能⽴刻下降。

修法：任何超过 1000 字的数据 / 模板，都搬到 resources/ ⾥，instructions 只留「在 X 情况下 fetch resources/Y」的指引。

2.3. 其他可用的属性

2.3.1. disable-model-invocation 技能描述

设为 true 时，只有你能手动触发，Claude 不会自动加载

2.3.2. user-invocable技能描述

设为 false 时，从 / 菜单隐藏，只由 Claude 自动调用

2.3.3. effort 技能描述

控制思考深度：可以为特定技能设置不同的思考强度，平衡速度和质量。

---
name: deep-review
description: 深度代码审查
effort: max
---

注意 max 级别仅 Claude Opus 4.6 可用。

2.3.4. paths 技能描述

按文件类型激活：让技能只在处理特定文件时才被激活，避免污染不相关的任务

---
name: react-patterns
description: React 最佳实践
paths: "**/*.tsx,**/*.jsx"
---
 
# 这个技能只在处理 React 文件时才会被 Claude 考虑加载

2.3.5. Shell 命令注入（动态上下文） 技能描述

使用 !command 语法，可以在技能被发送给 Claude 之前，先执行一段 Shell 命令，并将输出注入到技能内容中。

举例 1：内联注入

---
name: pr-summary
description: 总结当前 Pull Request 的变更
context: fork
allowed-tools: Bash(gh *)
---
 
## PR 上下文
- 变更差异：!`gh pr diff`
- PR 评论：!`gh pr view --comments`
- 修改文件：!`gh pr diff --name-only`
 
## 你的任务
请总结这个 PR 的主要变更、影响范围和潜在风险。

举例 2：多行命令注入

对于多行命令，使用 \`\`\`! 代码块：

## 运行环境
node --version
npm --version
git log --oneline -5

禁用 Shell 注入

管理员可以在设置中添加 "disableSkillShellExecution": true 来禁用此功能（适合安全敏感环境）。被禁用时，注入点会替换为 [shell command execution disabled by policy]。

⚠️ 重要区别

这不是 Claude 执行命令——而是 Claude Code 在发送技能给 Claude 之前预处理。Claude 只看到最终输出的文本，不知道有命令被执行过。

2.4. 角色设定

角色设定——让 AI 进入"测试工程师"模式

这一步很多教程不讲，但极其重要。不设定角色，AI 生成的用例会很泛、很"教科书"。

# 测试用例设计助手

你是一位资深测试工程师，擅长从需求中提取测试
点，并运用多种测试设计方法生成高覆盖度的用例。
你特别注重：
- 业务边界条件和异常路径
- 用户实际操作习惯和易错场景
- 接口参数校验和数据一致性

2.3. 执行流程

执行流程，这是 Skill 的灵魂，执行步骤是重点。

instructions--17：流程要有明确的"步骤感"

用"第一步""第二步"来组织，不要写成一大段散文。AI 执行有步骤的指令比执行散文描述稳定得多。

举例：

如下是产品研发测试活动的常规流程，在这里，你可以把测试方法论"编码"进去。

如下是一个样例，按照实际工作中的用例设计顺序来组织流程步骤：

## 执行流程

### 第一步：需求分析
1. 解析用户输入的需求描述（$ARGUMENTS）
2. 提取功能点、业务规则、输入输出
3. 识别隐含需求和边界条件
4. 列出需要澄清的模糊点（如果有）

### 第二步：测试设计方法选择
根据需求特征，选择适用的设计方法：
- 有输入范围 → 等价类划分 + 边界值分析
- 有多条件组合 → 判定表 / 因果图
- 有状态变化 → 状态迁移图
- 有业务流程 → 场景法
- 有大量参数组合 → 正交试验法

### 第三步：生成用例
每条用例必须包含：
| 字段 | 说明 |
| 用例ID | TC_模块_序号 |
| 优先级 | P0/P1/P2/P3 |
| 前置条件 | 执行前需要满足的状态 |
| 测试步骤 | 具体操作步骤 |
| 测试数据 | 具体的输入值 |
| 预期结果 | 明确可验证的结果 |
| 设计方法 | 用了什么方法得出的 |

instructions--18：可让 Skill 标注每条输出结果是什么设计方法，以便快速检查

在 AI 输出结果中，可以让 Skill 标注结果有生成过程用的方案或方法，以使人在最后检查/Review 结果质量时，能更系统化的判断。

举例：

如上面流程要有明确的"步骤感"场景中，在第三步的生成用例结果中，可以增加一个字段信息：

| 设计方法 | 用了什么方法得出的 |

🚯 踩坑经历：

前：AI 每次设计出来的用例，在人工检查时，一个一个的看，没有任何规律，分类跳来跳去，看的人发晕！最后，也检查不出几个遗漏。

后：增加 ”设计方法“字段后，人工检查，可一类一类的看，很容易发现遗漏点！

经验：一定要让 Skill 标注每条用例用的是什么设计方法。这样你在 review AI 生成的用例时，可以快速判断覆盖度——如果全是等价类没有边界值，说明边界场景漏了。

💡 此技巧，可应用在任何过程中，标注 这个结果 是用的前面哪个方案、方法、处理逻辑 得到的。

2.4. 质量约束

质量约束——防止 AI 偷懒

不加约束的话，AI 特别容易生成一堆"验证输入为空""验证超长字符"这种套路用例。你需要明确告诉它什么是好用例：

## 质量要求

- 正向用例和反向用例比例约 4:6
- 测试数据必须具体，不写"合法值"，写"张三"
- 预期结果必须可验证，不写"正确显示"，
  写"页面显示'登录成功'并跳转至首页"
- 必须覆盖：权限校验、并发场景、数据边界
- 合并重复场景，不凑数量

instructions--19：显性要求"xx 数据必须具体"，有助于结果的真实性

AI 在处理数据的过程中，有时会出现 “幻觉”，特别是在找不到结果的情况下，会“一本正经”的编造一些抽象的数据，若此时有约束显性要求"xx 数据必须具体"，AI 就会减少幻觉出现，找到真实数据，或为空。

🚯 踩坑经历：

前：AI 每次设计出来的用例，都是很抽象，感觉放哪都能用，不具体，不能指导具体场景的应用。

后：增加 约束就是在把你脑子里的"什么是好用例"的标准外化出来。我用下来发现，加了"测试数据必须具体"这一条之后，生成的用例实用性提升了一大截！

💡 此技巧，可应用在：任何过程中，输出结果很抽象，感觉放哪都能用，不具体，不能指导具体场景的应用。

3. resources资源

Skill 技能包中 主文件SKILL.md （包括name、description、instructions ）之外还有resources目录，它里面 装 如：

• 代码模板（ templates/api-client.ts ）
• 示例数据（ examples/sample-input.json ）
• ⼤型查表（ data/iso-currency-codes.csv ）
• 分步骤的更细 instructions（ steps/01-init.md 、 steps/02-config.md ）
• 测试⽤例（ tests/case-001.json
• ......

description（L1） 和 instructions（L2） 都是⽂本，resources（L3） 是 ⽂件。

一个真实例子 · Leon's taste-skill

Leonxlnx/taste-skill。它的 resources/ 结构是这样：

taste-skill/
├── SKILL.md                  (L1 + L2 → 21KB)
├── resources/
│   ├── easings.css           (CSS easing 常量)
│   ├── animation-timings.md  (按场景查表)
│   ├── color-palettes/       (不同风格的色板)
│   │   ├── minimalist.json
│   │   ├── brutalist.json
│   │   └── soft.json
│   └── reference-sites.md    (灵感参考)

SKILL.md 里只有这样的引用：

For specific easing curves, fetch resources/easings.css.
For palette by style, fetch resources/color-palettes/{style}.json.

Agent 在执行某个具体任务时（如「我要做一个 minimalist 风格的 hero section」），才会去 fetch resources/color-palettes/minimalist.json。SKILL.md 本身不携带这些数据，但又把它们组织得让 Agent 找得到。

这就是 resources 的优雅之处——Skill 可以做得很「重」，但运行时 Agent 实际加载的 prompt 仍然很「轻」。

💡 Skill 不是 Agent 唯一的扩展机制——还有 System Prompt、RAG、Tool Use、MCP Server 这 4 个常被混淆的概念。

5 个机制是互补的，不是竞争的。第 1 章讲过这五种的类比：

• System Prompt 是「永久人格」
• Tool 是「四肢」
• MCP 是「独立的手」
• RAG 是「百科全书」
• Skill 是「教练笔记」

Skill 的独特价值——把「该怎么做」分层组织——是其他 4 个都不具备的。System Prompt 没有按需加载；RAG 不带程序性知识；Tool/MCP 是动作而非方法论。

3.1. scripts/执行脚本

存放可执行代码（Python/Bash/Node），AI 按指令调用，不读源码、不占 token。

作用是针对特殊场景，处理精确、重复、易出错的任务，保证结果 100% 一致。

典型场景与示例：

数据处理

# scripts/extract_pdf.py
import pdfplumber
def extract_text(pdf_path):
    with pdfplumber.open(pdf_path) as f:
        return "\n".join([p.extract_text() for p in f.pages])

系统操作

# scripts/merge_pdf.sh
# 合并多个PDF
pdftk "$@" cat output output/merged_$(date +%Y%m%d).pdf

API 封装

# scripts/ocr_service.py
# 调用百度OCR识别扫描PDF
import requests
def ocr_scan(pdf_path):
    res=requests.post("https://ocr-api.com/recognize", files={"file": open(pdf_path,"rb")})
    return res.json().get("text")

scripts--21：代码规范原则，Scripts 脚本遵循统一的代码规范

在开发 Skill 时遵循统一的代码规范，确保代码的可读性和可维护性。

举例 1：

✅ 正确做法，举例：

1. 严格类型提示，使用 TypeScript 或类似静态类型系统
2. 使用数据类（Data Classes）或 Pydantic 进行内存优化
3. 使用上下文管理器和任务组实现安全并发
4. 包含全面的错误处理和日志记录
5. ...

例如，一个遵循最佳实践的 Python Skill 实现：

from pydantic import BaseModel
from typing import List, Dict
class SkillRequest(BaseModel):
    city: str
    date: str
  
async def run_weather_skill(request: SkillRequest) -> Dict:
    """获取指定城市的天气信息"""
    try:
        # 实现天气查询逻辑
        return {"temperature": "25°C", "condition": "Sunny"}
    except Exception as e:
        logger.error(f"天气查询失败: {e}")
        return {"error": "天气服务不可用"}

❌ 忽视代码规范，使用不规范的命名和结构。

某 Skill 开发中使用模糊的变量名（如 a、b、c），没有类型提示，错误处理不完整，导致后续开发者无法理解代码逻辑，维护成本极高。

scripts--22：Scripts 脚本职责要单一，1 脚本 = 1 功能，命名清晰

scripts/ 是 AI 的 “手脚”，只做确定性、可复用的动作：

• 每个脚本只做一件事，做完就退出
• 不混杂逻辑、不包办全套流程、不跨领域处理
• 方便：AI 调用、调试、替换、复用、排错

一句话：

一个脚本只实现一个原子能力，Skill 用编排把它们串起来。

应用案例：

## 执行流程
  1. 调用 scripts/get_system_info.ps1 获取信息
  2. 调用 scripts/json_extract_field.ps1 提取磁盘使用率
  3. 如果使用率 > 90%，调用 scripts/post_webhook.ps1 发送告警
  4. 调用 scripts/cleanup_temp_files.ps1 清理

💡 AI 只负责 “指挥”，scripts 只负责 “执行”。

scripts--24：Scripts 脚本参数化，支持命令行参数/配置，灵活复用

脚本参数化 = 把脚本里固定写死的值（路径、地址、阈值、名称等），全部抽成可外部传入的命令行参数 / 配置项。让脚本不写死、不绑定环境、可复用、可被 AI 精准调用。

💡 一句话：参数化 = 让脚本变成通用工具，而不是一次性代码。

3 条黄金规则（必须遵守）

1. ✅所有可变值必须参数化（路径、域名、端口、阈值、文件名、目标地址等）
2. ✅参数必须带类型、必选 / 可选、默认值、说明
3. ✅脚本只做一件事，参数只控制这件事的细节

举例 1：

❌ 案例 1：文件清理脚本（最常用）

未参数化（坏写法，写死路径、写死天数）

# 写死路径、写死天数 → 只能删这个目录，无法复用
Get-ChildItem "C:\temp" -Recurse -File | Where-Object {   # 写死路径
    $_.LastWriteTime -lt (Get-Date).AddDays(-7)     # 写死天数
} | Remove-Item -Force

✅ 参数化（好写法，AI 可随意调用）：

脚本如下：scripts/file/clean\_old\_files.ps1

AI 调用方式：

* clean\_old\_files.ps1 -Path "C:\\temp" -DaysOld 7
* clean\_old\_files.ps1 -Path "D:\\logs" -DaysOld 3
* clean\_old\_files.ps1 -Path "E:\\backup" -DaysOld 30 -Recurse \$false

<#
.SYNOPSIS
删除指定目录下超过指定天数的文件（单一职责+参数化）
#>

param(
    [Parameter(Mandatory=$true)]
    [string]$Path,          # 目标目录（必传）

    [Parameter(Mandatory=$true)]
    [int]$DaysOld,          # 超过 N 天删除（必传）

    [bool]$Recurse = $true  # 是否递归（可选，默认开启）
)

# 脚本逻辑完全通用
$cutoff = (Get-Date).AddDays(-$DaysOld)
Get-ChildItem $Path -File -Recurse:$Recurse | Where-Object {
    $_.LastWriteTime -lt $cutoff
} | Remove-Item -Force

Write-Host "已清理 $Path 下 $DaysOld 天前的文件"

scripts--25：结构化错误返回，Scripts 脚本错误处理，返回码 + 日志，AI 可判断成功/失败

设计统一的错误处理机制，让 AI 能够正确识别和处理各种错误情况。

举例 1：

✅ 永远不要让工具函数抛出异常，始终返回清晰的结构化对象：

这样做的好处是 AI 能够区分 "空数据" 和 "服务故障"，做出相应的处理。

如下实例代码参考：

async function get_weather({ city }) {
  try {
    const response = await fetch(`https://api.example.com/weather?city=${city}`);
    if (!response.ok) {
      return { error: `Weather API returned ${response.status}. Try again later.` }; #结构化
    }
    const data = await response.json();
    if (!data.current) {
      return { error: `No weather data found for "${city}".` };  #结构化
    }
    return {    #结构化
      city: data.location.name,
      temperature: `${data.current.temp_c}°C`,
      condition: data.current.condition.text
    };
  } catch (err) {
    return { error: `Could not reach weather service: ${err.message}` };  #结构化
  }
}

scripts--26：错误分类，Scripts 脚本根据错误类型设计不同的处理策略

根据错误类型设计不同的处理策略，提供合适的用户反馈。

根据错误类型返回不同的用户反馈：

💡 如果是用户可以修复的问题，告诉他们；如果是系统问题，隐藏技术细节，提供友好的错误信息。

scripts--27：重试机制设计，Scripts 脚本减少临时环境异常等可恢复的故障，提升可靠性

设计智能的重试机制，处理临时网络错误等可恢复的故障。

举例 1：

✅ 适用场景，临时环境异常，举例：

• 网络闪断（3 秒后重试可能成功）
• 服务过载（等待几秒后可能恢复）
• 限流错误（等待冷却时间后重试）

如下实例代码参考：

async function withRetry(fn, maxAttempts = 3, baseDelayMs = 500) {
  let lastError;
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    try {
      const result = await fn();
      if (result?.error && result?.retryable) throw new Error(result.error);
      return result;
    } catch (err) {
      lastError = err;
      if (attempt < maxAttempts) {
        const delay = baseDelayMs * Math.pow(2, attempt - 1);
        await new Promise(resolve => setTimeout(resolve, delay));
      }
    }
  }
  return { error: `Failed after ${maxAttempts} attempts: ${lastError.message}` };
}

scripts--28：优雅降级，有备选方案确保基本功能的可用性

当主要功能不可用时，Skill 需要有备选方案确保基本功能的可用性，为关键功能设计降级方案。

举例 1：

✅ 正确做法：

为每个关键功能设计降级方案：

1. 主要数据源故障时，尝试备用数据源
2. 备用数据源也失败时，提供降级响应
3. 明确告知用户当前处于降级模式

❌ 错误做法：

某监控系统 Agent 直接将 50K tokens 的原始监控数据塞给模型分析，当数据量过大时模型直接崩溃，没有任何降级处理机制。

没有降级方案，当主要功能失败时直接返回错误或让用户重试。

scripts--29：并行处理优化，提升整体执行效率

设计支持并行处理的 Skill 架构，提升整体执行效率。

举例 1：

✅ 具体做法，举例：

1. 识别可并行执行的任务，如：文件扫描时，可多文件处理
2. 使用任务组（Task Group）实现安全并发
3. 设计合理的并行度，避免资源竞争

例如，在处理多个文件时，可以并行读取和处理：

效果：

• 多文件处理速度提升 5-10 倍
• 资源利用率提高 80%
• 响应时间显著缩短(103)

async def process_files(files):
    async with asyncio.TaskGroup() as tg:
        tasks = []
        for file in files:
            tasks.append(tg.create_task(process_single_file(file)))
    return await asyncio.gather(*tasks)

scripts--30：让 Skill 读项目代码来补充上下文

这是 Claude Code Skill 比纯 ChatGPT 对话强的地方——它能读你的代码。在 SKILL.md 里加一段：

## 上下文增强（可选）

如果用户提供了接口路径或文件路径，用 Read
工具读取源码，提取：
- 参数校验规则（正则、长度限制等）
- 业务逻辑分支（if/else、switch）
- 异常处理逻辑（try/catch）
将这些信息作为补充输入，生成更精准的用例。

这意味着你可以这样用：/test-case-design 请根据 src/api/user.py 中的注册接口设计用例。Claude 会先读代码，再结合你的测试方法论来生成用例。这才是 AI 测试用例设计的正确打开方式——不是凭空生成，而是基于真实代码。

scripts--31：Scripts 脚本跨平台，优先 Python（跨系统）

Scripts 跨平台 = 同一份脚本代码，不修改、不兼容处理，就能在 Windows / macOS / Linux 三大系统直接运行。

在 Skill 架构中，优先用 Python 实现跨平台脚本，彻底告别：

• PowerShell 脚本只能 Windows 跑
• Shell 脚本只能 Linux/macOS 跑
• 同功能要写 2\~3 套代码
• AI 调用时要判断系统、分支执行

💡 Scripts 跨平台 【建议】 用 Python

1. 三大系统默认 / 极易安装现代 Windows/macOS/Linux 都自带或一键装 Python
2. 一套代码跑所有系统无需区分系统、无需写两套逻辑
3. AI 更容易调用统一命令：python script.py，不用区分 ps1 / .sh
4. 库极丰富文件、网络、系统、数据、通知全能搞定
5. 完全贴合 Skill 设计 Scripts = 执行层，跨平台 = 更强通用能力

一句话：Skill 要做到 “一处编写，全系统运行”，Scripts 建议 Python。

跨平台 Python 脚本 3 条黄金规则：

1. 不写死系统路径不用 C:\temp 或 /tmp，用 Python 标准库自动获取
2. 不用系统专属命令不用 dir / ls / ipconfig，用 Python 库实现
3. 路径分隔符自动适配用 os.path 或 pathlib，不手写 / 或 \

举例：

案例 1：跨平台创建临时目录：scripts/file/create\_temp\_dir.py

import tempfile
import os

def create_temp_dir():
    # 自动适配系统临时目录：C:\Users\xxx\AppData\Local\Temp 或 /tmp
    temp_dir = tempfile.mkdtemp(prefix="skill-task-")
    return temp_dir

if __name__ == "__main__":
    # 输出目录路径，供 AI/调用方获取
    print(create_temp_dir())

案例 2：跨平台清理旧文件（最常用）：scripts/file/clean\_old\_files.py

# 删除指定目录 N 天前的文件
import os
import time
import argparse

# 脚本参数化（Skill 必备）
parser = argparse.ArgumentParser(description="跨平台清理旧文件")
parser.add_argument("--path", required=True, help="目标目录")
parser.add_argument("--days", type=int, required=True, help="超过几天删除")
args = parser.parse_args()

# 跨平台时间计算
cutoff_time = time.time() - (args.days * 86400)

# 跨平台遍历文件
for root, dirs, files in os.walk(args.path):
    for file in files:
        file_path = os.path.join(root, file)
        if os.path.getmtime(file_path) < cutoff_time:
            os.remove(file_path)
            print(f"已删除: {file_path}")
  
 # 调用命令（全系统一样）
 python clean_old_files.py --path "./logs" --days 7

案例 3：跨平台获取系统信息：scripts/system/get\_system\_info.py

# 获取 OS、CPU、内存、磁盘
import platform
import sys
import os

def get_info():
    return {
        "system": platform.system(),       # Windows/Darwin(Linux)/Linux
        "version": platform.version(),
        "python": sys.version,
        "cpu_count": os.cpu_count(),
        "cwd": os.getcwd()
    }

if __name__ == "__main__":
    print(get_info())

案例 4：跨平台发送 Webhook 通知：scripts/notify/send\_webhook.py

# 发送消息到飞书 / 钉钉 / 企业微信
import requests
import argparse

parser = argparse.ArgumentParser()
parser.add_argument("--url", required=True, help="webhook 地址")
parser.add_argument("--msg", required=True, help="消息内容")
args = parser.parse_args()

# 跨平台发送请求
resp = requests.post(args.url, json={
    "msg_type": "text",
    "content": {"text": args.msg}
})

print("发送成功" if resp.status_code == 200 else "发送失败")

案例 5：跨平台路径拼接（绝对不能手写 \ 或 /）

import os

# 错误写法（不跨平台）
path = "logs\\2025"       # Windows 专用
path = "logs/2025"        # Linux/macOS 专用

# 正确写法（自动适配所有系统）
path = os.path.join("logs", "2025")

以上的执行流程

1. 调用 scripts/system/get\_system\_info.py 获取系统信息
2. 调用 scripts/file/create\_temp\_dir.py 创建临时目录
3. 业务处理...

4. 如果文件超过 7 天

   → 调用 scripts/file/clean\_old\_files.py --path "./logs" --days 7

5. 调用 scripts/notify/send\_webhook.py 发送完成通知

SKILL.md 里可以如上这样写（一套流程，全系统通吃）

3.2. assets/静态资源

存放输出所需静态文件（图片、字体、图标、样式、素材包），AI 不读取、只引用 / 复制。作用是提供输出素材，不占 token，保证结果完整性。

包里的内容，Agent 过程中 只读不解析：AI 只复制 / 引用，不理解内容。

典型场景与示例：

1. 品牌素材

   1. assets/logo.png（报告水印）
   2. assets/style.css（HTML 报告样式）

2. 模板素材

   1. assets/ppt_template.pptx（PPT 母版）
   2. assets/word_template.docx（Word 格式模板）

3. 项目脚手架

   1. assets/react-template/（React 项目模板）
   2. assets/api-server/（后端服务骨架）

assets--32：资源内聚原则，所有静态素材必须放进 assets，不许散放

assets 是 Skill唯一的静态资源出口，图片、样式、骨架、prompt 片段、固定模板等，统一收拢，不散落于 Skill 根目录、scripts、templates 中。

容易理解，不过多介绍了。

assets--33：静态纯粹原则 ，assets 只放 “静态”，不放代码、逻辑、脚本

assets = 死素材，不包含可执行逻辑、不包含业务代码、不包含配置。

容易理解，不过多介绍了。

assets--34：路径纯净原则，禁止绝对路径，禁止外部依赖

assets 内资源只使用相对路径，不依赖 Skill 目录以外的任何文件，保证 “拷贝即运行”。

❌ 不能出现：C:\xxx、D:\xxx、/home/user/xxx

❌ 不能引用网络资源当本地静态资源（除非明确是在线图床）

❌ 不依赖其他软件安装目录

容易理解，不过多介绍了。

assets--35：资目录结构化原则，按类型分文件夹，禁止平铺一堆文件

assets 内部必须按资源类型建子目录，不把几十张图、一堆文件直接扔 assets 根目录。

容易理解，不过多介绍了。

✅ 标准子目录建议：

• images/ 图片、图标、封面
• styles/ 样式、排版骨架、CSS、HTML 模板骨架
• prompts/ 系统提示词片段、角色文案
• templates/ 静态模板（与 templates/ 目录区分：这里是无逻辑纯素材）
• files/ 附件、样本文件、示例素材
• icons/ 小图标（可选）

assets--36：命名规范原则，英文、小写、短横线，无中文无空格无特殊字符

统一命名规则，保证跨平台、跨工具、AI 识别都不出错。

容易理解，不过多介绍了。

✅ 只用：小写字母、数字、短横线 -、下划线 _

❌ 禁止：中文、空格、()、&、%、#、 emoji

文件名见名知意

assets--37：路径固定，要用包中的**相对路径，增加移植兼容性

assets（静态资源层）：存放 Skill 运行所需的静态素材（图标、图片、模板骨架、样式文件、固定配置、prompt 片段、本地素材等）。

路径固定 + 包内相对路径：所有资源必须以 assets 目录为基准，用相对路径引用，绝不写死绝对路径（如 C:\xxx、/usr/xxx），确保 Skill 拷贝到任何电脑、任何目录都能直接运行，无路径报错。

3 条强制规则（必须遵守）：

1. 所有静态资源必须放在 assets/ 下，不许乱放
2. 引用路径永远以 Skill 根目录为基准格式：assets/文件夹/文件名
3. 代码中永远使用「相对路径」，禁止出现绝对路径

✅ 必须：assets/images/logo.png

❌ 禁止：C:\project\my-skill\assets\logo.png

案例：

如下是定义的 my-skill 包，其中 assets 资源调用写法如下：

my-skill/
├── SKILL.md
├── assets/                 # 固定根目录
│    ├── images/          # 图片、图标
│    │    ├── logo.png
│    │    └── cover.jpg
│    ├── styles/            # 样式、模板骨架
│    │    └── report.css
│    ├── prompts/         # 固定 prompt 片段
│    │    └── system.txt
│    └── files/              # 静态文件、素材
│         └── template.docx

# 角色设定
使用图标：assets/images/logo.png

# 执行流程
1. 读取骨架模板：assets/styles/report.css
2. 加载系统提示词：assets/prompts/system.txt
3. 使用封面图：assets/images/cover.jpg

assets--38：可复用原则，提取公共片段到 assets，避免多处复制粘贴

把多个 Skill、多个模板共用的素材，统一放到 assets 公共目录，实现一处修改、全局生效。

✅ 共用的素材，统一放到 assets 公共目录：

• 公共头部、公共底部
• 统一角色提示词
• 统一样式
• 统一图标

assets/styles/common.css

assets/prompts/common-role.txt

在 SKILL.md 或模板中引用：

使用公共样式：assets/styles/common.css

❌ 每个模板里都复制一遍相同 CSS、相同角色描述。

assets--39：轻量原则，不存放大文件、不存放可下载资源

assets 存放轻量素材，保证 Skill 体积小、加载快、移植快。

不存放如下举例：

• 不存放视频、大安装包、压缩包、镜像
• 不存放几百 MB 的模型文件
• 大文件放外部或单独仓库
• ... ...

✅ 可存放：

• 小图标
• 小封面图
• 文本片段
• 样式文件

❌ 不建议存放：

• assets/large-video.mp4
• assets/model.gguf
• assets/dataset.zip

assets--40：版本干净原则，不上传临时文件、缓存、垃圾文件

assets 只保留最终可用资源，不留过程文件、缓存、缩略图、草稿。

容易理解，不过多介绍了。

assets--41：assets 与 templates 目录严格区分（非常重要）

很多人会混淆：

• templates/：带结构、可填充变量、AI 输出用的完整模板
• assets/templates/：仅骨架、样式、片段，不直接输出

✅ 可存放：

• templates/report.md # 完整输出模板，有 {{var}}
• assets/styles/report.css # 仅样式素材

❌ 不建议存放：

• assets/完整报告模板.md # 不该放这
• templates/style.css # 不该放这

3.3. references/参考文档

references = 知识层：AI 的知识库、API 文档、规则、约束、标准、踩坑、参考资料

references 是 Skill 的只读知识层，统一存放业务规则、API 文档、标准、约束、踩坑教训；结构清晰、条目化、只放静态知识、与模板 / 资源分离、命名规范、便于 AI 理解与更新。

典型场景与示例：

1. API 文档

# references/pdf_api.md
## PDF 处理AP
- 提取文本：POST /api/pdf/extract
- 合并PDF：POST /api/pdf/merge
- 参数：file_path, password, pages
- 返回：code=0成功，msg=结果，data=文件路径

2. 规范标准

# references/naming_rules.md
## 输出文件命名规范
- 格式：{操作类型}_{日期}_{原文件名}
- 例：extract_20260405_report.pdf、merge_20260405_all.pdf
- 禁止：中文、空格、特殊字符（!@#$）

3. 数据结构

// references/schema.json
{"pdf_info": {
    "path": "string",
    "pages": "int",
    "encrypted": "bool",
    "size_mb": "float"
   }
 }

references--42：知识唯一入口原则，统一只放 references/，不散落别处

所有外部知识、业务规则、接口说明、标准、约束、禁忌、经验教训，统一只放 references/，不散落别处。

✅ 可存放：

AI 只需要从这里获取 “事实知识”

不让知识散落在 SKILL.md、scripts、templates 里

便于更新、版本管理、多人维护

如：

references/api.md

references/business-rules.md

references/lessons.md

references/standards.md

❌ 不建议存放：

SKILL.md 里写大段接口说明

scripts/ 里写业务规则注释

templates/ 里埋约束条款

根目录放一个 rules.txt

references--43：按需拆分，按主题分文件，不加载无关内容

按需拆分：按主题分文件（api.md、rules.md），不加载无关内容

my-skill/ 
├── 
├── references/
│   ├── api.md            # API规范
│   ├── rules.md          # 命名/约束
│   └── schema.json       # 数据结构

references--44：references/只放 “静态知识”，不放逻辑、模板、代码

references 是只读知识库，不放可执行内容、不放输出模板、不放脚本。

✅ 可存放：

接口文档

业务规范

数据字典

踩坑总结

标准格式要求

❌ 不建议存放：

不放 .py / .ps1 脚本

不放带变量的输出模板

不放配置文件、运行参数

如：

references/run.py

references/template.md

references/config.json

references--45：references 按领域拆分文件，不堆砌大杂烩

知识按主题 / 业务域 / 类型拆分成多个小文件，不要一个 ref.md 写所有内容。

✅ references/可存放：

api.md # 接口字段、调用方式

business.md # 业务规则

standards.md # 格式标准

pitfalls.md # 踩坑、禁忌、常见错误

faq.md # 常见问题

data-dict.md # 数据字典

❌ 不建议存放：

references/ref.md # 几千行，包含 API、规则、坑、示例、说明一锅炖

references--46：references 知识结构化、条目化，便于 AI 理解

知识不要写成散文，要条目化、清单化、表格化，AI 更容易检索与遵守。

✅ 建议举例：

用列表、表格、加粗关键词

每条知识只讲一件事

明确：规则 / 约束 / 允许 / 禁止

## 命名规则
- 文件名必须小写
- 不能使用中文和空格
- 分隔符统一用短横线 -

## 接口字段
- code: 状态码，0=成功
- message: 返回信息

❌ 不建议：

这个接口大概返回一些状态，成功一般是 0，文件名最好别用中文，不然可能会出问题……

references--47：references 文件 SKILL.md 只引用，不复制全文

SKILL.md 中不要大段粘贴 references 内容，只需引用路径。

✅ 建议举例：

业务规则参见 references/business-rules.md

接口字段参见 references/api.md

❌ 不建议：

SKILL.md 里复制几十行规则、接口说明，导致两份内容不同步。

容易理解，不过多介绍了。

references--48：“踩坑、禁忌、教训” 易错点积累，不重犯同样问题

犯过的错误、踩过的坑、不能做的事、历史教训、典型问题等等，统一归属 references。

要及时总结，随时更新进 Skill，不重犯同样问题。

references/目录 = 知识层（AI 的知识库），API 文档、规则、经验、约束、注意事项、禁忌、避坑点

my-skill/

├── SKILL.md

├── ...

├── references/ <-- 这里

│ ├── mistakes.md <-- 你犯过的错误

│ └── lessons.md <-- 你的踩坑总结、经验总结、避坑指南、历史教训

│ ├── rules.md <-- API 文档、规则、约束

├── templates/

├── examples/

├── hooks/

└── \_meta.json

举例：

输出 JSON 时字段顺序混乱：生成的 JSON 字段顺序每次都不一样。（问题一直重复发生）

输出 JSON 时字段顺序混乱：在references/rules.json 里提供标准格式。

references--49：references与 templates 严格分离，知识 ≠ 输出结构

两者区别：

references：AI 用来理解规则、查资料。不放带 {{变量}} 的模板

templates：AI 用来生成输出内容。不放业务规则说明

容易理解，不过多介绍了。

references--50：references与 assets 严格分离，知识 ≠ 静态素材

两者区别：

references：文字性知识、规则、文档。不放图片、不放样式、不放图标、不放多媒体。

assets：图片、样式、图标、prompt 片段等静态资源

容易理解，不过多介绍了。

references--51：references版本可追溯，每条重要规则可记录来源

关键业务规则、标准、接口变更，建议标注来源 / 版本 / 更新时间，便于回溯。

适合正式业务 Skill、工程类 Skill、合规类 Skill

# 业务规则 v2026-04-07
更新者：xxx
来源：业务需求文档 v3.2

1. 金额保留2位小数
2. 超时时间不得超过30s

references--52：references 禁止放运行时动态生成内容

references 是静态知识库，不存放运行时产生的日志、缓存、结果数据。

✅ 建议举例：

只放人工整理、固化下来的知识。

❌ 不建议：

不放运行日志

不放脚本输出结果

不放临时数据

如：

references/run.log

references/temp-result.json

references/cache.txt

容易理解，不过多介绍了。

references--53：references 文件名规范，英文小写、语义明确、无特殊字符

统一命名风格，便于 AI 调用、脚本读取、移植跨平台。

容易理解，不过多介绍了。

3.4. templates/样式模板

存放固定格式模板（Markdown/Word/HTML/ 代码），AI 填充数据生成结果。

templates = 模板层：AI 的输出模具，用于生成标准化结果（报告、文案、代码、邮件、表格等），作用是保证输出格式统一、合规、美观，无需 AI 重复排版。

典型场景与示例：

1. 报告模板

# templates/report.md# PDF 处理报告- 原文件：{{PDF_PATH}}
- 操作：{{ACTION}}
- 页数：{{PAGES}}
- 状态：{{STATUS}}
- 结果文件：{{OUTPUT_PATH}}
---## 内容摘要
{{CONTENT_SUMMARY}}

1. 代码模板

# templates/script_template.py
def {{FUNCTION_NAME}}({{PARAMS}}):
"""{{DESCRIPTION}}"""
try:
    # 执行逻辑
    {{CODE_BODY}}
    return {"code":0, "msg":"成功", "data":result}
except Exception as e:
    return {"code":1, "msg":f"失败：{str(e)}", "data":null}

1. 邮件模板

<!-- templates/email.html -->
<h3>PDF 处理完成</h3>
<p>您好，您的文件 {{PDF_NAME}} 已{{ACTION}}成功。</p>
<p>下载链接：<a href="{{DOWNLOAD_URL}}">点击下载</a></p>

templates--54：templates 只放 “输出用模板”，不放别的

templates 目录只存放最终输出结构模板，不掺杂知识、规则、素材、脚本。

模板 = 输出骨架，AI 往里填内容。

✅ 建议举例：

只放：输出格式模板（.md/.txt/.json/.html/.sql 等）

不放：业务规则、API 文档、图片、脚本、配置

不放：参考资料、踩坑记录、说明文档

如：

templates/

report.md

email.md

api\_response.json

sql\_query.tpl

❌ 不建议：

templates/

rules.md # 规则应放 references

logo.png # 图片应放 assets

run\_script.py # 脚本应放 scripts

templates--55：templates 变量占位符统一、标准化，便于 AI 识别

模板内使用统一风格的变量占位符，让 AI 清晰知道哪里需要填充、填充什么。

✅ 推荐统一格式：

• {{变量名}}
• {{section.子项}}
• 禁止随意格式、无标识文本

如：

# {{title}}
## 概览
- 时间：{{date}}
- 负责人：{{username}}
- 结果：{{result_summary}}

❌ 不建议：

这里填标题

时间：自己填时间

结果：把结果写在这里

templates--56：templates 模板与知识分离，不内嵌规则到模板里

模板只管结构，不管业务规则。

业务规则、约束、格式标准统一放 references/。

✅ 推荐：

模板不写判断逻辑

不写业务说明

不写约束条件

只保留结构与占位符

如：

# 巡检报告
{{date}}
{{device_name}}
{{status_list}}

❌ 不建议：

# 巡检报告

注意：磁盘 >90% 必须标红，接口超时要告警，这些规则写在下面……

templates--57：templates 一个模板一个输出目标，职责单一

1 模板 = 1 类输出，不把多种格式、多种用途混在一个文件里。

✅ 推荐：

日报模板、周报模板分开

JSON 模板、Markdown 模板分开

简洁版、详细版分开

如：

my-skill/ 
├── 
├── templates/
│   ├── daily_report.md           # 日报
│   ├── weekly_report.md          # 周报
│   └── report_simple.md

❌ 不建议：

my-skill/ 
├── 
├── templates/
│   ├── all_in_one.md   # 包含日报、周报、JSON、代码，混乱不堪

templates--58：templates 使用相对路径引用 assets，不写死外部资源

模板如果需要引用静态资源（图片、样式），只使用 assets 相对路径，保证移植兼容。

✅ 路径格式固定：

assets/images/xxx.png

assets/styles/xxx.css

如：

<link rel="stylesheet" href="assets/styles/report.css">
<img src="assets/images/logo.png">

❌ 不建议：

<img src="C:\files\logo.png">
<img src="../logo.png">

templates--59：templates 模板命名语义化、英文小写、无特殊字符

文件名清晰、规范、跨平台兼容，AI 与脚本都能稳定识别。

格式：

• 小写英文 + 数字 + 短横线 -
• 见名知意
• 无中文、空格、特殊符号、emoji

如：

daily-report.md

server-check.md

error-response.json

❌ 不建议：

模板最终版.md

报告(新).txt

测试模板 222\_final\_final.md

templates--60：templates 禁止在模板内写可执行代码与逻辑

模板是静态结构，不写循环、判断、脚本调用、命令执行。

格式：

不写 Python/Shell/PS 代码

不写复杂逻辑

不写 AI 执行流程

逻辑由 SKILL.md 执行流程控制

如：

{{error_list}}
{{summary}}

❌ 不建议：

{% for i in list %}
if status == 'error': print(...)

templates--61：templates 公共结构抽成共用模板，避免重复复制

多个模板共用的头部、尾部、格式片段，抽成公共子模板，一处修改全局生效。

建立公共子目录：

• templates/common/
• templates/parts/

如：

my-skill/ 
├── 
├── templates/
│   ├── common/
│        ├── header.md         # 页眉
│        └── footer.md         # 页脚

❌ 不建议：

每个模板都复制一遍相同的头部、尾部、格式说明。

templates--62：templates 模板必须带示例注释，便于 AI 理解结构意图

模板内可加少量示例注释，帮助 AI 理解每个区块填什么、格式要求。

格式：

注释用 <!-- --> 或 --- 包裹，不污染最终输出。

如：

# {{title}}
<!-- 此处填写任务名称，不超过20字 -->

## 结果
{{result}}
<!-- 只填成功/失败/异常，不要写描述 -->

❌ 不建议：

无任何说明，AI 随意填充，格式混乱。

templates--63：templates 与 SKILL.md 执行流程对应，可被直接编排调用

模板文件名、路径稳定固定，方便在 SKILL.md 中直接引用，形成 “流程 + 模板” 闭环。

格式：

## 执行流程：
1. 获取数据
2. 使用 templates/daily-report.md 生成日报
3. 输出结果

❌ 不建议：

模板路径混乱、文件名经常改，导致 SKILL.md 引用失效。

templates--64：templates 模板只定义结构，不填充真实业务数据

模板是模具，不是成品。不填充真实示例数据，只保留占位符。

格式：

用户名：{{username}}
时间：{{time}}

❌ 不建议：

用户名：张三
时间：2025-01-01

templates--65：templates 与 assets、references 严格三层分离

明确三层边界，不混用：

• templates：输出结构
• assets：静态素材（图、样式、图标）
• references：规则、知识、约束、文档

格式：

templates/report.md      # 结构
assets/style.css            # 样式
references/rules.md      # 规则

❌ 不建议：

templates/rules.md
references/template.md
assets/report.md

3.5. examples/参考示例

存放真实输入输出样例，展示技能用法与预期结果。作用是降低 AI 理解成本，减少偏差；方便用户 / 开发者测试验证。

examples = 范例层：用于清晰展示 Skill 输入输出、用法、效果、边界案例让 AI、使用者、维护者一眼看懂 “这个 Skill 到底干嘛、怎么用、长什么样”。

典型场景与示例：

1. 输入示例

# examples/input.txt
操作：提取PDF文本
文件：./docs/sample.pdf
密码：无
页码：1-5

1. 输出示例

# examples/output.txt
✅ PDF提取成功
原文件：sample.pdf（5页，1.2MB）
结果文件：output/extract_20260405_sample.txt
内容摘要：
1. 项目概述
2. 需求分析
3. 系统设计
...

1. 失败示例

# examples/error.txt
❌ 失败：文件加密
原文件：protected.pdf
错误：需要密码，请提供正确密码后重试

examples--66：examples 职责纯粹原则

examples 只存放真实、可复现的输入 / 输出范例，不存放知识、规则、模板、脚本、素材。

建议：

只放：示例输入、示例输出、完整对话案例、效果展示

不放：业务规则、API 文档、代码脚本、图片、配置、模板

如：

examples/
  example-1-success.md
  example-2-warning.md
  example-3-error.md

❌ 不建议：

examples/
  rules.md        # 应放 references
  template.md     # 应放 templates
  script.py       # 应放 scripts
  logo.png        # 应放 assets

examples--67：examples 必须成对出现：输入 + 输出

一个完整范例 = 清晰输入 + 对应输出，不能只给结果不给输入，也不能只给输入不给结果。

建议：

让别人能复现

让 AI 理解预期格式

让维护者快速判断是否正常

如：

# 示例：磁盘正常巡检
## 输入
检查C盘磁盘状态

## 输出
✅ C盘使用率 45%，状态正常

❌ 不建议：

# 只写输出
磁盘正常

# 只写输入
检查磁盘

examples--68：examples 覆盖场景要明确，包含典型场景 、边界场景 、成功、失败、异常场景类示例

范例不只做 “成功案例”，必须覆盖：

• 正常场景
• 边界场景（阈值临界）
• 异常 / 错误场景
• 禁止 / 不支持场景

让 AI 知道什么能做、什么不能做、做到什么程度算对。

examples/
  normal.md       # 正常
  boundary.md     # 边界值
  warning.md      # 告警
  error.md        # 异常
  invalid.md      # 不支持的输入

不建议：

examples/
  demo.md  # 只有一个完美案例，其他一概没有

examples--69：examples 一个范例一个场景，职责单一、不堆砌

1 个示例文件 = 1 个独立场景，不要把正常、异常、边界全塞一个文件里。

建议：

• 结构清晰
• AI 易检索
• 便于单独更新

如：

examples/disk-normal.md
examples/disk-high-usage.md
examples/disk-not-found.md

不建议：

examples/all-examples.md
# 里面混杂正常、异常、边界、对话、多轮操作一锅炖

examples--70：examples命名语义化、小写英文、无特殊字符

文件名清晰、稳定、跨平台兼容，便于 AI 与脚本调用。

建议：

小写英文、数字、短横线 -

命名 = 场景 + 状态

无中文、空格、括号、emoji

如：

examples/
  check-disk-normal.md
  check-disk-warning.md
  check-service-failed.md

不建议：

示例1.md
测试最终版(修改).md
示范案例新的.txt

examples--71：examples格式统一、结构固定，便于 AI 理解

所有示例使用统一结构，AI 可以稳定解析范例意图。

推荐固定结构：

# 示例名称
## 场景说明
## 输入
## 输出
## 说明（可选）
如：
# 示例：服务端口不通
## 场景 目标IP端口未开放  
## 输入 检查 192.168.1.10:8080  
## 输出 ❌ 端口 8080 无法连接

不建议：

格式混乱、散文式、无分段：
我试了一下检查端口，好像不通，返回了一堆错误信息大概是这样……

examples--72：examples 范例必须真实、简短、可直接复现，用真实文件/参数，不虚构，不放理论说明

示例内容必须真实可跑，不能编造、不能夸张、不能过于冗长。

建议：

长度适中
可直接复制测试
不使用虚假占位内容冒充示例

不建议：

## 输出
（此处省略一万字结果）

examples--73：examples 禁止放真实敏感数据、隐私信息

示例中脱敏处理，不出现真实 IP、手机号、密钥、公司内部隐私数据。

建议：

IP 用 192.168.x.x
域名用 example.com
不出现真实姓名、工号、机密信息
如：
检查 192.168.1.100:80
用户 test_user

不建议：

检查 10.123.xx.xx 真实办公IP
张三 13800138000

examples--74：examples 加支持文件——放一个好用例样本

在 Skill 目录下建一个 examples/good-case.md，放一份你认为质量最高的真实用例文档。在 SKILL.md 里引用它："对于输出格式和用例粒度，参考 examples/good-case.md"。Claude 会读取这个文件来校准输出质量。

examples--75：examples 与 templates、references 对应一致

示例输出格式必须严格对齐 templates，规则对齐 references，不出现矛盾。

建议：

示例输出 ≡ 模板最终渲染效果
示例规则 ≡ references 里的约束
如：
template 定义表格格式 → 示例也输出表格。

不建议：

模板是表格，示例却是一段散文；规则说不能超过 3 条，示例却写 10 条。

examples--76：examples 用于 “教学”，不是 “文档”

examples 是演示用法，不是写说明文档，不长篇大论讲原理。

建议：

少解释，多展示
用输入输出说话
不写原理、不写架构、不写代码实现
如：
展示 “输入什么 → 得到什么”。

不建议：

这个 Skill 的原理是……它的架构分为……底层实现是……

examples--77：examples 不随运行动态生成，保持静态

examples 是静态范例，不是运行日志、不是实时结果、不是缓存。

建议：

不存放脚本运行产生的临时文件
不存放日志
人工编写、人工维护
如：
手工编写、固定不变的示例。

不建议：

examples/result-20260407.txt
examples/cache.json
examples/runtime.log

8. 【高阶】hooks/约束与观测

hooks = 约束与观测层：用于记录调用、控制权限、拦截流程、校验输入输出、审计日志 它不是业务逻辑，也不是脚本，而是Skill 的 “门卫 + 监控 + 记录仪”。

hooks 是 Skill 的约束与观测层，专注于权限校验、输入拦截、流程控制、调用审计与日志记录；单一职责、可插拔、跨平台、无侵入、不参与业务输出，统一接口、安全可追溯，轻量高效。

Hooks 三大生命周期（所有场景都归这 3 类）：

1）执行前：before\_*

校验、拦截、权限、限流、参数检查不让违规请求进入主流程

2）执行后：after\_*

日志、审计、通知、归档、数据上报记录结果、不影响主流程

3）事件触发：on\_*

出错、成功、超时、重试、中止时触发

hooks--78：Hooks 什么时候用

该用 Hooks：

• 要拦截请求
• 要校验权限 / 参数
• 要限流 / 安全 / 过滤
• 要日志 / 审计 / 留痕
• 要出错处理 / 超时
• 要结果脱敏 / 格式校验

不应该用 Hooks：

• 执行业务逻辑（scripts）
• 生成输出内容（templates）
• 存放业务规则（references）
• 存放图片 / 素材（assets）
• 存放示例（examples）

hooks--79：Hooks 的应用调用

Hooks 不是自动运行的，是「被编排」的

在 OpenClaw 体系里，Hooks 不是魔法自动执行，而是在 SKILL.md 的执行流程里显式调用。

SKILL.md（指挥）
  ↓ 调用
hooks/xxx.py（门卫/校验/记录）
  ↓ 通过才继续
scripts/xxx.py（真正干活）

项目中标准接入模式（固定套路，所有 Skill 通用）

标准执行流程（强制规范）

执行流程：
1. 调用前置钩子（权限、参数、环境、限流）
2. 执行业务脚本
3. 调用后置钩子（日志、审计、通知）
4. 异常时触发错误钩子

执行流程：
1. 获取输入参数：path、user、remark
2. 调用 hooks/validate_input.py 校验参数
   → 不通过则终止
3. 调用 hooks/check_permission.py 校验权限
   → 不通过则终止
4. 调用 hooks/rate_limit.py 限流检查
   → 超限则终止

5. 执行业务脚本：scripts/check_disk.py

6. 执行成功：
   → 调用 hooks/record_audit.py 记录审计日志
7. 执行失败：
   → 调用 hooks/on_error.py 发送告警
8. 无论成败：
   → 调用 hooks/cleanup_temp.py 清理临时文件

hooks--80：调用前 → 参数校验 Hook

必传参数是否存在、格式是否合法，提前拦截错误。

import sys
import json

def validate(context):
    # 从参数中获取输入
    args = context.get("args", {})
    path = args.get("path")

    if not path:
        return {
            "allowed": False,
            "message": "缺少必传参数：path"
        }

    if not path.strip():
        return {
            "allowed": False,
            "message": "path 不能为空"
        }

    return {
        "allowed": True,
        "message": "参数校验通过"
    }

if __name__ == "__main__":
    # OpenClaw 通常以 JSON 传入上下文
    context = json.loads(sys.argv[1])
    result = validate(context)
    print(json.dumps(result, ensure_ascii=False))

在 SKILL.md 中使用

执行流程：
1. 传入参数：{"path": "{{path}}"}
2. 调用 hooks/validate_input.py，获取校验结果
3. 如果不通过 → 直接终止并返回错误信息
4. 继续执行 scripts/check_disk.py

hooks--81：调用前 → 权限校验 Hook

控制哪些人 / 哪些群 / 哪些角色能使用该 Skill。

import sys
import json

def validate(context):
    # 从参数中获取输入
    args = context.get("args", {})
    path = args.get("path")

    if not path:
        return {
            "allowed": False,
            "message": "缺少必传参数：path"
        }

    if not path.strip():
        return {
            "allowed": False,
            "message": "path 不能为空"
        }

    return {
        "allowed": True,
        "message": "参数校验通过"
    }

if __name__ == "__main__":
    # OpenClaw 通常以 JSON 传入上下文
    context = json.loads(sys.argv[1])
    result = validate(context)
    print(json.dumps(result, ensure_ascii=False))

在 SKILL.md 中使用

执行流程：
1. 获取调用用户：{{user_id}}
2. 调用 hooks/check_permission.py
3. 不允许则终止

hooks--82：调用前 → 限流 Hook（防刷）

防止短时间频繁调用，保护系统。

import time, sys, json

RATE_LIMIT = 3    # 每分钟最多 3 次
WINDOW = 60

def check_rate(user):
    now = time.time()
    # 真实项目可使用 redis / 文件记录
    return True

if __name__ == "__main__":
    ctx = json.loads(sys.argv[1])
    ok = check_rate(ctx.get("user"))
    print(json.dumps({"allowed": ok}))

在 SKILL.md 中使用

执行流程：
1. 传入参数：{"path": "{{path}}"}
2. 调用 hooks/validate_input.py，获取校验结果
3. 如果不通过 → 直接终止并返回错误信息
4. 继续执行 scripts/rate_limit.py

hooks--83：调用后 → 审计日志 Hook（必备）

谁、何时、调用了什么、参数是什么，安全合规必备。

import sys, json, time

def log_audit(context):
    user = context.get("user")
    skill = context.get("skill")
    args = context.get("args")
    now = time.strftime("%Y-%m-%d %H:%M:%S")

    log = f"[{now}] 用户={user} 调用技能={skill} 参数={args}"

    with open("audit.log", "a", encoding="utf-8") as f:
        f.write(log + "\n")

    return {"success": True}

if __name__ == "__main__":
    log_audit(json.loads(sys.argv[1]))

在 SKILL.md 中使用

执行流程：
...
5. 调用完成后，执行 hooks/record_audit.py 记录审计日志

hooks--84：异常时 → 错误捕获 Hook

脚本报错自动发飞书告警。

import sys, json, requests

def send_error_alert(msg):
    webhook = "https://open.feishu.cn/xxx"
    requests.post(webhook, json={
        "msg_type": "text",
        "content": {"text": f"Skill 执行异常：{msg}"}
    })

if __name__ == "__main__":
    ctx = json.loads(sys.argv[1])
    send_error_alert(ctx.get("error"))

在 SKILL.md 中使用

执行流程：
4. 如果执行出错 → 调用 hooks/on_error.py 发送告警

hooks--85：调用后 → 临时文件清理 Hook

执行完自动删除 temp 目录，不残留垃圾。

import os, sys, json

def clean(path):
    if os.path.exists(path):
        os.remove(path)

if __name__ == "__main__":
    ctx = json.loads(sys.argv[1])
    clean(ctx.get("temp_path"))

在 SKILL.md 中使用

执行流程：
...执行结束...
调用 scripts/cleanup_temp.py

hooks--86：Hooks 执行前校验类（before\_*)

hooks--87：Hooks 执行后观测类（after\_*)

hooks--88：事件触发类（on\_*)

hooks--89：最推荐的「标准 Hooks 套装」（团队通用版）

如果你想给团队定最少但最实用的一套 hooks，固定下面 8 个就够 99% 场景：

hooks/
  before_execute.py       # 总入口前校验
  validate_input.py       # 参数校验
  check_permission.py     # 权限控制
  rate_limit.py           # 限流

  after_execute.py        # 执行后统一处理
  record_audit.py         # 审计日志（必备）
  on_error.py             # 错误捕获
  cleanup_temp.py         # 临时文件清理

hooks--90：hooks 职责纯粹原则，只做拦截、校验、观测、审计

hooks 只负责在 Skill 执行前后 “插手” 控制，不做业务功能、不生成结果、不处理数据。

典型职责：

• 调用前：权限校验、参数校验、频率限制
• 调用中：流程拦截、中止判断
• 调用后：记录日志、上报结果、归档、通知
• 全程：审计、安全控制

不属于 hooks 的一律不放：

• 业务脚本、数据处理
• 输出模板
• 静态资源
• 参考知识

如：

hooks/
  before_call.py      # 调用前校验
  after_call.py       # 调用后日志
  permission_check.py # 权限控制
  rate_limit.py       # 限流

不建议：

hooks/
  disk_check.py       # 业务脚本，应放 scripts
  report.md           # 模板，应放 templates
  logo.png            # 资源，应放 assets

hooks--91：hooks 生命周期清晰，与执行流程严格对应

hooks 按 Skill 执行生命周期命名，什么时候触发一目了然。

标准命名风格：

• before_*.py：执行前
• after_*.py：执行后
• on_*.py：某事件触发
• validate_*.py：校验类

如：

hooks/
  before_execute.py
  after_execute.py
  validate_input.py
  on_error.py
  on_success.py

不建议：

hooks/
  a.py
  test.py
  do_something.py
  钩子1.py

hooks--92：hooks单一职责：一个 hook 只做一件控制事情

和 scripts 一样，hooks 必须职责单一，不要一个文件做所有控制。

便于开关、替换、维护。

建议：

权限校验单独一个 hook

参数校验单独一个

日志单独一个

限流单独一个

如：

hooks/
  validate_input.py
  check_permission.py
  record_log.py

不建议：

hooks/control_all.py
# 里面又校验、又记录、又权限、又限流

hooks--93：hooks只做控制决策，不做业务实现

hooks 只返回 允许 / 拒绝 / 中止 / 警告 这类决策，不处理业务逻辑、不调用业务接口、不生成输出内容。

建议：

返回：True/False、raise 异常、返回消息

不做：查询数据、生成报告、执行命令

如：

# validate_input.py
def run(args):
    if not args.get("user_id"):
        raise Exception("缺少 user_id，禁止执行")

不建议：

# hook 里写业务逻辑
def run(args):
    data = requests.get(...)  # 业务请求
    result = parse(data)      # 业务处理
    save(result)             # 业务存储

hooks--94：hooks无侵入、可插拔，不破坏主流程

hooks 是附加控制，主流程 SKILL.md 不依赖某个 hook 才能跑。

关闭 / 删除 hook 后，Skill 主体功能仍然正常。

建议：

可单独启用 / 禁用

不修改主业务逻辑

不硬编码到 SKILL.md 流程内部

如：

# SKILL.md 执行流程
1. 执行前触发 hooks/before_execute.py
2. 执行业务逻辑
3. 执行后触发 hooks/after_execute.py

不建议：

# SKILL.md 里把 hook 逻辑写死在流程里
1. 判断用户权限（写死逻辑，不可插拔）
2. 判断频率（写死逻辑）

hooks--95：hooks统一入参出参格式，便于 AI 与框架调用

所有 hook 对外接口保持一致，AI / 调度器可以统一调用，不用逐个适配。

统一结构示例：

• 输入：skill\_context（上下文、参数、用户信息）

• 输出：

  • allowed: bool
  • message: str
  • action: continue / abort / warn

如：

def hook(context):
    return {
        "allowed": True,
        "message": "校验通过",
        "action": "continue"
    }

不建议：

每个 hook 返回格式不一样：有的返回字符串，有的返回数字，有的直接打印。

hooks--96：hooks优先跨平台 Python，不写系统专属脚本

hooks 是控制层，要稳定可移植，统一使用 Python，不写 .ps1 /.sh。

建议：

跨 Windows/macOS/Linux

权限、校验、日志逻辑一致

便于 AI 调用

如：

hooks/
  validate_input.py
  record_audit.py

不建议：

hooks/
  check_permission.ps1
  log.sh

hooks--97：禁止在 hooks中输出最终结果内容

hooks 只做控制与记录，不生成、不修改最终输出。

输出由 templates + AI 主流程负责。

建议：

不写报告、表格、文案

不修改返回结果

只记录、拦截、校验

如：

# 只记录，不输出结果
def after_execute(context, result):
    audit_log(f"用户 {context.user} 调用了 {context.skill}")

不建议：

def after_execute(...):
    print("最终报告：……")  # 输出业务结果，错误

hooks--98：hooks 安全与审计优先，必须可追溯

凡是涉及权限、敏感操作的 hook，必须留日志、可追溯、不可篡改。

记录至少包含：

• 用户 / 调用方
• 时间
• 输入参数（脱敏）
• 执行结果
• 是否被拦截

如：

# record_audit.py
with open("audit.log", "a", encoding="utf-8") as f:
    f.write(f"{time} | {user} | {skill} | {allowed}\n")

不建议：

无任何记录，出问题无法追溯。

hooks--99：hooks 命名规范：小写、下划线、语义明确

文件名小写英文 + 下划线，禁止中文、空格、特殊字符、版本号后缀。

建议：

hooks/
  before_execute.py
  validate_input.py
  check_permission.py
  record_audit_log.py

不建议：

钩子.py
校验新的.pl
Hook最终版(修改).py

hooks--100：hooks 禁止放业务配置、静态资源、参考资料

hooks 只放控制逻辑，不放任何其他类型文件。

建议：

只放拦截、校验、日志类脚本。

不建议：

hooks/
  config.json
  api.md
  logo.png
  template.md

hooks--101：hooks 轻量、快速、不阻塞主流程

hook 执行要极快，不做复杂计算、不请求慢接口、不阻塞 Skill 主流程。

建议：

不做网络大文件下载

不做复杂数据计算

不做 heavy 逻辑

简单判断、快速写入日志、内存校验。

不建议：

hook 里执行模型推理、爬取网页、压缩文件等耗时操作。

9 \_meta.json

\_meta.json = Skill 的身份证 + 档案表 + 管理元数据

专门存放：版本、作者、分类、标签、依赖、更新日志、权限、描述等管理用信息，不参与业务执行，只给平台 / 工具 / 人做管理使用。

\_meta.json 模板样式

{
  "name": "skill-disk-monitor",
  "version": "1.0.0",
  "author": "your-name",
  "description": "磁盘使用率巡检与阈值告警",
  "category": "system",
  "tags": ["disk", "monitor", "alert", "system"],
  "dependencies": {
    "python": "3.8+",
    "libs": ["psutil", "requests"]
  },
  "create_time": "2026-04-07T00:00:00Z",
  "update_time": "2026-04-07T00:00:00Z",
  "language": "zh-CN",
  "level": "stable",
  # 自定义增加项（可自定义）
  "xxx":"xxxxxxxx"
}

附1 - Skill 金句

Skills 能把我们的最佳实践、流程和经验，以一种可维护、可复用的方式，输入给 AI，让 AI 变得更聪明。

未来普通人使用 Agent，未必是天天重写 Prompt，而更可能是围绕一组已经沉淀好的 Skills，去持续调用、组合和优化。

用的人越多，积累的经验越多，Skills 的质量和覆盖面就越广，Skills 不再是个人本地的“小本本”，而是一个可共享、可迭代、可组合的能力生态。

一个 skill 就干一件事，单一职责，skill 越简单，触发越精准，执行越稳定。

附2 - 本文编号规约

编号规约 ： [ 分层 ] - [ 对象 ] - （PR|SP|RE|PE|BE ） - （001）

所有技巧，统一“6级标题”目录

定义如下：

短标识定义：

附3 - 关键更新记录

| | | | |
| - | - | - | - |