Skills & Client Setup Guide

How to add CodeWiki MCP as a skill, custom instruction, or tool in VS Code, Copilot CLI, Claude Desktop, Cursor, Windsurf, and other AI clients.

Overview

Modern AI coding assistants support multiple ways to integrate external capabilities. This guide covers how to wire CodeWiki MCP into every major client — from VS Code Agent Skills (the new open standard) to MCP server configurations in Claude Desktop, Cursor, and Windsurf.

Client	Method	Config Location
VS Code	Agent Skills + MCP Server	`.github/skills/` + `.vscode/mcp.json`
VS Code	Custom Instructions	`.github/copilot-instructions.md`
VS Code	Prompt Files	`.github/prompts/`
VS Code	Custom Agents	`.github/agents/`
Copilot CLI	Skills + MCP + Instructions	`~/.copilot/`
Claude Desktop	MCP Server	`claude_desktop_config.json`
Cursor	MCP Server	`.cursor/mcp.json`
Windsurf	MCP Server	`~/.codeium/windsurf/mcp_config.json`
Claude Code	Agent Skills	`.claude/skills/`

VS Code: Agent Skills (Recommended)

Agent Skills is an open standard that works across VS Code, GitHub Copilot CLI, Claude Code, Cursor, and many other tools. Skills are folders with a SKILL.md file that Copilot loads on-demand when relevant to your task.

Already included: This repository ships with the codewiki-usage skill at .github/skills/codewiki-usage/SKILL.md and 5 custom agents in .github/agents/. The examples below show how to create your own or adapt them for other projects.

Step 1 — Create the skill folder

# In your project root:
mkdir -p .github/skills/codewiki-usage

Supported locations for skills:

Type	Paths
Project skills	`.github/skills/`, `.claude/skills/`, `.agents/skills/`
Personal skills	`~/.copilot/skills/`, `~/.claude/skills/`, `~/.agents/skills/`

Step 2 — Create SKILL.md

Create .github/skills/codewiki-usage/SKILL.md:

---
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)

| Tool | Tokens | Use When |
|------|--------|----------|
| codewiki_read_structure | ~Low  | First call — get the table of contents as JSON |
| codewiki_list_topics    | ~Med  | Need section titles + short previews |
| codewiki_read_contents  | ~High | Read full section content (supports pagination) |
| codewiki_search_wiki    | ~High | Ask Gemini a specific question about the repo |
| codewiki_request_indexing | ~Min | Submit an unindexed repo for Google to process |

## Recommended Workflow

1. Start cheap: codewiki_read_structure(repo_url) to see what sections exist
2. Pick sections: identify 1–3 relevant section titles
3. Read targeted: codewiki_read_contents(repo_url, section_title=<title>)
4. Search if needed: codewiki_search_wiki for specific questions
5. Paginate large sections: use offset and limit parameters

## Anti-Patterns to Avoid

- Don't call codewiki_list_topics AND codewiki_read_contents without
  a section_title — they overlap significantly
- Don't call codewiki_search_wiki first — it's the most expensive tool
- Don't read all sections — pick only what's relevant
- Don't guess section titles — get real titles from codewiki_read_structure

## Handling NOT_INDEXED Errors

1. Tell the user the repo is not yet indexed
2. Call codewiki_request_indexing(repo_url) to submit
3. Explain indexing depends on demand — suggest trying later
4. Never fabricate documentation for an unindexed repo

## Citation Rules

- Always cite which CodeWiki section your information comes from
- Use format: [Section Title] from owner/repo
- If from codewiki_search_wiki, note it was an AI-generated answer

Step 3 — Add supplementary resources (optional)

You can add example files alongside SKILL.md for richer context:

.github/skills/codewiki-usage/
  SKILL.md                  # Required — skill definition
  examples/
    research-workflow.md    # Example research session
    compare-repos.md        # How to compare two repos
  README.md                 # Additional notes for the skill

Step 4 — Wire up the MCP server

The skill needs the CodeWiki MCP server running. Add to .vscode/mcp.json:

{
  "servers": {
    "codewiki-mcp": {
      "type": "stdio",
      "command": "codewiki-mcp"
    }
  }
}

Step 5 — Use the skill

The skill activates automatically when Copilot detects a relevant task. You can also invoke it manually:

# Type / in the chat and select "codewiki-usage"
/codewiki-usage How does React handle fiber reconciliation?

Important: agents need the `read` tool

For skills to work, agents must have the read tool in their tools list. VS Code injects skill metadata into the agent's context, and the agent uses read to load the full SKILL.md content on demand. All CodeWiki subagents in this repo already include 'read':

# In .agent.md frontmatter:
tools:
  - 'read'                              # Required for skill loading
  - 'codewiki-mcp/codewiki_list_topics'
  - 'codewiki-mcp/codewiki_read_structure'
  # ... etc.

How Agent Skills loading works

Level	What loads	When
1. Discovery	`name` + `description` from frontmatter	Always (lightweight)
2. Instructions	Full SKILL.md body	When task matches description
3. Resources	Additional files in skill folder	Only when referenced

This progressive disclosure keeps context efficient — you can install many skills without consuming tokens.

VS Code: Custom Instructions

Custom instructions are always-on guidelines automatically included in every chat request. Use them for project-wide rules about how to use CodeWiki MCP.

Option A — copilot-instructions.md (always-on)

Create .github/copilot-instructions.md:

# Project Instructions

## CodeWiki MCP Usage
When the user asks about an open-source repository's architecture,
implementation, or documentation, use the CodeWiki MCP tools:

- Start with `codewiki_list_topics` to check coverage
- Use `codewiki_read_structure` to find relevant sections
- Use `codewiki_read_contents` for broad topics
- Use `codewiki_search_wiki` for specific implementation questions
- Use `codewiki_request_indexing` when a repo is not yet indexed
- Always cite which section or tool response your answer is based on
- Use `owner/repo` shorthand for repository URLs

Option B — .instructions.md (file-based, conditional)

Create .github/instructions/codewiki.instructions.md:

---
name: 'CodeWiki Research Rules'
description: 'Guidelines for using CodeWiki MCP tools when researching repos'
applyTo: '**'
---
When researching open-source repositories, always use CodeWiki MCP tools
in this order: topics → structure → contents → search.

Cite your sources by mentioning the section title you read from.
Never fabricate information — only report what the tools return.

Option C — AGENTS.md (multi-agent compatible)

For projects using multiple AI agents (VS Code, Claude Code, etc.), create an AGENTS.md in your workspace root with the same instructions. VS Code, Claude Code, and other tools recognize this file.

VS Code: Prompt Files

Prompt files are reusable slash commands (.prompt.md) you invoke manually in chat. Unlike skills that activate automatically, prompts run on demand.

Create a research prompt

Create .github/prompts/research-repo.prompt.md:

---
description: 'Research an open-source repository using CodeWiki MCP'
agent: agent
tools:
  - codewiki-mcp/*
---
Research the repository: ${input:repo:owner/repo}

Follow this workflow:
1. Call codewiki_list_topics to see what documentation exists
2. Call codewiki_read_structure to get the table of contents
3. Read the most relevant sections using codewiki_read_contents
4. Answer the user's question with citations

User's question: ${input:question:What do you want to know?}

Use it in chat

# Type / and select "research-repo"
/research-repo

VS Code prompts you for the repo and question inputs, then runs the full workflow.

VS Code: Custom Agents

Custom agents are persistent AI personas with specific tools and instructions. This repo ships with a proven 5-agent architecture — 1 master orchestrator + 4 specialist subagents. See the Agentic AI Guide for the full architecture.

Included agents (in .github/agents/):

File	Agent	Role
`codewiki.agent.md`	CodeWiki (master)	Routes requests to the right specialist
`codewiki-researcher.agent.md`	CodeWiki Researcher	General codebase exploration
`codewiki-reviewer.agent.md`	CodeWiki Code Review	Module/function analysis
`codewiki-architect.agent.md`	CodeWiki Architecture Explorer	System design & data flow
`codewiki-comparison.agent.md`	CodeWiki Comparison	Multi-repo side-by-side analysis

Creating your own agent

Create a .agent.md file in .github/agents/:

---
name: CodeWiki Researcher
description: Explores open-source codebases using Google CodeWiki
model: GPT-5 Mini (copilot)
user-invokable: false
tools:
  - 'read'
  - 'codewiki-mcp/codewiki_list_topics'
  - 'codewiki-mcp/codewiki_read_structure'
  - 'codewiki-mcp/codewiki_read_contents'
  - 'codewiki-mcp/codewiki_search_wiki'
  - 'codewiki-mcp/codewiki_request_indexing'
---
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.

## 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 user
- Use owner/repo shorthand for repo_url parameters
- Never fabricate information — only report what tools return

Key design choices

Pure router master — The master has only the agent tool (zero MCP tools). This forces delegation and saves tokens by eliminating redundant availability checks.
user-invokable: false — Subagents are hidden from the picker; only the master is user-facing.
'read' tool — Required for on-demand skill loading via SKILL.md files.
Subagents handle errors — Each subagent has all 5 MCP tools and handles NOT_INDEXED errors independently. No pre-checking by the master needed.
Explicit tool names — Use 'codewiki-mcp/codewiki_list_topics' format (must match the server name in .vscode/mcp.json).

Use it in chat

Type @codewiki in VS Code Chat to invoke the master orchestrator, which routes to the right specialist.

GitHub Copilot CLI

GitHub Copilot CLI is a powerful terminal-based AI agent that supports Agent Skills, MCP servers, custom instructions, and custom agents — the same customization primitives as VS Code.

Step 1 — Install Copilot CLI

# npm (all platforms — requires Node.js 22+)
npm install -g @github/copilot

# WinGet (Windows)
winget install GitHub.Copilot

# Homebrew (macOS / Linux)
brew install copilot-cli

# Install script (macOS / Linux)
curl -fsSL https://gh.io/copilot-install | bash

Then start a session with copilot and authenticate using the /login slash command.

Step 2 — Add CodeWiki MCP server

Inside an interactive Copilot CLI session, use the /mcp add slash command:

# In a Copilot CLI session:
/mcp add

# Fill in the fields:
#   Name:    codewiki
#   Command: codewiki-mcp
#   Args:    (leave empty)
# Press Ctrl+S to save

The server config is stored in ~/.copilot/mcp-config.json. You can also edit this file directly:

{
  "mcpServers": {
    "codewiki": {
      "command": "codewiki-mcp"
    }
  }
}

Verify the server is active with /mcp in the interactive session.

Step 3 — Skills (automatic)

Copilot CLI reads Agent Skills from the same locations as VS Code:

Scope	Location
Repository	`.github/skills/`
User (personal)	`~/.copilot/skills/`

If you created the .github/skills/codewiki-usage/SKILL.md file from the VS Code section above (already included in this repo), Copilot CLI will automatically discover and use it when relevant.

Step 4 — Custom instructions (automatic)

Copilot CLI automatically picks up:

.github/copilot-instructions.md — repository-wide instructions
.github/instructions/**/*.instructions.md — path-specific instructions
AGENTS.md — multi-agent compatible instructions

All instruction files combine and are included in your prompts automatically.

Step 5 — Custom agents

Copilot CLI loads custom agents from:

Scope	Location
User-level	`~/.copilot/agents/`
Repository-level	`.github/agents/`
Organization-level	`.github-private/agents/`

Use agents with the /agent slash command, reference them in a prompt, or pass --agent=name on the command line:

# Interactive mode — pick from list
/agent

# Reference in a prompt
Use the codewiki-researcher agent to explain React fiber

# Programmatic mode
copilot --agent=codewiki-researcher -p "Explain React fiber"

Step 6 — MCP tool permissions

By default Copilot CLI asks approval before using MCP tools. You can pre-approve CodeWiki tools:

# Allow all tools from the codewiki server
copilot --allow-tool 'codewiki'

# Or allow all tools globally (use with caution)
copilot --allow-all-tools

Copilot CLI built-in agents

Copilot CLI ships with specialized agents you can combine with CodeWiki:

Agent	Purpose
Explore	Quick codebase analysis without adding to main context
Task	Execute commands (tests, builds) with summary output
Plan	Analyze dependencies and create implementation plans
Code-review	Review changes, surfacing genuine issues

Claude Desktop

Claude Desktop connects to MCP servers via claude_desktop_config.json.

Step 1 — Open config

Open Claude Desktop, go to Settings → Developer → Edit Config. The file is at:

OS	Path
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Windows	`%APPDATA%\Claude\claude_desktop_config.json`

Step 2 — Add CodeWiki MCP

{
  "mcpServers": {
    "codewiki": {
      "command": "codewiki-mcp"
    }
  }
}

If you installed via uvx:

{
  "mcpServers": {
    "codewiki": {
      "command": "uvx",
      "args": ["codewiki-mcp"]
    }
  }
}

Step 3 — Restart Claude Desktop

Quit and relaunch Claude Desktop. You should see an MCP indicator in the chat input. Click it to see the 4 CodeWiki tools.

Cursor

Cursor supports MCP servers via .cursor/mcp.json (project-level) or ~/.cursor/mcp.json (global).

Project-level config

Create .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "codewiki": {
      "command": "codewiki-mcp"
    }
  }
}

Global config

Create ~/.cursor/mcp.json to make CodeWiki available in all Cursor projects:

{
  "mcpServers": {
    "codewiki": {
      "command": "codewiki-mcp"
    }
  }
}

With Python/uvx

{
  "mcpServers": {
    "codewiki": {
      "command": "uvx",
      "args": ["codewiki-mcp"]
    }
  }
}

Once configured, CodeWiki tools appear in Cursor's Available Tools list in Agent mode. Cursor loads them automatically when relevant.

Windsurf

Windsurf uses ~/.codeium/windsurf/mcp_config.json for MCP server configuration. You can also add servers via the MCP Marketplace in the Cascade panel.

Manual config

{
  "mcpServers": {
    "codewiki": {
      "command": "codewiki-mcp"
    }
  }
}

With uvx

{
  "mcpServers": {
    "codewiki": {
      "command": "uvx",
      "args": ["codewiki-mcp"]
    }
  }
}

After saving, restart Windsurf. The tools appear in Cascade's MCP tools panel.

Claude Code & Other Agent Skills Clients

The Agent Skills standard (agentskills.io) is supported by a growing ecosystem of tools:

Claude Code — reads from .claude/skills/
GitHub Copilot CLI — uses the same .github/skills/
Roo Code, OpenAI Codex, Factory, Qodo, Goose, Firebender

For Claude Code, create the skill at .claude/skills/codewiki-usage/SKILL.md using the same SKILL.md content shown in the VS Code section above.

SSE / HTTP Mode (Any Client)

For clients that support remote MCP servers via SSE or Streamable HTTP:

# Start CodeWiki MCP in SSE mode
codewiki-mcp --sse --port 8080

Then point your client to the endpoint:

# Cursor / Windsurf remote config example
{
  "mcpServers": {
    "codewiki": {
      "url": "http://localhost:8080/sse"
    }
  }
}

When to Use What

VS Code offers multiple customization layers. Here's when to use each:

Mechanism	Scope	Activation	Best For
Agent Skills	Portable (cross-tool)	Auto + slash command	Reusable capabilities with scripts and examples
Custom Instructions	VS Code + GitHub	Always-on or glob-matched	Project-wide coding standards and guidelines
Prompt Files	VS Code	Manual (slash command)	Repeatable tasks like scaffolding or reviews
Custom Agents	VS Code	Manual (agent picker)	Specialized personas with restricted tool sets
MCP Server	Universal	Auto (available tools)	Making tools available to any MCP-compatible client

Troubleshooting

VS Code Diagnostics

Right-click in the Chat view and select Diagnostics to see all loaded skills, agents, prompts, and instructions. You can also run the quick commands:

# Quick access commands in VS Code chat input:
/skills         → Configure Skills menu
/instructions   → Configure Instructions menu
/prompts        → Configure Prompt Files menu
/agents         → Configure Custom Agents menu

Common issues

Issue	Solution
Skill not appearing in `/` menu	Check `SKILL.md` is in a supported location and has valid YAML frontmatter with `name` and `description`. The skill name must match its parent folder name.
MCP tools not available	Verify `.vscode/mcp.json` has the server config and `codewiki-mcp` is installed and on PATH
Instructions not applying	Check `applyTo` glob pattern matches your files; verify in Diagnostics view
Claude Desktop: no MCP indicator	Fully quit and restart; check config file path and JSON syntax
Cursor: tools not showing	Verify `.cursor/mcp.json` is valid JSON; restart Cursor
Skill not loading in agent	Ensure the agent has `'read'` in its tools list. VS Code needs the read tool to load skill content on demand. Check `chat.useAgentSkills` is `true` in settings.
Agent tool name mismatch	Tool references in `.agent.md` must use the format `'server-name/tool_name'` matching the server name in `.vscode/mcp.json`. For this repo: `'codewiki-mcp/codewiki_list_topics'`.

Skills & Client Setup Guide

Overview

VS Code: Agent Skills (Recommended)

Step 1 — Create the skill folder

Step 2 — Create SKILL.md

Step 3 — Add supplementary resources (optional)

Step 4 — Wire up the MCP server

Step 5 — Use the skill

Important: agents need the read tool

How Agent Skills loading works

VS Code: Custom Instructions

Option A — copilot-instructions.md (always-on)

Option B — .instructions.md (file-based, conditional)

Option C — AGENTS.md (multi-agent compatible)

VS Code: Prompt Files

Create a research prompt

Use it in chat

VS Code: Custom Agents

Creating your own agent

Key design choices

Use it in chat

GitHub Copilot CLI

Step 1 — Install Copilot CLI

Step 2 — Add CodeWiki MCP server

Step 3 — Skills (automatic)

Step 4 — Custom instructions (automatic)

Step 5 — Custom agents

Step 6 — MCP tool permissions

Copilot CLI built-in agents

Claude Desktop

Step 1 — Open config

Step 2 — Add CodeWiki MCP

Step 3 — Restart Claude Desktop

Cursor

Project-level config

Global config

With Python/uvx

Windsurf

Manual config

With uvx

Claude Code & Other Agent Skills Clients

SSE / HTTP Mode (Any Client)

When to Use What

Troubleshooting

VS Code Diagnostics

Common issues

References

Important: agents need the `read` tool