Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Browser & automation

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-creator

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

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

Read the complete source ↗