aspiers/agent-command-authoring

Agent Command Authoring

Create commands that delegate to subagents for Claude Code and OpenCode.

When to Use This Skill

Use this skill when:

• Creating a new custom command
• Refactoring an existing command to delegate to a subagent
• Ensuring consistency between Claude Code and OpenCode command implementations

The Delegation Pattern

Commands should be thin wrappers that delegate to subagents (which in turn delegate to skills):

command → subagent → skill

Claude Code command (.claude/commands/<name>.md):

---
description: Brief description of what the command does
allowed-tools: Task(subagent-name)
---

Use the `<subagent-name>` subagent to accomplish this task.

OpenCode command (.config/opencode/command/<name>.md):

---
description: Brief description of what the command does
agent: <subagent-name>
---

Use the `<subagent-name>` subagent to accomplish this task.

Claude Code Command Structure

Frontmatter Fields

| Field | Required | Description | |-------|----------|-------------| | description | Yes | 1-2 sentence description of what the command does | | allowed-tools | Yes | Task(subagent-name) to invoke the subagent | | argument-hint | No | Hint for command arguments (e.g., [feature_name [subtask_number]]) |

allowed-tools Format

For commands that delegate to subagents:

• Task(subagent-name) - Invoke a subagent

Example:

allowed-tools: Task(git-committer)

Naming Conventions

Command names should use the imperative form of verbs (telling the agent what to do):

• ✅ commit, stage, lint, test, review, reflect
• ❌ committing, git-committer, do-linting

The imperative form gives commands their characteristic feel:

• "commit" = "perform a commit"
• "stage" = "stage changes"
• "test" = "run tests"

OpenCode Command Structure

Frontmatter Fields

| Field | Required | Description | |-------|----------|-------------| | description | Yes | 1-2 sentence description of what the command does | | agent | Yes | Name of the subagent to invoke |

Example:

---
description: Create well-formatted commits using conventional commits style
agent: git-committer
---

Command Body

The command body should be 5-20 lines maximum and contain only:

Use the `<subagent-name>` subagent to accomplish this task.

Do NOT include:

• Full implementation steps
• Duplicated content between Claude and OpenCode
• More than ~20 lines of content

Examples

Minimal Command (Claude Code)

---
description: Create well-formatted commits using conventional commits style
allowed-tools: Task(git-committer)
---

Use the `git-committer` subagent to create a well-formatted commit.

Minimal Command (OpenCode)

---
description: Create well-formatted commits using conventional commits style
agent: git-committer
---

Use the `git-committer` subagent to create a well-formatted commit.

Command with Arguments (Claude Code)

---
description: Generate a PRP
argument-hint: [feature_name]
allowed-tools: Task(prp-generator)
---

Use the `prp-generator` subagent to create a Product Requirements Prompt.

Why This Pattern?

1. Single source of truth: Skills contain all implementation content
2. Easier maintenance: Changes to skills automatically propagate
3. Platform consistency: Commands are thin wrappers with platform-specific frontmatter
4. Token efficiency: Subagents load skills progressively via progressive disclosure
5. No duplication: Implementation lives in one place (the skill)
6. Isolation: Subagents run in their own context with appropriate permissions

Anti-Pattern to Avoid

BAD - Command with full implementation:

---
description: Stage changes
allowed-tools: Bash(git add:*)
---

# Staging Changes

Stage relevant changes via `git add`...

1. Run `git status` to check for already staged changes
2. Verify no staged changes exist...
3. Run `git status` again...
4. Carefully review which files are relevant...
5. Stage only the relevant files...
6. Run `git status` again...

BAD - Command that delegates directly to skill (skipping subagent), for commands that do not need session context:

---
description: Stage changes via git add
allowed-tools: Skill(git-staging)
---

Use the `git-staging` skill to stage relevant changes.

GOOD - Command that delegates to subagent (for context-independent tasks):

---
description: Stage changes via git add
allowed-tools: Task(git-stager)
---

Use the `git-stager` subagent to stage relevant changes.

EXCEPTION - Commands that are inherently session-context-dependent (e.g. "review what I just wrote", "remove duplication I just introduced") should skip the subagent and invoke the skill directly. Subagents start with a fresh context and will not know what was recently worked on unless the parent agent tells them — which defeats the purpose of the command.

---
description: Remove code duplication you just introduced
allowed-tools: Skill(code-refactoring-dry)
---

Use the `code-refactoring-dry` skill to remove duplication in the files you
have worked on in this session.

In OpenCode, omit the agent: field entirely for the same effect (the command then runs in the primary agent's context).

Workflow

1. Check for existing skill: Identify the skill the command should use
2. Check for existing subagent: Look for a subagent that delegates to that skill
   • Claude Code: .claude/agents/<name>.md
   • OpenCode: .config/opencode/agents/<name>.md
3. If no subagent exists: Ask the user if they want one created
   • If yes, use the subagent-authoring skill to create it first
   • If no, stop and explain the command cannot be created without a subagent
4. Create/refactor Claude Code command with allowed-tools: Task(subagent-name)
5. Create/refactor OpenCode command with agent: subagent-name
6. Verify the full chain works: command → subagent → skill

Missing Subagent Handling

Before creating a command, always verify the target subagent exists:

# Check Claude Code subagent
ls ~/.claude/agents/<subagent-name>.md

# Check OpenCode subagent
ls ~/.config/opencode/agents/<subagent-name>.md

If either file is missing, ask the user:

"The subagent <subagent-name> doesn't exist yet. Would you like me to create it using the subagent-authoring skill before proceeding with the command?"

Do NOT create commands that reference non-existent subagents.

Related Skills

• subagent-authoring - For creating subagent definitions that delegate to skills
• skill-authoring - For creating skills themselves