/harness-subagent
Use this skill to create and manage subagent entities in the agent-harness workspace. A subagent is a specialized agent definition — with a name, description, optional tool restrictions, and an optional model override — that harness renders into provider-native agent configuration files for every enabled provider.
What is a subagent entity?
A subagent entity is a single canonical Markdown source file under .harness/src/subagents/<subagent-id>.md. It contains:
- Required YAML frontmatter:
nameanddescription - Optional frontmatter: provider-specific fields set via override sidecars (model, tools, handoffs)
- Body: Markdown prose that becomes the agent's system prompt
Harness renders one output artifact per enabled provider from that single source file. You edit the source once; all provider files stay in sync.
Provider output mapping
Claude Code
| Item | Value |
|---|---|
| Output path | .claude/agents/<subagent-id>.md |
| Format | Markdown with YAML frontmatter |
| Required frontmatter | name, description |
| Optional frontmatter | tools (string or string[]), model |
Claude Code loads agent files from .claude/agents/ at session start. Each file's description field tells Claude when to delegate to that agent. Claude routes tasks automatically, or the user can invoke an agent explicitly with @agent-<name> or the /agents command. Supported model values: sonnet, opus, haiku, a full model ID such as claude-sonnet-4-6, or inherit (default). Subagents run in isolated context windows and cannot spawn further subagents.
Official docs: https://code.claude.com/docs/en/sub-agents
OpenAI Codex CLI
| Item | Value |
|---|---|
| Output path | .codex/config.toml |
| Format | TOML, section [agents.<subagent-id>] |
| Required fields | description, developer_instructions (body) |
| Optional fields | model, model_reasoning_effort, nickname_candidates |
Harness writes all enabled subagents into .codex/config.toml under [agents.<id>] entries. The description drives when Codex routes to that agent role; the body becomes developer_instructions. Codex also supports standalone TOML agent files in .codex/agents/ (outside of harness management), which are auto-discovered and take precedence over same-named inline entries.
Official docs: https://developers.openai.com/codex/config-reference
GitHub Copilot
| Item | Value |
|---|---|
| Output path | .github/agents/<subagent-id>.agent.md |
| Format | Markdown with YAML frontmatter |
| Required frontmatter | description |
| Optional frontmatter | name, tools (string[]), model, handoffs, mcp-servers, target, disable-model-invocation, user-invocable |
Copilot discovers agent files in .github/agents/ at the repository level. The handoffs field is Copilot-specific and is supported in VS Code agent mode: it defines routing buttons that let users switch to another agent mid-conversation, optionally with a pre-filled prompt. Note: handoffs are currently not supported by the Copilot coding agent on GitHub.com — they are silently ignored there. Example handoff entry (VS Code only):
yaml1handoffs: 2 - label: "Start Implementation" 3 agent: implementation 4 prompt: "Now implement the plan outlined above." 5 send: true
When send: true is set, the handoff prompt submits automatically.
Official docs: https://docs.github.com/en/copilot/reference/custom-agents-configuration
Provider-specific frontmatter comparison
| Field | Claude Code | Codex CLI | GitHub Copilot |
|---|---|---|---|
name | required | via TOML key | optional |
description | required | required | required |
tools | string or string[] | — | string[] |
model | optional | optional | optional |
developer_instructions | — | required (body) | — |
handoffs | — | — | optional (VS Code only) |
Provider-specific options (model, tools, handoffs) are set through override sidecar files, not in the canonical source frontmatter — see the Override sidecars section below.
Canonical source format
markdown1--- 2name: <human-readable display name> 3description: <when this agent should be used — used by all providers> 4--- 5 6You are a [role description]. When invoked: 7 81. [Step one] 92. [Step two] 103. [Step three] 11 12Focus on [specific domain]. Do not [out-of-scope actions].
Only name and description are required in the canonical frontmatter. The body becomes the agent's system prompt for all providers.
Override sidecars
To set provider-specific options (model, tools, handoffs), create or edit the generated override YAML files:
.harness/src/subagents/<subagent-id>.overrides.claude.yaml.harness/src/subagents/<subagent-id>.overrides.codex.yaml.harness/src/subagents/<subagent-id>.overrides.copilot.yaml
Example Claude override sidecar:
yaml1version: 1 2options: 3 model: haiku 4 tools: 5 - Read 6 - Grep 7 - Glob
Example Copilot override sidecar:
yaml1version: 1 2options: 3 model: gpt-4o 4 tools: 5 - search 6 - fetch 7 handoffs: 8 - label: "Hand off to planner" 9 agent: planner 10 prompt: "Now create a plan based on the research above."
Harness CLI commands
bash1# Scaffold a new subagent source file and register it in manifest.json 2npx harness add subagent <subagent-id> 3 4# Preview what files will be generated (dry run) 5npx harness plan 6 7# Write all provider artifacts from current canonical sources 8npx harness apply 9 10# Watch sources and auto-apply on changes 11npx harness watch 12 13# Remove a subagent entity and its source files 14npx harness remove subagent <subagent-id> 15 16# Remove entity but keep source files on disk 17npx harness remove subagent <subagent-id> --no-delete-source
Complete example
Source file: .harness/src/subagents/code-reviewer.md
markdown1--- 2name: code-reviewer 3description: Expert code review specialist. Reviews code for quality, security, and maintainability. Use proactively after writing or modifying code. 4--- 5 6You are a senior code reviewer ensuring high standards of quality and security. 7 8When invoked: 91. Run git diff to see recent changes 102. Focus on modified files 113. Begin review immediately without asking for clarification 12 13Review checklist: 14- Code is clear and readable 15- Functions and variables are well-named 16- No duplicated logic 17- Proper error handling and input validation 18- No exposed secrets or API keys 19- Adequate test coverage 20- Performance considerations addressed 21 22Provide feedback organized by priority: 23- Critical issues (must fix before merging) 24- Warnings (should fix) 25- Suggestions (consider improving) 26 27Include specific examples of how to fix each issue. Do not modify files yourself.
Override sidecar for Claude (.harness/src/subagents/code-reviewer.overrides.claude.yaml):
yaml1version: 1 2options: 3 model: sonnet 4 tools: 5 - Read 6 - Grep 7 - Glob 8 - Bash
After running npx harness apply, this produces:
.claude/agents/code-reviewer.md— used by Claude Code- An entry in
.codex/config.tomlunder[agents.code-reviewer]— used by Codex .github/agents/code-reviewer.agent.md— used by GitHub Copilot
Typical workflow
bash1# 1. Scaffold the subagent source 2npx harness add subagent code-reviewer 3 4# 2. Edit the source file 5# .harness/src/subagents/code-reviewer.md 6 7# 3. (Optional) Edit provider-specific overrides 8# .harness/src/subagents/code-reviewer.overrides.claude.yaml 9 10# 4. Preview the plan 11npx harness plan 12 13# 5. Generate provider artifacts 14npx harness apply
Check .claude/agents/, .codex/config.toml, and .github/agents/ to verify the rendered output.
References
- Claude Code sub-agents: https://code.claude.com/docs/en/sub-agents
- OpenAI Codex agents: https://developers.openai.com/codex/config-reference
- OpenAI Codex config reference: https://developers.openai.com/codex/config-reference
- GitHub Copilot custom agents configuration: https://docs.github.com/en/copilot/reference/custom-agents-configuration
- GitHub Copilot custom agents how-to: https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/create-custom-agents
- Agent harness providers overview: docs/providers.md
