Back to Details

skill-standardization

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Skill Standardization

技能标准化

When to use this skill

何时使用该技能

  • Creating a new SKILL.md file from scratch
  • Auditing existing skills for Agent Skills specification compliance
  • Converting legacy skill formats (non-standard headings, frontmatter) to standard
  • Improving skill descriptions to trigger more reliably on relevant prompts
  • Adding evaluation test cases (
    evals/evals.json
    ) to a skill
  • Batch-validating all skills in a directory for consistency
  • 从零创建新的SKILL.md文件
  • 审核现有技能是否符合Agent Skills规范
  • 将旧版技能格式（非标准标题、frontmatter）转换为标准结构
  • 优化技能描述，使其在相关提示下的触发更可靠
  • 为技能添加评估测试用例（
    evals/evals.json
    ）
  • 批量校验目录下所有技能的一致性

Agent Skills Specification Reference

Agent Skills规范参考

Frontmatter fields

Frontmatter字段

FieldRequiredConstraints
name
Yes1–64 chars, lowercase alphanumeric + hyphens, no leading/trailing/consecutive hyphens, must match parent directory name
description
Yes1–1024 chars, must describe what skill does AND when to trigger
allowed-tools
NoSpace-delimited list of pre-approved tools
compatibility
NoMax 500 chars, environment requirements
license
NoLicense name or reference to bundled file
metadata
NoArbitrary key-value map for additional fields
字段是否必填约束
name
是1-64个字符，小写字母+数字+连字符，无首尾/连续连字符，必须与父目录名称一致
description
是1-1024个字符，必须说明技能功能以及触发时机
allowed-tools
否预审批工具的空格分隔列表
compatibility
否最多500个字符，说明环境要求
license
否许可证名称或对绑定许可证文件的引用
metadata
否存储额外字段的任意键值映射

Standard directory structure

标准目录结构

skill-name/
├── SKILL.md          # Required
├── scripts/          # Optional: executable scripts
├── references/       # Optional: detailed documentation
├── assets/           # Optional: templates, images, data
└── evals/            # Optional: evaluation test cases
    └── evals.json
skill-name/
├── SKILL.md          # 必选
├── scripts/          # 可选：可执行脚本
├── references/       # 可选：详细文档
├── assets/           # 可选：模板、图片、数据
└── evals/            # 可选：评估测试用例
    └── evals.json

Progressive disclosure tiers

渐进式披露层级

TierWhat's loadedWhenToken budget
1. Catalogname + descriptionSession start~100 tokens per skill
2. InstructionsFull SKILL.md bodyOn activation< 5000 tokens (500 lines max)
3. Resourcesscripts/, references/When neededVaries
层级加载内容触发时机Token预算
1. 目录name + description会话启动时每个技能约100 tokens
2. 使用说明完整SKILL.md正文技能激活时< 5000 tokens（最多500行）
3. 资源scripts/、references/需要时不固定

Instructions

使用说明

Step 1: Validate an existing skill

步骤1：校验现有技能

Run the validation script on a skill directory:
bash
bash scripts/validate_skill.sh path/to/skill-directory
Validate all skills in a directory:
bash
bash scripts/validate_skill.sh --all .agent-skills/
The script checks:
  • Required frontmatter fields (
    name
    , 
    description
    )
  • name
    format: lowercase, no consecutive hyphens, matches directory name
  • description
    length: 1–1024 characters
  • allowed-tools
    format: space-delimited (not YAML list)
  • Recommended sections present
  • File length: warns if over 500 lines
在技能目录下运行校验脚本：
bash
bash scripts/validate_skill.sh path/to/skill-directory
校验某个目录下的所有技能：
bash
bash scripts/validate_skill.sh --all .agent-skills/
脚本会校验以下内容：
  • 必选frontmatter字段（
    name
    、
    description
    ）是否存在
  • name
    格式：小写、无连续连字符、与目录名一致
  • description
    长度：1-1024个字符
  • allowed-tools
    格式：空格分隔（而非YAML列表）
  • 推荐章节是否存在
  • 文件长度：超过500行时给出警告

Step 2: Write an effective description

步骤2：编写有效的描述

The 
description
field determines when a skill triggers. A weak description means the skill never activates; an over-broad one triggers at wrong times.
Template:
yaml
description: >
  [What the skill does — list specific operations.]
  Use when [trigger conditions]. Even if the user doesn't explicitly
  mention [domain keyword] — also triggers on: [synonym list].
Principles (from agentskills.io):
  1. Imperative phrasing — "Use this skill when..." not "This skill does..."
  2. User intent, not implementation — describe what the user wants to achieve
  3. Be explicit about edge cases — "even if they don't say X"
  4. List trigger keywords — synonyms, related terms the user might type
  5. Stay under 1024 characters — descriptions grow during editing; watch the limit
Before / After:
yaml
undefined
description
字段决定了技能的触发时机。描述太弱会导致技能永远无法激活，描述太宽泛则会在错误的时机触发。
模板：
yaml
description: >
  [技能功能——列出具体操作]
  Use when [触发条件]. Even if the user doesn't explicitly
  mention [领域关键词] — also triggers on: [同义词列表].
原则（来源：agentskills.io）：
  1. 祈使句式 — 用"Use this skill when..."而非"This skill does..."
  2. 聚焦用户意图，而非实现逻辑 — 描述用户想要达成的目标
  3. 明确说明边缘场景 — 比如"即使用户没有提到X"
  4. 列出触发关键词 — 用户可能输入的同义词、相关术语
  5. 保持在1024字符以内 — 编辑过程中描述内容会增加，注意长度限制
优化前后对比：
yaml
undefined

Before (weak — never triggers)

优化前（效果差——永远不会触发）

description: Helps with PDFs.
description: Helps with PDFs.

After (optimized — reliable triggering)

优化后（效果好——触发可靠）

description: > Extract text and tables from PDF files, fill forms, merge and split documents. Use when the user needs to work with PDF files, even if they don't explicitly say 'PDF' — triggers on: fill form, extract text from document, merge files, read scanned pages.
undefined
description: > Extract text and tables from PDF files, fill forms, merge and split documents. Use when the user needs to work with PDF files, even if they don't explicitly say 'PDF' — triggers on: fill form, extract text from document, merge files, read scanned pages.
undefined

Step 3: Create a new SKILL.md

步骤3：创建新的SKILL.md

Use this template as the starting point:
markdown
---
name: skill-name
description: >
  [What it does and specific operations it handles.]
  Use when [trigger conditions]. Triggers on: [keyword list].
allowed-tools: Bash Read Write Edit Glob Grep
metadata:
  tags: tag1, tag2, tag3
  version: "1.0"
---
使用以下模板作为起点：
markdown
---
name: skill-name
description: >
  [技能功能和支持的具体操作]
  Use when [触发条件]. Triggers on: [关键词列表].
allowed-tools: Bash Read Write Edit Glob Grep
metadata:
  tags: tag1, tag2, tag3
  version: "1.0"
---

Skill Title

技能标题

When to use this skill

何时使用该技能

  • Scenario 1
  • Scenario 2
  • 场景1
  • 场景2

Instructions

使用说明

Step 1: [Action]

步骤1：[操作]

Content...
内容...

Step 2: [Action]

步骤2：[操作]

Content...
内容...

Examples

示例

Example 1: [Scenario]

示例1：[场景]

Input: ... Output: ...
输入：... 输出：...

Best practices

最佳实践

  1. Practice 1
  2. Practice 2
  1. 实践1
  2. 实践2

References

参考链接

  • Link
undefined
  • 链接
undefined

Step 4: Convert legacy section headings

步骤4：转换旧版章节标题

Legacy headingStandard heading
## Purpose
## When to use this skill
## When to Use
## When to use this skill
## Procedure
## Instructions
## Best Practices
## Best practices
## Reference
## References
## Output Format
## Output format
旧版标题标准标题
## Purpose
## 何时使用该技能
## When to Use
## 何时使用该技能
## Procedure
## 使用说明
## Best Practices
## 最佳实践
## Reference
## 参考链接
## Output Format
## 输出格式

Step 5: Add evaluation test cases

步骤5：添加评估测试用例

Create 
evals/evals.json
with 2–5 realistic test prompts:
json
{
  "skill_name": "your-skill-name",
  "evals": [
    {
      "id": 1,
      "prompt": "Realistic user message that should trigger this skill",
      "expected_output": "Description of what success looks like",
      "assertions": [
        "Specific verifiable claim (file exists, count is correct, format is valid)",
        "Another specific claim"
      ]
    }
  ]
}
Good assertions are verifiable: file exists, JSON is valid, chart has 3 bars. Avoid vague assertions like "output is good."
创建
evals/evals.json
文件，包含2-5个真实测试提示：
json
{
  "skill_name": "your-skill-name",
  "evals": [
    {
      "id": 1,
      "prompt": "应当触发该技能的真实用户消息",
      "expected_output": "成功执行的结果描述",
      "assertions": [
        "可验证的具体断言（文件存在、计数正确、格式有效）",
        "另一个具体断言"
      ]
    }
  ]
}
优秀的断言是可验证的：文件存在、JSON有效、图表有3个条形。避免使用模糊断言，比如"输出效果好"。

Available scripts

可用脚本

  • scripts/validate_skill.sh
     — Validates a SKILL.md against the Agent Skills spec
  • scripts/validate_skill.sh
     — 按照Agent Skills规范校验SKILL.md文件

Examples

示例

Example 1: Validate a skill directory

示例1：校验单个技能目录

bash
bash scripts/validate_skill.sh .agent-skills/my-skill/
Output:
Validating: .agent-skills/my-skill/SKILL.md
✓ Required field: name = 'my-skill'
✓ Required field: description present
✗ Description length: 1087 chars (max 1024)
✓ Name format: valid lowercase
✗ Name/directory mismatch: name='myskill' vs dir='my-skill'
✓ Recommended section: When to use this skill
✓ Recommended section: Instructions
⚠ Missing recommended section: Examples
✓ File length: 234 lines (OK)

Issues: 2 errors, 1 warning
bash
bash scripts/validate_skill.sh .agent-skills/my-skill/
输出：
Validating: .agent-skills/my-skill/SKILL.md
✓ Required field: name = 'my-skill'
✓ Required field: description present
✗ Description length: 1087 chars (max 1024)
✓ Name format: valid lowercase
✗ Name/directory mismatch: name='myskill' vs dir='my-skill'
✓ Recommended section: When to use this skill
✓ Recommended section: Instructions
⚠ Missing recommended section: Examples
✓ File length: 234 lines (OK)

Issues: 2 errors, 1 warning

Example 2: Batch validate all skills

示例2：批量校验所有技能

bash
bash scripts/validate_skill.sh --all .agent-skills/
bash
bash scripts/validate_skill.sh --all .agent-skills/

Example 3: Fix common frontmatter issues

示例3：修复常见的frontmatter问题

yaml
undefined
yaml
undefined

WRONG — tags inside metadata is non-standard for some validators

错误 — 部分校验器不支持metadata内的tags列表写法

metadata: tags: [tag1, tag2] # list syntax platforms: Claude # non-spec field
metadata: tags: [tag1, tag2] # 列表语法 platforms: Claude # 非规范字段

CORRECT — per Agent Skills spec

正确 — 符合Agent Skills规范

metadata: tags: tag1, tag2 # string value allowed-tools: Bash Read Write # space-delimited, not a YAML list
undefined
metadata: tags: tag1, tag2 # 字符串值 allowed-tools: Bash Read Write # 空格分隔，而非YAML列表
undefined

Best practices

最佳实践

  1. Description quality first — weak descriptions mean the skill never activates; improve it before anything else
  2. Keep SKILL.md under 500 lines — move detailed reference docs to 
    references/
  3. Pin script versions — use 
    uvx ruff@0.8.0
    not just 
    ruff
    to ensure reproducibility
  4. No interactive prompts in scripts — agents run in non-interactive shells; use 
    --flag
    inputs, never TTY prompts
  5. Structured output from scripts — prefer JSON/CSV over free-form text; send data to stdout, diagnostics to stderr
  6. Add evals before publishing — at least 2–3 test cases covering core and edge cases
  1. 描述质量优先 — 描述过差会导致技能永远无法激活，这是优先级最高的优化项
  2. 保持SKILL.md不超过500行 — 将详细参考文档移动到
    references/
    目录下
  3. 固定脚本版本 — 使用
    uvx ruff@0.8.0
    而非仅
    ruff
    ，确保可复现性
  4. 脚本中不要使用交互式提示 — Agent运行在非交互式shell中，使用
    --flag
    参数输入，永远不要使用TTY提示
  5. 脚本输出结构化内容 — 优先使用JSON/CSV而非自由格式文本；数据输出到stdout，诊断信息输出到stderr
  6. 发布前添加评估用例 — 至少包含2-3个覆盖核心场景和边缘场景的测试用例

References

参考链接