gh-sjungling-claude-plugins-plugins-claude/skills/builder/SKILL.md

---
name: builder
description: Expert in creating Claude Code subagents, skills, slash commands, plugins, and plugin marketplaces. Automatically activates when working with .md files in .claude/ directories, agent/command/skill frontmatter, marketplace.json, or when discussing Claude Code extensibility and component creation.
---

# 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:
```bash
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)

```yaml
---
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)

```yaml
---
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)

```yaml
---
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

```markdown
---
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

```yaml
---
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

```markdown
---
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

```yaml
---
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