跳转到主要内容

文档索引

获取完整的文档索引：https://agentskills.ac.cn/llms.txt

在进一步探索之前，使用此文件可以发现所有可用页面。

​
目录结构

一个技能是一个至少包含 SKILL.md 文件的目录 
skill-name/
├── SKILL.md          # Required: metadata + instructions
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation
├── assets/           # Optional: templates, resources
└── ...               # Any additional files or directories

​
SKILL.md 格式

SKILL.md 文件必须包含 YAML frontmatter，后跟 Markdown 内容。

​
Frontmatter

字段必填约束
name是最多 64 个字符。仅限小写字母、数字和连字符（-）。不能以连字符开头或结尾。
description是最多 1024 个字符。不能为空。描述技能的作用以及何时使用它。
license否许可证名称或对附带的许可证文件的引用。
compatibility否最多 500 个字符。指示环境要求（目标产品、系统软件包、网络访问等）。
metadata否用于附加元数据的任意键值映射。
allowed-tools否以空格分隔的字符串，表示该技能可以使用的预批准工具。（实验性）

极简示例
SKILL.md
---
name: skill-name
description: A description of what this skill does and when to use it.
---
包含可选字段的示例
SKILL.md
---
name: pdf-processing
description: Extract PDF text, fill forms, merge files. Use when handling PDFs.
license: Apache-2.0
metadata:
  author: example-org
  version: "1.0"
---

​
name 字段

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

有效示例
name: pdf-processing

name: data-analysis

name: code-review
无效示例
name: PDF-Processing  # uppercase not allowed

name: -pdf  # cannot start with hyphen

name: pdf--processing  # consecutive hyphens not allowed

​
description 字段

必填的 description 字段
  • 必须为 1-1024 个字符
  • 应该同时描述技能的作用以及何时使用它
  • 应该包含特定的关键词，以帮助 Agent 识别相关任务

推荐示例
description: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction.
不佳示例
description: Helps with PDFs.

​
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: Requires Python 3.14+ and uv
大多数技能不需要 compatibility 字段。

​
metadata 字段

可选的 metadata 字段
  • 从字符串键到字符串值的映射
  • 客户端可以使用此字段来存储 Agent 技能规范中未定义的其他属性
  • 我们建议使您的键名具有合理的唯一性，以避免意外冲突

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

​
allowed-tools 字段

可选的 allowed-tools 字段
  • 以空格分隔的、预先批准运行的工具字符串
  • 实验性功能。不同 Agent 实现对该字段的支持可能有所不同

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

​
正文内容

Frontmatter 之后的 Markdown 正文包含技能说明。没有格式限制。可以编写任何有助于 Agent 有效执行任务的内容。 推荐章节：
  • 分步说明
  • 输入和输出示例
  • 常见边缘情况
请注意，一旦 Agent 决定激活某项技能，它就会加载这整个文件。考虑将较长的 SKILL.md 内容拆分到被引用的文件中。

​
可选目录

​
scripts/

包含 Agent 可以运行的可执行代码。脚本应该：
  • 自包含或清晰地记录依赖项
  • 包含有用的错误信息
  • 优雅地处理边缘情况
支持的语言取决于 Agent 的实现。常见选项包括 Python、Bash 和 JavaScript。

​
references/

包含 Agent 在需要时可以阅读的附加文档
  • REFERENCE.md - 详细的技术参考
  • FORMS.md - 表单模板或结构化数据格式
  • 特定领域的文档（finance.md、legal.md 等）
保持每个独立的参考文件重点突出。Agent 会按需加载这些文件，因此文件越小意味着占用的上下文越少。

​
assets/

包含静态资源
  • 模板（文档模板、配置模板）
  • 图片（图表、示例）
  • 数据文件（查找表、Schema 模式）

​
渐进式加载

Agent 会渐进式地加载技能，仅在任务需要时才拉取更多细节。技能的结构应该充分利用这一特性
  1. 元数据（约 100 个 token）：所有技能的 name 和 description 字段都会在启动时加载
  2. 说明（建议小于 5000 个 token）：激活技能时，会加载完整的 SKILL.md 正文
  3. 资源（按需）：只有在需要时，才会加载文件（例如 scripts/、references/ 或 assets/ 中的文件）
保持主 SKILL.md 在 500 行以内。将详细的参考资料移至单独的文件中。

​
文件引用

在技能中引用其他文件时，请使用相对于技能根目录的相对路径
SKILL.md
See [the reference guide](references/REFERENCE.md) for details.

Run the extraction script:
scripts/extract.py
保持文件引用与 SKILL.md 只有一级深度。避免深度嵌套的引用链。

​
校验

使用 skills-ref 参考库来验证您的技能 
skills-ref validate ./my-skill
这将检查您的 SKILL.md frontmatter 是否有效，并且是否遵循了所有命名规范。