playbook/outfitter-agents/plugins/outfitter/templates

Claude Code Templates

Copy-paste ready templates for all Claude Code component types. These templates follow best practices from the Claude Code Documentation.

Directory Structure

templates/
├── slash-commands/     # Custom command templates
├── hooks/              # Event hook templates
├── skills/             # Agent skill templates
├── agents/             # Specialized agent templates
└── README.md           # This file

Quick Start

Using Templates

1. Choose a template that matches your needs
2. Copy to appropriate location:
   • Slash commands: .claude/commands/ or ~/.claude/commands/
   • Hooks: .claude/hooks/ (scripts) + .claude/settings.json (config)
   • Skills: .claude/skills/ or ~/.claude/skills/
   • Agents: .claude/agents/ or ~/.claude/agents/
3. Replace placeholders (search for [YOUR_*])
4. Test and iterate

Example: Create a Slash Command

# 1. Copy template
cp templates/slash-commands/simple.md .claude/commands/review.md

# 2. Edit the file, replace placeholders:
#    [YOUR_DESCRIPTION] → "Review code for best practices"
#    [YOUR_COMMAND_NAME] → "Code Review"
#    [YOUR_PROMPT_INSTRUCTIONS] → Your instructions

# 3. Test it
claude
/review

Templates Overview

Slash Commands

Located in slash-commands/:

Template	Use Case	Features
simple.md	Basic command with no args	Simple prompt template
with-args.md	Command with arguments	$1, $2, $ARGUMENTS
with-bash.md	Command executing bash	! prefix for bash execution
with-files.md	Command reading files	@ prefix for file references

Quick reference:

• Arguments: $1, $2, $ARGUMENTS
• Bash execution: !git status``
• File references: @src/file.ts
• Frontmatter: description, argument-hint, allowed-tools

Hooks

Located in hooks/:

Template	Hook Type	Use Case
post-tool-use-formatter/	PostToolUse	Auto-format files after Write/Edit
pre-tool-use-validator/	PreToolUse	Validate operations before execution
user-prompt-context/	UserPromptSubmit	Add context to every prompt
bash-validator/	PreToolUse	Validate bash commands (Bun/TypeScript)

Each hook template includes:

• hooks.json - Configuration with matchers
• Script file - Working implementation (Bash or TypeScript)
• Security best practices built-in
• Error handling patterns

Installing a hook:

# 1. Copy script to project
cp -r templates/hooks/post-tool-use-formatter/ .claude/hooks/

# 2. Add configuration to .claude/settings.json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit(*.ts)",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/format.sh",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

# 3. Make script executable
chmod +x .claude/hooks/format.sh

Skills

Located in skills/:

Template	Complexity	Use Case
simple-skill/	Simple	Single-file skill
multi-file-skill/	Complex	Skill with reference docs
skill-with-scripts/	Advanced	Skill using helper scripts

Skill template features:

• Complete SKILL.md with frontmatter
• Best practices for descriptions
• Tool restrictions examples
• Progressive disclosure patterns
• Helper scripts (for advanced template)

Creating a skill:

# 1. Choose template
cp -r templates/skills/simple-skill/ .claude/skills/my-skill/

# 2. Rename template and edit
mv .claude/skills/my-skill/SKILL.template.md .claude/skills/my-skill/SKILL.md
# Replace all [YOUR_*] placeholders
# Update name and description (critical for discovery!)

# 3. Test
claude
# Skill will activate when description keywords are mentioned

Agents

Located in agents/:

Template	Specialization	Use Case
code-reviewer.md	Code review	Security, performance, quality analysis
test-specialist.md	Testing	TDD, test writing, coverage analysis
documentation-generator.md	Documentation	API docs, guides, architecture docs

Agent template features:

• Complete role definition
• Detailed process workflows
• Best practices and patterns
• Output format guidelines
• Tool restrictions

Using an agent template:

# 1. Copy to project
cp templates/agents/code-reviewer.md .claude/agents/

# 2. Customize if needed
# Agents work out of the box, but you can adjust to your needs

# 3. Claude will use agents automatically when appropriate

Template Customization Guide

Common Placeholders

Replace these in all templates:

• [YOUR_DESCRIPTION] - Brief description of functionality
• [YOUR_COMMAND_NAME] - Name of the command/skill/agent
• [YOUR_PROMPT_INSTRUCTIONS] - Core instructions
• [YOUR_ARG_HINT] - Hint for arguments (e.g., <file-path>)
• [YOUR_ALLOWED_TOOLS] - Tool restrictions (e.g., Read, Grep, Glob)
• [YOUR_SKILL_NAME] - Name for skills
• [CORE_CAPABILITY] - What the skill/agent does
• [language] - Programming language for examples
• [CODE_EXAMPLE] - Working code example

Frontmatter Fields

Slash Commands

---
description: Brief description (shown in /help)
argument-hint: <arg1> [optional-arg2]
allowed-tools: Bash(git *), Read, Write
model: claude-3-5-haiku-20241022  # Optional: specific model
disable-model-invocation: false    # Optional: prevent SlashCommand tool
---

Skills

---
name: skill-name
description: What the skill does and when to use it. Include trigger keywords.
allowed-tools: Read, Grep, Glob  # Optional: restrict tools
version: 1.0.0                    # Optional: version tracking
---

Agents

---
description: What this agent specializes in
capabilities:
  - Capability 1
  - Capability 2
allowed-tools: Read, Write, Edit  # Optional: restrict tools
---

Best Practices for Customization

1. Write Specific Descriptions

# ❌ Too vague
description: Helps with files

# ✅ Specific with triggers
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when users mention PDFs, forms, or document extraction.

2. Include Working Examples

Always provide code examples that:

• Actually work (test them!)
• Are realistic (not just foo/bar)
• Include comments explaining non-obvious parts
• Show common use cases

3. Follow the AAA Pattern for Examples

// Arrange: Setup
const items = [{ price: 10 }, { price: 20 }];

// Act: Execute
const result = calculateTotal(items);

// Assert: Verify
expect(result).toBe(30);

4. Security in Hooks

Always include:

set -euo pipefail  # Fail on errors, undefined vars, pipe failures

# Quote variables
rm "$FILE_PATH"  # ✅ Safe
rm $FILE_PATH    # ❌ Unsafe

# Validate inputs
if echo "$FILE_PATH" | grep -q '\.\.'; then
  echo "Path traversal detected" >&2
  exit 2
fi

Testing Your Components

Testing Slash Commands

# 1. Create command
cp templates/slash-commands/simple.md .claude/commands/test.md

# 2. Edit and customize
# ...

# 3. Test in Claude
claude
/help                    # Verify it's listed
/test                    # Run the command
# Ctrl+R for transcript mode to see detailed execution

Testing Hooks

# 1. Install hook
cp -r templates/hooks/post-tool-use-formatter/ .claude/hooks/
chmod +x .claude/hooks/format.sh

# 2. Add to settings.json
# ...

# 3. Test manually first
echo '{"tool_name":"Write","tool_input":{"file_path":"test.ts"}}' | .claude/hooks/format.sh

# 4. Test with Claude
claude
# Write a .ts file and watch hook execute

Testing Skills

# 1. Create skill
cp -r templates/skills/simple-skill/ .claude/skills/my-test-skill/

# 2. Rename and customize
mv .claude/skills/my-test-skill/SKILL.template.md .claude/skills/my-test-skill/SKILL.md
# Focus on a SPECIFIC, CLEAR description with trigger keywords

# 3. Test discovery
claude --debug  # Check skill loading logs

# 4. Test activation
claude
# Use trigger keywords from description in your prompt

Common Patterns

Pattern 1: Command with Git Context

---
description: Review recent changes
allowed-tools: Bash(git *), Read
---

# Recent Changes Review

## Context
Recent commits: !`git log --oneline -5`
Uncommitted changes: !`git diff`
Current branch: !`git branch --show-current`

## Task
Review the changes above and summarize:
1. What changed
2. Potential issues
3. Suggested improvements

Pattern 2: Validation Hook

#!/usr/bin/env bash
set -euo pipefail

INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

# Validate
if [[ -z "$FILE_PATH" ]]; then
  echo "Error: No file path" >&2
  exit 2  # Block and show to Claude
fi

# Check path traversal
if echo "$FILE_PATH" | grep -q '\.\.'; then
  echo "❌ Path traversal blocked" >&2
  exit 2
fi

echo "✓ Validation passed"
exit 0

Pattern 3: Multi-File Skill

my-skill/
├── SKILL.md         # Essential info + quick start
├── REFERENCE.md     # Complete API documentation
├── EXAMPLES.md      # Real-world use cases
└── scripts/
    └── helper.sh    # Helper utilities

In SKILL.md:

## Quick Start
[Essential info here]

## Advanced Usage
See [REFERENCE.md](REFERENCE.md) for complete API documentation.
See [EXAMPLES.md](EXAMPLES.md) for real-world examples.

Troubleshooting

Command Not Found

Problem: /my-command not recognized

Solutions:

1. Check file location: .claude/commands/my-command.md
2. Check filename: lowercase, no spaces, .md extension
3. Restart Claude Code

Hook Not Firing

Problem: Hook doesn't execute

Solutions:

1. Verify matcher syntax in settings.json
2. Check script is executable: chmod +x script.sh
3. Test script manually with sample input
4. Enable debug mode: claude --debug

Skill Not Activating

Problem: Skill doesn't trigger when expected

Solutions:

1. Check description is specific with trigger keywords
2. Verify YAML frontmatter syntax (no tabs!)
3. Enable debug mode: claude --debug
4. Test by explicitly mentioning trigger keywords

Script Permission Errors

Problem: Permission denied when running scripts

Solutions:

# Make executable
chmod +x .claude/hooks/*.sh

# Check permissions
ls -la .claude/hooks/

# Verify shebang
head -1 script.sh  # Should be #!/usr/bin/env bash

Advanced Customization

Combining Templates

You can combine patterns from multiple templates:

---
description: Deploy with validation
argument-hint: <environment>
allowed-tools: Bash(git *), Bash(docker *), Read
---

# Deploy Command

## Context
Git status: !`git status`
Docker images: !`docker images | head -5`

## Validation
Current environment: $1
Config file: @.env.$1

## Task
Deploy to $1 environment with:
1. Run tests
2. Build Docker image
3. Deploy to cluster
4. Verify health checks

Creating Skill Suites

Organize related skills:

.claude/skills/
├── pdf-processing/
│   └── SKILL.md
├── excel-analysis/
│   └── SKILL.md
└── document-conversion/
    └── SKILL.md

Hook Chains

Combine multiple hooks:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "./.claude/hooks/validate.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit(*.ts)",
        "hooks": [
          {
            "type": "command",
            "command": "./.claude/hooks/format.sh"
          },
          {
            "type": "command",
            "command": "./.claude/hooks/lint.sh"
          }
        ]
      }
    ]
  }
}

Resources

• Official Docs: Claude Code Documentation
• Skills Reference: Agent Skills Overview
• Authoring Skills: See claude-* skills in outfitter for detailed guidance

Contributing

Found an issue or want to improve a template?

1. Test your changes thoroughly
2. Ensure all placeholders are clearly marked
3. Include working examples
4. Update this README if adding new templates

License

These templates are provided as-is for use with Claude Code.

---

Last Updated: 2025-10-20 Template Version: 1.0.0 Compatible with: Claude Code 1.0+