aiblueprint-cli 1.4.12 → 1.4.13

package/claude-code-config/skills/create-slash-commands/SKILL.md

@@ -0,0 +1,1110 @@
+---
+name: create-slash-commands
+description: Expert guidance for creating Claude Code slash commands. Use when working with slash commands, creating custom commands, understanding command structure, or learning YAML configuration.
+---
+
+<objective>
+Create effective slash commands for Claude Code that enable users to trigger reusable prompts with `/command-name` syntax. Slash commands expand as prompts in the current conversation, allowing teams to standardize workflows and operations.
+
+Commands can be **global** (available everywhere in `~/.claude/commands/`) or **project-specific** (shared with team in `.claude/commands/`). This skill teaches you to structure commands with proper formatting (XML or Markdown), YAML frontmatter, dynamic context loading, and intelligent argument handling.
+
+**CRITICAL WORKFLOW**: This skill enforces a mandatory research phase where you MUST:
+1. Read all reference documentation
+2. Examine existing slash commands for patterns
+3. Understand syntax and best practices
+4. Only then create the command
+
+This prevents poorly-structured commands and ensures consistency with established patterns.
+</objective>
+
+<quick_start>
+
+<workflow>
+1. Create `.claude/commands/` directory (project) or use `~/.claude/commands/` (personal)
+2. Create `command-name.md` file
+3. Add YAML frontmatter (at minimum: `description`)
+4. Write command prompt
+5. Test with `/command-name [args]`
+</workflow>
+
+<example>
+**File**: `.claude/commands/optimize.md`
+
+```markdown
+---
+description: Analyze this code for performance issues and suggest optimizations
+---
+
+Analyze the performance of this code and suggest three specific optimizations:
+```
+
+**Usage**: `/optimize`
+
+Claude receives the expanded prompt and analyzes the code in context.
+</example>
+</quick_start>
+
+<xml_structure>
+Slash commands can use either XML tags OR Markdown headings in the body (after YAML frontmatter).
+
+**Format choice depends on**:
+- User preference (ask if not specified)
+- Command complexity (XML better for complex, Markdown fine for simple)
+- Existing project patterns (match what's already in use)
+
+See [references/prompt-examples.md](references/prompt-examples.md) for real examples of both formats in production.
+
+<required_tags>
+
+**`<objective>`** - What the command does and why it matters
+
+```markdown
+<objective>
+What needs to happen and why this matters.
+Context about who uses this and what it accomplishes.
+</objective>
+```
+
+**`<process>` or `<steps>`** - How to execute the command
+
+```markdown
+<process>
+Sequential steps to accomplish the objective:
+1. First step
+2. Second step
+3. Final step
+</process>
+```
+
+**`<success_criteria>`** - How to know the command succeeded
+
+```markdown
+<success_criteria>
+Clear, measurable criteria for successful completion.
+</success_criteria>
+```
+
+</required_tags>
+
+<conditional_tags>
+
+**`<context>`** - When loading dynamic state or files
+
+```markdown
+<context>
+Current state: ! `git status`
+Relevant files: @ package.json
+</context>
+```
+
+(Note: Remove the space after @ in actual usage)
+
+**`<verification>`** - When producing artifacts that need checking
+
+```markdown
+<verification>
+Before completing, verify:
+- Specific test or check to perform
+- How to confirm it works
+</verification>
+```
+
+**`<testing>`** - When running tests is part of the workflow
+
+```markdown
+<testing>
+Run tests: ! `npm test`
+Check linting: ! `npm run lint`
+</testing>
+```
+
+**`<output>`** - When creating/modifying specific files
+
+```markdown
+<output>
+Files created/modified:
+- `./path/to/file.ext` - Description
+</output>
+```
+
+</conditional_tags>
+
+<structure_example>
+
+```markdown
+---
+name: example-command
+description: Does something useful
+argument-hint: [input]
+---
+
+<objective>
+Process #$ARGUMENTS to accomplish [goal].
+
+This helps [who] achieve [outcome].
+</objective>
+
+<context>
+Current state: ! `relevant command`
+Files: @ relevant/files
+</context>
+
+<process>
+1. Parse #$ARGUMENTS
+2. Execute operation
+3. Verify results
+</process>
+
+<success_criteria>
+
+- Operation completed without errors
+- Output matches expected format
+  </success_criteria>
+```
+
+</structure_example>
+
+<intelligence_rules>
+
+**Simple commands** (single operation, no artifacts):
+
+- Required: `<objective>`, `<process>`, `<success_criteria>`
+- Example: `/check-todos`, `/first-principles`
+
+**Complex commands** (multi-step, produces artifacts):
+
+- Required: `<objective>`, `<process>`, `<success_criteria>`
+- Add: `<context>` (if loading state), `<verification>` (if creating files), `<output>` (what gets created)
+- Example: `/commit`, `/create-prompt`, `/run-prompt`
+
+**Commands with dynamic arguments**:
+
+- Use `#$ARGUMENTS` in `<objective>` or `<process>` tags
+- Include `argument-hint` in frontmatter
+- Make it clear what the arguments are for
+
+**Commands that produce files**:
+
+- Always include `<output>` tag specifying what gets created
+- Always include `<verification>` tag with checks to perform
+
+**Commands that run tests/builds**:
+
+- Include `<testing>` tag with specific commands
+- Include pass/fail criteria in `<success_criteria>`
+  </intelligence_rules>
+  </xml_structure>
+
+<arguments_intelligence>
+The skill should intelligently determine whether a slash command needs arguments.
+
+<commands_that_need_arguments>
+
+**User provides specific input:**
+
+- `/fix-issue [issue-number]` - Needs issue number
+- `/review-pr [pr-number]` - Needs PR number
+- `/optimize [file-path]` - Needs file to optimize
+- `/commit [type]` - Needs commit type (optional)
+
+**Pattern:** Task operates on user-specified data
+
+Include `argument-hint: [description]` in frontmatter and reference `#$ARGUMENTS` in the body.
+</commands_that_need_arguments>
+
+<commands_without_arguments>
+
+**Self-contained procedures:**
+
+- `/check-todos` - Operates on known file (TO-DOS.md)
+- `/first-principles` - Operates on current conversation
+- `/whats-next` - Analyzes current context
+
+**Pattern:** Task operates on implicit context (current conversation, known files, project state)
+
+Omit `argument-hint` and don't reference `#$ARGUMENTS`.
+</commands_without_arguments>
+
+<incorporating_arguments>
+
+**In `<objective>` tag:**
+
+```markdown
+<objective>
+Fix issue #$ARGUMENTS following project conventions.
+
+This ensures bugs are resolved systematically with proper testing.
+</objective>
+```
+
+**In `<process>` tag:**
+
+```markdown
+<process>
+1. Understand issue #$ARGUMENTS from issue tracker
+2. Locate relevant code
+3. Implement fix
+4. Add tests
+</process>
+```
+
+**In `<context>` tag:**
+
+```markdown
+<context>
+Issue details: @ issues/#$ARGUMENTS.md
+Related files: ! `grep -r "TODO.*#$ARGUMENTS" src/`
+</context>
+```
+
+(Note: Remove the space after the exclamation mark in actual usage)
+</incorporating_arguments>
+
+<positional_arguments>
+
+For structured input, use `$1`, `$2`, `$3`:
+
+```markdown
+---
+argument-hint: <pr-number> <priority> <assignee>
+---
+
+<objective>
+Review PR #$1 with priority $2 and assign to $3.
+</objective>
+```
+
+**Usage:** `/review-pr 456 high alice`
+</positional_arguments>
+</arguments_intelligence>
+
+<file_structure>
+
+**Project commands**: `.claude/commands/` (in project root)
+
+- Shared with team via version control
+- Project-specific workflows
+- Shows `(project)` in `/help` list
+- Committed to git for team use
+
+**Global commands**: `~/.claude/commands/` (user home directory)
+
+- Available across all your projects
+- Personal productivity commands
+- Shows `(user)` in `/help` list
+- Not shared with team
+
+**File naming**: `command-name.md` → invoked as `/command-name`
+
+**Choosing between global and project**:
+
+- Use **global** for: Personal workflows, general utilities, commands you use everywhere
+- Use **project** for: Team workflows, project-specific operations, shared conventions
+  </file_structure>
+
+<yaml_frontmatter>
+
+<field name="description">
+**Required** - Describes what the command does
+
+```yaml
+description: Analyze this code for performance issues and suggest optimizations
+```
+
+Shown in the `/help` command list.
+</field>
+
+<field name="allowed-tools">
+**Optional** - Restricts which tools Claude can use
+
+```yaml
+allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*)
+```
+
+**Formats**:
+
+- Array: `allowed-tools: [Read, Edit, Write]`
+- Single tool: `allowed-tools: SequentialThinking`
+- Bash restrictions: `allowed-tools: Bash(git add:*)`
+
+If omitted: All tools available
+</field>
+</yaml_frontmatter>
+
+<arguments>
+<all_arguments_string>
+
+**Command file**: `.claude/commands/fix-issue.md`
+
+```markdown
+---
+description: Fix issue following coding standards
+---
+
+Fix issue #$ARGUMENTS following our coding standards
+```
+
+**Usage**: `/fix-issue 123 high-priority`
+
+**Claude receives**: "Fix issue #123 high-priority following our coding standards"
+</all_arguments_string>
+
+<positional_arguments_syntax>
+
+**Command file**: `.claude/commands/review-pr.md`
+
+```markdown
+---
+description: Review PR with priority and assignee
+---
+
+Review PR #$1 with priority $2 and assign to $3
+```
+
+**Usage**: `/review-pr 456 high alice`
+
+**Claude receives**: "Review PR #456 with priority high and assign to alice"
+
+See [references/arguments.md](references/arguments.md) for advanced patterns.
+</positional_arguments_syntax>
+</arguments>
+
+<dynamic_context>
+
+Execute bash commands before the prompt using the exclamation mark prefix directly before backticks (no space between).
+
+**Note:** Examples below show a space after the exclamation mark to prevent execution during skill loading. In actual slash commands, remove the space.
+
+Example:
+
+```markdown
+---
+description: Create a git commit
+allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*)
+---
+
+## Context
+
+- Current git status: ! `git status`
+- Current git diff: ! `git diff HEAD`
+- Current branch: ! `git branch --show-current`
+- Recent commits: ! `git log --oneline -10`
+
+## Your task
+
+Based on the above changes, create a single git commit.
+```
+
+The bash commands execute and their output is included in the expanded prompt.
+</dynamic_context>
+
+<file_references>
+
+Use `@` prefix to reference specific files:
+
+```markdown
+---
+description: Review implementation
+---
+
+Review the implementation in @ src/utils/helpers.js
+```
+
+(Note: Remove the space after @ in actual usage)
+
+Claude can access the referenced file's contents.
+</file_references>
+
+<best_practices>
+
+**1. Always use XML structure**
+
+```yaml
+# All slash commands should have XML-structured bodies
+```
+
+After frontmatter, use XML tags:
+
+- `<objective>` - What and why (always)
+- `<process>` - How to do it (always)
+- `<success_criteria>` - Definition of done (always)
+- Additional tags as needed (see xml_structure section)
+
+**2. Clear descriptions**
+
+```yaml
+# Good
+description: Analyze this code for performance issues and suggest optimizations
+
+# Bad
+description: Optimize stuff
+```
+
+**3. Use dynamic context for state-dependent tasks**
+
+```markdown
+Current git status: ! `git status`
+Files changed: ! `git diff --name-only`
+```
+
+**4. Restrict tools when appropriate**
+
+```yaml
+# For git commands - prevent running arbitrary bash
+allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*)
+
+# For analysis - thinking only
+allowed-tools: SequentialThinking
+```
+
+**5. Use #$ARGUMENTS for flexibility**
+
+```markdown
+Find and fix issue #$ARGUMENTS
+```
+
+**6. Reference relevant files**
+
+```markdown
+Review @ package.json for dependencies
+Analyze @ src/database/\* for schema
+```
+
+(Note: Remove the space after @ in actual usage)
+</best_practices>
+
+<common_patterns>
+
+**Simple analysis command**:
+
+```markdown
+---
+description: Review this code for security vulnerabilities
+---
+
+<objective>
+Review code for security vulnerabilities and suggest fixes.
+</objective>
+
+<process>
+1. Scan code for common vulnerabilities (XSS, SQL injection, etc.)
+2. Identify specific issues with line numbers
+3. Suggest remediation for each issue
+</process>
+
+<success_criteria>
+
+- All major vulnerability types checked
+- Specific issues identified with locations
+- Actionable fixes provided
+  </success_criteria>
+```
+
+**Git workflow with context**:
+
+```markdown
+---
+description: Create a git commit
+allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*)
+---
+
+<objective>
+Create a git commit for current changes following repository conventions.
+</objective>
+
+<context>
+- Current status: ! `git status`
+- Changes: ! `git diff HEAD`
+- Recent commits: ! `git log --oneline -5`
+</context>
+
+<process>
+1. Review staged and unstaged changes
+2. Stage relevant files
+3. Write commit message following recent commit style
+4. Create commit
+</process>
+
+<success_criteria>
+
+- All relevant changes staged
+- Commit message follows repository conventions
+- Commit created successfully
+  </success_criteria>
+```
+
+**Parameterized command**:
+
+```markdown
+---
+description: Fix issue following coding standards
+argument-hint: [issue-number]
+---
+
+<objective>
+Fix issue #$ARGUMENTS following project coding standards.
+
+This ensures bugs are resolved systematically with proper testing.
+</objective>
+
+<process>
+1. Understand the issue described in ticket #$ARGUMENTS
+2. Locate the relevant code in codebase
+3. Implement a solution that addresses root cause
+4. Add appropriate tests
+5. Verify fix resolves the issue
+</process>
+
+<success_criteria>
+
+- Issue fully understood and addressed
+- Solution follows coding standards
+- Tests added and passing
+- No regressions introduced
+  </success_criteria>
+```
+
+**File-specific command**:
+
+```markdown
+---
+description: Optimize code performance
+argument-hint: [file-path]
+---
+
+<objective>
+Analyze performance of @ #$ARGUMENTS and suggest specific optimizations.
+
+This helps improve application performance through targeted improvements.
+</objective>
+
+<process>
+1. Review code in @ #$ARGUMENTS for performance issues
+2. Identify bottlenecks and inefficiencies
+3. Suggest three specific optimizations with rationale
+4. Estimate performance impact of each
+</process>
+
+<success_criteria>
+
+- Performance issues clearly identified
+- Three concrete optimizations suggested
+- Implementation guidance provided
+- Performance impact estimated
+  </success_criteria>
+```
+
+**Usage**: `/optimize src/utils/helpers.js`
+
+See [references/patterns.md](references/patterns.md) for more examples.
+</common_patterns>
+
+<reference_guides>
+
+**Slash command specific references:**
+
+- [arguments.md](references/arguments.md) - #$ARGUMENTS, positional args, parsing strategies
+- [patterns.md](references/patterns.md) - Git workflows, code analysis, file operations, **subagent patterns**
+- [tool-restrictions.md](references/tool-restrictions.md) - Bash patterns, security best practices
+- [prompt-examples.md](references/prompt-examples.md) - Real-world command examples by pattern
+
+**Prompt engineering references from create-prompt skill:**
+
+- [clarity-principles.md](../../create-prompt/references/clarity-principles.md) - Being clear and direct
+- [xml-structure.md](../../create-prompt/references/xml-structure.md) - XML tag usage
+- [few-shot-patterns.md](../../create-prompt/references/few-shot-patterns.md) - Example-based prompting
+- [reasoning-techniques.md](../../create-prompt/references/reasoning-techniques.md) - Chain of thought, step-by-step
+- [system-prompt-patterns.md](../../create-prompt/references/system-prompt-patterns.md) - System prompt templates
+- [anthropic-best-practices.md](../../create-prompt/references/anthropic-best-practices.md) - Claude-specific techniques
+- [context-management.md](../../create-prompt/references/context-management.md) - Context windows, long-horizon reasoning
+- [anti-patterns.md](../../create-prompt/references/anti-patterns.md) - Common mistakes to avoid
+  </reference_guides>
+
+<generation_protocol>
+
+<step_0_mandatory_research>
+**CRITICAL: Complete this research phase BEFORE proceeding to any other steps.**
+
+You MUST read and understand these materials before creating any slash command:
+
+**1. Read ALL reference files in order:**
+
+Use the Read tool to read these files:
+- `references/prompt-examples.md` - Real-world patterns and examples
+- `references/patterns.md` - Verified command patterns
+- `references/arguments.md` - Argument handling examples
+- `references/tool-restrictions.md` - Tool restriction patterns
+
+**2. Examine existing slash commands:**
+
+Use Bash to find and Read existing commands:
+```bash
+find ~/.claude/commands -name "*.md" -type f | head -10
+```
+
+Then Read 2-3 relevant existing commands to understand:
+- How they structure their YAML frontmatter
+- What format they use (XML vs Markdown)
+- How they handle arguments (#$ARGUMENTS vs positional)
+- What tool restrictions they apply
+- How they structure their workflow sections
+
+**3. Identify the right pattern:**
+
+Based on the user's request, match it to one of these patterns from prompt-examples.md:
+- **Pattern 1**: Numbered workflow (git ops, CI, EPCT) - for multi-step processes
+- **Pattern 2**: Reference/docs (CLI wrappers) - for command documentation
+- **Pattern 3**: Section-based analysis (research, investigation) - for analysis tasks
+- **Subagent patterns**: For commands that launch Task tool agents
+- **Hybrid patterns**: Combining multiple approaches
+
+**4. Check for similar existing commands:**
+
+Before creating a new command, check if a similar command already exists:
+```bash
+grep -l "description.*<similar-concept>" ~/.claude/commands/*.md
+```
+
+If a similar command exists, read it to:
+- Avoid duplication
+- Learn from its structure
+- Understand how to differentiate the new command
+
+**VERIFICATION CHECKLIST:**
+
+Before proceeding to step 1, confirm you have:
+- ✅ Read all 4 reference files
+- ✅ Examined at least 2 existing slash commands
+- ✅ Identified which pattern to use
+- ✅ Checked for similar existing commands
+- ✅ Understand the correct syntax (#$ARGUMENTS, tool restrictions, etc.)
+
+**DO NOT PROCEED** until all items are checked. This research phase is non-negotiable and prevents creating poorly structured commands.
+
+</step_0_mandatory_research>
+
+<step_1_analyze_request>
+**Analyze the user's request** to understand what they want:
+
+- What is the command's purpose?
+- Does it need user input (#$ARGUMENTS)?
+- Does it produce files or artifacts?
+- Does it require verification or testing?
+- Is it simple (single-step) or complex (multi-step)?
+- What pattern does it match? (see [references/prompt-examples.md](references/prompt-examples.md))
+
+**Intelligence rule**: Only proceed to questions if critical information is missing. If the request is clear, skip directly to format choice.
+</step_1_analyze_request>
+
+<step_2_ask_questions_if_needed>
+**INTELLIGENCE RULE**: Only ask questions if critical information is truly missing.
+
+If the request is clear, skip directly to scope and format questions. Most requests like "create a command to X" contain enough information to proceed.
+
+**Ask clarifying questions** ONLY if essential information is missing:
+
+Use AskUserQuestion to gather ONLY what's needed:
+
+1. **Command purpose** (if completely unclear):
+   - header: "Purpose"
+   - question: "What should this command do?"
+   - Let user provide via "Other" option
+
+2. **Arguments** (if truly ambiguous - rare):
+   - header: "Arguments"
+   - question: "Does this command need user input?"
+   - options: "Yes - takes arguments", "No - uses context only"
+
+**SKIP questions for**:
+
+- Clear purposes: "create a command to commit and push" → obvious purpose
+- Obvious complexity: "simple command to..." vs "command that monitors and fixes..."
+- Clear arguments: "for [file-path]" → needs args, "to analyze current code" → no args
+- Standard tools: Git commands → Bash(git :\*), file operations → Read/Edit/Write
+
+**Default assumptions** (use unless contradicted):
+
+- Git operations → `Bash(git :*)`
+- Analysis tasks → No tool restrictions
+- File modifications → `Read, Edit, Write`
+- Complex multi-step → Add verification and testing sections
+  </step_2_ask_questions_if_needed>
+
+<step_2b_ask_scope>
+**ALWAYS ask about scope** unless explicitly specified in the request:
+
+Use AskUserQuestion:
+
+- header: "Scope"
+- question: "Where should this command be available?"
+- options:
+  - "Global (all projects)" - description: "Saved to ~/.claude/commands/ - available everywhere"
+  - "Project only" - description: "Saved to .claude/commands/ - shared with team via git"
+
+**Detection rules**:
+
+- If request says "global command" → Skip, use global scope
+- If request says "project command" or "team command" → Skip, use project scope
+- Otherwise → ALWAYS ask
+
+**Important**: This determines the save location:
+
+- Global: `~/.claude/commands/command-name.md`
+- Project: `.claude/commands/command-name.md` (in current working directory)
+  </step_2b_ask_scope>
+
+<step_3_choose_format>
+**Determine format based on existing patterns:**
+
+Before asking the user, check what format existing commands in the target directory use:
+- If creating global command: Check `~/.claude/commands/*.md`
+- If creating project command: Check `.claude/commands/*.md`
+
+Read 2-3 existing commands to see if they use XML or Markdown format.
+
+**Then ask for format preference**:
+
+Use AskUserQuestion:
+
+- header: "Format"
+- question: "What format do you prefer for this slash command?"
+- options:
+  - First option based on what you found: If most commands use Markdown, make "Markdown (matches existing)" the first option
+  - Second option: The alternative format
+  - Include note about what existing commands use
+
+**Recommendation**:
+- Match existing commands format for consistency
+- XML for complex multi-step commands
+- Markdown for simple straightforward commands
+
+See [references/prompt-examples.md](references/prompt-examples.md) for format examples.
+</step_3_choose_format>
+
+<step_4_create_frontmatter>
+**Create YAML frontmatter** based on gathered information:
+
+```yaml
+---
+name: command-name
+description: Clear description of what it does
+argument-hint: [input] # Only if arguments needed
+allowed-tools: [...] # Only if tool restrictions needed
+---
+```
+
+**Frontmatter rules**:
+
+- `description`: Always required, clear and concise
+- `argument-hint`: Include if command takes user input
+- `allowed-tools`: Include if restricting tools for security
+- `model`: Include only if need specific model (haiku for speed, opus for complexity)
+  </step_4_create_frontmatter>
+
+<step_5_create_body>
+**Create command body** in chosen format (XML or Markdown):
+
+<xml_body>
+**Always include:**
+
+- `<objective>` - What and why
+- `<process>` - How to do it (numbered steps)
+- `<success_criteria>` - Definition of done
+
+**Include when relevant:**
+
+- `<context>` - Dynamic state (! `commands`) or file references (@ files)
+- `<verification>` - Checks to perform if creating artifacts
+- `<testing>` - Test commands if tests are part of workflow
+- `<output>` - Files created/modified
+
+**Reference**: Apply prompt engineering best practices from create-prompt skill:
+
+- [clarity-principles.md](../../create-prompt/references/clarity-principles.md) - Being clear and direct
+- [xml-structure.md](../../create-prompt/references/xml-structure.md) - XML tag usage
+- [anthropic-best-practices.md](../../create-prompt/references/anthropic-best-practices.md) - Claude-specific techniques
+  </xml_body>
+
+<markdown_body>
+**Always include:**
+
+- `## Objective` - What and why
+- `## Process` or `## Workflow` - How to do it (numbered list)
+- `## Success Criteria` - Definition of done
+
+**Include when relevant:**
+
+- `## Context` - Dynamic state or file references
+- `## Verification` - Checks to perform if creating artifacts
+- `## Testing` - Test commands if tests are part of workflow
+- `## Output` - Files created/modified
+  </markdown_body>
+  </step_5_create_body>
+
+<step_6_integrate_arguments>
+**Integrate #$ARGUMENTS** if command takes input:
+
+- If user input needed: Add `argument-hint` and use `#$ARGUMENTS` in body
+- If self-contained: Omit `argument-hint` and `#$ARGUMENTS`
+- For structured input: Use positional args `$1`, `$2`, `$3`
+
+**Examples**: See [references/arguments.md](references/arguments.md)
+</step_6_integrate_arguments>
+
+<step_7_apply_intelligence>
+**Apply appropriate complexity level**:
+
+- **Simple commands**: Keep concise (objective + process + success criteria)
+- **Complex commands**: Add context, verification, testing as needed
+- **Don't over-engineer**: Simple tasks stay simple
+- **Don't under-specify**: Complex tasks get full structure
+
+**Pattern matching**: Choose pattern from [references/prompt-examples.md](references/prompt-examples.md):
+
+- Pattern 1: Numbered workflow (git ops, CI, EPCT)
+- Pattern 2: Reference/docs (CLI wrappers)
+- Pattern 3: Section-based analysis (research, investigation)
+  </step_7_apply_intelligence>
+
+<step_8_save_file>
+**Save the command file** based on chosen scope:
+
+**Global scope** (user selected "Global (all projects)"):
+
+- Path: `~/.claude/commands/command-name.md`
+- Available across all projects
+- Personal commands, not shared with team
+
+**Project scope** (user selected "Project only"):
+
+- Path: `.claude/commands/command-name.md` (in current working directory)
+- Shared with team via version control
+- Project-specific commands
+
+**Verification**:
+
+- File created at correct location based on scope
+- YAML frontmatter valid
+- Body follows chosen format consistently
+- All required sections present
+
+**After saving**:
+
+- Confirm location to user
+- Remind them to commit if project scope
+- Provide usage example: `/command-name [args]`
+  </step_8_save_file>
+
+</generation_protocol>
+
+<success_criteria>
+A well-structured slash command meets these criteria:
+
+**YAML Frontmatter**:
+
+- `description` field is clear and concise
+- `argument-hint` present if command accepts arguments
+- `allowed-tools` specified if tool restrictions needed
+
+**XML Structure**:
+
+- All three required tags present: `<objective>`, `<process>`, `<success_criteria>`
+- Conditional tags used appropriately based on complexity
+- No raw markdown headings in body
+- All XML tags properly closed
+
+**Arguments Handling**:
+
+- `#$ARGUMENTS` used when command operates on user-specified data
+- Positional arguments (`$1`, `$2`, etc.) used when structured input needed
+- No `#$ARGUMENTS` reference for self-contained commands
+
+**Functionality**:
+
+- Command expands correctly when invoked
+- Dynamic context loads properly (bash commands, file references)
+- Tool restrictions prevent unauthorized operations
+- Command accomplishes intended purpose reliably
+
+**Quality**:
+
+- Clear, actionable instructions in `<process>` tag or `## Workflow` section
+- Measurable completion criteria in `<success_criteria>` tag or `## Success Criteria` section
+- Appropriate level of detail (not over-engineered for simple tasks)
+- Examples provided when beneficial
+  </success_criteria>
+
+<common_mistakes>
+
+## Critical Anti-Patterns to Avoid
+
+These are common mistakes that result from skipping the mandatory research phase:
+
+### ❌ MISTAKE 1: Skipping the Research Phase
+
+**Wrong**:
+```
+User asks to create /quick-search command
+→ Immediately ask scope/format questions
+→ Create command without reading references or existing commands
+→ Use wrong syntax, wrong format, miss best practices
+```
+
+**Correct**:
+```
+User asks to create /quick-search command
+→ Read all 4 reference files first
+→ Find and examine existing commands (especially /search if it exists)
+→ Understand patterns and syntax
+→ Then ask questions and create command
+```
+
+### ❌ MISTAKE 2: Using Wrong Argument Syntax
+
+**Wrong**:
+```markdown
+---
+description: Quick search
+---
+Answer the question: #args
+```
+
+**Correct**:
+```markdown
+---
+description: Quick search
+argument-hint: <question>
+---
+User: #$ARGUMENTS
+```
+
+The correct syntax is `#$ARGUMENTS` (not `#args`). This is documented in references/arguments.md.
+
+### ❌ MISTAKE 3: Not Checking for Similar Commands
+
+**Wrong**:
+- Create `/quick-search` without checking if `/search` already exists
+- Result: Duplicate functionality, confusion
+
+**Correct**:
+- Check existing commands first: `find ~/.claude/commands -name "*.md"`
+- If similar command exists, read it to understand how to differentiate
+- Consider if the new command is really needed
+
+### ❌ MISTAKE 4: Wrong Format Choice
+
+**Wrong**:
+- User asks for command
+- Randomly choose XML or Markdown without checking existing commands
+- Result: Inconsistent codebase
+
+**Correct**:
+- Check what format existing commands use
+- Match that format for consistency
+- Only deviate if user explicitly requests different format
+
+### ❌ MISTAKE 5: Missing Tool Restrictions
+
+**Wrong**:
+```yaml
+---
+description: Quick search with Haiku model
+model: haiku
+---
+```
+
+**Correct**:
+```yaml
+---
+description: Quick search with Haiku model
+model: haiku
+allowed-tools: [Grep, Glob, Read]
+---
+```
+
+For speed-optimized commands, restrict tools to prevent using slow agents like Task.
+
+### ❌ MISTAKE 6: Not Matching Existing Patterns
+
+**Wrong**:
+- Create unique structure that doesn't match any existing pattern
+- Result: Hard to maintain, unfamiliar to users
+
+**Correct**:
+- Read prompt-examples.md to see verified patterns
+- Match your command to Pattern 1, 2, 3, or hybrid
+- Follow the established structure
+
+### ❌ MISTAKE 7: Not Including "User: #$ARGUMENTS" at the End
+
+**Wrong**:
+```markdown
+---
+description: Search command
+argument-hint: <question>
+---
+
+You are a search specialist.
+
+## Workflow
+1. Search for the answer
+2. Provide results
+```
+
+**Correct**:
+```markdown
+---
+description: Search command
+argument-hint: <question>
+---
+
+You are a search specialist.
+
+## Workflow
+1. Search for the answer
+2. Provide results
+
+---
+
+User: #$ARGUMENTS
+```
+
+Many commands end with `User: #$ARGUMENTS` to properly pass the user's input to the command.
+
+### ❌ MISTAKE 8: Over-Engineering Simple Commands
+
+**Wrong**:
+```markdown
+<objective>Create comprehensive search system</objective>
+<context>Load all git state</context>
+<verification>Run extensive checks</verification>
+<testing>Test all edge cases</testing>
+```
+
+For a simple search command, this is too much.
+
+**Correct**:
+```markdown
+You are a rapid search specialist.
+
+## Workflow
+1. Search
+2. Answer
+
+User: #$ARGUMENTS
+```
+
+Match complexity to the task.
+
+## How to Avoid These Mistakes
+
+**Follow the Step 0 checklist religiously**:
+1. ✅ Read all 4 reference files
+2. ✅ Examine 2-3 existing commands
+3. ✅ Identify the pattern to use
+4. ✅ Check for similar commands
+5. ✅ Understand correct syntax
+
+**If you skip Step 0, you WILL make these mistakes.**
+
+</common_mistakes>