/compact-skill-creator

name: compact-skill-creator
description: Author or refine a skill for maximum token economy without losing intent. Use when creating any new skill or editing an existing `SKILL.md`.
allowed-tools: Read, Write, Edit, Glob, Grep, Bash
license: MIT
metadata:
  version: "1.25"

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](../compact-docs-writer/SKILL.md), 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