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:

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

Minimal valid skill:

yaml

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

Check frontmatter against hard rules (required fields, character limits, naming)
Check for disallowed frontmatter fields (see below)
Verify directory structure (only
```
scripts/
```
,
```
references/
```
,
```
assets/
```
allowed)
Scan for non-standard top-level files (README, LICENSE, CHANGELOG)
Count SKILL.md body lines (<500)
Assess description quality (specific triggers? capability + when?)
Assess progressive disclosure (too much in SKILL.md?)
Check script interfaces if
```
scripts/
```
exists
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:

markdown

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:

"What does this skill do?" (capability)
"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:

bash

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

Install if needed:

bash

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

agent-skills-spec

NPX Install

Tags

SKILL.md Content