78 lines
2.7 KiB
Markdown
78 lines
2.7 KiB
Markdown
# 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
|
|
|
|
```yaml
|
|
---
|
|
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
|