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

description

allowed-tools

Task(subagent-name)

argument-hint

[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

description

agent

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):

---
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:

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

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

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/agent/<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/agent/<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