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

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

版本：v1.02 更新：2026--0616 收录：101

想象这样一个场景：

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

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

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

1. Skill 结构回顾

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

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

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

1.1. 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 结构稍有差别，但能兼容。以上蓝色为部分官方建议结构，但实际使用中可以自定义、优化和增强。

本文以上分层结构为章节索引，方便大家检索。

注：为方便大家检索，本文的设计技巧编号规则：" [ 原则 | 技巧 ] + i ” ---不细分原则和技巧，统一编号，如原则 1、技巧 2、技巧 3、原则 4、技巧 5、技巧 6、... ...

1.2. 加载原则/优先级

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

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

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

1.2.1. OpenClaw 加载规则

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

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

1.2.2. 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，优先级最低）

1.2.3. ClaudeCode 加载规则

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

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

1.2.4. 通用加载原则补充

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

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

1.3. Skill 设计原则

原则1： 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 设计技巧，可作为所有设计活动的参考

原则2：单一职责优先原则

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

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

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

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

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

这样做的好处是：

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

❌ 错误做法：

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

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

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

技巧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……"

技巧4：给信息，别设限

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

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

举例：

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

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

技巧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"。

原则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 等等，也要保持类似：多方拼凑的内容，需要开展检查或优化，不然导致准确率低下！

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

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

举例 1：

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

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

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

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

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

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

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

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

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

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

举例 1：

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

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

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

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

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

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

举例 1：

✅ 正确做法，举例：

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

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

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

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

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

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

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

举例 1：

✅ 正确做法，举例：

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

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

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

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

技巧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)

2. SKILL.md 主文件

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

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  # 短横线命名，小写

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

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

2.1.2. description 技能描述

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

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

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

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

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

description 的原则：

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

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

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

技巧13：Description 是触发器，写给"机器"看，要精准，列清触发词，简洁明了，避免模糊

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

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

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

举例 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'"

技巧14：能力边界清晰，Description 描述的触发范围容易判断

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

举例 1：

✅ 正确做法：

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

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

❌ 错误做法：

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

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

技巧15：负样本，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 文档时也被触发，造成错误的处理结果。

技巧16：多场景触发设计，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。

2.1.3. disable-model-invocation 技能描述

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

2.1.4. user-invocable技能描述

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

2.1.5. effort 技能描述

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

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

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

2.1.6. paths 技能描述

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

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

2.1.7. 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.2. 角色设定

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

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

# 测试用例设计助手

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

2.3. 执行流程

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

原则17：流程要有明确的"步骤感"

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

举例：

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

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

## 执行流程

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

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

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

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

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

举例：

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

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

🚯 踩坑经历：

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

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

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

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

2.4. 质量约束

质量约束——防止 AI 偷懒

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

## 质量要求

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

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

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

🚯 踩坑经历：

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

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

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

3. 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")

原则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），没有类型提示，错误处理不完整，导致后续开发者无法理解代码逻辑，维护成本极高。

技巧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 只负责 “执行”。

技巧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 天前的文件"

技巧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}` };  #结构化
  }
}

技巧26：错误分类，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}` };
}

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

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

举例 1：

✅ 正确做法：

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

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

❌ 错误做法：

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

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

技巧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)

技巧30：让 Skill 读项目代码来补充上下文

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

## 上下文增强（可选）

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

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

技巧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 里可以如上这样写（一套流程，全系统通吃）

4. 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/（后端服务骨架）

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

✅ 标准子目录建议：

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

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

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

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

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

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

文件名见名知意

原则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

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

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

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

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

assets/styles/common.css

assets/prompts/common-role.txt

在 SKILL.md 或模板中引用：

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

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

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

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

不存放如下举例：

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

✅ 可存放：

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

❌ 不建议存放：

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

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

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

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

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

很多人会混淆：

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

✅ 可存放：

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

❌ 不建议存放：

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

5. 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"
   }
 }

原则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

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

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

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

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

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

✅ 可存放：

接口文档

业务规范

数据字典

踩坑总结

标准格式要求

❌ 不建议存放：

不放 .py / .ps1 脚本

不放带变量的输出模板

不放配置文件、运行参数

如：

references/run.py

references/template.md

references/config.json

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

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

✅ references/可存放：

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

business.md # 业务规则

standards.md # 格式标准

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

faq.md # 常见问题

data-dict.md # 数据字典

❌ 不建议存放：

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

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

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

✅ 建议举例：

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

每条知识只讲一件事

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

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

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

❌ 不建议：

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

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

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

✅ 建议举例：

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

接口字段参见 references/api.md

❌ 不建议：

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

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

技巧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 里提供标准格式。

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

两者区别：

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

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

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

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

两者区别：

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

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

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

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

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

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

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

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

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

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

✅ 建议举例：

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

❌ 不建议：

不放运行日志

不放脚本输出结果

不放临时数据

如：

references/run.log

references/temp-result.json

references/cache.txt

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

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

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

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

6 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>

技巧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

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

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

✅ 推荐统一格式：

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

如：

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

❌ 不建议：

这里填标题

时间：自己填时间

结果：把结果写在这里

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

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

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

✅ 推荐：

模板不写判断逻辑

不写业务说明

不写约束条件

只保留结构与占位符

如：

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

❌ 不建议：

# 巡检报告

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

技巧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、代码，混乱不堪

技巧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">

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

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

格式：

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

如：

daily-report.md

server-check.md

error-response.json

❌ 不建议：

模板最终版.md

报告(新).txt

测试模板 222\_final\_final.md

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

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

格式：

不写 Python/Shell/PS 代码

不写复杂逻辑

不写 AI 执行流程

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

如：

{{error_list}}
{{summary}}

❌ 不建议：

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

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

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

建立公共子目录：

• templates/common/
• templates/parts/

如：

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

❌ 不建议：

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

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

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

格式：

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

如：

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

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

❌ 不建议：

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

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

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

格式：

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

❌ 不建议：

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

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

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

格式：

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

❌ 不建议：

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

技巧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

7 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
错误：需要密码，请提供正确密码后重试

原则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

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

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

建议：

让别人能复现

让 AI 理解预期格式

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

如：

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

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

❌ 不建议：

# 只写输出
磁盘正常

# 只写输入
检查磁盘

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

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

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

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

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

不建议：

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

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

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

建议：

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

如：

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

不建议：

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

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

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

建议：

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

命名 = 场景 + 状态

无中文、空格、括号、emoji

如：

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

不建议：

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

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

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

推荐固定结构：

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

不建议：

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

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

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

建议：

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

不建议：

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

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

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

建议：

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

不建议：

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

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

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

技巧75：examples 与 templates、references 对应一致

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

建议：

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

不建议：

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

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

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

建议：

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

不建议：

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

技巧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\_*

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

应用78：Hooks 什么时候用

该用 Hooks：

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

不应该用 Hooks：

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

应用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 清理临时文件

应用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

应用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. 不允许则终止

应用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

应用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 记录审计日志

应用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 发送告警

应用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

应用86：Hooks 执行前校验类（before\_*)

应用87：Hooks 执行后观测类（after\_*)

应用88：事件触发类（on\_*)

技巧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         # 临时文件清理

技巧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

技巧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

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

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

便于开关、替换、维护。

建议：

权限校验单独一个 hook

参数校验单独一个

日志单独一个

限流单独一个

如：

hooks/
  validate_input.py
  check_permission.py
  record_log.py

不建议：

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

技巧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)             # 业务存储

技巧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. 判断频率（写死逻辑）

技巧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 返回格式不一样：有的返回字符串，有的返回数字，有的直接打印。

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

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

建议：

跨 Windows/macOS/Linux

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

便于 AI 调用

如：

hooks/
  validate_input.py
  record_audit.py

不建议：

hooks/
  check_permission.ps1
  log.sh

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

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

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

建议：

不写报告、表格、文案

不修改返回结果

只记录、拦截、校验

如：

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

不建议：

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

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

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

记录至少包含：

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

如：

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

不建议：

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

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

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

建议：

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

不建议：

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

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

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

建议：

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

不建议：

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

技巧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"
}

附 - Skill 金句

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

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

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

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