Initial commit

2025-11-30 08:48:43 +08:00
commit 2b34b5aa74
25 changed files with 7414 additions and 0 deletions
--- a/skills/slash-command-design/SKILL.md
+++ b/skills/slash-command-design/SKILL.md
@@ -0,0 +1,504 @@
+---
+name: box-factory-slash-command-design
+description: Interpretive guidance for designing Claude Code slash commands. Helps you apply official documentation effectively and create high-quality commands. Use when creating or reviewing slash commands.
+---
+
+# Slash Command Design Skill
+
+This skill provides interpretive guidance and best practices for creating Claude Code slash commands. **ALWAYS fetch current official documentation before creating commands** - this skill helps you understand what the docs mean and how to create excellent commands.
+
+## Required Reading Before Creating Commands
+
+Fetch these docs with WebFetch every time:
+
+- **https://code.claude.com/docs/en/slash-commands.md** - Core specification and examples
+- **https://code.claude.com/docs/en/settings#tools-available-to-claude** - Verify tool names
+- **https://code.claude.com/docs/en/model-config.md** - Model selection guidance
+
+## Core Understanding
+
+### Commands Are User-Triggered, Not Autonomous
+
+**Key distinction:**
+
+- **Commands** = User explicitly invokes with `/command-name`
+- **Agents** = Claude autonomously delegates based on context
+- **Skills** = Knowledge that loads when relevant
+
+**Quality test:** If you want this to happen automatically based on context, it's an agent, not a command.
+
+### Command Structure
+
+Commands are Markdown files with optional YAML frontmatter:
+
+```markdown
+---
+description: Brief description (optional, defaults to first line)
+argument-hint: [expected-args]
+allowed-tools: Tool1, Tool2
+model: sonnet
+disable-model-invocation: false
+---
+
+Command prompt content goes here.
+Use $1, $2 for individual arguments or $ARGUMENTS for all.
+```
+
+## Frontmatter Fields (Official Specification)
+
+All fields are optional:
+
+| Field | Purpose | Default |
+|-------|---------|---------|
+| `description` | Brief command description for `/help` | First line of prompt |
+| `argument-hint` | Expected arguments (e.g., `[pr-number] [priority]`) | None |
+| `allowed-tools` | Restrict to specific tools (e.g., `Bash(git:*)`) | Inherits from conversation |
+| `model` | Specific model to use | Inherits from conversation |
+| `disable-model-invocation` | Prevents SlashCommand tool from auto-invoking | false |
+
+**Best practice:** Always include `description` even though it's optional - improves discoverability and Claude's ability to use the SlashCommand tool.
+
+## Argument Syntax (Official Specification)
+
+**All arguments as single string:**
+
+```markdown
+$ARGUMENTS
+```
+
+Example: `/fix-issue 123 high-priority` → `$ARGUMENTS = "123 high-priority"`
+
+**Individual positional arguments:**
+
+```markdown
+$1, $2, $3, etc.
+```
+
+Example: `/review-pr 456 high alice` → `$1="456"`, `$2="high"`, `$3="alice"`
+
+**Official guidance:** "Use individual arguments (`$1`, `$2`) for complex commands with multiple parameters"
+
+**Best practice:** Use `$1, $2` when you need arguments in different parts of the prompt or want to provide defaults. Keep argument parsing simple - if you need validation or complex logic, delegate to an agent.
+
+## Advanced Features (Official Specification)
+
+### Bash Execution with `!` Prefix
+
+Execute bash commands before the prompt runs:
+
+```markdown
+---
+allowed-tools: Bash(git:*)
+---
+
+!git status
+
+Review the git status above and suggest next steps.
+```
+
+### File References with `@` Prefix
+
+Include file contents in the prompt:
+
+```markdown
+Review @src/utils/helpers.js for potential improvements.
+```
+
+Multiple files: `Compare @src/old.js with @src/new.js`
+
+### Subdirectory Namespacing
+
+Organize commands in subdirectories:
+
+```
+.claude/commands/frontend/component.md → /component (project:frontend)
+.claude/commands/backend/endpoint.md → /endpoint (project:backend)
+```
+
+Command name comes from filename, subdirectory appears in `/help` as namespace label.
+
+## Decision Framework
+
+### Command vs Agent vs Skill
+
+**Use Command when:**
+
+- User wants explicit control over when it runs
+- Simple, deterministic operation
+- Wrapping a bash script or tool sequence
+- "I want to type `/something` to make X happen"
+
+**Use Agent when:**
+
+- Want autonomous delegation based on context
+- Need isolated context window
+- Require specific tool restrictions
+- Complex decision-making involved
+
+**Use Skill when:**
+
+- Multiple contexts need the same knowledge
+- Substantial procedural expertise
+- Progressive disclosure would save tokens
+
+## Best Practices (Opinionated Guidance)
+
+### Delegation Pattern
+
+Most robust commands delegate to specialized agents rather than implementing complex logic:
+
+```markdown
+---
+description: Run full test suite and analyze failures
+---
+
+Use the test-runner agent to execute all tests and provide detailed failure analysis.
+```
+
+**Why this works:**
+
+- Keeps command simple and focused
+- Leverages specialized agent capabilities
+- Avoids reimplementing logic
+- Agent gets isolated context for complex work
+
+**When to use:** Any command that needs file reading/parsing, complex decision trees, error recovery logic, or multi-step state management.
+
+### Tool Restriction Pattern
+
+For simple, deterministic operations, restrict tools for security and clarity:
+
+```markdown
+---
+description: Show git status
+allowed-tools: Bash(git status:*)
+model: haiku
+---
+
+Run `git status` and display the output.
+```
+
+**Benefits:**
+
+- Fast execution (haiku model)
+- Restricted permissions
+- Clear, single-purpose command
+
+### Simple Sequential Pattern
+
+**Commands CAN handle sequential bash operations** when they're straightforward and don't require file inspection or complex parsing:
+
+```markdown
+---
+description: Install GitHub CLI if not present
+allowed-tools: Bash
+model: haiku
+---
+
+Check if gh CLI is installed. If not, provide installation instructions for the user's platform.
+
+Simple workflow:
+1. Check: `which gh` or `command -v gh`
+2. If not found, provide platform-specific install guidance
+3. Verify with `gh --version` if installed
+4. Output success message or next steps
+```
+
+**This pattern is OK in commands when you have:**
+
+✅ **3-5 sequential bash steps** - Simple linear workflow
+✅ **Basic conditionals** - Simple if/else (installed vs not installed)
+✅ **Simple verification** - Exit codes, command success/failure
+✅ **User-facing instructions** - Output guidance, next steps
+
+**When to keep it in a command:**
+
+- Checking if a tool is installed (`which`, `command -v`)
+- Installing via package manager (`brew install`, `apt-get install`)
+- Running simple verification (`--version`, `status` checks)
+- Providing user instructions based on results
+- Linear workflows without branching complexity
+
+**Rule of thumb:** If you can write it as 3-5 bash commands with simple if/else logic and no file reading, keep it in the command.
+
+**Delegate to an agent when you need:**
+
+❌ **File reading/parsing** - Requires Read, Grep, or complex text processing
+❌ **Complex decision trees** - Framework detection, config file parsing, multi-path logic
+❌ **Error recovery logic** - Retries, fallbacks, multiple failure modes
+❌ **State management** - Tracking across multiple steps, rollback capability
+❌ **Multiple tool orchestration** - Coordinating Read + Grep + Write + Bash
+
+**Example requiring agent delegation:**
+
+```markdown
+# ❌ Too complex for command - needs agent
+---
+description: Set up test environment
+---
+
+Detect test framework by:
+1. Read package.json, check for jest/mocha/vitest dependencies
+2. Read test config files (.jestrc, mocha.opts, vitest.config.ts)
+3. Scan for existing test files in src/, tests/, __tests__/
+4. Parse configuration to determine coverage settings
+5. Install missing dependencies based on framework
+6. Generate framework-specific config if missing
+7. Create example test files following detected patterns
+8. Verify setup with test run
+```
+
+**Why this needs an agent:**
+
+- Requires Read tool for multiple files
+- Complex decision tree (framework detection)
+- Config file parsing
+- State management across steps
+- Multiple failure modes to handle
+- Error recovery (config generation, dependency installation)
+
+**Better approach:**
+
+```markdown
+---
+description: Set up test environment for current project
+---
+
+Use the test-setup agent to detect the test framework, install dependencies, and configure the testing environment.
+```
+
+**The threshold:**
+
+- **Commands:** `which gh && gh --version || echo "Install with: brew install gh"`
+- **Agents:** Anything requiring Read/Grep/Parse or complex multi-step decision-making
+
+### Generation Pattern
+
+For creating files/code, be specific about structure and requirements:
+
+```markdown
+---
+description: Create a new React component with TypeScript
+argument-hint: component-name
+---
+
+Create a new React component named `$1` in the components directory.
+
+Include:
+- TypeScript interface for props
+- Basic component structure with proper typing
+- Export statement
+- Test file in __tests__ directory
+
+Follow project conventions for imports and file structure.
+```
+
+## Common Pitfalls (Best Practices)
+
+### Pitfall #1: Knowledge Storage in Commands
+
+**Problem:** Using commands to store documentation instead of actions
+
+**Example of wrong pattern:**
+
+```markdown
+---
+description: Show API documentation standards
+---
+
+Our API documentation standards:
+[50 lines of guidelines...]
+```
+
+**Why it's wrong:** This is knowledge, not an action. Commands should DO things.
+
+**Better approach:** Create a skill for standards, command for action:
+
+```markdown
+---
+description: Generate API documentation for current file
+---
+
+Use the api-documentation skill to generate comprehensive API docs for the current file.
+```
+
+### Pitfall #2: Reimplementing Agent Logic
+
+**Problem:** Commands with complex logic that agents handle better
+
+**Example of wrong pattern:**
+
+```markdown
+---
+description: Run tests
+---
+
+First, scan for test files in src/, tests/, and __tests__.
+Then determine the test framework by checking package.json.
+If Jest, run `npm test`. If pytest, run `pytest -v`.
+Parse the output for failures and categorize by severity...
+```
+
+**Why it's wrong:** Too much logic, too many decisions, better in isolated context.
+
+**Better approach:**
+
+```markdown
+---
+description: Run full test suite
+---
+
+Use the test-runner agent to execute the full test suite and analyze failures.
+```
+
+### Pitfall #3: Overly Complex Arguments
+
+**Problem:** Arguments that need extensive parsing or validation
+
+**Example of questionable pattern:**
+
+```markdown
+/deploy env=staging branch=main force=true rollback=false
+```
+
+**Why it's questionable:** No argument validation, no type checking, brittle parsing.
+
+**Better approach:** Keep arguments simple, let agent handle complexity:
+
+```markdown
+---
+description: Deploy to specified environment
+argument-hint: environment
+---
+
+Deploy to $1 environment. The deployer agent will handle validation, rollback strategy, and confirmation.
+```
+
+### Pitfall #4: Scope Creep
+
+**Problem:** Single command tries to do too much
+
+**Example:**
+
+```markdown
+description: Test, lint, format, commit, and deploy
+```
+
+**Why it fails:** Multiple distinct operations with different failure modes.
+
+**Better:** Separate commands or orchestrator agent that coordinates multiple specialized agents.
+
+## Command Quality Checklist
+
+Before finalizing a command:
+
+**Structure (from official docs):**
+
+- ✓ Valid YAML frontmatter (if used)
+- ✓ Proper markdown formatting
+- ✓ Filename is kebab-case (becomes command name)
+
+**Best Practices (opinionated):**
+
+- ✓ Includes `description` field for discoverability
+- ✓ Uses `argument-hint` if arguments expected
+- ✓ Action-oriented (not knowledge storage)
+- ✓ Delegates to agents for complex logic (file parsing, decision trees, error recovery)
+- ✓ Simple sequential bash is OK (3-5 steps, basic if/else)
+- ✓ Arguments are simple (if present)
+- ✓ Clear, single-purpose design
+- ✓ Appropriate tool restrictions (if needed)
+- ✓ Model choice matches complexity (haiku for simple, sonnet for complex)
+
+## Path Resolution
+
+**Official locations:**
+
+- **Project-level:** `.claude/commands/` (shared with team)
+- **User-level:** `~/.claude/commands/` (personal, all projects)
+- **Plugin context:** `plugins/[name]/commands/` (when creating plugin commands)
+
+**Resolution logic:**
+
+1. If caller specifies exact path → use that
+2. If in plugin context → use `plugins/[name]/commands/`
+3. Default → `.claude/commands/` (project-level)
+4. User-level → only when explicitly requested
+
+## Name Normalization
+
+Command names must be kebab-case (filename without .md extension):
+
+**Transform these:**
+
+- "Run Tests" → `run-tests.md`
+- "create_component" → `create-component.md`
+- "DeployStaging" → `deploy-staging.md`
+
+## Example: Good Command Design
+
+**Before (from hypothetical docs):**
+
+```markdown
+---
+description: Create component
+---
+
+Create a new component.
+```
+
+**Issues:**
+
+- ❌ Description too vague
+- ❌ Prompt lacks specifics
+- ❌ No argument handling when clearly needed
+- ❌ No guidance on structure
+
+**After (applying best practices):**
+
+```markdown
+---
+description: Create a new React component with TypeScript and tests
+argument-hint: component-name
+---
+
+Create a new React component named `$1`.
+
+Requirements:
+- Location: src/components/$1/$1.tsx
+- TypeScript interface for props
+- Proper exports (default and named)
+- Test file: src/components/$1/__tests__/$1.test.tsx
+- Storybook file: src/components/$1/$1.stories.tsx
+
+Follow project conventions:
+- Use existing component patterns as reference
+- Include JSDoc comments
+- Export types separately
+```
+
+**Improvements:**
+
+- ✅ Specific description (React + TypeScript + tests)
+- ✅ Clear argument placeholder and hint
+- ✅ Detailed deliverables listed
+- ✅ References project conventions
+- ✅ Actionable and unambiguous
+
+## Documentation References
+
+These are the authoritative sources. Fetch them before creating commands:
+
+**Core specifications:**
+
+- https://code.claude.com/docs/en/slash-commands.md - Command structure, examples, patterns
+
+**Tool verification:**
+
+- https://code.claude.com/docs/en/settings#tools-available-to-claude - Current tool list
+
+**Model selection:**
+
+- https://code.claude.com/docs/en/model-config.md - Model guidance
+
+**Remember:** Official docs provide structure and features. This skill provides best practices and patterns for creating excellent commands.