Initial commit: Fresh start with current state
This commit is contained in:
Claude Code
581
.claude/TEMPLATES_README.md
Normal file
581
.claude/TEMPLATES_README.md
Normal file
@@ -0,0 +1,581 @@
|
||||
# Claude Code Templates Collection
|
||||
|
||||
> **Complete blueprint library for Claude Code configuration**
|
||||
>
|
||||
> **Version**: 1.0.0 | **Last Updated**: 2025-10-17
|
||||
|
||||
This directory contains comprehensive, harmonized templates for all major Claude Code configuration types. Each template follows best practices and provides detailed guidance for creating production-ready configurations.
|
||||
|
||||
---
|
||||
|
||||
## 📚 Available Templates
|
||||
|
||||
### 1. [SKILL_TEMPLATE.md](skills/SKILL_TEMPLATE.md)
|
||||
**Type**: Agent Skills (Model-Invoked)
|
||||
**Location**: `.claude/skills/[skill-name]/SKILL.md`
|
||||
|
||||
**What it's for:**
|
||||
- Creating autonomous capabilities that Claude discovers and uses automatically
|
||||
- Packaging domain expertise that activates based on context
|
||||
- Extending Claude's functionality for specific workflows
|
||||
|
||||
**When to use:**
|
||||
- You want Claude to automatically help with specific tasks
|
||||
- You have specialized knowledge to package
|
||||
- The capability should activate based on user's question/context
|
||||
|
||||
**Key features:**
|
||||
- YAML frontmatter with `allowed-tools` for permission control
|
||||
- Progressive disclosure pattern for multi-file skills
|
||||
- Comprehensive testing checklist
|
||||
- Version history tracking
|
||||
|
||||
**Example use cases:**
|
||||
- PDF processing skill
|
||||
- Excel data analysis skill
|
||||
- Code review skill
|
||||
- Documentation generation skill
|
||||
|
||||
---
|
||||
|
||||
### 2. [COMMANDS_TEMPLATE.md](commands/COMMANDS_TEMPLATE.md)
|
||||
**Type**: Slash Commands (User-Invoked)
|
||||
**Location**: `.claude/commands/[command-name].md`
|
||||
|
||||
**What it's for:**
|
||||
- Creating explicit commands users trigger with `/command-name`
|
||||
- Defining repeatable workflows and routines
|
||||
- Building project-specific utilities
|
||||
|
||||
**When to use:**
|
||||
- You want predictable, on-demand behavior
|
||||
- The action should be explicitly triggered
|
||||
- You're building a specific workflow or routine
|
||||
|
||||
**Key features:**
|
||||
- Argument handling (`$ARGUMENTS`, `$1`, `$2`, etc.)
|
||||
- Bash execution with `!` prefix
|
||||
- File references with `@` prefix
|
||||
- Model selection per command
|
||||
- Conditional logic support
|
||||
|
||||
**Example use cases:**
|
||||
- `/review-pr` - Review pull request
|
||||
- `/generate-tests` - Generate unit tests
|
||||
- `/commit` - Create git commit with message
|
||||
- `/deploy` - Deployment workflow
|
||||
|
||||
---
|
||||
|
||||
### 3. [AGENT_TEMPLATE.md](agents/AGENT_TEMPLATE.md)
|
||||
**Type**: Specialized Agents/Subagents
|
||||
**Location**: `.claude/agents/[agent-name].md`
|
||||
|
||||
**What it's for:**
|
||||
- Creating specialized AI assistants for specific domains
|
||||
- Delegating complex tasks to focused agents
|
||||
- Building multi-agent workflows
|
||||
|
||||
**When to use:**
|
||||
- You need specialized expertise for a domain
|
||||
- Tasks benefit from isolated context windows
|
||||
- You want to parallelize independent work
|
||||
|
||||
**Key features:**
|
||||
- YAML frontmatter with `tools` and `model` configuration
|
||||
- Standard operating procedures
|
||||
- Context management guidelines
|
||||
- Integration patterns with other agents
|
||||
- Performance optimization tips
|
||||
|
||||
**Example use cases:**
|
||||
- Research agent (deep codebase exploration)
|
||||
- Implementation agent (writing code)
|
||||
- Testing agent (verification)
|
||||
- Review agent (quality checks)
|
||||
|
||||
---
|
||||
|
||||
### 4. [CLAUDE_TEMPLATE.md](../CLAUDE_TEMPLATE.md)
|
||||
**Type**: Project Instructions
|
||||
**Location**: `CLAUDE.md` (project root)
|
||||
|
||||
**What it's for:**
|
||||
- Documenting project conventions and standards
|
||||
- Providing context about technology stack
|
||||
- Defining development workflows
|
||||
- Establishing code style guidelines
|
||||
|
||||
**When to use:**
|
||||
- Starting a new project
|
||||
- Onboarding Claude to existing project
|
||||
- Standardizing team practices
|
||||
- Documenting project architecture
|
||||
|
||||
**Key features:**
|
||||
- Comprehensive project overview
|
||||
- Detailed code style guide with examples
|
||||
- Testing requirements and strategies
|
||||
- Git workflow and commit conventions
|
||||
- Development environment setup
|
||||
- API and database documentation
|
||||
|
||||
**Example sections:**
|
||||
- Technology stack
|
||||
- Project structure
|
||||
- Code style & standards
|
||||
- Testing requirements
|
||||
- Git workflow
|
||||
- Deployment process
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Template Comparison
|
||||
|
||||
| Feature | Skill | Command | Agent | CLAUDE.md |
|
||||
|---------|-------|---------|-------|-----------|
|
||||
| **Invocation** | Auto (model) | Manual (user) | Both | N/A (reference) |
|
||||
| **Scope** | Focused capability | Single workflow | Domain expertise | Project-wide |
|
||||
| **Arguments** | No | Yes | Yes (input) | N/A |
|
||||
| **Tool Control** | `allowed-tools` | `allowed-tools` | `tools` | N/A |
|
||||
| **Multi-file** | Yes | No | Yes | N/A |
|
||||
| **Model Selection** | No | Yes | Yes | N/A |
|
||||
| **Version Control** | Recommended | Recommended | Recommended | Required |
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Quick Start Guide
|
||||
|
||||
### Creating a New Skill
|
||||
|
||||
```bash
|
||||
# 1. Create skill directory
|
||||
mkdir -p .claude/skills/my-skill
|
||||
|
||||
# 2. Copy template
|
||||
cp .claude/skills/SKILL_TEMPLATE.md .claude/skills/my-skill/SKILL.md
|
||||
|
||||
# 3. Edit the template
|
||||
# - Fill in name and description (frontmatter)
|
||||
# - Write clear instructions
|
||||
# - Add examples
|
||||
# - Define when to use
|
||||
|
||||
# 4. Test it
|
||||
# Start Claude and ask questions that match your description
|
||||
```
|
||||
|
||||
### Creating a New Command
|
||||
|
||||
```bash
|
||||
# 1. Copy template
|
||||
cp .claude/commands/COMMANDS_TEMPLATE.md .claude/commands/my-command.md
|
||||
|
||||
# 2. Edit the template
|
||||
# - Add description (frontmatter)
|
||||
# - Define argument handling
|
||||
# - Write instructions
|
||||
# - Add examples
|
||||
|
||||
# 3. Test it
|
||||
claude
|
||||
> /my-command arg1 arg2
|
||||
```
|
||||
|
||||
### Creating a New Agent
|
||||
|
||||
```bash
|
||||
# 1. Copy template
|
||||
cp .claude/agents/AGENT_TEMPLATE.md .claude/agents/my-agent.md
|
||||
|
||||
# 2. Edit the template
|
||||
# - Fill in name, description, tools (frontmatter)
|
||||
# - Define agent role and responsibilities
|
||||
# - Write workflows
|
||||
# - Add domain knowledge
|
||||
|
||||
# 3. Test it
|
||||
# Use Task tool to invoke: "Please use the my-agent agent to..."
|
||||
```
|
||||
|
||||
### Setting Up New Project
|
||||
|
||||
```bash
|
||||
# 1. Copy template to project root
|
||||
cp .claude/CLAUDE_TEMPLATE.md ./CLAUDE.md
|
||||
|
||||
# 2. Fill in project details
|
||||
# - Project overview
|
||||
# - Technology stack
|
||||
# - Code style guidelines
|
||||
# - Development workflows
|
||||
|
||||
# 3. Keep it updated as project evolves
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📖 Best Practices
|
||||
|
||||
### General Guidelines
|
||||
|
||||
1. **Keep it focused**: Each template should do one thing well
|
||||
2. **Be specific**: Use concrete examples and clear descriptions
|
||||
3. **Test thoroughly**: Verify with real usage before deploying
|
||||
4. **Version track**: Document changes over time
|
||||
5. **Share knowledge**: Commit to git for team access
|
||||
|
||||
### Writing Effective Descriptions
|
||||
|
||||
**Good descriptions:**
|
||||
- Include trigger words and scenarios
|
||||
- Specify file types and operations
|
||||
- Explain both WHAT and WHEN
|
||||
- Use concrete, specific language
|
||||
|
||||
**Poor descriptions:**
|
||||
- Vague or generic terms
|
||||
- No context about when to use
|
||||
- Missing key terminology
|
||||
- Too broad or too narrow
|
||||
|
||||
**Example comparison:**
|
||||
|
||||
❌ **Poor**: "Helps with documents"
|
||||
|
||||
✅ **Good**: "Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when user mentions PDFs, forms, or document extraction."
|
||||
|
||||
### Tool Permission Strategy
|
||||
|
||||
**Read-only configurations:**
|
||||
```yaml
|
||||
allowed-tools: Read, Grep, Glob
|
||||
```
|
||||
Best for: Research, analysis, review tasks
|
||||
|
||||
**File operations:**
|
||||
```yaml
|
||||
allowed-tools: Read, Write, Edit, Grep, Glob
|
||||
```
|
||||
Best for: Implementation, code generation
|
||||
|
||||
**Full development:**
|
||||
```yaml
|
||||
allowed-tools: Read, Write, Edit, Grep, Glob, Bash(*)
|
||||
```
|
||||
Best for: Complete workflows, testing, deployment
|
||||
|
||||
**Git operations:**
|
||||
```yaml
|
||||
allowed-tools: Bash(git status:*), Bash(git diff:*), Bash(git log:*)
|
||||
```
|
||||
Best for: Version control workflows
|
||||
|
||||
### Organizing Multi-File Configurations
|
||||
|
||||
**Skills with supporting files:**
|
||||
```
|
||||
skill-name/
|
||||
├── SKILL.md # Main skill file
|
||||
├── reference.md # Detailed docs
|
||||
├── examples.md # Usage examples
|
||||
└── scripts/
|
||||
└── helper.py # Utility scripts
|
||||
```
|
||||
|
||||
**Commands with subdirectories:**
|
||||
```
|
||||
.claude/commands/
|
||||
├── git/
|
||||
│ ├── commit.md
|
||||
│ ├── review-pr.md
|
||||
│ └── sync.md
|
||||
└── testing/
|
||||
├── run-tests.md
|
||||
└── generate-tests.md
|
||||
```
|
||||
|
||||
Usage: `/git/commit`, `/testing/run-tests`
|
||||
|
||||
---
|
||||
|
||||
## 🔄 When to Use What
|
||||
|
||||
### Decision Tree
|
||||
|
||||
```
|
||||
Is it general project knowledge?
|
||||
└─ Yes → Use CLAUDE.md
|
||||
└─ No ↓
|
||||
|
||||
Does user explicitly trigger it?
|
||||
└─ Yes → Use Command (/slash-command)
|
||||
└─ No ↓
|
||||
|
||||
Is it a complete domain/workflow?
|
||||
└─ Yes → Use Agent (subagent)
|
||||
└─ No ↓
|
||||
|
||||
Is it a specific capability?
|
||||
└─ Yes → Use Skill (auto-invoked)
|
||||
```
|
||||
|
||||
### Common Scenarios
|
||||
|
||||
| Scenario | Best Template | Rationale |
|
||||
|----------|---------------|-----------|
|
||||
| Project coding standards | CLAUDE.md | Project-wide reference |
|
||||
| Generate commit message | Command | Explicit user action |
|
||||
| Analyze PDF documents | Skill | Auto-activate on context |
|
||||
| Deep codebase research | Agent | Specialized, focused task |
|
||||
| Team Git workflow | CLAUDE.md | Project-wide convention |
|
||||
| Run test suite | Command | Explicit action |
|
||||
| Excel data analysis | Skill | Auto-activate capability |
|
||||
| Code review process | Agent | Complex, multi-step |
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ Template Features Matrix
|
||||
|
||||
### Common Features Across All Templates
|
||||
|
||||
- ✅ Clear structure and organization
|
||||
- ✅ Best practices guidance
|
||||
- ✅ Concrete examples
|
||||
- ✅ Error handling patterns
|
||||
- ✅ Testing considerations
|
||||
- ✅ Version history
|
||||
- ✅ Quick reference sections
|
||||
|
||||
### Unique Features by Template
|
||||
|
||||
**SKILL_TEMPLATE.md**
|
||||
- Progressive disclosure pattern
|
||||
- `allowed-tools` frontmatter
|
||||
- Multi-file organization
|
||||
- Discovery optimization
|
||||
- Testing checklist
|
||||
|
||||
**COMMANDS_TEMPLATE.md**
|
||||
- Argument handling ($ARGUMENTS, $1, $2...)
|
||||
- Bash execution (! prefix)
|
||||
- File references (@ prefix)
|
||||
- Model selection
|
||||
- Conditional logic
|
||||
|
||||
**AGENT_TEMPLATE.md**
|
||||
- System prompt guidelines
|
||||
- Tool configuration
|
||||
- Workflow definitions
|
||||
- Context management
|
||||
- Performance metrics
|
||||
- Agent integration patterns
|
||||
|
||||
**CLAUDE_TEMPLATE.md**
|
||||
- Technology stack documentation
|
||||
- Code style guide
|
||||
- Testing strategy
|
||||
- Git workflow
|
||||
- Deployment process
|
||||
- Team conventions
|
||||
|
||||
---
|
||||
|
||||
## 📋 Template Checklist
|
||||
|
||||
### Before Creating From Template
|
||||
|
||||
- [ ] Understand the use case clearly
|
||||
- [ ] Choose the right template type
|
||||
- [ ] Review similar existing configurations
|
||||
- [ ] Plan tool permissions needed
|
||||
- [ ] Consider integration with other configs
|
||||
|
||||
### While Filling Template
|
||||
|
||||
- [ ] Remove placeholder text
|
||||
- [ ] Fill in all required sections
|
||||
- [ ] Add concrete, project-specific examples
|
||||
- [ ] Write clear, specific descriptions
|
||||
- [ ] Define tool permissions appropriately
|
||||
- [ ] Add relevant error handling
|
||||
- [ ] Include testing scenarios
|
||||
|
||||
### After Creating
|
||||
|
||||
- [ ] Test with real usage
|
||||
- [ ] Verify tool permissions work
|
||||
- [ ] Check examples are accurate
|
||||
- [ ] Get feedback from team
|
||||
- [ ] Document in project README
|
||||
- [ ] Commit to version control
|
||||
|
||||
---
|
||||
|
||||
## 🔍 Troubleshooting
|
||||
|
||||
### Skill Not Activating
|
||||
|
||||
**Problem**: Claude doesn't use your skill when expected
|
||||
|
||||
**Solutions:**
|
||||
1. Make description more specific with trigger words
|
||||
2. Include file types and operations in description
|
||||
3. Add "Use when..." clause with scenarios
|
||||
4. Test description matches actual user questions
|
||||
5. Check YAML frontmatter is valid
|
||||
|
||||
### Command Not Found
|
||||
|
||||
**Problem**: `/command-name` not recognized
|
||||
|
||||
**Solutions:**
|
||||
1. Verify file is in `.claude/commands/` directory
|
||||
2. Check filename matches command (without .md)
|
||||
3. Restart Claude Code to reload commands
|
||||
4. Check for syntax errors in frontmatter
|
||||
5. Use `/help` to list available commands
|
||||
|
||||
### Agent Not Using Tools
|
||||
|
||||
**Problem**: Agent asks for permission for allowed tools
|
||||
|
||||
**Solutions:**
|
||||
1. Check `tools` field in frontmatter is correct
|
||||
2. Verify tool names match exactly (case-sensitive)
|
||||
3. Use wildcard patterns correctly (e.g., `Bash(git *:*)`)
|
||||
4. Restart Claude to reload agent configuration
|
||||
5. Check settings.json doesn't override permissions
|
||||
|
||||
### CLAUDE.md Too Long
|
||||
|
||||
**Problem**: Project instructions file is overwhelming
|
||||
|
||||
**Solutions:**
|
||||
1. Focus on most critical information
|
||||
2. Link to external docs for details
|
||||
3. Use concise bullet points
|
||||
4. Remove redundant sections
|
||||
5. Consider splitting into multiple files
|
||||
|
||||
---
|
||||
|
||||
## 💡 Pro Tips
|
||||
|
||||
### Skill Development
|
||||
- Start with simple, focused skills
|
||||
- Test with various phrasings
|
||||
- Iterate based on real usage
|
||||
- Keep description trigger-rich
|
||||
- Use progressive disclosure
|
||||
|
||||
### Command Creation
|
||||
- Use descriptive verb-noun names
|
||||
- Provide argument hints
|
||||
- Handle errors gracefully
|
||||
- Include usage examples
|
||||
- Test edge cases
|
||||
|
||||
### Agent Design
|
||||
- Define clear boundaries
|
||||
- Limit tool access appropriately
|
||||
- Document workflows explicitly
|
||||
- Plan for delegation
|
||||
- Optimize for performance
|
||||
|
||||
### Project Documentation
|
||||
- Keep CLAUDE.md current
|
||||
- Update with major changes
|
||||
- Include examples liberally
|
||||
- Reference from other configs
|
||||
- Make it scannable
|
||||
|
||||
---
|
||||
|
||||
## 🤝 Contributing
|
||||
|
||||
### Improving Templates
|
||||
|
||||
Found a better pattern? Have suggestions?
|
||||
|
||||
1. Test your improvement thoroughly
|
||||
2. Document the change clearly
|
||||
3. Update examples if needed
|
||||
4. Maintain backward compatibility
|
||||
5. Share with the team
|
||||
|
||||
### Template Versioning
|
||||
|
||||
When updating templates:
|
||||
- Update version number in template
|
||||
- Document changes in version history
|
||||
- Notify team of breaking changes
|
||||
- Provide migration guide if needed
|
||||
|
||||
---
|
||||
|
||||
## 📚 Additional Resources
|
||||
|
||||
### Official Documentation
|
||||
- [Claude Code Docs](https://docs.claude.com/en/docs/claude-code/)
|
||||
- [Agent Skills Overview](https://docs.claude.com/en/docs/claude-code/skills)
|
||||
- [Slash Commands Guide](https://docs.claude.com/en/docs/claude-code/slash-commands)
|
||||
- [Subagents Documentation](https://docs.claude.com/en/docs/claude-code/subagents)
|
||||
|
||||
### Example Projects
|
||||
- [Anthropic Skills Repository](https://github.com/anthropics/skills)
|
||||
- [Claude Code Examples](https://github.com/anthropics/claude-code/tree/main/examples)
|
||||
|
||||
### Community
|
||||
- [GitHub Issues](https://github.com/anthropics/claude-code/issues)
|
||||
- [Discord Community](https://discord.gg/anthropic)
|
||||
|
||||
---
|
||||
|
||||
## 📄 Template Index
|
||||
|
||||
Quick reference for finding templates:
|
||||
|
||||
| Template | File | Purpose |
|
||||
|----------|------|---------|
|
||||
| Skill | [.claude/skills/SKILL_TEMPLATE.md](skills/SKILL_TEMPLATE.md) | Auto-invoked capabilities |
|
||||
| Command | [.claude/commands/COMMANDS_TEMPLATE.md](commands/COMMANDS_TEMPLATE.md) | User-triggered workflows |
|
||||
| Agent | [.claude/agents/AGENT_TEMPLATE.md](agents/AGENT_TEMPLATE.md) | Specialized subagents |
|
||||
| Project | [CLAUDE_TEMPLATE.md](../CLAUDE_TEMPLATE.md) | Project instructions |
|
||||
|
||||
---
|
||||
|
||||
## 🎓 Learning Path
|
||||
|
||||
**Beginner:**
|
||||
1. Start with CLAUDE.md for project
|
||||
2. Create 1-2 simple commands
|
||||
3. Understand tool permissions
|
||||
|
||||
**Intermediate:**
|
||||
4. Create focused skills
|
||||
5. Build custom agents
|
||||
6. Combine multiple configs
|
||||
|
||||
**Advanced:**
|
||||
7. Multi-agent workflows
|
||||
8. Complex skill architectures
|
||||
9. Template customization
|
||||
|
||||
---
|
||||
|
||||
**Template Collection Version**: 1.0.0
|
||||
**Last Updated**: 2025-10-17
|
||||
**Maintained by**: [Your Team/Name]
|
||||
|
||||
---
|
||||
|
||||
## 🙏 Acknowledgments
|
||||
|
||||
These templates are based on:
|
||||
- Official Anthropic documentation
|
||||
- Claude Agent SDK best practices
|
||||
- Community feedback and usage patterns
|
||||
- Real-world production experience
|
||||
|
||||
**Note**: These templates are designed to work together as a harmonized system. Each follows consistent patterns while respecting the unique requirements of its configuration type.
|
||||
Reference in New Issue
Block a user