common-skill-creator

name	common-skill-creator
description	Standards for creating, testing, and optimizing Agent Skills for any AI Agent (Claude, Cursor, Windsurf, Copilot). Use when: writing SKILL.md, auditing a skill, improving trigger accuracy, checking size limits, structuring references/, writing anti-patterns, starting a new skill from scratch, or reviewing skill quality.

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:

1. Capture intent — what does it do, when does it trigger, expected output format?
2. Write SKILL.md — draft using TEMPLATE.md
3. Test — spawn parallel subagents: one with-skill, one without-skill (baseline)
4. Evaluate — grade assertions, review benchmark (pass rate, tokens, time)
5. Iterate — rewrite based on feedback, rerun into next iteration dir, repeat
6. Optimize description — run trigger eval queries, target ≥80% accuracy

Existing skill:

1. Audit — run Quality Checklist below; identify violations
2. Snapshot — cp -r <skill-dir> <workspace>/skill-snapshot/ before any edits
3. Improve SKILL.md — fix violations, compress, move oversized content to references/
4. Test — spawn parallel subagents: one with-new-skill, one with-snapshot (baseline)
5. Evaluate & iterate — same as steps 4–5 above
6. 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 separate keywords: 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'"
• 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