🔌 Módulo 3.3 — Integración con otros agentes

Escribes una skill para Claude Code. Funciona perfecto. Entonces tu colega usa Codex y pregunta: "¿cómo ejecuto esto aquí?". Respuesta breve: no se ejecuta. Respuesta larga: cada agente tiene su propia sintaxis: frontmatter, formato de tools, sistema de permisos. Copiar y pegar no basta.

La skill polyskill (presente en el repo) resuelve el problema del sobre. Escribes una fuente única y ella genera builds específicos para cada runtime. Piensa en "Babel para skills".

minha-skill/
├── source.md              # fonte única (neutra)
├── polyskill.config.json  # mapeamento de tools
├── claude-code/           # build pra Claude Code
│   └── SKILL.md           # frontmatter + Read/Edit/Bash
├── codex/                 # build pra Codex
│   └── skill.yaml         # frontmatter Codex + read_file/write_file
└── tests/
    └── snapshot.test.ts   # garante paridade entre builds

Ventaja práctica: ajustas un párrafo en la fuente única, ejecutas polyskill build y los dos builds salen coherentes. Un bug en producción es un git diff, no un "¿en qué copia lo corregí?".

Antes de portar una skill, conviene entender dónde los dos difieren. Adelanto: en la superficie son iguales (markdown + frontmatter), pero en los detalles son muy diferentes.

La regla práctica: si tu skill solo lee archivos y escribe markdown, es trivialmente portable. Si ella orquesta subagentes paralelos con hooks, va a necesitar una adaptación seria: probablemente se convierta en dos skills.

En vez de pedirle al otro agente que entienda tu formato de skill, envuelve la skill en un servidor MCP. Cualquier cliente MCP (Claude Code, Codex, Cursor, Cline) puede llamarla como tool sin saber que detrás hay una skill.

// mcp-skills-server/index.ts
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { readFileSync } from "fs";

const server = new Server({ name: "skills-bridge", version: "0.1.0" });

server.tool({
  name: "grill-me",
  description: "Stress-test a plan adversarially. Returns gaps and risks.",
  inputSchema: {
    type: "object",
    properties: { plan: { type: "string" } },
    required: ["plan"]
  },
  handler: async ({ plan }) => {
    const skillBody = readFileSync("./skills/grill-me/SKILL.md", "utf8");
    return runAgentLoop({ system: skillBody, user: plan });
  }
});

server.start();

Caso de uso: skills como API. Tu skill /grill-me se convierte en un endpoint que cualquier agente — o incluso tu CI — llama vía HTTP/MCP. Centraliza la lógica, evita la duplicación.

Las skills no tienen que ser interactivas. En CI/CD las ejecutas en modo batch (no interactivo, con entrada fija y salida en un archivo). Útil para la revisión automática de PR, la generación de docs y la validación de migrations.

Escenario concreto: cuando un PR rompa las pruebas, activa automáticamente la skill /tdd. Analiza el error, propone una solución y abre un commit en el propio PR. El desarrollador se despierta al día siguiente con el build en verde.

name: tdd-loop
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  run-tdd:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Run tests (capture failure)
        id: tests
        run: npm test || echo "failed=true" >> $GITHUB_OUTPUT

      - name: Run /tdd skill
        if: steps.tests.outputs.failed == 'true'
        uses: anthropics/claude-action@v1
        with:
          skill: tdd
          input: "fix failing tests in this PR"
          allowed-tools: "Read,Edit,Bash(npm test)"
          anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}

      - name: Commit fix
        if: steps.tests.outputs.failed == 'true'
        run: |
          git config user.name "tdd-bot"
          git config user.email "bot@example.com"
          git add -A
          git commit -m "fix: /tdd auto-repair" || exit 0
          git push

Cursor, Aider y Continue no tienen el concepto nativo de Skill. Tienen rules, conventions o prompts del sistema. La buena noticia: el contenido de una skill cabe perfectamente en estos formatos.

// scripts/sync-skills.ts
import { readFileSync, writeFileSync } from "fs";
import { stripFrontmatter } from "./utils";

const skill = readFileSync("./skills/tdd/SKILL.md", "utf8");
const body = stripFrontmatter(skill);

// Cursor
writeFileSync(".cursorrules", body);

// Aider
writeFileSync("CONVENTIONS.md", body);

// Continue
const config = JSON.parse(readFileSync(".continue/config.json", "utf8"));
config.systemMessage = body;
writeFileSync(".continue/config.json", JSON.stringify(config, null, 2));

console.log("✓ skill syncronized to Cursor / Aider / Continue");

Limitación: agentes sin El concepto de skill carga el contenido todo el tiempo (sin activación dinámica). Para las skills cortas, no hay problema. Para las skills largas, considera dividirlas en rules más pequeñas y específicas para cada contexto.

La composición más poderosa hoy: la skill orquesta; el servidor MCP ejecuta. La skill guía al modelo en el cuándo e como; el servidor MCP ofrece tools especializadas (DB, GitHub, Figma, Slack).

┌──────────────────────────────────────────────────────────┐
│                      USUÁRIO                              │
│                  "/release-notes v2.3"                    │
└────────────────────────┬─────────────────────────────────┘
                         │
                         ▼
┌──────────────────────────────────────────────────────────┐
│          SKILL: /release-notes (markdown + frontmatter)   │
│   "Quando o user pedir release notes:                     │
│    1. liste commits desde a última tag                    │
│    2. agrupe por tipo (feat/fix/chore)                    │
│    3. publique no Slack #releases"                        │
└──────┬───────────────────┬───────────────────┬───────────┘
       │                   │                   │
       ▼                   ▼                   ▼
┌──────────────┐   ┌───────────────┐   ┌──────────────┐
│ MCP: github  │   │ MCP: linear   │   │ MCP: slack   │
│ list-commits │   │ get-issues    │   │ post-message │
└──────────────┘   └───────────────┘   └──────────────┘

Entre entornos de ejecución es un trabajo en curso. Algunas cosas ya funcionan bien; otras todavía dependen de soluciones improvisadas. Mapa honesto del territorio:

Llegaste al final. Repaso de las tres rutas, un párrafo por cada una, para fijar el camino recorrido.