Lessons from building Claude Code: How we use skills

Types of skills技能类型

After cataloging all of our internal skills at Anthropic, we noticed they cluster into nine categories. The best skills fit cleanly into one; the ones that try to do too much straddle several and confuse the agent. This isn't a definitive list, but it is a useful framework for identifying gaps in your own skills library. 在整理 Anthropic 内部所有技能后，我们发现它们可归为九类。最佳技能恰好属于其中一类；而那些试图面面俱到的技能则横跨多个类别，反而让智能体感到困惑。这并非最终列表，但为识别自身技能库中的缺口提供了实用框架。

1. Library and API reference1. 库与 API 参考

These are skills that explain how to correctly use a library, CLI, or SDKs. They could be both for internal libraries or common libraries that Claude Code sometimes struggles to handle. These skills often included a folder of reference code snippets and a list of gotchas for Claude to avoid when writing a script.这些技能解释了如何正确使用库、CLI 或 SDK。它们既适用于内部库，也适用于 Claude Code 有时难以处理的常见库。这些技能通常包含一个参考代码片段文件夹，以及 Claude 在编写脚本时应避免的陷阱列表。

Examples include:示例包括：

• billing-lib — your internal billing library: edge cases, footguns, etc.billing-lib — 你的内部计费库：边缘情况、陷阱等。
• internal-platform-cli — every subcommand of your internal CLI wrapper with examples on when to use them.internal-platform-cli — 内部 CLI 包装器的每个子命令，以及何时使用它们的示例。
• sandbox-proxy — configuring your org's egress gateway for dev work: which hosts are reachable, how to debug "connection refused" errors, how to add an allowlist entry.sandbox-proxy — 配置组织的开发用出口网关：哪些主机可访问，如何调试“连接被拒绝”错误，如何添加白名单条目。

2. Product verification2. 产品验证

These are skills that describe how to test or verify that your code is working. They are often paired with playwright, tmux, or other external tools for verification.这些技能描述了如何测试或验证代码是否正常工作。它们通常与 playwright、tmux 或其他外部验证工具配合使用。

Verification skills have had the most measurable impact on Claude’s output quality internally. It can be worth having an engineer spend a week just making your verification skills excellent.验证技能对 Claude 内部输出质量的影响最为显著。值得让工程师花一周时间专门完善验证技能。

Consider techniques like having Claude record a video of its output so you can see exactly what it tested, or enforcing programmatic assertions on state at each step. These are often done by including a variety of scripts in the skill.考虑使用诸如让 Claude 录制输出视频以便精确查看测试内容，或在每一步强制执行程序化状态断言等技术。这些通常通过在技能中包含各种脚本来实现。

Examples include:

• signup-flow-driver — runs through signup → email verify → onboarding in a headless browser, with hooks for asserting state at each stepsignup-flow-driver — 在无头浏览器中执行注册 → 邮箱验证 → 新手引导流程，并在每一步设置状态断言钩子。
• checkout-verifier — drives the checkout UI with Stripe test cards, verifies the invoice actually lands in the right statecheckout-verifier — 使用 Stripe 测试卡驱动结账 UI，验证发票确实进入正确状态。
• tmux-cli-driver — for interactive CLI testing where the thing you're verifying needs a TTYtmux-cli-driver — 用于需要 TTY 的交互式 CLI 测试。

3. Data fetching and analysis3. 数据获取与分析

These are skills that connect to your data and monitoring stacks. These skills might include libraries to fetch your data with credentials, specific dashboard ids, etc., as well as instructions on common workflows or ways to get data.这些技能连接到你的数据和监控栈。它们可能包含用于获取数据的库（含凭据）、特定仪表板 ID 等，以及常见工作流或数据获取方式的说明。

Examples include:

• funnel-query — "which events do I join to see signup → activation → paid" plus the table that actually has the canonical user_idfunnel-query — “我需要关联哪些事件才能看到注册 → 激活 → 付费”以及包含规范 user_id 的表。
• cohort-compare — compare two cohorts' retention or conversion, flag statistically significant deltas, link to the segment definitionscohort-compare — 比较两个群组的留存或转化率，标记统计显著差异，链接到细分定义。
• grafana — datasource UIDs, cluster names, problem → dashboard lookup tablegrafana — 数据源 UID、集群名称、问题 → 仪表板查找表。
• datadog — field reference (@request_id vs trace_id), service list, metric prefix conventionsdatadog — 字段参考（@request_id 与 trace_id）、服务列表、指标前缀约定。

4. Business process and team automation4. 业务流程与团队自动化

These are skills that automate repetitive workflows into one command. These skills are usually fairly simple instructions but might have more complicated dependencies on other skills or MCPs. For these skills, saving previous results in log files can help the model stay consistent and reflect on previous executions of the workflow.这些技能可以将重复性工作流自动化整合为一条命令。这些技能通常是指令较为简单，但可能依赖于其他技能或MCP，依赖关系较为复杂。对于这些技能，将先前的结果保存在日志文件中可以帮助模型保持一致性，并反思之前的工作流执行情况。

Examples include:

• standup-post — aggregates your ticket tracker, GitHub activity, and prior Slack → formatted standup, delta-onlystandup-post — 聚合你的工单追踪器、GitHub活动和之前的Slack消息 → 格式化的每日站会报告，仅增量内容
• create-<ticket-system>-ticket — enforces schema (valid enum values, required fields) plus post-creation workflow (ping reviewer, link in Slack)create-<ticket-system>-ticket — 强制执行模式（有效的枚举值、必填字段）以及创建后的工作流（通知审核人、在Slack中链接）
• weekly-recap — merged PRs + closed tickets + deploys → formatted recap postweekly-recap — 合并的PR + 关闭的工单 + 部署 → 格式化的周报

5. Code scaffolding and templates5. 代码脚手架和模板

These are skills that generate framework boilerplates for a specific function in a codebase. You might combine these skills with scripts that can be composed. They are especially useful when your scaffolding has natural language requirements that can’t be purely covered by code. 这些技能可以为代码库中的特定功能生成框架模板。你可以将这些技能与可组合的脚本结合使用。当你的脚手架包含无法完全由代码覆盖的自然语言需求时，这些技能尤其有用。

Examples include:

• new-<framework>-workflow — scaffolds a new service/workflow/handler with your annotationsnew-<framework>-workflow — 使用你的注解搭建新的服务/工作流/处理器
• new-migration — your migration file template plus common gotchasnew-migration — 你的迁移文件模板加上常见陷阱
• create-app — new internal app with your auth, logging, and deploy config pre-wiredcreate-app — 新的内部应用，预配置了你的认证、日志记录和部署配置

6. Code quality and review6. 代码质量和审查

These are skills that enforce code quality inside of your org and help review code. These can include deterministic scripts or tools for maximum robustness. You may want to run these skills automatically as part of hooks or inside of a GitHub Action. 这些技能用于在你的组织内强制执行代码质量并帮助审查代码。这些技能可以包括确定性脚本或工具，以实现最大稳健性。你可能希望将这些技能作为钩子的一部分或在GitHub Action中自动运行。

• adversarial-review — spawns a fresh-eyes subagent to critique, implements fixes, iterates until findings degrade to nitpicksadversarial-review — 生成一个全新视角的子代理进行评审，实施修复，迭代直到发现的问题降级为小问题
• code-style — enforces code style, especially styles that Claude does not do well by default.code-style — 强制执行代码风格，特别是Claude默认处理不好的风格
• testing-practices — instructions on how to write tests and what to test.testing-practices — 关于如何编写测试以及测试内容的说明

7. CI/CD and deployment7. CI/CD和部署

These are skills that help you fetch, push, and deploy code inside of your codebase. These skills may reference other skills to collect data.这些技能帮助你获取、推送和部署代码库中的代码。这些技能可能引用其他技能来收集数据。

Examples include:

• babysit-pr — monitors a PR → retries flaky CI → resolves merge conflicts → enables auto-mergebabysit-pr — 监控PR → 重试不稳定的CI → 解决合并冲突 → 启用自动合并
• deploy-<service> — build → smoke test → gradual traffic rollout with error-rate comparison → auto-rollback on regressiondeploy-<service> — 构建 → 冒烟测试 → 逐步流量发布，带错误率比较 → 回归时自动回滚
• cherry-pick-prod — isolated worktree → cherry-pick → conflict resolution → PR with templatecherry-pick-prod — 隔离工作树 → cherry-pick → 冲突解决 → 带模板的PR

8. Runbooks8. 运行手册

These are skills that take a symptom (such as a Slack thread, alert, or error signature), walk through a multi-tool investigation, and produce a structured report.这些技能能够获取一个症状（例如 Slack 线程、告警或错误特征），进行多工具调查，并生成结构化报告。

Examples include:

• <service>-debugging — maps symptoms → tools → query patterns for your highest-traffic services<service>-debugging — 将症状映射到工具和查询模式，适用于你的高流量服务
• oncall-runner — fetches the alert → checks the usual suspects → formats a findingoncall-runner — 获取告警 → 检查常见问题 → 格式化发现结果
• log-correlator — given a request ID, pulls matching logs from every system that might have touched itlog-correlator — 给定一个请求 ID，从所有可能涉及的系统拉取匹配的日志

9. Infrastructure operations9. 基础设施运维

These are skills that perform routine maintenance and operational procedures, some of which involve destructive actions that benefit from guardrails. These make it easier for engineers to follow best practices in critical operations.这些技能执行日常维护和运维流程，其中一些涉及破坏性操作，需要安全护栏。它们使工程师更容易在关键操作中遵循最佳实践。

Examples include:

• <resource>-orphans — finds orphaned pods/volumes → posts to Slack → soak period → user confirms → cascading cleanup<resource>-orphans — 发现孤立的 Pod/卷 → 发布到 Slack → 等待期 → 用户确认 → 级联清理
• dependency-management — your org's dependency approval workflowdependency-management — 你所在组织的依赖审批工作流
• cost-investigation — "why did our storage/egress bill spike" with the specific buckets and query patternscost-investigation — “为什么我们的存储/出口费用飙升”，附带具体的存储桶和查询模式

Tips for making skills制作技能的技巧

Once you've decided on the skill to make, how do you write it? These are some of the Claude Code team’s best practices, tips, and tricks for making skills一旦你决定要制作某个技能，如何编写它？以下是 Claude Code 团队的一些最佳实践、技巧和窍门

Don’t state the obvious不要陈述显而易见的内容

Claude already knows how to code and can read your codebase. A skill that restates what Claude would do by default adds context without adding value. If you’re publishing a skill that is primarily about knowledge, focus on information that pushes Claude out of its normal way of thinking.Claude 已经知道如何编码，并且可以读取你的代码库。一个重复 Claude 默认行为的技能只会增加上下文，而不增加价值。如果你发布的技能主要是关于知识的，请专注于那些能推动 Claude 跳出常规思维的信息。

The frontend design skill is a great example; it was built by an engineer at Anthropic by iterating with customers on improving Claude’s design taste, avoiding classic patterns like the Inter font and purple gradients. 前端设计技能就是一个很好的例子；它由 Anthropic 的一位工程师通过与客户迭代改进 Claude 的设计品味而构建，避免了像 Inter 字体和紫色渐变这样的经典模式。

Build a gotchas section构建“注意事项”部分

The highest-signal content in any skill is the Gotchas section. These sections should be built up from common failure points that Claude runs into when using your skill. Ideally, you will update your skill over time to capture these gotchas.任何技能中信号最强的部分就是“注意事项”部分。这些部分应该从 Claude 使用你的技能时遇到的常见失败点中积累而来。理想情况下，你会随着时间的推移更新你的技能，以捕捉这些注意事项。

For example:例如：

"The subscriptions table is append-only. The row you want is the one with the highest version, not the most recent created_at." "This field is called @request_id in the API gateway and trace_id in the billing service. They're the same value." "Staging returns 200 even when the Stripe webhook didn't actually process. Check payment_events for the real state."“订阅表是仅追加的。你需要的行是版本最高的那一行，而不是 created_at 最新的那一行。” “这个字段在 API 网关中叫 @request_id，在计费服务中叫 trace_id。它们是同一个值。” “Staging 环境即使 Stripe webhook 没有实际处理也会返回 200。请检查 payment_events 以获取真实状态。”

Use the file system and progressive disclosure使用文件系统和渐进式披露

Like we said earlier, a skill is a folder, not just a markdown file. You should think of the entire file system as a form of context engineering and progressive disclosure. Tell Claude what files are in your skill, and it will read them at appropriate times.正如我们之前所说，技能是一个文件夹，而不仅仅是一个 markdown 文件。你应该将整个文件系统视为一种上下文工程和渐进式披露。告诉 Claude 你的技能中有哪些文件，它会在适当的时候读取它们。

The simplest form of progressive disclosure is to point to other markdown files for Claude to use. For example, you may split detailed function signatures and usage examples into references/api.md.渐进式披露的最简单形式是指向其他 markdown 文件供 Claude 使用。例如，你可以将详细的函数签名和用法示例拆分到 references/api.md 中。

Another example: if your end output is a markdown file, you might include a template file for it in assets/ to copy and use.另一个例子：如果你的最终输出是一个 markdown 文件，你可以在 assets/ 中包含一个模板文件供复制和使用。

You can have folders of references, scripts, examples, etc., which help Claude work more effectively. 你可以有引用、脚本、示例等文件夹，这些有助于 Claude 更有效地工作。

Avoid railroading Claude避免过度引导 Claude

Claude will generally try to stick to your instructions, and because skills are so reusable you’ll want to be careful of being too specific in your instructions. Give Claude the information it needs, but give it the flexibility to adapt to the situation. Claude 通常会尽量遵循你的指令，由于技能的可重用性很高，你需要注意不要让你的指令过于具体。给 Claude 所需的信息，但也要让它能够灵活适应情况。

For example:

Think through the setup考虑设置

Some skills may need to be set up with context from the user. For example, if you are making a skill that posts your standup to Slack, you may want Claude to ask which Slack channel to post it in.某些技能可能需要用户提供上下文才能设置。例如，如果你正在制作一个将你的站会发布到 Slack 的技能，你可能希望 Claude 询问发布到哪个 Slack 频道。

A good pattern to do this is to store this setup information in a config.json file in the skill directory like the above example. If the config is not set up, the agent can then ask the user for information.实现这一点的好模式是将这些设置信息存储在技能目录中的 config.json 文件中，如上例所示。如果配置未设置，代理可以询问用户信息。

If you want the agent to present structured, multiple choice questions you can instruct Claude to use the AskUserQuestion tool. 如果你希望代理呈现结构化的多项选择题，你可以指示 Claude 使用 AskUserQuestion 工具。

Write descriptions for the model, not for humans为模型编写描述，而不是为人类

When Claude Code starts a session, it builds a listing of every available skill with its description. This listing is what Claude scans to decide "is there a skill for this request?" Which means the description field is not a summary, it's a description of when to trigger this skill.当 Claude Code 启动一个会话时，它会构建每个可用技能及其描述的列表。Claude 扫描这个列表来决定“是否有技能可以处理这个请求？”这意味着描述字段不是摘要，而是描述何时触发该技能。

‍

Help Claude remember帮助 Claude 记住

Some skills can include a form of memory by storing data within them. You could store data in anything as simple as an append only text log file or JSON files, or as complicated as a SQLite database.某些技能可以通过在自身内部存储数据来实现一种记忆形式。你可以将数据存储在简单如仅追加的文本日志文件或JSON文件中，也可以复杂如SQLite数据库。

For example, a standup-post skill might keep a standups.log with every post it's written, which means the next time you run it, Claude reads its own history and can tell what's changed since yesterday. 例如，一个站会发布技能可能会保留一个standups.log文件，记录每次发布的内容，这样下次运行时，Claude会读取自己的历史记录，并能够判断自昨天以来发生了什么变化。

You can use the env variable ${CLAUDE_PLUGIN_DATA} to get a stable directory where you can store data, read more persisting data in skills here: https://code.claude.com/docs/en/plugins-reference#persistent-data-directory. 你可以使用环境变量${CLAUDE_PLUGIN_DATA}来获取一个稳定的目录，用于存储数据。更多关于在技能中持久化数据的信息，请参阅：https://code.claude.com/docs/en/plugins-reference#persistent-data-directory。

Store scripts and generate code存储脚本并生成代码

One of the most powerful tools you can give Claude is code. Giving Claude scripts and libraries lets Claude spend its turns on composition, deciding what to do next rather than reconstructing boilerplate.你可以给Claude的最强大工具之一就是代码。为Claude提供脚本和库，可以让Claude将精力集中在组合上，决定下一步做什么，而不是重复构建样板代码。

For example, in your data-science skill you might have a library of functions to fetch data from your event source. In order for Claude to do complex analysis, you could give it a set of helper functions like this:例如，在你的数据科学技能中，你可能有一个函数库，用于从事件源获取数据。为了让Claude进行复杂分析，你可以给它一组这样的辅助函数：

Claude can then generate scripts on the fly to compose this functionality to do more advanced analysis for prompts like “What happened on Tuesday?”然后Claude可以即时生成脚本，组合这些功能，对诸如“周二发生了什么？”这样的提示进行更高级的分析。

Use on-demand hooks 使用按需钩子

Skills can include hooks that are only activated when the skill is called, and that only last for the duration of the session. Use this for more opinionated hooks that you don’t want to run all the time, but are extremely useful sometimes.技能可以包含仅在技能被调用时激活的钩子，并且这些钩子仅在会话期间有效。对于你不想一直运行但有时非常实用的、更具主观性的钩子，可以使用这种方式。

For example:

• /careful — blocks rm -rf, DROP TABLE, force-push, kubectl delete via PreToolUse matcher on Bash. You only want this when you know you're touching prod — having it always on would drive you insane./careful — 通过Bash的PreToolUse匹配器阻止rm -rf、DROP TABLE、force-push、kubectl delete。你只会在你知道正在操作生产环境时才需要这个——如果一直开启，会让你抓狂。
• /freeze — blocks any Edit/Write that's not in a specific directory. Useful during debugging: "I want to add logs but I keep accidentally 'fixing' unrelated code.”/freeze — 阻止任何不在特定目录中的编辑/写入操作。在调试时很有用：“我想添加日志，但总是意外‘修复’不相关的代码。”

Distributing skills分发技能

One of the biggest benefits of skills is that you can share them with the rest of your team.技能的最大好处之一是你可以在团队中分享它们。

There are two ways you might want to share skills with others:有两种方式可以与他人分享技能：

• check your skills into your repo (under ./.claude/skills)将你的技能检入到仓库中（放在./.claude/skills下）
• make a plugin and have a Claude Code Plugin marketplace where users can upload and install plugins (read more on the documentation here)制作一个插件，并建立一个Claude Code插件市场，用户可以在其中上传和安装插件（更多信息请参阅文档）

For smaller teams working across relatively few repos, checking your skills into repos works well. But every skill that is checked in also adds a little bit to the context of the model. As you scale, an internal plugin marketplace allows you to distribute skills and let your team decide which ones to install, as well as include a setup flow.对于在相对较少的仓库上工作的小团队，将技能检入仓库效果很好。但每个检入的技能都会给模型上下文增加一点负担。随着规模扩大，内部插件市场允许你分发技能，让团队决定安装哪些技能，并包含设置流程。

Managing a skills marketplace管理技能市场

How do you decide which skills go in a marketplace? How do people submit them?如何决定哪些技能进入市场？人们如何提交它们？

At Anthropic, we don't have a centralized team that decides; instead we try to find the most useful skills organically. If someone has a skill that they want people to try out, they can upload it to a sandbox folder in GitHub and point people to it in Slack or other forums.在Anthropic，我们没有集中式的团队来决定；相反，我们尝试有机地找到最有用的技能。如果有人有一个技能想让别人试用，他们可以将其上传到GitHub的沙盒文件夹中，并在Slack或其他论坛中分享链接。

Once a skill has gotten traction (which is up to the skill owner to decide), they can put in a PR to move it into the marketplace.一旦某个技能获得了关注（由技能所有者决定），他们可以提交PR将其移入市场。

Composing skills 组合技能

You may want to have skills that depend on each other. For example, you may have a file upload skill that uploads a file, and a CSV generation skill that makes a CSV and uploads it. This sort of dependency management is not natively built into marketplaces or skills yet, but you can just reference other skills by name, and the model will invoke them if they are installed.你可能希望拥有相互依赖的技能。例如，你可能有一个文件上传技能用于上传文件，以及一个CSV生成技能用于生成CSV并上传。这种依赖管理尚未原生集成到市场或技能中，但你可以直接按名称引用其他技能，如果它们已安装，模型将调用它们。

Measuring skills衡量技能

To understand how a skill is doing, we use a PreToolUse hook that lets us log skill usage within the company (example code here). This means we can find skills that are popular or are undertriggering compared to our expectations.为了了解技能的表现，我们使用PreToolUse钩子来记录公司内部的技能使用情况（示例代码在此）。这样我们可以找到受欢迎的技能，或者那些触发频率低于预期的技能。

Get started开始使用

Skills best practices are still evolving. Most of our best skills began as a few lines and a single gotcha, then got better because people kept adding to them as Claude hit new edge cases. 技能的最佳实践仍在发展中。我们大多数最好的技能最初只有几行代码和一个注意事项，然后随着Claude遇到新的边缘情况，人们不断添加内容而变得更好。

The best way to understand skills is to get started, experiment, and see what works for you. 理解技能的最佳方式是开始使用、实验，并看看什么对你有效。

• Check out our skills documentation查看我们的技能文档
• Find example skills to customize查找可定制的示例技能

This article was written by Thariq Shihipar, a member of technical staff at Anthropic, working on Claude Code.本文由Thariq Shihipar撰写，他是Anthropic的技术人员，负责Claude Code的工作。