Skill refresh
This commit is contained in:
movq
@@ -1,13 +1,14 @@
|
||||
{
|
||||
"name": "claude-code",
|
||||
"description": "Comprehensive skills for mastering Claude Code features: plugins, slash commands, hooks, subagents, and memory management",
|
||||
"version": "1.0.0",
|
||||
"description": "Comprehensive skills for mastering Claude Code features: plugins, skills, slash commands, hooks, subagents, and memory management",
|
||||
"version": "1.1.0",
|
||||
"author": {
|
||||
"name": "Claude Skills Contributors"
|
||||
},
|
||||
"keywords": [
|
||||
"claude-code",
|
||||
"plugins",
|
||||
"skills",
|
||||
"slash-commands",
|
||||
"hooks",
|
||||
"subagents",
|
||||
|
||||
@@ -6,7 +6,7 @@ Comprehensive skills for mastering Claude Code features including plugins, slash
|
||||
|
||||
This plugin provides five specialized skills that help you work more effectively with Claude Code:
|
||||
|
||||
### 1. claude-code-plugins
|
||||
### 1. claude-plugins
|
||||
Create and structure Claude Code plugins with commands, agents, skills, hooks, and MCP servers.
|
||||
|
||||
**Use when:**
|
||||
@@ -14,7 +14,7 @@ Create and structure Claude Code plugins with commands, agents, skills, hooks, a
|
||||
- Setting up plugin structure
|
||||
- Configuring plugin manifests
|
||||
|
||||
### 2. claude-code-slash-commands
|
||||
### 2. claude-commands
|
||||
Create custom slash commands with argument handling, bash execution, and file references.
|
||||
|
||||
**Use when:**
|
||||
@@ -22,7 +22,7 @@ Create custom slash commands with argument handling, bash execution, and file re
|
||||
- Automating workflows
|
||||
- Creating project-specific commands
|
||||
|
||||
### 3. claude-code-hooks
|
||||
### 3. claude-hooks
|
||||
Configure event-driven hooks for automating workflows, validating code, and controlling tool execution.
|
||||
|
||||
**Use when:**
|
||||
@@ -31,7 +31,7 @@ Configure event-driven hooks for automating workflows, validating code, and cont
|
||||
- Injecting context
|
||||
- Integrating external tools
|
||||
|
||||
### 4. claude-code-subagents
|
||||
### 4. claude-subagents
|
||||
Refine and troubleshoot Claude Code subagents by optimizing prompts, tool access, and delegation patterns.
|
||||
|
||||
**Use when:**
|
||||
@@ -39,7 +39,7 @@ Refine and troubleshoot Claude Code subagents by optimizing prompts, tool access
|
||||
- Debugging activation issues
|
||||
- Optimizing performance
|
||||
|
||||
### 5. claude-code-memory
|
||||
### 5. claude-memory
|
||||
Optimize and troubleshoot Claude Code memory files (CLAUDE.md) for efficiency, token management, and team collaboration.
|
||||
|
||||
**Use when:**
|
||||
@@ -75,11 +75,11 @@ Or install from local directory:
|
||||
|
||||
Once installed, these skills activate automatically when you work on related tasks:
|
||||
|
||||
- **Working on a plugin?** → claude-code-plugins skill activates
|
||||
- **Creating slash commands?** → claude-code-slash-commands skill activates
|
||||
- **Setting up hooks?** → claude-code-hooks skill activates
|
||||
- **Refining a subagent?** → claude-code-subagents skill activates
|
||||
- **Troubleshooting CLAUDE.md?** → claude-code-memory skill activates
|
||||
- **Working on a plugin?** → claude-plugins skill activates
|
||||
- **Creating slash commands?** → claude-commands skill activates
|
||||
- **Setting up hooks?** → claude-hooks skill activates
|
||||
- **Refining a subagent?** → claude-subagents skill activates
|
||||
- **Troubleshooting CLAUDE.md?** → claude-memory skill activates
|
||||
|
||||
You can also explicitly reference skills:
|
||||
```
|
||||
@@ -90,7 +90,7 @@ You can also explicitly reference skills:
|
||||
|
||||
## Skills Details
|
||||
|
||||
### claude-code-plugins
|
||||
### claude-plugins
|
||||
|
||||
**Covers:**
|
||||
- Plugin manifest configuration (plugin.json)
|
||||
@@ -98,9 +98,9 @@ You can also explicitly reference skills:
|
||||
- Distribution and marketplace publishing
|
||||
- Best practices and troubleshooting
|
||||
|
||||
[View Details](./skills/claude-code-plugins/SKILL.md)
|
||||
[View Details](./skills/claude-plugins/SKILL.md)
|
||||
|
||||
### claude-code-slash-commands
|
||||
### claude-commands
|
||||
|
||||
**Covers:**
|
||||
- Command syntax and frontmatter options
|
||||
@@ -109,9 +109,9 @@ You can also explicitly reference skills:
|
||||
- File references with @ prefix
|
||||
- Complete examples and patterns
|
||||
|
||||
[View Details](./skills/claude-code-slash-commands/SKILL.md)
|
||||
[View Details](./skills/claude-commands/SKILL.md)
|
||||
|
||||
### claude-code-hooks
|
||||
### claude-hooks
|
||||
|
||||
**Covers:**
|
||||
- All hook types (SessionStart, PreToolUse, PostToolUse, etc.)
|
||||
@@ -120,9 +120,9 @@ You can also explicitly reference skills:
|
||||
- Environment variables
|
||||
- Complete working examples
|
||||
|
||||
[View Details](./skills/claude-code-hooks/SKILL.md)
|
||||
[View Details](./skills/claude-hooks/SKILL.md)
|
||||
|
||||
### claude-code-subagents
|
||||
### claude-subagents
|
||||
|
||||
**Covers:**
|
||||
- Common problems and solutions
|
||||
@@ -132,9 +132,9 @@ You can also explicitly reference skills:
|
||||
- Testing and validation
|
||||
- Migration from ad-hoc prompts
|
||||
|
||||
[View Details](./skills/claude-code-subagents/SKILL.md)
|
||||
[View Details](./skills/claude-subagents/SKILL.md)
|
||||
|
||||
### claude-code-memory
|
||||
### claude-memory
|
||||
|
||||
**Covers:**
|
||||
- Memory hierarchy (project/user/subfolder)
|
||||
@@ -144,7 +144,7 @@ You can also explicitly reference skills:
|
||||
- Troubleshooting loading issues
|
||||
- Template examples
|
||||
|
||||
[View Details](./skills/claude-code-memory/SKILL.md)
|
||||
[View Details](./skills/claude-memory/SKILL.md)
|
||||
|
||||
## Best Practices
|
||||
|
||||
@@ -176,18 +176,18 @@ Start with one skill at a time:
|
||||
- Try explicit skill references in prompts
|
||||
|
||||
**Need help with specific features?**
|
||||
- Memory issues → Use claude-code-memory skill
|
||||
- Subagent problems → Use claude-code-subagents skill
|
||||
- Hook debugging → Use claude-code-hooks skill
|
||||
- Memory issues → Use claude-memory skill
|
||||
- Subagent problems → Use claude-subagents skill
|
||||
- Hook debugging → Use claude-hooks skill
|
||||
|
||||
## Version History
|
||||
|
||||
### 1.0.0 (Initial Release)
|
||||
- claude-code-plugins skill
|
||||
- claude-code-slash-commands skill
|
||||
- claude-code-hooks skill
|
||||
- claude-code-subagents skill
|
||||
- claude-code-memory skill
|
||||
- claude-plugins skill
|
||||
- claude-slash-commands skill
|
||||
- claude-hooks skill
|
||||
- claude-subagents skill
|
||||
- claude-memory skill
|
||||
|
||||
## Contributing
|
||||
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
@@ -1,698 +0,0 @@
|
||||
---
|
||||
name: Slash Command Creator
|
||||
description: Create custom slash commands for Claude Code with argument handling, bash execution, and file references. Use when building reusable prompts, automating workflows, or creating project-specific commands.
|
||||
---
|
||||
|
||||
# Slash Command Development
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
Use this skill when:
|
||||
- Creating custom slash commands for Claude Code
|
||||
- Building reusable prompt templates
|
||||
- Automating repetitive tasks with commands
|
||||
- Setting up project-specific workflows
|
||||
- Converting manual prompts to slash commands
|
||||
|
||||
Do NOT use this skill for:
|
||||
- Creating full plugins (use claude-code-plugins skill)
|
||||
- Setting up hooks (use claude-code-hooks skill)
|
||||
- General Claude Code usage
|
||||
|
||||
## Quick Start: Creating a Command
|
||||
|
||||
### 1. Create Command File
|
||||
|
||||
```bash
|
||||
# Project-specific command (shared with team)
|
||||
mkdir -p .claude/commands
|
||||
cat > .claude/commands/review.md << 'EOF'
|
||||
---
|
||||
description: Review code for common issues
|
||||
---
|
||||
|
||||
Review the following code for:
|
||||
- Bugs and logic errors
|
||||
- Code style issues
|
||||
- Performance problems
|
||||
- Security vulnerabilities
|
||||
|
||||
$ARGUMENTS
|
||||
EOF
|
||||
```
|
||||
|
||||
**Usage**: `/review @src/main.js`
|
||||
|
||||
### 2. Personal Command (Your Use Only)
|
||||
|
||||
```bash
|
||||
# Personal command (not shared)
|
||||
mkdir -p ~/.claude/commands
|
||||
cat > ~/.claude/commands/explain.md << 'EOF'
|
||||
---
|
||||
description: Explain code in detail
|
||||
argument-hint: <file-path>
|
||||
---
|
||||
|
||||
Provide a detailed explanation of: $ARGUMENTS
|
||||
|
||||
Include:
|
||||
- What the code does
|
||||
- How it works
|
||||
- Key design decisions
|
||||
- Potential improvements
|
||||
EOF
|
||||
```
|
||||
|
||||
**Usage**: `/explain @utils/parser.ts`
|
||||
|
||||
## Command Locations
|
||||
|
||||
### Project Commands (.claude/commands/)
|
||||
|
||||
**Location**: `.claude/commands/` in your project
|
||||
**Scope**: Available to everyone working on the project
|
||||
**Version Control**: Commit to git for team sharing
|
||||
**Use For**: Project-specific workflows, team standards
|
||||
|
||||
### Personal Commands (~/.claude/commands/)
|
||||
|
||||
**Location**: `~/.claude/commands/`
|
||||
**Scope**: Available in all your projects
|
||||
**Version Control**: Not in git (user-specific)
|
||||
**Use For**: Personal productivity, custom preferences
|
||||
|
||||
## Command Syntax
|
||||
|
||||
### Basic Structure
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Brief description for /help
|
||||
---
|
||||
|
||||
Prompt content here
|
||||
```
|
||||
|
||||
### Command Name
|
||||
|
||||
The filename (without `.md`) becomes the command:
|
||||
|
||||
```bash
|
||||
# File: .claude/commands/test.md
|
||||
# Command: /test
|
||||
|
||||
# File: .claude/commands/commit-push.md
|
||||
# Command: /commit-push
|
||||
```
|
||||
|
||||
## Frontmatter Options
|
||||
|
||||
### description
|
||||
|
||||
Shows in `/help` output:
|
||||
|
||||
```yaml
|
||||
---
|
||||
description: Generate unit tests for a function
|
||||
---
|
||||
```
|
||||
|
||||
### argument-hint
|
||||
|
||||
Shows expected arguments in autocomplete:
|
||||
|
||||
```yaml
|
||||
---
|
||||
description: Compare two files
|
||||
argument-hint: <file1> <file2>
|
||||
---
|
||||
```
|
||||
|
||||
### allowed-tools
|
||||
|
||||
Specifies which tools the command can use:
|
||||
|
||||
```yaml
|
||||
---
|
||||
description: Review and commit changes
|
||||
allowed-tools: Bash(git status:*), Bash(git add:*), Bash(git commit:*)
|
||||
---
|
||||
```
|
||||
|
||||
**Patterns**:
|
||||
- `Bash(git status:*)` - Specific command with any args
|
||||
- `Read(*)` - Tool with any args
|
||||
- `*` - All tools allowed
|
||||
|
||||
### model
|
||||
|
||||
Override default model for this command:
|
||||
|
||||
```yaml
|
||||
---
|
||||
description: Simple task
|
||||
model: claude-haiku-4
|
||||
---
|
||||
```
|
||||
|
||||
### disable-model-invocation
|
||||
|
||||
Prevent SlashCommand tool from calling this:
|
||||
|
||||
```yaml
|
||||
---
|
||||
description: Internal helper command
|
||||
disable-model-invocation: true
|
||||
---
|
||||
```
|
||||
|
||||
## Argument Handling
|
||||
|
||||
### $ARGUMENTS - All Arguments
|
||||
|
||||
Captures everything passed to the command:
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Explain multiple files
|
||||
---
|
||||
|
||||
Explain these files: $ARGUMENTS
|
||||
```
|
||||
|
||||
**Usage**: `/explain @src/a.js @src/b.js @src/c.js`
|
||||
**Result**: All three file paths captured
|
||||
|
||||
### Positional Arguments ($1, $2, $3...)
|
||||
|
||||
Individual arguments like shell scripts:
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Compare two approaches
|
||||
argument-hint: <approach1> <approach2>
|
||||
---
|
||||
|
||||
Compare approach "$1" versus "$2" and recommend which is better.
|
||||
```
|
||||
|
||||
**Usage**: `/compare REST GraphQL`
|
||||
**$1** = "REST"
|
||||
**$2** = "GraphQL"
|
||||
|
||||
### Combining Arguments
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Test specific function
|
||||
argument-hint: <file> <function-name>
|
||||
---
|
||||
|
||||
In file $1, create comprehensive tests for the function: $2
|
||||
|
||||
$ARGUMENTS
|
||||
```
|
||||
|
||||
## File References with @
|
||||
|
||||
### Single File
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Review a file
|
||||
---
|
||||
|
||||
Review @$1 for code quality issues.
|
||||
```
|
||||
|
||||
**Usage**: `/review src/auth.js`
|
||||
Claude will read `src/auth.js` automatically
|
||||
|
||||
### Multiple Files
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Compare implementations
|
||||
---
|
||||
|
||||
Compare the implementation approaches in:
|
||||
$ARGUMENTS
|
||||
|
||||
Which approach is better and why?
|
||||
```
|
||||
|
||||
**Usage**: `/compare @old/version.js @new/version.js`
|
||||
|
||||
### Inline File References
|
||||
|
||||
```markdown
|
||||
Review @src/config.js and ensure it follows @docs/style-guide.md
|
||||
```
|
||||
|
||||
The `@` prefix tells Claude to read those files before processing.
|
||||
|
||||
## Bash Execution with !
|
||||
|
||||
### Prefix Commands with !
|
||||
|
||||
Run bash before the slash command executes:
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Show git status and suggest next steps
|
||||
allowed-tools: Bash(git status:*), Bash(git diff:*)
|
||||
---
|
||||
|
||||
!git status
|
||||
!git diff --stat
|
||||
|
||||
Based on the current git state, suggest what I should do next.
|
||||
```
|
||||
|
||||
**Important**: Must include `allowed-tools` with Bash tool specification.
|
||||
|
||||
### Why Use ! Prefix?
|
||||
|
||||
Without `!`, bash commands are just text in the prompt.
|
||||
With `!`, they execute and results are included in context.
|
||||
|
||||
```markdown
|
||||
# This doesn't work (just text):
|
||||
git status
|
||||
What should I commit?
|
||||
|
||||
# This works (executes first):
|
||||
---
|
||||
allowed-tools: Bash(git status:*)
|
||||
---
|
||||
|
||||
!git status
|
||||
What should I commit?
|
||||
```
|
||||
|
||||
## Namespacing with Directories
|
||||
|
||||
### Organize Related Commands
|
||||
|
||||
```
|
||||
.claude/commands/
|
||||
├── git/
|
||||
│ ├── commit.md
|
||||
│ ├── review.md
|
||||
│ └── sync.md
|
||||
└── test/
|
||||
├── unit.md
|
||||
└── integration.md
|
||||
```
|
||||
|
||||
**Commands**: `/commit`, `/review`, `/sync`, `/unit`, `/integration`
|
||||
|
||||
**Note**: Directory structure is for organization only - it doesn't affect command names.
|
||||
|
||||
## Complete Examples
|
||||
|
||||
### 1. Security Review Command
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Comprehensive security review of code files
|
||||
allowed-tools: Read(*), Grep(*), Bash(grep:*)
|
||||
argument-hint: <files...>
|
||||
---
|
||||
|
||||
Perform a security audit on: $ARGUMENTS
|
||||
|
||||
Check for:
|
||||
1. SQL injection vulnerabilities
|
||||
2. XSS vulnerabilities
|
||||
3. Authentication/authorization issues
|
||||
4. Hardcoded secrets or credentials
|
||||
5. Unsafe deserialization
|
||||
6. Path traversal vulnerabilities
|
||||
7. Insecure cryptography
|
||||
8. Information disclosure
|
||||
|
||||
For each issue found:
|
||||
- Severity level (Critical/High/Medium/Low)
|
||||
- Location (file:line)
|
||||
- Explanation of the vulnerability
|
||||
- Recommended fix with code example
|
||||
```
|
||||
|
||||
**Usage**: `/security-review @src/auth.js @src/api.js`
|
||||
|
||||
### 2. Commit + Push Command
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Review changes, commit, and push to remote
|
||||
allowed-tools: Bash(git:*)
|
||||
---
|
||||
|
||||
!git status
|
||||
!git diff
|
||||
|
||||
Review the changes above and:
|
||||
1. Create an appropriate commit message
|
||||
2. Commit the changes
|
||||
3. Push to remote
|
||||
|
||||
Ask for confirmation before pushing.
|
||||
```
|
||||
|
||||
**Usage**: `/commit-push`
|
||||
|
||||
### 3. Test Generator
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Generate comprehensive tests for a function
|
||||
argument-hint: <file> <function-name>
|
||||
model: claude-sonnet-4
|
||||
---
|
||||
|
||||
For the function "$2" in @$1:
|
||||
|
||||
1. Analyze the function's behavior
|
||||
2. Identify edge cases
|
||||
3. Generate comprehensive unit tests including:
|
||||
- Happy path tests
|
||||
- Edge case tests
|
||||
- Error condition tests
|
||||
- Boundary value tests
|
||||
|
||||
Use the project's existing test framework and patterns.
|
||||
```
|
||||
|
||||
**Usage**: `/test-gen src/parser.js parseQuery`
|
||||
|
||||
### 4. API Documentation
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Generate API documentation for endpoints
|
||||
allowed-tools: Read(*), Grep(*)
|
||||
---
|
||||
|
||||
Generate API documentation for: $ARGUMENTS
|
||||
|
||||
Include:
|
||||
- Endpoint URL and method
|
||||
- Request parameters (query, body, headers)
|
||||
- Response format and status codes
|
||||
- Example requests and responses
|
||||
- Error conditions
|
||||
- Authentication requirements
|
||||
|
||||
Format as OpenAPI/Swagger compatible YAML.
|
||||
```
|
||||
|
||||
**Usage**: `/api-docs @routes/users.js @routes/posts.js`
|
||||
|
||||
### 5. Performance Analysis
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Analyze code for performance issues
|
||||
argument-hint: <file>
|
||||
---
|
||||
|
||||
Analyze @$1 for performance issues:
|
||||
|
||||
1. **Time Complexity**: Identify algorithms and their complexity
|
||||
2. **Space Complexity**: Memory usage patterns
|
||||
3. **Bottlenecks**: Potential performance problems
|
||||
4. **Optimization Opportunities**: Specific improvements with examples
|
||||
|
||||
For each issue:
|
||||
- Current implementation
|
||||
- Why it's problematic
|
||||
- Optimized version
|
||||
- Performance impact estimate
|
||||
```
|
||||
|
||||
**Usage**: `/perf @src/data-processor.js`
|
||||
|
||||
## Command Patterns
|
||||
|
||||
### Review Pattern
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Review X for Y
|
||||
---
|
||||
|
||||
Review $ARGUMENTS for [specific criteria]
|
||||
|
||||
Include:
|
||||
- [Aspect 1]
|
||||
- [Aspect 2]
|
||||
- [Aspect 3]
|
||||
```
|
||||
|
||||
### Generate Pattern
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Generate X from Y
|
||||
---
|
||||
|
||||
Generate [output type] for: $ARGUMENTS
|
||||
|
||||
Requirements:
|
||||
- [Requirement 1]
|
||||
- [Requirement 2]
|
||||
```
|
||||
|
||||
### Compare Pattern
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Compare X and Y
|
||||
argument-hint: <option1> <option2>
|
||||
---
|
||||
|
||||
Compare "$1" versus "$2"
|
||||
|
||||
Analyze:
|
||||
- [Comparison aspect 1]
|
||||
- [Comparison aspect 2]
|
||||
|
||||
Recommendation: [Which is better and why]
|
||||
```
|
||||
|
||||
### Workflow Pattern
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Execute multi-step workflow
|
||||
allowed-tools: Bash(*), Read(*), Write(*)
|
||||
---
|
||||
|
||||
Execute the following workflow:
|
||||
|
||||
1. [Step 1]
|
||||
2. [Step 2]
|
||||
3. [Step 3]
|
||||
|
||||
After each step, confirm before proceeding.
|
||||
```
|
||||
|
||||
## Testing Commands
|
||||
|
||||
### 1. Check Command List
|
||||
|
||||
```bash
|
||||
# See all available commands
|
||||
/help
|
||||
|
||||
# Your command should appear in the list
|
||||
```
|
||||
|
||||
### 2. Test Argument Handling
|
||||
|
||||
```bash
|
||||
# Test with different argument patterns
|
||||
/mycommand arg1
|
||||
/mycommand arg1 arg2
|
||||
/mycommand @file.js
|
||||
/mycommand @file1.js @file2.js
|
||||
```
|
||||
|
||||
### 3. Verify Bash Execution
|
||||
|
||||
If using `!` prefix, confirm commands execute:
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Test bash execution
|
||||
allowed-tools: Bash(echo:*)
|
||||
---
|
||||
|
||||
!echo "This should show before prompt processing"
|
||||
|
||||
Did the echo work?
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Clear Descriptions
|
||||
|
||||
```yaml
|
||||
# Good
|
||||
description: Generate unit tests for a specific function
|
||||
|
||||
# Bad
|
||||
description: Testing
|
||||
```
|
||||
|
||||
### 2. Explicit Arguments
|
||||
|
||||
```yaml
|
||||
# Good
|
||||
argument-hint: <file-path> <function-name>
|
||||
|
||||
# Bad (no hint)
|
||||
argument-hint:
|
||||
```
|
||||
|
||||
### 3. Specific Tool Permissions
|
||||
|
||||
```yaml
|
||||
# Good - minimal permissions
|
||||
allowed-tools: Bash(git status:*), Bash(git diff:*)
|
||||
|
||||
# Risky - too permissive
|
||||
allowed-tools: *
|
||||
```
|
||||
|
||||
### 4. Meaningful Names
|
||||
|
||||
```bash
|
||||
# Good
|
||||
/generate-tests
|
||||
/review-security
|
||||
/commit-and-push
|
||||
|
||||
# Bad
|
||||
/gt
|
||||
/rs
|
||||
/cap
|
||||
```
|
||||
|
||||
### 5. Self-Documenting Content
|
||||
|
||||
```markdown
|
||||
Review code for:
|
||||
1. Logic errors
|
||||
2. Style issues
|
||||
3. Performance problems
|
||||
|
||||
$ARGUMENTS
|
||||
```
|
||||
|
||||
Better than:
|
||||
|
||||
```markdown
|
||||
Review: $ARGUMENTS
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Command Not Found
|
||||
|
||||
**Issue**: `/mycommand` says command not found
|
||||
|
||||
**Solutions**:
|
||||
1. Check file is in `.claude/commands/` or `~/.claude/commands/`
|
||||
2. Verify filename ends with `.md`
|
||||
3. Restart Claude Code to refresh command list
|
||||
|
||||
### Arguments Not Working
|
||||
|
||||
**Issue**: `$ARGUMENTS` or `$1` showing literally
|
||||
|
||||
**Solutions**:
|
||||
1. Ensure proper syntax: `$ARGUMENTS`, `$1`, `$2` (not `${ARGUMENTS}`)
|
||||
2. Check for typos in variable names
|
||||
3. Test with simple command first
|
||||
|
||||
### Bash Commands Not Executing
|
||||
|
||||
**Issue**: `!command` not running
|
||||
|
||||
**Solutions**:
|
||||
1. Add `allowed-tools` to frontmatter
|
||||
2. Include specific tool pattern: `Bash(git:*)`
|
||||
3. Test with simple command: `!echo test`
|
||||
|
||||
### File References Not Loading
|
||||
|
||||
**Issue**: `@file.js` not including file content
|
||||
|
||||
**Solutions**:
|
||||
1. Verify file path is correct (relative to project root)
|
||||
2. Check file exists: `ls @file.js`
|
||||
3. Ensure no typos in file path
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### Limit Tool Access
|
||||
|
||||
Only grant necessary permissions:
|
||||
|
||||
```yaml
|
||||
# Specific commands only
|
||||
allowed-tools: Bash(git status:*), Bash(git log:*)
|
||||
|
||||
# Never use unless absolutely required
|
||||
allowed-tools: *
|
||||
```
|
||||
|
||||
### No Hardcoded Secrets
|
||||
|
||||
```markdown
|
||||
# Bad - hardcoded API key
|
||||
!curl -H "API-Key: sk-abc123..." api.example.com
|
||||
|
||||
# Good - use environment variables
|
||||
!curl -H "API-Key: $MY_API_KEY" api.example.com
|
||||
```
|
||||
|
||||
### Validate User Input
|
||||
|
||||
If using arguments in bash:
|
||||
|
||||
```markdown
|
||||
# Risky - no validation
|
||||
!rm -rf $1
|
||||
|
||||
# Better - validate first
|
||||
Confirm you want to delete: $1
|
||||
(Then use interactive confirmation before executing)
|
||||
```
|
||||
|
||||
## Command Template
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: [Clear, concise description of what this command does]
|
||||
argument-hint: [Expected arguments format]
|
||||
allowed-tools: [Specific tool patterns if needed]
|
||||
---
|
||||
|
||||
[Command prompt template]
|
||||
|
||||
$ARGUMENTS
|
||||
```
|
||||
|
||||
## Resources
|
||||
|
||||
- [Official Slash Commands Documentation](https://docs.claude.com/en/docs/claude-code/slash-commands)
|
||||
- [Plugin Development](../claude-code-plugins/SKILL.md) - For packaging commands in plugins
|
||||
- [Hooks](../claude-code-hooks/SKILL.md) - For event-based automation
|
||||
|
||||
---
|
||||
|
||||
**Remember**: Slash commands are for reusable prompts. Start with manual prompts, identify patterns you repeat, then codify them as commands.
|
||||
@@ -1,934 +0,0 @@
|
||||
---
|
||||
name: Claude Code Subagent Specialist
|
||||
description: Refine and troubleshoot Claude Code subagents by optimizing prompts, tool access, descriptions, and performance. Use when improving existing subagents, debugging activation issues, or optimizing delegation patterns. NOT for initial creation - use /agents command first.
|
||||
---
|
||||
|
||||
# Claude Code Subagent Refinement & Troubleshooting
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
Use this skill when:
|
||||
- Refining existing subagent prompts for better performance
|
||||
- Troubleshooting why a subagent isn't activating
|
||||
- Optimizing tool access and permissions
|
||||
- Improving subagent descriptions for better delegation
|
||||
- Debugging context management issues
|
||||
- Testing and validating subagent behavior
|
||||
- Converting ad-hoc workflows to reusable subagents
|
||||
|
||||
Do NOT use this skill for:
|
||||
- **Initial creation** - Use `/agents` command instead (it provides interactive UI)
|
||||
- Creating slash commands (use claude-code-slash-commands skill)
|
||||
- General Claude Code troubleshooting
|
||||
|
||||
**Important**: Always start with `/agents` to create subagents. Use this skill to refine them afterward.
|
||||
|
||||
## Quick Reference: Subagent Structure
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: agent-name # Lowercase, kebab-case identifier
|
||||
description: When to use # Triggers automatic delegation
|
||||
tools: Tool1, Tool2 # Optional: omit to inherit all
|
||||
model: sonnet # Optional: sonnet/opus/haiku/inherit
|
||||
---
|
||||
|
||||
System prompt defining role, capabilities, and behavior.
|
||||
Include specific instructions, constraints, and examples.
|
||||
```
|
||||
|
||||
**File Locations**:
|
||||
- Project: `.claude/agents/` (highest priority)
|
||||
- User: `~/.claude/agents/` (shared across projects)
|
||||
- Plugin: `agents/` in plugin directory
|
||||
|
||||
## Common Problems & Solutions
|
||||
|
||||
### Problem 1: Subagent Never Activates
|
||||
|
||||
**Symptoms**: Claude doesn't delegate to your subagent
|
||||
|
||||
**Diagnose**:
|
||||
```yaml
|
||||
# Check your description field
|
||||
---
|
||||
description: Helper agent # ❌ Too vague
|
||||
---
|
||||
```
|
||||
|
||||
**Fix - Make Description Specific**:
|
||||
```yaml
|
||||
# Before (vague)
|
||||
---
|
||||
description: Helps with security
|
||||
---
|
||||
|
||||
# After (specific)
|
||||
---
|
||||
description: Analyze code for security vulnerabilities including SQL injection, XSS, authentication flaws, and hardcoded secrets. Use PROACTIVELY when reviewing code for security issues.
|
||||
---
|
||||
```
|
||||
|
||||
**Best Practices for Descriptions**:
|
||||
- Include specific trigger words and scenarios
|
||||
- Add "use PROACTIVELY" or "MUST BE USED" for automatic activation
|
||||
- Mention the domain/context clearly
|
||||
- List key capabilities or checks
|
||||
|
||||
### Problem 2: Subagent Has Wrong Tools
|
||||
|
||||
**Symptoms**: Subagent can't complete tasks or has too many permissions
|
||||
|
||||
**Diagnose**:
|
||||
```bash
|
||||
# Check current tool configuration
|
||||
cat .claude/agents/my-agent.md | grep "tools:"
|
||||
```
|
||||
|
||||
**Fix - Whitelist Specific Tools**:
|
||||
```yaml
|
||||
# Inherits all tools (may be too permissive)
|
||||
---
|
||||
name: security-analyzer
|
||||
description: Security analysis
|
||||
---
|
||||
|
||||
# Restricted to read-only tools (better)
|
||||
---
|
||||
name: security-analyzer
|
||||
description: Security analysis
|
||||
tools: Read, Grep, Glob
|
||||
---
|
||||
```
|
||||
|
||||
**Tool Access Strategies**:
|
||||
|
||||
**1. Inherit All (Default)**:
|
||||
```yaml
|
||||
# Omit 'tools' field entirely
|
||||
---
|
||||
name: general-helper
|
||||
description: General assistance
|
||||
---
|
||||
```
|
||||
Use when: Agent needs full flexibility
|
||||
|
||||
**2. Read-Only Access**:
|
||||
```yaml
|
||||
---
|
||||
tools: Read, Grep, Glob, Bash(git log:*), Bash(git diff:*)
|
||||
---
|
||||
```
|
||||
Use when: Analysis, review, documentation
|
||||
|
||||
**3. Specific Permissions**:
|
||||
```yaml
|
||||
---
|
||||
tools: Read, Write, Edit, Bash(npm test:*)
|
||||
---
|
||||
```
|
||||
Use when: Implementation with validation
|
||||
|
||||
**4. No File Access**:
|
||||
```yaml
|
||||
---
|
||||
tools: WebFetch, WebSearch, Bash
|
||||
---
|
||||
```
|
||||
Use when: Research, external data gathering
|
||||
|
||||
### Problem 3: Poor Quality Output
|
||||
|
||||
**Symptoms**: Subagent completes tasks but results are inconsistent or low-quality
|
||||
|
||||
**Diagnose**: Check system prompt specificity
|
||||
|
||||
**Fix - Enhance System Prompt**:
|
||||
|
||||
```markdown
|
||||
# Before (vague)
|
||||
---
|
||||
name: code-reviewer
|
||||
---
|
||||
|
||||
You review code for issues.
|
||||
```
|
||||
|
||||
```markdown
|
||||
# After (specific)
|
||||
---
|
||||
name: code-reviewer
|
||||
---
|
||||
|
||||
You are a senior code reviewer specializing in production-ready code quality.
|
||||
|
||||
## Your Responsibilities
|
||||
|
||||
1. **Logic & Correctness**
|
||||
- Verify algorithm correctness
|
||||
- Check edge case handling
|
||||
- Validate error conditions
|
||||
|
||||
2. **Code Quality**
|
||||
- Ensure single responsibility principle
|
||||
- Check for code duplication (DRY)
|
||||
- Verify meaningful naming
|
||||
|
||||
3. **Security**
|
||||
- Identify injection vulnerabilities
|
||||
- Check authentication/authorization
|
||||
- Flag hardcoded secrets
|
||||
|
||||
4. **Performance**
|
||||
- Spot O(n²) or worse algorithms
|
||||
- Identify unnecessary loops
|
||||
- Check resource cleanup
|
||||
|
||||
## Output Format
|
||||
|
||||
For each issue found:
|
||||
- **Severity**: Critical/High/Medium/Low
|
||||
- **Location**: file:line
|
||||
- **Issue**: Clear description
|
||||
- **Fix**: Specific code example
|
||||
|
||||
## Constraints
|
||||
|
||||
- Only report actionable issues
|
||||
- Provide code examples for fixes
|
||||
- Focus on high-impact problems first
|
||||
- No nitpicking style issues unless severe
|
||||
```
|
||||
|
||||
**System Prompt Best Practices**:
|
||||
- Define role and expertise level
|
||||
- List specific responsibilities
|
||||
- Include output format requirements
|
||||
- Add examples of good/bad cases
|
||||
- Specify constraints and boundaries
|
||||
- Use headings for scannability
|
||||
|
||||
### Problem 4: Context Pollution
|
||||
|
||||
**Symptoms**: Main conversation gets cluttered with subagent details
|
||||
|
||||
**Understand**: Subagents have isolated context windows - only their final output returns
|
||||
|
||||
**Fix - Structure Output Properly**:
|
||||
|
||||
```markdown
|
||||
# System prompt guidance
|
||||
---
|
||||
name: research-agent
|
||||
---
|
||||
|
||||
Research [topic] and return ONLY:
|
||||
1. Key findings (3-5 bullet points)
|
||||
2. Relevant URLs
|
||||
3. Recommendation
|
||||
|
||||
Do NOT include:
|
||||
- Full article text
|
||||
- Research methodology
|
||||
- Intermediate thoughts
|
||||
```
|
||||
|
||||
**Best Practices**:
|
||||
- Explicitly tell subagent what to return
|
||||
- Request summaries, not full details
|
||||
- Have subagent filter before returning
|
||||
- Use structured output formats
|
||||
|
||||
### Problem 5: Activation Too Broad/Narrow
|
||||
|
||||
**Symptoms**: Subagent activates for wrong tasks OR misses relevant tasks
|
||||
|
||||
**Diagnose - Test Trigger Scenarios**:
|
||||
|
||||
```markdown
|
||||
# Test cases for a "security-analyzer" subagent
|
||||
|
||||
Should Activate:
|
||||
- "Review this auth code for vulnerabilities"
|
||||
- "Check if we're handling passwords securely"
|
||||
- "Scan for SQL injection risks"
|
||||
|
||||
Should NOT Activate:
|
||||
- "Write unit tests" (different concern)
|
||||
- "Refactor this function" (not security-focused)
|
||||
- "Add logging" (different task)
|
||||
```
|
||||
|
||||
**Fix - Refine Description**:
|
||||
|
||||
```yaml
|
||||
# Too narrow
|
||||
---
|
||||
description: Checks for SQL injection only
|
||||
---
|
||||
|
||||
# Too broad
|
||||
---
|
||||
description: Helps with code
|
||||
---
|
||||
|
||||
# Just right
|
||||
---
|
||||
description: Analyze code for security vulnerabilities including SQL injection, XSS, CSRF, authentication issues, and secrets exposure. Use when reviewing code for security concerns or compliance requirements.
|
||||
---
|
||||
```
|
||||
|
||||
### Problem 6: Model Selection Issues
|
||||
|
||||
**Symptoms**: Subagent too slow/expensive OR too simple for task
|
||||
|
||||
**Fix - Choose Right Model**:
|
||||
|
||||
```yaml
|
||||
# Fast, simple tasks (formatting, linting)
|
||||
---
|
||||
model: haiku
|
||||
---
|
||||
|
||||
# Complex reasoning (architecture, design)
|
||||
---
|
||||
model: opus
|
||||
---
|
||||
|
||||
# Balanced (most cases)
|
||||
---
|
||||
model: sonnet
|
||||
---
|
||||
|
||||
# Same as main conversation
|
||||
---
|
||||
model: inherit
|
||||
---
|
||||
```
|
||||
|
||||
**Model Selection Guide**:
|
||||
|
||||
| Model | Use For | Avoid For |
|
||||
|-------|---------|-----------|
|
||||
| haiku | Simple transforms, quick checks | Complex reasoning, creativity |
|
||||
| sonnet | General tasks, balanced quality | When opus is specifically needed |
|
||||
| opus | Complex architecture, creative work | Simple/repetitive tasks (cost) |
|
||||
| inherit | Task complexity matches main thread | When you need different capability |
|
||||
|
||||
## Optimization Patterns
|
||||
|
||||
### Pattern 1: Role-Based Pipeline
|
||||
|
||||
Create specialized agents for each workflow stage:
|
||||
|
||||
```yaml
|
||||
# 1. Spec Agent
|
||||
---
|
||||
name: product-spec-writer
|
||||
description: Create detailed product specifications from user requirements
|
||||
tools: Read, Write, WebSearch
|
||||
model: opus
|
||||
---
|
||||
|
||||
You convert user requirements into detailed product specs.
|
||||
|
||||
[Detailed prompt...]
|
||||
```
|
||||
|
||||
```yaml
|
||||
# 2. Architect Agent
|
||||
---
|
||||
name: solution-architect
|
||||
description: Design system architecture from product specs
|
||||
tools: Read, Write, Grep, Glob
|
||||
model: opus
|
||||
---
|
||||
|
||||
You design scalable system architectures.
|
||||
|
||||
[Detailed prompt...]
|
||||
```
|
||||
|
||||
```yaml
|
||||
# 3. Implementer Agent
|
||||
---
|
||||
name: code-implementer
|
||||
description: Implement features from architectural designs
|
||||
tools: Read, Write, Edit, Bash(npm test:*)
|
||||
model: sonnet
|
||||
---
|
||||
|
||||
You implement features following architectural guidelines.
|
||||
|
||||
[Detailed prompt...]
|
||||
```
|
||||
|
||||
**Usage**: Chain with hooks or explicit handoffs
|
||||
|
||||
### Pattern 2: Domain Specialists
|
||||
|
||||
```yaml
|
||||
# Frontend Specialist
|
||||
---
|
||||
name: frontend-specialist
|
||||
description: React/TypeScript UI development and component design. Use PROACTIVELY for frontend work.
|
||||
tools: Read, Write, Edit, Grep, Bash(npm:*)
|
||||
---
|
||||
|
||||
You are a React/TypeScript expert specializing in modern frontend development.
|
||||
|
||||
## Tech Stack
|
||||
- React 18+ with hooks
|
||||
- TypeScript (strict mode)
|
||||
- Tailwind CSS
|
||||
- Component-driven architecture
|
||||
|
||||
## Principles
|
||||
- Functional components only
|
||||
- Custom hooks for logic reuse
|
||||
- Accessibility (WCAG AA)
|
||||
- Performance (lazy loading, memoization)
|
||||
|
||||
[More specific guidance...]
|
||||
```
|
||||
|
||||
```yaml
|
||||
# Backend Specialist
|
||||
---
|
||||
name: backend-specialist
|
||||
description: Node.js/Express API development, database design, and server architecture. Use PROACTIVELY for backend work.
|
||||
tools: Read, Write, Edit, Grep, Bash(npm:*), Bash(docker:*)
|
||||
---
|
||||
|
||||
You are a Node.js backend expert.
|
||||
|
||||
[Similar detailed structure...]
|
||||
```
|
||||
|
||||
### Pattern 3: Security-First Architecture
|
||||
|
||||
```yaml
|
||||
# Security Analyzer (Read-Only)
|
||||
---
|
||||
name: security-analyzer
|
||||
description: Analyze code for security vulnerabilities before allowing modifications. MUST BE USED before code changes in sensitive areas.
|
||||
tools: Read, Grep, Glob, Bash(git diff:*)
|
||||
---
|
||||
|
||||
You are a security analyst. Review code for vulnerabilities BEFORE changes are made.
|
||||
|
||||
## Security Checks
|
||||
1. Authentication/Authorization
|
||||
2. Input validation
|
||||
3. SQL injection
|
||||
4. XSS vulnerabilities
|
||||
5. CSRF protection
|
||||
6. Secrets management
|
||||
|
||||
## Output
|
||||
Return ONLY:
|
||||
- Security score (1-10)
|
||||
- Critical issues (block changes)
|
||||
- Warnings (allow with caution)
|
||||
```
|
||||
|
||||
### Pattern 4: Test-Driven Subagent
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: test-first-developer
|
||||
description: Write comprehensive tests before implementing features. Use PROACTIVELY for TDD workflows.
|
||||
tools: Read, Write, Bash(npm test:*)
|
||||
model: sonnet
|
||||
---
|
||||
|
||||
You are a TDD expert. For every feature request:
|
||||
|
||||
1. **Analyze Requirements**
|
||||
- Extract testable behaviors
|
||||
- Identify edge cases
|
||||
|
||||
2. **Write Tests FIRST**
|
||||
- Unit tests for logic
|
||||
- Integration tests for workflows
|
||||
- Edge case coverage
|
||||
|
||||
3. **Run Tests** (they should fail)
|
||||
```bash
|
||||
npm test
|
||||
```
|
||||
|
||||
4. **Implement ONLY Enough** to pass tests
|
||||
|
||||
5. **Refactor** while keeping tests green
|
||||
|
||||
## Test Structure
|
||||
```javascript
|
||||
describe('Feature', () => {
|
||||
it('handles happy path', () => {})
|
||||
it('handles edge case 1', () => {})
|
||||
it('throws on invalid input', () => {})
|
||||
})
|
||||
```
|
||||
|
||||
Never implement before tests exist.
|
||||
```
|
||||
|
||||
## Testing & Validation
|
||||
|
||||
### 1. Test Trigger Accuracy
|
||||
|
||||
Create test scenarios:
|
||||
|
||||
```markdown
|
||||
# Test Plan for "api-developer" subagent
|
||||
|
||||
## Positive Tests (Should Activate)
|
||||
1. "Create a REST endpoint for user authentication"
|
||||
- Expected: Activates
|
||||
- Actual: ___
|
||||
|
||||
2. "Add GraphQL mutation for updating profile"
|
||||
- Expected: Activates
|
||||
- Actual: ___
|
||||
|
||||
## Negative Tests (Should NOT Activate)
|
||||
1. "Write unit tests for the API"
|
||||
- Expected: Does not activate (testing concern)
|
||||
- Actual: ___
|
||||
|
||||
2. "Review API security"
|
||||
- Expected: Does not activate (security concern)
|
||||
- Actual: ___
|
||||
|
||||
## Results
|
||||
- Precision: X% (correct activations / total activations)
|
||||
- Recall: Y% (correct activations / should activate)
|
||||
```
|
||||
|
||||
### 2. Test Output Quality
|
||||
|
||||
```markdown
|
||||
# Quality Checklist
|
||||
|
||||
Task: "Review auth.js for security issues"
|
||||
|
||||
Subagent Output Should Include:
|
||||
- [ ] Specific vulnerabilities identified
|
||||
- [ ] File:line locations
|
||||
- [ ] Severity ratings
|
||||
- [ ] Concrete fix suggestions
|
||||
- [ ] Code examples for fixes
|
||||
|
||||
Should NOT Include:
|
||||
- [ ] Generic advice
|
||||
- [ ] Full file listings
|
||||
- [ ] Unrelated issues
|
||||
- [ ] Style nitpicks
|
||||
```
|
||||
|
||||
### 3. Test Tool Access
|
||||
|
||||
```bash
|
||||
# Verify tool restrictions work
|
||||
# Give subagent a task requiring forbidden tool
|
||||
|
||||
# Example: Read-only subagent shouldn't be able to edit
|
||||
# Test by asking it to "fix the security issue"
|
||||
# Should fail or request permission
|
||||
```
|
||||
|
||||
### 4. Performance Testing
|
||||
|
||||
```markdown
|
||||
# Performance Metrics
|
||||
|
||||
Task: "Generate API documentation"
|
||||
|
||||
Metrics:
|
||||
- Time to complete: ___
|
||||
- Tokens used: ___
|
||||
- Quality score (1-10): ___
|
||||
- Required follow-ups: ___
|
||||
|
||||
Optimization targets:
|
||||
- < 30 seconds for docs
|
||||
- < 5000 tokens
|
||||
- Quality >= 8
|
||||
- 0 follow-ups needed
|
||||
```
|
||||
|
||||
## Refinement Workflow
|
||||
|
||||
### Step 1: Baseline Performance
|
||||
|
||||
```bash
|
||||
# Document current behavior
|
||||
echo "Task: [Specific task]
|
||||
Expected: [What should happen]
|
||||
Actual: [What actually happens]
|
||||
Issues: [Problems observed]
|
||||
" > .claude/agents/refinement-notes.md
|
||||
```
|
||||
|
||||
### Step 2: Identify Root Cause
|
||||
|
||||
Common causes:
|
||||
- Description too vague → Won't activate
|
||||
- Prompt lacks specificity → Poor output
|
||||
- Wrong tools → Can't complete task
|
||||
- Wrong model → Too slow/simple
|
||||
- Output not filtered → Context pollution
|
||||
|
||||
### Step 3: Make Targeted Changes
|
||||
|
||||
**Only change ONE thing at a time**:
|
||||
1. Update description OR
|
||||
2. Refine prompt OR
|
||||
3. Adjust tools OR
|
||||
4. Change model
|
||||
|
||||
### Step 4: Test Changes
|
||||
|
||||
```bash
|
||||
# Test with same scenarios
|
||||
# Compare before/after results
|
||||
# Document improvements
|
||||
```
|
||||
|
||||
### Step 5: Iterate
|
||||
|
||||
Repeat until subagent meets quality bar.
|
||||
|
||||
## Best Practices Summary
|
||||
|
||||
### Description Writing
|
||||
|
||||
```yaml
|
||||
# Template
|
||||
description: [Action verb] [domain/task] [including specific capabilities]. Use [trigger condition]. PROACTIVELY when [scenario].
|
||||
```
|
||||
|
||||
**Examples**:
|
||||
```yaml
|
||||
description: Analyze Python code for performance bottlenecks including O(n²) algorithms, memory leaks, and inefficient database queries. Use PROACTIVELY when optimizing Python applications.
|
||||
|
||||
description: Generate comprehensive API documentation from code including endpoints, parameters, responses, and examples. Use when documenting REST or GraphQL APIs.
|
||||
|
||||
description: Review frontend code for accessibility issues following WCAG 2.1 AA standards. MUST BE USED for all UI component changes.
|
||||
```
|
||||
|
||||
### System Prompt Structure
|
||||
|
||||
```markdown
|
||||
# Role Definition
|
||||
You are a [role] specializing in [domain].
|
||||
|
||||
## Responsibilities
|
||||
1. [Primary responsibility]
|
||||
2. [Secondary responsibility]
|
||||
3. [Additional responsibilities]
|
||||
|
||||
## Process
|
||||
1. [Step 1]
|
||||
2. [Step 2]
|
||||
3. [Step 3]
|
||||
|
||||
## Output Format
|
||||
[Specific structure required]
|
||||
|
||||
## Examples
|
||||
|
||||
### Good Example
|
||||
[Show what good looks like]
|
||||
|
||||
### Bad Example
|
||||
[Show what to avoid]
|
||||
|
||||
## Constraints
|
||||
- [Important limitation]
|
||||
- [Another constraint]
|
||||
```
|
||||
|
||||
### Tool Selection Strategy
|
||||
|
||||
```markdown
|
||||
Decision Tree:
|
||||
|
||||
1. Does it need to modify files?
|
||||
No → Read, Grep, Glob only
|
||||
Yes → Continue
|
||||
|
||||
2. Does it need to run tests/builds?
|
||||
No → Read, Write, Edit only
|
||||
Yes → Add Bash(test:*), Bash(build:*)
|
||||
|
||||
3. Does it need external data?
|
||||
Yes → Add WebFetch, WebSearch
|
||||
No → Continue
|
||||
|
||||
4. Does it need git operations?
|
||||
Yes → Add Bash(git:*) with specific commands
|
||||
No → Done
|
||||
```
|
||||
|
||||
### Model Selection
|
||||
|
||||
```markdown
|
||||
Choose model based on:
|
||||
|
||||
1. Task complexity
|
||||
- Simple transforms → haiku
|
||||
- Standard coding → sonnet
|
||||
- Complex reasoning → opus
|
||||
|
||||
2. Cost sensitivity
|
||||
- High volume, simple → haiku
|
||||
- Balanced → sonnet
|
||||
- Quality critical → opus
|
||||
|
||||
3. Speed requirements
|
||||
- Real-time needed → haiku
|
||||
- Standard → sonnet
|
||||
- Can wait → opus
|
||||
|
||||
Default: sonnet (best balance)
|
||||
```
|
||||
|
||||
## Debugging Checklist
|
||||
|
||||
When subagent doesn't work as expected:
|
||||
|
||||
```markdown
|
||||
- [ ] Description is specific and includes trigger words
|
||||
- [ ] Description includes "PROACTIVELY" or "MUST BE USED" if needed
|
||||
- [ ] System prompt defines role clearly
|
||||
- [ ] System prompt includes process/steps
|
||||
- [ ] System prompt specifies output format
|
||||
- [ ] System prompt has examples
|
||||
- [ ] Tools match required capabilities
|
||||
- [ ] Tools follow least-privilege principle
|
||||
- [ ] Model appropriate for task complexity
|
||||
- [ ] File location correct (.claude/agents/)
|
||||
- [ ] YAML frontmatter valid
|
||||
- [ ] Name uses kebab-case
|
||||
- [ ] Tested with positive/negative scenarios
|
||||
```
|
||||
|
||||
## Common Anti-Patterns
|
||||
|
||||
### ❌ Anti-Pattern 1: Generic Description
|
||||
|
||||
```yaml
|
||||
---
|
||||
description: Helps with coding
|
||||
---
|
||||
```
|
||||
|
||||
**Why Bad**: Won't trigger reliably
|
||||
|
||||
**Fix**: Be specific about domain and triggers
|
||||
|
||||
### ❌ Anti-Pattern 2: No Process Defined
|
||||
|
||||
```markdown
|
||||
You are a code reviewer. Review code.
|
||||
```
|
||||
|
||||
**Why Bad**: Inconsistent results
|
||||
|
||||
**Fix**: Define step-by-step process
|
||||
|
||||
### ❌ Anti-Pattern 3: All Tools Granted
|
||||
|
||||
```yaml
|
||||
---
|
||||
# Omitting tools when only reads needed
|
||||
---
|
||||
```
|
||||
|
||||
**Why Bad**: Unnecessary permissions, security risk
|
||||
|
||||
**Fix**: Whitelist minimum required tools
|
||||
|
||||
### ❌ Anti-Pattern 4: Verbose System Prompt
|
||||
|
||||
```markdown
|
||||
You are an expert developer with 20 years of experience who has worked on numerous projects across different industries... [3000 words]
|
||||
```
|
||||
|
||||
**Why Bad**: Token waste, slower activation
|
||||
|
||||
**Fix**: Be concise, focus on process and format
|
||||
|
||||
### ❌ Anti-Pattern 5: No Output Structure
|
||||
|
||||
```markdown
|
||||
Review the code and tell me about issues.
|
||||
```
|
||||
|
||||
**Why Bad**: Inconsistent format, hard to parse
|
||||
|
||||
**Fix**: Define exact output format
|
||||
|
||||
## Advanced Techniques
|
||||
|
||||
### Technique 1: Chained Subagents
|
||||
|
||||
Use hooks or explicit handoffs:
|
||||
|
||||
```json
|
||||
// .claude/settings.json
|
||||
{
|
||||
"hooks": {
|
||||
"PostToolUse": [
|
||||
{
|
||||
"matcher": "Write",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "echo 'Please use security-analyzer subagent to review this file' && exit 0"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Technique 2: Context Injection
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: context-aware-developer
|
||||
---
|
||||
|
||||
Before starting any task:
|
||||
1. Read PROJECT_CONTEXT.md
|
||||
2. Review ARCHITECTURE.md
|
||||
3. Check CODING_STANDARDS.md
|
||||
|
||||
Then proceed with development following documented patterns.
|
||||
```
|
||||
|
||||
### Technique 3: Quality Gates
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: pr-ready-checker
|
||||
description: Verify code is PR-ready before submitting. MUST BE USED before creating pull requests.
|
||||
tools: Read, Grep, Bash(npm test:*), Bash(npm run lint:*)
|
||||
---
|
||||
|
||||
Verify PR readiness:
|
||||
|
||||
1. **Tests Pass**
|
||||
```bash
|
||||
npm test
|
||||
```
|
||||
All tests must pass.
|
||||
|
||||
2. **Linting Clean**
|
||||
```bash
|
||||
npm run lint
|
||||
```
|
||||
Zero warnings or errors.
|
||||
|
||||
3. **Coverage Adequate**
|
||||
- New code > 80% covered
|
||||
- Overall coverage not decreased
|
||||
|
||||
4. **Documentation Updated**
|
||||
- README if public API changed
|
||||
- Inline comments for complex logic
|
||||
|
||||
5. **No Debug Code**
|
||||
- No console.log
|
||||
- No debugger statements
|
||||
- No commented code
|
||||
|
||||
Return: "PR Ready: Yes/No" + blockers list
|
||||
```
|
||||
|
||||
### Technique 4: Iterative Refinement Prompt
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: iterative-implementer
|
||||
---
|
||||
|
||||
When implementation fails or produces errors:
|
||||
|
||||
1. **Analyze Failure**
|
||||
- What was the error?
|
||||
- Why did it happen?
|
||||
- What was I trying to achieve?
|
||||
|
||||
2. **Adjust Approach**
|
||||
- How should I do it differently?
|
||||
- What did I learn?
|
||||
|
||||
3. **Re-implement**
|
||||
- Apply new approach
|
||||
- Test immediately
|
||||
|
||||
4. **Verify**
|
||||
- Did it work?
|
||||
- If not, repeat from step 1
|
||||
|
||||
Never give up after one failure. Iterate until success.
|
||||
```
|
||||
|
||||
## Migration: Ad-Hoc to Subagent
|
||||
|
||||
### When to Migrate
|
||||
|
||||
Migrate repetitive prompts to subagents when:
|
||||
- You've used the same prompt 3+ times
|
||||
- Prompt has clear pattern/structure
|
||||
- Task benefits from isolation
|
||||
- Multiple team members need it
|
||||
|
||||
### Migration Process
|
||||
|
||||
**Step 1: Extract Pattern**
|
||||
|
||||
```markdown
|
||||
# Repeated prompts you've used:
|
||||
|
||||
1. "Review auth.js for security issues including SQL injection, XSS, and auth flaws"
|
||||
2. "Check payment.js for security vulnerabilities like injection and secrets"
|
||||
3. "Analyze api.js for security problems including validation and auth"
|
||||
|
||||
# Common pattern:
|
||||
Review [file] for security [vulnerability types]
|
||||
```
|
||||
|
||||
**Step 2: Generalize**
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: security-reviewer
|
||||
description: Review code for security vulnerabilities including SQL injection, XSS, authentication flaws, and hardcoded secrets. Use PROACTIVELY for security reviews.
|
||||
tools: Read, Grep, Glob
|
||||
---
|
||||
|
||||
Review provided files for security vulnerabilities:
|
||||
|
||||
[Extract common structure from your prompts]
|
||||
```
|
||||
|
||||
**Step 3: Test & Refine**
|
||||
|
||||
Test with previous use cases, refine until quality matches or exceeds manual prompts.
|
||||
|
||||
## Resources
|
||||
|
||||
- [Official Subagents Documentation](https://docs.claude.com/en/docs/claude-code/sub-agents)
|
||||
- [Claude Code Plugins](../claude-code-plugins/SKILL.md) - For packaging subagents
|
||||
- [Slash Commands](../claude-code-slash-commands/SKILL.md) - Alternative for simpler patterns
|
||||
- [Hooks](../claude-code-hooks/SKILL.md) - For automating subagent workflows
|
||||
|
||||
---
|
||||
|
||||
**Remember**: Start with `/agents` command for creation. Use this skill for refinement. Iterate based on real usage. Test thoroughly. Document learnings.
|
||||
399
claude-code/skills/claude-commands/SKILL.md
Normal file
399
claude-code/skills/claude-commands/SKILL.md
Normal file
@@ -0,0 +1,399 @@
|
||||
---
|
||||
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.
|
||||
---
|
||||
|
||||
# Slash Command Development
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
Use this skill when:
|
||||
- Creating custom slash commands for Claude Code
|
||||
- Building reusable prompt templates
|
||||
- Automating repetitive tasks with commands
|
||||
- Setting up project-specific workflows
|
||||
- Converting manual prompts to slash commands
|
||||
|
||||
Do NOT use this skill for:
|
||||
- Creating full plugins (use claude-plugin skill)
|
||||
- Setting up hooks (use claude-hooks skill)
|
||||
- Complex multi-file operations (use subagents)
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Create Command File
|
||||
|
||||
```bash
|
||||
# Project-specific (team shared)
|
||||
mkdir -p .claude/commands
|
||||
cat > .claude/commands/review.md << 'EOF'
|
||||
---
|
||||
description: Review code for common issues
|
||||
---
|
||||
|
||||
Review the following code for:
|
||||
- Bugs and logic errors
|
||||
- Code style issues
|
||||
- Performance problems
|
||||
- Security vulnerabilities
|
||||
|
||||
$ARGUMENTS
|
||||
EOF
|
||||
```
|
||||
|
||||
**Usage**: `/review @src/main.js`
|
||||
|
||||
## 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 |
|
||||
|
||||
## Command Syntax
|
||||
|
||||
### Basic Structure
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Brief description for /help
|
||||
---
|
||||
|
||||
Prompt content here
|
||||
|
||||
$ARGUMENTS
|
||||
```
|
||||
|
||||
### Filename = Command Name
|
||||
|
||||
```bash
|
||||
# File: .claude/commands/test.md
|
||||
# Command: /test
|
||||
|
||||
# File: .claude/commands/commit-push.md
|
||||
# Command: /commit-push
|
||||
```
|
||||
|
||||
## 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
|
||||
---
|
||||
```
|
||||
|
||||
## Argument Handling
|
||||
|
||||
### $ARGUMENTS - All Arguments
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Explain multiple files
|
||||
---
|
||||
|
||||
Explain these files: $ARGUMENTS
|
||||
```
|
||||
|
||||
**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.
|
||||
```
|
||||
|
||||
**Usage**: `/compare REST GraphQL`
|
||||
|
||||
### File References with @
|
||||
|
||||
```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:*)
|
||||
---
|
||||
|
||||
!git status
|
||||
!git diff --stat
|
||||
|
||||
Based on the current git state, suggest what I should do next.
|
||||
```
|
||||
|
||||
**Important**: Must include `allowed-tools` with Bash specifications.
|
||||
|
||||
## Complete 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
|
||||
```
|
||||
|
||||
### 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.
|
||||
```
|
||||
|
||||
### 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)
|
||||
|
||||
## 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
|
||||
|
||||
```yaml
|
||||
# Good
|
||||
description: Generate unit tests for a specific function
|
||||
|
||||
# Bad
|
||||
description: Testing
|
||||
```
|
||||
|
||||
### 2. Explicit Arguments
|
||||
|
||||
```yaml
|
||||
# Good
|
||||
argument-hint: <file-path> <function-name>
|
||||
|
||||
# Bad (no hint)
|
||||
```
|
||||
|
||||
### 3. Specific Tool Permissions
|
||||
|
||||
```yaml
|
||||
# Good - minimal permissions
|
||||
allowed-tools: Bash(git status:*), Bash(git diff:*)
|
||||
|
||||
# Risky - too permissive
|
||||
allowed-tools: *
|
||||
```
|
||||
|
||||
### 4. Meaningful Names
|
||||
|
||||
```bash
|
||||
# Good
|
||||
/generate-tests
|
||||
/review-security
|
||||
/commit-and-push
|
||||
|
||||
# Bad
|
||||
/gt
|
||||
/rs
|
||||
/cap
|
||||
```
|
||||
|
||||
### 5. Self-Documenting Content
|
||||
|
||||
```markdown
|
||||
Review code for:
|
||||
1. Logic errors
|
||||
2. Style issues
|
||||
3. Performance problems
|
||||
|
||||
$ARGUMENTS
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
| 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 |
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### Limit Tool Access
|
||||
|
||||
```yaml
|
||||
# Specific commands only
|
||||
allowed-tools: Bash(git status:*), Bash(git log:*)
|
||||
|
||||
# Never use unless required
|
||||
allowed-tools: *
|
||||
```
|
||||
|
||||
### No Hardcoded Secrets
|
||||
|
||||
```markdown
|
||||
# Bad - hardcoded API key
|
||||
!curl -H "API-Key: sk-abc123..." api.example.com
|
||||
|
||||
# Good - use environment variables
|
||||
!curl -H "API-Key: $MY_API_KEY" api.example.com
|
||||
```
|
||||
|
||||
### Validate User Input
|
||||
|
||||
```markdown
|
||||
# Risky - no validation
|
||||
!rm -rf $1
|
||||
|
||||
# Better - validate first
|
||||
Confirm you want to delete: $1
|
||||
(Then use interactive confirmation)
|
||||
```
|
||||
|
||||
## Command Template
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: [Clear, concise description]
|
||||
argument-hint: [Expected arguments]
|
||||
allowed-tools: [Specific patterns if needed]
|
||||
---
|
||||
|
||||
[Command prompt template]
|
||||
|
||||
$ARGUMENTS
|
||||
```
|
||||
|
||||
## 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
|
||||
|
||||
---
|
||||
|
||||
**Remember**: Slash commands are for reusable prompts. Start with manual prompts, identify patterns you repeat, then codify them as commands.
|
||||
404
claude-code/skills/claude-hooks/SKILL.md
Normal file
404
claude-code/skills/claude-hooks/SKILL.md
Normal file
@@ -0,0 +1,404 @@
|
||||
---
|
||||
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.
|
||||
---
|
||||
|
||||
# Claude Code Hooks
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
Use this skill when:
|
||||
- Automating workflows with event-driven triggers
|
||||
- Enforcing code standards or security 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)
|
||||
|
||||
## Quick Start
|
||||
|
||||
### 1. Hook Configuration File
|
||||
|
||||
```bash
|
||||
# Project-wide (team shared)
|
||||
.claude/settings.json
|
||||
|
||||
# User-specific (not shared)
|
||||
.claude/settings.local.json
|
||||
|
||||
# Global (all projects)
|
||||
~/.claude/settings.json
|
||||
```
|
||||
|
||||
### 2. Simple Example - Log File Changes
|
||||
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"PostToolUse": [
|
||||
{
|
||||
"matcher": "Write|Edit",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "echo \"$(date): Modified $TOOL_ARGS\" >> .claude/changes.log"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Hook Types
|
||||
|
||||
| Event | When It Runs | Common Use |
|
||||
|-------|--------------|-----------|
|
||||
| SessionStart | Session begins | Inject project context |
|
||||
| SessionEnd | Session ends | Cleanup, backups |
|
||||
| PreToolUse | Before tool execution | Validation, permission checks |
|
||||
| PostToolUse | After tool completes | Formatting, linting |
|
||||
| UserPromptSubmit | User submits prompt | Logging, analytics |
|
||||
| Notification | Claude sends notification | Desktop alerts |
|
||||
| Stop | Agent finishes responding | Post-response processing |
|
||||
|
||||
## Core Concepts
|
||||
|
||||
### Matcher Patterns
|
||||
|
||||
```json
|
||||
// Single tool
|
||||
"matcher": "Write"
|
||||
|
||||
// Multiple tools (OR)
|
||||
"matcher": "Write|Edit|Read"
|
||||
|
||||
// All tools
|
||||
"matcher": "*"
|
||||
|
||||
// Git operations
|
||||
"matcher": "Bash(git:*)"
|
||||
```
|
||||
|
||||
### Exit Codes
|
||||
|
||||
```bash
|
||||
# Success - Continue
|
||||
exit 0
|
||||
|
||||
# Blocking Error - Stop operation
|
||||
exit 2
|
||||
|
||||
# Non-Blocking Error - Continue
|
||||
exit 1
|
||||
```
|
||||
|
||||
### 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.)
|
||||
```
|
||||
|
||||
## Common Use Cases
|
||||
|
||||
### Auto-Format on Save
|
||||
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"PostToolUse": [
|
||||
{
|
||||
"matcher": "Write|Edit",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "cd $CLAUDE_PROJECT_DIR && npx prettier --write $TOOL_ARGS && exit 0"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Security Validation
|
||||
|
||||
```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
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Test Before Commit
|
||||
|
||||
```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
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
For complete examples, see [examples.md](examples.md)
|
||||
|
||||
## Hook Configuration
|
||||
|
||||
### Basic Structure
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "command",
|
||||
"command": "your-command-here",
|
||||
"timeout": 60 // Optional, default 60 seconds
|
||||
}
|
||||
```
|
||||
|
||||
### Multiple Hooks
|
||||
|
||||
Run several hooks in sequence:
|
||||
|
||||
```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"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Conditional Execution
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "command",
|
||||
"command": "if [[ $TOOL_ARGS == *.js ]]; then npm run format $TOOL_ARGS; fi; exit 0"
|
||||
}
|
||||
```
|
||||
|
||||
## Settings File 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
|
||||
|
||||
**Use Cases**:
|
||||
- **Global**: Personal preferences, universal logging
|
||||
- **Project**: Team standards, project automation
|
||||
- **Local**: Personal overrides, development experiments
|
||||
|
||||
## Testing Hooks
|
||||
|
||||
### Start Simple
|
||||
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"PostToolUse": [
|
||||
{
|
||||
"matcher": "Write",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "echo 'Hook triggered for: $TOOL_ARGS' && exit 0"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Test Exit Codes
|
||||
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"PreToolUse": [
|
||||
{
|
||||
"matcher": "Write",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "echo 'This should block' >&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)
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Always Exit Explicitly
|
||||
|
||||
```bash
|
||||
# Good
|
||||
command && exit 0
|
||||
|
||||
# Bad
|
||||
command
|
||||
```
|
||||
|
||||
### 2. Use Timeouts
|
||||
|
||||
```json
|
||||
{
|
||||
"command": "npm test",
|
||||
"timeout": 120 // Don't let tests run forever
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Handle Errors Gracefully
|
||||
|
||||
```bash
|
||||
if [ -f "$TOOL_ARGS" ]; then
|
||||
process_file "$TOOL_ARGS"
|
||||
else
|
||||
echo "File not found" >&2
|
||||
fi
|
||||
exit 0 # Don't block on missing file
|
||||
```
|
||||
|
||||
### 4. Use Scripts for Complex Logic
|
||||
|
||||
```json
|
||||
// Bad - complex bash in JSON
|
||||
{
|
||||
"command": "if [ -f $TOOL_ARGS ]; then cat $TOOL_ARGS | grep pattern | wc -l; fi"
|
||||
}
|
||||
|
||||
// Good - external script
|
||||
{
|
||||
"command": "$CLAUDE_PROJECT_DIR/.claude/hooks/check-file.sh $TOOL_ARGS"
|
||||
}
|
||||
```
|
||||
|
||||
### 5. Test Before Team Deployment
|
||||
|
||||
Test in `.claude/settings.local.json` before adding to `.claude/settings.json`.
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### Validate Input
|
||||
|
||||
```bash
|
||||
# Sanitize TOOL_ARGS
|
||||
if [[ ! $TOOL_ARGS =~ ^[a-zA-Z0-9/_.-]+$ ]]; then
|
||||
echo "Invalid file path" >&2
|
||||
exit 2
|
||||
fi
|
||||
```
|
||||
|
||||
### Limit Permissions
|
||||
|
||||
```json
|
||||
// Specific (good)
|
||||
"matcher": "Write|Edit"
|
||||
|
||||
// Too broad (risky)
|
||||
"matcher": "*"
|
||||
```
|
||||
|
||||
### Avoid Destructive Commands
|
||||
|
||||
```bash
|
||||
# Dangerous
|
||||
rm -rf $TOOL_ARGS
|
||||
|
||||
# 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
|
||||
|
||||
### Common Patterns
|
||||
|
||||
```json
|
||||
// Format on save
|
||||
"PostToolUse": [{"matcher": "Write|Edit", "hooks": [{"type": "command", "command": "prettier --write $TOOL_ARGS"}]}]
|
||||
|
||||
// Block secrets
|
||||
"PreToolUse": [{"matcher": "Write", "hooks": [{"type": "command", "command": "grep -q 'secret' $TOOL_ARGS && exit 2 || exit 0"}]}]
|
||||
|
||||
// Log all activity
|
||||
"PreToolUse": [{"matcher": "*", "hooks": [{"type": "command", "command": "echo \"$TOOL_NAME: $TOOL_ARGS\" >> .claude/log && exit 0"}]}]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Remember**: Hooks are powerful automation tools. Start simple, test thoroughly, use exit codes properly to control flow.
|
||||
258
claude-code/skills/claude-hooks/examples.md
Normal file
258
claude-code/skills/claude-hooks/examples.md
Normal file
@@ -0,0 +1,258 @@
|
||||
# Complete Hook Examples
|
||||
|
||||
Working hook configurations for common scenarios.
|
||||
|
||||
## 1. Auto-Format on Save
|
||||
|
||||
Format files automatically after writing/editing:
|
||||
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"PostToolUse": [
|
||||
{
|
||||
"matcher": "Write|Edit",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "cd $CLAUDE_PROJECT_DIR && npx prettier --write $TOOL_ARGS && exit 0"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 2. Security Validation
|
||||
|
||||
Block writes containing secrets:
|
||||
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"PreToolUse": [
|
||||
{
|
||||
"matcher": "Write|Edit",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "if grep -qiE '(password|api[_-]?key|secret|sk-[a-zA-Z0-9]{48})' $TOOL_ARGS 2>/dev/null; then echo 'Error: Possible secret detected' >&2; exit 2; fi; exit 0",
|
||||
"timeout": 30
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 3. Auto-Git on Changes
|
||||
|
||||
Automatically stage and commit changes:
|
||||
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"PostToolUse": [
|
||||
{
|
||||
"matcher": "Write|Edit",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "cd $CLAUDE_PROJECT_DIR && git add $TOOL_ARGS && git commit -m 'Auto-commit: Modified $TOOL_ARGS' && exit 0"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 4. Test Before Commit
|
||||
|
||||
Run tests before allowing file writes:
|
||||
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"PreToolUse": [
|
||||
{
|
||||
"matcher": "Write|Edit",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "cd $CLAUDE_PROJECT_DIR && npm test -- --silent || (echo 'Tests failed, cannot save' >&2; exit 2)",
|
||||
"timeout": 120
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 5. Inject Project Context
|
||||
|
||||
Load project info at session start:
|
||||
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"SessionStart": [
|
||||
{
|
||||
"matcher": "*",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "cat << EOF\nProject: MyApp\nEnvironment: Production\nKey Files: src/config.js, .env.example\nCoding Standards: See CONTRIBUTING.md\nEOF"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 6. Log All Activity
|
||||
|
||||
Track all tool usage:
|
||||
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"PreToolUse": [
|
||||
{
|
||||
"matcher": "*",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "echo \"$(date '+%Y-%m-%d %H:%M:%S') - $TOOL_NAME - $TOOL_ARGS\" >> $CLAUDE_PROJECT_DIR/.claude/activity.log && exit 0"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 7. Multiple Hooks Sequence
|
||||
|
||||
Format, lint, then stage:
|
||||
|
||||
```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"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 8. Script-Based Hooks
|
||||
|
||||
Call external script for complex logic:
|
||||
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"PreToolUse": [
|
||||
{
|
||||
"matcher": "Write",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "$CLAUDE_PROJECT_DIR/.claude/hooks/validate-write.sh $TOOL_ARGS",
|
||||
"timeout": 60
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**validate-write.sh**:
|
||||
```bash
|
||||
#!/bin/bash
|
||||
file=$1
|
||||
|
||||
# Check file size
|
||||
if [ -f "$file" ] && [ $(wc -c < "$file") -gt 1000000 ]; then
|
||||
echo "Error: File too large" >&2
|
||||
exit 2
|
||||
fi
|
||||
|
||||
# Check for secrets
|
||||
if grep -qiE '(password|api[_-]?key)' "$file" 2>/dev/null; then
|
||||
echo "Error: Possible secret detected" >&2
|
||||
exit 2
|
||||
fi
|
||||
|
||||
exit 0
|
||||
```
|
||||
|
||||
## 9. Conditional by File Type
|
||||
|
||||
Only format JavaScript files:
|
||||
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"PostToolUse": [
|
||||
{
|
||||
"matcher": "Write",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "if [[ $TOOL_ARGS == *.js ]]; then npm run format $TOOL_ARGS; fi; exit 0"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 10. Desktop Notifications
|
||||
|
||||
Alert when Claude needs attention:
|
||||
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"Notification": [
|
||||
{
|
||||
"matcher": "*",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "osascript -e 'display notification \"Claude needs attention\" with title \"Claude Code\"' && exit 0"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
For advanced patterns, see [patterns.md](patterns.md)
|
||||
254
claude-code/skills/claude-memory/SKILL.md
Normal file
254
claude-code/skills/claude-memory/SKILL.md
Normal file
@@ -0,0 +1,254 @@
|
||||
---
|
||||
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.
|
||||
---
|
||||
|
||||
# Claude Code Memory Optimization & Troubleshooting
|
||||
|
||||
## 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
|
||||
- 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)
|
||||
- General Claude Code issues
|
||||
|
||||
**Important**: Always start with `/init` for initial project memory setup.
|
||||
|
||||
## Quick Reference: Memory Hierarchy
|
||||
|
||||
```
|
||||
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
|
||||
```
|
||||
|
||||
**Lookup Order**: Claude searches upward from current directory, loading all CLAUDE.md files found.
|
||||
|
||||
## Core Principles
|
||||
|
||||
### 1. Target Size: 100-200 Lines
|
||||
|
||||
**Why**: Each CLAUDE.md loaded consumes tokens in every conversation.
|
||||
|
||||
```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)
|
||||
Quick reference, critical rules, imports
|
||||
|
||||
# docs/architecture.md (Loaded on demand)
|
||||
Detailed architecture information
|
||||
|
||||
# docs/style-guide.md (Loaded on demand)
|
||||
Comprehensive coding standards
|
||||
```
|
||||
|
||||
### 3. Use Specific, Emphatic Language
|
||||
|
||||
```markdown
|
||||
# ❌ Weak
|
||||
Use functional components
|
||||
|
||||
# ✓ Strong
|
||||
IMPORTANT: ALL React components MUST be functional (no class components).
|
||||
```
|
||||
|
||||
## Essential Structure
|
||||
|
||||
### Minimal Template (100 lines)
|
||||
|
||||
```markdown
|
||||
# ProjectName
|
||||
|
||||
Brief description.
|
||||
|
||||
## Tech Stack
|
||||
- Key technologies
|
||||
- See @docs/tech-stack.md for details
|
||||
|
||||
## Common Commands
|
||||
```bash
|
||||
npm run dev # Start development
|
||||
npm test # Run tests
|
||||
```
|
||||
|
||||
## Conventions
|
||||
- 2-space indentation
|
||||
- ESLint + Prettier
|
||||
- See @docs/style-guide.md
|
||||
|
||||
## IMPORTANT Rules
|
||||
- YOU MUST run tests before commits
|
||||
- Never commit secrets
|
||||
- Update docs with code changes
|
||||
```
|
||||
|
||||
For complete templates, see [templates.md](templates.md)
|
||||
|
||||
## Common Problems (Quick Fixes)
|
||||
|
||||
| Problem | Quick Fix |
|
||||
|---------|-----------|
|
||||
| Memory not loading | Check filename case: `CLAUDE.md` |
|
||||
| Claude ignores rules | Add `IMPORTANT:` or `YOU MUST` |
|
||||
| Too many tokens | Move details to @docs/ imports |
|
||||
| Updates not working | Restart session or use `/memory` |
|
||||
| Conflicting memories | Project wins over user (check hierarchy) |
|
||||
|
||||
For detailed troubleshooting, see [troubleshooting.md](troubleshooting.md)
|
||||
|
||||
## Optimization Quick Win
|
||||
|
||||
**Before (bloated)**:
|
||||
```markdown
|
||||
This project is a comprehensive platform built with React, Node.js, Express,
|
||||
PostgreSQL... [extensive paragraph explaining everything]
|
||||
```
|
||||
|
||||
**After (lean)**:
|
||||
```markdown
|
||||
Tech Stack: React + Node.js + PostgreSQL
|
||||
See @docs/architecture.md for details
|
||||
```
|
||||
|
||||
**Result**: 80% token reduction
|
||||
|
||||
For optimization patterns, see [patterns.md](patterns.md)
|
||||
|
||||
## File Locations
|
||||
|
||||
### Project (Team-Shared)
|
||||
```bash
|
||||
.claude/CLAUDE.md # Team standards (in git)
|
||||
.claude/settings.json # Team configuration
|
||||
```
|
||||
|
||||
### Personal (Not Shared)
|
||||
```bash
|
||||
.claude/CLAUDE.local.md # Personal overrides (gitignored)
|
||||
~/.claude/CLAUDE.md # Global defaults
|
||||
```
|
||||
|
||||
## Import Best Practices
|
||||
|
||||
### ✓ Do
|
||||
```markdown
|
||||
# CLAUDE.md
|
||||
Quick reference content
|
||||
|
||||
For detailed architecture: @docs/architecture.md
|
||||
For API reference: @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
|
||||
```
|
||||
|
||||
**Rules**:
|
||||
- Max import depth: 5 levels
|
||||
- No circular references
|
||||
- Use relative paths for project files
|
||||
- Keep import 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
|
||||
```
|
||||
|
||||
### Method 2: /memory Command
|
||||
```bash
|
||||
/memory
|
||||
# Opens memory management interface
|
||||
```
|
||||
|
||||
### Method 3: Direct Edit
|
||||
```bash
|
||||
vim CLAUDE.md
|
||||
# Then ask Claude to reload
|
||||
```
|
||||
|
||||
## Emphasis Techniques
|
||||
|
||||
For critical rules:
|
||||
|
||||
```markdown
|
||||
IMPORTANT: [Critical rule]
|
||||
YOU MUST [mandatory action]
|
||||
NEVER [forbidden action]
|
||||
**Bold** for emphasis
|
||||
ALL CAPS for maximum attention
|
||||
```
|
||||
|
||||
## Testing Memory Effectiveness
|
||||
|
||||
### Quick Test
|
||||
```markdown
|
||||
# Add temporary marker to CLAUDE.md
|
||||
**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
|
||||
|
||||
```bash
|
||||
# .gitignore
|
||||
.claude/CLAUDE.local.md # Personal only
|
||||
.claude/settings.local.json # Personal settings
|
||||
|
||||
# .claude/CLAUDE.md (in git)
|
||||
# Team Standards
|
||||
|
||||
@docs/architecture.md
|
||||
@docs/conventions.md
|
||||
|
||||
IMPORTANT: All team members follow these standards.
|
||||
|
||||
## Git Workflow
|
||||
1. Feature branch from develop
|
||||
2. PR requires 2 approvals
|
||||
3. Squash merge
|
||||
|
||||
## NEVER
|
||||
- Commit directly to main
|
||||
- Merge without tests passing
|
||||
```
|
||||
|
||||
For team workflows, see [workflows.md](workflows.md)
|
||||
|
||||
## Resources
|
||||
|
||||
- [Memory File 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)
|
||||
|
||||
---
|
||||
|
||||
**Remember**: Practice what we preach - keep memory lean (100-200 lines), be specific not vague, use imports for details, emphasize critical rules, test effectiveness.
|
||||
557
claude-code/skills/claude-memory/patterns.md
Normal file
557
claude-code/skills/claude-memory/patterns.md
Normal file
@@ -0,0 +1,557 @@
|
||||
# Memory Optimization Patterns
|
||||
|
||||
Advanced techniques for token-efficient memory management.
|
||||
|
||||
## Pattern 1: Core + Imports Architecture
|
||||
|
||||
**Strategy**: Keep main CLAUDE.md minimal, import details on demand.
|
||||
|
||||
### Structure
|
||||
|
||||
```
|
||||
project/
|
||||
├── CLAUDE.md (100 lines - core)
|
||||
├── docs/
|
||||
│ ├── tech-stack.md
|
||||
│ ├── architecture.md
|
||||
│ ├── style-guide.md
|
||||
│ └── api-reference.md
|
||||
```
|
||||
|
||||
### CLAUDE.md (Core - Always Loaded)
|
||||
|
||||
```markdown
|
||||
# MyProject
|
||||
|
||||
Quick reference for AI coding assistant.
|
||||
|
||||
## Tech Stack
|
||||
- Backend: Node.js + Express + PostgreSQL
|
||||
- Frontend: React + TypeScript + Tailwind
|
||||
- Details: @docs/tech-stack.md
|
||||
|
||||
## Common Commands
|
||||
```bash
|
||||
npm run dev # Start dev server
|
||||
npm test # Run tests
|
||||
npm run build # Production build
|
||||
```
|
||||
|
||||
## Coding Standards
|
||||
- 2-space indentation
|
||||
- ESLint + Prettier
|
||||
- Full details: @docs/style-guide.md
|
||||
|
||||
## Architecture
|
||||
- Microservices pattern
|
||||
- See @docs/architecture.md
|
||||
|
||||
## IMPORTANT Rules
|
||||
- YOU MUST run tests before commits
|
||||
- Never commit secrets
|
||||
- Update API docs with endpoint changes
|
||||
```
|
||||
|
||||
**Token Cost**: ~400 tokens (loaded every conversation)
|
||||
|
||||
### docs/tech-stack.md (Detailed - Loaded on Demand)
|
||||
|
||||
```markdown
|
||||
# Technology Stack
|
||||
|
||||
## Backend
|
||||
- Node.js 20 LTS
|
||||
- Express 4.18
|
||||
- PostgreSQL 15
|
||||
- Sequelize ORM
|
||||
- Redis for caching
|
||||
- JWT authentication
|
||||
- bcrypt for passwords
|
||||
|
||||
[Extensive details, dependencies, versions, configuration...]
|
||||
```
|
||||
|
||||
**Token Cost**: ~1500 tokens (loaded only when discussing tech stack)
|
||||
|
||||
### Benefits
|
||||
|
||||
- **Main memory stays lean**: 100 lines vs 500+
|
||||
- **Details loaded contextually**: Only when needed
|
||||
- **Easy to update**: Each doc has single focus
|
||||
- **Team ownership**: Different people can own different docs
|
||||
|
||||
---
|
||||
|
||||
## Pattern 2: Subfolder Specialization
|
||||
|
||||
**Strategy**: Use subfolder memory for context-specific guidance.
|
||||
|
||||
### Directory Structure
|
||||
|
||||
```
|
||||
myproject/
|
||||
├── CLAUDE.md # Root - shared context
|
||||
├── frontend/
|
||||
│ ├── CLAUDE.md # Frontend-specific
|
||||
│ └── src/
|
||||
├── backend/
|
||||
│ ├── CLAUDE.md # Backend-specific
|
||||
│ └── src/
|
||||
└── docs/
|
||||
├── architecture.md
|
||||
└── conventions.md
|
||||
```
|
||||
|
||||
### Root CLAUDE.md
|
||||
|
||||
```markdown
|
||||
# MyProject
|
||||
|
||||
Microservices e-commerce platform.
|
||||
|
||||
## Common Across All Areas
|
||||
- Git workflow: feature branches + PRs
|
||||
- Testing required before merge
|
||||
- See @docs/architecture.md
|
||||
|
||||
## Subprojects
|
||||
- `frontend/` - React app (see frontend/CLAUDE.md)
|
||||
- `backend/` - API server (see backend/CLAUDE.md)
|
||||
```
|
||||
|
||||
### frontend/CLAUDE.md (Loaded When Working in frontend/)
|
||||
|
||||
```markdown
|
||||
# Frontend Context
|
||||
|
||||
- React 18 + TypeScript strict mode
|
||||
- Component structure: Atomic Design
|
||||
- Styling: Tailwind utility-first
|
||||
- State: Redux Toolkit
|
||||
|
||||
## Component Patterns
|
||||
@../docs/ui-patterns.md
|
||||
|
||||
## Testing
|
||||
- Jest + React Testing Library
|
||||
- Coverage > 80%
|
||||
- Test user interactions, not implementation
|
||||
```
|
||||
|
||||
### backend/CLAUDE.md (Loaded When Working in backend/)
|
||||
|
||||
```markdown
|
||||
# Backend Context
|
||||
|
||||
- Express + TypeScript
|
||||
- Database: PostgreSQL + Sequelize
|
||||
- Auth: JWT + refresh tokens
|
||||
- Caching: Redis
|
||||
|
||||
## API Patterns
|
||||
@../docs/api-patterns.md
|
||||
|
||||
## Security
|
||||
- All endpoints have rate limiting
|
||||
- Input validation with Zod
|
||||
- SQL injection protection via ORM
|
||||
```
|
||||
|
||||
### When to Use
|
||||
|
||||
- Large monorepos
|
||||
- Different tech stacks per area
|
||||
- Team specialization (frontend/backend teams)
|
||||
- Different conventions per module
|
||||
|
||||
---
|
||||
|
||||
## Pattern 3: User + Project Separation
|
||||
|
||||
**Strategy**: Personal preferences globally, project specifics locally.
|
||||
|
||||
### ~/.claude/CLAUDE.md (Personal - All Projects)
|
||||
|
||||
```markdown
|
||||
# Personal Defaults
|
||||
|
||||
## Communication Style
|
||||
- Explain decisions before acting
|
||||
- Ask before destructive operations
|
||||
- Show diffs for large changes
|
||||
|
||||
## Code Preferences
|
||||
- Prefer functional programming
|
||||
- Avoid premature optimization
|
||||
- Comprehensive error handling
|
||||
|
||||
## Tools
|
||||
- Git commit format: Conventional Commits
|
||||
- Prefer `npm` over `yarn`
|
||||
```
|
||||
|
||||
**Applies To**: Every project you work on
|
||||
|
||||
### ./CLAUDE.md (Project - Overrides Personal)
|
||||
|
||||
```markdown
|
||||
# ProjectX
|
||||
|
||||
IMPORTANT: This legacy project uses OOP extensively (override FP preference).
|
||||
|
||||
Tech stack:
|
||||
- Java Spring Boot
|
||||
- MySQL
|
||||
- jQuery (legacy frontend)
|
||||
|
||||
Common commands:
|
||||
```bash
|
||||
mvn clean install
|
||||
mvn test
|
||||
```
|
||||
|
||||
Conventions:
|
||||
- CamelCase for classes
|
||||
- snake_case for database
|
||||
```
|
||||
|
||||
**Applies To**: Only this project, overrides personal preferences
|
||||
|
||||
### Benefits
|
||||
|
||||
- Consistent personal style across all projects
|
||||
- Project-specific overrides when needed
|
||||
- Easy onboarding to new projects
|
||||
- Maintain personal workflow preferences
|
||||
|
||||
---
|
||||
|
||||
## Pattern 4: Team Collaboration
|
||||
|
||||
**Strategy**: Shared standards in git, personal overrides local.
|
||||
|
||||
### Setup
|
||||
|
||||
```bash
|
||||
# Version control
|
||||
.claude/CLAUDE.md # Team standards (in git)
|
||||
.claude/settings.json # Team settings (in git)
|
||||
|
||||
# Local overrides
|
||||
.claude/CLAUDE.local.md # Personal (gitignored)
|
||||
.claude/settings.local.json # Personal (gitignored)
|
||||
```
|
||||
|
||||
### .gitignore
|
||||
|
||||
```gitignore
|
||||
# Personal overrides only
|
||||
.claude/CLAUDE.local.md
|
||||
.claude/settings.local.json
|
||||
|
||||
# Team files are tracked
|
||||
# .claude/CLAUDE.md
|
||||
# .claude/settings.json
|
||||
```
|
||||
|
||||
### .claude/CLAUDE.md (Team - In Git)
|
||||
|
||||
```markdown
|
||||
# Team Standards
|
||||
|
||||
IMPORTANT: All team members should follow these conventions.
|
||||
|
||||
## Git Workflow
|
||||
1. Create feature branch: `feature/description`
|
||||
2. PR to `develop` (not `main`)
|
||||
3. 2 approvals required
|
||||
4. Squash merge
|
||||
|
||||
## Code Review Checklist
|
||||
- Tests pass locally
|
||||
- Coverage > 80%
|
||||
- No linter warnings
|
||||
- Documentation updated
|
||||
|
||||
## Architecture Decisions
|
||||
@docs/adr/ # Architecture Decision Records
|
||||
|
||||
## NEVER
|
||||
- Commit directly to `main`
|
||||
- Merge without tests passing
|
||||
- Hardcode credentials
|
||||
```
|
||||
|
||||
### .claude/CLAUDE.local.md (Personal - Gitignored)
|
||||
|
||||
```markdown
|
||||
# My Personal Overrides
|
||||
|
||||
## Development Preferences
|
||||
- Use Neovim for editing
|
||||
- Prefer verbose logging during dev
|
||||
- Run tests in watch mode
|
||||
|
||||
[Preferences that don't affect team]
|
||||
```
|
||||
|
||||
### Benefits
|
||||
|
||||
- Consistent team standards
|
||||
- Personal customization allowed
|
||||
- Version-controlled team rules
|
||||
- Built-in onboarding documentation
|
||||
|
||||
---
|
||||
|
||||
## Token Management Strategies
|
||||
|
||||
### Strategy 1: Measure Current Usage
|
||||
|
||||
```bash
|
||||
# Estimate tokens (rough: chars ÷ 4)
|
||||
wc -c CLAUDE.md | awk '{print $1/4}'
|
||||
# Goal: < 5000 tokens (<20KB file)
|
||||
|
||||
# Count lines
|
||||
wc -l CLAUDE.md
|
||||
# Goal: 100-200 lines
|
||||
|
||||
# Find verbose sections (lines >100 chars)
|
||||
grep -n "." CLAUDE.md | awk -F: 'length($2) > 100 {print NR": "$0}'
|
||||
```
|
||||
|
||||
### Strategy 2: Lean Writing Techniques
|
||||
|
||||
#### Before (150 tokens)
|
||||
|
||||
```markdown
|
||||
The application uses a microservices architecture where each service is
|
||||
independently deployable and scalable. The services communicate via REST
|
||||
APIs and message queues. This allows for better separation of concerns
|
||||
and makes it easier to maintain and scale individual components.
|
||||
```
|
||||
|
||||
#### After (30 tokens)
|
||||
|
||||
```markdown
|
||||
Architecture: Microservices (REST + message queues)
|
||||
- Independent deployment/scaling
|
||||
- See @docs/architecture.md
|
||||
```
|
||||
|
||||
**Reduction**: 80%
|
||||
|
||||
### Compression Techniques
|
||||
|
||||
1. **Bullet Points > Paragraphs**
|
||||
- Lists are 50% more token-efficient
|
||||
- Easier to scan
|
||||
|
||||
2. **Commands > Explanations**
|
||||
- Show `npm test` instead of describing testing process
|
||||
- Code is self-documenting
|
||||
|
||||
3. **Imports > Embedding**
|
||||
- `@docs/api.md` costs 5 tokens
|
||||
- Embedding API docs costs 2000 tokens
|
||||
|
||||
4. **Examples > Theory**
|
||||
- One example worth 100 words
|
||||
- Concrete beats abstract
|
||||
|
||||
### Strategy 3: Strategic Importing
|
||||
|
||||
```markdown
|
||||
# Decision Tree
|
||||
|
||||
Is this info needed in 80%+ of sessions?
|
||||
→ YES: Keep in CLAUDE.md
|
||||
|
||||
Is this info needed occasionally?
|
||||
→ YES: Put in @docs/, reference from CLAUDE.md
|
||||
|
||||
Is this info needed rarely?
|
||||
→ NO: Don't include, use web search or direct file read
|
||||
```
|
||||
|
||||
### Example
|
||||
|
||||
```markdown
|
||||
# CLAUDE.md (Always Loaded - ~400 tokens)
|
||||
Core commands, key conventions, critical rules
|
||||
|
||||
# @docs/architecture.md (On Demand - ~1500 tokens)
|
||||
Loaded only when discussing architecture
|
||||
|
||||
# @docs/api-reference.md (On Demand - ~2000 tokens)
|
||||
Loaded only when working on APIs
|
||||
|
||||
# @docs/testing-guide.md (On Demand - ~800 tokens)
|
||||
Loaded only when writing tests
|
||||
|
||||
# @docs/deployment.md (On Demand - ~600 tokens)
|
||||
Loaded only when deploying
|
||||
```
|
||||
|
||||
**Total**: 400 tokens/conversation instead of 5300 tokens
|
||||
**Savings**: 92%
|
||||
|
||||
### Strategy 4: Regular Cleanup
|
||||
|
||||
Monthly review checklist:
|
||||
|
||||
```bash
|
||||
# 1. Find outdated content
|
||||
grep -i "deprecated\|old\|legacy\|TODO" CLAUDE.md
|
||||
|
||||
# 2. Check for redundant sections
|
||||
# Look for repeated information
|
||||
|
||||
# 3. Identify candidates for @imports
|
||||
# Sections >50 lines that aren't always needed
|
||||
|
||||
# 4. Verify all rules are current
|
||||
# Test: does Claude follow each rule?
|
||||
|
||||
# 5. Measure improvement
|
||||
# Before: X lines
|
||||
# After: Y lines
|
||||
# Reduction: Z%
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Advanced Patterns
|
||||
|
||||
### Dynamic Context Loading
|
||||
|
||||
```markdown
|
||||
# CLAUDE.md
|
||||
|
||||
## Context Selection
|
||||
|
||||
When working on:
|
||||
- **Frontend**: Read @frontend/CLAUDE.md
|
||||
- **Backend**: Read @backend/CLAUDE.md
|
||||
- **DevOps**: Read @docs/devops.md
|
||||
- **Testing**: Read @docs/testing.md
|
||||
- **Documentation**: Read @docs/writing-guide.md
|
||||
|
||||
Ask yourself: "What am I working on?" and load that context.
|
||||
```
|
||||
|
||||
### Versioned Standards
|
||||
|
||||
```markdown
|
||||
# CLAUDE.md
|
||||
|
||||
## Current Standards
|
||||
|
||||
API Version: v2
|
||||
See @docs/api-v2.md
|
||||
|
||||
## Migration Guides
|
||||
|
||||
Upgrading from v1? See @docs/migration-v1-to-v2.md
|
||||
|
||||
## Deprecated
|
||||
|
||||
v1 API (deprecated, remove by Q1 2024)
|
||||
Historical reference: @docs/api-v1-deprecated.md
|
||||
```
|
||||
|
||||
### Role-Based Memory
|
||||
|
||||
```markdown
|
||||
# CLAUDE.md
|
||||
|
||||
## Available Roles
|
||||
|
||||
You can act as different roles depending on the task:
|
||||
|
||||
- **Full-Stack Developer**: @docs/role-fullstack.md
|
||||
- **Frontend Specialist**: @docs/role-frontend.md
|
||||
- **Backend Specialist**: @docs/role-backend.md
|
||||
- **DevOps Engineer**: @docs/role-devops.md
|
||||
- **QA Engineer**: @docs/role-qa.md
|
||||
|
||||
Switch roles: "Act as [role name]"
|
||||
```
|
||||
|
||||
### Conditional Instructions
|
||||
|
||||
```markdown
|
||||
# CLAUDE.md
|
||||
|
||||
## Environment-Aware Behavior
|
||||
|
||||
### Development Environment
|
||||
- Verbose logging OK
|
||||
- Use local DB (localhost:5432)
|
||||
- Mock external APIs
|
||||
|
||||
### Staging Environment
|
||||
- Moderate logging
|
||||
- Use staging DB
|
||||
- Real external APIs (test keys)
|
||||
|
||||
### Production Environment
|
||||
- Minimal logging
|
||||
- Use RDS
|
||||
- NEVER commit with console.log
|
||||
- ALWAYS check deployment checklist
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Performance Optimization
|
||||
|
||||
### Before Optimization
|
||||
|
||||
```markdown
|
||||
# CLAUDE.md (1000 lines, 4000 tokens)
|
||||
[Everything embedded]
|
||||
|
||||
Average tokens per conversation: 4000
|
||||
Cost per 1000 conversations: ~$80 (input tokens)
|
||||
```
|
||||
|
||||
### After Optimization
|
||||
|
||||
```markdown
|
||||
# CLAUDE.md (150 lines, 600 tokens)
|
||||
[Core + imports]
|
||||
|
||||
# Imported when needed:
|
||||
@docs/architecture.md (1500 tokens)
|
||||
@docs/api.md (1200 tokens)
|
||||
@docs/testing.md (800 tokens)
|
||||
|
||||
Average tokens per conversation: 600
|
||||
+ Architecture discussions: +1500 (20% of conversations)
|
||||
+ API work: +1200 (30% of conversations)
|
||||
+ Testing: +800 (15% of conversations)
|
||||
|
||||
Weighted average: 600 + (1500×0.2) + (1200×0.3) + (800×0.15) = 1380 tokens
|
||||
|
||||
Cost per 1000 conversations: ~$27 (input tokens)
|
||||
Savings: 66%
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Summary: Best Practices
|
||||
|
||||
1. **Target 100-200 lines** for main CLAUDE.md
|
||||
2. **Use imports liberally** for detailed docs
|
||||
3. **Write concisely**: bullets > paragraphs
|
||||
4. **Be specific**: concrete > vague
|
||||
5. **Emphasize critical rules**: IMPORTANT, YOU MUST, NEVER
|
||||
6. **Organize by scope**: user vs project vs subfolder
|
||||
7. **Measure regularly**: track token usage
|
||||
8. **Clean monthly**: remove outdated content
|
||||
9. **Test effectiveness**: verify Claude follows rules
|
||||
10. **Version control team files**: track changes
|
||||
|
||||
**Goal**: Minimum tokens for maximum effectiveness.
|
||||
406
claude-code/skills/claude-memory/templates.md
Normal file
406
claude-code/skills/claude-memory/templates.md
Normal file
@@ -0,0 +1,406 @@
|
||||
# Memory File Templates
|
||||
|
||||
Ready-to-use CLAUDE.md templates for different project types.
|
||||
|
||||
## Template 1: Minimal Project
|
||||
|
||||
For simple projects with straightforward requirements.
|
||||
|
||||
```markdown
|
||||
# ProjectName
|
||||
|
||||
Brief description.
|
||||
|
||||
## Tech Stack
|
||||
- Language/Framework
|
||||
- Database
|
||||
- Key libraries
|
||||
|
||||
## Common Commands
|
||||
```bash
|
||||
start-command
|
||||
test-command
|
||||
build-command
|
||||
```
|
||||
|
||||
## Conventions
|
||||
- Code style rule 1
|
||||
- Code style rule 2
|
||||
- Naming convention
|
||||
|
||||
## IMPORTANT
|
||||
- Critical rule 1
|
||||
- Critical rule 2
|
||||
```
|
||||
|
||||
**Target Size**: ~50 lines
|
||||
**Use For**: Small projects, prototypes, personal projects
|
||||
|
||||
---
|
||||
|
||||
## Template 2: Team Project
|
||||
|
||||
For collaborative projects with extensive documentation.
|
||||
|
||||
```markdown
|
||||
# ProjectName
|
||||
|
||||
@docs/overview.md
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### Tech Stack
|
||||
@docs/tech-stack.md
|
||||
|
||||
### Common Commands
|
||||
```bash
|
||||
npm run dev
|
||||
npm test
|
||||
npm run build
|
||||
```
|
||||
|
||||
### Coding Standards
|
||||
- 2-space indentation
|
||||
- ESLint + Prettier
|
||||
- Full guide: @docs/style-guide.md
|
||||
|
||||
### Architecture
|
||||
@docs/architecture.md
|
||||
|
||||
## IMPORTANT Team Rules
|
||||
|
||||
- YOU MUST create PR for all changes
|
||||
- Tests must pass before merge
|
||||
- Update docs with code changes
|
||||
|
||||
## Git Workflow
|
||||
@docs/git-workflow.md
|
||||
|
||||
## NEVER
|
||||
- Commit to main directly
|
||||
- Merge without review
|
||||
- Commit secrets
|
||||
```
|
||||
|
||||
**Target Size**: ~100 lines
|
||||
**Use For**: Team projects, open source, enterprise applications
|
||||
|
||||
---
|
||||
|
||||
## Template 3: Monorepo
|
||||
|
||||
For multi-package repositories.
|
||||
|
||||
```markdown
|
||||
# MonorepoName
|
||||
|
||||
Multi-package repository.
|
||||
|
||||
## Structure
|
||||
- `packages/frontend/` - React app → See frontend/CLAUDE.md
|
||||
- `packages/backend/` - API server → See backend/CLAUDE.md
|
||||
- `packages/shared/` - Common code
|
||||
|
||||
## Global Standards
|
||||
- Node.js 20+
|
||||
- pnpm workspaces
|
||||
- Shared ESLint config
|
||||
|
||||
## Commands (from root)
|
||||
```bash
|
||||
pnpm install
|
||||
pnpm test
|
||||
pnpm run build
|
||||
```
|
||||
|
||||
## Cross-Package
|
||||
- Import from `@myapp/shared`
|
||||
- See @docs/package-deps.md
|
||||
|
||||
## IMPORTANT
|
||||
- Changes affecting multiple packages need full test suite
|
||||
```
|
||||
|
||||
**Target Size**: ~80 lines
|
||||
**Use For**: Monorepos, microservices, multi-tier applications
|
||||
|
||||
---
|
||||
|
||||
## Template 4: Personal Defaults
|
||||
|
||||
For ~/.claude/CLAUDE.md (applies to all your projects).
|
||||
|
||||
```markdown
|
||||
# Personal Preferences
|
||||
|
||||
Applied to all my projects unless overridden.
|
||||
|
||||
## Communication
|
||||
- Explain reasoning before acting
|
||||
- Confirm before destructive ops
|
||||
- Show diffs for large changes
|
||||
|
||||
## Code Style
|
||||
- Functional programming preferred
|
||||
- Descriptive variable names
|
||||
- Comments for "why", not "what"
|
||||
|
||||
## Git
|
||||
- Conventional Commits format
|
||||
- Squash feature branches
|
||||
|
||||
## Testing
|
||||
- Write tests alongside code
|
||||
- Aim for 80%+ coverage
|
||||
```
|
||||
|
||||
**Target Size**: ~50 lines
|
||||
**Use For**: Personal global settings
|
||||
|
||||
---
|
||||
|
||||
## Template 5: Frontend Project
|
||||
|
||||
```markdown
|
||||
# Frontend App
|
||||
|
||||
React/TypeScript application.
|
||||
|
||||
## Tech Stack
|
||||
- React 18 + TypeScript
|
||||
- Tailwind CSS
|
||||
- State: Redux Toolkit
|
||||
- Router: React Router v6
|
||||
|
||||
## Commands
|
||||
```bash
|
||||
npm run dev # Dev server (localhost:3000)
|
||||
npm test # Jest + RTL
|
||||
npm run build # Production build
|
||||
npm run lint # ESLint
|
||||
```
|
||||
|
||||
## Structure
|
||||
- `src/components/` - React components
|
||||
- `src/hooks/` - Custom hooks
|
||||
- `src/store/` - Redux slices
|
||||
- `src/utils/` - Helper functions
|
||||
|
||||
## Conventions
|
||||
- Functional components only
|
||||
- Custom hooks for logic reuse
|
||||
- 2-space indentation
|
||||
- Import order: external → internal → styles
|
||||
|
||||
## IMPORTANT
|
||||
- All components need tests
|
||||
- Accessibility: WCAG AA minimum
|
||||
- No inline styles (use Tailwind)
|
||||
```
|
||||
|
||||
**Target Size**: ~100 lines
|
||||
**Use For**: React, Vue, Angular, or other SPA projects
|
||||
|
||||
---
|
||||
|
||||
## Template 6: Backend API
|
||||
|
||||
```markdown
|
||||
# Backend API
|
||||
|
||||
Node.js/Express REST API.
|
||||
|
||||
## Tech Stack
|
||||
- Express + TypeScript
|
||||
- PostgreSQL + Sequelize
|
||||
- Redis for caching
|
||||
- JWT authentication
|
||||
|
||||
## Commands
|
||||
```bash
|
||||
npm run dev # Dev server (localhost:4000)
|
||||
npm test # Jest
|
||||
npm run migrate # Run migrations
|
||||
npm run seed # Seed database
|
||||
```
|
||||
|
||||
## Structure
|
||||
- `src/routes/` - API endpoints
|
||||
- `src/controllers/` - Business logic
|
||||
- `src/models/` - Database models
|
||||
- `src/middleware/` - Express middleware
|
||||
- `src/utils/` - Helper functions
|
||||
|
||||
## Environment
|
||||
- See `.env.example` for required vars
|
||||
- Never commit `.env`
|
||||
|
||||
## IMPORTANT
|
||||
- All endpoints need rate limiting
|
||||
- Input validation required
|
||||
- Error handling middleware
|
||||
- Log security events
|
||||
```
|
||||
|
||||
**Target Size**: ~110 lines
|
||||
**Use For**: API servers, backend services
|
||||
|
||||
---
|
||||
|
||||
## Template 7: Python Project
|
||||
|
||||
```markdown
|
||||
# Python Project
|
||||
|
||||
Python application using modern tooling.
|
||||
|
||||
## Tech Stack
|
||||
- Python 3.11+
|
||||
- uv for dependency management
|
||||
- pytest for testing
|
||||
- ruff for linting
|
||||
|
||||
## Commands
|
||||
```bash
|
||||
uv run python main.py # Run application
|
||||
uv run pytest # Run tests
|
||||
uv run ruff check . # Lint
|
||||
```
|
||||
|
||||
## Structure
|
||||
- `src/` - Application code
|
||||
- `tests/` - Test files
|
||||
- `pyproject.toml` - Project config
|
||||
|
||||
## Conventions
|
||||
- Type hints required
|
||||
- Docstrings for public APIs
|
||||
- Follow PEP 8
|
||||
- Max line length: 100
|
||||
|
||||
## IMPORTANT
|
||||
- All functions need type hints
|
||||
- Test coverage > 80%
|
||||
- No bare `except:` clauses
|
||||
```
|
||||
|
||||
**Target Size**: ~90 lines
|
||||
**Use For**: Python applications, CLI tools, data science projects
|
||||
|
||||
---
|
||||
|
||||
## Customization Tips
|
||||
|
||||
### Adding Project-Specific Rules
|
||||
|
||||
```markdown
|
||||
## IMPORTANT Project Rules
|
||||
|
||||
- YOU MUST [mandatory action]
|
||||
- NEVER [forbidden action]
|
||||
- ALWAYS [required practice]
|
||||
```
|
||||
|
||||
### Adding Tech Stack Details
|
||||
|
||||
```markdown
|
||||
## Tech Stack
|
||||
- Backend: Node.js + Express
|
||||
- Auth: JWT + refresh tokens
|
||||
- ORM: Sequelize
|
||||
- Validation: Zod
|
||||
- Frontend: React + TypeScript
|
||||
- State: Zustand
|
||||
- Styling: Tailwind
|
||||
- Forms: React Hook Form
|
||||
```
|
||||
|
||||
### Adding Team Workflow
|
||||
|
||||
```markdown
|
||||
## Git Workflow
|
||||
1. Branch from `develop`
|
||||
2. Name: `feature/description` or `fix/description`
|
||||
3. PR requires 2 approvals
|
||||
4. Squash merge to develop
|
||||
5. Weekly releases to main
|
||||
```
|
||||
|
||||
### Referencing External Docs
|
||||
|
||||
```markdown
|
||||
## Documentation
|
||||
- Architecture: @docs/architecture.md
|
||||
- API Reference: @docs/api.md
|
||||
- Contributing: @CONTRIBUTING.md
|
||||
- Deployment: @docs/deployment.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Anti-Patterns to Avoid
|
||||
|
||||
### ❌ Too Verbose
|
||||
|
||||
```markdown
|
||||
# Bad: 500 lines
|
||||
This project is a comprehensive e-commerce platform that provides
|
||||
users with the ability to browse products, add them to their cart,
|
||||
and complete purchases securely. The architecture follows a microservices
|
||||
pattern with separate services for user management, product catalog,
|
||||
shopping cart, payment processing, and order fulfillment...
|
||||
|
||||
[400 more lines of detailed explanation]
|
||||
```
|
||||
|
||||
### ✓ Concise with Imports
|
||||
|
||||
```markdown
|
||||
# Good: 100 lines
|
||||
E-commerce platform with microservices architecture.
|
||||
|
||||
Tech Stack: @docs/tech-stack.md
|
||||
Architecture: @docs/architecture.md
|
||||
Conventions: @docs/conventions.md
|
||||
|
||||
## Quick Start
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
```
|
||||
|
||||
### ❌ Vague Instructions
|
||||
|
||||
```markdown
|
||||
# Bad
|
||||
- Write clean code
|
||||
- Follow best practices
|
||||
- Be secure
|
||||
```
|
||||
|
||||
### ✓ Specific Instructions
|
||||
|
||||
```markdown
|
||||
# Good
|
||||
IMPORTANT:
|
||||
- All API endpoints MUST have rate limiting (100 req/min)
|
||||
- Passwords MUST be hashed with bcrypt (min 10 rounds)
|
||||
- Input validation MUST use Zod schemas
|
||||
- SQL queries MUST use parameterized statements
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Selection Guide
|
||||
|
||||
| Project Type | Template | Target Size |
|
||||
|-------------|----------|-------------|
|
||||
| Personal/Small | Minimal | ~50 lines |
|
||||
| Team Project | Team | ~100 lines |
|
||||
| Monorepo | Monorepo | ~80 lines |
|
||||
| Frontend SPA | Frontend | ~100 lines |
|
||||
| Backend API | Backend | ~110 lines |
|
||||
| Python App | Python | ~90 lines |
|
||||
| Global Settings | Personal Defaults | ~50 lines |
|
||||
|
||||
**General Rule**: Start with the appropriate template, customize for your needs, keep under 200 lines.
|
||||
513
claude-code/skills/claude-memory/troubleshooting.md
Normal file
513
claude-code/skills/claude-memory/troubleshooting.md
Normal file
@@ -0,0 +1,513 @@
|
||||
# Memory Troubleshooting Guide
|
||||
|
||||
Detailed problem-solution reference for CLAUDE.md issues.
|
||||
|
||||
## Problem 1: Memory File Not Loading
|
||||
|
||||
**Symptoms**: Claude doesn't seem to remember project context, no awareness of CLAUDE.md contents.
|
||||
|
||||
### Diagnosis
|
||||
|
||||
```bash
|
||||
# Check if file exists
|
||||
ls -la CLAUDE.md
|
||||
ls -la .claude/CLAUDE.md
|
||||
ls -la ~/.claude/CLAUDE.md
|
||||
|
||||
# Check file permissions
|
||||
ls -l CLAUDE.md
|
||||
|
||||
# Check current directory
|
||||
pwd
|
||||
```
|
||||
|
||||
### Common Causes & Solutions
|
||||
|
||||
#### Cause 1: Wrong Location
|
||||
|
||||
```bash
|
||||
# ❌ Bad: Random location
|
||||
/some/random/path/CLAUDE.md
|
||||
|
||||
# ✓ Good: Project root
|
||||
./CLAUDE.md
|
||||
# or
|
||||
./.claude/CLAUDE.md
|
||||
```
|
||||
|
||||
**Solution**: Move file to project root or `.claude/` directory.
|
||||
|
||||
#### Cause 2: Wrong Filename (Case-Sensitive!)
|
||||
|
||||
```bash
|
||||
# ❌ Bad
|
||||
claude.md
|
||||
Claude.md
|
||||
CLAUDE.MD
|
||||
README.md
|
||||
|
||||
# ✓ Good
|
||||
CLAUDE.md
|
||||
```
|
||||
|
||||
**Solution**: Rename to exactly `CLAUDE.md` (all caps).
|
||||
|
||||
#### Cause 3: Syntax Errors in Imports
|
||||
|
||||
```markdown
|
||||
# ❌ Bad: Broken import
|
||||
@docs/nonexistent.md
|
||||
|
||||
# ✓ Good: Valid path
|
||||
@docs/architecture.md
|
||||
```
|
||||
|
||||
**Solution**: Verify all imported paths exist and are correct.
|
||||
|
||||
#### Cause 4: File Permissions
|
||||
|
||||
```bash
|
||||
# Check permissions
|
||||
ls -l CLAUDE.md
|
||||
|
||||
# If not readable, fix it
|
||||
chmod 644 CLAUDE.md
|
||||
```
|
||||
|
||||
### Verification Test
|
||||
|
||||
Add a temporary marker to CLAUDE.md:
|
||||
|
||||
```markdown
|
||||
**MEMORY LOADED: This is a test marker**
|
||||
```
|
||||
|
||||
Ask Claude: "What's the first line of your memory?"
|
||||
If Claude sees the marker, memory is loading correctly.
|
||||
Remove marker after test.
|
||||
|
||||
---
|
||||
|
||||
## Problem 2: Bloated Memory (Token Waste)
|
||||
|
||||
**Symptoms**: Context fills up quickly, slow responses, high costs, frequent compaction.
|
||||
|
||||
### Diagnosis
|
||||
|
||||
```bash
|
||||
# Check file size
|
||||
wc -l CLAUDE.md
|
||||
# Goal: 100-200 lines max
|
||||
|
||||
# Count characters (rough token estimate: chars ÷ 4)
|
||||
wc -c CLAUDE.md
|
||||
# Goal: < 20KB
|
||||
```
|
||||
|
||||
### Solution: Trim and Split
|
||||
|
||||
#### Before (Bloated - 500 lines)
|
||||
|
||||
```markdown
|
||||
# Project Overview
|
||||
|
||||
This project is a comprehensive e-commerce platform built with React, Node.js,
|
||||
Express, PostgreSQL, Redis, and Docker. The frontend uses React 18 with TypeScript
|
||||
in strict mode, Tailwind CSS for styling, React Router for navigation, Redux Toolkit
|
||||
for state management, and Axios for API calls. The backend uses Express.js with
|
||||
TypeScript, Sequelize ORM for database access, JWT for authentication, bcrypt for
|
||||
password hashing, and Redis for session management...
|
||||
|
||||
[400 more lines of verbose content]
|
||||
```
|
||||
|
||||
#### After (Lean - 150 lines)
|
||||
|
||||
```markdown
|
||||
# Tech Stack
|
||||
|
||||
- Frontend: React 18 + TypeScript + Tailwind
|
||||
- Backend: Express + PostgreSQL + Redis
|
||||
- Architecture: Microservices
|
||||
- Details: @docs/tech-stack.md
|
||||
|
||||
## Common Commands
|
||||
|
||||
```bash
|
||||
npm run dev # Local development
|
||||
npm test # Run all tests
|
||||
npm run build # Production build
|
||||
```
|
||||
|
||||
## Key Conventions
|
||||
|
||||
- 2-space indentation
|
||||
- Functional components only
|
||||
- ESLint + Prettier
|
||||
- 80% test coverage minimum
|
||||
|
||||
## IMPORTANT Rules
|
||||
|
||||
- YOU MUST run tests before committing
|
||||
- Never commit .env files
|
||||
- Always update API docs when adding endpoints
|
||||
```
|
||||
|
||||
**Result**: 70% token reduction
|
||||
|
||||
### Compression Techniques
|
||||
|
||||
1. **Use Bullet Points, Not Paragraphs**
|
||||
2. **Use Imports for Details**
|
||||
3. **Show Commands, Not Explanations**
|
||||
4. **Prefer Tables Over Text**
|
||||
|
||||
---
|
||||
|
||||
## Problem 3: Claude Not Following Instructions
|
||||
|
||||
**Symptoms**: Claude ignores rules in CLAUDE.md, doesn't follow conventions.
|
||||
|
||||
### Diagnosis
|
||||
|
||||
Check instruction specificity:
|
||||
|
||||
```markdown
|
||||
# ❌ Too Vague (ignored)
|
||||
- Write clean code
|
||||
- Follow best practices
|
||||
- Be careful with security
|
||||
|
||||
# ✓ Specific (followed)
|
||||
- Use 2-space indentation (not tabs)
|
||||
- All API endpoints must have rate limiting
|
||||
- Hash passwords with bcrypt (min 10 rounds)
|
||||
```
|
||||
|
||||
### Solution: Add Emphasis
|
||||
|
||||
#### Weak Instruction (Often Ignored)
|
||||
|
||||
```markdown
|
||||
Use functional components in React.
|
||||
Run tests before committing.
|
||||
```
|
||||
|
||||
#### Strong Instruction (Followed)
|
||||
|
||||
```markdown
|
||||
IMPORTANT: ALL React components MUST be functional (no class components).
|
||||
|
||||
YOU MUST run `npm test` and ensure all tests pass before any git commit.
|
||||
```
|
||||
|
||||
### Emphasis Hierarchy
|
||||
|
||||
1. `ALL CAPS` - Maximum attention
|
||||
2. `IMPORTANT:` - Critical rules
|
||||
3. `YOU MUST` - Mandatory actions
|
||||
4. `NEVER` - Forbidden actions
|
||||
5. **Bold** - Standard emphasis
|
||||
6. Regular text - General info
|
||||
|
||||
### Example: Strong Rules Section
|
||||
|
||||
```markdown
|
||||
## IMPORTANT Project Rules
|
||||
|
||||
YOU MUST:
|
||||
- Run full test suite before every commit
|
||||
- Get 2 PR approvals before merging
|
||||
- Update API documentation when adding endpoints
|
||||
|
||||
NEVER:
|
||||
- Commit directly to main branch
|
||||
- Merge code with failing tests
|
||||
- Hardcode API keys or secrets
|
||||
|
||||
ALWAYS:
|
||||
- Use environment variables for config
|
||||
- Include error handling in all async functions
|
||||
- Write tests for new features
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Problem 4: Memory Updates Not Reflected
|
||||
|
||||
**Symptoms**: Changes to CLAUDE.md don't take effect in current session.
|
||||
|
||||
### Solutions
|
||||
|
||||
#### Method 1: Quick Add (# Shortcut)
|
||||
|
||||
```bash
|
||||
# At input prompt, press # first
|
||||
# Type: Use snake_case for Python functions
|
||||
# Claude auto-adds to appropriate CLAUDE.md
|
||||
```
|
||||
|
||||
**Best For**: Quick single-line updates
|
||||
|
||||
#### Method 2: /memory Command
|
||||
|
||||
```bash
|
||||
/memory
|
||||
# Opens memory management interface
|
||||
```
|
||||
|
||||
**Best For**: Reviewing and editing existing memory
|
||||
|
||||
#### Method 3: Direct Edit + Reload
|
||||
|
||||
```bash
|
||||
# Edit the file
|
||||
vim CLAUDE.md
|
||||
|
||||
# Then explicitly ask Claude
|
||||
"Please re-read CLAUDE.md"
|
||||
```
|
||||
|
||||
**Best For**: Major updates or reorganization
|
||||
|
||||
#### Method 4: Session Restart (Most Reliable)
|
||||
|
||||
```bash
|
||||
# Close and reopen Claude Code
|
||||
# Or Ctrl+C to exit CLI
|
||||
```
|
||||
|
||||
**Best For**: When other methods don't work
|
||||
|
||||
---
|
||||
|
||||
## Problem 5: Too Many Memory Files
|
||||
|
||||
**Symptoms**: Conflicting instructions, unclear hierarchy, unexpected behavior.
|
||||
|
||||
### Diagnosis
|
||||
|
||||
```bash
|
||||
# Find all CLAUDE.md files
|
||||
find . -name "CLAUDE.md"
|
||||
find ~ -name "CLAUDE.md"
|
||||
|
||||
# Check which directory you're in
|
||||
pwd
|
||||
```
|
||||
|
||||
### Understanding Priority
|
||||
|
||||
Higher priority wins on conflicts:
|
||||
|
||||
```
|
||||
1. ~/.claude/enterprise/CLAUDE.md # Organization policy (highest)
|
||||
↓
|
||||
2. ./CLAUDE.md # Current project
|
||||
↓
|
||||
3. ~/.claude/CLAUDE.md # Your personal defaults
|
||||
↓
|
||||
4. ./subfolder/CLAUDE.md # Subfolder overrides
|
||||
```
|
||||
|
||||
### Solution: Organize Properly
|
||||
|
||||
#### Global Personal (~/.claude/CLAUDE.md)
|
||||
|
||||
```markdown
|
||||
# Personal Defaults
|
||||
|
||||
## Communication Style
|
||||
- Explain decisions before acting
|
||||
- Ask before destructive operations
|
||||
|
||||
## Code Preferences
|
||||
- Prefer functional programming
|
||||
- Avoid premature optimization
|
||||
```
|
||||
|
||||
**Use For**: Universal personal preferences
|
||||
|
||||
#### Project Root (./CLAUDE.md)
|
||||
|
||||
```markdown
|
||||
# MyProject
|
||||
|
||||
@docs/tech-stack.md
|
||||
@docs/conventions.md
|
||||
|
||||
IMPORTANT: This project uses OOP (override personal FP preference).
|
||||
|
||||
Tech Stack: Java + Spring Boot
|
||||
```
|
||||
|
||||
**Use For**: Project-specific standards (overrides personal)
|
||||
|
||||
#### Subfolder (./frontend/CLAUDE.md)
|
||||
|
||||
```markdown
|
||||
# Frontend Context
|
||||
|
||||
- React 18 + TypeScript
|
||||
- Component structure: Atomic Design
|
||||
- See @../docs/ui-patterns.md
|
||||
```
|
||||
|
||||
**Use For**: Directory-specific context (loaded when in that directory)
|
||||
|
||||
---
|
||||
|
||||
## Problem 6: Import Loops or Errors
|
||||
|
||||
**Symptoms**: "Import depth exceeded", circular import error, or infinite loading.
|
||||
|
||||
### Import Rules
|
||||
|
||||
```markdown
|
||||
# ❌ Bad: Too Deep
|
||||
CLAUDE.md
|
||||
→ @docs/a.md (depth 1)
|
||||
→ @docs/b.md (depth 2)
|
||||
→ @docs/c.md (depth 3)
|
||||
→ @docs/d.md (depth 4)
|
||||
→ @docs/e.md (depth 5)
|
||||
→ @docs/f.md (depth 6 - FAILS!)
|
||||
|
||||
# ✓ Good: Flat Structure
|
||||
CLAUDE.md
|
||||
→ @docs/architecture.md
|
||||
→ @docs/conventions.md
|
||||
→ @docs/testing.md
|
||||
→ @docs/deployment.md
|
||||
|
||||
# ❌ Bad: Circular Import
|
||||
CLAUDE.md → @docs/a.md → @docs/b.md → @docs/a.md (LOOP!)
|
||||
|
||||
# ✓ Good: No Circles
|
||||
CLAUDE.md → @docs/a.md → @docs/c.md
|
||||
→ @docs/b.md → @docs/c.md
|
||||
```
|
||||
|
||||
### Solution: Restructure Imports
|
||||
|
||||
**Before (Deep Chain)**:
|
||||
```markdown
|
||||
# CLAUDE.md
|
||||
@docs/main.md
|
||||
|
||||
# docs/main.md
|
||||
@project/overview.md
|
||||
|
||||
# project/overview.md
|
||||
@details/architecture.md
|
||||
|
||||
# details/architecture.md
|
||||
[content]
|
||||
```
|
||||
|
||||
**After (Flat)**:
|
||||
```markdown
|
||||
# CLAUDE.md
|
||||
@docs/overview.md
|
||||
@docs/architecture.md
|
||||
@docs/conventions.md
|
||||
```
|
||||
|
||||
### Best Practices
|
||||
|
||||
- **Max depth**: 5 levels
|
||||
- **No circular references**
|
||||
- **Prefer flat over deep**
|
||||
- **Use relative paths** for project files: `@docs/file.md`
|
||||
- **Use absolute paths** for global files: `@~/.claude/shared.md`
|
||||
|
||||
---
|
||||
|
||||
## Problem 7: Conflicting Team Instructions
|
||||
|
||||
**Symptoms**: Different team members get different behavior from Claude.
|
||||
|
||||
### Diagnosis
|
||||
|
||||
```bash
|
||||
# Check for local overrides
|
||||
ls .claude/CLAUDE.local.md
|
||||
ls .claude/settings.local.json
|
||||
|
||||
# Check git-tracked files
|
||||
git ls-files | grep -i claude
|
||||
```
|
||||
|
||||
### Solution: Proper Separation
|
||||
|
||||
#### Team-Shared (.claude/CLAUDE.md - in git)
|
||||
|
||||
```markdown
|
||||
# Team Standards
|
||||
|
||||
IMPORTANT: All team members follow these conventions.
|
||||
|
||||
## Git Workflow
|
||||
1. Branch from `develop`
|
||||
2. PR requires 2 approvals
|
||||
3. Squash merge
|
||||
|
||||
## Coding Standards
|
||||
@docs/style-guide.md
|
||||
|
||||
## NEVER
|
||||
- Commit directly to main
|
||||
- Merge without tests
|
||||
```
|
||||
|
||||
#### Personal (.claude/CLAUDE.local.md - gitignored)
|
||||
|
||||
```markdown
|
||||
# My Personal Preferences
|
||||
|
||||
[Individual customizations that don't affect team]
|
||||
```
|
||||
|
||||
#### .gitignore Setup
|
||||
|
||||
```gitignore
|
||||
# Personal files (not shared)
|
||||
.claude/CLAUDE.local.md
|
||||
.claude/settings.local.json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference: Diagnostic Checklist
|
||||
|
||||
When memory isn't working, check:
|
||||
|
||||
```markdown
|
||||
- [ ] File named exactly "CLAUDE.md" (case-sensitive)
|
||||
- [ ] File in project root or .claude/ directory
|
||||
- [ ] File has read permissions (chmod 644)
|
||||
- [ ] Valid markdown syntax
|
||||
- [ ] Imports use correct paths
|
||||
- [ ] No circular import loops
|
||||
- [ ] Import depth ≤ 5 levels
|
||||
- [ ] File size < 20KB (~200 lines)
|
||||
- [ ] Instructions are specific, not vague
|
||||
- [ ] Used emphasis for critical rules
|
||||
- [ ] No syntax errors in code blocks
|
||||
- [ ] Tried session restart
|
||||
- [ ] Verified loading with test marker
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Getting Help
|
||||
|
||||
If problems persist:
|
||||
|
||||
1. **Verify File Loading**: Add test marker, ask Claude to read it
|
||||
2. **Check Hierarchy**: Understand which files are being loaded
|
||||
3. **Review Syntax**: Ensure valid markdown and imports
|
||||
4. **Simplify First**: Start with minimal CLAUDE.md, add back gradually
|
||||
5. **Restart Session**: Most reliable way to reload changes
|
||||
|
||||
For further assistance, see [Official Documentation](https://docs.claude.com/en/docs/claude-code/memory).
|
||||
624
claude-code/skills/claude-memory/workflows.md
Normal file
624
claude-code/skills/claude-memory/workflows.md
Normal file
@@ -0,0 +1,624 @@
|
||||
# Team Collaboration Workflows
|
||||
|
||||
Strategies for using CLAUDE.md in team environments.
|
||||
|
||||
## Workflow 1: Onboarding New Developer
|
||||
|
||||
### Goal
|
||||
Get new team members productive immediately using CLAUDE.md as primary documentation.
|
||||
|
||||
### Setup
|
||||
|
||||
```bash
|
||||
# Project repository structure
|
||||
myproject/
|
||||
├── .claude/
|
||||
│ └── CLAUDE.md # Team standards
|
||||
├── docs/
|
||||
│ ├── architecture.md
|
||||
│ ├── conventions.md
|
||||
│ └── getting-started.md
|
||||
└── README.md
|
||||
```
|
||||
|
||||
### Process
|
||||
|
||||
#### Step 1: Clone Repository
|
||||
|
||||
```bash
|
||||
git clone repo
|
||||
cd myproject
|
||||
```
|
||||
|
||||
#### Step 2: Claude Reads Memory Automatically
|
||||
|
||||
New developer opens Claude Code - memory loads automatically.
|
||||
|
||||
#### Step 3: Ask Claude for Orientation
|
||||
|
||||
```
|
||||
New Dev: "What's this project about?"
|
||||
|
||||
Claude (using CLAUDE.md): "This is an e-commerce platform using:
|
||||
- Tech Stack: React + Node.js + PostgreSQL
|
||||
- Architecture: Microservices pattern
|
||||
- Key directories: src/api, src/components, src/services
|
||||
- Start with: npm install && npm run dev
|
||||
- See docs/getting-started.md for detailed setup"
|
||||
```
|
||||
|
||||
#### Step 4: Productive Immediately
|
||||
|
||||
New developer can:
|
||||
- Ask Claude about any convention
|
||||
- Get help with setup issues
|
||||
- Understand architecture decisions
|
||||
- Follow team standards automatically
|
||||
|
||||
### Benefits
|
||||
|
||||
- **Zero onboarding docs to read**: Claude explains everything
|
||||
- **Consistent answers**: Same info for all team members
|
||||
- **Always up to date**: Update CLAUDE.md, everyone gets it
|
||||
- **Interactive learning**: Ask questions, get context-aware answers
|
||||
|
||||
---
|
||||
|
||||
## Workflow 2: Updating Team Standards
|
||||
|
||||
### Goal
|
||||
Change team conventions and have all developers adopt them immediately.
|
||||
|
||||
### Scenario
|
||||
Team decides to switch from npm to pnpm.
|
||||
|
||||
### Process
|
||||
|
||||
#### Step 1: Update CLAUDE.md
|
||||
|
||||
```bash
|
||||
# Edit .claude/CLAUDE.md
|
||||
sed -i 's/npm run/pnpm run/g' .claude/CLAUDE.md
|
||||
sed -i 's/npm test/pnpm test/g' .claude/CLAUDE.md
|
||||
sed -i 's/npm install/pnpm install/g' .claude/CLAUDE.md
|
||||
```
|
||||
|
||||
Update commands section:
|
||||
|
||||
```markdown
|
||||
## Common Commands
|
||||
```bash
|
||||
pnpm run dev # Start development server
|
||||
pnpm test # Run test suite
|
||||
pnpm run build # Production build
|
||||
```
|
||||
|
||||
IMPORTANT: This project uses pnpm, not npm.
|
||||
```
|
||||
|
||||
#### Step 2: Commit Change
|
||||
|
||||
```bash
|
||||
git add .claude/CLAUDE.md
|
||||
git commit -m "docs: switch package manager from npm to pnpm"
|
||||
git push
|
||||
```
|
||||
|
||||
#### Step 3: Team Pulls Update
|
||||
|
||||
```bash
|
||||
# Each developer
|
||||
git pull
|
||||
```
|
||||
|
||||
#### Step 4: Claude Uses New Standard
|
||||
|
||||
Next time anyone asks Claude to run a command, it uses pnpm automatically.
|
||||
|
||||
### Benefits
|
||||
|
||||
- **Immediate adoption**: No need to notify team
|
||||
- **No context switching**: Claude reminds developers
|
||||
- **Version controlled**: Track convention changes
|
||||
- **Rollback if needed**: Git history
|
||||
|
||||
---
|
||||
|
||||
## Workflow 3: Feature-Specific Context
|
||||
|
||||
### Goal
|
||||
Provide context for specific feature areas without bloating root memory.
|
||||
|
||||
### Structure
|
||||
|
||||
```
|
||||
project/
|
||||
├── CLAUDE.md # Root context
|
||||
├── features/
|
||||
│ ├── auth/
|
||||
│ │ ├── CLAUDE.md # Auth-specific context
|
||||
│ │ └── src/
|
||||
│ ├── payments/
|
||||
│ │ ├── CLAUDE.md # Payment-specific context
|
||||
│ │ └── src/
|
||||
│ └── notifications/
|
||||
│ ├── CLAUDE.md # Notification-specific context
|
||||
│ └── src/
|
||||
```
|
||||
|
||||
### Root CLAUDE.md
|
||||
|
||||
```markdown
|
||||
# MyProject
|
||||
|
||||
## Feature Areas
|
||||
|
||||
Each feature has specific context:
|
||||
- `features/auth/` - Authentication (see auth/CLAUDE.md)
|
||||
- `features/payments/` - Payment processing (see payments/CLAUDE.md)
|
||||
- `features/notifications/` - Notification system (see notifications/CLAUDE.md)
|
||||
|
||||
When working in a feature directory, Claude loads that context automatically.
|
||||
```
|
||||
|
||||
### features/auth/CLAUDE.md
|
||||
|
||||
```markdown
|
||||
# Authentication Feature
|
||||
|
||||
## Implementation
|
||||
- JWT + refresh tokens
|
||||
- Token lifetime: 15min access, 7d refresh
|
||||
- Password requirements: min 12 chars, bcrypt rounds: 12
|
||||
|
||||
## Key Files
|
||||
- `src/auth.service.ts` - Core auth logic
|
||||
- `src/jwt.util.ts` - Token generation/validation
|
||||
- `src/password.util.ts` - Password hashing
|
||||
|
||||
## IMPORTANT Security Rules
|
||||
- Passwords MUST be hashed with bcrypt (min 12 rounds)
|
||||
- Tokens MUST have expiration
|
||||
- MFA required for admin accounts
|
||||
- Log all authentication failures
|
||||
|
||||
## Testing
|
||||
- Unit tests: `tests/auth.test.ts`
|
||||
- Integration: `tests/auth.integration.test.ts`
|
||||
- All auth changes need security review
|
||||
```
|
||||
|
||||
### Usage
|
||||
|
||||
```bash
|
||||
# Developer working on auth feature
|
||||
cd features/auth
|
||||
|
||||
# Claude now has both root context + auth-specific context
|
||||
# Can answer auth-specific questions with full context
|
||||
```
|
||||
|
||||
### Benefits
|
||||
|
||||
- **Contextual memory**: Right info at right time
|
||||
- **No bloat**: Root memory stays lean
|
||||
- **Feature ownership**: Each team owns their feature docs
|
||||
- **Isolated changes**: Update feature context independently
|
||||
|
||||
---
|
||||
|
||||
## Workflow 4: Architecture Decision Records (ADR)
|
||||
|
||||
### Goal
|
||||
Document why decisions were made and have Claude reference them.
|
||||
|
||||
### Structure
|
||||
|
||||
```
|
||||
project/
|
||||
├── .claude/
|
||||
│ └── CLAUDE.md
|
||||
└── docs/
|
||||
└── adr/
|
||||
├── 001-use-postgresql.md
|
||||
├── 002-microservices-architecture.md
|
||||
├── 003-graphql-over-rest.md
|
||||
└── template.md
|
||||
```
|
||||
|
||||
### CLAUDE.md Reference
|
||||
|
||||
```markdown
|
||||
# MyProject
|
||||
|
||||
## Architecture Decisions
|
||||
|
||||
All architectural decisions are documented in ADRs.
|
||||
|
||||
See @docs/adr/ for all decisions.
|
||||
|
||||
When making architectural changes:
|
||||
1. Propose via ADR
|
||||
2. Get team review
|
||||
3. Update CLAUDE.md if needed
|
||||
```
|
||||
|
||||
### ADR Format (docs/adr/003-graphql-over-rest.md)
|
||||
|
||||
```markdown
|
||||
# 3. Use GraphQL Instead of REST
|
||||
|
||||
Date: 2024-01-15
|
||||
Status: Accepted
|
||||
|
||||
## Context
|
||||
Need API design pattern for new features.
|
||||
|
||||
## Decision
|
||||
Use GraphQL for new APIs, maintain REST for legacy.
|
||||
|
||||
## Consequences
|
||||
**Positive:**
|
||||
- Flexible queries
|
||||
- Reduced over-fetching
|
||||
- Strong typing
|
||||
|
||||
**Negative:**
|
||||
- Learning curve
|
||||
- More complex caching
|
||||
|
||||
## Implementation
|
||||
See @docs/graphql-guide.md
|
||||
```
|
||||
|
||||
### Usage
|
||||
|
||||
Developer asks Claude: "Why do we use GraphQL?"
|
||||
|
||||
Claude references ADR and explains the decision context.
|
||||
|
||||
### Benefits
|
||||
|
||||
- **Historical context**: Understand past decisions
|
||||
- **Onboarding**: New devs understand "why"
|
||||
- **Consistency**: Reference when making new decisions
|
||||
- **Change tracking**: Git history of decisions
|
||||
|
||||
---
|
||||
|
||||
## Workflow 5: Code Review Automation
|
||||
|
||||
### Goal
|
||||
Use CLAUDE.md to establish review standards, have Claude enforce them.
|
||||
|
||||
### .claude/CLAUDE.md
|
||||
|
||||
```markdown
|
||||
# MyProject
|
||||
|
||||
## Code Review Checklist
|
||||
|
||||
Before approving PRs, verify:
|
||||
|
||||
### Functionality
|
||||
- [ ] Tests pass locally
|
||||
- [ ] New features have tests
|
||||
- [ ] Coverage > 80%
|
||||
|
||||
### Code Quality
|
||||
- [ ] Follows style guide
|
||||
- [ ] No linter warnings
|
||||
- [ ] Functions < 50 lines
|
||||
- [ ] Clear variable names
|
||||
|
||||
### Security
|
||||
- [ ] No hardcoded secrets
|
||||
- [ ] Input validation present
|
||||
- [ ] SQL uses parameterized queries
|
||||
- [ ] Auth checks on protected routes
|
||||
|
||||
### Documentation
|
||||
- [ ] API changes documented
|
||||
- [ ] Complex logic has comments
|
||||
- [ ] README updated if needed
|
||||
|
||||
## NEVER Approve PRs With
|
||||
- Failing tests
|
||||
- Linter errors
|
||||
- Hardcoded credentials
|
||||
- console.log statements
|
||||
```
|
||||
|
||||
### Usage in Review
|
||||
|
||||
```
|
||||
Reviewer: "Review this PR: #123"
|
||||
|
||||
Claude (reads PR, checks against CLAUDE.md):
|
||||
"Reviewing PR #123 against team standards:
|
||||
|
||||
✓ Tests pass
|
||||
✓ Coverage maintained (85%)
|
||||
✗ Found console.log in auth.ts:42
|
||||
✗ Missing input validation in user.controller.ts:67
|
||||
✗ API changes not documented
|
||||
|
||||
Recommendation: Request changes before approval.
|
||||
|
||||
Specific issues:
|
||||
1. auth.ts:42 - Remove console.log (violates standards)
|
||||
2. user.controller.ts:67 - Add Zod validation for email field
|
||||
3. Missing: Update API.md with new /users/profile endpoint
|
||||
```
|
||||
|
||||
### Benefits
|
||||
|
||||
- **Consistent reviews**: Same standards for all reviewers
|
||||
- **Automated checks**: Claude catches issues
|
||||
- **Teaching tool**: Shows reviewers what to look for
|
||||
- **Living standards**: Update CLAUDE.md as standards evolve
|
||||
|
||||
---
|
||||
|
||||
## Workflow 6: Multi-Repository Consistency
|
||||
|
||||
### Goal
|
||||
Maintain consistent standards across multiple repositories.
|
||||
|
||||
### Setup
|
||||
|
||||
```
|
||||
~/.claude/CLAUDE.md # Personal + org standards
|
||||
|
||||
org-repo-1/
|
||||
└── .claude/
|
||||
└── CLAUDE.md # Repo-specific (imports personal)
|
||||
|
||||
org-repo-2/
|
||||
└── .claude/
|
||||
└── CLAUDE.md # Repo-specific (imports personal)
|
||||
```
|
||||
|
||||
### ~/.claude/CLAUDE.md (Shared Across All Repos)
|
||||
|
||||
```markdown
|
||||
# Organization Standards
|
||||
|
||||
Applied to all our repositories.
|
||||
|
||||
## Git Workflow
|
||||
- Branch from main
|
||||
- Squash merge PRs
|
||||
- Conventional commits
|
||||
|
||||
## Code Quality
|
||||
- Tests required
|
||||
- Linting enforced
|
||||
- 80% coverage minimum
|
||||
|
||||
## Security
|
||||
- No hardcoded secrets
|
||||
- Input validation required
|
||||
- Security review for auth changes
|
||||
|
||||
## Documentation
|
||||
@~/docs/org-standards.md
|
||||
```
|
||||
|
||||
### org-repo-1/.claude/CLAUDE.md
|
||||
|
||||
```markdown
|
||||
# Repo 1
|
||||
|
||||
Frontend React application.
|
||||
|
||||
## Repo-Specific
|
||||
- React 18 + TypeScript
|
||||
- Tailwind for styling
|
||||
- Jest + RTL for testing
|
||||
|
||||
## Tech Stack
|
||||
@docs/tech-stack.md
|
||||
|
||||
All organization standards apply (see ~/.claude/CLAUDE.md)
|
||||
```
|
||||
|
||||
### Benefits
|
||||
|
||||
- **DRY**: Don't repeat org standards in each repo
|
||||
- **Consistency**: Same standards everywhere
|
||||
- **Easy updates**: Change once, applies to all
|
||||
- **Repo specifics**: Each repo adds its unique context
|
||||
|
||||
---
|
||||
|
||||
## Workflow 7: Gradual Migration
|
||||
|
||||
### Goal
|
||||
Migrate existing documentation to CLAUDE.md progressively.
|
||||
|
||||
### Phase 1: Start Small (Week 1)
|
||||
|
||||
```markdown
|
||||
# CLAUDE.md (50 lines)
|
||||
|
||||
## Common Commands
|
||||
```bash
|
||||
npm run dev
|
||||
npm test
|
||||
npm run build
|
||||
```
|
||||
|
||||
## Key Conventions
|
||||
- 2-space indentation
|
||||
- ESLint + Prettier
|
||||
```
|
||||
|
||||
### Phase 2: Add Core Info (Week 2-3)
|
||||
|
||||
```markdown
|
||||
# CLAUDE.md (100 lines)
|
||||
|
||||
[Previous content]
|
||||
|
||||
## Tech Stack
|
||||
- Backend: Node.js + Express
|
||||
- Frontend: React + TypeScript
|
||||
- Database: PostgreSQL
|
||||
|
||||
## Architecture
|
||||
@docs/architecture.md
|
||||
|
||||
## IMPORTANT Rules
|
||||
- Tests required before merge
|
||||
- No commits to main
|
||||
```
|
||||
|
||||
### Phase 3: Import Existing Docs (Week 4)
|
||||
|
||||
```markdown
|
||||
# CLAUDE.md (150 lines)
|
||||
|
||||
[Previous content]
|
||||
|
||||
## Detailed Documentation
|
||||
- Architecture: @docs/architecture.md
|
||||
- API Reference: @docs/api.md
|
||||
- Style Guide: @docs/style-guide.md
|
||||
- Testing: @docs/testing-guide.md
|
||||
```
|
||||
|
||||
### Phase 4: Optimize (Ongoing)
|
||||
|
||||
- Move inline content to imports
|
||||
- Compress verbose sections
|
||||
- Test with team
|
||||
- Gather feedback
|
||||
- Iterate
|
||||
|
||||
### Benefits
|
||||
|
||||
- **Low risk**: Start small, grow gradually
|
||||
- **Learn as you go**: Discover what works
|
||||
- **Team adoption**: Give team time to adjust
|
||||
- **Continuous improvement**: Iterate based on usage
|
||||
|
||||
---
|
||||
|
||||
## Workflow 8: Cross-Team Collaboration
|
||||
|
||||
### Goal
|
||||
Enable multiple teams to work on shared codebase with team-specific context.
|
||||
|
||||
### Structure
|
||||
|
||||
```
|
||||
monorepo/
|
||||
├── .claude/
|
||||
│ └── CLAUDE.md # Shared standards
|
||||
├── packages/
|
||||
│ ├── frontend/
|
||||
│ │ └── .claude/
|
||||
│ │ └── CLAUDE.md # Frontend team context
|
||||
│ └── backend/
|
||||
│ └── .claude/
|
||||
│ └── CLAUDE.md # Backend team context
|
||||
```
|
||||
|
||||
### Root .claude/CLAUDE.md (Shared)
|
||||
|
||||
```markdown
|
||||
# Monorepo Standards
|
||||
|
||||
## Shared Across All Teams
|
||||
- pnpm workspaces
|
||||
- Conventional commits
|
||||
- Test coverage > 80%
|
||||
- Code review required
|
||||
|
||||
## Team-Specific Context
|
||||
- Frontend: packages/frontend/CLAUDE.md
|
||||
- Backend: packages/backend/CLAUDE.md
|
||||
|
||||
When in a package directory, team-specific context loads automatically.
|
||||
```
|
||||
|
||||
### packages/frontend/.claude/CLAUDE.md
|
||||
|
||||
```markdown
|
||||
# Frontend Team Context
|
||||
|
||||
**Team**: Frontend (React specialists)
|
||||
|
||||
## Our Stack
|
||||
- React 18 + TypeScript
|
||||
- Tailwind + shadcn/ui
|
||||
- Zustand for state
|
||||
- React Query for data
|
||||
|
||||
## Our Conventions
|
||||
- Atomic design pattern
|
||||
- Mobile-first responsive
|
||||
- Dark mode support required
|
||||
|
||||
## Our PR Process
|
||||
- 2 frontend developers must approve
|
||||
- Accessibility check required
|
||||
- Browser testing checklist
|
||||
|
||||
## Contact
|
||||
- Lead: @alice
|
||||
- Questions: #frontend-team
|
||||
```
|
||||
|
||||
### packages/backend/.claude/CLAUDE.md
|
||||
|
||||
```markdown
|
||||
# Backend Team Context
|
||||
|
||||
**Team**: Backend (API specialists)
|
||||
|
||||
## Our Stack
|
||||
- Node.js + Express + TypeScript
|
||||
- PostgreSQL + Prisma
|
||||
- Redis caching
|
||||
- JWT authentication
|
||||
|
||||
## Our Conventions
|
||||
- RESTful API design
|
||||
- OpenAPI documentation
|
||||
- Rate limiting all endpoints
|
||||
|
||||
## Our PR Process
|
||||
- 2 backend developers must approve
|
||||
- Security review for auth changes
|
||||
- Load testing for perf-critical paths
|
||||
|
||||
## Contact
|
||||
- Lead: @bob
|
||||
- Questions: #backend-team
|
||||
```
|
||||
|
||||
### Benefits
|
||||
|
||||
- **Team autonomy**: Each team defines their standards
|
||||
- **Shared foundations**: Common org-wide rules
|
||||
- **Context switching**: Right context automatically
|
||||
- **Cross-team awareness**: See other team's standards
|
||||
|
||||
---
|
||||
|
||||
## Summary: Team Success Patterns
|
||||
|
||||
1. **Start Simple**: Begin with 50-100 lines, grow organically
|
||||
2. **Version Control**: Track changes, review updates
|
||||
3. **Team Buy-In**: Get feedback, iterate together
|
||||
4. **Clear Ownership**: Assign responsibility for updates
|
||||
5. **Regular Reviews**: Monthly check for outdated content
|
||||
6. **Measure Impact**: Track onboarding time, review consistency
|
||||
7. **Document Decisions**: Use ADRs for architecture
|
||||
8. **Progressive Disclosure**: Core in CLAUDE.md, details in imports
|
||||
9. **Feature Contexts**: Use subfolders for feature-specific guidance
|
||||
10. **Cross-Repo Standards**: Share common standards across projects
|
||||
|
||||
**Goal**: Make CLAUDE.md the single source of truth for team development practices.
|
||||
@@ -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 when building plugins for Claude Code, setting up plugin structure, or configuring plugin manifests.
|
||||
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.
|
||||
---
|
||||
|
||||
# Claude Code Plugin Development
|
||||
@@ -186,66 +186,7 @@ Create `.mcp.json` for external tools:
|
||||
|
||||
## Complete Plugin Example
|
||||
|
||||
### File Structure
|
||||
|
||||
```
|
||||
weather-plugin/
|
||||
├── .claude-plugin/
|
||||
│ └── plugin.json
|
||||
├── commands/
|
||||
│ └── weather.md
|
||||
├── agents/
|
||||
│ └── forecast-analyst.md
|
||||
├── skills/
|
||||
│ └── weather-api/
|
||||
│ └── SKILL.md
|
||||
└── README.md
|
||||
```
|
||||
|
||||
### plugin.json
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "weather-plugin",
|
||||
"description": "Weather forecasting and analysis tools",
|
||||
"version": "1.0.0",
|
||||
"author": {
|
||||
"name": "Weather Team"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### commands/weather.md
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Get current weather for a location
|
||||
argument-hint: <location>
|
||||
---
|
||||
|
||||
Get the current weather conditions for: $ARGUMENTS
|
||||
|
||||
Include:
|
||||
- Temperature
|
||||
- Conditions
|
||||
- Humidity
|
||||
- Wind speed
|
||||
```
|
||||
|
||||
### agents/forecast-analyst.md
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Analyzes weather patterns and forecasts
|
||||
tools: [WebFetch, Read]
|
||||
---
|
||||
|
||||
You are a weather analysis specialist. When asked about weather:
|
||||
1. Gather current conditions
|
||||
2. Analyze patterns
|
||||
3. Provide forecast insights
|
||||
4. Suggest appropriate actions
|
||||
```
|
||||
See [examples.md](examples.md) for full working plugin examples including weather-plugin, git-tools, and api-plugin.
|
||||
|
||||
## Distribution & Installation
|
||||
|
||||
@@ -459,56 +400,14 @@ allowed-tools: Read(src/**), Grep(src/**)
|
||||
|
||||
## Plugin Template
|
||||
|
||||
Use this as a starting point:
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# create-plugin.sh <plugin-name>
|
||||
|
||||
PLUGIN_NAME=$1
|
||||
|
||||
mkdir -p "$PLUGIN_NAME"/{.claude-plugin,commands,agents,skills,hooks}
|
||||
|
||||
cat > "$PLUGIN_NAME/.claude-plugin/plugin.json" << EOF
|
||||
{
|
||||
"name": "$PLUGIN_NAME",
|
||||
"description": "TODO: Add description",
|
||||
"version": "0.1.0",
|
||||
"author": {
|
||||
"name": "TODO: Add author"
|
||||
}
|
||||
}
|
||||
EOF
|
||||
|
||||
cat > "$PLUGIN_NAME/README.md" << EOF
|
||||
# $PLUGIN_NAME
|
||||
|
||||
TODO: Add plugin description
|
||||
|
||||
## Installation
|
||||
|
||||
\`\`\`
|
||||
/plugin install $PLUGIN_NAME@marketplace
|
||||
\`\`\`
|
||||
|
||||
## Features
|
||||
|
||||
TODO: List features
|
||||
|
||||
## Usage
|
||||
|
||||
TODO: Add usage examples
|
||||
EOF
|
||||
|
||||
echo "Plugin structure created in $PLUGIN_NAME/"
|
||||
```
|
||||
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-code-slash-commands/SKILL.md)
|
||||
- [Hooks Guide](../claude-code-hooks/SKILL.md)
|
||||
- [Agent Skills Guide](../claude-skills/SKILL.md)
|
||||
- [Slash Commands Guide](../claude-command-expert/SKILL.md)
|
||||
- [Hooks Guide](../claude-hooks/SKILL.md)
|
||||
- [Agent Skills Guide](../claude-skill/SKILL.md)
|
||||
|
||||
## Quick Reference
|
||||
|
||||
151
claude-code/skills/claude-skills/README.md
Normal file
151
claude-code/skills/claude-skills/README.md
Normal file
@@ -0,0 +1,151 @@
|
||||
# Skill Creator - Meta Skill for Building Agent Skills
|
||||
|
||||
A comprehensive guide for creating effective Claude Agent Skills, complete with best practices, templates, and real-world examples.
|
||||
|
||||
## What's Included
|
||||
|
||||
- **SKILL.md**: Complete best practices guide with progressive disclosure principles, structure guidelines, and development workflows
|
||||
- **examples.md**: Working examples of well-structured skills across different domains (testing, API integration, documentation)
|
||||
- **templates.md**: Ready-to-use templates for common skill types (code frameworks, workflows, reference guides, tools)
|
||||
|
||||
## Quick Start
|
||||
|
||||
### For Claude Code Users
|
||||
|
||||
1. Place this skill directory in your skills folder
|
||||
2. The skill will automatically be available when you need to create or improve skills
|
||||
3. Invoke by mentioning skill creation, or Claude will trigger it when relevant
|
||||
|
||||
### For Claude.ai Users
|
||||
|
||||
1. Zip this directory
|
||||
2. Upload via Settings > Capabilities > Upload skill
|
||||
3. Enable the skill toggle
|
||||
|
||||
## When This Skill Triggers
|
||||
|
||||
This skill activates when you:
|
||||
- Create a new Agent Skill from scratch
|
||||
- Improve or refactor an existing skill
|
||||
- Debug why a skill isn't triggering correctly
|
||||
- Need to understand skill architecture
|
||||
- Optimize skill structure for token efficiency
|
||||
|
||||
## Key Principles Covered
|
||||
|
||||
1. **Progressive Disclosure**: Three-layer architecture (metadata → instructions → resources)
|
||||
2. **Trigger Optimization**: Writing descriptions that activate at the right time
|
||||
3. **Token Efficiency**: Strategic file splitting and on-demand loading
|
||||
4. **Development Workflow**: Iterative approach to skill creation
|
||||
5. **Security Considerations**: Best practices for safe skill creation and usage
|
||||
|
||||
## Example Skills Included
|
||||
|
||||
### 1. Python Testing with pytest
|
||||
Complete guide for writing comprehensive Python tests with fixtures, parametrization, and mocking.
|
||||
|
||||
### 2. REST API Integration
|
||||
Patterns for building robust API clients with authentication, error handling, rate limiting, and pagination.
|
||||
|
||||
### 3. Technical Documentation Writer
|
||||
Templates and guidelines for creating clear API docs, README files, and code comments.
|
||||
|
||||
## Templates Available
|
||||
|
||||
- **Code Framework Skill**: For teaching libraries/frameworks
|
||||
- **Workflow/Process Skill**: For guiding through procedures
|
||||
- **Reference/Lookup Skill**: For quick information access
|
||||
- **Tool/Utility Skill**: For operating specific tools
|
||||
|
||||
## Using This Skill
|
||||
|
||||
### Creating a New Skill
|
||||
|
||||
Ask Claude: "Help me create a skill for [topic]"
|
||||
|
||||
Claude will:
|
||||
1. Guide you through choosing the right template
|
||||
2. Help write an effective description
|
||||
3. Structure content using progressive disclosure
|
||||
4. Provide examples relevant to your domain
|
||||
|
||||
### Improving an Existing Skill
|
||||
|
||||
Ask Claude: "Review my skill and suggest improvements"
|
||||
|
||||
Claude will analyze:
|
||||
- Trigger accuracy (does description match use cases?)
|
||||
- Structure optimization (can it be split for better token usage?)
|
||||
- Content clarity (are examples concrete enough?)
|
||||
- Best practices alignment
|
||||
|
||||
### Debugging Skill Triggering
|
||||
|
||||
Ask Claude: "Why isn't my skill triggering when [scenario]?"
|
||||
|
||||
Claude will check:
|
||||
- Description specificity and keywords
|
||||
- Name clarity
|
||||
- Potential conflicts with other skills
|
||||
- Whether use cases are documented
|
||||
|
||||
## Structure of a Good Skill
|
||||
|
||||
```
|
||||
my-skill/
|
||||
├── SKILL.md # Required: Main entry point with metadata
|
||||
├── examples.md # Optional: Detailed examples
|
||||
├── reference.md # Optional: Deep reference material
|
||||
├── templates/ # Optional: Reusable templates
|
||||
└── scripts/ # Optional: Executable utilities
|
||||
```
|
||||
|
||||
### Minimal Skill
|
||||
|
||||
At minimum, you need `SKILL.md` with:
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: Your Skill Name
|
||||
description: Specific description of what this does and when to use it
|
||||
---
|
||||
|
||||
[Skill content]
|
||||
```
|
||||
|
||||
## Best Practices Checklist
|
||||
|
||||
- [ ] Description is under 1024 characters and specific
|
||||
- [ ] Name is under 64 characters and clear
|
||||
- [ ] "When to Use This Skill" section is present
|
||||
- [ ] At least one concrete example is included
|
||||
- [ ] No sensitive information is hardcoded
|
||||
- [ ] Tested triggering with target scenarios
|
||||
- [ ] File splitting used for mutually exclusive content
|
||||
- [ ] Security considerations addressed
|
||||
|
||||
## Common Pitfalls Covered
|
||||
|
||||
1. **Vague descriptions** that don't trigger reliably
|
||||
2. **Overly broad content** that wastes tokens
|
||||
3. **Missing examples** that leave users guessing
|
||||
4. **Security oversights** like hardcoded credentials
|
||||
5. **Poor file organization** that loads unnecessary content
|
||||
|
||||
## Resources
|
||||
|
||||
- [Official Agent Skills Documentation](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview)
|
||||
- [Engineering Blog: Equipping Agents for the Real World](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills)
|
||||
- [Using Skills in Claude](https://support.claude.com/en/articles/12512180-using-skills-in-claude)
|
||||
|
||||
## Contributing
|
||||
|
||||
This is a meta-skill that helps create other skills. If you discover new patterns or best practices:
|
||||
|
||||
1. Test them in real skill creation scenarios
|
||||
2. Document what works and what doesn't
|
||||
3. Add to the appropriate section (SKILL.md for principles, examples.md for cases, templates.md for reusable patterns)
|
||||
|
||||
## License
|
||||
|
||||
This skill is provided as a reference implementation for creating Agent Skills. Use it freely to build your own skills.
|
||||
456
claude-code/skills/claude-skills/SKILL.md
Normal file
456
claude-code/skills/claude-skills/SKILL.md
Normal file
@@ -0,0 +1,456 @@
|
||||
---
|
||||
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.
|
||||
---
|
||||
|
||||
# Skill Creation Best Practices
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
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
|
||||
- Optimizing skill structure for token efficiency
|
||||
|
||||
## Core Principle: Progressive Disclosure
|
||||
|
||||
**Progressive disclosure is the fundamental design pattern for Agent Skills.** It works 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 - helps Claude decide if skill is relevant
|
||||
|
||||
### 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
|
||||
|
||||
### 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
|
||||
|
||||
## Skill Structure Requirements
|
||||
|
||||
### Mandatory: SKILL.md File
|
||||
|
||||
Every skill MUST have a `SKILL.md` file with YAML frontmatter:
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: Your Skill Name
|
||||
description: Clear description of what this does and when to use it
|
||||
---
|
||||
```
|
||||
|
||||
**Critical Constraints:**
|
||||
- Name: Maximum 64 characters
|
||||
- Description: Maximum 1024 characters
|
||||
- **The description is crucial** - it determines when Claude triggers the skill
|
||||
|
||||
### Optional: Additional Resources
|
||||
|
||||
Structure additional files strategically:
|
||||
|
||||
```
|
||||
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
|
||||
```
|
||||
|
||||
## 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
|
||||
|
||||
```
|
||||
[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."
|
||||
|
||||
## Best Practices for SKILL.md Content
|
||||
|
||||
### 1. Start with "When to Use This Skill"
|
||||
|
||||
Immediately clarify trigger scenarios:
|
||||
|
||||
```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
|
||||
|
||||
Use clear hierarchies and action-oriented headers:
|
||||
|
||||
```markdown
|
||||
## Quick Start
|
||||
[Minimal example to get started]
|
||||
|
||||
## Core Workflows
|
||||
### Workflow 1: [Name]
|
||||
1. Step one
|
||||
2. Step two
|
||||
|
||||
### Workflow 2: [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
|
||||
|
||||
When you need to split content, reference it clearly:
|
||||
|
||||
```markdown
|
||||
## Deep Dive: Advanced Patterns
|
||||
|
||||
For comprehensive examples of [topic], 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 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.
|
||||
|
||||
## 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 whether it triggers correctly:
|
||||
|
||||
**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 a minimal SKILL.md:
|
||||
- Clear metadata
|
||||
- One core workflow
|
||||
- A few examples
|
||||
|
||||
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
|
||||
|
||||
## Common Patterns by Domain
|
||||
|
||||
### Code Development Skills
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: [Framework/Language] [Pattern] Guide
|
||||
description: [Action] [framework] applications following [specific pattern/principles]. Use when building [type of apps] with [key requirements].
|
||||
---
|
||||
|
||||
## When to Use This Skill
|
||||
Use when building [specific project type] with [language/framework]
|
||||
|
||||
## Project Structure
|
||||
[Standard directory layout]
|
||||
|
||||
## Core Workflows
|
||||
### Create New [Component Type]
|
||||
[Step-by-step process]
|
||||
|
||||
### Common Patterns
|
||||
[Frequently used code patterns with examples]
|
||||
|
||||
## Testing Strategy
|
||||
[How to test this type of code]
|
||||
```
|
||||
|
||||
### Workflow/Process Skills
|
||||
|
||||
```markdown
|
||||
---
|
||||
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]
|
||||
|
||||
## Step-by-Step Process
|
||||
### Phase 1: [Name]
|
||||
[Detailed steps]
|
||||
|
||||
### Phase 2: [Name]
|
||||
[Detailed steps]
|
||||
|
||||
## Quality Checklist
|
||||
- [ ] [Verification step]
|
||||
- [ ] [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
|
||||
|
||||
### 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
|
||||
|
||||
**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."`
|
||||
|
||||
### 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
|
||||
|
||||
### 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
|
||||
|
||||
## Skill Metadata Checklist
|
||||
|
||||
Before finalizing a skill, verify:
|
||||
|
||||
- [ ] 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
|
||||
|
||||
## Quick Start Template
|
||||
|
||||
Use this template to begin a new skill:
|
||||
|
||||
```markdown
|
||||
---
|
||||
name:
|
||||
description:
|
||||
---
|
||||
|
||||
# [Skill Name]
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
Use this skill when:
|
||||
-
|
||||
-
|
||||
|
||||
Do NOT use this skill for:
|
||||
-
|
||||
|
||||
## Quick Start
|
||||
|
||||
[Minimal working example]
|
||||
|
||||
## Core Workflows
|
||||
|
||||
### Workflow 1: [Name]
|
||||
|
||||
1.
|
||||
2.
|
||||
3.
|
||||
|
||||
**Example:**
|
||||
```
|
||||
[Code or command]
|
||||
```
|
||||
|
||||
**Result:** [What this achieves]
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
### Issue: [Problem]
|
||||
**Solution:** [How to avoid/fix]
|
||||
|
||||
### Issue: [Problem]
|
||||
**Solution:** [How to avoid/fix]
|
||||
|
||||
## Advanced Topics
|
||||
|
||||
[Optional: complex scenarios or optimizations]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Remember**: The best skills emerge from real usage patterns. Start simple, iterate based on actual needs, and prioritize clarity over comprehensiveness.
|
||||
260
claude-code/skills/claude-skills/checklist.md
Normal file
260
claude-code/skills/claude-skills/checklist.md
Normal file
@@ -0,0 +1,260 @@
|
||||
# Skill Creation Checklist
|
||||
|
||||
Use this checklist when creating or reviewing Agent Skills to ensure quality and effectiveness.
|
||||
|
||||
## Pre-Creation
|
||||
|
||||
- [ ] Identified a real need (tested Claude on tasks where it struggled or asked repetitive questions)
|
||||
- [ ] Verified no existing skill already covers this domain
|
||||
- [ ] Defined clear trigger scenarios (when should this skill activate?)
|
||||
- [ ] Identified target audience (junior devs, experienced engineers, specific domain experts)
|
||||
|
||||
## Metadata (YAML Frontmatter)
|
||||
|
||||
- [ ] **Name** is clear and descriptive
|
||||
- [ ] Under 64 characters
|
||||
- [ ] Avoids generic terms ("Helper", "Utility")
|
||||
- [ ] Includes domain/context (e.g., "Python Testing with pytest", not just "Testing")
|
||||
|
||||
- [ ] **Description** is specific and trigger-focused
|
||||
- [ ] Under 1024 characters
|
||||
- [ ] Includes action verbs
|
||||
- [ ] Mentions primary use cases
|
||||
- [ ] Contains keywords from likely user requests
|
||||
- [ ] Specifies "Use when..." scenarios
|
||||
- [ ] Example: "Create and analyze Excel spreadsheets with formulas, formatting, and pivot tables. Use when building spreadsheet-based reports or data analysis tools."
|
||||
|
||||
## Content Structure
|
||||
|
||||
- [ ] **"When to Use This Skill"** section is present at the top
|
||||
- [ ] Lists 3-5 positive scenarios ("Use this skill when...")
|
||||
- [ ] Lists 2-3 negative scenarios ("Do NOT use this skill for...")
|
||||
- [ ] Helps Claude decide when to trigger
|
||||
|
||||
- [ ] **Quick Start** section provides minimal working example
|
||||
- [ ] Can be completed in under 5 minutes
|
||||
- [ ] Demonstrates core value proposition
|
||||
- [ ] Includes actual code/commands, not pseudocode
|
||||
|
||||
- [ ] **Core Workflows** are clearly structured
|
||||
- [ ] Each workflow has a descriptive name
|
||||
- [ ] Steps are numbered and actionable
|
||||
- [ ] Each step explains "what" and "why"
|
||||
- [ ] Workflows show expected outputs/results
|
||||
|
||||
- [ ] **Examples** are concrete and realistic
|
||||
- [ ] Use real-world scenarios, not "foo/bar" placeholders
|
||||
- [ ] Include full code, not fragments
|
||||
- [ ] Show both input and expected output
|
||||
- [ ] Cover common use cases, not just edge cases
|
||||
|
||||
## Progressive Disclosure
|
||||
|
||||
- [ ] **Main SKILL.md** contains essential information
|
||||
- [ ] Under ~3000 tokens if possible
|
||||
- [ ] Focuses on 80% use cases
|
||||
- [ ] References additional files when needed
|
||||
|
||||
- [ ] **Separate files** used strategically
|
||||
- [ ] Mutually exclusive content split (e.g., Python vs JavaScript examples)
|
||||
- [ ] Advanced topics in separate files
|
||||
- [ ] Deep reference material externalized
|
||||
- [ ] Files explicitly referenced: "See [examples.md](examples.md) for..."
|
||||
|
||||
- [ ] **Scripts** serve dual purpose
|
||||
- [ ] Executable tools Claude can run
|
||||
- [ ] Documentation through working code
|
||||
- [ ] Don't duplicate information in SKILL.md
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] **No sensitive information**
|
||||
- [ ] No hardcoded API keys, passwords, or tokens
|
||||
- [ ] No personal identifying information
|
||||
- [ ] No proprietary code without permission
|
||||
- [ ] Examples use environment variables or placeholders for secrets
|
||||
|
||||
- [ ] **Examples are tested**
|
||||
- [ ] All code examples actually run
|
||||
- [ ] Commands produce expected output
|
||||
- [ ] Dependencies are documented
|
||||
- [ ] Version-specific behavior is noted
|
||||
|
||||
- [ ] **Terminology is consistent**
|
||||
- [ ] Same terms used throughout (not "function" then "method")
|
||||
- [ ] Acronyms defined on first use
|
||||
- [ ] Domain-specific jargon explained
|
||||
|
||||
- [ ] **Navigation is clear**
|
||||
- [ ] Headers create logical hierarchy
|
||||
- [ ] Related sections are linked
|
||||
- [ ] Table of contents if skill is long
|
||||
- [ ] File references are accurate
|
||||
|
||||
## Security & Safety
|
||||
|
||||
- [ ] **Reviewed for security issues**
|
||||
- [ ] No instructions to disable security features
|
||||
- [ ] No unsafe system operations
|
||||
- [ ] Dependencies from trusted sources only
|
||||
- [ ] Network access is documented and justified
|
||||
|
||||
- [ ] **Privacy considerations**
|
||||
- [ ] No data exfiltration to unexpected locations
|
||||
- [ ] File access is scoped appropriately
|
||||
- [ ] User consent for sensitive operations
|
||||
|
||||
## Testing & Validation
|
||||
|
||||
- [ ] **Trigger accuracy tested**
|
||||
- [ ] Activates for intended scenarios
|
||||
- [ ] Doesn't activate for unrelated scenarios
|
||||
- [ ] Description keywords match user vocabulary
|
||||
|
||||
- [ ] **Content accessibility tested**
|
||||
- [ ] Referenced files load correctly
|
||||
- [ ] Scripts execute without errors
|
||||
- [ ] Relative paths are correct
|
||||
|
||||
- [ ] **Used in real scenarios**
|
||||
- [ ] Tested with actual tasks, not hypotheticals
|
||||
- [ ] Refined based on Claude's usage patterns
|
||||
- [ ] Addressed gaps discovered during use
|
||||
|
||||
## Optimization
|
||||
|
||||
- [ ] **Token efficiency considered**
|
||||
- [ ] Frequently needed info in SKILL.md
|
||||
- [ ] Rarely needed info in separate files
|
||||
- [ ] Scripts used instead of inline code where possible
|
||||
- [ ] Repetitive content templated or scripted
|
||||
|
||||
- [ ] **Scanning-friendly format**
|
||||
- [ ] Clear section headers
|
||||
- [ ] Bulleted lists for quick reading
|
||||
- [ ] Code blocks with syntax highlighting
|
||||
- [ ] Tables for comparison/reference
|
||||
|
||||
- [ ] **Progressive complexity**
|
||||
- [ ] Begins with simple concepts
|
||||
- [ ] Builds to advanced topics
|
||||
- [ ] Clear path from beginner to expert
|
||||
- [ ] Advanced sections clearly marked
|
||||
|
||||
## Documentation
|
||||
|
||||
- [ ] **README.md includes**
|
||||
- [ ] Purpose and scope
|
||||
- [ ] Installation instructions (if needed)
|
||||
- [ ] Quick start guide
|
||||
- [ ] File structure explanation
|
||||
- [ ] Link to official resources
|
||||
|
||||
- [ ] **Common pitfalls documented**
|
||||
- [ ] Known issues listed
|
||||
- [ ] Workarounds provided
|
||||
- [ ] Error messages explained
|
||||
- [ ] Troubleshooting section
|
||||
|
||||
- [ ] **Prerequisites stated**
|
||||
- [ ] Required tools/dependencies
|
||||
- [ ] Minimum versions specified
|
||||
- [ ] Assumed knowledge level
|
||||
- [ ] Setup instructions if complex
|
||||
|
||||
## Final Review
|
||||
|
||||
- [ ] Read through as a new user
|
||||
- [ ] Can someone unfamiliar follow along?
|
||||
- [ ] Are all terms defined?
|
||||
- [ ] Do examples make sense in context?
|
||||
|
||||
- [ ] Test with Claude
|
||||
- [ ] Ask Claude to use the skill on test tasks
|
||||
- [ ] Verify it triggers when expected
|
||||
- [ ] Check that instructions are clear
|
||||
- [ ] Identify any confusion or gaps
|
||||
|
||||
- [ ] Spell check and grammar
|
||||
- [ ] Professional tone maintained
|
||||
- [ ] No typos in code or commands
|
||||
- [ ] Formatting is consistent
|
||||
|
||||
- [ ] Package correctly
|
||||
- [ ] All referenced files included
|
||||
- [ ] File paths are relative, not absolute
|
||||
- [ ] Directory structure is clean
|
||||
- [ ] No unnecessary files (build artifacts, etc.)
|
||||
|
||||
## Post-Launch
|
||||
|
||||
- [ ] Monitor usage patterns
|
||||
- [ ] Track when skill triggers
|
||||
- [ ] Note when it should trigger but doesn't
|
||||
- [ ] Identify frequently asked questions
|
||||
|
||||
- [ ] Iterate based on feedback
|
||||
- [ ] Update examples that caused confusion
|
||||
- [ ] Add missing workflows discovered through use
|
||||
- [ ] Refine description if trigger accuracy is poor
|
||||
- [ ] Split or merge sections based on token usage
|
||||
|
||||
- [ ] Keep current
|
||||
- [ ] Update when dependencies change versions
|
||||
- [ ] Revise when best practices evolve
|
||||
- [ ] Add new patterns as discovered
|
||||
- [ ] Remove outdated information
|
||||
|
||||
## Template Selection
|
||||
|
||||
Choose the right starting template:
|
||||
|
||||
| If your skill... | Use template |
|
||||
|------------------|--------------|
|
||||
| Teaches a framework or library | Code Framework |
|
||||
| Guides through a multi-step process | Workflow/Process |
|
||||
| Provides quick reference info | Reference/Lookup |
|
||||
| Explains how to use a tool | Tool/Utility |
|
||||
| Doesn't fit above | Start with minimal template and build up |
|
||||
|
||||
## Common Mistakes to Avoid
|
||||
|
||||
- [ ] **Avoided**: Vague description ("Python helpers")
|
||||
- **Instead**: Specific description with use cases
|
||||
|
||||
- [ ] **Avoided**: No examples or only pseudocode
|
||||
- **Instead**: Real, runnable examples
|
||||
|
||||
- [ ] **Avoided**: Everything in one giant SKILL.md file
|
||||
- **Instead**: Strategic file splitting for token efficiency
|
||||
|
||||
- [ ] **Avoided**: "What" without "why"
|
||||
- **Instead**: Explain reasoning and trade-offs
|
||||
|
||||
- [ ] **Avoided**: Hardcoded secrets or credentials
|
||||
- **Instead**: Environment variables and configuration
|
||||
|
||||
- [ ] **Avoided**: Testing only happy path
|
||||
- **Instead**: Test errors, edge cases, and "should not trigger" scenarios
|
||||
|
||||
- [ ] **Avoided**: Generic names like "Helper" or "Utils"
|
||||
- **Instead**: Specific, searchable names
|
||||
|
||||
- [ ] **Avoided**: Assuming too much knowledge
|
||||
- **Instead**: State prerequisites and define terms
|
||||
|
||||
## Success Criteria
|
||||
|
||||
A well-crafted skill should:
|
||||
|
||||
✓ Trigger reliably for intended use cases
|
||||
✓ Load quickly (tokens optimized)
|
||||
✓ Be immediately useful (quick start works)
|
||||
✓ Scale from beginner to advanced
|
||||
✓ Remain current and maintainable
|
||||
✓ Be secure and privacy-conscious
|
||||
✓ Provide clear value over generic Claude
|
||||
|
||||
---
|
||||
|
||||
**Remember**: Skills emerge from real usage. Start minimal, test with actual tasks, and iterate based on what Claude actually needs.
|
||||
903
claude-code/skills/claude-skills/examples.md
Normal file
903
claude-code/skills/claude-skills/examples.md
Normal file
@@ -0,0 +1,903 @@
|
||||
# Skill Examples
|
||||
|
||||
This file contains complete, working examples of well-structured skills across different domains.
|
||||
|
||||
## Example 1: Python Testing Skill
|
||||
|
||||
### Structure
|
||||
```
|
||||
python-testing-skill/
|
||||
├── SKILL.md
|
||||
└── test-templates/
|
||||
├── pytest-basic.py
|
||||
└── pytest-advanced.py
|
||||
```
|
||||
|
||||
### SKILL.md
|
||||
```markdown
|
||||
---
|
||||
name: Python Testing with pytest
|
||||
description: Create comprehensive Python tests using pytest with fixtures, parametrization, and mocking. Use when writing unit tests, integration tests, or setting up test infrastructure for Python projects.
|
||||
---
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
Use this skill when:
|
||||
- Writing unit tests for Python functions and classes
|
||||
- Creating integration tests for Python applications
|
||||
- Setting up pytest configuration and fixtures
|
||||
- Implementing test parametrization for multiple scenarios
|
||||
- Mocking external dependencies in tests
|
||||
|
||||
Do NOT use this skill for:
|
||||
- Testing non-Python code
|
||||
- End-to-end browser testing (use Playwright skill instead)
|
||||
- Load testing or performance benchmarking
|
||||
|
||||
## Quick Start
|
||||
|
||||
Basic test structure:
|
||||
|
||||
```python
|
||||
import pytest
|
||||
from myapp import add_numbers
|
||||
|
||||
def test_add_numbers():
|
||||
result = add_numbers(2, 3)
|
||||
assert result == 5
|
||||
```
|
||||
|
||||
Run tests:
|
||||
```bash
|
||||
pytest tests/ -v
|
||||
```
|
||||
|
||||
## Core Workflows
|
||||
|
||||
### Workflow 1: Writing Unit Tests
|
||||
|
||||
1. Create a test file matching your source file: `test_module.py` for `module.py`
|
||||
2. Import the code to test and pytest
|
||||
3. Write test functions starting with `test_`
|
||||
4. Use assert statements for validation
|
||||
5. Run pytest from project root
|
||||
|
||||
**Example:**
|
||||
```python
|
||||
# test_calculator.py
|
||||
import pytest
|
||||
from calculator import Calculator
|
||||
|
||||
def test_addition():
|
||||
calc = Calculator()
|
||||
assert calc.add(2, 3) == 5
|
||||
assert calc.add(-1, 1) == 0
|
||||
assert calc.add(0, 0) == 0
|
||||
|
||||
def test_division_by_zero():
|
||||
calc = Calculator()
|
||||
with pytest.raises(ValueError, match="Cannot divide by zero"):
|
||||
calc.divide(10, 0)
|
||||
```
|
||||
|
||||
### Workflow 2: Using Fixtures
|
||||
|
||||
1. Create fixtures for common test setup
|
||||
2. Use `@pytest.fixture` decorator
|
||||
3. Accept fixtures as test function parameters
|
||||
4. Fixtures run automatically before tests
|
||||
|
||||
**Example:**
|
||||
```python
|
||||
import pytest
|
||||
from database import Database
|
||||
|
||||
@pytest.fixture
|
||||
def db():
|
||||
"""Provide a test database instance"""
|
||||
database = Database(":memory:")
|
||||
database.setup()
|
||||
yield database
|
||||
database.teardown()
|
||||
|
||||
def test_create_user(db):
|
||||
user = db.create_user("alice", "alice@example.com")
|
||||
assert user.name == "alice"
|
||||
assert user.email == "alice@example.com"
|
||||
|
||||
def test_query_user(db):
|
||||
db.create_user("bob", "bob@example.com")
|
||||
user = db.query_user("bob")
|
||||
assert user is not None
|
||||
```
|
||||
|
||||
### Workflow 3: Parametrized Tests
|
||||
|
||||
1. Use `@pytest.mark.parametrize` decorator
|
||||
2. Provide parameter names and test cases
|
||||
3. Test function runs once per parameter set
|
||||
|
||||
**Example:**
|
||||
```python
|
||||
import pytest
|
||||
from validators import validate_email
|
||||
|
||||
@pytest.mark.parametrize("email,expected", [
|
||||
("user@example.com", True),
|
||||
("user@domain.co.uk", True),
|
||||
("invalid@", False),
|
||||
("@example.com", False),
|
||||
("no-at-sign.com", False),
|
||||
("", False),
|
||||
])
|
||||
def test_email_validation(email, expected):
|
||||
assert validate_email(email) == expected
|
||||
```
|
||||
|
||||
### Workflow 4: Mocking External Dependencies
|
||||
|
||||
1. Import `unittest.mock` or use `pytest-mock`
|
||||
2. Use `mocker.patch()` to replace dependencies
|
||||
3. Configure mock return values or side effects
|
||||
4. Verify mock interactions
|
||||
|
||||
**Example:**
|
||||
```python
|
||||
import pytest
|
||||
from unittest.mock import Mock
|
||||
from weather_app import get_weather
|
||||
|
||||
def test_get_weather(mocker):
|
||||
# Mock the external API call
|
||||
mock_api = mocker.patch('weather_app.weather_api.fetch')
|
||||
mock_api.return_value = {
|
||||
"temperature": 72,
|
||||
"conditions": "sunny"
|
||||
}
|
||||
|
||||
result = get_weather("San Francisco")
|
||||
|
||||
assert result["temperature"] == 72
|
||||
assert result["conditions"] == "sunny"
|
||||
mock_api.assert_called_once_with("San Francisco")
|
||||
```
|
||||
|
||||
## Test Organization
|
||||
|
||||
### Project Structure
|
||||
```
|
||||
myproject/
|
||||
├── src/
|
||||
│ └── myapp/
|
||||
│ ├── __init__.py
|
||||
│ ├── core.py
|
||||
│ └── utils.py
|
||||
├── tests/
|
||||
│ ├── __init__.py
|
||||
│ ├── conftest.py # Shared fixtures
|
||||
│ ├── test_core.py
|
||||
│ └── test_utils.py
|
||||
└── pyproject.toml # pytest configuration
|
||||
```
|
||||
|
||||
### conftest.py for Shared Fixtures
|
||||
```python
|
||||
import pytest
|
||||
from myapp import create_app
|
||||
|
||||
@pytest.fixture(scope="session")
|
||||
def app():
|
||||
"""Create application for testing"""
|
||||
app = create_app(testing=True)
|
||||
return app
|
||||
|
||||
@pytest.fixture
|
||||
def client(app):
|
||||
"""Test client for making requests"""
|
||||
return app.test_client()
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
### pyproject.toml
|
||||
```toml
|
||||
[tool.pytest.ini_options]
|
||||
testpaths = ["tests"]
|
||||
python_files = ["test_*.py"]
|
||||
python_functions = ["test_*"]
|
||||
addopts = [
|
||||
"-v",
|
||||
"--strict-markers",
|
||||
"--cov=myapp",
|
||||
"--cov-report=term-missing",
|
||||
]
|
||||
markers = [
|
||||
"slow: marks tests as slow",
|
||||
"integration: marks tests as integration tests",
|
||||
]
|
||||
```
|
||||
|
||||
## Coverage Goals
|
||||
|
||||
Aim for:
|
||||
- 80%+ code coverage for business logic
|
||||
- 100% coverage for critical paths (auth, payments, data integrity)
|
||||
- Edge cases and error conditions tested
|
||||
- Integration tests for key workflows
|
||||
|
||||
Check coverage:
|
||||
```bash
|
||||
pytest --cov=myapp --cov-report=html
|
||||
open htmlcov/index.html
|
||||
```
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
### Issue: Tests Pass Locally but Fail in CI
|
||||
**Solution:**
|
||||
- Use fixtures to avoid state pollution between tests
|
||||
- Don't rely on file system state or specific paths
|
||||
- Mock time-dependent functionality
|
||||
- Set explicit random seeds for reproducibility
|
||||
|
||||
### Issue: Slow Test Suite
|
||||
**Solution:**
|
||||
- Use `@pytest.mark.slow` for slow tests, run separately
|
||||
- Mock external API calls instead of making real requests
|
||||
- Use in-memory databases for tests
|
||||
- Run fast unit tests before slow integration tests
|
||||
|
||||
### Issue: Fixtures Not Running
|
||||
**Solution:**
|
||||
- Ensure fixture name matches parameter name exactly
|
||||
- Check fixture scope (function/class/module/session)
|
||||
- Verify conftest.py is in correct location
|
||||
|
||||
## Advanced Techniques
|
||||
|
||||
### Async Testing
|
||||
```python
|
||||
import pytest
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_async_function():
|
||||
result = await async_fetch_data()
|
||||
assert result["status"] == "success"
|
||||
```
|
||||
|
||||
### Testing Exceptions with Context
|
||||
```python
|
||||
def test_invalid_input():
|
||||
with pytest.raises(ValueError) as exc_info:
|
||||
process_data(invalid_input)
|
||||
assert "expected format" in str(exc_info.value)
|
||||
```
|
||||
|
||||
### Temporary File Testing
|
||||
```python
|
||||
def test_file_processing(tmp_path):
|
||||
# tmp_path is a pytest fixture providing a temporary directory
|
||||
test_file = tmp_path / "test.txt"
|
||||
test_file.write_text("test content")
|
||||
|
||||
result = process_file(test_file)
|
||||
assert result.success
|
||||
```
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Example 2: API Integration Skill
|
||||
|
||||
### SKILL.md
|
||||
```markdown
|
||||
---
|
||||
name: REST API Integration
|
||||
description: Design and implement RESTful API integrations with proper error handling, authentication, and rate limiting. Use when building API clients or integrating third-party services.
|
||||
---
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
Use this skill when:
|
||||
- Integrating third-party REST APIs into your application
|
||||
- Building API client libraries
|
||||
- Implementing API authentication flows (OAuth, JWT, API keys)
|
||||
- Handling rate limiting and retries
|
||||
- Creating robust error handling for API calls
|
||||
|
||||
Do NOT use this skill for:
|
||||
- GraphQL APIs (different query paradigm)
|
||||
- gRPC or WebSocket connections
|
||||
- Building API servers (use framework-specific skills)
|
||||
|
||||
## Quick Start
|
||||
|
||||
Basic API client structure:
|
||||
|
||||
```python
|
||||
import requests
|
||||
|
||||
class APIClient:
|
||||
def __init__(self, base_url, api_key):
|
||||
self.base_url = base_url
|
||||
self.session = requests.Session()
|
||||
self.session.headers.update({
|
||||
"Authorization": f"Bearer {api_key}",
|
||||
"Content-Type": "application/json"
|
||||
})
|
||||
|
||||
def get(self, endpoint):
|
||||
response = self.session.get(f"{self.base_url}{endpoint}")
|
||||
response.raise_for_status()
|
||||
return response.json()
|
||||
```
|
||||
|
||||
## Core Workflows
|
||||
|
||||
### Workflow 1: Implementing Authentication
|
||||
|
||||
**API Key Authentication:**
|
||||
```python
|
||||
class APIKeyClient:
|
||||
def __init__(self, api_key):
|
||||
self.headers = {"X-API-Key": api_key}
|
||||
|
||||
def request(self, method, url, **kwargs):
|
||||
kwargs.setdefault('headers', {}).update(self.headers)
|
||||
return requests.request(method, url, **kwargs)
|
||||
```
|
||||
|
||||
**OAuth 2.0 Flow:**
|
||||
```python
|
||||
from requests_oauthlib import OAuth2Session
|
||||
|
||||
class OAuthClient:
|
||||
def __init__(self, client_id, client_secret, redirect_uri):
|
||||
self.client_id = client_id
|
||||
self.client_secret = client_secret
|
||||
self.redirect_uri = redirect_uri
|
||||
self.session = None
|
||||
|
||||
def get_authorization_url(self, authorization_base_url):
|
||||
oauth = OAuth2Session(self.client_id, redirect_uri=self.redirect_uri)
|
||||
authorization_url, state = oauth.authorization_url(authorization_base_url)
|
||||
return authorization_url, state
|
||||
|
||||
def fetch_token(self, token_url, authorization_response):
|
||||
oauth = OAuth2Session(self.client_id, redirect_uri=self.redirect_uri)
|
||||
token = oauth.fetch_token(
|
||||
token_url,
|
||||
authorization_response=authorization_response,
|
||||
client_secret=self.client_secret
|
||||
)
|
||||
self.session = oauth
|
||||
return token
|
||||
```
|
||||
|
||||
### Workflow 2: Error Handling and Retries
|
||||
|
||||
```python
|
||||
import time
|
||||
from requests.adapters import HTTPAdapter
|
||||
from requests.packages.urllib3.util.retry import Retry
|
||||
|
||||
class RobustAPIClient:
|
||||
def __init__(self, base_url, api_key, max_retries=3):
|
||||
self.base_url = base_url
|
||||
self.session = requests.Session()
|
||||
|
||||
# Configure retry strategy
|
||||
retry_strategy = Retry(
|
||||
total=max_retries,
|
||||
backoff_factor=1,
|
||||
status_forcelist=[429, 500, 502, 503, 504],
|
||||
allowed_methods=["GET", "POST", "PUT", "DELETE"]
|
||||
)
|
||||
adapter = HTTPAdapter(max_retries=retry_strategy)
|
||||
self.session.mount("http://", adapter)
|
||||
self.session.mount("https://", adapter)
|
||||
|
||||
self.session.headers.update({
|
||||
"Authorization": f"Bearer {api_key}"
|
||||
})
|
||||
|
||||
def request(self, method, endpoint, **kwargs):
|
||||
url = f"{self.base_url}{endpoint}"
|
||||
try:
|
||||
response = self.session.request(method, url, **kwargs)
|
||||
response.raise_for_status()
|
||||
return response.json()
|
||||
except requests.exceptions.HTTPError as e:
|
||||
if e.response.status_code == 401:
|
||||
raise AuthenticationError("Invalid or expired API key")
|
||||
elif e.response.status_code == 404:
|
||||
raise NotFoundError(f"Resource not found: {endpoint}")
|
||||
elif e.response.status_code == 429:
|
||||
raise RateLimitError("Rate limit exceeded")
|
||||
else:
|
||||
raise APIError(f"API request failed: {e}")
|
||||
except requests.exceptions.RequestException as e:
|
||||
raise APIError(f"Network error: {e}")
|
||||
|
||||
class APIError(Exception): pass
|
||||
class AuthenticationError(APIError): pass
|
||||
class NotFoundError(APIError): pass
|
||||
class RateLimitError(APIError): pass
|
||||
```
|
||||
|
||||
### Workflow 3: Rate Limiting
|
||||
|
||||
```python
|
||||
import time
|
||||
from threading import Lock
|
||||
|
||||
class RateLimiter:
|
||||
def __init__(self, calls_per_second):
|
||||
self.calls_per_second = calls_per_second
|
||||
self.min_interval = 1.0 / calls_per_second
|
||||
self.last_call = 0
|
||||
self.lock = Lock()
|
||||
|
||||
def __call__(self, func):
|
||||
def wrapper(*args, **kwargs):
|
||||
with self.lock:
|
||||
elapsed = time.time() - self.last_call
|
||||
if elapsed < self.min_interval:
|
||||
time.sleep(self.min_interval - elapsed)
|
||||
self.last_call = time.time()
|
||||
return func(*args, **kwargs)
|
||||
return wrapper
|
||||
|
||||
class RateLimitedClient:
|
||||
def __init__(self, base_url, api_key, rate_limit=10):
|
||||
self.client = APIClient(base_url, api_key)
|
||||
self.limiter = RateLimiter(rate_limit)
|
||||
|
||||
@property
|
||||
def get(self):
|
||||
return self.limiter(self.client.get)
|
||||
|
||||
@property
|
||||
def post(self):
|
||||
return self.limiter(self.client.post)
|
||||
```
|
||||
|
||||
### Workflow 4: Pagination Handling
|
||||
|
||||
```python
|
||||
class PaginatedAPIClient(APIClient):
|
||||
def get_all_pages(self, endpoint, params=None):
|
||||
"""Fetch all pages of results"""
|
||||
results = []
|
||||
page = 1
|
||||
params = params or {}
|
||||
|
||||
while True:
|
||||
params['page'] = page
|
||||
response = self.get(endpoint, params=params)
|
||||
|
||||
# Adjust based on API response structure
|
||||
items = response.get('items', [])
|
||||
results.extend(items)
|
||||
|
||||
# Check if more pages exist
|
||||
if not response.get('has_more', False):
|
||||
break
|
||||
|
||||
page += 1
|
||||
|
||||
return results
|
||||
|
||||
def get_all_cursor(self, endpoint, params=None):
|
||||
"""Fetch all results using cursor-based pagination"""
|
||||
results = []
|
||||
cursor = None
|
||||
params = params or {}
|
||||
|
||||
while True:
|
||||
if cursor:
|
||||
params['cursor'] = cursor
|
||||
|
||||
response = self.get(endpoint, params=params)
|
||||
items = response.get('data', [])
|
||||
results.extend(items)
|
||||
|
||||
cursor = response.get('next_cursor')
|
||||
if not cursor:
|
||||
break
|
||||
|
||||
return results
|
||||
```
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Request Caching
|
||||
```python
|
||||
from functools import lru_cache
|
||||
import hashlib
|
||||
import json
|
||||
|
||||
class CachedAPIClient(APIClient):
|
||||
def __init__(self, base_url, api_key, cache_ttl=300):
|
||||
super().__init__(base_url, api_key)
|
||||
self.cache = {}
|
||||
self.cache_ttl = cache_ttl
|
||||
|
||||
def _cache_key(self, method, endpoint, params):
|
||||
key_data = f"{method}:{endpoint}:{json.dumps(params, sort_keys=True)}"
|
||||
return hashlib.md5(key_data.encode()).hexdigest()
|
||||
|
||||
def get_cached(self, endpoint, params=None):
|
||||
cache_key = self._cache_key("GET", endpoint, params or {})
|
||||
|
||||
if cache_key in self.cache:
|
||||
cached_data, cached_time = self.cache[cache_key]
|
||||
if time.time() - cached_time < self.cache_ttl:
|
||||
return cached_data
|
||||
|
||||
data = self.get(endpoint, params=params)
|
||||
self.cache[cache_key] = (data, time.time())
|
||||
return data
|
||||
```
|
||||
|
||||
### Webhook Signature Verification
|
||||
```python
|
||||
import hmac
|
||||
import hashlib
|
||||
|
||||
class WebhookValidator:
|
||||
def __init__(self, secret):
|
||||
self.secret = secret.encode()
|
||||
|
||||
def verify_signature(self, payload, signature_header):
|
||||
"""Verify webhook signature"""
|
||||
expected_signature = hmac.new(
|
||||
self.secret,
|
||||
payload.encode(),
|
||||
hashlib.sha256
|
||||
).hexdigest()
|
||||
|
||||
return hmac.compare_digest(expected_signature, signature_header)
|
||||
```
|
||||
|
||||
## Testing API Integrations
|
||||
|
||||
### Using responses Library
|
||||
```python
|
||||
import responses
|
||||
import requests
|
||||
|
||||
@responses.activate
|
||||
def test_api_get():
|
||||
# Mock the API response
|
||||
responses.add(
|
||||
responses.GET,
|
||||
'https://api.example.com/users/123',
|
||||
json={'id': 123, 'name': 'Alice'},
|
||||
status=200
|
||||
)
|
||||
|
||||
client = APIClient('https://api.example.com', 'test-key')
|
||||
user = client.get('/users/123')
|
||||
|
||||
assert user['name'] == 'Alice'
|
||||
|
||||
@responses.activate
|
||||
def test_api_error_handling():
|
||||
responses.add(
|
||||
responses.GET,
|
||||
'https://api.example.com/users/999',
|
||||
json={'error': 'Not found'},
|
||||
status=404
|
||||
)
|
||||
|
||||
client = RobustAPIClient('https://api.example.com', 'test-key')
|
||||
|
||||
with pytest.raises(NotFoundError):
|
||||
client.request('GET', '/users/999')
|
||||
```
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
### Issue: Leaking API Keys
|
||||
**Solution:** Never hardcode keys. Use environment variables or secret management:
|
||||
```python
|
||||
import os
|
||||
|
||||
api_key = os.environ.get('API_KEY')
|
||||
if not api_key:
|
||||
raise ValueError("API_KEY environment variable not set")
|
||||
```
|
||||
|
||||
### Issue: Not Handling Rate Limits
|
||||
**Solution:** Implement exponential backoff and respect rate limit headers:
|
||||
```python
|
||||
def handle_rate_limit(response):
|
||||
if response.status_code == 429:
|
||||
retry_after = int(response.headers.get('Retry-After', 60))
|
||||
time.sleep(retry_after)
|
||||
# Retry request
|
||||
```
|
||||
|
||||
### Issue: Timeout Issues
|
||||
**Solution:** Always set timeouts:
|
||||
```python
|
||||
response = self.session.get(url, timeout=(3.0, 10.0)) # (connect, read)
|
||||
```
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Example 3: Documentation Skill
|
||||
|
||||
### SKILL.md
|
||||
```markdown
|
||||
---
|
||||
name: Technical Documentation Writer
|
||||
description: Create clear, comprehensive technical documentation including API docs, README files, user guides, and code comments. Use when documenting code, APIs, or writing user-facing technical content.
|
||||
---
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
Use this skill when:
|
||||
- Writing README.md files for repositories
|
||||
- Documenting APIs (REST, GraphQL, SDKs)
|
||||
- Creating user guides and tutorials
|
||||
- Writing inline code documentation
|
||||
- Building developer onboarding materials
|
||||
|
||||
Do NOT use this skill for:
|
||||
- Marketing copy or sales content
|
||||
- Academic papers or research documentation
|
||||
- Legal or compliance documentation
|
||||
|
||||
## Core Principles
|
||||
|
||||
1. **Write for your audience**: Junior developers need more context than senior engineers
|
||||
2. **Show, don't just tell**: Include code examples for every concept
|
||||
3. **Start with "why"**: Explain the purpose before the implementation
|
||||
4. **Maintain consistency**: Use the same terminology throughout
|
||||
5. **Keep it current**: Documentation that's out of date is worse than no documentation
|
||||
|
||||
## README.md Template
|
||||
|
||||
```markdown
|
||||
# Project Name
|
||||
|
||||
Brief (1-2 sentence) description of what this project does.
|
||||
|
||||
## Features
|
||||
|
||||
- Key feature 1
|
||||
- Key feature 2
|
||||
- Key feature 3
|
||||
|
||||
## Installation
|
||||
|
||||
\```bash
|
||||
npm install project-name
|
||||
\```
|
||||
|
||||
## Quick Start
|
||||
|
||||
\```javascript
|
||||
const Project = require('project-name');
|
||||
|
||||
const instance = new Project({
|
||||
apiKey: 'your-api-key'
|
||||
});
|
||||
|
||||
const result = await instance.doSomething();
|
||||
console.log(result);
|
||||
\```
|
||||
|
||||
## Documentation
|
||||
|
||||
Full documentation available at [link]
|
||||
|
||||
## Configuration
|
||||
|
||||
| Option | Type | Default | Description |
|
||||
|--------|------|---------|-------------|
|
||||
| apiKey | string | required | Your API key |
|
||||
| timeout | number | 5000 | Request timeout in ms |
|
||||
|
||||
## Examples
|
||||
|
||||
### Example 1: Basic Usage
|
||||
[Code example with explanation]
|
||||
|
||||
### Example 2: Advanced Pattern
|
||||
[Code example with explanation]
|
||||
|
||||
## Contributing
|
||||
|
||||
See [CONTRIBUTING.md](CONTRIBUTING.md)
|
||||
|
||||
## License
|
||||
|
||||
[License type] - see [LICENSE](LICENSE)
|
||||
```
|
||||
|
||||
## API Documentation Template
|
||||
|
||||
```markdown
|
||||
## endpoint_name
|
||||
|
||||
Brief description of what this endpoint does.
|
||||
|
||||
### HTTP Request
|
||||
|
||||
\```
|
||||
POST /api/v1/resource
|
||||
\```
|
||||
|
||||
### Parameters
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| name | string | Yes | Resource name |
|
||||
| type | string | No | Resource type (default: "standard") |
|
||||
| metadata | object | No | Additional metadata |
|
||||
|
||||
### Request Example
|
||||
|
||||
\```json
|
||||
{
|
||||
"name": "example-resource",
|
||||
"type": "premium",
|
||||
"metadata": {
|
||||
"created_by": "user123"
|
||||
}
|
||||
}
|
||||
\```
|
||||
|
||||
### Response
|
||||
|
||||
\```json
|
||||
{
|
||||
"id": "res_abc123",
|
||||
"name": "example-resource",
|
||||
"type": "premium",
|
||||
"status": "active",
|
||||
"created_at": "2024-01-15T10:30:00Z"
|
||||
}
|
||||
\```
|
||||
|
||||
### Errors
|
||||
|
||||
| Status Code | Error Code | Description |
|
||||
|-------------|------------|-------------|
|
||||
| 400 | invalid_name | Name contains invalid characters |
|
||||
| 401 | unauthorized | Invalid or missing API key |
|
||||
| 409 | duplicate | Resource with this name already exists |
|
||||
|
||||
### Example Usage
|
||||
|
||||
\```python
|
||||
import requests
|
||||
|
||||
response = requests.post(
|
||||
'https://api.example.com/api/v1/resource',
|
||||
headers={'Authorization': 'Bearer YOUR_API_KEY'},
|
||||
json={
|
||||
'name': 'example-resource',
|
||||
'type': 'premium'
|
||||
}
|
||||
)
|
||||
|
||||
resource = response.json()
|
||||
print(f"Created resource: {resource['id']}")
|
||||
\```
|
||||
```
|
||||
|
||||
## Code Comment Guidelines
|
||||
|
||||
### Function Documentation
|
||||
|
||||
**Python (docstring):**
|
||||
```python
|
||||
def calculate_discount(price: float, discount_percent: float, min_price: float = 0) -> float:
|
||||
"""
|
||||
Calculate discounted price with minimum price floor.
|
||||
|
||||
Args:
|
||||
price: Original price before discount
|
||||
discount_percent: Discount percentage (0-100)
|
||||
min_price: Minimum price floor (default: 0)
|
||||
|
||||
Returns:
|
||||
Final price after applying discount, never below min_price
|
||||
|
||||
Raises:
|
||||
ValueError: If discount_percent is not between 0 and 100
|
||||
ValueError: If price or min_price is negative
|
||||
|
||||
Examples:
|
||||
>>> calculate_discount(100, 20)
|
||||
80.0
|
||||
>>> calculate_discount(100, 20, min_price=85)
|
||||
85.0
|
||||
"""
|
||||
if not 0 <= discount_percent <= 100:
|
||||
raise ValueError("Discount percent must be between 0 and 100")
|
||||
if price < 0 or min_price < 0:
|
||||
raise ValueError("Prices cannot be negative")
|
||||
|
||||
discounted = price * (1 - discount_percent / 100)
|
||||
return max(discounted, min_price)
|
||||
```
|
||||
|
||||
**JavaScript (JSDoc):**
|
||||
```javascript
|
||||
/**
|
||||
* Fetch user data from the API with caching
|
||||
*
|
||||
* @param {string} userId - The unique user identifier
|
||||
* @param {Object} options - Configuration options
|
||||
* @param {boolean} [options.skipCache=false] - Whether to bypass cache
|
||||
* @param {number} [options.timeout=5000] - Request timeout in ms
|
||||
* @returns {Promise<User>} The user object
|
||||
* @throws {NotFoundError} If user doesn't exist
|
||||
* @throws {APIError} If the API request fails
|
||||
*
|
||||
* @example
|
||||
* const user = await fetchUser('user123');
|
||||
* console.log(user.name);
|
||||
*
|
||||
* @example
|
||||
* // Skip cache for fresh data
|
||||
* const user = await fetchUser('user123', { skipCache: true });
|
||||
*/
|
||||
async function fetchUser(userId, options = {}) {
|
||||
// Implementation
|
||||
}
|
||||
```
|
||||
|
||||
### Inline Comments
|
||||
|
||||
**Good inline comments explain "why", not "what":**
|
||||
|
||||
```python
|
||||
# Good: Explains reasoning
|
||||
# Use a Set for O(1) lookup time since we'll be checking membership frequently
|
||||
seen_ids = set()
|
||||
|
||||
# Bad: Just repeats what the code says
|
||||
# Create a set called seen_ids
|
||||
seen_ids = set()
|
||||
```
|
||||
|
||||
```python
|
||||
# Good: Explains non-obvious behavior
|
||||
# Delay between requests to avoid hitting rate limit (10 req/sec)
|
||||
time.sleep(0.1)
|
||||
|
||||
# Bad: States the obvious
|
||||
# Sleep for 0.1 seconds
|
||||
time.sleep(0.1)
|
||||
```
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
### Issue: Documentation Out of Sync with Code
|
||||
**Solution:**
|
||||
- Keep docs close to code (docstrings, inline comments)
|
||||
- Auto-generate API docs from code when possible
|
||||
- Include doc updates in pull request checklist
|
||||
- Set up CI checks for documentation completeness
|
||||
|
||||
### Issue: Too Much or Too Little Detail
|
||||
**Solution:**
|
||||
- README: High-level overview + quick start
|
||||
- API Docs: Complete reference for every parameter
|
||||
- Tutorials: Step-by-step with context
|
||||
- Code Comments: Why, not what
|
||||
|
||||
### Issue: Examples Don't Run
|
||||
**Solution:**
|
||||
- Test all code examples as part of CI
|
||||
- Use tools like doctest (Python) or jsdoc-to-markdown
|
||||
- Include a "examples" directory with runnable code
|
||||
- Version examples alongside code releases
|
||||
```
|
||||
729
claude-code/skills/claude-skills/templates.md
Normal file
729
claude-code/skills/claude-skills/templates.md
Normal file
@@ -0,0 +1,729 @@
|
||||
# Skill Templates
|
||||
|
||||
Ready-to-use templates for common skill types. Copy and customize for your needs.
|
||||
|
||||
## Template 1: Code Framework Skill
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: [Framework Name] Development
|
||||
description: Build [type of applications] using [framework] following [key principles/patterns]. Use when creating [specific project types] with [key requirements].
|
||||
---
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
Use this skill when:
|
||||
- Building [specific type] applications with [framework]
|
||||
- Implementing [key feature] using [framework] patterns
|
||||
- Setting up [framework] projects with best practices
|
||||
|
||||
Do NOT use this skill for:
|
||||
- [Related but different framework]
|
||||
- [Different type of application]
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- [Framework] version X.X or higher
|
||||
- [Required dependencies]
|
||||
- Basic understanding of [concepts]
|
||||
|
||||
## Quick Start
|
||||
|
||||
Create a new project:
|
||||
|
||||
\```bash
|
||||
[command to create project]
|
||||
\```
|
||||
|
||||
Basic structure:
|
||||
|
||||
\```[language]
|
||||
[Minimal working example]
|
||||
\```
|
||||
|
||||
Run the application:
|
||||
|
||||
\```bash
|
||||
[command to run]
|
||||
\```
|
||||
|
||||
## Project Structure
|
||||
|
||||
\```
|
||||
project-name/
|
||||
├── src/
|
||||
│ ├── [key directory 1]/
|
||||
│ ├── [key directory 2]/
|
||||
│ └── [key file]
|
||||
├── tests/
|
||||
├── [config file]
|
||||
└── README.md
|
||||
\```
|
||||
|
||||
## Core Patterns
|
||||
|
||||
### Pattern 1: [Name]
|
||||
|
||||
**When to use:** [Scenario]
|
||||
|
||||
**Implementation:**
|
||||
|
||||
\```[language]
|
||||
[Code example]
|
||||
\```
|
||||
|
||||
**Key points:**
|
||||
- [Important detail]
|
||||
- [Important detail]
|
||||
|
||||
### Pattern 2: [Name]
|
||||
|
||||
**When to use:** [Scenario]
|
||||
|
||||
**Implementation:**
|
||||
|
||||
\```[language]
|
||||
[Code example]
|
||||
\```
|
||||
|
||||
## Common Tasks
|
||||
|
||||
### Task 1: [Name]
|
||||
|
||||
1. [Step]
|
||||
2. [Step]
|
||||
3. [Step]
|
||||
|
||||
**Example:**
|
||||
\```[language]
|
||||
[Code]
|
||||
\```
|
||||
|
||||
### Task 2: [Name]
|
||||
|
||||
1. [Step]
|
||||
2. [Step]
|
||||
3. [Step]
|
||||
|
||||
**Example:**
|
||||
\```[language]
|
||||
[Code]
|
||||
\```
|
||||
|
||||
## Configuration
|
||||
|
||||
### [Config File Name]
|
||||
|
||||
\```[format]
|
||||
[Example configuration]
|
||||
\```
|
||||
|
||||
**Options:**
|
||||
|
||||
| Option | Type | Default | Description |
|
||||
|--------|------|---------|-------------|
|
||||
| [name] | [type] | [default] | [description] |
|
||||
|
||||
## Testing
|
||||
|
||||
### Unit Tests
|
||||
|
||||
\```[language]
|
||||
[Test example]
|
||||
\```
|
||||
|
||||
### Integration Tests
|
||||
|
||||
\```[language]
|
||||
[Test example]
|
||||
\```
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
### Issue: [Problem]
|
||||
**Solution:** [How to fix/avoid]
|
||||
|
||||
### Issue: [Problem]
|
||||
**Solution:** [How to fix/avoid]
|
||||
|
||||
## Advanced Topics
|
||||
|
||||
### [Topic 1]
|
||||
[Brief explanation and example]
|
||||
|
||||
### [Topic 2]
|
||||
[Brief explanation and example]
|
||||
|
||||
## Resources
|
||||
|
||||
- Official Documentation: [link]
|
||||
- Best Practices Guide: [link]
|
||||
- Community Examples: [link]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Template 2: Workflow/Process Skill
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: [Process Name]
|
||||
description: [Action verb] for [domain/purpose] following [methodology/standard]. Use when [primary scenario] and [key differentiator].
|
||||
---
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
Use this skill when:
|
||||
- [Primary use case]
|
||||
- [Secondary use case]
|
||||
- [Edge case to include]
|
||||
|
||||
Do NOT use this skill for:
|
||||
- [Common confusion case]
|
||||
- [Related but different process]
|
||||
|
||||
## Overview
|
||||
|
||||
[Brief explanation of what this process achieves and why it matters]
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before starting, ensure you have:
|
||||
- [ ] [Requirement 1]
|
||||
- [ ] [Requirement 2]
|
||||
- [ ] [Requirement 3]
|
||||
|
||||
## Process Steps
|
||||
|
||||
### Phase 1: [Name]
|
||||
|
||||
**Goal:** [What this phase accomplishes]
|
||||
|
||||
**Steps:**
|
||||
|
||||
1. **[Step name]**
|
||||
- [Detailed action]
|
||||
- [Why this matters]
|
||||
- **Output:** [What you should have after this step]
|
||||
|
||||
2. **[Step name]**
|
||||
- [Detailed action]
|
||||
- [Why this matters]
|
||||
- **Output:** [What you should have after this step]
|
||||
|
||||
**Checkpoint:** [How to verify this phase is complete]
|
||||
|
||||
### Phase 2: [Name]
|
||||
|
||||
**Goal:** [What this phase accomplishes]
|
||||
|
||||
**Steps:**
|
||||
|
||||
1. **[Step name]**
|
||||
- [Detailed action]
|
||||
- [Why this matters]
|
||||
- **Output:** [What you should have after this step]
|
||||
|
||||
2. **[Step name]**
|
||||
- [Detailed action]
|
||||
- [Why this matters]
|
||||
- **Output:** [What you should have after this step]
|
||||
|
||||
**Checkpoint:** [How to verify this phase is complete]
|
||||
|
||||
### Phase 3: [Name]
|
||||
|
||||
**Goal:** [What this phase accomplishes]
|
||||
|
||||
**Steps:**
|
||||
|
||||
1. **[Step name]**
|
||||
- [Detailed action]
|
||||
- [Why this matters]
|
||||
- **Output:** [What you should have after this step]
|
||||
|
||||
**Checkpoint:** [How to verify this phase is complete]
|
||||
|
||||
## Decision Points
|
||||
|
||||
### Decision 1: [Name]
|
||||
|
||||
**When:** [At what point in the process]
|
||||
|
||||
**Question:** [What you need to decide]
|
||||
|
||||
**Options:**
|
||||
- **Option A:** [Description] → Proceed to [next step/phase]
|
||||
- **Option B:** [Description] → Proceed to [next step/phase]
|
||||
|
||||
### Decision 2: [Name]
|
||||
|
||||
**When:** [At what point in the process]
|
||||
|
||||
**Question:** [What you need to decide]
|
||||
|
||||
**Options:**
|
||||
- **Option A:** [Description] → Proceed to [next step/phase]
|
||||
- **Option B:** [Description] → Proceed to [next step/phase]
|
||||
|
||||
## Quality Checklist
|
||||
|
||||
Before considering the process complete, verify:
|
||||
|
||||
- [ ] [Quality criterion 1]
|
||||
- [ ] [Quality criterion 2]
|
||||
- [ ] [Quality criterion 3]
|
||||
- [ ] [Quality criterion 4]
|
||||
|
||||
## Common Scenarios
|
||||
|
||||
### Scenario 1: [Name]
|
||||
|
||||
**Situation:** [When this applies]
|
||||
|
||||
**Approach:**
|
||||
1. [Specific step for this scenario]
|
||||
2. [Specific step for this scenario]
|
||||
|
||||
### Scenario 2: [Name]
|
||||
|
||||
**Situation:** [When this applies]
|
||||
|
||||
**Approach:**
|
||||
1. [Specific step for this scenario]
|
||||
2. [Specific step for this scenario]
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Problem: [Issue]
|
||||
**Symptoms:** [How you know this is happening]
|
||||
**Solution:** [Steps to resolve]
|
||||
|
||||
### Problem: [Issue]
|
||||
**Symptoms:** [How you know this is happening]
|
||||
**Solution:** [Steps to resolve]
|
||||
|
||||
## Examples
|
||||
|
||||
### Example 1: [Scenario Name]
|
||||
|
||||
**Context:** [Background and requirements]
|
||||
|
||||
**Process:**
|
||||
|
||||
1. [What was done in Phase 1]
|
||||
2. [What was done in Phase 2]
|
||||
3. [What was done in Phase 3]
|
||||
|
||||
**Outcome:** [What was achieved]
|
||||
|
||||
**Lessons learned:** [Key insights]
|
||||
|
||||
### Example 2: [Scenario Name]
|
||||
|
||||
**Context:** [Background and requirements]
|
||||
|
||||
**Process:**
|
||||
|
||||
1. [What was done in Phase 1]
|
||||
2. [What was done in Phase 2]
|
||||
3. [What was done in Phase 3]
|
||||
|
||||
**Outcome:** [What was achieved]
|
||||
|
||||
**Lessons learned:** [Key insights]
|
||||
|
||||
## Templates and Tools
|
||||
|
||||
### Template 1: [Name]
|
||||
|
||||
\```
|
||||
[Template content]
|
||||
\```
|
||||
|
||||
### Template 2: [Name]
|
||||
|
||||
\```
|
||||
[Template content]
|
||||
\```
|
||||
|
||||
## References
|
||||
|
||||
- [Resource 1]
|
||||
- [Resource 2]
|
||||
- [Resource 3]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Template 3: Reference/Lookup Skill
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: [Topic] Reference
|
||||
description: Quick reference for [specific domain/tool/technology] covering [key aspects]. Use when [looking up/configuring/troubleshooting] [specific scenarios].
|
||||
---
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
Use this skill when:
|
||||
- Looking up [specific information type]
|
||||
- Configuring [system/tool]
|
||||
- Troubleshooting [specific issues]
|
||||
|
||||
Do NOT use this skill for:
|
||||
- [Different but related topic]
|
||||
- [Step-by-step tutorials - refer to X skill instead]
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### Most Common Operations
|
||||
|
||||
| Operation | Command/Syntax | Example |
|
||||
|-----------|----------------|---------|
|
||||
| [Operation 1] | `[syntax]` | `[example]` |
|
||||
| [Operation 2] | `[syntax]` | `[example]` |
|
||||
| [Operation 3] | `[syntax]` | `[example]` |
|
||||
|
||||
## Command Reference
|
||||
|
||||
### Category 1: [Name]
|
||||
|
||||
#### [command_name]
|
||||
|
||||
**Purpose:** [What it does]
|
||||
|
||||
**Syntax:**
|
||||
\```
|
||||
[command syntax]
|
||||
\```
|
||||
|
||||
**Options:**
|
||||
- `[option]`: [description]
|
||||
- `[option]`: [description]
|
||||
|
||||
**Examples:**
|
||||
\```
|
||||
[example 1]
|
||||
[example 2]
|
||||
\```
|
||||
|
||||
#### [command_name]
|
||||
|
||||
**Purpose:** [What it does]
|
||||
|
||||
**Syntax:**
|
||||
\```
|
||||
[command syntax]
|
||||
\```
|
||||
|
||||
**Options:**
|
||||
- `[option]`: [description]
|
||||
- `[option]`: [description]
|
||||
|
||||
**Examples:**
|
||||
\```
|
||||
[example 1]
|
||||
[example 2]
|
||||
\```
|
||||
|
||||
### Category 2: [Name]
|
||||
|
||||
[Similar structure as Category 1]
|
||||
|
||||
## Configuration Reference
|
||||
|
||||
### [Configuration File/Section Name]
|
||||
|
||||
**Location:** `[path/to/config]`
|
||||
|
||||
**Format:** [format type]
|
||||
|
||||
**Common Settings:**
|
||||
|
||||
\```[format]
|
||||
[example configuration with comments]
|
||||
\```
|
||||
|
||||
**Options:**
|
||||
|
||||
| Setting | Type | Default | Description |
|
||||
|---------|------|---------|-------------|
|
||||
| [name] | [type] | [default] | [description] |
|
||||
| [name] | [type] | [default] | [description] |
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Pattern 1: [Name]
|
||||
|
||||
**Use case:** [When to use this]
|
||||
|
||||
**Implementation:**
|
||||
\```
|
||||
[code/commands]
|
||||
\```
|
||||
|
||||
### Pattern 2: [Name]
|
||||
|
||||
**Use case:** [When to use this]
|
||||
|
||||
**Implementation:**
|
||||
\```
|
||||
[code/commands]
|
||||
\```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Error: [Error message or type]
|
||||
|
||||
**Cause:** [Why this happens]
|
||||
|
||||
**Solution:**
|
||||
\```
|
||||
[fix command or steps]
|
||||
\```
|
||||
|
||||
### Error: [Error message or type]
|
||||
|
||||
**Cause:** [Why this happens]
|
||||
|
||||
**Solution:**
|
||||
\```
|
||||
[fix command or steps]
|
||||
\```
|
||||
|
||||
## Tips and Tricks
|
||||
|
||||
### Tip 1: [Name]
|
||||
[Description and example]
|
||||
|
||||
### Tip 2: [Name]
|
||||
[Description and example]
|
||||
|
||||
## Related Topics
|
||||
|
||||
- **[Related Skill/Topic]**: [When to use instead]
|
||||
- **[Related Skill/Topic]**: [When to use instead]
|
||||
|
||||
## Further Reading
|
||||
|
||||
For detailed information, see [reference.md](reference.md)
|
||||
|
||||
- Official Documentation: [link]
|
||||
- Cheat Sheet: [link]
|
||||
- Common Examples: [link]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Template 4: Tool/Utility Skill
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: [Tool Name]
|
||||
description: Use [tool] to [primary purpose] for [domain/use case]. Covers [key features] and [integration points].
|
||||
---
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
Use this skill when:
|
||||
- [Primary use case]
|
||||
- [Secondary use case]
|
||||
- [Integration scenario]
|
||||
|
||||
Do NOT use this skill for:
|
||||
- [What the tool doesn't do]
|
||||
- [Alternative tool suggestion]
|
||||
|
||||
## Installation
|
||||
|
||||
### Prerequisites
|
||||
- [System requirement 1]
|
||||
- [System requirement 2]
|
||||
|
||||
### Install
|
||||
|
||||
**Using [package manager 1]:**
|
||||
\```bash
|
||||
[install command]
|
||||
\```
|
||||
|
||||
**Using [package manager 2]:**
|
||||
\```bash
|
||||
[install command]
|
||||
\```
|
||||
|
||||
**Verify installation:**
|
||||
\```bash
|
||||
[verify command]
|
||||
\```
|
||||
|
||||
## Quick Start
|
||||
|
||||
Minimal example to get started:
|
||||
|
||||
\```bash
|
||||
[command]
|
||||
\```
|
||||
|
||||
Expected output:
|
||||
\```
|
||||
[output]
|
||||
\```
|
||||
|
||||
## Core Features
|
||||
|
||||
### Feature 1: [Name]
|
||||
|
||||
**What it does:** [Description]
|
||||
|
||||
**Basic usage:**
|
||||
\```bash
|
||||
[command]
|
||||
\```
|
||||
|
||||
**Common options:**
|
||||
- `[option]`: [what it does]
|
||||
- `[option]`: [what it does]
|
||||
|
||||
**Example:**
|
||||
\```bash
|
||||
[example command]
|
||||
\```
|
||||
|
||||
### Feature 2: [Name]
|
||||
|
||||
**What it does:** [Description]
|
||||
|
||||
**Basic usage:**
|
||||
\```bash
|
||||
[command]
|
||||
\```
|
||||
|
||||
**Common options:**
|
||||
- `[option]`: [what it does]
|
||||
- `[option]`: [what it does]
|
||||
|
||||
**Example:**
|
||||
\```bash
|
||||
[example command]
|
||||
\```
|
||||
|
||||
## Common Workflows
|
||||
|
||||
### Workflow 1: [Name]
|
||||
|
||||
**Goal:** [What you're trying to achieve]
|
||||
|
||||
**Steps:**
|
||||
1. [Step with command]
|
||||
\```bash
|
||||
[command]
|
||||
\```
|
||||
|
||||
2. [Step with command]
|
||||
\```bash
|
||||
[command]
|
||||
\```
|
||||
|
||||
3. [Step with command]
|
||||
\```bash
|
||||
[command]
|
||||
\```
|
||||
|
||||
**Result:** [What you've accomplished]
|
||||
|
||||
### Workflow 2: [Name]
|
||||
|
||||
[Similar structure]
|
||||
|
||||
## Configuration
|
||||
|
||||
### Configuration File
|
||||
|
||||
**Location:** `[path]`
|
||||
|
||||
**Example:**
|
||||
\```[format]
|
||||
[configuration example]
|
||||
\```
|
||||
|
||||
### Environment Variables
|
||||
|
||||
| Variable | Purpose | Example |
|
||||
|----------|---------|---------|
|
||||
| [VAR_NAME] | [description] | `[example value]` |
|
||||
|
||||
## Integration
|
||||
|
||||
### Integration with [Tool/Framework 1]
|
||||
|
||||
\```[language]
|
||||
[integration example]
|
||||
\```
|
||||
|
||||
### Integration with [Tool/Framework 2]
|
||||
|
||||
\```[language]
|
||||
[integration example]
|
||||
\```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Issue: [Problem]
|
||||
**Symptoms:** [How you know]
|
||||
**Cause:** [Why it happens]
|
||||
**Solution:**
|
||||
\```bash
|
||||
[fix]
|
||||
\```
|
||||
|
||||
### Issue: [Problem]
|
||||
**Symptoms:** [How you know]
|
||||
**Cause:** [Why it happens]
|
||||
**Solution:**
|
||||
\```bash
|
||||
[fix]
|
||||
\```
|
||||
|
||||
## Advanced Usage
|
||||
|
||||
### Advanced Feature 1: [Name]
|
||||
[Description and example]
|
||||
|
||||
### Advanced Feature 2: [Name]
|
||||
[Description and example]
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **[Practice 1]:** [Why and how]
|
||||
2. **[Practice 2]:** [Why and how]
|
||||
3. **[Practice 3]:** [Why and how]
|
||||
|
||||
## Resources
|
||||
|
||||
- Official Documentation: [link]
|
||||
- GitHub Repository: [link]
|
||||
- Tutorial: [link]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Template Selection Guide
|
||||
|
||||
Choose your template based on:
|
||||
|
||||
| Skill Type | Primary Goal | Use Template |
|
||||
|------------|--------------|--------------|
|
||||
| Teaching a framework/library | Help users write code | Code Framework |
|
||||
| Guiding through a process | Help users complete workflow | Workflow/Process |
|
||||
| Quick information lookup | Provide reference material | Reference/Lookup |
|
||||
| Using a specific tool | Help users operate tool | Tool/Utility |
|
||||
|
||||
## Customization Tips
|
||||
|
||||
1. **Remove unnecessary sections**: If a section doesn't apply, delete it
|
||||
2. **Add domain-specific sections**: Include what matters for your skill
|
||||
3. **Adjust examples**: Make examples relevant to actual use cases
|
||||
4. **Set the right scope**: Focus on one clear purpose per skill
|
||||
5. **Test trigger accuracy**: Ensure description matches when you want it to activate
|
||||
362
claude-code/skills/claude-subagents/SKILL.md
Normal file
362
claude-code/skills/claude-subagents/SKILL.md
Normal file
@@ -0,0 +1,362 @@
|
||||
---
|
||||
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.
|
||||
---
|
||||
|
||||
# Claude Code Subagent Refinement & Troubleshooting
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
Use this skill when:
|
||||
- Refining existing subagent prompts for better performance
|
||||
- Troubleshooting why a subagent isn't activating
|
||||
- Optimizing tool access and permissions
|
||||
- Improving subagent descriptions for better delegation
|
||||
- Debugging context management issues
|
||||
- Converting ad-hoc workflows to reusable 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
|
||||
|
||||
**Important**: Always start with `/agents` to create subagents. Use this skill to refine them afterward.
|
||||
|
||||
## Quick Reference: Subagent Structure
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: agent-name # Lowercase, kebab-case
|
||||
description: When to use # Triggers automatic delegation
|
||||
tools: Tool1, Tool2 # Optional: omit to inherit all
|
||||
model: sonnet # Optional: sonnet/opus/haiku/inherit
|
||||
---
|
||||
|
||||
System prompt defining role, capabilities, and behavior.
|
||||
```
|
||||
|
||||
**Locations**:
|
||||
- Project: `.claude/agents/` (highest priority)
|
||||
- User: `~/.claude/agents/` (shared across projects)
|
||||
- Plugin: `agents/` in plugin directory
|
||||
|
||||
## Common Problems (Quick Solutions)
|
||||
|
||||
### Problem 1: Subagent Never Activates
|
||||
|
||||
**Diagnosis**: Check description specificity
|
||||
|
||||
```yaml
|
||||
# ❌ Too vague (ignored)
|
||||
---
|
||||
description: Helper agent
|
||||
---
|
||||
|
||||
# ✓ Specific (works)
|
||||
---
|
||||
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"
|
||||
|
||||
### Problem 2: Wrong Tool Access
|
||||
|
||||
**Diagnosis**: Check tool configuration
|
||||
|
||||
```yaml
|
||||
# ❌ Too permissive
|
||||
---
|
||||
name: security-analyzer
|
||||
# (inherits all tools)
|
||||
---
|
||||
|
||||
# ✓ Restricted to needs
|
||||
---
|
||||
name: security-analyzer
|
||||
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)
|
||||
|
||||
### Problem 3: Poor Output Quality
|
||||
|
||||
**Diagnosis**: System prompt needs structure
|
||||
|
||||
```markdown
|
||||
# ❌ Vague
|
||||
You review code for issues.
|
||||
|
||||
# ✓ Structured
|
||||
You are a senior code reviewer specializing in production-ready code quality.
|
||||
|
||||
## Your Responsibilities
|
||||
1. **Logic & Correctness**: Verify algorithms, edge cases
|
||||
2. **Code Quality**: SRP, DRY, meaningful naming
|
||||
3. **Security**: Injection vulnerabilities, auth checks
|
||||
4. **Performance**: O(n²) algorithms, resource cleanup
|
||||
|
||||
## Output Format
|
||||
For each issue:
|
||||
- **Severity**: Critical/High/Medium/Low
|
||||
- **Location**: file:line
|
||||
- **Issue**: Clear description
|
||||
- **Fix**: Specific code example
|
||||
|
||||
## Constraints
|
||||
- Only actionable issues
|
||||
- Focus on high-impact problems
|
||||
```
|
||||
|
||||
For detailed system prompt patterns, see [patterns.md](patterns.md)
|
||||
|
||||
## Description Best Practices
|
||||
|
||||
### Template
|
||||
```yaml
|
||||
description: [Action verb] [domain/task] [including capabilities]. Use [trigger]. PROACTIVELY when [scenario].
|
||||
```
|
||||
|
||||
### Examples
|
||||
|
||||
**✓ Good**:
|
||||
```yaml
|
||||
description: Analyze Python code for performance bottlenecks including O(n²) algorithms, memory leaks, and inefficient database queries. Use PROACTIVELY when optimizing Python applications.
|
||||
|
||||
description: Generate comprehensive API documentation from code including endpoints, parameters, responses, and examples. Use when documenting REST or GraphQL APIs.
|
||||
|
||||
description: Review frontend code for accessibility issues following WCAG 2.1 AA standards. MUST BE USED for all UI component changes.
|
||||
```
|
||||
|
||||
**❌ Avoid**:
|
||||
```yaml
|
||||
description: Helps with coding
|
||||
description: Python utilities
|
||||
description: Security checker
|
||||
```
|
||||
|
||||
## Model Selection Guide
|
||||
|
||||
| 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) |
|
||||
| inherit | Task matches main thread | Need different capability |
|
||||
|
||||
**Default**: sonnet (best balance)
|
||||
|
||||
## Testing Subagents
|
||||
|
||||
### Test Plan Template
|
||||
|
||||
```markdown
|
||||
# Positive Tests (Should Activate)
|
||||
1. "Create REST endpoint for user auth"
|
||||
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)
|
||||
Actual: ___
|
||||
|
||||
## Results
|
||||
- Precision: X% (correct activations / total activations)
|
||||
- Recall: Y% (correct activations / should activate)
|
||||
```
|
||||
|
||||
For complete testing strategies, see [testing.md](testing.md)
|
||||
|
||||
## System Prompt Structure
|
||||
|
||||
```markdown
|
||||
# Role Definition
|
||||
You are a [role] specializing in [domain].
|
||||
|
||||
## Responsibilities
|
||||
1. [Primary responsibility]
|
||||
2. [Secondary responsibility]
|
||||
3. [Additional responsibilities]
|
||||
|
||||
## Process
|
||||
1. [Step 1]
|
||||
2. [Step 2]
|
||||
3. [Step 3]
|
||||
|
||||
## Output Format
|
||||
[Specific structure required]
|
||||
|
||||
## Examples
|
||||
|
||||
### Good Example
|
||||
[Show what good looks like]
|
||||
|
||||
### Bad Example
|
||||
[Show what to avoid]
|
||||
|
||||
## Constraints
|
||||
- [Important limitation]
|
||||
- [Another constraint]
|
||||
```
|
||||
|
||||
## 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
|
||||
|
||||
```yaml
|
||||
# Frontend Specialist
|
||||
---
|
||||
name: frontend-specialist
|
||||
description: React/TypeScript UI development and component design. Use PROACTIVELY for frontend work.
|
||||
tools: Read, Write, Edit, Grep, Bash(npm:*)
|
||||
---
|
||||
|
||||
You are a React/TypeScript expert specializing in modern frontend development.
|
||||
|
||||
## Tech Stack
|
||||
- React 18+ with hooks
|
||||
- TypeScript (strict mode)
|
||||
- Tailwind CSS
|
||||
- Component-driven architecture
|
||||
|
||||
## Principles
|
||||
- Functional components only
|
||||
- Custom hooks for logic reuse
|
||||
- Accessibility (WCAG AA)
|
||||
- Performance (lazy loading, memoization)
|
||||
```
|
||||
|
||||
For more patterns, see [patterns.md](patterns.md)
|
||||
|
||||
## Debugging Checklist
|
||||
|
||||
When subagent doesn't work as expected:
|
||||
|
||||
```markdown
|
||||
- [ ] Description is specific and includes trigger words
|
||||
- [ ] Description includes "PROACTIVELY" or "MUST BE USED" if needed
|
||||
- [ ] System prompt defines role clearly
|
||||
- [ ] System prompt includes process/steps
|
||||
- [ ] System prompt specifies output format
|
||||
- [ ] System prompt has examples
|
||||
- [ ] Tools match required capabilities
|
||||
- [ ] Tools follow least-privilege principle
|
||||
- [ ] Model appropriate for task complexity
|
||||
- [ ] File location correct (.claude/agents/)
|
||||
- [ ] YAML frontmatter valid
|
||||
- [ ] Name uses kebab-case
|
||||
- [ ] Tested with positive/negative scenarios
|
||||
```
|
||||
|
||||
## Common Anti-Patterns
|
||||
|
||||
### ❌ 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
|
||||
|
||||
### When to Migrate
|
||||
- Used same prompt 3+ times
|
||||
- Prompt has clear pattern/structure
|
||||
- Task benefits from isolation
|
||||
- Multiple team members need it
|
||||
|
||||
### Process
|
||||
|
||||
**Step 1: Extract Pattern**
|
||||
```markdown
|
||||
# Repeated prompts:
|
||||
1. "Review auth.js for security issues"
|
||||
2. "Check payment.js for vulnerabilities"
|
||||
3. "Analyze api.js for security problems"
|
||||
|
||||
# Common pattern: Review [file] for security [types]
|
||||
```
|
||||
|
||||
**Step 2: Generalize**
|
||||
```yaml
|
||||
---
|
||||
name: security-reviewer
|
||||
description: Review code for security vulnerabilities including SQL injection, XSS, authentication flaws, and hardcoded secrets. Use PROACTIVELY for security reviews.
|
||||
tools: Read, Grep, Glob
|
||||
---
|
||||
```
|
||||
|
||||
**Step 3: Test & Refine**
|
||||
Test with previous use cases, refine until quality matches manual prompts.
|
||||
|
||||
## Resources
|
||||
|
||||
- [Optimization Patterns](patterns.md) - Advanced subagent patterns
|
||||
- [Testing Strategies](testing.md) - Comprehensive testing guide
|
||||
- [System Prompt Templates](templates.md) - Ready-to-use prompts
|
||||
- [Official Documentation](https://docs.claude.com/en/docs/claude-code/sub-agents)
|
||||
|
||||
---
|
||||
|
||||
**Remember**: Start with `/agents` for creation. Use this skill for refinement. Iterate based on real usage. Test thoroughly.
|
||||
Reference in New Issue
Block a user