agent-skills-spec（Agent 技能规范）

Agent Skills Spec

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

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.

Create Workflow

Create a new spec-compliant skill:

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

Minimal valid skill:

---
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]

Audit Workflow

Audit an existing skill for spec compliance:

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

For the full checklist: see 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:

Frontmatter Rules

Required fields

Optional fields

Disallowed fields

Any field not in {name, description, license, compatibility, metadata, allowed-tools} is a validation error. Common offenders:

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

Progressive Disclosure

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

Replace offloaded content with a one-line reference:

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

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

Description Quality

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

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

Validation

With skills-ref installed:

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

Install if needed:

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

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

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

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