agent skill ： 简化说法：给llm的‘说明文档’ ```mindmap - Agent Skill 概念 - 定义：LLM可随时查阅的说明文档 - 功能：简化重复性任务指令，提升任务AI表现 - 应用场景：智能客服、会议总结等 - Agent Skill 基础使用 - 创建步骤 - 指定文件夹创建agent skill - 标记skill.md文件，定义名称、描述、指令 - 使用流程 - 用户请求 - Cloud Code识别并询问使用agent skill - 加载完整skill.md内容 - 模型响应 - 高级功能 - Reference - Script - 渐进式披漏机制 - Agent Skill 与 MCP对比 ``` ## Agent Skill 的核心概念 Agent Skill 本质是大模型可随时调用的说明文档，其核心价值在于 “简化重复性任务指令”—— 通过预定义的规则与流程，帮助 AI 更高效地完成标准化工作，典型应用场景包括智能客服（快速匹配应答话术）、会议总结（自动梳理内容框架）等。 在Claude中Skill 是一个 markdown 文件，它教 Claude 如何做特定的事情：使用你的团队标准审查 PR、以你喜欢的格式生成提交消息，或查询你公司的数据库架构。当你要求 Claude 做与 Skill 目的相匹配的事情时，Claude 会自动应用它。 ## 创建第一个 Skill [tabs] [tab name="检查可用的 Skills" active="true"] 在创建 Skill 之前，查看 Claude 已经可以访问的 Skills：`What Skills are available?` Claude 将列出当前加载的任何 Skills。你可能看不到任何，或者你可能看到来自插件或你的组织的 Skills。 [/tab] [tab name="创建 Skill 目录"] 在你的个人 Skills 文件夹中为 Skill 创建一个目录。个人 Skills 在你的所有项目中都可用。（你也可以在 `.claude/skills/` 中创建项目 Skills以与团队共享。） ```bash theme={null} mkdir -p ~/.claude/skills/explaining-code ``` [/tab] [tab name="编写 SKILL.md"] 每个 Skill 都需要一个 `SKILL.md` 文件。该文件以 `---` 标记之间的 YAML 元数据开始，必须包含 `name` 和 `description`，然后是 Claude 在 Skill 活跃时遵循的 Markdown 说明。`description` 特别重要，因为 Claude 使用它来决定何时应用 Skill。创建 `~/.claude/skills/explaining-code/SKILL.md`： ``` --- name: explaining-code description: Explains code with visual diagrams and analogies. Use when explaining how code works, teaching about a codebase, or when the user asks "how does this work?" --- When explaining code, always include: 1. **Start with an analogy**: Compare the code to something from everyday life 2. **Draw a diagram**: Use ASCII art to show the flow, structure, or relationships 3. **Walk through the code**: Explain step-by-step what happens 4. **Highlight a gotcha**: What's a common mistake or misconception? Keep explanations conversational. For complex concepts, use multiple analogies. ``` [/tab] [tab name="加载并验证 Skill"] Skills 在创建或修改时会自动加载。验证 Skill 出现在列表中： ``` What Skills are available? ``` [/tab] [tab name="测试 Skill"] 打开你项目中的任何文件，并向 Claude 提出与 Skill 描述相匹配的问题： ``` How does this code work? ``` Claude 应该要求使用 `explaining-code` Skill，然后在其解释中包含一个类比和 ASCII 图表。如果 Skill 没有触发，请尝试重新表述以包含描述中的更多关键词，例如”explain how this works”。 [/tab] [tab name="Skills 存放"] 存储 Skill 的位置决定了谁可以使用它： | 位置 | 路径 | 适用于 | | :--- | :------------------ | :----------------------- | | 个人 | `~/.claude/skills/` | 你，跨所有项目 | | 项目 | `.claude/skills/` | 在此存储库中工作的任何人 | | 插件 | 与[插件]捆绑 | 安装了该插件的任何人 | 如果两个 Skills 有相同的名称，较高的行获胜：个人覆盖项目，项目覆盖插件。 [/tab] [/tabs] ## 配置 Skills 本部分涵盖 Skill 文件结构、支持文件、工具限制和分发选项。 ### 编写 SKILL.md `SKILL.md` 文件是 Skill 中唯一必需的文件。它有两部分：顶部的 YAML 元数据（`---` 标记之间的部分）和告诉 Claude 如何使用 Skill 的 Markdown 说明： ```yaml --- name: your-skill-name description: Brief description of what this Skill does and when to use it --- # Your Skill Name ## Instructions Provide clear, step-by-step guidance for Claude. ## Examples Show concrete examples of using this Skill. ``` #### 可用的元数据字段 你可以在 YAML 前置部分中使用以下字段： | 字段 | 必需 | 描述 | | :--------------- | :--- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `name` | 是 | Skill 名称。必须仅使用小写字母、数字和连字符（最多 64 个字符）。应与目录名称匹配。 | | `description` | 是 | Skill 的功能和何时使用它（最多 1024 个字符）。Claude 使用这个来决定何时应用 Skill。 | | `allowed-tools` | 否 | 当此 Skill 活跃时，Claude 可以使用而无需请求权限的工具。支持逗号分隔的值或 YAML 风格的列表。参见[限制工具访问](#restrict-tool-access-with-allowed-tools)。 | | `model` | 否 | 当此 Skill 活跃时使用的[模型](https://docs.claude.com/zh-CN/docs/about-claude/models/overview)（例如，`claude-sonnet-4-20250514`）。默认为对话的模型。 | | `context` | 否 | 设置为`fork` 以在具有自己对话历史的分叉子代理上下文中运行 Skill。 | | `agent` | 否 | 指定当设置`context: fork` 时使用哪个[代理类型](/zh-CN/sub-agents#built-in-subagents)（例如，`Explore`、`Plan`、`general-purpose` 或来自 `.claude/agents/` 的自定义代理名称）。如果未指定，默认为 `general-purpose`。仅在与 `context: fork` 结合时适用。 | | `hooks` | 否 | 定义限定于此 Skill 生命周期的 hooks。支持`PreToolUse`、`PostToolUse` 和 `Stop` 事件。 | | `user-invocable` | 否 | 控制 Skill 是否出现在斜杠命令菜单中。不影响[`Skill` 工具](/zh-CN/slash-commands#skill-tool)或自动发现。默认为 `true`。参见[控制 Skill 可见性](#control-skill-visibility)。 | 有关完整的编写指导，包括验证规则，请参阅[最佳实践指南](https://docs.claude.com/zh-CN/docs/agents-and-tools/agent-skills/best-practices)。 ### 更新或删除 Skill 要更新 Skill，直接编辑其 `SKILL.md` 文件。要删除 Skill，删除其目录。更改立即生效。 ### 使用渐进式披露添加支持文件 Skills 与对话历史、其他 Skills 和你的请求共享 Claude 的上下文窗口。为了保持上下文集中，使用**渐进式披露**：将必要信息放在 `SKILL.md` 中，将详细的参考资料放在 Claude 仅在需要时读取的单独文件中。 这种方法让你可以捆绑全面的文档、示例和脚本，而不会提前消耗上下文。Claude 仅在任务需要时加载其他文件。 <Tip>保持 `SKILL.md` 在 500 行以下以获得最佳性能。如果你的内容超过这个，将详细的参考资料分成单独的文件。</Tip> #### 示例：多文件 Skill 结构 Claude 通过 `SKILL.md` 中的链接发现支持文件。以下示例显示了一个 Skill，其详细文档在单独的文件中，以及 Claude 可以执行而无需读取的实用脚本： ``` my-skill/ ├── SKILL.md (required - overview and navigation) ├── reference.md (detailed API docs - loaded when needed) ├── examples.md (usage examples - loaded when needed) └── scripts/ └── helper.py (utility script - executed, not loaded) ``` `SKILL.md` 文件引用这些支持文件，以便 Claude 知道它们存在： ````markdown ## Overview [Essential instructions here] ## Additional resources - For complete API details, see [reference.md](reference.md) - For usage examples, see [examples.md](examples.md) ## Utility scripts To validate input files, run the helper script. It checks for required fields and returns any validation errors: ```bash python scripts/helper.py input.txt ``` ```` <Tip>保持引用一级深。直接从 `SKILL.md` 链接到参考文件。深层嵌套的引用（文件 A 链接到文件 B，文件 B 链接到文件 C）可能导致 Claude 部分读取文件。</Tip> **为零上下文执行捆绑实用脚本。** 你的 Skill 目录中的脚本可以在不加载其内容到上下文的情况下执行。Claude 运行脚本，只有输出消耗令牌。这对以下情况很有用： * 复杂的验证逻辑，用散文描述会很冗长 * 作为经过测试的代码比生成的代码更可靠的数据处理 * 受益于跨使用一致性的操作 在 `SKILL.md` 中，告诉 Claude 运行脚本而不是读取它： ```markdown Run the validation script to check the form: python scripts/validate_form.py input.pdf ``` 有关构建 Skills 的完整指导，请参阅[最佳实践指南](https://docs.claude.com/zh-CN/docs/agents-and-tools/agent-skills/best-practices#progressive-disclosure-patterns)。 ### 使用 allowed-tools 限制工具访问 使用 `allowed-tools` 前置部分字段来限制当 Skill 活跃时 Claude 可以使用哪些工具。你可以将工具指定为逗号分隔的字符串或 YAML 列表： ```yaml --- name: reading-files-safely description: Read files without making changes. Use when you need read-only file access. allowed-tools: Read, Grep, Glob --- ``` 或使用 YAML 风格的列表以获得更好的可读性： ```yaml --- name: reading-files-safely description: Read files without making changes. Use when you need read-only file access. allowed-tools: - Read - Grep - Glob --- ``` 当此 Skill 活跃时，Claude 只能使用指定的工具（Read、Grep、Glob）而无需请求权限。这对以下情况很有用： * 不应修改文件的只读 Skills * 范围有限的 Skills：例如，仅数据分析，无文件写入 * 你想限制功能的安全敏感工作流 如果省略 `allowed-tools`，Skill 不会限制工具。Claude 使用其标准权限模型，可能会要求你批准工具使用。 <Note> `allowed-tools` 仅在 Claude Code 中的 Skills 支持。 </Note> ### 在分叉上下文中运行 Skills 使用 `context: fork` 在具有自己对话历史的隔离子代理上下文中运行 Skill。这对于执行复杂的多步骤操作而不会使主对话混乱的 Skills 很有用： ```yaml --- name: code-analysis description: Analyze code quality and generate detailed reports context: fork --- ``` ### 为 Skills 定义 Hooks Skills 可以定义在 Skill 生命周期期间运行的 hooks。使用 `hooks` 字段指定 `PreToolUse`、`PostToolUse` 或 `Stop` 处理程序： ```yaml --- name: secure-operations description: Perform operations with additional security checks hooks: PreToolUse: - matcher: "Bash" hooks: - type: command command: "./scripts/security-check.sh $TOOL_INPUT" once: true --- ``` `once: true` 选项每个会话仅运行一次 hook。在第一次成功执行后，hook 被删除。 在 Skill 中定义的 Hooks 限定于该 Skill 的执行，并在 Skill 完成时自动清理。 有关完整的 hook 配置格式，请参阅[Hooks](/zh-CN/hooks)。 ### 控制 Skill 可见性 Skills 可以通过三种方式调用： 1. **手动调用**：你在提示中输入 `/skill-name` 2. **程序调用**：Claude 通过[`Skill` 工具](/zh-CN/slash-commands#skill-tool)调用它 3. **自动发现**：Claude 读取 Skill 的描述并在与对话相关时加载它 `user-invocable` 字段仅控制手动调用。当设置为 `false` 时，Skill 从斜杠命令菜单中隐藏，但 Claude 仍然可以通过程序调用或自动发现它。 要通过 `Skill` 工具阻止程序调用，请改用 `disable-model-invocation: true`。 #### 何时使用每个设置 | 设置 | 斜杠菜单 | `Skill` 工具 | 自动发现 | 用例 | | :------------------------------- | :------- | :----------- | :------- | :------------------------------------------------ | | `user-invocable: true`（默认） | 可见 | 允许 | 是 | 你想让用户直接调用的 Skills | | `user-invocable: false` | 隐藏 | 允许 | 是 | Claude 可以使用但用户不应手动调用的 Skills | | `disable-model-invocation: true` | 可见 | 阻止 | 是 | 你想让用户调用但 Claude 不能通过程序调用的 Skills | #### 示例：仅模型 Skill 设置 `user-invocable: false` 以从斜杠菜单中隐藏 Skill，同时仍然允许 Claude 通过程序调用它： ```yaml --- name: internal-review-standards description: Apply internal code review standards when reviewing pull requests user-invocable: false --- ``` 使用此设置，用户不会在 `/` 菜单中看到 Skill，但 Claude 仍然可以通过 `Skill` 工具调用它或根据上下文自动发现它。 ### Skills 和子代理 Skills 和子代理可以通过两种方式协同工作： #### 给子代理访问 Skills [子代理](/zh-CN/sub-agents)不会自动从主对话继承 Skills。要给自定义子代理访问特定 Skills，在子代理的 `skills` 字段中列出它们： ```yaml # .claude/agents/code-reviewer.md --- name: code-reviewer description: Review code for quality and best practices skills: pr-review, security-check --- ``` 列出的 Skills 在子代理启动时加载到其上下文中。如果省略 `skills` 字段，则不会为该子代理预加载任何 Skills。 <Note> 内置代理（Explore、Plan、general-purpose）无法访问你的 Skills。只有你在 `.claude/agents/` 中定义的具有显式 `skills` 字段的自定义子代理可以使用 Skills。 </Note> #### 在子代理上下文中运行 Skill 使用 `context: fork` 和 `agent` 在具有自己单独上下文的分叉子代理中运行 Skill。有关详细信息，请参阅[在分叉上下文中运行 Skills](#run-skills-in-a-forked-context)。 ### 分发 Skills 你可以通过多种方式共享 Skills： * **项目 Skills**：将 `.claude/skills/` 提交到版本控制。任何克隆存储库的人都会获得 Skills。 * **插件**：要在多个存储库中共享 Skills，在你的[插件](/zh-CN/plugins)中创建一个 `skills/` 目录，其中包含包含 `SKILL.md` 文件的 Skill 文件夹。通过[插件市场](/zh-CN/plugin-marketplaces)分发。 * **托管**：管理员可以通过[托管设置](/zh-CN/iam#managed-settings)在组织范围内部署 Skills。有关托管 Skill 路径，请参阅[Skills 存放在哪里](#where-skills-live)。 ## 示例 这些示例展示了常见的 Skill 模式，从最小的单文件 Skills 到具有支持文档和脚本的多文件 Skills。 ### 简单 Skill（单文件） 最小的 Skill 仅需要一个带有前置部分和说明的 `SKILL.md` 文件。这个例子通过检查暂存的更改来帮助 Claude 生成提交消息： ``` commit-helper/ └── SKILL.md ``` ```yaml --- name: generating-commit-messages description: Generates clear commit messages from git diffs. Use when writing commit messages or reviewing staged changes. --- # Generating Commit Messages ## Instructions 1. Run `git diff --staged` to see changes 2. I'll suggest a commit message with: - Summary under 50 characters - Detailed description - Affected components ## Best practices - Use present tense - Explain what and why, not how ``` ### 使用多个文件 对于复杂的 Skills，使用渐进式披露来保持主 `SKILL.md` 集中，同时在支持文件中提供详细文档。这个 PDF 处理 Skill 包括参考文档、实用脚本，并使用 `allowed-tools` 将 Claude 限制为特定工具： ``` pdf-processing/ ├── SKILL.md # Overview and quick start ├── FORMS.md # Form field mappings and filling instructions ├── REFERENCE.md # API details for pypdf and pdfplumber └── scripts/ ├── fill_form.py # Utility to populate form fields └── validate.py # Checks PDFs for required fields ``` **`SKILL.md`**: ````yaml --- name: pdf-processing description: Extract text, fill forms, merge PDFs. Use when working with PDF files, forms, or document extraction. Requires pypdf and pdfplumber packages. allowed-tools: Read, Bash(python:*) --- # PDF Processing ## Quick start Extract text: ```python import pdfplumber with pdfplumber.open("doc.pdf") as pdf: text = pdf.pages[0].extract_text() ``` For form filling, see [FORMS.md](FORMS.md). For detailed API reference, see [REFERENCE.md](REFERENCE.md). ## Requirements Packages must be installed in your environment: ```bash pip install pypdf pdfplumber ``` ```` <Note> 如果你的 Skill 需要外部包，在描述中列出它们。在 Claude 可以使用它们之前，必须在你的环境中安装包。 </Note> Loading... agent skill ： 简化说法：给llm的‘说明文档’ ```mindmap - Agent Skill 概念 - 定义：LLM可随时查阅的说明文档 - 功能：简化重复性任务指令，提升任务AI表现 - 应用场景：智能客服、会议总结等 - Agent Skill 基础使用 - 创建步骤 - 指定文件夹创建agent skill - 标记skill.md文件，定义名称、描述、指令 - 使用流程 - 用户请求 - Cloud Code识别并询问使用agent skill - 加载完整skill.md内容 - 模型响应 - 高级功能 - Reference - Script - 渐进式披漏机制 - Agent Skill 与 MCP对比 ``` ## Agent Skill 的核心概念 Agent Skill 本质是大模型可随时调用的说明文档，其核心价值在于 “简化重复性任务指令”—— 通过预定义的规则与流程，帮助 AI 更高效地完成标准化工作，典型应用场景包括智能客服（快速匹配应答话术）、会议总结（自动梳理内容框架）等。 在Claude中Skill 是一个 markdown 文件，它教 Claude 如何做特定的事情：使用你的团队标准审查 PR、以你喜欢的格式生成提交消息，或查询你公司的数据库架构。当你要求 Claude 做与 Skill 目的相匹配的事情时，Claude 会自动应用它。 ## 创建第一个 Skill <div class="tab-container post_tab box-shadow-wrap-lg"> <ul class="nav no-padder b-b scroll-hide" role="tablist"> <li class='nav-item active' role="presentation"><a class='nav-link active' style="" data-toggle="tab" aria-controls='tabs-606d6a0cf86d28f1f22adbb40b5f2d88190' role="tab" data-target='#tabs-606d6a0cf86d28f1f22adbb40b5f2d88190'>检查可用的 Skills</a></li><li class='nav-item ' role="presentation"><a class='nav-link ' style="" data-toggle="tab" aria-controls='tabs-80cec719f28ea3db1e81c80dea2fe2aa751' role="tab" data-target='#tabs-80cec719f28ea3db1e81c80dea2fe2aa751'>创建 Skill 目录</a></li><li class='nav-item ' role="presentation"><a class='nav-link ' style="" data-toggle="tab" aria-controls='tabs-79925bedb0eae4425fd27bddc3be0020752' role="tab" data-target='#tabs-79925bedb0eae4425fd27bddc3be0020752'>编写 SKILL.md</a></li><li class='nav-item ' role="presentation"><a class='nav-link ' style="" data-toggle="tab" aria-controls='tabs-55dddf563c7cef9ba54f340442d2b36813' role="tab" data-target='#tabs-55dddf563c7cef9ba54f340442d2b36813'>加载并验证 Skill</a></li><li class='nav-item ' role="presentation"><a class='nav-link ' style="" data-toggle="tab" aria-controls='tabs-1438b84d5267096ee1297dc25bb139ee1004' role="tab" data-target='#tabs-1438b84d5267096ee1297dc25bb139ee1004'>测试 Skill</a></li><li class='nav-item ' role="presentation"><a class='nav-link ' style="" data-toggle="tab" aria-controls='tabs-326ffd5ca41b0169acf1e2899e720de9715' role="tab" data-target='#tabs-326ffd5ca41b0169acf1e2899e720de9715'>Skills 存放</a></li> </ul> <div class="tab-content no-border"> <div role="tabpanel" id='tabs-606d6a0cf86d28f1f22adbb40b5f2d88190' class="tab-pane fade active in"> 在创建 Skill 之前，查看 Claude 已经可以访问的 Skills：`What Skills are available?` Claude 将列出当前加载的任何 Skills。你可能看不到任何，或者你可能看到来自插件或你的组织的 Skills。 </div><div role="tabpanel" id='tabs-80cec719f28ea3db1e81c80dea2fe2aa751' class="tab-pane fade "> 在你的个人 Skills 文件夹中为 Skill 创建一个目录。个人 Skills 在你的所有项目中都可用。（你也可以在 `.claude/skills/` 中创建项目 Skills以与团队共享。） ```bash theme={null} mkdir -p ~/.claude/skills/explaining-code ``` </div><div role="tabpanel" id='tabs-79925bedb0eae4425fd27bddc3be0020752' class="tab-pane fade "> 每个 Skill 都需要一个 `SKILL.md` 文件。该文件以 `---` 标记之间的 YAML 元数据开始，必须包含 `name` 和 `description`，然后是 Claude 在 Skill 活跃时遵循的 Markdown 说明。`description` 特别重要，因为 Claude 使用它来决定何时应用 Skill。创建 `~/.claude/skills/explaining-code/SKILL.md`： ``` --- name: explaining-code description: Explains code with visual diagrams and analogies. Use when explaining how code works, teaching about a codebase, or when the user asks "how does this work?" --- When explaining code, always include: 1. **Start with an analogy**: Compare the code to something from everyday life 2. **Draw a diagram**: Use ASCII art to show the flow, structure, or relationships 3. **Walk through the code**: Explain step-by-step what happens 4. **Highlight a gotcha**: What's a common mistake or misconception? Keep explanations conversational. For complex concepts, use multiple analogies. ``` </div><div role="tabpanel" id='tabs-55dddf563c7cef9ba54f340442d2b36813' class="tab-pane fade "> Skills 在创建或修改时会自动加载。验证 Skill 出现在列表中： ``` What Skills are available? ``` </div><div role="tabpanel" id='tabs-1438b84d5267096ee1297dc25bb139ee1004' class="tab-pane fade "> 打开你项目中的任何文件，并向 Claude 提出与 Skill 描述相匹配的问题： ``` How does this code work? ``` Claude 应该要求使用 `explaining-code` Skill，然后在其解释中包含一个类比和 ASCII 图表。如果 Skill 没有触发，请尝试重新表述以包含描述中的更多关键词，例如”explain how this works”。 </div><div role="tabpanel" id='tabs-326ffd5ca41b0169acf1e2899e720de9715' class="tab-pane fade "> 存储 Skill 的位置决定了谁可以使用它： | 位置 | 路径 | 适用于 | | :--- | :------------------ | :----------------------- | | 个人 | `~/.claude/skills/` | 你，跨所有项目 | | 项目 | `.claude/skills/` | 在此存储库中工作的任何人 | | 插件 | 与[插件]捆绑 | 安装了该插件的任何人 | 如果两个 Skills 有相同的名称，较高的行获胜：个人覆盖项目，项目覆盖插件。 </div> </div> </div> ## 配置 Skills 本部分涵盖 Skill 文件结构、支持文件、工具限制和分发选项。 ### 编写 SKILL.md `SKILL.md` 文件是 Skill 中唯一必需的文件。它有两部分：顶部的 YAML 元数据（`---` 标记之间的部分）和告诉 Claude 如何使用 Skill 的 Markdown 说明： ```yaml --- name: your-skill-name description: Brief description of what this Skill does and when to use it --- # Your Skill Name ## Instructions Provide clear, step-by-step guidance for Claude. ## Examples Show concrete examples of using this Skill. ``` #### 可用的元数据字段 你可以在 YAML 前置部分中使用以下字段： | 字段 | 必需 | 描述 | | :--------------- | :--- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `name` | 是 | Skill 名称。必须仅使用小写字母、数字和连字符（最多 64 个字符）。应与目录名称匹配。 | | `description` | 是 | Skill 的功能和何时使用它（最多 1024 个字符）。Claude 使用这个来决定何时应用 Skill。 | | `allowed-tools` | 否 | 当此 Skill 活跃时，Claude 可以使用而无需请求权限的工具。支持逗号分隔的值或 YAML 风格的列表。参见[限制工具访问](#restrict-tool-access-with-allowed-tools)。 | | `model` | 否 | 当此 Skill 活跃时使用的[模型](https://docs.claude.com/zh-CN/docs/about-claude/models/overview)（例如，`claude-sonnet-4-20250514`）。默认为对话的模型。 | | `context` | 否 | 设置为`fork` 以在具有自己对话历史的分叉子代理上下文中运行 Skill。 | | `agent` | 否 | 指定当设置`context: fork` 时使用哪个[代理类型](/zh-CN/sub-agents#built-in-subagents)（例如，`Explore`、`Plan`、`general-purpose` 或来自 `.claude/agents/` 的自定义代理名称）。如果未指定，默认为 `general-purpose`。仅在与 `context: fork` 结合时适用。 | | `hooks` | 否 | 定义限定于此 Skill 生命周期的 hooks。支持`PreToolUse`、`PostToolUse` 和 `Stop` 事件。 | | `user-invocable` | 否 | 控制 Skill 是否出现在斜杠命令菜单中。不影响[`Skill` 工具](/zh-CN/slash-commands#skill-tool)或自动发现。默认为 `true`。参见[控制 Skill 可见性](#control-skill-visibility)。 | 有关完整的编写指导，包括验证规则，请参阅[最佳实践指南](https://docs.claude.com/zh-CN/docs/agents-and-tools/agent-skills/best-practices)。 ### 更新或删除 Skill 要更新 Skill，直接编辑其 `SKILL.md` 文件。要删除 Skill，删除其目录。更改立即生效。 ### 使用渐进式披露添加支持文件 Skills 与对话历史、其他 Skills 和你的请求共享 Claude 的上下文窗口。为了保持上下文集中，使用**渐进式披露**：将必要信息放在 `SKILL.md` 中，将详细的参考资料放在 Claude 仅在需要时读取的单独文件中。 这种方法让你可以捆绑全面的文档、示例和脚本，而不会提前消耗上下文。Claude 仅在任务需要时加载其他文件。 <Tip>保持 `SKILL.md` 在 500 行以下以获得最佳性能。如果你的内容超过这个，将详细的参考资料分成单独的文件。</Tip> #### 示例：多文件 Skill 结构 Claude 通过 `SKILL.md` 中的链接发现支持文件。以下示例显示了一个 Skill，其详细文档在单独的文件中，以及 Claude 可以执行而无需读取的实用脚本： ``` my-skill/ ├── SKILL.md (required - overview and navigation) ├── reference.md (detailed API docs - loaded when needed) ├── examples.md (usage examples - loaded when needed) └── scripts/ └── helper.py (utility script - executed, not loaded) ``` `SKILL.md` 文件引用这些支持文件，以便 Claude 知道它们存在： ````markdown ## Overview [Essential instructions here] ## Additional resources - For complete API details, see [reference.md](reference.md) - For usage examples, see [examples.md](examples.md) ## Utility scripts To validate input files, run the helper script. It checks for required fields and returns any validation errors: ```bash python scripts/helper.py input.txt ``` ```` <Tip>保持引用一级深。直接从 `SKILL.md` 链接到参考文件。深层嵌套的引用（文件 A 链接到文件 B，文件 B 链接到文件 C）可能导致 Claude 部分读取文件。</Tip> **为零上下文执行捆绑实用脚本。** 你的 Skill 目录中的脚本可以在不加载其内容到上下文的情况下执行。Claude 运行脚本，只有输出消耗令牌。这对以下情况很有用： * 复杂的验证逻辑，用散文描述会很冗长 * 作为经过测试的代码比生成的代码更可靠的数据处理 * 受益于跨使用一致性的操作 在 `SKILL.md` 中，告诉 Claude 运行脚本而不是读取它： ```markdown Run the validation script to check the form: python scripts/validate_form.py input.pdf ``` 有关构建 Skills 的完整指导，请参阅[最佳实践指南](https://docs.claude.com/zh-CN/docs/agents-and-tools/agent-skills/best-practices#progressive-disclosure-patterns)。 ### 使用 allowed-tools 限制工具访问 使用 `allowed-tools` 前置部分字段来限制当 Skill 活跃时 Claude 可以使用哪些工具。你可以将工具指定为逗号分隔的字符串或 YAML 列表： ```yaml --- name: reading-files-safely description: Read files without making changes. Use when you need read-only file access. allowed-tools: Read, Grep, Glob --- ``` 或使用 YAML 风格的列表以获得更好的可读性： ```yaml --- name: reading-files-safely description: Read files without making changes. Use when you need read-only file access. allowed-tools: - Read - Grep - Glob --- ``` 当此 Skill 活跃时，Claude 只能使用指定的工具（Read、Grep、Glob）而无需请求权限。这对以下情况很有用： * 不应修改文件的只读 Skills * 范围有限的 Skills：例如，仅数据分析，无文件写入 * 你想限制功能的安全敏感工作流 如果省略 `allowed-tools`，Skill 不会限制工具。Claude 使用其标准权限模型，可能会要求你批准工具使用。 <Note> `allowed-tools` 仅在 Claude Code 中的 Skills 支持。 </Note> ### 在分叉上下文中运行 Skills 使用 `context: fork` 在具有自己对话历史的隔离子代理上下文中运行 Skill。这对于执行复杂的多步骤操作而不会使主对话混乱的 Skills 很有用： ```yaml --- name: code-analysis description: Analyze code quality and generate detailed reports context: fork --- ``` ### 为 Skills 定义 Hooks Skills 可以定义在 Skill 生命周期期间运行的 hooks。使用 `hooks` 字段指定 `PreToolUse`、`PostToolUse` 或 `Stop` 处理程序： ```yaml --- name: secure-operations description: Perform operations with additional security checks hooks: PreToolUse: - matcher: "Bash" hooks: - type: command command: "./scripts/security-check.sh $TOOL_INPUT" once: true --- ``` `once: true` 选项每个会话仅运行一次 hook。在第一次成功执行后，hook 被删除。 在 Skill 中定义的 Hooks 限定于该 Skill 的执行，并在 Skill 完成时自动清理。 有关完整的 hook 配置格式，请参阅[Hooks](/zh-CN/hooks)。 ### 控制 Skill 可见性 Skills 可以通过三种方式调用： 1. **手动调用**：你在提示中输入 `/skill-name` 2. **程序调用**：Claude 通过[`Skill` 工具](/zh-CN/slash-commands#skill-tool)调用它 3. **自动发现**：Claude 读取 Skill 的描述并在与对话相关时加载它 `user-invocable` 字段仅控制手动调用。当设置为 `false` 时，Skill 从斜杠命令菜单中隐藏，但 Claude 仍然可以通过程序调用或自动发现它。 要通过 `Skill` 工具阻止程序调用，请改用 `disable-model-invocation: true`。 #### 何时使用每个设置 | 设置 | 斜杠菜单 | `Skill` 工具 | 自动发现 | 用例 | | :------------------------------- | :------- | :----------- | :------- | :------------------------------------------------ | | `user-invocable: true`（默认） | 可见 | 允许 | 是 | 你想让用户直接调用的 Skills | | `user-invocable: false` | 隐藏 | 允许 | 是 | Claude 可以使用但用户不应手动调用的 Skills | | `disable-model-invocation: true` | 可见 | 阻止 | 是 | 你想让用户调用但 Claude 不能通过程序调用的 Skills | #### 示例：仅模型 Skill 设置 `user-invocable: false` 以从斜杠菜单中隐藏 Skill，同时仍然允许 Claude 通过程序调用它： ```yaml --- name: internal-review-standards description: Apply internal code review standards when reviewing pull requests user-invocable: false --- ``` 使用此设置，用户不会在 `/` 菜单中看到 Skill，但 Claude 仍然可以通过 `Skill` 工具调用它或根据上下文自动发现它。 ### Skills 和子代理 Skills 和子代理可以通过两种方式协同工作： #### 给子代理访问 Skills [子代理](/zh-CN/sub-agents)不会自动从主对话继承 Skills。要给自定义子代理访问特定 Skills，在子代理的 `skills` 字段中列出它们： ```yaml # .claude/agents/code-reviewer.md --- name: code-reviewer description: Review code for quality and best practices skills: pr-review, security-check --- ``` 列出的 Skills 在子代理启动时加载到其上下文中。如果省略 `skills` 字段，则不会为该子代理预加载任何 Skills。 <Note> 内置代理（Explore、Plan、general-purpose）无法访问你的 Skills。只有你在 `.claude/agents/` 中定义的具有显式 `skills` 字段的自定义子代理可以使用 Skills。 </Note> #### 在子代理上下文中运行 Skill 使用 `context: fork` 和 `agent` 在具有自己单独上下文的分叉子代理中运行 Skill。有关详细信息，请参阅[在分叉上下文中运行 Skills](#run-skills-in-a-forked-context)。 ### 分发 Skills 你可以通过多种方式共享 Skills： * **项目 Skills**：将 `.claude/skills/` 提交到版本控制。任何克隆存储库的人都会获得 Skills。 * **插件**：要在多个存储库中共享 Skills，在你的[插件](/zh-CN/plugins)中创建一个 `skills/` 目录，其中包含包含 `SKILL.md` 文件的 Skill 文件夹。通过[插件市场](/zh-CN/plugin-marketplaces)分发。 * **托管**：管理员可以通过[托管设置](/zh-CN/iam#managed-settings)在组织范围内部署 Skills。有关托管 Skill 路径，请参阅[Skills 存放在哪里](#where-skills-live)。 ## 示例 这些示例展示了常见的 Skill 模式，从最小的单文件 Skills 到具有支持文档和脚本的多文件 Skills。 ### 简单 Skill（单文件） 最小的 Skill 仅需要一个带有前置部分和说明的 `SKILL.md` 文件。这个例子通过检查暂存的更改来帮助 Claude 生成提交消息： ``` commit-helper/ └── SKILL.md ``` ```yaml --- name: generating-commit-messages description: Generates clear commit messages from git diffs. Use when writing commit messages or reviewing staged changes. --- # Generating Commit Messages ## Instructions 1. Run `git diff --staged` to see changes 2. I'll suggest a commit message with: - Summary under 50 characters - Detailed description - Affected components ## Best practices - Use present tense - Explain what and why, not how ``` ### 使用多个文件 对于复杂的 Skills，使用渐进式披露来保持主 `SKILL.md` 集中，同时在支持文件中提供详细文档。这个 PDF 处理 Skill 包括参考文档、实用脚本，并使用 `allowed-tools` 将 Claude 限制为特定工具： ``` pdf-processing/ ├── SKILL.md # Overview and quick start ├── FORMS.md # Form field mappings and filling instructions ├── REFERENCE.md # API details for pypdf and pdfplumber └── scripts/ ├── fill_form.py # Utility to populate form fields └── validate.py # Checks PDFs for required fields ``` **`SKILL.md`**: ````yaml --- name: pdf-processing description: Extract text, fill forms, merge PDFs. Use when working with PDF files, forms, or document extraction. Requires pypdf and pdfplumber packages. allowed-tools: Read, Bash(python:*) --- # PDF Processing ## Quick start Extract text: ```python import pdfplumber with pdfplumber.open("doc.pdf") as pdf: text = pdf.pages[0].extract_text() ``` For form filling, see [FORMS.md](FORMS.md). For detailed API reference, see [REFERENCE.md](REFERENCE.md). ## Requirements Packages must be installed in your environment: ```bash pip install pypdf pdfplumber ``` ```` <Note> 如果你的 Skill 需要外部包，在描述中列出它们。在 Claude 可以使用它们之前，必须在你的环境中安装包。 </Note> 最后修改：2026 年 01 月 09 日 © 允许规范转载 赞 2 如果觉得我的文章对你有用，请随意赞赏