📦 deps(thirdparty): update snapshots

2026-05-29 08:33:53 +00:00
parent fdb52f1e96
commit 06e0d13d57
1615 changed files with 232858 additions and 0 deletions
@@ -0,0 +1,553 @@
+# Claude Code Templates
+
+Copy-paste ready templates for all Claude Code component types. These templates follow best practices from the [Claude Code Documentation](https://docs.claude.com/en/docs/claude-code/overview).
+
+## 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
+
+```bash
+# 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**:
+
+```bash
+# 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**:
+
+```bash
+# 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**:
+
+```bash
+# 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
+
+```yaml
+---
+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
+
+```yaml
+---
+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
+
+```yaml
+---
+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
+
+```yaml
+# ❌ 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
+
+```typescript
+// 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:
+
+```bash
+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
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# 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
+
+```markdown
+---
+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
+
+```bash
+#!/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`:
+
+```markdown
+## 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**:
+
+```bash
+# 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:
+
+```markdown
+---
+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:
+
+```json
+{
+  "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](https://docs.claude.com/en/docs/claude-code/overview)
+- **Skills Reference**: [Agent Skills Overview](https://docs.anthropic.com/en/docs/agents-and-tools/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+