structure｜1️⃣ 三级笔记、思想框架
核心观点
Skills 是 Claude Code 中最广泛使用的扩展方式之一。Anthropic 内部已有数百个 Skills 在实际运行。这篇文章来自 Claude Code 团队工程师、Skills 功能核心参与者 Thariq Shihipar，分享了 Anthropic 内部使用 Skills 的实战经验——什么类型的 Skills 值得开发，怎样写出优秀的 Skill，以及何时将它们分享给他人。
一、Skills 的本质：不只是 Markdown 文件
- 一个常见误解：Skills「只是一些 Markdown 文件」
- 实际上，Skills 是一个文件夹，里面可以包含脚本、资源、数据等内容，供智能体发现、探索和操作
- Skills 还具备多种配置选项，包括注册动态钩子（hooks）等
- 最有意思的 Skills，正是通过巧妙利用这些配置选项和文件结构来实现的
二、Skills 的九大类型
整理所有 Skills 后，大致分为九个常见类别。最好的 Skills 通常能清晰归入一个类别；跨越多个类别的 Skills 往往更复杂、更难理解。
2.1 库与 API 参考（Library & API Reference）
- 解释如何正确使用库、CLI 或 SDK
- 包含参考代码片段，以及 Claude 编写脚本时应避免的常见问题
- 示例：billing-lib（内部账单库的边缘情况和陷阱）、internal-platform-cli（CLI 子命令与使用示例）、frontend-design（理解你的设计系统）
2.2 产品验证（Product Verification）
- 描述如何测试或验证代码是否正常工作
- 通常与 Playwright、tmux 等外部工具配合
- 验证 Skills 对确保 Claude 输出正确非常有用，可能值得让工程师花一周时间专注提高验证 Skills 的质量
- 考虑让 Claude 记录输出视频，这样可以准确看到它测试了什么；或在每个步骤上强制进行状态的程序化断言
- 示例：signup-flow-driver（无头浏览器跑注册流程）、checkout-verifier（Stripe 测试卡验证结账）、tmux-cli-driver（交互式 CLI 测试）
2.3 数据抓取与分析（Data Fetching & Analysis）
- 连接到数据和监控系统
- 包括通过凭证、仪表盘 ID 抓取数据的库，以及常见工作流说明
- 示例：funnel-query（注册→激活→付费的事件查询）、cohort-compare（比较群体留存/转化率，标记统计显著差异）、grafana（数据源 UID 和仪表盘查找表）
2.4 业务流程与团队自动化（Business Process & Team Automation）
- 将重复工作流自动化为一个命令
- 指令相对简单，但可能有更复杂的依赖关系（涉及其他 Skills 或 MCP）
- 将先前的结果保存在日志文件中有助于保持模型的一致性，并反映工作流的前期执行
- 示例：standup-post（汇总任务追踪器+GitHub+Slack→格式化站立会议）、create-ticket（强制执行必填字段和创建后工作流）、weekly-recap（合并 PR+关闭票据+部署→格式化周报）
2.5 代码脚手架与模板（Code Scaffolding & Templates）
- 生成代码库中特定功能的框架模板
- 可与可组合的脚本结合使用
- 在脚手架有自然语言要求、而这些要求无法仅通过代码覆盖时尤为有用
- 示例：new-workflow（脚手架新服务/工作流/处理器）、new-migration（迁移文件模板及常见坑）、create-app（预配认证、日志和部署的新内部应用）
2.6 代码质量与审核（Code Quality & Review）
- 强制执行代码质量并帮助审查代码
- 可包括确定性脚本或工具，确保最大程度的稳健性
- 可自动运行，作为 hooks 或 GitHub Actions 的一部分
- 示例：adversarial-review（启动子智能体批评→修复→迭代直到反馈降级为小瑕疵）、code-style（强制执行 Claude 默认处理不好的风格）、testing-practices（如何写测试及测试什么）
2.7 CI/CD 与部署（CI/CD & Deployment）
- 帮助在代码库内获取、推送和部署代码
- 示例：babysit-pr（监控 PR→重试不稳定 CI→解决合并冲突→启用自动合并）、deploy（构建→烟雾测试→渐进式流量发布→回滚回退）、cherry-pick-prod（隔离工作树→衍生选择→冲突解决→带模板的 PR）
2.8 运行手册（Runbooks）
- 通过症状（Slack 线程、警报、错误签名）进行多工具调查，生成结构化报告
- 示例：service-debugging（映射症状→工具→查询模式）、oncall-runner（获取警报→检查常见问题→格式化结果）、log-correlator（给定请求 ID，从所有系统提取匹配日志）
2.9 基础设施操作（Infrastructure Operations）
- 执行常规维护和操作程序，涉及需要有防护措施的破坏性操作
- 使工程师更容易遵循最佳实践，避免出错
- 示例：orphans（查找孤立 pods/volumes→Slack 通知→浸泡期→用户确认→级联清理）、dependency-management（依赖审批工作流）、cost-investigation（存储/出站流量账单飙升的排查）
三、制作 Skills 的技巧
3.1 不要陈述显而易见的内容
- Claude Code 已经了解很多关于代码库和编码基础知识
- 专注于那些能让 Claude 脱离正常思维方式的信息
- 例子：frontend-design Skill 通过与客户反复迭代，提升 Claude 的设计品味，避免经典的 AI 设计模式（如 Inter 字体和紫色渐变）
3.2 构建 Gotchas（常见陷阱）部分
- Gotchas 部分是任何 Skill 中最有价值的内容
- 应基于 Claude 在使用 Skill 时遇到的常见失败点来构建
- 随时间不断更新，捕捉这些常见问题
3.3 使用文件系统和渐进式披露（Progressive Disclosure）
- Skills 是一个文件夹——应将整个文件系统视为上下文工程和渐进式披露的方式
- 告诉 Claude 你的 Skill 包含哪些文件，它将在适当时候读取
- 最简单形式：指向其他 Markdown 文件（如 references/api.md 放详细函数签名）
- 可在 assets/ 文件夹中放模板文件供 Claude 复制使用
- 多个文件夹存储参考资料、脚本、示例
3.4 避免「束缚」Claude
- Skills 高度可复用，不要让指令过于具体
- 给予必要信息，同时留给 Claude 灵活性以适应不同情况
3.5 思考 Skills 的设置（Setup）
- 有些 Skills 需要用户提供上下文信息来完成设置
- 良好做法：将设置信息存储在 Skill 目录中的 config.json 文件中
- 如果配置尚未设置，智能体可以提示用户提供必要信息
- 可指示 Claude 使用 AskUserQuestion 工具呈现结构化多选问题
3.6 描述字段（Description）是给模型的
- Claude Code 启动会话时，会构建包含每个可用 Skill 及其描述的列表
- 这份列表是 Claude 用来决定「是否有 Skill 能解决这个请求」的依据
- 因此，描述字段不是 Skill 的总结，而是描述何时触发这个 Skill 的场景
3.7 记忆与存储数据
- Skills 可通过在内部存储数据实现一定的记忆功能
- 可存储在简单文本日志、JSON 文件或 SQLite 数据库中
- 例子：standup-post Skill 保留 standups.log，下次运行时 Claude 可读取历史记录，检测自昨天以来的变化
- 注意：Skill 目录中的数据可能在升级时被删除，应使用稳定文件夹（如
${CLAUDE_PLUGIN_DATA}）
3.8 存储脚本与生成代码
- 提供代码是给 Claude 最强大的工具之一
- 将脚本和库交给 Claude，让它专注于组合和决策，而不是重新构建基础代码
- 例子：数据科学 Skill 中提供一套从事件源抓取数据的帮助函数，Claude 动态生成脚本来组合这些函数执行高级分析
3.9 按需钩子（On Demand Hooks）
- Skills 可包括仅在被调用时激活的钩子，持续到会话结束
- 对于有强烈意见、但不希望一直运行的钩子特别有用
- 示例：
四、Skills 分发
4.1 两种分享方式
- 检入代码库：在
./.claude/skills 下检入（适合较小团队、较少代码库）
- 插件市场：创建 Claude Code Plugin 市场，用户可上传和安装插件（适合团队规模扩大时）
- 每个检入的 Skill 都会增加模型上下文；内部插件市场可让团队成员自主决定安装哪些 Skills
4.2 管理市场
- 没有集中式团队做决定
- 流程：上传到 GitHub 沙箱文件夹 → 通过 Slack 分享链接 → 获得一定关注度后 → 提交 PR 移入市场
- 警告：创建不必要或冗余的 Skills 非常容易，发布前确保有筛选和策划的方法
4.3 组合 Skills
- Skills 可以相互依赖（如：CSV 生成 Skill 调用文件上传 Skill）
concepts｜2️⃣ 关键概念、概念网络
agentic reading｜3️⃣ 费曼 x3