write-best-practice-skill

Write Skill

Author a new grimoire SKILL.md that encodes a domain best practice and passes review-best-practice-skill.

Why This Is Best Practice

Adopted by: Structured authoring guides are standard in high-quality OSS knowledge projects — Wikipedia's Manual of Style, MDN Web Docs contributor guide, and all major package registries provide explicit authoring templates to maintain quality at scale. Impact: Defects caught at authoring time cost 5–10× less to fix than those caught at review — a principle established in software engineering (Boehm, Software Engineering Economics, 1981) that applies equally to knowledge contributions. Wikipedia's Manual of Style, applied at authoring time, contributes to Featured Articles achieving measurably higher quality benchmarks (citation density, edit stability) than non-featured articles — a direct effect of structured authoring criteria applied before submission. Why best: An explicit authoring guide — vs. ad-hoc contribution where authors discover requirements through reviewer rejection — eliminates the most common failure modes (vague "Adopted by", missing impact numbers, over-scoped skills) before a reviewer ever sees the file.

Sources: Wikipedia Manual of Style, MDN Web Docs Contributor Guide, Boehm (Software Engineering Economics, 1981)

Steps

1. Verify the practice qualifies

Before writing a single line, confirm all four gates:

• Majority adoption: adopted by MOST top-tier companies or credentialed professionals — not just a few notable ones, not your team's approach
• Measurable impact: strong demonstrated outcome (%, time saved, defect reduction, risk reduction) — "helps" or "improves" without numbers fails this gate
• No duplicate: run suggest-best-practice with your topic first — if a skill already covers it, extend that skill instead of creating a duplicate
• No genuine controversy: if credible top-tier professionals are split ~50/50, there is no consensus and therefore no best practice — skip it

If any gate fails, stop. Writing a skill that doesn't qualify wastes reviewer time.

2. Pick the name

Follow the full naming standard in STANDARD.md. Key rules:

• Pattern: <verb>-<subject>[-<qualifier>]
• Verb must be imperative and specific — use the approved verb table; reject handle-, manage-, improve-, get-, use-, help-
• Subject must be specific — if "which kind?" is a valid follow-up, it's too generic
• Qualifier only when verb-subject collides across domains
• Kebab-case, ≤50 characters, no skill-/guide- prefix
• One concept only — if you need "and" in the name, it's two skills

❌ handle-deployment        → rejected verb
✅ diagnose-deployment-failure

❌ improve-code             → rejected verb + generic subject
✅ optimize-query-latency

❌ code-review              → noun-first
✅ review-pull-request

3. Find credible sources

The source field must be verifiable. Match source type to domain:

Domain	Qualifying sources
Engineering	Google Engineering Practices, Netflix/Stripe/AWS engineering blogs
Health	WHO guidelines, Mayo Clinic, NIH, ACSM, NSCA position stands
Finance	CFA Institute, Bridgewater, Goldman Sachs frameworks
Law	ABA Model Rules, BigLaw practice standards, ISDA/NVCA model agreements
Business	McKinsey/BCG/Bain frameworks, HBS/INSEAD curriculum
Design	Apple HIG, Material Design, Nielsen Norman Group
Sports	NSCA CSCS, USA Weightlifting, Olympic coaching methodology

Failing source examples: "industry standard", "widely known", "common practice".

4. Write the frontmatter

---
name: write-best-practice-skill
description: Use when <triggering conditions — NOT a summary of the steps>.
source: <institution, standard body, or top-tier company list>
tags: [problem-keyword-1, problem-keyword-2, problem-keyword-3]
---

description check: does it start with "Use when"? Does it describe WHEN to use it, not WHAT it does? Could you answer "I have this problem, should I use this skill?" by reading it? If yes, it's correct.

tags check: cover all 4 axes — problem keyword (injury-prevention), tool/method (progressive-overload), role/context (athlete), outcome (strength-gain). Not domain names (health, engineering). 3–8 tags, lowercase kebab-case.

5. Write ## Why This Is Best Practice

This is the most scrutinized section. All four sub-fields are required:

## Why This Is Best Practice

**Adopted by:** [Specific companies or institutions — not "many companies"]
**Impact:** [Measurable outcome with cited evidence — not "significantly better"]
**Why best:** [Why this over alternatives — name the alternatives]

Sources: [Verifiable citation — institution, study, engineering blog]

Adopted by checklist:

• Names at least 2 specific companies or 1 named institution
• Claims majority adoption, not just notable adoption
• A domain expert would agree this is the majority position

Impact checklist:

• Contains a number (%, ratio, time) OR cites a named study
• The outcome is causal, not just correlated
• Not "significantly better" or "much faster" without data

Why best checklist:

• Names at least one alternative approach
• Explains why this approach wins over that alternative
• Not just "this is good" — argues why

6. Write ## Steps

Steps must be immediately executable — the reader can follow them right now.

• Concrete: "Run git diff --cached" not "check your changes"
• Commandable: every step is an action, not a description
• Complete: includes what to do when something fails or is ambiguous
• Specific: names the actual tool, shows the actual command or output

Size check: 50–300 lines total. Under 50 = too shallow. Over 300 = split into two skills.

7. Add domain safety footer (if applicable)

Domain	Required footer
Health / Medicine	> For personal health decisions, consult a qualified healthcare provider.
Law	> This is educational content, not legal advice. Consult qualified legal counsel for your situation.
Finance / Investing	> This is educational content, not financial advice. Consult a licensed financial advisor for personal decisions.
Psychology / Mental Health	> For mental health concerns, consult a qualified mental health professional.

8. Run review-best-practice-skill

Invoke review-best-practice-skill on your draft file.

Revision gate before PR: Before creating a PR or outputting the final SKILL.md, run review-best-practice-skill against the draft. If the review produces REJECT or NEEDS-REVISION findings, fix them before proceeding. Do not submit a skill that fails its own quality gate.

Fix every REJECT and NEEDS-REVISION finding until the verdict is PASS.

Common first-draft failures:

• "Adopted by" says "many companies" → name them
• "Impact" says "significantly improves" → cite the study or the number
• Steps describe concepts instead of actions → rewrite as commands
• Skill covers two separable concepts → split into two skills

9. Register in SKILLS.md

Add a one-line entry to SKILLS.md in the correct domain section and subsection, in alphabetical order among peers:

- [`skill-name`](./skills/<domain>/<subdomain>/skills/<skill-name>/) — <description field verbatim>

SKILLS.md entry format: When adding the skill to SKILLS.md, use this format:

| skill-name | domain/subdomain | One sentence: what problem it solves | [source-author, year] |

The description column must complete the sentence 'Use this when...' and reference the triggering situation, not the skill's method.

Then increment the domain count in the section header:

## Domain (N) → ## Domain (N+1)

If the subdomain does not yet exist in SKILLS.md, add a ### subdomain header in alphabetical order within the domain section before the entry.

Rules

• Run suggest-best-practice first — never create a duplicate
• Verify majority top-tier adoption before writing anything
• description field describes triggering conditions ONLY — no workflow summary
• Must pass review-best-practice-skill before opening a PR
• If contested 50/50 among top-tier, do not write the skill

Common Mistakes

Over-scoping: "nutrition and training program" — two separable concepts, two skills.

Vague adoption: "Used by top companies and professionals in the field" — this fails the Adopted by check. Name Google, Netflix, Mayo Clinic, CFA Institute — specific names.

Missing impact number: "Code review reduces defects" — passes. "Code review helps code quality" — fails. Always find the study or internal data with a number.

Description summarizes workflow: "Use when writing a skill — checks frontmatter, writes steps, runs review." — WRONG. Correct: "Use when authoring a new SKILL.md to contribute to grimoire."

Skill for one team's approach: your company uses Terraform — that's not a grimoire skill unless it's majority adoption across the industry.