Skip to main content
Commands in Pro Workflow are markdown files with YAML frontmatter that define slash commands (e.g., /wrap-up, /develop). They support dynamic string substitution and tool constraints.

​
Command Structure

---
description: What this command does
argument-hint: <placeholder>
allowed-tools: ["Read", "Bash"]
model: opus
---

# Command Instructions

Command body with dynamic substitution:
- User input: $ARGUMENTS
- First word: $ARGUMENTS[0]
- Session ID: ${CLAUDE_SESSION_ID}
- Live output: !`git branch --show-current`

​
Frontmatter Fields

​
description
string
required
Short description shown in the / command menu. Keep under 80 characters.
​
argument-hint
string
Placeholder text for command arguments. Example: <feature description>, <query>.
​
allowed-tools
string[]
Tool whitelist for this command. Only these tools will be available during execution.Example: ["Read", "Glob", "Grep"] for read-only exploration.
​
model
string
Model override for this command. Values: opus, sonnet, haiku.
​
disallowed-tools
string[]
Tool blacklist. Blocks specific tools from being used.Example: ["Edit", "Write"] for read-only commands.

​
Dynamic Substitution

​
User Arguments

# Command: /search testing edge cases

Query: $ARGUMENTS
# Expands to: testing edge cases

​
Environment Variables

Session: ${CLAUDE_SESSION_ID}
# Expands to: session-abc123

​
Live Command Output

Use !`command` to inject live shell output: 
Current branch: !`git branch --show-current`
Last commit: !`git log --oneline -1`
Modified files: !`git diff --name-only`

# Expands to:
# Current branch: feature/add-auth
# Last commit: abc123d Add login endpoint
# Modified files: src/auth.ts
Live commands execute immediately when the command is invoked. Avoid slow operations.

​
Tool Constraints

​
Read-Only Commands

---
description: Explore code without making changes
allowed-tools: ["Read", "Glob", "Grep", "Bash"]
---

Explore the codebase:
1. Find all TypeScript files
2. Read key interfaces
3. Summarize architecture

Do NOT edit any files.

​
Edit-Only Commands

---
description: Apply automated refactoring
allowed-tools: ["Read", "Edit"]
---

Refactor all files matching pattern:
1. Read each file
2. Apply transformation
3. Verify syntax

Do NOT run tests or git commands.

​
Blocked Tools

---
description: Safe exploration for untrusted tasks
disallowed-tools: ["Bash", "Write"]
---

Explore safely:
- Can read files
- Can search
- Cannot execute shell commands
- Cannot create new files

​
Model Selection

---
description: Break down complex task into plan
model: opus
allowed-tools: ["Read", "Glob", "Grep"]
---

Analyze the task and create a detailed plan.

​
Examples

---
description: End-of-session ritual with quality checks
allowed-tools: ["Read", "Bash"]
---

# Wrap-Up Ritual

Session: ${CLAUDE_SESSION_ID}
Branch: !`git branch --show-current`

## Checklist

1. **Changes Audit**
   - Modified files: !`git diff --name-only`
   - Uncommitted: !`git status --short`

2. **Quality Check**
   - Lint: !`npm run lint 2>&1 | head -5`
   - Tests: !`npm test -- --changed --passWithNoTests`

3. **Learning Capture**
   - What mistakes were made?
   - What patterns worked?
   - Format: `[LEARN] Category: Rule`

4. **Summary**
   - One paragraph: what was accomplished, current state, next steps

---
description: Build a feature using Research > Plan > Implement phases
argument-hint: <feature description>
model: opus
---

# Multi-Phase Feature Development

Feature: $ARGUMENTS

## Phase 1: Research

Explore the codebase to understand scope:
1. Find relevant files
2. Check dependencies
3. Score confidence (0-100)

**Decision:**
- Score >= 70 → Move to Phase 2
- Score < 70 → Gather more context

## Phase 2: Plan

Present plan for approval:
PLAN: $ARGUMENTSGoal: [one sentence]Files to modify:
  1. path/file.ts - [changes]
Approach:
  1. [step]
Risks:
  • [potential issue]

**Wait for approval before Phase 3.**

## Phase 3: Implement

1. Make changes in plan order
2. Run tests after each file
3. Pause for review every 5 edits
4. Run quality gates at end

---
description: Search learnings database
argument-hint: <query>
model: haiku
---

# Search Learnings

Query: $ARGUMENTS

Run this:

\`\`\`bash
node -e "
const { createStore, searchLearnings } = require('pro-workflow');
const store = createStore();
const results = searchLearnings(store.db, '$ARGUMENTS', { limit: 10 });

if (results.length === 0) {
  console.log('No learnings found.');
} else {
  console.log('Found ' + results.length + ' learnings:\\n');
  for (const r of results) {
    console.log('#' + r.id + ' [' + r.category + '] ' + r.rule);
    if (r.mistake) console.log('  Mistake: ' + r.mistake);
  }
}

store.close();
"
\`\`\`

​
Command Discovery

Commands are discovered from:
  1. Project: .claude/commands/*.md
  2. User: ~/.claude/commands/*.md
  3. Plugin: ~/.claude/plugins/*/commands/*.md
File name becomes command name:
  • wrap-up.md → /wrap-up
  • learn-rule.md → /learn-rule
Use hyphens in filenames, not underscores or spaces.

​
Precedence

When multiple commands have the same name:
  1. Project (.claude/commands/) — highest priority
  2. User (~/.claude/commands/)
  3. Plugin (~/.claude/plugins/*/commands/) — lowest priority

​
Best Practices

Short Descriptions

Keep description under 80 characters for clean / menu display.

Clear Arguments

Use descriptive argument-hint like <feature description>, not <input>.

Constrain Tools

Use allowed-tools to enforce read-only or specific tool access.

Live Context

Use !`command` sparingly. Slow commands delay invocation.

​
Validation

Test your command: 
# Validate frontmatter
yq eval '.description' commands/my-command.md

# Test substitution
echo "User input: test" | sed 's/test/$ARGUMENTS/'

# Invoke command
/my-command test argument

​
Next Steps

Arguments

Advanced argument parsing and validation

Delegation

Delegate commands to agents

Agents

Create agents for command execution

Skills

Preload skills into commands

Build docs developers (and LLMs) love

Get started for freeTalk to us