Claude Code 的 Skills 远不止于 Markdown 文件，它们是可包含脚本、资产和数据的文件夹，能让代理动态发现与操作。基于 Anthropic 内部数百个技能的实践，其应用可归纳为 9 种主要类型，而编写高效技能则有 9 条关键最佳实践，包括避免陈述已知信息、构建“陷阱”章节、利用文件系统进行渐进式披露等。本文将系统阐述这一体系，助你从零构建强大的 Skills。

Thariq 的 Skills 实战指南：9 种技能类型、9 条编写最佳实践 #

Claude Code 的 Skills 是其最具灵活性的扩展点之一，它们为 AI 代理提供了可复用的知识、工具和工作流。Anthropic 的 Thariq 分享了其团队内部大规模使用 Skills 的经验，揭示了技能设计与编写的成熟模式。掌握这些模式，能帮助你从随意提示转向结构化的代理工程实践。

Skills 不仅仅是 Markdown #

一个常见的误解是将技能等同于简单的 Markdown 指令文件。实际上，技能的本质是一个文件夹，它可以包含 Markdown 文档、可执行脚本、参考数据甚至 SQLite 数据库。这种结构使得代理能够“发现、探索和操作”技能中的资源。技能还拥有丰富的配置选项，包括注册动态钩子（Hooks），这使其能力远超静态指令。

9 种技能类型分类 #

Anthropic 团队在梳理其内部大量技能后，发现它们自然聚类为 9 个核心类别。清晰的分类有助于你设计目标明确的技能，避免功能混杂。

1. 库与 API 参考 (Library & API Reference) #

这类技能旨在指导 Claude 正确使用特定的库、CLI 工具或 SDK。内容通常包括参考代码片段列表和使用时必须避免的“陷阱”（Gotchas）。它们特别适用于内部库或 Claude 理解有困难的常用库。

• 示例：billing-lib（账单库）、internal-platform-cli（内部平台 CLI）、frontend-design（前端设计规范）。

2. 产品验证 (Product Verification) #

技能描述如何测试或验证代码是否正常工作。它们常与 Playwright、tmux 等外部工具配对使用。拥有优秀的验证技能对于确保 Claude 输出的正确性至关重要，值得投入专门精力来打磨。

• 示例：signup-flow-driver（注册流程驱动）、checkout-verifier（结账验证器）。

3. 数据获取与分析 (Data Fetching & Analysis) #

连接到你的数据源和监控栈。可能包含获取数据所需的库、特定的仪表盘 ID 以及常见数据查询工作流说明。

• 示例：funnel-query（漏斗查询）、grafana（Grafana 仪表板操作）。

4. 业务流程与团队自动化 (Business Process & Team Automation) #

将重复性工作流自动化为一个命令。指令通常相对简单，但可能依赖其他技能或 MCP 服务器。建议将历史执行结果保存在日志文件中，以帮助模型保持一致性并进行反思。

• 示例：standup-post（站会发布）、weekly-recap（每周总结）。

5. 代码脚手架与模板 (Code Scaffolding & Templates) #

为代码库中的特定功能生成框架样板代码。这些技能尤其适用于那些无法完全用纯代码覆盖的、包含自然语言描述的脚手架需求。

• 示例：new-migration（创建新数据库迁移）、create-app（创建应用骨架）。

6. 代码质量与审查 (Code Quality & Review) #

在组织内强制执行代码质量标准并辅助代码审查。可以包含为追求最大鲁棒性而设计的确定性脚本或工具。你可能希望通过钩子或 GitHub Actions 来自动运行这些技能。

• 示例：adversarial-review（对抗性审查）、testing-practices（测试实践）。

7. CI/CD 与部署 (CI/CD & Deployment) #

辅助代码获取、推送和部署。这些技能可能会引用其他技能来收集必要的数据。

• 示例：babysit-pr（PR 看护）、deploy-<service>（部署某服务）。

8. 运行手册 (Runbooks) #

接收一个“症状”（如一个 Slack 讨论串、告警或错误特征），引导代理进行多工具调查，并最终生成一份结构化报告。

• 示例：<service>-debugging（某服务调试）、oncall-runner（值班运行器）。

9. 基础设施运维 (Infrastructure Operations) #

执行例行维护和操作流程，其中一些可能涉及破坏性操作，因此需要防护栏。它们让工程师在关键操作中更容易遵循最佳实践。

• 示例：<resource>-orphans（资源孤儿清理）、cost-investigation（成本调查）。

9 条技能编写最佳实践 #

理解了技能类型后，如何编写出真正高效、健壮的技能？以下是来自数百个实战技能的 9 条核心建议。

1. 不要陈述已知信息 (Don’t State the Obvious) #

Claude 和 Claude Code 对编码和通用知识已有很深理解。如果你发布一个技能的主要目的是提供知识，那么应聚焦于那些能推动 Claude 跳出其默认思维模式的信息。例如，frontend-design 技能就是通过与客户迭代，改进 Claude 的设计品味，避免使用千篇一律的模式。

2. 构建“陷阱”章节 (Build a Gotchas Section) #

任何技能中，信号强度最高的内容就是“陷阱”章节。这些章节应该基于 Claude 在使用你的技能时最常见的失败点来构建。理想情况下，你应该随着时间推移持续更新技能，以捕获新发现的陷阱。

3. 利用文件系统与渐进式披露 (Use the File System & Progressive Disclosure) #

技能是一个文件夹，而不仅仅是 Markdown 文件。你应该将整个文件系统视为一种上下文工程和渐进式披露的形式。告诉 Claude 你的技能中有哪些文件，它会在适当的时候去读取它们。最简单的形式是将详细的函数签名和用法示例拆分到 references/api.md 等文件中。你可以拥有包含参考、脚本、示例的子文件夹。

4. 避免过度约束 Claude (Avoid Railroading Claude) #

Claude 通常会尽力遵循你的指令。由于技能具有高度复用性，你需要注意指令不要过于具体。为 Claude 提供所需信息，同时给予它适应具体情境的灵活性。与其给出规定性的分步指令，不如给出目标与约束条件。

5. 仔细思考初始化 (Think through the Setup) #

某些技能可能需要用户提供上下文才能进行设置。一个好的模式是将这些配置信息存储在技能目录下的 config.json 文件中。如果配置未设置，代理可以随后向用户询问信息。你可以指示 Claude 使用 AskUserQuestion 工具来提出结构化的多项选择问题。

6. “描述”字段是给模型看的 (The Description Field Is For the Model) #

当 Claude Code 启动会话时，它会构建一个包含每个可用技能及其描述的列表。Claude 会扫描这个列表来决定“这个请求是否有对应的技能？”。这意味着描述字段不是摘要，而是对该技能何时触发（when to trigger）的描述。请为模型编写它。

7. 记忆与数据存储 (Memory & Storing Data) #

一些技能可以通过在自身内部存储数据来包含一种记忆形式。你可以将数据存储在任何地方，从简单的追加写入文本日志文件、JSON 文件，到复杂的 SQLite 数据库。需要注意的是，存储在技能目录下的数据在你升级技能时可能会被删除，因此应使用 ${CLAUDE_PLUGIN_DATA} 作为每个插件的稳定文件夹来存储数据。

8. 存储脚本并生成代码 (Store Scripts & Generate Code) #

你能给 Claude 的最强大工具之一是代码。向 Claude 提供脚本和库，可以让它将计算轮次用于“组合”和决策下一步做什么，而不是重构样板代码。Claude 随后可以动态生成脚本来组合这些功能，以进行更高级的分析。

9. 按需钩子 (On Demand Hooks) #

技能可以包含仅在技能被调用时激活、并持续整个会话生命周期的钩子。适用于那些你不想一直运行，但在某些时候极其有用的观点性钩子。

• 示例：
  • /careful — 通过 Bash 的 PreToolUse 匹配器，阻止 rm -rf、DROP TABLE、force-push、kubectl delete 等危险命令。
  • /freeze — 阻止对特定目录之外文件的任何 Edit/Write 操作。

技能的分发、组合与度量 #

分发技能 #

有两种主要方式与团队共享技能：

1. 检入到仓库（放在 .claude/skills 下）：适用于跨相对较少仓库工作的小型团队。
2. 制作成插件：建立一个 Claude Code 插件市场，用户可上传和安装插件。每个检入的技能都会为模型上下文增加一点负担。随着规模扩大，内部插件市场可以让你分发技能，并让团队决定安装哪些。

组合技能 #

你可能希望技能之间存在依赖。例如，一个文件上传技能和一个生成 CSV 并上传的技能。虽然目前市场或技能本身并未原生内置这种依赖管理，但你可以直接通过名称引用其他技能，如果已安装，模型将会调用它们。

度量技能使用情况 #

要了解一个技能的运行状况，可以使用一个 PreToolUse 钩子来在公司内部记录技能使用日志。这样你就能发现哪些技能很受欢迎，或者哪些技能的触发率低于预期。

总结 #

Skills 是强大而灵活的代理工具，但该领域仍处于早期阶段，我们都在摸索最佳实践。将本文视为从大量实践中提炼出的实用技巧集合，而非绝对指南。理解技能的最佳方式是立即开始，进行实验，看看什么对你有效。大多数优秀的技能都始于几行指令和一个简单的“陷阱”，并在人们不断因 Claude 遇到新的边缘情况而补充内容的过程中变得更好。想要更深入地了解 Skills 的字段定义与调用模式，可以参考这份 Claude Code Skills 深度解析。

FAQ #

Q: Skills 和 Commands 的主要区别是什么？ A: Skills 是可被代理按需发现和调用的知识或能力模块，通常包含详细的上下文和工具。Commands（如 /goal、/ultrareview）是用户主动触发的、执行特定任务的快捷指令，更侧重于触发一个动作或流程。

Q: 如何开始编写我的第一个 Skill？ A: 从一个明确的、小范围的目标开始，例如“总结当前 Git 状态”或“查询某个特定 API”。创建一个文件夹，放入一个 SKILL.md 文件，清晰描述其目的和触发条件（“描述”字段）。先实现一个核心功能，并记录下你在测试过程中发现的“陷阱”。

Q: 技能应该放在项目目录还是全局目录？ A: 这取决于技能的用途。如果技能只与当前项目相关（如特定框架的脚手架），应放在项目级的 .claude/skills/ 下。如果技能是通用的（如代码风格检查、个人常用工具），可以放在用户主目录的全局配置中。对于团队协作，推荐使用项目级配置或内部插件市场进行分发。