movq/claude-plugins
2
0
Fork 0
Code Issues Pull Requests Actions Releases Activity

Refinement for context size

Browse Source
This commit is contained in:
movq
2025-10-28 12:48:17 -05:00
parent 35d2069861
commit ddea00cb40
11 changed files with 1539 additions and 1196 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
claude-code/.claude-plugin/plugin.json
View File

@@ -1,7 +1,7 @@
{ {
"name": "claude-code", "name": "claude-code",
"description": "Comprehensive skills for mastering Claude Code features: plugins, skills, slash commands, hooks, subagents, and memory management", "description": "Comprehensive skills for mastering Claude Code features: plugins, skills, slash commands, hooks, subagents, and memory management",
"version": "1.1.0", "version": "1.1.1",
"author": { "author": {
"name": "Claude Skills Contributors" "name": "Claude Skills Contributors"
}, },

347
claude-code/skills/claude-commands/SKILL.md
View File

@@ -1,6 +1,6 @@
--- ---
name: Slash Command Creator name: Slash Command Creator
description: Create custom slash commands for Claude Code with argument handling, bash execution, and file references. Use PROACTIVELY when building reusable prompts, automating workflows, creating project-specific commands, or when users mention "create a command", "reusable prompt", "/something", or "slash command". NOT for complex multi-file operations. description: Create custom slash commands for Claude Code with argument handling, bash execution, and file references. Use PROACTIVELY when users repeat similar prompts 3+ times, mention "create a command", "reusable prompt", "/something", or "slash command". Triggers BEFORE user asks explicitly to suggest command creation for repeated workflows. NOT for complex multi-file operations.
--- ---
# Slash Command Development # Slash Command Development
@@ -10,21 +10,20 @@ description: Create custom slash commands for Claude Code with argument handling
Use this skill when: Use this skill when:
- Creating custom slash commands for Claude Code - Creating custom slash commands for Claude Code
- Building reusable prompt templates - Building reusable prompt templates
- Automating repetitive tasks with commands - User repeats similar prompts 3+ times
- Setting up project-specific workflows - Automating repetitive tasks
- Converting manual prompts to slash commands - Converting manual workflows to commands
Do NOT use this skill for: Do NOT use this skill for:
- Creating full plugins (use claude-plugin skill) - Creating full plugins (use claude-plugins skill)
- Setting up hooks (use claude-hooks skill) - Setting up hooks (use claude-hooks skill)
- Complex multi-file operations (use subagents) - Complex multi-file operations (use subagents)
## Quick Start ## Quick Start
### Create Command File Create a command file in `.claude/commands/`:
```bash ```bash
# Project-specific (team shared)
mkdir -p .claude/commands mkdir -p .claude/commands
cat > .claude/commands/review.md << 'EOF' cat > .claude/commands/review.md << 'EOF'
--- ---
@@ -45,12 +44,12 @@ EOF
## Command Locations ## Command Locations
| Location | Scope | Version Control | Use For | | Location | Scope | Use For |
|----------|-------|-----------------|---------| |----------|-------|---------|
| `.claude/commands/` | Project (team) | In git | Team workflows, standards | | `.claude/commands/` | Project (team) | Team workflows, standards |
| `~/.claude/commands/` | User (personal) | Not in git | Personal productivity | | `~/.claude/commands/` | User (personal) | Personal productivity |
## Command Syntax ## Essential Syntax
### Basic Structure ### Basic Structure
@@ -64,313 +63,143 @@ Prompt content here
$ARGUMENTS $ARGUMENTS
``` ```
### Filename = Command Name **File name = Command name**: `review.md` → `/review`
```bash ### Frontmatter Options
# File: .claude/commands/test.md
# Command: /test
# File: .claude/commands/commit-push.md
# Command: /commit-push
```
## Frontmatter Options
```yaml ```yaml
--- ---
description: Generate unit tests for a function # Shows in /help description: Generate unit tests for a function # Required
argument-hint: <file-path> <function-name> # Autocomplete hint argument-hint: <file-path> <function-name> # Autocomplete
allowed-tools: Read(*), Bash(git:*) # Tool permissions allowed-tools: Read(*), Bash(git:*) # Permissions
model: claude-haiku-4 # Override default model model: claude-haiku-4 # Model override
disable-model-invocation: true # Prevent auto-invocation
--- ---
``` ```
## Argument Handling ### Arguments
### $ARGUMENTS - All Arguments
```markdown ```markdown
--- $ARGUMENTS # All arguments
description: Explain multiple files $1, $2, $3 # Positional arguments
--- @$1 or @file.js # Load file content
Explain these files: $ARGUMENTS
``` ```
**Usage**: `/explain @src/a.js @src/b.js @src/c.js` **Examples**:
```bash
### Positional ($1, $2, $3...) /compare REST GraphQL # $1="REST", $2="GraphQL"
/review @src/main.js # Loads main.js content
```markdown /explain @src/a.js @src/b.js # Loads both files
---
description: Compare two approaches
argument-hint: <approach1> <approach2>
---
Compare approach "$1" versus "$2" and recommend which is better.
``` ```
**Usage**: `/compare REST GraphQL` ### Bash Execution
### File References with @ Prefix with `!` to execute before processing:
```markdown ```markdown
--- ---
description: Review a file description: Git workflow helper
--- allowed-tools: Bash(git:*)
Review @$1 for code quality issues.
```
**Usage**: `/review src/auth.js`
Claude reads `src/auth.js` automatically.
## Bash Execution with !
Prefix commands with `!` to execute before processing:
```markdown
---
description: Show git status and suggest next steps
allowed-tools: Bash(git status:*), Bash(git diff:*)
--- ---
!git status !git status
!git diff --stat !git diff --stat
Based on the current git state, suggest what I should do next. Based on above, suggest next steps.
``` ```
**Important**: Must include `allowed-tools` with Bash specifications. **Important**: Must include `allowed-tools` with Bash patterns.
## Complete Examples ## Quick Examples
### Security Review
### Simple Review Command
```markdown ```markdown
--- ---
description: Comprehensive security review of code files description: Review code quality
allowed-tools: Read(*), Grep(*)
argument-hint: <files...>
--- ---
Perform a security audit on: $ARGUMENTS Review @$1 for:
1. Logic errors
2. Code style
3. Performance issues
Check for: Provide specific fixes.
1. SQL injection vulnerabilities
2. XSS vulnerabilities
3. Authentication/authorization issues
4. Hardcoded secrets or credentials
5. Unsafe deserialization
6. Path traversal vulnerabilities
For each issue found:
- Severity level (Critical/High/Medium/Low)
- Location (file:line)
- Explanation of the vulnerability
- Recommended fix with code example
``` ```
### Commit + Push ### Multi-Step Workflow
```markdown ```markdown
--- ---
description: Review changes, commit, and push to remote description: Commit and push changes
allowed-tools: Bash(git:*) allowed-tools: Bash(git:*)
--- ---
!git status !git status
!git diff !git diff
Review the changes above and: 1. Review changes
1. Create an appropriate commit message 2. Create commit message
2. Commit the changes 3. Commit and push
3. Push to remote
Ask for confirmation before pushing. Ask confirmation before push.
```
### 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.
``` ```
For more examples, see [examples.md](examples.md) For more examples, see [examples.md](examples.md)
## Command Patterns
### Review Pattern
```markdown
---
description: Review X for Y
---
Review $ARGUMENTS for [specific criteria]
Include:
- [Aspect 1]
- [Aspect 2]
```
### 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]
```
## Testing Commands
```bash
# See all available commands
/help
# Test with different arguments
/mycommand arg1
/mycommand @file.js
/mycommand @file1.js @file2.js
```
## Best Practices ## Best Practices
### 1. Clear Descriptions ### ✓ Do
- Clear descriptions under 100 chars
- Specific tool permissions
- Meaningful command names (kebab-case)
- Self-documenting prompts
- Include argument hints
```yaml ### ✗ Avoid
# Good - Vague descriptions ("Helper", "Utils")
description: Generate unit tests for a specific function - Wildcard permissions (`allowed-tools: *`)
- Short cryptic names (`/gt`, `/rs`)
- Hardcoded secrets or paths
- Missing frontmatter
# Bad ## Testing
description: Testing
```
### 2. Explicit Arguments
```yaml
# Good
argument-hint: <file-path> <function-name>
# Bad (no 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 ```bash
# Good # List all commands
/generate-tests /help
/review-security
/commit-and-push
# Bad # Test with arguments
/gt /mycommand arg1
/rs /mycommand @file.js
/cap
``` ```
### 5. Self-Documenting Content ## Common Issues
```markdown
Review code for:
1. Logic errors
2. Style issues
3. Performance problems
$ARGUMENTS
```
## Troubleshooting
| Problem | Solution | | Problem | Solution |
|---------|----------| |---------|----------|
| Command not found | Check file is in `.claude/commands/`, ends with `.md` | | Command not found | Check `.claude/commands/`, restart Claude |
| Arguments not working | Use `$ARGUMENTS`, `$1`, `$2` (not `${ARGUMENTS}`) | | Arguments not working | Use `$ARGUMENTS`, not `${ARGUMENTS}` |
| Bash not executing | Add `allowed-tools` frontmatter with `Bash()` pattern | | Bash not executing | Add `allowed-tools: Bash(...)` |
| File references not loading | Verify file path, use `@` prefix | | File not loading | Use `@` prefix, verify path |
## Security Considerations For detailed troubleshooting, see [troubleshooting.md](troubleshooting.md)
### Limit Tool Access ## Security
**Limit permissions**:
```yaml ```yaml
# Specific commands only # ✓ Specific
allowed-tools: Bash(git status:*), Bash(git log:*) allowed-tools: Bash(git status:*), Bash(git diff:*)
# Never use unless required # ✗ Too broad
allowed-tools: * allowed-tools: *
``` ```
### No Hardcoded Secrets **No secrets**:
```markdown ```markdown
# Bad - hardcoded API key # ✗ Bad
!curl -H "API-Key: sk-abc123..." api.example.com !curl -H "API-Key: sk-abc123..."
# Good - use environment variables # ✓ Good
!curl -H "API-Key: $MY_API_KEY" api.example.com !curl -H "API-Key: $MY_API_KEY"
```
### Validate User Input
```markdown
# Risky - no validation
!rm -rf $1
# Better - validate first
Confirm you want to delete: $1
(Then use interactive confirmation)
``` ```
## Command Template ## Command Template
@@ -387,13 +216,17 @@ allowed-tools: [Specific patterns if needed]
$ARGUMENTS $ARGUMENTS
``` ```
## Resources ## Additional Resources
- [Complete Examples](examples.md) - Working command configurations **Need more?**
- [Advanced Patterns](patterns.md) - Complex workflows - [Complete Examples](examples.md) - 10+ working commands
- [Official Documentation](https://docs.claude.com/en/docs/claude-code/slash-commands) - [Command Patterns](patterns.md) - Reusable templates
- [Plugin Development](../claude-plugin/SKILL.md) - Packaging commands - [Troubleshooting Guide](troubleshooting.md) - Problem solutions
- [Official Docs](https://docs.claude.com/en/docs/claude-code/slash-commands)
- [Plugin Development](../claude-plugins/SKILL.md) - Package commands
💡 **Tip**: Start with manual prompts, identify repetition, then create commands. Commands are for workflows you use 3+ times.
--- ---
**Remember**: Slash commands are for reusable prompts. Start with manual prompts, identify patterns you repeat, then codify them as commands. **Remember**: Slash commands = reusable prompts. Keep them simple, specific, and secure.

216
claude-code/skills/claude-commands/examples.md Normal file
View File

@@ -0,0 +1,216 @@
# Command Examples
Complete, working slash command examples.
## Security Review
```markdown
---
description: Comprehensive security review of code files
allowed-tools: Read(*), 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
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`
## Commit + Push
```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`
## 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**: `/generate-tests src/utils.js calculateTotal`
## Documentation Generator
```markdown
---
description: Generate JSDoc/TSDoc comments for code
---
Generate comprehensive documentation for: $ARGUMENTS
Include:
- Function/class description
- Parameter types and descriptions
- Return value description
- Usage examples
- Edge cases and error conditions
```
**Usage**: `/document @src/api/users.js`
## API Endpoint Creator
```markdown
---
description: Create REST API endpoint with tests
argument-hint: <method> <path> <description>
---
Create a $1 endpoint at "$2" that $3
Include:
1. Route handler with validation
2. Controller logic
3. Unit tests
4. Integration tests
5. API documentation
```
**Usage**: `/api POST /users/login "authenticates a user"`
## Refactor Command
```markdown
---
description: Refactor code for better maintainability
---
Refactor $ARGUMENTS
Focus on:
- Extract repeated code into functions
- Improve naming clarity
- Reduce complexity
- Add error handling
- Maintain existing behavior
Show before/after comparison.
```
**Usage**: `/refactor @src/legacy.js`
## Performance Analyzer
```markdown
---
description: Analyze code for performance bottlenecks
allowed-tools: Read(*), Grep(*)
---
Analyze $ARGUMENTS for performance issues
Check for:
1. O(n²) or worse algorithms
2. Unnecessary re-renders (React)
3. Memory leaks
4. Inefficient database queries
5. Large bundle sizes
Provide specific optimization suggestions with code examples.
```
**Usage**: `/performance @src/components/DataTable.tsx`
## Dependency Audit
```markdown
---
description: Audit project dependencies
allowed-tools: Bash(npm:*), Read(package.json)
---
!npm outdated
!npm audit
Review dependencies and:
1. Identify security vulnerabilities
2. Find outdated packages
3. Detect unused dependencies
4. Recommend updates or replacements
```
**Usage**: `/audit-deps`
## Code Cleanup
```markdown
---
description: Clean up code formatting and style
allowed-tools: Read(*), Write(*), Bash(npx prettier:*)
---
Clean up $ARGUMENTS
1. Remove unused imports
2. Fix formatting issues
3. Resolve linter warnings
4. Remove console.logs
5. Add missing type annotations
```
**Usage**: `/cleanup @src/**/*.ts`
## Migration Helper
```markdown
---
description: Help migrate code to new API/library version
argument-hint: <files> <from-version> <to-version>
---
Migrate $1 from version $2 to $3
1. Identify breaking changes
2. Update deprecated APIs
3. Fix type errors
4. Update tests
5. Verify functionality
```
**Usage**: `/migrate @src/app.js 3.0 4.0`

93
claude-code/skills/claude-commands/patterns.md Normal file
View File

@@ -0,0 +1,93 @@
# Command Patterns
Common patterns for creating effective slash commands.
## Review Pattern
```markdown
---
description: Review X for Y
---
Review $ARGUMENTS for [specific criteria]
Include:
- [Aspect 1]
- [Aspect 2]
```
**Use for**: Code review, security audits, style checks
## Generate Pattern
```markdown
---
description: Generate X from Y
---
Generate [output type] for: $ARGUMENTS
Requirements:
- [Requirement 1]
- [Requirement 2]
```
**Use for**: Test generation, documentation, boilerplate code
## 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]
```
**Use for**: Technology comparisons, approach evaluation
## Workflow Pattern
```markdown
---
description: Execute multi-step workflow
allowed-tools: Bash(git:*), Read(*), Write(*)
---
!git status
!git diff
1. [Step 1]
2. [Step 2]
3. [Step 3]
Ask for confirmation before final step.
```
**Use for**: Git workflows, build processes, deployment
## Analysis Pattern
```markdown
---
description: Analyze X and provide insights
---
Analyze $ARGUMENTS
Focus on:
1. [Key metric 1]
2. [Key metric 2]
3. [Key metric 3]
Provide actionable recommendations.
```
**Use for**: Performance analysis, complexity metrics, dependency review

235
claude-code/skills/claude-commands/troubleshooting.md Normal file
View File

@@ -0,0 +1,235 @@
# Troubleshooting Slash Commands
Common problems and solutions.
## Command Not Found
**Symptoms**: `/mycommand` shows "Command not found"
**Solutions**:
1. Verify file exists in `.claude/commands/` directory
2. Check filename ends with `.md` extension
3. Ensure filename matches command name (dash-separated)
4. Restart Claude Code to reload commands
**Example**:
```bash
# Wrong location
./commands/review.md
# Correct location
./.claude/commands/review.md
# Usage
/review @file.js
```
## Arguments Not Working
**Symptoms**: Variables like `$ARGUMENTS` appear literally in output
**Solutions**:
1. Use correct syntax: `$ARGUMENTS`, `$1`, `$2` (not `${ARGUMENTS}`)
2. Don't escape dollar signs in command files
3. Verify arguments are passed when invoking command
**Example**:
```markdown
# ❌ Wrong
Review these files: ${ARGUMENTS}
# ✓ Correct
Review these files: $ARGUMENTS
```
## Bash Commands Not Executing
**Symptoms**: `!git status` appears as text instead of executing
**Solutions**:
1. Add `allowed-tools` frontmatter with Bash specification
2. Use specific patterns, not wildcard `*` unless necessary
3. Ensure bash command is valid and available
**Example**:
```markdown
---
description: Git workflow
allowed-tools: Bash(git status:*), Bash(git diff:*)
---
!git status
!git diff --stat
```
## File References Not Loading
**Symptoms**: `@file.js` doesn't load file content
**Solutions**:
1. Use `@` prefix before file path
2. Verify file path is correct (relative to project root)
3. Check file exists and is readable
4. Combine with positional arguments: `@$1`
**Example**:
```markdown
# Direct reference
Review @src/main.js for issues
# With argument
Review @$1 for issues
# Usage: /review src/main.js
```
## Permission Errors
**Symptoms**: "Tool not allowed" or permission denied errors
**Solutions**:
1. Add required tools to `allowed-tools` frontmatter
2. Use specific patterns instead of broad permissions
3. Separate file paths from command patterns
**Example**:
```yaml
# ✓ Good - specific permissions
allowed-tools: Read(src/**), Bash(git status:*), Bash(git diff:*)
# ⚠️ Risky - too permissive
allowed-tools: *
```
## Command Timeout
**Symptoms**: Command hangs or times out
**Solutions**:
1. Avoid long-running processes in `!` commands
2. Use background processes if needed
3. Break into smaller commands
4. Consider using subagents for complex workflows
## Model Not Respecting Instructions
**Symptoms**: Claude doesn't follow command template
**Solutions**:
1. Use clear, imperative language
2. Number steps explicitly
3. Add constraints section
4. Use `model: claude-sonnet-4` for complex commands
**Example**:
```markdown
Review $ARGUMENTS
YOU MUST:
1. Check for X
2. Verify Y
3. Report Z
DO NOT:
- Skip any files
- Suggest changes without explanation
```
## Description Not Showing in /help
**Symptoms**: Command appears but no description
**Solutions**:
1. Verify frontmatter has `description` field
2. Check YAML syntax (no tabs, proper spacing)
3. Keep description under 100 characters for /help display
**Example**:
```yaml
---
description: Review code for security issues
---
```
## Argument Hints Not Working
**Symptoms**: Autocomplete doesn't show expected arguments
**Solutions**:
1. Add `argument-hint` to frontmatter
2. Use standard format: `<arg1> <arg2>`
3. Use descriptive names
**Example**:
```yaml
---
description: Generate tests
argument-hint: <file-path> <function-name>
---
```
## Commands Conflict with Built-ins
**Symptoms**: Custom command doesn't run, built-in does instead
**Solutions**:
1. Use different command name
2. Avoid names like `/help`, `/clear`, `/init`
3. Use descriptive, unique names
## Debugging Tips
### Test Basic Structure
```bash
# Create minimal test command
cat > .claude/commands/test.md << 'EOF'
---
description: Test command
---
Echo test: $ARGUMENTS
EOF
# Try it
/test hello world
# Should output: Echo test: hello world
```
### Test Bash Execution
```markdown
---
description: Test bash
allowed-tools: Bash(echo:*)
---
!echo "Bash works"
Result above should show "Bash works"
```
### Test File Loading
```markdown
---
description: Test file loading
---
Content from @package.json
Above should show package.json content
```
### Verify Command Registration
```bash
# List all commands
/help
# Look for your command in the list
```
## Getting Help
If problems persist:
1. Check [Official Documentation](https://docs.claude.com/en/docs/claude-code/slash-commands)
2. Review command file syntax carefully
3. Test with minimal example first
4. Verify Claude Code version supports features

294
claude-code/skills/claude-hooks/SKILL.md
View File

@@ -1,6 +1,6 @@
--- ---
name: Claude Code Hooks name: Claude Code Hooks
description: Configure event-driven hooks for Claude Code to automate workflows, validate code, inject context, and control tool execution. Use PROACTIVELY when setting up automation, enforcing standards, integrating external tools, or when users mention "automatically run", "on save", "event-driven", "workflow automation", or "enforce rules". NOT for one-time scripts. description: Configure event-driven hooks for Claude Code to automate workflows, validate code, inject context, and control tool execution. Use PROACTIVELY when users want automation that runs automatically (not manually), mention "automatically run", "on save", "after editing", "event-driven", "workflow automation", or "enforce rules". NOT for one-time scripts.
--- ---
# Claude Code Hooks # Claude Code Hooks
@@ -8,74 +8,65 @@ description: Configure event-driven hooks for Claude Code to automate workflows,
## When to Use This Skill ## When to Use This Skill
Use this skill when: Use this skill when:
- Automating workflows with event-driven triggers - Automating workflows with event triggers
- Enforcing code standards or security policies - Enforcing code standards or policies
- Validating changes before/after tool execution - Validating changes before/after tool execution
- Injecting context at session start - Injecting context at session start
- Logging or monitoring tool usage - Logging or monitoring tool usage
- Setting up team-wide automation - Setting up team-wide automation
Do NOT use this skill for: Do NOT use this skill for:
- Creating slash commands (use claude-command-expert skill) - Creating slash commands (use claude-commands skill)
- Building full plugins (use claude-plugin skill) - Building plugins (use claude-plugins skill)
- One-time scripts (just run them directly) - One-time scripts (run them directly)
## Quick Start ## Quick Start
### 1. Hook Configuration File ### Configuration File Locations
```bash ```bash
# Project-wide (team shared) .claude/settings.json # Project (team)
.claude/settings.json .claude/settings.local.json # Project (personal)
~/.claude/settings.json # Global (personal)
# User-specific (not shared)
.claude/settings.local.json
# Global (all projects)
~/.claude/settings.json
``` ```
### 2. Simple Example - Log File Changes ### Simple Example - Auto-Format
```json ```json
{ {
"hooks": { "hooks": {
"PostToolUse": [ "PostToolUse": [{
{ "matcher": "Write|Edit",
"matcher": "Write|Edit", "hooks": [{
"hooks": [ "type": "command",
{ "command": "npx prettier --write $TOOL_ARGS && exit 0"
"type": "command", }]
"command": "echo \"$(date): Modified $TOOL_ARGS\" >> .claude/changes.log" }]
}
]
}
]
} }
} }
``` ```
## Hook Types ## Hook Types
| Event | When It Runs | Common Use | | Event | When | Common Use |
|-------|--------------|-----------| |-------|------|-----------|
| SessionStart | Session begins | Inject project context | | SessionStart | Session begins | Inject context |
| SessionEnd | Session ends | Cleanup, backups | | SessionEnd | Session ends | Cleanup, backups |
| PreToolUse | Before tool execution | Validation, permission checks | | PreToolUse | Before tool execution | Validation, checks |
| PostToolUse | After tool completes | Formatting, linting | | PostToolUse | After tool completes | Formatting, linting |
| UserPromptSubmit | User submits prompt | Logging, analytics | | UserPromptSubmit | User submits prompt | Logging |
| Notification | Claude sends notification | Desktop alerts | | Notification | Claude sends notification | Desktop alerts |
| Stop | Agent finishes responding | Post-response processing | | Stop | Agent finishes | Post-processing |
## Core Concepts ## Core Concepts
### Matcher Patterns ### Matchers
```json ```json
// Single tool // Single tool
"matcher": "Write" "matcher": "Write"
// Multiple tools (OR) // Multiple (OR)
"matcher": "Write|Edit|Read" "matcher": "Write|Edit|Read"
// All tools // All tools
@@ -88,23 +79,18 @@ Do NOT use this skill for:
### Exit Codes ### Exit Codes
```bash ```bash
# Success - Continue exit 0 # Success - Continue
exit 0 exit 1 # Non-blocking error - Continue
exit 2 # Blocking error - Stop operation
# Blocking Error - Stop operation
exit 2
# Non-Blocking Error - Continue
exit 1
``` ```
### Environment Variables ### Environment Variables
```bash ```bash
$CLAUDE_PROJECT_DIR # Current project directory $CLAUDE_PROJECT_DIR # Current project
$TOOL_NAME # Name of the tool being used $TOOL_NAME # Tool being used
$TOOL_ARGS # Arguments passed to the tool $TOOL_ARGS # Tool arguments
$HOOK_EVENT # Event type (PreToolUse, etc.) $HOOK_EVENT # Event type
``` ```
## Common Use Cases ## Common Use Cases
@@ -114,17 +100,13 @@ $HOOK_EVENT # Event type (PreToolUse, etc.)
```json ```json
{ {
"hooks": { "hooks": {
"PostToolUse": [ "PostToolUse": [{
{ "matcher": "Write|Edit",
"matcher": "Write|Edit", "hooks": [{
"hooks": [ "type": "command",
{ "command": "cd $CLAUDE_PROJECT_DIR && npx prettier --write $TOOL_ARGS && exit 0"
"type": "command", }]
"command": "cd $CLAUDE_PROJECT_DIR && npx prettier --write $TOOL_ARGS && exit 0" }]
}
]
}
]
} }
} }
``` ```
@@ -134,18 +116,14 @@ $HOOK_EVENT # Event type (PreToolUse, etc.)
```json ```json
{ {
"hooks": { "hooks": {
"PreToolUse": [ "PreToolUse": [{
{ "matcher": "Write|Edit",
"matcher": "Write|Edit", "hooks": [{
"hooks": [ "type": "command",
{ "command": "if grep -qiE '(password|api[_-]?key|secret)' $TOOL_ARGS 2>/dev/null; then echo 'Error: Possible secret' >&2; exit 2; fi; exit 0",
"type": "command", "timeout": 30
"command": "if grep -qiE '(password|api[_-]?key|secret)' $TOOL_ARGS 2>/dev/null; then echo 'Error: Possible secret detected' >&2; exit 2; fi; exit 0", }]
"timeout": 30 }]
}
]
}
]
} }
} }
``` ```
@@ -155,23 +133,19 @@ $HOOK_EVENT # Event type (PreToolUse, etc.)
```json ```json
{ {
"hooks": { "hooks": {
"PreToolUse": [ "PreToolUse": [{
{ "matcher": "Write|Edit",
"matcher": "Write|Edit", "hooks": [{
"hooks": [ "type": "command",
{ "command": "cd $CLAUDE_PROJECT_DIR && npm test -- --silent || (echo 'Tests failed' >&2; exit 2)",
"type": "command", "timeout": 120
"command": "cd $CLAUDE_PROJECT_DIR && npm test -- --silent || (echo 'Tests failed' >&2; exit 2)", }]
"timeout": 120 }]
}
]
}
]
} }
} }
``` ```
For complete examples, see [examples.md](examples.md) For more examples, see [examples.md](examples.md)
## Hook Configuration ## Hook Configuration
@@ -185,32 +159,19 @@ For complete examples, see [examples.md](examples.md)
} }
``` ```
### Multiple Hooks ### Multiple Hooks (Sequential)
Run several hooks in sequence:
```json ```json
{ {
"hooks": { "hooks": {
"PostToolUse": [ "PostToolUse": [{
{ "matcher": "Write|Edit",
"matcher": "Write|Edit", "hooks": [
"hooks": [ {"type": "command", "command": "npx prettier --write $TOOL_ARGS"},
{ {"type": "command", "command": "npx eslint --fix $TOOL_ARGS"},
"type": "command", {"type": "command", "command": "git add $TOOL_ARGS"}
"command": "npx prettier --write $TOOL_ARGS" ]
}, }]
{
"type": "command",
"command": "npx eslint --fix $TOOL_ARGS"
},
{
"type": "command",
"command": "git add $TOOL_ARGS"
}
]
}
]
} }
} }
``` ```
@@ -224,18 +185,18 @@ Run several hooks in sequence:
} }
``` ```
## Settings File Hierarchy ## Settings Hierarchy
**Load Order** (highest to lowest priority): **Load Order** (highest to lowest priority):
1. `.claude/settings.local.json` - Project, user-only (gitignored) 1. `.claude/settings.local.json` - Project, personal (gitignored)
2. `.claude/settings.json` - Project, team-shared (in git) 2. `.claude/settings.json` - Project, team (in git)
3. `~/.claude/settings.json` - Global, user-only 3. `~/.claude/settings.json` - Global, personal
**Use Cases**: **Use Cases**:
- **Global**: Personal preferences, universal logging - **Global**: Personal preferences, universal logging
- **Project**: Team standards, project automation - **Project**: Team standards, project automation
- **Local**: Personal overrides, development experiments - **Local**: Personal overrides, experiments
## Testing Hooks ## Testing Hooks
@@ -244,17 +205,13 @@ Run several hooks in sequence:
```json ```json
{ {
"hooks": { "hooks": {
"PostToolUse": [ "PostToolUse": [{
{ "matcher": "Write",
"matcher": "Write", "hooks": [{
"hooks": [ "type": "command",
{ "command": "echo 'Hook triggered: $TOOL_ARGS' && exit 0"
"type": "command", }]
"command": "echo 'Hook triggered for: $TOOL_ARGS' && exit 0" }]
}
]
}
]
} }
} }
``` ```
@@ -264,44 +221,28 @@ Run several hooks in sequence:
```json ```json
{ {
"hooks": { "hooks": {
"PreToolUse": [ "PreToolUse": [{
{ "matcher": "Write",
"matcher": "Write", "hooks": [{
"hooks": [ "type": "command",
{ "command": "echo 'This blocks' >&2 && exit 2"
"type": "command", }]
"command": "echo 'This should block' >&2 && exit 2" }]
}
]
}
]
} }
} }
``` ```
Try writing a file - should be blocked. Try writing - should be blocked.
## Troubleshooting
| Problem | Solution |
|---------|----------|
| Hook not triggering | Check matcher pattern, restart Claude Code |
| Hook fails silently | Check exit codes (use 0 for success) |
| Command not found | Use full path: `/usr/local/bin/prettier` |
| Permission denied | `chmod +x .claude/hooks/script.sh` |
| Timeout | Increase timeout value or optimize command |
For detailed troubleshooting, see [troubleshooting.md](troubleshooting.md)
## Best Practices ## Best Practices
### 1. Always Exit Explicitly ### 1. Always Exit Explicitly
```bash ```bash
# Good # ✓ Good
command && exit 0 command && exit 0
# Bad # ✗ Bad
command command
``` ```
@@ -310,7 +251,7 @@ command
```json ```json
{ {
"command": "npm test", "command": "npm test",
"timeout": 120 // Don't let tests run forever "timeout": 120 // Don't hang forever
} }
``` ```
@@ -328,29 +269,41 @@ exit 0 # Don't block on missing file
### 4. Use Scripts for Complex Logic ### 4. Use Scripts for Complex Logic
```json ```json
// Bad - complex bash in JSON // ✓ Good - external script
{ {
"command": "if [ -f $TOOL_ARGS ]; then cat $TOOL_ARGS | grep pattern | wc -l; fi" "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/check.sh $TOOL_ARGS"
} }
// Good - external script // ✗ Bad - complex bash in JSON
{ {
"command": "$CLAUDE_PROJECT_DIR/.claude/hooks/check-file.sh $TOOL_ARGS" "command": "if [ -f $TOOL_ARGS ]; then cat $TOOL_ARGS | grep pattern | wc -l; fi"
} }
``` ```
### 5. Test Before Team Deployment ### 5. Test Before Team Deployment
Test in `.claude/settings.local.json` before adding to `.claude/settings.json`. Test in `.claude/settings.local.json` before adding to team settings.
## Security Considerations ## Troubleshooting
| Problem | Solution |
|---------|----------|
| Not triggering | Check matcher, restart Claude |
| Fails silently | Check exit codes (use 0 for success) |
| Command not found | Use full path |
| Permission denied | `chmod +x script.sh` |
| Timeout | Increase timeout or optimize |
For detailed troubleshooting, see [troubleshooting.md](troubleshooting.md)
## Security
### Validate Input ### Validate Input
```bash ```bash
# Sanitize TOOL_ARGS # Sanitize TOOL_ARGS
if [[ ! $TOOL_ARGS =~ ^[a-zA-Z0-9/_.-]+$ ]]; then if [[ ! $TOOL_ARGS =~ ^[a-zA-Z0-9/_.-]+$ ]]; then
echo "Invalid file path" >&2 echo "Invalid path" >&2
exit 2 exit 2
fi fi
``` ```
@@ -358,33 +311,26 @@ fi
### Limit Permissions ### Limit Permissions
```json ```json
// Specific (good) // ✓ Specific
"matcher": "Write|Edit" "matcher": "Write|Edit"
// Too broad (risky) // ✗ Too broad
"matcher": "*" "matcher": "*"
``` ```
### Avoid Destructive Commands ### Avoid Destructive Commands
```bash ```bash
# Dangerous # ✗ Dangerous
rm -rf $TOOL_ARGS rm -rf $TOOL_ARGS
# Safer # ✓ Safer
if [[ -f "$TOOL_ARGS" ]] && [[ "$TOOL_ARGS" != "/" ]]; then if [[ -f "$TOOL_ARGS" ]] && [[ "$TOOL_ARGS" != "/" ]]; then
rm "$TOOL_ARGS" rm "$TOOL_ARGS"
fi fi
``` ```
## Resources ## Quick Reference
- [Complete Examples](examples.md) - Working hook configurations
- [Advanced Patterns](patterns.md) - Complex workflows
- [Troubleshooting Guide](troubleshooting.md) - Problem-solution reference
- [Official Documentation](https://docs.claude.com/en/docs/claude-code/hooks)
## Quick Reference Card
### Common Patterns ### Common Patterns
@@ -395,10 +341,20 @@ fi
// Block secrets // Block secrets
"PreToolUse": [{"matcher": "Write", "hooks": [{"type": "command", "command": "grep -q 'secret' $TOOL_ARGS && exit 2 || exit 0"}]}] "PreToolUse": [{"matcher": "Write", "hooks": [{"type": "command", "command": "grep -q 'secret' $TOOL_ARGS && exit 2 || exit 0"}]}]
// Log all activity // Log activity
"PreToolUse": [{"matcher": "*", "hooks": [{"type": "command", "command": "echo \"$TOOL_NAME: $TOOL_ARGS\" >> .claude/log && exit 0"}]}] "PreToolUse": [{"matcher": "*", "hooks": [{"type": "command", "command": "echo \"$TOOL_NAME: $TOOL_ARGS\" >> .claude/log && exit 0"}]}]
``` ```
## Additional Resources
**Need more?**
- [Complete Examples](examples.md) - Working hook configurations
- [Advanced Patterns](patterns.md) - Complex workflows
- [Troubleshooting Guide](troubleshooting.md) - Problem solutions
- [Official Docs](https://docs.claude.com/en/docs/claude-code/hooks)
💡 **Tip**: Start simple, test thoroughly, use exit codes correctly. Hooks are powerful - use them wisely.
--- ---
**Remember**: Hooks are powerful automation tools. Start simple, test thoroughly, use exit codes properly to control flow. **Remember**: Hooks automate workflows. Exit codes control flow. Test in local settings first. Use specific matchers for security.

136
claude-code/skills/claude-memory/SKILL.md
View File

@@ -1,6 +1,6 @@
--- ---
name: Claude Code Memory Specialist name: Claude Code Memory Specialist
description: Optimize and troubleshoot Claude Code memory files (CLAUDE.md) for efficiency, token management, and team collaboration. Use PROACTIVELY when memory isn't loading, context is bloated, optimizing existing memory files, or when users mention "CLAUDE.md", "memory file", or "project context". NOT for initial setup - use /init command first. description: Optimize and troubleshoot Claude Code memory files (CLAUDE.md) for efficiency, token management, and team collaboration. Use PROACTIVELY after reading ANY CLAUDE.md file to suggest optimizations, when CLAUDE.md exceeds 200 lines, when starting work on projects, or when users mention "CLAUDE.md", "memory file", or "project context". NOT for initial setup - use /init command first.
--- ---
# Claude Code Memory Optimization & Troubleshooting # Claude Code Memory Optimization & Troubleshooting
@@ -8,59 +8,52 @@ description: Optimize and troubleshoot Claude Code memory files (CLAUDE.md) for
## When to Use This Skill ## When to Use This Skill
Use this skill when: Use this skill when:
- Troubleshooting memory files that aren't loading - CLAUDE.md file exceeds 200 lines (bloat)
- Optimizing bloated CLAUDE.md files (>200 lines) - After reading any CLAUDE.md to suggest improvements
- Managing token consumption in project memory - Memory files not loading correctly
- Managing token consumption
- Setting up memory hierarchy (project/user/subfolder) - Setting up memory hierarchy (project/user/subfolder)
- Debugging why Claude isn't following instructions
- Organizing memory for team collaboration - Organizing memory for team collaboration
Do NOT use this skill for: Do NOT use this skill for:
- **Initial setup** - Use `/init` command instead - **Initial setup** - Use `/init` command instead
- Creating slash commands (use claude-command-expert skill) - Creating slash commands (use claude-commands skill)
- General Claude Code issues - General Claude Code issues
**Important**: Always start with `/init` for initial project memory setup. **Important**: Always start with `/init` for initial project memory setup.
## Quick Reference: Memory Hierarchy ## Quick Reference
### Memory Hierarchy (Load Order)
``` ```
1. Enterprise Policy ~/.claude/enterprise/CLAUDE.md (highest priority) 1. Enterprise Policy ~/.claude/enterprise/CLAUDE.md (highest)
2. Project Memory ./CLAUDE.md or ./.claude/CLAUDE.md 2. Project Memory ./CLAUDE.md or ./.claude/CLAUDE.md
3. User Memory ~/.claude/CLAUDE.md 3. User Memory ~/.claude/CLAUDE.md
4. Subfolder Memory ./subfolder/CLAUDE.md 4. Subfolder Memory ./subfolder/CLAUDE.md
``` ```
**Lookup Order**: Claude searches upward from current directory, loading all CLAUDE.md files found. Claude searches upward from current directory, loading all found.
### Target Size
**Goal**: 100-200 lines per CLAUDE.md (~400-800 tokens)
**Why**: Loaded in EVERY conversation. 500+ line files waste thousands of tokens.
## Core Principles ## Core Principles
### 1. Target Size: 100-200 Lines ### 1. Progressive Disclosure Pattern
**Why**: Each CLAUDE.md loaded consumes tokens in every conversation.
```markdown ```markdown
# ❌ Bad (500+ lines) # CLAUDE.md (Core - Always Loaded)
Extensive documentation embedded inline
# ✓ Good (150 lines)
Core info + imports for details
```
### 2. Progressive Disclosure Pattern
```markdown
# CLAUDE.md (Core - always loaded)
Quick reference, critical rules, imports Quick reference, critical rules, imports
# docs/architecture.md (Loaded on demand) # docs/architecture.md (Loaded on Demand)
Detailed architecture information Detailed architecture information
# docs/style-guide.md (Loaded on demand)
Comprehensive coding standards
``` ```
### 3. Use Specific, Emphatic Language **Token Savings**: 400 tokens (core) vs 2000+ tokens (everything embedded)
### 2. Use Specific, Emphatic Language
```markdown ```markdown
# ❌ Weak # ❌ Weak
@@ -72,15 +65,15 @@ IMPORTANT: ALL React components MUST be functional (no class components).
## Essential Structure ## Essential Structure
### Minimal Template (100 lines) ### Minimal Template (100-150 lines)
```markdown ```markdown
# ProjectName # ProjectName
Brief description. Brief description (1-2 sentences).
## Tech Stack ## Tech Stack
- Key technologies - Key technologies (3-5 items)
- See @docs/tech-stack.md for details - See @docs/tech-stack.md for details
## Common Commands ## Common Commands
@@ -106,7 +99,7 @@ For complete templates, see [templates.md](templates.md)
| Problem | Quick Fix | | Problem | Quick Fix |
|---------|-----------| |---------|-----------|
| Memory not loading | Check filename case: `CLAUDE.md` | | Memory not loading | Check filename: `CLAUDE.md` (case-sensitive) |
| Claude ignores rules | Add `IMPORTANT:` or `YOU MUST` | | Claude ignores rules | Add `IMPORTANT:` or `YOU MUST` |
| Too many tokens | Move details to @docs/ imports | | Too many tokens | Move details to @docs/ imports |
| Updates not working | Restart session or use `/memory` | | Updates not working | Restart session or use `/memory` |
@@ -116,15 +109,17 @@ For detailed troubleshooting, see [troubleshooting.md](troubleshooting.md)
## Optimization Quick Win ## Optimization Quick Win
**Before (bloated)**: **Before (bloated - 1500 tokens)**:
```markdown ```markdown
This project is a comprehensive platform built with React, Node.js, Express, This project is a comprehensive platform built with React 18,
PostgreSQL... [extensive paragraph explaining everything] utilizing TypeScript for type safety, Node.js 20 for the backend,
Express 4.18 for API routes, PostgreSQL 15 for data persistence...
[extensive paragraphs explaining everything]
``` ```
**After (lean)**: **After (lean - 300 tokens)**:
```markdown ```markdown
Tech Stack: React + Node.js + PostgreSQL Tech Stack: React 18 + Node.js 20 + PostgreSQL 15
See @docs/architecture.md for details See @docs/architecture.md for details
``` ```
@@ -151,38 +146,33 @@ For optimization patterns, see [patterns.md](patterns.md)
### ✓ Do ### ✓ Do
```markdown ```markdown
# CLAUDE.md # CLAUDE.md
Quick reference content Quick reference
For detailed architecture: @docs/architecture.md For architecture: @docs/architecture.md
For API reference: @docs/api-reference.md For API details: @docs/api-reference.md
``` ```
### ❌ Don't ### ❌ Don't
```markdown ```markdown
# CLAUDE.md # Deep chains (max depth = 5)
@docs/a.md → @docs/b.md → @docs/c.md → @docs/d.md → @docs/e.md → @docs/f.md @docs/a.md → @docs/b.md → @docs/c.md → @docs/d.md → @docs/e.md
# Max depth is 5, avoid deep chains
``` ```
**Rules**: **Rules**:
- Max import depth: 5 levels - Max import depth: 5 levels
- No circular references - No circular references
- Use relative paths for project files - Keep chains flat, not deep
- Keep import chains flat, not deep
## Quick Update Methods ## Quick Update Methods
### Method 1: # Shortcut (Fastest) ### Method 1: # Shortcut (Fastest)
```bash ```
# Press # at input start Press # at input start → type update → auto-adds to CLAUDE.md
# Type your update
# Auto-adds to appropriate CLAUDE.md
``` ```
### Method 2: /memory Command ### Method 2: /memory Command
```bash ```
/memory /memory → Opens management interface
# Opens memory management interface
``` ```
### Method 3: Direct Edit ### Method 3: Direct Edit
@@ -194,7 +184,6 @@ vim CLAUDE.md
## Emphasis Techniques ## Emphasis Techniques
For critical rules: For critical rules:
```markdown ```markdown
IMPORTANT: [Critical rule] IMPORTANT: [Critical rule]
YOU MUST [mandatory action] YOU MUST [mandatory action]
@@ -203,25 +192,24 @@ NEVER [forbidden action]
ALL CAPS for maximum attention ALL CAPS for maximum attention
``` ```
## Testing Memory Effectiveness ## Testing Effectiveness
### Quick Test
```markdown ```markdown
# Add temporary marker to CLAUDE.md # Add temporary marker
**MEMORY TEST: If you see this, memory loaded correctly** **MEMORY TEST: If you see this, memory loaded correctly**
# Ask Claude: "What's the first line of your memory?" # Ask Claude: "What's the first line of your memory?"
# Should see marker, then remove it # Should see marker, then remove it
``` ```
## Team Setup Example ## Team Setup Pattern
```bash ```bash
# .gitignore # .gitignore
.claude/CLAUDE.local.md # Personal only .claude/CLAUDE.local.md # Personal only
.claude/settings.local.json # Personal settings .claude/settings.local.json # Personal settings
# .claude/CLAUDE.md (in git) # .claude/CLAUDE.md (in git - team standards)
# Team Standards # Team Standards
@docs/architecture.md @docs/architecture.md
@@ -241,14 +229,36 @@ IMPORTANT: All team members follow these standards.
For team workflows, see [workflows.md](workflows.md) For team workflows, see [workflows.md](workflows.md)
## Resources ## Compression Techniques
- [Memory File Templates](templates.md) - Ready-to-use CLAUDE.md templates 1. **Bullet Points > Paragraphs** (50% more efficient)
2. **Commands > Explanations** (show `npm test`, not prose)
3. **Imports > Embedding** (`@docs/api.md` = 5 tokens vs 2000)
4. **Examples > Theory** (concrete beats abstract)
### Decision Tree
```
Needed in 80%+ sessions?
→ YES: Keep in CLAUDE.md
Needed occasionally?
→ YES: Put in @docs/, reference from CLAUDE.md
Needed rarely?
→ NO: Omit, use web search or direct read
```
## Additional Resources
**Need more?**
- [Memory Templates](templates.md) - Ready-to-use CLAUDE.md templates
- [Troubleshooting Guide](troubleshooting.md) - Detailed problem-solution guide - [Troubleshooting Guide](troubleshooting.md) - Detailed problem-solution guide
- [Optimization Patterns](patterns.md) - Advanced token-saving techniques - [Optimization Patterns](patterns.md) - Advanced token-saving techniques
- [Team Workflows](workflows.md) - Collaboration strategies - [Team Workflows](workflows.md) - Collaboration strategies
- [Official Documentation](https://docs.claude.com/en/docs/claude-code/memory) - [Official Documentation](https://docs.claude.com/en/docs/claude-code/memory)
💡 **Tip**: Measure regularly using `wc -l CLAUDE.md` (target: 100-200 lines)
--- ---
**Remember**: Practice what we preach - keep memory lean (100-200 lines), be specific not vague, use imports for details, emphasize critical rules, test effectiveness. **Remember**: Practice what we preach - keep memory lean (100-200 lines), be specific not vague, use imports for details, emphasize critical rules, test effectiveness.

423
claude-code/skills/claude-plugins/SKILL.md
View File

@@ -1,6 +1,6 @@
--- ---
name: Claude Code Plugin Developer name: Claude Code Plugin Developer
description: Create and structure Claude Code plugins with commands, agents, skills, hooks, and MCP servers. Use PROACTIVELY when building plugins for Claude Code, setting up plugin structure, configuring plugin manifests, or when users mention "create a plugin", "package for distribution", or "plugin marketplace". NOT for creating individual components in isolation. description: Create and structure Claude Code plugins with commands, agents, skills, hooks, and MCP servers. Use PROACTIVELY when users package multiple related features, mention "create a plugin", "package for distribution", "plugin marketplace", or have 3+ commands/skills to organize. NOT for creating individual components in isolation.
--- ---
# Claude Code Plugin Development # Claude Code Plugin Development
@@ -8,66 +8,55 @@ description: Create and structure Claude Code plugins with commands, agents, ski
## When to Use This Skill ## When to Use This Skill
Use this skill when: Use this skill when:
- Creating a new Claude Code plugin from scratch - Creating a new plugin from scratch
- Adding components to an existing plugin (commands, agents, skills, hooks) - Adding components to existing plugin
- Configuring plugin manifests and metadata - Configuring plugin manifests
- Setting up plugin distribution and marketplaces - Setting up distribution/marketplaces
- Troubleshooting plugin structure or installation issues - Packaging 3+ related commands/skills/agents
Do NOT use this skill for: Do NOT use this skill for:
- Creating standalone MCP servers (use MCP-specific documentation) - Creating standalone MCP servers
- General Claude Code usage (not plugin development) - Single commands (use claude-commands skill)
- Creating individual skills without plugin context - General Claude Code usage
## Quick Start: Creating a Plugin ## Quick Start
### 1. Basic Plugin Structure ### 1. Basic Plugin Structure
```bash ```bash
# Create plugin directory mkdir my-plugin && cd my-plugin
mkdir my-plugin
cd my-plugin
# Create required manifest directory
mkdir -p .claude-plugin mkdir -p .claude-plugin
# Create plugin.json manifest
cat > .claude-plugin/plugin.json << 'EOF' cat > .claude-plugin/plugin.json << 'EOF'
{ {
"name": "my-plugin", "name": "my-plugin",
"description": "Description of what your plugin does", "description": "What your plugin does",
"version": "1.0.0", "version": "1.0.0",
"author": { "author": {"name": "Your Name"}
"name": "Your Name"
}
} }
EOF EOF
# Add component directories
mkdir -p commands agents skills hooks
``` ```
### 2. Add Component Directories ### 2. Test Installation
```bash ```bash
# Create directories for plugin components /plugin install /path/to/my-plugin@local
mkdir -p commands # Slash commands /plugin list
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) ## Plugin Manifest (plugin.json)
### Required Fields ### Required Fields
```json ```json
{ {
"name": "plugin-name", // Lowercase, kebab-case "name": "plugin-name", // kebab-case
"description": "What it does", // Clear, concise description "description": "What it does", // Clear, concise
"version": "1.0.0", // Semantic versioning "version": "1.0.0", // Semantic versioning
"author": { "author": {"name": "Author"}
"name": "Author Name" // Your name or organization
}
} }
``` ```
@@ -75,14 +64,6 @@ mkdir -p hooks # Event handlers
```json ```json
{ {
"name": "my-plugin",
"description": "Advanced features",
"version": "1.2.0",
"author": {
"name": "Your Name",
"email": "you@example.com",
"url": "https://yoursite.com"
},
"repository": { "repository": {
"type": "git", "type": "git",
"url": "https://github.com/user/repo" "url": "https://github.com/user/repo"
@@ -94,200 +75,122 @@ mkdir -p hooks # Event handlers
## Plugin Components ## Plugin Components
### 1. Commands (Slash Commands) ### 1. Commands (commands/)
Create markdown files in `commands/` directory: ```markdown
# commands/review.md
```bash
# commands/review-security.md
--- ---
description: Review code for security vulnerabilities description: Review code for issues
allowed-tools: Read(*), Grep(*)
--- ---
Review the following files for common security issues: Review $ARGUMENTS for:
- SQL injection vulnerabilities - Logic errors
- XSS vulnerabilities - Style issues
- Hardcoded credentials
- Unsafe deserialization
$ARGUMENTS
``` ```
**Usage**: `/review-security @src/auth.js` **Usage**: `/review @file.js`
### 2. Agents ### 2. Agents (agents/)
Create agent configurations in `agents/` directory: ```markdown
```bash
# agents/code-reviewer.md # agents/code-reviewer.md
--- ---
description: Reviews code for best practices description: Reviews code for best practices
tools: [Read, Grep, Bash] tools: [Read, Grep]
model: claude-sonnet-4 model: claude-sonnet-4
--- ---
You are a code review specialist. When reviewing code: You are a code review specialist...
1. Check for common patterns and anti-patterns
2. Verify error handling
3. Look for security issues
4. Suggest improvements
``` ```
### 3. Skills ### 3. Skills (skills/)
Create skill directories in `skills/`: ```
skills/
```bash └── my-skill/
mkdir -p skills/my-skill └── SKILL.md # With frontmatter
# Then create skills/my-skill/SKILL.md with proper frontmatter
``` ```
See the `claude-skills` skill for comprehensive skill creation guidance. See claude-skills skill for details.
### 4. Hooks ### 4. Hooks (hooks/hooks.json)
Create `hooks/hooks.json` to define event handlers:
```json ```json
{ {
"PostToolUse": [ "PostToolUse": [{
{ "matcher": "Write|Edit",
"matcher": "Edit|Write", "hooks": [{
"hooks": [ "type": "command",
{ "command": "npx prettier --write $TOOL_ARGS"
"type": "command", }]
"command": "echo 'File modified: $TOOL_ARGS' >> .claude/activity.log" }]
}
]
}
]
} }
``` ```
### 5. MCP Servers ### 5. MCP Servers (.mcp.json)
Create `.mcp.json` for external tools:
```json ```json
{ {
"mcpServers": { "mcpServers": {
"my-server": { "my-server": {
"command": "node", "command": "node",
"args": ["server.js"], "args": ["server.js"]
"env": {
"API_KEY": "env:MY_API_KEY"
}
} }
} }
} }
``` ```
## Complete Plugin Example ## Directory Organization
See [examples.md](examples.md) for full working plugin examples including weather-plugin, git-tools, and api-plugin. **IMPORTANT**: Components at plugin root, NOT in `.claude-plugin/`
## 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/ my-plugin/
├── .claude-plugin/ # Manifest only ├── .claude-plugin/ # Manifest only
│ └── plugin.json │ └── plugin.json
├── commands/ # At plugin root, not in .claude-plugin/ ├── commands/ # At root
├── agents/ # At plugin root ├── agents/ # At root
├── skills/ # At plugin root ├── skills/ # At root
└── README.md # Usage documentation └── README.md
``` ```
**IMPORTANT**: Component directories go at the plugin root, NOT inside `.claude-plugin/` ## Distribution
### Testing Checklist ### Local Testing
- [ ] 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 ```bash
# Update version in plugin.json /plugin install /path/to/plugin@local
{ ```
"version": "1.1.0" // Increment for changes
}
# Breaking changes: 2.0.0 ### Team Marketplace
# New features: 1.1.0
# Bug fixes: 1.0.1 ```json
// .claude/settings.json
{
"plugin-marketplaces": {
"team": {
"url": "file:///path/to/marketplace"
}
},
"plugins": ["my-plugin@team"]
}
```
### Marketplace Structure
```
marketplace/
├── .claude-plugin/
│ └── marketplace.json
└── plugin-name/
├── .claude-plugin/plugin.json
└── [components]
``` ```
## Common Patterns ## Common Patterns
### Multi-Command Plugin ### Multi-Command Plugin
For related commands, use subdirectories:
``` ```
git-tools/ git-tools/
├── .claude-plugin/plugin.json ├── .claude-plugin/plugin.json
@@ -297,11 +200,7 @@ git-tools/
└── review.md └── review.md
``` ```
**Usage**: `/commit`, `/pr`, `/review` ### Agent + Skill Combo
### Agent + Skill Combination
Combine agents with specialized skills:
``` ```
api-plugin/ api-plugin/
@@ -309,137 +208,83 @@ api-plugin/
├── agents/ ├── agents/
│ └── api-specialist.md │ └── api-specialist.md
└── skills/ └── skills/
└── rest-api/ └── rest-api/SKILL.md
└── SKILL.md
``` ```
The agent can leverage the skill for specialized knowledge.
### Hook-Based Automation ### Hook-Based Automation
Use hooks for workflow automation:
```json ```json
{ {
"PostToolUse": [ "PostToolUse": [{
{ "matcher": "Write",
"matcher": "Write", "hooks": [{
"hooks": [ "type": "command",
{ "command": "npm run format $TOOL_ARGS"
"type": "command", }]
"command": "npm run format $TOOL_ARGS" }]
}
]
}
]
} }
``` ```
## Testing Checklist
- [ ] plugin.json valid JSON
- [ ] All required fields present
- [ ] Components at plugin root
- [ ] Commands have frontmatter
- [ ] Local installation works
- [ ] No sensitive data
- [ ] README documents features
## Troubleshooting ## Troubleshooting
### Plugin Not Found | Problem | Solution |
|---------|----------|
| Plugin not found | Check plugin.json in `.claude-plugin/` |
| Commands unavailable | Verify `commands/` at root, restart |
| Invalid structure | Move components to root, not `.claude-plugin/` |
**Issue**: `/plugin install` can't find plugin ## Security
**Solutions**: **Never include**:
1. Check marketplace configuration in settings.json - API keys or credentials
2. Verify plugin name matches directory name - Hardcoded secrets
3. Ensure plugin.json exists in `.claude-plugin/` - Personal paths
### 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
**Use environment variables**:
```json ```json
// .mcp.json
{ {
"mcpServers": { "mcpServers": {
"api-server": { "api": {
"env": { "env": {"API_KEY": "env:MY_API_KEY"}
"API_KEY": "env:MY_API_KEY" // Reference env var
}
} }
} }
} }
``` ```
### Command Permissions ## Version Management
Limit tool access in command frontmatter:
```markdown
---
allowed-tools: Read(src/**), Grep(src/**)
---
```
## Plugin Template
See [templates.md](templates.md) for ready-to-use templates and the create-plugin.sh script.
## Resources
- [Official Plugin Documentation](https://docs.claude.com/en/docs/claude-code/plugins)
- [Slash Commands Guide](../claude-command-expert/SKILL.md)
- [Hooks Guide](../claude-hooks/SKILL.md)
- [Agent Skills Guide](../claude-skill/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 ```json
{ {
"name": "plugin-name", "version": "1.1.0" // Semantic versioning
"description": "What it does",
"version": "1.0.0",
"author": {"name": "Your Name"}
} }
// Breaking: 2.0.0
// Features: 1.1.0
// Fixes: 1.0.1
``` ```
## Additional Resources
**Need more?**
- [Plugin Examples](examples.md) - Complete working plugins
- [Component Templates](templates.md) - Ready-to-use structures
- [Official Docs](https://docs.claude.com/en/docs/claude-code/plugins)
- [Commands Guide](../claude-commands/SKILL.md)
- [Hooks Guide](../claude-hooks/SKILL.md)
- [Skills Guide](../claude-skills/SKILL.md)
💡 **Tip**: Start with one component type, test thoroughly, then expand. Plugins organize related functionality.
--- ---
**Remember**: Plugins extend Claude Code with persistent, reusable functionality. Start simple with one or two components, test thoroughly, then expand based on actual needs. **Remember**: Plugins package related features. Components go at root. Test locally first. Use semantic versioning.

482
claude-code/skills/claude-skills/SKILL.md
View File

@@ -1,6 +1,6 @@
--- ---
name: Skill Creator name: Skill Creator
description: Guide for creating effective Claude Agent Skills with best practices, structure guidelines, and progressive disclosure principles. Use PROACTIVELY when creating new skills, refining existing skills, debugging why skills don't trigger, optimizing SKILL.md files for token efficiency, or when users mention "create a skill", "skill not working", or "skill.md". NOT for using existing skills. description: Guide for creating effective Claude Agent Skills with best practices, structure guidelines, and progressive disclosure principles. Use PROACTIVELY BEFORE starting skill creation to review best practices, DURING skill structuring to optimize content organization, AFTER completing a skill draft to validate triggers and structure, or when users mention "create a skill", "skill not working", or "skill.md". NOT for using existing skills.
--- ---
# Skill Creation Best Practices # Skill Creation Best Practices
@@ -10,94 +10,82 @@ description: Guide for creating effective Claude Agent Skills with best practice
Use this skill when: Use this skill when:
- Creating a new Agent Skill from scratch - Creating a new Agent Skill from scratch
- Improving or refactoring an existing skill - Improving or refactoring an existing skill
- Debugging why a skill isn't triggering correctly - Debugging why a skill isn't triggering
- Understanding skill architecture and design patterns
- Optimizing skill structure for token efficiency - Optimizing skill structure for token efficiency
- Before, during, and after skill creation
## Core Principle: Progressive Disclosure ## Core Principle: Progressive Disclosure
**Progressive disclosure is the fundamental design pattern for Agent Skills.** It works in three layers: **The fundamental design pattern for Agent Skills.**
### Layer 1: Metadata (Always Loaded) ### Three Layers
- **What**: YAML frontmatter with `name` and `description`
- **When**: Pre-loaded at every session start
- **Cost**: ~100 tokens per skill
- **Purpose**: Trigger detection - helps Claude decide if skill is relevant
### Layer 2: Instructions (Triggered) 1. **Metadata** (Always Loaded ~100 tokens)
- **What**: Main SKILL.md content - YAML frontmatter: `name` and `description`
- **When**: Loads when Claude determines skill applies - Triggers skill activation
- **Cost**: Variable (keep focused and concise)
- **Purpose**: Procedural guidance, workflows, best practices
### Layer 3: Resources (On-Demand) 2. **Instructions** (Triggered ~800-1000 tokens)
- **What**: Additional files, scripts, reference materials - Main SKILL.md content
- **When**: Only when explicitly needed - Workflows and guidance
- **Cost**: Only when accessed
- **Purpose**: Deep reference, executable code, examples 3. **Resources** (On-Demand)
- Additional files loaded when needed
- Examples, reference docs, scripts
## Skill Structure Requirements ## Skill Structure Requirements
### Mandatory: SKILL.md File ### Mandatory: SKILL.md
Every skill MUST have a `SKILL.md` file with YAML frontmatter:
```yaml ```yaml
--- ---
name: Your Skill Name name: Your Skill Name # Max 64 chars
description: Clear description of what this does and when to use it description: What it does and when to use it # Max 1024 chars
--- ---
``` ```
**Critical Constraints:** **Critical**: The description determines when Claude triggers the skill.
- Name: Maximum 64 characters
- Description: Maximum 1024 characters
- **The description is crucial** - it determines when Claude triggers the skill
### Optional: Additional Resources ### Optional: Additional Files
Structure additional files strategically:
``` ```
my-skill/ my-skill/
├── SKILL.md # Main entry point (required) ├── SKILL.md # Required entry point
├── reference.md # Deep reference material (load on-demand) ├── examples.md # Working code samples
├── examples.md # Code samples and templates ├── reference.md # Deep API docs
├── workflows/ # Step-by-step procedures └── workflows/
│ ├── advanced.md ├── beginner.md
│ └── beginner.md └── advanced.md
└── scripts/ # Executable utilities
└── helper.sh
``` ```
## Writing Effective Descriptions ## Writing Effective Descriptions
The `description` field is your skill's trigger mechanism. Make it count: The `description` is your trigger mechanism.
### Good Descriptions
✓ **Specific use cases**: "Create and analyze Excel spreadsheets with formulas, formatting, and pivot tables"
✓ **Clear triggers**: "Use when building React components following atomic design principles"
✓ **Domain clarity**: "Debug Swift applications using LLDB for crashes, memory issues, and runtime errors"
### Poor Descriptions
✗ **Too vague**: "Helps with coding"
✗ **No trigger context**: "Python utilities"
✗ **Feature list without purpose**: "Has functions for A, B, and C"
### Template for Descriptions
### Template
``` ```
[Action verb] [specific domain/task] [with/for/using] [key capabilities]. [Action] [domain/task] [with capabilities].
Use when [primary trigger scenario] [and optional secondary scenarios]. Use when [trigger scenario]. PROACTIVELY when [context].
``` ```
**Example:** "Create professional PowerPoint presentations with custom themes, charts, and animations. Use when building slide decks, pitch presentations, or visual reports." ### Examples
## Best Practices for SKILL.md Content **✓ Good**:
```yaml
description: Create and analyze Excel spreadsheets with formulas, formatting, and pivot tables. Use when building reports or data analysis.
### 1. Start with "When to Use This Skill" description: Debug Swift applications using LLDB for crashes, memory issues, and runtime errors. Use PROACTIVELY when encountering Swift bugs.
```
Immediately clarify trigger scenarios: **✗ Poor**:
```yaml
description: Helps with coding
description: Python utilities
description: Security checker
```
## Essential SKILL.md Structure
### 1. When to Use This Skill
```markdown ```markdown
## When to Use This Skill ## When to Use This Skill
@@ -105,142 +93,126 @@ Immediately clarify trigger scenarios:
Use this skill when: Use this skill when:
- [Primary scenario] - [Primary scenario]
- [Secondary scenario] - [Secondary scenario]
- [Edge case to include]
Do NOT use this skill for: Do NOT use this skill for:
- [Common confusion case] - [Common confusion]
- [Related but different scenario] - [Different tool]
``` ```
### 2. Structure for Scannability ### 2. Quick Start
Use clear hierarchies and action-oriented headers:
```markdown ```markdown
## Quick Start ## Quick Start
[Minimal example to get started]
Minimal working example:
```[language]
[code]
```
**Result**: [What this achieves]
```
### 3. Core Workflows
```markdown
## Core Workflows ## Core Workflows
### Workflow 1: [Name] ### Workflow 1: [Name]
1. Step one
2. Step two
### Workflow 2: [Name] 1. [Step]
1. Step one 2. [Step]
2. Step two 3. [Step]
## Advanced Techniques **Example**:
[Less common but powerful approaches] ```[language]
[code]
## Common Pitfalls ```
[Known issues and how to avoid them]
``` ```
### 3. Include Concrete Examples ### 4. Additional Resources
Always provide working examples, not abstract descriptions:
```markdown ```markdown
## Example: Creating a User Authentication Module ## Additional Resources
**Scenario**: Building JWT-based auth for a Flask API **Need more?**
- [Examples](examples.md) - Working code samples
- [Reference](reference.md) - API documentation
- [Advanced Workflows](workflows/advanced.md)
**Steps**: 💡 **Tip**: These load only when referenced.
1. Install dependencies: `pip install pyjwt flask-login`
2. Create auth.py with [specific structure]
3. Configure middleware in app.py
4. Add protected routes with @login_required
**Result**: Users can register, login, and access protected endpoints
``` ```
### 4. Reference Additional Files Explicitly ## Token Optimization
When you need to split content, reference it clearly: ### Target Sizes
- SKILL.md: 800-1000 tokens (~200-250 lines)
- Supplementary files: As needed
```markdown ### When to Split
## Deep Dive: Advanced Patterns
For comprehensive examples of [topic], see [examples.md](examples.md). **Keep in SKILL.md**:
- Needed 80%+ of time
- Under 1000 tokens
- Sequential steps
For API reference, consult [reference.md](reference.md). **Move to separate file**:
``` - Mutually exclusive content
- Reference material
- Advanced/edge cases
## Optimizing for Token Efficiency ### Compression Techniques
### When to Split Files 1. **Bullet points > Paragraphs** (50% more efficient)
2. **Code examples > Prose** (show don't tell)
**Keep in SKILL.md if:** 3. **References > Embedding** (load on-demand)
- Information is needed for 80%+ of use cases 4. **Concrete > Abstract** (examples beat theory)
- Content is under ~2000 tokens
- Steps are sequential and interdependent
**Split to separate file if:**
- Content is mutually exclusive (e.g., Python vs JavaScript examples)
- Material is reference-heavy (API docs, configuration options)
- Information is advanced/edge-case focused
### Code as Documentation
Executable scripts serve dual purposes:
1. **Tools Claude can run** without loading code into context
2. **Documentation by example** showing best practices
```markdown
## Generating Boilerplate
Run the initialization script to create project structure:
```bash
./scripts/init-project.sh my-app
```
This creates [description of what's created].
```
Claude can execute this without the script code consuming context tokens.
## Development Workflow ## Development Workflow
### 1. Start with Evaluation ### 1. Identify Need
**Don't guess what skills you need.** Instead: Don't guess - observe:
1. Run Claude on representative tasks 1. Run Claude on representative tasks
2. Identify where it struggles or asks repetitive questions 2. Find repeated questions or struggles
3. Capture successful patterns from those sessions 3. Capture successful patterns
4. Codify into a skill 4. Codify into skill
### 2. Iterate with Claude ### 2. Start Minimal
Build skills collaboratively: ```yaml
1. Work with Claude on a task ---
2. When you find a good solution, ask: "Should we capture this as a skill?" name: My Skill
3. Let Claude help structure the skill content description: [Specific, clear trigger description]
4. Test with new similar tasks ---
5. Refine based on actual usage
### 3. Monitor Trigger Accuracy ## When to Use This Skill
[Clear scenarios]
After creating a skill, test whether it triggers correctly: ## Quick Start
[One minimal example]
**Test scenarios:** ## Core Workflow
- Direct requests that SHOULD trigger it [3-5 essential steps]
- Similar requests that SHOULD trigger it ```
- Related requests that should NOT trigger it
If triggering is unreliable, refine the `description` field. ### 3. Test Triggering
### 4. Start Simple, Grow Organically **Positive tests** (should activate):
- "Create X using Y"
- "[Domain-specific request]"
Begin with a minimal SKILL.md: **Negative tests** (should NOT activate):
- Clear metadata - "[Related but different domain]"
- One core workflow - "[Different tool's purpose]"
- A few examples
Add complexity only when you encounter actual needs: ### 4. Grow Organically
- Split files when SKILL.md exceeds ~3000 tokens
- Add scripts when you repeat the same commands Add only when needed:
- Create reference files for API documentation - More examples from actual usage
- Advanced workflows when requested
- Reference docs when API is complex
- Scripts for repeated commands
## Common Patterns by Domain ## Common Patterns by Domain
@@ -248,28 +220,25 @@ Add complexity only when you encounter actual needs:
```markdown ```markdown
--- ---
name: [Framework/Language] [Pattern] Guide name: [Framework] [Pattern] Guide
description: [Action] [framework] applications following [specific pattern/principles]. Use when building [type of apps] with [key requirements]. description: [Action] [framework] applications following [pattern]. Use when building [type] with [requirements].
--- ---
## When to Use This Skill ## When to Use This Skill
Use when building [specific project type] with [language/framework] [Specific project types]
## Project Structure ## Project Structure
[Standard directory layout] [Standard layout]
## Core Workflows ## Core Workflows
### Create New [Component Type] ### Create [Component]
[Step-by-step process] [Steps]
### Common Patterns
[Frequently used code patterns with examples]
## Testing Strategy ## Testing Strategy
[How to test this type of code] [How to test]
``` ```
### Workflow/Process Skills ### Workflow Skills
```markdown ```markdown
--- ---
@@ -277,135 +246,71 @@ name: [Task] Workflow
description: [Action] for [domain] following [methodology]. Use when [scenario]. description: [Action] for [domain] following [methodology]. Use when [scenario].
--- ---
## When to Use This Skill
Use when you need to [primary task] and [key differentiator]
## Prerequisites ## Prerequisites
[What's needed before starting] [What's needed]
## Step-by-Step Process ## Step-by-Step Process
### Phase 1: [Name] ### Phase 1: [Name]
[Detailed steps] [Steps]
### Phase 2: [Name]
[Detailed steps]
## Quality Checklist ## Quality Checklist
- [ ] [Verification step] - [ ] [Verification]
- [ ] [Verification step]
``` ```
### Reference/Documentation Skills
```markdown
---
name: [Topic] Reference
description: [Type of information] for [domain/tool]. Use when [looking up/configuring/understanding] [specific aspects].
---
## Quick Reference
[Most common lookups in concise format]
## Detailed Documentation
See [reference.md](reference.md) for comprehensive API documentation.
## Common Tasks
### Task 1
[Quick example]
### Task 2
[Quick example]
```
## Security Considerations
### For Skill Creators
**Never include in skills:**
- Hardcoded credentials or API keys
- Personal identifying information
- Proprietary code without permission
- Instructions to make unsafe system changes
**Always consider:**
- Can this skill be misused if shared?
- Does it access sensitive file locations?
- Are external dependencies from trusted sources?
### For Skill Users
**Before installing a skill:**
1. Audit all files in the skill package
2. Check for network access attempts
3. Review any bundled scripts for malicious code
4. Verify the source is trustworthy
## Debugging Skills ## Debugging Skills
### Skill Doesn't Trigger ### Skill Doesn't Trigger
**Checklist:** **Fix description**:
1. Is the description specific enough? ```yaml
2. Does the description mention the trigger scenario? # ❌ Too vague
3. Is the name too generic? description: Python development helpers
4. Test with explicit requests mentioning keywords from the description
**Example fix:** # ✓ Specific with triggers
- Before: `description: "Python development helpers"` description: Create Python projects using Hatch and Hatchling for dependency management. Use when initializing new Python packages or configuring build systems.
- After: `description: "Create Python projects using Hatch and Hatchling for dependency management. Use when initializing new Python packages or configuring build systems."` ```
### Skill Triggers Too Often ### Skill Triggers Too Often
**Checklist:** **Add negatives**:
1. Is the description too broad? ```markdown
2. Add negative cases: "Do NOT use for..." ## When to Use This Skill
3. Make the domain more specific
Use when:
- [Specific scenario]
Do NOT use for:
- [Broader scenario that should use different skill]
```
### Content Doesn't Load ### Content Doesn't Load
**Checklist:** **Check references**:
1. Verify file paths in references are correct - Verify file paths are correct
2. Check that additional .md files are in the skill package - Ensure .md files exist in skill directory
3. Ensure script paths are relative to skill root - Use relative paths from skill root
## Skill Metadata Checklist ## Skill Checklist
Before finalizing a skill, verify: Before finalizing:
- [ ] Name is under 64 characters - [ ] Name under 64 characters
- [ ] Description is under 1024 characters - [ ] Description under 1024 characters, includes triggers
- [ ] Description includes specific use cases - [ ] SKILL.md has YAML frontmatter
- [ ] Description mentions when to trigger the skill - [ ] "When to Use This Skill" section present
- [ ] SKILL.md has YAML frontmatter with both fields - [ ] At least one concrete example
- [ ] "When to Use This Skill" section is present - [ ] No sensitive information
- [ ] At least one concrete example is included - [ ] File references work
- [ ] No sensitive information is hardcoded - [ ] Tested positive trigger scenarios
- [ ] File references are accurate - [ ] Tested negative scenarios (doesn't over-trigger)
- [ ] Tested triggering with target scenarios - [ ] Size under 1000 tokens for SKILL.md
- [ ] Tested NOT triggering with related but different scenarios
## Resources
### Official Documentation
- [Agent Skills Overview](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview)
- [Engineering Blog Post](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills)
- [Using Skills Guide](https://support.claude.com/en/articles/12512180-using-skills-in-claude)
### Example Skills
Study Anthropic's pre-built skills for reference:
- Excel (xlsx) - Complex domain with many features
- Word (docx) - Document generation workflows
- PowerPoint (pptx) - Creative + structured content
- PDF (pdf) - File manipulation and analysis
## Quick Start Template ## Quick Start Template
Use this template to begin a new skill:
```markdown ```markdown
--- ---
name: name: [Skill Name]
description: description: [Action] [domain] [with capabilities]. Use when [scenario]. PROACTIVELY when [context].
--- ---
# [Skill Name] # [Skill Name]
@@ -413,11 +318,11 @@ description:
## When to Use This Skill ## When to Use This Skill
Use this skill when: Use this skill when:
- - [Primary scenario]
- - [Secondary scenario]
Do NOT use this skill for: Do NOT use this skill for:
- - [Common confusion]
## Quick Start ## Quick Start
@@ -427,30 +332,43 @@ Do NOT use this skill for:
### Workflow 1: [Name] ### Workflow 1: [Name]
1. 1. [Step]
2. 2. [Step]
3. 3. [Step]
**Example:** **Example**:
``` ```
[Code or command] [code]
``` ```
**Result:** [What this achieves] **Result**: [What this achieves]
## Common Pitfalls ## Common Pitfalls
### Issue: [Problem] ### Issue: [Problem]
**Solution:** [How to avoid/fix] **Solution**: [Fix]
### Issue: [Problem] ## Additional Resources
**Solution:** [How to avoid/fix]
## Advanced Topics **Need more?**
- [Examples](examples.md) - Working samples
- [Reference](reference.md) - API docs
- [Advanced](workflows/advanced.md) - Complex patterns
[Optional: complex scenarios or optimizations] 💡 **Tip**: [Key insight]
``` ```
## Additional Resources
**Need more?**
- [Skill Examples](examples.md) - Complete working skills
- [Best Practices Guide](best-practices.md) - Comprehensive guidelines
- [Templates](templates.md) - Ready-to-use templates
- [Checklist](checklist.md) - Validation checklist
- [Official Docs](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview)
💡 **Tip**: Best skills emerge from real usage. Start simple, iterate based on actual needs, prioritize clarity over comprehensiveness.
--- ---
**Remember**: The best skills emerge from real usage patterns. Start simple, iterate based on actual needs, and prioritize clarity over comprehensiveness. **Remember**: Specific descriptions trigger correctly. Progressive disclosure saves tokens. Test thoroughly. Start minimal and grow organically.

297
claude-code/skills/claude-skills/best-practices.md Normal file
View File

@@ -0,0 +1,297 @@
# Skill Best Practices
Comprehensive guidelines for creating effective Agent Skills.
## Progressive Disclosure Architecture
Skills work in three layers:
### Layer 1: Metadata (Always Loaded)
- **What**: YAML frontmatter with `name` and `description`
- **When**: Pre-loaded at every session start
- **Cost**: ~100 tokens per skill
- **Purpose**: Trigger detection
### Layer 2: Instructions (Triggered)
- **What**: Main SKILL.md content
- **When**: Loads when Claude determines skill applies
- **Cost**: Variable (keep under 1000 tokens)
- **Purpose**: Procedural guidance, workflows
### Layer 3: Resources (On-Demand)
- **What**: Additional files, scripts, reference materials
- **When**: Only when explicitly needed
- **Cost**: Only when accessed
- **Purpose**: Deep reference, examples
## Writing Effective Descriptions
The `description` field is your skill's trigger mechanism. Make it count.
### Good Descriptions
✓ **Specific use cases**: "Create and analyze Excel spreadsheets with formulas, formatting, and pivot tables"
✓ **Clear triggers**: "Use when building React components following atomic design principles"
✓ **Domain clarity**: "Debug Swift applications using LLDB for crashes, memory issues, and runtime errors"
### Poor Descriptions
✗ **Too vague**: "Helps with coding"
✗ **No trigger context**: "Python utilities"
✗ **Feature list without purpose**: "Has functions for A, B, and C"
### Template
```
[Action verb] [specific domain/task] [with/for/using] [key capabilities].
Use when [primary trigger scenario] [and optional secondary scenarios].
```
**Example**: "Create professional PowerPoint presentations with custom themes, charts, and animations. Use when building slide decks, pitch presentations, or visual reports."
## Skill File Structure
### Mandatory: SKILL.md
```yaml
---
name: Your Skill Name # Max 64 chars
description: Clear description of usage # Max 1024 chars
---
```
### Optional: Additional Resources
```
my-skill/
├── SKILL.md # Main entry (required)
├── reference.md # Deep reference
├── examples.md # Code samples
├── workflows/ # Step-by-step procedures
│ ├── advanced.md
│ └── beginner.md
└── scripts/ # Executable utilities
└── helper.sh
```
## SKILL.md Content Structure
### 1. Start with "When to Use This Skill"
```markdown
## When to Use This Skill
Use this skill when:
- [Primary scenario]
- [Secondary scenario]
- [Edge case to include]
Do NOT use this skill for:
- [Common confusion case]
- [Related but different scenario]
```
### 2. Structure for Scannability
```markdown
## Quick Start
[Minimal example to get started]
## Core Workflows
### Workflow 1: [Name]
1. Step one
2. Step two
## Advanced Techniques
[Less common but powerful approaches]
## Common Pitfalls
[Known issues and how to avoid them]
```
### 3. Include Concrete Examples
Always provide working examples, not abstract descriptions:
```markdown
## Example: Creating a User Authentication Module
**Scenario**: Building JWT-based auth for a Flask API
**Steps**:
1. Install dependencies: `pip install pyjwt flask-login`
2. Create auth.py with [specific structure]
3. Configure middleware in app.py
4. Add protected routes with @login_required
**Result**: Users can register, login, and access protected endpoints
```
### 4. Reference Additional Files Explicitly
```markdown
## Deep Dive: Advanced Patterns
For comprehensive examples, see [examples.md](examples.md).
For API reference, consult [reference.md](reference.md).
```
## Optimizing for Token Efficiency
### When to Split Files
**Keep in SKILL.md if:**
- Information needed for 80%+ of use cases
- Content is under ~2000 tokens
- Steps are sequential and interdependent
**Split to separate file if:**
- Content is mutually exclusive (e.g., Python vs JavaScript examples)
- Material is reference-heavy (API docs, configuration options)
- Information is advanced/edge-case focused
### Code as Documentation
Executable scripts serve dual purposes:
1. **Tools Claude can run** without loading code into context
2. **Documentation by example** showing best practices
```markdown
## Generating Boilerplate
Run the initialization script:
```bash
./scripts/init-project.sh my-app
```
This creates [description of what's created].
```
Claude can execute this without script code consuming context tokens.
## Development Workflow
### 1. Start with Evaluation
**Don't guess what skills you need.** Instead:
1. Run Claude on representative tasks
2. Identify where it struggles or asks repetitive questions
3. Capture successful patterns from those sessions
4. Codify into a skill
### 2. Iterate with Claude
Build skills collaboratively:
1. Work with Claude on a task
2. When you find a good solution, ask: "Should we capture this as a skill?"
3. Let Claude help structure the skill content
4. Test with new similar tasks
5. Refine based on actual usage
### 3. Monitor Trigger Accuracy
After creating a skill, test triggering:
**Test scenarios:**
- Direct requests that SHOULD trigger it
- Similar requests that SHOULD trigger it
- Related requests that should NOT trigger it
If triggering is unreliable, refine the `description` field.
### 4. Start Simple, Grow Organically
Begin with minimal SKILL.md:
- Clear metadata
- One core workflow
- A few examples
Add complexity only when needed:
- Split files when SKILL.md exceeds ~3000 tokens
- Add scripts when repeating same commands
- Create reference files for API documentation
## Common Anti-Patterns
### ❌ Generic Description
```yaml
description: Helps with coding
```
**Fix**: Be specific about domain and triggers
### ❌ No Process Defined
```markdown
You are a code reviewer. Review code.
```
**Fix**: Define step-by-step process
### ❌ All Tools Granted
```yaml
# Omitting tools when only reads needed
```
**Fix**: Whitelist minimum required tools
### ❌ Verbose Prompt
```markdown
You are an expert developer with 20 years of experience... [3000 words]
```
**Fix**: Be concise, focus on process and format
## Testing Skills
### Test Plan Template
```markdown
# Positive Tests (Should Activate)
1. "Create REST endpoint for user auth"
Expected: Activates
Actual: ___
# Negative Tests (Should NOT Activate)
1. "Write unit tests for API"
Expected: Does not activate
Actual: ___
## Results
- Precision: X%
- Recall: Y%
```
## Security Considerations
### Never Include
- Hardcoded credentials or API keys
- Personal identifying information
- Proprietary code without permission
- Instructions to make unsafe system changes
### Always Consider
- Can this skill be misused if shared?
- Does it access sensitive file locations?
- Are external dependencies from trusted sources?
## Skill Metadata Checklist
Before finalizing:
- [ ] Name is under 64 characters
- [ ] Description is under 1024 characters
- [ ] Description includes specific use cases
- [ ] Description mentions when to trigger
- [ ] SKILL.md has YAML frontmatter
- [ ] "When to Use This Skill" section present
- [ ] At least one concrete example
- [ ] No sensitive information
- [ ] File references are accurate
- [ ] Tested triggering scenarios
- [ ] Tested NOT triggering scenarios
## Summary
**Best practices in order of importance:**
1. **Write specific descriptions** with clear triggers
2. **Structure progressively** (metadata → core → details)
3. **Start simple** and grow based on actual needs
4. **Test thoroughly** with positive and negative scenarios
5. **Optimize tokens** by splitting appropriately
6. **Provide examples** not just theory
7. **Monitor usage** and refine based on feedback

210
claude-code/skills/claude-subagents/SKILL.md
View File

@@ -1,6 +1,6 @@
--- ---
name: Claude Code Subagent Specialist name: Claude Code Subagent Specialist
description: Refine and troubleshoot Claude Code subagents by optimizing prompts, tool access, descriptions, and performance. Use PROACTIVELY when improving existing subagents, debugging activation issues, optimizing delegation patterns, or when users mention "subagent not working", "agent won't trigger", or "refine agent". NOT for initial creation - use /agents command first. description: Refine and troubleshoot Claude Code subagents by optimizing prompts, tool access, descriptions, and performance. Use PROACTIVELY immediately AFTER creating subagent with /agents command to optimize configuration, when subagent doesn't activate as expected, when users mention "subagent not working", "agent won't trigger", or "refine agent". NOT for initial creation - use /agents command first.
--- ---
# Claude Code Subagent Refinement & Troubleshooting # Claude Code Subagent Refinement & Troubleshooting
@@ -8,31 +8,30 @@ description: Refine and troubleshoot Claude Code subagents by optimizing prompts
## When to Use This Skill ## When to Use This Skill
Use this skill when: Use this skill when:
- Refining existing subagent prompts for better performance - Refining existing subagent prompts
- Troubleshooting why a subagent isn't activating - Troubleshooting activation issues
- Optimizing tool access and permissions - Optimizing tool access and permissions
- Improving subagent descriptions for better delegation - Improving delegation patterns
- Debugging context management issues - Converting ad-hoc workflows to subagents
- Converting ad-hoc workflows to reusable subagents
Do NOT use this skill for: Do NOT use this skill for:
- **Initial creation** - Use `/agents` command instead (interactive UI) - **Initial creation** - Use `/agents` command
- Creating slash commands (use claude-command-expert skill) - Creating slash commands (use claude-commands skill)
- General Claude Code troubleshooting - General troubleshooting
**Important**: Always start with `/agents` to create subagents. Use this skill to refine them afterward. **Important**: Always start with `/agents` to create subagents.
## Quick Reference: Subagent Structure ## Quick Reference: Subagent Structure
```yaml ```yaml
--- ---
name: agent-name # Lowercase, kebab-case name: agent-name # kebab-case
description: When to use # Triggers automatic delegation description: When to use # Triggers delegation
tools: Tool1, Tool2 # Optional: omit to inherit all tools: Tool1, Tool2 # Optional: omit to inherit all
model: sonnet # Optional: sonnet/opus/haiku/inherit model: sonnet # Optional: sonnet/opus/haiku/inherit
--- ---
System prompt defining role, capabilities, and behavior. System prompt defining role, capabilities, behavior.
``` ```
**Locations**: **Locations**:
@@ -44,31 +43,29 @@ System prompt defining role, capabilities, and behavior.
### Problem 1: Subagent Never Activates ### Problem 1: Subagent Never Activates
**Diagnosis**: Check description specificity **Diagnosis**: Vague description
```yaml ```yaml
# ❌ Too vague (ignored) # ❌ Too vague
--- ---
description: Helper agent description: Helper agent
--- ---
# ✓ Specific (works) # ✓ Specific with triggers
--- ---
description: Analyze code for security vulnerabilities including SQL injection, XSS, authentication flaws, and hardcoded secrets. Use PROACTIVELY when reviewing code for security issues. description: Analyze code for security vulnerabilities including SQL injection, XSS, authentication flaws, and hardcoded secrets. Use PROACTIVELY when reviewing code for security issues.
--- ---
``` ```
**Fix**: Make description specific with trigger words + "PROACTIVELY" or "MUST BE USED" **Fix**: Add specificity + "PROACTIVELY" or "MUST BE USED"
### Problem 2: Wrong Tool Access ### Problem 2: Wrong Tool Access
**Diagnosis**: Check tool configuration
```yaml ```yaml
# ❌ Too permissive # ❌ Too permissive (inherits all)
--- ---
name: security-analyzer name: security-analyzer
# (inherits all tools) # (no tools field)
--- ---
# ✓ Restricted to needs # ✓ Restricted to needs
@@ -79,21 +76,21 @@ tools: Read, Grep, Glob
``` ```
**Tool Access Strategies**: **Tool Access Strategies**:
- **Inherit All**: Omit `tools` field (full flexibility) - **Inherit All**: Omit `tools` field
- **Read-Only**: `tools: Read, Grep, Glob` (analysis/review) - **Read-Only**: `tools: Read, Grep, Glob`
- **Specific**: `tools: Read, Write, Edit, Bash(npm test:*)` (implementation) - **Specific**: `tools: Read, Write, Edit, Bash(npm test:*)`
- **No Files**: `tools: WebFetch, WebSearch` (research only) - **Research**: `tools: WebFetch, WebSearch`
### Problem 3: Poor Output Quality ### Problem 3: Poor Output Quality
**Diagnosis**: System prompt needs structure **Diagnosis**: Needs structured prompt
```markdown ```markdown
# ❌ Vague # ❌ Vague
You review code for issues. You review code for issues.
# ✓ Structured # ✓ Structured
You are a senior code reviewer specializing in production-ready code quality. You are a senior code reviewer specializing in production-ready quality.
## Your Responsibilities ## Your Responsibilities
1. **Logic & Correctness**: Verify algorithms, edge cases 1. **Logic & Correctness**: Verify algorithms, edge cases
@@ -113,13 +110,13 @@ For each issue:
- Focus on high-impact problems - Focus on high-impact problems
``` ```
For detailed system prompt patterns, see [patterns.md](patterns.md) For detailed patterns, see [patterns.md](patterns.md)
## Description Best Practices ## Description Best Practices
### Template ### Template
```yaml ```yaml
description: [Action verb] [domain/task] [including capabilities]. Use [trigger]. PROACTIVELY when [scenario]. description: [Action] [domain] [including capabilities]. Use [trigger]. PROACTIVELY when [scenario].
``` ```
### Examples ### Examples
@@ -140,17 +137,15 @@ description: Python utilities
description: Security checker description: Security checker
``` ```
## Model Selection Guide ## Model Selection
| Model | Use For | Avoid For | | Model | Use For | Avoid For |
|-------|---------|-----------| |-------|---------|-----------|
| haiku | Simple transforms, quick checks | Complex reasoning, creativity | | haiku | Simple transforms, quick checks | Complex reasoning |
| sonnet | General tasks, balanced quality | When opus needed | | sonnet | General tasks (default) | When opus needed |
| opus | Complex architecture, creative work | Simple/repetitive (costly) | | opus | Complex architecture, creative work | Simple tasks (costly) |
| inherit | Task matches main thread | Need different capability | | inherit | Task matches main thread | Need different capability |
**Default**: sonnet (best balance)
## Testing Subagents ## Testing Subagents
### Test Plan Template ### Test Plan Template
@@ -161,25 +156,17 @@ description: Security checker
Expected: Activates Expected: Activates
Actual: ___ Actual: ___
2. "Add GraphQL mutation for profile"
Expected: Activates
Actual: ___
# Negative Tests (Should NOT Activate) # Negative Tests (Should NOT Activate)
1. "Write unit tests for API" 1. "Write unit tests for API"
Expected: Does not activate (testing concern) Expected: Does not activate (different concern)
Actual: ___
2. "Review API security"
Expected: Does not activate (security concern)
Actual: ___ Actual: ___
## Results ## Results
- Precision: X% (correct activations / total activations) - Precision: X%
- Recall: Y% (correct activations / should activate) - Recall: Y%
``` ```
For complete testing strategies, see [testing.md](testing.md) For complete testing, see [testing.md](testing.md)
## System Prompt Structure ## System Prompt Structure
@@ -190,62 +177,25 @@ You are a [role] specializing in [domain].
## Responsibilities ## Responsibilities
1. [Primary responsibility] 1. [Primary responsibility]
2. [Secondary responsibility] 2. [Secondary responsibility]
3. [Additional responsibilities]
## Process ## Process
1. [Step 1] 1. [Step 1]
2. [Step 2] 2. [Step 2]
3. [Step 3]
## Output Format ## Output Format
[Specific structure required] [Specific structure required]
## Examples ## Examples
### Good Example ### Good Example
[Show what good looks like] [Show what good looks like]
### Bad Example
[Show what to avoid]
## Constraints ## Constraints
- [Important limitation] - [Important limitation]
- [Another constraint]
``` ```
## Optimization Patterns ## Optimization Patterns
### Pattern 1: Role-Based Pipeline ### Domain Specialists
Specialized agents for each workflow stage:
```yaml
# Spec Agent (opus)
---
name: product-spec-writer
description: Create detailed product specifications from user requirements
tools: Read, Write, WebSearch
model: opus
---
# Architect Agent (opus)
---
name: solution-architect
description: Design system architecture from product specs
tools: Read, Write, Grep, Glob
model: opus
---
# Implementer Agent (sonnet)
---
name: code-implementer
description: Implement features from architectural designs
tools: Read, Write, Edit, Bash(npm test:*)
model: sonnet
---
```
### Pattern 2: Domain Specialists
```yaml ```yaml
# Frontend Specialist # Frontend Specialist
@@ -255,7 +205,7 @@ description: React/TypeScript UI development and component design. Use PROACTIVE
tools: Read, Write, Edit, Grep, Bash(npm:*) tools: Read, Write, Edit, Grep, Bash(npm:*)
--- ---
You are a React/TypeScript expert specializing in modern frontend development. You are a React/TypeScript expert specializing in modern frontend.
## Tech Stack ## Tech Stack
- React 18+ with hooks - React 18+ with hooks
@@ -267,96 +217,86 @@ You are a React/TypeScript expert specializing in modern frontend development.
- Functional components only - Functional components only
- Custom hooks for logic reuse - Custom hooks for logic reuse
- Accessibility (WCAG AA) - Accessibility (WCAG AA)
- Performance (lazy loading, memoization)
``` ```
For more patterns, see [patterns.md](patterns.md) ### Role-Based Pipeline
```yaml
# Architect Agent (opus)
---
name: solution-architect
description: Design system architecture from requirements
tools: Read, Write, WebSearch
model: opus
---
# Implementer Agent (sonnet)
---
name: code-implementer
description: Implement features from designs
tools: Read, Write, Edit, Bash(npm test:*)
model: sonnet
---
```
## Debugging Checklist ## Debugging Checklist
When subagent doesn't work as expected: When subagent doesn't work:
```markdown - [ ] Description is specific with trigger words
- [ ] Description is specific and includes trigger words - [ ] Description includes "PROACTIVELY" if needed
- [ ] Description includes "PROACTIVELY" or "MUST BE USED" if needed
- [ ] System prompt defines role clearly - [ ] System prompt defines role clearly
- [ ] System prompt includes process/steps - [ ] System prompt includes process/steps
- [ ] System prompt specifies output format - [ ] System prompt specifies output format
- [ ] System prompt has examples
- [ ] Tools match required capabilities - [ ] Tools match required capabilities
- [ ] Tools follow least-privilege principle - [ ] Model appropriate for complexity
- [ ] Model appropriate for task complexity - [ ] File in `.claude/agents/`
- [ ] File location correct (.claude/agents/)
- [ ] YAML frontmatter valid - [ ] YAML frontmatter valid
- [ ] Name uses kebab-case - [ ] Name uses kebab-case
- [ ] Tested with positive/negative scenarios - [ ] Tested positive/negative scenarios
```
## Common Anti-Patterns
### ❌ Generic Description
```yaml
description: Helps with coding
```
**Fix**: Be specific about domain and triggers
### ❌ No Process Defined
```markdown
You are a code reviewer. Review code.
```
**Fix**: Define step-by-step process
### ❌ All Tools Granted
```yaml
# Omitting tools when only reads needed
```
**Fix**: Whitelist minimum required tools
### ❌ Verbose Prompt
```markdown
You are an expert developer with 20 years of experience... [3000 words]
```
**Fix**: Be concise, focus on process and format
## Migration: Ad-Hoc to Subagent ## Migration: Ad-Hoc to Subagent
### When to Migrate ### When to Migrate
- Used same prompt 3+ times - Used same prompt 3+ times
- Prompt has clear pattern/structure - Prompt has clear pattern
- Task benefits from isolation - Task benefits from isolation
- Multiple team members need it - Multiple team members need it
### Process ### Process
**Step 1: Extract Pattern** **Step 1: Extract Pattern**
```markdown ```
# Repeated prompts: # Repeated prompts:
1. "Review auth.js for security issues" 1. "Review auth.js for security"
2. "Check payment.js for vulnerabilities" 2. "Check payment.js for vulnerabilities"
3. "Analyze api.js for security problems" 3. "Analyze api.js for security"
# Common pattern: Review [file] for security [types] # Pattern: Review [file] for security
``` ```
**Step 2: Generalize** **Step 2: Generalize**
```yaml ```yaml
--- ---
name: security-reviewer name: security-reviewer
description: Review code for security vulnerabilities including SQL injection, XSS, authentication flaws, and hardcoded secrets. Use PROACTIVELY for security reviews. description: Review code for security vulnerabilities. Use PROACTIVELY for security reviews.
tools: Read, Grep, Glob tools: Read, Grep, Glob
--- ---
``` ```
**Step 3: Test & Refine** **Step 3: Test & Refine**
Test with previous use cases, refine until quality matches manual prompts. Test with previous use cases, refine until quality matches.
## Resources ## Additional Resources
**Need more?**
- [Optimization Patterns](patterns.md) - Advanced subagent patterns - [Optimization Patterns](patterns.md) - Advanced subagent patterns
- [Testing Strategies](testing.md) - Comprehensive testing guide - [Testing Strategies](testing.md) - Comprehensive testing
- [System Prompt Templates](templates.md) - Ready-to-use prompts - [System Prompt Templates](templates.md) - Ready-to-use prompts
- [Official Documentation](https://docs.claude.com/en/docs/claude-code/sub-agents) - [Official Docs](https://docs.claude.com/en/docs/claude-code/sub-agents)
💡 **Tip**: Start with `/agents`, then refine. Iterate based on real usage. Test thoroughly.
--- ---
**Remember**: Start with `/agents` for creation. Use this skill for refinement. Iterate based on real usage. Test thoroughly. **Remember**: Use `/agents` to create. This skill refines. Specific descriptions trigger correctly. Test positive AND negative scenarios.