AI AI 工具指南
AI 工具教程

Claude Code Skills 全指南：内置、自定义、插件、团队共享

Claude Code skills 的完整入门：什么是 skill、如何调用、如何写一个 SKILL.md、何时用 hook 或 subagent 替代、以及如何在团队里共享。

发布于: 作者: AI Productivity Guide Team 🌐 查看英文版本

这篇讲什么

Claude Code skills 的完整入门：什么是 skill、如何调用、如何写一个 SKILL.md、何时用 hook 或 subagent 替代、以及如何在团队里共享。

本文涉及的工具 / 概念：

  • Claude Code: Anthropic 推出的命令行 AI 编程 agent，能在你的终端里读、写、运行项目代码。
  • Claude: Anthropic 的对话式 AI 助手，类似 ChatGPT，支持文件、长文档和工具集成。

这篇适合谁看

已经能正常用 claude 命令，想把”每次都要手敲的同一段流程”变成”输入 /<name> 就能跑”的开发者。也适合在团队里负责标准化代码评审、安全审查、发布检查的人。

什么时候适合用

  • 同一个任务你已经重复执行三次以上：安全审查、发布前 QA、batch 改 metadata、生成测试。
  • 流程不只是一段 prompt，还要带参考文档、模板脚本、或者特定步骤的 checklist。
  • 团队希望所有人按同一套标准跑，而不是各写各的 prompt。
  • 想让 Claude 在某些上下文里自动触发某个工作流，而不是每次靠人记得调用。

skill、slash command、hook、subagent 的区别

这四个概念经常被搞混，先分清楚再往下看：

  • skill：一段带说明的工作流，存在 SKILL.md 里。Claude 看到任务匹配 skill 的描述时，会主动加载它的指令；你也能用 /<name> 显式调用。skill 可以附带脚本、模板、参考资料。
  • slash command：纯文本扩展，定义在 .claude/commands/ 下，执行时把模板插进 prompt。适合”复用一句话指令”。
  • hook：在某个事件（PreToolUse、PostToolUse、Stop、UserPromptSubmit 等）触发的 shell 命令。适合”每次写文件后跑 lint”这种自动行为。
  • subagent：独立上下文窗口跑一段任务，结果返回给主会话。适合并行调研、隔离长上下文。

判断方法：

你要什么用什么
”我想再用一遍那段长 prompt”slash command
”某种任务出现时自动按一套流程做”skill
”写完文件自动跑 prettier”hook
”并行去查 5 个文件再汇总”subagent

skill 的独特之处：可以被 Claude 自动识别并调用，不一定要你显式 /。

skill 长什么样

skill 是一个目录，里面至少有一个 SKILL.md，可以附带任意脚本、文档、模板：

.claude/skills/
  ship/
    SKILL.md
    templates/
      changelog.md
    scripts/
      bump-version.sh

SKILL.md 用 frontmatter 描述 skill 自己：

---
name: ship
description: |
  Ship workflow: detect base branch, run tests, review diff,
  bump VERSION, update CHANGELOG, commit, push, create PR.
  Use when the user says "ship", "release", or asks to cut a version.
---

# Ship workflow

1. Run `git status` and `git diff` to confirm clean working tree.
2. Run the test suite. If it fails, stop and show output.
3. ... (具体步骤)

要点：

  • description 是 Claude 用来匹配任务的索引。写得越具体（带触发词、典型场景），自动调用越准。
  • 正文是 Claude 看到的指令。可以引用同目录下的脚本和模板，用相对路径。
  • 不要在 description 里堆名词。“用于代码评审” → 太空；“PR landing 前对 diff 做 SQL safety / LLM trust boundary / conditional side-effect 检查” → 可被精准匹配。

skill 放在哪

skill 可以来自四个位置，按优先级理解：

  1. 项目级：.claude/skills/<name>/SKILL.md — 跟着仓库走，所有协作者都能用。
  2. 用户级：~/.claude/skills/<name>/SKILL.md — 跨所有项目可用，只属于你。
  3. 插件：用 gh 风格的插件机制安装的 skill 包，前缀类似 gstack:qa。
  4. 内置：Claude Code 自带的 skill，比如 init、review、security-review，不需要你写文件。

常见的内置或官方插件级 skill（会随版本变化，以你 / 菜单为准）：

Skill干什么
init初始化或更新项目 CLAUDE.md
reviewPR diff 审查，找代码味、潜在 bug
security-review当前分支的安全审查
verify跑应用、用浏览器或 CLI 验证改动是否真的工作
simplify评审改动并简化重复或冗余代码
run起项目跑起来看效果
update-config改 .claude/settings.json（权限、hook、env）
loop把一条命令按间隔循环跑
schedule创建/管理定时远程 agent
keybindings-help帮你改 ~/.claude/keybindings.json
fewer-permission-prompts扫历史，把常见只读命令加进 allowlist
claude-api写 Anthropic SDK 代码、做版本迁移

插件类（举例，需要先装相应插件）：

Skill干什么
gstack:browse无头浏览器，自动化点页面、截图、对比 diff
gstack:qa系统化 QA 整站并修 bug，原子化 commit
gstack:ship一键 ship 流程：合并基线、跑测试、改 CHANGELOG、push、开 PR
gstack:review上线前 PR 评审
gstack:retro周回顾，分析 commit 历史和质量趋势

不确定哪些可用？敲一个 / 看菜单，或者跑 /help。

怎么调用 skill

三种触发方式：

  1. 显式 /<name>：在输入框里敲 /，菜单里找你要的 skill，回车。最直接。
  2. 自动触发：当你描述的任务匹配某个 skill 的 description，Claude 会主动加载它。比如你说”帮我审一下这个 PR 的安全风险”，可能会自动套上 security-review。
  3. 显式让 Claude 用某 skill：在 prompt 里直接说 “use the security-review skill on this branch”，比含糊地说”看看安全问题”更稳。

带参数的 skill 调用一般是 /<name> <args>，例如：

/loop 5m /verify
/schedule daily 09:00 "summarize yesterday's commits"

具体参数怎么写以 skill 自己的 SKILL.md 描述为准。

写一个属于你自己的 skill：完整例子

假设你想要一个 pr-summary skill：给当前分支自动生成 PR 描述。

第 1 步：在仓库根目录建文件：

.claude/skills/pr-summary/SKILL.md

第 2 步：写 frontmatter 和正文：

---
name: pr-summary
description: |
  Generate a PR description for the current branch.
  Pulls commits since the merge-base with main, summarizes
  what changed, and produces "Summary / Test plan / Risks"
  sections. Use when the user asks for a "PR description",
  "PR body", or is about to open a PR.
---

# Generate a PR description

1. Detect base branch — try `main`, fall back to `master`.
2. List commits with `git log <base>..HEAD --oneline`.
3. Get the diff stat with `git diff <base>..HEAD --stat`.
4. Output three sections:
   - **Summary** — 1-3 bullets of what this PR does.
   - **Test plan** — checklist of what was verified.
   - **Risks** — known unknowns and what to watch in prod.
5. Do not include co-author trailers or auto-generated notes
   unless the user asks for them.

第 3 步：在会话里跑 /pr-summary 验证。如果你描述的工作场景在用户 prompt 里出现（比如”帮我写个 PR description”），Claude 也会自动套用。

第 4 步：commit 这个目录到仓库——所有协作者拉下来都直接能用。

给 skill 加脚本和模板

skill 可以引用同目录下的文件：

.claude/skills/release-notes/
  SKILL.md
  template.md
  fetch-issues.sh

SKILL.md 里这样用：

1. Run `bash .claude/skills/release-notes/fetch-issues.sh <version>` to
   collect closed issues since the last tag.
2. Use `.claude/skills/release-notes/template.md` as the output skeleton.
3. Fill the template, keep tone matter-of-fact, no marketing language.

注意：用相对路径，并且让 Claude 实际去读模板而不是猜内容，结果稳定得多。

skill 和自动触发：怎么让它真的自动起来

description 字段决定自动触发是否准。三条规则：

  1. 写触发词：用户实际会说什么？“ship”、“cut a release”、“review the diff”、“qa”——把这些词写进 description。
  2. 写场景：什么时候不该触发也要写。比如 description 里加 “Skip if user only wants to chat about release strategy without actually shipping”。
  3. 写产物：明确产出什么。比如 “Produces an updated VERSION file, CHANGELOG entry, and a pushed PR” 比 “handles release” 准得多。

如果 skill 一直触发不到，先在 SKILL.md 描述里加你自己实际用过的几句话；如果触发太频繁，反过来收紧场景描述。

团队共享与版本控制

  • 项目 skill：把 .claude/skills/ 提交到 git。所有人拉下来即可用，符合”基础设施即代码”原则。
  • 用户级 skill：自己机器跨项目复用。可以放进一个私有 dotfiles 仓库，并 symlink 到 ~/.claude/skills/。
  • 插件：在 README 里写明依赖的插件名和版本，让队友按官方说明安装。

CI 上不需要执行 skill，但建议加 lint：检查每个 SKILL.md 都有 name 和 description，避免有人 commit 了空壳目录。

什么时候不该用 skill

  • 一次性问题：直接 prompt 比写 skill 快。
  • 单句指令的复用：用 slash command（.claude/commands/<name>.md）。
  • 想”每次写文件后自动跑 X”：用 hook，不是 skill。
  • 跨上下文并行调研：用 subagent。
  • skill 描述写得很模糊以至于没人记得它存在：删掉，重写或合并。

实操：第一周做这三件事

  1. 跑一遍现有内置 skill：/init、/review、/security-review，感受触发体验和输出风格。
  2. 把你最近三次手敲的同一段流程，写成一个项目级 skill，提交到仓库。
  3. 让一个同事不告诉你而触发这个 skill，看是否能自动匹配——不行就改 description。

完成后检查

  • skill 是否真的被自动触发？看 / 菜单 + transcript 里有没有出现 “Loaded skill: …”。
  • 跑 skill 的输出是否一致？两次跑应该结构相同，差异只在内容。
  • 团队里别人能用吗？换个未参与编写的同事跑一遍。
  • skill 描述里有没有触发词、典型场景、明确产物？三者缺一不可。

容易踩的坑

  • description 写成”用于代码评审”——太空，自动匹配几乎不会命中。
  • 把上百行步骤全塞 SKILL.md——Claude 抓不到重点。拆步骤、列编号、必要时引用外部脚本。
  • 在 skill 里硬编码绝对路径——换个仓库就崩。用相对路径，或让 skill 自己探测。
  • 把敏感凭据写进 skill 模板——skill 跟着 git 走，等于明文提交。用环境变量或 secret manager。
  • 跟 hook 搞混：skill 是”AI 的工作流指令”，hook 是”harness 的自动执行命令”。两者要解决的问题不同。

FAQ

Q：skill 和 slash command 有什么区别？ A：slash command 是纯文本扩展，定义在 .claude/commands/，执行时把模板插进 prompt——适合复用一句话指令。skill 是带 SKILL.md 描述的工作流，Claude 看到任务匹配时会自动加载，也支持显式 /<name> 调用。要自动触发用 skill，要手动复用用 slash command。

Q：什么时候用 skill，什么时候用 hook？ A：skill 是“AI 的工作流指令”——某种任务出现时按一套流程做；hook 是“harness 的自动执行命令”——写完文件自动跑 prettier 这种确定性自动化。要 AI 判断走不走流程用 skill，要每次都跑的副作用用 hook。

Q：skill 怎么团队共享？ A：把 skill 目录提交到 git（.claude/skills/<name>/SKILL.md + 附带脚本 / 模板），团队成员拉下来就能用。注意不要把 API key 等敏感凭据写进 skill 模板——skill 跟着 git 走等于明文提交，用环境变量或 secret manager。

Q：为什么我的 skill 没被自动触发？ A：99% 是 SKILL.md 的 description 写得太空。“用于代码评审”这种自动匹配几乎不会命中。description 要具体到“当 Claude 被要求做发布前 QA / 安全审计 / API 迁移时使用”——给出明确触发条件。

相关阅读

标签: #Claude #Claude Code #教程

相关文章