skill-optimizer

Skill Creator

此技能提供创建有效技能的指导。

关于技能

技能是模块化的独立软件包，可通过提供专业知识、工作流和工具来扩展 Claude 的能力。可以将它们视为针对特定领域或任务的“入门指南”——它们能将 Claude 从通用 Agent 转变为具备流程知识的专业 Agent，而这些知识并非任何模型都能完全掌握。

技能遵循 Agent Skills 开放标准，并通过 Claude Code 扩展支持调用控制、子 Agent 执行和动态上下文注入。

技能提供的内容

1. 专业工作流——针对特定领域的多步骤流程
2. 工具集成——使用特定文件格式或 API 的说明
3. 领域专业知识——公司专属知识、架构和业务逻辑
4. 捆绑资源——用于复杂且重复任务的脚本、参考资料和资源

技能的构成

每项技能都包含一个必需的 SKILL.md 文件，以及可选的捆绑资源：

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter metadata
│   └── Markdown instructions
└── Bundled Resources (optional)
    ├── scripts/          - Executable code (Python/Bash/etc.)
    ├── references/       - Documentation loaded into context as needed
    └── assets/           - Files used in output (templates, icons, fonts)

SKILL.md（必需）

元数据质量： YAML 前置内容中的 name 和 description 决定 Claude 何时使用该技能。请具体说明技能的功能和适用时机。使用第三人称（例如，“This skill should be used when...” 而不是 “Use this skill when...”）。

前置内容字段：

字段	必需	说明
name	否	显示名称（最多 64 个字符，仅限小写字母和连字符）。默认为目录名称。
description	建议填写	技能的功能和适用时机（最多 1024 个字符）。
argument-hint	否	自动补全时显示的提示（例如，[issue-number]）。
disable-model-invocation	否	true = 只能由用户通过 /name 调用。
user-invocable	否	false = 从 / 菜单中隐藏（仅供 Claude 使用的后台知识）。
allowed-tools	否	限制技能激活时可用的工具（例如，Read, Grep, Glob）。
model	否	技能激活时使用的模型覆盖项。
context	否	fork = 在隔离的子 Agent 中运行。
agent	否	子 Agent 类型：Explore、Plan、general-purpose，或来自 .claude/agents/ 的自定义类型。
hooks	否	技能生命周期的作用域钩子。请参阅 Hooks 文档。

包含所有字段的示例：

---
name: deploy-production
description: Deploy the application to production. Use after all tests pass.
argument-hint: [environment]
disable-model-invocation: true
allowed-tools: Bash(deploy:*), Read
context: fork
agent: general-purpose
---

字符串替换

技能支持在 Markdown 内容中动态替换值：

变量	说明
$ARGUMENTS	调用时传入的所有参数（例如，/my-skill arg1 arg2）
${CLAUDE_SESSION_ID}	当前会话 ID，可用于日志记录或创建会话专属文件

如果内容中未包含 $ARGUMENTS，参数会以 ARGUMENTS: <value> 的形式追加。

示例：

---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
---

Fix GitHub issue $ARGUMENTS following our coding standards.

Log progress to logs/${CLAUDE_SESSION_ID}.log

动态上下文注入

感叹号-反引号语法会在技能内容传递给 Claude 之前运行 shell 命令。命令输出会替换占位符。

语法： 感叹号后接用反引号括起的命令：EXCLAIM + BACKTICK command BACKTICK

技能内容示例：

## PR Context
- Diff: EXCLAIM-BACKTICK gh pr diff BACKTICK
- Comments: EXCLAIM-BACKTICK gh pr view --comments BACKTICK
- Changed files: EXCLAIM-BACKTICK gh pr diff --name-only BACKTICK

Summarize this pull request...

（在实际技能中，将 EXCLAIM 替换为感叹号字符，并将 BACKTICK 替换为反引号）

运行此技能时：

1. 每个感叹号-反引号命令都会立即执行（在 Claude 看到任何内容之前）
2. 命令输出会替换技能内容中的占位符
3. Claude 会收到包含实际数据的完整渲染提示词

这是预处理，并非由 Claude 执行的操作。Claude 只会看到最终结果。

调用控制

默认情况下，用户和 Claude 都可以调用任何技能。两个 frontmatter 字段可以控制此行为：

Frontmatter	用户可以调用	Claude 可以调用	在上下文中
（默认）	是	是	始终显示描述
disable-model-invocation: true	是	否	对 Claude 隐藏描述
user-invocable: false	否	是	始终显示描述

何时使用：

• disable-model-invocation: true：用于具有副作用的工作流（部署、提交、发送消息）。防止 Claude 自动触发。
• user-invocable: false：用于没有实际命令意义的背景知识（例如 legacy-system-context）。Claude 应在相关时了解这些内容，但 /legacy-system-context 对用户没有用处。

子 Agent 集成

添加 context: fork，即可在隔离环境中运行技能。技能内容会成为子 Agent 的提示词（无法访问对话历史）。

---
name: deep-research
description: Research a topic thoroughly
context: fork
agent: Explore
---

Research $ARGUMENTS thoroughly:
1. Find relevant files using Glob and Grep
2. Read and analyze the code
3. Summarize findings with specific file references

Agent 选项：

Agent	描述
Explore	只读代码库探索（Glob、Grep、Read）
Plan	架构规划与设计
general-purpose	完整能力（默认）
Custom	.claude/agents/ 中的任意 Agent

注意：context: fork 仅适用于包含明确指令的技能。仅包含指南的技能（例如“使用这些 API 约定”）不会提供可执行的提示词，因此不会产生有意义的输出。

技能位置

技能的存储位置决定了谁可以使用它：

位置	路径	适用范围	优先级
Enterprise	托管设置	组织中的所有用户	最高
Personal	~/.claude/skills/<name>/SKILL.md	你的所有项目	高
Project	.claude/skills/<name>/SKILL.md	仅此项目	中
Plugin	<plugin>/skills/<name>/SKILL.md	插件启用的位置	命名空间

当多个技能同名时，优先级较高的位置会胜出。插件技能使用 plugin-name:skill-name 命名空间，因此不会发生冲突。

**嵌套发现：**在子目录（例如 packages/frontend/）中编辑文件时，Claude Code 也会发现嵌套的 .claude/skills/ 目录中的技能。这支持各个包拥有自身技能的单体仓库。

旧版命令：.claude/commands/ 中的文件仍可使用相同的 frontmatter。建议使用技能，因为它们支持其他功能，例如支持文件。

捆绑资源（可选）

脚本（scripts/）

内容类型：代码——用于需要确定性可靠性或会反复重写任务的可执行代码（Python/Bash 等）。

• 适用情况：反复重写相同代码，或需要确定性可靠性时
• 示例：用于 PDF 旋转任务的 scripts/rotate_pdf.py
• 优点：节省 Token、结果确定、脚本代码不会进入上下文——只有输出会进入
• 主要优势：一个 200 行的脚本只需约 20 个 Token（输出），而不是 2000 多个 Token（代码）
• 注意：Claude 可能仍需读取脚本，以便修补代码或进行环境特定的调整

参考资料（references/）

内容类型：说明 —— 按需加载到上下文中的文档和参考资料，用于指导 Claude 的流程和思考。

• 适用情形：Claude 工作时需要参考的文档
• 示例：用于财务架构的 references/finance.md、公司 NDA 模板 references/mnda.md、公司政策 references/policies.md、API 规范 references/api_docs.md
• 使用场景：数据库架构、API 文档、领域知识、公司政策、详细的工作流指南
• 优点：让 SKILL.md 保持精简，仅在 Claude 判断需要时加载
• 最佳实践：如果文件较大（>10k 个单词），请在 SKILL.md 中加入 grep 搜索模式
• 避免重复：信息应放在 SKILL.md 或参考资料文件中，而不是两者兼有。除非某些信息确实是技能的核心内容，否则详细信息优先放在参考资料文件中。这样既能让 SKILL.md 保持精简，也能让信息易于查找，避免占用过多上下文窗口。SKILL.md 中只保留必要的流程说明和工作流指导；将详细参考资料、架构和示例移至参考资料文件。

资源（assets/）

内容类型：资源 —— 不用于加载到上下文中，而是在 Claude 生成输出时使用的文件。

• 适用情形：技能需要在最终输出中使用文件时
• 示例：品牌资源 assets/logo.png、PowerPoint 模板 assets/slides.pptx、HTML/React 样板文件 assets/frontend-template/、字体 assets/font.ttf
• 使用场景：模板、图像、图标、样板代码、字体、会被复制或修改的示例文档
• 优点：将输出资源与文档分开，让 Claude 无需将文件加载到上下文中即可使用

渐进式披露设计原则

技能使用三级加载系统来高效管理上下文：

级别	加载时机	Token 开销	内容
级别 1：元数据	始终（启动时）	每个 Skill 约 100 个 token	YAML frontmatter 中的 name 和 description
级别 2：说明	触发 Skill 时	少于 5k 个 token	包含说明和指导的 SKILL.md 正文
级别 3+：资源	按需	实际上不受限制*	通过 bash 执行的捆绑文件，不加载到上下文中

*脚本执行时不会将代码加载到上下文中（只有输出会进入上下文）。只有在 Claude 通过 bash 命令明确访问参考资料文件和资源时，它们才会被加载。

关键要点：你可以安装数十个 Skill，而几乎不会增加上下文开销。在 Skill 被触发之前，Claude 只知道每个 Skill 的存在及其适用时机。

上下文预算：Skill 描述会加载到上下文中，以便 Claude 知道有哪些内容可用。如果 Skill 很多，可能会超出字符预算（默认 15,000 个字符）。运行 /context 检查哪些 Skill 未被纳入。若要提高上限，请设置 SLASH_COMMAND_TOOL_CHAR_BUDGET 环境变量。

技能的文件系统架构

技能以目录的形式存在于本地文件系统中，Claude 通过 bash 命令和文件操作与其交互。

Claude 如何访问技能内容：

1. 读取说明：触发技能后，Claude 通过 bash 从文件系统读取 SKILL.md，将其中的说明载入上下文
2. 加载参考资料：如果说明引用了其他文件（例如 references/api_docs.md 或数据库架构），Claude 会通过其他 bash 命令读取这些文件
3. 执行脚本：如果说明提到了可执行脚本，Claude 会通过 bash 运行这些脚本。只有脚本输出会进入上下文，代码本身不会

这带来的优势：

• 按需访问文件：Claude 只读取每项任务所需的文件。一个技能可以包含数十个参考文件，但如果任务只需要一个架构文件，Claude 就只会加载该文件。其余文件不会消耗任何 token
• 高效执行脚本：Claude 运行 validate_form.py 时，只有输出会消耗 token，200 行脚本本身不会。这让脚本的效率远高于让 Claude 即时生成等效代码
• 打包内容没有实际限制：由于文件在被访问前不会占用上下文，技能可以包含全面的文档、数据集、示例或参考资料，而不会带来上下文开销

工作流示例：

1. User: "Process this PDF and extract tables"
2. Claude: bash: read pdf-skill/SKILL.md
3. SKILL.md mentions scripts/extract_tables.py
4. Claude: bash: python scripts/extract_tables.py input.pdf
5. Script output: "Extracted 3 tables: [table data...]"
6. Claude proceeds using the extracted data (script code never entered context)

技能创建流程

创建技能时，请按顺序遵循“技能创建流程”，只有在有明确理由认为某个步骤不适用时才跳过。

步骤 1：通过具体示例了解技能

只有在已经清楚了解技能的使用模式时，才跳过此步骤。即使是在处理现有技能时，这一步仍然很有价值。

要创建有效的技能，必须清楚了解技能的具体使用方式。请使用 references/interview-protocol.md 中的流程进行结构化访谈，其中包含 6 个必问问题、深入追问，以及在回答过于含糊时明确提出异议的规则。

最重要的问题是：没有这个技能时，Claude 目前会在哪些方面出错？ 如果 Claude 已经能很好地完成这项任务，就不值得构建这个技能。发现的每一种失败模式都会成为一个注意事项条目——这是技能所能包含的信号价值最高的内容。

为避免让用户应接不暇，请每次只问一个问题，并从最重要的问题开始。当你获得具体用例、失败模式清单和可验证的成功标准后，即可结束此步骤（参见 references/interview-protocol.md 中的退出标准）。

步骤 2：规划可复用的技能内容

要将具体示例转化为有效的技能，请通过以下方式分析每个示例：

1. 考虑如何从头开始完成示例
2. 确定在重复执行这些工作流时，哪些脚本、参考资料和资源会有所帮助

示例：创建 pdf-editor 技能来处理“帮我旋转这个 PDF”之类的请求时，分析表明：

1. 每次旋转 PDF 都需要重新编写相同的代码
2. 将 scripts/rotate_pdf.py 脚本存放在技能中会有所帮助

示例：设计 frontend-webapp-builder 技能来处理“帮我构建一个待办事项应用”或“帮我构建一个用于追踪步数的仪表板”之类的请求时，分析表明：

1. 每次编写前端 Web 应用都需要使用相同的 HTML/React 样板代码
2. 将包含样板 HTML/React 项目文件的 assets/hello-world/ 模板存放在技能中会有所帮助

示例：创建 big-query 技能来处理“今天有多少用户登录过？”之类的请求时，分析表明：

1. 每次查询 BigQuery 都需要重新发现表结构及其关系
2. 将记录表结构的 references/schema.md 文件存放在技能中会有所帮助

要确定技能内容，请分析每个具体示例，并列出需要包含的可复用资源：脚本、参考资料和资源文件。

类别识别

确定该技能属于 9 个技能类别中的哪一类（完整分类体系及示例和结构指导，请参阅 references/skill-categories.md）：

1. 库与 API 参考
2. 产品验证
3. 数据获取与分析
4. 代码脚手架与模板
5. 代码质量与审查
6. CI/CD 与部署
7. 操作手册
8. 业务流程与团队自动化
9. 基础设施运维

列出类别并请用户确认。最理想的技能应明确归属一个类别。如果技能横跨两个类别，请指出这一点——可能需要将其拆分。类别会影响技能的结构模式和评估策略。

步骤 3：初始化技能

现在可以开始实际创建技能了。

仅当正在开发的技能已经存在，并且需要迭代或打包时，才跳过此步骤。在这种情况下，请继续下一步。

从头创建新技能时，务必运行 init_skill.py 脚本。该脚本可以便捷地生成新的技能模板目录，并自动包含技能所需的全部内容，从而大幅提高技能创建过程的效率和可靠性。

用法：

scripts/init_skill.py <skill-name> --path <output-directory>

该脚本会：

• 在指定路径创建技能目录
• 生成带有正确 frontmatter 和 TODO 占位符的 SKILL.md 模板
• 创建示例资源目录：scripts/、references/ 和 assets/
• 在每个目录中添加可自定义或删除的示例文件

初始化后，根据需要自定义或删除生成的 SKILL.md 和示例文件。

步骤 4：编辑技能

编辑（新生成或现有的）技能时，请记住，该技能是为另一个 Claude 实例创建的。重点纳入对 Claude 有益且不显而易见的信息。考虑哪些程序性知识、特定领域的细节或可复用资源能够帮助另一个 Claude 实例更有效地执行这些任务。

从可复用的技能内容开始

开始实施时，先从上文确定的可复用资源入手：scripts/、references/ 和 assets/ 文件。请注意，此步骤可能需要用户提供输入。例如，实现 brand-guidelines 技能时，用户可能需要提供品牌素材或模板，存放在 assets/ 中，或提供文档，存放在 references/ 中。

此外，删除技能不需要的示例文件和目录。初始化脚本会在 scripts/、references/ 和 assets/ 中创建示例文件，以演示目录结构，但大多数技能并不需要这些文件。

从文档填充参考资料（可选）

对于基于现有框架、库或工具且有在线文档的技能，请使用 Skill_Seekers（v2.0.0+）自动抓取文档并整理到 references/ 目录中。Skill_Seekers 现已支持统一的多来源抓取，可将文档网站、GitHub 仓库和 PDF 文件整合为全面的参考资料。

适用场景：

• 为在线文档详尽的框架构建技能（React、Django、FastAPI 等）
• 为游戏引擎创建技能（Godot、Unity）
• 编写基于 Web 文档的 API 或库的文档
• 直接从 GitHub 源代码中提取 API 参考资料
• 组合多个来源（文档 + 代码 + PDF），创建全面的技能
• 检测文档与实际实现之间的差异

快速开始：

# One-time setup
git clone https://github.com/yusufkaraaslan/Skill_Seekers.git ~/Skill_Seekers
cd ~/Skill_Seekers
pip install requests beautifulsoup4

# Option 1: Documentation-only scraping (classic approach)
python3 cli/doc_scraper.py --config configs/react.json
cp -r output/react/references/* /path/to/your-skill/references/

# Option 2: GitHub-only scraping (extract API from source code)
python3 cli/github_scraper.py --repo facebook/react --extract-api
cp -r output/react_github/references/* /path/to/your-skill/references/

# Option 3: Unified multi-source scraping (RECOMMENDED)
# Combines documentation + GitHub code + PDFs into one comprehensive skill
python3 cli/unified_scraper.py --config configs/react_unified.json
cp -r output/react_complete/references/* /path/to/your-skill/references/

# Option 4: Custom unified config
python3 cli/config_validator.py configs/myframework_unified.json
python3 cli/unified_scraper.py --config configs/myframework_unified.json

替代方案： 对于较简单的需求，或文档不基于 Web 的情况，可在 references/ 目录中手动创建参考文件。

有关 Skill_Seekers 的详细文档，请参阅 references/documentation-scraping.md。

更新 SKILL.md

写作风格： 使用祈使式／不定式（动词开头的指令）编写整个技能，而非使用第二人称。采用客观、指导性的语言（例如“要完成 X，请执行 Y”，而不是“你应该执行 X”或“如果你需要执行 X”）。这样可确保内容一致、清晰，便于 AI 使用。避免使用全大写来强调内容，改用粗体 Markdown 或章节标题。避免使用 CRITICAL／MANDATORY／MUST 等限定词；对于 Claude 4.6，直接使用祈使句即可。

要完成 SKILL.md，请回答以下问题：

1. 用几句话说明技能的用途。
2. 应在何时使用该技能？
3. 在实际使用中，Claude 应如何使用该技能？请引用上文开发的所有可复用技能内容，让 Claude 知道如何使用它们。

技能编写理念

编写技能指令时，请遵循以下改编自 Anthropic 技能创建研究的原则：

解释每件事背后的“原因”。 解释推理过程的指令，比单纯的命令更能帮助模型举一反三。“使用脚本验证输出，因为扫描文档中常见 OCR 错误”比“运行验证脚本”更有效。Claude 能将这些推理推广到指令未涵盖的新情境。

保持提示词精简。 SKILL.md 中的每个令牌都要与用户的实际任务争夺上下文。将参考资料移至 references/，将详细示例移至 assets/，将重复逻辑移至 scripts/。技能正文只应包含 Claude 决定做什么所需的内容，而非关于如何做的详尽细节。

将重复工作封装到脚本中。 如果相同代码出现在多次测试运行或评估记录中，就将其提取到脚本里。脚本能节省令牌（只有输出会进入上下文）、具有确定性且可缓存。查看各测试用例中的模式，找出可封装的部分。

让描述稍微“主动”一些。 技能触发不足的情况比过度触发更常见。主动声明适用范围的描述（例如“遇到以下情况时应使用此技能”，并列出具体触发短语）比被动描述效果更好。请加入用户自然会说出的关键词。

Claude 4.6 提示词编写规范

编写或审阅技能指令时，请遵循以下模式：

语言校准：

• 使用直接的祈使句，不要用全大写字母强调。“使用 Firecrawl 抓取网页”，而不是“务必使用 Firecrawl”或“你必须使用 Firecrawl”。
• 将 CRITICAL／MANDATORY／MUST 标记替换为普通标题。Claude 4.6 能很好地遵循结构清晰的指令，无需强制语气。
• 解释指令背后的原因。“使用 --only-main-content 可减少令牌消耗”，而不是“务必使用 --only-main-content”。Claude 能更好地根据解释举一反三。

移除反懒惰提示：

• 不要加入“全面细致”“仔细思考”“不要偷懒”等要求或激励性措辞。Claude 4.6 已经积极主动，这类措辞会让它过度规划，或陷入先写后改的循环。

子 Agent 指引（适用于编排类技能）：

• 明确说明何时不应启动 Agent。Claude 4.6 即使直接处理更快，也倾向于调用子 Agent。
• “任务可以并行执行或需要隔离上下文时使用 Agent。对于顺序任务、单文件编辑，或可在 5 分钟内完成的工作，请直接处理。”

避免过度积极：

• 加入关于最小化解决方案的指引。事实性质量标准（如“遵循现有惯例”）比激励性措辞（如“对抗熵增”）更有效。

第 5 步：打包技能

技能准备就绪后，应将其打包成可分发的 zip 文件并分享给用户。打包过程会先自动验证技能，确保其符合所有要求：

scripts/package_skill.py <path/to/skill-folder>

可选的输出目录指定方式：

scripts/package_skill.py <path/to/skill-folder> ./dist

打包脚本将：

1. 验证技能，自动检查：

   • YAML frontmatter 格式和必填字段
   • 技能命名规范和目录结构
   • 描述的完整性和质量
   • 文件组织和资源引用

2. 如果验证通过，则打包技能，创建一个以技能命名的 zip 文件（例如，my-skill.zip），其中包含所有文件，并保持正确的目录结构以供分发。

如果验证失败，脚本会报告错误并退出，不会创建软件包。修复所有验证错误，然后再次运行打包命令。

第 6 步：测试与评估

打包后，系统地测试技能，以衡量其效果。此步骤将 Anthropic 的评估框架改编用于技能质量测量。

两类技能

编写评估之前，先确定技能属于哪一类——这将决定评估策略：

• 能力提升：帮助 Claude 稳定完成没有该技能时无法做到的事情（例如，填写 PDF 表单、生成特定文件格式）。评估策略：比较使用和不使用该技能时的输出。
• 偏好编码：将 Claude 已能完成的工作流步骤按顺序组织起来，但编码了特定偏好或领域知识（例如，编码风格指南、品牌语气）。评估策略：将输出与经过人工审核的黄金标准进行比较。

有关针对不同类别的技能采取不同评估策略（如何区别评估 Library/API 技能与 Runbook 或 Verification 技能），请参阅 references/skill-categories.md。

编写评估

在技能目录中创建 evals/evals.json，其中包含 2-5 个真实的测试提示词：

{
  "skill_name": "example-skill",
  "evals": [
    {
      "id": 1,
      "prompt": "User's example prompt",
      "expected_output": "Description of expected result",
      "files": ["evals/files/sample1.pdf"],
      "expectations": [
        "The output includes X",
        "The skill used script Y"
      ]
    }
  ]
}

每个评估都需要：

• 用户实际会提出的真实提示词
• 可选输入文件（放在 evals/files/ 中）
• 对预期输出的易读说明
• 3-7 条可验证的预期结果，供评分器对照输出进行检查

请将预期结果写成具体、可证伪的陈述，而不是含糊的质量判断。“输出包含一张有 5 列的表格”是可验证的；“输出格式良好”则不是。

运行评估

使用评估运行器脚本执行评估：

# Run evals with the skill active
python3 scripts/run_eval.py --eval-set evals/evals.json --skill-path <skill-path>

# Run with multiple attempts per query for reliability
python3 scripts/run_eval.py --eval-set evals/evals.json --skill-path <skill-path> --runs-per-query 3

每次运行都会生成一个输出目录，其中包含技能的输出、记录文本以及时间和令牌指标。

评分

运行评估后，根据预期结果对输出进行评分。评分器 Agent（agents/grader.md）会根据证据，将每项预期评为 PASS/FAIL，从输出中提取隐含主张，并根据记录文本总结执行器的行为。

评分会生成包含通过率、执行指标和时间数据的 grading.json。完整架构请参阅 references/schemas.md。

基准测试

如需汇总多次运行的结果：

python3 scripts/aggregate_benchmark.py <benchmark-dir> --skill-path <skill-path>

这会生成 benchmark.json，其中包含使用技能和不使用技能配置下通过率、耗时和令牌用量的统计汇总（平均值、标准差）。随后，分析器 Agent（agents/analyzer.md）会揭示汇总指标可能掩盖的模式——无法区分优劣的断言、方差较大的评估，以及质量与速度之间的权衡。

查看结果

启动评估查看器，进行定性和定量审查：

# Interactive server (auto-refreshes on new outputs)
python3 eval-viewer/generate_review.py <workspace-path>

# Static HTML export
python3 eval-viewer/generate_review.py <workspace-path> --static review.html

# With previous iteration context
python3 eval-viewer/generate_review.py <workspace-path> --previous-workspace <prev-workspace>

# With benchmark data
python3 eval-viewer/generate_review.py <workspace-path> --benchmark <benchmark.json>

查看器包含两个选项卡：Outputs（定性审查，可针对每次运行提供反馈）和 Benchmark（以图表显示定量通过率、耗时和令牌数据）。

盲测 A/B 比较

要比较两个技能版本，请使用比较器 Agent（agents/comparator.md）。它接收标记为 A 和 B 的输出，但不知道由哪个技能生成，从而避免偏向某种方法。比较器会生成包含内容和结构两个维度的评估标准，对每个输出按 1-5 分评分，并选出胜者。

比较完成后，分析器 Agent 会揭盲结果，并生成可执行的改进建议，按优先级（高/中/低）和类型（instructions、tools、examples、error_handling、structure、references）分类。

版本跟踪

在 history.json 中跟踪各轮改进：

{
  "skill_name": "pdf",
  "current_best": "v2",
  "iterations": [
    {"version": "v0", "parent": null, "expectation_pass_rate": 0.65, "grading_result": "baseline"},
    {"version": "v1", "parent": "v0", "expectation_pass_rate": 0.75, "grading_result": "won"},
    {"version": "v2", "parent": "v1", "expectation_pass_rate": 0.85, "grading_result": "won"}
  ]
}

步骤 7：描述优化

技能描述决定 Claude 何时使用该技能。描述薄弱会导致触发不足（应调用技能时未调用）或过度触发（不应调用技能时却调用）。此步骤将系统地优化描述。

生成触发评估查询

创建 20 条测试查询：10 条应触发技能，另外 10 条不应触发。加入真实的边缘案例——这些查询与技能的适用领域接近，但不应触发技能。

对于 pdf-editor 技能，示例：

• 应触发：“将这个 PDF 旋转 90 度”“合并这三个 PDF”“从这个文档中提取第 5 页”
• 不应触发：“阅读这个 PDF 并进行总结”“将这个 Word 文档转换为 PDF”“这个 PDF 包含什么内容？”

运行优化循环

python3 scripts/run_loop.py \
  --eval-set trigger-queries.json \
  --skill-path <skill-path> \
  --holdout 0.4 \
  --runs-per-query 3 \
  --max-iterations 5 \
  --model sonnet

循环步骤：

1. 将查询拆分为 60% 的训练集和 40% 的测试集
2. 每个查询运行 3 次以确保可靠性（多数表决）
3. 分析训练集中的失败情况
4. 使用扩展思考生成改进后的描述
5. 在留出的测试集上进行评估
6. 重复上述步骤，直到收敛或达到最大迭代次数

审查并采用

循环会生成一份 HTML 报告，展示各次迭代的准确率变化。请审查最终描述——它应足够具体，以避免过度触发，同时也应足够全面，能够涵盖合理的使用场景。

如果优化后的描述提高了测试集准确率，请更新该技能 YAML frontmatter 中的 description 字段。如果准确率停滞或下降，请保留当前描述，并调查是否需要改进触发查询。

第 8 步：迭代

测试技能后，用户可能会要求改进。通常，这种情况会发生在使用技能后不久，此时用户对技能的表现仍有清晰的印象。

迭代工作流：

1. 在实际任务中使用该技能
2. 留意遇到的困难或低效之处
3. 确定应如何更新 SKILL.md 或随附资源
4. 实施更改并再次测试

对于需要按用户配置、持久记忆、会话级钩子或使用情况分析的技能，请参阅 references/advanced-patterns.md。

分享技能

技能可以在不同范围内分发：

• 项目技能：将 .claude/skills/ 提交到版本控制
• 插件：在你的插件中创建 skills/ 目录
• 托管：通过托管设置在整个组织范围内部署

有关何时使用各个层级、技能的自然晋级（个人 -> 项目 -> 插件 -> 托管），以及技能组合维护（上下文预算、整理、约 40 个 Agent 的上限）的指导，请参阅 references/distribution-strategy.md。

故障排除

技能未触发

如果 Claude 没有在预期情况下使用某个技能：

1. 检查描述是否包含用户自然会说出的关键词
2. 确认在回答“有哪些可用技能？”时，该技能会显示出来
3. 尝试改写请求，使其与描述更加匹配
4. 如果该技能允许用户主动调用，请使用 /skill-name 直接调用

技能触发过于频繁

如果 Claude 在你不希望使用技能时仍然使用它：

1. 让描述更加具体
2. 如果只希望手动调用，请添加 disable-model-invocation: true

Claude 看不到所有技能

技能描述会加载到上下文中。如果技能数量很多，可能会超出字符预算（默认 15,000 个字符）。运行 /context，检查是否有关于技能被排除的警告。

如需提高上限，请设置 SLASH_COMMAND_TOOL_CHAR_BUDGET 环境变量。

相关资源

• 子 Agent：将任务委派给专用 Agent
• 插件：将技能与其他扩展打包并分发
• 钩子：围绕工具事件自动执行工作流
• 记忆：管理 CLAUDE.md 文件，以提供持久上下文
• 权限：控制工具和技能的访问权限