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

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

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

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

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

# 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

# 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

# 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

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

allowed-tools: Read, Grep, Glob

Best for: Research, analysis, review tasks

File operations:

allowed-tools: Read, Write, Edit, Grep, Glob

Best for: Implementation, code generation

Full development:

allowed-tools: Read, Write, Edit, Grep, Glob, Bash(*)

Best for: Complete workflows, testing, deployment

Git operations:

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
• Agent Skills Overview
• Slash Commands Guide
• Subagents Documentation

Example Projects

• Anthropic Skills Repository
• Claude Code Examples

Community

• GitHub Issues
• Discord Community

---

📄 Template Index

Quick reference for finding templates:

Template	File	Purpose
Skill	.claude/skills/SKILL_TEMPLATE.md	Auto-invoked capabilities
Command	.claude/commands/COMMANDS_TEMPLATE.md	User-triggered workflows
Agent	.claude/agents/AGENT_TEMPLATE.md	Specialized subagents
Project	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.