Claude Skills 专业入门：把“会用 AI”变成“可复制的工程能力”

Claude Skills 解决的不是“怎么写出更长的提示词”，而是一个更工程的问题：如何把团队的做事方式沉淀成可版本化、可复用、可验收的能力模块。

当你把流程、模板、检查清单、脚本化工具链都塞进一次次对话里，短期看“能跑”，长期一定会出现三件事：同类任务输出漂移、验收靠人肉、上下文越用越乱。

Skills 的设计目标很克制：把“怎么做”做成资产，用时按需加载。

0) 一句话总纲：把“方法”做成模块

在工程里，“知道什么”和“怎么做”是两类资产：

• 知道什么：业务背景、接口文档、历史决策，随项目变化。
• 怎么做：排障步骤、审查清单、报告模板、发布流程，应长期稳定且可复用。

Claude Skills 更偏向后者：把“怎么做”固化下来，并把它变成可组合的模块。

1) Skills 是什么：程序化知识（procedural knowledge）的封装

一个 Skill 通常由三类资产组成：

1. SKILL.md（必需）：入口指令 + 元数据（name/description 等）。
2. 参考资料（可选）：规范、模板、清单、示例，按需加载（不默认进入上下文）。
3. 脚本（可选但强烈推荐）：把确定性工作交给程序，让模型专注于编排与判断。

你可以把 Skill 理解成一个“训练手册 + 工具箱”：它不是让模型更会聊天，而是让它更稳定地执行一套流程。

2) 为什么团队会需要 Skills：三个老问题 Prompt 很难根治

2.1 一致性：同一件事，每个人都在重新发明提示词

写方案、做 review、排障、出周报……这类任务是高频的。靠“现场写提示词”复用，会天然漂移。

2.2 验收：没有可执行验收，输出只能“看起来对”

Skill 的正确姿势是把验收写进流程里：测试命令、格式校验、输出结构、截图对比、数据检查。

2.3 上下文：把 SOP 都堆进对话，越用越慢、越用越乱

把规范、模板、清单都堆在 prompt 里，会造成上下文挤压与注意力竞争。Skills 的思路相反：让信息按需进入上下文。

3) Skills 怎么工作：渐进式披露（Progressive Disclosure）

Skills 的关键差异在于加载方式：不是一次性把所有内容塞进上下文，而是分层加载。

• 发现（Discovery）：启动时只读取每个 Skill 的 name/description，形成“能力目录”。
• 激活（Activation）：意图匹配时才加载该 Skill 的 SKILL.md 正文。
• 执行（Execution）：需要更多细节时，才按需读 references/ 或运行 scripts/。

图 1：渐进式披露（按需加载）

    flowchart TB
  U[用户请求] --> D[发现：只加载<br/>name/description]
  D -->|命中| A[激活：加载 SKILL.md<br/>流程/边界/验收]
  A --> E{执行中需要细节？}
  E -->|需要| R[按需读取 references/<br/>模板/规范/清单]
  E -->|需要| S[按需运行 scripts/<br/>确定性处理]
  R --> O[输出结果]
  S --> O[输出结果]
  

工程含义很直接：能力规模可以很大，但常驻上下文成本仍可控。

4) Skill 长什么样：目录结构与 SKILL.md 关键字段

从一个能跑通的结构开始就够了：

my-skill/
├── SKILL.md              # 必需：入口指令 + 元数据
├── references/           # 可选：规范/模板/清单/示例（按需加载）
│  ├── checklist.md
│  └── templates.md
└── scripts/              # 可选：脚本（按需执行，推荐）
   └── run.sh

在 Claude Code 里，Skill 通常放在两个位置之一：

• 个人级：~/.claude/skills/（跨项目复用）
• 项目级：.claude/skills/（仓库共享，适合团队版本化）

图 2：Skill 的“分层”结构

    flowchart LR
  A[SKILL.md<br/>入口：流程/边界/验收] --> B[references/<br/>按需加载：规范/模板/清单]
  A --> C[scripts/<br/>按需执行：确定性处理]
  

4.1 YAML 头部：它决定“会不会触发”

SKILL.md 头部的 description 更像路由规则：写清“何时使用 + 会产出什么”，并尽量包含用户真实会说的关键词。

最小可用示例：

---
name: code-review
description: 代码评审清单与输出规范。用于 PR 评审、风险识别、可维护性建议与测试补齐。触发词：代码审查、review、PR、可维护性、风险、测试覆盖。
---

更工程化的写法，通常会额外考虑“执行面收敛”和“上下文隔离”：

示例（重点看思路，不必照抄）：

---
name: repo-audit
description: 仓库安全审计与风险清单输出。用于依赖漏洞扫描结果解读、敏感配置检查、权限边界核对。触发词：安全审计、依赖漏洞、secret、权限、风险清单。
allowed-tools: [Read, Grep, Glob, Bash]
context: fork
user-invocable: true
---

4.2 入口文件别写成长文档站

入口只放三件事：

1. 流程：按顺序做什么
2. 边界：什么时候不做/缺什么先问
3. 验收：怎样算完成（尽量可验证）

细节、案例、模板拆进 references/，需要时再按需加载。

5) Skills 里最被低估的部分：脚本化让系统更确定

“脚本化”的价值不是更强，而是更工程：

• 失败模式可分类（权限不足/环境缺失/格式不合法）
• 可重试、可回归
• 让模型从“操作者”收敛为“编排者”

典型适合脚本化的任务：

• 校验输出格式（lint/JSON schema/Markdown 结构）
• 批量处理文件、提取元信息、生成表格
• 跑测试、跑构建、抓取关键日志并归纳

6) 把概念放回能力栈：Prompt/Projects/Subagents/Skills/MCP 怎么分工

图 3：能力栈分工（组合使用更稳定）

    graph TB
  U[用户需求] --> P[Prompt：本次任务指挥<br/>输入/约束/验收]
  U --> Proj[Projects：长期背景<br/>资料/链接/上下文]
  U --> Skills[Skills：方法与流程<br/>SOP/清单/脚本入口]
  Skills --> Sub[Subagents：分工与隔离<br/>并行探索/审计/排障]
  Skills --> Tools[工具执行：文件/命令/脚本]
  Tools <--> MCP[MCP：连接外部系统<br/>DB/SaaS/Drive/GitHub]
  

一句话总结：Skills 负责“怎么做才稳定”，MCP 负责“怎么连到外部世界”。

7) 团队落地：把 Skills 纳入“配置即代码”

团队要可复制，关键是把经验沉淀成可评审资产。一个最小可用的“配置即代码”拆分是：

1. CLAUDE.md：项目记忆与约定（命令、目录、禁区）
2. rules/：必须遵守的底线（安全、测试、代码风格、Git 流程）
3. commands/：高频流程一键化（例如 /plan、/code-review）
4. agents/：分工子代理（规划/审查/排障/E2E）
5. hooks/：关键事件点护栏（提醒/阻断/一致性检查）
6. skills/：可复用方法论与 SOP（按需加载）
7. MCP 配置：外部系统接入（该用再用）

图 4：团队落地的 7 个构件

    flowchart TB
  A[配置即代码] --> B[CLAUDE.md<br/>项目记忆与约定]
  A --> C[rules/<br/>底线与规范]
  A --> D[commands/<br/>高频流程一键化]
  A --> E[agents/<br/>分工子代理]
  A --> F[hooks/<br/>自动化护栏]
  A --> G[skills/<br/>可复用方法与SOP]
  A --> H[MCP 配置<br/>外部系统接入]
  

站内延伸：

• 团队落地：把 Claude Code 配置当代码管理

8) 一个可直接复用的 SKILL.md 模板

第一次写 Skill，别追求大而全。先写一个“单一、可重复、能验收”的任务：

---
name: incident-triage
description: 线上故障排障与分级处置流程。用于收集证据、定位根因、制定修复/回滚方案并输出复盘。触发词：线上故障、告警、排障、root cause、回滚、复盘。
---

# 目标
- 用最少步骤拿到“可行动的结论”：根因假设 + 验证证据 + 处置建议

# 输入（缺一不可就先问）
- 影响范围（用户/区域/时间）
- 复现或日志（stack trace / metrics / trace / screenshots）
- 最近变更（发布记录/配置变更/依赖升级）

# 工作流程（按序）
1) 先止血：判断是否需要降级/回滚（给出判断依据）
2) 再取证：列出必须收集的证据清单
3) 再定位：给出 2-3 个根因假设，并说明如何验证
4) 再修复：给出最小修复方案 + 验证方式
5) 最后复盘：输出复盘模板（时间线/根因/改进项）

# 验收（可验证）
- 输出包含：影响评估、证据清单、根因假设、验证步骤、处置方案、复盘草稿

9) 5 个常见坑（提前避坑）

1. 入口文件太长：关键约束被淹没，执行反而不稳定。
2. description 太泛：触发率低到你怀疑人生。
3. 没有验收标准：输出永远停留在“看起来对”。
4. 全靠模型推理：能脚本化的部分没脚本化，结果不确定。
5. Skill 变成“技巧合集”：不聚焦单一工作流，难以组合复用。

10) 安全与治理：Skill 一旦可执行，就必须有边界

三条底线足够覆盖大多数团队：

1. 最小权限：能只读就别可写；能限制目录就别全盘开放。
2. 关键动作可审计：把底线写进 rules/，把流程写进 commands/，把高风险点交给 hooks 做提醒或阻断。
3. 把外部内容当不可信输入：网页/工单/邮件/issue 里都可能夹 prompt injection；流程上先“提取事实”，再“执行动作”。

11) 一页行动清单：30 分钟做出第一个可复用 Skill

1. 选一个高频任务（越土越好）：review/排障/周报/方案模板。
2. 写短入口（流程 + 验收），先跑通。
3. 把确定性部分脚本化（测试/抽日志/校验格式/生成表格）。
4. 用两个真实样例回归：能触发、能按步骤做、输出可验收。

只要这四步成立，你的 Skill 就已经比大多数“提示词模板”更值钱。