Command Development

Quick Start

If you need to create a command: Place in folder matching hierarchy (e.g., .claude/commands/meta/refine/rules.md).

If you need to audit a command: Invoke this skill directly to validate structure and patterns.

If you need to refine a command: Compare against patterns and apply fixes.

Navigation

Philosophy

Commands are stateless interfaces that bind Reality to logic. Unlike skills (which are self-contained knowledge), commands exist at the boundary between Claude and the filesystem, injecting dynamic content at invocation time.

Key insight: Commands are "Skin" - thin wrappers that gather context and delegate to Knowledge Skills ("Brain"). They should contain minimal logic.

Why this matters:

• Commands are auto-named from file paths (no name field in frontmatter)
• Commands use @ and ! for dynamic content injection
• Commands are single-file (no references/ folder)
• Commands delegate to Skills for complex logic

PATTERN: Namespacing

Commands use folder hierarchy for namespacing. Path maps to colon syntax:

Namespacing Rules

Flat vs Namespaced

Namespace Categories

PATTERN: Thin Interface

Commands are "Skin" - thin interfaces that bind Reality to Knowledge Skills ("Brain").

Three Command Use-Cases

Thin Interface Rules

1. Commands MUST provide at least one "Reality" source (@ or !)
2. Commands SHOULD NOT contain complex logic - delegate to Skills
3. Commands MUST NOT delegate to other commands (only to Skills)
4. Skill chaining requires context: forked in frontmatter for result return
5. Without context: forked, subprocess results don't reliably return

Context Forking (Orchestration)

When a command/skill must orchestrate subprocesses and receive their results:

Without context:forked:

---
description: "Call skill B."
---
1. Invoke `skill-b` skill.
2. [Skill A ends here - unreliable return]

Skill B runs but results don't reliably return to Skill A.

With context:forked:

---
description: "Call skill B with result return."
context: forked
---

1. Invoke `skill-b` skill.
2. [Skill B completes, result returns to Skill A]
3. Process skill B results...

How it works:

• context: forked in frontmatter makes the component behave like a subagent
• Results reliably return to the parent for analysis
• Essential for: multi-step workflows, result aggregation, orchestration

Reality Source Requirement

Delegation Pattern

## Execution
1. Read the provided skill content.
2. Invoke `skill-development` skill.
3. Compare content against standards.
4. Apply refinements autonomously.

PATTERN: Frontmatter

Commands use minimal frontmatter:

---
description: "Brief description, non spoiling of the content. Use when {trigger condition + keywords + key sentences user might say that should lead the command to be triggered}. Not for {exclusions}."
argument-hint: "<identifier>"  # Optional
context: fork  # Optional: for orchestration, see ## PATTERN: Thin Interface
---

Frontmatter Fields

Description Format

Description Examples

Basic:

description: "Create portable skills with SKILL.md. Use when building new skills or documenting reusable patterns."

Intermediate:

description: "Refine skill content for quality. Use when improving existing skills, fixing quality issues, or updating documentation. Not for creating new skills from scratch."

Gold Standard:

description: "Autonomously correct project rules when negative feedback occurs. Use PROACTIVELY when user says 'no', 'wrong', 'wait', 'not that', or 'actually'. Identifies root cause and rewrites offending instruction. Not for new feature requests or unrelated changes."

PATTERN: Perfect Command

Simple Command (Context Gathering)

---
description: "Show current git state. Use when needing branch and status information. Includes branch name, status, and modified files."
---

<mission_control>
<objective>Display current git state for context</objective>
<success_criteria>Git branch and status displayed</success_criteria>
</mission_control>

## Quick Start
Current git state shown below.

## Git State

<injected_content>
!`git branch --show-current`
!`git status --short`
</injected_content>

Medium Command (With Delegation)

---
description: "Refine skill content for quality. Use when improving existing skills. Includes pattern validation. Not for creating new skills."
argument-hint: "<skill-name>"
---

<mission_control>
<objective>Refine skill to meet quality standards</objective>
<success_criteria>Skill passes all validation checks</success_criteria>
</mission_control>

## Quick Start
Refining skill: $1

## Context

Current Skill: @.claude/skills/$1/SKILL.md
Project State: !`ls .claude/skills`

## Execution
1. Read the provided skill content.
2. Invoke `skill-development` skill.
3. Compare content against standards.
4. Apply refinements autonomously.

Complex Command (Liaison + Delegation)

---
description: "Clarify intent and delegate to appropriate engine. Use when user intent is ambiguous. Includes clarification questions. Not for clear intents."
disable-model-invocation: true
---

<mission_control>
<objective>Clarify ambiguous intent and route to appropriate handler</objective>
<success_criteria>User intent clarified and routed to correct engine</success_criteria>
</mission_control>

## Clarification
[AskUserQuestion to determine user intent]

## Execution
[Based on answer, invoke appropriate Knowledge Skill]

ANTI-PATTERN: Common Failures

Anti-Pattern: No Reality Source

❌ Wrong:
---
description: "Validate skill structure."
---
## Execution
1. Read skill content.
2. Check frontmatter.
3. Validate structure.

Fix: Add @ or ! to provide reality source:

✅ Correct:
---
description: "Validate skill structure."
---
## Context
Skill: @.claude/skills/$1/SKILL.md

Anti-Pattern: Command Contains Complex Logic

❌ Wrong:
---
description: "Create perfect skill."
---
## Execution
1. Write frontmatter.
2. Add Quick Start section.
3. Add Navigation table.
4. Add Philosophy section.
5. Add PATTERN sections.
6. Add ANTI-PATTERN sections.
7. Add Validation Checklist.
8. Add critical_constraint.

Fix: Delegate to Knowledge Skill:

✅ Correct:
---
description: "Create perfect skill."
---
## Execution
1. Read `skill-development` skill.
2. Invoke `skill-development` skill with context.
3. Apply refinements.

Anti-Pattern: References Folder

❌ Wrong:
.claude/commands/example/
├── command.md
└── references/
    └── detail.md

✅ Correct:
.claude/skills/example/
├── SKILL.md
└── references/
    └── detail.md

Fix: Commands are single-file. If you need references/, build a Skill.

Anti-Pattern: Slash Command Reference

❌ Wrong:
---
description: "Run meta refinement. See /meta:refine:all for details."
---

Fix: Never reference slash commands:

✅ Correct:
---
description: "Run meta refinement. Use when improving multiple components. Orchestrates all refine operations."
---

Anti-Pattern: Missing Frontmatter Description

❌ Wrong:
---
# My Command
## Quick Start
Do something.
---

Fix: Add proper frontmatter:

✅ Correct:
---
description: "Do something. Use when [condition]. Includes [features]."
---
## Quick Start
Do something.

Validation Checklist

Before claiming command authoring complete:

Structure:

• Single markdown file in .claude/commands/
• File has .md extension
• No name field in frontmatter (auto-derived)
• Valid frontmatter with description

Namespacing:

• File path matches intended command invocation
• Folders used for namespacing if applicable

Injection:

• At least one @ or ! injection present
• Injections wrapped in <injected_content> if grouping
• Missing files handled gracefully

Thin Interface:

• Command delegates to Knowledge Skill for logic
• Command does not contain complex logic
• Command does not reference slash commands

Frontmatter:

• Description uses "Use when" format
• argument-hint present if command uses $1

Recognition Questions

Validation Checklist

Before claiming command complete:

• Namespacing follows path-to-colon syntax
• At least one @ or ! injection provides reality source
• Complex logic delegated to skills (not commands)
• No references to slash commands
• Single-file format, no references/ folder
• Description follows What-When-Not format
• Argument hints for positional parameters if applicable
• context: fork for orchestration with result return

1. This skill MUST NEVER reference a slash command (e.g., /meta)
2. Skills never know about commands that trigger them
3. All validation logic MUST reside in this skill
4. Never use relative paths pointing outside the skill itself. When referencing other components, use: "invoke skill-name" or "invoke skill-name and read its file"

Self-Contained:

1. Command validation patterns MUST be documented here
2. No external dependencies for validation
3. Fork isolation (works in vacuum)

Thin Interface:

1. Commands MUST provide at least one reality source (@ or !)
2. Commands MUST NOT delegate to other commands
3. Skill chaining requires context: forked in frontmatter for result return
4. Without context: forked, subprocess results don't reliably return