skills.rest
avdi
avdiCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

defining-subagents

Configure Claude Code subagent frontmatter and grant MCP tools via mcpServers declarations.

Updated May 9, 2020
Search Tags:#debugging#claude code#subagent#frontmatter#mcp servers#agent tools#tool inheritance
One-click install
npx skills add https://github.com/avdi/purse --skill defining-subagents-avdi
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: defining-subagents
Source: https://github.com/avdi/purse/tree/main/home/dot_agents/skills/defining-subagents
Command: npx skills add https://github.com/avdi/purse --skill defining-subagents-avdi

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Subagents dispatched via the Agent tool often fail to inherit the parent's MCP tools, leaving them unable to call mcp__* tools even when the tools field lists them. This Skill documents the correct frontmatter fields and the mcpServers declaration that reliably wires MCP servers into a subagent. ## Core Features & Use Cases - Frontmatter reference: Covers name, description, tools, mcpServers, model, and permissionMode fields for .claude/agents/.md files, including which tools subagents can never receive. - MCP inheritance workaround: Explains the Agent-tool MCP-inheritance gap (claude-code#30280) and shows that a named mcpServers entry grants that server's whole toolset directly, bypassing the broken ToolSearch path. - Verification workflow: Provides a probe-agent pattern to report what tools a subagent actually receives, plus guidance on the session-start agent registry freeze and headless claude -p testing. - Use Case: A search-heavy subagent reports only Bash, Read, and Write; add mcpServers: [ripgrep] and mcp__ripgrep__ to its frontmatter so it gains structured search tools. ## Quick Start Ask the agent to write a Claude Code subagent definition that grants the playwright MCP server using the mcpServers frontmatter field and verify it with a probe agent.

Frequently Asked Questions about defining-subagents

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I give a Claude Code subagent MCP tools?▼

Declare the server in the subagent's own frontmatter with mcpServers: [server-name], which shares the parent session's connection and grants that server's tools directly. Listing mcp__server__* in tools alone is unreliable because Agent-tool dispatch does not propagate MCP config.

Why can't my subagent see mcp__* tools?▼

Subagents dispatched via the Agent tool do not reliably inherit the parent's MCP tools (claude-code#30280), and some child-session harnesses strip ToolSearch. Fix it by adding a named mcpServers entry to the agent's frontmatter.

What frontmatter fields does a Claude Code subagent support?▼

A subagent Markdown file supports name, description, tools, mcpServers, model, and permissionMode. Omitting tools inherits all tools, while an explicit list restricts access; some tools like AskUserQuestion and ExitPlanMode are never available to subagents.

Does mcpServers: ["*"] grant all MCP servers to a subagent?▼

No, the wildcard is scope-dependent and unreliable; it has been observed granting project-scope servers but not user-scope ones. Name each server explicitly in the mcpServers list instead.

Why doesn't my edited subagent file take effect?▼

The Agent tool's dispatchable agent registry is fixed at session start, so new or edited agent files are not picked up mid-session. Restart the session rooted in the directory holding the agent file, or test with a headless claude -p invocation.

Is it safe to grant a subagent the github MCP server?▼

A named mcpServers reference grants the server's entire toolset, including write operations like merge_pull_request and push_files, and is not narrowed by the tools list. For narrow needs, prefer Bash with the gh CLI over granting the whole server.

Related Skills

Explore More Software Engineering Skills→
FRIKKernFRIKKern
6

doey-mcp-example

Declare MCP server dependencies in skill frontmatter for per-team isolation.

Community
Advanced
Moisesjr20Moisesjr20
1

subagent-creator

Create and configure specialized subagents with DOE lifecycle frontmatter.

Community
Intermediate
treejhtreejh

session-analyzer

Parses session JSONL logs to verify subagent, hook, and tool behavior against SKILL.md.

Community
Advanced
danielctcdanielctc

mcp-management

Discover, analyze, and execute MCP capabilities across configured servers.

Community
Advanced