Claude Code Skills 完全指南：自定义与扩展 Claude 能力

本文是对官方文档 Extend Claude with skills 的中文要点摘要,完整内容以原文为准。

什么是 Skills

Skills 是 Claude Code 的可插拔技能单元。创建一个 SKILL.md 文件后,Claude 就会将其纳入工具箱:相关场景下自动调用,或由用户以 /技能名 手动触发。

适合创建 Skill 的时机:

• 你反复把同一套指令、检查列表、多步流程粘贴进对话
• CLAUDE.md 中某个章节已经演变成一个操作流程,而不再是背景事实

Skill 的正文按需加载——只有真正调用时才消耗 token,不像 CLAUDE.md 每次都随上下文载入,因此把大段参考资料放进 Skill 几乎没有额外成本。

Custom Commands 已并入 Skills

旧版自定义命令(custom commands)与新版 Skills 已完全合并:

两种写法完全等效,旧的 .claude/commands/ 文件无需改动,继续生效。新版 Skills 额外支持:

• 配套支撑文件(放在同一目录下)
• Frontmatter 控制调用方式
• Claude 自动识别并主动调用

内置(Bundled)Skills

Claude Code 官方预置了一批开箱即用的技能,覆盖常见开发工作流(除非通过 disableBundledSkills 设置禁用)。与多数直接执行固定逻辑的内置命令不同,bundled skills 是基于提示词的:它们给 Claude 详细指令,由 Claude 用自己的工具来编排完成。常见示例包括:

• /deep-research — 多源网络深度调研,自动验证并生成引用报告
• /code-review — 审查当前分支 diff,支持 --comment(发 PR 评论)和 --fix(直接应用修复)
• /debug — 调试问题排查
• /security-review — 对待合入变更执行安全审查
• /simplify — 对已改动代码做可读性与效率优化
• /verify — 运行应用并观察行为,验证改动是否符合预期
• /run — 启动并驱动项目应用
• /init — 为代码库生成 CLAUDE.md 初始文档
• /review — 审查指定的 GitHub Pull Request
• /update-config — 通过自然语言修改 settings.json(hooks、权限、环境变量)
• /loop — 以自定义间隔循环执行某个提示或命令
• /schedule — 创建和管理定时云端 Agent(支持 cron 表达式)
• /claude-api — Claude API / Anthropic SDK 的即查即用参考手册
• /fewer-permission-prompts — 分析历史记录,自动添加白名单减少权限弹窗
• /keybindings-help — 自定义键盘快捷键

创建自定义 Skill

目录结构

.claude/
  skills/
    deploy/
      SKILL.md          # 主技能文件(必须)
      checklist.md      # 可选支撑文件
      templates/        # 其他资源
  commands/             # 旧版路径,仍可用
    deploy.md

用户级技能放在 ~/.claude/skills/(对所有项目生效),项目级技能放在 .claude/skills/(仅当前项目)。

SKILL.md 格式

---
name: deploy
description: Deploy the application to production
disable-model-invocation: true
allowed-tools: Read Grep
---

# Deploy

1. Run `npm run build` and confirm it exits 0
2. Check `git status` — no uncommitted changes
3. Run `./scripts/deploy.sh $ARGUMENTS`
4. Verify the health endpoint responds 200

常用 Frontmatter 字段说明(所有字段均可选,推荐至少写 description):

控制调用方式

默认情况下,你和 Claude 都能调用任意技能。两个 frontmatter 字段可以限制调用方:

• disable-model-invocation: true:只能由用户输入 /技能名 手动触发,Claude 不会自动调用。适合带副作用或需要人工把控时机的工作流(如 /commit、/deploy)。
• user-invocable: false:从 / 菜单隐藏,只能由 Claude 在合适时机自动调用。适合不可直接当作命令执行的背景知识。

这个设计让你能明确区分「工具型」(需要人主动决策)和「辅助型」(让 Claude 在合适时机悄悄帮你)两类技能。

在子代理中运行 Skill(context: fork)

设置 context: fork 字段后,技能会在一个独立子代理中执行,而不是在主会话上下文中运行,技能正文会成为驱动该子代理的提示词。这带来两个好处:

• 技能消耗的 token 和工具调用不污染主上下文
• 通过 agent 字段可为不同类型的工作选择最合适的代理(如 Explore、Plan、general-purpose 或自定义子代理);省略时默认 general-purpose

动态上下文注入

技能支持在加载时动态注入实时信息。在 SKILL.md 正文中用 !`<命令>` 语法嵌入 shell 命令(如 !`git diff HEAD`),Claude Code 会在把内容发给 Claude 之前先执行该命令,并用其输出替换占位符,因此 Claude 收到的是已填好实时数据的提示词,无需手动维护上下文。多行命令可改用以 ```! 开头的代码块。

共享与安装 Skills

Claude Code 技能遵循 Agent Skills 开放标准,可跨多种 AI 工具使用。技能可按受众范围分发:

• 项目技能:把 .claude/skills/ 提交到版本库,团队成员拉取后即生效
• 插件(Plugins):在插件中建立 skills/ 目录随插件一起分发
• 组织级(Managed):通过托管设置(managed settings)在组织范围内统一部署

与 CLAUDE.md 的分工