zhongwei/gh-alexanderop-claude-code-builder
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-29 17:52:01 +08:00
commit 6d7255ec20
10 changed files with 1616 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

121
commands/create-agent.md Normal file
View File

@@ -0,0 +1,121 @@
---
description: Create a new custom subagent for specialized tasks
argument-hint: [name] [description]
---
# /create-agent
## Purpose
Create a new custom subagent (skill) for specialized tasks with proper configuration and system prompts.
## Contract
**Inputs:**
- `$1` — AGENT_NAME (lowercase, kebab-case, e.g., "code-reviewer")
- `$2` — DESCRIPTION (when this agent should be invoked, e.g., "Expert code reviewer. Use proactively after code changes.")
- `--user` — Create user-level agent in `~/.claude/agents/` (default: project-level in `.claude/agents/`)
- `--tools` — Comma-separated list of tools (e.g., "Read,Grep,Glob,Bash")
- `--model` — Model to use: "sonnet", "opus", "haiku", or "inherit" (default: sonnet)
**Outputs:**
- `STATUS=<CREATED|EXISTS|FAIL> PATH=<path> AGENT=<name>`
## Instructions
1. **Validate inputs:**
- Agent name must be lowercase, kebab-case only
- Description must be non-empty and descriptive
- If `--tools` specified, validate tool names against available tools
- If `--model` specified, validate it's one of: sonnet, opus, haiku, inherit
2. **Determine file location:**
- Default: `.claude/agents/{AGENT_NAME}.md` (project-level)
- With `--user`: `~/.claude/agents/{AGENT_NAME}.md` (user-level)
- Create directory if it doesn't exist
3. **Check for existing agent:**
- If file exists, output `STATUS=EXISTS` and exit
- Recommend using `/agents` command to edit existing agents
4. **Generate agent file content:**
```markdown
---
name: {AGENT_NAME}
description: {DESCRIPTION}
tools: {TOOLS} # Optional - only include if specified
model: {MODEL} # Optional - only include if specified
---
You are a specialized agent for {purpose based on description}.
When invoked:
1. Understand the specific task or problem
2. Analyze the relevant context
3. Execute your specialized function
4. Provide clear, actionable results
Key responsibilities:
- {Responsibility 1 based on description}
- {Responsibility 2 based on description}
- {Responsibility 3 based on description}
Best practices:
- Be focused and efficient
- Provide specific, actionable feedback
- Document your reasoning
- Follow established patterns and conventions
For each task:
- Explain your approach
- Show your work
- Highlight key findings or changes
- Suggest next steps if applicable
```
5. **Write the file:**
- Create the agent file with proper frontmatter
- Ensure proper formatting and indentation
- Set appropriate file permissions
6. **Output result:**
- Print: `STATUS=CREATED PATH={path} AGENT={name}`
- Provide usage example: `Use the {name} agent to...`
## Examples
### Basic project-level agent
```bash
/create-skill code-reviewer "Expert code review specialist. Use proactively after code changes."
# Output: STATUS=CREATED PATH=.claude/agents/code-reviewer.md AGENT=code-reviewer
```
### User-level agent with specific tools
```bash
/create-skill debugger "Debugging specialist for errors and test failures" --user --tools "Read,Edit,Bash,Grep,Glob"
# Output: STATUS=CREATED PATH=~/.claude/agents/debugger.md AGENT=debugger
```
### Agent with specific model
```bash
/create-skill data-scientist "Data analysis expert for SQL queries and insights" --tools "Bash,Read,Write" --model "sonnet"
# Output: STATUS=CREATED PATH=.claude/agents/data-scientist.md AGENT=data-scientist
```
## Constraints
- Idempotent: Won't overwrite existing agents
- No network access required
- Agent names must follow naming conventions
- Tools list must match available Claude Code tools
- Model must be valid alias or 'inherit'
## Best Practices
- Use descriptive, action-oriented descriptions
- Include "use PROACTIVELY" in description for automatic invocation
- Start with Claude-generated agents via `/agents` for complex cases
- Limit tools to only what the agent needs
- Design focused agents with single, clear responsibilities
- Add to version control for team collaboration
## Related Commands
- `/agents` - Interactive interface for managing agents (recommended for editing)
- Use created agents: "Use the {name} agent to..."
- Invoke explicitly: "Ask the {name} agent to investigate..."

75
commands/create-command.md Normal file
View File

@@ -0,0 +1,75 @@
---
description: Create new slash commands with standardized structure
argument-hint: [name] [purpose]
allowed-tools: Bash(mkdir:*), Bash(tee:*), Bash(test:*)
---
# /create-command
## Purpose
Generate properly structured slash command files for Claude Code.
## Contract
**Inputs:**
- `$1` — COMMAND_NAME (lowercase, kebab-case, verb-first)
- `$2` — PURPOSE (command description)
**Outputs:**
- `STATUS=<WROTE> PATH=<path>`
## Instructions
1. **Validate inputs:**
- Command name: lowercase, kebab-case only
- Purpose: non-empty string
2. **Generate file content** using this template:
```markdown
---
description: {{PURPOSE}}
argument-hint: [args...]
---
# /{{COMMAND_NAME}}
## Purpose
{{PURPOSE}}
## Contract
**Inputs:** `$ARGUMENTS` — command arguments
**Outputs:** `STATUS=<OK|FAIL> [key=value ...]`
## Instructions
1. **Validate inputs:**
- Check that required arguments are provided
- Validate argument format/values
2. **Execute the command:**
\`\`\`bash
# Add specific bash commands here
# Example: git worktree add path/to/worktree branch-name
\`\`\`
3. **Output status:**
- Print `STATUS=OK` on success
- Print `STATUS=FAIL ERROR="message"` on failure
## Constraints
- Idempotent and deterministic
- No network tools by default
- Minimal console output (STATUS line only)
```
3. **Output:**
- Show preview in fenced markdown block
- Create `.claude/commands/` dir and write file atomically
- Print: `STATUS=WROTE PATH=.claude/commands/{{COMMAND_NAME}}.md`
## Example
```bash
/create-command analyze-deps "Analyze dependencies for outdated packages"
# Output: STATUS=WROTE PATH=.claude/commands/analyze-deps.md
```

566
commands/create-hook.md Normal file
View File

@@ -0,0 +1,566 @@
---
description: Create and configure Claude Code hooks with reference documentation
argument-hint: [hook-type] [matcher] [command]
---
# /create-hook
## Purpose
Create and configure Claude Code hooks with reference documentation and interactive guidance.
## Contract
**Inputs:**
- `$1` — HOOK_TYPE (optional: PreToolUse, PostToolUse, UserPromptSubmit, Notification, Stop, SubagentStop, PreCompact, SessionStart, SessionEnd)
- `$2` — MATCHER (optional: tool name pattern, e.g., "Bash", "Edit|Write", "*")
- `$3` — COMMAND (optional: shell command to execute)
**Outputs:** `STATUS=<OK|FAIL> HOOK_FILE=<path>`
## Instructions
1. **Detect common use cases (hybrid approach):**
- Scan user's request for keywords: "eslint", "prettier", "format", "lint", "typescript", "test", "commit"
- If detected, ask: "I can set up a production-ready [TOOL] hook. Would you like to use the template or create a custom hook?"
- If template chosen: Generate external script file in `.claude/hooks/` + settings.json entry
- If custom or no match: Fall back to current workflow (steps 2-3)
2. **Determine hook configuration mode:**
- If no arguments provided: Show interactive menu of hook types with examples
- If HOOK_TYPE provided: Guide user through creating that specific hook
- If all arguments provided: Create hook directly
3. **Validate inputs:**
- HOOK_TYPE must be one of the valid hook events
- MATCHER should be a valid tool name or pattern
- COMMAND should be a valid shell command or path to external script
- For external scripts: Ensure `.claude/hooks/` directory exists
4. **Reference documentation:**
Review the Claude Code hooks documentation for best practices and examples:
**Hook Events:**
- `PreToolUse`: Runs before tool calls (can block them)
- `PostToolUse`: Runs after tool calls complete
- `UserPromptSubmit`: Runs when user submits a prompt
- `Notification`: Runs when Claude Code sends notifications
- `Stop`: Runs when Claude Code finishes responding
- `SubagentStop`: Runs when subagent tasks complete
- `PreCompact`: Runs before compact operations
- `SessionStart`: Runs when session starts/resumes
- `SessionEnd`: Runs when session ends
5. **Production-Ready Script Templates:**
When user requests common integrations, generate these external scripts in `.claude/hooks/`:
**ESLint Auto-Fix (`run-eslint.sh`):**
```bash
#!/usr/bin/env bash
# Auto-fix JavaScript/TypeScript files with ESLint after edits
set -euo pipefail
# Extract file path from Claude's JSON payload
file_path="$(jq -r '.tool_input.file_path // ""')"
# Only process JS/TS files
[[ "$file_path" =~ \.(js|jsx|ts|tsx)$ ]] || exit 0
# Auto-detect package manager (prefer project's lock file)
if command -v pnpm >/dev/null 2>&1 && [ -f "pnpm-lock.yaml" ]; then
PM="pnpm exec"
elif command -v yarn >/dev/null 2>&1 && [ -f "yarn.lock" ]; then
PM="yarn"
else
PM="npx"
fi
# Run ESLint with auto-fix from project root
cd "$CLAUDE_PROJECT_DIR" && $PM eslint --fix "$file_path"
```
**Prettier Format (`run-prettier.sh`):**
```bash
#!/usr/bin/env bash
# Format files with Prettier after edits
set -euo pipefail
file_path="$(jq -r '.tool_input.file_path // ""')"
# Skip non-formattable files
[[ "$file_path" =~ \.(js|jsx|ts|tsx|json|css|scss|md|html|yml|yaml)$ ]] || exit 0
# Auto-detect package manager
if command -v pnpm >/dev/null 2>&1 && [ -f "pnpm-lock.yaml" ]; then
PM="pnpm exec"
elif command -v yarn >/dev/null 2>&1 && [ -f "yarn.lock" ]; then
PM="yarn"
else
PM="npx"
fi
cd "$CLAUDE_PROJECT_DIR" && $PM prettier --write "$file_path"
```
**TypeScript Type Check (`run-typescript.sh`):**
```bash
#!/usr/bin/env bash
# Run TypeScript type checker on TS/TSX file edits
set -euo pipefail
file_path="$(jq -r '.tool_input.file_path // ""')"
# Only process TypeScript files
[[ "$file_path" =~ \.(ts|tsx)$ ]] || exit 0
# Auto-detect package manager
if command -v pnpm >/dev/null 2>&1 && [ -f "pnpm-lock.yaml" ]; then
PM="pnpm exec"
elif command -v yarn >/dev/null 2>&1 && [ -f "yarn.lock" ]; then
PM="yarn"
else
PM="npx"
fi
# Run tsc --noEmit to check types without emitting files
cd "$CLAUDE_PROJECT_DIR" && $PM tsc --noEmit --pretty
```
**Run Affected Tests (`run-tests.sh`):**
```bash
#!/usr/bin/env bash
# Run tests for modified files
set -euo pipefail
file_path="$(jq -r '.tool_input.file_path // ""')"
# Only run tests for source files (not test files themselves)
[[ "$file_path" =~ \.(test|spec)\.(js|ts|jsx|tsx)$ ]] && exit 0
[[ "$file_path" =~ \.(js|jsx|ts|tsx)$ ]] || exit 0
# Auto-detect test runner and package manager
if [ -f "vitest.config.ts" ] || [ -f "vitest.config.js" ]; then
TEST_CMD="vitest related --run"
elif [ -f "jest.config.js" ] || [ -f "jest.config.ts" ]; then
TEST_CMD="jest --findRelatedTests"
else
exit 0 # No test runner configured
fi
if command -v pnpm >/dev/null 2>&1 && [ -f "pnpm-lock.yaml" ]; then
PM="pnpm exec"
elif command -v yarn >/dev/null 2>&1 && [ -f "yarn.lock" ]; then
PM="yarn"
else
PM="npx"
fi
cd "$CLAUDE_PROJECT_DIR" && $PM $TEST_CMD "$file_path"
```
**Commit Message Validation (`validate-commit.sh`):**
```bash
#!/usr/bin/env bash
# Validate commit messages follow conventional commits format
set -euo pipefail
# Extract commit message from tool input
commit_msg="$(jq -r '.tool_input // ""')"
# Check for conventional commit format: type(scope): message
if ! echo "$commit_msg" | grep -qE '^(feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert)(\(.+\))?: .+'; then
echo "ERROR: Commit message must follow conventional commits format"
echo "Expected: type(scope): description"
echo "Got: $commit_msg"
exit 2 # Block the commit
fi
```
**Corresponding settings.json entries:**
```json
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"comment": "Auto-fix with ESLint",
"command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/run-eslint.sh"
}
]
}
]
}
}
```
6. **Best Practices for Hook Development:**
**Always use shell safety headers:**
```bash
#!/usr/bin/env bash
set -euo pipefail # Exit on error, undefined vars, pipe failures
```
**Extract data from Claude's JSON payload:**
```bash
# File path (Edit/Write tools)
file_path="$(jq -r '.tool_input.file_path // ""')"
# Command (Bash tool)
command="$(jq -r '.tool_input.command // ""')"
# Tool name
tool_name="$(jq -r '.tool_name // ""')"
# Full tool input
tool_input="$(jq -r '.tool_input' | jq -c .)"
```
**Use environment variables provided by Claude:**
```bash
$CLAUDE_PROJECT_DIR # Project root directory
$CLAUDE_USER_DIR # User's ~/.claude directory
$CLAUDE_SESSION_ID # Current session identifier
```
**Efficient file extension filtering:**
```bash
# Good: Use bash regex matching
[[ "$file_path" =~ \.(ts|tsx)$ ]] || exit 0
# Avoid: Spawning grep subprocess
echo "$file_path" | grep -q '\.ts$' || exit 0
```
**Package manager auto-detection pattern:**
```bash
# Check lock files to match project's package manager
if command -v pnpm >/dev/null 2>&1 && [ -f "pnpm-lock.yaml" ]; then
PM="pnpm exec"
elif command -v yarn >/dev/null 2>&1 && [ -f "yarn.lock" ]; then
PM="yarn"
else
PM="npx" # Fallback to npx
fi
```
**Exit codes matter:**
```bash
exit 0 # Success: Allow operation to continue
exit 1 # Error: Log error but don't block
exit 2 # Block: Prevent operation in PreToolUse hooks
```
**Performance considerations:**
- Avoid heavy operations in tight loops (e.g., don't run full test suite on every file edit)
- Use file extension checks to skip irrelevant files early
- Consider async/background execution for slow operations
- Cache results when possible (e.g., dependency checks)
**When to use external scripts vs inline commands:**
- **External scripts** (`.claude/hooks/*.sh`): Complex logic, multiple steps, reusable patterns
- **Inline commands**: Simple one-liners, quick jq filters, logging
Example inline command:
```json
"command": "jq -r '.tool_input.command' >> ~/.claude/command-log.txt"
```
7. **Common use cases and examples (updated with best practices):**
**Logging Bash commands:**
```json
{
"hooks": {
"PreToolUse": [{
"matcher": "Bash",
"hooks": [{
"type": "command",
"comment": "Log all Bash commands with descriptions",
"command": "set -euo pipefail; cmd=$(jq -r '.tool_input.command // \"\"'); desc=$(jq -r '.tool_input.description // \"No description\"'); echo \"[$(date -u +%Y-%m-%dT%H:%M:%SZ)] $cmd - $desc\" >> \"$CLAUDE_USER_DIR/bash-command-log.txt\""
}]
}]
}
}
```
**Auto-format TypeScript files with Prettier:**
```json
{
"hooks": {
"PostToolUse": [{
"matcher": "Edit|Write",
"hooks": [{
"type": "command",
"comment": "Auto-format TypeScript files after edits",
"command": "set -euo pipefail; file_path=$(jq -r '.tool_input.file_path // \"\"'); [[ \"$file_path\" =~ \\.(ts|tsx)$ ]] || exit 0; cd \"$CLAUDE_PROJECT_DIR\" && npx prettier --write \"$file_path\""
}]
}]
}
}
```
**Block sensitive file edits:**
```json
{
"hooks": {
"PreToolUse": [{
"matcher": "Edit|Write",
"hooks": [{
"type": "command",
"comment": "Prevent edits to sensitive files",
"command": "set -euo pipefail; file_path=$(jq -r '.tool_input.file_path // \"\"'); if [[ \"$file_path\" =~ \\.(env|secrets|credentials) ]] || [[ \"$file_path\" == *\"package-lock.json\" ]] || [[ \"$file_path\" == *.git/* ]]; then echo \"ERROR: Cannot edit sensitive file: $file_path\" >&2; exit 2; fi"
}]
}]
}
}
```
**Desktop notifications:**
```json
{
"hooks": {
"Notification": [{
"matcher": "*",
"hooks": [{
"type": "command",
"comment": "Send desktop notifications",
"command": "if command -v notify-send >/dev/null 2>&1; then notify-send 'Claude Code' 'Awaiting your input'; elif command -v osascript >/dev/null 2>&1; then osascript -e 'display notification \"Awaiting your input\" with title \"Claude Code\"'; fi"
}]
}]
}
}
```
8. **Generic Patterns Reference:**
**Pattern: Extract file path and check multiple extensions**
```bash
set -euo pipefail
file_path=$(jq -r '.tool_input.file_path // ""')
[[ "$file_path" =~ \.(js|ts|jsx|tsx|py|go|rs)$ ]] || exit 0
# Your command here
```
**Pattern: Process multiple files from array**
```bash
set -euo pipefail
jq -r '.tool_input.files[]?' | while IFS= read -r file; do
[[ -f "$file" ]] && echo "Processing: $file"
# Your processing logic here
done
```
**Pattern: Conditional execution based on directory**
```bash
set -euo pipefail
file_path=$(jq -r '.tool_input.file_path // ""')
# Only process files in src/ directory
[[ "$file_path" =~ ^src/ ]] || exit 0
# Your command here
```
**Pattern: Extract and validate Bash command**
```bash
set -euo pipefail
cmd=$(jq -r '.tool_input.command // ""')
# Block dangerous commands
if [[ "$cmd" =~ (rm -rf|mkfs|dd|:(){:|:&};:) ]]; then
echo "ERROR: Dangerous command blocked" >&2
exit 2
fi
```
**Pattern: Background/async execution**
```bash
set -euo pipefail
file_path=$(jq -r '.tool_input.file_path // ""')
# Run slow operation in background, don't block Claude
(cd "$CLAUDE_PROJECT_DIR" && npm run build "$file_path" &> /tmp/build.log) &
```
**Pattern: Conditional tool execution**
```bash
set -euo pipefail
tool_name=$(jq -r '.tool_name // ""')
case "$tool_name" in
Edit|Write)
file_path=$(jq -r '.tool_input.file_path // ""')
echo "File modified: $file_path"
;;
Bash)
cmd=$(jq -r '.tool_input.command // ""')
echo "Command executed: $cmd"
;;
esac
```
**Pattern: Multi-tool chain with error handling**
```bash
set -euo pipefail
file_path=$(jq -r '.tool_input.file_path // ""')
[[ "$file_path" =~ \.(ts|tsx)$ ]] || exit 0
cd "$CLAUDE_PROJECT_DIR"
# Run linter
if ! npx eslint --fix "$file_path" 2>/dev/null; then
echo "Warning: ESLint failed" >&2
fi
# Run formatter (always runs even if linter fails)
npx prettier --write "$file_path" 2>/dev/null || true
```
**Pattern: Cache validation results**
```bash
set -euo pipefail
file_path=$(jq -r '.tool_input.file_path // ""')
cache_file="/tmp/claude-hook-cache-$(echo \"$file_path\" | md5sum | cut -d' ' -f1)"
# Check cache freshness
if [[ -f "$cache_file" ]] && [[ "$cache_file" -nt "$file_path" ]]; then
cat "$cache_file"
exit 0
fi
# Run expensive validation
result=$(npx tsc --noEmit "$file_path" 2>&1)
echo "$result" > "$cache_file"
echo "$result"
```
**Pattern: Cross-platform compatibility**
```bash
set -euo pipefail
# Detect OS and use appropriate commands
case "$(uname -s)" in
Darwin*)
# macOS
osascript -e 'display notification "Build complete"'
;;
Linux*)
# Linux
notify-send "Build complete"
;;
MINGW*|MSYS*|CYGWIN*)
# Windows
powershell -Command "New-BurntToastNotification -Text 'Build complete'"
;;
esac
```
9. **Security considerations:**
- Hooks run automatically with your environment's credentials
- Always review hook implementation before registering
- Be cautious with hooks that execute external commands
- Avoid hardcoding sensitive data in hook commands
- Use exit code 2 to block operations in PreToolUse hooks
10. **Hook creation workflow:**
**For common tools (ESLint, Prettier, TypeScript, Tests):**
1. Detect tool name from user request keywords
2. Ask user: "I can set up a production-ready [TOOL] hook. Use template or create custom?"
3. If template:
- Create `.claude/hooks/` directory if needed
- Generate appropriate script file (e.g., `run-eslint.sh`)
- Make script executable (`chmod +x`)
- Add settings.json entry with `$CLAUDE_PROJECT_DIR` reference
- Verify package manager and dependencies exist
4. Provide setup summary and next steps
**For custom hooks:**
1. Determine appropriate hook event for the use case
2. Define matcher pattern (specific tool name, regex like "Edit|Write", or "*" for all)
3. Write shell command that processes JSON input via stdin
4. Always start with `set -euo pipefail` for safety
5. Use `$CLAUDE_PROJECT_DIR` and other environment variables
6. Test hook command independently before registering
7. Choose storage location:
- `.claude/settings.json` - Project-specific, committed to git
- `.claude/settings.local.json` - Project-specific, not committed
- `~/.claude/settings.json` - User-wide, all projects
8. Register hook and reload with `/hooks` command
11. **Debugging hooks:**
- Run `claude --debug` to see hook execution logs
- Use `/hooks` command to verify hook registration
- Check hook configuration in settings files
- Test hook command standalone with sample JSON:
```bash
echo '{"tool_name":"Edit","tool_input":{"file_path":"test.ts"}}' | .claude/hooks/run-eslint.sh
```
- Review Claude Code output for hook execution errors
- Use `jq` to inspect JSON data passed to hooks
- Check exit codes (0=success/continue, 1=error/log, 2=block operation)
- Verify file permissions (`chmod +x` for external scripts)
- Check that `$CLAUDE_PROJECT_DIR` resolves correctly
12. **Output:**
**Template mode:**
- Create external script file in `.claude/hooks/[script-name].sh`
- Generate settings.json configuration snippet
- Make script executable
- Print: `STATUS=OK HOOK_FILE=.claude/hooks/[script-name].sh SETTINGS=.claude/settings.json`
- Show: Next steps (reload hooks, test the hook)
**Interactive/Direct mode:**
- Guide user through hook creation with prompts
- Show the complete JSON configuration to add
- Provide instructions for registering the hook
- Print: `STATUS=OK HOOK_FILE=~/.claude/settings.json` or `STATUS=OK HOOK_FILE=.claude/settings.local.json`
- Remind user to run `/hooks` to reload configuration
## Constraints
- External scripts must be executable (`chmod +x`)
- Hooks must be valid shell commands or script paths
- JSON structure must follow hooks schema
- PreToolUse hooks can block operations with exit code 2
- Hooks should be idempotent and handle errors gracefully
- Consider performance impact of hooks in tight loops
- Always use `set -euo pipefail` in bash scripts for safety
- Use `$CLAUDE_PROJECT_DIR` for project-relative paths
- Test hooks standalone before deploying
## Examples
**Template mode (recommended for common tools):**
```bash
# User: "Set up ESLint to run on file edits"
/create-hook
# Detects "ESLint", offers template
# → Creates .claude/hooks/run-eslint.sh
# → Adds PostToolUse hook to settings.json
# → Makes script executable
# → STATUS=OK HOOK_FILE=.claude/hooks/run-eslint.sh
```
**Interactive mode:**
```bash
/create-hook
# Shows menu of:
# 1. Common tools (ESLint, Prettier, TypeScript, Tests)
# 2. Hook types (PreToolUse, PostToolUse, etc.)
# 3. Custom hook creation
```
**Guided mode:**
```bash
/create-hook PostToolUse
# Guides through creating a PostToolUse hook
# Asks for: matcher, command/script, storage location
```
**Direct mode:**
```bash
/create-hook PreToolUse "Bash" "set -euo pipefail; cmd=\$(jq -r '.tool_input.command'); echo \"[\$(date -Iseconds)] \$cmd\" >> \"\$CLAUDE_USER_DIR/bash.log\""
# Creates hook configuration directly with best practices
```
## Reference
For complete documentation, see: https://docs.claude.com/en/hooks

114
commands/create-md.md Normal file
View File

@@ -0,0 +1,114 @@
---
description: Generate CLAUDE.md files for project and key subdirectories
argument-hint: [thoroughness: quick|medium|very-thorough]
---
# /create-md
## Purpose
Analyze project structure using the Explore subagent and generate CLAUDE.md files—one global file describing the project in general, plus nested CLAUDE.md files in important subdirectories for localized context.
## Contract
**Inputs:**
- `$1` — THOROUGHNESS (optional: `quick`, `medium`, `very-thorough`; default: `medium`)
**Outputs:**
- `STATUS=<OK|FAIL>`
- `FILES=<list of created CLAUDE.md paths>`
## Instructions
1. **Explore the project structure** using the Task tool with `subagent_type=Explore`:
- Understand the overall architecture and technology stack
- Identify key directories (e.g., `/src`, `/frontend`, `/backend`, `/services`, `/packages`)
- Find existing setup/build/test commands (package.json, Makefile, etc.)
- Detect coding conventions (ESLint, Prettier, etc.)
- Map out the project structure
2. **Create root CLAUDE.md** with:
- Project overview and architecture map
- Setup, run, and test commands
- Code style and conventions
- Workflow and review expectations
- Safety guardrails (no secrets, env vars, etc.)
- Examples of good changes
3. **Create nested CLAUDE.md files** in subdirectories where useful:
- For monorepo packages/apps with different tech stacks
- For frontend/backend splits
- For specialized modules with unique conventions
- Keep them focused and scoped to that directory's context
4. **Output results**:
- Print created file paths
- Print: `STATUS=OK FILES=<comma-separated paths>`
## What to include in CLAUDE.md files
### Root CLAUDE.md
```md
# CLAUDE.md — Project rules
## Overview
One-liner + architecture map.
## Setup & Run
- Install: [command]
- Start dev: [command]
- Tests: [command]
## Code Style
- Linting/formatting tools and configs
- Commit style (Conventional Commits, etc.)
## Safety rails
- Never commit secrets; use .env.example
- Don't modify generated files
## Workflow
- For bugfixes: write failing test → fix → link issue
- For features: create RFC before code
## Examples
- See /docs/examples for typical PRs
```
### Nested CLAUDE.md (e.g., `/frontend/CLAUDE.md`)
```md
# Frontend — Local rules
## Stack
Next.js 14, TypeScript, TailwindCSS
## Key directories
- `/app` — App router pages
- `/components` — Reusable UI components
- `/lib` — Utilities and helpers
## Conventions
- Components: PascalCase, one per file
- Hooks: camelCase, prefix with `use`
- Server components by default; add 'use client' when needed
## Testing
- Run: pnpm test:frontend
- Write tests alongside components (*.test.tsx)
```
## Constraints
- Use the Explore subagent (Task tool) for analysis
- Keep CLAUDE.md files concise and actionable
- Only create nested files where they add value
- Link to existing docs rather than duplicating content
## Example usage
```bash
# Quick exploration and basic CLAUDE.md files
/create-md quick
# Medium depth (default)
/create-md
# Very thorough analysis with comprehensive CLAUDE.md files
/create-md very-thorough
```

95
commands/create-output-style.md Normal file
View File

@@ -0,0 +1,95 @@
---
description: Generate custom output styles that modify Claude Code's system prompt for different agent behaviors
argument-hint: [style-name] [--user|--project] [--description "..."]
---
# /create-output-style
## Purpose
Generate custom output style files for Claude Code with proper structure and YAML frontmatter.
## Contract
**Inputs:**
- `$1` — STYLE_NAME (optional: name for the output style)
- `--user` — Save to user-level directory (~/.claude/output-styles)
- `--project` — Save to project-level directory (.claude/output-styles)
- `--description "..."` — Brief description of the output style
**Outputs:** `STATUS=<OK|FAIL> PATH=<path> SCOPE=<user|project>`
## Instructions
1. **Determine scope:**
- If `--user` is provided: save to `~/.claude/output-styles/`
- If `--project` is provided: save to `.claude/output-styles/`
- Default: `--user` (user-level)
2. **Gather information:**
- If STYLE_NAME not provided, ask user for the style name
- If description not provided via `--description`, ask user what behavior they want
- Style name should be title-cased (e.g., "My Custom Style")
3. **Generate output style file** using this template:
```markdown
---
name: {{STYLE_NAME}}
description: {{DESCRIPTION}}
---
# {{STYLE_NAME}} Instructions
You are an interactive CLI tool that helps users with software engineering tasks.
{{CUSTOM_INSTRUCTIONS}}
## Specific Behaviors
{{SPECIFIC_BEHAVIORS}}
## Key Principles
- {{PRINCIPLE_1}}
- {{PRINCIPLE_2}}
- {{PRINCIPLE_3}}
```
4. **Create the file:**
- Convert style name to kebab-case for filename (e.g., "My Custom Style" → "my-custom-style.md")
- Create target directory if it doesn't exist
- Write the file
- Print: `STATUS=OK PATH=<full-path> SCOPE=<user|project>`
5. **Inform user:**
- Let them know the file was created
- Remind them they can activate it with `/output-style [style-name]`
- Mention they can edit the file directly to refine the instructions
## Examples
**Example 1: Basic usage**
```bash
/create-output-style
# Claude will ask for style name and description interactively
```
**Example 2: Full specification**
```bash
/create-output-style "Teaching Assistant" --project --description "Explains concepts step by step with examples"
# STATUS=OK PATH=.claude/output-styles/teaching-assistant.md SCOPE=project
```
**Example 3: User-level style**
```bash
/create-output-style "Code Reviewer" --user --description "Focuses on thorough code review with best practices"
# STATUS=OK PATH=~/.claude/output-styles/code-reviewer.md SCOPE=user
```
## Notes
- Output styles modify Claude Code's system prompt completely
- Non-default styles exclude standard code generation instructions
- User-level styles are available across all projects
- Project-level styles are specific to the current project
- You can manually edit the generated files to refine instructions

155
commands/create-plugin.md Normal file
View File

@@ -0,0 +1,155 @@
---
description: Convert a project into a Claude Code plugin
argument-hint: [project-path]
---
# /create-plugin
## Purpose
Guide users through converting an existing project into a properly structured Claude Code plugin, following official documentation standards.
## Contract
**Inputs:** `[project-path]` — Optional path to project directory (defaults to current directory)
**Outputs:** `STATUS=<OK|FAIL> PLUGIN_PATH=<path>`
## Instructions
1. **Analyze the project structure:**
- Identify existing components that could become plugin features
- Check for slash commands, agents, skills, hooks, or MCP integrations
- Review documentation files
2. **Create plugin and marketplace structure:**
- Create `.claude-plugin/` directory at project root
- Generate `plugin.json` manifest with proper metadata:
- name (lowercase, kebab-case)
- description
- version (semantic versioning)
- author information (object with name and optional url)
- repository (string URL, not object)
- license (optional)
- Generate `marketplace.json` in the same directory with:
- marketplace name
- owner information
- plugins array with source reference `"./"` (self-reference)
3. **Organize plugin components:**
- `commands/` - Slash command markdown files
- `agents/` - Agent definition markdown files
- `skills/` - Agent Skills with SKILL.md files
- `hooks/` - hooks.json for event handlers
- `.mcp.json` - MCP server configurations (if applicable)
4. **Generate documentation:**
- Create/update README.md with:
- Installation instructions
- Usage examples
- Component descriptions
- Testing guidance
5. **Provide testing workflow:**
- Local marketplace setup commands
- Installation verification steps
- Iteration and debugging guidance
## Reference Documentation
Follow the official Claude Code plugin and marketplace structure:
```
my-plugin/
├── .claude-plugin/
│ ├── marketplace.json # Marketplace manifest
│ └── plugin.json # Plugin metadata
├── commands/ # Custom slash commands (optional)
│ └── command-name.md
├── agents/ # Custom agents (optional)
│ └── agent-name.md
├── skills/ # Agent Skills (optional)
│ └── skill-name/
│ └── SKILL.md
├── hooks/ # Event handlers (optional)
│ └── hooks.json
├── .mcp.json # MCP servers (optional)
└── README.md # Documentation
```
## Plugin Manifest Template
The plugin.json file MUST be created at `<plugin-dir>/.claude-plugin/plugin.json`:
```json
{
"name": "plugin-name",
"version": "1.0.0",
"description": "Plugin description",
"author": {
"name": "Author Name",
"url": "https://github.com/username"
},
"repository": "https://github.com/username/plugin-name",
"license": "MIT"
}
```
**Important:** The `repository` field must be a string URL, not an object. Using an object format like `{"type": "git", "url": "..."}` will cause validation errors.
## Marketplace Manifest Template
The marketplace.json file MUST be created at `<plugin-dir>/.claude-plugin/marketplace.json` alongside plugin.json:
```json
{
"name": "marketplace-name",
"owner": {
"name": "Owner Name"
},
"plugins": [
{
"name": "plugin-name",
"source": "./",
"description": "Plugin description"
}
]
}
```
## Key Guidelines
- **Plugin manifest**: Use semantic versioning, clear descriptions
- **Marketplace manifest**: MUST create marketplace.json in the same .claude-plugin/ directory alongside plugin.json
- **Commands**: Markdown files with frontmatter (description, argument-hint)
- **Skills**: Create subdirectories with SKILL.md files
- **Testing**: Use local marketplace for iterative development
- **Documentation**: Include installation, usage, and examples
## Constraints
- Must create valid plugin.json schema in .claude-plugin/ directory
- Must create valid marketplace.json schema in the same .claude-plugin/ directory
- The repository field in plugin.json MUST be a string URL, not an object
- Follow kebab-case naming conventions
- Include proper frontmatter in all markdown files
- Marketplace source must reference "./" to point to the plugin directory itself
- Output final STATUS line with plugin path
## Example Output
```
Created plugin structure at: ./my-plugin
Generated components:
- .claude-plugin/plugin.json
- .claude-plugin/marketplace.json
- commands/helper.md
- README.md
Next steps:
1. cd my-plugin && claude
2. /plugin marketplace add .
3. /plugin install my-plugin@my-plugin-dev
Or for GitHub-based installation:
1. Push to GitHub repository
2. /plugin marketplace add username/my-plugin
3. /plugin install my-plugin@my-plugin-dev
STATUS=OK PLUGIN_PATH=./my-plugin
```

406
commands/create-skill.md Normal file
View File

@@ -0,0 +1,406 @@
---
description: Generate a new Claude Skill with proper structure and YAML frontmatter using official documentation as reference
argument-hint: [skill-name] [description]
---
# /create-skill
## Purpose
Generate a new Claude Skill with proper structure and YAML frontmatter using official documentation as reference
## Contract
**Inputs:**
- `$1` — SKILL_NAME (lowercase, kebab-case, max 64 characters)
- `$2` — DESCRIPTION (what the skill does and when to use it, max 1024 characters)
- `--personal` — create in ~/.claude/skills/ (default)
- `--project` — create in .claude/skills/
**Outputs:** `STATUS=<CREATED|EXISTS|FAIL> PATH=<path>`
## Instructions
1. **Validate inputs:**
- Skill name: lowercase letters, numbers, hyphens only (max 64 chars)
- Description: non-empty, max 1024 characters, no angle brackets (< or >)
- Description should include both WHAT the skill does and WHEN to use it
- If user provides additional frontmatter properties, validate against allowed list:
- **Allowed:** name, description, license, allowed-tools, metadata
- **Warning** (not error) for unexpected properties like version, author, tags
- Inform user that unexpected properties may cause issues during packaging
2. **Determine target directory:**
- Personal (default): `~/.claude/skills/{{SKILL_NAME}}/`
- Project: `.claude/skills/{{SKILL_NAME}}/`
3. **Check if skill already exists:**
- If exists: output `STATUS=EXISTS PATH=<path>` and stop
4. **Analyze what bundled resources this skill needs:**
Based on the skill name and description, intelligently determine which bundled resources would be valuable:
**Create scripts/ directory when:**
- Skill involves file manipulation (PDF, images, documents, etc.)
- Skill requires deterministic operations (data processing, conversions)
- Same code would be rewritten repeatedly
- Examples: pdf-editor, image-processor, data-analyzer, file-converter
**Create references/ directory when:**
- Skill needs reference documentation (API docs, schemas, specifications)
- Detailed information would make SKILL.md too long (>5k words)
- Domain knowledge needs to be documented (company policies, standards)
- Examples: api-client, database-query, brand-guidelines, coding-standards
**Create assets/ directory when:**
- Skill uses templates or boilerplate code
- Skill needs brand assets (logos, fonts, images)
- Skill creates documents from templates (presentations, reports)
- Examples: frontend-builder, brand-guidelines, document-generator, presentation-maker
**Questions to ask user for clarification (only if unclear):**
- "Will this skill need to run any scripts repeatedly?" (→ scripts/)
- "Does this skill need reference documentation like API docs or schemas?" (→ references/)
- "Will this skill use templates or assets like logos/fonts/boilerplate?" (→ assets/)
**Communicate the decision:**
After analysis, inform the user which directories will be created and why:
- Example: "Based on the description, I'll create scripts/ for PDF manipulation utilities and references/ for schema documentation."
- Be transparent about the reasoning
- It's better to include a directory with placeholders than to omit one that might be needed
5. **Create skill directory structure based on analysis:**
Always create:
```
{{SKILL_NAME}}/
└── SKILL.md (required)
```
Conditionally create based on Step 4 analysis:
```
├── scripts/ (if determined needed)
│ └── example.py (executable placeholder with TODO)
├── references/ (if determined needed)
│ └── README.md (documentation placeholder with guidance)
└── assets/ (if determined needed)
└── README.md (asset placeholder with examples)
```
6. **Generate SKILL.md using this template:**
```markdown
---
name: {{SKILL_NAME}}
description: {{DESCRIPTION}}
# Optional fields (uncomment if needed):
# allowed-tools: ["Read", "Write", "Bash"] # Restrict to specific tools
# metadata:
# category: "development"
# version: "1.0.0" # For tracking in your project
# license: "MIT" # For shared skills
---
# {{Title Case Skill Name}}
## Overview
[TODO: 1-2 sentences explaining what this skill does and why it's valuable]
## When to Use
[TODO: Specific triggers and scenarios where this skill should be invoked]
## Structuring This Skill
Choose an organizational pattern:
**Workflow-Based** (sequential) - TDD workflows, git commits, deployments
- Structure: Overview → Step 1 → Step 2 → Step 3...
**Task-Based** (operations) - File tools, API operations, data transforms
- Structure: Overview → Quick Start → Operation A → Operation B...
**Reference-Based** (guidelines) - Brand standards, coding rules, checklists
- Structure: Overview → Guidelines → Specifications → Examples
**Capabilities-Based** (integrated) - Product management, debugging, systems
- Structure: Overview → Core Capabilities → Feature 1 → Feature 2...
Patterns can be mixed. Delete this section after choosing.
[TODO: Delete this "Structuring This Skill" section after choosing your approach]
## Instructions
[TODO: Provide clear, step-by-step guidance using imperative/infinitive language]
[TODO: Reference any bundled resources (scripts, references, assets) so Claude knows how to use them]
Example structure:
1. First major step
2. Second major step
3. Third major step
## Bundled Resources
[TODO: Document bundled resources. Delete unused subsections.]
**scripts/** - Executable code run directly (not loaded into context)
- Example: `scripts/process_data.py` - Processes CSV and generates reports
**references/** - Documentation loaded into context when needed
- Example: `references/api_docs.md` - API endpoint documentation
**assets/** - Files used in output (not loaded into context)
- Example: `assets/template.pptx` - Presentation template
## Examples
[TODO: Show concrete examples with realistic user requests]
```
User: "Help me [specific task]"
Claude: [How the skill responds]
```
## Progressive Disclosure
Keep SKILL.md <5k words. Move detailed info to references/. Three-level loading:
1. Metadata (~100 words) - Always in context
2. SKILL.md - Loaded when triggered
3. Bundled resources - Loaded as needed
```
7. **Create bundled resource placeholders (based on Step 4 analysis):**
For each directory determined in Step 4, create appropriate placeholder files:
**scripts/** → Create `scripts/example.py` (executable Python template with TODO comment)
**references/** → Create `references/README.md` (documentation template explaining purpose)
**assets/** → Create `assets/README.md` (asset placeholder explaining common types)
Make scripts executable: `chmod +x scripts/*.py`
8. **Follow official guidelines:**
- Name: lowercase, numbers, hyphens only (max 64 chars)
- Description: Include triggers and use cases (max 1024 chars)
- Instructions: Clear, step-by-step guidance
- Keep skills focused on single capabilities
- Make descriptions specific with trigger keywords
9. **Output:**
- Print: `STATUS=CREATED PATH={{full_path}}`
- Summarize what was created and why (list directories + reasoning)
- Remind user to populate placeholders and complete [TODO] items
## Constraints
- Skills are model-invoked (Claude decides when to use them)
- Description must be specific enough for Claude to discover when to use it
- One skill = one capability (stay focused)
- Use forward slashes in all file paths
- Valid YAML syntax required in frontmatter
## Frontmatter Properties
**Required:**
- `name` - Lowercase hyphen-case identifier (max 64 chars, matches directory name)
- `description` - What it does + when to use it (max 1024 chars, no angle brackets)
**Optional:**
- `allowed-tools: ["Read", "Write", "Bash"]` - Restrict Claude to specific tools
- `metadata: {category: "dev", version: "1.0"}` - Custom tracking fields
- `license: "MIT"` - License for shared skills
**Prohibited** (causes warnings):
- `version`, `author`, `tags` - Use metadata or description instead
## Examples
**Simple workflow skill:**
```bash
/create-skill commit-helper "Generate clear git commit messages from diffs. Use when writing commits or reviewing staged changes."
```
*Claude will determine: No bundled resources needed - just workflow guidance*
**File manipulation skill:**
```bash
/create-skill pdf-processor "Extract text and tables from PDF files. Use when working with PDFs, forms, or document extraction."
```
*Claude will determine: Needs scripts/ directory for PDF manipulation utilities*
**API integration skill:**
```bash
/create-skill api-client "Make REST API calls and handle responses. Use for API testing and integration work with the company API."
```
*Claude will determine: Needs references/ directory for API documentation and schemas*
**Image processing skill:**
```bash
/create-skill image-processor "Resize, rotate, and convert images. Use when editing images or batch processing files."
```
*Claude will determine: Needs scripts/ directory for image manipulation operations*
**Brand guidelines skill:**
```bash
/create-skill brand-guidelines "Apply company brand guidelines to designs. Use when creating presentations, documents, or marketing materials."
```
*Claude will determine: Needs references/ for guidelines + assets/ for logos, fonts, templates*
**Frontend builder skill:**
```bash
/create-skill frontend-builder "Build responsive web applications with React. Use when creating new frontend projects or components." --project
```
*Claude will determine: Needs scripts/ for build tools + assets/ for boilerplate templates*
**Database query skill:**
```bash
/create-skill database-query "Query and analyze database tables. Use when working with SQL, BigQuery, or data analysis tasks." --project
```
*Claude will determine: Needs references/ for schema documentation*
**How Claude determines what's needed:**
- Mentions "PDF", "images", "documents", "convert" → scripts/
- Mentions "API", "database", "guidelines", "standards" → references/
- Mentions "templates", "boilerplate", "brand", "presentations" → assets/
- Simple workflow/process skills → SKILL.md only
**Adding optional frontmatter properties:**
After creating a skill, you can manually edit SKILL.md to add optional frontmatter properties:
```markdown
---
name: database-query
description: Query and analyze database tables. Use when working with SQL, BigQuery, or data analysis tasks.
allowed-tools: ["Bash", "Read", "Grep"]
metadata:
category: "data"
version: "1.0.0"
team: "analytics"
license: "MIT"
---
```
## Post-Creation Workflow
**1. Edit** - Complete [TODO] placeholders, populate bundled resources, add concrete examples
**2. Test** - Restart Claude Code, test with trigger queries matching description
**3. Validate** - Check frontmatter properties, description clarity, no sensitive data
**4. Iterate** - Use on real tasks, update based on struggles/feedback
**Optional:**
- Package for distribution: Use packaging tools or `/create-plugin`
- Share with team: Distribute .zip or via plugin marketplace
## Example: Well-Structured Skill
Here's an example of a production-quality skill to demonstrate best practices:
**artifacts-builder** - A skill for creating complex React/TypeScript artifacts with shadcn/ui
```
artifacts-builder/
├── SKILL.md (focused, ~75 lines)
└── scripts/
├── init-artifact.sh (323 lines - initializes React+Vite+shadcn project)
├── bundle-artifact.sh (54 lines - bundles to single HTML)
└── shadcn-components.tar.gz (pre-packaged shadcn/ui components)
```
**SKILL.md structure:**
```markdown
---
name: artifacts-builder
description: Suite of tools for creating elaborate, multi-component claude.ai HTML artifacts using modern frontend web technologies (React, Tailwind CSS, shadcn/ui). Use for complex artifacts requiring state management, routing, or shadcn/ui components - not for simple single-file HTML/JSX artifacts.
license: Complete terms in LICENSE.txt
---
# Artifacts Builder
To build powerful frontend claude.ai artifacts, follow these steps:
1. Initialize the frontend repo using `scripts/init-artifact.sh`
2. Develop your artifact by editing the generated code
3. Bundle all code into a single HTML file using `scripts/bundle-artifact.sh`
4. Display artifact to user
5. (Optional) Test the artifact
**Stack**: React 18 + TypeScript + Vite + Parcel (bundling) + Tailwind CSS + shadcn/ui
## Design & Style Guidelines
VERY IMPORTANT: To avoid what is often referred to as "AI slop", avoid using excessive centered layouts, purple gradients, uniform rounded corners, and Inter font.
## Quick Start
### Step 1: Initialize Project
Run the initialization script to create a new React project:
```bash
bash scripts/init-artifact.sh <project-name>
cd <project-name>
```
This creates a fully configured project with:
- ✅ React + TypeScript (via Vite)
- ✅ Tailwind CSS 3.4.1 with shadcn/ui theming system
- ✅ Path aliases (`@/`) configured
- ✅ 40+ shadcn/ui components pre-installed
- ✅ All Radix UI dependencies included
- ✅ Parcel configured for bundling
- ✅ Node 18+ compatibility
### Step 2: Develop Your Artifact
To build the artifact, edit the generated files. See **Common Development Tasks** below for guidance.
### Step 3: Bundle to Single HTML File
To bundle the React app into a single HTML artifact:
```bash
bash scripts/bundle-artifact.sh
```
This creates `bundle.html` - a self-contained artifact with all JavaScript, CSS, and dependencies inlined.
### Step 4: Share Artifact with User
Finally, share the bundled HTML file in conversation with the user so they can view it as an artifact.
### Step 5: Testing/Visualizing the Artifact (Optional)
Note: This is a completely optional step. Only perform if necessary or requested.
## Reference
- **shadcn/ui components**: https://ui.shadcn.com/docs/components
```
**What makes this skill excellent:**
1. **Clear, specific description** - States exactly what it does (React artifacts with shadcn/ui) and when NOT to use it (simple HTML)
2. **Task-Based organizational pattern** - Uses numbered steps (Quick Start → Step 1, 2, 3...) for clear workflow
3. **Practical scripts/** - Contains executable utilities that prevent rewriting the same setup code:
- `init-artifact.sh` - Automates 20+ setup steps (Vite, Tailwind, shadcn/ui, dependencies)
- `bundle-artifact.sh` - Bundles multi-file React app into single HTML
- `shadcn-components.tar.gz` - Pre-packaged components (saves installation time)
4. **Focused SKILL.md** - Only ~75 lines, moves implementation details to scripts
5. **Domain-specific guidance** - Includes "Design & Style Guidelines" section with specific advice
6. **Optional license field** - Uses `license: Complete terms in LICENSE.txt` since Apache 2.0 is verbose
7. **Progressive disclosure** - Metadata (~50 words), SKILL.md core workflow (<2k words), scripts executed without loading
8. **Explicit references** - Points to external docs (shadcn/ui) rather than duplicating them
**Claude Code would create scripts/ automatically for this skill because:**
- Description mentions "tools", "React", "Tailwind CSS", "shadcn/ui" (technical setup)
- Name "builder" implies construction/automation
- Description emphasizes "elaborate, multi-component" (complexity requiring tooling)
## Reference
Based on official Claude Code Agent Skills documentation:
- Personal skills: `~/.claude/skills/`
- Project skills: `.claude/skills/`
- Changes take effect on next Claude Code restart
- Test by asking questions matching the description triggers