Claude Code Builder

Expert guidance for creating Claude Code subagents, skills, slash commands, plugins, and plugin marketplaces.

Automatic Activation

This skill automatically activates when:

• Creating or editing .claude/agents/*.md files
• Working with .claude/commands/*.md files
• Developing skills/*/SKILL.md files
• Configuring .claude-plugin/plugin.json or marketplace.json
• Working with files in .claude/ directories
• Users ask "How do I create a Claude Code skill?"
• Users ask "How do I make a slash command?"
• Users mention "building a plugin" or "creating an agent"
• Discussing Claude Code extensibility and customization

When NOT to Use This Skill

Do not use this skill for:

• General Claude Code usage questions (non-extensibility topics)
• Debugging existing user code (unless related to plugin development)
• Standard development tasks unrelated to Claude Code components
• Basic Claude Code CLI operations (use /help instead)
• Questions about using existing plugins (rather than creating them)

Quick Start

Progressive Disclosure Design Principle

Claude Code components use a three-level loading system to manage context efficiently:

1. Metadata (name + description) - Always in context (~100 words)
2. Component body - Loaded when component triggers (<5k words recommended)
3. Bundled resources - Loaded as needed (unlimited)

Design components to be lean in the body, delegating detailed information to bundled references. This approach keeps the context window efficient while making specialized knowledge available when needed.

Creating a New Component

Before starting, determine which component type fits the requirements:

• Skill: Automatic activation based on context (preferred for most use cases)
• Slash Command: Quick keyboard shortcuts for common tasks
• Subagent: Delegatable workflows needing context isolation
• Plugin: Package multiple components for distribution

Component Selection Guide

Need	Use	Example
Always-available guidance	Skill	Code style patterns, debugging workflows
Keyboard shortcut	Command	/format-code, /run-tests
Delegatable workflow	Subagent	Code reviews, complex migrations
Package for distribution	Plugin	Collection of related components
Validate prerequisites	Hook	Check dependencies, verify API keys

Core Workflows

1. Creating a Skill

Skills provide automatic, context-aware guidance.

Steps:

1. Create directory: skills/skill-name/
2. Create SKILL.md with frontmatter
3. Write comprehensive description with trigger keywords
4. Add skill content with examples and patterns
5. Bundle reference materials in subdirectories
6. Test activation contexts

See: ./references/skills-guide.md for complete best practices

2. Creating a Slash Command

Commands provide quick shortcuts for common tasks.

Steps:

1. Create file: commands/command-name.md
2. Add optional YAML frontmatter (description, allowed-tools, args)
3. Write command prompt with argument placeholders
4. Preapprove necessary tools
5. Test command execution

See: ./references/slash-commands-guide.md for complete best practices

3. Creating a Subagent

Subagents provide specialized expertise and delegatable workflows.

Steps:

1. Create file: agents/agent-name.md
2. Add required YAML frontmatter (name, description, model, color, tools)
3. Write focused system prompt
4. Define workflows and success criteria
5. Test with Task tool

See: ./references/subagents-guide.md for complete best practices

4. Creating a Plugin

Plugins package components for distribution.

Quick Start: Plugin scaffold generator usage:

python ./scripts/init_plugin.py --name my-plugin --description "Description" --author "Your Name"

Steps:

1. Create plugin directory structure (or use ./scripts/init_plugin.py)
2. Create .claude-plugin/plugin.json with metadata
3. Add components (agents, commands, skills)
4. Create README.md and SKILLS.md
5. Register in marketplace.json
6. Validate marketplace configuration (use ./scripts/validate_marketplace.py)
7. Test installation

See: ./references/plugins-guide.md for complete best practices

5. Creating Hooks

Hooks validate prerequisites and control tool execution.

Steps:

1. Create hooks/hooks.json configuration
2. Create hook script in scripts/ directory
3. Make script executable (chmod +x)
4. Implement proper input/output contract
5. Test with mock inputs
6. Verify error messages are helpful

See: ./references/hooks-guide.md for complete best practices

YAML Frontmatter Quick Reference

Note: This is a quick reference. See individual reference guides for complete schema details.

Skills (SKILL.md)

---
name: skill-name
description: Expert in [domain]. Automatically activates when [triggers]...
---

Note: Skills support ONLY name and description in frontmatter. Unlike subagents, skills do not support version, model, color, tools, or any other fields. Additional fields will be ignored.

See ./references/skills-guide.md for complete frontmatter specification.

Subagents (agents/*.md)

---
name: agent-name
description: Agent purpose...
model: inherit
color: blue
tools: Read, Write, Edit
---

See ./references/subagents-guide.md for complete frontmatter specification.

Slash Commands (commands/*.md)

---
description: Command description
allowed-tools:
  - Bash(npm:*)
args:
  - name: arg-name
    description: What it does
---

See ./references/slash-commands-guide.md for complete frontmatter specification.

Best Practices

Skill Development

Do:

• Write descriptions with specific activation triggers
• Include technology names and file patterns
• Bundle reference materials in skill directory
• Test in multiple contexts to verify activation
• Start description with third-person voice

Don't:

• Write descriptions too generic
• Omit specific technologies from description
• Include network-dependent resources
• Use skills for simple linear workflows (use commands instead)

Command Development

Do:

• Use clear, descriptive command names
• Preapprove necessary tools
• Document arguments
• Include error handling guidance
• Support argument substitution

Don't:

• Preapprove dangerous commands unnecessarily
• Create commands for complex decision-making (use agents/skills)
• Skip testing with different argument combinations

Subagent Development

Do:

• Focus on specific domain expertise
• Provide step-by-step workflows
• Reference authoritative documentation
• Define clear success criteria
• Restrict tools appropriately

Don't:

• Create agents too general-purpose
• Duplicate main Claude capabilities
• Create overly complex nested workflows
• Skip examples in description

Plugin Development

Do:

• Focus on specific use case or domain
• Provide comprehensive documentation
• Test all components before publishing
• Use semantic versioning
• Include usage examples

Don't:

• Create unfocused plugins
• Use absolute paths in configuration
• Skip testing installation process
• Omit documentation for any components

Common Patterns

Component Templates: Use provided templates as starting points:

• ./assets/templates/plugin.json - Plugin metadata template
• ./assets/templates/agent-template.md - Subagent structure template
• ./assets/templates/skill-template.md - Skill structure template
• ./assets/templates/command-template.md - Slash command template

Skill with References

skill-name/
├── SKILL.md
├── references/
│   ├── guide.md
│   └── patterns.md
└── templates/
    └── template.txt

Multi-Component Plugin

plugin-name/
├── .claude-plugin/
│   └── plugin.json
├── agents/
│   └── expert.md
├── commands/
│   └── quick-action.md
├── skills/
│   └── auto-guidance/
│       └── SKILL.md
├── SKILLS.md
└── README.md

Command with Subagent

---
description: Complex workflow delegated to expert
allowed-tools:
  - Task
---

Use the domain-expert agent to [accomplish task].

Provide the agent with:
- [Context 1]
- [Context 2]

Expected deliverables:
- [Output 1]
- [Output 2]

Troubleshooting

Skill Not Activating

Problem: Skill doesn't trigger in expected contexts

Solutions:

• Add more specific keywords to description
• Include technology/framework names
• Mention file patterns (.swift, .tsx, etc.)
• Start description with third-person voice
• Test different description variations

Invalid YAML Frontmatter

Problem: Component fails to load

Solutions:

• Validate YAML syntax (indentation, colons, dashes)
• Check field names match requirements
• Verify string values are quoted if they contain special chars
• Ensure name fields use kebab-case

Command Tools Not Preapproved

Problem: Command prompts for approval repeatedly

Solutions:

• Add tools to allowed-tools array
• Use glob patterns for flexibility: Bash(npm:*)
• Include all commands the workflow requires
• Test command to identify missing approvals

Plugin Not Installing

Problem: Plugin installation fails

Solutions:

• Verify source path uses ./ prefix
• Check all component paths are relative
• Validate marketplace.json is valid JSON
• Ensure files exist at specified paths
• Test with: cat marketplace.json | python -m json.tool

Bundled Resources

This skill includes bundled resources to support component creation:

References (loaded into context as needed):

• ./references/subagents-guide.md - Complete frontmatter reference, system prompt best practices, testing and integration patterns, common agent patterns
• ./references/skills-guide.md - Description writing for activation, content structure recommendations, bundling reference materials, discovery and testing
• ./references/slash-commands-guide.md - Tool preapproval syntax, argument handling, workflow patterns, security considerations
• ./references/plugins-guide.md - Plugin structure and metadata, marketplace configuration, installation and distribution, testing and versioning
• ./references/hooks-guide.md - Hook types and when to use them, PreToolUse hook implementation, input/output contracts, validation patterns and best practices

Scripts (executable utilities):

• ./scripts/init_plugin.py - Generate plugin scaffold with complete directory structure (agents/, commands/, skills/, .claude-plugin/)
• ./scripts/validate_marketplace.py - Validate marketplace.json configuration for correctness and best practices

Assets (templates used in output):

• ./assets/templates/plugin.json - Plugin metadata template with standard fields
• ./assets/templates/agent-template.md - Subagent structure template with frontmatter and system prompt sections
• ./assets/templates/skill-template.md - Skill structure template with activation triggers and bundled resources
• ./assets/templates/command-template.md - Slash command template with argument handling and tool preapprovals

Examples

Example: Creating a Testing Skill

---
name: api-testing-patterns
description: Expert in API testing patterns. Automatically activates when writing tests for REST APIs, GraphQL endpoints, or API integration tests - provides patterns for request mocking, response validation, authentication testing, and error scenario coverage
---

# API Testing Patterns

## Quick Start

When testing API endpoints:
1. Arrange: Set up test data and mocks
2. Act: Make the API request
3. Assert: Validate response
4. Cleanup: Reset state

[Additional content with patterns and examples]

Example: Creating a Deployment Command

---
description: Deploy application to specified environment
allowed-tools:
  - Bash(git:*)
  - Bash(npm run deploy:*)
  - Bash(gh:*)
args:
  - name: environment
    description: Target environment (dev, staging, prod)
---

Deploy to $1 environment:

1. Verify git status is clean
2. Run deployment script for $1
3. Monitor deployment status
4. Create deployment record

Use: /deploy staging

Example: Creating a Code Review Agent

---
name: code-reviewer
description: Expert code reviewer analyzing code quality, best practices, security, and maintainability. Use for comprehensive code reviews before merging.
model: inherit
color: purple
tools: Read, Grep, Glob
---

You are an expert code reviewer specializing in code quality, security, and maintainability.

## Review Process

1. Analyze changed files for:
   - Code quality and readability
   - Security vulnerabilities
   - Performance implications
   - Test coverage

2. Provide feedback on:
   - Best practices adherence
   - Design patterns
   - Error handling
   - Documentation

3. Suggest improvements with examples

[Additional review guidelines]

Success Criteria

Claude Code components are successful when:

Skills:

• Activate automatically in appropriate contexts
• Provide clear, actionable guidance
• Include comprehensive examples
• Bundle useful reference materials efficiently
• Use third-person voice in description
• Use imperative/infinitive form consistently in content

Commands:

• Execute workflows efficiently without unnecessary approval prompts
• Handle arguments correctly with proper substitution
• Have necessary tools preapproved in frontmatter
• Provide clear feedback on execution status
• Follow security best practices for destructive operations

Subagents:

• Stay focused on their domain expertise
• Follow defined workflows consistently
• Have appropriate tool access restrictions
• Deliver expected results autonomously
• Include usage examples in description

Plugins:

• Install without errors via marketplace
• All components work as documented
• Clear, comprehensive documentation provided
• Properly versioned using semantic versioning
• Use relative paths with ./ prefix in configurations

Documentation Links

Official Claude Code Documentation:

• Subagents: https://docs.claude.com/en/docs/claude-code/sub-agents.md
• Skills: https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview.md
• Slash Commands: https://docs.claude.com/en/docs/claude-code/slash-commands.md
• Plugins: https://docs.claude.com/en/docs/claude-code/plugins.md
• Plugin Marketplaces: https://docs.claude.com/en/docs/claude-code/plugin-marketplaces.md