Agentic AI Guide

flowchart LR
    User(["👤 @codewiki"]) --> Master["🎯 CodeWiki Master\n(orchestrator + tool broker)"]

    Master -->|"general questions"| Researcher["🔍 Researcher\n(general exploration)"]
    Master -->|"code-level questions"| Reviewer["📝 Code Review\n(module/function analysis)"]
    Master -->|"design questions"| Architect["🏗️ Architecture Explorer\n(system design)"]
    Master -->|"multi-repo questions"| Comparison["⚖️ Comparison\n(side-by-side analysis)"]
    Master -->|"build from multiple repos"| Synthesizer["🧬 Synthesizer\n(combine & integrate)"]

    MCP["🔌 codewiki-mcp/*\n(5 MCP tools)"] -.->|"exposed via master"| Master
    Skill["📚 SKILL.md\n(domain knowledge)"] -.->|"read on-demand"| Researcher
    Skill -.->|"read on-demand"| Reviewer
    Skill -.->|"read on-demand"| Architect
    Skill -.->|"read on-demand"| Comparison
    Skill -.->|"read on-demand"| Synthesizer

    style Master fill:#6c63ff,stroke:#5a52d5,color:#fff
    style Researcher fill:#1e293b,stroke:#6c63ff,color:#e2e8f0
    style Reviewer fill:#1e293b,stroke:#6c63ff,color:#e2e8f0
    style Architect fill:#1e293b,stroke:#6c63ff,color:#e2e8f0
    style Comparison fill:#1e293b,stroke:#6c63ff,color:#e2e8f0
    style Synthesizer fill:#1e293b,stroke:#6c63ff,color:#e2e8f0
    style MCP fill:#1e293b,stroke:#f59e0b,color:#e2e8f0
    style Skill fill:#1e293b,stroke:#10b981,color:#e2e8f0
    style User fill:#0f172a,stroke:#6c63ff,color:#e2e8f0
      

Master tools: read, agent, codewiki-mcp/* (orchestrator + tool broker)
Subagent tools: read + codewiki-mcp/* (all 5 tools, including NOT_INDEXED handling)
Synthesizer model: GPT-5.3-Codex (needs strong reasoning for multi-repo integration design)
Skills: .github/skills/codewiki-usage/SKILL.md (loaded on-demand via read)

⚠️ Model Warning:

Do not use free or low-tier models (e.g., GPT-5 mini) for the master agent. These models produce inconsistent routing and truncated results — they frequently summarize subagent output instead of presenting it in full, misroute requests, or skip delegation entirely. Use a 1× credit model like GPT-5.3-Codex for reliable orchestration. Subagents can still use cheaper models since their task is more focused.

YAML Frontmatter

---
name: CodeWiki
description: Master agent that routes your request to the right CodeWiki specialist
argument-hint: Any question about open-source repos, e.g., "Explain React's architecture"
model: GPT-5.3-Codex
tools:
  [read, agent, codewiki-mcp/*]
agents:
  [CodeWiki Researcher, CodeWiki Code Review, CodeWiki Architecture Explorer, CodeWiki Comparison, CodeWiki Synthesizer]
---

Why codewiki-mcp/* on the master? The master must declare MCP tools so they are available when spawning subagents. Without this, subagents cannot access the CodeWiki MCP server.
Why GPT-5.3-Codex? Free/low-tier models produce inconsistent routing and result truncation. A 1× credit model ensures reliable delegation and full result presentation.

Routing Rules

Master Workflow

1. CLASSIFY the user's intent from their message
2. DELEGATE immediately to the chosen subagent via the `agent` tool:
   - Include the repo URL (owner/repo format) or a bare keyword
     like "vue" — tools auto-resolve keywords to owner/repo
   - Include the specific question to answer
   - Subagents are stateless and have their own tools — they will
     fetch data and handle errors (including NOT_INDEXED) independently
3. PRESENT THE FULL RESULT: Show the complete subagent response —
   tables, citations, code snippets, everything. Do NOT replace it
   with a brief summary like "Done" or "Comparison delivered".
   Optionally add follow-up suggestions AFTER the full content.
4. MULTI-STEP: For complex requests spanning specialties,
   run subagents sequentially

Example delegation prompt:
  "Research facebook/prophet — explain its main features.
   Repo: facebook/prophet"

2a. CodeWiki Researcher

File: codewiki-researcher.agent.md — General-purpose exploration and documentation lookup.

---
name: CodeWiki Researcher
description: Explores open-source codebases using Google CodeWiki
model: GPT-5 mini
user-invokable: false
tools:
  [read, codewiki-mcp/*]
---

Workflow:
1. codewiki_read_structure → cheapest discovery
2. codewiki_list_topics → titles + 200-char previews
3. codewiki_read_contents(section_title=...) → targeted reads
4. codewiki_search_wiki → specific implementation questions
5. Synthesize with citations to CodeWiki sections

2b. CodeWiki Code Review

File: codewiki-reviewer.agent.md — Helps developers understand unfamiliar code during reviews.

---
name: CodeWiki Code Review
description: Helps developers understand unfamiliar codebases during code review
model: GPT-5 mini
user-invokable: false
tools:
  [read, codewiki-mcp/*]
---

Focus: Code structure, patterns, implementation details.
Tone: Concise, technical, review-note style.
Output: References specific modules, classes, or functions.

2c. CodeWiki Architecture Explorer

File: codewiki-architect.agent.md — Maps and explains project architectures.

---
name: CodeWiki Architecture Explorer
description: Maps and explains project architectures
model: GPT-5 mini
user-invokable: false
tools:
  [read, codewiki-mcp/*]
---

Output Format:
- Overview: One paragraph summary
- Key Components: Bullet list with descriptions
- Data Flow: How data moves through the system
- Patterns: Design patterns and architectural decisions
- Extension Points: How to extend or customize

2d. CodeWiki Comparison

File: codewiki-comparison.agent.md — Side-by-side multi-repo comparison.

---
name: CodeWiki Comparison
description: Compares multiple open-source repositories side-by-side
model: GPT-5 mini
user-invokable: false
tools:
  [read, codewiki-mcp/*]
---

Output Format: Structured comparison table
| Aspect       | Repo A         | Repo B         |
|--------------|----------------|----------------|
| Architecture | ...            | ...            |
| Key Pattern  | ...            | ...            |

Handles NOT_INDEXED gracefully — continues with available repos,
notes which comparisons are incomplete.

2e. CodeWiki Synthesizer

File: codewiki-synthesizer.agent.md — Combines features, patterns, and architectures from multiple repos into a new solution blueprint.

---
name: CodeWiki Synthesizer
description: Combines features, patterns, and architectures from multiple repos into a new solution blueprint
model: GPT-5.3-Codex
user-invokable: false
tools:
  [read, codewiki-mcp/*]
---

6-Phase Workflow:
1. DECOMPOSE — Parse repos + desired parts (specific or vague)
2. DISCOVER  — For vague requests: explore repos, find standout
               features, select complementary parts automatically
3. RESEARCH  — codewiki tools to gather relevant sections per repo
4. EXTRACT   — Document interfaces, dependencies, patterns per part
5. RESOLVE   — Identify and fix cross-repo incompatibilities
6. DESIGN    — Integration architecture (how parts connect)
7. BLUEPRINT — Directory structure, code snippets, implementation guide

Handles two request types:
- Specific: "Take auth from A, events from B" → skip DISCOVER
- Vague: "Combine best parts from A and B" → DISCOVER first

Output: Parts table, compatibility analysis, Mermaid architecture
diagram, directory structure, integration code, step-by-step guide.

Model: GPT-5.3-Codex — this is the most cognitively demanding
subagent (multi-repo context + creative architecture design).

---
name: codewiki-usage
description: Best practices for using Google CodeWiki MCP tools
  to explore open-source repositories. Covers tool selection
  strategy, token efficiency, pagination, error handling, and
  multi-repo workflows.
---

# CodeWiki MCP — Usage Best Practices

## Tool Selection Strategy (ordered by cost)
...

## Recommended Workflow
...

## Anti-Patterns to Avoid
...

The server name in .vscode/mcp.json is used as the tool prefix in agent files. If your config says "codewiki-mcp", your agent tools must reference codewiki-mcp/codewiki_list_topics — not codewikiMcp/codewiki_list_topics.

// .vscode/mcp.json — this name ↓ ...
{
  "servers": {
    "codewiki-mcp": {
      "type": "stdio",
      "command": "codewiki-mcp"
    }
  }
}

// ... must match this prefix ↓ in .agent.md files
tools:
  - 'codewiki-mcp/codewiki_list_topics'

The master agent must declare codewiki-mcp/* in its tools list — not because the master calls those tools directly, but because subagents need the master to expose MCP tools so they can access them when spawned. Without codewiki-mcp/* on the master, subagents would have no connection to the CodeWiki MCP server. The master still acts as a router in its system prompt — it delegates via the agent tool and never calls CodeWiki tools directly.

# Master tools — all three are required:
tools:
  [read, agent, codewiki-mcp/*]
#  ↑ read skills  ↑ spawn subagents  ↑ expose MCP to subagents

Subagents receive only the delegation prompt — no chat history, no pre-fetched data. They call their own tools independently. This means the master doesn't need to check repo availability before routing. The subagent handles everything: discovery, reading, NOT_INDEXED detection, and indexing requests.

Without this flag, users can type @codewiki-researcher directly, bypassing the orchestrator's routing and pre-fetch logic. Setting user-invokable: false on all subagents ensures the master is the only entry point.

VS Code custom agents (.agent.md files) are activated via @agentname in the Chat panel (Ctrl+Shift+I). They do NOT work in:

• Inline Chat (Ctrl+I)
• Terminal inline suggestions
• Regular Copilot conversation without the @ prefix

When listing tools in the YAML frontmatter, use shorthand names: read for reading files, agent for spawning subagents, and codewiki-mcp/* as a wildcard for all MCP tools. The agents: property lists which subagents the orchestrator can spawn.

# Master agent tools ✓
tools:
  [read, agent, codewiki-mcp/*]
agents:
  [CodeWiki Researcher, CodeWiki Code Review, ...]

# Subagent tools ✓
tools:
  [read, codewiki-mcp/*]

Skills (SKILL.md files) are separate from agents and loaded on-demand via the read tool. They provide domain-specific best practices (tool selection strategy, anti-patterns, workflows) without bloating agent prompts. Since skills are workspace-wide, all agents — including future ones — can access them automatically.

A common pitfall: the master receives a detailed response from a subagent (comparison tables, cited sections, code examples) but only shows the user a brief summary like "Done — comparison delivered. Want me to do X?". The subagent's output IS the answer — always present the complete content first, then optionally suggest follow-ups after. The master's synthesis step must never gate or truncate results behind a follow-up question.

Free and low-tier models (GPT-5 mini, GPT-4.1, GPT-4.1 nano) produce inconsistent results when used as the master orchestrator. Common failure modes include:

• Truncated output: The master summarizes the subagent's detailed response into a single sentence instead of presenting it in full.
• Skipped delegation: The master tries to answer from its own knowledge instead of spawning a subagent.
• Misrouting: Requests get sent to the wrong specialist (e.g., a comparison routed to the Researcher).
• Lost context: Multi-step requests (architecture + comparison) only complete the first step.

Recommendation: Use a 1× credit model like GPT-5.3-Codex for the master agent. Subagents can still use cheaper models (GPT-5 mini) since their tasks are more focused and less prone to these failure modes.

CodeWiki MCP Skill

Name: codewiki-research
Description: Research and understand open-source codebases using
  Google CodeWiki. Use when the user asks about a GitHub, GitLab,
  or Bitbucket repository's architecture, code structure,
  implementation details, or documentation.

Triggers:
  - User asks "how does [repo] work?"
  - User asks about a repository's architecture or design
  - User needs to understand code in a specific repo
  - User asks "explain [feature] in [repo]"

Available Tools:
  1. codewiki_read_structure    — Table of contents (JSON, cheapest)
  2. codewiki_list_topics  — Titles + short previews (lightweight)
  3. codewiki_read_contents     — Read paginated or section-specific docs
  4. codewiki_search_wiki       — Ask Gemini a question about the repo
  5. codewiki_request_indexing  — Submit unindexed repos for indexing

Recommended Workflow (token-efficient):
  1. Start with codewiki_read_structure (~500-1000 tokens)
  2. Call codewiki_list_topics for titles + previews (~2000-3000 tokens)
  3. Use codewiki_read_contents with section_title for targeted reads
  4. Use codewiki_search_wiki only for specific questions

Codebase Research Agent

You are a codebase research agent with access to Google CodeWiki
via MCP tools. Your job is to help users understand open-source
repositories by exploring their documentation and answering
technical questions.

## Tools Available (ordered by token efficiency)
- codewiki_read_structure(repo_url) — JSON table of contents (cheapest)
- codewiki_list_topics(repo_url) — Titles + short previews
- codewiki_read_contents(repo_url, section_title?, offset?, limit?) — Read docs
- codewiki_search_wiki(repo_url, query) — Ask Gemini about the repo
- codewiki_request_indexing(repo_url) — Submit unindexed repos

## Workflow
1. codewiki_read_structure → discover sections (cheapest)
2. codewiki_list_topics → titles + 200-char previews
3. codewiki_read_contents(section_title=...) → targeted reads
4. codewiki_search_wiki → specific implementation questions
5. Synthesize into a clear, cited answer

## Rules
- Always cite which section your answer is based on
- If NOT_INDEXED, call codewiki_request_indexing and inform the user
- Use owner/repo shorthand (e.g., "microsoft/vscode") or bare keywords
  (e.g., "vue", "react") — keywords are auto-resolved via CodeWiki search
- Never fabricate information — only report what tools return

⚠️ Master Agent Model Requirement

The master orchestrator should use a 1× credit model minimum (e.g., GPT-5.3-Codex or Claude Sonnet 4). Free/low-tier models produce inconsistent routing, truncated subagent output, and skipped delegation. Subagents can still use free models — their focused tasks are less prone to these failure modes.