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

Initial genealogy skill

Browse Source
This commit is contained in:
movq
2026-03-26 07:21:34 -05:00
parent 5d073ffefc
commit 804e13ba52
37 changed files with 1065 additions and 8706 deletions
Download Patch File Download Diff File Expand all files Collapse all files

15
.claude-plugin/marketplace.json
View File

@@ -1,20 +1,19 @@
{ {
"name": "claude-skills-marketplace", "name": "local-plugins",
"owner": { "owner": {
"name": "Claude Skills Contributors" "name": "Tom, Dick, and Harry"
}, },
"description": "A curated collection of Agent Skills and plugins for Claude Code and Claude.ai", "description": "A curated collection of Agent Skills and plugins for Claude Code and Claude.ai",
"plugins": [ "plugins": [
{
"name": "claude-code",
"source": "./claude-code",
"description": "Complete toolkit for Claude Code: plugins, skills, slash commands, hooks, subagents, and memory management"
},
{ {
"name": "council-of-experts", "name": "council-of-experts",
"source": "./council-of-experts", "source": "./council-of-experts",
"description": "A research council that attacks hard problems from multiple expert perspectives simultaneously." "description": "A research council that attacks hard problems from multiple expert perspectives simultaneously."
},
{
"name": "genealogy",
"source": "./genealogy",
"description": "Genealogy research methodology — GPS evidence evaluation, FAN workflows, research journal, claim promotion, and transcription."
} }
] ]
} }

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

@@ -1,18 +0,0 @@
{
"name": "claude-code",
"description": "Comprehensive skills for mastering Claude Code features: plugins, skills, slash commands, hooks, subagents, and memory management",
"version": "1.3.0",
"author": {
"name": "Claude Skills Contributors"
},
"keywords": [
"claude-code",
"plugins",
"skills",
"slash-commands",
"hooks",
"subagents",
"memory",
"productivity"
]
}

202
claude-code/README.md
View File

@@ -1,202 +0,0 @@
# Claude Code Plugin
Comprehensive skills for mastering Claude Code features including plugins, slash commands, hooks, subagents, and memory management.
## What's Included
This plugin provides five specialized skills that help you work more effectively with Claude Code:
### 1. claude-plugins
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
- Configuring plugin manifests
### 2. claude-commands
Create custom slash commands with argument handling, bash execution, and file references.
**Use when:**
- Building reusable prompts
- Automating workflows
- Creating project-specific commands
### 3. claude-hooks
Configure event-driven hooks for automating workflows, validating code, and controlling tool execution.
**Use when:**
- Setting up automation
- Enforcing standards
- Injecting context
- Integrating external tools
### 4. claude-subagents
Refine and troubleshoot Claude Code subagents by optimizing prompts, tool access, and delegation patterns.
**Use when:**
- Improving existing subagents (NOT initial creation - use `/agents` command)
- Debugging activation issues
- Optimizing performance
### 5. claude-memory
Optimize and troubleshoot Claude Code memory files (CLAUDE.md) for efficiency, token management, and team collaboration.
**Use when:**
- Memory isn't loading
- Context is bloated
- Organizing memory hierarchy
- Setting up team collaboration (NOT initial setup - use `/init` command)
## Installation
### For Claude Code
Install from marketplace:
```bash
/plugin install claude-code@claude-skills-marketplace
```
Or install from local directory:
```bash
/plugin install /path/to/Skills/claude-code@local
```
### For Claude.ai
1. Zip this plugin directory
2. Go to Settings > Capabilities > Upload skill
3. Upload the zip file
4. Enable the plugin
## Usage
Once installed, these skills activate automatically when you work on related tasks:
- **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:
```
"Help me optimize my CLAUDE.md file"
"My subagent isn't triggering correctly"
"How do I create a hook that runs after file writes?"
```
## Skills Details
### claude-plugins
**Covers:**
- Plugin manifest configuration (plugin.json)
- Component setup (commands/agents/skills/hooks)
- Distribution and marketplace publishing
- Best practices and troubleshooting
[View Details](./skills/claude-plugins/SKILL.md)
### claude-commands
**Covers:**
- Command syntax and frontmatter options
- Argument patterns ($ARGUMENTS, $1, $2...)
- Bash integration with ! prefix
- File references with @ prefix
- Complete examples and patterns
[View Details](./skills/claude-commands/SKILL.md)
### claude-hooks
**Covers:**
- All hook types (SessionStart, PreToolUse, PostToolUse, etc.)
- Matcher patterns for tool filtering
- Exit codes and control flow
- Environment variables
- Complete working examples
[View Details](./skills/claude-hooks/SKILL.md)
### claude-subagents
**Covers:**
- Common problems and solutions
- System prompt optimization
- Tool access strategies
- Model selection guide
- Testing and validation
- Migration from ad-hoc prompts
[View Details](./skills/claude-subagents/SKILL.md)
### claude-memory
**Covers:**
- Memory hierarchy (project/user/subfolder)
- Token management and optimization
- Import system (@path/to/file)
- Team collaboration patterns
- Troubleshooting loading issues
- Template examples
[View Details](./skills/claude-memory/SKILL.md)
## Best Practices
### Initial Setup
1. Use built-in commands first:
- `/init` for memory setup
- `/agents` for subagent creation
2. Use these skills to refine and optimize afterward
### Progressive Learning
Start with one skill at a time:
1. Begin with **memory** - establish good context management
2. Add **slash commands** for common workflows
3. Implement **hooks** for automation
4. Create **subagents** for specialized tasks
5. Package everything in **plugins** for reusability
### Team Collaboration
- Share this plugin with your team for consistent workflows
- Use memory files for team standards
- Create project-specific slash commands
- Document subagent usage patterns
## Troubleshooting
**Skills not activating?**
- Verify plugin is installed: `/plugin list`
- Check descriptions match your use case
- Try explicit skill references in prompts
**Need help with specific features?**
- 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-plugins skill
- claude-slash-commands skill
- claude-hooks skill
- claude-subagents skill
- claude-memory skill
## Contributing
Found an issue or have improvements? See the main marketplace [CONTRIBUTING.md](../CONTRIBUTING.md).
## License
See main marketplace repository for license information.
---
**Remember**: These skills are for refinement and troubleshooting. Use Claude Code's built-in commands (`/init`, `/agents`, `/memory`) for initial setup, then use these skills to optimize.

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

@@ -1,232 +0,0 @@
---
name: Slash Command Creator
description: Create custom slash commands for Claude Code with argument handling, bash execution, and file references. Use PROACTIVELY when users repeat similar prompts 3+ times, mention "create a command", "reusable prompt", "/something", or "slash command". Triggers BEFORE user asks explicitly to suggest command creation for repeated workflows. NOT for complex multi-file operations.
---
# Slash Command Development
## When to Use This Skill
Use this skill when:
- Creating custom slash commands for Claude Code
- Building reusable prompt templates
- User repeats similar prompts 3+ times
- Automating repetitive tasks
- Converting manual workflows to commands
Do NOT use this skill for:
- Creating full plugins (use claude-plugins skill)
- Setting up hooks (use claude-hooks skill)
- Complex multi-file operations (use subagents)
## Quick Start
Create a command file in `.claude/commands/`:
```bash
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 | Use For |
|----------|-------|---------|
| `.claude/commands/` | Project (team) | Team workflows, standards |
| `~/.claude/commands/` | User (personal) | Personal productivity |
## Essential Syntax
### Basic Structure
```markdown
---
description: Brief description for /help
---
Prompt content here
$ARGUMENTS
```
**File name = Command name**: `review.md` → `/review`
### Frontmatter Options
```yaml
---
description: Generate unit tests for a function # Required
argument-hint: <file-path> <function-name> # Autocomplete
allowed-tools: Read(*), Bash(git:*) # Permissions
model: claude-haiku-4 # Model override
---
```
### Arguments
```markdown
$ARGUMENTS # All arguments
$1, $2, $3 # Positional arguments
@$1 or @file.js # Load file content
```
**Examples**:
```bash
/compare REST GraphQL # $1="REST", $2="GraphQL"
/review @src/main.js # Loads main.js content
/explain @src/a.js @src/b.js # Loads both files
```
### Bash Execution
Prefix with `!` to execute before processing:
```markdown
---
description: Git workflow helper
allowed-tools: Bash(git:*)
---
!git status
!git diff --stat
Based on above, suggest next steps.
```
**Important**: Must include `allowed-tools` with Bash patterns.
## Quick Examples
### Simple Review Command
```markdown
---
description: Review code quality
---
Review @$1 for:
1. Logic errors
2. Code style
3. Performance issues
Provide specific fixes.
```
### Multi-Step Workflow
```markdown
---
description: Commit and push changes
allowed-tools: Bash(git:*)
---
!git status
!git diff
1. Review changes
2. Create commit message
3. Commit and push
Ask confirmation before push.
```
For more examples, see [examples.md](examples.md)
## Best Practices
### ✓ Do
- Clear descriptions under 100 chars
- Specific tool permissions
- Meaningful command names (kebab-case)
- Self-documenting prompts
- Include argument hints
### ✗ Avoid
- Vague descriptions ("Helper", "Utils")
- Wildcard permissions (`allowed-tools: *`)
- Short cryptic names (`/gt`, `/rs`)
- Hardcoded secrets or paths
- Missing frontmatter
## Testing
```bash
# List all commands
/help
# Test with arguments
/mycommand arg1
/mycommand @file.js
```
## Common Issues
| Problem | Solution |
|---------|----------|
| Command not found | Check `.claude/commands/`, restart Claude |
| Arguments not working | Use `$ARGUMENTS`, not `${ARGUMENTS}` |
| Bash not executing | Add `allowed-tools: Bash(...)` |
| File not loading | Use `@` prefix, verify path |
For detailed troubleshooting, see [troubleshooting.md](troubleshooting.md)
## Security
**Limit permissions**:
```yaml
# ✓ Specific
allowed-tools: Bash(git status:*), Bash(git diff:*)
# ✗ Too broad
allowed-tools: *
```
**No secrets**:
```markdown
# ✗ Bad
!curl -H "API-Key: sk-abc123..."
# ✓ Good
!curl -H "API-Key: $MY_API_KEY"
```
## Command Template
```markdown
---
description: [Clear, concise description]
argument-hint: [Expected arguments]
allowed-tools: [Specific patterns if needed]
---
[Command prompt template]
$ARGUMENTS
```
## Additional Resources
**Need more?**
- [Complete Examples](examples.md) - 10+ working commands
- [Command Patterns](patterns.md) - Reusable templates
- [Troubleshooting Guide](troubleshooting.md) - Problem solutions
- [Official Docs](https://docs.claude.com/en/docs/claude-code/slash-commands)
- [Plugin Development](../claude-plugins/SKILL.md) - Package commands
💡 **Tip**: Start with manual prompts, identify repetition, then create commands. Commands are for workflows you use 3+ times.
---
**Remember**: Slash commands = reusable prompts. Keep them simple, specific, and secure.

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

@@ -1,216 +0,0 @@
# Command Examples
Complete, working slash command examples.
## Security Review
```markdown
---
description: Comprehensive security review of code files
allowed-tools: Read(*), Grep(*)
argument-hint: <files...>
---
Perform a security audit on: $ARGUMENTS
Check for:
1. SQL injection vulnerabilities
2. XSS vulnerabilities
3. Authentication/authorization issues
4. Hardcoded secrets or credentials
5. Unsafe deserialization
6. Path traversal vulnerabilities
For each issue found:
- Severity level (Critical/High/Medium/Low)
- Location (file:line)
- Explanation of the vulnerability
- Recommended fix with code example
```
**Usage**: `/security-review @src/auth.js @src/api.js`
## Commit + Push
```markdown
---
description: Review changes, commit, and push to remote
allowed-tools: Bash(git:*)
---
!git status
!git diff
Review the changes above and:
1. Create an appropriate commit message
2. Commit the changes
3. Push to remote
Ask for confirmation before pushing.
```
**Usage**: `/commit-push`
## Test Generator
```markdown
---
description: Generate comprehensive tests for a function
argument-hint: <file> <function-name>
model: claude-sonnet-4
---
For the function "$2" in @$1:
1. Analyze the function's behavior
2. Identify edge cases
3. Generate comprehensive unit tests including:
- Happy path tests
- Edge case tests
- Error condition tests
- Boundary value tests
Use the project's existing test framework and patterns.
```
**Usage**: `/generate-tests src/utils.js calculateTotal`
## Documentation Generator
```markdown
---
description: Generate JSDoc/TSDoc comments for code
---
Generate comprehensive documentation for: $ARGUMENTS
Include:
- Function/class description
- Parameter types and descriptions
- Return value description
- Usage examples
- Edge cases and error conditions
```
**Usage**: `/document @src/api/users.js`
## API Endpoint Creator
```markdown
---
description: Create REST API endpoint with tests
argument-hint: <method> <path> <description>
---
Create a $1 endpoint at "$2" that $3
Include:
1. Route handler with validation
2. Controller logic
3. Unit tests
4. Integration tests
5. API documentation
```
**Usage**: `/api POST /users/login "authenticates a user"`
## Refactor Command
```markdown
---
description: Refactor code for better maintainability
---
Refactor $ARGUMENTS
Focus on:
- Extract repeated code into functions
- Improve naming clarity
- Reduce complexity
- Add error handling
- Maintain existing behavior
Show before/after comparison.
```
**Usage**: `/refactor @src/legacy.js`
## Performance Analyzer
```markdown
---
description: Analyze code for performance bottlenecks
allowed-tools: Read(*), Grep(*)
---
Analyze $ARGUMENTS for performance issues
Check for:
1. O(n²) or worse algorithms
2. Unnecessary re-renders (React)
3. Memory leaks
4. Inefficient database queries
5. Large bundle sizes
Provide specific optimization suggestions with code examples.
```
**Usage**: `/performance @src/components/DataTable.tsx`
## Dependency Audit
```markdown
---
description: Audit project dependencies
allowed-tools: Bash(npm:*), Read(package.json)
---
!npm outdated
!npm audit
Review dependencies and:
1. Identify security vulnerabilities
2. Find outdated packages
3. Detect unused dependencies
4. Recommend updates or replacements
```
**Usage**: `/audit-deps`
## Code Cleanup
```markdown
---
description: Clean up code formatting and style
allowed-tools: Read(*), Write(*), Bash(npx prettier:*)
---
Clean up $ARGUMENTS
1. Remove unused imports
2. Fix formatting issues
3. Resolve linter warnings
4. Remove console.logs
5. Add missing type annotations
```
**Usage**: `/cleanup @src/**/*.ts`
## Migration Helper
```markdown
---
description: Help migrate code to new API/library version
argument-hint: <files> <from-version> <to-version>
---
Migrate $1 from version $2 to $3
1. Identify breaking changes
2. Update deprecated APIs
3. Fix type errors
4. Update tests
5. Verify functionality
```
**Usage**: `/migrate @src/app.js 3.0 4.0`

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

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

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

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

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

@@ -1,360 +0,0 @@
---
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 users want automation that runs automatically (not manually), mention "automatically run", "on save", "after editing", "event-driven", "workflow automation", or "enforce rules". NOT for one-time scripts.
---
# Claude Code Hooks
## When to Use This Skill
Use this skill when:
- Automating workflows with event triggers
- Enforcing code standards or policies
- Validating changes before/after tool execution
- Injecting context at session start
- Logging or monitoring tool usage
- Setting up team-wide automation
Do NOT use this skill for:
- Creating slash commands (use claude-commands skill)
- Building plugins (use claude-plugins skill)
- One-time scripts (run them directly)
## Quick Start
### Configuration File Locations
```bash
.claude/settings.json # Project (team)
.claude/settings.local.json # Project (personal)
~/.claude/settings.json # Global (personal)
```
### Simple Example - Auto-Format
```json
{
"hooks": {
"PostToolUse": [{
"matcher": "Write|Edit",
"hooks": [{
"type": "command",
"command": "npx prettier --write $TOOL_ARGS && exit 0"
}]
}]
}
}
```
## Hook Types
| Event | When | Common Use |
|-------|------|-----------|
| SessionStart | Session begins | Inject context |
| SessionEnd | Session ends | Cleanup, backups |
| PreToolUse | Before tool execution | Validation, checks |
| PostToolUse | After tool completes | Formatting, linting |
| UserPromptSubmit | User submits prompt | Logging |
| Notification | Claude sends notification | Desktop alerts |
| Stop | Agent finishes | Post-processing |
## Core Concepts
### Matchers
```json
// Single tool
"matcher": "Write"
// Multiple (OR)
"matcher": "Write|Edit|Read"
// All tools
"matcher": "*"
// Git operations
"matcher": "Bash(git:*)"
```
### Exit Codes
```bash
exit 0 # Success - Continue
exit 1 # Non-blocking error - Continue
exit 2 # Blocking error - Stop operation
```
### Environment Variables
```bash
$CLAUDE_PROJECT_DIR # Current project
$TOOL_NAME # Tool being used
$TOOL_ARGS # Tool arguments
$HOOK_EVENT # Event type
```
## 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' >&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 more 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 (Sequential)
```json
{
"hooks": {
"PostToolUse": [{
"matcher": "Write|Edit",
"hooks": [
{"type": "command", "command": "npx prettier --write $TOOL_ARGS"},
{"type": "command", "command": "npx eslint --fix $TOOL_ARGS"},
{"type": "command", "command": "git add $TOOL_ARGS"}
]
}]
}
}
```
### Conditional Execution
```json
{
"type": "command",
"command": "if [[ $TOOL_ARGS == *.js ]]; then npm run format $TOOL_ARGS; fi; exit 0"
}
```
## Settings Hierarchy
**Load Order** (highest to lowest priority):
1. `.claude/settings.local.json` - Project, personal (gitignored)
2. `.claude/settings.json` - Project, team (in git)
3. `~/.claude/settings.json` - Global, personal
**Use Cases**:
- **Global**: Personal preferences, universal logging
- **Project**: Team standards, project automation
- **Local**: Personal overrides, experiments
## Testing Hooks
### Start Simple
```json
{
"hooks": {
"PostToolUse": [{
"matcher": "Write",
"hooks": [{
"type": "command",
"command": "echo 'Hook triggered: $TOOL_ARGS' && exit 0"
}]
}]
}
}
```
### Test Exit Codes
```json
{
"hooks": {
"PreToolUse": [{
"matcher": "Write",
"hooks": [{
"type": "command",
"command": "echo 'This blocks' >&2 && exit 2"
}]
}]
}
}
```
Try writing - should be blocked.
## Best Practices
### 1. Always Exit Explicitly
```bash
# ✓ Good
command && exit 0
# ✗ Bad
command
```
### 2. Use Timeouts
```json
{
"command": "npm test",
"timeout": 120 // Don't hang 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
// ✓ Good - external script
{
"command": "$CLAUDE_PROJECT_DIR/.claude/hooks/check.sh $TOOL_ARGS"
}
// ✗ Bad - complex bash in JSON
{
"command": "if [ -f $TOOL_ARGS ]; then cat $TOOL_ARGS | grep pattern | wc -l; fi"
}
```
### 5. Test Before Team Deployment
Test in `.claude/settings.local.json` before adding to team settings.
## Troubleshooting
| Problem | Solution |
|---------|----------|
| Not triggering | Check matcher, restart Claude |
| Fails silently | Check exit codes (use 0 for success) |
| Command not found | Use full path |
| Permission denied | `chmod +x script.sh` |
| Timeout | Increase timeout or optimize |
For detailed troubleshooting, see [troubleshooting.md](troubleshooting.md)
## Security
### Validate Input
```bash
# Sanitize TOOL_ARGS
if [[ ! $TOOL_ARGS =~ ^[a-zA-Z0-9/_.-]+$ ]]; then
echo "Invalid path" >&2
exit 2
fi
```
### Limit Permissions
```json
// ✓ Specific
"matcher": "Write|Edit"
// ✗ Too broad
"matcher": "*"
```
### Avoid Destructive Commands
```bash
# ✗ Dangerous
rm -rf $TOOL_ARGS
# ✓ Safer
if [[ -f "$TOOL_ARGS" ]] && [[ "$TOOL_ARGS" != "/" ]]; then
rm "$TOOL_ARGS"
fi
```
## Quick Reference
### 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 activity
"PreToolUse": [{"matcher": "*", "hooks": [{"type": "command", "command": "echo \"$TOOL_NAME: $TOOL_ARGS\" >> .claude/log && exit 0"}]}]
```
## Additional Resources
**Need more?**
- [Complete Examples](examples.md) - Working hook configurations
- [Advanced Patterns](patterns.md) - Complex workflows
- [Troubleshooting Guide](troubleshooting.md) - Problem solutions
- [Official Docs](https://docs.claude.com/en/docs/claude-code/hooks)
💡 **Tip**: Start simple, test thoroughly, use exit codes correctly. Hooks are powerful - use them wisely.
---
**Remember**: Hooks automate workflows. Exit codes control flow. Test in local settings first. Use specific matchers for security.

258
claude-code/skills/claude-hooks/examples.md
View File

@@ -1,258 +0,0 @@
# 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)

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

@@ -1,264 +0,0 @@
---
name: Claude Code Memory Specialist
description: Optimize and troubleshoot Claude Code memory files (CLAUDE.md) for efficiency, token management, and team collaboration. Use PROACTIVELY after reading ANY CLAUDE.md file to suggest optimizations, when CLAUDE.md exceeds 200 lines, when starting work on projects, or when users mention "CLAUDE.md", "memory file", or "project context". NOT for initial setup - use /init command first.
---
# Claude Code Memory Optimization & Troubleshooting
## When to Use This Skill
Use this skill when:
- CLAUDE.md file exceeds 200 lines (bloat)
- After reading any CLAUDE.md to suggest improvements
- Memory files not loading correctly
- Managing token consumption
- Setting up memory hierarchy (project/user/subfolder)
- Organizing memory for team collaboration
Do NOT use this skill for:
- **Initial setup** - Use `/init` command instead
- Creating slash commands (use claude-commands skill)
- General Claude Code issues
**Important**: Always start with `/init` for initial project memory setup.
## Quick Reference
### Memory Hierarchy (Load Order)
```
1. Enterprise Policy ~/.claude/enterprise/CLAUDE.md (highest)
2. Project Memory ./CLAUDE.md or ./.claude/CLAUDE.md
3. User Memory ~/.claude/CLAUDE.md
4. Subfolder Memory ./subfolder/CLAUDE.md
```
Claude searches upward from current directory, loading all found.
### Target Size
**Goal**: 100-200 lines per CLAUDE.md (~400-800 tokens)
**Why**: Loaded in EVERY conversation. 500+ line files waste thousands of tokens.
## Core Principles
### 1. Progressive Disclosure Pattern
```markdown
# CLAUDE.md (Core - Always Loaded)
Quick reference, critical rules, imports
# docs/architecture.md (Loaded on Demand)
Detailed architecture information
```
**Token Savings**: 400 tokens (core) vs 2000+ tokens (everything embedded)
### 2. 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-150 lines)
```markdown
# ProjectName
Brief description (1-2 sentences).
## Tech Stack
- Key technologies (3-5 items)
- 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: `CLAUDE.md` (case-sensitive) |
| Claude ignores rules | Add `IMPORTANT:` or `YOU MUST` |
| Too many tokens | Move details to @docs/ imports |
| Updates not working | Restart session or use `/memory` |
| Conflicting memories | Project wins over user (check hierarchy) |
For detailed troubleshooting, see [troubleshooting.md](troubleshooting.md)
## Optimization Quick Win
**Before (bloated - 1500 tokens)**:
```markdown
This project is a comprehensive platform built with React 18,
utilizing TypeScript for type safety, Node.js 20 for the backend,
Express 4.18 for API routes, PostgreSQL 15 for data persistence...
[extensive paragraphs explaining everything]
```
**After (lean - 300 tokens)**:
```markdown
Tech Stack: React 18 + Node.js 20 + PostgreSQL 15
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
For architecture: @docs/architecture.md
For API details: @docs/api-reference.md
```
### ❌ Don't
```markdown
# Deep chains (max depth = 5)
@docs/a.md → @docs/b.md → @docs/c.md → @docs/d.md → @docs/e.md
```
**Rules**:
- Max import depth: 5 levels
- No circular references
- Keep chains flat, not deep
## Quick Update Methods
### Method 1: # Shortcut (Fastest)
```
Press # at input start → type update → auto-adds to CLAUDE.md
```
### Method 2: /memory Command
```
/memory → Opens 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 Effectiveness
```markdown
# Add temporary marker
**MEMORY TEST: If you see this, memory loaded correctly**
# Ask Claude: "What's the first line of your memory?"
# Should see marker, then remove it
```
## Team Setup Pattern
```bash
# .gitignore
.claude/CLAUDE.local.md # Personal only
.claude/settings.local.json # Personal settings
# .claude/CLAUDE.md (in git - team standards)
# 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)
## Compression Techniques
1. **Bullet Points > Paragraphs** (50% more efficient)
2. **Commands > Explanations** (show `npm test`, not prose)
3. **Imports > Embedding** (`@docs/api.md` = 5 tokens vs 2000)
4. **Examples > Theory** (concrete beats abstract)
### Decision Tree
```
Needed in 80%+ sessions?
→ YES: Keep in CLAUDE.md
Needed occasionally?
→ YES: Put in @docs/, reference from CLAUDE.md
Needed rarely?
→ NO: Omit, use web search or direct read
```
## Additional Resources
**Need more?**
- [Memory Templates](templates.md) - Ready-to-use CLAUDE.md templates
- [Troubleshooting Guide](troubleshooting.md) - Detailed problem-solution guide
- [Optimization Patterns](patterns.md) - Advanced token-saving techniques
- [Team Workflows](workflows.md) - Collaboration strategies
- [Official Documentation](https://docs.claude.com/en/docs/claude-code/memory)
💡 **Tip**: Measure regularly using `wc -l CLAUDE.md` (target: 100-200 lines)
---
**Remember**: Practice what we preach - keep memory lean (100-200 lines), be specific not vague, use imports for details, emphasize critical rules, test effectiveness.

557
claude-code/skills/claude-memory/patterns.md
View File

@@ -1,557 +0,0 @@
# 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
View File

@@ -1,406 +0,0 @@
# 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
View File

@@ -1,513 +0,0 @@
# 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
View File

@@ -1,624 +0,0 @@
# 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.

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

@@ -1,302 +0,0 @@
---
name: Claude Code Plugin Developer
description: Create and structure Claude Code plugins with commands, agents, skills, hooks, and MCP servers. Use PROACTIVELY when users package multiple related features, mention "create a plugin", "package for distribution", "plugin marketplace", or have 3+ commands/skills to organize. NOT for creating individual components in isolation.
---
# Claude Code Plugin Development
## When to Use This Skill
Use this skill when:
- Creating a new plugin from scratch
- Adding components to existing plugin
- Configuring plugin manifests
- Setting up distribution/marketplaces
- Packaging 3+ related commands/skills/agents
Do NOT use this skill for:
- Creating standalone MCP servers
- Single commands (use claude-commands skill)
- General Claude Code usage
## Quick Start
### 1. Basic Plugin Structure
```bash
mkdir my-plugin && cd my-plugin
mkdir -p .claude-plugin
cat > .claude-plugin/plugin.json << 'EOF'
{
"name": "my-plugin",
"description": "What your plugin does",
"version": "1.0.0",
"author": {"name": "Your Name"}
}
EOF
# Add component directories
mkdir -p commands agents skills hooks
```
### 2. Test Installation
```bash
/plugin install /path/to/my-plugin@local
/plugin list
```
## Plugin Manifest (plugin.json)
### Required Fields
```json
{
"name": "plugin-name", // kebab-case
"description": "What it does", // Clear, concise
"version": "1.0.0", // Semantic versioning
"author": {"name": "Author"}
}
```
### Optional Fields
```json
{
"repository": {
"type": "git",
"url": "https://github.com/user/repo"
},
"license": "MIT",
"keywords": ["productivity", "automation"]
}
```
## Plugin Components
### 1. Commands (commands/)
**→ [See claude-commands skill for full guide](../claude-commands/skill.md)**
```markdown
# commands/review.md
---
description: Review code for issues
---
Review $ARGUMENTS for:
- Logic errors
- Style issues
```
**Usage**: `/review @file.js`
### 2. Agents (agents/)
**→ [See claude-subagents skill for full guide](../claude-subagents/skill.md)**
```markdown
# agents/code-reviewer.md
---
description: Reviews code for best practices
tools: [Read, Grep]
model: claude-sonnet-4
---
You are a code review specialist...
```
### 3. Skills (skills/)
**→ [See claude-skills skill for full guide](../claude-skills/skill.md)**
```
skills/
└── my-skill/
└── skill.md # With frontmatter
```
### 4. Hooks (hooks/hooks.json)
**→ [See claude-hooks skill for full guide](../claude-hooks/skill.md)**
```json
{
"PostToolUse": [{
"matcher": "Write|Edit",
"hooks": [{
"type": "command",
"command": "npx prettier --write $TOOL_ARGS"
}]
}]
}
```
### 5. MCP Servers (.mcp.json)
**→ [See mcp-config skill for full guide](../mcp-config/skill.md)**
```json
{
"mcpServers": {
"my-server": {
"command": "node",
"args": ["server.js"]
}
}
}
```
## Directory Organization
**IMPORTANT**: Components at plugin root, NOT in `.claude-plugin/`
```
my-plugin/
├── .claude-plugin/ # Manifest only
│ └── plugin.json
├── commands/ # At root
├── agents/ # At root
├── skills/ # At root
└── README.md
```
## Distribution
### Local Testing
```bash
/plugin install /path/to/plugin@local
```
### Team Marketplace
```json
// .claude/settings.json
{
"plugin-marketplaces": {
"team": {
"url": "file:///path/to/marketplace"
}
},
"plugins": ["my-plugin@team"]
}
```
### Marketplace Structure
```
marketplace/
├── .claude-plugin/
│ └── marketplace.json
└── plugin-name/
├── .claude-plugin/plugin.json
└── [components]
```
## Common Patterns
### Multi-Command Plugin
```
git-tools/
├── .claude-plugin/plugin.json
└── commands/
├── commit.md
├── pr.md
└── review.md
```
### Agent + Skill Combo
```
api-plugin/
├── .claude-plugin/plugin.json
├── agents/
│ └── api-specialist.md
└── skills/
└── rest-api/SKILL.md
```
### Hook-Based Automation
```json
{
"PostToolUse": [{
"matcher": "Write",
"hooks": [{
"type": "command",
"command": "npm run format $TOOL_ARGS"
}]
}]
}
```
## Testing Checklist
- [ ] plugin.json valid JSON
- [ ] All required fields present
- [ ] Components at plugin root
- [ ] Commands have frontmatter
- [ ] Local installation works
- [ ] No sensitive data
- [ ] README documents features
## Troubleshooting
| Problem | Solution |
|---------|----------|
| Plugin not found | Check plugin.json in `.claude-plugin/` |
| Commands unavailable | Verify `commands/` at root, restart |
| Invalid structure | Move components to root, not `.claude-plugin/` |
## Security
**Never include**:
- API keys or credentials
- Hardcoded secrets
- Personal paths
**Use environment variables**:
```json
{
"mcpServers": {
"api": {
"env": {"API_KEY": "env:MY_API_KEY"}
}
}
}
```
## Version Management
```json
{
"version": "1.1.0" // Semantic versioning
}
// Breaking: 2.0.0
// Features: 1.1.0
// Fixes: 1.0.1
```
## Additional Resources
**Component Skills:**
- [Commands Guide](../claude-commands/skill.md) - Create slash commands
- [Subagents Guide](../claude-subagents/skill.md) - Configure specialized agents
- [Skills Guide](../claude-skills/skill.md) - Build contextual knowledge skills
- [Hooks Guide](../claude-hooks/skill.md) - Automate with event-driven hooks
- [MCP Config Guide](../mcp-config/skill.md) - Integrate MCP servers
- [Memory Guide](../claude-memory/skill.md) - Manage persistent memory
**External Resources:**
- [Official Docs](https://docs.claude.com/en/docs/claude-code/plugins)
- [MCP Protocol](https://modelcontextprotocol.io/)
💡 **Tip**: Start with one component type, test thoroughly, then expand. Plugins organize related functionality.
---
**Remember**: Plugins package related features. Components go at root. Test locally first. Use semantic versioning.

151
claude-code/skills/claude-skills/README.md
View File

@@ -1,151 +0,0 @@
# 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.

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

@@ -1,374 +0,0 @@
---
name: Skill Creator
description: Guide for creating effective Claude Agent Skills with best practices, structure guidelines, and progressive disclosure principles. Use PROACTIVELY BEFORE starting skill creation to review best practices, DURING skill structuring to optimize content organization, AFTER completing a skill draft to validate triggers and structure, or when users mention "create a skill", "skill not working", or "skill.md". NOT for using existing skills.
---
# Skill Creation Best Practices
## 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
- Optimizing skill structure for token efficiency
- Before, during, and after skill creation
## Core Principle: Progressive Disclosure
**The fundamental design pattern for Agent Skills.**
### Three Layers
1. **Metadata** (Always Loaded ~100 tokens)
- YAML frontmatter: `name` and `description`
- Triggers skill activation
2. **Instructions** (Triggered ~800-1000 tokens)
- Main SKILL.md content
- Workflows and guidance
3. **Resources** (On-Demand)
- Additional files loaded when needed
- Examples, reference docs, scripts
## Skill Structure Requirements
### Mandatory: SKILL.md
```yaml
---
name: Your Skill Name # Max 64 chars
description: What it does and when to use it # Max 1024 chars
---
```
**Critical**: The description determines when Claude triggers the skill.
### Optional: Additional Files
```
my-skill/
├── SKILL.md # Required entry point
├── examples.md # Working code samples
├── reference.md # Deep API docs
└── workflows/
├── beginner.md
└── advanced.md
```
## Writing Effective Descriptions
The `description` is your trigger mechanism.
### Template
```
[Action] [domain/task] [with capabilities].
Use when [trigger scenario]. PROACTIVELY when [context].
```
### Examples
**✓ Good**:
```yaml
description: Create and analyze Excel spreadsheets with formulas, formatting, and pivot tables. Use when building reports or data analysis.
description: Debug Swift applications using LLDB for crashes, memory issues, and runtime errors. Use PROACTIVELY when encountering Swift bugs.
```
**✗ Poor**:
```yaml
description: Helps with coding
description: Python utilities
description: Security checker
```
## Essential SKILL.md Structure
### 1. When to Use This Skill
```markdown
## When to Use This Skill
Use this skill when:
- [Primary scenario]
- [Secondary scenario]
Do NOT use this skill for:
- [Common confusion]
- [Different tool]
```
### 2. Quick Start
```markdown
## Quick Start
Minimal working example:
```[language]
[code]
```
**Result**: [What this achieves]
```
### 3. Core Workflows
```markdown
## Core Workflows
### Workflow 1: [Name]
1. [Step]
2. [Step]
3. [Step]
**Example**:
```[language]
[code]
```
```
### 4. Additional Resources
```markdown
## Additional Resources
**Need more?**
- [Examples](examples.md) - Working code samples
- [Reference](reference.md) - API documentation
- [Advanced Workflows](workflows/advanced.md)
💡 **Tip**: These load only when referenced.
```
## Token Optimization
### Target Sizes
- SKILL.md: 800-1000 tokens (~200-250 lines)
- Supplementary files: As needed
### When to Split
**Keep in SKILL.md**:
- Needed 80%+ of time
- Under 1000 tokens
- Sequential steps
**Move to separate file**:
- Mutually exclusive content
- Reference material
- Advanced/edge cases
### Compression Techniques
1. **Bullet points > Paragraphs** (50% more efficient)
2. **Code examples > Prose** (show don't tell)
3. **References > Embedding** (load on-demand)
4. **Concrete > Abstract** (examples beat theory)
## Development Workflow
### 1. Identify Need
Don't guess - observe:
1. Run Claude on representative tasks
2. Find repeated questions or struggles
3. Capture successful patterns
4. Codify into skill
### 2. Start Minimal
```yaml
---
name: My Skill
description: [Specific, clear trigger description]
---
## When to Use This Skill
[Clear scenarios]
## Quick Start
[One minimal example]
## Core Workflow
[3-5 essential steps]
```
### 3. Test Triggering
**Positive tests** (should activate):
- "Create X using Y"
- "[Domain-specific request]"
**Negative tests** (should NOT activate):
- "[Related but different domain]"
- "[Different tool's purpose]"
### 4. Grow Organically
Add only when needed:
- More examples from actual usage
- Advanced workflows when requested
- Reference docs when API is complex
- Scripts for repeated commands
## Common Patterns by Domain
### Code Development Skills
```markdown
---
name: [Framework] [Pattern] Guide
description: [Action] [framework] applications following [pattern]. Use when building [type] with [requirements].
---
## When to Use This Skill
[Specific project types]
## Project Structure
[Standard layout]
## Core Workflows
### Create [Component]
[Steps]
## Testing Strategy
[How to test]
```
### Workflow Skills
```markdown
---
name: [Task] Workflow
description: [Action] for [domain] following [methodology]. Use when [scenario].
---
## Prerequisites
[What's needed]
## Step-by-Step Process
### Phase 1: [Name]
[Steps]
## Quality Checklist
- [ ] [Verification]
```
## Debugging Skills
### Skill Doesn't Trigger
**Fix description**:
```yaml
# ❌ Too vague
description: Python development helpers
# ✓ Specific with triggers
description: Create Python projects using Hatch and Hatchling for dependency management. Use when initializing new Python packages or configuring build systems.
```
### Skill Triggers Too Often
**Add negatives**:
```markdown
## When to Use This Skill
Use when:
- [Specific scenario]
Do NOT use for:
- [Broader scenario that should use different skill]
```
### Content Doesn't Load
**Check references**:
- Verify file paths are correct
- Ensure .md files exist in skill directory
- Use relative paths from skill root
## Skill Checklist
Before finalizing:
- [ ] Name under 64 characters
- [ ] Description under 1024 characters, includes triggers
- [ ] SKILL.md has YAML frontmatter
- [ ] "When to Use This Skill" section present
- [ ] At least one concrete example
- [ ] No sensitive information
- [ ] File references work
- [ ] Tested positive trigger scenarios
- [ ] Tested negative scenarios (doesn't over-trigger)
- [ ] Size under 1000 tokens for SKILL.md
## Quick Start Template
```markdown
---
name: [Skill Name]
description: [Action] [domain] [with capabilities]. Use when [scenario]. PROACTIVELY when [context].
---
# [Skill Name]
## When to Use This Skill
Use this skill when:
- [Primary scenario]
- [Secondary scenario]
Do NOT use this skill for:
- [Common confusion]
## Quick Start
[Minimal working example]
## Core Workflows
### Workflow 1: [Name]
1. [Step]
2. [Step]
3. [Step]
**Example**:
```
[code]
```
**Result**: [What this achieves]
## Common Pitfalls
### Issue: [Problem]
**Solution**: [Fix]
## Additional Resources
**Need more?**
- [Examples](examples.md) - Working samples
- [Reference](reference.md) - API docs
- [Advanced](workflows/advanced.md) - Complex patterns
💡 **Tip**: [Key insight]
```
## Additional Resources
**Need more?**
- [Skill Examples](examples.md) - Complete working skills
- [Best Practices Guide](best-practices.md) - Comprehensive guidelines
- [Templates](templates.md) - Ready-to-use templates
- [Checklist](checklist.md) - Validation checklist
- [Official Docs](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview)
💡 **Tip**: Best skills emerge from real usage. Start simple, iterate based on actual needs, prioritize clarity over comprehensiveness.
---
**Remember**: Specific descriptions trigger correctly. Progressive disclosure saves tokens. Test thoroughly. Start minimal and grow organically.

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

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

260
claude-code/skills/claude-skills/checklist.md
View File

@@ -1,260 +0,0 @@
# 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
View File

@@ -1,903 +0,0 @@
# 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
View File

@@ -1,729 +0,0 @@
# 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

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

@@ -1,302 +0,0 @@
---
name: Claude Code Subagent Specialist
description: Refine and troubleshoot Claude Code subagents by optimizing prompts, tool access, descriptions, and performance. Use PROACTIVELY immediately AFTER creating subagent with /agents command to optimize configuration, when subagent doesn't activate as expected, when users mention "subagent not working", "agent won't trigger", or "refine agent". NOT for initial creation - use /agents command first.
---
# Claude Code Subagent Refinement & Troubleshooting
## When to Use This Skill
Use this skill when:
- Refining existing subagent prompts
- Troubleshooting activation issues
- Optimizing tool access and permissions
- Improving delegation patterns
- Converting ad-hoc workflows to subagents
Do NOT use this skill for:
- **Initial creation** - Use `/agents` command
- Creating slash commands (use claude-commands skill)
- General troubleshooting
**Important**: Always start with `/agents` to create subagents.
## Quick Reference: Subagent Structure
```yaml
---
name: agent-name # kebab-case
description: When to use # Triggers delegation
tools: Tool1, Tool2 # Optional: omit to inherit all
model: sonnet # Optional: sonnet/opus/haiku/inherit
---
System prompt defining role, capabilities, 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**: Vague description
```yaml
# ❌ Too vague
---
description: Helper agent
---
# ✓ Specific with triggers
---
description: Analyze code for security vulnerabilities including SQL injection, XSS, authentication flaws, and hardcoded secrets. Use PROACTIVELY when reviewing code for security issues.
---
```
**Fix**: Add specificity + "PROACTIVELY" or "MUST BE USED"
### Problem 2: Wrong Tool Access
```yaml
# ❌ Too permissive (inherits all)
---
name: security-analyzer
# (no tools field)
---
# ✓ Restricted to needs
---
name: security-analyzer
tools: Read, Grep, Glob
---
```
**Tool Access Strategies**:
- **Inherit All**: Omit `tools` field
- **Read-Only**: `tools: Read, Grep, Glob`
- **Specific**: `tools: Read, Write, Edit, Bash(npm test:*)`
- **Research**: `tools: WebFetch, WebSearch`
### Problem 3: Poor Output Quality
**Diagnosis**: Needs structured prompt
```markdown
# ❌ Vague
You review code for issues.
# ✓ Structured
You are a senior code reviewer specializing in production-ready 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 patterns, see [patterns.md](patterns.md)
## Description Best Practices
### Template
```yaml
description: [Action] [domain] [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
| Model | Use For | Avoid For |
|-------|---------|-----------|
| haiku | Simple transforms, quick checks | Complex reasoning |
| sonnet | General tasks (default) | When opus needed |
| opus | Complex architecture, creative work | Simple tasks (costly) |
| inherit | Task matches main thread | Need different capability |
## Testing Subagents
### Test Plan Template
```markdown
# Positive Tests (Should Activate)
1. "Create REST endpoint for user auth"
Expected: Activates
Actual: ___
# Negative Tests (Should NOT Activate)
1. "Write unit tests for API"
Expected: Does not activate (different concern)
Actual: ___
## Results
- Precision: X%
- Recall: Y%
```
For complete testing, 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]
## Process
1. [Step 1]
2. [Step 2]
## Output Format
[Specific structure required]
## Examples
### Good Example
[Show what good looks like]
## Constraints
- [Important limitation]
```
## Optimization Patterns
### 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.
## 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)
```
### Role-Based Pipeline
```yaml
# Architect Agent (opus)
---
name: solution-architect
description: Design system architecture from requirements
tools: Read, Write, WebSearch
model: opus
---
# Implementer Agent (sonnet)
---
name: code-implementer
description: Implement features from designs
tools: Read, Write, Edit, Bash(npm test:*)
model: sonnet
---
```
## Debugging Checklist
When subagent doesn't work:
- [ ] Description is specific with trigger words
- [ ] Description includes "PROACTIVELY" if needed
- [ ] System prompt defines role clearly
- [ ] System prompt includes process/steps
- [ ] System prompt specifies output format
- [ ] Tools match required capabilities
- [ ] Model appropriate for complexity
- [ ] File in `.claude/agents/`
- [ ] YAML frontmatter valid
- [ ] Name uses kebab-case
- [ ] Tested positive/negative scenarios
## Migration: Ad-Hoc to Subagent
### When to Migrate
- Used same prompt 3+ times
- Prompt has clear pattern
- Task benefits from isolation
- Multiple team members need it
### Process
**Step 1: Extract Pattern**
```
# Repeated prompts:
1. "Review auth.js for security"
2. "Check payment.js for vulnerabilities"
3. "Analyze api.js for security"
# Pattern: Review [file] for security
```
**Step 2: Generalize**
```yaml
---
name: security-reviewer
description: Review code for security vulnerabilities. Use PROACTIVELY for security reviews.
tools: Read, Grep, Glob
---
```
**Step 3: Test & Refine**
Test with previous use cases, refine until quality matches.
## Additional Resources
**Need more?**
- [Optimization Patterns](patterns.md) - Advanced subagent patterns
- [Testing Strategies](testing.md) - Comprehensive testing
- [System Prompt Templates](templates.md) - Ready-to-use prompts
- [Official Docs](https://docs.claude.com/en/docs/claude-code/sub-agents)
💡 **Tip**: Start with `/agents`, then refine. Iterate based on real usage. Test thoroughly.
---
**Remember**: Use `/agents` to create. This skill refines. Specific descriptions trigger correctly. Test positive AND negative scenarios.

358
claude-code/skills/mcp-config/examples.md
View File

@@ -1,358 +0,0 @@
# Real-World MCP Configuration Examples
Complete plugin configurations for common integration scenarios.
## GitHub Integration Plugin
Full-featured GitHub integration with authentication:
```json
{
"mcpServers": {
"github": {
"type": "http",
"url": "https://api.githubcopilot.com/mcp/",
"headers": {
"Authorization": "Bearer ${GITHUB_TOKEN}",
"Accept": "application/vnd.github.v3+json"
}
}
}
}
```
**Required Environment Variables:**
- `GITHUB_TOKEN` - Personal access token with repo permissions
**Plugin Structure:**
```
github-plugin/
├── .claude-plugin/plugin.json
├── .mcp.json
└── README.md
```
## Database Tools Plugin
Multi-database support with PostgreSQL and Redis:
```json
{
"mcpServers": {
"postgres": {
"command": "npx",
"args": ["-y", "@bytebase/dbhub", "--dsn", "${DATABASE_URL}"],
"env": {
"PGPASSWORD": "${DB_PASSWORD}"
}
},
"redis": {
"command": "${CLAUDE_PLUGIN_ROOT}/servers/redis-server",
"env": {
"REDIS_URL": "${REDIS_URL:-redis://localhost:6379}",
"REDIS_DB": "${REDIS_DB:-0}"
}
}
}
}
```
**Required Environment Variables:**
- `DATABASE_URL` - PostgreSQL connection string (e.g., `postgresql://user:pass@host:5432/db`)
- `DB_PASSWORD` - Database password
- `REDIS_URL` - Redis connection string (optional, defaults to localhost)
- `REDIS_DB` - Redis database number (optional, defaults to 0)
## Multi-Environment API Plugin
Supports staging and production environments:
```json
{
"mcpServers": {
"api": {
"type": "http",
"url": "${API_BASE_URL:-https://api.example.com}/mcp",
"headers": {
"Authorization": "Bearer ${API_TOKEN}",
"X-Environment": "${ENVIRONMENT:-production}",
"X-Version": "v2",
"X-Client-ID": "${CLIENT_ID}"
}
}
}
}
```
**Environment Configuration:**
Production:
```bash
export API_BASE_URL="https://api.example.com"
export API_TOKEN="prod_token_here"
export ENVIRONMENT="production"
export CLIENT_ID="client_prod_id"
```
Staging:
```bash
export API_BASE_URL="https://staging.api.example.com"
export API_TOKEN="staging_token_here"
export ENVIRONMENT="staging"
export CLIENT_ID="client_staging_id"
```
## Monitoring and Observability Plugin
Integrates with Sentry and custom logging:
```json
{
"mcpServers": {
"sentry": {
"type": "http",
"url": "https://mcp.sentry.dev/mcp",
"headers": {
"Authorization": "Bearer ${SENTRY_TOKEN}"
}
},
"logs": {
"command": "${CLAUDE_PLUGIN_ROOT}/servers/log-aggregator",
"args": ["--endpoint", "${LOG_ENDPOINT}"],
"env": {
"LOG_LEVEL": "${LOG_LEVEL:-info}",
"LOG_FORMAT": "json"
}
}
}
}
```
## Cloud Services Plugin
AWS, Azure, and GCP integrations:
```json
{
"mcpServers": {
"aws": {
"command": "aws-mcp-server",
"env": {
"AWS_REGION": "${AWS_REGION:-us-east-1}",
"AWS_PROFILE": "${AWS_PROFILE:-default}"
}
},
"azure": {
"type": "http",
"url": "${AZURE_ENDPOINT}/mcp",
"headers": {
"Authorization": "Bearer ${AZURE_TOKEN}",
"Subscription-ID": "${AZURE_SUBSCRIPTION_ID}"
}
},
"gcp": {
"command": "gcloud",
"args": ["mcp", "serve", "--project", "${GCP_PROJECT_ID}"]
}
}
}
```
## Local Development Tools Plugin
File watchers, linters, and formatters:
```json
{
"mcpServers": {
"file-watcher": {
"command": "${CLAUDE_PLUGIN_ROOT}/servers/watcher",
"args": ["--watch", "${WATCH_PATH:-.}", "--ignore", "node_modules"]
},
"linter": {
"command": "npx",
"args": ["-y", "eslint", "--format", "json", "--stdin"],
"env": {
"ESLINT_USE_FLAT_CONFIG": "true"
}
},
"formatter": {
"command": "npx",
"args": ["-y", "prettier", "--stdin-filepath", "file.js"]
}
}
}
```
**Windows Version:**
```json
{
"mcpServers": {
"linter": {
"command": "cmd",
"args": ["/c", "npx", "-y", "eslint", "--format", "json", "--stdin"]
}
}
}
```
## Testing and CI/CD Plugin
Integrates with test runners and deployment tools:
```json
{
"mcpServers": {
"test-runner": {
"command": "${CLAUDE_PLUGIN_ROOT}/servers/test-server",
"args": ["--config", "${CLAUDE_PLUGIN_ROOT}/test-config.json"],
"env": {
"TEST_ENV": "${TEST_ENV:-development}",
"COVERAGE_THRESHOLD": "${COVERAGE_THRESHOLD:-80}"
}
},
"deployment": {
"type": "http",
"url": "${DEPLOY_ENDPOINT}/mcp",
"headers": {
"Authorization": "Bearer ${DEPLOY_TOKEN}",
"X-Pipeline-ID": "${PIPELINE_ID}"
}
}
}
}
```
## Documentation Generator Plugin
Generates and maintains documentation:
```json
{
"mcpServers": {
"docs-generator": {
"command": "node",
"args": ["${CLAUDE_PLUGIN_ROOT}/servers/docs-gen.js"],
"env": {
"DOCS_OUTPUT": "${DOCS_OUTPUT:-./docs}",
"DOCS_FORMAT": "${DOCS_FORMAT:-markdown}",
"INCLUDE_EXAMPLES": "true"
}
}
}
}
```
## Custom Protocol Handler Plugin
For proprietary internal systems:
```json
{
"mcpServers": {
"internal-system": {
"command": "${CLAUDE_PLUGIN_ROOT}/bin/internal-mcp-server",
"args": [
"--endpoint", "${INTERNAL_ENDPOINT}",
"--cert", "${CLAUDE_PLUGIN_ROOT}/certs/client.pem",
"--key", "${CLAUDE_PLUGIN_ROOT}/certs/client-key.pem"
],
"env": {
"INTERNAL_API_KEY": "${INTERNAL_API_KEY}",
"TLS_VERIFY": "true",
"REQUEST_TIMEOUT": "${REQUEST_TIMEOUT:-30000}"
}
}
}
}
```
## Microservices Communication Plugin
Service mesh integration:
```json
{
"mcpServers": {
"service-mesh": {
"type": "http",
"url": "${MESH_GATEWAY_URL}/mcp",
"headers": {
"Authorization": "Bearer ${MESH_TOKEN}",
"X-Service-Name": "${SERVICE_NAME}",
"X-Namespace": "${NAMESPACE:-default}"
}
},
"service-discovery": {
"command": "consul",
"args": ["mcp", "serve", "-address", "${CONSUL_ADDRESS}"]
}
}
}
```
## Tips for Real-World Configurations
1. **Always document required environment variables** in your plugin's README
2. **Provide sensible defaults** using `${VAR:-default}` syntax
3. **Use `${CLAUDE_PLUGIN_ROOT}`** for bundled servers and assets
4. **Group related servers** in a single plugin
5. **Test with both local and remote transports** before distribution
6. **Include environment variable validation** in your MCP servers
7. **Provide example configurations** for common deployment scenarios
## Common Configuration Mistakes to Avoid
❌ **Hardcoded credentials**
```json
{
"env": {"API_KEY": "sk_live_abc123"} // Never do this!
}
```
✅ **Environment variables**
```json
{
"env": {"API_KEY": "${API_KEY}"}
}
```
---
❌ **Absolute paths**
```json
{
"command": "/Users/yourname/projects/plugin/server.js" // Won't work for others
}
```
✅ **Plugin-relative paths**
```json
{
"command": "${CLAUDE_PLUGIN_ROOT}/server.js"
}
```
---
❌ **Missing Windows compatibility**
```json
{
"command": "npx", // Fails on Windows
"args": ["-y", "package"]
}
```
✅ **Windows-compatible**
```json
{
"command": "cmd",
"args": ["/c", "npx", "-y", "package"]
}
```
## See Also
- [Main MCP Configuration Guide](skill.md)
- [Configuration Reference](reference.md)
- [MCP Protocol Documentation](https://modelcontextprotocol.io/)

545
claude-code/skills/mcp-config/reference.md
View File

@@ -1,545 +0,0 @@
# MCP Configuration Reference
Complete schema and technical reference for MCP server configuration in Claude Code plugins.
## Configuration Schema
### Stdio Server Configuration
```typescript
{
command: string // Required: Executable path or command name
args?: string[] // Optional: Command-line arguments
env?: Record<string, string> // Optional: Environment variables
}
```
**Field Details:**
- **`command`**: The executable to run. Can be:
- System command: `"node"`, `"python"`, `"npx"`
- Absolute path: `"/usr/local/bin/my-server"`
- Plugin-relative: `"${CLAUDE_PLUGIN_ROOT}/servers/my-server"`
- **`args`**: Array of arguments passed to the command
- Order matters
- Supports variable expansion: `["--config", "${CONFIG_PATH}"]`
- **`env`**: Environment variables for the process
- Inherits user's environment by default
- Additional vars override/extend inherited ones
- Supports variable expansion: `{"KEY": "${USER_KEY}"}`
**Example:**
```json
{
"my-server": {
"command": "node",
"args": ["${CLAUDE_PLUGIN_ROOT}/dist/server.js", "--port", "8080"],
"env": {
"NODE_ENV": "production",
"LOG_LEVEL": "${LOG_LEVEL:-info}"
}
}
}
```
### HTTP Server Configuration
```typescript
{
type: "http" // Required: Transport type
url: string // Required: HTTP(S) endpoint URL
headers?: Record<string, string> // Optional: HTTP headers
}
```
**Field Details:**
- **`type`**: Must be `"http"` for HTTP transport
- **`url`**: The MCP endpoint URL
- Must be valid HTTP(S) URL
- Supports variable expansion: `"${API_BASE_URL}/mcp"`
- Should end in `/mcp` by convention
- **`headers`**: HTTP headers sent with requests
- Common uses: Authentication, API keys, custom metadata
- Supports variable expansion: `{"Authorization": "Bearer ${TOKEN}"}`
**Example:**
```json
{
"api-server": {
"type": "http",
"url": "https://api.example.com/mcp",
"headers": {
"Authorization": "Bearer ${API_TOKEN}",
"X-Client-Version": "1.0.0",
"Accept": "application/json"
}
}
}
```
### SSE Server Configuration (Deprecated)
```typescript
{
type: "sse" // Required: Transport type
url: string // Required: SSE endpoint URL
headers?: Record<string, string> // Optional: HTTP headers
}
```
**Note**: SSE transport is deprecated. Use HTTP transport instead when available.
**Field Details:**
- **`type`**: Must be `"sse"` for Server-Sent Events transport
- **`url`**: The SSE endpoint URL
- **`headers`**: HTTP headers (same as HTTP transport)
**Example:**
```json
{
"legacy-server": {
"type": "sse",
"url": "https://api.example.com/sse",
"headers": {
"X-API-Key": "${API_KEY}"
}
}
}
```
## Environment Variable Expansion
### Syntax
| Pattern | Behavior | Example |
|---------|----------|---------|
| `${VAR}` | Required variable (error if not set) | `${API_KEY}` |
| `${VAR:-default}` | Optional with fallback value | `${PORT:-8080}` |
| `${CLAUDE_PLUGIN_ROOT}` | Plugin directory path (special) | `${CLAUDE_PLUGIN_ROOT}/bin` |
### Expansion Locations
Environment variables can be expanded in:
- **Stdio servers**:
- `command` field
- `args` array elements
- `env` object values
- **HTTP/SSE servers**:
- `url` field
- `headers` object values
### Special Variables
#### `${CLAUDE_PLUGIN_ROOT}`
- **Type**: Plugin-specific
- **Value**: Absolute path to plugin directory
- **Use case**: Reference bundled servers, configs, assets
- **Example**: `"${CLAUDE_PLUGIN_ROOT}/servers/db-server"`
#### User Environment Variables
All variables from user's shell environment are available:
```json
{
"env": {
"PATH": "${PATH}", // User's PATH
"HOME": "${HOME}", // User's home directory
"DATABASE_URL": "${DATABASE_URL}" // Custom user variable
}
}
```
### Expansion Examples
**Basic expansion:**
```json
{
"url": "${API_BASE_URL}/mcp"
}
```
With `API_BASE_URL=https://api.example.com`, becomes:
```
https://api.example.com/mcp
```
**Default values:**
```json
{
"env": {
"LOG_LEVEL": "${LOG_LEVEL:-info}",
"PORT": "${PORT:-3000}"
}
}
```
Without environment variables set, becomes:
```json
{
"env": {
"LOG_LEVEL": "info",
"PORT": "3000"
}
}
```
**Plugin-relative paths:**
```json
{
"command": "${CLAUDE_PLUGIN_ROOT}/bin/server",
"args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"]
}
```
With plugin at `/home/user/.claude/plugins/my-plugin`, becomes:
```
command: /home/user/.claude/plugins/my-plugin/bin/server
args: ["--config", "/home/user/.claude/plugins/my-plugin/config.json"]
```
## Configuration Files
### .mcp.json (Recommended)
**Location**: Plugin root directory
**Structure**:
```json
{
"mcpServers": {
"server-name-1": { /* config */ },
"server-name-2": { /* config */ }
}
}
```
**Advantages**:
- Separates concerns (MCP config separate from plugin metadata)
- Easier to maintain complex configurations
- Can be shared/reused across plugins
- Better for multiple MCP servers
**Example**:
```json
{
"mcpServers": {
"database": {
"command": "npx",
"args": ["-y", "@bytebase/dbhub", "--dsn", "${DATABASE_URL}"]
},
"api": {
"type": "http",
"url": "${API_BASE_URL}/mcp"
}
}
}
```
### plugin.json (Inline)
**Location**: `.claude-plugin/plugin.json`
**Structure**:
```json
{
"name": "my-plugin",
"version": "1.0.0",
"mcpServers": {
"server-name": { /* config */ }
}
}
```
**Advantages**:
- Single file for simple plugins
- All configuration in one place
- No additional files needed
**Example**:
```json
{
"name": "simple-plugin",
"version": "1.0.0",
"description": "A simple plugin with one MCP server",
"mcpServers": {
"api": {
"type": "http",
"url": "https://api.example.com/mcp"
}
}
}
```
**Choosing Between .mcp.json and inline:**
- Use `.mcp.json` for 2+ servers or complex configs
- Use inline for single simple server
- Both methods are functionally identical
## Server Lifecycle
### 1. Plugin Enable
- Plugin is enabled via `/plugin enable`
- MCP servers are registered with Claude Code
- No servers start yet
### 2. Claude Code Start
- Claude Code reads enabled plugins
- MCP servers start automatically
- Stdio servers: Process spawned
- HTTP/SSE servers: Connection established
### 3. Server Ready
- Server responds to initialization
- Tools/resources/prompts registered
- Available via `/mcp` command
### 4. Plugin Update
- Configuration changes detected
- **Requires Claude Code restart** to apply
- Old servers stop, new ones start on restart
### 5. Plugin Disable
- Plugin disabled via `/plugin disable`
- MCP servers stop automatically
- Resources cleaned up
## Platform-Specific Considerations
### Windows
**npx Wrapper Required:**
```json
{
"command": "cmd",
"args": ["/c", "npx", "-y", "package-name"]
}
```
**Path Separators:**
- Windows: Use forward slashes `/` in JSON
- Variable expansion handles platform differences
- Example: `"${CLAUDE_PLUGIN_ROOT}/bin/server"` works on all platforms
**Environment Variables:**
```json
{
"env": {
"USERPROFILE": "${USERPROFILE}", // Windows home directory
"APPDATA": "${APPDATA}" // Windows app data
}
}
```
### macOS/Linux
**Standard Commands:**
```json
{
"command": "npx",
"args": ["-y", "package-name"]
}
```
**Executable Permissions:**
- Bundled executables must have execute permissions
- Set in version control: `git update-index --chmod=+x server.sh`
- Or in plugin distribution: `chmod +x ${CLAUDE_PLUGIN_ROOT}/bin/*`
## Validation and Errors
### Common Validation Errors
**Invalid JSON:**
```
Error: Failed to parse .mcp.json
```
**Solution**: Validate JSON syntax with `jq` or JSON validator
**Missing Required Fields:**
```
Error: Missing required field 'command' in stdio server config
Error: Missing required field 'url' in http server config
```
**Solution**: Add required fields per schema above
**Invalid Variable Expansion:**
```
Error: Environment variable 'API_KEY' is required but not set
```
**Solution**: Set required environment variable or provide default value
**Invalid URL:**
```
Error: Invalid URL in http server config
```
**Solution**: Ensure URL is valid HTTP(S) format
### Runtime Errors
**Server Won't Start:**
- Check command path exists and is executable
- Verify all required environment variables are set
- Check server logs for startup errors
**Connection Failed (HTTP/SSE):**
- Verify URL is accessible
- Check network/firewall settings
- Confirm authentication headers are correct
**Server Not Found:**
- Ensure plugin is enabled
- Restart Claude Code after config changes
- Check `/mcp` output for registered servers
## Performance Considerations
### Stdio Servers
**Process Overhead:**
- Each stdio server is a separate process
- Consider resource usage for multiple servers
- Use HTTP servers for remote services
**Startup Time:**
- Servers start on Claude Code launch
- Slow-starting servers delay tool availability
- Consider lazy initialization for heavy servers
### HTTP/SSE Servers
**Network Latency:**
- Remote servers add network latency
- Use connection pooling where possible
- Consider caching for read-heavy operations
**Rate Limiting:**
- Respect API rate limits
- Implement backoff strategies
- Cache responses when appropriate
## Security Best Practices
### Credential Management
✅ **Do:**
- Store credentials in environment variables
- Use `${VAR}` expansion in configs
- Document required variables in README
- Use secure storage for sensitive values
❌ **Don't:**
- Hardcode credentials in JSON
- Commit credentials to version control
- Share credentials in plugin distributions
- Log credential values
### Network Security
**HTTPS Only:**
```json
{
"type": "http",
"url": "https://api.example.com/mcp" // ✅ HTTPS
}
```
**Avoid HTTP:**
```json
{
"type": "http",
"url": "http://api.example.com/mcp" // ❌ Insecure
}
```
**Certificate Validation:**
- HTTPS certificates are validated by default
- Don't disable certificate validation
- Use valid, trusted certificates
### Process Security
**Least Privilege:**
- Stdio servers run with user's permissions
- Don't require elevated privileges
- Validate all inputs from MCP protocol
**Sandboxing:**
- Stdio servers are not sandboxed
- Be cautious with user input
- Validate/sanitize all data
## Debugging
### Enable Debug Logging
Set environment variables before starting Claude Code:
```bash
export DEBUG=mcp:*
export MCP_LOG_LEVEL=debug
claude
```
### Check Server Status
Within Claude Code:
```
/mcp
```
Shows:
- Registered servers
- Connection status
- Available tools/resources
### Test Server Manually
**Stdio Server:**
```bash
# Test command directly
node ${CLAUDE_PLUGIN_ROOT}/servers/my-server.js
# With environment
API_KEY=test node servers/my-server.js
```
**HTTP Server:**
```bash
# Test endpoint
curl -H "Authorization: Bearer ${API_TOKEN}" \
https://api.example.com/mcp
```
### Common Debug Scenarios
**Server Not Appearing:**
1. Check plugin is enabled: `/plugin list`
2. Verify config syntax: `cat .mcp.json | jq .`
3. Restart Claude Code
4. Check for error messages on startup
**Server Starts But No Tools:**
1. Check server logs for initialization errors
2. Verify server implements MCP protocol correctly
3. Test server manually outside Claude Code
4. Check server responds to `tools/list` request
**Environment Variables Not Expanding:**
1. Verify syntax: `${VAR}` not `$VAR`
2. Check variable is set: `echo $VAR`
3. Restart Claude Code after setting variables
4. Check for typos in variable names
## See Also
- [Main MCP Configuration Guide](skill.md)
- [Real-World Examples](examples.md)
- [MCP Protocol Specification](https://modelcontextprotocol.io/)
- [Claude Code Plugin Documentation](https://docs.claude.com/en/docs/claude-code/plugins)

306
claude-code/skills/mcp-config/skill.md
View File

@@ -1,306 +0,0 @@
---
name: MCP Configuration Specialist
description: Configure MCP servers in Claude Code plugins and .mcp.json files. Use PROACTIVELY when users mention "MCP server", "configure MCP", "add MCP", ".mcp.json", "Model Context Protocol", or need to bundle MCP integrations in plugins. NOT for using existing MCP tools.
---
# MCP Configuration in Claude Code Plugins
## When to Use This Skill
Use this skill when:
- Configuring MCP servers in plugin `.mcp.json` files
- Adding MCP servers to `plugin.json` inline
- Setting up stdio, HTTP, or SSE transports
- Configuring environment variables and authentication
- Bundling MCP servers with plugins for distribution
Do NOT use this skill for:
- Using MCP tools (that's normal Claude Code usage)
- Creating MCP servers themselves (use mcp-builder skill)
- Installing MCP servers via CLI commands
## Quick Start
### 1. Plugin MCP Configuration (.mcp.json at plugin root)
```json
{
"mcpServers": {
"server-name": {
"command": "${CLAUDE_PLUGIN_ROOT}/servers/my-server",
"args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
"env": {
"API_KEY": "${API_KEY}",
"DB_URL": "${DB_URL}"
}
}
}
}
```
### 2. Inline in plugin.json
```json
{
"name": "my-plugin",
"version": "1.0.0",
"mcpServers": {
"plugin-api": {
"command": "${CLAUDE_PLUGIN_ROOT}/servers/api-server",
"args": ["--port", "8080"]
}
}
}
```
## MCP Transport Types
### Stdio (Local Process)
**Best for**: Local tools, file system access, custom scripts
```json
{
"my-local-server": {
"command": "node",
"args": ["${CLAUDE_PLUGIN_ROOT}/servers/local.js"],
"env": {
"LOG_LEVEL": "info"
}
}
}
```
**Common commands**: `node`, `python`, `npx`, `${CLAUDE_PLUGIN_ROOT}/bin/server`
**Windows Note**: Wrap `npx` with `"cmd", ["/c", "npx", ...]`
### HTTP (Remote Server)
**Best for**: Cloud services, REST APIs, remote integrations
```json
{
"remote-api": {
"type": "http",
"url": "https://mcp.example.com/mcp",
"headers": {
"Authorization": "Bearer ${API_TOKEN}"
}
}
}
```
### SSE (Deprecated)
**Note**: Prefer HTTP transport when available
```json
{
"legacy-sse": {
"type": "sse",
"url": "https://api.example.com/sse"
}
}
```
## Environment Variables
### Plugin-Relative Paths
```json
{
"command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
"args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"]
}
```
### User Environment Variables
```json
{
"env": {
"DATABASE_URL": "${DATABASE_URL}",
"API_KEY": "${API_KEY}"
}
}
```
### Default Values
```json
{
"url": "${API_BASE_URL:-https://api.example.com}/mcp",
"env": {
"LOG_LEVEL": "${LOG_LEVEL:-info}"
}
}
```
**Syntax**: `${VAR}` (required) or `${VAR:-default}` (optional with fallback)
## Common Patterns
### Database Access
```json
{
"postgres-db": {
"command": "npx",
"args": ["-y", "@bytebase/dbhub", "--dsn", "${DATABASE_URL}"]
}
}
```
### API Integration
```json
{
"company-api": {
"type": "http",
"url": "${API_BASE_URL}/mcp",
"headers": {
"Authorization": "Bearer ${API_TOKEN}",
"X-Workspace-ID": "${WORKSPACE_ID}"
}
}
}
```
### Multi-Server Plugin
```json
{
"mcpServers": {
"database": {
"command": "${CLAUDE_PLUGIN_ROOT}/servers/db",
"env": {"DB_URL": "${DATABASE_URL}"}
},
"api": {
"type": "http",
"url": "${API_URL}/mcp"
}
}
}
```
## Security Best Practices
### ✅ DO
```json
{
"env": {
"API_KEY": "${API_KEY}", // User environment
"CONFIG": "${CLAUDE_PLUGIN_ROOT}" // Plugin-relative
}
}
```
### ❌ DON'T
```json
{
"env": {
"API_KEY": "sk_live_1234567890", // ❌ Hardcoded secret
"PASSWORD": "my_password" // ❌ Exposed credential
}
}
```
**Best practices**:
1. Document required environment variables in README
2. Use placeholders in examples: `${API_KEY}`
3. Never commit actual credentials
4. Validate required vars at runtime
## Plugin Distribution
### Directory Structure
```
my-plugin/
├── .claude-plugin/
│ └── plugin.json
├── .mcp.json # MCP configuration at root
├── servers/ # Optional bundled servers
│ └── custom-server.js
└── README.md # Document env vars needed
```
### README Documentation Template
```markdown
## Required Environment Variables
Set these before enabling the plugin:
- `DATABASE_URL` - PostgreSQL connection string
- `API_KEY` - Your API authentication key
Example:
```bash
export DATABASE_URL="postgresql://user:pass@localhost/db"
export API_KEY="your-key-here"
```
```
## Testing & Troubleshooting
### Validate Configuration
```bash
# Check JSON syntax
cat .mcp.json | jq .
# Install and test
/plugin install /path/to/plugin@local
/mcp
# Verify environment variables
echo $DATABASE_URL
```
### Common Issues
| Problem | Solution |
|---------|----------|
| Server not starting | Check command path, ensure executable exists |
| Environment var not expanded | Verify syntax: `${VAR}` not `$VAR` |
| Windows stdio failure | Add `"cmd /c"` wrapper for npx |
| Connection errors | Verify URL, check network/firewall |
| Server not found in `/mcp` | Restart Claude Code after plugin changes |
## Key Concepts
**Configuration Scopes**: Plugin MCP servers are project-scoped:
- Start automatically when plugin is enabled
- Require Claude Code restart to apply changes
- Managed through plugin installation (not `/mcp` commands)
**Transport Selection**:
- **Stdio**: Local processes, file system access
- **HTTP**: Cloud services, REST APIs (recommended)
- **SSE**: Legacy support (use HTTP instead)
**Integration Points**:
1. `.mcp.json` at plugin root (preferred for complex configs)
2. `plugin.json` → `mcpServers` field (inline for simple configs)
## Additional Resources
**Related Skills:**
- [Plugin Development](../claude-plugins/skill.md) - Create complete plugins
- [MCP Builder](../../example-skills/mcp-builder/) - Build MCP servers
**Auxiliary Documentation:**
- [Real-World Examples](examples.md) - Complete plugin configurations
- [Configuration Reference](reference.md) - Detailed schema and options
**External:**
- [MCP Protocol Docs](https://modelcontextprotocol.io/)
- [Claude Code MCP Docs](https://docs.claude.com/en/docs/claude-code/mcp)
---
**Remember**: Plugin MCP servers start automatically when enabled. Use `${CLAUDE_PLUGIN_ROOT}` for plugin-relative paths. Document required environment variables. Restart Claude Code to apply MCP changes.

193
claude-code/skills/project-mcp-setup/skill.md
View File

@@ -1,193 +0,0 @@
# Project MCP Setup Templates
## When to Use This Skill
Use this skill when you need to quickly create a `.mcp.json` file for a new project with common MCP server configurations. This skill provides pre-configured templates so you don't have to look up MCP settings every time.
**Triggers:**
- User mentions creating or setting up `.mcp.json` for a project
- User wants to configure MCPs for a specific project type (technical, prose, minimal)
- User asks to "set up MCPs" or "configure MCP servers"
**Do NOT use for:**
- Configuring MCPs in plugins (use `claude-code:mcp-config` skill)
- Creating MCP servers (use `example-skills:mcp-builder` skill)
## Available Templates
### 1. Technical Projects
Full-featured setup for software development:
- **gitea**: Issue and PR management for Gitea-hosted repos
- **ya-memory**: Persistent memory across conversations
- **ya-rag**: Document indexing and semantic search
- **sequential-thinking**: Complex problem-solving
- **rubber-duck**: Debugging assistant
### 2. Prose/Writing Projects
Minimal setup focused on writing:
- **ya-memory**: Character tracking, world-building notes
- **rubber-duck**: Brainstorming and feedback
### 3. Minimal Projects
Bare essentials:
- **ya-memory**: Basic memory only
### 4. Custom
Let the user specify which MCPs they want from their user configuration.
## Template Definitions
### Technical Template
```json
{
"mcpServers": {
"gitea": {
"command": "uvx",
"args": ["mcp-server-gitea"],
"env": {
"GITEA_BASE_URL": "${GITEA_BASE_URL:-https://code.movq.us}",
"GITEA_TOKEN": "${GITEA_TOKEN}"
}
},
"ya-memory": {
"command": "uvx",
"args": ["--from", "git+https://github.com/russellballestrini/ya-memory-mcp.git", "ya-memory-mcp"],
"env": {
"YA_MEMORY_BASE_DIR": "${YA_MEMORY_BASE_DIR:-~/.ya-memory}"
}
},
"ya-rag": {
"command": "uvx",
"args": ["--from", "git+https://github.com/russellballestrini/ya-rag-mcp.git", "ya-rag-mcp"],
"env": {
"YA_RAG_BASE_DIR": "${YA_RAG_BASE_DIR:-~/.ya-rag}"
}
},
"sequential-thinking": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
},
"rubber-duck": {
"command": "uvx",
"args": ["--from", "git+https://github.com/russelballestrini/rubber-duck-mcp.git", "rubber-duck-mcp"]
}
}
}
```
### Prose Template
```json
{
"mcpServers": {
"ya-memory": {
"command": "uvx",
"args": ["--from", "git+https://github.com/russellballestrini/ya-memory-mcp.git", "ya-memory-mcp"],
"env": {
"YA_MEMORY_BASE_DIR": "${YA_MEMORY_BASE_DIR:-~/.ya-memory}"
}
},
"rubber-duck": {
"command": "uvx",
"args": ["--from", "git+https://github.com/russelballestrini/rubber-duck-mcp.git", "rubber-duck-mcp"]
}
}
}
```
### Minimal Template
```json
{
"mcpServers": {
"ya-memory": {
"command": "uvx",
"args": ["--from", "git+https://github.com/russellballestrini/ya-memory-mcp.git", "ya-memory-mcp"],
"env": {
"YA_MEMORY_BASE_DIR": "${YA_MEMORY_BASE_DIR:-~/.ya-memory}"
}
}
}
}
```
## Usage Instructions
When this skill is invoked:
1. **Ask the user which template they want** (unless they already specified):
- Technical (software development with full tooling)
- Prose (writing projects)
- Minimal (just memory)
- Custom (user specifies MCPs)
2. **For Custom**, ask which MCPs they want to include from:
- gitea
- ya-memory
- ya-rag
- sequential-thinking
- rubber-duck
- (or any others they specify)
3. **Check if `.mcp.json` already exists** in the current directory:
- If yes, ask if they want to overwrite or merge
- If merge, combine configurations
4. **Generate the `.mcp.json` file** with the selected template
5. **Inform the user**:
- Where the file was created
- What MCPs were included
- That they need to restart Claude Code or use `/mcp reload` to load the new configuration
- Any required environment variables they need to set
## Environment Variables Reference
Document these common environment variables:
- **GITEA_BASE_URL**: Gitea instance URL (default: https://code.movq.us)
- **GITEA_TOKEN**: Gitea API token (required for gitea MCP)
- **YA_MEMORY_BASE_DIR**: Memory storage location (default: ~/.ya-memory)
- **YA_RAG_BASE_DIR**: RAG index location (default: ~/.ya-rag)
## Example Interactions
**Example 1: Quick technical setup**
```
User: Set up MCPs for this project
Assistant: I'll help you set up a .mcp.json file. What type of project is this?
- Technical (software development)
- Prose (writing)
- Minimal (just memory)
- Custom
User: Technical
Assistant: [Creates .mcp.json with technical template]
```
**Example 2: Direct request**
```
User: Create a .mcp.json with just memory and rubber duck
Assistant: [Creates .mcp.json with those two MCPs]
```
**Example 3: Merge existing**
```
User: Add gitea to my MCP config
Assistant: I see you already have a .mcp.json with ya-memory. I'll add gitea to it.
[Merges gitea into existing config]
```
## Key Points
- **Project-specific**: These `.mcp.json` files are for individual projects, not global
- **Restartable**: Changes require Claude Code restart or `/mcp reload`
- **Committable**: These files can be committed to version control (but not with secrets)
- **Environment variables**: Use `${VAR}` syntax with optional defaults like `${VAR:-default}`
- **Additive**: Can be added to existing projects without affecting user-level MCPs
## Related Skills
- **claude-code:mcp-config**: For plugin MCP configuration
- **example-skills:mcp-builder**: For creating new MCP servers

9
genealogy/.claude-plugin/plugin.json Normal file
View File

@@ -0,0 +1,9 @@
{
"name": "genealogy",
"version": "1.0.0",
"description": "Genealogy research methodology plugin. GPS-based evidence evaluation, FAN research workflows, research journal conventions, claim promotion, and Council of Experts escalation criteria.",
"author": {
"name": "Adam Knight"
},
"keywords": ["genealogy", "research", "methodology", "GPS", "FAN", "evidence"]
}

186
genealogy/commands/transcribe.md Normal file
View File

@@ -0,0 +1,186 @@
---
name: transcribe
argument: path
---
# Transcription Prompt for Historical Document Images
You are transcribing historical document images into a structured markdown sidecar file for an Obsidian vault. Your goal is to produce a faithful, readable transcription that clearly distinguishes certainty from uncertainty and keeps editorial commentary out of the transcription body.
If a filename has been provided, process only that filename. Otherwise, process each image in the current directory ONE AT A TIME. Do not batch.
Consider each document carefully according to the following instructions.
## Output Structure
The sidecar file has five parts: YAML frontmatter, a heading, Description, Transcription, and Transcription Notes.
### YAML Frontmatter
Use Obsidian-compatible YAML frontmatter (`---` delimited) at the top of the file. Include `source` (the image filename) and `type` (the document type), then add any applicable annotations from the list below. Omit fields that cannot be determined. Do not invent new field names — if none of the suggested fields fit, describe it in the Description section instead.
**Required fields (always include):**
- `source` — the image filename
- `type` — the document type (e.g., deed, will, death certificate, marriage record, pension record, bible record, gravestone, letter, court order)
- `date` — document date (ISO 8601 format: YYYY-MM-DD, or YYYY-MM or YYYY if day/month unknown)
- `state` — state where the document was created or filed
- `county` — county where the document was created or filed
**Suggested annotations (include when applicable):**
- `collection` — the archive, repository, or record group
- `book_volume` — book or volume identifier
- `page` — page number(s)
- `file_number` — official file or certificate number
- `grantor` — seller or conveyor (deeds)
- `grantee` — buyer or recipient (deeds)
- `testator` — person making a will
- `executor` — person appointed to execute a will
- `deceased` — the deceased person (death certificates, probate)
- `applicant` — person applying (pensions, bounty land)
- `soldier` — the servicemember (military records)
- `bride` — bride's name (marriage records)
- `groom` — groom's name (marriage records)
- `acreage` — land area as stated
- `consideration` — price or payment
- `witnesses` — list of witnesses
- `clerk` — recording clerk
- `justice` — justice of the peace or presiding judge
Example frontmatter for a deed:
```yaml
---
source: "Leto Atreides deed to Duncan Idaho.jpg"
type: deed
date: 1829-08-01
state: Caladan
county: Habbanya
book_volume: "Deed Book 21"
page: 177
grantor: Leto Atreides and wife Jessica
grantee: Duncan Idaho
acreage: "50 acres"
consideration: "$250"
---
```
### Heading
A single `#` heading derived from the document title / filename.
### Description
A brief, plain-language summary of the physical document and its contents. Include:
- What type of record it is and where it comes from (book, page, archive)
- General condition and legibility observations
- Notable features (e.g., multiple hands, later annotations, damage)
Keep this to 2-4 sentences.
### Transcription
An exact transcription of the text as it appears on the page. This section contains **only** what is on the page: the words, their order, and visual descriptions of non-textual elements. No summaries, no interpretive commentary, no editorial notes.
Use footnote markers `[fn1]`, `[fn2]`, etc. to flag anything that needs discussion, and place the commentary in the Transcription Notes section.
#### Conventions
**Layout and formatting:**
- Preserve paragraph breaks where they appear in the original
- Do not attempt to reproduce exact line breaks within a paragraph
- Use `---` to indicate a visual separation or change of section on the page (e.g., between the deed body and the acknowledgment)
- Use blank lines between distinct blocks (signatures, recording notations, etc.)
**Page errata:**
- Include page numbers, headers, footers, and any other marginal notations exactly where they appear relative to the body text
- Place page headers/numbers at the top of the transcription, before the body text
- Place footers at the bottom, after the body text
- Marginal notes should be indicated with `[margin: text]` at the nearest point in the body text
**Abbreviations:**
- Preserve abbreviations as written
- Expand on first occurrence only: `Wm [William]`
- Do not expand common/obvious abbreviations after first use
**Annotations for uncertain or missing text:**
| Annotation | Use |
|---|---|
| `[illegible]` | One illegible word |
| `[word?]` | Best guess at one word |
| `[word or word?]` | Multiple guesses for one word |
| `[illegible, ~N words]` | Short illegible run, approximate word count |
| `[illegible passage]` | Long illegible run; describe in Transcription Notes |
**Annotations for physical features:**
| Annotation | Use |
|---|---|
| `[his mark]` or `[her mark]` | A mark made in lieu of a signature |
| `{seal: text}` | Text or content within a seal or containing mark |
| `{seal}` | A seal with no legible content |
| `[inserted above: text]` | Interlineation (text added above the line) |
| `[struck: text]` | Visible struck-through or crossed-out text |
| `[damaged: description]` | Physical damage (torn, stained, faded) preventing reading |
| `[description of non-text element]` | Any other visual, non-textual element on the page |
**What does NOT go in the transcription:**
- Summaries or restatements of content
- Interpretations of legal meaning
- Commentary on handwriting quality (save for Description or Notes)
- Historical context
- Corrections to spelling or grammar
### Transcription Notes
All editorial commentary goes here. This includes:
- Footnotes referenced in the transcription (`fn1.`, `fn2.`, etc.)
- Discussion of difficult readings and why a particular guess was chosen
- Identification of hands (if multiple scribes)
- Observations about unusual spellings, legal formulae, or period conventions
- Cross-references to other documents or records
- Anything else that aids understanding but is not part of the original text
## Example Output
```markdown
---
source: "Leto Atreides deed to Duncan Idaho.jpg"
type: deed
date: 1829-08-01
state: Caladan
county: Habbanya
book_volume: "Deed Book 21"
page: 177
grantor: Leto Atreides and wife Jessica
grantee: Duncan Idaho
acreage: "50 acres"
consideration: "$250"
---
# Leto Atreides and wife Jessica deed land to Duncan Idaho, 1829
## Description
Deed record from Habbanya County, Caladan, Deed Book 21, Page 177. The document is an indenture conveying 50 acres from Leto Atreides and wife Jessica to Duncan Idaho. The text is in a single clerk's hand with generally fair legibility; the lower portion containing the acknowledgment and recording notation is more difficult to read.
## Transcription
[margin: Halleck & wife to Duncan Idaho]
177
This Indenture made this 1st day of August in the year of our Lord one thousand eight hundred and twenty nine between Leto Atreides and Jessica his wife of the County of Habbanya and State of Caladan of the one part and Duncan Idaho of the County of [Carthag?] [fn1] and State of Caladan of the other part ...
## Transcription Notes
fn1. The county name for Duncan Idaho is difficult to read. "Carthag" is the best reading based on letter shapes and the fact that Carthag County borders Habbanya to the east.
```
## Processing Instructions
- IMPORTANT: Process each image one at a time
- The sidecar file should have the same filename as the image but with a `.md` extension
- Use the image filename to inform the frontmatter and heading, but always verify against the actual document content
- When in doubt about a reading, prefer `[word?]` over silently guessing
- Err on the side of more annotations rather than fewer

263
genealogy/skills/genealogy-methodology/SKILL.md Normal file
View File

@@ -0,0 +1,263 @@
---
name: genealogy-methodology
description: Genealogy research methodology — GPS-based evidence evaluation, FAN research workflows with target lists, research journal conventions, claim promotion, and Council of Experts escalation criteria. Integrates with Librarian notebook and Gramps tree.
---
# Genealogy Research Methodology
## Purpose
This skill defines the research methodology, workflows, and standards for genealogy work in this project. It governs how research is planned, executed, documented, and validated.
This skill does NOT gate research behind planning steps. Research is autonomous. This skill ensures that autonomous research is *methodical* — that it extracts maximum value from every document, tracks what was searched, logs what was and wasn't found, and knows when to stop grinding and reassess.
## Core Principles
### Fact-Centric Research
- **Facts require sources.** Every `[fact]` must cite the source it came from.
- **Claims are not facts.** Unverified data — Ancestry hints, member trees, secondary accounts — is logged as `[question]` or `[claim]` until confirmed against a primary source image.
- **No interpretation during research.** If a person appears in County A then County B, record both appearances. Do not conclude they moved. Interpretation comes when all facts and gaps are known.
- **Absence of evidence is not evidence of absence.** A missing record means the record is missing, not that the event didn't happen.
### Source Hierarchy
1. **Original source images** — courthouse records, original certificates, church registers
2. **Derivative sources** — microfilm, published abstracts, database transcriptions
3. **Authored works** — compiled genealogies, county histories, message board posts
Ancestry hints, member trees, and indexed records are *leads*, not sources. They point you to images. The image is the source.
### Extract Everything Valuable in One Pass
When examining a document (census page, deed book, tax roll, will), do not extract only the target person. Extract every person relevant to the tree or the FAN cluster. You may not come back to this document, and re-finding it costs time.
## Workflows
### FAN Research Workflow
A FAN (Family, Associates, Neighbors) research workflow is a structured investigation with a defined goal and finish line.
#### Structure
1. **Goal Statement** — A specific, measurable research question. Not "research Paulus Atreides" but "Determine the father of Leto Paulus Atreides using Arrakeen Province records 10150-10175."
2. **Target List** — People to watch for while examining documents:
- The primary subject
- Known family members (from tree or prior research)
- Associates (witnesses, executors, bondsmen, business partners)
- Neighbors (adjacent land, same census page, same church)
- Anyone else in the tree who appears in the same time and place
The target list grows during research. When a will names executors or a deed has witnesses, add them. When a census page shows a familiar surname, note it.
3. **Strategy** — The concrete plan to reach the goal:
- Which record sets to search (census, tax rolls, deeds, wills, church records)
- Which repositories hold them (FamilySearch, Ancestry, courthouse, state archives)
- What order to search them (usually chronological or by expected yield)
- Known coverage gaps or access restrictions
4. **Execution Log** — As each step is completed, record:
- What was searched (collection, date range, pages covered)
- What was found (with citations)
- What was NOT found (negative evidence)
- New targets or leads discovered
- Coverage notes (see Collection Coverage below)
5. **Finish Line** — The goal is met when:
- The research question is answered with sufficient evidence, OR
- All identified record sets have been searched and the question remains open (document the gap), OR
- The Council of Experts has reviewed the dead end and confirmed no further avenues exist
Use the FAN Research Plan template (`templates/fan-plan.md`) to structure these.
### Claim Promotion (GPS Checklist)
A claim becomes a fact when it satisfies the Genealogical Proof Standard. This is a deliberate, reviewable process.
#### The Five GPS Elements
1. **Reasonably exhaustive research** — Have you searched the record sets that could confirm or deny this claim? Not every record ever created, but the ones a competent researcher would check.
2. **Complete and accurate citations** — Every supporting source is cited with enough detail to find the original.
3. **Analysis and correlation** — Sources have been compared. Agreements and disagreements are documented.
4. **Resolution of conflicting evidence** — If sources disagree, the conflict is explained (not ignored).
5. **Soundly reasoned conclusion** — The logic connecting evidence to conclusion is explicit and defensible.
#### Promotion Process
1. Assemble all sources supporting the claim on the person's note, each with inline citation.
2. Check each GPS element. Document which sources satisfy each element.
3. If all five are met, draft a brief proof statement on the person's note explaining the reasoning.
4. Submit to the Council of Experts for review (use the `council` skill).
5. Collect approved promotions and present them to the user in a batch — list each claim, the supporting sources, and the proof statement. The user will call out any they disagree with.
6. Promote approved claims: change the tag from `[claim]` to `[fact]` and note the date of promotion.
If GPS cannot be fully satisfied, assign a confidence level:
- **Probable** — Preponderance of evidence supports it; minor gaps remain
- **Possible** — Some evidence supports it; significant gaps exist
- **Unproven** — Insufficient evidence to assess
- **Disproven** — Evidence contradicts the claim
### Council of Experts Escalation
The Council of Experts provides fresh perspectives when research stalls. Use it deliberately — not after every failed search, but when patterns suggest you're stuck.
#### When to Escalate
**Escalate when:**
- Multiple record sets across different collections yield nothing (e.g., two census years across three counties with no appearance)
- Conflicting sources cannot be resolved by evidence weight alone
- You've exhausted the obvious strategy and need new angles
- A FAN workflow has hit its finish line without answering the question
- You suspect identity confusion (two people conflated, or one person split)
**Do NOT escalate when:**
- You're partway through a large collection (30 images in a tax reel is normal)
- A single census or record set didn't have the person (they get missed)
- You haven't yet tried the obvious sources
- The search is progressing but slowly
**Rule of thumb:** If you've searched the same type of record across two independent dimensions (two time periods, two jurisdictions, two collection types) and found nothing in either, stop and think. One miss is normal. Two independent misses is a pattern worth examining.
### Collection Coverage Tracking
When working through a record collection (tax rolls, deed books, census reels), track coverage on the **source note** for that collection.
#### What to Record
- Collection identifier (FamilySearch film number, Ancestry collection ID, book/volume)
- Date range covered in this pass
- Pages or image numbers examined
- What was extracted (people found, documents noted)
- What was NOT found (negative evidence for target list members)
#### Before Re-Searching a Collection
Always check the source note for previous coverage. If pages 12-48 of Arrakeen PPT 10150-10160 were already covered, start at page 49 or move to a different year range.
## Research Journal
The Research Journal (formerly "Worklog") is the running record of all research activity. It lives as a Librarian note and serves two purposes: session continuity and institutional memory.
### Structure
Each entry uses this format:
```
## YYYY-MM-DD
### HH:MM — [Short Title]
**Goal:** [What you set out to do]
**Searched:**
- [Collection/source searched] — [pages/range covered] — [result: found X / nothing relevant]
- [Collection/source searched] — [pages/range covered] — [result]
**Found:**
- [Key finding with inline citation]
- [Key finding with inline citation]
**Not Found (Negative Evidence):**
- [What you expected to find but didn't, and where you looked]
**New Leads:**
- [Anything discovered that warrants follow-up]
**Target List Updates:**
- [New people added to the FAN target list and why]
**Notes:**
[Unstructured observations, theories, hunches, anything that doesn't fit above but shouldn't be lost. This is the place for "I noticed that..." and "I wonder if..." — things that aren't facts but might matter later.]
**Open Questions:**
- [question] [Specific unanswered question arising from this session]
**Tasks:**
- [todo] [Specific next action arising from this session]
**Session Close:**
- Unfinished: [What was in progress when the session ended]
- Next: [What the next session should start with]
- Blocking: [Anything preventing progress — access issues, missing records, need user input]
```
### Conventions
- Use `[question]` and `[todo]` tags so they're searchable across the notebook
- The **Notes** section is deliberately unstructured — don't skip it. Hunches recorded here have led to breakthroughs.
- **Session Close** is mandatory. It's the handoff to the next session (which may be a different Claude instance with no memory of this one).
- Append entries within a day using `### HH:MM` subsections. Create a new `## YYYY-MM-DD` section for each day.
## Evidence Classification Reference
When evaluating a source, classify along three axes:
### Source Classification (What you consulted)
| Type | Description | Example |
|------|-------------|---------|
| Original | First recording in original form | Courthouse deed book, original certificate |
| Derivative | Copy, transcription, or extract | Published abstracts, database entries, microfilm |
| Authored | Compiled or analyzed work | Published genealogy, county history |
### Information Classification (When recorded relative to event)
| Type | Description | Example |
|------|-------------|---------|
| Primary | Recorded at/near time of event by knowledgeable person | Birth date on birth certificate |
| Secondary | Recorded well after event, from memory or hearsay | Birth date on death certificate |
| Undetermined | Cannot determine timing or informant | Undated family Bible entry |
### Evidence Classification (What it tells you)
| Type | Description | Example |
|------|-------------|---------|
| Direct | Explicitly states the needed fact | Marriage record naming bride and groom |
| Indirect | Implies fact when combined with other evidence | Age on census implying birth year |
| Negative | Expected information that is absent | Person missing from tax roll they should appear on |
**Critical distinction:** An original source can contain secondary information. A death certificate (original source) recording a birth date 80 years prior (secondary information) is weaker evidence for birth date than a birth certificate (original source, primary information) — even though both are "original records."
Load `references/evidence-evaluation.md` for detailed frameworks on conflict resolution and source weighting.
## Source Document Rules
Source notes in the Librarian notebook contain **only source material**:
- Citation (full reference)
- Transcription or abstract
- Persons table (who appears in the document)
- Factual discrepancy notes (e.g., name spelled two ways in the same document)
- Collection coverage (what was searched, what range)
Source notes do NOT contain:
- Analysis or commentary
- `[insight]` or `[question]` tags
- Theory or supposition
- Connections to other sources
Analysis, insights, questions, and theories belong in **person notes** (with citations back to the source) or in the **Research Journal**.
## Note Section Rules
**Templates define the allowed sections for each note type.** When a template includes "Open Questions" and "Tasks" sections, those sections belong on that note type. When a template does not include them (e.g., the source template), do not add them — put those items on the relevant person note instead.
### Standard Tags
| Tag | Meaning | Where Used |
|-----|---------|------------|
| `[fact]` | Verified with GPS-level evidence | Person notes |
| `[claim]` | Unverified assertion with a source | Person notes |
| `[question]` | Open research question | Person notes, location notes, journal entries |
| `[todo]` | Specific pending action | Person notes, location notes, journal entries |
| `[insight]` | Observation or pattern (with optional source) | Person notes |
Source notes use **no tags**. FAN plans use their own structure (execution log, target list).
## Templates
Output templates for structured documents:
- `templates/fan-plan.md` — FAN research plan with goal, target list, strategy, and execution log
- `templates/source.md` — Source document note (transcription + persons + coverage)
- `templates/person.md` — Person note (identity, claims, evidence, relations)
- `templates/location.md` — Location note (jurisdiction history, available records, coverage)
- `templates/journal-entry.md` — Single research journal entry
## References
Detailed reference material loaded as needed:
- `references/evidence-evaluation.md` — Conflict resolution frameworks, source weighting, GPS deep dive
- `references/fan-strategies.md` — FAN principle application, cluster genealogy, community reconstruction
- `references/council-escalation.md` — Detailed escalation criteria and examples

85
genealogy/skills/genealogy-methodology/references/council-escalation.md Normal file
View File

@@ -0,0 +1,85 @@
# Council of Experts Escalation Guide
When to convene the Council, what to bring, and what to expect.
## Purpose
The Council of Experts provides independent perspectives on research problems. It is most valuable when you've been grinding in one direction and need fresh eyes to see what you're missing. It is NOT a substitute for doing the research.
## Escalation Criteria
### Escalate: Pattern of Independent Failures
The key signal is **independent** failures — the same negative result across unrelated dimensions.
**Two independent misses = stop and think:**
- Searched two census years (different decades) across the expected county — person absent from both
- Searched tax rolls AND deed books for the same period — no appearance in either
- Searched two adjacent counties for the same period — nothing in either
- Searched the expected record type in two different repositories — nothing in either
**Single misses are normal:**
- One census year with no hit (people get missed, enumerators skip households)
- One tax reel with no appearance (might be in the other district)
- One deed book with no transactions (not everyone bought/sold land every decade)
- Thirty images deep in a large collection with nothing yet (keep going)
### Escalate: Unresolvable Source Conflicts
When you have:
- Two or more sources of roughly equal reliability that disagree
- No clear explanation for the disagreement
- No additional source that could break the tie
- The conflict matters for the research question
### Escalate: Identity Confusion
When you suspect:
- Two different people are being conflated into one (common with Sr./Jr. or same-name cousins)
- One person has been split into two (different name spellings treated as different people)
- Records attributed to your ancestor may belong to someone else
### Escalate: Dead End After Systematic Search
When:
- The FAN research plan has been executed through its strategy
- All identified record sets have been searched
- The question remains unanswered
- You need new avenues to explore
### Do NOT Escalate
- You're partway through a planned search (finish first)
- You've only tried one obvious source (try more first)
- The search is progressing, just slowly
- You want confirmation of something you're already confident about (just log it)
- You haven't yet searched the primary record sets identified in the strategy
## What to Bring to the Council
When invoking the Council skill, provide:
1. **The research question** — Specific, measurable, as defined in the FAN plan
2. **What was searched** — Record sets, repositories, date ranges, pages covered
3. **What was found** — Key findings, even if they didn't answer the question
4. **What was NOT found** — Specific negative evidence
5. **Current hypothesis** — What you think is going on (even if uncertain)
6. **Why you're stuck** — What specifically is blocking progress
The Council works best with concrete data, not vague summaries. Give them the details.
## What to Expect
The Council will typically:
- Challenge assumptions you may not realize you're making
- Suggest record types or repositories you haven't considered
- Offer alternative interpretations of evidence you've found
- Identify patterns you may have missed (naming patterns, migration patterns, community connections)
- Recommend whether to continue the current strategy, pivot, or accept the dead end
## After the Council
1. Log the Council's recommendations in the Research Journal
2. Update the FAN research plan if new avenues are identified
3. Continue research along the recommended path
4. If the Council confirms a dead end, document it clearly on the person's note so future sessions don't re-search the same ground

121
genealogy/skills/genealogy-methodology/references/evidence-evaluation.md Normal file
View File

@@ -0,0 +1,121 @@
# Evidence Evaluation and Conflict Resolution
Detailed frameworks for analyzing genealogical evidence, resolving conflicts between sources, and building proof arguments.
## Source Weighting
Not all sources are equal. When sources conflict, weight them — don't count them.
### Weighting Factors (in priority order)
1. **Proximity to event** — Was the informant present? Was the record created at the time of the event?
2. **Informant knowledge** — Did the informant have direct knowledge, or are they reporting hearsay?
3. **Purpose of the record** — Was the information central to the record's purpose (bride's name on a marriage license) or incidental (birthplace on a census)?
4. **Original vs. derivative** — Are you looking at the original, or a transcription/abstract that may contain copying errors?
5. **Internal consistency** — Does the source contradict itself?
6. **Corroboration** — Do independent sources agree? (Derivative copies of the same original are NOT independent corroboration.)
### Common Weighting Mistakes
- **Counting sources instead of weighing them.** Three Ancestry member trees copying the same wrong date don't outweigh one original record.
- **Treating indexes as sources.** An index points to a record. The record is the source. Index errors are common.
- **Assuming original = accurate.** A death certificate is an original source but contains secondary information about birth (reported decades later by someone who may not have been present).
- **Ignoring negative evidence.** A person's absence from a record they should appear in is evidence. It doesn't prove anything alone, but it contributes to the picture.
## Conflict Resolution Framework
When sources disagree about a fact:
### Step 1: Define the Conflict Precisely
State exactly what each source says. "The birth year is unclear" is not precise. "The 1850 census says age 35 (born ~1815), the 1860 census says age 50 (born ~1810), and the death certificate says born 1812" is precise.
### Step 2: Classify Each Source
For each conflicting source, document:
- Source type (original / derivative / authored)
- Information type (primary / secondary / undetermined)
- Evidence type (direct / indirect / negative)
- Informant (who provided the information, if known)
- Informant's relationship to the fact (direct knowledge / hearsay / unknown)
### Step 3: Identify Explanations
Before choosing a winner, consider why the sources disagree:
- **Transcription error** — The original says one thing, the copy says another
- **Informant error** — The person reporting didn't know or misremembered
- **Different informants** — Each source had a different informant with different knowledge
- **Rounding or estimation** — Census ages are often rounded; "about 35" could mean 33-37
- **Identity confusion** — The sources may be about different people with the same name
- **Both partially correct** — The truth may be between the sources (e.g., moved mid-year)
### Step 4: Apply Evidence Weight
Rank the sources from most to least reliable for THIS SPECIFIC FACT. A source can be highly reliable for one fact and unreliable for another within the same document.
### Step 5: State the Conclusion
- If one source clearly outweighs others: state the conclusion and explain why
- If sources are roughly equal: acknowledge the conflict is unresolvable with current evidence and note what additional records might resolve it
- If a pattern emerges (e.g., ages consistently decrease on later censuses): note the pattern as it may explain the discrepancy
## GPS Deep Dive
### Element 1: Reasonably Exhaustive Research
"Reasonably exhaustive" does not mean "every record ever created." It means:
- You searched the record types that could confirm or deny the claim
- You searched the repositories where those records are likely held
- You searched for the subject AND relevant FAN members
- You documented what you searched, including negative results
- You did not stop at the first confirming source
**Test:** Could a competent researcher point to an obvious, accessible record set you didn't check?
### Element 2: Complete and Accurate Citations
Every source must be cited with enough detail that another researcher can:
- Find the exact same record
- Evaluate the source's reliability
- Distinguish between the original record and the access method (e.g., "digital image of original" vs. "database entry")
### Element 3: Analysis and Correlation
Sources must be compared to each other:
- What do they agree on?
- What do they disagree on?
- Do they corroborate independently, or are they derivative of each other?
- What does each source contribute to the overall picture?
### Element 4: Resolution of Conflicting Evidence
Conflicts cannot be ignored. For each conflict:
- Acknowledge it explicitly
- Explain possible causes
- Apply evidence weight
- State whether the conflict is resolved or remains open
- If unresolved, explain what additional evidence might resolve it
### Element 5: Soundly Reasoned Conclusion
The conclusion must:
- Follow logically from the evidence presented
- Not overstate what the evidence supports
- Acknowledge limitations and remaining uncertainties
- Be written clearly enough that another researcher can follow the reasoning and evaluate it independently
## Proof Levels
| Level | Meaning | GPS Status |
|-------|---------|------------|
| Proven | Beyond reasonable doubt | All 5 elements fully satisfied |
| Probable | Preponderance supports it | Most elements satisfied; minor gaps |
| Possible | Some evidence supports it | Significant gaps in research or evidence |
| Unproven | Insufficient evidence | Cannot assess; more research needed |
| Disproven | Evidence contradicts it | Evidence actively refutes the claim |
## Common Genealogical Evidence Patterns
### Census Age Discrepancies
Census ages are notoriously unreliable. The informant may not have known exact ages, may have rounded, or the enumerator may have estimated. A 2-3 year spread across censuses is normal and does not constitute a meaningful conflict.
### Name Spelling Variations
Before standardized spelling, names were recorded phonetically by the recorder. Atreides/Atreidies, Halleck/Hallek/Hallak, Leto/Leeto are the same name. Treat spelling as fluid, not as evidence of different people.
### "Same Name, Same Place" Trap
Two people with the same name in the same county are NOT necessarily the same person. Use age, associates, property, and family context to distinguish. The existence of "Sr." and "Jr." designations in records may indicate father/son, but may also just mean "older" and "younger" among unrelated men.

101
genealogy/skills/genealogy-methodology/references/fan-strategies.md Normal file
View File

@@ -0,0 +1,101 @@
# FAN Strategies and Community Reconstruction
Detailed guidance on applying the FAN (Family, Associates, Neighbors) principle and reconstructing historical communities.
## The FAN Principle
Your ancestor did not live in isolation. They existed within a web of family, business, legal, and social relationships. When direct records for your ancestor are scarce, the people around them often left records that mention, imply, or contextualize your ancestor.
### Family
- Parents, siblings, children, spouses
- In-laws (often co-located, often witnesses)
- Step-relations and guardians
- Aunts, uncles, cousins (especially in migration — families moved together)
- Godparents (in church records — often indicate close relationships)
### Associates
- **Legal:** Witnesses to deeds, wills, and bonds. Executors and administrators. Bondsmen. Attorneys-in-fact.
- **Business:** Partners, co-signers, buyers and sellers of land. People who appear in the same merchant ledgers.
- **Military:** Men in the same company or regiment. Officers who signed documents.
- **Church:** Fellow members, elders, deacons. People who witnessed baptisms or marriages.
- **Government:** Fellow jurors, road overseers, tax commissioners. People appointed together.
### Neighbors
- Adjacent landowners (from deeds and plats)
- Same census enumeration district (census takers walked in order)
- Same tax district
- Same church congregation
- People who migrated together (appearing in both the origin and destination)
## Building a Target List
A target list starts with the people you know and grows as you research.
### Starting a Target List
1. Gather what is already known about the subject from the tree and existing research notes
2. Check for an existing FAN cluster in the notebook
3. Add anyone from the tree who lived in the same time and place
4. Add names from any known documents (witnesses, neighbors from census, etc.)
### Growing the Target List During Research
Every document you examine may reveal new targets:
- **Wills:** Executors, witnesses, beneficiaries, people mentioned by name
- **Deeds:** Buyers, sellers, witnesses, adjacent landowners named in bounds
- **Census:** Everyone on the same page or enumeration district
- **Tax rolls:** People listed near the subject (often geographic neighbors)
- **Court records:** Plaintiffs, defendants, witnesses, jurors, judges
- **Church records:** Other families in the register near the same dates
When you see a name you recognize from the tree or from prior research, note it even if it's not directly relevant to the current goal. Record it in the journal under "Target List Updates."
### Managing the Target List
The target list is part of the FAN research plan. Keep it updated:
- Add new names with a note on where they appeared
- Mark names that turn out to be irrelevant (but don't delete — they may matter later)
- Note relationships as they become clear ("Thufir Hawat — witness to Paulus Atreides's will; appears adjacent in 10156 census")
## Community Reconstruction
Community reconstruction is the practice of mapping the social, economic, and geographic relationships in a locality rather than researching a single family in isolation.
### Why It Matters
- Records are community records. A deed book contains everyone's deeds. A census page contains everyone's household. Researching one family means you're already looking at the community.
- Migration was social. Families moved with neighbors. Finding where the neighbors went often reveals where your ancestor went.
- Naming patterns are community patterns. If three families in the same sietch all name sons "Gurney," it might be a local tradition, not a family connection.
- Witnesses and bondsmen reveal trust networks. The people your ancestor chose for legal documents were people they trusted — often family.
### How to Do It
1. **Start with a document, not a person.** When you're reading a deed book or tax roll, note everyone — not just your target.
2. **Map repeated names.** Who appears across multiple record types? Who witnesses for whom? Who buys land from whom?
3. **Track geographic proximity.** Adjacent landowners in deeds, nearby households in census, same district in tax rolls.
4. **Note migration clusters.** If three families from County A all appear in County B within a few years, that's a cluster migration worth documenting.
5. **Record it in the FAN cluster notes** in Librarian (fan/[person-place]/ structure).
### What to Extract from Documents (Full-Page Reading)
When examining a document page, extract for anyone on the target list:
- Full names (with spelling variants)
- Ages, dates, locations
- Relationships stated or implied
- Property descriptions and values
- Occupations or status markers
- Marks vs. signatures (literacy indicator)
- Witnesses and their roles
For people NOT on the target list but in the same document:
- Note surnames that appear frequently (potential community members)
- Note anyone with the same surname as a target list member
- Note unusual details that might connect to the research question
## FAN in Practice: Working a Will
A will is one of the richest FAN documents. Here's how to extract maximum value:
1. **Identify everyone named:** Beneficiaries, executors, witnesses
2. **Note relationships stated:** "my son," "my beloved wife," "my friend"
3. **Note property details:** Land descriptions (neighbors named in bounds), enslaved persons (named, may appear in other records), specific bequests
4. **Check the probate file:** The will is often just the beginning. Estate inventories, accounts of sale, guardian appointments, and distribution records follow.
5. **Research the witnesses:** Who were they? Were they family? Neighbors? Did they witness other documents for the same family?
6. **Research the executors:** Why were they chosen? Family connection? Business partner?
7. **Cross-reference the beneficiaries:** Do they appear in census, tax, or land records nearby?
8. **Note who is NOT in the will:** If a known child is absent, that's potentially significant (predeceased? already received inheritance? estranged?).

73
genealogy/skills/genealogy-methodology/templates/fan-plan.md Normal file
View File

@@ -0,0 +1,73 @@
# FAN Research Plan Template
Use this template when creating a new FAN research workflow in the Librarian notebook.
---
## [Goal Statement]
**Research Question:** [Specific, measurable question — e.g., "Determine the parents of Leto Paulus Atreides using Arrakeen Province records 10150-10175"]
**Subject:** [Primary person being researched]
**Time Period:** [Date range for research]
**Location:** [County, state, or broader area]
**Finish Line:** [What constitutes completion — e.g., "Question answered with GPS-level evidence" or "All identified record sets searched and question documented as open"]
## Target List
| Name | Relationship to Subject | How Identified | Notes |
|------|------------------------|----------------|-------|
| [Subject] | Self | — | |
| [Name] | [wife/son/neighbor/etc.] | [Source where identified] | |
*Update this list as research progresses. New names from documents go here with source of identification.*
## Strategy
### Record Sets to Search
| Priority | Record Set | Repository | Date Range | Status |
|----------|-----------|------------|------------|--------|
| 1 | [e.g., Personal property tax lists] | [e.g., FamilySearch Film 2024561] | [1780-1800] | [Not started / In progress / Complete] |
| 2 | | | | |
| 3 | | | | |
### Known Access Restrictions
- [e.g., FamilySearch images restricted — need affiliate library or in-person access]
### Search Order Rationale
[Brief note on why this order — chronological? Expected yield? Availability?]
## Execution Log
### [Date] — [Record Set / Action]
**Searched:** [Collection, pages/images, date range covered]
**Found:**
- [Finding with citation]
**Not Found:**
- [Expected record/person not present — negative evidence]
**New Targets Added:**
- [Name — reason for addition]
**Coverage Note:** [Record what was covered so future sessions don't re-search]
---
*Copy the "Execution Log" section for each research step.*
## Status
**Current Status:** [Active / Paused / Complete / Dead End]
**Last Updated:** [Date]
**GPS Assessment:** [If question answered — which GPS elements are satisfied?]
**Council Review:** [If escalated — date and outcome]

57
genealogy/skills/genealogy-methodology/templates/journal-entry.md Normal file
View File

@@ -0,0 +1,57 @@
# Research Journal Entry Template
Append this structure to the Research Journal note in Librarian. Each day gets a `## YYYY-MM-DD` heading. Each session within a day gets a `### HH:MM` subheading.
---
```
## YYYY-MM-DD
### HH:MM — [Short Descriptive Title]
**Goal:** [What you set out to do this session]
**Searched:**
- [Collection/source] — [pages/range covered] — [found X / nothing relevant]
- [Collection/source] — [pages/range covered] — [result]
**Found:**
- [Key finding] — [[Source Note Title]]
- [Key finding] — [[Source Note Title]]
**Not Found (Negative Evidence):**
- [Expected to find X in Y but did not] — [[Source Note Title]]
**New Leads:**
- [Lead discovered that warrants follow-up]
**Target List Updates:**
- Added [Name] — [reason, source where identified]
- Added [Name] — [reason]
**Notes:**
[Unstructured space. Hunches, observations, patterns noticed, things that don't fit
elsewhere but shouldn't be lost. "I noticed that..." and "I wonder if..." belong here.
Theory and supposition live here, not on source or person notes.]
**Open Questions:**
- [question] [Specific unanswered question from this session]
**Tasks:**
- [todo] [Specific next action from this session]
**Session Close:**
- Unfinished: [What was in progress when session ended]
- Next: [What the next session should start with]
- Blocking: [Access issues, missing records, need user input, or "None"]
```
---
## Conventions
- **[question]** and **[todo]** tags are searchable across the notebook. Use them consistently.
- **Notes** section is deliberately unstructured. Don't skip it. Hunches recorded here have led to breakthroughs in this project.
- **Session Close** is mandatory. It's the handoff to the next session, which may be a different Claude instance with no memory of this one.
- **Negative evidence** is research data. "Searched and didn't find" is as important as "searched and found." Always record it.
- Append entries within a day using `### HH:MM` subsections. New day = new `## YYYY-MM-DD`.

67
genealogy/skills/genealogy-methodology/templates/location.md Normal file
View File

@@ -0,0 +1,67 @@
# Location Note Template
Use this template when creating a new location note in the Librarian notebook. Location notes document jurisdiction history and available records for a research area.
---
## Jurisdiction
- **Current Name:** [Current county/city/state name]
- **Formed:** [Date formed and parent county/jurisdiction]
- **Parent Jurisdiction:** [What it was carved from]
- **Child Jurisdictions:** [Counties later formed from this one, with dates]
## Jurisdiction Timeline
| Period | Jurisdiction | Notes |
|--------|-------------|-------|
| [e.g., Before 10150] | [e.g., Carthag Province, Arrakis] | [e.g., Arrakeen carved from Carthag 10150] |
| [10150-present] | [Arrakeen Province, Arrakis] | |
*This matters because records before the formation date are in the parent county.*
## Available Records
### Vital Records
- [What exists, date range, where held]
### Census
- [Federal census years available, state census if applicable]
### Tax Records
- [Personal property, land tax — date ranges, repositories, film numbers]
### Land Records
- [Deed books, grants — date ranges, repositories]
### Probate Records
- [Will books, estate files — date ranges, repositories]
### Court Records
- [Order books, minute books — date ranges, repositories]
### Church Records
- [Known congregations, record types, repositories]
### Military Records
- [Militia, pension, service records relevant to this area]
## Repositories
| Repository | Record Types | Access | Notes |
|-----------|-------------|--------|-------|
| [e.g., FamilySearch] | [e.g., PPT, deed books] | [e.g., Free / Restricted / In-person only] | [e.g., Film 2024561-2024562] |
| [e.g., Archives of Caladan] | | | |
| [e.g., County courthouse] | | | |
## Research Notes
[Observations about this location relevant to research — e.g., courthouse fires, known record gaps, local naming conventions, migration patterns in/out of this area.]
## Open Questions
- [question] [e.g., "Does the Arrakeen deed book for 10153 survive, or was it destroyed?"]
## Tasks
- [todo] [e.g., "Check Archives of Caladan catalog for surviving records"]

51
genealogy/skills/genealogy-methodology/templates/person.md Normal file
View File

@@ -0,0 +1,51 @@
# Person Note Template
Use this template when creating a new person note in the Librarian notebook. Person notes are the primary location for claims, analysis, and evidence evaluation.
---
## Identity
- **Name:** [Full name as most commonly recorded]
- **Name Variants:** [Alternate spellings found in records]
- **Born:** [Date and place — tag as [fact] or [claim]]
- **Died:** [Date and place — tag as [fact] or [claim]]
- **Buried:** [Location — tag as [fact] or [claim]]
## Relations
- **Father:** [[link-to-person-note]] — [fact/claim]
- **Mother:** [[link-to-person-note]] — [fact/claim]
- **Spouse(s):** [[link-to-person-note]] — married [date/place] — [fact/claim]
- **Children:** [[link-to-person-note]], [[link-to-person-note]]
## Claims
[Each claim is a statement with an inline citation and a tag. Claims are candidates for promotion to fact via GPS review.]
- [claim] [Statement about this person] — [[Source Note Title]]
- [fact] [Verified statement with GPS-level evidence] — [[Source Note Title]] — promoted [date]
- [claim] [Another unverified statement] — [[Source Note Title]]
## Open Questions
- [question] [Specific unanswered question about this person]
- [question] [Another question]
## Tasks
- [todo] [Specific research action related to this person]
## Evidence
[Analysis of sources relating to this person. This is where conflicts are examined, sources are weighed, and reasoning is documented.]
### [Topic — e.g., "Parentage" or "Birth Year"]
[Discussion of evidence for and against. Cite sources inline. If GPS review has been done, include the proof statement here.]
## Notes
[Unstructured observations, theories, naming pattern analysis, community connections. Anything that might matter but isn't a formal claim or question. Tag speculation clearly.]
- [insight] [Observation with optional source] — [[Source Note Title]]

45
genealogy/skills/genealogy-methodology/templates/source.md Normal file
View File

@@ -0,0 +1,45 @@
# Source Note Template
Use this template when creating a new source note in the Librarian notebook. Source notes contain ONLY source material — no analysis, no theory, no commentary.
---
## Citation
**Full Citation:** [Evidence Explained format — specific-to-general: item, source, repository]
**Access Method:** [Original / Digital image of original / Microfilm / Database transcription / Published abstract]
**Repository:** [Where the source is held — archive, website, courthouse]
**URL:** [If online — include access date]
**Collection ID:** [FamilySearch film number, Ancestry collection ID, book/volume, etc.]
## Persons
| Name | Role/Relationship | Details |
|------|------------------|---------|
| [Name as written] | [Testator/witness/grantee/head of household/etc.] | [Age, occupation, mark vs. signature, other details from document] |
## Transcription
[Full or partial transcription of the document. Preserve original spelling, punctuation, and line breaks where practical. Use [sic] sparingly — only where ambiguity exists. Use [illegible] or [torn] for unreadable portions.]
## Discrepancies
[Note ONLY factual discrepancies within the document itself — e.g., name spelled two different ways, date inconsistency between heading and body. Do NOT include analysis of how this document relates to other sources.]
## Coverage
**Date Range Covered:** [For collections — what range was examined in this pass]
**Pages/Images Examined:** [e.g., Images 12-48, Pages 100-150]
**Previous Coverage:** [Link to prior examination if this collection was searched before]
---
**This note has no Open Questions or Tasks sections.** Questions and tasks arising from this source belong on the relevant person notes, not here.
**No tags on source notes.** Do not use `[fact]`, `[claim]`, `[question]`, `[todo]`, or `[insight]` tags. Source notes contain only source material. Analysis, insights, questions, and theories belong on person notes (with citations back to this source). Both come back in searches, so nothing is lost.