Claude Code skill：如何创建，附示例与最佳实践

Claude Code skill 是什么

如果你总是在对话里反复粘贴同样的指令、检查清单或多步骤流程，或者 CLAUDE.md 里某一部分已经从一条事实膨胀成了一套流程，就该把它做成 skill。skill 遵循开放的 Agent Skills 标准（agentskills.io），其他 AI 工具也能读取；Claude Code 在此基础上增加了调用控制、以 subagent 运行，以及在提示词里嵌入实时 shell 输出等功能。

• 两种运行方式：当你的请求和它的 description 相符时由 Claude 加载，或者你输入 /skill-name。
• 不用就几乎不花钱：上下文里只放名称和描述，skill 运行时才加载正文。设置为只能手动运行的 skill 连描述都不会列出。
• 自定义斜杠命令现在就是 skill：.claude/commands/<name>.md 仍然可用，但 skill 文件夹还能放辅助文件。参见 Claude Code 斜杠命令。
• Claude Code 也自带捆绑 skill，比如 /simplify、/loop、/batch 和 /debug。

skill、CLAUDE.md、subagent、插件与 MCP 对比

如何创建 Claude Code skill

1. 选好存放位置

   ~/.claude/skills/<name>/ 供你自己在所有项目里使用；仓库里的 .claude/skills/<name>/ 提交后，所有在这个仓库工作的人都能用。文件夹名就是命令名，所以 summarize-changes 对应 /summarize-changes。

2. 编写 SKILL.md：先写描述，再写指令

   frontmatter 放在文件最顶部的两行 --- 之间。只有 description 是推荐填写的：把使用场景和大家实际会说的话放在最前面。下面用 Markdown 写指令。以 ` !command ` 开头的一行会先运行这条命令，再把输出贴进去，这样 skill 就能基于你的真实状态工作。

   ---
   description: 总结未提交的改动，并标出有风险的地方。当用户问改了什么、想要一条 commit message，或要求评审 diff 时使用。
   ---
   
   ## 当前改动
   
   !`git diff HEAD`
   
   ## 指令
   
   用两三个要点总结上面的改动，然后列出风险，比如缺少错误处理、
   硬编码的值，或需要更新的测试。

3. 两种方式都测一测

   在一个有未提交改动的 git 项目里启动 claude。先问“我改了什么？”，看看 Claude 会不会自己用上这个 skill，再输入 /summarize-changes 直接运行它。会话中新增的 skill 会自动加载；如果某个没出现，运行 /reload-skills。

4. 决定谁可以运行它

   部署、发消息这类有副作用的操作，加上 disable-model-invocation: true，这样只有你能启动它。只应由 Claude 加载的背景知识，加上 user-invocable: false。用 $ARGUMENTS 传入输入，用法见斜杠命令指南。

5. 共享它

   把 .claude/skills/ 提交到仓库，或者把 skill 打包成插件，供多个仓库或团队使用。

来源：Claude Code 文档，Extend Claude with skills

Claude Code skill 示例

1. 只对匹配文件加载的参考型 skill

   参考型 skill 存放 Claude 在工作时要遵守的约定。paths 把自动加载限制在匹配这些 glob 的文件上。

   ---
   description: 这个代码库的 API 设计约定。编写或评审 HTTP 接口时使用。
   paths: ["src/api/**"]
   ---
   
   编写 API 接口时：
   - 使用 RESTful 命名，资源名用复数
   - 错误以 { error: { code, message } } 的形式返回
   - 用 src/api/schemas/ 里的 schema 校验请求体

2. 带辅助文件的任务型 skill

   让 SKILL.md 保持简短，其余内容用指引带过去。只有 SKILL.md 让 Claude 去读时，它才会读 checklist.md；bump.sh 则直接运行而不读取，所以这些细节在用到之前不占任何开销。

   release/
   ├── SKILL.md          # 步骤，以及什么时候读其他文件
   ├── checklist.md      # 只有 SKILL.md 让 Claude 去读时才加载
   └── scripts/
       └── bump.sh       # 直接运行，不读进上下文

3. 在独立 subagent 中运行的 skill

   context: fork 会启动一个 subagent（这里是只读的 Explore 类型），以 skill 作为它的提示词。它看不到你的对话，所以指令必须能独立成立；除非设置 background: false，它会在后台运行。

   ---
   description: 审计依赖中的已知漏洞和落后的大版本
   context: fork
   agent: Explore
   disable-model-invocation: true
   ---
   
   运行包管理器的 audit，列出每个高危或严重问题及其修复版本，
   并报告哪些依赖落后了大版本。不要修改任何文件。

从插件和插件市场安装 skill

别人写的 skill 通常装在插件里。第一次启动交互式会话时，Claude Code 会注册 Anthropic 的官方插件市场（claude-plugins-official）；用 /plugin 浏览，或者直接安装，例如 /plugin install skill-creator@claude-plugins-official。团队或社区的插件市场，先用 /plugin marketplace add owner/repo 添加。

• 插件里的 skill 命名为 /plugin-name:skill-name。
• 官方插件市场会显示每个插件每一轮以及被调用时的上下文开销。
• skill-creator 插件能帮你编写 skill，并运行评测，对比用和不用它时的结果。
• 信任一个仓库或插件的 skill 之前先读一读：allowed-tools 可以在 skill 运行的那一轮预先批准工具。

最佳实践，以及 Claude 忽略 skill 时怎么办

• 描述要为匹配而写：先写清楚要做的事和用户会说的话。在列表里，描述加上 when_to_use 超过 1,536 个字符的部分会被截掉。
• 最重要的指令放在靠前的位置：对话被压缩后，Claude Code 可能只保留已调用 skill 的开头部分。再调用一次就能恢复。
• 针对整个任务来写指导（“每次编辑后都运行测试”），因为之后的轮次不会重新读取 skill 文件。绝不能跳过的规则应该放进 hook。
• 想减少 token 用量，就把流程从 CLAUDE.md 移到 skill 里，给手动运行的 skill 设置 disable-model-invocation: true，再用 /skill-doctor 找出占用上下文却很少使用的 skill。
• 没有触发？检查描述里有没有对的关键词，问一句“有哪些可用的 skill？”，再运行 claude plugin validate .claude/skills 找出无法解析的 frontmatter。
• 触发太频繁？把描述写得更窄，或者用 disable-model-invocation: true 把 skill 改成手动运行。

skill 教会 Claude Code 怎么做，Crewmark 让它每小时都有事可做。

一套 skill 让每个会话都更能干，但它仍然要等你开口。Crewmark 把 Claude Code、Codex、DeepSeek Harness 或 OpenCode 会话变成有岗位、目标和工作时间的 AI 员工，并按心跳唤醒它，从看板上接手下一个 issue，同时加载你项目里的 skill。

1. 把 skill 留在仓库里

   员工的会话会像你的会话一样读取 .claude/skills/ 和 CLAUDE.md，所以发布 skill 或评审检查清单都会一起带过去。

2. 让心跳启动工作

   在工作时间内，员工每 15、30 或 60 分钟在同一个对话里醒来一次，接手下一个 issue；参见如何让 Claude Code 主动工作。

3. 分配 issue，回复它的消息

   把工作放到看板上；员工边做边评论，需要你拍板时给你发消息。阅读什么是 AI 员工。

Claude Code skill 常见问题