如何为 Claude Code 创建高质量 Skill：完整案例

每次都在重复同样的 Prompt

你有没有这种经历？

每周五写项目周报，你打开 Claude Code，花两分钟描述格式要求：标题用什么格式、分几个板块、哪些指标必须包含、语气要专业但不呆板。Claude 给你生成了一份不错的周报。下周五，你又得重新描述一遍。

或者你在做前端开发，每次让 Claude 写组件都要先说一遍："用 TypeScript、遵循 React 19 的模式、样式用 Tailwind、不要用 class component。"说了一百遍，它还是偶尔给你写个 useState 的时候忘了加类型注解。

这些重复的、结构化的指令，其实不应该每次都由你手动传达。它们应该被打包成一个东西，让 Claude 在需要的时候自动加载。

这个东西就是 Skill。

Skill 不是代码，不是插件，不是 MCP 服务器。它是一组结构化的指令——打包成一个文件夹——教 Claude 如何处理特定任务。你可以把它理解为一本"操作手册"：Claude 遇到相关任务时会自动翻开它，按照里面的指引来做。

这篇文章会带你走完一个 Skill 从构思到发布的全过程。但在动手之前，我想先介绍三样你必须知道的东西。

三项官方资源——你的学习起点

Anthropic 为 Skill 创建提供了三项核心资源，它们各自承担不同角色，组合起来构成了完整的学习体系。

The Complete Guide to Building Skills for Claude

这是 Anthropic 发布的官方 PDF 指南，共 30 页，覆盖从概念理解到分发上线的完整流程。全文分为六章：

这是你的"教科书"。如果你只读一样东西，读这个。

Skill Creator Skill

这是 Anthropic 内置在 Claude Code 中的一个元技能——一个用来创建其他 Skill 的 Skill。它有 486 行指令，内部包含专用的评分 Agent、盲比较 Agent、分析 Agent，以及一套完整的 Python 自动化脚本。

调用方式极其简单：

CopyUse the skill-creator skill to help me build a skill for [your use case]

Skill Creator 会引导你完成意图捕获、访谈研究、撰写 SKILL.md、创建测试用例的全流程。它自身的目录结构就是一个优秀的 Skill 架构范例：

Copyskill-creator/
├── SKILL.md              # 主指令（486 行）
├── agents/               # 专用 SubAgent 指令
│   ├── grader.md
│   ├── comparator.md
│   └── analyzer.md
├── references/
│   └── schemas.md        # 七种 JSON 结构定义
├── scripts/              # Python 自动化脚本（8 个）
└── assets/
    └── eval_review.html  # 评审 UI 模板

这是你的"实验室"。想创建 Skill 但不知道从何下手？让 Skill Creator 带你走。

16 个官方示例 Skills

Anthropic 的 Skills 仓库包含 16 个完整示例，从最简到生产级，覆盖了所有常见的设计模式：

• brand-guidelines（约 74 行）：最简型——只有一个 SKILL.md，纯知识嵌入，没有脚本，没有引用文件。适合理解 Skill 的最低配置
• theme-factory（约 60 行 + assets 目录）：展示如何用 assets/ 目录存放可视化资源，让用户选择主题
• pdf（约 315 行 + 8 个 Python 脚本 + 2 个 reference 文件）：脚本密集型典范，展示渐进式披露的完整实践——SKILL.md 放核心指令，reference.md 放高级内容，scripts/ 放确定性操作
• mcp-builder（约 237 行 + 4 个 reference 文件）：展示大型 Skill 如何用 reference/ 目录按主题分文件，让 SKILL.md 作为"路由器"

这是你的"案例库"。看别人怎么做的，比自己摸索快十倍。

三者的互补关系：PDF 是教科书——告诉你原理和方法论；Skill Creator 是实验室——带你实际动手；官方示例是案例库——让你看到成熟的模式长什么样。从 PDF 开始理解概念，用 Skill Creator 开始实践，遇到不确定的设计决策时翻案例库找灵感。

确定用例：从痛点出发

好了，资源就绪，现在该动手了。但先别急着写代码——最重要的一步是确定你的 Skill 要解决什么问题。

官方指南把 Skill 用例分为三类：

我的痛点是周报，属于 Document Creation。具体来说：

• 每周五需要一份项目周报
• 格式固定：本周完成、下周计划、风险项、关键指标四个板块
• 语气要求：专业但不呆板，数据驱动但不堆砌
• 关键指标来自 Git 提交记录和项目管理工具

确定了用例之后，建议你再想 2-3 个具体的使用场景。不是泛泛地说"帮我写周报"，而是具体到"周五下午，我需要一份包含本周 Git 提交摘要、项目进度百分比和风险预警的周报"。场景越具体，后面写 SKILL.md 的指令就越精准。

规划结构：从最简开始

Skill 的最简结构极其简单——一个文件夹，里面一个 SKILL.md：

Copyweekly-report/
└── SKILL.md

SKILL.md 由两部分组成：YAML frontmatter（元数据）和 Markdown body（指令正文）。

YAML frontmatter

frontmatter 是 Skill 的"身份证"。其中最关键的字段是 description——它决定了 Claude 是否会在遇到相关任务时加载你的 Skill。

Copy---
name: weekly-report
description: >
  Generate structured weekly project reports from Git activity
  and project management data. Use when the user asks to "write
  a weekly report", "create a status update", "summarize this
  week's progress", or mentions "周报" or "项目进展".
  Produces consistent four-section reports with completion summary,
  next-week plan, risk items, and key metrics.
---

description 的写作有一个公式：What it does + When to use it + Key capabilities。

这里有一个重要的设计细节：Claude 对 Skill 有"触发不足（undertrigger）"的倾向——它倾向于不加载 Skill，自己硬做。所以 description 应该写得"pushy"一些，多列举用户可能说的短语和关键词。宁可过度触发（之后再调），也不要触发不足。

反面教材是什么样的？

CopyHelps with reports.

太模糊。Claude 不知道什么时候该用它。

CopyCreates sophisticated multi-page documentation systems.

缺少触发条件。用户不会说"我要创建一个 sophisticated multi-page documentation system"。

命名规范

文件夹和 name 字段必须用 kebab-case（小写字母 + 连字符）。不要用空格、下划线或驼峰命名。SKILL.md 的文件名必须精确大写——不接受 skill.md、SKILL.MD 或任何变体。

编写核心指令：解释 Why，而不是堆 MUST

SKILL.md 的 Markdown body 是你的核心指令区。这里的写作质量直接决定了 Skill 的效果。

Skill Creator 的改进哲学中有一条核心原则：

如果发现自己在写 ALWAYS 或 NEVER 全大写，那是黄旗——重构为解释推理，让模型理解为什么这件事重要。

今天的 LLM 足够聪明。它们有良好的推理能力，当你解释了"为什么"之后，它们能举一反三地处理你没有预见到的边缘情况。而堆砌 MUST 和 NEVER 只会让指令变得僵硬且容易过时。

看一组对比：

Copy<!-- 差：堆砌命令 -->
ALWAYS include exactly 4 sections. NEVER use bullet points in the
summary section. MUST include at least 3 metrics.

Copy<!-- 好：解释推理 -->
## Report Structure
The report uses four sections because stakeholders scan reports in
under 30 seconds — they need a predictable structure to find what
they care about. The sections are:
1. **Completion Summary** — paragraph form, not bullets, because
   narrative reads faster for 3-5 items
2. **Next Week Plan** — prioritized list with owners
3. **Risk Items** — only items that need action, not general concerns
4. **Key Metrics** — 3-5 numbers with week-over-week trend arrows

第二种写法不仅告诉 Claude "做什么"，还告诉它"为什么这样做"。这意味着当它遇到只有 2 个完成项时，它会自然地写成段落而不是硬凑 5 个 bullet point——因为它理解了"段落适合少量条目"的底层逻辑。

渐进式披露

Skill 系统的核心架构设计是三级渐进加载：

这意味着：SKILL.md 应该保持精简，放核心指令。详细的参考文档、模板、示例代码应该移到 references/ 或 scripts/ 目录，通过 SKILL.md 中的链接引用。

Copy## Formatting Reference
For detailed formatting rules and examples, consult
`references/report-format.md` before generating the report.

scripts 目录下的脚本有一个特别的优势：Claude 可以直接执行它们而不需要把代码读进上下文。这对节省 context window 极为重要——脚本是确定性的，不需要 Claude "理解"就能使用。

测试和迭代：双向对比才有说服力

Skill 写完了，怎么知道它有没有用？

最有效的方式是双向测试：同一个请求，分别在有 Skill 和没有 Skill 的情况下运行，对比输出质量。这不是主观感觉"好像好了一点"，而是可量化的对比。

Skill Creator 提供了 evals.json 框架来支持这种测试：

Copy{
  "skill_name": "weekly-report",
  "evals": [
    {
      "id": "standard-weekly",
      "prompt": "帮我写本周的项目周报",
      "expectations": [
        "包含四个标准板块",
        "使用段落形式总结完成项",
        "风险项有明确的建议行动"
      ]
    },
    {
      "id": "light-week",
      "prompt": "这周没什么大事，帮我写个简短的周报",
      "expectations": [
        "仍然保持四板块结构",
        "内容简洁但不敷衍",
        "指标部分标注'无显著变化'"
      ]
    }
  ]
}

先不写 assertions（预期断言），运行一遍看看实际输出，然后再根据实际情况补充。这是 Skill Creator 推荐的做法——先观察，再约束。

迭代信号

测试之后，你会遇到四种信号：

一个重要的改进原则：从反馈中泛化，而不是过拟合。你的 Skill 会被使用很多次，不能只为当前的测试用例优化。如果某个修改只是为了让某一个测试通过，而对其他场景没有帮助甚至有害，那就不应该做。

发布与维护

Skill 测试完毕，可以投入使用了。安装路径取决于你的使用范围：

把文件夹放到对应路径即可。Claude Code 会自动发现并注册你的 Skill。

关于 Skill 系统的最新变化

如果你之前用过 Claude Code 的 Commands（.claude/commands/），有一个重要的变化需要了解：Commands 已合并入 Skills 系统。旧的 .claude/commands/ 目录仍然可用，但 Skills 是现在推荐的方式——它有更完整的渐进式加载机制和更丰富的元数据支持。

Skill 的 YAML frontmatter 也新增了几个实用字段：

• effort：指定 Skill 的 effort 级别（low / medium / high / max），让特定 Skill 自动使用更高的推理深度
• hooks：在 Skill 内部定义生命周期钩子，Skill 激活期间自动生效
• paths：基于文件路径的条件加载——只在操作匹配文件时才触发 Skill
• context: fork：在隔离的 SubAgent 中执行 Skill，不影响主会话的上下文

此外，Skill 已发布为开放标准（Agent Skills）。同一个 SKILL.md 可以在 Claude Code、Cursor、Gemini CLI、Codex CLI 等工具间通用——你的 Skill 不会被锁定在单一平台上。

社区分享

如果你创建了一个好用的 Skill，可以把它打包为 .zip 上传到 Claude.ai 的 Settings > Capabilities > Skills，或者发布到 GitHub 让其他人使用。

回顾：一个 Skill 的诞生

从"每周五重复写一遍格式要求"的痛点出发，我们走过了完整的 Skill 创建流程：

1. 确定用例——从具体的工作流痛点出发，而不是为了创建 Skill 而创建
2. 规划结构——从最简的单文件开始，按需扩展
3. 编写指令——解释推理而不是堆砌命令，利用渐进式披露控制 context 占用
4. 测试迭代——双向对比验证价值，根据迭代信号精准调整
5. 发布维护——选择合适的安装路径，关注系统新特性

整个过程中最重要的心智转变是：Skill 不是一次性写完的产物，而是一个持续迭代的知识载体。你的工作流在变化，Skill 也应该跟着进化。