Agent Skills Spec

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

Common Fixes

Decision Tree

Is the issue in frontmatter?
├── Yes → Frontmatter Fixes below
└── No
    Is the issue in directory structure?
    ├── Yes → Structure Fixes below
    └── No
        Is the issue in SKILL.md body?
        ├── Yes → Body Fixes below
        └── No → Script Fixes below

---

Frontmatter Fixes

Non-spec frontmatter fields

Symptom: skills-ref validate reports unexpected fields.

Action by field:

Before:

---
name: my-skill
description: Does things
version: "2.0.0"
author: someone
tags:
  - foo
  - bar
references:
  - workers
  - pages
---

After:

---
name: my-skill
description: Does things
metadata:
  version: "2.0.0"
  author: someone
  tags: "foo, bar"
---

Note: metadata values must be strings. Convert arrays to comma-delimited strings.

allowed-tools as YAML array

Before:

allowed-tools:
  - Bash(firecrawl *)
  - Bash(npx firecrawl *)

After:

allowed-tools: Bash(firecrawl *) Bash(npx firecrawl *)

Name/directory mismatch

Decide which is correct — directory name or frontmatter name:

• If directory name is intended: update frontmatter name to match
• If frontmatter name is intended: rename directory

Invalid name characters

Vague description

Template:

description: >
  [Action verb] [what it does in specific terms]. Use when [specific trigger
  conditions]. Triggers on [keywords users might say].

Before (vague):

description: Comprehensive platform skill for development

After (specific):

description: >
  Build and deploy on Cloudflare Workers, Pages, D1, KV, R2, and Durable Objects.
  Use for any Cloudflare development task including serverless functions, static
  sites, databases, object storage, and real-time applications.

Description too long (>1024 chars)

1. Remove trigger word lists (keep 3–5 key triggers in natural language) 2. Remove cross-references to other skills (move to SKILL.md body) 3. Focus on primary capability + top 2–3 use cases 4. Remove redundant phrases

---

Structure Fixes

README / LICENSE / CHANGELOG present

Delete these files. Agents do not need meta-documentation.

• README.md: SKILL.md IS the agent instruction
• LICENSE: Use the license frontmatter field. If full terms needed: license: Proprietary. See assets/LICENSE.txt
• CHANGELOG: Remove. Version tracking belongs in git.

Non-standard top-level markdown files

Move to references/:

mkdir -p references
mv PRACTICAL-TIPS.md references/
mv api_reference.md references/

Update references in SKILL.md to use references/ prefix.

Non-standard directories

Rename to spec-standard names:

Build artifacts

Remove: package.json, tsconfig.json, lock files, node_modules/, __pycache__/, .git/

Scripts at top level

Move into scripts/:

mkdir -p scripts
mv *.py *.sh scripts/

Update references in SKILL.md.

---

Body Fixes

SKILL.md over 500 lines

1. Count lines: wc -l SKILL.md 2. Identify sections to offload (priority order):

• Complete 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

3. Replace offloaded content with one-line reference:

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

4. Verify under 500 lines after split 5. Verify all referenced files exist

Imperative mood violations

Deeply nested references

Symptom: SKILL.md → references/a.md → references/b.md

Fix: Flatten so SKILL.md links directly to all needed reference files. If b.md is important enough to exist, SKILL.md should reference it directly.

---

Script Fixes

Interactive prompts

Replace TTY input with CLI flags:

Before:

target = input("Target environment: ")

After:

import argparse
parser = argparse.ArgumentParser()
parser.add_argument("--env", required=True, choices=["dev", "staging", "prod"])
args = parser.parse_args()

Missing --help

Add argument parsing with usage documentation:

parser = argparse.ArgumentParser(
    description="Process input data and produce a summary report.",
    epilog="Examples:\n  %(prog)s data.csv\n  %(prog)s --format csv data.csv",
    formatter_class=argparse.RawDescriptionHelpFormatter,
)
parser.add_argument("input", help="Input file to process")
parser.add_argument("--format", choices=["json", "csv"], default="json")
parser.add_argument("--dry-run", action="store_true", help="Preview without changes")

Unstructured output

Replace free-form text with JSON:

Before:

Name: my-service
Status: running

After:

{"name": "my-service", "status": "running"}

Diagnostics to stderr:

import sys
print("Processing...", file=sys.stderr)
print('{"result": "ok"}')

Script Guidelines

Complete guide for writing spec-compliant scripts in agent skills.

Hard Requirements

Non-negotiable. Violations cause agent hangs or failures.

No interactive prompts

Agents run in non-interactive shells. They cannot respond to:

• input() / raw_input() (Python)
• read without timeout (Bash)
• readline() (Node.js)
• Confirmation dialogs, password prompts, TUI menus

Every input must come from CLI flags, environment variables, or stdin pipes.

Self-documenting with --help

Agents discover script interfaces through --help output. Include: 1. One-line description 2. Usage pattern with required and optional arguments 3. Available flags with defaults 4. 2–3 usage examples 5. Exit codes

Keep --help concise — output enters the agent's context window.

Usage: scripts/process.py [OPTIONS] INPUT_FILE

Process input data and produce a summary report.

Options:
  --format FORMAT    Output format: json, csv, table (default: json)
  --output FILE      Write output to FILE instead of stdout
  --verbose          Print progress to stderr
  --dry-run          Preview changes without applying

Exit codes:
  0  Success
  1  Invalid arguments
  2  Input file not found
  3  Processing error

Examples:
  scripts/process.py data.csv
  scripts/process.py --format csv --output report.csv data.csv

Interface Design

CLI flags for all input

Use argument parsing libraries:

• Python: argparse (stdlib) or click
• Bash: getopts or manual flag parsing
• Node.js: commander, yargs, or parseArgs

Reject ambiguous input

Fail with a clear error rather than guessing:

if args.format not in VALID_FORMATS:
    print(f"Error: --format must be one of: {', '.join(VALID_FORMATS)}.", file=sys.stderr)
    print(f"       Received: \"{args.format}\"", file=sys.stderr)
    sys.exit(1)

Use closed sets

Constrain choices where possible:

parser.add_argument("--env", choices=["dev", "staging", "prod"], required=True)

--dry-run for destructive operations

if args.dry_run:
    print(json.dumps({"action": "delete", "target": args.file, "dry_run": True}))
    sys.exit(0)

Safe defaults

Destructive operations require explicit confirmation:

parser.add_argument("--confirm", action="store_true",
    help="Required for destructive operations")

if not args.confirm:
    print("Error: --confirm required for delete operations.", file=sys.stderr)
    sys.exit(1)

Output Design

Structured output to stdout

Prefer JSON (or CSV/TSV for tabular data):

import json
result = {"name": "my-service", "status": "running"}
print(json.dumps(result))

Diagnostics to stderr

Progress, warnings, debug info go to stderr:

import sys
print("Processing file...", file=sys.stderr)
print('{"result": "ok"}')  # clean stdout for piping

Predictable output size

Agent harnesses may truncate beyond 10–30K characters:

• Default to summary output
• Support --offset and --limit for pagination
• Support --output FILE for large results

Error Handling

Helpful error messages

Tell the agent what went wrong, what was expected, and what to try:

Error: --format must be one of: json, csv, table.
       Received: "xml"

Not: Error: invalid input

Meaningful exit codes

Document in --help.

Dependency Management

Self-contained scripts

Declare dependencies inline:

Python (PEP 723):

# /// script
# dependencies = [
#   "beautifulsoup4>=4.12,<5",
# ]
# requires-python = ">=3.11"
# ///

Run with uv run scripts/extract.py.

Deno:

import * as cheerio from "npm:cheerio@1.0.0";

Pin versions

Always pin for reproducibility:

• Python: "beautifulsoup4>=4.12,<5" (not "beautifulsoup4")
• npm: npx eslint@9.0.0 (not npx eslint)
• Go: go run tool@v1.2.3 (not go run tool@latest)

State prerequisites

In SKILL.md, document what each script needs:

**Requirements:** Python 3.11+, uv

For runtime-level requirements, use the compatibility frontmatter field.

Execution Context

Relative paths from skill root

Reference other skill files with relative paths:

import pathlib
skill_root = pathlib.Path(__file__).parent.parent
template = skill_root / "assets" / "template.json"

Forward slashes only

Always use forward slashes, even on Windows:

• scripts/helper.py (correct)
• scripts\helper.py (wrong)

SKILL.md documentation

For each script, document in SKILL.md:

## Scripts

- **scripts/validate.sh** — Validate configuration files
- **scripts/process.py** — Process input data (run with `uv run`)

Make clear whether the agent should execute or read as reference.

Idempotency

Design scripts so running them twice produces the same result:

• "Create if not exists" instead of "create and fail on duplicate"
• "Upsert" instead of "insert"
• Check current state before making changes

Checklist

• [ ] No interactive prompts
• [ ] --help with usage, flags, examples, exit codes
• [ ] Structured output (JSON/CSV) to stdout
• [ ] Diagnostics to stderr
• [ ] Meaningful exit codes
• [ ] Dependencies pinned
• [ ] Self-contained (inline deps or documented requirements)
• [ ] Idempotent where possible
• [ ] --dry-run for destructive operations
• [ ] --confirm for irreversible operations
• [ ] Forward slashes in all paths
• [ ] Documented in SKILL.md with invocation example

Validation Checklist

Walk through each section in order. Report all failures before suggesting fixes.

1. Directory Structure

• [ ] Directory exists and contains SKILL.md
• [ ] No non-standard top-level files (see list below)
• [ ] No non-standard subdirectories (only scripts/, references/, assets/)
• [ ] No build artifacts (node_modules/, __pycache__/, .git/, dist/)

Disallowed top-level files

Any of these present = finding (Warning):

README.md, README, LICENSE, LICENSE.md, LICENSE.txt, CHANGELOG.md, CHANGELOG, AGENTS.md, package.json, tsconfig.json, pnpm-lock.yaml, package-lock.json, yarn.lock, bun.lockb, Makefile, Dockerfile, .eslintrc, .prettierrc, metadata.json, _meta.json, nori.json, skills-lock.json

Non-standard directories

Any directory other than scripts/, references/, assets/ = finding (Warning):

rules/, templates/, examples/, src/, test/, tests/, docs/, lib/, dist/, .github/

Bare markdown files

Any .md file at top level other than SKILL.md should be in references/.

2. SKILL.md Format

• [ ] File starts with --- (YAML frontmatter delimiter)
• [ ] Frontmatter closed with second ---
• [ ] YAML parses without errors
• [ ] Frontmatter is a YAML mapping (not list or scalar)

3. Required Frontmatter: name

• [ ] Present and non-empty string
• [ ] 1–64 characters after NFKC normalisation
• [ ] All lowercase
• [ ] Only: Unicode lowercase letters, digits, hyphens
• [ ] Does not start with hyphen
• [ ] Does not end with hyphen
• [ ] No consecutive hyphens (--)
• [ ] No underscores, spaces, dots, or other punctuation
• [ ] Matches parent directory name exactly

4. Required Frontmatter: description

• [ ] Present and non-empty string
• [ ] 1–1024 characters
• [ ] Describes what the skill does (capability)
• [ ] Describes when to use it (trigger conditions)
• [ ] Includes specific keywords for task matching
• [ ] Does not contain XML tags

5. Optional Frontmatter Fields

allowed-tools (if present)

• [ ] Is a space-delimited string (not YAML array)
• [ ] Format: ToolName(pattern) ToolName or just ToolName

compatibility (if present)

• [ ] Is a string, 1–500 characters
• [ ] Describes environment requirements only

metadata (if present)

• [ ] Is a YAML mapping (key-value pairs)
• [ ] Keys and values are strings

license (if present)

• [ ] Is a string (license name or filename reference)

6. Disallowed Frontmatter Fields

Any field not in {name, description, license, compatibility, metadata, allowed-tools} = Error.

Check for these common offenders:

• [ ] No references field
• [ ] No user-invocable field
• [ ] No argument-hint field
• [ ] No version at top level (use metadata.version)
• [ ] No author at top level (use metadata.author)
• [ ] No tags at top level (use metadata.tags)

7. Body Content

• [ ] Under 500 lines
• [ ] Imperative mood ("Extract text" not "You should extract text")
• [ ] File references use relative paths (forward slashes)
• [ ] Referenced files actually exist
• [ ] References one level deep (no A → B → C chains)
• [ ] No "you should", "make sure to", "don't forget" phrasing

8. Scripts (if scripts/ exists)

• [ ] No interactive prompts (TTY input hangs agents)
• [ ] Each script supports --help
• [ ] --help includes: description, flags, examples, exit codes
• [ ] Structured output (JSON/CSV) to stdout
• [ ] Diagnostics/progress to stderr
• [ ] Meaningful exit codes (different codes for different failures)
• [ ] Idempotent where possible
• [ ] --dry-run for destructive operations
• [ ] Dependencies pinned to versions
• [ ] SKILL.md documents each script with invocation example

9. Progressive Disclosure

• [ ] SKILL.md focuses on core workflow and decision frameworks
• [ ] Detailed reference material in references/, not SKILL.md body
• [ ] Scripts in scripts/, not inline in SKILL.md
• [ ] Templates/schemas in assets/ if applicable
• [ ] Agent handles the common case without loading all files

Severity Levels