diff --git a/.agents/skills/cloudflare/references/waf/api.md b/.agents/skills/cloudflare/references/waf/api.md index f58964f..564d362 100644 --- a/.agents/skills/cloudflare/references/waf/api.md +++ b/.agents/skills/cloudflare/references/waf/api.md @@ -105,7 +105,7 @@ contains; // Substring match matches; // Regex match (use carefully) starts_with; // Prefix match ends_with in // Suffix match -// Value in list + // Value in list // List operations not; // Logical NOT and; // Logical AND diff --git a/.agents/skills/command-development/README.md b/.agents/skills/command-development/README.md index a5d303f..746cb98 100644 --- a/.agents/skills/command-development/README.md +++ b/.agents/skills/command-development/README.md @@ -5,6 +5,7 @@ Comprehensive guidance on creating Claude Code slash commands, including file fo ## Overview This skill provides knowledge about: + - Slash command file format and structure - YAML frontmatter configuration fields - Dynamic arguments ($ARGUMENTS, $1, $2, etc.) @@ -23,6 +24,7 @@ This skill provides knowledge about: Core skill content covering: **Fundamentals:** + - Command basics and locations - File format (Markdown with optional frontmatter) - YAML frontmatter fields overview @@ -34,6 +36,7 @@ Core skill content covering: - Troubleshooting **Plugin-Specific:** + - ${CLAUDE_PLUGIN_ROOT} environment variable - Plugin command discovery and organization - Plugin command patterns (configuration, template, multi-script) @@ -82,6 +85,7 @@ Practical command examples: ## When This Skill Triggers Claude Code activates this skill when users: + - Ask to "create a slash command" or "add a command" - Need to "write a custom command" - Want to "define command arguments" @@ -122,6 +126,7 @@ allowed-tools: Read, Bash(git:*) --- Command prompt content with: + - Arguments: $1, $2, or $ARGUMENTS - Files: @path/to/file - Bash: !`command here` @@ -136,24 +141,27 @@ Command prompt content with: ### Key Features **Dynamic arguments:** + - `$ARGUMENTS` - All arguments as single string - `$1`, `$2`, `$3` - Positional arguments **File references:** + - `@path/to/file` - Include file contents **Bash execution:** + - `!`command`` - Execute and include output ## Frontmatter Fields Quick Reference -| Field | Purpose | Example | -|-------|---------|---------| -| `description` | Brief description for /help | `"Review code for issues"` | -| `allowed-tools` | Restrict tool access | `Read, Bash(git:*)` | -| `model` | Specify model | `sonnet`, `opus`, `haiku` | -| `argument-hint` | Document arguments | `[pr-number] [priority]` | -| `disable-model-invocation` | Manual-only command | `true` | +| Field | Purpose | Example | +| -------------------------- | --------------------------- | -------------------------- | +| `description` | Brief description for /help | `"Review code for issues"` | +| `allowed-tools` | Restrict tool access | `Read, Bash(git:*)` | +| `model` | Specify model | `sonnet`, `opus`, `haiku` | +| `argument-hint` | Document arguments | `[pr-number] [priority]` | +| `disable-model-invocation` | Manual-only command | `true` | ## Common Patterns @@ -243,11 +251,13 @@ Recent commits: !`git log --oneline -5` ## Status **Completed enhancements:** + - ✓ Plugin command patterns (${CLAUDE_PLUGIN_ROOT}, discovery, organization) - ✓ Integration patterns (agents, skills, hooks coordination) - ✓ Validation patterns (input, file, resource validation, error handling) **Remaining enhancements (in progress):** + - Advanced workflows (multi-step command sequences) - Testing strategies (how to test commands effectively) - Documentation patterns (command documentation best practices) @@ -256,6 +266,7 @@ Recent commits: !`git log --oneline -5` ## Maintenance To update this skill: + 1. Keep SKILL.md focused on core fundamentals 2. Move detailed specifications to references/ 3. Add new examples/ for different use cases @@ -266,6 +277,7 @@ To update this skill: ## Version History **v0.1.0** (2025-01-15): + - Initial release with basic command fundamentals - Frontmatter field reference - 10 simple command examples diff --git a/.agents/skills/command-development/SKILL.md b/.agents/skills/command-development/SKILL.md index e39435e..cbd21cd 100644 --- a/.agents/skills/command-development/SKILL.md +++ b/.agents/skills/command-development/SKILL.md @@ -11,6 +11,7 @@ version: 0.2.0 Slash commands are frequently-used prompts defined as Markdown files that Claude executes during interactive sessions. Understanding command structure, frontmatter options, and dynamic features enables creating powerful, reusable workflows. **Key concepts:** + - Markdown file format for commands - YAML frontmatter for configuration - Dynamic arguments and file references @@ -22,6 +23,7 @@ Slash commands are frequently-used prompts defined as Markdown files that Claude ### What is a Slash Command? A slash command is a Markdown file containing a prompt that Claude executes when invoked. Commands provide: + - **Reusability**: Define once, use repeatedly - **Consistency**: Standardize common workflows - **Sharing**: Distribute across team or projects @@ -34,8 +36,10 @@ A slash command is a Markdown file containing a prompt that Claude executes when When a user invokes `/command-name`, the command content becomes Claude's instructions. Write commands as directives TO Claude about what to do, not as messages TO the user. **Correct approach (instructions for Claude):** + ```markdown Review this code for security vulnerabilities including: + - SQL injection - XSS attacks - Authentication issues @@ -44,6 +48,7 @@ Provide specific line numbers and severity ratings. ``` **Incorrect approach (messages to user):** + ```markdown This command will review your code for security issues. You'll receive a report with vulnerability details. @@ -54,18 +59,21 @@ The first example tells Claude what to do. The second tells the user what will h ### Command Locations **Project commands** (shared with team): + - Location: `.claude/commands/` - Scope: Available in specific project - Label: Shown as "(project)" in `/help` - Use for: Team workflows, project-specific tasks **Personal commands** (available everywhere): + - Location: `~/.claude/commands/` - Scope: Available in all projects - Label: Shown as "(user)" in `/help` - Use for: Personal workflows, cross-project utilities **Plugin commands** (bundled with plugins): + - Location: `plugin-name/commands/` - Scope: Available when plugin installed - Label: Shown as "(plugin-name)" in `/help` @@ -85,8 +93,10 @@ Commands are Markdown files with `.md` extension: ``` **Simple command:** + ```markdown Review this code for security vulnerabilities including: + - SQL injection - XSS attacks - Authentication bypass @@ -138,6 +148,7 @@ allowed-tools: Read, Write, Edit, Bash(git:*) ``` **Patterns:** + - `Read, Write, Edit` - Specific tools - `Bash(git:*)` - Bash with git commands only - `*` - All tools (rarely needed) @@ -157,6 +168,7 @@ model: haiku ``` **Use cases:** + - `haiku` - Fast, simple commands - `sonnet` - Standard workflows - `opus` - Complex analysis @@ -174,6 +186,7 @@ argument-hint: [pr-number] [priority] [assignee] ``` **Benefits:** + - Helps users understand command arguments - Improves command discovery - Documents command interface @@ -208,12 +221,14 @@ Fix issue #$ARGUMENTS following our coding standards and best practices. ``` **Usage:** + ``` > /fix-issue 123 > /fix-issue 456 ``` **Expands to:** + ``` Fix issue #123 following our coding standards... Fix issue #456 following our coding standards... @@ -234,11 +249,13 @@ After review, assign to $3 for follow-up. ``` **Usage:** + ``` > /review-pr 123 high alice ``` **Expands to:** + ``` Review pull request #123 with priority level high. After review, assign to alice for follow-up. @@ -253,11 +270,13 @@ Deploy $1 to $2 environment with options: $3 ``` **Usage:** + ``` > /deploy api staging --force --skip-tests ``` **Expands to:** + ``` Deploy api to staging environment with options: --force --skip-tests ``` @@ -275,12 +294,14 @@ argument-hint: [file-path] --- Review @$1 for: + - Code quality - Best practices - Potential bugs ``` **Usage:** + ``` > /review-file src/api/users.ts ``` @@ -295,6 +316,7 @@ Reference multiple files: Compare @src/old-version.js with @src/new-version.js Identify: + - Breaking changes - New features - Bug fixes @@ -308,6 +330,7 @@ Reference known files without arguments: Review @package.json and @tsconfig.json for consistency Ensure: + - TypeScript version matches - Dependencies are aligned - Build configuration is correct @@ -318,6 +341,7 @@ Ensure: Commands can execute bash commands inline to dynamically gather context before Claude processes the command. This is useful for including repository state, environment information, or project-specific context. **When to use:** + - Include dynamic context (git status, environment vars, etc.) - Gather project/repository state - Build context-aware workflows @@ -361,6 +385,7 @@ Organize commands in subdirectories: ``` **Benefits:** + - Logical grouping by category - Namespace shown in `/help` - Easier to find related commands @@ -390,8 +415,8 @@ argument-hint: [pr-number] --- $IF($1, - Review PR #$1, - Please provide a PR number. Usage: /review-pr [number] +Review PR #$1, +Please provide a PR number. Usage: /review-pr [number] ) ``` @@ -444,6 +469,7 @@ allowed-tools: Read, Bash(git:*) Files changed: !`git diff --name-only` Review each file for: + 1. Code quality and style 2. Potential bugs or issues 3. Test coverage @@ -475,6 +501,7 @@ argument-hint: [source-file] --- Generate comprehensive documentation for @$1 including: + - Function/class descriptions - Parameter documentation - Return value descriptions @@ -502,23 +529,27 @@ PR #$1 Workflow: ## Troubleshooting **Command not appearing:** + - Check file is in correct directory - Verify `.md` extension present - Ensure valid Markdown format - Restart Claude Code **Arguments not working:** + - Verify `$1`, `$2` syntax correct - Check `argument-hint` matches usage - Ensure no extra spaces **Bash execution failing:** + - Check `allowed-tools` includes Bash - Verify command syntax in backticks - Test command in terminal first - Check for required permissions **File references not working:** + - Verify `@` syntax correct - Check file path is valid - Ensure Read tool allowed @@ -531,6 +562,7 @@ PR #$1 Workflow: Plugin commands have access to `${CLAUDE_PLUGIN_ROOT}`, an environment variable that resolves to the plugin's absolute path. **Purpose:** + - Reference plugin files portably - Execute plugin scripts - Load plugin configuration @@ -553,19 +585,24 @@ Review results and report findings. ```markdown # Execute plugin script + !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/script.sh` # Load plugin configuration + @${CLAUDE_PLUGIN_ROOT}/config/settings.json # Use plugin template + @${CLAUDE_PLUGIN_ROOT}/templates/report.md # Access plugin resources + @${CLAUDE_PLUGIN_ROOT}/docs/reference.md ``` **Why use it:** + - Works across all installations - Portable between systems - No hardcoded paths needed @@ -586,12 +623,14 @@ plugin-name/ ``` **Namespace benefits:** + - Logical command grouping - Shown in `/help` output - Avoid name conflicts - Organize related commands **Naming conventions:** + - Use descriptive action names - Avoid generic names (test, run) - Consider plugin-specific prefix @@ -661,17 +700,20 @@ argument-hint: [file-path] Initiate comprehensive review of @$1 using the code-reviewer agent. The agent will analyze: + - Code structure - Security issues - Performance - Best practices Agent uses plugin resources: + - ${CLAUDE_PLUGIN_ROOT}/config/rules.json - ${CLAUDE_PLUGIN_ROOT}/checklists/review.md ``` **Key points:** + - Agent must exist in `plugin/agents/` directory - Claude uses Task tool to launch agent - Document agent capabilities @@ -690,6 +732,7 @@ argument-hint: [api-file] Document API in @$1 following plugin standards. Use the api-docs-standards skill to ensure: + - Complete endpoint documentation - Consistent formatting - Example quality @@ -699,6 +742,7 @@ Generate production-ready API docs. ``` **Key points:** + - Skill must exist in `plugin/skills/` directory - Mention skill name to trigger invocation - Document skill purpose @@ -707,6 +751,7 @@ Generate production-ready API docs. ### Hook Coordination Design commands that work with plugin hooks: + - Commands can prepare state for hooks to process - Hooks execute automatically on tool events - Commands should document expected hook behavior @@ -743,6 +788,7 @@ Compile findings into report following template. ``` **When to use:** + - Complex multi-step workflows - Leverage multiple plugin capabilities - Require specialized analysis @@ -763,10 +809,10 @@ argument-hint: [environment] Validate environment: !`echo "$1" | grep -E "^(dev|staging|prod)$" || echo "INVALID"` If $1 is valid environment: - Deploy to $1 +Deploy to $1 Otherwise: - Explain valid environments: dev, staging, prod - Show usage: /deploy [environment] +Explain valid environments: dev, staging, prod +Show usage: /deploy [environment] ``` ### File Existence Checks @@ -780,11 +826,11 @@ argument-hint: [config-file] Check file exists: !`test -f $1 && echo "EXISTS" || echo "MISSING"` If file exists: - Process configuration: @$1 +Process configuration: @$1 Otherwise: - Explain where to place config file - Show expected format - Provide example configuration +Explain where to place config file +Show expected format +Provide example configuration ``` ### Plugin Resource Validation @@ -796,6 +842,7 @@ allowed-tools: Bash(test:*) --- Validate plugin setup: + - Script: !`test -x ${CLAUDE_PLUGIN_ROOT}/bin/analyze && echo "✓" || echo "✗"` - Config: !`test -f ${CLAUDE_PLUGIN_ROOT}/config.json && echo "✓" || echo "✗"` @@ -814,14 +861,15 @@ allowed-tools: Bash(*) Execute build: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/build.sh 2>&1 || echo "BUILD_FAILED"` If build succeeded: - Report success and output location +Report success and output location If build failed: - Analyze error output - Suggest likely causes - Provide troubleshooting steps +Analyze error output +Suggest likely causes +Provide troubleshooting steps ``` **Best practices:** + - Validate early in command - Provide helpful error messages - Suggest corrective actions diff --git a/.agents/skills/command-development/examples/plugin-commands.md b/.agents/skills/command-development/examples/plugin-commands.md index e14ef4d..5800b58 100644 --- a/.agents/skills/command-development/examples/plugin-commands.md +++ b/.agents/skills/command-development/examples/plugin-commands.md @@ -35,6 +35,7 @@ Analyze @$1 using plugin's quality checker: !`node ${CLAUDE_PLUGIN_ROOT}/scripts/quality-check.js $1` Review the analysis output and provide: + 1. Summary of findings 2. Priority issues to address 3. Suggested improvements @@ -42,6 +43,7 @@ Review the analysis output and provide: ``` **Key features:** + - Uses `${CLAUDE_PLUGIN_ROOT}` for portable path - Combines file reference with script execution - Simple single-purpose command @@ -74,6 +76,7 @@ Running complete audit on $1: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/best-practices.sh $1` Analyze all results and create comprehensive report including: + - Critical issues requiring immediate attention - Performance optimization opportunities - Security vulnerabilities and fixes @@ -81,6 +84,7 @@ Analyze all results and create comprehensive report including: ``` **Key features:** + - Multiple script executions - Organized output sections - Comprehensive workflow @@ -107,6 +111,7 @@ API implementation: @$1 Generate complete API documentation following the template format above. Ensure documentation includes: + - Endpoint descriptions with HTTP methods - Request/response schemas - Authentication requirements @@ -118,6 +123,7 @@ Format output as markdown suitable for README or docs site. ``` **Key features:** + - Uses plugin template - Combines template with source file - Standardized output format @@ -153,6 +159,7 @@ Executing release workflow for version $1: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/package.sh $1` Review all step outputs and report: + 1. Any failures or warnings 2. Build artifacts location 3. Test results summary @@ -161,6 +168,7 @@ Review all step outputs and report: ``` **Key features:** + - Multi-step workflow - Sequential script execution - Clear step numbering @@ -190,6 +198,7 @@ Build info: !`cat package.json | grep -E '(name|version)'` Execute deployment to $1 environment using configuration above. Deployment checklist: + 1. Validate configuration settings 2. Build application for $1 3. Run pre-deployment tests @@ -202,6 +211,7 @@ Report deployment status and any issues encountered. ``` **Key features:** + - Environment-specific configuration - Dynamic config file loading - Pre-deployment validation @@ -224,6 +234,7 @@ argument-hint: [file-or-directory] Initiate comprehensive code review of @$1 using the code-reviewer agent. The agent will perform: + 1. **Static analysis** - Check for code smells and anti-patterns 2. **Security audit** - Identify potential vulnerabilities 3. **Performance review** - Find optimization opportunities @@ -231,6 +242,7 @@ The agent will perform: 5. **Documentation check** - Verify adequate documentation The agent has access to: + - Plugin's linting rules: ${CLAUDE_PLUGIN_ROOT}/config/lint-rules.json - Security checklist: ${CLAUDE_PLUGIN_ROOT}/checklists/security.md - Performance guidelines: ${CLAUDE_PLUGIN_ROOT}/docs/performance.md @@ -239,6 +251,7 @@ Note: This uses the Task tool to launch the plugin's code-reviewer agent for tho ``` **Key features:** + - Delegates to plugin agent - Documents agent capabilities - References plugin resources @@ -263,6 +276,7 @@ API source code: @$1 Generate API documentation following the plugin's API documentation standards. Use the api-documentation-standards skill to ensure: + - **OpenAPI compliance** - Follow OpenAPI 3.0 specification - **Consistent formatting** - Use plugin's documentation style - **Complete coverage** - Document all endpoints and schemas @@ -270,6 +284,7 @@ Use the api-documentation-standards skill to ensure: - **Error documentation** - Cover all error scenarios The skill provides: + - Standard documentation templates - API documentation best practices - Common patterns for this codebase @@ -279,6 +294,7 @@ Generate production-ready API documentation. ``` **Key features:** + - Invokes plugin skill by name - Documents skill purpose - Clear expectations @@ -309,6 +325,7 @@ Run plugin analyzer: !`node ${CLAUDE_PLUGIN_ROOT}/scripts/analyze.js $1` **Phase 2: Deep Review (Agent)** Launch the code-quality-reviewer agent for detailed analysis. Agent will examine: + - Code structure and organization - Error handling patterns - Testing coverage @@ -316,6 +333,7 @@ Agent will examine: **Phase 3: Standards Check (Skill)** Use the coding-standards skill to validate: + - Naming conventions - Code formatting - Best practices adherence @@ -328,6 +346,7 @@ Compile all findings into comprehensive report following template. **Phase 5: Recommendations** Generate prioritized action items: + 1. Critical issues (must fix) 2. Important improvements (should fix) 3. Nice-to-have enhancements (could fix) @@ -336,6 +355,7 @@ Include specific file locations and suggested changes for each item. ``` **Key features:** + - Multi-phase workflow - Combines scripts, agents, skills - Template-based reporting @@ -373,6 +393,7 @@ If all validations pass: Report build status and any issues. If validations fail: + - Explain which validation failed - Provide expected values/locations - Suggest corrective actions @@ -380,6 +401,7 @@ If validations fail: ``` **Key features:** + - Input validation - Resource existence checks - Error handling @@ -408,12 +430,14 @@ Load environment configuration: @${CLAUDE_PLUGIN_ROOT}/config/$1-checks.json Determine check level: !`echo "$1" | grep -E "^prod$" && echo "FULL" || echo "BASIC"` **For production environment:** + - Full test suite: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/test-full.sh` - Security scan: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/security-scan.sh` - Performance audit: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/perf-check.sh` - Compliance check: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/compliance.sh` **For non-production environments:** + - Basic tests: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/test-basic.sh` - Quick lint: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/lint.sh` @@ -427,6 +451,7 @@ Report status and recommend proceed/block decision. ``` **Key features:** + - Environment-aware logic - Conditional execution - Different validation levels @@ -437,45 +462,59 @@ Report status and recommend proceed/block decision. ## Common Patterns Summary ### Pattern: Plugin Script Execution + ```markdown !`node ${CLAUDE_PLUGIN_ROOT}/scripts/script-name.js $1` ``` + Use for: Running plugin-provided Node.js scripts ### Pattern: Plugin Configuration Loading + ```markdown @${CLAUDE_PLUGIN_ROOT}/config/config-name.json ``` + Use for: Loading plugin configuration files ### Pattern: Plugin Template Usage + ```markdown @${CLAUDE_PLUGIN_ROOT}/templates/template-name.md ``` + Use for: Using plugin templates for generation ### Pattern: Agent Invocation + ```markdown Launch the [agent-name] agent for [task description]. ``` + Use for: Delegating complex tasks to plugin agents ### Pattern: Skill Reference + ```markdown Use the [skill-name] skill to ensure [requirements]. ``` + Use for: Leveraging plugin skills for specialized knowledge ### Pattern: Input Validation + ```markdown Validate input: !`echo "$1" | grep -E "^pattern$" && echo "OK" || echo "ERROR"` ``` + Use for: Validating command arguments ### Pattern: Resource Validation + ```markdown Check exists: !`test -f ${CLAUDE_PLUGIN_ROOT}/path/file && echo "YES" || echo "NO"` ``` + Use for: Verifying required plugin files exist --- @@ -485,18 +524,21 @@ Use for: Verifying required plugin files exist ### Testing Plugin Commands 1. **Test with plugin installed:** + ```bash cd /path/to/plugin claude /command-name args ``` 2. **Verify ${CLAUDE_PLUGIN_ROOT} expansion:** + ```bash # Add debug output to command !`echo "Plugin root: ${CLAUDE_PLUGIN_ROOT}"` ``` 3. **Test across different working directories:** + ```bash cd /tmp && claude /command-name cd /other/project && claude /command-name @@ -512,42 +554,55 @@ Use for: Verifying required plugin files exist ### Common Mistakes to Avoid 1. **Using relative paths instead of ${CLAUDE_PLUGIN_ROOT}:** + ```markdown # Wrong + !`node ./scripts/analyze.js` # Correct + !`node ${CLAUDE_PLUGIN_ROOT}/scripts/analyze.js` ``` 2. **Forgetting to allow required tools:** + ```markdown # Missing allowed-tools - !`bash script.sh` # Will fail without Bash permission + + !`bash script.sh` # Will fail without Bash permission # Correct + --- - allowed-tools: Bash(*) - --- + + ## allowed-tools: Bash(\*) + !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/script.sh` ``` 3. **Not validating inputs:** + ```markdown # Risky - no validation + Deploy to $1 environment # Better - with validation + Validate: !`echo "$1" | grep -E "^(dev|staging|prod)$" || echo "INVALID"` Deploy to $1 environment (if valid) ``` 4. **Hardcoding plugin paths:** + ```markdown # Wrong - breaks on different installations + @/home/user/.claude/plugins/my-plugin/config.json # Correct - works everywhere + @${CLAUDE_PLUGIN_ROOT}/config.json ``` diff --git a/.agents/skills/command-development/examples/simple-commands.md b/.agents/skills/command-development/examples/simple-commands.md index 2348239..2254ab1 100644 --- a/.agents/skills/command-development/examples/simple-commands.md +++ b/.agents/skills/command-development/examples/simple-commands.md @@ -35,6 +35,7 @@ Provide specific feedback with file and line references. ``` **Usage:** + ``` > /review ``` @@ -55,6 +56,7 @@ model: sonnet Perform comprehensive security review checking for: **Common Vulnerabilities:** + - SQL injection risks - Cross-site scripting (XSS) - Authentication/authorization issues @@ -62,6 +64,7 @@ Perform comprehensive security review checking for: - Hardcoded secrets or credentials **Security Best Practices:** + - Input validation present - Output encoding correct - Secure defaults used @@ -69,6 +72,7 @@ Perform comprehensive security review checking for: - Logging appropriate (no sensitive data) For each issue found: + - File and line number - Severity (Critical/High/Medium/Low) - Description of vulnerability @@ -78,6 +82,7 @@ Prioritize issues by severity. ``` **Usage:** + ``` > /security-review ``` @@ -100,6 +105,7 @@ Run tests for $1: Test execution: !`npm test $1` Analyze results: + - Tests passed/failed - Code coverage - Performance issues @@ -109,6 +115,7 @@ If failures found, suggest fixes based on error messages. ``` **Usage:** + ``` > /test-file src/utils/helpers.test.ts ``` @@ -130,22 +137,26 @@ Generate comprehensive documentation for @$1 Include: **Overview:** + - Purpose and responsibility - Main functionality - Dependencies **API Documentation:** + - Function/method signatures - Parameter descriptions with types - Return values with types - Exceptions/errors thrown **Usage Examples:** + - Basic usage - Common patterns - Edge cases **Implementation Notes:** + - Algorithm complexity - Performance considerations - Known limitations @@ -154,6 +165,7 @@ Format as Markdown suitable for project documentation. ``` **Usage:** + ``` > /document src/api/users.ts ``` @@ -181,12 +193,14 @@ Repository Status Summary: **Remote Status:** !`git fetch && git status -sb` Provide: + - Summary of changes - Suggested next actions - Any warnings or issues ``` **Usage:** + ``` > /git-status ``` @@ -207,11 +221,13 @@ allowed-tools: Bash(kubectl:*), Read Deploy to $1 environment using version $2 **Pre-deployment Checks:** + 1. Verify $1 configuration exists 2. Check version $2 is valid 3. Verify cluster accessibility: !`kubectl cluster-info` **Deployment Steps:** + 1. Update deployment manifest with version $2 2. Apply configuration to $1 3. Monitor rollout status @@ -225,6 +241,7 @@ Proceed with deployment? (yes/no) ``` **Usage:** + ``` > /deploy staging v1.2.3 ``` @@ -270,6 +287,7 @@ Present as structured comparison report. ``` **Usage:** + ``` > /compare-files src/old-api.ts src/new-api.ts ``` @@ -290,12 +308,14 @@ model: haiku Quickly fix: $ARGUMENTS **Approach:** + 1. Identify the issue 2. Find relevant code 3. Propose fix 4. Explain solution Focus on: + - Simple, direct solution - Minimal changes - Following existing patterns @@ -305,6 +325,7 @@ Provide code changes with file paths and line numbers. ``` **Usage:** + ``` > /quick-fix button not responding to clicks > /quick-fix typo in error message @@ -350,6 +371,7 @@ Provide actionable guidance based on research. ``` **Usage:** + ``` > /research error handling in async operations > /research API authentication patterns @@ -400,6 +422,7 @@ Explain at level appropriate for junior engineer. ``` **Usage:** + ``` > /explain src/utils/cache.ts > /explain AuthService.login diff --git a/.agents/skills/command-development/references/advanced-workflows.md b/.agents/skills/command-development/references/advanced-workflows.md index 5e0d7b1..bf3a59d 100644 --- a/.agents/skills/command-development/references/advanced-workflows.md +++ b/.agents/skills/command-development/references/advanced-workflows.md @@ -22,20 +22,25 @@ allowed-tools: Bash(gh:*), Read, Grep # PR Review Workflow for #$1 ## Step 1: Fetch PR Details + !`gh pr view $1 --json title,body,author,files` ## Step 2: Review Files + Files changed: !`gh pr diff $1 --name-only` For each file: + - Check code quality - Verify tests exist - Review documentation ## Step 3: Run Checks + Test status: !`gh pr checks $1` Verify: + - All tests passing - No merge conflicts - CI/CD successful @@ -43,11 +48,13 @@ Verify: ## Step 4: Provide Feedback Summarize: + - Issues found (critical/minor) - Suggestions for improvement - Approval recommendation Would you like to: + 1. Approve PR 2. Request changes 3. Leave comments only @@ -56,6 +63,7 @@ Reply with your choice and I'll help complete the action. ``` **Key features:** + - Numbered steps for clarity - Bash execution for context - Decision points for user input @@ -80,13 +88,14 @@ Latest commit: !`git log -1 --format=%H` Deployment state saved to `.claude/deployment-state.local.md`: -\`\`\`markdown ---- +## \`\`\`markdown + initialized: true branch: $(git branch --show-current) commit: $(git log -1 --format=%H) timestamp: $(date -u +%Y-%m-%dT%H:%M:%SZ) status: initialized + --- # Deployment Tracking @@ -95,15 +104,17 @@ Branch: $(git branch --show-current) Started: $(date) Next steps: + 1. Run tests: /deploy-test 2. Build: /deploy-build 3. Deploy: /deploy-execute -\`\`\` + \`\`\` State saved. Run `/deploy-test` to continue. ``` **Next command** (`/deploy-test`): + ```markdown --- description: Run deployment tests @@ -120,6 +131,7 @@ Tests complete. Run `/deploy-build` to continue. ``` **Pattern benefits:** + - Persistent state across commands - Clear workflow progression - Safety checkpoints @@ -196,6 +208,7 @@ Starting sequence... ``` **Individual commands** are simple: + - `/format-code` - Just formats - `/lint-code` - Just lints - `/test-all` - Just tests @@ -214,28 +227,35 @@ description: Analyze test failures # Analyze Test Failures ## Step 1: Get test results + (Run /test-all first if not done) Reading test output... ## Step 2: Categorize failures + - Flaky tests (random failures) - Consistent failures - New failures vs existing ## Step 3: Prioritize + Rank by: + - Impact (critical path vs edge case) - Frequency (always fails vs sometimes) - Effort (quick fix vs major work) ## Step 4: Generate fix plan + For each failure: + - Root cause hypothesis - Suggested fix approach - Estimated effort Would you like me to: + 1. Fix highest priority failure 2. Generate detailed fix plans for all 3. Create GitHub issues for each @@ -256,6 +276,7 @@ allowed-tools: Bash(*), Read Running validations in parallel... Starting: + - Code quality checks - Security scanning - Dependency audit @@ -267,6 +288,7 @@ and report when complete. [Poll each process and report progress] All validations complete. Summary: + - Quality: PASS (0 issues) - Security: WARN (2 minor issues) - Dependencies: PASS @@ -286,6 +308,7 @@ Store workflow state in plugin-specific files: .claude/plugin-name-workflow.local.md: --- + workflow: deployment stage: testing started: 2025-01-15T10:30:00Z @@ -294,6 +317,7 @@ branch: feature/new-api commit: abc123def tests_passed: false build_complete: false + --- # Deployment Workflow State @@ -302,11 +326,13 @@ Current stage: Testing Started: 2025-01-15 10:30 UTC Completed steps: + - ✅ Validation - ✅ Branch check - ⏳ Testing (in progress) Pending steps: + - Build - Deploy - Smoke tests @@ -346,11 +372,13 @@ Checking for interrupted workflow... State file: @.claude/plugin-name-workflow.local.md **Workflow found:** + - Started: [timestamp] - Environment: [env] - Last completed: [step] **Recovery options:** + 1. Resume from last step 2. Restart from beginning 3. Abort and clean up @@ -377,6 +405,7 @@ Writing completion marker... Creating: .claude/feature-complete.flag This signals other commands that feature is ready for: + - Integration testing (/integration-test will auto-detect) - Documentation generation (/docs-generate will include) - Release notes (/release-notes will add) @@ -395,7 +424,7 @@ allowed-tools: Read, Bash(git:*) Checking for completed features... if [ -f .claude/feature-complete.flag ]; then - Feature ready for release notes +Feature ready for release notes fi [Include in release notes] @@ -416,13 +445,13 @@ allowed-tools: Read, Write, Bash Checking for active deployments... if [ -f .claude/deployment.lock ]; then - ERROR: Deployment already in progress - Started: [timestamp from lock file] +ERROR: Deployment already in progress +Started: [timestamp from lock file] - Cannot start concurrent deployment. - Wait for completion or run /deployment-abort +Cannot start concurrent deployment. +Wait for completion or run /deployment-abort - Exit. +Exit. fi Creating deployment lock... @@ -463,6 +492,7 @@ Version: ${2:-latest} Deploying ${2:-latest} to ${1:-staging}... Note: Using defaults for missing arguments: + - Environment defaults to 'staging' - Version defaults to 'latest' ``` @@ -481,9 +511,9 @@ Validating environment... valid_envs="dev staging production" if ! echo "$valid_envs" | grep -w "$1" > /dev/null; then - ERROR: Invalid environment '$1' - Valid options: dev, staging, production - Exit. +ERROR: Invalid environment '$1' +Valid options: dev, staging, production +Exit. fi Environment validated. Proceeding... @@ -500,15 +530,16 @@ argument-hint: [env-shorthand] Input: $1 Expanding shorthand: + - d/dev → development - s/stg → staging - p/prod → production case "$1" in - d|dev) ENV="development";; - s|stg) ENV="staging";; - p|prod) ENV="production";; - *) ENV="$1";; +d|dev) ENV="development";; +s|stg) ENV="staging";; +p|prod) ENV="production";; +\*) ENV="$1";; esac Deploying to: $ENV @@ -528,22 +559,25 @@ description: Resilient deployment workflow Running steps with error handling... ## Step 1: Tests + !`npm test` if [ $? -ne 0 ]; then - ERROR: Tests failed +ERROR: Tests failed + +Options: - Options: - 1. Fix tests and retry - 2. Skip tests (NOT recommended) - 3. Abort deployment +1. Fix tests and retry +2. Skip tests (NOT recommended) +3. Abort deployment - What would you like to do? +What would you like to do? - [Wait for user input before continuing] +[Wait for user input before continuing] fi ## Step 2: Build + [Continue only if Step 1 succeeded] ``` @@ -564,13 +598,13 @@ Deploying new version... !`deploy.sh` if [ $? -ne 0 ]; then - DEPLOYMENT FAILED +DEPLOYMENT FAILED - Initiating automatic rollback... - !`rollback.sh` +Initiating automatic rollback... +!`rollback.sh` - Rolled back to previous version. - Check logs for failure details. +Rolled back to previous version. +Check logs for failure details. fi Deployment complete. @@ -586,14 +620,17 @@ description: Workflow with checkpoints # Multi-Stage Deployment ## Checkpoint 1: Validation + !`validate.sh` echo "checkpoint:validation" >> .claude/deployment-checkpoints.log ## Checkpoint 2: Build + !`build.sh` echo "checkpoint:build" >> .claude/deployment-checkpoints.log ## Checkpoint 3: Deploy + !`deploy.sh` echo "checkpoint:deploy" >> .claude/deployment-checkpoints.log @@ -649,15 +686,17 @@ allowed-tools: Write, Bash(git:*) Creating workflow state... -\`\`\`yaml ---- +## \`\`\`yaml + workflow: deployment environment: $1 branch: !`git branch --show-current` commit: !`git rev-parse HEAD` stage: initialized timestamp: !`date -u +%Y-%m-%dT%H:%M:%SZ` + --- + \`\`\` Written to .claude/deployment-state.local.md @@ -676,6 +715,7 @@ allowed-tools: Read, Bash Reading state: @.claude/deployment-state.local.md Running validation... + - Branch check: PASS - Tests: PASS - Build: PASS diff --git a/.agents/skills/command-development/references/documentation-patterns.md b/.agents/skills/command-development/references/documentation-patterns.md index 3ea03ec..a6d6e47 100644 --- a/.agents/skills/command-development/references/documentation-patterns.md +++ b/.agents/skills/command-development/references/documentation-patterns.md @@ -73,42 +73,50 @@ CHANGELOG: ### Documentation Comment Sections **PURPOSE**: Why the command exists + - Problem it solves - Use cases - When to use vs when not to use **USAGE**: Basic syntax + - Command invocation pattern - Required vs optional arguments - Default values **ARGUMENTS**: Detailed argument documentation + - Each argument described - Type information - Valid values/ranges - Defaults **EXAMPLES**: Concrete usage examples + - Common use cases - Edge cases - Expected outputs **REQUIREMENTS**: Prerequisites + - Dependencies - Permissions - Environmental setup **RELATED COMMANDS**: Connections + - Similar commands - Complementary commands - Alternative approaches **TROUBLESHOOTING**: Common issues + - Known problems - Solutions - Workarounds **CHANGELOG**: Version history + - What changed when - Breaking changes highlighted - Migration guidance @@ -126,6 +134,7 @@ description: Complex multi-step command Checking prerequisites... + - Git repository: !`git rev-parse --git-dir 2>/dev/null` - Branch exists: [validation logic] @@ -156,15 +165,18 @@ description: Deployment command with inline docs ## Pre-flight Checks + Current branch: !`git branch --show-current` + if [ "$1" = "production" ] && [ "$(git branch --show-current)" != "main" ]; then - ⚠️ WARNING: Not on main branch for production deploy - This is unusual. Confirm this is intentional. +⚠️ WARNING: Not on main branch for production deploy +This is unusual. Confirm this is intentional. fi + Running tests: !`npm test` ✓ All checks passed @@ -173,10 +185,12 @@ Running tests: !`npm test` + Deploying to $1 environment... [Deployment steps...] + Verifying deployment health... [Health checks...] @@ -185,6 +199,7 @@ Deployment complete! ## Next Steps + 1. Monitor logs: /logs $1 2. Run smoke tests: /smoke-test $1 3. Notify team: /notify-deployment $1 @@ -212,6 +227,7 @@ New version: $2 Review the above configuration. **Continue with deployment?** + - Reply "yes" to proceed - Reply "no" to cancel - Reply "edit" to modify configuration @@ -239,28 +255,28 @@ argument-hint: [subcommand] [args] # Command Processor if [ "$1" = "help" ] || [ "$1" = "--help" ] || [ "$1" = "-h" ]; then - **Command Help** +**Command Help** - USAGE: - /command [subcommand] [args] +USAGE: +/command [subcommand] [args] - SUBCOMMANDS: - init [name] Initialize new configuration - deploy [env] Deploy to environment - status Show current status - rollback Rollback last deployment - help Show this help +SUBCOMMANDS: +init [name] Initialize new configuration +deploy [env] Deploy to environment +status Show current status +rollback Rollback last deployment +help Show this help - EXAMPLES: - /command init my-project - /command deploy staging - /command status - /command rollback +EXAMPLES: +/command init my-project +/command deploy staging +/command status +/command rollback - For detailed help on a subcommand: - /command [subcommand] --help +For detailed help on a subcommand: +/command [subcommand] --help - Exit. +Exit. fi [Regular command processing...] @@ -279,23 +295,24 @@ argument-hint: [operation] [target] # Context-Aware Operation if [ -z "$1" ]; then - **No operation specified** +**No operation specified** - Available operations: - - analyze: Analyze target for issues - - fix: Apply automatic fixes - - report: Generate detailed report +Available operations: - Usage: /command [operation] [target] +- analyze: Analyze target for issues +- fix: Apply automatic fixes +- report: Generate detailed report - Examples: - /command analyze src/ - /command fix src/app.js - /command report +Usage: /command [operation] [target] - Run /command help for more details. +Examples: +/command analyze src/ +/command fix src/app.js +/command report - Exit. +Run /command help for more details. + +Exit. fi [Command continues if operation provided...] @@ -313,37 +330,39 @@ description: Command with good error messages # Validation Command if [ -z "$1" ]; then - ❌ ERROR: Missing required argument +❌ ERROR: Missing required argument - The 'file-path' argument is required. +The 'file-path' argument is required. - USAGE: - /validate [file-path] +USAGE: +/validate [file-path] - EXAMPLE: - /validate src/app.js +EXAMPLE: +/validate src/app.js - Try again with a file path. +Try again with a file path. - Exit. +Exit. fi if [ ! -f "$1" ]; then - ❌ ERROR: File not found: $1 +❌ ERROR: File not found: $1 + +The specified file does not exist or is not accessible. - The specified file does not exist or is not accessible. +COMMON CAUSES: - COMMON CAUSES: - 1. Typo in file path - 2. File was deleted or moved - 3. Insufficient permissions +1. Typo in file path +2. File was deleted or moved +3. Insufficient permissions - SUGGESTIONS: - - Check spelling: $1 - - Verify file exists: ls -la $(dirname "$1") - - Check permissions: ls -l "$1" +SUGGESTIONS: - Exit. +- Check spelling: $1 +- Verify file exists: ls -la $(dirname "$1") +- Check permissions: ls -l "$1" + +Exit. fi [Command continues if validation passes...] @@ -363,30 +382,33 @@ Running operation... !`risky-operation.sh` if [ $? -ne 0 ]; then - ❌ OPERATION FAILED +❌ OPERATION FAILED + +The operation encountered an error and could not complete. - The operation encountered an error and could not complete. +WHAT HAPPENED: +The risky-operation.sh script returned a non-zero exit code. - WHAT HAPPENED: - The risky-operation.sh script returned a non-zero exit code. +WHAT THIS MEANS: - WHAT THIS MEANS: - - Changes may be partially applied - - System may be in inconsistent state - - Manual intervention may be needed +- Changes may be partially applied +- System may be in inconsistent state +- Manual intervention may be needed - RECOVERY STEPS: - 1. Check operation logs: cat /tmp/operation.log - 2. Verify system state: /check-state - 3. If needed, rollback: /rollback-operation - 4. Fix underlying issue - 5. Retry operation: /retry-operation +RECOVERY STEPS: - NEED HELP? - - Check troubleshooting guide: /help troubleshooting - - Contact support with error code: ERR_OP_FAILED_001 +1. Check operation logs: cat /tmp/operation.log +2. Verify system state: /check-state +3. If needed, rollback: /rollback-operation +4. Fix underlying issue +5. Retry operation: /retry-operation - Exit. +NEED HELP? + +- Check troubleshooting guide: /help troubleshooting +- Contact support with error code: ERR_OP_FAILED_001 + +Exit. fi ``` @@ -418,6 +440,7 @@ Analyzes all files in src/ directory for feature usage. \`\`\` Provides detailed analysis including: + - Feature breakdown by file - Usage patterns - Optimization suggestions @@ -465,6 +488,7 @@ Transforms data from one format to another. ## Examples First ### Example 1: JSON to YAML + **Input:** `data.json` \`\`\`json {"name": "test", "value": 42} @@ -479,6 +503,7 @@ value: 42 \`\`\` ### Example 2: CSV to JSON + **Input:** `data.csv` \`\`\`csv name,value @@ -493,6 +518,7 @@ test,42 \`\`\` ### Example 3: With Options + **Command:** `/transform data.json yaml --pretty --sort-keys` **Result:** Formatted YAML with sorted keys @@ -631,6 +657,7 @@ Basic usage: ## Examples ### Example 1: Basic Usage + \`\`\` /command-name value1 value2 \`\`\` @@ -638,6 +665,7 @@ Basic usage: Description of what happens. ### Example 2: Advanced Usage + \`\`\` /command-name value1 --option \`\`\` @@ -648,11 +676,13 @@ Description of advanced feature. Optional configuration file: `.claude/command-name.local.md` -\`\`\`markdown ---- +## \`\`\`markdown + default_arg: value enable_feature: true + --- + \`\`\` ## Requirements diff --git a/.agents/skills/command-development/references/frontmatter-reference.md b/.agents/skills/command-development/references/frontmatter-reference.md index aa85294..d92e362 100644 --- a/.agents/skills/command-development/references/frontmatter-reference.md +++ b/.agents/skills/command-development/references/frontmatter-reference.md @@ -31,28 +31,34 @@ All fields are optional. Commands work without any frontmatter. **Purpose:** Describes what the command does, shown in `/help` output **Examples:** + ```yaml description: Review code for security issues ``` + ```yaml description: Deploy to staging environment ``` + ```yaml description: Generate API documentation ``` **Best practices:** + - Keep under 60 characters for clean display - Start with verb (Review, Deploy, Generate) - Be specific about what command does - Avoid redundant "command" or "slash command" **Good:** + - ✅ "Review PR for code quality and security" - ✅ "Deploy application to specified environment" - ✅ "Generate comprehensive API documentation" **Bad:** + - ❌ "This command reviews PRs" (unnecessary "This command") - ❌ "Review" (too vague) - ❌ "A command that reviews pull requests for code quality, security issues, and best practices" (too long) @@ -68,16 +74,19 @@ description: Generate API documentation **Formats:** **Single tool:** + ```yaml allowed-tools: Read ``` **Multiple tools (comma-separated):** + ```yaml allowed-tools: Read, Write, Edit ``` **Multiple tools (array):** + ```yaml allowed-tools: - Read @@ -88,11 +97,13 @@ allowed-tools: **Tool Patterns:** **Specific tools:** + ```yaml allowed-tools: Read, Grep, Edit ``` **Bash with command filter:** + ```yaml allowed-tools: Bash(git:*) # Only git commands allowed-tools: Bash(npm:*) # Only npm commands @@ -100,6 +111,7 @@ allowed-tools: Bash(docker:*) # Only docker commands ``` **All tools (not recommended):** + ```yaml allowed-tools: "*" ``` @@ -107,11 +119,13 @@ allowed-tools: "*" **When to use:** 1. **Security:** Restrict command to safe operations + ```yaml - allowed-tools: Read, Grep # Read-only command + allowed-tools: Read, Grep # Read-only command ``` 2. **Clarity:** Document required tools + ```yaml allowed-tools: Bash(git:*), Read ``` @@ -122,6 +136,7 @@ allowed-tools: "*" ``` **Best practices:** + - Be as restrictive as possible - Use command filters for Bash (e.g., `git:*` not `*`) - Only specify when different from conversation permissions @@ -137,19 +152,23 @@ allowed-tools: "*" **Purpose:** Specify which Claude model executes the command **Examples:** + ```yaml -model: haiku # Fast, efficient for simple tasks +model: haiku # Fast, efficient for simple tasks ``` + ```yaml -model: sonnet # Balanced performance (default) +model: sonnet # Balanced performance (default) ``` + ```yaml -model: opus # Maximum capability for complex tasks +model: opus # Maximum capability for complex tasks ``` **When to use:** **Use `haiku` for:** + - Simple, formulaic commands - Fast execution needed - Low complexity tasks @@ -163,6 +182,7 @@ model: haiku ``` **Use `sonnet` for:** + - Standard commands (default) - Balanced speed/quality - Most common use cases @@ -175,6 +195,7 @@ model: sonnet ``` **Use `opus` for:** + - Complex analysis - Architectural decisions - Deep code understanding @@ -188,6 +209,7 @@ model: opus ``` **Best practices:** + - Omit unless specific need - Use `haiku` for speed when possible - Reserve `opus` for genuinely complex tasks @@ -202,6 +224,7 @@ model: opus **Purpose:** Document expected arguments for users and autocomplete **Format:** + ```yaml argument-hint: [arg1] [arg2] [optional-arg] ``` @@ -209,26 +232,31 @@ argument-hint: [arg1] [arg2] [optional-arg] **Examples:** **Single argument:** + ```yaml argument-hint: [pr-number] ``` **Multiple required arguments:** + ```yaml argument-hint: [environment] [version] ``` **Optional arguments:** + ```yaml argument-hint: [file-path] [options] ``` **Descriptive names:** + ```yaml argument-hint: [source-branch] [target-branch] [commit-message] ``` **Best practices:** + - Use square brackets `[]` for each argument - Use descriptive names (not `arg1`, `arg2`) - Indicate optional vs required in description @@ -238,16 +266,17 @@ argument-hint: [source-branch] [target-branch] [commit-message] **Examples by pattern:** **Simple command:** + ```yaml --- description: Fix issue by number argument-hint: [issue-number] --- - Fix issue #$1... ``` **Multi-argument:** + ```yaml --- description: Deploy to environment @@ -258,6 +287,7 @@ Deploy $1 to $2 using version $3... ``` **With options:** + ```yaml --- description: Run tests with options @@ -276,6 +306,7 @@ Run tests matching $1 with options: $2 **Purpose:** Prevent SlashCommand tool from programmatically invoking command **Examples:** + ```yaml disable-model-invocation: true ``` @@ -283,6 +314,7 @@ disable-model-invocation: true **When to use:** 1. **Manual-only commands:** Commands requiring user judgment + ```yaml --- description: Approve deployment to production @@ -291,6 +323,7 @@ disable-model-invocation: true ``` 2. **Destructive operations:** Commands with irreversible effects + ```yaml --- description: Delete all test data @@ -307,16 +340,19 @@ disable-model-invocation: true ``` **Default behavior (false):** + - Command available to SlashCommand tool - Claude can invoke programmatically - Still available for manual invocation **When true:** + - Command only invokable by user typing `/command` - Not available to SlashCommand tool - Safer for sensitive operations **Best practices:** + - Use sparingly (limits Claude's autonomy) - Document why in command comments - Consider if command should exist if always manual @@ -356,6 +392,7 @@ allowed-tools: Bash(git:*), Read Current changes: !`git diff --name-only` Review each changed file for: + - Code quality - Potential bugs - Best practices @@ -376,6 +413,7 @@ model: sonnet Deploy $1 to $2 environment using version $3 Pre-deployment checks: + - Verify $2 configuration - Check cluster status: !`kubectl cluster-info` - Validate version $3 exists @@ -405,6 +443,7 @@ Review deployment $1 for production approval: Deployment details: !`gh api /deployments/$1` Verify: + - All tests passed - Security scan clean - Stakeholder approval @@ -418,26 +457,29 @@ Type "APPROVED" to confirm deployment. ### Common Errors **Invalid YAML syntax:** + ```yaml --- description: Missing quote allowed-tools: Read, Write model: sonnet ---- # ❌ Missing closing quote above +--- # ❌ Missing closing quote above ``` **Fix:** Validate YAML syntax **Incorrect tool specification:** + ```yaml -allowed-tools: Bash # ❌ Missing command filter +allowed-tools: Bash # ❌ Missing command filter ``` **Fix:** Use `Bash(git:*)` format **Invalid model name:** + ```yaml -model: gpt4 # ❌ Not a valid Claude model +model: gpt4 # ❌ Not a valid Claude model ``` **Fix:** Use `sonnet`, `opus`, or `haiku` @@ -445,6 +487,7 @@ model: gpt4 # ❌ Not a valid Claude model ### Validation Checklist Before committing command: + - [ ] YAML syntax valid (no errors) - [ ] Description under 60 characters - [ ] allowed-tools uses proper format diff --git a/.agents/skills/command-development/references/interactive-commands.md b/.agents/skills/command-development/references/interactive-commands.md index e55bc38..e277938 100644 --- a/.agents/skills/command-development/references/interactive-commands.md +++ b/.agents/skills/command-development/references/interactive-commands.md @@ -5,6 +5,7 @@ Comprehensive guide to creating commands that gather user feedback and make deci ## Overview Some commands need user input that doesn't work well with simple arguments. For example: + - Choosing between multiple complex options with trade-offs - Selecting multiple items from a list - Making decisions that require explanation @@ -38,28 +39,29 @@ For these cases, use the **AskUserQuestion tool** within command execution rathe questions: [ { question: "Which authentication method should we use?", - header: "Auth method", // Short label (max 12 chars) - multiSelect: false, // true for multiple selection + header: "Auth method", // Short label (max 12 chars) + multiSelect: false, // true for multiple selection options: [ { label: "OAuth 2.0", - description: "Industry standard, supports multiple providers" + description: "Industry standard, supports multiple providers", }, { label: "JWT", - description: "Stateless, good for APIs" + description: "Stateless, good for APIs", }, { label: "Session", - description: "Traditional, server-side state" - } - ] - } - ] + description: "Traditional, server-side state", + }, + ], + }, + ]; } ``` **Key points:** + - Users can always choose "Other" to provide custom input (automatic) - `multiSelect: true` allows selecting multiple options - Options should be 2-4 choices (not more) @@ -84,6 +86,7 @@ This command will guide you through configuring the plugin with a series of ques Use the AskUserQuestion tool to ask: **Question 1 - Deployment target:** + - header: "Deploy to" - question: "Which deployment platform will you use?" - options: @@ -93,6 +96,7 @@ Use the AskUserQuestion tool to ask: - Local (Docker on local machine) **Question 2 - Environment strategy:** + - header: "Environments" - question: "How many environments do you need?" - options: @@ -101,6 +105,7 @@ Use the AskUserQuestion tool to ask: - Complete (Dev, QA, Staging, Production) **Question 3 - Features to enable:** + - header: "Features" - question: "Which features do you want to enable?" - multiSelect: true @@ -123,15 +128,16 @@ Based on the answers received from AskUserQuestion: Create `.claude/plugin-name.local.md` with: -\`\`\`yaml ---- +## \`\`\`yaml + deployment_target: [answer from Q1] environments: [answer from Q2] features: - auto_scaling: [true if selected in Q3] - monitoring: [true if selected in Q3] - ci_cd: [true if selected in Q3] - backups: [true if selected in Q3] +auto_scaling: [true if selected in Q3] +monitoring: [true if selected in Q3] +ci_cd: [true if selected in Q3] +backups: [true if selected in Q3] + --- # Plugin Configuration @@ -169,11 +175,13 @@ Based on answers, determine which additional questions to ask. If user selected "Advanced" deployment in Stage 1: Use AskUserQuestion to ask about: + - Load balancing strategy - Caching configuration - Security hardening options If user selected "Simple" deployment: + - Skip advanced questions - Use sensible defaults @@ -182,6 +190,7 @@ If user selected "Simple" deployment: Show summary of all selections. Use AskUserQuestion for final confirmation: + - header: "Confirm" - question: "Does this configuration look correct?" - options: @@ -201,38 +210,45 @@ Based on confirmed configuration, execute setup steps. ### Question Structure **Good questions:** + ```markdown Question: "Which database should we use for this project?" Header: "Database" Options: - - PostgreSQL (Relational, ACID compliant, best for complex queries) - - MongoDB (Document store, flexible schema, best for rapid iteration) - - Redis (In-memory, fast, best for caching and sessions) + +- PostgreSQL (Relational, ACID compliant, best for complex queries) +- MongoDB (Document store, flexible schema, best for rapid iteration) +- Redis (In-memory, fast, best for caching and sessions) ``` **Poor questions:** + ```markdown -Question: "Database?" // Too vague -Header: "DB" // Unclear abbreviation +Question: "Database?" // Too vague +Header: "DB" // Unclear abbreviation Options: - - Option 1 // Not descriptive - - Option 2 + +- Option 1 // Not descriptive +- Option 2 ``` ### Option Design Best Practices **Clear labels:** + - Use 1-5 words - Specific and descriptive - No jargon without context **Helpful descriptions:** + - Explain what the option means - Mention key benefits or trade-offs - Help user make informed decision - Keep to 1-2 sentences **Appropriate number:** + - 2-4 options per question - Don't overwhelm with too many choices - Group related options @@ -247,12 +263,13 @@ Use AskUserQuestion for enabling features: Question: "Which features do you want to enable?" Header: "Features" -multiSelect: true // Allow selecting multiple +multiSelect: true // Allow selecting multiple Options: - - Logging (Detailed operation logs) - - Metrics (Performance monitoring) - - Alerts (Error notifications) - - Backups (Automatic backups) + +- Logging (Detailed operation logs) +- Metrics (Performance monitoring) +- Alerts (Error notifications) +- Backups (Automatic backups) ``` User can select any combination: none, some, or all. @@ -261,7 +278,7 @@ User can select any combination: none, some, or all. ```markdown Question: "Which authentication method?" -multiSelect: false // Only one auth method makes sense +multiSelect: false // Only one auth method makes sense ``` Mutually exclusive choices should not use multiSelect. @@ -285,16 +302,17 @@ Use AskUserQuestion to confirm: Question: "This will delete all cached data. Are you sure?" Header: "Confirm" Options: - - Yes (Proceed with deletion) - - No (Cancel operation) + +- Yes (Proceed with deletion) +- No (Cancel operation) If user selects "Yes": - Execute deletion - Report completion +Execute deletion +Report completion If user selects "No": - Cancel operation - Exit without changes +Cancel operation +Exit without changes ``` ### Pattern 2: Multiple Configuration Questions @@ -312,22 +330,26 @@ Gather configuration through multiple questions. Use AskUserQuestion with multiple questions in one call: **Question 1:** + - question: "Which programming language?" - header: "Language" - options: Python, TypeScript, Go, Rust **Question 2:** + - question: "Which test framework?" - header: "Testing" - options: Jest, PyTest, Go Test, Cargo Test (Adapt based on language from Q1) **Question 3:** + - question: "Which CI/CD platform?" - header: "CI/CD" - options: GitHub Actions, GitLab CI, CircleCI **Question 4:** + - question: "Which features do you need?" - header: "Features" - multiSelect: true @@ -353,25 +375,29 @@ Use AskUserQuestion: Question: "How complex is your deployment?" Header: "Complexity" Options: - - Simple (Single server, straightforward) - - Standard (Multiple servers, load balancing) - - Complex (Microservices, orchestration) + +- Simple (Single server, straightforward) +- Standard (Multiple servers, load balancing) +- Complex (Microservices, orchestration) ## Conditional Questions Based on Answer If answer is "Simple": - - No additional questions - - Use minimal configuration + +- No additional questions +- Use minimal configuration If answer is "Standard": - - Ask about load balancing strategy - - Ask about scaling policy + +- Ask about load balancing strategy +- Ask about scaling policy If answer is "Complex": - - Ask about orchestration platform (Kubernetes, Docker Swarm) - - Ask about service mesh (Istio, Linkerd, None) - - Ask about monitoring (Prometheus, Datadog, CloudWatch) - - Ask about logging aggregation + +- Ask about orchestration platform (Kubernetes, Docker Swarm) +- Ask about service mesh (Istio, Linkerd, None) +- Ask about monitoring (Prometheus, Datadog, CloudWatch) +- Ask about logging aggregation ## Process Conditional Answers @@ -397,10 +423,11 @@ Use AskUserQuestion: Question: "How many team members should we set up?" Header: "Team size" Options: - - 2 people - - 3 people - - 4 people - - 6 people + +- 2 people +- 3 people +- 4 people +- 6 people ## Iterate Through Team Members @@ -411,11 +438,12 @@ Use AskUserQuestion for member details: Question: "What role for team member [number]?" Header: "Role" Options: - - Frontend Developer - - Backend Developer - - DevOps Engineer - - QA Engineer - - Designer + +- Frontend Developer +- Backend Developer +- DevOps Engineer +- QA Engineer +- Designer Store each member's information. @@ -442,17 +470,19 @@ Question: "Which libraries does your project need?" Header: "Dependencies" multiSelect: true Options: - - React (UI framework) - - Express (Web server) - - TypeORM (Database ORM) - - Jest (Testing framework) - - Axios (HTTP client) + +- React (UI framework) +- Express (Web server) +- TypeORM (Database ORM) +- Jest (Testing framework) +- Axios (HTTP client) User can select any combination. ## Process Selections For each selected library: + - Add to package.json dependencies - Generate sample configuration - Create usage examples @@ -477,15 +507,15 @@ For each selected library: After calling AskUserQuestion, verify answers received: If answers are empty or invalid: - Something went wrong gathering responses. +Something went wrong gathering responses. - Please try again or provide configuration manually: - [Show alternative approach] +Please try again or provide configuration manually: +[Show alternative approach] - Exit. +Exit. If answers look correct: - Process as expected +Process as expected ``` ### Progressive Disclosure @@ -500,40 +530,44 @@ Use AskUserQuestion: Question: "How would you like to set up?" Header: "Setup type" Options: - - Quick (Use recommended defaults) - - Custom (Configure all options) - - Guided (Step-by-step with explanations) + +- Quick (Use recommended defaults) +- Custom (Configure all options) +- Guided (Step-by-step with explanations) If "Quick": - Apply defaults, minimal questions +Apply defaults, minimal questions If "Custom": - Ask all available configuration questions +Ask all available configuration questions If "Guided": - Ask questions with extra explanation - Provide recommendations along the way +Ask questions with extra explanation +Provide recommendations along the way ``` ### Multi-Select Guidelines **Good multi-select use:** + ```markdown Question: "Which features do you want to enable?" multiSelect: true Options: - - Logging - - Metrics - - Alerts - - Backups + +- Logging +- Metrics +- Alerts +- Backups Reason: User might want any combination ``` **Bad multi-select use:** + ```markdown Question: "Which database engine?" -multiSelect: true // ❌ Should be single-select +multiSelect: true // ❌ Should be single-select Reason: Can only use one database engine ``` @@ -557,23 +591,21 @@ Use AskUserQuestion to collect settings. ## Validate Configuration Check if configuration is valid: + - Required dependencies available? - Settings compatible with each other? - No conflicts detected? If validation fails: - Show validation errors +Show validation errors - Use AskUserQuestion to ask: +Use AskUserQuestion to ask: - Question: "Configuration has issues. What would you like to do?" - Header: "Next step" - Options: - - Fix (Adjust settings to resolve issues) - - Override (Proceed despite warnings) - - Cancel (Abort setup) +Question: "Configuration has issues. What would you like to do?" +Header: "Next step" +Options: - Fix (Adjust settings to resolve issues) - Override (Proceed despite warnings) - Cancel (Abort setup) - Based on answer, retry or proceed or exit. +Based on answer, retry or proceed or exit. ``` ### Build Configuration Incrementally @@ -597,6 +629,7 @@ Save to `.claude/config-partial.yml` Show user the core settings: Based on these core settings, you need to configure: + - [Setting A] (because you chose [X]) - [Setting B] (because you chose [Y]) @@ -616,9 +649,10 @@ Use AskUserQuestion for confirmation: Question: "Is this configuration correct?" Options: - - Yes (Save and apply) - - No (Start over) - - Modify (Edit specific settings) + +- Yes (Save and apply) +- No (Start over) +- Modify (Edit specific settings) ``` ### Dynamic Options Based on Context @@ -634,6 +668,7 @@ allowed-tools: AskUserQuestion, Bash, Read ## Detect Current State Check existing configuration: + - Current language: !`detect-language.sh` - Existing frameworks: !`detect-frameworks.sh` - Available tools: !`check-tools.sh` @@ -644,23 +679,17 @@ Based on detected language, ask relevant questions. If language is TypeScript: - Use AskUserQuestion: +Use AskUserQuestion: - Question: "Which TypeScript features should we enable?" - Options: - - Strict Mode (Maximum type safety) - - Decorators (Experimental decorator support) - - Path Mapping (Module path aliases) +Question: "Which TypeScript features should we enable?" +Options: - Strict Mode (Maximum type safety) - Decorators (Experimental decorator support) - Path Mapping (Module path aliases) If language is Python: - Use AskUserQuestion: +Use AskUserQuestion: - Question: "Which Python tools should we configure?" - Options: - - Type Hints (mypy for type checking) - - Black (Code formatting) - - Pylint (Linting and style) +Question: "Which Python tools should we configure?" +Options: - Type Hints (mypy for type checking) - Black (Code formatting) - Pylint (Linting and style) Questions adapt to project context. ``` @@ -688,11 +717,12 @@ Use AskUserQuestion: Question: "How many agents should we launch?" Header: "Agent count" Options: - - 2 agents (Best for simple projects) - - 3 agents (Good for medium projects) - - 4 agents (Standard team size) - - 6 agents (Large projects) - - 8 agents (Complex multi-component projects) + +- 2 agents (Best for simple projects) +- 3 agents (Good for medium projects) +- 4 agents (Standard team size) +- 6 agents (Large projects) +- 8 agents (Complex multi-component projects) ### Question 2: Task Definition Approach @@ -701,16 +731,17 @@ Use AskUserQuestion: Question: "How would you like to define tasks?" Header: "Task setup" Options: - - File (I have a task list file ready) - - Guided (Help me create tasks interactively) - - Custom (Other approach) + +- File (I have a task list file ready) +- Guided (Help me create tasks interactively) +- Custom (Other approach) If "File": - Ask for file path - Validate file exists and has correct format +Ask for file path +Validate file exists and has correct format If "Guided": - Enter iterative task creation mode (see below) +Enter iterative task creation mode (see below) ### Question 3: Coordination Mode @@ -719,9 +750,10 @@ Use AskUserQuestion: Question: "How should agents coordinate?" Header: "Coordination" Options: - - Team Leader (One agent coordinates others) - - Collaborative (Agents coordinate as peers) - - Autonomous (Independent work, minimal coordination) + +- Team Leader (One agent coordinates others) +- Collaborative (Agents coordinate as peers) +- Autonomous (Independent work, minimal coordination) ### Iterative Task Creation (If "Guided" Selected) @@ -731,38 +763,42 @@ For each agent (1 to N from Question 1): Question: "What should we call agent [number]?" Header: "Agent name" Options: - - auth-agent - - api-agent - - ui-agent - - db-agent + +- auth-agent +- api-agent +- ui-agent +- db-agent (Provide relevant suggestions based on common patterns) **Question B: Task Type** Question: "What task for [agent-name]?" Header: "Task type" Options: - - Authentication (User auth, JWT, OAuth) - - API Endpoints (REST/GraphQL APIs) - - UI Components (Frontend components) - - Database (Schema, migrations, queries) - - Testing (Test suites and coverage) - - Documentation (Docs, README, guides) + +- Authentication (User auth, JWT, OAuth) +- API Endpoints (REST/GraphQL APIs) +- UI Components (Frontend components) +- Database (Schema, migrations, queries) +- Testing (Test suites and coverage) +- Documentation (Docs, README, guides) **Question C: Dependencies** Question: "What does [agent-name] depend on?" Header: "Dependencies" multiSelect: true Options: - - [List of previously defined agents] - - No dependencies + +- [List of previously defined agents] +- No dependencies **Question D: Base Branch** Question: "Which base branch for PR?" Header: "PR base" Options: - - main - - staging - - develop + +- main +- staging +- develop Store all task information for each agent. @@ -822,10 +858,11 @@ Question: "Which features do you need?" Header: "Features" multiSelect: true Options: - - Authentication - - Authorization - - Rate Limiting - - Caching + +- Authentication +- Authorization +- Rate Limiting +- Caching ``` ### Pattern: Environment Configuration @@ -836,9 +873,10 @@ Use AskUserQuestion: Question: "Which environment is this?" Header: "Environment" Options: - - Development (Local development) - - Staging (Pre-production testing) - - Production (Live environment) + +- Development (Local development) +- Staging (Pre-production testing) +- Production (Live environment) ``` ### Pattern: Priority Selection @@ -849,10 +887,11 @@ Use AskUserQuestion: Question: "What's the priority for this task?" Header: "Priority" Options: - - Critical (Must be done immediately) - - High (Important, do soon) - - Medium (Standard priority) - - Low (Nice to have) + +- Critical (Must be done immediately) +- High (Important, do soon) +- Medium (Standard priority) +- Low (Nice to have) ``` ### Pattern: Scope Selection @@ -863,9 +902,10 @@ Use AskUserQuestion: Question: "What scope should we analyze?" Header: "Scope" Options: - - Current file (Just this file) - - Current directory (All files in directory) - - Entire project (Full codebase scan) + +- Current file (Just this file) +- Current directory (All files in directory) +- Entire project (Full codebase scan) ``` ## Combining Arguments and Questions @@ -873,6 +913,7 @@ Options: ### Use Both Appropriately **Arguments for known values:** + ```markdown --- argument-hint: [project-name] @@ -887,10 +928,12 @@ Use AskUserQuestion for options that require explanation. ``` **Questions for complex choices:** + ```markdown Project name from argument: $1 Now use AskUserQuestion to choose: + - Architecture pattern - Technology stack - Deployment strategy @@ -901,17 +944,20 @@ These require explanation, so questions work better than arguments. ## Troubleshooting **Questions not appearing:** + - Verify AskUserQuestion in allowed-tools - Check question format is correct - Ensure options array has 2-4 items **User can't make selection:** + - Check option labels are clear - Verify descriptions are helpful - Consider if too many options - Ensure multiSelect setting is correct **Flow feels confusing:** + - Reduce number of questions - Group related questions - Add explanation between stages diff --git a/.agents/skills/command-development/references/marketplace-considerations.md b/.agents/skills/command-development/references/marketplace-considerations.md index 03e706c..2270407 100644 --- a/.agents/skills/command-development/references/marketplace-considerations.md +++ b/.agents/skills/command-development/references/marketplace-considerations.md @@ -23,23 +23,28 @@ allowed-tools: Bash(*) Detecting platform... case "$(uname)" in - Darwin*) PLATFORM="macOS" ;; - Linux*) PLATFORM="Linux" ;; - MINGW*|MSYS*|CYGWIN*) PLATFORM="Windows" ;; - *) PLATFORM="Unknown" ;; +Darwin*) PLATFORM="macOS" ;; +Linux*) PLATFORM="Linux" ;; +MINGW*|MSYS*|CYGWIN*) PLATFORM="Windows" ;; +*) PLATFORM="Unknown" ;; esac Platform: $PLATFORM + if [ "$PLATFORM" = "Windows" ]; then - # Windows-specific handling - PATH_SEP="\\" - NULL_DEVICE="NUL" + +# Windows-specific handling + +PATH_SEP="\\" +NULL_DEVICE="NUL" else - # Unix-like handling - PATH_SEP="/" - NULL_DEVICE="/dev/null" + +# Unix-like handling + +PATH_SEP="/" +NULL_DEVICE="/dev/null" fi [Platform-appropriate implementation...] @@ -49,17 +54,19 @@ fi ```markdown + !`pbcopy < file.txt` + if command -v pbcopy > /dev/null; then - pbcopy < file.txt +pbcopy < file.txt elif command -v xclip > /dev/null; then - xclip -selection clipboard < file.txt +xclip -selection clipboard < file.txt elif command -v clip.exe > /dev/null; then - cat file.txt | clip.exe +cat file.txt | clip.exe else - echo "Clipboard not available on this platform" +echo "Clipboard not available on this platform" fi ``` @@ -76,6 +83,7 @@ allowed-tools: Bash(*) # Check Dependencies Required tools: + - git - jq - node @@ -85,22 +93,23 @@ Checking availability... MISSING_DEPS="" for tool in git jq node; do - if ! command -v $tool > /dev/null; then +if ! command -v $tool > /dev/null; then MISSING_DEPS="$MISSING_DEPS $tool" - fi +fi done if [ -n "$MISSING_DEPS" ]; then - ❌ ERROR: Missing required dependencies:$MISSING_DEPS +❌ ERROR: Missing required dependencies:$MISSING_DEPS - INSTALLATION: - - git: https://git-scm.com/downloads - - jq: https://stedolan.github.io/jq/download/ - - node: https://nodejs.org/ +INSTALLATION: - Install missing tools and try again. +- git: https://git-scm.com/downloads +- jq: https://stedolan.github.io/jq/download/ +- node: https://nodejs.org/ - Exit. +Install missing tools and try again. + +Exit. fi ✓ All dependencies available @@ -141,22 +150,26 @@ Detecting available features... FEATURES="" if command -v gh > /dev/null; then - FEATURES="$FEATURES github" +FEATURES="$FEATURES github" fi if command -v docker > /dev/null; then - FEATURES="$FEATURES docker" +FEATURES="$FEATURES docker" fi Available features: $FEATURES if echo "$FEATURES" | grep -q "github"; then - # Full functionality with GitHub integration - echo "✓ GitHub integration available" + +# Full functionality with GitHub integration + +echo "✓ GitHub integration available" else - # Reduced functionality without GitHub - echo "⚠ Limited functionality: GitHub CLI not installed" - echo " Install 'gh' for full features" + +# Reduced functionality without GitHub + +echo "⚠ Limited functionality: GitHub CLI not installed" +echo " Install 'gh' for full features" fi [Adapt behavior based on available features...] @@ -177,26 +190,27 @@ allowed-tools: Read, Write # First Run Check if [ ! -f ".claude/command-initialized" ]; then - **Welcome to Command Name!** +**Welcome to Command Name!** - This appears to be your first time using this command. +This appears to be your first time using this command. - WHAT THIS COMMAND DOES: - [Brief explanation of purpose and benefits] +WHAT THIS COMMAND DOES: +[Brief explanation of purpose and benefits] - QUICK START: - 1. Basic usage: /command [arg] - 2. For help: /command help - 3. Examples: /command examples +QUICK START: - SETUP: - No additional setup required. You're ready to go! +1. Basic usage: /command [arg] +2. For help: /command help +3. Examples: /command examples - ✓ Initialization complete +SETUP: +No additional setup required. You're ready to go! - [Create initialization marker] +✓ Initialization complete - Ready to proceed with your request... +[Create initialization marker] + +Ready to proceed with your request... fi [Normal command execution...] @@ -218,7 +232,7 @@ description: Command with tips 💡 TIP: Did you know? You can speed up this command with the --fast flag: - /command --fast [args] +/command --fast [args] For more tips: /command tips ``` @@ -237,26 +251,29 @@ description: Forgiving command Argument: "$1" + if [ "$1" = "hlep" ] || [ "$1" = "hepl" ]; then - Did you mean: help? +Did you mean: help? - Showing help instead... - [Display help] +Showing help instead... +[Display help] - Exit. +Exit. fi + if [ "$1" != "valid-option1" ] && [ "$1" != "valid-option2" ]; then - ❌ Unknown option: $1 +❌ Unknown option: $1 + +Did you mean: - Did you mean: - - valid-option1 (most similar) - - valid-option2 +- valid-option1 (most similar) +- valid-option2 - For all options: /command help +For all options: /command help - Exit. +Exit. fi [Command continues...] @@ -276,12 +293,14 @@ The operation could not complete. **Diagnostic Information:** Environment: + - Platform: $(uname) - Shell: $SHELL - Working directory: $(pwd) - Command: /command $@ Checking common issues: + - Git repository: $(git rev-parse --git-dir 2>&1) - Write permissions: $(test -w . && echo "OK" || echo "DENIED") - Required files: $(test -f config.yml && echo "Found" || echo "Missing") @@ -355,6 +374,7 @@ allowed-tools: Read # Load User Configuration Default configuration: + - verbose: false - color: true - max_results: 10 @@ -362,15 +382,17 @@ Default configuration: Checking for user config: .claude/plugin-name.local.md if [ -f ".claude/plugin-name.local.md" ]; then - # Parse YAML frontmatter for settings - VERBOSE=$(grep "^verbose:" .claude/plugin-name.local.md | cut -d: -f2 | tr -d ' ') + +# Parse YAML frontmatter for settings + +VERBOSE=$(grep "^verbose:" .claude/plugin-name.local.md | cut -d: -f2 | tr -d ' ') COLOR=$(grep "^color:" .claude/plugin-name.local.md | cut -d: -f2 | tr -d ' ') - MAX_RESULTS=$(grep "^max_results:" .claude/plugin-name.local.md | cut -d: -f2 | tr -d ' ') +MAX_RESULTS=$(grep "^max_results:" .claude/plugin-name.local.md | cut -d: -f2 | tr -d ' ') - echo "✓ Using user configuration" +echo "✓ Using user configuration" else - echo "Using default configuration" - echo "Create .claude/plugin-name.local.md to customize" +echo "Using default configuration" +echo "Create .claude/plugin-name.local.md to customize" fi [Use configuration in command...] @@ -386,22 +408,27 @@ description: Command with smart defaults # Smart Defaults Configuration: -- Format: ${FORMAT:-json} # Defaults to json -- Output: ${OUTPUT:-stdout} # Defaults to stdout -- Verbose: ${VERBOSE:-false} # Defaults to false + +- Format: ${FORMAT:-json} # Defaults to json +- Output: ${OUTPUT:-stdout} # Defaults to stdout +- Verbose: ${VERBOSE:-false} # Defaults to false These defaults work for 80% of use cases. Override with arguments: - /command --format yaml --output file.txt --verbose +/command --format yaml --output file.txt --verbose Or set in .claude/plugin-name.local.md: \`\`\`yaml + --- + format: yaml output: custom.txt verbose: true + --- + \`\`\` ``` @@ -432,16 +459,16 @@ VERSION HISTORY: Command version: 2.1.0 Plugin version: [detect from plugin.json] -if [ "$PLUGIN_VERSION" < "2.0.0" ]; then - ❌ ERROR: Incompatible plugin version +if [ "$PLUGIN_VERSION" < "2.0.0" ]; then +❌ ERROR: Incompatible plugin version - This command requires plugin version >= 2.0.0 - Current version: $PLUGIN_VERSION +This command requires plugin version >= 2.0.0 +Current version: $PLUGIN_VERSION - Update plugin: - /plugin update plugin-name +Update plugin: +/plugin update plugin-name - Exit. +Exit. fi ✓ Version compatible @@ -459,20 +486,20 @@ description: Command with deprecation warnings # Deprecation Check if [ "$1" = "--old-flag" ]; then - ⚠️ DEPRECATION WARNING +⚠️ DEPRECATION WARNING - The --old-flag option is deprecated as of v2.0.0 - It will be removed in v3.0.0 (est. June 2025) +The --old-flag option is deprecated as of v2.0.0 +It will be removed in v3.0.0 (est. June 2025) - Use instead: --new-flag +Use instead: --new-flag - Example: - Old: /command --old-flag value - New: /command --new-flag value +Example: +Old: /command --old-flag value +New: /command --new-flag value - See migration guide: /command migrate +See migration guide: /command migrate - Continuing with deprecated behavior for now... +Continuing with deprecated behavior for now... fi [Handle both old and new flags during deprecation period...] @@ -532,6 +559,7 @@ Try it now: \`\`\` **What you'll get:** + - Security vulnerability detection - Code quality metrics - Performance bottleneck identification @@ -543,18 +571,21 @@ Security Analysis Results ========================= 🔴 Critical (2): - - SQL injection risk in users.js:45 - - XSS vulnerability in display.js:23 + +- SQL injection risk in users.js:45 +- XSS vulnerability in display.js:23 🟡 Warnings (5): - - Unvalidated input in api.js:67 + +- Unvalidated input in api.js:67 ... Recommendations: + 1. Fix critical issues immediately 2. Review warnings before next release 3. Run /analyze-code --fix for auto-fixes -\`\`\` + \`\`\` --- @@ -583,12 +614,14 @@ description: Command with feedback This helps improve the command for everyone. Rate this command: + - 👍 Helpful - 👎 Not helpful - 🐛 Found a bug - 💡 Have a suggestion Reply with an emoji or: + - /command feedback Your feedback matters! @@ -633,6 +666,7 @@ Part of the [Plugin Name] suite --- **Need Help?** + - Documentation: https://docs.example.com - Support: support@example.com - Community: https://community.example.com @@ -668,17 +702,18 @@ description: Idempotent command Checking if operation already completed... if [ -f ".claude/operation-completed.flag" ]; then - ℹ️ Operation already completed +ℹ️ Operation already completed - Completed at: $(cat .claude/operation-completed.flag) +Completed at: $(cat .claude/operation-completed.flag) - To re-run: - 1. Remove flag: rm .claude/operation-completed.flag - 2. Run command again +To re-run: - Otherwise, no action needed. +1. Remove flag: rm .claude/operation-completed.flag +2. Run command again - Exit. +Otherwise, no action needed. + +Exit. fi Performing operation... @@ -707,19 +742,19 @@ Performing changes in isolated environment... [Make changes in $TEMP_DIR] if [ $? -eq 0 ]; then - ✓ Changes validated +✓ Changes validated - Applying changes atomically... - mv $TEMP_DIR/* ./target/ +Applying changes atomically... +mv $TEMP_DIR/\* ./target/ - ✓ Operation complete +✓ Operation complete else - ❌ Changes failed validation +❌ Changes failed validation - Rolling back... - rm -rf $TEMP_DIR +Rolling back... +rm -rf $TEMP_DIR - No changes applied. Safe to retry. +No changes applied. Safe to retry. fi ``` @@ -785,17 +820,20 @@ description: Beta command (v0.9.0) Features may change based on feedback. BETA STATUS: + - Version: 0.9.0 - Stability: Experimental - Support: Limited - Feedback: Encouraged Known limitations: + - Performance not optimized - Some edge cases not handled - Documentation incomplete Help improve this command: + - Report issues: /command report-issue - Suggest features: /command suggest - Join beta testers: /command join-beta @@ -856,20 +894,21 @@ Current version: 2.1.0 Latest version: [check if available] if [ "$CURRENT_VERSION" != "$LATEST_VERSION" ]; then - 📢 UPDATE AVAILABLE +📢 UPDATE AVAILABLE + +New version: $LATEST_VERSION +Current: $CURRENT_VERSION - New version: $LATEST_VERSION - Current: $CURRENT_VERSION +What's new: - What's new: - - Feature improvements - - Bug fixes - - Performance enhancements +- Feature improvements +- Bug fixes +- Performance enhancements - Update with: - /plugin update plugin-name +Update with: +/plugin update plugin-name - Release notes: https://releases.example.com/v$LATEST_VERSION +Release notes: https://releases.example.com/v$LATEST_VERSION fi [Command continues...] diff --git a/.agents/skills/command-development/references/plugin-features-reference.md b/.agents/skills/command-development/references/plugin-features-reference.md index c89e906..3638e75 100644 --- a/.agents/skills/command-development/references/plugin-features-reference.md +++ b/.agents/skills/command-development/references/plugin-features-reference.md @@ -25,6 +25,7 @@ plugin-name/ ``` **Key points:** + - Commands are discovered at plugin load time - No manual registration required - Commands appear in `/help` with "(plugin:plugin-name)" label @@ -46,6 +47,7 @@ plugin-name/ ``` **Namespace behavior:** + - Subdirectory name becomes namespace - Shown as "(plugin:plugin-name:namespace)" in `/help` - Helps organize related commands @@ -54,12 +56,14 @@ plugin-name/ ### Command Naming Conventions **Plugin command names should:** + 1. Be descriptive and action-oriented 2. Avoid conflicts with common command names 3. Use hyphens for multi-word names 4. Consider prefixing with plugin name for uniqueness **Examples:** + ``` Good: - /mylyn-sync (plugin-specific prefix) @@ -79,6 +83,7 @@ Avoid: `${CLAUDE_PLUGIN_ROOT}` is a special environment variable available in plugin commands that resolves to the absolute path of the plugin directory. **Why it matters:** + - Enables portable paths within plugin - Allows referencing plugin files and scripts - Works across different installations @@ -100,6 +105,7 @@ Read template: @${CLAUDE_PLUGIN_ROOT}/templates/report.md ``` **Expands to:** + ``` Run analysis: !`node /path/to/plugins/plugin-name/scripts/analyze.js` @@ -164,15 +170,19 @@ Review results and report status. ### Best Practices 1. **Always use for plugin-internal paths:** + ```markdown # Good + @${CLAUDE_PLUGIN_ROOT}/templates/foo.md # Bad - @./templates/foo.md # Relative to current directory, not plugin + + @./templates/foo.md # Relative to current directory, not plugin ``` 2. **Validate file existence:** + ```markdown --- description: Use plugin config if exists @@ -186,6 +196,7 @@ Review results and report status. ``` 3. **Document plugin file structure:** + ```markdown