pal-e-docs
Project not found.

Convention: Agent-Skill-MCP Wiring

convention-agent-skill-mcp-wiring Convention

active convention
Project

Convention: Agent-Skill-MCP Wiring

How agents, skills, and MCP tools connect. This documents the full wiring pattern and the enforcement stack that governs it.

The Wiring Pattern

Three Layers

Layer What it does Where it lives Enforcement?
<strong>MCP Tools</strong> The actual operations — read notes, create issues, submit PRs MCP server configs in settings.json No — tools execute whatever is asked
<strong>Skills</strong> Multi-step workflows that orchestrate MCP tool calls <code>~/.claude/skills/{name}/SKILL.md</code> + pal-e-docs notes No — convenience wiring via <code>context: fork</code>
<strong>Agents</strong> Stateless roles with tool restrictions and MCP scoping <code>~/.claude/agents/{name}.md</code> + pal-e-docs profiles Organizational — <code>disallowedTools</code> and <code>mcpServers</code> restrict but don't guarantee. Frontmatter PreToolUse hooks add hard enforcement.

The Enforcement Stack

None of the above is enforcement by itself. The only guaranteed enforcement is hooks.

Skill → Agent Wiring

Skills delegate to agents via two frontmatter fields:
Field Purpose Example
<code>context: fork</code> Run skill in isolated subagent context (no conversation history) <code>context: fork</code>
<code>agent</code> Which subagent type to use (matches <code>name</code> field in agent .md) <code>agent: qa</code>

Current Wiring

Skill Agent context: fork? Purpose
<code>/review-pr</code> <code>qa</code> Yes QA reviews PR diff in fresh context
<code>/implement-phase</code> <code>dev</code> Yes Dev implements a plan phase in worktree
<code>/fix-review</code> <code>dev</code> Yes Dev fixes QA review findings
<code>/create-issue</code> <code>issue-creator</code> Yes Issue Creator proposes templated issue
<code>/plan</code> (none) No Runs inline in main session (Betty Sue's work)

Agent → MCP Wiring

Agents access MCP servers via the mcpServers frontmatter field. If omitted, agents inherit ALL MCP servers from the parent session.
Agent MCP Servers Why
<code>dev</code> <code>pal-e-docs</code>, <code>forgejo</code> Read plans/SOPs, create issues, submit PRs
<code>qa</code> <code>pal-e-docs</code>, <code>forgejo</code> Read SOPs for compliance checks, review PRs, post comments
<code>issue-creator</code> <code>pal-e-docs</code>, <code>forgejo</code> Read plans/templates, check for duplicate issues

Dual Source of Truth

Each agent and skill has two representations:
What Runtime config Source of truth
Agent <code>~/.claude/agents/{name}.md</code> (frontmatter + thin pointer) <code>get_note(slug="agent-{name}")</code> in pal-e-docs
Skill <code>~/.claude/skills/{name}/SKILL.md</code> (frontmatter + thin pointer) <code>get_note(slug="skill-{name}")</code> in pal-e-docs
The files are thin pointers — they contain frontmatter for Claude Code's runtime and a get_note() call for the full content. pal-e-docs is where the SOPs, constraints, and step-by-step workflows live.

Why This Matters

  • Organizational clarity: Skills route work to the right agent. Agents have the right tools. MCP provides the right data.
  • Not security by itself: A misconfigured skill could route to the wrong agent. A missing disallowedTools entry could let QA write code. These are bugs, not security holes — because hooks are the real enforcement.
  • Hooks are the guarantee: Settings.json hooks block unauthorized merges, missing plan references, and direct main commits. Frontmatter PreToolUse hooks enforce tool restrictions inside agents. The wiring makes things convenient; hooks make things safe.
  • Enforcement asymmetry: Manual spawns (Agent tool) can be blocked by PreToolUse. Native delegation (SubagentStart) cannot be blocked — only context can be injected. Frontmatter hooks compensate by enforcing tool restrictions inside the agent.
  • enforcement-architecture — the enforcement stack, four pillars, and enforcement asymmetry
  • template-agent — agent frontmatter fields reference
  • template-skill — skill frontmatter fields and wiring pattern
  • agent-spawn-conventions — spawn axiom and enforcement asymmetry
  • hook-events-reference — SubagentStart context injection (not blocking)