Agent Skills: Commands Manager - Branch of JARVIS-06

Commands Manager - Branch of JARVIS-06

Build and improve commands following the commands-management policy.

Policy Source

Primary policy: JARVIS-06 → .claude/skills/commands-management/SKILL.md

This branch executes the policy defined by JARVIS-06. Always sync with Primary before major operations.

Quick Decision Tree

Task Received
    │
    ├── Create new command? ─────────────> Workflow 1: Build
    │   └── What type?
    │       ├── Simple action ───────────> Single-phase command
    │       ├── Complex workflow ────────> Multi-phase command
    │       └── Skill invocation ────────> Skill-invoking command
    │
    ├── Adapt marketplace command? ──────> Workflow 3: Adapt
    │
    ├── Fix existing command? ───────────> Workflow 2: Improve
    │
    └── Validate command? ───────────────> Validation Checklist

Command Overview

Slash commands are frequently-used prompts defined as Markdown files that Claude executes during interactive sessions.

Key concepts:

• Markdown file format for commands
• YAML frontmatter for configuration
• Dynamic arguments ($ARGUMENTS, $1, $2)
• File references (@$1, @file.txt)
• Bash execution for context (!command)
• Commands are instructions FOR Claude, not messages TO user

Critical: Commands are Instructions FOR Claude

Commands are written for agent consumption, not human consumption.

When a user invokes /command-name, the command content becomes Claude's instructions.

Correct (instructions for Claude):

Review this code for security vulnerabilities including:
- SQL injection
- XSS attacks
- Authentication issues

Provide specific line numbers and severity ratings.

Incorrect (messages to user):

This command will review your code for security issues.
You'll receive a report with vulnerability details.

Always use the first approach - tell Claude what to do.

Command Locations

| Location | Scope | Label | Use For | |----------|-------|-------|---------| | .claude/commands/ | Project | (project) | Team workflows, project-specific | | ~/.claude/commands/ | User | (user) | Personal workflows, cross-project | | plugin/commands/ | Plugin | (plugin-name) | Plugin-bundled functionality |

Command Types

| Type | Phases | Use When | |------|--------|----------| | Single-phase | 1 | Simple, direct action | | Multi-phase | 2-4 | Complex workflow with stages | | Skill-invoking | 1+ | Needs skill knowledge |

Workflow 1: Build New Command

Step 1: Define Command Purpose

Answer these questions:

• What task does this command automate?
• What arguments does it need (if any)?
• What tools should it use?
• Does it need multiple phases?
• Should it invoke a skill?
• Does it need bash execution for context?

Step 2: Write Frontmatter

---
description: Brief description for /help (<60 chars)
argument-hint: [file-path] [options]
allowed-tools: Read, Write, Edit, Bash(git:*)
model: inherit
---

Frontmatter fields:

| Field | Required | Purpose | Example | |-------|----------|---------|---------| | description | Yes | Shows in /help, max 60 chars | "Review code for security issues" | | argument-hint | If args | Shows expected arguments | "[file-path] [options]" | | allowed-tools | Optional | Restricts available tools | "Read, Bash(git:*)" | | model | Optional | Override model | sonnet/opus/haiku | | disable-model-invocation | Optional | Prevent programmatic calls | true |

Step 3: Write Command Body

Single-Phase Template:

---
description: [What it does in <60 chars]
argument-hint: [expected-args]
allowed-tools: Read, Write, Edit
---

[Action verb] the [target] to [achieve goal]:

1. [First step with specific action]
2. [Second step]
3. [Third step]

Report [expected output format].

Multi-Phase Template:

---
description: [What it does]
argument-hint: [args]
---

## Phase 1: Analysis

Analyze [target] for [criteria]:

1. [Analysis step 1]
2. [Analysis step 2]

Document findings before proceeding.

## Phase 2: Implementation

Based on Phase 1 findings, implement [changes]:

1. [Implementation step 1]
2. [Implementation step 2]

## Phase 3: Verification

Verify implementation:

1. [Verification step 1]
2. [Verification step 2]

Report completion status with summary.

Skill-Invoking Template:

---
description: [What it does]
disable-model-invocation: true
---

Invoke the [skill-name] skill to [purpose].

Follow the skill's workflow for [specific task].

Report results following skill's output format.

Step 4: Use Arguments Correctly

| Syntax | Purpose | Example | |--------|---------|---------| | $ARGUMENTS | All args as single string | "Fix issue #$ARGUMENTS" | | $1, $2, $3 | Positional arguments | "Compare $1 with $2" | | @$1 | Include file contents | "Review code in @$1" | | @file.txt | Static file reference | "Load @config.json" |

Examples:

# Using $ARGUMENTS (all args)
---
description: Create PR with given title
argument-hint: [title]
---

Create a pull request with title: $ARGUMENTS

# Using positional args
---
description: Compare two files
argument-hint: [file1] [file2]
---

Compare the contents of @$1 with @$2

# Using @$1 for file content
---
description: Review code file
argument-hint: [file-path]
---

Review the following code for issues:

@$1

Provide feedback on quality and suggestions.

Step 5: Add Bash Execution (if needed)

Use ! backticks to execute bash and include output:

---
description: Review changed files
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

Provide specific feedback for each file.

Bash execution patterns:

# Get git status
Current branch: !`git branch --show-current`

# Run tests
Test results: !`npm test 2>&1`

# Check environment
Node version: !`node --version`

Note: Requires Bash in allowed-tools with appropriate pattern.

Step 6: Save and Validate

Save to: commands/[command-name].md

Run validation checklist.

Workflow 2: Improve Existing Command

Step 1: Analyze Current State

# Read command file
cat commands/[name].md

# Check for common issues:
# - Written as message TO user?
# - Missing description?
# - No argument-hint when needed?
# - Missing output format?

Step 2: Gap Analysis

| Component | Check | Common Issues | |-----------|-------|---------------| | description | Present? <60 chars? | Missing or too long | | argument-hint | Present if args needed? | Missing when command takes args | | body | Instructions FOR Claude? | Written as "This command will..." | | body | Imperative form? | Uses "I will" or "should" | | output | Defined? | No "Report..." section | | bash | Correct syntax? | Wrong backtick pattern |

Step 3: Apply Fixes

Converting message to instructions:

Before (wrong):

This command will analyze your code and find bugs.
You'll receive a report when it's done.

After (correct):

Analyze the code for bugs and issues:

1. Search for common error patterns
2. Check for security vulnerabilities
3. Identify performance issues

Report findings with severity levels and fix suggestions.

Adding output format:

Report results as:
- Summary: [1-2 sentences]
- Findings: [Bulleted list]
- Recommendations: [Action items]

Converting to multi-phase:

## Phase 1: Discovery
[Analysis steps]

## Phase 2: Action
[Implementation steps]

## Phase 3: Verification
[Check steps]

Fixing bash execution:

Wrong:

`git status`

Correct:

!`git status`

Step 4: Validate

Run full validation checklist.

Workflow 3: Adapt Marketplace Command

When taking a command from wshobson-agents, obra-superpowers, or similar:

Step 1: Read Original Command

cat marketplace-plugin/commands/[command].md

Note:

• Frontmatter structure
• Phase structure (if multi-phase)
• Argument handling
• Tool restrictions
• Bash execution patterns

Step 2: Identify JARVIS Fit

| Original Purpose | JARVIS Application | |------------------|-------------------| | Generic code review | Category-specific code review | | Generic deployment | MCP-aware deployment | | Generic testing | Category testing patterns | | Generic workflow | 4-plugin aware workflow |

Step 3: Adapt Frontmatter

Original:

---
description: Review code for issues
---

Adapted for JARVIS:

---
description: Review code following JARVIS standards
argument-hint: [file-path]
allowed-tools: Read, Grep, Glob
---

Step 4: Adapt Body

Add JARVIS-specific context:

Review the code following JARVIS ecosystem standards:

1. Check compliance with Primary Skill patterns
2. Verify MCP tool usage follows category guidelines
3. Ensure 4-plugin architecture is respected
4. Validate CLAUDE.md references are current

Report findings with JARVIS-specific recommendations.

Add category-specific instructions:

For this category (JARVIS-XX), additionally check:
- [Category-specific check 1]
- [Category-specific check 2]

Step 5: Validate Adaptation

Run full validation checklist.

Plugin Command Features

CLAUDE_PLUGIN_ROOT Variable

Plugin commands can reference plugin files portably:

---
description: Analyze using plugin script
allowed-tools: Bash(node:*)
---

Run analysis: !`node ${CLAUDE_PLUGIN_ROOT}/scripts/analyze.js $1`

Review results and report findings.

Common patterns:

# 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

Plugin Command Organization

plugin-name/
├── commands/
│   ├── foo.md              # /foo (plugin:plugin-name)
│   ├── bar.md              # /bar (plugin:plugin-name)
│   └── utils/
│       └── helper.md       # /helper (plugin:plugin-name:utils)
└── plugin.json

Subdirectories create namespaces shown in /help.

Integration with Plugin Components

Agent integration:

---
description: Deep code review
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

Skill integration:

---
description: Document API with standards
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

Multi-component workflow:

---
description: Comprehensive review workflow
argument-hint: [file]
allowed-tools: Bash(node:*), Read
---

Target: @$1

Phase 1 - Static Analysis:
!`node ${CLAUDE_PLUGIN_ROOT}/scripts/lint.js $1`

Phase 2 - Deep Review:
Launch code-reviewer agent for detailed analysis.

Phase 3 - Standards Check:
Use coding-standards skill for validation.

Phase 4 - Report:
Template: @${CLAUDE_PLUGIN_ROOT}/templates/review.md

Compile findings into report following template.

Validation Patterns

Argument Validation

---
description: Deploy with validation
argument-hint: [environment]
---

Validate environment: !`echo "$1" | grep -E "^(dev|staging|prod)$" || echo "INVALID"`

If $1 is valid environment:
  Deploy to $1
Otherwise:
  Explain valid environments: dev, staging, prod
  Show usage: /deploy [environment]

File Existence Checks

---
description: Process configuration
argument-hint: [config-file]
---

Check file exists: !`test -f $1 && echo "EXISTS" || echo "MISSING"`

If file exists:
  Process configuration: @$1
Otherwise:
  Explain where to place config file
  Provide example configuration

Plugin Resource Validation

---
description: Run plugin analyzer
allowed-tools: Bash(test:*)
---

Validate plugin setup:
- Script: !`test -x ${CLAUDE_PLUGIN_ROOT}/bin/analyze && echo "OK" || echo "MISSING"`
- Config: !`test -f ${CLAUDE_PLUGIN_ROOT}/config.json && echo "OK" || echo "MISSING"`

If all checks pass, run analysis.
Otherwise, report missing components.

Validation Checklist

Structure

• [ ] File in commands/ directory with .md extension
• [ ] Filename is lowercase with hyphens
• [ ] Valid YAML frontmatter between --- markers

Frontmatter

• [ ] description present and under 60 characters
• [ ] argument-hint present if command takes arguments
• [ ] allowed-tools present if tool restriction needed
• [ ] model valid if specified (sonnet/opus/haiku/inherit)

Body Content

• [ ] Written as instructions FOR Claude (imperative)
• [ ] Does NOT use "I will", "This command will", "You'll get"
• [ ] Uses action verbs: "Analyze", "Create", "Review", "Check"
• [ ] Has numbered steps for procedures
• [ ] Has "Report..." section defining output format

Arguments (if applicable)

• [ ] $ARGUMENTS used correctly for all args
• [ ] $1, $2, $3 used correctly for positional args
• [ ] @$1 used correctly for file content inclusion
• [ ] argument-hint matches actual usage

Bash Execution (if applicable)

• [ ] Uses ! backticks syntax (!command)
• [ ] allowed-tools includes Bash with appropriate pattern
• [ ] Commands are safe and tested
• [ ] Error output handled (2>&1 if needed)

Multi-Phase (if applicable)

• [ ] Phases clearly marked with ## headers
• [ ] Each phase has distinct purpose
• [ ] Phases build on each other logically
• [ ] Final phase includes verification

Plugin Commands (if applicable)

• [ ] Uses ${CLAUDE_PLUGIN_ROOT} for plugin paths
• [ ] No hardcoded absolute paths
• [ ] Resources exist in plugin

Command Examples

Example 1: Simple Review Command

---
description: Review file for code quality
argument-hint: [file-path]
allowed-tools: Read, Grep
---

Review @$1 for code quality issues:

1. Check for code style violations
2. Identify potential bugs
3. Look for performance issues
4. Verify error handling

Report findings with:
- Issue: [description]
- Severity: [high/medium/low]
- Suggestion: [fix recommendation]

Example 2: Multi-Phase Deployment Command

---
description: Deploy category to production
argument-hint: [category-number]
allowed-tools: Read, Bash(git:*), Bash(gcloud:*)
---

## Phase 1: Pre-Deployment Checks

Verify JARVIS-$1 is ready for deployment:

1. Check all tests pass
2. Verify CLAUDE.md is up to date
3. Confirm Primary Skill has no TODOs
4. Validate mcp.json configuration

Document any issues before proceeding.

## Phase 2: Deployment

Deploy JARVIS-$1:

1. Tag the release with version
2. Push to production branch
3. Deploy MCP server if applicable
4. Update BigQuery tables if needed

## Phase 3: Verification

Verify deployment success:

1. Test MCP tools are responding
2. Verify category loads correctly
3. Check logs for errors

Report deployment status with:
- Version deployed
- Components updated
- Any issues encountered

Example 3: Skill-Invoking Command

---
description: Improve category following dev cycle
argument-hint: [category-number]
disable-model-invocation: true
---

Invoke the category-optimizer skill for JARVIS-$1.

Follow the skill's self-improvement cycle:

1. Analyze current CLAUDE.md
2. Review settings.json
3. Check Primary Skill completeness
4. Apply improvements

Report all changes made following the skill's output format.

Example 4: Plugin Command with Bash

---
description: Run full analysis pipeline
argument-hint: [target-file]
allowed-tools: Read, Bash(node:*)
---

Target: @$1

Run analysis pipeline:

Step 1 - Lint:
!`node ${CLAUDE_PLUGIN_ROOT}/scripts/lint.js $1`

Step 2 - Type Check:
!`node ${CLAUDE_PLUGIN_ROOT}/scripts/typecheck.js $1`

Step 3 - Security Scan:
!`node ${CLAUDE_PLUGIN_ROOT}/scripts/security.js $1`

Compile all findings and provide summary with:
- Total issues found
- Issues by severity
- Recommended fixes

Troubleshooting

| Issue | Cause | Fix | |-------|-------|-----| | Command not appearing | Wrong directory | Check .claude/commands/ or commands/ | | Command not appearing | Missing .md extension | Add .md extension | | Arguments not working | Wrong syntax | Use $1 not ${1}, $ARGUMENTS not ${ARGUMENTS} | | File reference fails | Missing @ | Use @$1 not $1 for file content | | Bash not executing | Wrong syntax | Use !cmd not cmd or $(cmd) | | Bash fails | No tool permission | Add Bash(pattern:*) to allowed-tools | | Plugin path fails | Wrong variable | Use ${CLAUDE_PLUGIN_ROOT} not $PLUGIN_ROOT |

Common Issues & Fixes

| Issue | Diagnosis | Fix | |-------|-----------|-----| | Written as message | Uses "This command will" | Rewrite with imperative verbs | | No output format | Missing "Report..." | Add output specification | | Args not working | Wrong syntax | Check $ARGUMENTS vs $1 vs @$1 | | Too vague | "Check the code" | Add specific numbered steps | | Missing hint | Takes args but no hint | Add argument-hint field | | Tool errors | Needs restricted tool | Add allowed-tools field | | Bash not running | Missing allowed-tools | Add Bash(pattern:*) |

Best Practices

DO:

• ✅ Write instructions FOR Claude
• ✅ Use imperative verbs (Analyze, Create, Review)
• ✅ Include numbered steps for procedures
• ✅ Define output format with "Report..."
• ✅ Add argument-hint when taking arguments
• ✅ Use appropriate tool restrictions
• ✅ Test commands before deployment

DON'T:

• ❌ Write messages TO user ("This will...")
• ❌ Use vague instructions ("Check the code")
• ❌ Skip output format definition
• ❌ Forget argument-hint for arg-taking commands
• ❌ Use Bash(*) when specific pattern works
• ❌ Hardcode paths in plugin commands
• ❌ Skip validation

When to Use This Skill

• User asks to create a new slash command
• User asks to adapt a marketplace command
• User asks to validate command structure
• User asks to fix command that's not working
• User asks about command arguments or bash execution
• DEV-Manager detects command issues during improvement cycle
• Regular improvement cycle (~6 sessions)

Sync Protocol

Before executing any workflow:

1. Read JARVIS-06's commands-management SKILL.md
2. Check for policy updates
3. Apply current policy, not cached knowledge