
skills-toolkit
Create and manage Claude Code skills, plugins, subagents, and hooks. Use when building new skills, validating existing skills, creating plugins, converting projects to plugins, creating hooks, or managing plugin automation. Includes /skills-toolkit:create-skill, /skills-toolkit:create-plugin, /skills-toolkit:create-subagent, and /skills-toolkit:create-hook commands.
- version
- 1.6.0
- GitHub stars
- 26
Install
/plugin install skills-toolkit@skills-toolkit-marketplaceRun it inside Claude Code after adding the marketplace with /plugin marketplace add full-stack-biz/claude-skills-toolkit.
Contents
Discovered from sourceSkills 7
Implementing Skills with AskUserQuestion
How to author skills that use the AskUserQuestion tool for interactive user input, decisions, and guided workflows.
Official Tool Purpose
From Claude Code system prompt:
Use AskUserQuestion to:
- Gather user preferences or requirements - Understand what user wants
- Clarify ambiguous instructions - Ask when instructions are unclear
- Get decisions on implementation choices - Multiple valid approaches exist
- Offer choices about what direction to take - User picks path forward
Key Capabilities:
- Users always see "Other" option for custom text input
multiSelect: trueallows selecting multiple answers- Put recommended option first, labeled with "(Recommended)"
Important: Don't use to ask "Is my plan ready?" or similar meta-questions. Use in-band questions only for actual decisions.
How It Works in Skills
Response Format:
{
"questions": [...original questions...],
"answers": {
"Question text": "selected option OR custom text",
"Another question": "answer"
}
}
Critical Rule: Custom text appears in answers directly, not as "Other"
answers["Framework?"] = "angular" ✅ (user typed)
answers["Framework?"] = "Other" ❌ (never this)
Hard Constraints
Tool Limits (Claude Code enforced):
- Max 1-4 questions per call
- Min 2, Max 4 options per question
- "Other" is automatic (never include in options list)
- Max header: 12 characters
- Max option label: varies but aim for 1-5 words
- Max description: 1-2 sentences recommended
"Other" Behavior:
- Always present automatically
- Users can type any custom text
- Custom text returned as answer value (not "Other")
Example:
answers["Framework?"] = "angular" ✅ (user typed "angular")
answers["Framework?"] = "Other" ❌ (never this)
How to Wire AskUserQuestion Into a Skill
Pattern 1: Prose Question (Typical)
Ask in natural language, users respond freely:
## Step 1: Ask User for Input
**What are we building?**
Describe the feature or change you want to make.
(I'll ask follow-up questions if I need clarification)
[User responds with description]
## Step 2: Follow-Up If Needed
Based on their response, ask 1-2 clarifying questions:
- "Is this a new feature or updating existing?"
- "What's the expected outcome?"
[User responds]
## Step 3: Process Answers
Use their responses to inform next steps...
Pattern 2: Structured Options (When Choices Matter)
Use tool when user must select from specific options:
## Step 1: Ask for Configuration Choice
Use AskUserQuestion tool:
**Question 1:**
- Text: "Which option?"
- Header: "Choice"
- Options:
- Label: "Option A"
Description: "What this does, trade-offs"
- Label: "Option B"
Description: "Alternative approach"
[User selects or types "Other" for custom]
## Step 2: Process Answer
The response provides:
- answers["Which option?"] = user's selection
Based on answer:
- If "Option A": Do X
- If "Option B": Do Y
- If custom text: Do Z
## Step 3: Continue
Proceed with workflow...
Progressive Disclosure Pattern
CRITICAL: Ask ONE question, wait for response, THEN ask next.
## Question 1: Gather Type
Ask: "What type of project?"
Options: Web, Mobile, CLI
[User answers]
## Question 2: Framework (Conditional)
Based on answer to Q1:
- If Web: Ask "Frontend framework?"
- If Mobile: Ask "Platform?"
- If CLI: Ask "Language?"
[User answers]
## Question 3: Confirmation
Show summary and ask: "Proceed?"
Options: Yes, No, Edit
[Continue based on answer]
Defining Questions in Skills
Pattern 1: Prose with Guidance (Recommended)
Ask questions in natural language with examples. No options needed:
## What are we building?
Please describe the feature or change.
(Be as specific as you like — I'll ask follow-ups if needed)
Or with guidance:
## Do you have any visuals to reference?
- Mockups or wireframes
- Screenshots of similar features
- Examples from other apps
(Paste images, share file paths, or say "none")
This pattern:
- ✅ Feels natural to users
- ✅ Allows truly open input
- ✅ No constraint on number of options
- ✅ Users can respond with anything
Pattern 2: Structured Options (When Choosing Matters)
Use tool options when user must select from specific choices:
**Question: Database Selection**
- Text: "Which database for this project?"
- Header: "Database" (max 12 chars)
- Options:
- Label: "PostgreSQL"
Description: "Relational, ACID compliant, best for complex queries"
- Label: "MongoDB"
Description: "Document-based, flexible schema, rapid iteration"
- Label: "Redis"
Description: "In-memory, very fast, ideal for caching"
Constraints for this pattern:
- Min 2, Max 4 options per question
- "Other" automatic for custom input
- Users can select one (or multiple if
multiSelect: true)
Use when:
- Multiple mutually-exclusive choices exist
- Each option leads to different workflow
- You want to guide without forcing
Pattern 3: Multi-Select Options
When users should enable/select multiple independent items:
**Question: Which features to enable?**
- Header: "Features"
- multiSelect: true
- Options:
- "Logging" (Operation logs for debugging)
- "Metrics" (Performance monitoring)
- "Alerts" (Error notifications)
- "Backups" (Automatic data backups)
Response: answers["Features?"] = "Logging, Metrics" (joined with ", ")
Processing Responses
Basic Response Handling
The tool returns:
{
"questions": [...],
"answers": {
"Which database?": "PostgreSQL"
}
}
In skill body:
Based on the answer to "Which database?":
- If "PostgreSQL": Set up relational database
- If "MongoDB": Set up document database
- If "Redis": Set up in-memory cache
- If custom text: Configure for custom database name
Then proceed with configuration...
Checking Multiple Answers
From response:
- answers["Database?"] = "PostgreSQL"
- answers["Environment?"] = "production"
- answers["Features?"] = "Logging, Metrics"
In skill:
Database: PostgreSQL (check: is this supported?)
Environment: production (check: validate settings for prod)
Features: Split by ", " and enable each
If any validation fails:
Log error
Ask user to reconfigure
Return to questioning phase
Handling Free-Text Answers
When users select "Other" and type custom input, you need to handle it properly.
Pattern: Check if answer is a known option or custom text, then route accordingly.
If user selected "Other" and typed "custom-framework":
answers["Framework?"] = "custom-framework"
In skill:
Check if "custom-framework" is in known frameworks:
- If yes: use framework-specific setup
- If no: use generic setup with warning
Log: "Using custom framework: custom-framework"
Proceed with generic configuration...
See references/free-text-input-patterns.md for complete patterns for handling custom input including validation, generic fallbacks, and user feedback.
When to Use Each Pattern
Use Prose Questions When:
- Scope is open-ended (user describes feature, context, etc.)
- You need true free-form input
- Multiple follow-ups will be needed
- No specific options constrain the answer
- Examples: "What are we building?", "Describe the problem"
Use Structured Options When:
- User must choose from specific alternatives
- Each option leads to different workflow/configuration
- You want to guide without forcing
- Examples: "Which database?", "Enable monitoring?" (Yes/No)
Mixed Approach:
Start with prose for context/understanding, then use structured options for specific decisions:
Step 1: Ask "What are we building?" (prose)
Step 2: Ask "Which database?" (structured options)
Step 3: Ask "Which features?" (multi-select options)
Question Design (For Structured Options)
When using predefined options:
- Be specific: "Which database for this project?" (not "Database?")
- Provide context: "Relational, ACID compliant, best for complex queries"
- Show trade-offs: "Fast for reads, slower for writes, good for analytics"
- Mutually exclusive: Options should be distinct (unless multiSelect)
- Consistent format: Same capitalization, length (~1-2 sentences), detail level
See references/skill-patterns.md for complete question design examples.
Dynamic Questions Pattern
How to ask different questions based on previous answers:
## Step 1: Initial Question
Ask: "Application type?"
Options: Web, Mobile, CLI
[Get answer]
## Step 2: Conditional Question
If answer == "Web":
Ask: "Frontend framework?"
Options: React, Vue, Svelte
If answer == "Mobile":
Ask: "Platform?"
Options: iOS, Android, Cross-platform
If answer == "CLI":
Ask: "Language?"
Options: Python, Go, Rust
[Get answer]
## Step 3: More Conditional Questions
Based on BOTH previous answers:
If Web + React:
Ask: "State management?"
Options: Redux, Context, Zustand
If Web + Vue:
Ask: "State management?"
Options: Pinia, Vuex
[Continue...]
Error Handling in Skills
Check if Response Received
If AskUserQuestion fails or no answers:
Log error: "Failed to gather responses"
Show: "Please try again or provide configuration manually"
Exit
(Or restart the questioning phase)
Validate Answer Format
If question expects "port number":
answers["Port?"] could be:
- "8080" (valid)
- "invalid" (needs validation)
- "12345" (out of range)
Validate before using:
Parse as number
Check range (1-65535)
If invalid: Ask user to reconfigure
Handle Empty Answers
If answers["Required field?"] is empty or missing:
Log: "No answer provided for required field"
Ask user to reconfigure
Don't proceed with empty critical answers
Common Limitations & Workarounds
See references/advanced-patterns.md for detailed workarounds for common constraint scenarios (max questions, max options, dependent options, pre-populating answers).
Response Processing Workflow
Typical skill using AskUserQuestion:
1. Describe what you're asking
"Let's configure your database"
2. Ask Question 1
Call AskUserQuestion with 1 question
3. Get Response
Extract answers from response object
4. Validate
Check format, compatibility, ranges
5. Ask Question 2 (if conditional)
Based on Q1 answer, ask Q2
6. Get Response & Validate
7. Process All Answers
- Check compatibility across answers
- Apply configuration
- Generate outputs
8. Confirm
Ask: "Does this look right?"
If Yes: Proceed
If No: Restart from Q1
Writing About AskUserQuestion in Skills
See references/skill-patterns.md for guidance on documenting AskUserQuestion in skill descriptions, body content, and custom input support.
Testing Skills with AskUserQuestion
See references/robust-skills.md for testing validation patterns and common test cases (valid options, custom text, invalid input, edge cases).
Key Takeaways
✅ Max constraints: 1-4 questions, 2-4 options, 12-char header
✅ Progressive disclosure: One question → wait → next question
✅ Custom input: "Other" automatic, custom text goes in answers
✅ Conditional: Ask different Q2 based on Q1 answer
✅ Validation: Always check answers before using
✅ Response format: Extract from answers object
✅ Error handling: Check for missing/invalid answers
❌ Don't: Combine multiple questions, use >4 options, include "Other" in options
See references/common-mistakes.md for detailed anti-patterns and how to avoid them.
Plan Mode: Clarifying Decisions vs. Meta-Questions
Use AskUserQuestion in plan mode to clarify real implementation decisions (database choice, monitoring config), not meta-questions ("Is my plan ready?"). For plan approval, use the plan approval tool instead. See references/advanced-patterns.md for detailed guidance.
Based on: Claude Code system prompt (tool-description-askuserquestion.md) Source: https://github.com/Piebald-AI/claude-code-system-prompts Last updated: 2026-02-25 | Version: 1.0.0
Hook Creator
Dual purpose: Create hooks right the first time OR elevate existing hooks to best practices.
Quick Routing
Use AskUserQuestion with predefined options:
questions: [
{
question: "What would you like to do?",
header: "Action",
options: [
{
label: "Create a new hook",
description: "Build a hook from scratch with proper configuration and validation"
},
{
label: "Validate existing hooks",
description: "Check hooks against best practices and production standards"
},
{
label: "Refine/improve hooks",
description: "Enhance existing hooks for clarity, efficiency, or reliability"
}
],
multiSelect: false
}
]
Then route to the appropriate workflow section based on their selection.
Quick Start
What to do: Tell hook-creator whether you want to create, validate, or improve a hook.
Then hook-creator will:
- Ask clarifying questions about your goal (hook purpose, events, scope)
- Detect your project type (Claude plugin or regular project)
- Ensure hooks go to the right location:
- Plugin project:
hooks/hooks.json(at plugin root) - Regular project:
.claude/hooks.json(in .claude directory)
- Plugin project:
- Guide you through the workflow with templates and validation checklists
What this skill does: Ensures hooks trigger reliably, execute safely, and follow production best practices. Wrong events cause missed triggers. Loose matchers waste resources. Poor error handling breaks plugins. This skill prevents all of that.
NOT for: Debugging specific hook failures in running plugins, or writing hook scripts directly.
⚠️ CRITICAL: Hook File Location
Most common hook mistake: Placing hooks in .claude-plugin/hooks.json (WRONG)
✅ CORRECT locations:
- Plugin projects (has
.claude-plugin/plugin.json): Createhooks/hooks.jsonat plugin root - Regular projects (no
.claude-plugin/): Create.claude/hooks.jsonin .claude directory
❌ WRONG location: .claude-plugin/hooks.json (only plugin.json belongs in .claude-plugin/)
If your hooks aren't firing, check the file location first.
Hook System Essentials (Quick Reference)
Hook flow: Event fires → Matcher evaluated → If matched: action executes → Decision returned → Claude Code acts
Hook types:
- command - Shell scripts (formatting, validation, deterministic logic)
- prompt - LLM decisions (Stop, SubagentStop, UserPromptSubmit, PermissionRequest, PreToolUse only)
Execution modes:
- Synchronous (default) - Blocks Claude Code; use for validation/blocking
- Asynchronous (async: true) - Background execution; use for logging, notifications, cleanup
Matchers (case-sensitive regex):
- Precise:
^(Write|Edit)$matches exactly Write or Edit - File extension:
\.js$matches .js files - Avoid:
.*(matches everything, performance killer) - Some events don't need matchers: Stop, SessionEnd, UserPromptSubmit, SessionStart (omit field)
- MCP tools:
mcp__<server>__<tool>(e.g.,mcp__memory__create_entities)
Error handling (CRITICAL - this makes or breaks hooks):
exit 0= success (no error output)exit 2= blocking error (stderr shown DIRECTLY TO CLAUDE - he can fix it)exit 1= non-blocking error (stderr only in verbose mode, Claude never sees it)- RULE: If hook needs to communicate errors to Claude, use
exit 2. Otherwise use 0 or 1. - Always set
onErrorbehavior (warn/fail/continue)
HOW COMMAND HOOKS RECEIVE DATA (CRITICAL - most common mistake):
- ❌ Environment variable substitution DOES NOT WORK:
"env": {"FILE_PATH": "${arguments.file_path}"} - ✓ Command hooks receive ALL event data via stdin as JSON, not environment variables
- ✓ Read from stdin:
INPUT=$(cat)then parse:jq '.tool_input.file_path' - See
references/command-hook-input-parsing.mdfor correct patterns and examples - This is the #1 reason command hooks appear to do nothing (scripts get no arguments)
Critical constraints:
- Matchers must be precise (overly broad = performance impact)
- Commands must be fast (<1s synchronous, up to 10s asynchronous)
- All hooks need timeout + onError handling
- Command hook scripts must pass shellcheck (run:
shellcheck script.sh)
For detailed execution model, event timing, and decision schemas: See references/how-hooks-work.md, references/event-reference.md, and references/decision-schemas.md.
Workflow by Action
Step 1: Ask what you want to do (create / validate / improve)
Step 2: Scope detection (automatic)
- Check for
.claude-plugin/plugin.json— If exists, you're in a plugin project; if not, regular project - If plugin project: Hooks go to
hooks/hooks.jsonat plugin root (or inline in plugin.json) - If regular project: Hooks go to
.claude/hooks.jsonin project's .claude directory - Refuse installed paths: If user points to
~/.claude/plugins/cache/or~/.claude/, refuse—only work with project-scoped hooks
Step 3: Route to appropriate workflow below
Create New Hooks
- Interview user (hook purpose, event type, matcher, action type, error handling)
- Load
references/templates.md— pick appropriate template (command vs prompt) - Build hook with correct JSON structure (see step 3b below)
- Validate against
references/checklist.md(syntax, event correctness, matcher precision) - Write to correct file location and test
Step 3b: Correct JSON Structure (CRITICAL)
All hooks must use this structure:
{
"hooks": {
"EventName": [
{
"matcher": {...}, // or omit for SessionStart/SessionEnd/UserPromptSubmit
"hooks": [ // ← REQUIRED: This nesting is mandatory
{
"type": "command",
"command": "...",
"timeout": 5000,
"onError": "warn"
}
]
}
]
}
}
⚠️ CRITICAL MISTAKE TO AVOID: ❌ WRONG (missing nested hooks array):
{
"hooks": {
"SessionStart": [
{
"type": "command", // ← ERROR: No "hooks" wrapper
"command": "..."
}
]
}
}
✅ CORRECT (with hooks wrapper):
{
"hooks": {
"SessionStart": [
{
"hooks": [ // ← REQUIRED wrapper
{
"type": "command",
"command": "..."
}
]
}
]
}
}
Validate Existing Hooks
- Verify hook path is project-scoped:
- Plugin project:
hooks/hooks.jsonat plugin root - Regular project:
.claude/hooks.jsonin .claude directory - Refuse installed paths (
~/.claude/plugins/cache/or~/.claude/)
- Plugin project:
- Load
references/validation-workflow.md— follow 7-phase validation (event → matcher → type → error handling → performance → integration → testing) - Use
references/checklist.mdto verify completeness at each phase - Report issues and sign off
Improve Hooks
- Verify hook path is project-scoped. Refuse installed paths.
- Ask which aspect needs improvement (event, matcher, error handling, performance)
- Load relevant reference (
references/checklist.mdfor best practices;references/validation-workflow.mdfor systematic review) - Make targeted fixes (don't rewrite everything)
- Re-validate using checklist before signing off
Outcome Metrics
Measure success by whether the hook will execute reliably and safely:
✅ Correct event - Hook triggers on the right event; understands event timing ✅ Precise matcher - Matcher correctly identifies when hook should execute (not too broad, not too narrow) ✅ Safe action - Hook action is safe, fast, and doesn't block critical paths ✅ Error handling - Hook fails gracefully; includes validation and error messages ✅ Configuration - Valid JSON/YAML syntax; correct hook.json structure ✅ Testing - Validated with real plugin scenarios; tested both success and failure cases ✅ Documentation - Clear comments explaining matcher logic and failure modes
Core Principles
Event Correctness — Right event = right trigger time (Pre vs Post). Wrong event = missed or wrong-time triggers.
Matcher Precision — Specific enough to avoid false triggers, broad enough to catch intended cases. Overly broad = performance impact; overly narrow = missed triggers.
Safe Execution — Commands must be fast (<1s) and non-blocking. Failed hooks must not crash plugins.
Error Handling — All hooks need timeouts, onError behavior, validation. Production hooks need monitoring/logging.
Reference Guide
Creating a New Hook
Step 1: Understand hook architecture
→ Hook flow: event fires → matcher evaluated → action executes → decision returned
→ Hook types: command (shell scripts) vs. prompt (LLM decisions)
→ Execution modes: synchronous (blocking) vs. asynchronous (background)
→ references/how-hooks-work.md for detailed execution model and timing
Step 2: Choose the right template
→ Copy-paste starting points for command hooks and prompt hooks
→ references/templates.md
Step 3: Select event & matcher
→ Event decision tree: PreToolUse, PostToolUse, UserPromptSubmit, PermissionRequest, Stop, SessionStart/End
→ Matcher patterns: precise regex for specific targeting (avoid .* performance killer)
→ references/event-reference.md for all available events
Step 4: Configure command vs. prompt
→ Command: deterministic logic (linting, validation) with proper exit codes
→ Prompt: intelligent decision-making with decision schemas
→ references/decision-schemas.md for schema format and validation
Step 5: Handle errors & edge cases
→ Critical: exit codes (0=success, 2=blocking error), onError behavior (warn/fail/continue)
→ Async vs. sync decision (blocking validators → sync; logging → async)
→ references/command-hook-input-parsing.md for stdin parsing (common mistake: missing input)
Step 6: Validate before deployment
→ 7-phase validation: event → matcher → type → error handling → performance → integration → testing
→ references/validation-workflow.md for systematic validation
→ references/checklist.md for production readiness checklist
Validating Existing Hooks
→ Run 7-phase validation workflow systematically
→ references/validation-workflow.md for all phases
→ references/checklist.md for quality assessment
Improving/Refining Hooks
→ Identify issues using validation workflow, make targeted improvements, re-validate
→ references/checklist.md for identifying gaps
→ Topic-specific references as needed
Production & Advanced Patterns
→ Conditional execution, fallbacks, rate limiting, monitoring, testing patterns
→ references/advanced-patterns.md for production patterns
Key Reference Points
⚠️ CRITICAL: Hook JSON Structure
The #1 mistake that breaks hooks: Forgetting the nested "hooks": [...] array.
This causes: "hooks: Expected array, but received undefined" settings error.
✅ CORRECT structure (REQUIRED for all hooks):
{
"hooks": {
"EventName": [{
"matcher": "regex-pattern", // Optional for some events
"hooks": [{ // ← DO NOT FORGET THIS WRAPPER
"type": "command",
"command": "${CLAUDE_PLUGIN_ROOT}/scripts/script.sh",
"timeout": 5000,
"onError": "warn"
}]
}]
}
}
❌ WRONG (breaks settings):
{
"hooks": {
"EventName": [{
"type": "command", // ← ERROR: Missing "hooks" array wrapper
"command": "..."
}]
}
}
Every hook action (command, prompt, agent) MUST be inside a "hooks": [...] array. This is non-negotiable.
Event selection decision tree:
- Before execution? → PreToolUse
- After success? → PostToolUse (or PostToolUseFailure for errors)
- User input validation? → UserPromptSubmit
- Session/state lifecycle? → SessionStart/SessionEnd/PreCompact
- Permission request? → PermissionRequest
- Stopping Claude? → Stop/SubagentStop
Command vs Prompt decision:
- Deterministic logic (linting, formatting, validation checks) → command (shell scripts)
- Intelligent decision-making (needs context, reasoning) → prompt (LLM, but only for Stop, SubagentStop, UserPromptSubmit, PermissionRequest, PreToolUse)
- Complex conditions (multiple branches, state checks) → command (simpler error handling, faster execution)
Async vs Synchronous execution:
-
Use
async: false(default) when:- Hook must make a blocking decision (allow/deny, validation pass/fail)
- Hook runs on PreToolUse, PermissionRequest (validation gates)
- Hook result affects Claude Code flow (blocking action, updating input)
- Hook is critical to workflow and must fail fast
-
Use
async: truewhen:- Hook is for logging/auditing (doesn't affect execution flow)
- Hook is for notifications (Slack, email, webhooks)
- Hook is for telemetry/metrics (background tracking)
- Hook is for cleanup (temp files, state reset after SessionEnd)
- Hook may be slow but shouldn't slow Claude Code
Naming convention: action-on-event (e.g., format-on-write, validate-on-prompt-submit, backup-on-compact)
For detailed reference: Templates (references/templates.md), validation workflow (references/validation-workflow.md), best practices (references/checklist.md)
Production hooks checklist (summary):
- ✅ Timeout set (<2s for command, <10s for prompt)
- ✅ onError behavior specified (warn/fail/continue)
- ✅ Matcher tested with real scenarios
- ✅ Decisions use proper JSON schemas
- ✅ Exit codes/JSON output correct
- ✅ Async mode chosen correctly
- ✅ Error handling in place (failures don't break plugin)
For detailed production patterns: See references/advanced-patterns.md (conditional execution, fallbacks, rate limiting, monitoring, testing).
Plugin Creator
Dual purpose: Create plugins from scratch OR transform existing projects into well-structured plugins.
Quick Routing
Use AskUserQuestion with predefined options to gather requirements:
questions: [
{
question: "What would you like to do?",
header: "Action",
options: [
{
label: "Create a new plugin",
description: "Build a plugin from scratch with proper manifest, structure, and components"
},
{
label: "Convert a project to plugin",
description: "Transform existing project into plugin with manifest and proper directory layout"
},
{
label: "Validate a plugin",
description: "Check plugin structure against Claude Code standards"
},
{
label: "Publish to marketplace",
description: "Prepare plugin for distribution and marketplace publication"
}
],
multiSelect: false
}
]
Then proceed to the appropriate workflow section based on their selection.
When to Use This Skill
Invoke plugin-creator in these scenarios:
Creating new plugins: Building a plugin from scratch with proper manifest, commands, agents, Skills, hooks, and/or MCP servers organized correctly.
Converting projects to plugins: Take an existing project and transform it into a Claude Code plugin with .claude-plugin/plugin.json manifest and proper directory structure.
Validating plugin structure: Check existing plugins against Claude Code plugin standards (manifest schema, directory layout, naming conventions).
Multi-component plugins: Creating plugins that bundle multiple elements (Skills, hooks, agents, MCP servers, etc.).
Team/production plugins: Building plugins for distribution across teams or deployment to plugin marketplaces.
NOT for: General Claude questions, debugging plugin behavior at runtime, writing plugin code directly (focus on structure/organization only).
⚠️ Important: Slash Commands Deprecated
Slash commands (via commands/ directory) are deprecated in favor of Agent Skills.
When creating new plugins, use Agent Skills (skills/ directory) instead. Slash commands still work for backward compatibility but are being phased out. Use skill-creator to build Agent Skills instead.
Foundation: How Plugins Work
Plugins extend Claude Code with custom functionality shared across projects and teams.
Plugin activation: Pure LLM reasoning on manifest metadata. Claude discovers plugins via:
- name: Unique identifier (plugin namespace)
- description: Tells Claude when to suggest or use the plugin
Plugin structure (at project root):
.
├── .claude-plugin/
│ └── plugin.json # Required: metadata manifest
├── skills/ # Optional: Agent Skills (recommended)
│ └── code-review/
│ ├── SKILL.md
│ └── references/
├── agents/ # Optional: subagents
│ ├── code-reviewer.md
│ └── security-auditor.md
├── hooks.json # Optional: event handlers
├── .mcp.json # Optional: MCP servers
├── .lsp.json # Optional: LSP servers
└── commands/ # DEPRECATED: Use skills instead
├── hello.md
└── review.md
Token loading hierarchy:
- Plugin manifest (150 tokens): name + description in plugin.json (always loaded for discovery)
- Component metadata (50-200 tokens each): Command files, agent descriptions, skill descriptions
- Full content (unlimited): Loaded only when Claude uses the component
Why this matters for your plugin:
- plugin.json description is your activation signal (vague = plugin never recommended when needed)
- Naming conventions are critical (plugin name becomes skill namespace in plugins)
- Directory structure must be exact (Claude Code uses path conventions to discover components)
- Component metadata must be clear (descriptions tell Claude what each command/agent/skill does)
Quick Start: Create a Plugin in an Empty Project
Copy-paste templates for creating a plugin structure from scratch: manifest, skills, agents, and testing. See references/quick-start-guide.md for complete bash commands and examples.
Choose Your Workflow
START HERE: Always begin by asking the user to clarify their intent and collect all required manifest data using AskUserQuestion (one question at a time, progressive disclosure):
Interview Flow for New Plugin Creation
For users creating a new plugin, conduct this structured interview to gather all manifest.json fields before file creation. Use the predefined options format shown in Quick Routing above for Step 1.
-
Action - Use the predefined options from "Quick Routing" section above
- Create a new plugin (→ proceed to 2-9)
- Convert a project (→ skip to Converting Projects section)
- Validate a plugin (→ skip to Validating Plugins section)
- Publish to marketplace (→ skip to Publishing to Marketplace section)
-
Plugin name - "What's the plugin name?" (lowercase-hyphen, 1-64 chars)
- Maps to:
plugin.json→namefield - Example:
code-reviewer,pdf-processor
- Maps to:
-
Purpose/description - "What does the plugin do? Describe its main purpose and capabilities."
- Maps to:
plugin.json→descriptionfield (1-1024 chars) - Example: "Review code for best practices and potential issues."
- Maps to:
-
Version - "What version? (semantic format: MAJOR.MINOR.PATCH)"
- Maps to:
plugin.json→versionfield - Default if not specified:
1.0.0
- Maps to:
-
Author information - "Who is the author? (name, optional: email, URL)"
- Maps to:
plugin.json→authorobject withnamefield (REQUIRED) - Format:
{"name": "Your Name", "email": "optional@email.com", "url": "https://optional.url"} - CRITICAL: author must be object, not string (common failure point)
- Maps to:
-
Optional metadata - "Any additional metadata? (license, repository, homepage)"
- Maps to:
plugin.json→license,repository,homepagefields - Example:
"MIT","https://github.com/user/plugin","https://docs.example.com"
- Maps to:
-
Components (BATCH 1) - Use AskUserQuestion with predefined options (multiSelect: true):
questions: [
{
question: "Which core components will the plugin include?",
header: "Core Components",
options: [
{ label: "Skills", description: "Agent Skills (recommended)" },
{ label: "Agents", description: "Subagents for complex workflows" },
{ label: "Hooks", description: "Event handlers and automation" },
{ label: "MCP servers", description: "Model Context Protocol servers" }
],
multiSelect: true
}
]
- Components (BATCH 2) - Then use AskUserQuestion for optional server support:
questions: [
{
question: "Include Language Server Protocol (LSP) support?",
header: "LSP Servers",
options: [
{ label: "Yes", description: "Add language-specific code intelligence" },
{ label: "No", description: "Skip LSP servers" }
],
multiSelect: false
}
]
⏸️ Wait for both batch responses before proceeding.
- Distribution scope - Use AskUserQuestion with predefined options:
questions: [
{
question: "What's the distribution scope for this plugin?",
header: "Distribution",
options: [
{ label: "Personal", description: "Personal use only" },
{ label: "Team-shared", description: "Share with team members" },
{ label: "Marketplace", description: "Publish to plugin marketplace for community" }
],
multiSelect: false
}
]
Manifest Field Mapping Reference
| Interview Question | Maps to | Type | Required | Notes |
|---|---|---|---|---|
| Action | (routing logic) | string | Yes | Determines workflow path |
| Plugin name | plugin.json → name | string | Yes | kebab-case, 1-64 chars, no spaces |
| Purpose/description | plugin.json → description | string | Yes | 1-1024 chars, clear and specific |
| Version | plugin.json → version | string | No | Semantic versioning (default: 1.0.0) |
| Author name | plugin.json → author.name | string | Yes | Must be object property, not string |
| Author email | plugin.json → author.email | string | No | Optional contact information |
| Author URL | plugin.json → author.url | string | No | Optional profile/website |
| License | plugin.json → license | string | No | e.g., "MIT", "Apache-2.0" |
| Repository | plugin.json → repository | string | No | GitHub/GitLab URL |
| Homepage | plugin.json → homepage | string | No | Documentation URL |
| Components (BATCH 1) | Directory structure | array | No | Skills, Agents, Hooks, MCP servers (max 4 options) |
| Components (BATCH 2) | Directory structure | boolean | No | Include LSP servers (yes/no) |
| Distribution scope | marketplace.json | string | No | "personal", "team", or "marketplace" |
Common Manifest Generation Failures (Prevention)
Failure: author is string instead of object
- ❌ Wrong:
"author": "John Doe" - ✅ Correct:
"author": {"name": "John Doe"} - Prevention: Always structure author as object in template
Failure: Missing required fields
- Check:
name,description,author.nameare always present - Validate before writing plugin.json
Failure: Incorrect marketplace.json schema
- Critical requirements:
ownerMUST be object:{"name": "username"}pluginsMUST be array:[{...}]sourceMUST start with./
- See "Publishing to Marketplace" section for full schema
Based on their answers, route to the appropriate workflow section below:
Automated Scanning Phase (For Validation)
When validating existing plugins, always run the automated scanning phase FIRST before manual validation.
See references/automated-scanning-workflow.md for complete scanning workflow, decision handling, and example validation sequences. The scanner is read-only only—it scans and reports, never modifies. All user decisions are explicit and visible.
Quick reference: Run the scanner, process errors/warnings, use AskUserQuestion for decisions, execute approved changes, re-scan, then proceed to manual validation.
1. Creating a New Plugin from Scratch
Interview requirements → create structure → add components → run claude plugin validate → test locally
See references/implementation-workflow.md for complete step-by-step procedures.
2. Converting an Existing Project to a Plugin
Identify components → create plugin structure → migrate and update metadata → run claude plugin validate → test locally
See references/implementation-workflow.md for complete step-by-step procedures.
3. Validating or Improving Existing Plugins
FIRST: Run claude plugin validate /path/to/plugin directly. Review output for errors. THEN: Do manual checks for best practices from references/validation-checklist.md.
4. Publishing to Marketplace
Make your plugin installable via claude plugin marketplace add owner/repo.
Step 1: Ensure plugin.json exists at .claude-plugin/plugin.json
Step 2: Create .claude-plugin/marketplace.json with this structure:
{
"name": "your-plugin-name",
"owner": {
"name": "github-username-or-org"
},
"plugins": [
{
"name": "your-plugin-name",
"source": "./",
"description": "What the plugin does"
}
]
}
CRITICAL schema requirements:
ownerMUST be an object withnamefield, NOT a stringpluginsMUST be an array (can be empty[])sourcepaths MUST start with./
Step 3: Validate with claude plugin validate /path/to/plugin
See references/team-marketplaces.md for complete marketplace schema and common errors.
Manifest Generation Best Practices
BEFORE generating manifests, verify you have all required data:
- ✅ Plugin name (kebab-case, 1-64 chars)
- ✅ Description (clear, 1-1024 chars)
- ✅ Author name (will be in object:
{"name": "..."}) - ✅ Version (semantic format, default: 1.0.0)
ALWAYS structure author as object:
{
"name": "my-plugin",
"description": "What it does.",
"version": "1.0.0",
"author": {
"name": "Your Name"
}
}
NEVER generate with incomplete data - Incomplete manifests cause validation failures. Run the interview flow first, collect all fields, then proceed with generation.
For marketplace.json, use official schema:
{
"name": "plugin-name",
"owner": {
"name": "github-username"
},
"plugins": [
{
"name": "plugin-name",
"source": "./",
"description": "What it does"
}
]
}
Quick Start: 5-Minute Setup
Create plugin directory:
mkdir -p my-plugin/.claude-plugin
mkdir -p my-plugin/commands my-plugin/agents my-plugin/skills
Write plugin.json:
{
"name": "my-plugin",
"description": "[Action]. [Brief description of purpose and capabilities].",
"version": "1.0.3"
}
Add components:
- Agent Skills:
.mdfiles inskills/(recommended approach) - Other components: See "Component Overview" section below
- Test:
claude --plugin-dir /path/to/my-plugin
Reference Guide
Creating a New Plugin
Step 1: Understand plugin architecture
→ How plugins load, token costs, standard directory layout, manifest format
→ references/plugin-architecture.md for architecture overview
→ references/directory-structure.md for standard layout
→ references/plugin-json-schema.md for plugin.json format
Step 2: Set up plugin structure & manifest
→ Create .claude-plugin/plugin.json with metadata (name, description, version)
→ Templates and common patterns for quick setup
→ references/quick-reference.md for templates and metadata requirements
Step 3: Add Agent Skills, Hooks, or other components
→ Agent Skills: recommended approach, .md files in skills/
→ Hooks: event handlers in hooks.json
→ Subagents: isolated execution in agents/
→ External services: MCP servers, LSP for code intelligence
→ references/components-in-plugins.md for packaging guidance
→ Use skill-creator, subagent-creator, or hook-creator skills to build components
Step 4: Validate & test locally
→ Run claude plugin validate /path for errors
→ Run claude --plugin-dir /path for local testing
→ Check best practices from validation checklist
→ references/validation-checklist.md for comprehensive checks
→ references/local-development.md for debugging
Converting Existing Project to Plugin
→ Complete step-by-step procedures for converting projects to plugins
→ references/implementation-workflow.md for full conversion workflow
→ references/automated-scanning-workflow.md for scanning & validation phase
Publishing & Distribution
→ Semantic versioning, changelog, marketplace setup
→ references/versioning-and-distribution.md for versioning
→ references/team-marketplaces.md for marketplace.json schema and multi-plugin registries
Advanced Topics
Path handling & caching:
→ Use ${CLAUDE_PLUGIN_ROOT} variable in hooks/scripts. Plugins are cached for security.
→ references/plugin-paths-variables.md for path guidance
→ references/plugin-caching.md for caching behavior
Installing & managing plugins:
→ Installation scopes (global, project), CLI commands (install/uninstall/enable/disable/update)
→ references/installation-and-cli.md for scope and commands
Troubleshooting & production:
→ Debugging plugins, common issues, best practices, production checklist
→ references/troubleshooting-and-production.md
Integration patterns:
→ External service integration (MCP servers), language-specific intelligence (LSP)
→ references/mcp-servers.md for MCP configuration
→ references/lsp-servers.md for LSP integration
Legacy support:
→ Command file format (deprecated, for backward compatibility only)
→ references/slash-command-format.md for legacy command support
Component Overview
See references/quick-reference.md for component templates, formats, and metadata requirements.
| Component | Use Case |
|---|---|
Agent Skills (skills/) | Capabilities Claude uses automatically or via /skill-name (recommended) |
Subagents (agents/) | Isolated execution environments with custom prompts, tools, and permissions (use subagent-creator skill) |
Hooks (hooks.json) | Event handlers (tool use, permissions, sessions) (use hook-creator skill) |
MCP Servers (.mcp.json) | External service integration (APIs, databases) |
LSP Servers (.lsp.json) | Language-specific code intelligence |
Commands (commands/) | DEPRECATED: Use Agent Skills instead |
Key Notes
Plugin naming conventions: Hyphen-separated lowercase (code-reviewer, pdf-processor, test-runner). Include action/domain; becomes plugin namespace /plugin-name for skills, commands, hooks.
Description formula (Claude's activation signal):
[Action]. [Brief description of purpose]. [Components/scope].
Example: "Review code for best practices and potential issues. Includes validate, report, and export commands."
CLI commands: claude plugin install|uninstall|enable|disable|update <name>@<marketplace> [--scope user|project|local]
Important paths note: Plugins are cached (not in-place) for security. Use ${CLAUDE_PLUGIN_ROOT} variable in hooks/scripts for paths. See references/plugin-paths-variables.md for details.
Installation scopes:
user(global):~/.claude/skills/(all projects)project(shared):.claude/skills/(via git)local(personal):.claude/skills/(not shared)managed(read-only): System cache (marketplace plugins)
See references/installation-and-cli.md for scope and CLI details.
Validation Checklist
Step 0 (AUTOMATED SCANNING): For existing plugins, run the automated scanner first to catch common issues:
bash /path/to/plugin-creator/scripts/scan-plugin.sh /path/to/plugin /tmp/plugin-scan.json
Review the JSON output and use AskUserQuestion to handle any decisions (file cleanup, permissions, etc.). See "Automated Scanning Phase" section above for details.
Step 1 (REQUIRED): Run the validation command directly:
claude plugin validate /path/to/plugin
Do NOT create wrapper scripts. Run this command directly and review its output.
Step 2: If validation passes, check best practices from references/validation-checklist.md:
- Manifest description includes specific trigger phrases
- Component metadata is clear and complete
- Security: No hardcoded secrets, safe shell patterns, proper permissions
- Documentation: README.md, CHANGELOG.md present for distributed plugins
- Test locally with
claude --plugin-dir /path/to/plugin
Skill Composer
Purpose: Create new Claude Code skills from scratch following best practices. Use when building skills from scratch or converting existing slash commands to project-scoped skills.
Mindset
CRITICAL: Skills are instructions FOR CLAUDE, not documentation FOR PEOPLE. Always ask: "Will this help Claude execute the task?" not "Will people find this readable?"
Quick Start
Start at Implementation Approach below.
Core Use Cases
Create new skills - Build from scratch with correct structure, naming, frontmatter, and validation guidance.
Convert slash commands - Migrate existing ~/.claude/commands/ slash commands to project-scoped skills (better context management, subagent support).
Complex skills - Ensure robustness with error handling, tool scoping, and version tracking.
Core Principles
These principles apply to all skill creation and validation work—the foundational mental model Claude must follow.
Self-Containment — Skills must be self-contained. Claude needs everything within the skill directory (references, scripts, examples). Avoid external references or network dependencies unless core to the skill's purpose. When deciding about external dependencies, see references/self-containment-principle.md for architectural background.
Progressive Disclosure — Essential execution instructions first (Quick Start), detailed guidance second (references/), advanced topics last. Quick reference patterns solve 80% of task variants without loading auxiliary files.
Token Efficiency — Every token Claude loads must justify its cost for execution. Keep SKILL.md body <500 lines (non-negotiable). Use code examples before prose, tables instead of lists.
The 80% Rule: Core procedural content (used in 80%+ of skill activations) stays in SKILL.md. Example: release-process skill keeps standard workflows (patch/feature/breaking) in SKILL.md since every release uses them. Supplementary content (<20% of cases) moves to references/. Example: advanced monorepo coordination moves to references/ since most releases are single-component. Never delete content to reduce line count if it impairs execution. See references/skill-workflow.md for decision rules and preservation gates.
Token Loading — Metadata (~100 tokens) always loads. SKILL.md body (~1-5k tokens) loads on trigger. References load on-demand only (zero penalty until needed). For token loading mechanics and activation internals: references/how-skills-work.md.
Activation — Skills trigger via description text alone. Vague descriptions never activate. Include specific trigger phrases Claude will recognize in user requests (e.g., "create skill", "validate skill", "improve", "refine skill").
Implementation Approach
▶️ START HERE - Establish Action & Scope
Interview 1: Ask - What do you want to do?
Use AskUserQuestion with predefined options:
Ask: "What do you want to do?" (header: "Action") Options: "Create a new skill" | "Convert a slash command"
⏸️ Collect user input — Wait for response to Interview 1 before proceeding.
Interview 2: Ask - Where should the skill be created?
(Unified step for BOTH paths — regardless of whether creating from scratch or converting a slash command, establish the skill's location first. This applies before branching to the specific workflow.)
Use AskUserQuestion with predefined options:
Ask: "Where should this skill be created?" (header: "Skill Scope") Options: "Project-scoped (.claude/skills/)" | "User-space (~/.claude/skills/)" | "Plugin-scoped (skills/ in plugin)"
Critical guidance for Agent:
- ❌ NEVER default to user-space without asking (affects all projects)
- ❌ NEVER create in plugin/skills/ unless explicitly in a plugin project
- ✅ Always confirm scope with user first
- ✅ Default recommendation: Project-scoped (.claude/skills/) for isolated work
⏸️ Collect user input — Wait for response to Interview 2 before proceeding.
Step 3: Route based on action selection
Use the action choice from Interview 1 to route to the appropriate workflow. The location from Interview 2 applies to both paths:
- Action: "Create a new skill" → Proceed to "Create New Skill Workflow" section (use location for new skill placement)
- Action: "Convert a slash command" → Proceed to "Convert Slash Command to Skill" section (use location for converted skill placement)
For New Skills: Requirements Interview with Escape Hatch
After routing to "create", gather requirements using progressive disclosure (AskUserQuestion, one batch at a time). This ensures the skill will activate correctly and Claude will execute it effectively.
Step 1: Detect Predating Context
Check conversation history before the skill request:
- User provided URLs, documentation, or code snippets?
- User gave detailed explanation of what needs to be built?
- User asked to "create skill for this" or similar?
Step 2: Route Based on Context
IF NO PREDATING CONTEXT → Full interview (BATCH 1 + BATCH 2)
IF PREDATING CONTEXT EXISTS → Use AskUserQuestion to offer escape hatch:
Ask: "I've reviewed the docs/code/context you provided. How would you like to proceed?" (header: "Interview Style") Options: "Infer from context" | "Define explicitly"
Then route based on their choice:
- "Infer from context" → Skip BATCH 1, go straight to BATCH 2
- "Define explicitly" → Full interview (BATCH 1 + BATCH 2)
🔴 BATCH 1: Core Definition (Prose questions with guidance):
Do this batch if: no predating context exists, OR user chose "Define explicitly" in the escape hatch. Skip only if user chose "Infer from context."
Question 1: Skill Purpose
What domain-specific task should Claude execute? What problem does this skill solve?
Describe the skill's purpose and what problem it solves.
(Be specific — "Process PDFs with OCR" is better than "Process files")
[User responds with description]
Question 2: Trigger Phrases
What phrases will Claude see in user requests that should trigger this skill?
List the specific trigger phrases Claude will recognize:
Examples:
- "create skill" (for a skill-creator)
- "validate code" (for a linter)
- "convert to plugin" (for converter)
(Include 2-5 key phrases)
[User responds with trigger phrases]
Question 3: Scope & Constraints
What's IN scope for this skill versus OUT of scope?
Define the boundaries:
Examples:
- IN: "Create new skills, guide best practices"
- OUT: "Refine existing skills (use skill-refiner instead)"
(Clarify what this skill handles and what it doesn't)
[User responds with scope definition]
⏸️ Wait for all 3 responses.
🟢 BATCH 2: Complexity & Tools (Structured + Prose):
Question 1: Complexity (Structured choice)
Use AskUserQuestion with predefined options (different workflows apply):
Ask: "What's the skill's complexity level?" (header: "Complexity") Options: "Simple" (SKILL.md only, minimal structure) | "Complex" (multiple workflows, reference files/scripts)
[User selects Simple or Complex]
Question 2: Tool Requirements (Prose guidance)
Which tools will Claude need to execute this skill?
List the tools from this set:
- Read, Write (file operations)
- Bash (shell commands)
- Glob, Grep (file searching)
- AskUserQuestion (user input)
- WebFetch, WebSearch (internet access)
- Other tools as needed
Examples:
- "Read, Write, Bash"
- "Read, Write, AskUserQuestion"
- "Glob, Grep, Bash"
[User lists tools needed]
⏸️ Wait for both responses.
Step 3: Create Skill Structure
Execute the skill creation using your gathered requirements (BATCH 1-2 responses).
Step 3.1: Create skill directory in chosen location
Use the location from Implementation Approach Interview 2:
- Project-scoped:
mkdir -p .claude/skills/skill-name - User-space:
mkdir -p ~/.claude/skills/skill-name - Plugin-scoped:
mkdir -p skills/skill-name
Step 3.2: Check if templates needed and use them
Refer to references/templates.md to apply the template matching your BATCH 1-2 responses (skill purpose, complexity, tools needed). Copy or use template as reference while building.
Step 3.3: Write frontmatter
Create SKILL.md with required metadata. Frontmatter is what Claude reads to discover and activate skills:
---
name: skill-name
description: >-
What the skill does. Use when [trigger context]. Constraints/scope.
---
Guidelines for Claude's activation:
- name: lowercase, hyphens, ≤64 chars, no "anthropic"/"claude" (Claude uses this to reference the skill)
- description: ≤1024 chars, must include trigger phrases Claude will recognize in requests
For detailed frontmatter patterns, naming conventions, description formulas, and edge cases: See the Frontmatter section in Key Notes below.
Step 3.4: Write SKILL.md body
Write instructions Claude will follow to execute the task. Structure: Quick Start → Workflows → Key Notes → Full Reference (optional)
- Target <500 lines (Claude reads this body every time skill triggers; token efficiency is mandatory)
- Code-first: examples Claude can adapt before abstract explanations
- Progressive disclosure: essentials Claude needs immediately → advanced topics later
Step 3.5: Content-Size Check
After writing the body, evaluate what you've created:
- Count total lines of SKILL.md body + any planned reference content
- Check size:
- < 500 lines total? → Skip to Step 3.8 (Validate). No references/ directory needed.
- ≥ 500 lines total? → Proceed to Step 3.6 (Create references/). Split content across files.
User Feedback (if complexity/content mismatch):
If user selected "Complex" BUT total content < 500 lines:
You selected Complexity: Complex
Total content generated: [X lines]
Since the total content is [X lines] (under 500 line threshold),
I'm keeping everything in SKILL.md for now. No separate references needed yet.
As the skill grows beyond 500 lines, we'll split into references/ to maintain token efficiency.
Step 3.6: Create references/ (conditional)
Only proceed if Step 3.5 indicated ≥500 lines total:
mkdir -p skill-name/references
Step 3.7: Add references (conditional)
Only proceed if Step 3.6 created the references/ directory:
Move supplementary content (<20% of activations) into reference files. Create table of contents for comprehensive guides. Keep one level deep (no nested subdirectories).
Step 3.8: Validate
Check structure, content, security, activation. See references/checklist.md for comprehensive validation across all dimensions before deployment.
Step 3.9: Optional — Refine Your Skill
Question: Would you like to refine the skill before testing it?
Use AskUserQuestion:
questions: [
{
question: "Would you like to refine this skill before testing?",
header: "Next Step",
options: [
{
label: "Yes, refine with skill-refiner",
description: "Improve skill clarity, efficiency, structure. Validate against best practices (optional iteration)"
},
{
label: "No, skip refinement",
description: "Proceed directly to testing or completion"
}
],
multiSelect: false
}
]
⏸️ Collect user input.
If user chose "Yes, refine now":
Tell user: "Launching skill-refiner. This will validate and improve your skill's quality."
Then delegate to skill-refiner using Agent tool:
Agent type: general-purpose
Prompt: "
The user just finished creating a new skill at <skill_path>.
They want to refine it using skill-refiner.
Invoke skill-refiner to:
1. Analyze the skill (structure, clarity, efficiency)
2. Identify improvement opportunities
3. Apply refinements (wording, organization, token optimization)
4. Validate final quality
After refinement completes, tell the user: 'Skill refined. Ready for testing?'
Then stop and let the original skill-creator workflow offer testing."
If user chose "No, skip refinement":
Continue to Step 3.10 (testing step below).
Step 3.10: Optional — Test Your Skill (Empirical Validation)
Question: Would you like to test this skill empirically?
Use AskUserQuestion:
questions: [
{
question: "Would you like to test this skill empirically?",
header: "Testing",
options: [
{
label: "Yes, test now with skill-tester",
description: "Run quick validation: design test cases, test your new skill, show pass/fail results (fast feedback)"
},
{
label: "No, done",
description: "Skill is complete. You can test anytime with /skills-toolkit:skill-tester"
}
],
multiSelect: false
}
]
⏸️ Collect user input.
If user chose "Yes, test now":
Tell user: "Launching skill-tester (Quick Workflow). This will create an evals/ workspace, run test cases with the new skill, and show pass/fail results. No baseline comparison—just a sanity check."
Then delegate to skill-tester using Agent tool:
Agent type: general-purpose
Prompt: "
The user just finished creating a new skill at <skill_path>.
They want to quickly test it using skill-tester's QUICK WORKFLOW mode (not full pipeline).
Invoke skill-tester to:
1. Confirm the skill (Phase 1: Setup)
2. Interview user for test scenarios (Phase 2: Create Evals)
3. RUN QUICK WORKFLOW (fast validation):
- Test the new skill on the scenarios
- Grade if it passes the test criteria
- Show simple pass/fail results
- Ask: Refine? Run full benchmarking? Done?
QUICK MODE: Just test the skill itself, no comparisons.
The evals/ workspace should live at ./evals/<skill-name>/
Tell the user: 'Quick test complete. Results show if the skill works as intended.'"
If user chose "No, done":
Confirm: "Skill created and (optionally refined). You can test it anytime with /skills-toolkit:skill-tester."
Convert Slash Command to Skill
Shorthand: Recommend skill migration for complex commands or team/project-scoped automation. Self-convert simple commands (1-10 lines); offer help for complex logic or unclear structure.
Full conversion workflow: See references/slash-command-conversion.md for detection, mapping, conversion logic, and validation process.
Key Notes
Wizard Pattern (this skill models the pattern it teaches) - CRITICAL EXECUTION RULE: Progressive disclosure ALWAYS means: ask ONE question, wait for response, then ask next. Never combine questions into a single AskUserQuestion call.
- ❌ WRONG: Ask 2 questions in one AskUserQuestion (looks like a form)
- ✅ RIGHT: Ask question 1 → wait for response → then ask question 2 (if conditional) When tool has constraints (maxItems: 4), this pattern is mandatory. Applied in "For Improvements (Refining)" section's approval workflow. Claude must follow this pattern when implementing guided user interactions in skills.
Frontmatter (Claude reads this to discover and activate skills):
- YAML syntax (use triple dashes:
---) name: Optional (uses directory name if omitted), lowercase-hyphen, ≤64 chars, no "anthropic"/"claude"description: Recommended, ≤1024 chars, must include specific trigger phrases Claude recognizes- Description is Claude's activation signal (vague descriptions = skill never activates)
Optional frontmatter (for complex skills):
version: 1.0.0— Track skill evolution for coordinationallowed-tools: Read,Write,Bash(git:*)— Declare only tools Claude needs. Restrict Bash to specific commands (e.g.,Bash(git:*)). Seereferences/allowed-tools.mdfor tool scoping validation.- Copy tool patterns from
references/templates.mdfor reference
Naming conventions:
- Hyphen-separated lowercase:
skill-name,my-feature-validator - Prefer gerund form:
processing-pdfs,analyzing-spreadsheets - Include action/domain:
test-runner,skill-creator,code-reviewer - Avoid generic: prefer
log-analyzeroveranalyzer
Description formula (Claude uses this to decide whether to activate):
[Action]. Use when [trigger contexts]. [Scope/constraints].
Example: "Run tests and generate reports. Use when validating code before commit. Supports PHPUnit and Jest."
✅ Good descriptions include specific trigger phrases Claude will recognize in user requests (e.g., "create", "validate", "improve", "refine").
❌ Vague descriptions (e.g., "Process things") never activate the skill when users need it.
Complex skill considerations: For complex skills requiring robust structure, ensure error handling, tool scoping, validation scripts, security review, and clear documentation. See references/complex-skills-patterns.md for detailed guidance on these patterns, plus references/advanced-patterns.md and references/checklist.md for additional requirements.
Secrets & credentials: Skills must never contain hardcoded secrets (API keys, passwords, tokens). Use environment variables instead, validate they're set, and provide clear error messages. Never commit .env files or credentials to git. See references/secrets-and-credentials.md for complete guidance on detection, handling, git safety, and testing patterns.
Content distribution rule: Apply the 80% Rule principle: keep core procedural content in SKILL.md <500 lines total. Supplementary content (<20% of activations) moves to references/. Reference files have zero token penalty until needed. See the Content-Size Check section for sizing logic.
Reference Linking Pattern (when your skill has references):
Every reference link teaches agents what they're looking for, so they decide confidently whether to load it:
- ❌ WRONG:
Seereferences/advanced-patterns.mdfor more info.(Agent: "What's in there? Better load it to be safe.") - ✅ RIGHT:
Pattern: [core idea]. Seereferences/advanced-patterns.mdfor [edge cases/advanced scenarios].(Agent: "I have the pattern. The reference has detailed cases I might need.")
Template:
[What agents need 80% of the time]. See `references/<filename.md>` for [what depth/edge cases are there].
Example:
**The 80% Rule:** Will Claude execute this 80%+ of activations? → STAYS in SKILL.md. <20% cases? → MOVES to references/. See `references/<80-percent-rule.md>` for decision trees and edge cases.
Why? Without context, agents load references out of uncertainty (wastes tokens). With context, they load references intentionally when needed. The reference becomes more valuable, not less.
Base Directory context: When skill-creator loads, the system shows a "Base directory" path. This points to THIS skill's installed location—use it ONLY for loading skill-creator's own references (references/templates.md, etc.). Never use it to locate target skills you're asked to work on. Target skills must be discovered via the "Locate the Target Skill" workflow.
Reference Guide
Structuring Your Skill
Step 1: Choose the right template → Decision: Simple (SKILL.md only, <300 lines) or Complex (multiple references/scripts)? Each template shows: frontmatter + Quick Start + core sections + validation. references/templates.md
Step 2: Write frontmatter & descriptions → Pattern: [Action]. Use when [trigger contexts]. [Scope]. Include specific trigger phrases Claude recognizes. Example: "Create skills. Use when building new Claude Code skills from scratch." references/content-guidelines.md for phrase library and activation examples
Step 3: Organize content using 80% rule → Core procedural (80%+ of skill activations) → SKILL.md body (<500 lines). Supplementary (edge cases, <20%) → references/ subdirectory. Progressive disclosure: Quick Start → Workflows → Advanced sections. references/skill-workflow.md for detailed content distribution framework
Step 4: Design user interactions → Rule: Max 4 AskUserQuestion options per question. Progressive disclosure: ask → wait → ask next (never combine into forms). references/ask-user-question-patterns.md for interaction patterns and decision trees
Step 5: Validate quality before release → Checklist: (1) Frontmatter complete, (2) <500 lines, (3) 80% rule applied, (4) All references complete, (5) Tool scoping matches needs, (6) Tested with real trigger phrases. references/checklist.md for comprehensive validation across all dimensions
Step 6: Avoid common mistakes → 16 patterns: thinking of skills as documentation, orphaned references, vague descriptions, moving content just to reduce lines, etc. Each mistake has BAD/GOOD example showing what to do instead. references/anti-patterns.md
Understanding Skill Fundamentals (Optional Deep Dive)
How skills are loaded and activated: → Frontmatter (~100 tokens) always loads for discovery. SKILL.md body (~1-5k tokens) loads when skill triggers. References load on-demand (zero penalty until needed). references/how-skills-work.md for token loading mechanics and activation internals
Building Complex Skills
Error handling, security, tool scoping: → Robust patterns: validation scripts, error recovery, security review, documentation. references/complex-skills-patterns.md
Preventing secret leaks: → Never hardcode API keys, passwords, tokens. Use environment variables, validate at startup, provide clear error messages if missing. Never commit .env files to git. references/secrets-and-credentials.md for detection, handling, git safety, and testing patterns
Tool scoping (principle of least privilege): → Declare only tools Claude needs. Restrict Bash to specific commands (e.g., Bash(git:*)). references/allowed-tools.md for scoping validation and security patterns
External dependencies & self-containment: → Skills should contain everything they need (references, scripts, examples). Avoid external APIs unless core to skill purpose. references/self-containment-principle.md for architectural guidance
Complex skill patterns & specialized skills: → Patterns for robustness: encoding reproducible prompts, front-loading motivation, documenting ecosystem integration, risk tiering for safety, exit code standardization, ASCII flow diagrams, configuration precedence documentation, extended thinking signals, iteration protocols, dynamic context injection (live data preprocessing), impact tiering, and outcome metrics. Skill archetypes: CLI reference tools, methodology guides, safety/security tools, orchestration systems. references/advanced-patterns.md for full pattern library and detailed examples
Skill Refiner
Systematically improve and validate Claude Code skills while preserving functionality and following established patterns.
Quick Start
Step 0: Detect Predating Context (Escape Hatch)
Check conversation history:
- User already provided the skill file or shared code?
- User already described the problem/issue?
- User is actively discussing a skill's problems?
IF PREDATING CONTEXT EXISTS → Offer escape hatch immediately:
questions: [
{
question: "I've reviewed the skill and context you provided. How would you like to proceed?",
header: "Interview Style",
options: [
{
label: "Infer from context",
description: "I'll infer refinement needs from what you shared. Skip detailed interview (faster)"
},
{
label: "Define explicitly",
description: "I'll ask you to explicitly define improvement areas and goals (full interview)"
}
],
multiSelect: false
}
]
Then route:
- "Infer from context" → Skip to BATCH 2 with context-tailored prompts
- "Define explicitly" → Full BATCH 1 + BATCH 2
IF NO PREDATING CONTEXT → Continue to Step 1
Step 1: Use AskUserQuestion to ask: "What skill do you want to work on?" (open-form text input)
Step 2: Use AskUserQuestion with predefined options to ask:
questions: [
{
question: "What would you like to do with this skill?",
header: "Action",
options: [
{
label: "Refine",
description: "Improve clarity, structure, efficiency, token usage, or organization"
},
{
label: "Validate",
description: "Check if it's production-ready (tool scoping, completeness, error handling, trigger phrases)"
}
],
multiSelect: false
}
]
Step 3: Route based on their selection:
- If "Refine" → Proceed to Core Workflow: Refinement (you'll be asked BATCH 1 + BATCH 2 interview questions during the workflow)
- If "Validate" → Skip interview, go directly to Core Workflow: Validation
Core Workflow: Refinement
When user requests refinement:
- Locate the skill (MANDATORY first step)
- Search current project first:
skills/skill-name/,.claude/skills/skill-name/ - If not found in project → Check user-space:
~/.claude/skills/skill-name/ - If found in user-space → WARN: "This affects all projects. Continue?"
- If in cache (
~/.claude/plugins/cache/) → REFUSE: "That's an installed copy (read-only)" - If not found anywhere → ASK: "Where should I find this skill?"
- Search current project first:
Requirements Interview (Progressive Disclosure - One Batch at a Time)
After locating the skill, interview to gather what they want improved using AskUserQuestion with proper options.
🔴 BATCH 1: Refinement Focus (Progressive AskUserQuestion - ask one at a time):
Question 1: What aspects need improvement?
questions: [
{
question: "What aspects need improvement?",
header: "Focus Areas",
options: [
{ label: "Clarity", description: "Make instructions clearer, remove jargon, improve examples" },
{ label: "Efficiency", description: "Reduce token usage, consolidate references, optimize content" },
{ label: "Structure", description: "Reorganize sections, improve flow, better grouping" },
{ label: "User Interaction UX", description: "Convert free-form interactions to AskUserQuestion patterns, improve workflows" }
],
multiSelect: true
}
]
Question 2: What specific problems are you seeing?
questions: [
{
question: "What specific problems are you seeing?",
header: "Key Issues"
}
]
(Examples: "Instructions are hard to follow", "References scattered and redundant", "Too many nested sections")
Question 3: What would success look like?
questions: [
{
question: "What would success look like?",
header: "Success Metric"
}
]
(Examples: "Clearer workflow", "Fewer token costs", "Production-ready with error handling")
Question 4: Any areas to exclude or preserve as-is?
questions: [
{
question: "Any areas to exclude or preserve as-is?",
header: "Scope Limits"
}
]
(Examples: "Keep the validation gates", "Don't change tool scoping")
After gathering ALL responses, document approved scope and proceed to BATCH 2.
🟢 BATCH 2: Implementation Details (Use AskUserQuestion with predefined options)
ROUTING NOTE:
- If user chose "Infer from context" in escape hatch → Skip BATCH 1, come straight here
- If user chose "Define explicitly" → Proceed after BATCH 1 responses
- Context-Aware Prompts: When inferring from context, tailor questions to specific issues mentioned (e.g., "I saw token usage issues in references. Consolidate them?" vs generic "Should we consolidate?")
questions: [
{
question: "Should we consolidate related reference files to reduce scattered content?",
header: "References",
options: [
{ label: "Yes", description: "Merge related files for clarity" },
{ label: "No", description: "Keep current structure" }
],
multiSelect: false
},
{
question: "Should we also validate against production standards?",
header: "Production Validation",
options: [
{ label: "Yes", description: "Check error handling, tool scoping, security" },
{ label: "No", description: "Skip production validation" }
],
multiSelect: false
},
{
question: "Should we add testing & validation patterns (evaluation framework, test patterns, quality gates)?",
header: "Testing & Validation",
options: [
{ label: "Yes", description: "Add evaluation framework and quality gates" },
{ label: "No", description: "Skip testing patterns" }
],
multiSelect: false
}
]
After gathering ALL responses, document approved scope and proceed.
-
Load workflow reference
- Review
references/refinement-workflow.mdfor the complete refinement workflow with all preservation gates and validation phases
- Review
-
Identify consolidation opportunities (BEFORE changes)
- List all files in
references/directory with line counts - Group by topic (what do they cover?)
- Flag potential merges (2-4 files on same topic → 1 consolidated file)
- ASK: "Should we consolidate these files? Saves N lines, improves clarity"
- Only proceed if operator approves
- List all files in
-
Apply preservation gates (CRITICAL - four gates, in order)
- GATE 1: Content Audit - list ALL existing content, classify as core (80%+) or supplementary (<20%)
- GATE 2: Capability Assessment - will changes impair execution? If YES → cannot delete, only migrate
- GATE 3: Migration Verification - before moving content, verify destination exists and is complete
- GATE 4: Operator Confirmation - deletions require explicit approval, migrations auto-approved
-
Make changes (following movement pattern)
- CREATE/UPDATE destination FIRST (new file, updated section)
- LINK - update SKILL.md pointers to new destination
- DELETE old source (only after links verified)
- Never delete first; always: CREATE → LINK → DELETE
-
Validate result (seven phases)
- Phase 1: File Inventory - list structure before/after
- Phase 2: Read All - load complete content, verify no gaps
- Phase 3: Frontmatter - check required metadata (name, description)
- Phase 4: Body Content - verify <500 lines, 80% rule applied, clarity improved
- Phase 5: References - confirm all linked files exist and are complete
- Phase 6: Tools - review allowed-tools scoping against skill needs
- Phase 7: Testing - verify activation with real-world trigger phrases
Core Workflow: Validation
When user requests validation:
-
Locate the skill (same as refinement step 1)
-
Run validation phases (seven phases, systematic)
- Phase 1: File Inventory - List all files: SKILL.md, references/, scripts/, assets/
- Phase 2: Read All - Load complete skill content (frontmatter, body, all references)
- Phase 3: Frontmatter Check - Verify required fields:
name,description - Phase 4: Body Content - Check: <500 lines? 80% rule applied? Clear procedural instructions?
- Phase 5: References - Verify: all linked files exist? No orphaned files? One level deep only?
- Phase 6: Tool Scoping - Review
allowed-toolsagainst actual tool usage. Principle of least privilege applied? - Phase 7: Testing - Verify activation: does description include trigger phrases? Will Claude recognize real requests?
-
Generate validation report
- Structure: Status (✅ Production Ready / ⚠️ Needs Review / ❌ Issues Found)
- Detail: Findings from all seven phases
- Recommendations: Specific improvements if issues found
- Priority: Which issues are critical vs. advisory
Key Rules (Non-Negotiable)
The 80% Rule (Content Distribution)
- Will Claude execute this in 80%+ of skill activations? → STAYS in SKILL.md
- Will Claude execute this in <20% of cases? → CAN MOVE to references/
- Uncertain? → DEFER to operator; keep in SKILL.md by default
Movement Pattern (for content changes)
SEQUENCE (never violate order):
1. CREATE/UPDATE destination file(s) with merged content
2. LINK - Update SKILL.md pointers to new destination(s)
3. DELETE old source (only after links verified and tested)
NEVER: DELETE → LINK → CREATE (creates broken links and lost content)
Visual flow:
❌ WRONG ✅ CORRECT
DELETE old source CREATE destination
│ │
▼ ▼
LINK to new location LINK pointers
│ │
▼ ▼
CREATE destination DELETE old source
(broken links!) (safe, links verified)
Preservation Gates (Four Gates, In Order)
- Content Audit - List ALL existing content. Classify using the 80% rule: core content (used in 80%+ of activations) vs. supplementary (<20%). Example: release-process uses standard workflow every time → core; monorepo coordination is rare → supplementary. See
references/80-percent-rule.mdfor full decision framework. - Capability Assessment - Will changes impair execution? If YES → cannot delete, only migrate
- Migration Verification - Before moving, verify destination complete. NO GAPS
- Operator Confirmation - Deletions require explicit approval. Migrations auto-approved
Scope Rules (Where to Work)
✅ PREFERRED - Project paths (search first):
skills/skill-name/in plugin projects.claude/skills/skill-name/in any project
⚠️ CONDITIONAL - User-space (only if not in project):
~/.claude/skills/skill-name/- WARN: "Affects all projects"- Requires explicit user confirmation before editing
- Offer to copy to project instead
❌ FORBIDDEN - Never edit (REFUSE IMMEDIATELY):
~/.claude/plugins/cache/*(installed plugins - read-only)- Any path containing
/cache/(always read-only)
Reference Guide
Refining for Clarity
Remove jargon, improve examples, restructure for flow
→ references/ask-user-question-patterns.md for interaction patterns
→ references/content-guidelines.md for description improvement
→ references/anti-patterns.md for what NOT to do
Refining for Efficiency (Token Usage)
Apply 80% rule, consolidate references, optimize content
→ references/80-percent-rule.md for content distribution decisions
→ references/skill-workflow.md for detailed framework
→ references/movement-pattern.md for safe migration procedure
Refining for Structure
Reorganize sections, improve grouping, better information flow
→ references/refinement-workflow.md for unified workflow with gates
→ references/movement-pattern.md for safe content relocation
→ references/advanced-patterns.md for archetype structures
Preserving Functionality (Safety Gates)
Never break existing behavior, never delete without knowing where content goes
→ references/preservation-rules.md for what NEVER gets cut
→ references/refinement-guardrails.md for safe patterns
→ references/movement-pattern.md for CREATE → LINK → DELETE sequence
Validating Quality
Check production readiness, tool scoping, completeness
→ references/validation-checklist.md for comprehensive assessment
→ references/production-patterns.md for error handling and team patterns
→ references/allowed-tools.md for tool scoping validation
Understanding Refinement Fully
Complete workflow with all phases and preservation gates
→ references/refinement-workflow.md
Pro Tips
Finding skills efficiently:
- Project-scoped skills in
skills/or.claude/skills/(search project first) - User-space skills in
~/.claude/skills/(only if not in project) - Use
Globpattern:**/SKILL.mdto find all skills in project - Never search cache paths; they're read-only copies
Wizard pattern (progressive disclosure):
- Ask one question, wait for response, then ask next
- Build context step-by-step (avoid form-like multi-questions)
- Document operator's choices; proceed only with approved scope
Production patterns:
- Detailed logging of changes made (helps with version tracking)
- Validation scripts provide confidence before deployment
- Error handling for edge cases (missing files, malformed YAML, etc.)
Preservation principle:
- Refinement improves existing functionality; it never reduces it
- When in doubt about deletion, ask operator first
- Movement is safer than deletion (can always link back)
Common Scenarios
Scenario 1: "Simplify this skill" → Focus on clarity: restructure sections, improve examples, simplify language → Identify redundancy in references, suggest consolidation → Verify 80% rule for SKILL.md body content
Scenario 2: "Reduce token usage"
→ Apply 80% rule: identify supplementary content used in <20% of cases (e.g., error handling for rare failure modes) that can move to references
→ Keep core content (80%+ usage) in SKILL.md (e.g., standard error handling patterns)
→ Consolidate related reference files
→ Verify activation doesn't suffer from moved content
→ See references/80-percent-rule.md for decision examples
Scenario 3: "Improve user interaction UX"
→ Audit all AskUserQuestion calls (max 4 options, progressive disclosure)
→ Convert free-form instructions to predefined AskUserQuestion options where applicable
→ Ensure questions follow wizard pattern (ask → wait → ask, not forms)
→ Verify descriptions are clear and help users make good choices
→ Check for >4 options violations (split into multiple AskUserQuestion batches)
→ See references/ask-user-question-patterns.md for patterns and decision trees
Scenario 3.5: "Improve reference quality"
→ Audit every reference link: does it provide context about what agents will find?
→ Pattern check: [Core knowledge] + See references/file.md for [edge cases/depth]
→ Flag orphaned links (bare links with no context): "This reference might not get loaded because agents don't know what's in it"
→ Offer: "Let's add context snippets so agents load references intentionally, not out of uncertainty"
→ Improves token efficiency: references only load when truly needed
Scenario 4: "Check if this skill is production-ready"
→ Run full validation phases (all 7 phases)
→ Check: error handling, tool scoping, clear trigger phrases, comprehensive testing
→ Flag missing production patterns (error handling, validation scripts, security review). See references/production-patterns.md for team patterns.
→ Generate detailed report with findings and recommendations
Scenario 5: "Offer to help during skill work" → Detect user is working with skills (reading SKILL.md, editing references, etc.) → Offer: "I can help refine this skill (clarity, efficiency) or validate it. Want me to?" → If yes, use appropriate workflow above
Notes
Token efficiency: Skill-refiner itself should stay <500 lines (this body content). Reference files contain detailed workflows—loaded on-demand only.
Auto-activation signals: Watch for user requests containing: "refine", "improve", "make clearer", "reduce tokens", "validate", "check if ready", "is this production-ready", or when user is actively modifying skill files.
Error handling: If skill files can't be located, are malformed, or have structural issues, report specific problems and suggest solutions rather than failing silently.
Version tracking: Track changes made to skills during refinement (which files modified, what changed). Helps users understand impact of refinements.
Skill Tester
Purpose: Empirically validate Claude Code skills through evaluation-driven testing. Proves skills actually help Claude (with data) rather than guessing.
Mindset
Skills must be measured, not assumed. This pipeline provides systematic evidence: Does the skill improve Claude's performance? By how much? What should we improve next?
Core Use Cases
Validate new skills — Test a newly created skill against baseline Claude performance without it. Benchmark improvements — Measure impact of skill refinements across multiple iterations. Comparative analysis — Prove skill effectiveness with timing, token usage, and pass rates side-by-side. Iteration planning — Data-driven decisions on what to improve next.
Core Principles
Empirical Evidence — Intuition ≠ proof. Collect actual performance data: pass rates, tokens, timing.
Parallel Testing — For each eval, test WITH skill AND baseline SIMULTANEOUSLY (2 agents per eval, in parallel). Eliminates confounding variables from different test runs.
Workspace Isolation — Each iteration lives in workspace/iteration-N/. Keeps history clean. Easy to compare iteration 1 → 2 → 3 performance.
Schema Consistency — All JSON outputs follow strict schemas (evals.json, grading.json, benchmark.json, timing.json). Enables reliable aggregation and comparison.
Quick Start: The 7-Phase Pipeline
Phase 1: Setup → Identify skill + confirm what it does
Phase 2: Create Evals → Interview user → write test cases + assertions
Phase 3: Run Tests → Launch 2 agents per eval (with_skill + baseline) in parallel
Phase 4: Grade Results → Evaluate outputs against assertions
Phase 5: Aggregate → Run ruby script to compute benchmark.json
Phase 6: Review Summary → Show comparison table + improvement suggestions
Phase 7: Iterate → Update skill + run next iteration (or stop if satisfied)
Artifact Location (Standardized)
All evaluation artifacts live in a centralized ./evals/ directory at project root:
./evals/ ← Project root, NOT inside skill directory
├── <skill-name-1>/
│ ├── evals.json
│ └── workspace/
│ ├── iteration-1/
│ │ ├── eval-1/, eval-2/, eval-3/ ← Per-eval directories
│ │ └── benchmark.json ← Aggregated results
│ └── iteration-2/
│ └── ...
└── <skill-name-2>/
└── ...
Why centralized?
- Easy to compare multiple skills' test results
- Keeps skill directories clean (no /evals/ subdirs)
- Natural location for project-wide evaluation data
- Simplifies path references in automation
PHASE 1: Setup
Goal: Identify the skill being tested. Confirm what it does. Prepare workspace.
Step 1.1: Ask User - Which Skill?
Use AskUserQuestion to ask which skill to test:
question: "Which skill do you want to test?"
header: "Skill Selection"
options: [
{label: "skill-creator", description: "Testing skill-creator from skills/ directory"},
{label: "skill-refiner", description: "Testing skill-refiner from skills/ directory"},
{label: "Other skill", description: "Testing a skill not listed above"}
]
⏸️ Collect user input. Wait for response before proceeding.
Step 1.2: Confirm Skill Path & Purpose
Read the skill's SKILL.md to understand:
- What does this skill do?
- What are its core use cases?
- What problem does it solve?
Show user a summary:
Skill: <name>
Location: <path>
Purpose: <one-line summary from description>
Step 1.2b: Choose Workflow Mode
Question: Which testing mode do you want?
Use AskUserQuestion with 2 options:
questions: [
{
question: "Which testing mode would you like?",
header: "Workflow Mode",
options: [
{
label: "Quick Workflow",
description: "Fast validation: only test WITH skill (no baseline), no timing metrics. Just pass/fail on assertions. Perfect for quick checks."
},
{
label: "Full Pipeline",
description: "Complete analysis: test WITH skill + baseline parallel, measure tokens/timing, aggregate & compare. For comprehensive benchmarking."
}
],
multiSelect: false
}
]
⏸️ Collect user input.
If Quick Workflow selected:
- Skip to Phase 2 with note: "Quick mode: only with_skill, no baseline comparison"
- Jump to simplified Phase 3 (only 1 agent per eval)
- Skip Phase 5 (aggregation) and Phase 6 comparison tables
- Show simple pass/fail results
If Full Pipeline selected:
- Continue with standard 7-phase pipeline (proceed to Step 1.3)
Step 1.3: Create Workspace
Create directory structure in project root (standardized):
./evals/<skill-name>/
./evals/<skill-name>/workspace/iteration-1/
Example for skill-creator:
./evals/skill-creator/
./evals/skill-creator/workspace/iteration-1/
Log workspace path. All subsequent phases write to this directory (NOT inside the skill's directory).
PHASE 2: Create Evals
Goal: Build evaluation cases that measure skill effectiveness.
Step 2.1: Interview User for Test Scenarios
Ask 3 questions (use AskUserQuestion with free-form "Other" option):
Question 1: "What are 2-3 core scenarios this skill should handle?"
Example: "skill-creator should handle: creating a new skill from scratch,
converting a slash command, improving an existing skill"
Question 2: "For each scenario, what makes a GOOD response?"
Example: "Good responses: skill has clear name, description with trigger phrases,
correct SKILL.md structure, efficient references/"
Question 3: "What should FAIL (baseline without skill)?"
Example: "Baseline will miss best practices, create vague descriptions,
skip necessary structure"
⏸️ Collect responses. Store in memory.
Step 2.2: Generate evals.json
Create evals.json with structure:
{
"skill_name": "<name>",
"skill_path": "<path/to/SKILL.md>",
"description": "<purpose summary>",
"evals": [
{
"id": 1,
"name": "<scenario name>",
"prompt": "<complete user prompt for this eval>",
"expected_output": "<description of what good output looks like>",
"files": []
},
{
"id": 2,
...
}
]
}
Write to ./evals/<skill-name>/evals.json (project root, standardized location).
Step 2.3: Generate eval_metadata.json Files
For each eval (one per directory), create workspace/iteration-1/eval-N/eval_metadata.json:
{
"eval_id": N,
"skill_path": "<path/to/SKILL.md>",
"assertions": [
{
"text": "Output includes a clear skill name",
"type": "presence",
"target": "SKILL.md frontmatter"
},
{
"text": "Description has specific trigger phrases",
"type": "quality",
"target": "SKILL.md frontmatter description field"
},
{
"text": "References are organized with one-level nesting",
"type": "structure",
"target": "references/ directory"
}
]
}
Create directories: workspace/iteration-1/eval-1/, eval-2/, etc. (with_skill and baseline subdirs will be created in Phase 3).
QUICK WORKFLOW (Alternative Path)
If user chose "Quick Workflow" in Step 1.2b, follow this streamlined path instead of Phases 3-7.
Quick Phase 1: Run WITH_SKILL Only (No Baseline)
Goal: Test the skill itself. No baseline comparison, no timing metrics. Just: Does it work?
For EACH eval in evals.json, launch ONE agent (no parallel baseline):
Agent (WITH_SKILL_ONLY):
Type: general-purpose
Prompt: "
You are testing a Claude Code skill. Your job: HELP THE USER ACCOMPLISH THEIR TASK
using the skill provided below.
SKILL TO USE:
<read and include full SKILL.md content>
USER TASK:
<eval-N prompt from evals.json>
After completing the task, save all outputs to:
./evals/<skill-name>/workspace/iteration-1/eval-N/with_skill/outputs/
NO timing metrics needed for quick workflow. Just save your work."
⏸️ Wait for agent completion before proceeding to next eval.
Quick Phase 2: Grade Results (Assertions Only)
For each eval, manually grade against assertions:
- Does with_skill output satisfy each assertion?
- Record pass/fail (no baseline comparison)
- Save to:
./evals/<skill-name>/workspace/iteration-1/eval-N/with_skill/grading.json
{
"eval_id": N,
"configuration": "with_skill",
"assertions_evaluated": [
{"text": "...", "passed": true/false, "evidence": "..."}
],
"summary": {
"assertions_total": X,
"assertions_passed": Y,
"pass_rate": Y/X
}
}
Quick Phase 3: Show Results
Display simple pass/fail summary (no benchmark.json):
QUICK VALIDATION RESULTS: <skill-name>
====================================
Eval 1: <Scenario> ✓ PASS (5/5 assertions)
Eval 2: <Scenario> ✓ PASS (4/5 assertions)
Eval 3: <Scenario> ✗ FAIL (2/5 assertions)
Summary: 11/15 assertions passed (73%)
Status: Ready to refine or deploy
Quick Phase 4: Next Steps
Ask user:
question: "What would you like to do?"
header: "Next Steps"
options: [
{label: "Run full pipeline", description: "Move to complete benchmarking with baseline comparison"},
{label: "Refine skill", description: "Update skill based on failed assertions"},
{label: "Done", description: "Quick validation complete"}
]
PHASE 3: Run Tests
Goal: Execute 2 agents per eval (WITH skill + BASELINE) in parallel. Capture outputs.
Step 3.1: Spawn Agents (Parallel Execution)
For EACH eval, launch 2 agents SIMULTANEOUSLY in one Agent tool call:
Agent 1 (WITH_SKILL):
Agent type: general-purpose
Prompt: "
You are testing a Claude Code skill. Your job: HELP THE USER ACCOMPLISH THEIR TASK
using the skill provided below.
SKILL TO USE:
<read and include full SKILL.md content>
USER TASK:
<eval-N prompt from evals.json>
After completing the task, save all outputs (code, files, notes) to:
./evals/<skill-name>/workspace/iteration-1/eval-N/with_skill/outputs/
Then create a file ./evals/<skill-name>/workspace/iteration-1/eval-N/with_skill/timing.json with:
{
\"total_tokens\": <count>,
\"duration_ms\": <milliseconds>,
\"model\": \"claude-opus-4-6\"
}
"
Agent 2 (BASELINE):
Agent type: general-purpose
Prompt: "
You are testing a Claude Code skill by providing a BASELINE. Your job: HELP THE USER
accomplish their task WITHOUT any special skill or methodology.
USER TASK:
<eval-N prompt from evals.json>
NO SKILLS AVAILABLE. Use standard Claude capabilities only.
After completing the task, save all outputs (code, files, notes) to:
./evals/<skill-name>/workspace/iteration-1/eval-N/baseline/outputs/
Then create a file ./evals/<skill-name>/workspace/iteration-1/eval-N/baseline/timing.json with:
{
\"total_tokens\": <count>,
\"duration_ms\": <milliseconds>,
\"model\": \"claude-opus-4-6\"
}
"
⏸️ Wait for both agents to complete before proceeding to Phase 4.
PHASE 4: Grade Results
Goal: Evaluate each agent's outputs against assertions in eval_metadata.json.
Step 4.1: Review Outputs & Grade
For EACH eval:
- Read
with_skill/outputs/files - Read
baseline/outputs/files - For EACH assertion in
eval-N/eval_metadata.json:- Does with_skill output satisfy the assertion? (true/false)
- Does baseline output satisfy the assertion? (true/false)
- Collect brief evidence quotes from outputs
Step 4.2: Write grading.json Files
Create workspace/iteration-1/eval-N/with_skill/grading.json:
{
"eval_id": N,
"configuration": "with_skill",
"assertions_evaluated": [
{
"text": "Output includes a clear skill name",
"passed": true,
"evidence": "SKILL.md line 2: name: skill-tester"
},
{
"text": "Description has specific trigger phrases",
"passed": true,
"evidence": "Description mentions: 'validating', 'benchmarks', 'comparing performance'"
}
],
"summary": {
"assertions_total": 3,
"assertions_passed": 3,
"pass_rate": 1.0
}
}
Create identical file for baseline/grading.json with its results.
PHASE 5: Aggregate
Goal: Compute benchmark.json with summary stats (pass rates, tokens, timing).
Step 5.1: Run Ruby Script
Execute the aggregation script (see references/eval-schema.md for full script):
ruby skills/skill-tester/scripts/aggregate_benchmark.rb \
./evals/<skill-name>/workspace/iteration-1
Example:
ruby skills/skill-tester/scripts/aggregate_benchmark.rb \
./evals/skill-creator/workspace/iteration-1
This reads all grading.json and timing.json files from the standardized location, outputs benchmark.json:
{
"skill_name": "skill-tester",
"iteration": 1,
"timestamp": "2026-03-04T10:30:00Z",
"evals": [
{
"eval_id": 1,
"with_skill": {
"pass_rate": 1.0,
"assertions_passed": 3,
"assertions_total": 3,
"avg_tokens": 2500,
"avg_duration_ms": 8000
},
"baseline": {
"pass_rate": 0.67,
"assertions_passed": 2,
"assertions_total": 3,
"avg_tokens": 1800,
"avg_duration_ms": 5000
},
"delta": {
"pass_rate": 0.33,
"tokens": 700,
"duration_ms": 3000
}
}
],
"summary": {
"with_skill_avg_pass_rate": 0.95,
"baseline_avg_pass_rate": 0.70,
"improvement": 0.25,
"avg_tokens_with_skill": 2400,
"avg_tokens_baseline": 1900,
"token_cost": 500
}
}
PHASE 6: Review Summary
Goal: Show user a clear comparison table + next steps.
Step 6.1: Render Comparison Table
Display results in human-readable format:
EVALUATION RESULTS: skill-tester iteration-1
==============================================
Eval 1: [Scenario Name]
WITH SKILL: 3/3 (100%) | 2500 tokens | 8s
BASELINE: 2/3 (67%) | 1800 tokens | 5s
DELTA: +33% better | +700 tokens | +3s
Eval 2: [Scenario Name]
WITH SKILL: 2/3 (67%) | 2100 tokens | 7s
BASELINE: 2/3 (67%) | 1900 tokens | 4s
DELTA: Even | +200 tokens | +3s
SUMMARY
-------
With Skill Avg: 96.5% pass rate | 2300 avg tokens
Baseline Avg: 67.0% pass rate | 1850 avg tokens
IMPROVEMENT: +29.5 percentage points
Step 6.2: Offer Next Steps
Ask user (AskUserQuestion):
question: "What would you like to do?"
header: "Next Steps"
options: [
{
label: "Iterate (update skill, run next iteration)",
description: "Based on results, modify the skill and run workspace/iteration-2"
},
{
label: "Stop (satisfied with results)",
description: "Evaluation complete. Save benchmark data for reference"
},
{
label: "Refine evals (change test cases, rerun)",
description: "Update evals.json and run iteration again with same eval set"
}
]
⏸️ Collect user input.
PHASE 7: Iterate
Goal: If user chose "Iterate", update the skill and run next iteration.
Step 7.1: Get Improvement Feedback
Ask user (AskUserQuestion, free-form):
question: "What would you like to improve about the skill?"
header: "Improvement"
⏸️ Collect feedback.
Step 7.2: Update Skill
Use skill-refiner or direct edits to improve the skill based on feedback:
- Reword descriptions for clarity
- Add missing guidance to SKILL.md body
- Reorganize references
- Trim token usage
Step 7.3: Run Next Iteration
Create workspace/iteration-2/ directory. Repeat Phases 3–6 with updated skill.
Step 7.4: Compare Iterations
Show delta between iteration-1 benchmark and iteration-2 benchmark:
ITERATION COMPARISON
====================
Iteration 1 pass rate: 67% → Iteration 2: 95% (+28 points)
Iteration 1 tokens: 1900 → Iteration 2: 2100 (+200, acceptable)
Loop back to Phase 6 (Step 6.2) to ask: iterate again or stop?
Token Accountability
- SKILL.md body: ~340 lines (target <500) ✓
- Frontmatter + Quick Start: ~20 lines (always loaded)
- 7 phases + subagent prompts: ~320 lines
- All detailed reference schemas and aggregate script →
references/files
For full schemas, workflow details, and aggregate_benchmark.rb script code, see:
references/eval-schema.md— JSON schemas for all eval filesreferences/workflow.md— decision points and detailed workflowscripts/aggregate_benchmark.rb— Ruby aggregation script
Subagent Creator
Dual purpose: Create subagents right the first time OR elevate existing subagents to best practices.
Quick Routing
Use AskUserQuestion with predefined options:
questions: [
{
question: "What would you like to do?",
header: "Action",
options: [
{
label: "Create a new subagent",
description: "Build a subagent from scratch with proper scope, tool access, and permissions"
},
{
label: "Validate existing subagent",
description: "Check if subagent is properly configured and production-ready"
},
{
label: "Refine/improve subagent",
description: "Enhance existing subagent for clarity, efficiency, or reliability"
}
],
multiSelect: false
}
]
Then route to the appropriate workflow section based on their selection.
When to Use This Skill
- Creating subagents — Need structured guidance on scope, model, tool access, permission modes for new subagents
- Validating subagents — Ensure correct configuration, delegation clarity, tool scoping, permission modes
- Improving subagents — Enhance robustness (tool restrictions, permissions, delegation signals, error handling, hooks)
- Team/production — Building for multiple Claude instances; need stability and error handling
Quick Reference: Three Workflows
| Workflow | Purpose | Steps | Reference |
|---|---|---|---|
| Create | Build subagent from scratch | 1. Interview → 2. Design → 3. Implement → 4. Validate | templates.md + validation-workflow.md |
| Validate | Check existing subagent | 1. Configuration → 2. Delegation → 3. Prompt → 4. Tools → 5. Permissions → 6. Hooks → 7. Test | validation-workflow.md + checklist.md |
| Refine | Improve existing subagent | 1. Identify issues → 2. Target improvements → 3. Update → 4. Re-validate | checklist.md + topic-specific refs |
Why This Exists
Mindset: Subagents are execution FOR CLAUDE, not documentation FOR PEOPLE. Question: "Will Claude reliably delegate & execute?" not "Does this read well?"
Subagents isolate task execution with custom prompts, tool access, permissions. Without structured guidance, they become misconfigured and unreliable. This skill ensures every subagent is optimized for reliable delegation and execution from creation.
Foundation: Subagent Architecture
Subagents are isolated execution environments with independent configuration (prompt, tools, permissions). Claude delegates to subagents based on request context using natural language matching against descriptions. For complete architectural details including delegation mechanisms, configuration options, and integration patterns, see references/how-subagents-work.md.
Implementation Approach
⚠️ CRITICAL: Scope Detection & Clarification
Always detect project type first, then clarify scope only when needed:
Allowed scopes (project-scoped only):
- Claude plugin projects (has
.claude-plugin/plugin.json): Subagents inagents/(plugin) or.claude/agents/(project-level) - Regular projects: Subagents in
.claude/agents/only
🚫 Forbidden scopes (REFUSE all editing attempts):
~/.claude/plugins/cache/— Installed/cached plugins~/.claude/agents/— User-space subagents (affects all projects)- Global installations or outside project root
If user provides forbidden path: Refuse with explanation: "Subagent-creator only works with project-scoped subagents. User-space subagents (~/.claude/agents/) affect all projects and should not be edited here."
START HERE - Scope Detection & Clarification Flow:
-
Ask Question 1: Action type
- Create a new subagent (Recommended)
- Validate an existing subagent
- Refine a subagent
-
AUTO-DETECT: Check for
.claude-plugin/plugin.json- If it exists (project is a Claude plugin): Go to step 3a
- If it doesn't exist (regular project): Go to step 3b
3a. IF PROJECT IS A CLAUDE PLUGIN - Ask Question 2: Scope choice with predefined options
questions: [
{
question: "Should this subagent be part of the plugin or project-level?",
header: "Scope",
options: [
{
label: "Part of the plugin",
description: "Add to agents/ directory (bundled with plugin for distribution)"
},
{
label: "Project-level",
description: "Add to .claude/agents/ directory (local, not bundled with plugin)"
}
],
multiSelect: false
}
]
Then ask: "What do you want to call it?" (e.g., db-analyzer, code-reviewer, compliance-auditor)
3b. IF PROJECT IS REGULAR - No scope question needed
- Inform user: "Creating project-level subagent in
.claude/agents/" - Ask: "What do you want to call it?" (e.g.,
db-analyzer,code-reviewer,compliance-auditor)
For validating/refining: Ask "Provide the subagent name or path relative to project root" (e.g., agents/db-analyzer for plugins or .claude/agents/db-analyzer for regular projects)
Based on answers, route to the appropriate workflow below.
For New Subagents: Requirements Interview First
After routing to "create", interview the user to gather requirements using AskUserQuestion with proper options:
questions: [
{
question: "What specialized task should this subagent execute? What problem does isolation solve?",
header: "Purpose & Scope",
options: [] // Open-form
},
{
question: "When should Claude delegate to this subagent? What request phrases trigger it?",
header: "Delegation Trigger",
options: [] // Open-form
},
{
question: "Which tools will this subagent need? (Apply principle of least privilege)",
header: "Tool Access",
options: [] // Open-form
},
{
question: "How should the subagent handle permission prompts?",
header: "Permission Mode",
options: [
{ label: "default", description: "Prompt for each permission (standard behavior)" },
{ label: "acceptEdits", description: "Auto-accept file edits without prompting" },
{ label: "dontAsk", description: "Auto-accept all permissions without prompting" },
{ label: "plan", description: "Use plan mode for structured permission flow" }
],
multiSelect: false
}
]
- Model choice - Should it use fast Haiku, standard Sonnet, or powerful Opus? Or inherit from parent?
- Hooks & validation - Does the subagent need conditional tool validation or lifecycle hooks?
- Team/production - Will multiple Claude instances use this? Production data involved?
Then use references/templates.md to apply requirements to the appropriate subagent structure.
For Existing Subagents (Validating)
- FIRST: Verify the subagent path is project-scoped — Check if path contains
.claude/agents/oragents/relative to project root. If path is from~/.claude/plugins/cache/or~/.claude/, REFUSE and explain project scope - SECOND: Detect if subagent is plugin or project-level — Infer from path prefix:
- Path starts with
agents/→ Plugin-level subagent - Path starts with
.claude/agents/→ Project-level subagent
- Path starts with
- Follow the systematic workflow in
references/validation-workflow.md(Phase 1-7) - Use
references/checklist.mdto identify gaps during validation - Check
references/delegation-signals.mdfor description clarity - Validate: Complete workflow + checklist before considering the subagent complete
For Improvements (Refining)
- FIRST: Verify the subagent path is project-scoped — Check if path is in project directory, NOT in installed locations. Refuse if it's installed/cached
- SECOND: Detect scope from path — Determine if subagent is plugin-level or project-level based on path prefix
- Ask user which aspects need improvement (delegation, tools, permissions, etc.)
- Reference relevant sections from
references/checklist.mdorreferences/delegation-signals.md - Make targeted improvements rather than rewriting everything
Outcome Metrics
Measure success by whether Claude will reliably delegate to and execute the subagent:
✅ Description clarity - Includes specific trigger phrases Claude will recognize; delegates reliably when needed ✅ Configuration - Correct YAML frontmatter (name, description, tools, permissionMode, model, hooks) ✅ Prompt quality - System prompt is clear, procedural, and context-appropriate ✅ Tool scoping - Only necessary tools declared; principle of least privilege enforced ✅ Permission mode - Appropriate for use case (foreground vs background, interactive vs auto-deny) ✅ Hooks - Correctly configured for validation/lifecycle when needed ✅ Integration - Tested with real delegation scenarios; works with both foreground and background execution
Quick Start: Creating a New Subagent
When helping the user create a subagent, follow these steps:
Step 1: Prepare storage location Guide the user to create the directory:
- Global:
~/.claude/agents/ - Project-local:
.claude/agents/
Step 2: Create the Markdown file Write the subagent configuration with YAML frontmatter + system prompt body. Example structure:
---
name: db-analyzer
description: >-
Execute read-only database queries to analyze data. Use when exploring
databases, generating reports, or analyzing data patterns. Supports
SELECT queries only; write operations blocked.
model: sonnet
tools: Bash, Read, Write
permissionMode: dontAsk
---
You are a database analyst with read-only access...
Step 3: Apply guidelines for Claude's delegation Ensure the subagent meets these requirements:
- name: lowercase-hyphen, ≤64 chars, unique within scope
- description: ≤1024 chars, must include specific trigger phrases (this is Claude's delegation signal)
- tools: Allowlist or omit to inherit all tools
- model: sonnet (default), opus, haiku, or inherit from parent
- permissionMode: default (ask), acceptEdits (auto-accept edits), dontAsk (auto-deny), bypassPermissions (skip checks), plan (read-only)
Step 4: Write the system prompt The prompt body is what Claude executes when delegated. Structure: Purpose → Key behaviors → Constraints → Examples
Step 5: Add hooks if needed For conditional tool validation (e.g., read-only database access), guide the user to configure PreToolUse hooks with validation scripts.
Step 6: Guide user through validation
Have the user review the checklist in references/checklist.md before deployment. Then guide them through real-world testing: try requests that should trigger delegation, and requests that should not.
Refining Existing Subagents
- Follow the validation workflow (
references/validation-workflow.md) to identify issues systematically - Review against the checklist (
references/checklist.md) during validation - Improve so Claude delegates and executes reliably: description clarity (delegation) → configuration correctness → prompt clarity → hooks/validation if needed
- Guide user to test delegation: Ask them to make requests using the trigger phrases from the description. Check: Does Claude delegate to this subagent? If not, the description needs clearer trigger language.
- Guide user to test execution: Once delegation works, verify the subagent can complete the task with its prompt and tools. Ask the user to test actual workflows.
- Re-validate using the workflow before considering refinements complete
Reference Guide
Creating a New Subagent
Step 1: Understand subagent architecture
→ How Claude delegates, execution models, when to use subagents, delegation mechanisms
→ references/how-subagents-work.md for architecture overview
Step 2: Choose starting template
→ Real-world examples and copy-paste starting points for common patterns
→ references/templates.md
Step 3: Write clear delegation signals
→ Descriptions trigger Claude's delegation. Include specific trigger phrases; vague descriptions = poor reliability.
→ references/delegation-signals.md for writing descriptions that trigger delegation
Step 3b: Write reliable delegation prompts
→ Pattern: role statement → task → context → explicit outputs → constraints. Based on production implementations (skill-tester, skill-creator).
→ references/delegation-patterns.md for proven delegation patterns with real examples
Step 4: Configure tools & permissions
→ Grant only necessary tools (principle of least privilege). Permission modes: foreground/interactive, background/concurrent, plan/read-only
→ references/tool-scoping.md for tool access patterns
→ references/permission-modes.md for permission mode decision matrices
Step 5: Complete YAML configuration
→ Frontmatter fields: name, description, model, tools, permissionMode, hooks (PreToolUse, PostToolUse, SubagentStart, SubagentStop)
→ references/configuration-reference.md for complete YAML reference
Step 6: Validate before deployment
→ 7-phase validation process: configuration → delegation → prompt → tools → permissions → hooks → testing
→ references/validation-workflow.md for validation phases
→ references/checklist.md for best practices checklist
Validating Existing Subagents
→ Run 7-phase validation workflow systematically
→ references/validation-workflow.md for all phases
→ references/checklist.md for quality assessment
Improving/Refining Subagents
→ Identify gaps using checklist, make targeted improvements, re-validate
→ references/checklist.md for identifying issues
→ Topic-specific references as needed
Production & Advanced Patterns
→ Hook validation, chaining, background execution, lifecycle management, error handling
→ references/advanced-patterns.md for production patterns
Core Principles
- Clear Delegation Signals — Descriptions trigger Claude's delegation. Include specific trigger phrases; vague descriptions = poor reliability.
- Principle of Least Privilege — Grant only necessary tools. Use allowlist scoping and hooks for conditional validation (e.g., read-only queries).
- Appropriate Permission Mode — Match mode to use case: foreground/interactive, background/concurrent, or plan/read-only.
- Configuration Clarity — Validate YAML syntax, tool names, model values, and required fields before deploying.
Key Notes
Frontmatter essentials:
name: Required, lowercase-hyphen, ≤64 chars (Claude's reference label)description: Required, ≤1024 chars, must include trigger phrases Claude recognizes (PRIMARY delegation signal)- Example formula:
[Action]. Use when [trigger contexts]. [Scope/constraints].
Common optional fields:
model: sonnet|opus|haiku|inherit (default: sonnet)tools: Allowlist tools (default: inherit all)permissionMode: default|acceptEdits|dontAsk|bypassPermissions|planhooks: PreToolUse, PostToolUse, SubagentStart, SubagentStop for validation/lifecycle
Scope storage (project-scoped only; subagent-creator refuses user-space):
- ✅ Project-local:
.claude/agents/(recommended) - ✅ Plugin:
agents/in plugin directory (for plugin projects) - 🚫 Global/User-space:
~/.claude/agents/(forbidden; affects all projects — do not edit here)
For complete configuration reference, defaults, field combinations, naming conventions, and permission mode decision matrices, see references/configuration-reference.md and references/permission-modes.md.
Team/Production:
- Error handling: prompts must handle failures gracefully
- Tool scoping: principle of least privilege (see
tool-scoping.md) - Hooks: validation scripts must be tested before deployment
- See
checklist.md→ "Team & Production Subagents" for full considerations andadvanced-patterns.mdfor production patterns
Sponsors
Details
- Marketplace
- full-stack-biz/claude-skills-toolkit
- Source
- full-stack-biz/claude-skills-toolkit
- Author
- full-stack-biz
- Category
- Community
- License
- MIT
- Keywords
- skills, plugins, hooks, agents, subagents, development, toolkit, automation