ai-artifacts/projects/dotfiles/028-pi-subagents-agent-definition-conventions-research.md

status, claimed-by, claimed-at, completed-at, parent, blocked-by, tags

status	claimed-by	claimed-at	completed-at	parent	blocked-by	tags
done	019fba91-eabf-76ae-b086-a37ac061d6e8	2026-07-31T21:10:49-04:00	2026-08-01T02:08:00-04:00	021-pi-subagents-config-boundary-grill		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:

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.