Agent Skill Creator Standard

Priority: P0 — Apply to ALL skills

Maximize Token ROI. Every line in SKILL.md must provide specific procedural value. Activation (how it triggers) and Implementation (how it helps) are the primary quality metrics.

Three-Level Loading System

• Level 1 Frontmatter: name + description (Activation Anchor), ≤100 words.
• Level 2 SKILL.md body: Core Rules + Workflows (Implementation Core), ≤100 lines.
• Level 3 references/: Detailed examples, schemas, and "TESTS.md" (On-demand).

Workflow (New or Existing Skill)

New skill:

1. Research — web-search domain best practices, checklists, and standards; extract key terms → triggers, workflows → guidelines, mistakes → anti-patterns. See Web Search Research.
2. Capture intent — what does it do, when does it trigger, expected output format?
3. Write SKILL.md — draft using TEMPLATE.md
4. Test — spawn parallel subagents: one with-skill, one without-skill (baseline)
5. Evaluate — grade assertions, review benchmark (pass rate, tokens, time)
6. Iterate — rewrite based on feedback, rerun into next iteration dir, repeat
7. 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.

Description Quality (Activation)

• Third-Person Voice: Use Standardizes..., Audits..., Encrypts.... Avoid "I will" or "This skill helps to".
• What + When Structure:
  • What: Define 5–8 specific capabilities (e.g., "Generates JWT tokens, rotates keys").
  • When: Explicitly define triggers (e.g., "Use when user says 'rotate keys'").
• Specificity: Avoid vague verbs like "manage" or "handle". Use "Validate", "Inject", "Refactor", "Sanitize".
• Trigger Hint: Include a (triggers: *.ext, keyword) suffix for technical skills.

Content Quality (Implementation)

• No Redundant Knowledge: Do NOT explain concepts the AI already knows (e.g., HTTP status codes, standard library docs, basic SOLID principles). Focus strictly on project-specific rules.
• Actionability: Examples must be copy-paste ready and executable.
• Workflow Clarity: Use sequential ordered lists for multi-step processes.
• Progressive Disclosure: Move code blocks >10 lines to references/.

Anti-Patterns

• No "AI-splaining": Do not explain why a pattern is good unless it's a unique project constraint.
• No Vague Triggers: Never use src/** or **/*. Be surgical.
• No Description Bloat: If a description exceeds 100 words, some capabilities belong in the body.
• No long code blocks: >10 lines → extract to references/
• No redundancy: don't repeat frontmatter content in body

Quality Checklist (Tessl-Aligned)

• Activation ≥ 90%: Description covers both capabilities ("What") and triggers ("When").
• Implementation ≥ 90%: No general-purpose explanations; all examples are executable.
• Structural Compliance: SKILL.md ≤ 100 lines; code blocks moved to references/.
• Trigger rate ≥80% on should-trigger queries.

References

• Skill Template — load when starting a new skill from scratch
• Anti-Patterns Detail — load when fixing or reviewing anti-pattern format
• Size & Limits — load when SKILL.md approaches 100 lines
• Resource Organization — load when deciding where to place content (scripts/, references/, assets/)
• Testing & Trigger Rate — load when writing evals or measuring trigger rate
• Eval Workflow — load when running parallel subagent tests
• Full Lifecycle — load for complete phase-by-phase creation guide
• Web Search Research — load when creating a skill for an unfamiliar or non-engineering domain