Chapter 22 · Agent Skills Standards and SKILL.md

Chapter goals: Understand the core philosophy of the Agent Skills open standard, master the SKILL.md frontmatter field spec, and know how skills are loaded on-demand without blowing up context.

22.1 What Is the Agent Skills Standard

Agent Skills is an open standard (specification) that defines how AI coding agents distribute capability packs in a unified format. Its core contribution:

• Unified interface: regardless of whether you use Claude Code, Codex, Cursor, or Pi, the skill loading方式 is consistent;
• Progressive disclosure: at startup only name + description enter the system prompt; full instructions load on-demand;
• Self-contained: the skill directory cancarry scripts, resource files, reference docs — the whole thing is迁移able.

The standard is published by agentskills.io. The core requirement is just one: the skill's root directory must have a SKILL.md file.

my-skill/
├── SKILL.md              # Required: frontmatter + body instructions
├── scripts/
│   └── helper.py         # Optional: helper scripts
└── references/
    └── api-reference.md  # Optional: detailed docs for on-demand loading

This directory structure can be discovered and loaded by any tool that遵循 the standard — that's the meaning of "open."

22.2 SKILL.md Frontmatter Field Spec

The first part of SKILL.md must be YAML frontmatter, providing metadata for the agent. The official spec defines these fields:

Field	Required	Limit	Description
name	✅	≤64 chars, lowercase + digits + hyphens	The skill's unique identifier; does not need to match the directory name (this is Pi's宽容 extension to the standard)
description	✅	≤1024 chars	The most critical line — determines when the agent triggers loading; must be specific to get高命中率
license	—	—	License name or path
compatibility	—	≤500 chars	Runtime环境 requirements (e.g. Python ≥3.10)
metadata	—	arbitrary key-value	Custom fields for tool extensions
allowed-tools	—	experimental	Pre-approved tool list, avoiding运行时权限询问
disable-model-invocation	—	boolean	When true, the skill is隐藏 from the system prompt; can only be手动 called via /skill:name

Name Validation Rules

Valid: changelog-check, pdf-merge, code-review
Invalid: Changelog-Check (uppercase), -pdf (hyphen at start), data--analysis (consecutive hyphens)

Description Design Principles

The description is a trigger, not a功能说明书. A good description should contain trigger phrases and 适用场景:

# Good: specific, includes trigger phrases
description: >
  Verify CHANGELOG.md covers all notable changes since the last git tag.
  Use when preparing releases or the user mentions changelog.

# Bad: vague; the agent can\'t判断
description: Helps with PDFs.

Official wording

"The description determines when the agent loads the skill. Be specific."

22.3 Progressive Disclosure Mechanism

The skill's "progressive disclosure" is its core design distinguishing it from a one-time prompt:

At startup:
  Scan all skills → inject only 「name + description」 into system prompt
  (~50–200 lines; doesn\'t blow up context)

At runtime:
  Agent judges the task matches a skill → uses the read tool to加载 the full SKILL.md
  (on-demand, not bulk-loaded)

At execution:
  Follow the instructions in SKILL.md;引用 relative paths under scripts/references

This means: you can install dozens of skills, but the常驻 context cost is only dozens of descriptions.

22.4 Division of Labor vs MCP / AGENTS.md

Many readers ask: what's the difference between a Skill, an MCP Tool, and AGENTS.md? The定位 of the three:

Dimension	Agent Skill	MCP Tool	AGENTS.md
Form	Markdown instruction pack	Remotely callable function	Project-level instruction file
Load timing	On-demand read	Continuously注册 to tool list	Loaded at startup
Scope	Specific-task workflow	通用 capabilities (search/database, etc.)	The entire project's context
Dynamism	Replaceable/composable	Independent service	Static
Typical scenario	"Check changelog before releasing"	"Search GitHub issues"	"This project's tech stack is FastAPI+SQLModel"

The three互补: AGENTS.md gives全局 background; MCP provides跨-project通用 foundational capabilities; Skills封装 specific-task best practices.

22.5 Validation Rules Quick Reference

Issue	Behavior
Missing description	❌ Not loaded (the唯一 hard拦截)
name too long or has非法 chars	⚠️ Warning; still loaded
name inconsistent with目录名	✅ Allowed (Pi's extension)
同名冲突 (found in多处)	⚠️ Warning; keep the first-found
Unknown frontmatter field	✅ Ignored; doesn't affect loading

Chapter Summary

• Agent Skills is an open standard; the core is the SKILL.md file;
• description determines the trigger timing; must be具体化;
• Progressive disclosure keeps context costcontrolled to dozens of descriptions;
• Different from MCP/AGENTS.md in positioning; the three can叠加使用;
• Missing description is the唯一 hard拦截; other issues仅 warning.

🧪 随堂测验

点击你认为正确的选项。答错时会展示正确答案与原因解析。

1. In the Agent Skills standard, which frontmatter field's缺失 causes the skill to被拒绝 loaded?

2. Which of the following name values符合 the spec?

3. What is the core purpose of progressive disclosure?

4. Regarding the relationship between name and目录名, which statement is correct?

🛠️ Hands-on Practice

1. Create a skill named test-skill at ~/.pi/agent/skills/test-skill/SKILL.md; the description should写 "use when the user mentions unit tests or test coverage."
2. Deliberately write a skill missing description; observe whether the agent ignores it.
3. Test "vague" vs. "specific" versions of the description separately;对比 the agent trigger rate.

After completing the exercises, proceed to Next chapter: Writing High-Quality Skills.