Subagent Architecture Patterns Skill

Subagent Architecture Patterns

Subagents provide context isolation - intermediate work stays in subagent's context, keeping main conversation clean.

Skill Loading

Two Methods

| Method | When | How | |--------|------|-----| | Frontmatter | Known skills at design time | skills: skill1, skill2 | | Skill tool | Dynamic discovery at runtime | Skill("plugin:skill-name") |

Method 1: Frontmatter (Static)

skills: skill1, skill2    # Auto-loaded at subagent start

Skills can come from any source (plugins, user, project) - all are globally available.

Method 2: Skill Tool (Dynamic) - REQUIRED for Enhanced Agents

When user asks about [topic]:
1. Call `Skill("plugin:relevant-skill")` to load expertise
2. Apply loaded skill's guidance
3. Do NOT fall back to manual file reading

CRITICAL: Agents with Skill tool MUST use it instead of:

❌ Reading skill files directly via Read tool
❌ Searching for patterns manually via Grep/Glob
✅ Skill("forge-editor:skill-design") - Correct

Example Dynamic Call:

User: "Create a new skill for API validation"
Agent: Skill("forge-editor:skill-design")  ← Load skill expertise first
Agent: [Apply skill-design guidance to create the skill]

Pattern 1: Single-Skill Consumer

Use when: Focused, single-domain task

---
name: sql-agent
skills: sql-helper
tools: ["Read", "Grep", "Glob"]
model: sonnet
---

User → Subagent [isolated] → skill-x → Focused result

✅ Fast, focused, clear responsibility ❌ Limited to one domain

Pattern 2: Multi-Skill Orchestrator

Use when: Multi-domain workflow

---
name: fullstack-orchestrator
skills: frontend-design, api-generator, migration-patterns
tools: ["Read", "Write", "Bash", "Task"]
model: sonnet
---

User → Orchestrator [isolated]
         ├→ skill-a (if UI)
         ├→ skill-b (if API)
         └→ skill-c (if DB)
       → Coordinated result

✅ Handles complex workflows ❌ More decision-making overhead

Pattern 3: Enhanced Agent (with Codebase Bridge + Memory)

Use when: Complex tasks requiring codebase understanding and session continuity

---
name: smart-orchestrator
skills: domain-skill-1, domain-skill-2
tools: ["Read", "Write", "Bash", "Task", "Skill"]
model: sonnet
---

Session Start
    ↓
claude-mem: load recent context
    ↓
User Request
    ↓
Serena Gateway: explore codebase (QUERY)
    ↓
Match findings → skill-rules.json
    ↓
Auto-call relevant skills (via Skill tool)
    ↓
Execute task
    ↓
claude-mem: store observation

✅ Smart skill discovery via codebase analysis ✅ Cross-session memory persistence ✅ Reduces manual skill selection ❌ Requires Serena + claude-mem setup

Key Components:

Serena Gateway - Codebase exploration with MCP isolation (see mcp-gateway-patterns)
skill-rules.json - Trigger patterns for auto-activation (see skill-activation-patterns)
claude-mem - Context persistence across sessions (see references/enhanced-agent.md)

Decision Matrix

| Question | Single-Skill | Multi-Skill | Enhanced | |----------|--------------|-------------|----------| | Scope? | Narrow | Broad | Broad + Smart | | Skills needed? | 1 | 2+ | 2+ (auto-discovered) | | Coordination? | No | Yes | Yes + Auto | | Memory? | No | No | Yes (claude-mem) | | Codebase Aware? | No | No | Yes (Serena) |

Best Practices

Single-Skill:

Name: {domain}-agent
Minimal tools (Read, Grep, Glob)
"Use {skill} for all operations"

Multi-Skill:

Name: {domain}-orchestrator
Include Task tool for sub-delegation
Document when to use each skill
"Don't activate all skills for simple requests"

Enhanced:

Name: {domain}-smart-agent
Include Task + Skill tools
Configure Serena Gateway for exploration
Set claude-mem project name
MUST use Skill() tool for dynamic skill loading
Add explicit instruction: "When relevant topic detected, call Skill('plugin:skill-name') before proceeding. Do NOT read skill files directly."

Agent Skills: Subagent Architecture Patterns

Install this agent skill to your local

Skill Files