你可能已经体验过这种爽感：
- 把一个「写周报」「跑一次验证」「生成一段脚手架」的提示词存下来
- 下次直接复制粘贴
- Claude 又快又准
但当你开始把它引入团队协作，就会遇到更现实的挑战：
- 复用：同一个任务在不同项目/不同人手里，细节永远不一样
- 可靠：写出来能跑不算完，必须能验证、能回放、能定位失败
- 治理：Skill 一多就会“堆成垃圾场”，还会挤占上下文预算
这篇文章把一篇 Twitter 长文的经验做了“可落地”的重写：不仅讲 Skill 是什么，还给你一套 选题 → 写法 → 组织方式 → 分发治理 → 迭代方法 的路线图。尽量保留原文细节，同时补上关键背景与具体模板。
0. 先把概念说清楚：Skill 不等于一段提示词
很多人第一次写 Skill，会写成：
“当你做 X 时，请按照步骤 1、2、3 ……”
它当然有用，但真正能“变成团队资产”的 Skill，通常不是一段话，而是一个文件夹式工具包：它能放指令、放模板、放脚本、放参考资料。
这个思路和官方文档里的 “filesystem-based + progressive disclosure（渐进式加载）” 是一致的：Skill 先把 metadata（name/description）预加载到系统提示词里，只有触发时才读取 SKILL.md，需要时才读取更多参考文件或运行脚本。
一个好用的 Skill 目录通常长这样：
my-skill/
├── SKILL.md # 入口说明（必需）
├── references/ # 参考资料：API、规范、口径
├── examples/ # 样例输出：好的长什么样
├── scripts/ # 可执行脚本：验证/拉数/生成
├── assets/ # 模板：报告模板、PR模板、工单模板
└── config.json # 需要用户先填的配置把 Skill 当作“给新人用的 onboarding 目录”会很有帮助：新人不会一次性读完所有文档，而是遇到问题再查；Skill 也一样，按需加载，省 tokens 也更稳。
1. Skill 选题：最值得做的 9 类（附“什么时候该做”的判断）
下面 9 类是最常见、也最容易出效果的方向。它们的共同点是：
- 任务频率高（总有人在做）
- 失败代价高（总有人踩坑）
- 或者验证成本高（总要手工点来点去）
1）库 / API 参考：让 Claude 写得“更贴你们的真相”
适合：内部 SDK、封装 CLI、带业务规则的 API。
不要把公共文档复述一遍，而要写 Claude 默认不知道/容易写错 的部分：
- 你们的封装层到底怎么用
- 参数组合的禁区（footguns）
- 真实边界条件（比如：什么情况下会返回 200 但其实失败）
2）产品验证：让 Claude 学会“证明自己写对了”
这是最值得投入的一类。因为大部分 AI 失败不是“写不出”，而是“没有验收”。
你可以把验证流程做成：
- Playwright 自动跑 UI 流程
- tmux/TTY 驱动的交互式 CLI 验证
- 关键节点强制断言（assert state）
- 录屏/截图输出，方便人类复查
经验：如果一个任务需要人工点 8 个页面才能确认，那它非常适合变成验证 Skill。
3）数据拉取与分析：把“怎么查数据”教给 Claude
适合：漏斗、留存、A/B、监控排障。
它的价值不是“让 Claude 会写 SQL”，而是把你们组织里最贵的隐性知识写出来：
- canonical user_id 到底在哪张表
- 事件 join 的正确方法
- 指标口径（过滤测试账号、去重规则）
4）业务流程与团队自动化：把重复劳动变成一个命令
适合：
- standup/周报（还能做到“只写 delta”）
- 建票并强制 schema（必填字段、枚举值）
- 汇总 GitHub + 工单 + Slack → 输出格式化结果
这类 Skill 建议把历史结果写日志，下次先读历史，再输出差异。
5）脚手架与模板：把“正确的骨架”一次性生成
适合：新服务、新 handler、新 migration、新内部 app。
它比传统脚手架更强的一点是：脚手架外还有自然语言约束（比如“必须带审计日志、必须接内部鉴权、必须补部署配置”）。
6）代码质量与 Review：把“团队标准”变成可执行流程
适合：
- code style（尤其是模型默认做不好的风格）
- testing practices（测什么、怎么测）
- adversarial review（拉一个“fresh eyes”子代理挑刺，再迭代修复）
7）CI/CD 与部署：把发布做成“流程产品”
适合：
- babysit PR（盯 CI、重试 flaky、修冲突、开 auto-merge）
- deploy（build → smoke test → 灰度 → 误差对比 → 自动回滚）
- cherry-pick prod（隔离 worktree、解决冲突、自动 PR 模板）
8）Runbook：把排障写成“可跑的剧本”
适合：报警、Slack 线程、错误签名。
好的 runbook Skill 不是“写一段经验”，而是：
- 症状 → 工具 → 查询模式（query patterns）
- 最终产出固定结构（结论/证据/下一步）
9）基础设施运维：高风险动作要护栏
适合：清理 orphan 资源、成本排查、依赖治理。
关键是护栏：
- 分阶段（发现 → 通知 → soak → 用户确认 → 执行）
- 在工具层面拦截危险命令（例如 rm -rf / DROP TABLE / force push）
2. Skill 写法：6 条“硬核原则”，写完就能立刻变好用
这些原则背后有一个总目标：减少“模型自由发挥”的不可控区，把不可控点变成可控资产。
原则 1：别写常识，写“差异化信息”
Claude 已经很聪明，你写“什么是 REST”基本是浪费 tokens。
真正值钱的是：
- 你们的业务规则
- 团队默认约定
- 真实踩坑点（失败形态）
原则 2：Gotchas 是 Skill 的 ROI 核心
如果你只能在 Skill 里写一段内容，写 Gotchas。
推荐格式：
- 现象：Claude 常怎么写错
- 为什么错：错误的默认假设是什么
- 正确做法：给出最小正确示例
- 验证方式：怎么确认修好了
迭代方法：每次翻车就把“翻车原因”写回 Gotchas；越用越强，像 Bug 库一样积累复利。
原则 3：用文件系统做“渐进式暴露”
入口 SKILL.md 只做三件事：
- 这 Skill 什么时候触发
- 输入需要什么
- 输出长什么样（指向模板/示例）
细节全部下沉：
references/api.md（接口签名、字段、口径）examples/good.md（优秀输出示例）assets/report_template.md（可复制模板）
官方文档也建议：SKILL.md 不要太长，详细材料拆出去，按需读取。[1]
原则 4：不要“把 Claude 绑死”，而是控制自由度
一条好用的经验：
- 高风险、强约束（部署、迁移、删资源）→ 指令更具体，甚至要求“照抄命令”
- 低风险、强探索（review、研究）→ 给原则和检查清单，保留机动性
原则 5：Setup 要当产品做
很多团队 Skill 最差的一步在“启动”：缺参数、缺环境、缺 ID。
做法：
- 用
config.json存配置 - 不存在就引导用户补齐
- 需要结构化输入就用选择题（减少来回问答）
原则 6：description 不是摘要，是“触发器”
在 Claude Code 里，skill 的 description 会用于自动发现与触发（默认情况下 description 会在上下文里）。[1]
因此 description 要写成：
- 做什么（what）
- 什么时候用（when）
- 用户会怎么说（keywords）
官方最佳实践还建议 第三人称，避免“我/你”视角导致触发混乱。[3]
3. 让 Skill 更“像工程”：脚本、Hook、记忆、可验证输出
到这里你会发现：Skill 的重点已经不是“写得像提示词”，而是“写得像工具”。
3.1 直接把脚本当成 Skill 的肌肉
把重复、确定性强的动作（拉数、验证、生成报告）做成脚本：
- 脚本更稳定
- 脚本输出可验证
- 脚本本身不需要进入上下文（只消费输出 tokens）
3.2 On-demand hooks：只在需要时打开护栏
有些 hook 你只希望“这次会话”生效，比如：
/careful：拦截 rm -rf / DROP TABLE / force push/freeze：限制写文件范围，防止调试时误改别处
核心思想：护栏应该按需启用，不要常驻干扰日常工作。
3.3 Skill 也可以存“工作记忆”
你可以把历史结果写进：
- append-only log
- JSON
- SQLite
这样下次执行时，先读历史，再输出差异（例如 standup/周报只写新增）。
4. 分发与治理：从“个人收藏”到“团队市场”
Skill 一旦在团队里跑起来，最容易出现两种问题：
- 重复造轮子（同类 Skill 多份）
- 垃圾 Skill 膨胀（没人维护、没人用）
4.1 两条分发路径
- 直接进仓库：
.claude/skills/跟项目一起版本化 - 插件 + marketplace：适合多仓库/大组织，成员按需安装
Claude Code 官方提供了 marketplace 的规范与命令（/plugin marketplace add、/plugin install ...），并支持用 marketplace.json 维护插件目录。[4]
4.2 如何决定“哪些 Skill 上架”？用自然选择
一个可持续的策略是：
- 先在小范围共享试用（GitHub sandbox、Slack）
- 有 traction 再进入“正式目录”
- 上架后要求：版本、维护人、用途描述、更新记录
4.3 度量：记录 Skill 是否真的被用
在规模化后，用数据治理 Skill：
- 哪些 Skill 使用率高 → 继续投入
- 哪些 Skill 预期触发但没触发 → 调整 description/关键词
Claude Code 文档也提到：技能太多会受到 context budget 限制，可以通过环境变量调整预算并用 /context 检查被排除的技能。[1]
5. 一套能落地的“从 0 到 1”路线（建议直接照抄）
如果你只想要一个实践顺序：
- 先做验证 Skill：马上提升可靠性
- 把 Gotchas 写成机制：每次翻车必回收
- 用模板固化输出：报告/PR/工单统一结构
- 接数据与监控：让 Claude 能自己找证据
- 最后做部署与运维护栏：把高风险操作产品化
你会发现 Skill 最终会变成一种“团队工作方式的编码”：它把你们的标准、流程、坑点、验证、工具链都装进了一个可复用的目录。
附录 A：一个可直接复制的 SKILL.md 入口模板
目标：让入口短、触发准、使用稳。
---
name: signup-flow-driver
description: Drives the signup → email verify → onboarding flow and asserts key UI states. Use when verifying signup, onboarding, or email verification regressions.
disable-model-invocation: true
allowed-tools: Bash(playwright:*), Read
argument-hint: [env]
---
# Signup Flow Driver
## What this Skill does
- Runs an end-to-end signup flow in a browser
- Takes screenshots at each checkpoint
- Fails fast with clear assertions
## Usage
- /signup-flow-driver staging
## Artifacts
- See assets/report_template.md for the final report format
- See scripts/run.sh for the exact command
## Gotchas
- Always use test inbox accounts from references/test-accounts.md
- If email verification times out, retry once before failing附录 B：阅读材料（引用与延伸）
- [1] Claude Code Docs — Extend Claude with skills: https://code.claude.com/docs/en/skills
- [2] Claude API Docs — Agent Skills overview（解释了 metadata/instructions/resources 的分层加载与“渐进式暴露”）：https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview
- [3] Claude API Docs — Skill authoring best practices（description 写法、简洁原则、结构建议）：https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices
- [4] Claude Code Docs — Create and distribute a plugin marketplace: https://code.claude.com/docs/en/plugin-marketplaces