CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

moo-authoring

Use when adding or changing a skill, hook, or runtime file in this repo — including deciding which unit a new capability should be.

Quality

72%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./.claude/skills/moo-authoring/SKILL.md
SKILL.md
Quality
Evals
Security

Doctrine for authoring moo's own surfaces.

Frontmatter

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.

Sizing

  • Size a skill by a deletion pass using a /reduce loop, never a numeric cap.
  • Decision tables > prose explanations.

Efficiency

  • Challenge every sentence: "Does Claude need this?"
  • Bullets for enumerable items; a paragraph when the point is one connected argument.
  • No vague terminology; pick one term per concept.

Skill Design

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 aloneSkill
A trigger only the human perceivesSkill with disable-model-invocation: true
Behavior that must run every time, deterministicallyFunction hook aka claude code mods
An unproven ideahunch skill + HYPOTHESIS.md; graduates or dies
Doctrine for this repo's own surfacesRepo-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:

  • Skills compose by name: a composer names a move and invokes it with the Skill tool; a body never inlines another body.
  • New skill when the cognitive mode changes (clarify WHAT ≠ decide HOW ≠ judge unsupervised work; find ≠ fix). One skill = one mode + one gate.
  • Two skills over one when triggers differ; a shared explanation the pair needs lives in this file, which owns skill-design reasoning, not in either skill.
  • A body names a sibling in exactly two places: a refusal, and a route — wherever in the body those sit. There the name is the refusal's or the route's content, and a reader without it is stranded.
  • Ending over hand-off: a finished run states what is now settled and what is still open, in its own words. Naming who handles it next hardcodes the graph n², so one trigger change edits every sibling.

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 forUnlessThe turn carries
What only they hold — what they want, their reasons, taste and limits, what they understandA wrong guess costs less to undo than the question costs: state it, they correct itWhat 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 undoneTheir words, this session or recorded in reach, authorize that act and its contentThe 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 backBound it by
Something the agent restated in its own wordsAs 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 proposalPreserving them. A compression clause here destroys the result
A structure the reader navigates — verdict then evidence, a case set then a ruleBounding 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.

Hook Design

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.

  • A hook never starts a turn the human didn't ask for: no wake, no $.prompt.submit of its own.
  • What a hook finds waits where the human looks next, the band above the prompt, and appears there only while it holds something. Detail unfolds on a press and folds back. Exception: a band whose absence would read as "nothing running", as hum's does in a repo where hum serves, is always one row there.
  • A hook hands to Claude only on the human's Enter: $.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.
  • Two event sets are closed to a hook. On Team, Enterprise and managed machines, Claude Code's built-in guard, 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.
  • Work longer than one dispatch runs unawaited, so the turn's end is never held.
  • State lives in $.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.
  • A failure shows once, as a toast, and the event passes on. Exception: CLAUDE.md's answer-hook rule.
  • A pane or band is verified on events copied from real session transcripts, one per shape it renders; a synthetic event alone never verifies it.
  • One hooks module per plugin; a second part composes into it. A second registration on the same event and matcher in one plugin fails the module's load: give one a matcher, as slop's 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.

Repository

saadshahd/moo.md

Path

.claude/skills/moo-authoring/SKILL.md

Last updated
First committed

Is this your skill?

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.