perongh/better-skill-creator

Better Skill Creator

What a Skill Is

A skill is a reusable package of instructions and optional resources for a recurring kind of task. It can change the model's defaults, bundle a workflow, or provide scripts, references, and assets that make the work more reliable.

What a Skill Is Not

• Not a dump of background knowledge. Put niche detail in bundled references/ files, not the SKILL.md body.
• Not a tutorial. Don't teach; configure.
• Not exhaustive. If a line doesn't change behavior, it's wasted tokens.

Writing a Skill

Frontmatter

---
name: skill-name
description: "When to trigger. Keep it broad — one sentence."
---

• description is the trigger. Put all "when to use" information there: what the skill does and the situations that should trigger it. Make it broad enough that it fires whenever relevant. The model undertriggers — err on the side of pushy.
• Use lowercase letters, digits, and hyphens for name. Keep it short. Name the folder exactly after the skill name.

Body

The model has senior-level knowledge but generic habits. Every line in SKILL.md should change behavior, reduce repeated work, or point to the right bundled resource. Cut everything else.

• State what you want directly. Don't explain why unless the "why" changes behavior.
• Prefer imperative sentences. "Use X" not "You should consider using X".
• If a section has one sentence, it doesn't need a heading — fold it into a neighbor.
• One example is worth including only if the convention is ambiguous without it. Zero is usually fine.

Size

Ideal SKILL.md is under 100 lines. Hard limit for SKILL.md itself is 200 lines.

Bundled Resources

A skill can include more than SKILL.md:

skill-name/
├── SKILL.md
├── scripts/      — deterministic/repetitive tasks
├── references/   — niche knowledge the model lacks
└── assets/       — templates, fonts, etc.

SKILL.md stays short. Put detail in bundled resources and link reference files directly from SKILL.md. Avoid deep chains.

Exclusions

• Do not add auxiliary docs like README.md, CHANGELOG.md, or installation notes.