compact-skill-creator
Author or refine a skill for maximum token economy without losing intent. Use when creating any new skill or editing an existing `SKILL.md`.
eai-org · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add eai-org/agent-toolkit --skill compact-skill-creatorAbout this skill
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.17"
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 decision.
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. adisable-model-invocationflag), set it for Manual skills nothing invokes programmatically — the description then costs no standing context; pair the flag withtype: 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.
Two 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).
- 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