大多数 Claude Code Skill 教程把一件简单的事搞得很复杂。这是真正能用的版本。

Skill 是什么

Skill 是一个 Markdown 文件，教会 Claude Code 做一件它之前不会做的事，或者防止一种每次 session 都浪费你时间的失败模式。就这么多。

不是插件。不是框架。不是 API 集成。就是文件夹里的一个 Markdown 文件。

当 Claude 遇到匹配 Skill 描述的任务时，它自动加载 Skill 并遵循指令。你不需要手动调用，不需要写 prompt——Skill 在相关时自动触发。

Commands vs Agents vs Skills：

  • Commands 等你输入 /command-name，是手动触发
  • Agents 是在独立上下文窗口运行的专家角色
  • Skills 监视对话，在任务匹配时自动激活

Commands 是按钮。Agents 是专家。Skills 是本能。

SKILL.md 结构

每个 Skill 住在自己的目录里，SKILL.md 是入口：

.claude/skills/ └── my-skill/ ├── SKILL.md # skill 定义 ├── templates/ # 可选支持文件 └── examples/ # 可选参考输出

SKILL.md 有两部分：frontmatter + 指令。

frontmatter 示例：

--- name: security-review description: Comprehensive security audit. Use when reviewing code for vulnerabilities, before deployments, or when the user mentions security. allowed-tools: Read, Grep, Glob ---

description 是核心

description 决定 Skill 何时触发。如果描述模糊（"help with code"），Skill 会在所有场景触发。如果太窄（"only for Python 3.11 FastAPI handlers"），它永远不触发。

最佳实践：描述触发条件，而不是 Skill 本身。"use when reviewing code for vulnerabilities" 比 "security review tool" 好得多。

5分钟上手

最实用的新手 Skill：针对你团队实际问题的代码审查 Skill。

Step 1：mkdir -p .claude/skills/code-review

Step 2：写 SKILL.md

--- name: code-review description: Expert code reviewer. Use PROACTIVELY when reviewing PRs, checking for bugs, or before merging. allowed-tools: Read, Grep, Glob --- You are a senior code reviewer focused on correctness. When reviewing code: - Flag bugs, not style issues - Suggest specific fixes, not vague improvements - Check for edge cases and error handling gaps - Note performance concerns only at scale Output format: ## Critical (must fix) ## Warnings (should fix) ## Notes (consider)

Step 3：重启 Claude Code 或开启新 session

Step 4：让 Claude 审查代码。它会自动加载 Skill。

总耗时：不到5分钟。

五个最容易上手的 Skill

  1. Review Skill：检查代码的特定问题，上面刚演示过，最容易构建，回报最快
  2. Debugging Skill：强制在猜测之前执行方法论——"reproduce → isolate → hypothesize → verify"，防止"猜测并应用"的循环引入新 bug
  3. Documentation Skill：按团队格式生成文档，给一个模板让它填充，一致性无需手动维护
  4. Test-first Skill：强制先写测试再写实现，反转"写代码再补测试"这个默认行为
  5. Deploy Skill：运行部署清单——版本号变更、changelog、构建、测试、打 tag、推送，自动化你每次手动做的序列

从匹配你最大日常摩擦的那个开始，今晚就装一个。

五个常见错误

  • description 太宽：匹配一切，每次 session 都引入噪音
  • 指令太长：超过 200 行的 SKILL.md 消耗上下文但没带来相应价值，50 行说不清就拆成 SKILL.md + DETAILED_GUIDE.md
  • 没有 examples：Claude 看例子比看规则学得更好，想要特定输出格式就展示出来
  • 跳过 allowed-tools：没有工具限制，Skill 可以读、写、编辑、执行任何东西，永远指定最小所需工具
  • 在单文件 Skill 还没跑通时就建多文件 Skill：先掌握基础，复杂度只在简单版本不够用时才加

最重要的一点：Skill 不是代码，是用 Markdown 写的行为契约。触发条件、指令、输出格式定义得越好，Claude 交付得越可靠。