Initial commit

skills/prompt-writing/references/artifact-guides/commands.md

@@ -0,0 +1,152 @@
+<commands>
+
+## Command Namespacing
+
+Organize commands in subdirectories. Subdirectory names appear as labels but don't change invocation.
+
+- `commands/command.md` → `/command`
+- `commands/namespace/command.md` → `/command` (labeled with namespace)
+
+## Command File Structure
+
+Command files can contain optional frontmatter followed by the prompt content.
+
+**Frontmatter (Optional but Recommended):**
+
+```yaml
+---
+description: Brief description of what this command does
+argument-hint: [issue-number] [priority]
+allowed-tools: "Bash(git:*), Read, Write"
+model: claude-3-5-haiku-20241022
+disable-model-invocation: false
+---
+```
+
+All frontmatter fields are optional:
+- `description`: Brief description (defaults to first line of prompt). Include this for SlashCommand tool discovery.
+- `argument-hint`: Expected arguments for auto-completion
+- `allowed-tools`: Tools this command can use (inherits from conversation if omitted)
+- `model`: Specific model to use (inherits from conversation if omitted)
+- `disable-model-invocation`: Set to true to prevent SlashCommand tool from calling this command (defaults to false)
+
+**Prompt Content:**
+
+After frontmatter (or if no frontmatter), the markdown content becomes the prompt Claude receives.
+
+Simple example:
+```
+Run the test suite and report any failures in the scratchpad.
+```
+
+Example with frontmatter:
+```yaml
+---
+description: Fix GitHub issues following TDD workflow
+argument-hint: [issue-number]
+allowed-tools: "Bash(gh:*), Read, Write, Edit"
+---
+
+Analyze GitHub issue $ARGUMENTS and create a fix:
+1. Use `gh issue view $ARGUMENTS` to read the issue
+2. Identify the root cause
+3. Implement a fix
+4. Run tests to verify
+```
+
+## Argument Handling
+
+Commands support two argument patterns:
+
+**`$ARGUMENTS` - All arguments as single string:**
+
+Captures everything after the command name as one value.
+
+Example:
+
+- Command file contains: `Fix issue $ARGUMENTS`
+- Invocation: `/fix-issue 123 high-priority`
+- Result: `$ARGUMENTS` becomes `123 high-priority`
+- Claude receives: `Fix issue 123 high-priority`
+
+**Positional Parameters (`$1`, `$2`, `$3`) - Individual arguments:**
+
+Access specific arguments separately, like shell script parameters.
+
+Example:
+
+- Command file contains: `Review PR #$1 with priority $2 assigned to $3`
+- Invocation: `/review-pr 456 high alice`
+- Result: `$1` = `456`, `$2` = `high`, `$3` = `alice`
+- Claude receives: `Review PR #456 with priority high assigned to alice`
+
+**When to use each:**
+
+- `$ARGUMENTS`: All input as single value (commit messages, search queries, issue numbers with descriptions)
+- `$1, $2, $3`: Multiple distinct values (PR number + priority + assignee, file path + operation + output format)
+
+## Special Command Features
+
+**Bash Execution (`!` prefix):**
+
+Execute bash commands before the slash command runs. The output is included in the command context.
+
+Example:
+
+```yaml
+---
+description: Analyze current git status and suggest next steps
+allowed-tools: "Bash(git:*)"
+---
+
+Current git status:
+!`git status --short`
+
+Based on the above status, suggest what to do next.
+```
+
+Note: Requires `allowed-tools` frontmatter with Bash tool specified.
+
+**File References (`@` prefix):**
+
+Include file contents directly in the command context.
+
+Example:
+
+```markdown
+Review the implementation in @src/auth/login.js and suggest improvements.
+```
+
+**Extended Thinking:**
+
+Activate extended thinking by including relevant keywords in command definitions.
+
+Example:
+
+```markdown
+Think deeply about the architecture implications of this change and analyze thoroughly before proposing a solution.
+```
+
+## Commands vs Other Formats
+
+**Command vs Skill:** Command is a prompt stored in `.claude/commands/`, invoked explicitly with `/`. Skill is instructions in a folder, invoked automatically when Claude determines it's relevant.
+
+**Command vs CLAUDE.md:** Command is a prompt you explicitly invoke when needed. CLAUDE.md is context automatically loaded at the start of every conversation.
+
+**Command vs Just Typing:** Command saves typing for repeated prompts, shareable via git. Typing is appropriate for one-off requests or things you don't repeat.
+
+## What Matters When Generating Command Prompts
+
+When your prompt-writing skill generates a prompt for a command, it should:
+
+**Understand the use case:** Is this a repeated workflow? Does it need parameters?
+
+**Be complete:** The prompt should contain all instructions needed. Commands don't have special powers - they're just text that becomes Claude's input.
+
+**Use $ARGUMENTS appropriately:** If the workflow needs input, use `$ARGUMENTS`. If it doesn't, don't include it.
+
+**Be explicit:** Commands execute exactly as written. Don't assume Claude will infer missing steps.
+
+**Consider prompting techniques:** Commands can use any prompting strategy (CoT, Few-Shot, XML, etc.) - they're just prompts in files.
+
+</commands>