Use when adding or changing a skill, hook, or runtime file in this repo — including deciding which unit a new capability should be.
72%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
Passed
No findings from the security scan
Fix and improve this skill with Tessl
tessl review fix ./.claude/skills/moo-authoring/SKILL.mdDoctrine for authoring moo's own surfaces.
No when_to_use.
A condition that follows what the skill does is marked Use when <condition>.
A description may also open with the condition and stop there, where naming the capability would discriminate nothing.
A skill that stays in this repo declares metadata.internal: true.
Version lives in plugin.json only. Claude Code spec does not allow version in SKILL.md frontmatter.
Phrase design decisions as "X over Y: reason".
Unit choice — behavior inlines at build, data references at runtime; a skill's firing is probabilistic, so behavior that must run every time is a hook:
| The new thing is... | Unit |
|---|---|
| Data selected per use (catalog, profile, corpus) | Runtime file |
| A trigger + procedure that stands alone | Skill |
| A trigger only the human perceives | Skill with disable-model-invocation: true |
| Behavior that must run every time, deterministically | Function hook aka claude code mods |
| An unproven idea | hunch skill + HYPOTHESIS.md; graduates or dies |
| Doctrine for this repo's own surfaces | Repo-local skill in .claude/skills/; never ships |
Before building any unit, count how often its target situation occurs in real session transcripts, and weigh each case by what the miss cost. A rare, cheap situation caps the value whatever the build's accuracy; a planted test prompt proves the mechanism, never the value.
Composition — name-calls, never imports:
Turning to the user — information decides who is asked, never the skill's habit. hope/hooks/reach.ts adds the rule to every session, skill or none, so no skill restates it. A skill's own "ask" beats that rule where the two meet, so each ask a skill states covers only what sources in reach leave open. What stays the user's:
| Turn to the user for | Unless | The turn carries |
|---|---|---|
| What only they hold — what they want, their reasons, taste and limits, what they understand | A wrong guess costs less to undo than the question costs: state it, they correct it | What was read, so they answer only what is left |
| An act only their login or authority can take | — | The work done: values filled, request drafted, one exact step |
| An act that spends their money or time, reaches outside the work, or can't be undone | Their words, this session or recorded in reach, authorize that act and its content | The act ready to run on their yes |
Output form — bound by what the skill hands back, never by one shared sentence. Plain words is the only part that holds across all three:
| The Output hands back | Bound it by |
|---|---|
| Something the agent restated in its own words | As short as it goes with nothing the skill can't afford to drop lost — name that thing, it differs per skill |
| The user's own words — a record, an amended proposal | Preserving them. A compression clause here destroys the result |
| A structure the reader navigates — verdict then evidence, a case set then a rule | Bounding each part where a reader would pad it, never the whole |
A cap counted in lines is a compression budget on a handed-back artifact — replace it. A cap on one turn of a loop is pacing, and the rest arrives on the user's next pull — keep it.
Every hook is a function hook: it reaches the human with no model turn. The API is early access; plugin-authoring and /plugin-types are the reference for every event and call.
$.prompt.submit of its own.$.prompt.fill a sentence start they finish, with any bulk added as prompt.submit context. The one exception is a rule every turn must hold: it rides whichever prompt enters while the conversation lacks it, as reach.ts does.cc-plugin-sec-default, skips every installed plugin on the events that write the prompt, among them prompt.compose, prompt.context, skill.prompt and session.compact. An installed mod on an event that sees tool calls, among them tool.call, tool.check and agent.spawn, keeps Code Mode off. A skill's loaded text is open to both as its session.append row (door tool-message), as hunch's tend reads it.$.state (this session) or $.store (across sessions), never in temp files. Module variables hold only what a hot reload may drop: it drops them. Exception: a read every session in a repo would repeat, as hum's work-source watch, runs once per repo and shares its result through a cache file under a lock with an expiry, kept in the repo's own state folder.prompt.submit does.A hook that spawns headless claude -p copies its flag set from hope/hooks/judge.sh, where each flag is commented at the point of use.
saadshahd/moo.md
2a844a8
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.