Custom agent inheritance / composition (extends / include) for shared base prompts

[michaelBenin]

Describe the feature or problem you'd like to solve

Custom agents (.agent.md files) have no native way to inherit, extend, or compose shared rules from a base prompt. As soon as you have more than two or three specialist agents that need to share the same code-quality, scope, or style rules, every agent file ends up duplicating the same blocks of guidance, and the rules drift between agents over time.

There is currently no extends: / base: / include: mechanism in the agent frontmatter, no way to reference a shared rules document as a structural parent, and no way to share MCP servers or tools across agents from a single declaration (related: #1756).

Proposed solution

Add first-class support for agent inheritance / composition. A few possible shapes (any one would solve the underlying problem):

1. extends in frontmatter — point at one or more parent .agent.md files; the runtime concatenates parent prompt + child prompt, with the child taking precedence on conflicts.

   ---
   name: my-specialist
   extends:
     - my-base
   ---

2. include directive in agent prompt body — explicit, ordered inclusion of shared .md snippets so multiple specialists can compose from a small library of rule fragments (style, security, repo conventions, etc.).
3. Shared MCP / tools block — even without full prompt inheritance, allow mcp-servers and tools to be declared in a referenced parent agent so specialists do not have to redeclare them (overlaps with Allow external custom agents (installed from plugins) to access globally configured MCP servers #1756).

Benefits:

• Single source of truth for shared rules (style, scope boundaries, output contracts, security/PII rules, repo conventions).
• Eliminates copy/paste drift across a fleet of specialist agents.
• Makes it practical to ship cohesive "agent suites" that all share the same baseline rules.
• Encourages small, focused specialist agents instead of monolithic ones.
• Easier to evolve guidance: change the base, every specialist picks it up on next invocation.

Example prompts or workflows

1. Multi-specialist suite
   A team builds several agents for a single problem area (an orchestrator plus a handful of specialists). All of them should enforce the same code-quality rules, the same scope rules, and the same output format. With extends: my-base, those rules live in one file. Without it, every specialist file has to be kept in lockstep manually.

2. Org-wide style baseline
   An organization defines a single org-base.agent.md with shared rules (no secrets in code, follow AGENTS.md, prefer ecosystem tools, structured output sections). Every team's specialist agents extend it. Updating the org baseline updates every agent at once.

3. Layered MCP / tool inheritance
   A with-github.agent.md parent declares the GitHub MCP server and a curated tool set. Multiple specialist agents extend it instead of redeclaring MCP wiring in each frontmatter.

4. Composable rule fragments
   A specialist composes from several small docs:

   includes:
     - rules/human-readable-code.md
     - rules/security-baseline.md
     - rules/output-contract.md

   Each fragment is small and reusable across many agents.

5. Deprecating an agent cleanly
   When a base agent is renamed or split, every dependent agent surfaces immediately because the extends reference is a structural link the runtime can validate, instead of a hand-written "read this file first" instruction that may be silently ignored by the model.

Additional context

Current workaround

Since there is no native inheritance, the practical workaround is to maintain a canonical base prompt as a regular document and instruct each specialist agent to read it first. Concretely:

1. Create a shared base document, e.g. a *-base.agent.md (or any plain .md path).
2. In every specialist's <default_context> (or equivalent), include an explicit directive to read the base file before doing anything else.
3. Document a precedence rule in the base ("base rules apply unless a specialist explicitly overrides; specialists must call out overrides explicitly") because there is no runtime resolution.
4. Re-declare mcp-servers and tool config in each specialist, since shared frontmatter is not supported (see Allow external custom agents (installed from plugins) to access globally configured MCP servers #1756).

This works, but has clear limits:

• It is advisory, not enforced. The model can skip the read-first step under context pressure or with aggressive truncation.
• It costs context tokens on every invocation, because the base content is re-read each time instead of being merged at agent-load time.
• There is no diamond / override resolution; conflicts have to be policed by convention and prose.
• It cannot share MCP servers, allowed tools, model selection, or other frontmatter-level configuration — only prompt content.
• Renames and refactors of the base file silently break the link; there is no structural validation.

A first-class extends / include mechanism would replace this convention with something the runtime can validate and merge deterministically.

Related issues

• Allow external custom agents (installed from plugins) to access globally configured MCP servers #1756 — Allow external custom agents to access globally configured MCP servers (overlaps with the "share MCP wiring" angle of this request).
• Tool Scoping for Sub-Agents #2992 — Tool Scoping for Sub-Agents (composition / scoping concern; would compose well with prompt inheritance).
• Composable Sub-Agents #340 — Composable Sub-Agents (closed; covers a different but related composition problem).