Command Authoring

Quick Start

If you need to inject file content: Use @path pattern at invocation time.

If you need to execute shell commands: Use !`command` for dynamic state.

If you need graceful file handling: Wrap @path in <injected_content> with fallback text.

If you need argument handling: Use $1 for unique identifiers (IDs, hashes, slugs) only.

Navigation

PATTERN: @ Path Injection

Basic @ Syntax

<injected_content>
@.claude/workspace/handoffs/diagnostic.yaml
</injected_content>

Or inline:

Current handoff: @.claude/workspace/handoffs/latest.yaml

What @ Does

At invocation time, the file content replaces the @path pattern. This captures the current state of files that change between sessions.

@ Rules

@ Use Cases

Error Handling

Graceful File Handling

<injected_content>
@.claude/workspace/handoffs/diagnostic.yaml
</injected_content>

If file doesn't exist: Create new diagnostic

Multiple File Injection

<injected_content>
@.claude/workspace/handoffs/diagnostic.yaml
@.claude/workspace/handoffs/handoff.yaml
</injected_content>

PATTERN: ! Command Injection

Basic ! Syntax

Current branch: !`git branch --show-current`
Git status: !`git status --short`

What ! Does

At invocation time, the bash command executes and its output replaces the !`command` pattern. This captures runtime state that changes between invocations.

! Rules

! Use Cases

Error Handling

Safe Commands

✅ Safe:
!`git branch --show-current`
!`gh run list --limit 1 --json conclusion`
!`pwd`
!`ls *.md`

❌ Unsafe:
!`rm file.ts`
!`git push --force`
!`chmod -R 777 .`

Graceful Patterns

<injected_content>
@.claude/workspace/handoff.yaml
</injected_content>

If no handoff exists: Create new session

Current branch: !`git branch --show-current 2>/dev/null || echo "detached"`

PATTERN: Command Structure

Single-File Structure

Commands are single markdown files:

.claude/commands/folder-name.md

Or flat structure:

.claude/commands/command-name.md

Flat Structure

.claude/commands/analyze.md
.claude/commands/create.md
.claude/commands/verify.md

Nested Structure

.claude/commands/analysis/
├── diagnose.md
├── explore.md
└── reason.md

Command Scope

Command Components

What Commands Contain

What Commands Don't Contain

Frontmatter Fields

Commands use minimal frontmatter - no name field (auto-derived from path):

---
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: hint for positional args
context: fork  # Optional: for orchestration, see ## PATTERN: Thin Interface
---

All Frontmatter Fields

Example Frontmatter

---
description: "Refine skill content for quality and portability. Use when improving existing skills, fixing quality issues, or updating documentation. Includes pattern validation and anti-pattern detection. Not for creating new skills from scratch."
argument-hint: "<skill-name>"
hooks:
  PreToolUse:
    - matcher: "tool == \"Bash\" && tool_input.command matches \"rm\""
      type: prompt
      prompt: "About to run rm - confirm this is intentional."
---

Argument Handling

String Substitutions

Best Practices

1. Discovery: Commands available via slash command menu
2. Security: Limit allowed-tools to essentials when needed
3. Organization: Use subdirectories for namespacing complex projects

Command Frontmatter

---
description: "Verb + object. Use when [condition]. Includes [features]. Not for [exclusions]."
---

Command Body

## Quick Start

**If you need X:** Do Y

## Core Content

[Content with @ and ! injection patterns]

<injected_content>
@path/to/file.yaml
</injected_content>

Commands vs Skills

PATTERN: Engine Separation

Commands SHOULD NOT contain complex logic. They should:

1. Gather context (via @/!)
2. Ask clarifying questions (if Liaison)
3. Invoke the appropriate Skill

Anti-Pattern: Command with Logic

❌ Wrong: A 200-line "how-to" guide in a command
✅ Correct: 5-line context gatherer → invoke Skill

Command Responsibilities

When to Move to Skill

Use a Skill instead of a Command when:

• You need references/ for documentation
• Logic exceeds 50 lines of content
• Multiple patterns and anti-patterns needed
• Complex decision trees required

Rule: If you need references/, you are building a Skill, not a Command.

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 IS allowed when using context:forked in frontmatter

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

Delegation Pattern

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

Reality Source Requirement

PATTERN: Argument Patterns

Dual-Mode Pattern

Commands can operate in two modes:

Argument Rules

Example

$IF($1, Use the provided argument, Scan conversation for context and infer intent)

Argument Use Cases

Valid Arguments

✅ Valid (identifiers only):
session-abc123  # session ID
hash-xyz789     # file hash
my-project      # project slug

Invalid Arguments

❌ Invalid (flags not allowed):
--verbose               # flag
output-format json      # flag with value
--max-results 10        # flag with value

PATTERN: Error Handling

@ Error Behavior

! Error Behavior

ANTI-PATTERN: Common Mistakes

Anti-Pattern: Using @ in Skills

❌ Wrong (skill):
@injected_content>
@.claude/workspace/file.yaml
</injected_content>

✅ Correct (skill):
Read `references/configuration.md` to understand the schema.

Fix: Skills use semantic instructions, not @ injection.

Anti-Pattern: @ for Static Content

❌ Wrong:
@.claude/commands/static-template.md

✅ Correct:
[inline the template directly]

Fix: Use @ for dynamic content (changes between invocations), not static templates.

Anti-Pattern: No Error Handling

❌ Wrong:
Current branch: !`git branch --show-current`
[no fallback]

✅ Correct:
Current branch: !`git branch --show-current` (or detached HEAD)

Fix: Consider edge cases and provide context.

Anti-Pattern: $1 for Options

❌ Wrong:
--verbose               # using flags
output-format           # option names

✅ Correct:
session-abc123          # identifier only

Fix: $1 is for IDs, slugs, hashes only—not flags or options.

Anti-Pattern: Command with References/

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

✅ Correct:
.claude/commands/example.md  # Single file

Or if needed:
.claude/skills/example/
├── SKILL.md
└── references/

Anti-Pattern: Wrong Extension

❌ Wrong:
.claude/commands/command.txt
.claude/commands/command

✅ Correct:
.claude/commands/command.md

Anti-Pattern: Inconsistent Naming

❌ Wrong:
.claude/commands/create-prompt.md
.claude/commands/run_prompt.md
.claude/commands/runprompt.md

✅ Correct:
.claude/commands/create-prompt.md
.claude/commands/run-prompt.md
.claude/commands/run-prompt.md  # Consistent kebab-case

Anti-Pattern: Complex Logic in !

❌ Wrong:
!`for f in *.ts; do echo $f; done`

✅ Correct:
Use bash with proper escaping or inline differently

EDGE: Special Cases

Edge Case: No @ or !

Commands that don't need dynamic content:

✅ Valid:
.claude/commands/simple.md
[no @ or ! injection]

Content is static, no dynamic state needed.

Edge Case: Multiple Injections

Commands with complex injection:

<injected_content>
@.claude/workspace/handoff.yaml
</injected_content>

Current branch: !`git branch --show-current`
Modified files: !`git status --porcelain`

Edge Case: Nested Wrappers

<injected_content>
@main-file.yaml

<details>

<injected_content>
@supporting.yaml
</injected_content>

</details>
</injected_content>

Edge Case: Conditional Injection

$IF($1, Use explicit: $1, Infer from context)

Edge Case: Command Grouping

Related commands in folder:

.claude/commands/handoff/
├── create.md
├── diagnostic.md
├── resume.md
└── create-full.md

Edge Case: Single Command

No folder needed for single command:

.claude/commands/simple.md

Edge Case: Many Commands

Use folders for organization:

.claude/commands/
├── analysis/
├── build/
├── handoff/
├── learning/
├── ops/
├── planning/
├── qa/
├── strategy/
└── sync/

Edge Case: Optional Injection

Commands with optional @/!:

✅ Valid:
!`git branch --show-current` (or detached)

<injected_content>
@optional-file.yaml
</injected_content>
(if exists)

Edge Case: Multiple Commands

Commands with multiple ! patterns:

Branch: !`git branch --show-current`
Status: !`git status --short`
Last commit: !`git log -1 --oneline`

Edge Case: Conditional Arguments

$IF($1, Use: $1, Infer from context)

Validation Checklist

Before claiming command authoring complete:

Structure:

• Single markdown file in .claude/commands/
• File has .md extension
• Valid YAML frontmatter with description

Injection Patterns:

• @path for dynamic file content (not in skills)
• !command for runtime state capture
• Wrapped in <injected_content> for semantic grouping
• Paths are absolute or relative to workspace root

Error Handling:

• Missing files handled gracefully (empty result)
• Command failures handled gracefully

Argument Handling:

• $1 used only for identifiers (IDs, slugs, hashes)
• No flags or modes as $1 arguments

Content:

• Follows What-When-Not-Includes format in description
• Imperative/infinitive voice throughout
• No references/ folder (commands are single-file)

Common Mistakes to Avoid

Mistake 1: Using @ or ! in Skills

❌ Wrong:

# My Skill
Current branch: !`git branch --show-current`

✅ Correct: Skills use semantic instructions:

# My Skill
Determine the current Git branch using standard git commands.

Mistake 2: Using $1 for Flags

❌ Wrong:

$1: --verbose

✅ Correct:

$1: session-id  # Only for identifiers

Mistake 3: Missing Frontmatter

❌ Wrong:

# My Command
description: Does something useful

✅ Correct:

---
name: my-command
description: "Verb + object. Use when [condition]. Includes [features]. Not for [exclusions]."
---

Mistake 4: Complex Bash in !

❌ Wrong:

!`for f in $(ls *.json); do cat $f | jq '.name'; done`

✅ Correct:

!`find . -name "*.json" -exec jq -r '.name' {} \;`

Mistake 5: Missing Error Handling

❌ Wrong:

@/path/to/mandatory/file.yaml

(If file doesn't exist, command fails)

✅ Correct:

@/path/to/file.yaml

(gracefully handles missing files)

---

## Best Practices Summary

✅ **DO:**
- Use @path for dynamic file content that changes between sessions
- Use !command for runtime state (git status, CI results)
- Wrap injections in `<injected_content>` for semantic grouping
- Handle missing files gracefully
- Use $1 only for unique identifiers (IDs, slugs)
- Follow single-file structure (no references/ folder)
- Provide at least one "Reality" source (@ or !)
- Delegate complex logic to Skills

❌ **DON'T:**
- Use @ or ! in skills (skills use semantic instructions)
- Use $1 for flags, modes, or non-identifier values
- Create multi-file commands (use skills instead)
- Skip .md extension
- Skip frontmatter description
- Use complex bash in ! without proper escaping
- Delegate from command to another command (delegate to Skills only)

---

## Recognition Questions

| Question                                | Recognition |
| :-------------------------------------- | :---------- |
| Does @ inject dynamic file content?     | Yes, content changes between sessions |
| Does ! execute for runtime state?       | Yes, captures git status, CI, etc.    |
| Does command use single-file structure? | Yes, no references/ folder            |
| Does $1 use identifier-only pattern?    | Yes, IDs/slugs, not flags             |
| Is XML minimal?                         | Only injected_content wrapper         |
| Does command delegate to Skill?         | Yes, if logic exceeds ~50 lines       |

---

## Validation Checklist

Before claiming command authoring complete:

- [ ] @ injections provide dynamic content
- [ ] ! executions capture runtime state
- [ ] Single-file structure, no references/ folder
- [ ] $1 uses identifier-only pattern
- [ ] XML minimal (only injected_content wrapper)
- [ ] Complex logic delegated to skills

---

<critical_constraint>
**Command-Only Injection:**

1. Skills MUST NEVER use `@` or `!` syntax
2. Commands MAY use `@` and `!` freely
3. Use `<injected_content>` wrapper for semantic grouping
4. All paths MUST be absolute or relative to workspace root

**Namespacing:**

- Commands use folder hierarchy for namespacing
- Path `.claude/commands/meta/refine/rules.md` → `/meta:refine:rules`
- No `name` field in frontmatter (auto-derived from path)
- Only `description` is mandatory in frontmatter

**Thin Interface:**

- Commands are "Skin" that bind Reality to Knowledge Skills ("Brain")
- Commands MUST provide at least one "Reality" source (`@` or `!`)
- Commands MUST NOT delegate to other commands (only to Skills)
- Skill chaining requires `context: forked` in frontmatter for result return
- Without `context: forked`, subprocess results don't reliably return
- Commands SHOULD NOT contain complex logic (delegate to Skills)

**Engine vs Interface:**

- Commands are Interfaces that bind Skills to Reality
- Commands SHOULD NOT contain complex logic (delegate to Skills)
- If you need references/, you are building a Skill, not a Command

@ and ! are command-only features.

Skills MUST use semantic instructions, not injection.

Commands MUST handle missing files gracefully.

Commands MUST be single markdown files.

Commands MUST use .md extension.

Commands MUST have frontmatter with description.
</critical_constraint>