writing-skills

Writing Skills

Overview

Skills are the building blocks of this system. A well-written skill makes AI assistants genuinely better. A poorly-written skill adds noise.

Core principle: If following the skill doesn't produce measurably better results, the skill shouldn't exist.

Master reference: All skills inherit from _rules/SKILL.md. Read it before writing any skill.

The Iron Law

EVERY SKILL MUST HAVE A CLEAR IRON LAW, DEFINED ACTIVATION CONDITIONS, AND A VERIFIABLE PROCESS.

When to Use

• Creating a new skill for the library
• Enhancing an existing skill
• Reviewing a skill's quality
• Standardizing skill format

When NOT to Use

• Applying an existing skill (use using-skills)
• The intended behavior is better captured as a workflow, not a skill
• The behavior is a one-off checklist, not a repeatable process

Anti-Shortcut Rules

YOU CANNOT:
- Create a skill without an Iron Law -- if it has no non-negotiable rule, it's advice, not a skill
- Write "Use when..." descriptions that are vague -- "Use when coding" activates for everything
- Include "it depends" in a skill -- skills are prescriptive, not suggestive
- Skip the Common Rationalizations section -- every process has excuses people make to skip it
- Write a process with vague steps -- "make sure it's good" is not a verifiable step
- Create a skill that duplicates another skill's scope -- check existing skills first
- Skip the Anti-Shortcut Rules -- they prevent the most common ways the skill gets bypassed
- Write Iron Questions that can be answered without evidence -- "Did you check?" != "What was the output?"
- Omit the Red Flags section -- without observable violation indicators, the skill cannot self-enforce
- Skip the Integration section -- isolated skills are broken skills

Common Rationalizations (Don't Accept These)

Rationalization	Reality
"This skill is too short to need all sections"	Short skills still need structure. Sections prevent shortcuts.
"The process is self-explanatory"	To you, maybe. To an LLM following instructions literally, no.
"Iron Questions are overkill"	They're the accountability mechanism. Without them, skills get skipped.
"Not every skill needs rationalizations"	Every process has excuses for skipping it. Document them.
"I'll add the missing sections later"	Later never comes. Complete the skill now.
"This is a simple skill"	Simple skills with poor structure produce poor results.
"I'll just copy another skill and modify it"	Copying without understanding produces cargo-cult skills. Understand the WHY.
"The Red Flags are obvious"	If they were obvious, people wouldn't violate them. Write them down.