[FEATURE] Support shared tool definitions across agent/subagent frontmatter files

Resolved 💬 3 comments Opened Mar 27, 2026 by etrzanupgrade Closed May 4, 2026

Problem

When managing multiple subagent .md files in a plugin, the tools: frontmatter field must be repeated verbatim in every file. For example, a plugin with 30+ agents where 20 of them share the same read-only toolset requires duplicating tools: Read, Grep, Glob in each file.

This creates a maintenance burden:

  • Adding a new tool to a category of agents requires editing every file individually
  • No way to define a "toolset" once and reference it across agents
  • Inconsistencies creep in when files are updated independently

Current behavior

Each agent .md file requires its own explicit tools: or disallowedTools: list in YAML frontmatter. The @path/to/file import syntax works in the markdown body but not in frontmatter fields. There is no inheritance, extends, $ref, or shared config mechanism for frontmatter.

Proposed solution

Support one or more of the following:

Option A: Named toolsets

Define reusable toolsets in a shared config, reference them in frontmatter:

# In a shared config (e.g., .claude/toolsets.yaml or plugin.json)
toolsets:
  read-only: [Read, Grep, Glob]
  read-write: [Read, Grep, Glob, Write, Edit]
  research: [Read, Grep, Glob, MCP]
# In agent frontmatter
---
name: my-agent
toolset: read-only
---

Option B: Frontmatter @ imports

Allow @ import syntax to work within specific frontmatter fields:

---
name: my-agent
tools: @.claude/toolsets/read-only.txt
---

Option C: Agent inheritance

Allow an agent to extend another agent's frontmatter:

---
name: my-agent
extends: base-read-only-agent
---

Use case

We maintain a finance team plugin with 30+ specialized agents organized into categories (research, analysis, generation, planning). Most agents within a category share the same tool restrictions:

  • Research agents (9 agents): Read, Grep, Glob, MCP
  • Analysis agents (18 agents): Read, Grep, Glob
  • Generation agents (7 agents): Read, Grep, Glob, Write

Today, each of these 34 files independently declares its tools: list. When we need to add a tool to all research agents, we edit 9 files manually and risk missing one.

Alternatives considered

  • disallowedTools instead of tools: Shorter in some cases but doesn't solve the DRY problem — still repeated per file
  • Convention over configuration: Rely on directory structure to imply tools (e.g., all agents in research/ get MCP). This would be a significant architectural change

Environment

  • Claude Code version: latest
  • OS: macOS

View original on GitHub ↗

This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗