commit 6d7255ec209fd5835ad48e8d73ea2c2eb6611226 Author: Zhongwei Li Date: Sat Nov 29 17:52:01 2025 +0800 Initial commit diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..34e7ee1 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,12 @@ +{ + "name": "claude-code-builder", + "description": "Create skills, subagents, hooks, commands, and plugins for Claude Code", + "version": "1.0.0", + "author": { + "name": "Alexander Opalic", + "url": "https://github.com/alexanderop/claude-code-builder" + }, + "commands": [ + "./commands" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..520dd93 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# claude-code-builder + +Create skills, subagents, hooks, commands, and plugins for Claude Code diff --git a/commands/create-agent.md b/commands/create-agent.md new file mode 100644 index 0000000..e746826 --- /dev/null +++ b/commands/create-agent.md @@ -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= PATH= AGENT=` + +## 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..." diff --git a/commands/create-command.md b/commands/create-command.md new file mode 100644 index 0000000..0e76139 --- /dev/null +++ b/commands/create-command.md @@ -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= 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= [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 +``` \ No newline at end of file diff --git a/commands/create-hook.md b/commands/create-hook.md new file mode 100644 index 0000000..8b57f2e --- /dev/null +++ b/commands/create-hook.md @@ -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= HOOK_FILE=` + +## 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 diff --git a/commands/create-md.md b/commands/create-md.md new file mode 100644 index 0000000..df76a82 --- /dev/null +++ b/commands/create-md.md @@ -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=` +- `FILES=` + +## 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=` + +## 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 +``` diff --git a/commands/create-output-style.md b/commands/create-output-style.md new file mode 100644 index 0000000..c708884 --- /dev/null +++ b/commands/create-output-style.md @@ -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= PATH= SCOPE=` + +## 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= SCOPE=` + +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 diff --git a/commands/create-plugin.md b/commands/create-plugin.md new file mode 100644 index 0000000..a1aafbf --- /dev/null +++ b/commands/create-plugin.md @@ -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= PLUGIN_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 `/.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 `/.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 +``` diff --git a/commands/create-skill.md b/commands/create-skill.md new file mode 100644 index 0000000..fb9174c --- /dev/null +++ b/commands/create-skill.md @@ -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= 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=` 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 +cd +``` + +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 diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..2370591 --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,69 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:alexanderop/claude-code-builder:", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "7aa8f8a82e88c7daf5f776e7b39639f818fb839f", + "treeHash": "6be9d1d5b0fe1cd374975899cf394e4dda67ba05986e0232c3bd7ec58dd28cbc", + "generatedAt": "2025-11-28T10:13:08.375460Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "claude-code-builder", + "description": "Create skills, subagents, hooks, commands, and plugins for Claude Code", + "version": "1.0.0" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "3dae3441fb68b83222b70dc6158b595f88aa9fb2a4ed2891906651048321cadf" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "20585fe9434709d18d25edb0e04fc113f137b5439c256f8ca7dd69bbbcd1b719" + }, + { + "path": "commands/create-md.md", + "sha256": "3ef41d105c6bf15ba59f66bb66c129f4edec2ff6a84c73def5d30a4a303037f2" + }, + { + "path": "commands/create-skill.md", + "sha256": "2a95da3e9949f28cb669ed5554190b8939d6283dd37c8727a79fc397474bbd42" + }, + { + "path": "commands/create-command.md", + "sha256": "ccb8fc052116677ef65e82ec00994d4e2ba21568909ede20742e86a4d9df9b46" + }, + { + "path": "commands/create-hook.md", + "sha256": "ec3c1aff01885dd23665057012003781c81eb8cea0d3d7ea58f6d48dc04bfa6e" + }, + { + "path": "commands/create-output-style.md", + "sha256": "772549c0e79450992ee7c4dfd835ba285f7d68660c55d09d46703a2372b85604" + }, + { + "path": "commands/create-agent.md", + "sha256": "a8ede93151f1a16e924c3dac2bead910d4e0b7949c8311619c6bc1c4e1fa1780" + }, + { + "path": "commands/create-plugin.md", + "sha256": "2a02a6066caebc25f4178e2d30ff7e64ecfacf2c7834be03b7e893dd6fbf57b5" + } + ], + "dirSha256": "6be9d1d5b0fe1cd374975899cf394e4dda67ba05986e0232c3bd7ec58dd28cbc" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file