agent-skills-spec

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Agent Skills Spec

Agent技能规范

Structural compliance for the agentskills.io specification. For content quality and expertise transfer, use skill-creator-v2 instead.

用于保障agentskills.io规范的结构合规性。如果需要进行内容质量管控和专业知识迁移，请使用skill-creator-v2。

Mental Model

思维模型

A skill is a progressive disclosure pipeline. Each layer has strict constraints:

Layer 1: METADATA (~100 tokens)                    ← always loaded
  name + description in YAML frontmatter
  Must be precise enough for activation decisions

Layer 2: INSTRUCTIONS (<5000 tokens recommended)   ← loaded on activation
  SKILL.md body, <500 lines
  Core workflows, decision frameworks, essential examples

Layer 3: RESOURCES (on demand)                      ← loaded when referenced
  references/*.md, scripts/*, assets/*
  Deep knowledge, executable code, templates

Every spec rule serves this pipeline. Name/description enable discovery. Body enables execution. Resources enable depth without cost.

一个技能就是一条渐进式信息披露流水线，每一层都有严格的约束：

Layer 1: METADATA (~100 tokens)                    ← 始终加载
  name + description in YAML frontmatter
  Must be precise enough for activation decisions

Layer 2: INSTRUCTIONS (<5000 tokens recommended)   ← 激活时加载
  SKILL.md body, <500 lines
  Core workflows, decision frameworks, essential examples

Layer 3: RESOURCES (on demand)                      ← 被引用时加载
  references/*.md, scripts/*, assets/*
  Deep knowledge, executable code, templates

所有规范规则都是为这条流水线服务的：名称和描述用于技能发现，正文用于执行逻辑，资源文件则在不增加额外负载的前提下提供深度支持。

Create Workflow

创建工作流

Create a new spec-compliant skill:

Name: Choose lowercase kebab-case, 1–64 chars
Directory:
```
mkdir -p skill-name/references
```
Frontmatter: Write valid YAML with
```
name
```
+
```
description
```
Body: Core instructions in imperative mood, <500 lines
Split: Move detailed content into
```
references/
```
Scripts: Add to
```
scripts/
```
if needed (see script guidelines)
Validate: Run
```
skills-ref validate ./skill-name
```
or walk through validation checklist

Minimal valid skill:

yaml

---
name: my-skill
description: >
  Extract text from PDFs and fill forms. Use when working with PDF files
  or when the user mentions PDFs, forms, or document extraction.
---

创建符合规范的新技能：

命名：采用小写短横线命名法，长度1-64字符
创建目录：执行
```
mkdir -p skill-name/references
```
填写前置元数据：编写包含
```
name
```
和
```
description
```
字段的有效YAML内容
编写正文：使用祈使语气编写核心说明，行数不超过500行
内容拆分：将详细内容迁移到
```
references/
```
目录下
添加脚本：如有需要将脚本放到
```
scripts/
```
目录下（参考脚本指南）
验证合规性：执行
```
skills-ref validate ./skill-name
```
，或是对照验证清单手动检查

最小有效技能示例：

yaml

---
name: my-skill
description: >
  Extract text from PDFs and fill forms. Use when working with PDF files
  or when the user mentions PDFs, forms, or document extraction.
---

My Skill

[Instructions here]

undefined

[Instructions here]

undefined

Audit Workflow

审计工作流

Audit an existing skill for spec compliance:

Check frontmatter against hard rules (required fields, character limits, naming)
Check for disallowed frontmatter fields (see below)
Verify directory structure (only
```
scripts/
```
,
```
references/
```
,
```
assets/
```
allowed)
Scan for non-standard top-level files (README, LICENSE, CHANGELOG)
Count SKILL.md body lines (<500)
Assess description quality (specific triggers? capability + when?)
Assess progressive disclosure (too much in SKILL.md?)
Check script interfaces if
```
scripts/
```
exists
Report findings with severity + fix recommendations

For the full checklist: see references/validation-checklist.md

审计现有技能的规范合规性：

对照硬性规则检查前置元数据（必填字段、字符限制、命名规范）
检查是否存在不允许的前置元数据字段（见下文）
验证目录结构（仅允许
```
scripts/
```
、
```
references/
```
、
```
assets/
```
三个子目录）
扫描是否存在非标准顶层文件（README、LICENSE、CHANGELOG）
统计SKILL.md正文行数（需<500行）
评估描述质量（是否有明确触发词？是否说明能力和适用场景？）
评估渐进式信息披露合理性（SKILL.md是否包含过多内容？）
如果存在
```
scripts/
```
目录，检查脚本接口是否合规
输出审计结果，标注严重级别和修复建议

完整清单请参考：references/validation-checklist.md

Fix Workflow

修复工作流

Remediate common issues. For the complete decision tree with before/after examples: see references/common-fixes.md

Quick reference:

Issue	Severity	Fix
Non-spec frontmatter fields	Error	Move to `metadata` or remove
Name/directory mismatch	Error	Rename to match
`allowed-tools` as YAML array	Error	Convert to space-delimited string
Interactive prompts in scripts	Error	Replace with CLI flags/stdin
SKILL.md >500 lines	Warning	Split into `references/`
README/LICENSE/CHANGELOG present	Warning	Remove (AI meta-docs)
Non-standard directories ( `rules/` , `templates/` )	Warning	Rename to `references/` / `assets/`
Vague description	Warning	Add specific triggers and "Use when..."
Scripts without `--help`	Info	Add usage documentation

修复常见合规问题。包含前后对比示例的完整决策树请参考：references/common-fixes.md

快速参考：

问题	严重级别	修复方案
不符合规范的前置元数据字段	错误	移动到 `metadata` 字段下或直接删除
名称/目录名不匹配	错误	重命名使其一致
`allowed-tools` 为YAML数组格式	错误	转换为空格分隔的字符串
脚本中存在交互式提示	错误	替换为CLI flags/标准输入
SKILL.md行数超过500	警告	拆分内容到 `references/` 目录
存在README/LICENSE/CHANGELOG文件	警告	删除（属于AI元文档）
存在非标准目录（ `rules/` 、 `templates/` ）	警告	重命名为 `references/` / `assets/`
描述模糊	警告	添加明确的触发词和"Use when..."说明
脚本没有 `--help` 说明	提示	添加使用文档

Frontmatter Rules

前置元数据规则

Required fields

必填字段

Field	Constraints
`name`	1–64 chars. Lowercase alphanumeric + hyphens only. No leading/trailing/consecutive hyphens. Must match parent directory name (after NFKC normalisation).
`description`	1–1024 chars. Non-empty. Describe what the skill does AND when to use it. Include specific trigger keywords.

字段	约束
`name`	长度1-64字符，仅允许小写字母、数字和短横线，不能有首尾/连续短横线，必须与父目录名称一致（经过NFKC标准化后）
`description`	长度1-1024字符，非空，需要说明技能的功能以及适用场景，包含明确的触发关键词

Optional fields

可选字段

Field	Constraints
`license`	String. License name or reference to bundled file.
`compatibility`	1–500 chars. Environment requirements only. Most skills don't need this.
`metadata`	Key-value map (string → string). For client-specific properties.
`allowed-tools`	Space-delimited string (not YAML array). Experimental. e.g. `Bash(git:*) Read`

字段	约束
`license`	字符串，许可证名称或对应绑定文件的引用
`compatibility`	长度1-500字符，仅用于说明环境要求，大部分技能不需要该字段
`metadata`	键值对映射（字符串→字符串），用于存放客户端自定义属性
`allowed-tools`	空格分隔的字符串（不是YAML数组），实验性字段，例如 `Bash(git:*) Read`

Disallowed fields

禁止字段

Any field not in

{name, description, license, compatibility, metadata, allowed-tools}

is a validation error. Common offenders:

Found	Fix
`version`	Move to `metadata.version`
`author`	Move to `metadata.author`
`tags`	Move to `metadata.tags`
`references`	Remove (use directory convention)
`user-invocable`	Remove (non-spec)
`argument-hint`	Remove (non-spec)

任何不在

{name, description, license, compatibility, metadata, allowed-tools}

中的字段都会触发验证错误，常见违规字段：

违规字段	修复方案
`version`	移动到 `metadata.version`
`author`	移动到 `metadata.author`
`tags`	移动到 `metadata.tags`
`references`	删除（使用目录约定即可）
`user-invocable`	删除（非规范字段）
`argument-hint`	删除（非规范字段）

Directory Structure

目录结构

skill-name/                   # Must match frontmatter name
├── SKILL.md                  # Required
├── scripts/                  # Optional: executable code
├── references/               # Optional: on-demand documentation
└── assets/                   # Optional: static resources

Should not exist at top level:

```
README.md
```
,
```
LICENSE
```
,
```
CHANGELOG.md
```
— AI meta-docs
```
package.json
```
,
```
tsconfig.json
```
, lock files — build artifacts
Bare
```
.md
```
files other than
```
SKILL.md
```
— move to
```
references/
```

Non-standard directories (rename):

```
rules/
```
→
```
references/
```
```
templates/
```
→
```
assets/
```
```
examples/
```
→
```
references/
```
```
src/
```
,
```
docs/
```
,
```
test/
```
→ remove or restructure

skill-name/                   # 必须与前置元数据的name字段一致
├── SKILL.md                  # 必填
├── scripts/                  # 可选：可执行代码
├── references/               # 可选：按需加载的文档
└── assets/                   # 可选：静态资源

顶层目录不应该存在以下内容：

```
README.md
```
、
```
LICENSE
```
、
```
CHANGELOG.md
```
—— AI元文档
```
package.json
```
、
```
tsconfig.json
```
、依赖锁文件 —— 构建产物
除了
```
SKILL.md
```
之外的裸露
```
.md
```
文件 —— 移动到
```
references/
```
目录

非标准目录需重命名：

```
rules/
```
→
```
references/
```
```
templates/
```
→
```
assets/
```
```
examples/
```
→
```
references/
```
```
src/
```
、
```
docs/
```
、
```
test/
```
→ 删除或重构结构

Progressive Disclosure

渐进式信息披露

Keep SKILL.md body under 500 lines. When approaching this limit, offload to

references/

Content type	Move to
Detailed examples	`references/examples.md`
API reference tables	`references/api.md`
Edge cases/gotchas	`references/advanced.md`
Installation/setup	`references/setup.md`
Pattern libraries	`references/patterns.md`

Replace offloaded content with a one-line reference:

markdown

For detailed examples, see [references/examples.md](references/examples.md).

Keep references one level deep from SKILL.md. Avoid chains (A → B → C).

保持SKILL.md正文行数在500行以内，接近阈值时将内容迁移到

references/

内容类型	迁移目标
详细示例	`references/examples.md`
API参考表	`references/api.md`
边界情况/注意事项	`references/advanced.md`
安装/配置说明	`references/setup.md`
模式库	`references/patterns.md`

使用一行引用代替被迁移的内容：

markdown

For detailed examples, see [references/examples.md](references/examples.md).

引用文件保持在SKILL.md的一级目录下，避免链式引用（A→B→C）。

Description Quality

描述质量

A description is effective when an agent can answer from it alone:

"What does this skill do?" (capability)
"Should I activate it for this task?" (trigger)

Quality	Pattern	Example
Poor	Vague noun phrase	"Helps with documents"
Fair	Capability only	"Processes PDF files"
Good	Capability + trigger	"Extract text from PDFs. Use when working with PDF files."
Excellent	Capability + specific triggers + scope	"Extract text and tables from PDFs, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction."

好的描述应当可以让Agent仅凭描述就能回答两个问题：

"这个技能是做什么的？"（能力）
"当前任务我需要激活这个技能吗？"（触发条件）

质量等级	模式	示例
差	模糊的名词短语	"Helps with documents"
一般	仅说明能力	"Processes PDF files"
良好	能力+触发条件	"Extract text from PDFs. Use when working with PDF files."
优秀	能力+明确触发条件+适用范围	"Extract text and tables from PDFs, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction."

Validation

验证

With

skills-ref

installed:

bash

skills-ref validate ./my-skill        # structural validation
skills-ref read-properties ./my-skill  # dump parsed frontmatter

Install if needed:

bash

uv tool install skills-ref   # or: pip install skills-ref

Without the tool, walk through references/validation-checklist.md manually.

已安装

skills-ref

的情况下：

bash

skills-ref validate ./my-skill        # 结构验证
skills-ref read-properties ./my-skill  # 输出解析后的前置元数据

需要安装的话执行：

bash

uv tool install skills-ref   # 或者: pip install skills-ref

没有工具的情况下，手动对照references/validation-checklist.md检查即可。

Script Rules (Summary)

脚本规则（概要）

Full guide: references/script-guidelines.md

Non-negotiable:

No interactive prompts — agents cannot respond to TTY input
Support
--help
— agents discover script interfaces through help output
Structured output (JSON/CSV) to stdout, diagnostics to stderr
Meaningful exit codes — document in
```
--help
```
Pin dependency versions — reproducibility across environments
--dry-run
for destructive operations

完整指南：references/script-guidelines.md

硬性要求：

禁止交互式提示 —— Agent无法响应TTY输入
支持
--help
参数 —— Agent通过帮助输出发现脚本接口
结构化输出（JSON/CSV）输出到stdout，诊断信息输出到stderr
有意义的退出码 —— 在
```
--help
```
中说明
锁定依赖版本 —— 保障跨环境的可复现性
破坏性操作支持
--dry-run
参数

References

参考文档

Validation checklist — exhaustive audit checklist
Common fixes — decision tree + fix recipes
Script guidelines — spec-compliant script design
agentskills.io specification — canonical spec

验证清单 —— 完整的审计清单
常见修复方案 —— 决策树+修复指南
脚本指南 —— 符合规范的脚本设计说明
agentskills.io官方规范 —— 权威规范