gh-yaleh-meta-cc-claude/skills/subagent-prompt-construction/reference/integration-patterns.md

Claude Code Integration Patterns

Formal patterns for integrating Claude Code features (agents, MCP tools, skills) in subagent prompts.

---

1. Subagent Composition

Pattern:

agent(type, description) :: Context → Output

Semantics:

agent(type, desc) =
  invoke_task_tool(subagent_type: type, prompt: desc) ∧
  await_completion ∧
  return output

Usage in prompt:

agent(project-planner,
  "Create detailed TDD implementation plan for: ${objectives}\n" +
  "Scope: ${scope}\n" +
  "Constraints: ${constraints}"
) → plan

Actual invocation (Claude Code):

Task(subagent_type="project-planner", description=f"Create detailed TDD...")

Declaration:

agents_required :: [AgentType]
agents_required = [project-planner, stage-executor, ...]

Best practices:

• Declare all agents in dependencies section
• Pass context explicitly via description string
• Use meaningful variable names for outputs (→ plan, → result)
• Handle agent failures with conditional logic

Example:

generate_plan :: Requirements → Plan
generate_plan(req) =
  agent(project-planner, "Create plan for: ${req.objectives}") → plan ∧
  validate_plan(plan) ∧
  return plan

---

2. MCP Tool Integration

Pattern:

mcp::tool_name(params) :: → Data

Semantics:

mcp::tool_name(p) =
  direct_invocation(mcp__namespace__tool_name, p) ∧
  handle_result ∧
  return data

Usage in prompt:

mcp::query_tool_errors(limit: 20) → recent_errors
mcp::query_summaries() → summaries
mcp::query_user_messages(pattern: ".*bug.*") → bug_reports

Actual invocation (Claude Code):

mcp__meta_cc__query_tool_errors(limit=20)
mcp__meta_cc__query_summaries()
mcp__meta_cc__query_user_messages(pattern=".*bug.*")

Declaration:

mcp_tools_required :: [ToolName]
mcp_tools_required = [
  mcp__meta-cc__query_tool_errors,
  mcp__meta-cc__query_summaries,
  mcp__meta-cc__query_user_messages
]

Best practices:

• Use mcp:: prefix for clarity
• Declare all MCP tools in dependencies section
• Specify full tool name in declaration (mcp__namespace__tool)
• Handle empty results gracefully
• Limit result sizes with parameters

Example:

error_analysis :: Execution → ErrorReport
error_analysis(exec) =
  mcp::query_tool_errors(limit: 20) → recent_errors ∧
  if |recent_errors| > 0 then
    categorize(recent_errors) ∧
    suggest_fixes(recent_errors)
  else
    report("No errors found")

---

3. Skill Reference

Pattern:

skill(name) :: Context → Result

Semantics:

skill(name) =
  invoke_skill_tool(command: name) ∧
  await_completion ∧
  return guidelines

Usage in prompt:

skill(testing-strategy) → test_guidelines
skill(code-refactoring) → refactor_patterns
skill(methodology-bootstrapping) → baime_framework

Actual invocation (Claude Code):

Skill(command="testing-strategy")
Skill(command="code-refactoring")
Skill(command="methodology-bootstrapping")

Declaration:

skills_required :: [SkillName]
skills_required = [testing-strategy, code-refactoring, ...]

Best practices:

• Reference skill by name (kebab-case)
• Declare all skills in dependencies section
• Use skill guidelines to inform agent decisions
• Skills provide context, not direct execution
• Apply skill patterns via agent logic

Example:

enhance_tests :: CodeArtifact → ImprovedTests
enhance_tests(code) =
  skill(testing-strategy) → guidelines ∧
  current_coverage = analyze_coverage(code) ∧
  gaps = identify_gaps(code, guidelines) ∧
  generate_tests(gaps, guidelines)

---

4. Resource Loading

Pattern:

read(path) :: Path → Content

Semantics:

read(p) =
  load_file(p) ∧
  parse_content ∧
  return content

Usage in prompt:

read("docs/plan.md") → plan_doc
read("iteration_{n-1}.md") → previous_iteration
read("TODO.md") → tasks

Actual invocation (Claude Code):

Read(file_path="docs/plan.md")
Read(file_path=f"iteration_{n-1}.md")
Read(file_path="TODO.md")

Best practices:

• Use relative paths when possible
• Handle file not found errors
• Parse structured content (markdown, JSON)
• Extract relevant sections only
• Cache frequently accessed files

Example:

load_context :: IterationNumber → Context
load_context(n) =
  if n > 0 then
    read(f"iteration_{n-1}.md") → prev ∧
    extract_state(prev)
  else
    initial_state()

---

5. Combined Integration

Pattern: Multiple feature types in single prompt

Example (phase-planner-executor):

execute_phase :: FeatureSpec → PhaseReport
execute_phase(spec) =
  # Agent composition
  plan = agent(project-planner, spec.objectives) →

  # Sequential agent execution
  ∀stage_num ∈ [1..|plan.stages|]:
    result = agent(stage-executor, plan.stages[stage_num]) →

    # MCP tool integration for error analysis
    if result.status == "error" then
      errors = mcp::query_tool_errors(limit: 20) →
      analysis = analyze(errors) →
      return (plan, results, analysis)

  # Final reporting
  report(plan, results, quality_check, progress_tracking)

Integration score: 4 features (2 agents + 2 MCP tools) → 0.75

Best practices:

• Use ≥3 features for high integration score (≥0.75)
• Combine patterns appropriately (orchestration + analysis)
• Declare all dependencies upfront
• Handle failures at integration boundaries
• Maintain compactness despite multiple integrations

---

6. Conditional Integration

Pattern: Feature usage based on runtime conditions

Example:

execute_with_monitoring :: Task → Result
execute_with_monitoring(task) =
  result = agent(executor, task) →

  if result.status == "error" then
    # Conditional MCP integration
    errors = mcp::query_tool_errors(limit: 10) →
    recent_patterns = mcp::query_summaries() →
    enhanced_diagnosis = combine(errors, recent_patterns)
  else if result.needs_improvement then
    # Conditional skill reference
    guidelines = skill(code-refactoring) →
    suggestions = apply_guidelines(result, guidelines)
  else
    result

Benefits:

• Resource-efficient (only invoke when needed)
• Clearer error handling
• Adaptive behavior

---

Integration Complexity Matrix

Features	Integration Score	Complexity	Example
1 agent	0.25	Low	Simple executor
2 agents	0.50	Medium	Planner + executor
2 agents + 1 MCP	0.60	Medium-High	Executor + error query
2 agents + 2 MCP	0.75	High	phase-planner-executor
3 agents + 2 MCP + 1 skill	0.90	Very High	Complex orchestration

Recommendation: Target 0.50-0.75 for maintainability

---

Dependencies Section Template

## Dependencies

agents_required :: [AgentType]
agents_required = [
  agent-type-1,
  agent-type-2,
  ...
]

mcp_tools_required :: [ToolName]
mcp_tools_required = [
  mcp__namespace__tool_1,
  mcp__namespace__tool_2,
  ...
]

skills_required :: [SkillName]
skills_required = [
  skill-name-1,
  skill-name-2,
  ...
]

Rules:

• All sections optional (omit if not used)
• List all features used in prompt
• Use correct naming conventions (kebab-case for skills/agents, mcp__namespace__tool for MCP)
• Order: agents, MCP tools, skills

---

Error Handling Patterns

Agent Failure

result = agent(executor, task) →
if result.status == "error" then
  error_analysis(result) →
  return (partial_result, error_report)

MCP Tool Empty Results

data = mcp::query_tool(params) →
if |data| == 0 then
  return "No data available for analysis"
else
  process(data)

Skill Not Available

guidelines = skill(optional-skill) →
if guidelines.available then
  apply(guidelines)
else
  use_default_approach()

---

Validation Criteria

Integration quality checklist:

• All features declared in dependencies section
• Feature invocations use correct syntax
• Error handling at integration boundaries
• Integration score ≥0.50
• Compactness maintained despite integrations
• Clear separation between feature types
• Meaningful variable names for outputs

---

Related Resources

• Patterns: patterns.md (orchestration, analysis, enhancement patterns)
• Symbolic Language: symbolic-language.md (formal syntax)
• Template: ../templates/subagent-template.md (includes dependencies section)
• Example: ../examples/phase-planner-executor.md (2 agents + 2 MCP tools)