Claude Skills规范深度解读：从格式到团队协作

Claude Skills 是可复用的指令文件夹，当请求与某个技能（Skill）的用途匹配时，Claude 会加载它们。每个文件夹包含一个 SKILL.md 文件，以及该任务所需的脚本、参考文档和模板（可选）。Anthropic 将其描述为可复用的、基于文件系统的资源，能够将通用智能体转变为专业领域的专家。

该格式并非 Claude 独有。Anthropic 开发了它并将其作为开放标准发布，规范位于 agentskills.io，该站点的客户端展示列出了读取相同 SKILL.md 文件的智能体产品。

本文涵盖格式、技能的加载方式、当下技能的运行环境、安装方法、编写方法，以及值得使用的技能来源，并特别讨论当团队中有多人依赖技能时会发生什么变化。

创建团队技能库 · 在 GitHub 上阅读源码

发布方：Skills Board。发布时间：2026 年 8 月 12 日。最后检查：2026 年 8 月 15 日。

什么是 Claude Skill？

Claude Skill 是一个包含 SKILL.md 文件的文件夹：YAML frontmatter 包含 name 和 description，后接 Markdown 指令。Claude 只在上下文中保留 name 和 description，当请求与 description 匹配时才读取完整文件。捆绑的脚本、参考资料和资源文件仅在需要时才加载。

本节参考来源

Anthropic：Agent Skills overview

Agent Skills specification

Claude Skill 里面有什么？

一个 Skill 是一个目录，其入口文件是 SKILL.md。该文件以 YAML frontmatter 开头，后跟的 Markdown 内容在技能被触发后由 Claude 读取。前置数据中需要两个字段：name 和 description。规范定义了四个额外字段，全部为可选。

Agent Skills 规范定义的 SKILL.md frontmatter 字段。

my-skill/
  SKILL.md        # 必需：frontmatter 和指令
  scripts/        # 可选：智能体可执行的代码
  references/     # 可选：按需加载的文档
  assets/         # 可选：模板和其他静态文件

SKILL.md 之外的一切都是可选的。规范建议 scripts 放可执行代码，references 放智能体仅在需要时读取的文档，assets 放模板和其他静态文件。Markdown 正文本身没有任何限制。

Claude Code 接受自己额外的 frontmatter 字段，例如 disable-model-invocation 和参数声明。在 Claude Code 之外，claude.ai 上传路径、Skills API 和 Anthropic 的打包脚本只接受规范中的六个字段，意外的键会导致硬错误而非被忽略。符合规范的 frontmatter 在所有地方都能加载，包括 Claude Code。

本节参考来源

Agent Skills specification

Claude Code：skills documentation

Claude 如何决定使用哪个 Skill？

通过渐进式披露（progressive disclosure）。智能体分阶段加载技能，因此大量的已安装技能集合在没有任何一个真正相关之前几乎不消耗任何成本。

渐进式披露的三个阶段以及每个阶段的成本。

这就是为什么 description 在文件中比其他任何一行都更重要。它是大多数技能中在 Claude 决定是否读取其余内容之前唯一能看到的内容，因此如果一个 description 说了技能做什么却没有说何时使用它，那它就会无人问津。

同样的机制也解释了长度的指导原则。规范建议将 SKILL.md 保持在 500 行以内，并将细节移到引用文件中。在 Claude Code 中，加载的正文会留在对话中贯穿整个会话，因此你留在主文件中的每一行都是持续成本，而非一次性成本。

本节参考来源

Anthropic：Agent Skills overview

Agent Skills specification

Claude Code：skills documentation

Claude Skills 在哪里运行？

技能在 Claude Code、claude.ai 和通过 Claude API 运行，相同的 SKILL.md 文件夹被越来越多的其他智能体读取。不同之处在于技能如何安装、由谁使用，以及运行时允许什么。

各平台上技能的安装、共享和沙箱机制。

自定义技能不会跨平台同步。Anthropic 明确记录了这一点：通过 API 上传的技能在 claude.ai 上不可用，通过 API 上传的技能在 claude.ai 上不可用，而 Claude Code 技能是基于文件系统的，与两者独立。每个平台各自管理。

Anthropic 还为 PowerPoint、Excel、Word 和 PDF 提供了预构建技能。这些在 claude.ai 和 Claude API 上可用，在 Claude Code 中不可用。

本节参考来源

Anthropic：Agent Skills overview

Claude Code：skills documentation

Agent Skills：overview and client showcase

如何安装和运行 Claude Skill？

安装技能意味着将文件夹放到智能体查找的位置。格式本身没有包管理器，这就是为什么每个平台都有自己的路径。

在 Claude Code 中，将文件夹放到 skills 目录 使用 ~/.claude/skills/ 使技能在所有项目中可用，或使用 .claude/skills/ 将其限定在一个代码库并与代码一起提交。Claude Code 会监控这些目录，并在会话期间自动拾取新增或编辑的 SKILL.md，无需重启。

自己调用，或让 Claude 选择 一个技能可以作为以目录命名的斜杠命令使用，Claude 也可以在请求与 description 匹配时自动加载它。当只有你自己应该能够触发它时，添加 disable-model-invocation: true，这是任何涉及部署、提交或发送消息的操作的合理默认值。

在 claude.ai 上传 zip 自定义技能在 Settings 下的 Features 中上传，适用于启用了代码执行的 Pro、Max、Team 和 Enterprise 计划。由于 claude.ai 自定义技能是按用户划分的，每个队友需要为自己的账户完成此操作。

通过 API 传递 skill_id 技能在代码执行工具的容器中运行。在容器参数中通过 id 引用技能，并发送 skills-2025-10-02 beta 标头。当容器需要上传的输入文件或产生需要下载的输出文件时，添加 files-api-2025-04-14 标头。

从目录安装使用该目录的安装程序 npx skills add owner/repo 从 skills.sh 目录安装。/plugin marketplace add anthropics/skills 将 Anthropic 的仓库注册为 Claude Code 中的插件市场，文档和示例技能插件从那里安装。

本节参考来源

Claude Code：skills documentation

Anthropic：Agent Skills overview

skills.sh documentation

anthropics/skills on GitHub

如何编写自己的 Claude Skill？

编写技能的方式与指导新队友相同：先说明该流程适用的场景，然后给出步骤，最后链接到细节而非粘贴全文。

选择你已经重复做的事情 Anthropic 对 Claude Code 的触发条件很直接：当你在聊天中不断粘贴相同的指令、检查清单或多步骤流程时，就创建一个技能，或者当 CLAUDE.md 的某个部分已经演变成流程而非事实时。

本节参考来源

Create the directory and the file

目录名即为你在 Claude Code 中输入的命令，必须与 frontmatter 中的 name 字段保持一致。SKILL.md 是入口文件，也是唯一必需的文件。

Write the description for matching, not for reading

描述要服务于匹配，而不是供人阅读。说明该技能的作用以及何时使用，并包含用户需要该技能时会输入的关键词。仅列出技能名称的描述对 Agent 没有任何匹配依据。

Keep the body short

规范建议将正文控制在 500 行和约 5,000 个 token 以内，将更长的内容放到 references 目录下的文件中，仅在任务需要时加载。

Move deterministic work into scripts

脚本代码永远不会进入 context window，只有其输出会。这使得打包后的脚本比每次让 Agent 重新生成相同逻辑更便宜、更可靠。

Validate before you share it

skills-ref 参考库可以检查 frontmatter 是否有效以及命名规则是否合规：skills-ref validate ./my-skill。这能在上传或打包时捕获错误，而不是在编写时就报错。

Decide the distribution scope

将 .claude/skills/ 提交到项目仓库适合团队使用；将 skills 目录打包到插件中发布适合更广泛的受众；通过托管设置进行组织级部署适合企业场景。每种范围回答的是不同的问题——谁应该默认获得该技能。

SKILL.md 起点

---
name: release-notes
description: Draft release notes from merged pull requests. Use when preparing a release, writing a changelog, or summarizing what shipped.
---

# Release notes

## Steps
1. List the pull requests merged since the last tag.
2. Group them into Added, Changed, and Fixed.
3. Write one line per change, in plain language, from the reader's point of view.
4. Link every entry to its pull request.

## Output
A Markdown section ready to paste into the release description.

本节参考来源

Claude Code: skills documentation

Agent Skills specification

Where do you find Claude Skills worth using?

从发布技能文件的来源入手，这样可以在安装前先阅读技能内容。目前生态中的大多数可用选择都集中在以下四个来源。

Anthropic 的公共 Agent Skills 仓库。其中包含跨创意、技术和企业场景的示例技能、规范以及技能模板。许多技能采用 Apache 2.0 许可证。文档类技能（驱动 Claude 中文件创建的技能）为源码可用而非开源，Anthropic 将其作为更复杂技能的参考范例。用 /plugin marketplace add anthropics/skills 将该仓库注册为 Claude Code 插件市场。

一个 MIT 许可证的社区项目，将完整的软件开发方法论封装为可组合的技能集，采用规范优先、计划再构建的工作流程。文档中提供了面向 Claude Code 及多种其他 Agent 的安装路径，可从官方 Claude 插件市场安装。

Vercel 的公共 Agent Skills 目录。其中有基于 CLI 匿名遥测数据的排行榜、主题分类、官方技能集，以及将多个技能打包为一条安装命令的技能包。技能通过 npx skills add owner/repo 安装，CLI 为开源项目。

规范本身的官方网站：包含规范、快速入门，以及客户端展示页面（链接到支持该格式的各 Agent 产品的技能说明）。当你需要确认某个技能是否能在 Claude 以外的 Agent 中加载时很有用。

安装前先阅读。Anthropic 的指导原则是只使用你信任的来源的技能，因为技能会为 Agent 提供新的指令和可执行代码，恶意技能可能引导 Agent 以与声明目的不符的方式调用工具。如果技能来自不熟悉的来源，审计其中的每个文件，包括脚本及其从外部 URL 获取的任何内容，做决定时像对待安装软件一样谨慎。

本节参考来源

anthropics/skills on GitHub

obra/superpowers on GitHub

skills.sh documentation

Agent Skills: overview and client showcase

Anthropic: Agent Skills overview

How does a team share the skills it recommends?

格式本身不负责分享。SKILL.md 文件夹是可移植的，但分发是按 Surface 分开的，推荐本身通常没有任何地方存储。

看看各个 Surface 实际能为团队提供什么。claude.ai 上，自定义技能属于个人用户，无法在组织内共享，管理员也无法集中管理。通过 API 上传的技能是工作区级别的。在 Claude Code 中，技能可以存在于个人文件夹、一个仓库或一个插件中。但这些地方都无法存放团队成员一直在问的那部分内容：哪个技能适合这个任务，为什么是这个。

那部分内容最终散落在聊天记录、书签或某个人的记忆里。Skills Board 正是为了解决这一层问题而生的共享库：团队推荐使用的技能集，放在一个可搜索的地方，每个条目的原始来源都对所有人可见。

Open the original source

每个已保存的技能都记录了它来自哪个仓库和路径，团队成员在使用前可以先阅读 SKILL.md。

Copy an install command

为那些命令适合其安装方式的团队成员准备。

Download a ZIP

从源地址下载最新技能文件，供那些更喜欢自己放置文件夹的人使用。

Connect an agent over MCP

经过 MCP 身份验证的端点让兼容的 Agent 可以搜索同一个团队技能库、获取安装命令，并在获得授权范围内保存技能和组织集合。登录在浏览器中完成，无需复制 API 密钥。

A saved skill is a team recommendation, not a security review, an approval, or a compatibility certification.

Skills Board 跟随已保存来源中的最新可用版本。它不会固定或保留历史版本。

它不会在你的 Agent 内部安装或运行技能，也不会声称某个技能适用于团队使用的每个 Agent。

该托管产品永久免费，代码采用 MIT 许可证，你可以阅读或自行托管全部内容。

Create your team library

本节参考来源

Anthropic: Agent Skills overview

Claude Code: skills documentation

Frequently asked questions

What is a Claude Skill?

一个包含 SKILL.md 文件的文件夹，文件中带有 YAML frontmatter 和 Markdown 说明。frontmatter 需要 name 和 description；description 是 Claude 匹配请求的依据。文件夹中还可以打包脚本、参考文档和资源文件，仅在任务需要时加载。

What is the difference between a skill and a prompt?

Prompt 是针对单个任务在对话层面的指令。技能是一个可重用的文件夹，按需加载，因此相同的指导无需在每次对话中重复。Anthropic 在 Agent Skills 概述中直接阐明了这一区别。

Do Claude Skills work outside Claude?

可以。Agent Skills 是发布在 agentskills.io 上的开放规范，其客户端展示页面列出了读取相同 SKILL.md 文件的 Agent 产品。规范中六个字段以外的 frontmatter 字段，以及 Claude Code 独有的 body 特性（如动态 context 注入）不会迁移过去。

自定义技能能在 Claude Code、claude.ai 和 API 之间同步吗？不能。Anthropic 文档明确指出，自定义技能不会在各平台间同步。上传到 claude.ai 的技能不会通过 API 提供，API 技能在 claude.ai 上不可用，而 Claude Code 的技能以文件系统为基础，与两者完全独立。你需要自己在每个平台上单独管理。

安装多少技能后上下文会受影响？启动时只加载每个已安装技能的名称和描述，每个约 100 tokens，所以大量的技能集合在触发之前几乎不消耗。在 Claude Code 中，被触发的技能内容会在会话剩余时间内保留在对话中，所以真正重要的不是你安装了多少个技能，而是一次会话中实际使用了多少个。

安装 Claude Skills 安全吗？对待技能的態度应该像对待即将运行的软件一样。Anthropic 的指导原则是只使用来自可信来源的技能，并在使用任何来自未知来源的技能之前审查每个捆绑文件，因为技能可以指示智能体执行代码和调用工具。从外部 URL 获取内容的技能尤其需要仔细审查。

技能和 MCP 服务器有什么区别？技能是智能体读取的一组指令和资源。MCP 则是一种协议，通过服务器将智能体连接到外部工具和数据。它们解决的是不同的问题，且经常一起使用：Skills Board 通过经过身份验证的 MCP 端点发布团队知识库，而技能本身则保留在其原始来源的 SKILL.md 文件夹中。

团队应该在哪里存放推荐的技能？放在团队成员实际会去查看的地方。如果每个技能都属于团队共同工作的一个代码库，就将它们提交到 .claude/skills/ 然后到此为止。如果推荐来自其他人的代码库，且团队成员使用不同的智能体，那么维护一个在每个条目上都能看到来源的共享库会更容易保持更新。Skills Board 是一个选项，而且是免费和开源的。

编辑方法：关于格式和运行该格式的产品的每一条声明均来自下方的一手文档。产品行为会发生变化，所以在依赖某个细节之前请查看相关链接页面。

Anthropic：Agent Skills 概述：渐进式披露阶段和 token 消耗、必需的 frontmatter 字段、技能运行的平台、共享范围、运行时约束、预置的文档技能以及安全指导。

Claude Code：技能文档：Claude Code 从何处加载技能、斜杠命令调用、disable-model-invocation、实时变更检测、哪些 frontmatter 字段在 Claude Code 外部会保留，以及分发范围。

Agent Skills 规范：六个 frontmatter 字段及其约束、可选的 scripts、references 和 assets 目录、渐进式披露预算，以及 skills-ref 验证。

Agent Skills：概述和客户端展示：作为 Anthropic 最初开发的开放标准，以及支持该格式的智能体产品列表。

anthropics/skills on GitHub：Anthropic 的公开技能仓库：示例技能、规范、模板、文档技能的许可说明，以及插件市场命令。

obra/superpowers on GitHub：一个 MIT 许可的技能框架和开发方法论，提供了 Claude Code 和其他智能体的已记录安装路径。

skills.sh 文档：npx skills add 命令、基于遥测的排行榜、常规安全审计、packs，以及背后的开源 CLI。

Codex skills：它们是什么以及如何使用：OpenAI 智能体读取的相同标准、它扫描的目录，以及技能在迁移时保留的内容。

Cursor skills：它们是什么以及如何使用：Cursor 扫描的每个目录，包括 Claude 的目录，以及它添加的两个 frontmatter 字段。

在 Claude Code、Codex 和 Cursor 中管理技能：为每个队友运行的智能体准备一个规范的 SKILL.md 和经过测试的安装路径。

如何与团队共享 AI 智能体技能：将有用的技能变成下一位队友能找到的推荐。

面向团队的共享 MCP 技能库：已连接的智能体可以通过共享库做什么和不能做什么。

Skills Board vs skills.sh：公共目录与团队库并立，每个问题分别由谁回答。

把你的团队推荐的技能放在每个人都能找到的地方。

永久免费，MIT 许可，开源。创建一个库，保存第一个技能，然后邀请那些总是问该用哪个技能的人。

创建你的团队库 · 在 GitHub 上查看代码

最初发表于 skillsboard.sh/claude-skills。

为进一步操作，你可以考虑屏蔽此人并/或举报滥用行为