feat: Convert to Claude Code plugin marketplace
Transform repository into a plugin marketplace structure with two plugins: - claude-code plugin: Complete toolkit with 5 skills * claude-code-plugins * claude-code-slash-commands * claude-code-hooks * claude-code-subagents * claude-code-memory - claude-skills plugin: Meta-skill for creating Agent Skills * Comprehensive best practices guide * Templates and examples * Progressive disclosure patterns Infrastructure: - Add marketplace.json manifest - Create plugin.json for each plugin - Update documentation for marketplace structure - Add contribution and testing guides Installation: - /plugin install claude-code@claude-skills - /plugin install claude-skills@claude-skills 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
movq
1049
claude-code/skills/claude-code-hooks/SKILL.md
Normal file
1049
claude-code/skills/claude-code-hooks/SKILL.md
Normal file
File diff suppressed because it is too large
Load Diff
1032
claude-code/skills/claude-code-memory/SKILL.md
Normal file
1032
claude-code/skills/claude-code-memory/SKILL.md
Normal file
File diff suppressed because it is too large
Load Diff
546
claude-code/skills/claude-code-plugins/SKILL.md
Normal file
546
claude-code/skills/claude-code-plugins/SKILL.md
Normal file
@@ -0,0 +1,546 @@
|
||||
---
|
||||
name: Claude Code Plugin Developer
|
||||
description: Create and structure Claude Code plugins with commands, agents, skills, hooks, and MCP servers. Use when building plugins for Claude Code, setting up plugin structure, or configuring plugin manifests.
|
||||
---
|
||||
|
||||
# Claude Code Plugin Development
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
Use this skill when:
|
||||
- Creating a new Claude Code plugin from scratch
|
||||
- Adding components to an existing plugin (commands, agents, skills, hooks)
|
||||
- Configuring plugin manifests and metadata
|
||||
- Setting up plugin distribution and marketplaces
|
||||
- Troubleshooting plugin structure or installation issues
|
||||
|
||||
Do NOT use this skill for:
|
||||
- Creating standalone MCP servers (use MCP-specific documentation)
|
||||
- General Claude Code usage (not plugin development)
|
||||
- Creating individual skills without plugin context
|
||||
|
||||
## Quick Start: Creating a Plugin
|
||||
|
||||
### 1. Basic Plugin Structure
|
||||
|
||||
```bash
|
||||
# Create plugin directory
|
||||
mkdir my-plugin
|
||||
cd my-plugin
|
||||
|
||||
# Create required manifest directory
|
||||
mkdir -p .claude-plugin
|
||||
|
||||
# Create plugin.json manifest
|
||||
cat > .claude-plugin/plugin.json << 'EOF'
|
||||
{
|
||||
"name": "my-plugin",
|
||||
"description": "Description of what your plugin does",
|
||||
"version": "1.0.0",
|
||||
"author": {
|
||||
"name": "Your Name"
|
||||
}
|
||||
}
|
||||
EOF
|
||||
```
|
||||
|
||||
### 2. Add Component Directories
|
||||
|
||||
```bash
|
||||
# Create directories for plugin components
|
||||
mkdir -p commands # Slash commands
|
||||
mkdir -p agents # Custom agents
|
||||
mkdir -p skills # Agent Skills
|
||||
mkdir -p hooks # Event handlers
|
||||
```
|
||||
|
||||
**Result**: Basic plugin structure ready for adding components.
|
||||
|
||||
## Plugin Manifest (plugin.json)
|
||||
|
||||
### Required Fields
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "plugin-name", // Lowercase, kebab-case
|
||||
"description": "What it does", // Clear, concise description
|
||||
"version": "1.0.0", // Semantic versioning
|
||||
"author": {
|
||||
"name": "Author Name" // Your name or organization
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Optional Fields
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "my-plugin",
|
||||
"description": "Advanced features",
|
||||
"version": "1.2.0",
|
||||
"author": {
|
||||
"name": "Your Name",
|
||||
"email": "you@example.com",
|
||||
"url": "https://yoursite.com"
|
||||
},
|
||||
"repository": {
|
||||
"type": "git",
|
||||
"url": "https://github.com/user/repo"
|
||||
},
|
||||
"license": "MIT",
|
||||
"keywords": ["productivity", "automation"]
|
||||
}
|
||||
```
|
||||
|
||||
## Plugin Components
|
||||
|
||||
### 1. Commands (Slash Commands)
|
||||
|
||||
Create markdown files in `commands/` directory:
|
||||
|
||||
```bash
|
||||
# commands/review-security.md
|
||||
---
|
||||
description: Review code for security vulnerabilities
|
||||
allowed-tools: Read(*), Grep(*)
|
||||
---
|
||||
|
||||
Review the following files for common security issues:
|
||||
- SQL injection vulnerabilities
|
||||
- XSS vulnerabilities
|
||||
- Hardcoded credentials
|
||||
- Unsafe deserialization
|
||||
|
||||
$ARGUMENTS
|
||||
```
|
||||
|
||||
**Usage**: `/review-security @src/auth.js`
|
||||
|
||||
### 2. Agents
|
||||
|
||||
Create agent configurations in `agents/` directory:
|
||||
|
||||
```bash
|
||||
# agents/code-reviewer.md
|
||||
---
|
||||
description: Reviews code for best practices
|
||||
tools: [Read, Grep, Bash]
|
||||
model: claude-sonnet-4
|
||||
---
|
||||
|
||||
You are a code review specialist. When reviewing code:
|
||||
1. Check for common patterns and anti-patterns
|
||||
2. Verify error handling
|
||||
3. Look for security issues
|
||||
4. Suggest improvements
|
||||
```
|
||||
|
||||
### 3. Skills
|
||||
|
||||
Create skill directories in `skills/`:
|
||||
|
||||
```bash
|
||||
mkdir -p skills/my-skill
|
||||
# Then create skills/my-skill/SKILL.md with proper frontmatter
|
||||
```
|
||||
|
||||
See the `claude-skills` skill for comprehensive skill creation guidance.
|
||||
|
||||
### 4. Hooks
|
||||
|
||||
Create `hooks/hooks.json` to define event handlers:
|
||||
|
||||
```json
|
||||
{
|
||||
"PostToolUse": [
|
||||
{
|
||||
"matcher": "Edit|Write",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "echo 'File modified: $TOOL_ARGS' >> .claude/activity.log"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 5. MCP Servers
|
||||
|
||||
Create `.mcp.json` for external tools:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"my-server": {
|
||||
"command": "node",
|
||||
"args": ["server.js"],
|
||||
"env": {
|
||||
"API_KEY": "env:MY_API_KEY"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Complete Plugin Example
|
||||
|
||||
### File Structure
|
||||
|
||||
```
|
||||
weather-plugin/
|
||||
├── .claude-plugin/
|
||||
│ └── plugin.json
|
||||
├── commands/
|
||||
│ └── weather.md
|
||||
├── agents/
|
||||
│ └── forecast-analyst.md
|
||||
├── skills/
|
||||
│ └── weather-api/
|
||||
│ └── SKILL.md
|
||||
└── README.md
|
||||
```
|
||||
|
||||
### plugin.json
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "weather-plugin",
|
||||
"description": "Weather forecasting and analysis tools",
|
||||
"version": "1.0.0",
|
||||
"author": {
|
||||
"name": "Weather Team"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### commands/weather.md
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Get current weather for a location
|
||||
argument-hint: <location>
|
||||
---
|
||||
|
||||
Get the current weather conditions for: $ARGUMENTS
|
||||
|
||||
Include:
|
||||
- Temperature
|
||||
- Conditions
|
||||
- Humidity
|
||||
- Wind speed
|
||||
```
|
||||
|
||||
### agents/forecast-analyst.md
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Analyzes weather patterns and forecasts
|
||||
tools: [WebFetch, Read]
|
||||
---
|
||||
|
||||
You are a weather analysis specialist. When asked about weather:
|
||||
1. Gather current conditions
|
||||
2. Analyze patterns
|
||||
3. Provide forecast insights
|
||||
4. Suggest appropriate actions
|
||||
```
|
||||
|
||||
## Distribution & Installation
|
||||
|
||||
### Local Development
|
||||
|
||||
Test your plugin locally:
|
||||
|
||||
```bash
|
||||
# Install from local directory
|
||||
/plugin install /path/to/my-plugin@local
|
||||
|
||||
# Verify installation
|
||||
/plugin list
|
||||
```
|
||||
|
||||
### Development Marketplace
|
||||
|
||||
Create a development marketplace for testing:
|
||||
|
||||
```json
|
||||
// ~/.claude/settings.json
|
||||
{
|
||||
"plugin-marketplaces": {
|
||||
"dev": {
|
||||
"url": "file:///path/to/marketplace-dir"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Team Distribution
|
||||
|
||||
Add to project settings for automatic installation:
|
||||
|
||||
```json
|
||||
// .claude/settings.json
|
||||
{
|
||||
"plugins": [
|
||||
"my-plugin@company-marketplace"
|
||||
],
|
||||
"plugin-marketplaces": {
|
||||
"company-marketplace": {
|
||||
"url": "https://plugins.company.com"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Plugin Design
|
||||
|
||||
1. **Single responsibility**: Each plugin should have a focused purpose
|
||||
2. **Clear naming**: Use descriptive, kebab-case names
|
||||
3. **Semantic versioning**: Follow SemVer for version numbers
|
||||
4. **Documentation**: Include comprehensive README.md
|
||||
|
||||
### Directory Organization
|
||||
|
||||
```
|
||||
my-plugin/
|
||||
├── .claude-plugin/ # Manifest only
|
||||
│ └── plugin.json
|
||||
├── commands/ # At plugin root, not in .claude-plugin/
|
||||
├── agents/ # At plugin root
|
||||
├── skills/ # At plugin root
|
||||
└── README.md # Usage documentation
|
||||
```
|
||||
|
||||
**IMPORTANT**: Component directories go at the plugin root, NOT inside `.claude-plugin/`
|
||||
|
||||
### Testing Checklist
|
||||
|
||||
- [ ] Plugin.json is valid JSON
|
||||
- [ ] All required fields present
|
||||
- [ ] Component directories at plugin root
|
||||
- [ ] Commands have valid frontmatter
|
||||
- [ ] Skills follow proper structure
|
||||
- [ ] Local installation works
|
||||
- [ ] No sensitive data in files
|
||||
- [ ] README documents all features
|
||||
|
||||
### Version Management
|
||||
|
||||
```bash
|
||||
# Update version in plugin.json
|
||||
{
|
||||
"version": "1.1.0" // Increment for changes
|
||||
}
|
||||
|
||||
# Breaking changes: 2.0.0
|
||||
# New features: 1.1.0
|
||||
# Bug fixes: 1.0.1
|
||||
```
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Multi-Command Plugin
|
||||
|
||||
For related commands, use subdirectories:
|
||||
|
||||
```
|
||||
git-tools/
|
||||
├── .claude-plugin/plugin.json
|
||||
└── commands/
|
||||
├── commit.md
|
||||
├── pr.md
|
||||
└── review.md
|
||||
```
|
||||
|
||||
**Usage**: `/commit`, `/pr`, `/review`
|
||||
|
||||
### Agent + Skill Combination
|
||||
|
||||
Combine agents with specialized skills:
|
||||
|
||||
```
|
||||
api-plugin/
|
||||
├── .claude-plugin/plugin.json
|
||||
├── agents/
|
||||
│ └── api-specialist.md
|
||||
└── skills/
|
||||
└── rest-api/
|
||||
└── SKILL.md
|
||||
```
|
||||
|
||||
The agent can leverage the skill for specialized knowledge.
|
||||
|
||||
### Hook-Based Automation
|
||||
|
||||
Use hooks for workflow automation:
|
||||
|
||||
```json
|
||||
{
|
||||
"PostToolUse": [
|
||||
{
|
||||
"matcher": "Write",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "npm run format $TOOL_ARGS"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Plugin Not Found
|
||||
|
||||
**Issue**: `/plugin install` can't find plugin
|
||||
|
||||
**Solutions**:
|
||||
1. Check marketplace configuration in settings.json
|
||||
2. Verify plugin name matches directory name
|
||||
3. Ensure plugin.json exists in `.claude-plugin/`
|
||||
|
||||
### Commands Not Available
|
||||
|
||||
**Issue**: Slash commands don't appear
|
||||
|
||||
**Solutions**:
|
||||
1. Verify commands are in `commands/` at plugin root
|
||||
2. Check markdown files have `.md` extension
|
||||
3. Restart Claude Code to refresh
|
||||
|
||||
### Invalid Structure Error
|
||||
|
||||
**Issue**: Plugin fails to load
|
||||
|
||||
**Solutions**:
|
||||
1. Ensure `.claude-plugin/plugin.json` exists
|
||||
2. Validate JSON syntax
|
||||
3. Move component directories to plugin root (not in `.claude-plugin/`)
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### Never Include
|
||||
|
||||
- API keys or credentials in plugin files
|
||||
- Personal identifying information
|
||||
- Proprietary code without permission
|
||||
- Hardcoded paths to user-specific locations
|
||||
|
||||
### Use Environment Variables
|
||||
|
||||
```json
|
||||
// .mcp.json
|
||||
{
|
||||
"mcpServers": {
|
||||
"api-server": {
|
||||
"env": {
|
||||
"API_KEY": "env:MY_API_KEY" // Reference env var
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Command Permissions
|
||||
|
||||
Limit tool access in command frontmatter:
|
||||
|
||||
```markdown
|
||||
---
|
||||
allowed-tools: Read(src/**), Grep(src/**)
|
||||
---
|
||||
```
|
||||
|
||||
## Plugin Template
|
||||
|
||||
Use this as a starting point:
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# create-plugin.sh <plugin-name>
|
||||
|
||||
PLUGIN_NAME=$1
|
||||
|
||||
mkdir -p "$PLUGIN_NAME"/{.claude-plugin,commands,agents,skills,hooks}
|
||||
|
||||
cat > "$PLUGIN_NAME/.claude-plugin/plugin.json" << EOF
|
||||
{
|
||||
"name": "$PLUGIN_NAME",
|
||||
"description": "TODO: Add description",
|
||||
"version": "0.1.0",
|
||||
"author": {
|
||||
"name": "TODO: Add author"
|
||||
}
|
||||
}
|
||||
EOF
|
||||
|
||||
cat > "$PLUGIN_NAME/README.md" << EOF
|
||||
# $PLUGIN_NAME
|
||||
|
||||
TODO: Add plugin description
|
||||
|
||||
## Installation
|
||||
|
||||
\`\`\`
|
||||
/plugin install $PLUGIN_NAME@marketplace
|
||||
\`\`\`
|
||||
|
||||
## Features
|
||||
|
||||
TODO: List features
|
||||
|
||||
## Usage
|
||||
|
||||
TODO: Add usage examples
|
||||
EOF
|
||||
|
||||
echo "Plugin structure created in $PLUGIN_NAME/"
|
||||
```
|
||||
|
||||
## Resources
|
||||
|
||||
- [Official Plugin Documentation](https://docs.claude.com/en/docs/claude-code/plugins)
|
||||
- [Slash Commands Guide](../claude-code-slash-commands/SKILL.md)
|
||||
- [Hooks Guide](../claude-code-hooks/SKILL.md)
|
||||
- [Agent Skills Guide](../claude-skills/SKILL.md)
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### Required Structure
|
||||
```
|
||||
plugin-name/
|
||||
└── .claude-plugin/
|
||||
└── plugin.json
|
||||
```
|
||||
|
||||
### Common Commands
|
||||
```bash
|
||||
# Install
|
||||
/plugin install plugin-name@marketplace
|
||||
|
||||
# List installed
|
||||
/plugin list
|
||||
|
||||
# Uninstall
|
||||
/plugin uninstall plugin-name
|
||||
```
|
||||
|
||||
### Manifest Template
|
||||
```json
|
||||
{
|
||||
"name": "plugin-name",
|
||||
"description": "What it does",
|
||||
"version": "1.0.0",
|
||||
"author": {"name": "Your Name"}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Remember**: Plugins extend Claude Code with persistent, reusable functionality. Start simple with one or two components, test thoroughly, then expand based on actual needs.
|
||||
698
claude-code/skills/claude-code-slash-commands/SKILL.md
Normal file
698
claude-code/skills/claude-code-slash-commands/SKILL.md
Normal file
@@ -0,0 +1,698 @@
|
||||
---
|
||||
name: Slash Command Creator
|
||||
description: Create custom slash commands for Claude Code with argument handling, bash execution, and file references. Use when building reusable prompts, automating workflows, or creating project-specific commands.
|
||||
---
|
||||
|
||||
# Slash Command Development
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
Use this skill when:
|
||||
- Creating custom slash commands for Claude Code
|
||||
- Building reusable prompt templates
|
||||
- Automating repetitive tasks with commands
|
||||
- Setting up project-specific workflows
|
||||
- Converting manual prompts to slash commands
|
||||
|
||||
Do NOT use this skill for:
|
||||
- Creating full plugins (use claude-code-plugins skill)
|
||||
- Setting up hooks (use claude-code-hooks skill)
|
||||
- General Claude Code usage
|
||||
|
||||
## Quick Start: Creating a Command
|
||||
|
||||
### 1. Create Command File
|
||||
|
||||
```bash
|
||||
# Project-specific command (shared with team)
|
||||
mkdir -p .claude/commands
|
||||
cat > .claude/commands/review.md << 'EOF'
|
||||
---
|
||||
description: Review code for common issues
|
||||
---
|
||||
|
||||
Review the following code for:
|
||||
- Bugs and logic errors
|
||||
- Code style issues
|
||||
- Performance problems
|
||||
- Security vulnerabilities
|
||||
|
||||
$ARGUMENTS
|
||||
EOF
|
||||
```
|
||||
|
||||
**Usage**: `/review @src/main.js`
|
||||
|
||||
### 2. Personal Command (Your Use Only)
|
||||
|
||||
```bash
|
||||
# Personal command (not shared)
|
||||
mkdir -p ~/.claude/commands
|
||||
cat > ~/.claude/commands/explain.md << 'EOF'
|
||||
---
|
||||
description: Explain code in detail
|
||||
argument-hint: <file-path>
|
||||
---
|
||||
|
||||
Provide a detailed explanation of: $ARGUMENTS
|
||||
|
||||
Include:
|
||||
- What the code does
|
||||
- How it works
|
||||
- Key design decisions
|
||||
- Potential improvements
|
||||
EOF
|
||||
```
|
||||
|
||||
**Usage**: `/explain @utils/parser.ts`
|
||||
|
||||
## Command Locations
|
||||
|
||||
### Project Commands (.claude/commands/)
|
||||
|
||||
**Location**: `.claude/commands/` in your project
|
||||
**Scope**: Available to everyone working on the project
|
||||
**Version Control**: Commit to git for team sharing
|
||||
**Use For**: Project-specific workflows, team standards
|
||||
|
||||
### Personal Commands (~/.claude/commands/)
|
||||
|
||||
**Location**: `~/.claude/commands/`
|
||||
**Scope**: Available in all your projects
|
||||
**Version Control**: Not in git (user-specific)
|
||||
**Use For**: Personal productivity, custom preferences
|
||||
|
||||
## Command Syntax
|
||||
|
||||
### Basic Structure
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Brief description for /help
|
||||
---
|
||||
|
||||
Prompt content here
|
||||
```
|
||||
|
||||
### Command Name
|
||||
|
||||
The filename (without `.md`) becomes the command:
|
||||
|
||||
```bash
|
||||
# File: .claude/commands/test.md
|
||||
# Command: /test
|
||||
|
||||
# File: .claude/commands/commit-push.md
|
||||
# Command: /commit-push
|
||||
```
|
||||
|
||||
## Frontmatter Options
|
||||
|
||||
### description
|
||||
|
||||
Shows in `/help` output:
|
||||
|
||||
```yaml
|
||||
---
|
||||
description: Generate unit tests for a function
|
||||
---
|
||||
```
|
||||
|
||||
### argument-hint
|
||||
|
||||
Shows expected arguments in autocomplete:
|
||||
|
||||
```yaml
|
||||
---
|
||||
description: Compare two files
|
||||
argument-hint: <file1> <file2>
|
||||
---
|
||||
```
|
||||
|
||||
### allowed-tools
|
||||
|
||||
Specifies which tools the command can use:
|
||||
|
||||
```yaml
|
||||
---
|
||||
description: Review and commit changes
|
||||
allowed-tools: Bash(git status:*), Bash(git add:*), Bash(git commit:*)
|
||||
---
|
||||
```
|
||||
|
||||
**Patterns**:
|
||||
- `Bash(git status:*)` - Specific command with any args
|
||||
- `Read(*)` - Tool with any args
|
||||
- `*` - All tools allowed
|
||||
|
||||
### model
|
||||
|
||||
Override default model for this command:
|
||||
|
||||
```yaml
|
||||
---
|
||||
description: Simple task
|
||||
model: claude-haiku-4
|
||||
---
|
||||
```
|
||||
|
||||
### disable-model-invocation
|
||||
|
||||
Prevent SlashCommand tool from calling this:
|
||||
|
||||
```yaml
|
||||
---
|
||||
description: Internal helper command
|
||||
disable-model-invocation: true
|
||||
---
|
||||
```
|
||||
|
||||
## Argument Handling
|
||||
|
||||
### $ARGUMENTS - All Arguments
|
||||
|
||||
Captures everything passed to the command:
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Explain multiple files
|
||||
---
|
||||
|
||||
Explain these files: $ARGUMENTS
|
||||
```
|
||||
|
||||
**Usage**: `/explain @src/a.js @src/b.js @src/c.js`
|
||||
**Result**: All three file paths captured
|
||||
|
||||
### Positional Arguments ($1, $2, $3...)
|
||||
|
||||
Individual arguments like shell scripts:
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Compare two approaches
|
||||
argument-hint: <approach1> <approach2>
|
||||
---
|
||||
|
||||
Compare approach "$1" versus "$2" and recommend which is better.
|
||||
```
|
||||
|
||||
**Usage**: `/compare REST GraphQL`
|
||||
**$1** = "REST"
|
||||
**$2** = "GraphQL"
|
||||
|
||||
### Combining Arguments
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Test specific function
|
||||
argument-hint: <file> <function-name>
|
||||
---
|
||||
|
||||
In file $1, create comprehensive tests for the function: $2
|
||||
|
||||
$ARGUMENTS
|
||||
```
|
||||
|
||||
## File References with @
|
||||
|
||||
### Single File
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Review a file
|
||||
---
|
||||
|
||||
Review @$1 for code quality issues.
|
||||
```
|
||||
|
||||
**Usage**: `/review src/auth.js`
|
||||
Claude will read `src/auth.js` automatically
|
||||
|
||||
### Multiple Files
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Compare implementations
|
||||
---
|
||||
|
||||
Compare the implementation approaches in:
|
||||
$ARGUMENTS
|
||||
|
||||
Which approach is better and why?
|
||||
```
|
||||
|
||||
**Usage**: `/compare @old/version.js @new/version.js`
|
||||
|
||||
### Inline File References
|
||||
|
||||
```markdown
|
||||
Review @src/config.js and ensure it follows @docs/style-guide.md
|
||||
```
|
||||
|
||||
The `@` prefix tells Claude to read those files before processing.
|
||||
|
||||
## Bash Execution with !
|
||||
|
||||
### Prefix Commands with !
|
||||
|
||||
Run bash before the slash command executes:
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Show git status and suggest next steps
|
||||
allowed-tools: Bash(git status:*), Bash(git diff:*)
|
||||
---
|
||||
|
||||
!git status
|
||||
!git diff --stat
|
||||
|
||||
Based on the current git state, suggest what I should do next.
|
||||
```
|
||||
|
||||
**Important**: Must include `allowed-tools` with Bash tool specification.
|
||||
|
||||
### Why Use ! Prefix?
|
||||
|
||||
Without `!`, bash commands are just text in the prompt.
|
||||
With `!`, they execute and results are included in context.
|
||||
|
||||
```markdown
|
||||
# This doesn't work (just text):
|
||||
git status
|
||||
What should I commit?
|
||||
|
||||
# This works (executes first):
|
||||
---
|
||||
allowed-tools: Bash(git status:*)
|
||||
---
|
||||
|
||||
!git status
|
||||
What should I commit?
|
||||
```
|
||||
|
||||
## Namespacing with Directories
|
||||
|
||||
### Organize Related Commands
|
||||
|
||||
```
|
||||
.claude/commands/
|
||||
├── git/
|
||||
│ ├── commit.md
|
||||
│ ├── review.md
|
||||
│ └── sync.md
|
||||
└── test/
|
||||
├── unit.md
|
||||
└── integration.md
|
||||
```
|
||||
|
||||
**Commands**: `/commit`, `/review`, `/sync`, `/unit`, `/integration`
|
||||
|
||||
**Note**: Directory structure is for organization only - it doesn't affect command names.
|
||||
|
||||
## Complete Examples
|
||||
|
||||
### 1. Security Review Command
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Comprehensive security review of code files
|
||||
allowed-tools: Read(*), Grep(*), Bash(grep:*)
|
||||
argument-hint: <files...>
|
||||
---
|
||||
|
||||
Perform a security audit on: $ARGUMENTS
|
||||
|
||||
Check for:
|
||||
1. SQL injection vulnerabilities
|
||||
2. XSS vulnerabilities
|
||||
3. Authentication/authorization issues
|
||||
4. Hardcoded secrets or credentials
|
||||
5. Unsafe deserialization
|
||||
6. Path traversal vulnerabilities
|
||||
7. Insecure cryptography
|
||||
8. Information disclosure
|
||||
|
||||
For each issue found:
|
||||
- Severity level (Critical/High/Medium/Low)
|
||||
- Location (file:line)
|
||||
- Explanation of the vulnerability
|
||||
- Recommended fix with code example
|
||||
```
|
||||
|
||||
**Usage**: `/security-review @src/auth.js @src/api.js`
|
||||
|
||||
### 2. Commit + Push Command
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Review changes, commit, and push to remote
|
||||
allowed-tools: Bash(git:*)
|
||||
---
|
||||
|
||||
!git status
|
||||
!git diff
|
||||
|
||||
Review the changes above and:
|
||||
1. Create an appropriate commit message
|
||||
2. Commit the changes
|
||||
3. Push to remote
|
||||
|
||||
Ask for confirmation before pushing.
|
||||
```
|
||||
|
||||
**Usage**: `/commit-push`
|
||||
|
||||
### 3. Test Generator
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Generate comprehensive tests for a function
|
||||
argument-hint: <file> <function-name>
|
||||
model: claude-sonnet-4
|
||||
---
|
||||
|
||||
For the function "$2" in @$1:
|
||||
|
||||
1. Analyze the function's behavior
|
||||
2. Identify edge cases
|
||||
3. Generate comprehensive unit tests including:
|
||||
- Happy path tests
|
||||
- Edge case tests
|
||||
- Error condition tests
|
||||
- Boundary value tests
|
||||
|
||||
Use the project's existing test framework and patterns.
|
||||
```
|
||||
|
||||
**Usage**: `/test-gen src/parser.js parseQuery`
|
||||
|
||||
### 4. API Documentation
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Generate API documentation for endpoints
|
||||
allowed-tools: Read(*), Grep(*)
|
||||
---
|
||||
|
||||
Generate API documentation for: $ARGUMENTS
|
||||
|
||||
Include:
|
||||
- Endpoint URL and method
|
||||
- Request parameters (query, body, headers)
|
||||
- Response format and status codes
|
||||
- Example requests and responses
|
||||
- Error conditions
|
||||
- Authentication requirements
|
||||
|
||||
Format as OpenAPI/Swagger compatible YAML.
|
||||
```
|
||||
|
||||
**Usage**: `/api-docs @routes/users.js @routes/posts.js`
|
||||
|
||||
### 5. Performance Analysis
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Analyze code for performance issues
|
||||
argument-hint: <file>
|
||||
---
|
||||
|
||||
Analyze @$1 for performance issues:
|
||||
|
||||
1. **Time Complexity**: Identify algorithms and their complexity
|
||||
2. **Space Complexity**: Memory usage patterns
|
||||
3. **Bottlenecks**: Potential performance problems
|
||||
4. **Optimization Opportunities**: Specific improvements with examples
|
||||
|
||||
For each issue:
|
||||
- Current implementation
|
||||
- Why it's problematic
|
||||
- Optimized version
|
||||
- Performance impact estimate
|
||||
```
|
||||
|
||||
**Usage**: `/perf @src/data-processor.js`
|
||||
|
||||
## Command Patterns
|
||||
|
||||
### Review Pattern
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Review X for Y
|
||||
---
|
||||
|
||||
Review $ARGUMENTS for [specific criteria]
|
||||
|
||||
Include:
|
||||
- [Aspect 1]
|
||||
- [Aspect 2]
|
||||
- [Aspect 3]
|
||||
```
|
||||
|
||||
### Generate Pattern
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Generate X from Y
|
||||
---
|
||||
|
||||
Generate [output type] for: $ARGUMENTS
|
||||
|
||||
Requirements:
|
||||
- [Requirement 1]
|
||||
- [Requirement 2]
|
||||
```
|
||||
|
||||
### Compare Pattern
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Compare X and Y
|
||||
argument-hint: <option1> <option2>
|
||||
---
|
||||
|
||||
Compare "$1" versus "$2"
|
||||
|
||||
Analyze:
|
||||
- [Comparison aspect 1]
|
||||
- [Comparison aspect 2]
|
||||
|
||||
Recommendation: [Which is better and why]
|
||||
```
|
||||
|
||||
### Workflow Pattern
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Execute multi-step workflow
|
||||
allowed-tools: Bash(*), Read(*), Write(*)
|
||||
---
|
||||
|
||||
Execute the following workflow:
|
||||
|
||||
1. [Step 1]
|
||||
2. [Step 2]
|
||||
3. [Step 3]
|
||||
|
||||
After each step, confirm before proceeding.
|
||||
```
|
||||
|
||||
## Testing Commands
|
||||
|
||||
### 1. Check Command List
|
||||
|
||||
```bash
|
||||
# See all available commands
|
||||
/help
|
||||
|
||||
# Your command should appear in the list
|
||||
```
|
||||
|
||||
### 2. Test Argument Handling
|
||||
|
||||
```bash
|
||||
# Test with different argument patterns
|
||||
/mycommand arg1
|
||||
/mycommand arg1 arg2
|
||||
/mycommand @file.js
|
||||
/mycommand @file1.js @file2.js
|
||||
```
|
||||
|
||||
### 3. Verify Bash Execution
|
||||
|
||||
If using `!` prefix, confirm commands execute:
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Test bash execution
|
||||
allowed-tools: Bash(echo:*)
|
||||
---
|
||||
|
||||
!echo "This should show before prompt processing"
|
||||
|
||||
Did the echo work?
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Clear Descriptions
|
||||
|
||||
```yaml
|
||||
# Good
|
||||
description: Generate unit tests for a specific function
|
||||
|
||||
# Bad
|
||||
description: Testing
|
||||
```
|
||||
|
||||
### 2. Explicit Arguments
|
||||
|
||||
```yaml
|
||||
# Good
|
||||
argument-hint: <file-path> <function-name>
|
||||
|
||||
# Bad (no hint)
|
||||
argument-hint:
|
||||
```
|
||||
|
||||
### 3. Specific Tool Permissions
|
||||
|
||||
```yaml
|
||||
# Good - minimal permissions
|
||||
allowed-tools: Bash(git status:*), Bash(git diff:*)
|
||||
|
||||
# Risky - too permissive
|
||||
allowed-tools: *
|
||||
```
|
||||
|
||||
### 4. Meaningful Names
|
||||
|
||||
```bash
|
||||
# Good
|
||||
/generate-tests
|
||||
/review-security
|
||||
/commit-and-push
|
||||
|
||||
# Bad
|
||||
/gt
|
||||
/rs
|
||||
/cap
|
||||
```
|
||||
|
||||
### 5. Self-Documenting Content
|
||||
|
||||
```markdown
|
||||
Review code for:
|
||||
1. Logic errors
|
||||
2. Style issues
|
||||
3. Performance problems
|
||||
|
||||
$ARGUMENTS
|
||||
```
|
||||
|
||||
Better than:
|
||||
|
||||
```markdown
|
||||
Review: $ARGUMENTS
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Command Not Found
|
||||
|
||||
**Issue**: `/mycommand` says command not found
|
||||
|
||||
**Solutions**:
|
||||
1. Check file is in `.claude/commands/` or `~/.claude/commands/`
|
||||
2. Verify filename ends with `.md`
|
||||
3. Restart Claude Code to refresh command list
|
||||
|
||||
### Arguments Not Working
|
||||
|
||||
**Issue**: `$ARGUMENTS` or `$1` showing literally
|
||||
|
||||
**Solutions**:
|
||||
1. Ensure proper syntax: `$ARGUMENTS`, `$1`, `$2` (not `${ARGUMENTS}`)
|
||||
2. Check for typos in variable names
|
||||
3. Test with simple command first
|
||||
|
||||
### Bash Commands Not Executing
|
||||
|
||||
**Issue**: `!command` not running
|
||||
|
||||
**Solutions**:
|
||||
1. Add `allowed-tools` to frontmatter
|
||||
2. Include specific tool pattern: `Bash(git:*)`
|
||||
3. Test with simple command: `!echo test`
|
||||
|
||||
### File References Not Loading
|
||||
|
||||
**Issue**: `@file.js` not including file content
|
||||
|
||||
**Solutions**:
|
||||
1. Verify file path is correct (relative to project root)
|
||||
2. Check file exists: `ls @file.js`
|
||||
3. Ensure no typos in file path
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### Limit Tool Access
|
||||
|
||||
Only grant necessary permissions:
|
||||
|
||||
```yaml
|
||||
# Specific commands only
|
||||
allowed-tools: Bash(git status:*), Bash(git log:*)
|
||||
|
||||
# Never use unless absolutely required
|
||||
allowed-tools: *
|
||||
```
|
||||
|
||||
### No Hardcoded Secrets
|
||||
|
||||
```markdown
|
||||
# Bad - hardcoded API key
|
||||
!curl -H "API-Key: sk-abc123..." api.example.com
|
||||
|
||||
# Good - use environment variables
|
||||
!curl -H "API-Key: $MY_API_KEY" api.example.com
|
||||
```
|
||||
|
||||
### Validate User Input
|
||||
|
||||
If using arguments in bash:
|
||||
|
||||
```markdown
|
||||
# Risky - no validation
|
||||
!rm -rf $1
|
||||
|
||||
# Better - validate first
|
||||
Confirm you want to delete: $1
|
||||
(Then use interactive confirmation before executing)
|
||||
```
|
||||
|
||||
## Command Template
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: [Clear, concise description of what this command does]
|
||||
argument-hint: [Expected arguments format]
|
||||
allowed-tools: [Specific tool patterns if needed]
|
||||
---
|
||||
|
||||
[Command prompt template]
|
||||
|
||||
$ARGUMENTS
|
||||
```
|
||||
|
||||
## Resources
|
||||
|
||||
- [Official Slash Commands Documentation](https://docs.claude.com/en/docs/claude-code/slash-commands)
|
||||
- [Plugin Development](../claude-code-plugins/SKILL.md) - For packaging commands in plugins
|
||||
- [Hooks](../claude-code-hooks/SKILL.md) - For event-based automation
|
||||
|
||||
---
|
||||
|
||||
**Remember**: Slash commands are for reusable prompts. Start with manual prompts, identify patterns you repeat, then codify them as commands.
|
||||
934
claude-code/skills/claude-code-subagents/SKILL.md
Normal file
934
claude-code/skills/claude-code-subagents/SKILL.md
Normal file
@@ -0,0 +1,934 @@
|
||||
---
|
||||
name: Claude Code Subagent Specialist
|
||||
description: Refine and troubleshoot Claude Code subagents by optimizing prompts, tool access, descriptions, and performance. Use when improving existing subagents, debugging activation issues, or optimizing delegation patterns. NOT for initial creation - use /agents command first.
|
||||
---
|
||||
|
||||
# Claude Code Subagent Refinement & Troubleshooting
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
Use this skill when:
|
||||
- Refining existing subagent prompts for better performance
|
||||
- Troubleshooting why a subagent isn't activating
|
||||
- Optimizing tool access and permissions
|
||||
- Improving subagent descriptions for better delegation
|
||||
- Debugging context management issues
|
||||
- Testing and validating subagent behavior
|
||||
- Converting ad-hoc workflows to reusable subagents
|
||||
|
||||
Do NOT use this skill for:
|
||||
- **Initial creation** - Use `/agents` command instead (it provides interactive UI)
|
||||
- Creating slash commands (use claude-code-slash-commands skill)
|
||||
- General Claude Code troubleshooting
|
||||
|
||||
**Important**: Always start with `/agents` to create subagents. Use this skill to refine them afterward.
|
||||
|
||||
## Quick Reference: Subagent Structure
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: agent-name # Lowercase, kebab-case identifier
|
||||
description: When to use # Triggers automatic delegation
|
||||
tools: Tool1, Tool2 # Optional: omit to inherit all
|
||||
model: sonnet # Optional: sonnet/opus/haiku/inherit
|
||||
---
|
||||
|
||||
System prompt defining role, capabilities, and behavior.
|
||||
Include specific instructions, constraints, and examples.
|
||||
```
|
||||
|
||||
**File Locations**:
|
||||
- Project: `.claude/agents/` (highest priority)
|
||||
- User: `~/.claude/agents/` (shared across projects)
|
||||
- Plugin: `agents/` in plugin directory
|
||||
|
||||
## Common Problems & Solutions
|
||||
|
||||
### Problem 1: Subagent Never Activates
|
||||
|
||||
**Symptoms**: Claude doesn't delegate to your subagent
|
||||
|
||||
**Diagnose**:
|
||||
```yaml
|
||||
# Check your description field
|
||||
---
|
||||
description: Helper agent # ❌ Too vague
|
||||
---
|
||||
```
|
||||
|
||||
**Fix - Make Description Specific**:
|
||||
```yaml
|
||||
# Before (vague)
|
||||
---
|
||||
description: Helps with security
|
||||
---
|
||||
|
||||
# After (specific)
|
||||
---
|
||||
description: Analyze code for security vulnerabilities including SQL injection, XSS, authentication flaws, and hardcoded secrets. Use PROACTIVELY when reviewing code for security issues.
|
||||
---
|
||||
```
|
||||
|
||||
**Best Practices for Descriptions**:
|
||||
- Include specific trigger words and scenarios
|
||||
- Add "use PROACTIVELY" or "MUST BE USED" for automatic activation
|
||||
- Mention the domain/context clearly
|
||||
- List key capabilities or checks
|
||||
|
||||
### Problem 2: Subagent Has Wrong Tools
|
||||
|
||||
**Symptoms**: Subagent can't complete tasks or has too many permissions
|
||||
|
||||
**Diagnose**:
|
||||
```bash
|
||||
# Check current tool configuration
|
||||
cat .claude/agents/my-agent.md | grep "tools:"
|
||||
```
|
||||
|
||||
**Fix - Whitelist Specific Tools**:
|
||||
```yaml
|
||||
# Inherits all tools (may be too permissive)
|
||||
---
|
||||
name: security-analyzer
|
||||
description: Security analysis
|
||||
---
|
||||
|
||||
# Restricted to read-only tools (better)
|
||||
---
|
||||
name: security-analyzer
|
||||
description: Security analysis
|
||||
tools: Read, Grep, Glob
|
||||
---
|
||||
```
|
||||
|
||||
**Tool Access Strategies**:
|
||||
|
||||
**1. Inherit All (Default)**:
|
||||
```yaml
|
||||
# Omit 'tools' field entirely
|
||||
---
|
||||
name: general-helper
|
||||
description: General assistance
|
||||
---
|
||||
```
|
||||
Use when: Agent needs full flexibility
|
||||
|
||||
**2. Read-Only Access**:
|
||||
```yaml
|
||||
---
|
||||
tools: Read, Grep, Glob, Bash(git log:*), Bash(git diff:*)
|
||||
---
|
||||
```
|
||||
Use when: Analysis, review, documentation
|
||||
|
||||
**3. Specific Permissions**:
|
||||
```yaml
|
||||
---
|
||||
tools: Read, Write, Edit, Bash(npm test:*)
|
||||
---
|
||||
```
|
||||
Use when: Implementation with validation
|
||||
|
||||
**4. No File Access**:
|
||||
```yaml
|
||||
---
|
||||
tools: WebFetch, WebSearch, Bash
|
||||
---
|
||||
```
|
||||
Use when: Research, external data gathering
|
||||
|
||||
### Problem 3: Poor Quality Output
|
||||
|
||||
**Symptoms**: Subagent completes tasks but results are inconsistent or low-quality
|
||||
|
||||
**Diagnose**: Check system prompt specificity
|
||||
|
||||
**Fix - Enhance System Prompt**:
|
||||
|
||||
```markdown
|
||||
# Before (vague)
|
||||
---
|
||||
name: code-reviewer
|
||||
---
|
||||
|
||||
You review code for issues.
|
||||
```
|
||||
|
||||
```markdown
|
||||
# After (specific)
|
||||
---
|
||||
name: code-reviewer
|
||||
---
|
||||
|
||||
You are a senior code reviewer specializing in production-ready code quality.
|
||||
|
||||
## Your Responsibilities
|
||||
|
||||
1. **Logic & Correctness**
|
||||
- Verify algorithm correctness
|
||||
- Check edge case handling
|
||||
- Validate error conditions
|
||||
|
||||
2. **Code Quality**
|
||||
- Ensure single responsibility principle
|
||||
- Check for code duplication (DRY)
|
||||
- Verify meaningful naming
|
||||
|
||||
3. **Security**
|
||||
- Identify injection vulnerabilities
|
||||
- Check authentication/authorization
|
||||
- Flag hardcoded secrets
|
||||
|
||||
4. **Performance**
|
||||
- Spot O(n²) or worse algorithms
|
||||
- Identify unnecessary loops
|
||||
- Check resource cleanup
|
||||
|
||||
## Output Format
|
||||
|
||||
For each issue found:
|
||||
- **Severity**: Critical/High/Medium/Low
|
||||
- **Location**: file:line
|
||||
- **Issue**: Clear description
|
||||
- **Fix**: Specific code example
|
||||
|
||||
## Constraints
|
||||
|
||||
- Only report actionable issues
|
||||
- Provide code examples for fixes
|
||||
- Focus on high-impact problems first
|
||||
- No nitpicking style issues unless severe
|
||||
```
|
||||
|
||||
**System Prompt Best Practices**:
|
||||
- Define role and expertise level
|
||||
- List specific responsibilities
|
||||
- Include output format requirements
|
||||
- Add examples of good/bad cases
|
||||
- Specify constraints and boundaries
|
||||
- Use headings for scannability
|
||||
|
||||
### Problem 4: Context Pollution
|
||||
|
||||
**Symptoms**: Main conversation gets cluttered with subagent details
|
||||
|
||||
**Understand**: Subagents have isolated context windows - only their final output returns
|
||||
|
||||
**Fix - Structure Output Properly**:
|
||||
|
||||
```markdown
|
||||
# System prompt guidance
|
||||
---
|
||||
name: research-agent
|
||||
---
|
||||
|
||||
Research [topic] and return ONLY:
|
||||
1. Key findings (3-5 bullet points)
|
||||
2. Relevant URLs
|
||||
3. Recommendation
|
||||
|
||||
Do NOT include:
|
||||
- Full article text
|
||||
- Research methodology
|
||||
- Intermediate thoughts
|
||||
```
|
||||
|
||||
**Best Practices**:
|
||||
- Explicitly tell subagent what to return
|
||||
- Request summaries, not full details
|
||||
- Have subagent filter before returning
|
||||
- Use structured output formats
|
||||
|
||||
### Problem 5: Activation Too Broad/Narrow
|
||||
|
||||
**Symptoms**: Subagent activates for wrong tasks OR misses relevant tasks
|
||||
|
||||
**Diagnose - Test Trigger Scenarios**:
|
||||
|
||||
```markdown
|
||||
# Test cases for a "security-analyzer" subagent
|
||||
|
||||
Should Activate:
|
||||
- "Review this auth code for vulnerabilities"
|
||||
- "Check if we're handling passwords securely"
|
||||
- "Scan for SQL injection risks"
|
||||
|
||||
Should NOT Activate:
|
||||
- "Write unit tests" (different concern)
|
||||
- "Refactor this function" (not security-focused)
|
||||
- "Add logging" (different task)
|
||||
```
|
||||
|
||||
**Fix - Refine Description**:
|
||||
|
||||
```yaml
|
||||
# Too narrow
|
||||
---
|
||||
description: Checks for SQL injection only
|
||||
---
|
||||
|
||||
# Too broad
|
||||
---
|
||||
description: Helps with code
|
||||
---
|
||||
|
||||
# Just right
|
||||
---
|
||||
description: Analyze code for security vulnerabilities including SQL injection, XSS, CSRF, authentication issues, and secrets exposure. Use when reviewing code for security concerns or compliance requirements.
|
||||
---
|
||||
```
|
||||
|
||||
### Problem 6: Model Selection Issues
|
||||
|
||||
**Symptoms**: Subagent too slow/expensive OR too simple for task
|
||||
|
||||
**Fix - Choose Right Model**:
|
||||
|
||||
```yaml
|
||||
# Fast, simple tasks (formatting, linting)
|
||||
---
|
||||
model: haiku
|
||||
---
|
||||
|
||||
# Complex reasoning (architecture, design)
|
||||
---
|
||||
model: opus
|
||||
---
|
||||
|
||||
# Balanced (most cases)
|
||||
---
|
||||
model: sonnet
|
||||
---
|
||||
|
||||
# Same as main conversation
|
||||
---
|
||||
model: inherit
|
||||
---
|
||||
```
|
||||
|
||||
**Model Selection Guide**:
|
||||
|
||||
| Model | Use For | Avoid For |
|
||||
|-------|---------|-----------|
|
||||
| haiku | Simple transforms, quick checks | Complex reasoning, creativity |
|
||||
| sonnet | General tasks, balanced quality | When opus is specifically needed |
|
||||
| opus | Complex architecture, creative work | Simple/repetitive tasks (cost) |
|
||||
| inherit | Task complexity matches main thread | When you need different capability |
|
||||
|
||||
## Optimization Patterns
|
||||
|
||||
### Pattern 1: Role-Based Pipeline
|
||||
|
||||
Create specialized agents for each workflow stage:
|
||||
|
||||
```yaml
|
||||
# 1. Spec Agent
|
||||
---
|
||||
name: product-spec-writer
|
||||
description: Create detailed product specifications from user requirements
|
||||
tools: Read, Write, WebSearch
|
||||
model: opus
|
||||
---
|
||||
|
||||
You convert user requirements into detailed product specs.
|
||||
|
||||
[Detailed prompt...]
|
||||
```
|
||||
|
||||
```yaml
|
||||
# 2. Architect Agent
|
||||
---
|
||||
name: solution-architect
|
||||
description: Design system architecture from product specs
|
||||
tools: Read, Write, Grep, Glob
|
||||
model: opus
|
||||
---
|
||||
|
||||
You design scalable system architectures.
|
||||
|
||||
[Detailed prompt...]
|
||||
```
|
||||
|
||||
```yaml
|
||||
# 3. Implementer Agent
|
||||
---
|
||||
name: code-implementer
|
||||
description: Implement features from architectural designs
|
||||
tools: Read, Write, Edit, Bash(npm test:*)
|
||||
model: sonnet
|
||||
---
|
||||
|
||||
You implement features following architectural guidelines.
|
||||
|
||||
[Detailed prompt...]
|
||||
```
|
||||
|
||||
**Usage**: Chain with hooks or explicit handoffs
|
||||
|
||||
### Pattern 2: Domain Specialists
|
||||
|
||||
```yaml
|
||||
# Frontend Specialist
|
||||
---
|
||||
name: frontend-specialist
|
||||
description: React/TypeScript UI development and component design. Use PROACTIVELY for frontend work.
|
||||
tools: Read, Write, Edit, Grep, Bash(npm:*)
|
||||
---
|
||||
|
||||
You are a React/TypeScript expert specializing in modern frontend development.
|
||||
|
||||
## Tech Stack
|
||||
- React 18+ with hooks
|
||||
- TypeScript (strict mode)
|
||||
- Tailwind CSS
|
||||
- Component-driven architecture
|
||||
|
||||
## Principles
|
||||
- Functional components only
|
||||
- Custom hooks for logic reuse
|
||||
- Accessibility (WCAG AA)
|
||||
- Performance (lazy loading, memoization)
|
||||
|
||||
[More specific guidance...]
|
||||
```
|
||||
|
||||
```yaml
|
||||
# Backend Specialist
|
||||
---
|
||||
name: backend-specialist
|
||||
description: Node.js/Express API development, database design, and server architecture. Use PROACTIVELY for backend work.
|
||||
tools: Read, Write, Edit, Grep, Bash(npm:*), Bash(docker:*)
|
||||
---
|
||||
|
||||
You are a Node.js backend expert.
|
||||
|
||||
[Similar detailed structure...]
|
||||
```
|
||||
|
||||
### Pattern 3: Security-First Architecture
|
||||
|
||||
```yaml
|
||||
# Security Analyzer (Read-Only)
|
||||
---
|
||||
name: security-analyzer
|
||||
description: Analyze code for security vulnerabilities before allowing modifications. MUST BE USED before code changes in sensitive areas.
|
||||
tools: Read, Grep, Glob, Bash(git diff:*)
|
||||
---
|
||||
|
||||
You are a security analyst. Review code for vulnerabilities BEFORE changes are made.
|
||||
|
||||
## Security Checks
|
||||
1. Authentication/Authorization
|
||||
2. Input validation
|
||||
3. SQL injection
|
||||
4. XSS vulnerabilities
|
||||
5. CSRF protection
|
||||
6. Secrets management
|
||||
|
||||
## Output
|
||||
Return ONLY:
|
||||
- Security score (1-10)
|
||||
- Critical issues (block changes)
|
||||
- Warnings (allow with caution)
|
||||
```
|
||||
|
||||
### Pattern 4: Test-Driven Subagent
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: test-first-developer
|
||||
description: Write comprehensive tests before implementing features. Use PROACTIVELY for TDD workflows.
|
||||
tools: Read, Write, Bash(npm test:*)
|
||||
model: sonnet
|
||||
---
|
||||
|
||||
You are a TDD expert. For every feature request:
|
||||
|
||||
1. **Analyze Requirements**
|
||||
- Extract testable behaviors
|
||||
- Identify edge cases
|
||||
|
||||
2. **Write Tests FIRST**
|
||||
- Unit tests for logic
|
||||
- Integration tests for workflows
|
||||
- Edge case coverage
|
||||
|
||||
3. **Run Tests** (they should fail)
|
||||
```bash
|
||||
npm test
|
||||
```
|
||||
|
||||
4. **Implement ONLY Enough** to pass tests
|
||||
|
||||
5. **Refactor** while keeping tests green
|
||||
|
||||
## Test Structure
|
||||
```javascript
|
||||
describe('Feature', () => {
|
||||
it('handles happy path', () => {})
|
||||
it('handles edge case 1', () => {})
|
||||
it('throws on invalid input', () => {})
|
||||
})
|
||||
```
|
||||
|
||||
Never implement before tests exist.
|
||||
```
|
||||
|
||||
## Testing & Validation
|
||||
|
||||
### 1. Test Trigger Accuracy
|
||||
|
||||
Create test scenarios:
|
||||
|
||||
```markdown
|
||||
# Test Plan for "api-developer" subagent
|
||||
|
||||
## Positive Tests (Should Activate)
|
||||
1. "Create a REST endpoint for user authentication"
|
||||
- Expected: Activates
|
||||
- Actual: ___
|
||||
|
||||
2. "Add GraphQL mutation for updating profile"
|
||||
- Expected: Activates
|
||||
- Actual: ___
|
||||
|
||||
## Negative Tests (Should NOT Activate)
|
||||
1. "Write unit tests for the API"
|
||||
- Expected: Does not activate (testing concern)
|
||||
- Actual: ___
|
||||
|
||||
2. "Review API security"
|
||||
- Expected: Does not activate (security concern)
|
||||
- Actual: ___
|
||||
|
||||
## Results
|
||||
- Precision: X% (correct activations / total activations)
|
||||
- Recall: Y% (correct activations / should activate)
|
||||
```
|
||||
|
||||
### 2. Test Output Quality
|
||||
|
||||
```markdown
|
||||
# Quality Checklist
|
||||
|
||||
Task: "Review auth.js for security issues"
|
||||
|
||||
Subagent Output Should Include:
|
||||
- [ ] Specific vulnerabilities identified
|
||||
- [ ] File:line locations
|
||||
- [ ] Severity ratings
|
||||
- [ ] Concrete fix suggestions
|
||||
- [ ] Code examples for fixes
|
||||
|
||||
Should NOT Include:
|
||||
- [ ] Generic advice
|
||||
- [ ] Full file listings
|
||||
- [ ] Unrelated issues
|
||||
- [ ] Style nitpicks
|
||||
```
|
||||
|
||||
### 3. Test Tool Access
|
||||
|
||||
```bash
|
||||
# Verify tool restrictions work
|
||||
# Give subagent a task requiring forbidden tool
|
||||
|
||||
# Example: Read-only subagent shouldn't be able to edit
|
||||
# Test by asking it to "fix the security issue"
|
||||
# Should fail or request permission
|
||||
```
|
||||
|
||||
### 4. Performance Testing
|
||||
|
||||
```markdown
|
||||
# Performance Metrics
|
||||
|
||||
Task: "Generate API documentation"
|
||||
|
||||
Metrics:
|
||||
- Time to complete: ___
|
||||
- Tokens used: ___
|
||||
- Quality score (1-10): ___
|
||||
- Required follow-ups: ___
|
||||
|
||||
Optimization targets:
|
||||
- < 30 seconds for docs
|
||||
- < 5000 tokens
|
||||
- Quality >= 8
|
||||
- 0 follow-ups needed
|
||||
```
|
||||
|
||||
## Refinement Workflow
|
||||
|
||||
### Step 1: Baseline Performance
|
||||
|
||||
```bash
|
||||
# Document current behavior
|
||||
echo "Task: [Specific task]
|
||||
Expected: [What should happen]
|
||||
Actual: [What actually happens]
|
||||
Issues: [Problems observed]
|
||||
" > .claude/agents/refinement-notes.md
|
||||
```
|
||||
|
||||
### Step 2: Identify Root Cause
|
||||
|
||||
Common causes:
|
||||
- Description too vague → Won't activate
|
||||
- Prompt lacks specificity → Poor output
|
||||
- Wrong tools → Can't complete task
|
||||
- Wrong model → Too slow/simple
|
||||
- Output not filtered → Context pollution
|
||||
|
||||
### Step 3: Make Targeted Changes
|
||||
|
||||
**Only change ONE thing at a time**:
|
||||
1. Update description OR
|
||||
2. Refine prompt OR
|
||||
3. Adjust tools OR
|
||||
4. Change model
|
||||
|
||||
### Step 4: Test Changes
|
||||
|
||||
```bash
|
||||
# Test with same scenarios
|
||||
# Compare before/after results
|
||||
# Document improvements
|
||||
```
|
||||
|
||||
### Step 5: Iterate
|
||||
|
||||
Repeat until subagent meets quality bar.
|
||||
|
||||
## Best Practices Summary
|
||||
|
||||
### Description Writing
|
||||
|
||||
```yaml
|
||||
# Template
|
||||
description: [Action verb] [domain/task] [including specific capabilities]. Use [trigger condition]. PROACTIVELY when [scenario].
|
||||
```
|
||||
|
||||
**Examples**:
|
||||
```yaml
|
||||
description: Analyze Python code for performance bottlenecks including O(n²) algorithms, memory leaks, and inefficient database queries. Use PROACTIVELY when optimizing Python applications.
|
||||
|
||||
description: Generate comprehensive API documentation from code including endpoints, parameters, responses, and examples. Use when documenting REST or GraphQL APIs.
|
||||
|
||||
description: Review frontend code for accessibility issues following WCAG 2.1 AA standards. MUST BE USED for all UI component changes.
|
||||
```
|
||||
|
||||
### System Prompt Structure
|
||||
|
||||
```markdown
|
||||
# Role Definition
|
||||
You are a [role] specializing in [domain].
|
||||
|
||||
## Responsibilities
|
||||
1. [Primary responsibility]
|
||||
2. [Secondary responsibility]
|
||||
3. [Additional responsibilities]
|
||||
|
||||
## Process
|
||||
1. [Step 1]
|
||||
2. [Step 2]
|
||||
3. [Step 3]
|
||||
|
||||
## Output Format
|
||||
[Specific structure required]
|
||||
|
||||
## Examples
|
||||
|
||||
### Good Example
|
||||
[Show what good looks like]
|
||||
|
||||
### Bad Example
|
||||
[Show what to avoid]
|
||||
|
||||
## Constraints
|
||||
- [Important limitation]
|
||||
- [Another constraint]
|
||||
```
|
||||
|
||||
### Tool Selection Strategy
|
||||
|
||||
```markdown
|
||||
Decision Tree:
|
||||
|
||||
1. Does it need to modify files?
|
||||
No → Read, Grep, Glob only
|
||||
Yes → Continue
|
||||
|
||||
2. Does it need to run tests/builds?
|
||||
No → Read, Write, Edit only
|
||||
Yes → Add Bash(test:*), Bash(build:*)
|
||||
|
||||
3. Does it need external data?
|
||||
Yes → Add WebFetch, WebSearch
|
||||
No → Continue
|
||||
|
||||
4. Does it need git operations?
|
||||
Yes → Add Bash(git:*) with specific commands
|
||||
No → Done
|
||||
```
|
||||
|
||||
### Model Selection
|
||||
|
||||
```markdown
|
||||
Choose model based on:
|
||||
|
||||
1. Task complexity
|
||||
- Simple transforms → haiku
|
||||
- Standard coding → sonnet
|
||||
- Complex reasoning → opus
|
||||
|
||||
2. Cost sensitivity
|
||||
- High volume, simple → haiku
|
||||
- Balanced → sonnet
|
||||
- Quality critical → opus
|
||||
|
||||
3. Speed requirements
|
||||
- Real-time needed → haiku
|
||||
- Standard → sonnet
|
||||
- Can wait → opus
|
||||
|
||||
Default: sonnet (best balance)
|
||||
```
|
||||
|
||||
## Debugging Checklist
|
||||
|
||||
When subagent doesn't work as expected:
|
||||
|
||||
```markdown
|
||||
- [ ] Description is specific and includes trigger words
|
||||
- [ ] Description includes "PROACTIVELY" or "MUST BE USED" if needed
|
||||
- [ ] System prompt defines role clearly
|
||||
- [ ] System prompt includes process/steps
|
||||
- [ ] System prompt specifies output format
|
||||
- [ ] System prompt has examples
|
||||
- [ ] Tools match required capabilities
|
||||
- [ ] Tools follow least-privilege principle
|
||||
- [ ] Model appropriate for task complexity
|
||||
- [ ] File location correct (.claude/agents/)
|
||||
- [ ] YAML frontmatter valid
|
||||
- [ ] Name uses kebab-case
|
||||
- [ ] Tested with positive/negative scenarios
|
||||
```
|
||||
|
||||
## Common Anti-Patterns
|
||||
|
||||
### ❌ Anti-Pattern 1: Generic Description
|
||||
|
||||
```yaml
|
||||
---
|
||||
description: Helps with coding
|
||||
---
|
||||
```
|
||||
|
||||
**Why Bad**: Won't trigger reliably
|
||||
|
||||
**Fix**: Be specific about domain and triggers
|
||||
|
||||
### ❌ Anti-Pattern 2: No Process Defined
|
||||
|
||||
```markdown
|
||||
You are a code reviewer. Review code.
|
||||
```
|
||||
|
||||
**Why Bad**: Inconsistent results
|
||||
|
||||
**Fix**: Define step-by-step process
|
||||
|
||||
### ❌ Anti-Pattern 3: All Tools Granted
|
||||
|
||||
```yaml
|
||||
---
|
||||
# Omitting tools when only reads needed
|
||||
---
|
||||
```
|
||||
|
||||
**Why Bad**: Unnecessary permissions, security risk
|
||||
|
||||
**Fix**: Whitelist minimum required tools
|
||||
|
||||
### ❌ Anti-Pattern 4: Verbose System Prompt
|
||||
|
||||
```markdown
|
||||
You are an expert developer with 20 years of experience who has worked on numerous projects across different industries... [3000 words]
|
||||
```
|
||||
|
||||
**Why Bad**: Token waste, slower activation
|
||||
|
||||
**Fix**: Be concise, focus on process and format
|
||||
|
||||
### ❌ Anti-Pattern 5: No Output Structure
|
||||
|
||||
```markdown
|
||||
Review the code and tell me about issues.
|
||||
```
|
||||
|
||||
**Why Bad**: Inconsistent format, hard to parse
|
||||
|
||||
**Fix**: Define exact output format
|
||||
|
||||
## Advanced Techniques
|
||||
|
||||
### Technique 1: Chained Subagents
|
||||
|
||||
Use hooks or explicit handoffs:
|
||||
|
||||
```json
|
||||
// .claude/settings.json
|
||||
{
|
||||
"hooks": {
|
||||
"PostToolUse": [
|
||||
{
|
||||
"matcher": "Write",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "echo 'Please use security-analyzer subagent to review this file' && exit 0"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Technique 2: Context Injection
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: context-aware-developer
|
||||
---
|
||||
|
||||
Before starting any task:
|
||||
1. Read PROJECT_CONTEXT.md
|
||||
2. Review ARCHITECTURE.md
|
||||
3. Check CODING_STANDARDS.md
|
||||
|
||||
Then proceed with development following documented patterns.
|
||||
```
|
||||
|
||||
### Technique 3: Quality Gates
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: pr-ready-checker
|
||||
description: Verify code is PR-ready before submitting. MUST BE USED before creating pull requests.
|
||||
tools: Read, Grep, Bash(npm test:*), Bash(npm run lint:*)
|
||||
---
|
||||
|
||||
Verify PR readiness:
|
||||
|
||||
1. **Tests Pass**
|
||||
```bash
|
||||
npm test
|
||||
```
|
||||
All tests must pass.
|
||||
|
||||
2. **Linting Clean**
|
||||
```bash
|
||||
npm run lint
|
||||
```
|
||||
Zero warnings or errors.
|
||||
|
||||
3. **Coverage Adequate**
|
||||
- New code > 80% covered
|
||||
- Overall coverage not decreased
|
||||
|
||||
4. **Documentation Updated**
|
||||
- README if public API changed
|
||||
- Inline comments for complex logic
|
||||
|
||||
5. **No Debug Code**
|
||||
- No console.log
|
||||
- No debugger statements
|
||||
- No commented code
|
||||
|
||||
Return: "PR Ready: Yes/No" + blockers list
|
||||
```
|
||||
|
||||
### Technique 4: Iterative Refinement Prompt
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: iterative-implementer
|
||||
---
|
||||
|
||||
When implementation fails or produces errors:
|
||||
|
||||
1. **Analyze Failure**
|
||||
- What was the error?
|
||||
- Why did it happen?
|
||||
- What was I trying to achieve?
|
||||
|
||||
2. **Adjust Approach**
|
||||
- How should I do it differently?
|
||||
- What did I learn?
|
||||
|
||||
3. **Re-implement**
|
||||
- Apply new approach
|
||||
- Test immediately
|
||||
|
||||
4. **Verify**
|
||||
- Did it work?
|
||||
- If not, repeat from step 1
|
||||
|
||||
Never give up after one failure. Iterate until success.
|
||||
```
|
||||
|
||||
## Migration: Ad-Hoc to Subagent
|
||||
|
||||
### When to Migrate
|
||||
|
||||
Migrate repetitive prompts to subagents when:
|
||||
- You've used the same prompt 3+ times
|
||||
- Prompt has clear pattern/structure
|
||||
- Task benefits from isolation
|
||||
- Multiple team members need it
|
||||
|
||||
### Migration Process
|
||||
|
||||
**Step 1: Extract Pattern**
|
||||
|
||||
```markdown
|
||||
# Repeated prompts you've used:
|
||||
|
||||
1. "Review auth.js for security issues including SQL injection, XSS, and auth flaws"
|
||||
2. "Check payment.js for security vulnerabilities like injection and secrets"
|
||||
3. "Analyze api.js for security problems including validation and auth"
|
||||
|
||||
# Common pattern:
|
||||
Review [file] for security [vulnerability types]
|
||||
```
|
||||
|
||||
**Step 2: Generalize**
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: security-reviewer
|
||||
description: Review code for security vulnerabilities including SQL injection, XSS, authentication flaws, and hardcoded secrets. Use PROACTIVELY for security reviews.
|
||||
tools: Read, Grep, Glob
|
||||
---
|
||||
|
||||
Review provided files for security vulnerabilities:
|
||||
|
||||
[Extract common structure from your prompts]
|
||||
```
|
||||
|
||||
**Step 3: Test & Refine**
|
||||
|
||||
Test with previous use cases, refine until quality matches or exceeds manual prompts.
|
||||
|
||||
## Resources
|
||||
|
||||
- [Official Subagents Documentation](https://docs.claude.com/en/docs/claude-code/sub-agents)
|
||||
- [Claude Code Plugins](../claude-code-plugins/SKILL.md) - For packaging subagents
|
||||
- [Slash Commands](../claude-code-slash-commands/SKILL.md) - Alternative for simpler patterns
|
||||
- [Hooks](../claude-code-hooks/SKILL.md) - For automating subagent workflows
|
||||
|
||||
---
|
||||
|
||||
**Remember**: Start with `/agents` command for creation. Use this skill for refinement. Iterate based on real usage. Test thoroughly. Document learnings.
|
||||
Reference in New Issue
Block a user