From e5b1b7a8be886965b7d4cb2582fe723511b24a88 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EC=9D=B4=EC=98=81=EC=B0=BD=28piknow=29?= Date: Sat, 25 Oct 2025 23:08:48 +0900 Subject: [PATCH] agent: add make-command for interactive command scaffolding MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Requirement: Create a /make-command slash command to scaffold new Claude Code commands following the official guide. The command should help users create properly structured command files with correct frontmatter, tool permissions, and workflow structure. Implementation: - Created interactive workflow with 4 key questions (Q1: purpose, Q2: workflow steps, Q3: user input, Q4: external systems) - AI analyzes responses to generate description, infer required tools, and structure workflow - Smart tool inference from keywords (GitHubβ†’gh CLI, gitβ†’Bash(git *:*), npmβ†’Bash(npm *:*)) - Shows generated components to user for approval with iteration support - Generates complete command file with frontmatter, usage, workflow, examples, and best practices sections - Includes 4 comprehensive examples showing different scenarios (simple, arguments, iteration, fully interactive) - Command accepts optional command-name argument, all other info collected interactively Resolves #11 πŸ€– Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- .claude/commands/make-command.md | 653 +++++++++++++++++++++++++++++++ 1 file changed, 653 insertions(+) create mode 100644 .claude/commands/make-command.md diff --git a/.claude/commands/make-command.md b/.claude/commands/make-command.md new file mode 100644 index 0000000..1396d24 --- /dev/null +++ b/.claude/commands/make-command.md @@ -0,0 +1,653 @@ +--- +description: "Scaffold new Claude Code commands following official guide" +argument-hint: "[command-name]" +allowed-tools: + - Bash + - Write + - Read + - Glob +--- + +# Make Command + +Scaffold new Claude Code command files with proper frontmatter, structure, and best practices following the official guide at https://docs.claude.com/en/docs/claude-code/slash-commands + +## Usage + +``` +/make-command [command-name] +``` + +**Optional argument:** +- `command-name`: The name of the command (lowercase with hyphens) + - If not provided, you'll be prompted interactively + +**Note**: All other information (description, arguments, tools, workflow) will be collected through interactive questions. + +## Workflow + +### 1. Validate and Collect Command Name + +**Check if `$1` (command name) is provided:** +- If NOT provided, prompt: "What should the command be named? (Use lowercase with hyphens, e.g., 'review-pr')" +- If provided, use `$1` as the command name + +**Validate command name format:** +- Must be lowercase letters, hyphens, and numbers only +- No spaces, underscores, or special characters +- Good examples: `review-pr`, `analyze-code`, `check-deps` +- Bad examples: `Review-PR`, `analyze_code`, `check.deps` + +**Check for existing command:** +- Use Glob to check if `.claude/commands/{command-name}.md` already exists +- If exists, ask: "Command '/{command-name}' already exists at .claude/commands/{command-name}.md. Do you want to overwrite it? (y/n)" +- If user says no, stop and ask for a different name + +### 2. Collect Command Information + +Collect information through 4 key questions to understand what command to generate: + +#### Q1: Command Purpose + +**Prompt**: "What does this command do? Describe its main purpose:" + +**Purpose**: +- This will be used to generate the frontmatter `description` +- Helps understand the command's scope and intent +- Guides tool selection + +**Wait for user response and store it** + +#### Q2: Workflow Steps + +**Prompt**: "What are the main steps this command should perform? (e.g., fetch data, analyze, generate report)" + +**Purpose**: +- Helps structure the Workflow section in the generated file +- Used to infer which tools are needed +- Identifies potential error handling points + +**Examples to show users**: +- "Fetch PR info from GitHub, analyze the diff, generate review summary" +- "Read package.json, check for outdated dependencies, show report" +- "Create branch from issue info, validate name, checkout" + +**Wait for user response and store it** + +#### Q3: User Input Requirements + +**Prompt**: "Does this command need input from the user?" + +**Options**: +- `none` - No input needed, command runs independently +- `arguments` - Command-line arguments (e.g., PR number, file path, flags) +- `interactive` - Interactive prompts during execution + +**Wait for user response** + +**If user selects "arguments":** +- **Prompt**: "What arguments? Provide format (e.g., ` [--detailed]`)" +- **Show examples from existing commands**: + - ` [--no-review]` (from plan-issue) + - `[template-type] [issue-title]` (from make-task-issue) + - `[]: \n#` (from make-branch) +- **Explain notation**: Use `` for required args, `[optional]` for optional args +- **Store the argument-hint for frontmatter** + +**If user selects "none" or "interactive":** +- No argument-hint needed (will be omitted from frontmatter) + +#### Q4: External System Interaction + +**Prompt**: "Does this command interact with external systems? (e.g., git, GitHub via gh CLI, npm, file system)" + +**Purpose**: +- Determines if specific Bash permissions are needed (e.g., `Bash(git *:*)`) +- Identifies additional tools required +- Helps with error handling (network issues, authentication, etc.) + +**Examples**: +- "Yes, GitHub via gh CLI" +- "Yes, git for branch operations" +- "No, just file operations" +- "Yes, npm for dependency checks" + +**Wait for user response and store it** + +### 3. AI Analysis and Generation + +After collecting all information from the 4 questions, analyze and generate command components: + +#### Generate Description + +**From Q1 response, create concise description:** +- Extract the core purpose +- Make it action-oriented (start with a verb) +- Keep under 80 characters for readability +- Should work well in help text + +**Examples:** +- User: "Reviews GitHub pull requests and provides detailed analysis" + β†’ Description: "Review GitHub pull requests with detailed analysis" +- User: "This command helps analyze project dependencies for security issues" + β†’ Description: "Analyze project dependencies for security vulnerabilities" +- User: "Creates branch from issue information" + β†’ Description: "Create branch from GitHub issue information" + +#### Infer Required Tools + +**Based on Q2 (workflow steps) and Q4 (external systems), determine tools:** + +**Pattern matching:** +- Mentioned "GitHub" or "gh" or "pull request" or "issue" + β†’ Add `Bash(gh pr *:*)`, `Bash(gh issue *:*)` or general `Bash(gh *:*)` +- Mentioned "git" or "branch" or "commit" + β†’ Add `Bash(git *:*)` +- Mentioned "npm" or "package.json" or "dependencies" + β†’ Add `Bash(npm *:*)` +- Mentioned "read files" or "analyze code" or "search" + β†’ Add `Read`, `Grep`, `Glob` +- Mentioned "create files" or "generate" + β†’ Add `Write` +- Mentioned "modify files" or "update" + β†’ Add `Edit` +- Mentioned "other commands" or "slash commands" + β†’ Add `SlashCommand` +- Mentioned "complex analysis" or "agent" + β†’ Add `Task` + +**Default fallback:** +- If unclear or simple command: `[Bash, Read, Glob, Grep]` + +**Validation:** +- Ensure tools are in proper YAML list format +- Use specific Bash permissions for security (e.g., `Bash(git *:*)` not just `Bash`) +- Only include tools that are actually needed + +#### Structure Workflow + +**From Q2 response, break down into numbered steps:** + +**Pattern:** +1. If arguments exist (from Q3), start with validation step: + - "Validate {argument-name} from `$1`" +2. Convert user's workflow description into concrete steps +3. Add error handling points where needed +4. Include output/result step at the end + +**Example:** +- User Q2: "Fetch PR info from GitHub, get the diff, analyze changes, show summary" +- User Q3: "arguments" with `` +- Generated workflow: + 1. Validate PR number from `$1` + 2. Fetch PR information using `gh pr view` + 3. Get PR diff using `gh pr diff` + 4. Analyze code changes + 5. Generate and display review summary + +#### Present for Approval + +**Show generated components to user:** + +``` +Based on your input, I'll generate: + +Description: "{generated-description}" + +Allowed Tools: + - {tool-1} + - {tool-2} + - {tool-3} + +Workflow Structure: +1. {step-1} +2. {step-2} +3. {step-3} + +Does this look correct? (y/n or describe changes needed) +``` + +**Handle user response:** + +**If user says "y" or "yes":** +- Proceed to file generation (Section 4) + +**If user says "n" or "no" or provides specific feedback:** +- Ask: "What would you like to change? (description/tools/workflow/all)" +- Based on response, allow user to modify specific parts +- Re-generate and show updated version +- Ask for approval again +- Repeat until approved + +**Examples of iteration:** +- User: "Add Write tool, I need to create files" + β†’ Add `Write` to tools list, show updated version +- User: "Description should mention 'automated' analysis" + β†’ Regenerate description with that keyword +- User: "Workflow should also check for conflicts" + β†’ Add conflict checking step to workflow + +### 4. Generate Command File + +**Create the command file structure:** + +Use the Write tool to create `.claude/commands/{command-name}.md` with: + +**Use AI-generated information from Section 3:** +- Description: AI-generated from Q1 +- Tools: AI-inferred from Q2 and Q4 +- Argument-hint: From Q3 (if user selected "arguments") +- Workflow: AI-structured from Q2 + +**Frontmatter section:** +```yaml +--- +description: "{AI-generated-description}" +argument-hint: "{from Q3 if arguments, otherwise omit this line}" +allowed-tools: + {AI-suggested tools in YAML format} +--- +``` + +**Content sections:** + +```markdown +# {Command Name as Title Case} + +{Expanded description based on Q1 and Q2 responses} + +## Usage + +``` +/{command-name} {argument-hint from Q3 or empty if none} +``` + +{If has arguments, explain what each argument does based on Q3} + +## Workflow + +{Use AI-structured workflow from Section 3} + +### 1. {First step from AI-generated workflow} +{Add details based on Q2 response} + +{If has arguments from Q3:} +**Check if `$1` is provided:** +- If NOT provided, prompt: "{appropriate question}" +- If provided, use `$1` as {what it represents} + +### 2. {Second step from AI-generated workflow} +{Add implementation details} + +{Continue for all steps in AI-generated workflow} + +## Examples + +{Generate 2-3 concrete examples based on Q1, Q2, and Q3} + +### Example 1: {Scenario based on Q1} +```bash +/{command-name} {example arguments if applicable} +``` + +This will: +1. {Outcomes based on AI-structured workflow} +2. {Step 2 outcome} + +### Example 2: {Different scenario} +```bash +/{command-name} {different example arguments} +``` + +## Implementation Notes + +{Optional section - add if relevant based on Q4} + +- Tool usage: {Notes about external systems from Q4} +- Reference: https://docs.claude.com/en/docs/claude-code/slash-commands +- Related commands: {Suggest similar commands if applicable} + +{If arguments exist, add comment about argument patterns:} + +``` + +**Quality guidelines for generation:** +- Make workflow steps concrete and actionable +- Include validation steps for arguments +- Add error handling notes where appropriate +- Use examples that match the command's purpose from Q1 +- Reference tools that were inferred in Section 3 + +### 5. Display Success Message + +**After file is created, display:** + +``` +βœ“ Command created successfully! + +File: .claude/commands/{command-name}.md +Usage: /{command-name} {argument-hint} + +Next steps: +1. Review and customize the generated file +2. Add specific workflow steps and examples +3. Test the command: /{command-name} +4. Refer to https://docs.claude.com/en/docs/claude-code/slash-commands for advanced features + +Tip: Check existing commands in .claude/commands/ for patterns and examples. +``` + +## Error Handling + +**Invalid command name:** +- Detect uppercase letters, underscores, spaces, special characters +- Show error: "Invalid command name '{name}'. Use lowercase with hyphens only (e.g., 'review-pr')" +- Ask for corrected name + +**File already exists:** +- Show warning with file path +- Ask for confirmation to overwrite +- Suggest alternative name if user declines + +**Invalid tool syntax:** +- Detect malformed Bash command patterns +- Show error: "Invalid tool syntax. Use format like: Bash(git *:*) or Bash(gh issue *:*)" +- Show examples and ask for correction + +**Write permission issues:** +- If Write fails, show error: "Cannot write to .claude/commands/. Check directory permissions." +- Suggest running with appropriate permissions + +**Missing required information:** +- If user skips required prompts, re-ask with more guidance +- Show examples to help user understand what's needed + +## Examples + +### Example 1: Simple command (no arguments) + +```bash +/make-command hello-world +``` + +**Interactive flow:** + +``` +βœ“ Command name validated +βœ“ No conflicts found + +Q1: What does this command do? Describe its main purpose: +A: "Prints a hello world message to test the command system" + +Q2: What are the main steps this command should perform? +A: "Just print 'Hello World' to the console" + +Q3: Does this command need input from the user? +A: "none" + +Q4: Does this command interact with external systems? +A: "no" + +[AI Analysis] +Based on your input, I'll generate: + +Description: "Print hello world message" + +Allowed Tools: + - Bash + +Workflow Structure: +1. Print "Hello World" message to console + +Does this look correct? (y/n or describe changes needed) +A: "y" + +βœ“ Command created at .claude/commands/hello-world.md +Usage: /hello-world +``` + +Generated file: `.claude/commands/hello-world.md` + +### Example 2: GitHub PR review command with arguments + +```bash +/make-command review-pr +``` + +**Interactive flow:** + +``` +βœ“ Command name validated +βœ“ No conflicts found + +Q1: What does this command do? Describe its main purpose: +A: "Reviews GitHub pull requests and provides detailed analysis of the code changes" + +Q2: What are the main steps this command should perform? +A: "Fetch PR info from GitHub using gh CLI, get the diff, analyze the changes for potential issues, generate a review summary" + +Q3: Does this command need input from the user? +A: "arguments" + +Q3a: What arguments? Provide format: +A: " [--detailed]" + +Q4: Does this command interact with external systems? +A: "Yes, GitHub via gh CLI" + +[AI Analysis] +Based on your input, I'll generate: + +Description: "Review GitHub pull requests with detailed analysis" + +Allowed Tools: + - Bash(gh pr view:*) + - Bash(gh pr diff:*) + - Read + - Grep + +Workflow Structure: +1. Validate PR number from $1 +2. Check for --detailed flag from $2 +3. Fetch PR information using gh pr view +4. Get PR diff using gh pr diff +5. Analyze code changes for issues +6. Generate and display review summary + +Does this look correct? (y/n or describe changes needed) +A: "y" + +βœ“ Command created at .claude/commands/review-pr.md +Usage: /review-pr [--detailed] +``` + +Generated file: `.claude/commands/review-pr.md` + +### Example 3: With iteration (user requests changes) + +```bash +/make-command analyze-deps +``` + +**Interactive flow:** + +``` +βœ“ Command name validated +βœ“ No conflicts found + +Q1: What does this command do? Describe its main purpose: +A: "Checks npm dependencies for security vulnerabilities and outdated packages" + +Q2: What are the main steps this command should perform? +A: "Read package.json, run npm audit, check for outdated packages, show report" + +Q3: Does this command need input from the user? +A: "none" + +Q4: Does this command interact with external systems? +A: "Yes, npm for audit and outdated check" + +[AI Analysis] +Based on your input, I'll generate: + +Description: "Check npm dependencies for security vulnerabilities" + +Allowed Tools: + - Bash(npm audit:*) + - Bash(npm outdated:*) + - Read + +Workflow Structure: +1. Read package.json to verify project +2. Run npm audit for security check +3. Run npm outdated for version check +4. Generate combined report + +Does this look correct? (y/n or describe changes needed) +A: "Add Glob tool, I might need to search for other package files" + +[Updated AI Analysis] +Description: "Check npm dependencies for security vulnerabilities" + +Allowed Tools: + - Bash(npm audit:*) + - Bash(npm outdated:*) + - Read + - Glob + +Workflow Structure: +1. Search for package.json files using Glob +2. Read package.json to verify project +3. Run npm audit for security check +4. Run npm outdated for version check +5. Generate combined report + +Does this look correct? (y/n or describe changes needed) +A: "y" + +βœ“ Command created at .claude/commands/analyze-deps.md +Usage: /analyze-deps +``` + +Generated file: `.claude/commands/analyze-deps.md` + +### Example 4: Fully interactive (no command name provided) + +```bash +/make-command +``` + +**Interactive flow:** + +``` +Q: What should the command be named? (Use lowercase with hyphens) +A: "test-api" + +βœ“ Command name validated +βœ“ No conflicts found + +Q1: What does this command do? Describe its main purpose: +A: "Tests API endpoints to verify they're working correctly" + +Q2: What are the main steps this command should perform? +A: "Read API config, make test requests to endpoints, validate responses, show results" + +Q3: Does this command need input from the user? +A: "interactive" + +Q4: Does this command interact with external systems? +A: "Yes, makes HTTP requests to API endpoints" + +[AI Analysis] +Based on your input, I'll generate: + +Description: "Test API endpoints and validate responses" + +Allowed Tools: + - Bash + - Read + - Grep + +Workflow Structure: +1. Read API configuration file +2. Prompt user for which endpoints to test +3. Make HTTP requests to selected endpoints +4. Validate response status and structure +5. Display test results + +Does this look correct? (y/n or describe changes needed) +A: "y" + +βœ“ Command created at .claude/commands/test-api.md +Usage: /test-api +``` + +Generated file: `.claude/commands/test-api.md` + +## Best Practices + +**Information Gathering:** +- Ask clear, focused questions one at a time +- Provide examples to guide users (especially for Q2 and Q3) +- Listen carefully to user responses to infer context +- Be smart about tool inference from keywords +- Show what will be generated before creating files +- Allow iteration until user is satisfied +- Don't assume - confirm with user approval + +**AI Inference Patterns:** +- "GitHub" / "gh" / "PR" / "issue" β†’ `Bash(gh *:*)` +- "git" / "branch" / "commit" β†’ `Bash(git *:*)` +- "npm" / "package.json" β†’ `Bash(npm *:*)`, `Read` +- "read" / "analyze" / "search" β†’ `Read`, `Grep`, `Glob` +- "create file" / "generate" β†’ `Write` +- "modify" / "update file" β†’ `Edit` +- When uncertain β†’ `[Bash, Read, Glob, Grep]` + +**Command naming:** +- Use action verbs: `review-pr`, `analyze-code`, `check-deps` +- Keep names short but descriptive +- Use hyphens for multi-word names + +**Description generation:** +- Extract core action from Q1 (user's purpose) +- Start with a verb: "Review", "Analyze", "Create", "Update" +- Keep under 80 characters +- Be specific but concise +- Match the scope described by user + +**Arguments:** +- Use `` and `[optional]` notation clearly +- Provide argument hints for better autocomplete +- Document what each argument does in the Usage section +- Show examples from existing commands to guide users + +**Tool selection:** +- Only include tools the command actually needs +- Use specific Bash patterns for security (e.g., `Bash(git *:*)` not just `Bash`) +- Prefer specific over general permissions +- Validate tool combinations make sense together + +**Workflow generation:** +- Start with argument validation if arguments exist +- Break user's Q2 response into concrete, actionable steps +- Add error handling at logical points +- Include output/result step at the end +- Make steps specific to the command's purpose + +**Documentation:** +- Generate examples based on user's Q1 and Q2 responses +- Include concrete scenarios from user's description +- Explain the workflow step-by-step +- Reference tools that were inferred +- Add implementation notes if Q4 mentions external systems + +## Reference + +- Official guide: https://docs.claude.com/en/docs/claude-code/slash-commands +- Existing commands: [make-branch.md](/.claude/commands/make-branch.md), [make-commit.md](/.claude/commands/make-commit.md), [make-pr.md](/.claude/commands/make-pr.md), [make-task-issue.md](/.claude/commands/make-task-issue.md), [plan-issue.md](/.claude/commands/plan-issue.md) +- Frontmatter fields: description (required), argument-hint, allowed-tools, model, disable-model-invocation