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.

Core principle

Write each piece of information with the least text that still preserves every rule, constraint, edge case, and intent. Two directions, equally binding:

• Cut duplication, filler, and anything restatable more briefly.
• Never drop text whose removal loses information or instruction, just to be shorter.

Recurring reflex: "Can this exact rule be said in fewer words?" — if yes, do it.

Compaction counts words and information density, not whitespace. Blank lines between distinct chunks cost effectively nothing and aid the human reader, so keep them where they help; never collapse a long passage into one dense block to look shorter.

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 deliberately (e.g. a /command). No trigger bait; the description just states what it does so a human choosing from a list understands it.
• 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.

Agnosticism

• Agent-agnostic — hard rule. Say "the agent" / "the session"; never vendor names ("Claude Code", "Claude", etc.). When improving a skill, flag and fix violations.
• 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.

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."

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; if a question can be answered by exploring the codebase, explore instead of asking. Scale depth to complexity (complex skill → more questions; simple → few). The only limit: never interview for its own sake.
3. Metadata. Always include the frontmatter fields; never hardcode their values. Creating: infer defaults from context (sibling SKILL.md files, git config user.name, repo LICENSE), ask the user to confirm or override, and start version at "1.0". Improving: preserve existing fields, and flag any missing one.
4. Draft (create) or improve (existing). A first draft already meets the compaction standard — the core-principle reflex applies to new skills as much as to edits; don't ship a loose draft expecting a later pass to tighten it. Improving cuts redundancy and adds or clarifies where the skill is vague, under-specified, or missing a rule — loop back to intake for more questions if gaps surface.
5. Self-review before presenting (terse yes/no checks):
   • Every original rule/intent still present?
   • Wording agent-agnostic? Project coupling contained?
   • Trigger type identified, and the description written to fit it? Then test the description: reading only it, would an agent open the skill for the intended task (must be yes) and skip it for a similar but unrelated task (must be no)? Reword until both hold.
   • Duplication/filler gone, and every surviving rule in the fewest words — tight phrasing, not just free of redundancy? (Create and improve alike.)
   • Removal audit against the rendered diff, not memory: read every removed line — and every reordered or merged one, which count as removals — and confirm each drops only duplication or filler, never a rule, instruction, edge case, or nuance. After a merge, re-verify the result still carries every item from both sources.
6. Present & confirm. Show the proposed change as a diff with a word/token delta measured from the files (e.g. wc -w before vs. after — never estimated). In improve mode the same prompt must also ask whether to bump the version — never apply a skill edit without putting the version-bump decision to the user. If the version was already raised since the last commit, fold the change into that pending bump rather than bump again. Apply only on approval. Label the diff as not yet applied and awaiting approval, and after applying say so plainly.