Skill Creator

Skill Design Patterns

Pattern	When to Use	Effect
Progressive Disclosure	Always — every skill	3 loading levels: L1 name+desc (~100 words, always in context), L2 SKILL.md body (<500 lines, on trigger), L3 references/scripts/agents (on demand, unlimited). Heavy content stays unloaded until needed
Reference Splitting	Multi-mode skill: 2+ modes, >50 lines/mode, >300 lines total	Detect mode -> Read references/{mode}.md. Loads only the matching reference. Guard: “If not found -> ERROR + STOP”
Agents-as-References	Skill-coordinator with multi-step workflow and multiple specialized roles	Subagent prompts as .md files in agents/ inside skill dir. Coordinator does NOT read them — passes file path to subagent, subagent does Read itself. 0 tokens in coordinator context. agents/ is NOT a native feature — it’s a convention
Dynamic Context	Need live data before launch (git diff, PR info, env)	!`command` executes BEFORE sending to Claude. Output replaces placeholder in SKILL.md
Context Fork	Standalone task, no conversation history needed, <4 phases	context: fork -> isolated subagent. SKILL.md = task prompt. CLAUDE.md loaded, history — no. Warning: >5 phases — memory loss
Executable Bash	Bash blocks must execute, not be examples	EXECUTE keyword + && echo "done" || echo "FAILED" + > STOP if FAILED. Without keyword bash blocks are treated as examples
Skill Chaining	Skill invokes another skill	Skill in allowed-tools. Skill(skill="name", args="..."). Works only in main conversation
Background Knowledge	Claude needs context, but user doesn’t need a slash command	user-invocable: false. Description stays in context, Claude decides when to apply
Pushy Description	LLM-invocable skills	Description includes scenarios and keywords: “Use when - X. Trigger keywords - Y.” Raises activation 20% -> 50-72%
Preloaded Skills	Subagent must follow conventions/patterns	skills: [name] in agent frontmatter. Full skill content injected at startup. Inverse pattern to context: fork

Agents-as-References Detail

Pattern from official Anthropic skill-creator plugin. NOT a native Claude Code feature — agents/ inside a skill dir is not auto-discovered.

my-skill/
  SKILL.md              # Coordinator
  agents/               # Subagent prompts (convention, NOT native)
    researcher.md
    writer.md
  references/
  scripts/

How it works:

SKILL.md (coordinator):
  -> "Spawn subagent with instructions:"
  -> "Read agents/researcher.md at: ${CLAUDE_SKILL_DIR}/agents/researcher.md"
  -> Agent(general-purpose, prompt="Read agents/researcher.md ... Execute: ...")

Coordinator passes file path, not content. Subagent reads the .md itself and follows it as instructions.

Native agents .claude/agents/	”Agents” in skill agents/
Auto-discovered, visible in /agents	Only via Read by path
Own model, tools, hooks, memory	Inherits from subagent
YAML frontmatter + Markdown	Plain Markdown (prompt)
Public API	Implementation detail of skill

When to use: skill-coordinator with 2+ roles, need context isolation between roles, prompts are implementation details (not public API).

Progressive Disclosure

Level	Content	Budget
1	name + description (always loaded)	~100 words
2	SKILL.md body (on trigger)	<500 lines
3	references/, scripts/, agents/ (on demand)	Unlimited

SKILL.md Format

---
name: my-skill                    # max 64 chars, lowercase-hyphens
description: Apply X guidelines   # 150-300 chars, ONE line, no colons
---

# Skill Name

## Overview
One paragraph purpose.

## Instructions
Imperative form: "Do X" (not "You should do X").

Core Fields

Field	Limits	Description
name	64 chars	lowercase/numbers/hyphens. Uses directory name if omitted
description	150-250 chars optimal (truncated at 250 since v2.1.84), ALWAYS single line, no colons	What + when. Claude uses for auto-invocation. Front-load keywords

Invocation Control

Field	Default	Description
disable-model-invocation	false	true = user-only via /name. 100% reliable
user-invocable	true	false = hide from menu. Claude-only background knowledge
argument-hint	—	Autocomplete hint: [issue-number], [filename]

When to Use disable-model-invocation: true

Operation	Risk	Setting
Deploy to production	Data loss, downtime	disable-model-invocation: true
Git commit/push	Wrong commits	disable-model-invocation: true
Send email/notification	Spam, wrong recipients	disable-model-invocation: true
Delete data	Irreversible	disable-model-invocation: true
Financial transactions	Money loss	disable-model-invocation: true
Code formatting	Low risk	Auto OK
Documentation	Low risk	Auto OK
Analysis/research	No side effects	Auto OK

Remember: Auto-activation is 20-50% reliable. For critical ops, /name is the only guarantee.

Execution Control

Field	Values	Description
allowed-tools	Read, Grep, Glob, Bash(git:*), Skill	Restrict available tools
model	opus, sonnet, haiku	Override model
effort	low, medium, high, max, auto	Override effort level for this skill invocation (v2.1.80+)
context	fork	Run in isolated subagent
agent	Explore, Plan, general-purpose, custom	Subagent type (with context: fork)
hooks	object	Hooks scoped to skill lifecycle
once	true/false	Hook fires once per session (default: false)

Inline (Default)

Omit context field. Runs in main conversation with full history. Description loaded at start, full body on invoke. Best for reference material, guidelines, background knowledge.

---
name: api-conventions
description: REST API design patterns for this codebase
---

When writing API endpoints:
- Use RESTful naming conventions
- Return consistent error formats

Fork (context: fork)

Isolated subagent with fresh context, no conversation access. SKILL.md body becomes task prompt. CLAUDE.md still loaded. Best for standalone tasks, research, side effects.

---
name: deep-research
description: Research a topic thoroughly
context: fork
agent: Explore
---

Research $ARGUMENTS:
1. Find relevant files using Glob/Grep
2. Read and analyze code
3. Summarize with file references

Memory Behavior

Mode	Phases	Behavior
Inline	Any	Full conversation access
fork	1-4	Works well, context isolated
fork	5+	Memory loss — forgets task structure, skips phases

context: fork creates isolated context that fades over extended execution. For multi-phase skills: use inline mode or implement hooks/external state (TASK.md, KNOWLEDGE.jsonl).

Decision Matrix

Question	Answer	Mode
Needs conversation history?	Yes	Inline (omit context)
Standalone quick task (<4 phases)?	Yes	context: fork
Multi-phase orchestration (4+ phases)?	Yes	Inline + hooks/external state
Simple research/analysis?	Yes	context: fork + agent: Explore

Subagent Spawning Constraints

Skills with context: fork spawn a subagent. Subagents cannot spawn other subagents — SubAgentLoop excludes AgentTool.

Scenario	Works?	Why
Skill with context: fork from main conversation	Yes	Main agent has AgentTool
Skill with context: fork from subagent	No	AgentTool absent from SubAgentLoop
Task tool from subagent	No	Task tool = AgentTool, excluded
Skill tool from subagent	No	Skill tool unavailable in SubAgentLoop
Inline skill (no context) from subagent	No	Skill tool unavailable

Design implications: context: fork works only from main conversation or agent teams lead. For subagents, use skills: frontmatter (preload at startup). For multi-agent orchestration — chain from main agent, not nested spawning.

Agent Field

With context: fork, the agent field selects subagent.

Agent	Model	Tools	Purpose
Explore	Haiku	Read-only	File discovery, code search
Plan	Inherit	Read-only	Research during planning
general-purpose	Inherit	All	Multi-step tasks (default)
developer	Opus	Full	Code impl
tester	Sonnet	Full	Test execution
reviewer	Opus	Read+Bash	Code review

Custom agents: reference from .claude/agents/ or ~/.claude/agents/ via agent: my-custom-agent.

Invocation Matrix

Configuration	User	Claude	In Context	Budget
(default)	Yes	Yes	Description always, full on invoke	description in budget
disable-model-invocation: true	Yes	No	Not loaded	0 — not loaded
user-invocable: false	No	Yes	Description always	description in budget
Both true + false	No	No	Inaccessible (useless config)	0

Description Optimization

Claude uses description to decide when to invoke. Description quality directly affects activation rate (20% -> 72%).

User-Only Skills (NO optimization needed)

For disable-model-invocation: true skills — simple one-line description is enough.

LLM never auto-invokes these skills, so trigger keywords are useless. User calls via /skill-name directly.

LLM-Invocable Skills (optimization REQUIRED)

Write in third person — description injects into system prompt.

Pattern	Example
Good	”Processes Excel files and generates reports”
Good	”Extracts text from PDF files for analysis”
Bad	”I can help you process Excel files”
Bad	”Use this skill when…”
Bad	”Helps with code”

Trigger Keywords Pattern

CRITICAL: Include explicit trigger keywords. This raises activation 20% -> 50-72%.

# BAD -- multiline, too long (>300 chars)
description: |
  Creates presentations with slides, applies company colors, adds animations.
  Use when: creating presentations, building slides, formatting decks.
  Trigger keywords: presentation, slides, deck, pptx.

# GOOD -- single line, 150-300 chars, what + triggers
description: Creates conventional git commits with proper format. Use when - committing, saving work. Trigger keywords - commit, git commit, save changes.

Description Template

description: [One sentence - what it does]. Use when - [scenarios]. Trigger keywords - [keywords].

Rules:

• ONE line, no | multiline
• 150-250 chars optimal (truncated at 250 since v2.1.84). ALWAYS single line — no multiline YAML |
• Drop Triggers - phrases section (saves ~80 chars)
• Use - separator instead of :

Character Budget

Skills compete for context space. Default budget: 2% of context or 16K chars.

Increase via env var if you have many skills:

export SLASH_COMMAND_TOOL_CHAR_BUDGET=50000  # 50K chars

Symptom: Some skills never activate -> they’re beyond budget, Claude doesn’t see them.

Trigger Eval Queries (optional but recommended)

Generate 10 realistic eval queries to test description effectiveness:

Type	Count	Description
Should trigger	5	Queries where skill SHOULD activate. Different phrasings, casual/formal mix
Should NOT trigger	5	Near-misses — share keywords but need different tool. NOT obviously irrelevant

Key: should-not-trigger queries must be TRICKY, not obvious.

Reference Splitting Strategy

When to Split

Criteria	Threshold
Independent modes	2+ modes with different knowledge
Per-mode instructions	>50 lines per mode
Total reference content	>300 lines combined
Shared vs. specific ratio	<30% shared content

If ALL criteria met -> split into references/{mode}.md files.

Loading Patterns

Pattern	When	Example
Conditional (lazy)	Multi-mode, >50 lines/mode	standards-review: detect stack -> Read references/{stack}.md
Unconditional single	Single reference, <200 lines	text-optimize: always Read references/rules-review.md

3-Step Pattern

1. DETECT mode from $ARGUMENTS or project analysis
2. READ matching reference: references/{mode}.md
3. VALIDATE: "If file not found -> ERROR: Missing reference for {mode}. STOP."

Anti-Patterns

Anti-Pattern	Fix
Load ALL references regardless of mode	Detect mode -> load only matching reference
Inline all mode-specific content in SKILL.md	Split to references/{mode}.md when >50 lines
No validation after Read	Add “If not found -> ERROR + STOP” guard
Generic reference names	Use mode name: references/jvm.md, not references/ref1.md

Resource Path Resolution

Use ${CLAUDE_SKILL_DIR} (v2.1.71+) for bash commands, relative paths for Read instructions.

# Bash -- use ${CLAUDE_SKILL_DIR} (CWD is project root, not skill dir)
bash "${CLAUDE_SKILL_DIR}/scripts/validate.sh" $ARGUMENTS

# Read -- relative paths work (Claude auto-resolves from skill base dir)
Read references/api-spec.md for API details.

NEVER	ALWAYS
$BC_PLUGIN_ROOT/skills/my-skill/scripts/foo.sh	${CLAUDE_SKILL_DIR}/scripts/foo.sh
/absolute/hardcoded/path/to/assets/template.md	${CLAUDE_SKILL_DIR}/assets/template.md

Exception — passing path to agent via Task: use $BC_PLUGIN_ROOT (agent has no ${CLAUDE_SKILL_DIR}):

Task(subagent_type="developer", prompt="Read $BC_PLUGIN_ROOT/skills/my-skill/references/rules.md then...")

String Substitutions

Variable	Description	Since
$ARGUMENTS	All arguments passed when invoking the skill	—
$0, $1, $2	Specific argument by 0-based index	—
${CLAUDE_SESSION_ID}	Current session ID	—
${CLAUDE_SKILL_DIR}	Absolute path to directory containing the skill’s SKILL.md	v2.1.71

${CLAUDE_SKILL_DIR} — string substitution (NOT env var). Replaced in SKILL.md before sending to model. Plugin skills -> skill subdirectory, not plugin root. NOT available in hooks/agents — use $CLAUDE_PLUGIN_ROOT there.

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

Step 1: Understand

Check Conversation History

If the current conversation already contains a workflow the user wants to capture (e.g., “turn this into a skill”), extract from history first:

• Tools used and their sequence
• Steps taken and corrections made
• Input/output formats observed
• Edge cases encountered

Confirm extracted workflow with user before proceeding.

Identify usage patterns: direct examples from user, validated scenarios, real-world use cases. If invoked directly from main conversation (foreground) — use AskUserQuestion for max 2-3 clarifying questions: functionality, usage examples, trigger phrases.

Invocation Type (CRITICAL)

If unclear who will invoke the skill, ASK using AskUserQuestion tool:

Invocation Type	Configuration	Description Style
User-only (slash command)	disable-model-invocation: true	Simple one-liner, NO triggers needed
LLM-only (background)	user-invocable: false	Full triggers for auto-activation
Both (default)	(no flags)	Full triggers for auto-activation

Step 2: Plan Contents

• Scripts — tasks needing deterministic reliability
• Reference docs — schemas, API specs, policies (see Reference Splitting Strategy for multi-mode skills)
• Assets — templates, icons

Step 3: Create Structure

mkdir -p .claude/skills/skill-name/{references,scripts,assets}

Step 4: Configure

Question	Answer	Action
Needs history?	Yes	Inline (omit context)
Standalone task?	Yes	context: fork
Side effects?	Yes	Add disable-model-invocation: true
Background only?	Yes	Add user-invocable: false

Complexity	Model	Agent
Complex orchestration	opus	general-purpose
Optimization/analysis	sonnet	Explore (read-only)
Simple/fast	haiku	—

Write SKILL.md: frontmatter -> overview (1-2 sentences) -> instructions (imperative) -> resource refs. Word budget: 1,500-2,000 words. Move excess to references/.

Step 5: Validate

Structure Checklist

Check	Details
Structure	SKILL.md with valid YAML frontmatter
name	<=64 chars, lowercase-hyphens
description	150-250 chars optimal (truncated at 250 since v2.1.84), single line, third-person, no colons
Body	<500 lines, imperative form
context	fork if standalone
agent	Appropriate type
model	Based on complexity
allowed-tools	Minimal set
Examples	Working
Secrets	None hardcoded

Activation Checklist (CRITICAL)

Check	Details
What + When + Keywords	Description includes what skill does + scenarios + trigger keywords
Keywords present	Trigger keywords - deploy, staging, prod, release
Scenarios present	Use when - deploying, releasing, shipping
One line	No multiline `
Third-person	”Deploys…” not “I deploy…” or “Use this to…”
Critical -> slash	disable-model-invocation: true for risky operations

Step 6: Iterate

Refine based on real-world usage feedback. Check Claude’s thinking to verify triggering.

Detect Repeated Work

After running test cases, read transcripts. If all runs independently wrote similar helper scripts or took the same multi-step approach — that’s a signal to bundle it:

1. Write the common script once in scripts/
2. Reference from SKILL.md
3. Saves every future invocation from reinventing the wheel

Common Patterns

Reference (Inline)

---
name: api-conventions
description: REST API patterns for this codebase
---

Task (Fork + Side Effects)

---
name: deploy
description: Deploy to production
disable-model-invocation: true
context: fork
---

Research (Fork + Read-only)

---
name: codebase-analyzer
description: Analyzes codebase structure
context: fork
agent: Explore
model: haiku
---

Background (Claude-only)

---
name: legacy-context
description: Legacy payment system details
user-invocable: false
---

Dynamic Context

---
name: pr-summary
context: fork
agent: Explore
---
## Context
- Diff: !`gh pr diff`

commit (Critical — slash only)

---
name: commit
description: Creates conventional git commits with proper format. Use when - committing, saving work. Trigger keywords - commit, save, git commit.
context: fork
disable-model-invocation: true
---

## Context
- Status: !`git status --short`
- Diff: !`git diff --staged`

Create commit message following conventional commits format (type(scope) subject).
Analyze changes, determine type (feat/fix/refactor/test/docs), craft concise subject.
Execute commit with Co-Authored-By footer.

pr-review (Important — auto OK)

---
name: pr-review
description: Reviews pull requests with structured analysis. Use when - reviewing PR, checking code quality. Trigger keywords - review, PR, pull request, code review.
context: fork
agent: Explore
---

## Context
- Diff: !`gh pr diff`
- Comments: !`gh pr view --comments`

Review this PR analyzing changes, potential issues, test coverage.
Output structured review with sections - Summary, Issues (security/performance/bugs),
Improvements, Test Coverage.

codebase-qa (Background)

---
name: codebase-qa
description: Background knowledge for answering codebase architecture questions
user-invocable: false
---

## Architecture Patterns

| Pattern | Location | Purpose |
|---------|----------|---------|
| Repository | src/main/java/*/repository | JPA data access |
| Service | src/main/java/*/service | Business logic |
| Controller | src/main/java/*/controller | REST endpoints |

Reference this when answering architecture questions.

Common Mistakes

Structure and Syntax

Mistake	Fix
Colon in description	Remove : — breaks YAML
>500 lines	Move to references/
Missing fork for tasks	Add context: fork
Wrong agent	Explore=read-only, general-purpose=full
Hardcoded secrets	Use MCP
Multipurpose	Split into focused skills
Unmarked bash	Add EXECUTE keyword
$ARGUMENTS in bash block	Move to text, use placeholder
All references loaded unconditionally	Detect mode -> load matching references/{mode}.md only
Using $BC_PLUGIN_ROOT for own scripts	Use ${CLAUDE_SKILL_DIR} — it’s the skill’s own directory
Treating ${CLAUDE_SKILL_DIR} as env var	It’s string substitution in SKILL.md only, not available in hooks/agents
skill.md (lowercase)	Must be SKILL.md (uppercase) — lowercase silently ignored
context: fork with 5+ phases	Memory loss, forgets task — use inline + external state
Reserved skill names (“code”, “debug”, “bug-fix”)	Skill won’t load — avoid reserved words
Description >250 chars	Truncated since v2.1.84 — front-load keywords

Activation Mistakes (cause 20% rate)

Mistake	Fix
Summary WITHOUT triggers	Include BOTH what skill does AND trigger keywords
No trigger keywords	Add Trigger keywords: deploy, staging, prod
No “Use when:“	Add Use when: deploying, releasing, shipping
Vague description	Specific: “Deploy to k8s” not “Helps with deployment”
First-person description	Third-person: “Deploys…” not “I deploy…”
Second-person body	Imperative: “Do X” not “You should do X”
Critical without slash	Add disable-model-invocation: true for critical ops
Too many skills	Exceeds SLASH_COMMAND_TOOL_CHAR_BUDGET -> some invisible
Plugin skills: disable-model-invocation ignored	Plugin skills always in context — copy to .claude/skills/ if parity needed

Skill Not Auto-Activating

Symptom	Cause	Fix
Never activates	Beyond char budget	Increase SLASH_COMMAND_TOOL_CHAR_BUDGET
Never activates	Description is summary	Rewrite with triggers only
Sometimes activates	Weak keywords	Add explicit “Trigger keywords:“
Was working, stopped	Context compaction	Known bug #13919, use /name
Claude ignores instruction	Attention competition	Fewer skills or explicit /name

Debug Steps

1. Check if Claude sees it: Ask “What skills do you have?” — if skill not listed -> char budget exceeded
2. Check thinking (if visible): Look for skill name in Claude’s reasoning. If absent -> description not matching.
3. Test explicit invoke: /skill-name — if works -> activation issue. If fails -> skill broken.
4. Force test: “Use skill-name skill to do X” — explicit mention increases activation to ~70%.

Known Bugs

#	Bug	Impact	Status	Workaround
#13919	Skill context lost after compaction ~55K tokens	Instructions forgotten in long sessions	Open	Re-invoke /name or external state
#39686	claude.ai skills silently injected (~6000 tokens)	37% of skill budget consumed; no opt-out	Open	No workaround
#22345	Plugin skills ignore disable-model-invocation	Plugin skills always in context (~4400 tokens)	Open	No workaround
#17688	Skill-scoped hooks don’t fire in plugins	Hooks from SKILL.md frontmatter not working for plugin skills	Open	Use plugin hooks.json
#35641	/reload-plugins doesn’t load skills from new plugins	Skills emitter not called on reload	Open	Restart session
#33080	Built-in skills silently conflict with custom	Built-in takes priority; no notification	Open	Namespace prefix (e.g., my-)
#36031	User-level skills visible in autocomplete but not invoked in Desktop	SKILL.md not loaded; CLI works	Open	Use CLI
#17417	skill.md (lowercase) silently ignored	Skill not discovered	Open	Use SKILL.md (uppercase)
#10768	Auto-activation unreliable (20-50%)	Skill not invoked on relevant request	Closed (NOT PLANNED)	Optimize description (50-72%) or /name (100%)
#15136	Claude fails to invoke skill despite instructions	Skill skipped; 6+ duplicates	Closed (NOT PLANNED)	/name for 100%

Architectural Limitations

Limitation	Details	Workaround
Subagents cannot spawn subagents	AgentTool excluded from SubAgentLoop	Chain from main conversation
context: fork degrades at 5+ phases	Task structure memory loss	Inline + hooks/external state
Description budget	2% of context or 16K chars	SLASH_COMMAND_TOOL_CHAR_BUDGET env var
${CLAUDE_SKILL_DIR} only in SKILL.md	Not available in hooks/agents	$CLAUDE_PLUGIN_ROOT in hooks/agents
Compaction erases skill context	CLAUDE.md re-read, skills are not	Re-invoke /name, external state
Description <=250 chars	Truncated since v2.1.84	Front-load keywords
Plugin skills lack parity	disable-model-invocation and skill-scoped hooks don’t work	Copy skill to .claude/skills/
Reserved names	Skills named “code”, “debug”, “bug-fix” don’t load	Avoid reserved words

Version History (Skill Features)

Version	Date	Changes
v2.1.85	2026-03-26	if field for hooks; fix: skill hooks fired twice
v2.1.84	2026-03-26	Descriptions <=250 chars; alphabetical /skills sort
v2.1.80	2026-03-19	effort frontmatter for skills
v2.1.76	2026-03-14	/effort slash command
v2.1.74	2026-03-12	Fix: ask rules bypassed via allowed-tools
v2.1.73	2026-03-11	Fix: deadlock on mass skill file changes
v2.1.72	2026-03-10	Fix: built-in slash commands hidden; skill hooks dropped
v2.1.71	2026-03-07	${CLAUDE_SKILL_DIR} variable; /claude-api skill
v2.1.69	2026-03-05	Security: nested discovery skips gitignored dirs
v2.1.47	2026-02-18	Fix: crash on numeric name/description
v2.1.45	2026-02-17	Plugin skills available immediately after install (no restart)

Sources

• Claude Code Skills
• Custom Subagents
• Skill Best Practices
• agentskills.io