Skill Specification

Formal specification for evolutionarily robust agent skills.

Why This Matters

Skills that follow the spec work across:

• Claude Code (Anthropic)
• Codex CLI (OpenAI)
• Cursor (Anysphere)
• Amp (Sourcegraph)
• Letta (memGPT)
• Future agents

Non-compliant skills break silently or fail validation.

SKILL.md Schema

---
name: skill-name              # REQUIRED: lowercase, hyphens, 1-64 chars
description: What and when    # REQUIRED: max 1024 chars, no < or >
license: Apache-2.0           # optional
compatibility: Requires git   # optional, max 500 chars
metadata:                     # optional: custom key-value pairs
  trit: 0
  author: bmorphism
  version: "1.0"
allowed-tools: Bash Read      # optional, experimental
---

# Body content (Markdown)

Field Constraints

Field	Required	Rules
name	✓	[a-z0-9-]+, no --, no leading/trailing -, max 64
description	✓	1-1024 chars, no < or >, includes WHEN to use
license	✗	Short name or file reference
compatibility	✗	Environment requirements, max 500
metadata	✗	Arbitrary k:v for custom fields
allowed-tools	✗	Space-delimited tool names

Evolutionary Robustness Patterns

1. Progressive Disclosure

Level 1: name + description (~100 tokens) - loaded at startup
Level 2: SKILL.md body (<5000 tokens) - loaded on activation
Level 3: scripts/, references/, assets/ - loaded on demand

Keep SKILL.md under 500 lines. Move details to references/.

2. Cross-Platform Compatibility

# BAD - platform-specific
allowed-tools: claude_desktop_mcp

# GOOD - generic capability
compatibility: Requires MCP server access

3. Self-Validation Hook

Include validation in your skill:

# scripts/validate.sh
skills-ref validate "$(dirname "$0")/.."

4. Semantic Versioning in Metadata

metadata:
  version: "2.1.0"
  breaking-changes: "v2.0 changed API"

5. Triadic Classification (GF(3) Extension)

For plurigrid/asi skills:

metadata:
  trit: -1   # MINUS: verification, constraint
  trit: 0    # ERGODIC: balance, mediation
  trit: +1   # PLUS: generation, exploration

Conservation: Σ trits ≡ 0 (mod 3) across compositions.

Directory Structure

skill-name/
├── SKILL.md           # Required
├── scripts/           # Executable code
│   └── main.py
├── references/        # Additional docs
│   └── REFERENCE.md
└── assets/            # Static resources
    └── template.json

Validation Commands

# Official validator
skills-ref validate ./my-skill

# Codex-rs validator
python3 codex-rs/core/src/skills/assets/samples/skill-creator/scripts/quick_validate.py ./my-skill

# Batch validate
for d in skills/*/; do skills-ref validate "$d"; done

Common Failures

Error	Fix
No YAML frontmatter	Add --- delimiters
Unexpected keys	Move to metadata:
Angle brackets in description	Remove < and >
Name not hyphen-case	Lowercase, hyphens only
Description too long	Max 1024 chars
YAML colon in value	Quote the string

Evolution Strategy

1. Start minimal - name + description + one paragraph
2. Add scripts/ when automation helps
3. Add references/ when body exceeds 300 lines
4. Add metadata for custom classification
5. Validate on every commit via CI

References

• agentskills.io/specification
• github.com/agentskills/agentskills
• OpenAI Codex Skills
• Claude Code Skills