75 lines
1.9 KiB
Markdown
75 lines
1.9 KiB
Markdown
# Token Efficiency Criteria
|
|
|
|
Skills use progressive disclosure to minimize context window usage.
|
|
|
|
## Three-Level Loading
|
|
|
|
1. **Metadata** - Always loaded (~200 chars)
|
|
2. **SKILL.md body** - Loaded when skill triggers (<300 lines)
|
|
3. **Bundled resources** - Loaded as needed (unlimited for scripts)
|
|
|
|
## Size Limits
|
|
|
|
| Resource | Limit | Notes |
|
|
|----------|-------|-------|
|
|
| Description | <200 chars | In YAML frontmatter |
|
|
| SKILL.md | <300 lines | Core instructions only |
|
|
| Each reference file | <300 lines | Split if larger |
|
|
| Scripts | No limit | Executed, not loaded into context |
|
|
|
|
## SKILL.md Content Strategy
|
|
|
|
**Include in SKILL.md:**
|
|
- Purpose (2-3 sentences)
|
|
- When to use (trigger conditions)
|
|
- Quick reference for common workflows
|
|
- Pointers to resources (scripts, references, assets)
|
|
|
|
**Move to references/:**
|
|
- Detailed documentation
|
|
- Database schemas
|
|
- API specs
|
|
- Step-by-step guides
|
|
- Examples and templates
|
|
- Best practices
|
|
|
|
## No Duplication Rule
|
|
|
|
Information lives in ONE place:
|
|
- Either in SKILL.md
|
|
- Or in references/
|
|
|
|
**Bad:** Schema overview in SKILL.md + detailed schema in references/schema.md
|
|
**Good:** Brief mention in SKILL.md + full schema only in references/schema.md
|
|
|
|
## Splitting Large Files
|
|
|
|
If reference exceeds 300 lines, split by logical boundaries:
|
|
|
|
```
|
|
references/
|
|
├── api-endpoints-auth.md # Auth endpoints
|
|
├── api-endpoints-users.md # User endpoints
|
|
├── api-endpoints-payments.md # Payment endpoints
|
|
```
|
|
|
|
Include grep patterns in SKILL.md for discoverability:
|
|
|
|
```markdown
|
|
## API Documentation
|
|
- Auth: `references/api-endpoints-auth.md`
|
|
- Users: `references/api-endpoints-users.md`
|
|
- Payments: `references/api-endpoints-payments.md`
|
|
```
|
|
|
|
## Scripts: Best Token Efficiency
|
|
|
|
Scripts execute without loading into context.
|
|
|
|
**When to use scripts:**
|
|
- Repetitive code patterns
|
|
- Deterministic operations
|
|
- Complex transformations
|
|
|
|
**Example:** PDF rotation via `scripts/rotate_pdf.py` vs rewriting rotation code each time.
|