ComeOnOliver Agent Skill Creator Standard
Priority: P0 — Apply to ALL skills
Maximize info/token ratio. Every line in SKILL.md competes for context window space.
Three-Level Loading System
- Level 1 Frontmatter (always in context): name + description, ~100 words max
- Level 2 SKILL.md body (triggered): core rules, ≤100 lines
- Level 3 references/ (on demand): detailed examples, schemas, deep-dives
Workflow (New or Existing Skill)
New skill:
- Capture intent — what does it do, when does it trigger, expected output format?
- Write SKILL.md — draft using TEMPLATE.md
- Test — spawn parallel subagents: one with-skill, one without-skill (baseline)
- Evaluate — grade assertions, review benchmark (pass rate, tokens, time)
- Iterate — rewrite based on feedback, rerun into next iteration dir, repeat
- Optimize description — run trigger eval queries, target ≥80% accuracy
Existing skill:
- Audit — run Quality Checklist below; identify violations
- Snapshot —
cp -r <skill-dir> <workspace>/skill-snapshot/before any edits - Improve SKILL.md — fix violations, compress, move oversized content to
references/ - Test — spawn parallel subagents: one with-new-skill, one with-snapshot (baseline)
- Evaluate & iterate — same as steps 4–5 above
- Optimize description — re-run trigger eval if description changed
See Eval Workflow for full testing + iteration details.
Writing Rules
- Imperative compression: verbs first, drop articles. Bullets > paragraphs.
- Structure order: Priority → Core Rules → Anti-Patterns → References
- Descriptions: push trigger contexts into frontmatter; list edge cases; be "pushy"
- Anti-pattern format:
**No X**: Do Y.≤15 words total
Anti-Patterns
- No long code blocks: >10 lines → extract to
references/ - No redundancy: don't repeat frontmatter content in body
- No YAML bloat: embed all trigger context in
description— no separatekeywords:arrays. Two styles:- File/keyword triggers:
description: "... (triggers: SKILL.md, *.ext)" - Conversational triggers:
description: "... Use when the user says 'run X' or 'I want to Y'"
- File/keyword triggers:
- No packaging: skip Python packaging steps; distribute as folder directly
Quality Checklist
- SKILL.md ≤100 lines
- No inline code block >10 lines
- Description lists specific triggers, is "pushy"
- All references linked with load conditions
- Eval cases written in
evals/evals.json - Trigger rate ≥80% on should-trigger queries
References
- Skill Template — start here for new skills
- Anti-Patterns Detail — format guide + verbose examples
- Size & Limits — exact line budgets
- Resource Organization — scripts/, references/, assets/ rules
- Testing & Trigger Rate — evals, should-trigger queries, optimization loop
- Eval Workflow — test execution, benchmark, iteration, description optimization
- Full Lifecycle — phases 1–5, validation checklist