[FEATURE] Support shared tool definitions across agent/subagent frontmatter files
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
disallowedToolsinstead oftools: 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
This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗