Tutorial de Claude Opus 4.5: crea un agente para wikis de GitHub

Muchos repositorios modernos de GitHub carecen de documentación clara y estructurada, especialmente en sus wikis.

Crear estas páginas a mano puede suponer horas leyendo código, entendiendo la arquitectura y organizando el contenido.

Un agente de IA para wikis de GitHub puede solucionar este problema.

En este tutorial, te guiaré paso a paso para crear un agente de IA para wikis de GitHub totalmente automatizado: una herramienta de línea de comandos que utiliza Claude Opus 4.5 y el Claude Agent SDK para generar wikis completos de repositorios de GitHub con una única instrucción. 

En lugar de escribir la documentación manualmente, esta herramienta analiza tu base de código, entiende su estructura y produce contenido limpio para un wiki multipágina que se confirma y publica automáticamente en tu repositorio. 

Todo se ejecuta desde una app CLI interactiva, pensada para ser rápida, inteligente y amigable para desarrolladores.

En esta guía seguiremos un proceso sencillo en tres pasos para preparar el entorno, construir el agente de wiki de GitHub y probarlo en repos reales:

1. Configura el entorno: instala dependencias, instala y autentica Claude Code, configura los tokens de GitHub y habilita la función de Wiki.
2. Crea la aplicación: construye la herramienta CLI, configura el agente de Claude, integra las herramientas MCP de GitHub, añade control de costes e implementa la lógica de generación del wiki (Home, Getting Started, Architecture & Tools).
3. Prueba el agente: ejecútalo en repos reales (ECom-Intel e Issue-Analyzer) para verificar el clonado, el análisis, la creación del wiki y el push automático.

Si estás empezando con agentes de IA y quieres aprender más, te recomiendo echar un vistazo al itinerario de aprendizaje AI Agent Fundamentals. También deberías leer nuestro tutorial sobre Claude Cowork y nuestra guía sobre el nuevo Claude Opus 4.6.

Configura tu entorno para el tutorial de GitHub Wiki con Claude Opus 4.5

Antes de crear el GitHub Wiki Agent con Opus 4.5, asegúrate de que tu entorno esté bien configurado. En esta sección verás todos los requisitos previos y los pasos de configuración.

1. Requisitos para ejecutar el Wiki Agent con Claude Opus 4.5

• Python 3.11 o superior (requerido por el Python Claude Agent SDK).
• Node.js y npm (necesarios para instalar Claude Code), que será la base de nuestra aplicación y proporciona agentes, herramientas e integraciones para servidores MCP.

2. Instala y autentica Claude Code

Abre tu terminal (Command Prompt, PowerShell o Terminal de macOS) y ejecuta el siguiente comando para instalar la CLI de Claude Code:

npm install -g @anthropic-ai/claude-code

Escribe claude en tu terminal para iniciar Claude Code. Luego, dentro del chat de Claude, escribe /login para autenticarte y acceder al modelo y a las herramientas de Opus 4.5, como se muestra a continuación.

Puedes aprender más sobre Claude Code en nuestro tutorial práctico. 

3. Genera un token de acceso personal de GitHub de granularidad fina

Para generar un token de acceso personal de GitHub de granularidad fina, ve a GitHub y navega a: 

Settings → Developer Settings → Personal Access Tokens → Fine-grained tokens. 

Crea un token nuevo y selecciona el repositorio que vas a usar en la sección Repository. Después, configura los permisos. Por seguridad, se recomienda establecer una caducidad corta para el token.

Luego, define el token de acceso personal como variable de entorno:

export GITHUB_PAT="your-github-personal-access-token"

4. Inicializa tu Wiki de GitHub

Actualmente GitHub no permite crear primero una Wiki de forma local.

Por tanto, debes inicializar la wiki manualmente:

1. Abre tu repositorio en GitHub
2. Haz clic en la pestaña Wiki
3. Haz clic en «Create the first page»
4. Guarda la página (cualquier título sirve)

5. Instala el Claude Agent SDK

Instalaremos el framework agentivo de Claude que gestiona todo: desde usar MCP hasta invocar herramientas, crear archivos y enviar cambios al remoto.

pip install claude-agent-sdk

Crea el Auto Wiki Agent con Claude Opus 4.5

Ahora crearemos una aplicación CLI en Python llamada gh_wiki_cli.py. Este archivo incluirá configuraciones, agentes, herramientas, un cliente MCP, prompts de sistema, la propia app CLI y funciones de ayuda. 

Estos componentes garantizan que puedas proporcionar el enlace del repositorio y que el agente sepa cómo manejarlo correctamente para publicar la wiki de GitHub.

1. Imports

Aquí importamos módulos de la librería estándar de Python, ayudas de tipado y el Claude Agent SDK.

• asyncio para E/S asíncrona (chat + streaming).
• os, sys para variables de entorno y salida del programa.
• dataclass para registrar estadísticas.
• Imports del Claude Agent SDK para hablar con el agente y con las herramientas MCP.

import asyncio
import os
import sys
from dataclasses import dataclass
from typing import Dict

# --- SDK Imports ---
from claude_agent_sdk import (
    AssistantMessage,
    ClaudeAgentOptions,
    ClaudeSDKClient,
    McpSdkServerConfig,
    ResultMessage,
    TextBlock,
    ToolResultBlock,
    ToolUseBlock,
)

2. Prompt del sistema

Este es el “cerebro” del agente. Indicaremos al modelo Opus 4.5 cómo debe comportarse y cómo usar las herramientas.

SYSTEM_PROMPT = """
        You are an expert Technical Writer and GitHub Wiki specialist.

        TOOLS
        - Read, Write, Glob, Grep:
        - Use these to inspect files and folders in the project directory (e.g. /tmp/Issue-Analyzer) and in wiki_clone/.
        - Use them to list files, read contents, and search for patterns.
        - Write:
        - Use this ONLY to write or update three wiki pages inside wiki_clone/:
            - wiki_clone/Home.md
            - wiki_clone/Getting-Started.md
            - wiki_clone/Architecture-and-Tools.md
        - Bash:
        - Bash is ONLY allowed for git commands, never for inspection or editing.
        - Allowed commands (with cd wiki_clone/ when needed):
            - git clone <repo>.wiki.git wiki_clone  (if wiki_clone does not already exist)
            - git status
            - git add .
            - git commit -m \"Update wiki\"
            - git push
        - Do NOT use Bash for ls, cat, grep, find, python, or any other way of reading/writing files.

        WORKFLOW
        1. When the user gives a GitHub repo URL:
        - Use Bash to clone the wiki if wiki_clone/ does not already exist:
            git clone <repo>.wiki.git wiki_clone
        2. Use Read/Glob/Grep (and any GitHub MCP tools) to explore the project:
        - Read important files in the project folder (e.g. README, docs/, src/).
        - Use that information to generate documentation.
        3. Use Write to create or update ONLY:
        - wiki_clone/Home.md
        - wiki_clone/Getting-Started.md
        - wiki_clone/Architecture-and-Tools.md
        4. When the wiki pages are ready:
        - Use Bash from wiki_clone/ to:
            git add .
            git commit -m \"Update wiki\"
            git push

        RULES
        - You may READ from the whole project directory and wiki_clone/.
        - You may WRITE only to the three wiki pages inside wiki_clone/.
        - Never use Bash to inspect or edit files; only use it for git commands.
        - Keep documentation clear, concise, and in GitHub Wiki style.
        """

3. Gestión de colores en la CLI

Mejora la salida de la CLI; si no está instalado colorama, el script sigue funcionando.

• Intenta usar colorama para texto coloreado.
• Si falla, usa MockColors para que el script siga corriendo (sin colores, sin caídas).

try:
    from colorama import Fore, Style, init

    init()
except ImportError:

    class MockColors:
        def __getattr__(self, name):
            return ""

    Fore = Style = MockColors()

4. Seguimiento de estadísticas de sesión

Una pequeña dataclass para controlar coste, turnos y duración.

• total_cost: suma del coste en $ reportado por el SDK de Claude.
• total_turns: cuántas consultas enviaste.
• duration_ms: duración acumulada en milisegundos.

@dataclass
class SessionStats:
    total_cost: float = 0.0
    total_turns: int = 0
    duration_ms: int = 0

5. Crear las opciones del agente

A continuación crearemos el objeto ClaudeAgentOptions y conectaremos nuestros servidores MCP. La función de abajo valida las variables de entorno requeridas, configura el servidor MCP de GitHub si está disponible y restringe las herramientas que puede usar el agente.

Restringimos deliberadamente allowed_tools para que Opus 4.5 pueda usar Bash en operaciones de Git, llamar al servidor MCP de GitHub para inspeccionar el contenido del repositorio y emplear Read/Write (junto con Glob y Grep) para trabajar y validar archivos Markdown locales.

def create_agent_options() -> ClaudeAgentOptions:
    """Validates env vars and configures the agent options."""
    anthropic_key = os.getenv("ANTHROPIC_API_KEY")
    github_pat = os.getenv("GITHUB_PAT")

    if not anthropic_key:
        print(
            f"{Fore.RED}Error: ANTHROPIC_API_KEY environment variable is required.{Style.RESET_ALL}"
        )
        sys.exit(1)

    # Configure MCP servers
    mcp_servers: Dict[str, McpSdkServerConfig] = {}
    if github_pat:
        mcp_servers["github"] = {
            "type": "http",
            "url": "https://api.githubcopilot.com/mcp/",
            "headers": {"Authorization": f"Bearer {github_pat}"},
        }

    return ClaudeAgentOptions(
        model="claude-opus-4-5",
        system_prompt=SYSTEM_PROMPT,
        mcp_servers=mcp_servers,
        permission_mode="bypassPermissions",
        allowed_tools=[
            "Read",
            "Write",
            "Glob",
            "Grep",
            "Bash",
            "mcp__github__*",
        ],
    )

6. Procesar la respuesta en streaming

Esta función escucha el stream e imprime texto, uso de herramientas y sus salidas.

• Usa client.receive_response() como stream asíncrono.
• Imprime el texto del asistente a medida que llega.
• Cuando se invoca una herramienta → imprime [Tool Use: ...].
• Cuando devuelve salida → la trunca e imprime una vista previa de una sola línea.
• Cuando llega un ResultMessage → actualiza SessionStats con coste y duración.

async def process_response_stream(client: ClaudeSDKClient, stats: SessionStats):
    """Handles the stream of messages from the agent."""
    async for message in client.receive_response():
        # 1. Handle Assistant Content (Text & Tool Requests)
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if isinstance(block, TextBlock):
                    print(block.text, end="", flush=True)
                elif isinstance(block, ToolUseBlock):
                    print(f"\n{Fore.CYAN}[Tool Use: {block.name}]{Style.RESET_ALL}")

        # 2. Handle Tool Results (Outputs)
        if hasattr(message, "content") and isinstance(message.content, list):
            for block in message.content:
                if isinstance(block, ToolResultBlock):
                    # Truncate output for cleaner CLI
                    raw_output = str(block.content)
                    clean_output = raw_output.replace("\n", " ")
                    short_output = (
                        clean_output[:200] + "..."
                        if len(clean_output) > 200
                        else clean_output
                    )
                    print(
                        f"{Fore.YELLOW}  -> [Output]: {short_output}{Style.RESET_ALL}"
                    )

        # 3. Handle Result Metrics (Cost & Usage)
        if isinstance(message, ResultMessage):
            if message.total_cost_usd:
                stats.total_cost += message.total_cost_usd
            if message.duration_ms:
                stats.duration_ms += message.duration_ms

7. Imprimir un resumen final

Estadísticas de fin de sesión para la CLI que muestran turnos, duración y coste en dólares.

• Convierte duration_ms a segundos.
• Muestra el coste total con 4 decimales.

def print_summary(stats: SessionStats):
    """Prints the final session statistics."""
    print(f"\n\n{Fore.GREEN}=== Session Summary ==={Style.RESET_ALL}")
    print(f"Total Turns:   {stats.total_turns}")
    print(f"Duration:      {stats.duration_ms / 1000:.2f}s")
    print(f"Total Cost:    ${stats.total_cost:.4f}")
    print(f"{Fore.GREEN}======================={Style.RESET_ALL}")

8. Función principal asíncrona

Es el flujo de control principal: gestiona la configuración, conecta servicios, lee la entrada del usuario y envía consultas. La función llama a create_agent_options() e inicializa las estadísticas. Imprime un banner de bienvenida e indica qué servidores MCP están activos. También crea un ClaudeSDKClient usando un contexto asíncrono.

La aplicación ejecuta un REPL sencillo (Read-Eval-Print Loop):

1. Escribe 'exit' o 'quit' para salir de la aplicación.
2. Cada consulta válida incrementa stats.total_turns en 1.
3. await client.query(user_input) envía el mensaje del usuario.
4. await process_response_stream(...) imprime el resultado en streaming.
5. Cualquier excepción se captura y se muestra en rojo.
6. Finalmente, la función siempre llama a print_summary(stats).

async def main():
    options = create_agent_options()
    stats = SessionStats()

    # Welcome message
    print(f"{Fore.GREEN}=== GitHub Wiki AI Agent (Auto-Mode) ==={Style.RESET_ALL}")
    print(
        f"MCP Servers: {', '.join(options.mcp_servers.keys()) if options.mcp_servers else 'None'}"
    )
    print("Ask me to help with a GitHub wiki by mentioning the repository URL!")
    print("Type 'exit' to quit.\n")

    async with ClaudeSDKClient(options=options) as client:
        try:
            await client.connect()

            while True:
                try:
                    user_input = input(f"\n{Fore.BLUE}>> {Style.RESET_ALL}").strip()
                except EOFError:
                    break

                if not user_input:
                    continue

                if user_input.lower() in ["exit", "quit"]:
                    break

                stats.total_turns += 1

                # Send query
                await client.query(user_input)
                print()  # Spacer

                # Process response stream using helper function
                await process_response_stream(client, stats)

        except Exception as e:
            print(f"\n{Fore.RED}Session Error: {e}{Style.RESET_ALL}")
        finally:
            print_summary(stats)

9. Punto de entrada del script

Por último, definimos el punto de entrada para que la CLI se ejecute cuando el archivo se lance directamente. El bloque siguiente inicia el bucle asíncrono principal y gestiona un cierre limpio:

if __name__ == "__main__":
    try:
        asyncio.run(main())
    except KeyboardInterrupt:
        print("\nSession interrupted.")
        sys.exit(0)

Prueba del Auto Wiki Agent

Cuando esté todo instalado, inicia la app de chat por CLI y asegúrate de que tu CLI de Claude Code funciona:

python gh_wiki_cli.py

Ahora puedes interactuar con el agente como en una interfaz de chat. Haz preguntas generales o pídele directamente que construya la wiki para tu repositorio:

create the github wiki for https://github.com/kingabzpro/ECom-Intel

Si el usuario pide crear una wiki, el agente realiza automáticamente:

1. Clonado de la wiki: crea o reutiliza la carpeta wiki_clone/ y descarga el contenido más reciente de la wiki.
2. Inspección del repositorio: lee archivos clave del repositorio de GitHub usando las herramientas MCP. 
3. Generación de páginas: redacta y escribe automáticamente páginas como:
• Home.md
• Getting-Started.md
• Architecture-and-Tools.md
4. Commit y push: el agente prepara las páginas nuevas, hace commit y envía las actualizaciones a: <your-repo>.wiki.git
5. Ejemplo de salida correcta: al finalizar, verás un mensaje de confirmación claro. Y la wiki estará disponible en: https://github.com/kingabzpro/ECom-Intel/wiki

Me sorprendió gratamente lo bien que el agente fue capaz de recopilar imágenes de demo, gráficos y otra información clave, y montar una página de inicio coherente para la wiki.

La wiki ahora incluye un índice adecuado, explicaciones del asistente y de las herramientas e instrucciones claras para empezar.

Al final de la ejecución, el resumen mostró que esta única sesión costó casi 1 USD, algo caro para generar una wiki de tres páginas. Si el repositorio fuera más grande y necesitáramos, por ejemplo, una wiki de 12 páginas, el coste escalaría notablemente.

=== Session Summary ===
Total Turns:   1
Duration:      282.99s
Total Cost:    $0.9047
=======================

En la segunda prueba, pedí al agente que creara una wiki para otro repositorio:

create the github wiki for https://github.com/kingabzpro/Issue-Analyzer

El resultado fue aún mejor. La wiki generada, disponible en https://github.com/kingabzpro/Issue-Analyzer/wiki, ahora contiene documentación en condiciones que explica qué hace el proyecto y cómo empezar. 

Incluye tablas bien estructuradas, un diagrama de arquitectura y otras secciones clave que te permiten comprender el proyecto en unos cinco minutos, en lugar de pasar días leyendo código.

Reflexiones finales

Cuando escuché que Opus 4.5 se presentaba como el mejor modelo del mundo para programación y agentes, me hizo mucha ilusión, sobre todo porque su precio es similar al de los modelos Sonnet. 

Sin embargo, el entusiasmo bajó cuando vi que experimentar y crear una aplicación pequeña acabó costando unos 15 USD en uso de la API.

Opus 4.5 es potente pero caro. También intenté replicar el mismo flujo con Haiku y Sonnet, pero la experiencia fue claramente inferior para este tipo de tarea agentiva y centrada en documentación. 

Ambos volvieron con frecuencia a usar herramientas de Bash, incluso cuando pedí explícitamente que emplearan herramientas MCP para leer archivos de GitHub. Además, a menudo tomaban caminos más largos y menos directos para resolver los problemas.

Si priorizas la precisión, la fiabilidad y una alta calidad en la generación de código y documentación, Opus 4.5 merece la pena. 

Pero si tu caso de uso no es crítico o tienes un presupuesto ajustado, quizá te convenga seguir con Sonnet o incluso con modelos open source más baratos. Los costes de Opus 4.5 pueden subir rápido, especialmente en flujos agentivos de varios pasos sobre repos grandes.

Si te interesa el proyecto, puedes encontrar el código fuente completo aquí, para clonarlo y ejecutarlo en local: kingabzpro/GitHub-Wiki-Agent.

Si tienes ganas de seguir construyendo agentes de IA, te recomiendo el curso Multi-Agent Systems with LangGraph.