夜雨聆风如何从零开始构建一个高质量的 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 连看都看不到。
```yaml
---
name: weather-bot
description: |-
回答天气相关问题。当用户询问某地天气、
气温预报或穿衣建议时激活此技能。
---
执行步骤：
1. 解析用户提到的城市名称
2. 调用天气 API 获取实时数据
3. 用自然语言回复用户
```
1.2 完整版：按需扩展的目录结构
任务稍微复杂一点，一个文件就不够了。完整的目录结构是这样的：
四类资源各有定位。核心结论先记住：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 实战技巧速查表
五、Skill 与 MCP 的关系
如果说 MCP 是"专业厨房"——提供了工具、食材和设备，那么 Skill 就是"菜谱"——一步一步教你怎么做出有价值的东西。
没有 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
