english/.opencode/skills/skill-creator/references/skill-anatomy-and-requirements.md

Skill Anatomy & Requirements

Directory Structure

.opencode/skills/
└── skill-name/
    ├── SKILL.md          (required, <300 lines)
    │   ├── YAML frontmatter (name, description required)
    │   └── Markdown instructions
    └── Bundled Resources (optional)
        ├── scripts/      Executable code (Python/Node.js)
        ├── references/   Docs loaded into context as needed
        ├── agents/       Eval agent templates (grader, comparator, analyzer)
        └── assets/       Files used in output (templates, etc.)

Core Requirements

• SKILL.md: <300 lines. Concise quick-reference guide.
• References: <300 lines each. Split by logical boundaries.
• Scripts: No length limit. Must have tests. Must work cross-platform.
• Description: <200 chars. Specific triggers, not generic.
• Consolidation: Related topics combined (e.g., cloudflare+docker → devops)
• No duplication: Info lives in ONE place (SKILL.md OR references, not both)

SKILL.md Frontmatter

---
name: kebab-case-name  # optional namespace: ck:kebab-case-name
description: Under 200 chars, specific triggers and use cases
license: Optional
version: Optional
---

Metadata quality determines auto-activation. See references/metadata-quality-criteria.md.

Scripts (scripts/)

• Deterministic code for repeated tasks
• Prefer: Python or Node.js (Windows-compatible)
• Avoid: Bash scripts
• Required: Tests that pass, .env.example, requirements.txt/package.json
• Env hierarchy: process.env > skill .env > shared .env > global .env
• Token-efficient: executed without loading into context

See references/script-quality-criteria.md for full criteria.

References (references/)

• Documentation loaded as-needed into context
• Use cases: schemas, APIs, workflows, cheatsheets, domain knowledge
• Best practice: Split >300 lines into multiple files
• Include grep patterns in SKILL.md for discoverability
• Practical instructions, not educational documentation

Assets (assets/)

• Files used in output, NOT loaded into context
• Use cases: templates, images, icons, boilerplate, fonts
• Separates output resources from documentation

Progressive Disclosure

Three-level loading for context efficiency:

1. Metadata (~200 chars) — always in context
2. SKILL.md body (<300 lines) — when skill triggers
3. Bundled resources — as needed (scripts: unlimited, execute without loading)

Writing Style

• Imperative form: "To accomplish X, do Y"
• Third-person metadata: "This skill should be used when..."
• Concise: Sacrifice grammar for brevity in references
• Practical: Teach how to do tasks, not what tools are