skill-master

Skill Master

按照开放规范 agentskills.io 创建、编辑并验证 Agent Skills。此 skill 是创建和维护 Agent Skills 的入口。

语言要求： 所有 skills 必须使用英文撰写。

链接

• Agent Skills Specification
• What are Skills?
• Integrate Skills
• The Complete Guide to Building Skills for Claude（Anthropic）

快速导航

• 初次接触 skills？阅读：references/specification.md
• 需要 SKILL.md 模板？参见：assets/skill-templates.md
• 想撰写有效的描述和指令？阅读：references/writing-skills.md
• 想组织多步骤流程？阅读：references/workflows.md
• 想为 skill 添加脚本？阅读：references/scripts.md
• 想为 skill 添加资源/模板？阅读：references/assets.md
• 高级功能（上下文、agents、hooks）？阅读：references/advanced-features.md
• 想从文档创建？阅读：references/docs-ingestion.md
• 测试、评估、基准测试或迭代改进？阅读：references/testing-troubleshooting.md、references/eval-testing.md、references/iterative-improvement.md
• 描述优化？阅读：references/description-optimization.md
• JSON schemas（评估、评分、基准测试）？阅读：references/schemas.md
• 评估集审查 UI 和输出查看器？参见：assets/eval_review.html、eval-viewer/
• 验证和打包？参见：scripts/

何时使用

• 从零开始创建新 skill
• 更新现有 skill
• 通过引入外部文档创建 skill
• 验证或打包 skill 以便分发
• 运行完整的 skill-creator 式循环：访谈、起草、评估、基准测试、查看器审查和迭代

skill-master 涵盖 skill-creator；有关详细的操作指南、工作区布局、耗时记录、基准分析和查看器交接，请阅读 references/iterative-improvement.md。

Skill 结构（必需）

my-skill/
├── SKILL.md          # Required: instructions + metadata (must be human-readable too)
├── metadata.json     # Optional: extended metadata for publishing
├── references/       # Optional: documentation, guides, API references
├── examples/         # Optional: sample outputs, usage examples
├── scripts/          # Optional: executable code
└── assets/           # Optional: templates, images, data files

不要在 skill 文件夹中包含 README.md。SKILL.md 是唯一事实来源。如果迁移带有 README.md 的 skill，请将其内容合并到 SKILL.md 并删除它。

文件夹用途（关键）

文件夹	用途	示例
references/	供 agent 阅读的文档	指南、API 文档、概念说明、故障排除
examples/	展示预期格式的示例输出	输出示例、用法演示
assets/	供复制/使用的静态资源	文档模板、配置模板、图像、schemas
scripts/	供运行的可执行代码	Python 脚本、shell 脚本、验证器

各文件夹的使用时机

• references/ — agent 阅读并理解的文档
• examples/ — 展示预期格式的示例输出
• assets/ — 可原样复制的模板、配置、schemas
• scripts/ — agent 运行的可执行代码

重要：模板属于 assets/，示例属于 examples/，文档属于 references/。

Frontmatter Schema

每个 SKILL.md 必须以 YAML frontmatter 开头：

---
name: skill-name
description: "What it does. Keywords: term1, term2."
metadata:
  author: your-name
  version: "1.2.3"
  release_date: "2026-01-01"
---

字段顺序： name → description → license → compatibility → metadata

必填字段

字段	约束条件
name	1-64 个字符，小写 a-z0-9-，不能有 --，不能以 - 开头或结尾，必须与文件夹名一致
description	1-1024 个字符（目标：80-150），描述技能做什么 + 何时使用，需包含关键词

可选字段（顶层）

字段	用途
license	许可证名称或对捆绑 LICENSE 文件的引用
compatibility	环境要求（最多 500 个字符）
metadata	用于任意键值对的对象（见下文）

metadata 对象（常见字段）

字段	用途
author	作者姓名或组织
version	上游产品版本或技能版本
release_date	最后一次有意义的更新日期（YYYY-MM-DD）
argument-hint	自动补全提示，例如 [issue-number]

可选字段（Claude Code / 高级）

字段	用途
disable-model-invocation	true = 仅用户可调用（通过 /name）。默认值：false
user-invocable	false = 从 / 菜单隐藏，仅 Agent 可加载。默认值：true
allowed-tools	以空格分隔的工具列表，Agent 无需询问即可使用，例如 Read Grep Glob
model	技能激活时使用的特定模型
context	设为 fork 以在派生的子 Agent 上下文中运行
agent	当 context: fork 时的子 Agent 类型，例如 Explore、Plan
hooks	作用于技能生命周期的钩子（参见 Agent 文档）

调用控制矩阵

Frontmatter	用户可调用	Agent 可调用	备注
（默认）	✅ 是	✅ 是	描述在上下文中，使用时加载
disable-model-invocation: true	✅ 是	❌ 否	用于带副作用的手动工作流
user-invocable: false	❌ 否	✅ 是	背景知识，而非命令

变量替换

技能内容中可用的占位符：

变量	描述
$ARGUMENTS	调用技能时传入的所有参数
${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.

动态上下文注入

使用 !command`` 语法在技能内容发送给 Agent 之前运行 shell 命令：

## Pull request context

- PR diff: !`gh pr diff`
- Changed files: !`gh pr diff --name-only`

## Your task

Review this pull request...

命令输出会替换占位符，因此 Agent 接收的是实际数据。

metadata.json（可选）

若要发布或使用扩展元数据，请创建 metadata.json：

{
  "version": "1.0.0",
  "organization": "Your Org",
  "date": "January 2026",
  "abstract": "Brief description of what this skill provides...",
  "references": ["https://docs.example.com", "https://github.com/org/repo"]
}

字段：

• version — 技能版本（semver）
• organization — 作者或组织
• date — 发布日期
• abstract — 扩展描述（可比 frontmatter 更长）
• references — 源文档 URL 列表

名称校验示例

# Valid
name: pdf-processing
name: data-analysis
name: code-review

# Invalid
name: PDF-Processing  # uppercase not allowed
name: -pdf            # cannot start with hyphen
name: pdf--processing # consecutive hyphens not allowed

描述规则

目的： 告诉大模型该技能做什么以及何时激活它。尽量减少 token——只需足够做出激活决定即可。

公式：

对于库/参考类技能（Claude Code，基于关键词发现）：

[Product] [core function]. Covers [2-3 key topics]. Keywords: [terms].

对于工作流/自动化类技能（Claude.ai，基于触发器激活）：

[What it does]. Use when user [specific trigger phrases].

对自动触发至关重要： 包含明确的“当用户说 / 询问 / 提到……时使用”这类短语。没有它们，Claude 可能不会自动加载该技能。有关好/坏示例和调试技巧，请参见 references/writing-skills.md。

约束：

• 目标：80-150 个字符
• 上限：1024 个字符（若保持极简则为 300）
• 不要营销用语（“强大”、“全面”、“现代”）
• 不要填充词（“此技能”、“用于”、“有助于”）
• 不要 XML 尖括号 < >
• 名称中包含 “claude” 或 “anthropic” 的为保留名称

好的示例：

description: "Turso SQLite database. Covers encryption, sync, agent patterns. Keywords: Turso, libSQL, SQLite."

description: "Base UI unstyled React components. Covers forms, menus, overlays. Keywords: @base-ui/react, render props."

description: "Inworld TTS API. Covers voice cloning, audio markups, timestamps. Keywords: Inworld, TTS, visemes."

差的示例：

# Too vague
description: "Helps with PDFs."

# Too verbose
description: "Turso embedded SQLite database for modern apps and AI agents. Covers encryption, authorization, sync, partial sync, and agent database patterns."

# Marketing
description: "A powerful solution for all your database needs."

关键词： 产品名称、包名称，最多 3-5 个词条。

技能如何工作（渐进式披露）

1. 发现：Agent 只加载每个技能的 name + description（约 50-100 个 token）
2. 激活：当任务匹配时，Agent 将完整的 SKILL.md 读入上下文
3. 执行：Agent 遵循指令，按需加载引用的文件

关键规则： 保持 SKILL.md 在 500 行以内。将细节移到 references/。

创建新技能

专业提示：你可以使用 skill-creator 技能（在 Claude.ai 或 Claude Code 中可用）交互式生成你的初稿，然后使用以下步骤进行优化。

步骤 1：搭建脚手架

python scripts/init_skill.py <skill-name>
# Or specify custom directory:
python scripts/init_skill.py <skill-name> --skills-dir skills

或手动创建：

<skills-folder>/<skill-name>/
├── SKILL.md
├── references/   # For documentation, guides
└── assets/       # For templates, static files

步骤 2：编写 Frontmatter

---
name: <skill-name>
description: "[Purpose] + [Triggers/Keywords]"
---

步骤 3：编写正文

推荐章节：

• 何时使用（触发器、场景）
• 快速导航（指向 references 和 assets 的路由）
• 步骤 / 配方 / 检查清单
• 关键禁止事项
• 链接

步骤 4：添加 References（文档）

为每个主要主题创建 references/<topic>.md，包含：

• 可执行的要点（5-15 条）
• 陷阱 / 禁止事项
• 实用示例

步骤 5：添加 Scripts（如适用）

关于何时值得编写脚本以及如何组织它们，请查阅 references/scripts.md。

语言选择：

• Python——CLI 包装器、验证器、脚手架搭建的默认选择
• Go——当该技能的生态为 Kubernetes/云原生时（参见 k8s-cluster-api）
• JS/TS——当该技能的生态为 Node/npm 时

脚本的最小检查清单：

• 为所有参数使用 argparse（Python）或 flag（Go）——不要硬编码值
• 使用前检查工具是否可用（Python 中为 shutil.which()）
• 顶部包含带有 Usage + Examples 的文档字符串
• 捕获所有异常；以非零状态退出并向 stderr 输出消息

步骤 6：添加 Assets（如需要）

关于何时值得创建 assets 以及如何格式化它们，请查阅 references/assets.md。

对于模板或静态资源，创建 assets/<resource>。常见类型：

• 配置模板——.minimal.yaml / .full.yaml 配对；添加 # yaml-language-server: $schema= 头
• YAML 清单——使用 ${VAR_NAME:=default} 表示变量；顶部包含用途 + 用法注释
• 文本模板——使用以 # 为前缀的注释来解释字段和有效值
• Markdown 检查清单 / 运行手册——- [ ] 复选框、内联命令、签署部分
• 提示词 / 散文模板——按用例分组，每个块自包含

命名：<tool>.minimal.yaml、<purpose>-checklist.md、<name>.template、<topic>-prompts.md。

步骤 7：验证

python scripts/quick_validate_skill.py <skill-path>
# Compatibility alias:
python scripts/quick_validate.py <skill-path>

从文档创建技能

从外部文档构建技能时，使用自主摄取工作流：

阶段 1：搭建脚手架

1. 创建技能文件夹，包含 SKILL.md 骨架
2. 创建 plan.md 用于进度跟踪
3. 创建 references/ 目录

阶段 2：构建队列

对于每个文档链接：

• 抓取该页面
• 提取内部文档链接（避免导航重复项）
• 排定优先级：概念 → API → 操作 → 故障排查

阶段 3：摄取循环

对每个页面：

1. 抓取 一个 页面
2. 创建 references/<topic>.md，包含可操作的摘要
3. 更新 plan.md 复选框
4. 如果添加了有用的配方/规则，则更新 SKILL.md

不要在每个页面后询问用户 — 自主继续。

阶段 4：最终确定

• 检查 SKILL.md 的完整性
• 确保内容是实用配方，而非文档镜像
• plan.md 可在摄取后手动删除

关键禁令

• 不要从供应商文档中逐字复制大段内容（用自己的话总结）
• 不要用英语以外的语言编写技能
• 不要包含项目特定的机密、路径或假设
• 不要让 SKILL.md 超过 500 行
• 不要跳过 name 验证（必须与文件夹名称匹配）
• 不要使用缺乏触发关键词的糟糕描述
• 从文档创建技能时不要省略产品版本

版本跟踪

version 的含义

在本仓库中，将版本元数据存储为 metadata.version 和 metadata.release_date，以匹配现有技能和当前 Copilot 技能文件验证。 metadata.version 保存技能构建时所基于的 上游产品版本（例如，CAPI v1.12.3 对应 "1.12.3"）。对于不绑定外部产品的独立技能，它保存 技能自身的版本（例如，skill-master 对应 "1.2.4"）。 当产品使用持续部署且没有语义化版本控制时（例如 Cloudflare Workers 等托管服务），使用 "—"。

何时更新

触发条件	更新 metadata.version	更新 metadata.release_date
产品发布了新版本	✅ 是	✅ 是
内容变更，无上游版本	❌ 否	✅ 是
拼写错误或小幅修复	❌ 否	❌ 否

当提升 metadata.version 或进行重大内容更改时，还要更新：

• SKILLS_VERSIONS.md — 设置新版本 + 日期，将行移到表格顶部
• CHANGELOG.md — 在顶部添加新的带日期块

链接格式：

## Links

- [Documentation](https://example.com/docs)
- [Changelog](https://example.com/changelog)
- [GitHub](https://github.com/org/repo)
- [npm](https://www.npmjs.com/package/name)

顺序：文档 → 变更日志/发布 → GitHub → 包注册表。仅包含适用的链接。

验证清单

专业提示：你可以使用 skill-creator 技能（在 Claude.ai 或 Claude Code 中可用）来审查你的技能，并在最终确定前提出改进建议。

• name 与文件夹名称匹配，kebab-case，1-64 个字符，无 --
• description 包含它做什么以及何时使用（触发短语）
• description 没有 XML 尖括号 < >
• SKILL.md 少于 500 行
• 文档在 references/ 中，模板在 assets/ 中
• 复杂的多步骤流程提取到 references/workflows.md
• 所有文本为英语
• 技能在明显的测试查询上触发
• 技能在不相关的查询上不触发

完整的发布前清单：references/testing-troubleshooting.md

脚本

脚本	用途
init_skill.py	搭建新的 Agent Skill（agentskills.io）
init_copilot_asset.py	搭建 Copilot 专用资产（指令、Agent）
quick_validate_skill.py	校验 skill 结构
quick_validate.py	兼容旧版校验工作流的包装脚本
package_skill.py	将 skill 打包为可分发的 zip
run_eval.py	通过 claude -p 运行评估，使用并行 worker
run_loop.py	带训练/测试划分的评估 + 改进循环
improve_description.py	利用评估反馈改进 skill 描述
aggregate_benchmark.py	将评分结果汇总为基准统计数据
generate_report.py	根据循环迭代数据生成 HTML 报告

Agent：agents/grader.md（评分预期）、agents/comparator.md（盲测 A/B 对比）、agents/analyzer.md（事后分析 + 基准）

链接

• 规范：references/specification.md
• 编写 Skills（描述、指令、模式）：references/writing-skills.md
• 工作流模式：references/workflows.md
• Skills 中的脚本：references/scripts.md
• Skills 中的资产：references/assets.md
• 测试与故障排查：references/testing-troubleshooting.md
• 高级功能：references/advanced-features.md
• SKILL.md 模板：assets/skill-templates.md
• 文档摄取：references/docs-ingestion.md
• 评估测试与基准测试：references/eval-testing.md
• 迭代改进循环：references/iterative-improvement.md
• 描述优化：references/description-optimization.md
• JSON Schema：references/schemas.md
• 评估集审查：assets/eval_review.html
• 评估输出查看器：eval-viewer/
• 官方规范：https://agentskills.io/specification
• Claude Code skills：https://code.claude.com/docs/en/skills