在 AI 工具生态日益丰富的今天，Claude Code 的 Skills 功能为开发者提供了定制化扩展能力 —— 通过编写轻量化技能模块，可快速集成特定场景需求（如数据处理、文档生成、API 联动等），让终端交互更贴合个性化工作流。 然而，缺乏统一的编写规范易导致 Skills 兼容性不足、调用失效、协作成本高等问题，影响功能落地效率。本文将系统梳理 Claude Skills 的核心编写准则，涵盖文件结构、语法规范、权限控制、兼容性设计等关键维度，帮助开发者快速掌握标准化编写方法，打造高效、稳定、可复用的技能模块，充分释放 Claude Code 的扩展潜力。

目录结构

一个skill对应一个目录，至少包含一个 SKILL.md 文件：

skill-name/
└── SKILL.md          # 必需

您可以选择性地包含其他目录，例如 scripts/、references/ 和 assets/ 来支持您的skill。

SKILL.md 格式

SKILL.md 文件必须包含 YAML 前置元数据（frontmatter），后跟 Markdown 内容。

描述元数据（必需）

---
name: skill-name
description: 描述此技能的用途及使用场景。
---

可选字段：

---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge documents.
license: Apache-2.0
metadata:
  author: example-org
  version: "1.0"
---

字段	必需	约束条件
name	是	最多 64 个字符。仅包含小写字母、数字和连字符。不能以连字符开头或结尾。
description	是	最多 1024 个字符。非空。描述技能的功能和使用场景。
license	否	许可证名称或指向打包许可证文件的引用。
compatibility	否	最多 500 个字符。表示环境要求（目标产品、系统包、网络访问等）。
metadata	否	任意键值对，用于存储附加元数据。
allowed-tools	否	空格分隔的预批准工具列表，技能可使用这些工具。（实验性功能）

name 字段

必需的 name 字段：

• 必须为 1-64 个字符
• 只能包含 Unicode 小写字母数字字符和连字符（a-z 和 -）
• 不能以 - 开头或结尾
• 不能包含连续连字符（--）
• 必须与父目录名称匹配

有效示例：

name: pdf-processing

name: data-analysis

name: code-review

无效示例：

name: PDF-Processing  # 不允许大写

name: -pdf  # 不能以连字符开头

name: pdf--processing  # 不允许连续连字符

description 字段

必需的 description 字段：

• 必须为 1-1024 个字符
• 应描述技能的功能和使用场景
• 应包含特定的关键词，帮助Agent识别相关任务

良好示例：

description: 从 PDF 文件中提取文本和表格，填充 PDF 表单，并合并多个 PDF。在处理 PDF 文档或用户提及 PDF、表单或文档提取时使用。

不佳示例：

description: 帮助处理 PDF。

license 字段

可选的 license 字段：

• 指定应用于该技能的许可证
• 建议保持简短（许可证名称或打包许可证文件的名称）

示例：

license: Proprietary. LICENSE.txt has complete terms

compatibility 字段

可选的 compatibility 字段：

• 如果提供，必须为 1-500 个字符
• 仅在技能有特定环境要求时才应包含
• 可指示目标产品、必需的系统包、网络访问需求等

示例：

compatibility: Designed for Claude Code (or similar products)

compatibility: Requires git, docker, jq, and access to the internet

大多数技能不需要 compatibility 字段。

metadata 字段

可选的 metadata 字段：

• 字符串键到字符串值的映射
• 客户端可用它来存储 Agent Skills 规范中未定义的附加属性
• 建议使用相对唯一的键名以避免意外冲突

示例：

metadata:
  author: example-org
  version: "1.0"

allowed-tools 字段

可选的 allowed-tools 字段：

• 空格分隔的预批准工具列表
• 实验性功能。不同Agent实现对此字段的支持可能不同

示例：

allowed-tools: Bash(git:*) Bash(jq:*) Read

主体内容

描述元数据之后的 Markdown 主体包含技能指令。没有格式限制，编写任何有助于Agent有效完成任务的内容。

建议包含的章节：

• 分步说明
• 输入和输出示例
• 常见边缘情况

请注意，一旦Agent决定激活某个技能，它会加载整个文件。考虑将较长的 SKILL.md 内容拆分为引用文件。

可选目录

scripts/

包含智能体可执行运行的代码。脚本应该：

• 自包含或明确记录依赖项
• 包含有用的错误消息
• 优雅地处理边缘情况

支持的程序语言取决于Agent实现。常见选项包括 Python、Bash 和 JavaScript。

references/

包含智能体在需要时可以读取的附加文档：

• REFERENCE.md - 详细技术参考
• FORMS.md - 表单模板或结构化数据格式
• 特定领域文件（finance.md、legal.md 等）

保持单个参考文件专注于特定主题。智能体按需加载这些文件，因此较小的文件意味着更少的上下文使用。

assets/

包含静态资源：

• 模板（文档模板、配置模板）
• 图片（图表、示例）
• 数据文件（查找表、模式）

渐进式披露

Skill应针对高效的上下文使用进行结构化：

1. 元数据（约 100 个tokens）：启动时加载所有技能的 name 和 description 字段
2. 说明（建议少于 5000 个tokens）：激活技能时加载完整的 SKILL.md 主体
3. 资源（按需）：文件（如 scripts/、references/ 或 assets/ 中的文件）仅在需要时加载

保持主 SKILL.md 少于 500 行。将详细参考资料移到单独的文件中。

文件引用

引用技能中的其他文件时，使用相对于技能根目录的相对路径：

详细信息请参阅[参考指南](references/REFERENCE.md)。

运行提取脚本：
scripts/extract.py

保持文件引用相对于 SKILL.md 为一级深度。避免深层嵌套的引用链。

验证

使用 skills-ref 参考库来验证您的技能：

skills-ref validate ./my-skill

这将检查您的 SKILL.md 前置元数据是否有效并遵循所有命名规范。