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:

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

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.

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

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)

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/:

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:

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)

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."

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