authoring-skills
Skill0 starsChanged 53 days agoMITView on GitHub
Use when creating new skills, editing existing skills, or verifying a skill works before deployment. Applies TDD to process documentation — pressure-scenario baselines (RED), minimal skill (GREEN), loophole closing (REFACTOR) — plus the mechanics of frontmatter, invocation, and file structure.
9 other projects use a version of this.
Adopted by
Most recently taken up by
- roronoazoroshao369/vibe-coding-ostheir own version, first seen Nov 15, 2026
- PuntoyComaTech/hermes-agent-squadstheir own version, first seen Nov 1, 2026
- LucasDevKid9/collab-chartertheir own version, first seen Nov 1, 2026
- syntropic137/software-leverage-pointstheir own version, first seen Oct 14, 2026
- flutter/devtoolstheir own version, first seen Oct 9, 2026
- vercel/next.jstheir own version, first seen May 14, 2026
Other versions9 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 9
- vercel/next.js★ 144ksame name
- flutter/devtools★ 1.7ksame name
- andrueandersoncs/claude-skill-authoring-skill★ 11same name
- PuntoyComaTech/hermes-agent-squads★ 3same name
- LucasDevKid9/collab-charter★ 1same name
- roronoazoroshao369/vibe-coding-os★ 1same name
- forsonny/DG-Anvil★ 0same name
- larsch/skills★ 0same name
- syntropic137/software-leverage-points★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository12 other files it gives its agents.
- completion-gateSkill
- deep-researchSkill
- design-interviewSkill
- domain-glossarySkill
- dual-axis-reviewSkill
- finish-handoffSkill
- hypothesis-debuggingSkill
- seam-designSkill
- seam-driven-tddSkill
- tracer-planSkill
- using-waypowerSkill
- waymapSkill
The file
We split this skill into the rules it gives an agent
2 rules. 0 are common, 2 are distinctive, and 0 are very specific to this project.
0
Common
Most of the 8 edited versions we read keep these.
2
Distinctive
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 10
Core principle: if you didn't watch an agent fail without the skill, you don't know the skill teaches the right thing.
- Distinctive: line 38
Write the smallest skill that addresses the observed failures.
“Common” is measured: kept by at least 6 in 10 of the 8 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Authoring Skills
Writing skills is TDD applied to process documentation: write pressure scenarios (test cases), watch agents fail without the skill (RED), write the skill (GREEN), close loopholes (REFACTOR). Two fused halves: the testing methodology and the mechanics of how a skill is built and invoked.
Core principle: if you didn't watch an agent fail without the skill, you don't know the skill teaches the right thing.
When to Create a Skill
Create when: the technique wasn't intuitively obvious; you'd reference it again across projects; it applies broadly; others would benefit.
Don't create for: one-off solutions; standard practices documented elsewhere; project-specific conventions (those go in AGENTS.md); mechanically enforceable constraints (automate those — documentation is for judgment calls).
Mechanics
File structure. Flat namespace: skills/<skill-name>/SKILL.md (required), supporting files only when needed (heavy reference, tools). Every skill lives in one searchable namespace.
Frontmatter. YAML with name (letters, numbers, hyphens) and description (max 1024 chars). The description is the skill's top-level context pointer — always loaded, so every word earns its place: front-load the leading word, one trigger per branch (synonyms collapse into one), cut identity the body already carries.
Invocation choice. A model-invoked skill keeps a model-facing description ("Use when…" plus specific triggers, third person) so agents fire it autonomously — waypower's process skills. A user-invoked skill sets disable-model-invocation: true; its description becomes a human-facing one-liner — waypower's tool skills. Pick model-invocation only when the agent, or another skill, must reach it on its own.
Progressive disclosure. Inline what every branch needs; push behind a pointer what only some branches need. One excellent example beats five mediocre ones — no multi-language example dilution.
Writing rules. Single source of truth per meaning; prune no-op sentences (if deleting the sentence changes nothing versus the model's default behavior, delete it); prompt the positive, not the negation; recruit leading words the model already knows instead of coining new ones.
The TDD Loop for Skills
RED — baseline without the skill
Write pressure scenarios. For discipline skills combine 3+ pressures (time, sunk cost, authority, exhaustion). Run each with a sub-agent that has NOT seen the skill and document the exact rationalizations verbatim — they are the skill's requirements. Store scenarios in evals/evals.json beside the skill: happy-path, temptation, positive trigger, negative trigger.
GREEN — minimal skill
Write the smallest skill that addresses the observed failures. Match the guidance form to the failure type: checklist for skipped steps, rationalization table for excuses, red-flags list for bright-line violations. Run the same scenarios WITH the skill; the agent complies.
REFACTOR — close loopholes
New rationalizations appear under the skill. Add explicit counters, build the rationalization table from all test iterations, finish with a red-flags list. Re-test until bulletproof.
Eval Run Mechanics (waypower conventions)
- Paired runs: baseline vs with-skill sub-agents on the same temptation scenario, graded per expectation, no partial credit.
- Cap reply length on temptation runs — long unbounded replies time out.
- With-skill agents read only their SKILL.md first; expect a long first read to truncate mid-file, so the agent must page the remainder before answering.
- Baselines under "just do it" pressure take real side effects (scaffolding, file writes, dev servers). Run them in a scratch copy of the workspace, or verify and clean up afterward.
- An agent quoting the skill's own red flags back is evidence the loop worked.
- Structural gate:
node scripts/validate-evals.mjs(from the pack root) validates every skill'sevals.jsonshape — run it before shipping a skill change; CI runs it onskills/**PRs.
Anti-Patterns
- ❌ Narrative examples ("in session 2025-10-03 we found…") — too specific, not reusable
- ❌ Multi-language example dilution — one excellent example, one language
- ❌ Generic labels (
helper1,step3) — labels carry semantics - ❌ Batching: writing several skills and testing none — each skill completes RED-GREEN-REFACTOR before the next ships
Common Rationalizations
| Excuse | Reality |
| "I know agents will comply — skip the baseline" | You don't know; you hope. The baseline is where the skill's requirements come from. |
| "Batching skills is more efficient" | Deploying untested skills is deploying untested code. One at a time through the loop. |
| "The description can list every synonym for safety" | Synonyms are one branch written twice — always-loaded context spent for zero trigger gain. |
| "This project convention deserves a skill" | Conventions belong in AGENTS.md; skills are cross-project technique. |
| "More examples means more helpful" | Dilution. One excellent example; the rest is maintenance burden. |
| "We'll test after the batch ships" | The baseline precedes the skill; 'later' inverts RED-GREEN-REFACTOR. |
Red Flags — STOP
- Writing a skill body before a baseline failure is documented verbatim
- "Agents would never fall for that" — an untested assumption about behavior
- Description stuffed with synonyms, or written in first person
- Moving to the next skill before this one passes its temptation scenario
Completion Checklist
Feeds completion-gate; never replaces it:
- Baseline failures documented verbatim (RED)
- Skill addresses exactly those failures and passes the same scenarios (GREEN)
- Rationalization table + red flags built from test iterations (REFACTOR)
- Frontmatter valid; invocation choice deliberate; one trigger per branch
evals/evals.jsonholds happy-path, temptation, positive and negative trigger scenarios
In Waypower
This skill built the pack itself: every waypower skill carries an evals/evals.json produced by this loop, and the release gate is "all gates fire in every temptation run." Skill vocabulary (process vs tool skill, trigger branch) lives in the project CONTEXT.md, owned by domain-glossary. For agent-facing documents beyond skills (AGENTS.md, router skills), see the compatible companion writing-for-agents.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

