FoundryVTT/.claude/TEMPLATES_README.md

# 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.