Skill Creator

Caution

Skills auto-activate only 20–50% of the time. Trigger keywords, description format, and invocation type (user vs. LLM) determine whether Claude ever picks up the skill. A wrong description silently kills auto-activation — and the bug is invisible until you test it.

Tip

Skill Creator encodes every best practice from Anthropic’s official skill docs. It picks the right context mode, writes an activation-optimized description, validates structure, and generates test prompts — so you don’t have to read 1200 lines of agent instructions yourself.

Quick reference

FieldValue
Trigger”create skill”, “new skill”, “skill doesn’t invoke”, “improve skill”, “fix skill trigger”
Modelopus
ToolsRead, Write, Edit, Glob, Grep, Bash, Task, Skill, AskUserQuestion

When to use

  • You want a new Claude Code skill and need correct SKILL.md structure from the start
  • An existing skill isn’t auto-invoking and you need description optimization
  • You want to capture a workflow from the current conversation into a reusable skill
  • You need to choose the right context mode (fork vs inline) or invocation type for a new skill
  • A skill’s bash blocks aren’t executing — missing EXECUTE keyword or $ARGUMENTS in bash context

Examples

"Create a skill for database migrations"
"Claude isn't picking up my skill automatically"
"Turn what we just did into a skill"
"My /deploy skill isn't reliable — fix the description"
"new skill: scan for leaked secrets in git history"

Flow

  1. Understand the request

    If the current conversation contains a workflow the user wants to capture, the agent extracts it from history first — tools used, steps taken, input/output formats, edge cases encountered. Then asks 2–3 clarifying questions: purpose, invocation type, trigger phrases. Pre-filled values from an orchestrator prompt skip the question.

  2. Pick context mode and invocation type

    Critical operations (deploy, commit) get disable-model-invocation: true + slash-only. Background knowledge gets user-invocable: false. Standalone tasks with fewer than 4 phases get context: fork. Multi-phase orchestration stays inline. Model choice follows complexity: opus for orchestration, sonnet for analysis, haiku for simple helpers.

  3. Write SKILL.md with activation-optimized description

    Description follows the template: action verb sentence + explicit Triggers: “phrase1”, “phrase2” on a single line under 250 chars. Third-person, no colons (YAML breaks silently). For user-only skills, a plain one-liner is enough — trigger keywords are wasted tokens when LLM never auto-invokes.

  4. Validate structure and run tests

    Runs validate-skill.sh from the brewcode plugin. Checks: valid YAML frontmatter, name ≤ 64 chars, description ≤ 250 chars single-line, body under 500 lines, bash blocks have EXECUTE keyword, no hardcoded secrets. Then spawns 3–5 realistic test prompts to verify activation and output quality.

  5. Generate README and iterate

    Fills the standard README template with actual examples, then runs brewtools:text-optimize on the SKILL.md. If test runs reveal a repeated helper pattern, bundles it into scripts/ so every future invocation skips the boilerplate.

Full workflow internals — phase breakdown, frontmatter reference, patterns

Activation rates by configuration

ConfigurationActivation rate
Basic description, no triggers20%
Optimized description + Triggers: line50–72%
/skill-name explicit slash command100%
disable-model-invocation: true (user-only)n/a — LLM never invoked

Critical bug: Skills context lost after compaction ~55K tokens (#13919). Re-invoke /skill-name or use external state for long sessions.

Invocation type decision

Who invokesConfigurationDescription style
User only (slash command)disable-model-invocation: trueSimple one-liner, no triggers needed
LLM only (background)user-invocable: falseFull triggers for auto-activation
Both (default)(no flags)Full triggers for auto-activation

Rule: If failure is unacceptable (deploy, send-email, delete data) → disable-model-invocation: true + slash command only.

Skill anatomy

skill-name/
├── SKILL.md         # frontmatter + instructions (required)
├── references/      # detailed docs, loaded on demand
├── examples/        # working code examples
├── scripts/         # executable utilities
├── assets/          # templates, images
└── agents/          # subagent prompts (convention, NOT auto-discovered)

Key design patterns

PatternWhen to use
Progressive DisclosureAlways — L1 name+desc in context, L2 SKILL.md on trigger, L3 references on demand
Reference Splitting2+ modes, >50 lines/mode, >300 lines total — detect mode → load only matching references/{mode}.md
Agents-as-ReferencesCoordinator with multi-step workflow — pass file path to subagent, subagent reads itself. 0 tokens in coordinator context
Context ForkStandalone task, no history needed, <4 phases — context: fork + isolated subagent
Executable Bash**EXECUTE** using Bash tool: keyword + && echo "✅" || echo "❌" + > STOP if ❌
Mode Switcher”toggle”, “persistent behavior”, “from now on” → state in $BC_PLUGIN_DATA/modes.json, hooks inject on every event
Pushy DescriptionLLM-invocable skills — action verb + Triggers: "exact user phrases". Raises rate 20% → 50-72%

Description format

# LLM-invocable — action verb + Triggers on single line ≤250 chars
description: "Creates conventional git commits with proper format. Triggers: commit, git commit, save changes."

# User-only — simple one-liner, no triggers needed
description: "Deploy application to production environment."

Common mistakes: multiline | (truncated at 250 chars since v2.1.84), missing Triggers: (stays at 20%), starts with “Use this skill when” (should start with action verb), colon in description (YAML parse failure), setting permissionMode: bypassPermissions on production skills — this is equivalent to --dangerously-skip-permissions and skips all safety prompts. Only appropriate in sandboxed CI; never the right default for local skills.

Frontmatter quick reference

FieldLimitsNotes
name≤64 chars, lowercase-hyphensUse directory name if omitted
description≤250 chars, single line, always quotedALWAYS in double quotes — em dashes, colons break YAML silently
disable-model-invocationtrue/falsetrue = 100% reliable, slash-only
user-invocabletrue/falsefalse = hide from menu, Claude-only
contextforkIsolated subagent, fresh context
agentExplore, Plan, general-purpose, developerWith context: fork
modelopus, sonnet, haikuBased on complexity
effortlow, medium, high, max, autov2.1.80+
allowed-toolstool listMinimal set
argument-hintstringAutocomplete hint
oncetrue/falseFire once per session

$ARGUMENTS in bash blocks

$ARGUMENTS inside ```bash ``` blocks is a shell variable (empty/undefined), NOT Claude Code substitution. Claude Code replaces $ARGUMENTS only in markdown text.

# WRONG
` ```bash
bash script.sh "$ARGUMENTS"
` ```

# CORRECT — $ARGUMENTS in text, placeholder in bash
**Skill arguments received:** `$ARGUMENTS`
**EXECUTE** using Bash tool:
` ```bash
bash script.sh "ARGS_HERE"
` ```
Replace ARGS_HERE with the actual value from above.

Context fork memory behavior

ModePhasesBehavior
Inline (default)AnyFull conversation access
context: fork1–4Works well, context isolated
context: fork5+Memory loss — forgets task structure, skips phases

Known bugs

IssueImpactWorkaround
#13919Skill context lost after ~55K tokensRe-invoke /name, use external state
#22345Plugin skills ignore disable-model-invocationCopy skill to .claude/skills/
#17688Skill-scoped hooks don’t fire in pluginsUse plugin hooks.json
#17417skill.md (lowercase) silently ignoredUse SKILL.md (uppercase)
#10768Auto-activation 20–50% (NOT PLANNED)Optimize description or use /name
🤖

Agent Creator

Same workflow for creating agents instead of skills.

🔗

GitHub source

Full agent instructions — frontmatter reference, patterns, known bugs.

🚀

Brewcode overview

All brewcode agents, skills, and hooks in one place.

Updating plugins

Use /brewtools:plugin-update to check and update the brewcode plugin suite in one command. See the FAQ for details.