Compact Skill Creator

Compact skill creator

Author a new skill, or improve an existing one, so it carries all its rules and intent in the least text possible. Cost has two tiers: the description sits in context every session — the skill's most expensive text — while the body loads only when the skill triggers. Both stay lean. Be interactive: gather what you need, draft, then apply only on approval.

Compaction — always via compact-docs-writer

The compaction rules — the least-text principle, the removal-audit verification, and the present-and-confirm with a measured word delta — live in compact-docs-writer, the single source of truth; this skill never restates or re-derives them. From the moment you draft (step 4) through self-review (step 5) and present (step 6), always invoke compact-docs-writer and follow its workflow on the skill text — reading it, applying its principles by hand, or naming it after a direct edit does not count. This skill adds only the skill-specific layer: trigger taxonomy, agnosticism, progressive disclosure, completion criteria, metadata, and the version bump.

Trigger taxonomy — classify first

How a skill is triggered decides how its description is written. Classify into one:

• Mandatory — must auto-load whenever a task type is touched (e.g. "working on UI components", "dealing with unit tests"). A silent miss defeats its purpose, so the description spends words on a strict, concrete trigger: concrete verbs + the artifact ("when creating, editing, or reviewing …").
• Manual — invoked by name: a /command, or sibling skills/rules that reference it explicitly. The by-name reference does all the routing, so trigger wording buys nothing: the description is one short line of what the skill does — enough for a human choosing from a list — never a body summary, never a "load when …" clause. When the skill format can block model invocation (e.g. a disable-model-invocation flag), set it for Manual skills nothing invokes programmatically — the description then costs no standing context; pair the flag with type: flow — some agents hide flag-bearing skills even from manual invocation without it. When sibling skills must drive this one, keep it model-invocable and mark it "invoke manually only" in the description instead.
• Self-Evident — auto-loadable, but intent is obvious from a natural request (e.g. "fetch a ticket"). Trigger words ≈ the task name, so a short description routes correctly without a when/when-not clause.

Governing rule: description tokens are justified only by trigger precision, never by summary. Compress within a type — but never starve a Mandatory trigger to save a few tokens.

In every type, never use : in the description — : in the unquoted value breaks some agents' YAML parsers; avoid the character rather than quote it.

Three sharpeners for the trigger wording:

• One trigger per distinct path through the skill. Phrasings collapse only when they lead the agent down the same path (true synonyms — "review a branch" / "check changes before merging"); never collapse triggers that name different inputs or modes (a PR link vs a bare branch name).
• The observed error is a trigger path too for a Mandatory or Self-Evident skill that fixes a failure mode: the description names the error the agent hits during other work, in the error's distinctive words, never its whole message.
• Front-load the skill's leading word (see compact-docs-writer). When the description carries the word the user's prompts and docs already use, the agent links that shared language to the skill and fires it more reliably.

Placement corollary: the body loads only after the skill triggers, when the choice is already made — so keep when-to-use and routing cues in the description (read before the choice), never in the body, where they steer nothing.

Agnosticism

• Agent-agnostic — hard rule. Say "the agent" / "the session"; never vendor names ("Claude Code", "Claude", etc.). When improving a skill, flag violations and fix the ones that are framing; a clearly-marked agent-specific mechanism example with a generic fallback (e.g. a memory/config discovery path) is deliberate — flag it at most, never strip it.
• Project-agnostic — best-effort. Default to generic wording. Couple to a project/framework/tool only when the skill's purpose requires it; when you must, keep it explicit and contained — declared up front or in a referenced doc — but skip a standalone declaration when the body already names the coupled artifacts throughout, since restating them only duplicates.
• Tool-agnostic — follow the skill's stance. When a skill operates over an external tool/service with interchangeable equivalents (design tools, trackers, cloud providers, …): if the skill is already agnostic — treating such tools as a class, naming specific ones only as examples — preserve that; new or edited content must stay generic, never hardcode a lone vendor as the sole path. Otherwise it's a nice-to-have: prefer generic wording, and when unsure whether to generalize or couple, ask the user.
• Sibling-decoupled: track dependencies. A skill may be installed with only its declared hard dependencies, not the whole toolkit, so a link to a sibling that isn't a dependency can dangle. Reference another skill only when it's a declared dependency or the link earns its keep operationally (e.g. an actionable next-step handoff); never add orientation prose that merely situates the skill among its siblings. An optional sibling gates its hand-off; gate the artifact feeding it too only when, without the sibling, it isn't worth its run-time cost.

Progressive disclosure — when to split

A skill folder can hold a lean SKILL.md that references supporting .md docs. A referenced doc loads only when the agent follows the pointer — that is the lever.

• Primary criterion: conditional relevance. Extract content needed only in a sub-case (rare branch, long reference table, worked example, framework-specific detail). Keep always-needed instructions inline.
• Size only modulates: large conditional chunks are strong candidates; tiny ones stay inline (a pointer plus a round-trip can cost more than it saves). These are signals, not hard limits.
• Test: "Needed on every invocation, or only in a sub-case — and big enough that inlining taxes every invocation? If both, extract it."
• Every referenced doc links from SKILL.md directly, never only from another referenced doc.

Completion criteria — steps end checkable

When a skill encodes steps, end each on a completion criterion the agent can check — done vs not-done — and make it exhaustive where a partial pass could look complete ("every modified file accounted for", not "produce a summary"). A vague criterion is what makes an agent wrap up early; sharpening it is the first and cheapest fix. Only when a criterion stays irreducibly fuzzy and later steps still tempt rushing should those later steps move out of sight (a follow-on skill or a disclosed doc).

Workflow

1. Detect mode. A path/skill argument → improve; none → create. To create, put the skill in its own folder alongside existing skills, following the project's convention — ask the user if it's unclear; folder name and name field must match, in kebab-case.
2. Intake — interview relentlessly to shared understanding. Before drafting, walk down each branch of the skill's design tree, resolving dependencies between decisions one at a time — never fire a fixed batch of questions once and then draft. Cover at least the purpose, trigger type, and any unavoidable coupling, plus whatever each answer opens up. Ask one question at a time, each with your recommended answer, worded via explain-in-simple-language when available; if a question can be answered by exploring the codebase, explore instead of asking. A skill reading what other skills produce, or stepping into their hand-offs, takes its input types, the options its own hand-off carries on, and the files it must never write from a search of every such skill — never from the one pipeline in mind. Scale depth to complexity (complex skill → more questions; simple → few). The only limit: never interview for its own sake.
3. Metadata. Frontmatter always carries name and description, plus every field the project's conventions or all its sibling skills carry (e.g. a license, metadata.version); per-skill ones (tool grants, invocation flags) follow from the skill's own needs, never copied. Never hardcode values. Creating: infer defaults from context (sibling SKILL.md files, git config user.name, repo LICENSE), ask the user to confirm or override. The first version follows the project's stated convention; none stated → ask "1.0" or a "0.x" trial. Improving: preserve existing fields, and flag any missing one.
4. Draft (create) or improve (existing): get the skill's content right — the rules it encodes, plus what improving adds (clarify where it's vague, under-specified, or missing a rule; loop back to intake if gaps surface) — compacting it through compact-docs-writer as you write, not in a later pass.
5. Self-review before presenting — terse yes/no, skill-specific (compact-docs-writer runs the compaction and removal-audit checks):

   • Wording agent-agnostic? Project coupling contained? Cross-references limited to declared dependencies or a real operational benefit?

   • Trigger type identified, and the description written to fit it? Test it, reading only the description:

     • Mandatory or Self-Evident: write three prompts the skill must fire on and three near misses it must not (a similar task, a different input type) and judge each from the description alone. Manual: would an agent open it for the intended task, and skip a similar but unrelated one?
     • does it match what the skill now does (no stale claim the body contradicts)?
     • does it carry the skill's leading word itself — a paraphrase feels compliant but does no invocation work?

     Reword until all hold.

   • Body consistent with itself? Every "never" checked against each step and source it could forbid; every advertised input type handled by each step that touches it (a check fitting only one type fails the rest); every write surfaced where its reader looks — when a later phase reads only a document derived from the edited one, the addition reaches that one too.

   • Spawns a subagent, reviewer or fork? Its brief and its return are defined: what it receives, what it reports back (paths written, verdicts, blockers, edits made, what it did not check), and that it hands nothing off itself.

   • Creating: hand a fresh agent (a subagent when the tool offers one, else a prompt the user runs in a clean session) only the draft and one realistic input; have it walk the draft dry, writing, committing and posting nothing, narrating step by step and listing each point where the text is ambiguous, contradictory or silent. Each point loops back to draft; done when the run reports none. Improving: offer the run, never require it.

   • No new or grown inline chunk meets the split test (progressive disclosure)?

   • Steps end on checkable, exhaustive completion criteria?

   • scripts/check-skill.sh <skill-dir> passes? While the draft sits in scratch, set CHECK_SKILL_AS=<real folder>. It holds the conventions above that a script can check (wrap, links, frontmatter) and prints the version at HEAD, merge base and working tree for step 6; fix every failure before presenting.

6. Present & confirm through compact-docs-writer (diff + word delta measured from the files, applied only on approval). In improve mode the draft includes a version bump — the last component, unless the author names a value — never a question put to the user. Skip it only when the version was already raised, uncommitted or on the branch against its target, verified from git (version at HEAD and at the merge base vs working tree), never from session memory: the repo may have moved concurrently. A version line saying base unknown or no merge base never reads as "not bumped": resolve the target as self-review does — the upstream remote's default branch when one exists, else origin's, via git ls-remote --symref <remote> HEAD; offline, the sole existing candidate among main, master, develop/development — and rerun the script with CHECK_SKILL_BASE=<ref>; still unknown → ask the user only which branch is the target, never whether to bump. Done when the skill and every place the project catalogs its skills (a README entry, a manifest or dependency list, a relationship graph) carry the change, including any hard dependency a new cross-reference adds; find them by searching the repo for a sibling skill's name.