Skill

Skills: Formal Specification and Implementation Guide

What is a Skill?

A skill is a self-contained, discoverable unit of agent capability encoded as a directory containing:

• SKILL.md (required): YAML frontmatter + Markdown instructions
• scripts/ (optional): Executable code
• references/ (optional): Supplementary documentation
• assets/ (optional): Templates, data files, images

Each skill is identified by its name (kebab-case) and must be located in a directory matching that name.

Design Philosophy

Skills implement progressive disclosure: agents load skill metadata on startup (100 tokens), full instructions when activated (5000 tokens), and on-demand resources during execution. This minimizes context bloat while maximizing capability.

Part 1: Frontmatter Specification

The SKILL.md file opens with YAML frontmatter delimited by ---:

---
name: pdf-processing
description: Extract text and tables from PDF files. Use when processing documents.
license: MIT
compatibility: Requires Python 3.9, pypdf, pdfplumber
metadata:
  version: 1.0.0
  author: Your Name
allowed-tools: "Bash(python:*) Read"
---

Required Fields

Optional Fields

Frontmatter Rules

1. Field whitelist: Only name, description, license, compatibility, metadata, allowed-tools are recognized. Unknown fields cause validation errors.
2. No duplicate keys in metadata.
3. Type checking: name and description must be strings (not lists or objects).
4. Case sensitivity: All field names are lowercase.

Part 2: Name Validation Rules

The name field must satisfy these constraints:

Regex (simplified)

^[a-z0-9]+(-[a-z0-9]+)*$

Detailed Rules

1. Length: 1–64 characters
2. Characters: Lowercase ASCII letters (a-z), digits (0-9), hyphens (-)
3. No leading hyphen: pdf is valid; -pdf is invalid
4. No trailing hyphen: pdf-processing is valid; pdf- is invalid
5. No consecutive hyphens: pdf-processing is valid; pdf--processing is invalid
6. Must match parent directory: If SKILL.md is in pdf-processing/, the name must be pdf-processing
7. Unicode normalization: Name is NFKC-normalized (handles accents, ligatures, etc.)

Valid Examples

• pdf
• pdf-processing
• data-analysis
• code-review
• xlsx
• skill-creator

Invalid Examples

• PDF-Processing (uppercase)
• -pdf (leading hyphen)
• pdf- (trailing hyphen)
• pdf--processing (consecutive hyphens)
• pdf_processing (underscore not allowed)
• `` (empty)
• pdf-processing-and-analysis-suite (65 characters, exceeds max)

Part 3: Body Content (Markdown Instructions)

After the closing ---, everything is Markdown. This is Level 2: Instructions in progressive disclosure.

Guidelines

• Stay under 500 lines (hard limit in agentskills spec)
• Estimate under 5000 tokens (~20,000 characters) (advisory)
• Include clear structure: headings, lists, code blocks
• Document when to use: What problems does this skill solve? When should agents reach for it?
• Provide examples: Show input/output, common patterns, edge cases
• Link to resources: Use [reference guide](references/REFERENCE.md) or scripts/extract.py
• Avoid boilerplate: Don't include README.md, CHANGELOG.md, or license text (those live in the root)

Example Structure

# PDF Processing

## Overview
This skill provides tools for extracting text and tables from PDF files...

## Quick Start
1. Load a PDF: `python scripts/extract.py input.pdf`
2. Parse tables: `python scripts/tables.py input.pdf`

## When to Use
- User provides a PDF and wants specific data extracted
- Need OCR for scanned PDFs
- Converting PDF forms to structured data

## When NOT to Use
- User has a simple PDF they can convert to text with `pdftotext`
- Task requires heavy image processing (use image-processing skill)

## Common Tasks

### Extracting Text
See `references/EXTRACTION_GUIDE.md` for detailed steps.

### Parsing Tables
Tables.py handles:
- Bordered tables (Tabula style)
- Grid-based layouts
- Multi-row headers

### Watermarks & Encryption
Scripts provided for removal (see `references/SECURITY.md`).

## References
- [PyPDF docs](https://pypdf.readthedocs.io/)
- [PDFPlumber guide](references/PDFPLUMBER.md)

## Troubleshooting
Common errors and solutions in `references/TROUBLESHOOTING.md`.

Part 4: Progressive Disclosure Levels

Skills are loaded in three tiers to manage agent context efficiently.

Level 1: Metadata (~100 tokens)

Loaded at agent startup. Contains:

• name: Skill identifier (kebab-case)
• description: What the skill does + when to use
• role (boxxy extension): GF(3) trit-based role (Generator, Coordinator, Verifier)
• color (boxxy extension): Primary color for UI rendering

Example XML (from skills-ref to-prompt):

<skill name="pdf" description="Extract text and tables from PDF files."
        location="/path/to/pdf/SKILL.md" trit="0" role="Coordinator"
        color="#F59E0B" />

Agents use this to:

1. Recognize available skills
2. Match skills to user requests (semantic matching on name + description)
3. Decide whether to activate this skill (avoiding context bloat)

Level 2: Instructions (~5000 tokens recommended, <500 lines hard limit)

Loaded when skill is activated. Contains:

• Full Markdown body after frontmatter
• Step-by-step procedures
• Examples and edge cases
• Links to references and scripts

Example XML:

<skill name="pdf" ...>
[full Markdown body here]
</skill>

Level 3: Resources (on-demand)

Loaded during execution as needed. Contains:

• scripts/: Executable code (Python, Bash, Go, etc.)

  • Should be self-contained or clearly document dependencies
  • Include helpful error messages
  • Useful for deterministic, fragile operations

• references/: Supplementary docs (1 level deep from SKILL.md)

  • Individual files per topic (e.g., REFERENCE.md, FORMS.md)
  • Keep focused and modular
  • Examples: API docs, detailed tutorials, templates

• assets/: Static resources

  • Templates, images, data files, boilerplate
  • Used for output artifacts (forms, generated code, etc.)

File referencing from the body:

For details, see [FHIR reference guide](references/FHIR_GUIDE.md).
Run [extraction script](scripts/extract.py) with your PDF.
Use [form template](assets/form-template.txt) as a starting point.

Part 5: Directory Structure

skill-name/
├── SKILL.md                    # Required: frontmatter + body
├── scripts/                    # Optional: executable code
│   ├── extract.py            # Python script
│   ├── process.sh            # Bash script
│   └── query.go              # Go program
├── references/               # Optional: supplementary docs (1 level deep)
│   ├── EXTRACTION_GUIDE.md
│   ├── FORMS.md
│   ├── API_DOCS.md
│   └── TROUBLESHOOTING.md
└── assets/                    # Optional: static resources
    ├── form-template.txt
    ├── schema.json
    └── icon.png

Conventions

• SKILL.md (uppercase preferred, though skill.md is accepted)
• No extraneous files: Don't include README.md, CHANGELOG.md, or other cruft
• Scripts self-contained: Either a single tool with no deps, or clearly documented
• One level deep references: Avoid nesting references/subdir/file.md
• Relative paths: Use references/GUIDE.md, not absolute paths or ../

What Goes Where?

Part 6: Validation

Use the skills-ref CLI to validate SKILL.md files:

# Validate a single skill
skills-ref validate ./pdf

# Validate all skills in a directory
skills-ref validate ./skills

# Get structured output
skills-ref read-properties ./pdf

Validation Checklist

1. ✓ SKILL.md exists (case-insensitive)
2. ✓ Frontmatter is valid YAML
3. ✓ name field is present and valid (kebab-case, matches directory)
4. ✓ description field is present (1–1024 chars)
5. ✓ compatibility field is ≤500 chars (if present)
6. ✓ No unknown fields (only whitelisted: name, description, license, compatibility, metadata, allowed-tools)
7. ✓ Body is ≤500 lines (hard limit)
8. ✓ Body is ~<5000 tokens (advisory, for context efficiency)
9. ✓ No directory traversal in resource references (e.g., no ../../etc/passwd)
10. ✓ Metadata has no duplicate keys

Validation Errors

Hard errors (prevent use):

• Missing SKILL.md
• Invalid YAML frontmatter
• Missing required fields (name, description)
• Invalid name (wrong characters, too long, doesn't match directory)
• Unknown frontmatter fields
• Body exceeds 500 lines

Warnings (advisory):

• Body approaches 5000 tokens
• Compatibility exceeds 500 chars
• Name doesn't match directory (legacy skills)

Part 7: Integration with Agent Systems

For Agent Builders

To integrate skills into your agent:

1. Discover skills in designated directories:

   skills-ref validate ./skills
   

2. Extract metadata at startup:

   from skills_ref import read_properties
   props = read_properties("./pdf")
   # props.name, props.description, props.license, ...
   

3. Match requests to skills semantically:

   • Use name + description to find relevant skills
   • Filter by allowed-tools if provided

4. Load instructions when activated:

   from skills_ref import to_prompt
   xml = to_prompt(["./pdf", "./xlsx"])
   # Inject <available_skills>...</available_skills> into system prompt
   

5. Execute resources on demand:

   • Run scripts in isolated environments
   • Load references as context
   • Retrieve assets for output generation

6. Log and audit:

   • Track which skills were loaded and when
   • Validate tool usage against allowed-tools whitelist
   • Maintain execution logs for compliance

Security Considerations

• Execute in isolation: Run skill scripts in sandboxed environments
• Trust boundaries: Only execute scripts from trusted skill sources
• User approval: Obtain consent before dangerous operations (file deletion, network access)
• Path traversal: Validate that resource references don't escape the skill directory
• Tool whitelisting: Respect the allowed-tools field; don't grant skills access beyond their scope

Part 8: Examples

Minimal Skill

---
name: hello
description: A simple greeting skill for testing agent integration.
---

# Hello Skill

Say hello to the world.

## Usage

Just ask the agent to greet you!

Full-Featured Skill

See the references/FULL_EXAMPLE.md for a comprehensive example with all optional fields, metadata, and script references.

Part 9: Best Practices

For Skill Authors

1. Keep metadata tight: Name and description should be ~100 tokens total
2. Use progressive disclosure: Don't cram everything into SKILL.md; link to references
3. Document decision boundaries: Explain when to use and when NOT to use this skill
4. Version your skills: Add version to metadata; bump on breaking changes
5. Test validation: Run skills-ref validate before publishing
6. Name clearly: Use kebab-case names that hint at function (e.g., pdf-extraction not doc-proc)
7. Include examples: Show input/output; help agents understand scope
8. Provide troubleshooting: Common errors and solutions in a reference

For Agent Builders

1. Load metadata at startup: ~100 tokens per skill is acceptable
2. Match before loading full instructions: Use semantic search on name + description
3. Cache instructions: Load full SKILL.md body only once per session
4. Respect allowed-tools: Don't bypass tool restrictions
5. Log all skill activations: For debugging and compliance
6. Graceful degradation: If a script fails, provide helpful fallbacks
7. Document constraints: Tell users which skills you support

Part 10: Relationship to agentskills.io

This skill IS the agentskills.io specification, formatted as a self-referential skill. It teaches agents how to:

• Read and understand SKILL.md files
• Validate skill metadata against the spec
• Integrate skills into agent systems
• Author new skills
• Reason about progressive disclosure and context efficiency

The specification itself is maintained at:

• Spec site: https://agentskills.io/specification
• CLI tool: https://github.com/agentskills/agentskills (skills-ref)
• Example skills: https://github.com/anthropics/skills

Part 11: Tooling

skills-ref (Python CLI)

# Installation
pip install skills-ref
# or
uv pip install skills-ref

# Subcommands
skills-ref validate <path>              # Check if valid
skills-ref read-properties <path>       # Output JSON metadata
skills-ref to-prompt <path> [<path>...] # Generate XML for agents

boxxy (Go skill system)

The Boxxy skill system adds:

• GF(3) trit-based classification: Each skill gets a color-coded role (Generator, Coordinator, Verifier)
• Glamour rendering: Rich terminal output with trit-colored themes
• Batch operations: Validate and render multiple skills with ValidateDir and RenderTriadSummary
• Conservation laws: Balanced skill sets satisfy ∑ trits ≡ 0 (mod 3) for triadic harmony

See /Users/bob/i/boxxy/internal/skill/ for implementation.

Part 12: Formal Specification (Dafny)

A complete formal specification of the agentskills spec is maintained in AgentSkills.dfy with predicates for:

• Name validation (IsValidSkillName)
• Description constraints (IsValidDescription)
• Frontmatter structure (IsValidFrontmatter)
• Directory layout (IsValidSkillDirectory)
• Progressive disclosure (IsValidLevel1, IsValidLevel2, IsValidLevel3)
• Complete skill validity (IsValidCompleteSkill)

Every predicate translates 1:1 to Go validation logic in boxxy/internal/skill/skill.go, verified by exhaustive unit tests.

References

• Official Spec: https://agentskills.io/specification
• Skills CLI: https://github.com/agentskills/agentskills
• Example Skills: https://github.com/anthropics/skills
• Boxxy Implementation: https://github.com/bmorphism/boxxy
• Dafny Spec: verified/AgentSkills.dfy (this repo)

Troubleshooting

My skill fails validation

1. Check SKILL.md formatting: ensure it starts with --- on its own line
2. Validate name: lowercase, no leading/trailing/consecutive hyphens, matches directory
3. Check YAML: use python3 -c "import yaml; yaml.safe_load(open('SKILL.md'))" to debug
4. Frontmatter fields: only use name, description, license, compatibility, metadata, allowed-tools

Body exceeds 500 lines

Split content: move detailed guides to references/GUIDE.md, scripts to scripts/, and keep SKILL.md focused on quick start and key concepts.

Agents don't find my skill

Ensure the skill directory name matches the name field exactly (both kebab-case). Run skills-ref validate ./your-skill to confirm.

Unicode/encoding issues

Ensure SKILL.md is UTF-8 encoded. Use NFKC normalization for the name field.

This skill is self-validating: it teaches agents to read skills, and it is itself a valid skill according to this specification. ✓