Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

6.4 创建自定义 Skills

当内置 Skills 无法满足特定需求时，就是发挥创造力的时候了。本节将通过三个官方示例，深入讲解如何创建高质量的自定义 Skill。

6.4.1 Agent Skills 的完整解析：SKILL.md 结构与渐进式披露

Agent Skills 是 Anthropic 为了让 Agent 获得专业化能力而设计的机制。一个 Skill 本质上是一个包含 SKILL.md 文件的目录，其中包含了指令、脚本和资源。要创建有效的 Skill，首先要理解 SKILL.md 的完整生命周期。

SKILL.md 的 YAML 前置信息（Frontmatter）

每个 SKILL.md 以 YAML 前置信息开始。在 Claude Code 中，最小可用形态只需 description：

---
description: |
  Comprehensive PDF manipulation including form filling, content extraction,
  and page manipulation. Use this when Claude needs to: (1) Extract text
  from PDF files, (2) Fill out PDF forms, (3) Merge or split PDFs,
  (4) Analyze PDF structure and contents.
---

description（推荐填写）：简洁但完整的概述，帮助 Claude 决定何时使用这个 Skill。description 和可选的 when_to_use 合计在 skill 列表中被截断到 1,536 字符，要把关键用例放最前。

这构成了第一级渐进式披露 ——Claude 在启动时就知道有哪些 Skill 可用，以及大致的用途，但还不需要加载完整的细节。

产品范围：下表为 Claude Code 的 frontmatter 字段，其中大部分（如 when_to_use、context、agent、shell 等）是 Claude Code 对 Agent Skills 开放标准的扩展，仅在 Claude Code 中生效。经 API（/v1/skills）或 claude.ai 上传的 Skill 按平台规范校验：name 与 description 均为必填（name 不超过 64 字符，description 非空且不超过 1024 字符），扩展字段不会生效（参见 6.2.2）。

完整 frontmatter 字段表（按 Claude Code 官方文档）：

字段
用途

name

列表中显示的名称，默认取目录名。/skill-name 调用时仍然使用目录名（plugin 根目录除外）

description

何时使用此 skill

when_to_use

额外的触发场景或示例请求，会追加到 description 后参与 1,536 字符上限

argument-hint

自动补全时显示的参数提示，例如 [issue-number]

arguments

命名位置参数，配合 $name 占位符使用

disable-model-invocation

true 时只允许用户手动 /name 触发，Claude 不会自动加载。同时避免该 skill 被预加载到子代理

user-invocable

false 时只允许 Claude 自动加载，从 / 菜单隐藏

allowed-tools

此 skill 激活时预先批准的工具/命令，例如 Bash(git add *) Bash(git commit *)。它不是工具可见性白名单；其他工具仍可能按全局权限规则进入 ask/deny 流程

disallowed-tools

此 skill 激活时从可用池中移除的工具，例如自动循环中禁用 AskUserQuestion

model

激活时切换的模型（sonnet / opus / haiku / 全名 / inherit），仅本回合生效

effort

推理强度（low / medium / high / xhigh / max），覆盖会话默认

context: fork

在分叉的子代理上下文中执行此 skill；不带此字段时是内联到当前对话

agent

配合 context: fork 选择执行子代理类型（Explore、Plan、general-purpose，或 .claude/agents/ 下自定义的子代理）。省略时用 general-purpose

hooks

绑定到此 skill 生命周期的钩子

paths

Glob 模式，限制此 skill 仅在操作匹配文件时自动激活，例如 *.go,internal/**/*.go

shell

bash（默认）或 powershell，决定内联 shell 注入用哪个解释器

常见误读纠正：agent 字段的取值是子代理 类型名（如 Explore），不是 read-only 这种描述性词汇。“只读”是 Explore 这个内置子代理的特性——它默认拒绝 Write 和 Edit 工具。要让 skill 以只读方式运行，写 context: fork + agent: Explore。

权限误读纠正：allowed-tools 只表示免确认，不表示限制。要在 Skill 激活时移除工具，用 disallowed-tools；要跨所有 Skill 阻止危险工具或路径，用 Claude Code permission deny 规则，并在信任项目前审查 Skill 来源。

内联 Shell 注入：!`command` 语法

SKILL.md 中以 !`command` 形式书写的行，会在 skill 内容送达 Claude 之前被替换为命令的真实输出。这是预处理，不是 Claude 主动执行：

注意点：

  • ! 必须在行首或紧跟空白之后才被识别；KEY=!cmd`` 不会触发

  • 替换只跑一遍，命令输出不会再被扫描第二轮

  • 多行命令用 ```! 围栏代码块代替内联形式

  • 可通过 settings.json 的 "disableSkillShellExecution": true 禁用此能力

渐进式披露的三个层级

Agent Skills 采用了一个精妙的架构来管理上下文：

  1. 层级一：元数据（启动时加载）

    • 所有已安装 Skill 的名称和描述（几百字节）

    • 让 Claude 知道“有哪些工具可用”

    • 触发：应用启动时

  2. 层级二：SKILL.md 的主体（按需加载）

    • 当 Claude 认为某个 Skill 可能相关时，调用 bash 工具读取该 Skill 的完整 SKILL.md

    • 包含详细的使用指南、工作流说明、常见场景

    • 触发：Claude 决定该 Skill 与当前任务有关

  3. 层级三及以上：附加文件（深度按需加载）

    • SKILL.md 中引用的其他文件：reference.md、forms.md、examples.py 等

    • Claude 可以根据进展选择性地读取这些文件

    • 例如：在处理 PDF 表单时才读取 forms.md，而处理文本提取时才读取 text_extraction.md

实例：PDF Skill 的层级结构

当用户要求“从 PDF 中提取表单字段”时：

  1. Claude 读取元数据，发现有“pdf”Skill

  2. Claude 执行 cat pdf/SKILL.md，加载主体内容

  3. Claude 看到 SKILL.md 提到“forms.md 包含表单处理说明”

  4. Claude 执行 cat pdf/forms.md，加载表单特定信息

  5. Claude 可能执行 python pdf/scripts/extract_fields.py，让脚本做低级操作

这种设计的好处：

  • 初始上下文轻量：即使装了 100 个 Skill，启动时也只消耗几 KB token

  • 智能加载：只加载与当前任务相关的细节

  • 灵活性：Skill 可以包含任意大的代码或指令，不受上下文限制

SKILL.md 编写的关键原则

  1. 在 YAML 前置信息中描述“何时”而不仅是“是什么”

不好的写法：

好的写法：

  1. 主体部分应该包含工作流或决策树

不仅仅列举功能，而是提供清晰的“在这种情况下做 X，在那种情况下做 Y”的指导。

  1. 使用引用来分层内容

将不相关的细节移到单独的文件中，保持主 SKILL.md 清洁。例如：

SKILL.md 主体:

  1. 在 SKILL.md 中集成代码示例

融入自 Anthropic 的《Equipping agents for the real world with Agent Skills》中关于 SKILL.md 结构和渐进式披露的设计原则

6.4.2 核心设计原则：自由度与确定性

在编写 Skill 之前，首先要判断任务的属性。Anthropic 的研究员提出了 “自由度（Degrees of Freedom）” 的概念：

  • 高自由度任务（High DoF）：需要创意、适应性或模糊推理。

    • 例如：写一首诗、设计一个网页布局、总结一篇文章。

    • 最佳实现：使用 Markdown 文本指令。告诉 Claude 目标和风格，留出空间让模型发挥。

  • 低自由度任务（Low DoF）：需要精确格式、严密逻辑或零容错。

    • 例如：生成特定 schema 的 JSON、执行数学计算、转换文件格式。

    • 最佳实现：使用 Python 脚本。不要试图用 Prompt 强迫模型去“模拟”计算机的行为，直接给它工具（脚本）。

黄金法则：

如果任务逻辑是“脆弱”的（改一个字就报错），请写代码（Script）；如果任务需要“弹性”（多种结果都可接受），请写 Prompt（Instruction）。

6.4.3 示例一：DOCX 文档处理 Skill

这是 Anthropic 官方 Skills 仓库中的一个经典案例，展示了如何处理复杂的工作流分支。

SKILL.md 文件

设计亮点

  1. 决策树结构：根据任务类型（读取/创建/编辑）路由到不同流程

  2. 渐进式披露：主文件提供概述，详细流程放在独立的 workflow-*.md 文件中

  3. 明确的边界：区分了“自己的文档”和“别人的文档”应使用不同流程

6.4.4 示例二：品牌指南 Skill

这个示例展示了如何封装企业特有的设计规范。

设计亮点

  1. 精确信息：提供 Claude 无法内置的具体数值（十六进制颜色码、字体名称）

  2. 实用主义：不需要复杂逻辑，直接给出可执行的规范

  3. Fallback 策略：考虑到字体可能缺失，提供了备选方案

6.4.5 示例三：前端设计 Skill

这个高级示例展示了如何约束创意输出。

设计亮点

  1. 反面约束：明确列出“不要做什么”，避免生成千篇一律的 AI 风格

  2. 鼓励创意：使用激励性语言（“BOLD”, “UNFORGETTABLE”）引导高质量输出

  3. 思考框架：要求先思考再编码，提升输出的针对性

6.4.6 Description 对比：强 vs 弱

以下是影响 Skill 触发准确性的关键因素：

弱 Description
强 Description

"Helps with PDFs"

"Extract tables from PDFs, merge/split documents, fill forms. Use for batch processing. Not for simple viewing."

"Code review skill"

"Reviews code for OWASP Top 10 vulnerabilities, enforces company style guide, outputs severity-ranked findings table."

"Writing helper"

"Transforms rough notes into polished blog posts following SEO best practices. Outputs markdown with frontmatter."

核心原则：

  • 使用 动词 描述能力（extract, merge, transform）

  • 说明 触发场景（when to use）

  • 划定 边界（not for...）

6.4.7 测试矩阵

创建 Skill 后，使用以下矩阵进行系统测试：

测试类型
示例
期望结果

正常操作

使用 docx skill 创建合同

生成带格式的 .docx 文件

边缘情况

输入只有表格没有文字的文档

正确处理或提示需要补充信息

越界请求

请求 docx skill 分析 PDF

不应触发，提示使用 PDF skill

6.4.8 企业级部署

2025 年 12 月，Anthropic 发布了组织级 Skills 管理功能：

  • 集中管理：管理员可以统一部署、更新、撤回 Skills

  • 版本控制：通过 API 管理 Skill 版本

  • 审计日志：追踪 Skill 的使用情况

部署方式：

  1. 管理员在 claude.ai 的 Organization settings → Skills 上传 Skill（.zip 包，点击 “+ Add”）

  2. 上传后即对组织内全员生效，员工在 Claude.ai 中自动获得访问权限

  3. 注意：通过 API（Console /v1/skills）上传的 Skill 属于 API workspace，不会出现在 claude.ai——两条分发渠道相互独立

现在已经掌握了创建单一 Skill 的能力。在实际工作中，复杂任务往往需要多个 Skills 协同工作。下一节将探讨 Skills 的组合与编排。

➡️ Skills 组合与高级用法

上一页6.3 使用内置 Skills
下一页6.5 Skills 组合与高级用法

最后更新于