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?

• Single source of truth: Skills contain all implementation content

• Easier maintenance: Changes to skills automatically propagate

• Platform consistency: Commands are thin wrappers with platform-specific frontmatter

• Token efficiency: Subagents load skills progressively via progressive disclosure

• No duplication: Implementation lives in one place (the skill)

• 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

• Check for existing skill: Identify the skill the command should use

• 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

• 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

• Create/refactor Claude Code command with allowed-tools: Task(subagent-name)

• Create/refactor OpenCode command with agent: subagent-name

• 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