如何从零开始构建一个高质量的 Skill，让 AI 真正理解你的工作流
你有没有遇到过这种情况——辛辛苦苦写了一份 Skill 喂给 AI，结果它要么根本不触发，要么触发了却干得一塌糊涂？
问题往往不在 AI 身上。问题在于你写的那份"指令"，本质上是写给人看的文档，而不是写给 AI 看的操作手册。
一、Skill 到底是什么？
用最简单的话来说：Skill 就是一个文件夹，里面装着 AI 完成某项专项任务所需的全部家当——操作说明、参考资料、现成脚本和可直接使用的模板。
1.1 极简版：一个文件就能开始
Skill 的最低配置只需要一个 SKILL.md 文件：
weather-bot/
└── SKILL.md
这个文件分成两部分：
- 头部（Frontmatter）：YAML 格式的元信息，声明名称和用途描述。AI 启动时会扫描所有已安装 Skill 的 frontmatter，根据
description决定是否激活该技能。这是触发的唯一依据——description 写得含糊，技能就可能被误触发或错过。 - 正文（Body）：Markdown 格式的具体执行步骤。只有 Skill 被选中之后，body 才会被加载进上下文。没被触发的话，AI 连看都看不到。
---
name: weather-bot
description: |-
回答天气相关问题。当用户询问某地天气、
气温预报或穿衣建议时激活此技能。
---
执行步骤：
1. 解析用户提到的城市名称
2. 调用天气 API 获取实时数据
3. 用自然语言回复用户
1.2 完整版：按需扩展的目录结构
任务稍微复杂一点，一个文件就不够了。完整的目录结构是这样的：
excel-processor/
├── SKILL.md # [必需] 元信息 + 执行指令
├── agents/
│ └── openai.yaml # [可选] 界面展示用的元数据
├── scripts/ # [可选] 预写好的可执行代码
├── references/ # [可选] AI 按需查阅的参考资料
└── assets/ # [可选] 直接用于最终产出的素材
四类资源各有定位。核心结论先记住：SKILL.md 是唯一的刚需文件，其余按实际需求添加。
二、Skill 的核心设计原则
Anthropic 的官方指南揭示了一个关键矛盾：怎么在有限的上下文窗口里，给 AI 传递最有效的指令？
围绕这个矛盾，有三个核心设计原则。
2.1 渐进式披露（Progressive Disclosure）
Skill 使用三层加载系统：
- 第一层（YAML frontmatter）：始终加载。提供足够的信息让 Claude 判断是否该用这个 Skill，但不会把全部内容塞进上下文。
- 第二层（SKILL.md body）：当 Claude 认为 Skill 相关时才加载。包含完整的指令和指引。
- 第三层（链接文件）：Skill 目录内的附加文件，Claude 按需发现。
这种设计最小化了 token 消耗，同时保留了专业能力。
2.2 别写给人看，写给 AI 看
这是绝大多数人犯的错误。来看一个典型的"人类写法"的代码审查 Skill：
---
name: review-code
description: 用于代码审查
---
# 背景
本技能凝聚了团队三年的 code review 经验。
# 审查理念
- 建设性、专业的沟通风格
- 在严格与宽容间找到平衡
# 如何使用
收到用户提交的代码后，全面审查并输出建议。
如果递给一个刚入职的同事，这份文档没什么毛病。但 Skill 的读者是 AI，换个视角再看一遍，问题就来了：
- "凝聚三年经验"——AI 不需要这些背景信息，它只关心此刻要干什么
- "建设性、专业的"——人类读了能领会一个大致调性，AI 却会自由组合出无数种输出，每次结果都不一样
- "在严格与宽容间找到平衡"——一个老手心里有数，AI 没有这个直觉
- "全面审查"——太笼统了，AI 需要明确的检查清单：先看什么、后看什么、什么严重等级必须上报
- description 只写了五个字——AI 就靠这五个字来判断要不要触发，"帮我看看这段逻辑"触发还是不触发？
这些写法的共同点：全是面向人类读者的。 写得多不等于写得对，写错了读者比什么都不写更糟。
2.3 简洁是公共财产
上下文窗口就像手机内存，你的 Skill 和系统提示、对话历史、其他技能的元数据共享这块空间。编写前问自己两件事：
- 这个知识 AI 是不是天生就会？ 比如怎么发 HTTP 请求、怎么解析 JSON，不用教。
- 这段话占掉的空间值不值？ 一大段流程解释，也许用十几行代码片段就能更精准地传达同样的意思。
此外，去除冗余文件：README.md、CHANGELOG.md、INSTALLATION_GUIDE.md 都不该出现在 Skill 目录里——Skill 的消费者是 AI，不是接手项目的新人。
三、Skill 的九大使用场景类型
Anthropic 内部已经用了几百个 Skills 来加速开发。以下九种类型来自一线工程师的实战总结。
类型 1：库 & API 参考
教 AI 正确使用内部/外部库、CLI、SDK，附带代码片段和"坑点列表"。这是 Skills 里含金量最高的部分——模型已经懂很多通用知识，重点写只有你们才知道的坑（Gotchas）。
示例：billing-lib — your internal billing library: edge cases, footguns, etc.
类型 2：产品验证
教 AI 如何测试代码是否正确，常配合 Playwright、tmux 等工具，甚至可以让 Claude 录视频或做断言验证。
示例：signup-flow-driver — runs through signup → email verify → onboarding in a headless browser
类型 3：数据获取 & 分析
连接监控系统、数据库，快速跑查询、对比 cohort。一个公司总是有很多系统——监控、日志、DB、ES、Wiki、Git。站在 Agent 的界面上把这些平台打通，会有意想不到的效果。比如分析一个值班问题，模型会先去监控平台查数据，再结合代码找出关键日志，最后得出结论总结到 Wiki 上。
类型 4：业务流程 & 团队自动化
一键完成重复工作：发周报、建 ticket、standup 总结。难点通常不在执行，而在收集素材——一周做的事情除了需求池，还有微信群里的需求和口头传达的。
类型 5：代码脚手架 & 模板
快速生成符合公司规范的新服务、迁移文件等。
类型 6：代码质量 & Review
自动审代码、强制风格、找 bug。使用 Skill 来补充上下文，能分析到很多人工根本看不出来的 bug。
类型 7：CI/CD & 部署监控
PR 审查、自动部署、回滚、cherry-pick 等。
类型 8：Runbooks
根据告警/错误，自动多工具排查并输出结构化报告。这类 Skill 对于值班排查非常有用。
类型 9：基础设施运维
清理孤儿资源、依赖管理、成本分析等，通常需要带安全护栏。
示例：orphans — finds orphaned pods/volumes → posts to Slack → soak period → user confirms → cascading cleanup
四、动手构建你的第一个 Skill
4.1 六步走流程
Anthropic 的 skill-creator 提供了一个可操作的流程：
- 理解场景：明确你的 Skill 要解决什么问题
- 规划资源：需要哪些脚本、模板、参考资料
- 脚本初始化：用
skill-creator工具初始化目录 - 填充内容：按照原则编写 SKILL.md
- 自动校验：运行验证脚本检查格式
- 实战迭代：在实际使用中不断改进
4.2 好 Use Case 的定义模板
动手之前，先回答四个问题：
Use Case: Project Sprint Planning
Trigger: 用户说"帮我规划这个 sprint"或"创建 sprint 任务"
Steps:
1. 从 Linear 获取当前项目状态（通过 MCP）
2. 分析团队速率和容量
3. 建议任务优先级
4. 在 Linear 中创建带标签和估算的任务
Result: 完整规划好的 sprint，任务已创建
4.3 实战技巧速查表
| 技巧 | 要点 |
|---|---|
| 别说废话 | 重点写你们才知道的坑（Gotchas），通用知识别写 |
| 渐进式披露 | 把详细 API、模板、脚本拆到子文件夹，需要时再读 |
| 别绑死 | 指令要给信息，但留灵活性 |
| 配置 & 记忆 | 用 config.json 存设置，用日志或 SQLite 存历史 |
| 存脚本 | 把常用函数库放进 Skill，Claude 直接调用 |
| 按需钩子 | 只在特定场景下开启保护（如禁止 rm -rf） |
| 分发方式 | 小团队放仓库（.claude/skills），大规模用 Plugin 市场 |
| 测量效果 | 统计使用频率，删掉没用的 |
五、Skill 与 MCP 的关系
如果说 MCP 是"专业厨房"——提供了工具、食材和设备，那么 Skill 就是"菜谱"——一步一步教你怎么做出有价值的东西。
| MCP（连接） | Skill（知识） | |
|---|---|---|
| 做什么 | 连接 Claude 到你的服务（Notion、Linear 等） | 教 Claude 如何有效使用你的服务 |
| 能力 | 提供实时数据访问和工具调用 | 捕获工作流和最佳实践 |
| 意义 | Claude 能做什么 | Claude 应该怎么做 |
没有 Skill 的 MCP：用户连接了但不知道下一步怎么做，每次对话从零开始，结果不一致。
有 Skill 的 MCP：预构建的工作流自动激活，工具使用一致，最佳实践嵌入每次交互。
六、Skill 的三大常见用途
Anthropic 在实践中总结出三大 Skill 用途分类：
分类一：文档与资产创建
用于创建一致的高质量输出，包括文档、演示文稿、应用、设计、代码等。典型代表：frontend-design Skill。
关键技巧：
- 嵌入样式指南和品牌标准
- 模板结构确保输出一致性
- 完成前的质量检查清单
- 无需外部工具——使用 Claude 内置能力
分类二：工作流自动化
用于受益于一致方法论的多步骤流程。典型代表：skill-creator 本身。
关键技巧：
- 带验证门控的分步工作流
- 常见结构的模板
- 内置审查和改进建议
- 迭代精炼循环
分类三：MCP 增强
将原始工具访问转化为可靠、优化的工作流。适合已有 MCP Server 的团队。
七、测试、迭代与分发
测试
- 用
skill-creator的验证脚本自动校验格式 - 在实际对话中测试触发条件是否准确
- 检查输出是否一致、可靠
迭代
Anthropic 的结论很明确：很多好 Skills 都是从几行 Gotchas 开始，慢慢被团队完善起来的。
- 用 PreToolUse 钩子统计每个 Skill 的使用频率
- 删掉没用的，改进常用的
- 不要追求一步到位
分发
- 个人使用：放在
~/.claude/skills/目录 - 团队使用：放进 Git 仓库的
.claude/skills/目录 - 社区发布：通过 Plugin 市场提交，支持 PR 提交和审核流程
八、总结
Skills 超级强大，但还在早期。最好的方式就是多实验、多迭代。
记住三个关键词：
- 简洁：上下文窗口是公共财产，节约使用
- 精准：写给 AI 看，不是写给人看
- 渐进：按需加载，别一次性塞满
期待约 15-30 分钟，你就能用 skill-creator 构建并测试出第一个能用的 Skill。动手试试吧。
本文参考资料：
- Anthropic - The Complete Guide to Building Skill for Claude
