Skill Creator

Activation rates by configuration

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

Invocation type decision

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

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

$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

Additional skill facts (CC 2.1.142+)

Root-level SKILL.md: a plugin with a SKILL.md at the plugin root (no skills/ subdirectory) is surfaced as a skill automatically since CC 2.1.142. Useful for single-skill plugins.

/reload-skills re-scans skill directories without restarting the session (CC 2.1.152). Use this after editing or adding a SKILL.md — no session restart needed.

Known bugs

Subagent spawn constraint

CC allows nested subagent spawning, but prefer spawning from the main conversation so the orchestrator can integrate each agent’s result directly. Brewcode agents are stateless and resolve plugin paths via ${CLAUDE_PLUGIN_ROOT}.