Agent-Skills.md

Agent Skills: Agent Skill Creator Standard

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.

UncategorizedID: hoangnguyen0403/agent-skills-standard/common-skill-creator

Repository

hoangnguyen0403/agent-skills-standard
HoangNguyen0403License: Apache-2.0
362103

Install this agent skill to your local

pnpm dlx add-skill https://github.com/HoangNguyen0403/agent-skills-standard/tree/HEAD/.agent/skills/common/common-skill-creator

Skill Files

Browse the full folder contents for common-skill-creator.

Download Skill

Loading file tree…

.agent/skills/common/common-skill-creator/SKILL.md

Skill Metadata

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