188 lines
12 KiB
Markdown
188 lines
12 KiB
Markdown
---
|
|
status: done
|
|
claimed-by: "019fba91-eabf-76ae-b086-a37ac061d6e8"
|
|
claimed-at: "2026-07-31T21:10:49-04:00"
|
|
completed-at: "2026-08-01T02:08:00-04:00"
|
|
parent: "[[021-pi-subagents-config-boundary-grill]]"
|
|
blocked-by: []
|
|
tags:
|
|
- ticket/research
|
|
---
|
|
|
|
# Agent definition conventions research
|
|
|
|
## Question
|
|
|
|
What conventions do Pi subagent extensions and other coding-agent harnesses such as Claude Code, Antigravity, OpenCode, and adjacent tools use for named subagent or agent definition files, including location, frontmatter fields, body semantics, project/user precedence, and trust gating?
|
|
|
|
## Answer
|
|
|
|
The strongest shared convention is Markdown files with YAML frontmatter for metadata and a Markdown body for the agent's prompt or instructions.
|
|
Claude Code, OpenCode, Pi skills, and the Agent Skills specification all use that split, although OpenCode also supports JSON config and Pi skills are not subagents.
|
|
Claude Code and OpenCode both make the description field operational by using it for automatic delegation or task selection.
|
|
Claude Code uses an explicit `name` frontmatter field as identity, while OpenCode derives the agent name from the Markdown filename.
|
|
For Pi subagents, the safest neutral schema is therefore a Markdown file with frontmatter `name`, `description`, and optional runtime policy fields, with the body used only as the child system/developer instruction text.
|
|
|
|
The recommended locations for the Pi extension are `~/.pi/agent/agents/*.md` for user-level definitions and `.pi/agents/*.md` for project-level definitions.
|
|
This mirrors Pi's own user/project split for skills while avoiding `.agents/` unless cross-harness sharing becomes an explicit requirement.
|
|
Project definitions should load only after Pi's existing project trust gate approves the workspace.
|
|
If project and user definitions share a `name`, project definitions should override user definitions for that project, because project-specific agent prompts are the likely local intent.
|
|
Duplicate names within the same precedence tier should be reported as configuration errors rather than resolved by filesystem order.
|
|
|
|
## Findings
|
|
|
|
### Claude Code
|
|
|
|
Claude Code custom subagents are Markdown files with YAML frontmatter followed by a Markdown system prompt body.
|
|
The docs state that subagents run in their own context window, use a custom system prompt, can have specific tool access, and return results to the parent conversation.
|
|
Source: <https://docs.anthropic.com/en/docs/claude-code/sub-agents.md>.
|
|
|
|
Claude Code supports project-level `.claude/agents/` and user-level `~/.claude/agents/` definitions.
|
|
It also supports definitions passed through the `--agents` CLI flag, managed settings definitions, and plugin `agents/` directories.
|
|
The documented priority order places `--agents` highest, managed policies next, project definitions next, user definitions next, and plugin definitions lowest.
|
|
Source: <https://docs.anthropic.com/en/docs/claude-code/sub-agents.md#choose-the-subagent-scope>.
|
|
|
|
Claude Code discovers nested `.claude/agents/` directories by walking from the current working directory toward the repository root.
|
|
When nested project definitions share a name, the closest definition wins.
|
|
Within one scanned directory tree, duplicate names have no useful semantic distinction and Claude Code warns that filesystem read order decides which one loads.
|
|
Source: <https://docs.anthropic.com/en/docs/claude-code/sub-agents.md#choose-the-subagent-scope>.
|
|
|
|
Claude Code requires `name` and `description` in frontmatter.
|
|
It supports optional fields including `prompt`, `tools`, `disallowedTools`, `model`, `permissionMode`, `mcpServers`, `hooks`, `maxTurns`, `skills`, `initialPrompt`, `memory`, `effort`, `background`, `isolation`, and `color`.
|
|
The file body is equivalent to the `prompt` field for file-based subagents.
|
|
Source: <https://docs.anthropic.com/en/docs/claude-code/sub-agents.md#supported-frontmatter-fields>.
|
|
|
|
Claude Code treats `description` as delegation metadata.
|
|
The docs say Claude uses each subagent's description to decide when to delegate tasks, and recommend clear descriptions for proactive delegation.
|
|
Source: <https://docs.anthropic.com/en/docs/claude-code/sub-agents.md#understand-automatic-delegation>.
|
|
|
|
Claude Code has trust gating for project-level subagent hooks.
|
|
Project subagents still run before trust, but frontmatter hooks are skipped until the containing folder is trusted.
|
|
Source: <https://docs.anthropic.com/en/docs/claude-code/sub-agents.md#define-hooks-for-subagents>.
|
|
|
|
Claude Code also distinguishes subagent context from fully independent parallel sessions.
|
|
Its docs say subagents work within a single session and direct readers to background agents or agent teams for many independent sessions.
|
|
Source: <https://docs.anthropic.com/en/docs/claude-code/sub-agents.md>.
|
|
|
|
### OpenCode
|
|
|
|
OpenCode supports both JSON agent config in `opencode.json` and Markdown agent files.
|
|
Markdown agents live in `~/.config/opencode/agents/` globally and `.opencode/agents/` per project.
|
|
The Markdown filename becomes the agent name.
|
|
Source: <https://opencode.ai/docs/agents>.
|
|
|
|
OpenCode frontmatter uses fields such as `description`, `mode`, `model`, `temperature`, `permission`, `prompt`, `tools`, `hidden`, `color`, and provider-specific pass-through options.
|
|
Its `mode` can be `primary`, `subagent`, or `all`, with `all` as the default when omitted.
|
|
Source: <https://opencode.ai/docs/agents>.
|
|
|
|
OpenCode body semantics match the custom prompt pattern.
|
|
The Markdown example places YAML metadata first and then freeform instructions such as "You are in code review mode" in the body.
|
|
OpenCode also supports a `prompt` config field pointing at a custom system prompt file, with the path relative to the config file.
|
|
Source: <https://opencode.ai/docs/agents>.
|
|
|
|
OpenCode separates primary agents from subagents.
|
|
Primary agents handle the main conversation and can be switched with Tab, while subagents are invoked by primary agents or manually with `@` mentions.
|
|
Source: <https://opencode.ai/docs/agents>.
|
|
|
|
OpenCode exposes child-session navigation for subagents.
|
|
Its docs say subagents create child sessions and users can navigate from the parent to child sessions with `session_child_first` and related keybinds.
|
|
Source: <https://opencode.ai/docs/agents>.
|
|
|
|
OpenCode has permission controls that are both global and per-agent.
|
|
It supports `permission` entries such as edit, bash, webfetch, external directory access, and task invocation allow or deny patterns.
|
|
Source: <https://opencode.ai/docs/agents#permissions>.
|
|
|
|
I did not find an explicit OpenCode workspace trust gate in the agent docs section fetched for this research.
|
|
That is an evidence gap rather than evidence that no trust gate exists elsewhere in OpenCode.
|
|
|
|
### Pi and Agent Skills conventions
|
|
|
|
Pi's documented skill discovery uses global `~/.pi/agent/skills/` and `~/.agents/skills/`, project `.pi/skills/` and `.agents/skills/`, package `skills/` directories, settings `skills`, and CLI `--skill` paths.
|
|
Project skills load only after the project is trusted.
|
|
Source: `/nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/docs/skills.md`.
|
|
|
|
Pi skills use a directory with `SKILL.md` or supported direct `.md` files in some locations.
|
|
`SKILL.md` contains YAML frontmatter followed by instructions, with required `name` and `description` fields.
|
|
Pi says it implements the Agent Skills standard leniently.
|
|
Source: `/nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/docs/skills.md`.
|
|
|
|
The Agent Skills specification requires a `SKILL.md` file with YAML frontmatter and Markdown content.
|
|
It requires `name` and `description`, allows optional `license`, and says the Markdown body contains unrestricted skill instructions.
|
|
Source: <https://agentskills.io/specification>.
|
|
|
|
Pi skills are not named subagent definitions, but their discovery, trust, and progressive-disclosure shape is the closest native Pi precedent.
|
|
That makes `.pi/agents/` and `~/.pi/agent/agents/` a more Pi-native choice than copying `.claude/agents/` or `.opencode/agents/` directly.
|
|
Source: `/nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/docs/skills.md`.
|
|
|
|
### Antigravity
|
|
|
|
I attempted to fetch Antigravity documentation at `https://antigravity.google.com/docs/agents` and related Markdown URLs.
|
|
The page was served as a JavaScript application and the fetched source did not expose useful static text about custom agent definition files, frontmatter, precedence, or trust behavior.
|
|
The related guessed Markdown endpoints did not return usable Markdown documentation.
|
|
Source attempted: <https://antigravity.google.com/docs/agents>.
|
|
|
|
No primary Antigravity source available in this session established a named custom agent file convention.
|
|
Do not use Antigravity as a basis for Pi config schema until a primary doc, local installed product docs, or source artifact can be inspected.
|
|
|
|
### Adjacent tool patterns
|
|
|
|
The adjacent reusable-package pattern is the Agent Skills standard rather than subagent definitions.
|
|
It reinforces the `name` plus `description` frontmatter convention and the separation between startup metadata and body instructions.
|
|
Source: <https://agentskills.io/specification>.
|
|
|
|
Firstmate and related local prototypes inspected earlier use shell/backend orchestration patterns rather than a stable named-agent Markdown schema.
|
|
They are useful for process spawning and Herdr integration ideas, but not as schema authorities for Pi subagent definitions.
|
|
Source: `/tmp/firstmate-research/firstmate/README.md` and `/tmp/firstmate-research/shipmates/plugin-guide.md`.
|
|
|
|
## Recommendation for Pi subagents
|
|
|
|
Use Markdown definitions with YAML frontmatter and a Markdown body.
|
|
Require `name` and `description`.
|
|
Use `name` as canonical identity instead of deriving identity from the filename, because this matches Claude Code and Agent Skills and avoids rename churn when files are reorganized.
|
|
Require names to be lowercase slugs with letters, numbers, and hyphens.
|
|
Treat filenames as storage only, but warn when the filename stem does not match `name` because mismatches are easy to overlook.
|
|
|
|
Make the Markdown body the child instruction prompt.
|
|
Do not let the body define runtime, lifecycle, or permission policy implicitly.
|
|
Keep runtime and permission policy in typed frontmatter or Pi settings so the extension can validate it before launch.
|
|
|
|
Start with this minimal neutral frontmatter surface:
|
|
|
|
```yaml
|
|
name: review
|
|
description: Review recent changes and report risks without editing files.
|
|
model: inherit
|
|
context: fork
|
|
permissions:
|
|
tools:
|
|
read: allow
|
|
write: deny
|
|
hidden: false
|
|
color: blue
|
|
```
|
|
|
|
Treat `model`, `context`, `permissions`, `hidden`, and `color` as optional extension fields.
|
|
Do not bundle built-in named agent types in the extension.
|
|
Let users define these Markdown files in Pi config.
|
|
|
|
Resolve definitions in this order:
|
|
|
|
1. Explicit invocation object passed at spawn time.
|
|
2. Project `.pi/agents/` definitions from the trusted workspace, with nearest nested directory winning if nested support is implemented.
|
|
3. User `~/.pi/agent/agents/` definitions.
|
|
4. Package-provided definitions only if the user later enables a package source explicitly.
|
|
|
|
Reject duplicate names within the same directory tree with a diagnostic.
|
|
Do not silently choose by filesystem order.
|
|
|
|
For trust, load user definitions without a project trust prompt because the user controls their home Pi config.
|
|
Load project definitions only when the workspace is trusted.
|
|
Do not run project-defined lifecycle hooks, commands, MCP server declarations, or other active policy from an untrusted project.
|
|
If read-only project prompts are ever surfaced before trust, label them untrusted and require confirmation before spawning.
|
|
|
|
## Limitations
|
|
|
|
Antigravity findings are limited by lack of accessible static primary documentation in this session.
|
|
OpenCode agent docs provided locations and schema details, but this research did not separately inspect OpenCode source code for loader precedence or trust behavior.
|
|
Claude Code's documentation is unusually detailed and should not be copied wholesale into Pi, because its schema includes many Claude-specific concepts such as `permissionMode`, `memory`, and `isolation: worktree`.
|