aibot88 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):
---
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
- 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/agent/<name>.md
- Claude Code:
- If no subagent exists: Ask the user if they want one created
- If yes, use the
subagent-authoringskill to create it first - If no, stop and explain the command cannot be created without a subagent
- If yes, use the
- 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/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 thesubagent-authoringskill 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 skillsskill-authoring- For creating skills themselves