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

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

@@ -1,6 +1,6 @@
---
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
@@ -10,21 +10,20 @@ description: Create custom slash commands for Claude Code with argument handling
Use this skill when:
- Creating custom slash commands for Claude Code
- Building reusable prompt templates
- Automating repetitive tasks with commands
- Setting up project-specific workflows
- Converting manual prompts to slash commands
- User repeats similar prompts 3+ times
- Automating repetitive tasks
- Converting manual workflows to commands
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)
- Complex multi-file operations (use subagents)
## Quick Start
### Create Command File
Create a command file in `.claude/commands/`:
```bash
# Project-specific (team shared)
mkdir -p .claude/commands
cat > .claude/commands/review.md << 'EOF'
---
@@ -45,12 +44,12 @@ EOF
## Command Locations
| Location | Scope | Version Control | Use For |
|----------|-------|-----------------|---------|
| `.claude/commands/` | Project (team) | In git | Team workflows, standards |
| `~/.claude/commands/` | User (personal) | Not in git | Personal productivity |
| Location | Scope | Use For |
|----------|-------|---------|
| `.claude/commands/` | Project (team) | Team workflows, standards |
| `~/.claude/commands/` | User (personal) | Personal productivity |
## Command Syntax
## Essential Syntax
### Basic Structure
@@ -64,313 +63,143 @@ Prompt content here
$ARGUMENTS
```
### Filename = Command Name
**File name = Command name**: `review.md` → `/review`
```bash
# File: .claude/commands/test.md
# Command: /test
# File: .claude/commands/commit-push.md
# Command: /commit-push
```
## Frontmatter Options
### Frontmatter Options
```yaml
---
description: Generate unit tests for a function # Shows in /help
argument-hint: <file-path> <function-name> # Autocomplete hint
allowed-tools: Read(*), Bash(git:*) # Tool permissions
model: claude-haiku-4 # Override default model
disable-model-invocation: true # Prevent auto-invocation
description: Generate unit tests for a function # Required
argument-hint: <file-path> <function-name> # Autocomplete
allowed-tools: Read(*), Bash(git:*) # Permissions
model: claude-haiku-4 # Model override
---
```
## Argument Handling
### $ARGUMENTS - All Arguments
### Arguments
```markdown
---
description: Explain multiple files
---
Explain these files: $ARGUMENTS
$ARGUMENTS # All arguments
$1, $2, $3 # Positional arguments
@$1 or @file.js # Load file content
```
**Usage**: `/explain @src/a.js @src/b.js @src/c.js`
### Positional ($1, $2, $3...)
```markdown
---
description: Compare two approaches
argument-hint: <approach1> <approach2>
---
Compare approach "$1" versus "$2" and recommend which is better.
**Examples**:
```bash
/compare REST GraphQL # $1="REST", $2="GraphQL"
/review @src/main.js # Loads main.js content
/explain @src/a.js @src/b.js # Loads both files
```
**Usage**: `/compare REST GraphQL`
### Bash Execution
### File References with @
Prefix with `!` to execute before processing:
```markdown
---
description: Review a file
---
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:*)
description: Git workflow helper
allowed-tools: Bash(git:*)
---
!git status
!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
### Security Review
## Quick Examples
### Simple Review Command
```markdown
---
description: Comprehensive security review of code files
allowed-tools: Read(*), Grep(*)
argument-hint: <files...>
description: Review code quality
---
Perform a security audit on: $ARGUMENTS
Review @$1 for:
1. Logic errors
2. Code style
3. Performance issues
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
Provide specific fixes.
```
### Commit + Push
### Multi-Step Workflow
```markdown
---
description: Review changes, commit, and push to remote
description: Commit and push changes
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
1. Review changes
2. Create commit message
3. Commit and push
Ask for confirmation before pushing.
```
### 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.
Ask confirmation before push.
```
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
### 1. Clear Descriptions
### ✓ Do
- Clear descriptions under 100 chars
- Specific tool permissions
- Meaningful command names (kebab-case)
- Self-documenting prompts
- Include argument hints
```yaml
# Good
description: Generate unit tests for a specific function
### ✗ Avoid
- Vague descriptions ("Helper", "Utils")
- Wildcard permissions (`allowed-tools: *`)
- Short cryptic names (`/gt`, `/rs`)
- Hardcoded secrets or paths
- Missing frontmatter
# Bad
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
## Testing
```bash
# Good
/generate-tests
/review-security
/commit-and-push
# List all commands
/help
# Bad
/gt
/rs
/cap
# Test with arguments
/mycommand arg1
/mycommand @file.js
```
### 5. Self-Documenting Content
```markdown
Review code for:
1. Logic errors
2. Style issues
3. Performance problems
$ARGUMENTS
```
## Troubleshooting
## Common Issues
| Problem | Solution |
|---------|----------|
| Command not found | Check file is in `.claude/commands/`, ends with `.md` |
| Arguments not working | Use `$ARGUMENTS`, `$1`, `$2` (not `${ARGUMENTS}`) |
| Bash not executing | Add `allowed-tools` frontmatter with `Bash()` pattern |
| File references not loading | Verify file path, use `@` prefix |
| Command not found | Check `.claude/commands/`, restart Claude |
| Arguments not working | Use `$ARGUMENTS`, not `${ARGUMENTS}` |
| Bash not executing | Add `allowed-tools: Bash(...)` |
| File not loading | Use `@` prefix, verify path |
## Security Considerations
For detailed troubleshooting, see [troubleshooting.md](troubleshooting.md)
### Limit Tool Access
## Security
**Limit permissions**:
```yaml
# Specific commands only
allowed-tools: Bash(git status:*), Bash(git log:*)
# ✓ Specific
allowed-tools: Bash(git status:*), Bash(git diff:*)
# Never use unless required
# ✗ Too broad
allowed-tools: *
```
### No Hardcoded Secrets
**No secrets**:
```markdown
# Bad - hardcoded API key
!curl -H "API-Key: sk-abc123..." api.example.com
# ✗ Bad
!curl -H "API-Key: sk-abc123..."
# Good - use environment variables
!curl -H "API-Key: $MY_API_KEY" api.example.com
```
### Validate User Input
```markdown
# Risky - no validation
!rm -rf $1
# Better - validate first
Confirm you want to delete: $1
(Then use interactive confirmation)
# ✓ Good
!curl -H "API-Key: $MY_API_KEY"
```
## Command Template
@@ -387,13 +216,17 @@ allowed-tools: [Specific patterns if needed]
$ARGUMENTS
```
## Resources
## Additional Resources
- [Complete Examples](examples.md) - Working command configurations
- [Advanced Patterns](patterns.md) - Complex workflows
- [Official Documentation](https://docs.claude.com/en/docs/claude-code/slash-commands)
- [Plugin Development](../claude-plugin/SKILL.md) - Packaging commands
**Need more?**
- [Complete Examples](examples.md) - 10+ working commands
- [Command Patterns](patterns.md) - Reusable templates
- [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
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
@@ -8,74 +8,65 @@ description: Configure event-driven hooks for Claude Code to automate workflows,
## When to Use This Skill
Use this skill when:
- Automating workflows with event-driven triggers
- Enforcing code standards or security policies
- Automating workflows with event triggers
- Enforcing code standards or policies
- Validating changes before/after tool execution
- Injecting context at session start
- Logging or monitoring tool usage
- Setting up team-wide automation
Do NOT use this skill for:
- Creating slash commands (use claude-command-expert skill)
- Building full plugins (use claude-plugin skill)
- One-time scripts (just run them directly)
- Creating slash commands (use claude-commands skill)
- Building plugins (use claude-plugins skill)
- One-time scripts (run them directly)
## Quick Start
### 1. Hook Configuration File
### Configuration File Locations
```bash
# Project-wide (team shared)
.claude/settings.json
# User-specific (not shared)
.claude/settings.local.json
# Global (all projects)
~/.claude/settings.json
.claude/settings.json # Project (team)
.claude/settings.local.json # Project (personal)
~/.claude/settings.json # Global (personal)
```
### 2. Simple Example - Log File Changes
### Simple Example - Auto-Format
```json
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "command",
"command": "echo \"$(date): Modified $TOOL_ARGS\" >> .claude/changes.log"
}
]
}
]
"PostToolUse": [{
"matcher": "Write|Edit",
"hooks": [{
"type": "command",
"command": "npx prettier --write $TOOL_ARGS && exit 0"
}]
}]
}
}
```
## Hook Types
| Event | When It Runs | Common Use |
|-------|--------------|-----------|
| SessionStart | Session begins | Inject project context |
| Event | When | Common Use |
|-------|------|-----------|
| SessionStart | Session begins | Inject context |
| SessionEnd | Session ends | Cleanup, backups |
| PreToolUse | Before tool execution | Validation, permission checks |
| PreToolUse | Before tool execution | Validation, checks |
| PostToolUse | After tool completes | Formatting, linting |
| UserPromptSubmit | User submits prompt | Logging, analytics |
| UserPromptSubmit | User submits prompt | Logging |
| Notification | Claude sends notification | Desktop alerts |
| Stop | Agent finishes responding | Post-response processing |
| Stop | Agent finishes | Post-processing |
## Core Concepts
### Matcher Patterns
### Matchers
```json
// Single tool
"matcher": "Write"
// Multiple tools (OR)
// Multiple (OR)
"matcher": "Write|Edit|Read"
// All tools
@@ -88,23 +79,18 @@ Do NOT use this skill for:
### Exit Codes
```bash
# Success - Continue
exit 0
# Blocking Error - Stop operation
exit 2
# Non-Blocking Error - Continue
exit 1
exit 0 # Success - Continue
exit 1 # Non-blocking error - Continue
exit 2 # Blocking error - Stop operation
```
### Environment Variables
```bash
$CLAUDE_PROJECT_DIR # Current project directory
$TOOL_NAME # Name of the tool being used
$TOOL_ARGS # Arguments passed to the tool
$HOOK_EVENT # Event type (PreToolUse, etc.)
$CLAUDE_PROJECT_DIR # Current project
$TOOL_NAME # Tool being used
$TOOL_ARGS # Tool arguments
$HOOK_EVENT # Event type
```
## Common Use Cases
@@ -114,17 +100,13 @@ $HOOK_EVENT # Event type (PreToolUse, etc.)
```json
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "command",
"command": "cd $CLAUDE_PROJECT_DIR && npx prettier --write $TOOL_ARGS && exit 0"
}
]
}
]
"PostToolUse": [{
"matcher": "Write|Edit",
"hooks": [{
"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
{
"hooks": {
"PreToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "command",
"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
}
]
}
]
"PreToolUse": [{
"matcher": "Write|Edit",
"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",
"timeout": 30
}]
}]
}
}
```
@@ -155,23 +133,19 @@ $HOOK_EVENT # Event type (PreToolUse, etc.)
```json
{
"hooks": {
"PreToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "command",
"command": "cd $CLAUDE_PROJECT_DIR && npm test -- --silent || (echo 'Tests failed' >&2; exit 2)",
"timeout": 120
}
]
}
]
"PreToolUse": [{
"matcher": "Write|Edit",
"hooks": [{
"type": "command",
"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
@@ -185,32 +159,19 @@ For complete examples, see [examples.md](examples.md)
}
```
### Multiple Hooks
Run several hooks in sequence:
### Multiple Hooks (Sequential)
```json
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "command",
"command": "npx prettier --write $TOOL_ARGS"
},
{
"type": "command",
"command": "npx eslint --fix $TOOL_ARGS"
},
{
"type": "command",
"command": "git add $TOOL_ARGS"
}
]
}
]
"PostToolUse": [{
"matcher": "Write|Edit",
"hooks": [
{"type": "command", "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):
1. `.claude/settings.local.json` - Project, user-only (gitignored)
2. `.claude/settings.json` - Project, team-shared (in git)
3. `~/.claude/settings.json` - Global, user-only
1. `.claude/settings.local.json` - Project, personal (gitignored)
2. `.claude/settings.json` - Project, team (in git)
3. `~/.claude/settings.json` - Global, personal
**Use Cases**:
- **Global**: Personal preferences, universal logging
- **Project**: Team standards, project automation
- **Local**: Personal overrides, development experiments
- **Local**: Personal overrides, experiments
## Testing Hooks
@@ -244,17 +205,13 @@ Run several hooks in sequence:
```json
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write",
"hooks": [
{
"type": "command",
"command": "echo 'Hook triggered for: $TOOL_ARGS' && exit 0"
}
]
}
]
"PostToolUse": [{
"matcher": "Write",
"hooks": [{
"type": "command",
"command": "echo 'Hook triggered: $TOOL_ARGS' && exit 0"
}]
}]
}
}
```
@@ -264,44 +221,28 @@ Run several hooks in sequence:
```json
{
"hooks": {
"PreToolUse": [
{
"matcher": "Write",
"hooks": [
{
"type": "command",
"command": "echo 'This should block' >&2 && exit 2"
}
]
}
]
"PreToolUse": [{
"matcher": "Write",
"hooks": [{
"type": "command",
"command": "echo 'This blocks' >&2 && exit 2"
}]
}]
}
}
```
Try writing a file - 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)
Try writing - should be blocked.
## Best Practices
### 1. Always Exit Explicitly
```bash
# Good
# ✓ Good
command && exit 0
# Bad
# ✗ Bad
command
```
@@ -310,7 +251,7 @@ command
```json
{
"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
```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
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
```bash
# Sanitize TOOL_ARGS
if [[ ! $TOOL_ARGS =~ ^[a-zA-Z0-9/_.-]+$ ]]; then
echo "Invalid file path" >&2
echo "Invalid path" >&2
exit 2
fi
```
@@ -358,33 +311,26 @@ fi
### Limit Permissions
```json
// Specific (good)
// ✓ Specific
"matcher": "Write|Edit"
// Too broad (risky)
// ✗ Too broad
"matcher": "*"
```
### Avoid Destructive Commands
```bash
# Dangerous
# ✗ Dangerous
rm -rf $TOOL_ARGS
# Safer
# ✓ Safer
if [[ -f "$TOOL_ARGS" ]] && [[ "$TOOL_ARGS" != "/" ]]; then
rm "$TOOL_ARGS"
fi
```
## Resources
- [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
## Quick Reference
### Common Patterns
@@ -395,10 +341,20 @@ fi
// Block secrets
"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"}]}]
```
## 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
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
@@ -8,59 +8,52 @@ description: Optimize and troubleshoot Claude Code memory files (CLAUDE.md) for
## When to Use This Skill
Use this skill when:
- Troubleshooting memory files that aren't loading
- Optimizing bloated CLAUDE.md files (>200 lines)
- Managing token consumption in project memory
- CLAUDE.md file exceeds 200 lines (bloat)
- After reading any CLAUDE.md to suggest improvements
- Memory files not loading correctly
- Managing token consumption
- Setting up memory hierarchy (project/user/subfolder)
- Debugging why Claude isn't following instructions
- Organizing memory for team collaboration
Do NOT use this skill for:
- **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
**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)
2. Project Memory ./CLAUDE.md or ./.claude/CLAUDE.md
3. User Memory ~/.claude/CLAUDE.md
4. Subfolder Memory ./subfolder/CLAUDE.md
1. Enterprise Policy ~/.claude/enterprise/CLAUDE.md (highest)
2. Project Memory ./CLAUDE.md or ./.claude/CLAUDE.md
3. User Memory ~/.claude/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
### 1. Target Size: 100-200 Lines
**Why**: Each CLAUDE.md loaded consumes tokens in every conversation.
### 1. Progressive Disclosure Pattern
```markdown
# ❌ Bad (500+ lines)
Extensive documentation embedded inline
# ✓ Good (150 lines)
Core info + imports for details
```
### 2. Progressive Disclosure Pattern
```markdown
# CLAUDE.md (Core - always loaded)
# CLAUDE.md (Core - Always Loaded)
Quick reference, critical rules, imports
# docs/architecture.md (Loaded on demand)
# docs/architecture.md (Loaded on Demand)
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
# ❌ Weak
@@ -72,15 +65,15 @@ IMPORTANT: ALL React components MUST be functional (no class components).
## Essential Structure
### Minimal Template (100 lines)
### Minimal Template (100-150 lines)
```markdown
# ProjectName
Brief description.
Brief description (1-2 sentences).
## Tech Stack
- Key technologies
- Key technologies (3-5 items)
- See @docs/tech-stack.md for details
## Common Commands
@@ -106,7 +99,7 @@ For complete templates, see [templates.md](templates.md)
| 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` |
| Too many tokens | Move details to @docs/ imports |
| Updates not working | Restart session or use `/memory` |
@@ -116,15 +109,17 @@ For detailed troubleshooting, see [troubleshooting.md](troubleshooting.md)
## Optimization Quick Win
**Before (bloated)**:
**Before (bloated - 1500 tokens)**:
```markdown
This project is a comprehensive platform built with React, Node.js, Express,
PostgreSQL... [extensive paragraph explaining everything]
This project is a comprehensive platform built with React 18,
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
Tech Stack: React + Node.js + PostgreSQL
Tech Stack: React 18 + Node.js 20 + PostgreSQL 15
See @docs/architecture.md for details
```
@@ -151,38 +146,33 @@ For optimization patterns, see [patterns.md](patterns.md)
### ✓ Do
```markdown
# CLAUDE.md
Quick reference content
Quick reference
For detailed architecture: @docs/architecture.md
For API reference: @docs/api-reference.md
For architecture: @docs/architecture.md
For API details: @docs/api-reference.md
```
### ❌ Don't
```markdown
# CLAUDE.md
@docs/a.md → @docs/b.md → @docs/c.md → @docs/d.md → @docs/e.md → @docs/f.md
# Max depth is 5, avoid deep chains
# Deep chains (max depth = 5)
@docs/a.md → @docs/b.md → @docs/c.md → @docs/d.md → @docs/e.md
```
**Rules**:
- Max import depth: 5 levels
- No circular references
- Use relative paths for project files
- Keep import chains flat, not deep
- Keep chains flat, not deep
## Quick Update Methods
### Method 1: # Shortcut (Fastest)
```bash
# Press # at input start
# Type your update
# Auto-adds to appropriate CLAUDE.md
```
Press # at input start → type update → auto-adds to CLAUDE.md
```
### Method 2: /memory Command
```bash
/memory
# Opens memory management interface
```
/memory → Opens management interface
```
### Method 3: Direct Edit
@@ -194,7 +184,6 @@ vim CLAUDE.md
## Emphasis Techniques
For critical rules:
```markdown
IMPORTANT: [Critical rule]
YOU MUST [mandatory action]
@@ -203,25 +192,24 @@ NEVER [forbidden action]
ALL CAPS for maximum attention
```
## Testing Memory Effectiveness
## Testing Effectiveness
### Quick Test
```markdown
# Add temporary marker to CLAUDE.md
# Add temporary marker
**MEMORY TEST: If you see this, memory loaded correctly**
# Ask Claude: "What's the first line of your memory?"
# Should see marker, then remove it
```
## Team Setup Example
## Team Setup Pattern
```bash
# .gitignore
.claude/CLAUDE.local.md # Personal only
.claude/settings.local.json # Personal settings
# .claude/CLAUDE.md (in git)
# .claude/CLAUDE.md (in git - team standards)
# Team Standards
@docs/architecture.md
@@ -241,14 +229,36 @@ IMPORTANT: All team members follow these standards.
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
- [Optimization Patterns](patterns.md) - Advanced token-saving techniques
- [Team Workflows](workflows.md) - Collaboration strategies
- [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.

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

@@ -1,6 +1,6 @@
---
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
@@ -8,66 +8,55 @@ description: Create and structure Claude Code plugins with commands, agents, ski
## When to Use This Skill
Use this skill when:
- Creating a new Claude Code plugin from scratch
- Adding components to an existing plugin (commands, agents, skills, hooks)
- Configuring plugin manifests and metadata
- Setting up plugin distribution and marketplaces
- Troubleshooting plugin structure or installation issues
- Creating a new plugin from scratch
- Adding components to existing plugin
- Configuring plugin manifests
- Setting up distribution/marketplaces
- Packaging 3+ related commands/skills/agents
Do NOT use this skill for:
- Creating standalone MCP servers (use MCP-specific documentation)
- General Claude Code usage (not plugin development)
- Creating individual skills without plugin context
- Creating standalone MCP servers
- Single commands (use claude-commands skill)
- General Claude Code usage
## Quick Start: Creating a Plugin
## Quick Start
### 1. Basic Plugin Structure
```bash
# Create plugin directory
mkdir my-plugin
cd my-plugin
# Create required manifest directory
mkdir my-plugin && cd my-plugin
mkdir -p .claude-plugin
# Create plugin.json manifest
cat > .claude-plugin/plugin.json << 'EOF'
{
"name": "my-plugin",
"description": "Description of what your plugin does",
"description": "What your plugin does",
"version": "1.0.0",
"author": {
"name": "Your Name"
}
"author": {"name": "Your Name"}
}
EOF
# Add component directories
mkdir -p commands agents skills hooks
```
### 2. Add Component Directories
### 2. Test Installation
```bash
# Create directories for plugin components
mkdir -p commands # Slash commands
mkdir -p agents # Custom agents
mkdir -p skills # Agent Skills
mkdir -p hooks # Event handlers
/plugin install /path/to/my-plugin@local
/plugin list
```
**Result**: Basic plugin structure ready for adding components.
## Plugin Manifest (plugin.json)
### Required Fields
```json
{
"name": "plugin-name", // Lowercase, kebab-case
"description": "What it does", // Clear, concise description
"name": "plugin-name", // kebab-case
"description": "What it does", // Clear, concise
"version": "1.0.0", // Semantic versioning
"author": {
"name": "Author Name" // Your name or organization
}
"author": {"name": "Author"}
}
```
@@ -75,14 +64,6 @@ mkdir -p hooks # Event handlers
```json
{
"name": "my-plugin",
"description": "Advanced features",
"version": "1.2.0",
"author": {
"name": "Your Name",
"email": "you@example.com",
"url": "https://yoursite.com"
},
"repository": {
"type": "git",
"url": "https://github.com/user/repo"
@@ -94,200 +75,122 @@ mkdir -p hooks # Event handlers
## Plugin Components
### 1. Commands (Slash Commands)
### 1. Commands (commands/)
Create markdown files in `commands/` directory:
```bash
# commands/review-security.md
```markdown
# commands/review.md
---
description: Review code for security vulnerabilities
allowed-tools: Read(*), Grep(*)
description: Review code for issues
---
Review the following files for common security issues:
- SQL injection vulnerabilities
- XSS vulnerabilities
- Hardcoded credentials
- Unsafe deserialization
$ARGUMENTS
Review $ARGUMENTS for:
- Logic errors
- Style issues
```
**Usage**: `/review-security @src/auth.js`
**Usage**: `/review @file.js`
### 2. Agents
### 2. Agents (agents/)
Create agent configurations in `agents/` directory:
```bash
```markdown
# agents/code-reviewer.md
---
description: Reviews code for best practices
tools: [Read, Grep, Bash]
tools: [Read, Grep]
model: claude-sonnet-4
---
You are a code review specialist. When reviewing code:
1. Check for common patterns and anti-patterns
2. Verify error handling
3. Look for security issues
4. Suggest improvements
You are a code review specialist...
```
### 3. Skills
### 3. Skills (skills/)
Create skill directories in `skills/`:
```bash
mkdir -p skills/my-skill
# Then create skills/my-skill/SKILL.md with proper frontmatter
```
skills/
└── my-skill/
└── SKILL.md # With frontmatter
```
See the `claude-skills` skill for comprehensive skill creation guidance.
See claude-skills skill for details.
### 4. Hooks
Create `hooks/hooks.json` to define event handlers:
### 4. Hooks (hooks/hooks.json)
```json
{
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "echo 'File modified: $TOOL_ARGS' >> .claude/activity.log"
}
]
}
]
"PostToolUse": [{
"matcher": "Write|Edit",
"hooks": [{
"type": "command",
"command": "npx prettier --write $TOOL_ARGS"
}]
}]
}
```
### 5. MCP Servers
Create `.mcp.json` for external tools:
### 5. MCP Servers (.mcp.json)
```json
{
"mcpServers": {
"my-server": {
"command": "node",
"args": ["server.js"],
"env": {
"API_KEY": "env:MY_API_KEY"
}
"args": ["server.js"]
}
}
}
```
## Complete Plugin Example
## Directory Organization
See [examples.md](examples.md) for full working plugin examples including weather-plugin, git-tools, and api-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
**IMPORTANT**: Components at plugin root, NOT in `.claude-plugin/`
```
my-plugin/
├── .claude-plugin/ # Manifest only
│ └── plugin.json
├── commands/ # At plugin root, not in .claude-plugin/
├── agents/ # At plugin root
├── skills/ # At plugin root
└── README.md # Usage documentation
├── commands/ # At root
├── agents/ # At root
├── skills/ # At root
└── README.md
```
**IMPORTANT**: Component directories go at the plugin root, NOT inside `.claude-plugin/`
## Distribution
### Testing Checklist
- [ ] Plugin.json is valid JSON
- [ ] All required fields present
- [ ] Component directories at plugin root
- [ ] Commands have valid frontmatter
- [ ] Skills follow proper structure
- [ ] Local installation works
- [ ] No sensitive data in files
- [ ] README documents all features
### Version Management
### Local Testing
```bash
# Update version in plugin.json
{
"version": "1.1.0" // Increment for changes
}
/plugin install /path/to/plugin@local
```
# Breaking changes: 2.0.0
# New features: 1.1.0
# Bug fixes: 1.0.1
### Team Marketplace
```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
### Multi-Command Plugin
For related commands, use subdirectories:
```
git-tools/
├── .claude-plugin/plugin.json
@@ -297,11 +200,7 @@ git-tools/
└── review.md
```
**Usage**: `/commit`, `/pr`, `/review`
### Agent + Skill Combination
Combine agents with specialized skills:
### Agent + Skill Combo
```
api-plugin/
@@ -309,137 +208,83 @@ api-plugin/
├── agents/
│ └── api-specialist.md
└── skills/
└── rest-api/
└── SKILL.md
└── rest-api/SKILL.md
```
The agent can leverage the skill for specialized knowledge.
### Hook-Based Automation
Use hooks for workflow automation:
```json
{
"PostToolUse": [
{
"matcher": "Write",
"hooks": [
{
"type": "command",
"command": "npm run format $TOOL_ARGS"
}
]
}
]
"PostToolUse": [{
"matcher": "Write",
"hooks": [{
"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
### 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**:
1. Check marketplace configuration in settings.json
2. Verify plugin name matches directory name
3. Ensure plugin.json exists in `.claude-plugin/`
### Commands Not Available
**Issue**: Slash commands don't appear
**Solutions**:
1. Verify commands are in `commands/` at plugin root
2. Check markdown files have `.md` extension
3. Restart Claude Code to refresh
### Invalid Structure Error
**Issue**: Plugin fails to load
**Solutions**:
1. Ensure `.claude-plugin/plugin.json` exists
2. Validate JSON syntax
3. Move component directories to plugin root (not in `.claude-plugin/`)
## Security Considerations
### Never Include
- API keys or credentials in plugin files
- Personal identifying information
- Proprietary code without permission
- Hardcoded paths to user-specific locations
### Use Environment Variables
**Never include**:
- API keys or credentials
- Hardcoded secrets
- Personal paths
**Use environment variables**:
```json
// .mcp.json
{
"mcpServers": {
"api-server": {
"env": {
"API_KEY": "env:MY_API_KEY" // Reference env var
}
"api": {
"env": {"API_KEY": "env:MY_API_KEY"}
}
}
}
```
### 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
{
"name": "plugin-name",
"description": "What it does",
"version": "1.0.0",
"author": {"name": "Your Name"}
"version": "1.1.0" // Semantic versioning
}
// 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
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
@@ -10,94 +10,82 @@ description: Guide for creating effective Claude Agent Skills with best practice
Use this skill when:
- Creating a new Agent Skill from scratch
- Improving or refactoring an existing skill
- Debugging why a skill isn't triggering correctly
- Understanding skill architecture and design patterns
- Debugging why a skill isn't triggering
- Optimizing skill structure for token efficiency
- Before, during, and after skill creation
## 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)
- **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
### Three Layers
### Layer 2: Instructions (Triggered)
- **What**: Main SKILL.md content
- **When**: Loads when Claude determines skill applies
- **Cost**: Variable (keep focused and concise)
- **Purpose**: Procedural guidance, workflows, best practices
1. **Metadata** (Always Loaded ~100 tokens)
- YAML frontmatter: `name` and `description`
- Triggers skill activation
### Layer 3: Resources (On-Demand)
- **What**: Additional files, scripts, reference materials
- **When**: Only when explicitly needed
- **Cost**: Only when accessed
- **Purpose**: Deep reference, executable code, examples
2. **Instructions** (Triggered ~800-1000 tokens)
- Main SKILL.md content
- Workflows and guidance
3. **Resources** (On-Demand)
- Additional files loaded when needed
- Examples, reference docs, scripts
## Skill Structure Requirements
### Mandatory: SKILL.md File
Every skill MUST have a `SKILL.md` file with YAML frontmatter:
### Mandatory: SKILL.md
```yaml
---
name: Your Skill Name
description: Clear description of what this does and when to use it
name: Your Skill Name # Max 64 chars
description: What it does and when to use it # Max 1024 chars
---
```
**Critical Constraints:**
- Name: Maximum 64 characters
- Description: Maximum 1024 characters
- **The description is crucial** - it determines when Claude triggers the skill
**Critical**: The description determines when Claude triggers the skill.
### Optional: Additional Resources
Structure additional files strategically:
### Optional: Additional Files
```
my-skill/
├── SKILL.md # Main entry point (required)
├── reference.md # Deep reference material (load on-demand)
├── examples.md # Code samples and templates
├── workflows/ # Step-by-step procedures
│ ├── advanced.md
│ └── beginner.md
└── scripts/ # Executable utilities
└── helper.sh
├── SKILL.md # Required entry point
├── examples.md # Working code samples
├── reference.md # Deep API docs
└── workflows/
├── beginner.md
└── advanced.md
```
## 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 for Descriptions
The `description` is your trigger mechanism.
### Template
```
[Action verb] [specific domain/task] [with/for/using] [key capabilities].
Use when [primary trigger scenario] [and optional secondary scenarios].
[Action] [domain/task] [with capabilities].
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
## When to Use This Skill
@@ -105,142 +93,126 @@ Immediately clarify trigger scenarios:
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]
- [Common confusion]
- [Different tool]
```
### 2. Structure for Scannability
Use clear hierarchies and action-oriented headers:
### 2. Quick Start
```markdown
## Quick Start
[Minimal example to get started]
Minimal working example:
```[language]
[code]
```
**Result**: [What this achieves]
```
### 3. Core Workflows
```markdown
## Core Workflows
### Workflow 1: [Name]
1. Step one
2. Step two
### Workflow 2: [Name]
1. Step one
2. Step two
1. [Step]
2. [Step]
3. [Step]
## Advanced Techniques
[Less common but powerful approaches]
## Common Pitfalls
[Known issues and how to avoid them]
**Example**:
```[language]
[code]
```
```
### 3. Include Concrete Examples
Always provide working examples, not abstract descriptions:
### 4. Additional Resources
```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**:
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
💡 **Tip**: These load only when referenced.
```
### 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
## Deep Dive: Advanced Patterns
### When to Split
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
**Keep in SKILL.md if:**
- Information is 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 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.
1. **Bullet points > Paragraphs** (50% more efficient)
2. **Code examples > Prose** (show don't tell)
3. **References > Embedding** (load on-demand)
4. **Concrete > Abstract** (examples beat theory)
## 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
2. Identify where it struggles or asks repetitive questions
3. Capture successful patterns from those sessions
4. Codify into a skill
2. Find repeated questions or struggles
3. Capture successful patterns
4. Codify into skill
### 2. Iterate with Claude
### 2. Start Minimal
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
```yaml
---
name: My Skill
description: [Specific, clear trigger description]
---
### 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:**
- Direct requests that SHOULD trigger it
- Similar requests that SHOULD trigger it
- Related requests that should NOT trigger it
## Core Workflow
[3-5 essential steps]
```
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:
- Clear metadata
- One core workflow
- A few examples
**Negative tests** (should NOT activate):
- "[Related but different domain]"
- "[Different tool's purpose]"
Add complexity only when you encounter actual needs:
- Split files when SKILL.md exceeds ~3000 tokens
- Add scripts when you repeat the same commands
- Create reference files for API documentation
### 4. Grow Organically
Add only when needed:
- More examples from actual usage
- Advanced workflows when requested
- Reference docs when API is complex
- Scripts for repeated commands
## Common Patterns by Domain
@@ -248,28 +220,25 @@ Add complexity only when you encounter actual needs:
```markdown
---
name: [Framework/Language] [Pattern] Guide
description: [Action] [framework] applications following [specific pattern/principles]. Use when building [type of apps] with [key requirements].
name: [Framework] [Pattern] Guide
description: [Action] [framework] applications following [pattern]. Use when building [type] with [requirements].
---
## When to Use This Skill
Use when building [specific project type] with [language/framework]
[Specific project types]
## Project Structure
[Standard directory layout]
[Standard layout]
## Core Workflows
### Create New [Component Type]
[Step-by-step process]
### Common Patterns
[Frequently used code patterns with examples]
### Create [Component]
[Steps]
## Testing Strategy
[How to test this type of code]
[How to test]
```
### Workflow/Process Skills
### Workflow Skills
```markdown
---
@@ -277,135 +246,71 @@ name: [Task] Workflow
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
[What's needed before starting]
[What's needed]
## Step-by-Step Process
### Phase 1: [Name]
[Detailed steps]
### Phase 2: [Name]
[Detailed steps]
[Steps]
## Quality Checklist
- [ ] [Verification step]
- [ ] [Verification step]
- [ ] [Verification]
```
### 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
### Skill Doesn't Trigger
**Checklist:**
1. Is the description specific enough?
2. Does the description mention the trigger scenario?
3. Is the name too generic?
4. Test with explicit requests mentioning keywords from the description
**Fix description**:
```yaml
# ❌ Too vague
description: Python development helpers
**Example fix:**
- Before: `description: "Python development helpers"`
- After: `description: "Create Python projects using Hatch and Hatchling for dependency management. Use when initializing new Python packages or configuring build systems."`
# ✓ Specific with triggers
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
**Checklist:**
1. Is the description too broad?
2. Add negative cases: "Do NOT use for..."
3. Make the domain more specific
**Add negatives**:
```markdown
## When to Use This Skill
Use when:
- [Specific scenario]
Do NOT use for:
- [Broader scenario that should use different skill]
```
### Content Doesn't Load
**Checklist:**
1. Verify file paths in references are correct
2. Check that additional .md files are in the skill package
3. Ensure script paths are relative to skill root
**Check references**:
- Verify file paths are correct
- Ensure .md files exist in skill directory
- Use relative paths from skill root
## Skill Metadata Checklist
## Skill Checklist
Before finalizing a skill, verify:
Before finalizing:
- [ ] Name is under 64 characters
- [ ] Description is under 1024 characters
- [ ] Description includes specific use cases
- [ ] Description mentions when to trigger the skill
- [ ] SKILL.md has YAML frontmatter with both fields
- [ ] "When to Use This Skill" section is present
- [ ] At least one concrete example is included
- [ ] No sensitive information is hardcoded
- [ ] File references are accurate
- [ ] Tested triggering with target scenarios
- [ ] 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
- [ ] Name under 64 characters
- [ ] Description under 1024 characters, includes triggers
- [ ] SKILL.md has YAML frontmatter
- [ ] "When to Use This Skill" section present
- [ ] At least one concrete example
- [ ] No sensitive information
- [ ] File references work
- [ ] Tested positive trigger scenarios
- [ ] Tested negative scenarios (doesn't over-trigger)
- [ ] Size under 1000 tokens for SKILL.md
## Quick Start Template
Use this template to begin a new skill:
```markdown
---
name:
description:
name: [Skill Name]
description: [Action] [domain] [with capabilities]. Use when [scenario]. PROACTIVELY when [context].
---
# [Skill Name]
@@ -413,11 +318,11 @@ description:
## When to Use This Skill
Use this skill when:
-
-
- [Primary scenario]
- [Secondary scenario]
Do NOT use this skill for:
-
- [Common confusion]
## Quick Start
@@ -427,30 +332,43 @@ Do NOT use this skill for:
### Workflow 1: [Name]
1.
2.
3.
1. [Step]
2. [Step]
3. [Step]
**Example:**
**Example**:
```
[Code or command]
[code]
```
**Result:** [What this achieves]
**Result**: [What this achieves]
## Common Pitfalls
### Issue: [Problem]
**Solution:** [How to avoid/fix]
**Solution**: [Fix]
### Issue: [Problem]
**Solution:** [How to avoid/fix]
## Additional Resources
## 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
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
@@ -8,31 +8,30 @@ description: Refine and troubleshoot Claude Code subagents by optimizing prompts
## When to Use This Skill
Use this skill when:
- Refining existing subagent prompts for better performance
- Troubleshooting why a subagent isn't activating
- Refining existing subagent prompts
- Troubleshooting activation issues
- Optimizing tool access and permissions
- Improving subagent descriptions for better delegation
- Debugging context management issues
- Converting ad-hoc workflows to reusable subagents
- Improving delegation patterns
- Converting ad-hoc workflows to subagents
Do NOT use this skill for:
- **Initial creation** - Use `/agents` command instead (interactive UI)
- Creating slash commands (use claude-command-expert skill)
- General Claude Code troubleshooting
- **Initial creation** - Use `/agents` command
- Creating slash commands (use claude-commands skill)
- 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
```yaml
---
name: agent-name # Lowercase, kebab-case
description: When to use # Triggers automatic delegation
name: agent-name # kebab-case
description: When to use # Triggers delegation
tools: Tool1, Tool2 # Optional: omit to inherit all
model: sonnet # Optional: sonnet/opus/haiku/inherit
---
System prompt defining role, capabilities, and behavior.
System prompt defining role, capabilities, behavior.
```
**Locations**:
@@ -44,31 +43,29 @@ System prompt defining role, capabilities, and behavior.
### Problem 1: Subagent Never Activates
**Diagnosis**: Check description specificity
**Diagnosis**: Vague description
```yaml
# ❌ Too vague (ignored)
# ❌ Too vague
---
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.
---
```
**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
**Diagnosis**: Check tool configuration
```yaml
# ❌ Too permissive
# ❌ Too permissive (inherits all)
---
name: security-analyzer
# (inherits all tools)
# (no tools field)
---
# ✓ Restricted to needs
@@ -79,21 +76,21 @@ tools: Read, Grep, Glob
```
**Tool Access Strategies**:
- **Inherit All**: Omit `tools` field (full flexibility)
- **Read-Only**: `tools: Read, Grep, Glob` (analysis/review)
- **Specific**: `tools: Read, Write, Edit, Bash(npm test:*)` (implementation)
- **No Files**: `tools: WebFetch, WebSearch` (research only)
- **Inherit All**: Omit `tools` field
- **Read-Only**: `tools: Read, Grep, Glob`
- **Specific**: `tools: Read, Write, Edit, Bash(npm test:*)`
- **Research**: `tools: WebFetch, WebSearch`
### Problem 3: Poor Output Quality
**Diagnosis**: System prompt needs structure
**Diagnosis**: Needs structured prompt
```markdown
# ❌ Vague
You review code for issues.
# ✓ 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
1. **Logic & Correctness**: Verify algorithms, edge cases
@@ -113,13 +110,13 @@ For each issue:
- 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
### Template
```yaml
description: [Action verb] [domain/task] [including capabilities]. Use [trigger]. PROACTIVELY when [scenario].
description: [Action] [domain] [including capabilities]. Use [trigger]. PROACTIVELY when [scenario].
```
### Examples
@@ -140,17 +137,15 @@ description: Python utilities
description: Security checker
```
## Model Selection Guide
## Model Selection
| Model | Use For | Avoid For |
|-------|---------|-----------|
| haiku | Simple transforms, quick checks | Complex reasoning, creativity |
| sonnet | General tasks, balanced quality | When opus needed |
| opus | Complex architecture, creative work | Simple/repetitive (costly) |
| haiku | Simple transforms, quick checks | Complex reasoning |
| sonnet | General tasks (default) | When opus needed |
| opus | Complex architecture, creative work | Simple tasks (costly) |
| inherit | Task matches main thread | Need different capability |
**Default**: sonnet (best balance)
## Testing Subagents
### Test Plan Template
@@ -161,25 +156,17 @@ description: Security checker
Expected: Activates
Actual: ___
2. "Add GraphQL mutation for profile"
Expected: Activates
Actual: ___
# Negative Tests (Should NOT Activate)
1. "Write unit tests for API"
Expected: Does not activate (testing concern)
Actual: ___
2. "Review API security"
Expected: Does not activate (security concern)
Expected: Does not activate (different concern)
Actual: ___
## Results
- Precision: X% (correct activations / total activations)
- Recall: Y% (correct activations / should activate)
- Precision: X%
- Recall: Y%
```
For complete testing strategies, see [testing.md](testing.md)
For complete testing, see [testing.md](testing.md)
## System Prompt Structure
@@ -190,62 +177,25 @@ You are a [role] specializing in [domain].
## Responsibilities
1. [Primary responsibility]
2. [Secondary responsibility]
3. [Additional responsibilities]
## Process
1. [Step 1]
2. [Step 2]
3. [Step 3]
## Output Format
[Specific structure required]
## Examples
### Good Example
[Show what good looks like]
### Bad Example
[Show what to avoid]
## Constraints
- [Important limitation]
- [Another constraint]
```
## Optimization Patterns
### Pattern 1: Role-Based Pipeline
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
### Domain Specialists
```yaml
# Frontend Specialist
@@ -255,7 +205,7 @@ description: React/TypeScript UI development and component design. Use PROACTIVE
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
- React 18+ with hooks
@@ -267,96 +217,86 @@ You are a React/TypeScript expert specializing in modern frontend development.
- Functional components only
- Custom hooks for logic reuse
- 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
When subagent doesn't work as expected:
When subagent doesn't work:
```markdown
- [ ] Description is specific and includes trigger words
- [ ] Description includes "PROACTIVELY" or "MUST BE USED" if needed
- [ ] Description is specific with trigger words
- [ ] Description includes "PROACTIVELY" if needed
- [ ] System prompt defines role clearly
- [ ] System prompt includes process/steps
- [ ] System prompt specifies output format
- [ ] System prompt has examples
- [ ] Tools match required capabilities
- [ ] Tools follow least-privilege principle
- [ ] Model appropriate for task complexity
- [ ] File location correct (.claude/agents/)
- [ ] Model appropriate for complexity
- [ ] File in `.claude/agents/`
- [ ] YAML frontmatter valid
- [ ] Name uses kebab-case
- [ ] Tested with 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
- [ ] Tested positive/negative scenarios
## Migration: Ad-Hoc to Subagent
### When to Migrate
- Used same prompt 3+ times
- Prompt has clear pattern/structure
- Prompt has clear pattern
- Task benefits from isolation
- Multiple team members need it
### Process
**Step 1: Extract Pattern**
```markdown
```
# Repeated prompts:
1. "Review auth.js for security issues"
1. "Review auth.js for security"
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**
```yaml
---
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
---
```
**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
- [Testing Strategies](testing.md) - Comprehensive testing guide
- [Testing Strategies](testing.md) - Comprehensive testing
- [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.