🔌 Módulo 3.3 — Integração com outros agentes

Você escreve uma skill para o Claude Code. Funciona perfeito. Aí seu colega usa Codex e pergunta: "como rodo isso aqui?". Resposta curta: não roda. Resposta longa: cada agente tem sua sintaxe — frontmatter, formato de tools, sistema de permissões. Copiar e colar não basta.

A skill polyskill (presente no repo) resolve o problema do envelope. Você escreve uma fonte única e ela emite builds específicos pra cada runtime. Pense em "Babel pra 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

Vantagem prática: você ajusta um parágrafo na fonte única, roda polyskill build e os dois builds saem coerentes. Bug em produção é um git diff, não um "em qual cópia eu fixei isso mesmo?".

Antes de portar uma skill, vale entender onde os dois divergem. Spoiler: na superfície são iguais (markdown + frontmatter), no detalhe são bem diferentes.

A regra prática: se sua skill só lê arquivos e escreve markdown, ela é trivialmente portável. Se ela orquestra subagents paralelos com hooks, vai precisar de adaptação séria — provavelmente vira duas skills.

Em vez de pedir pro outro agente entender seu formato de skill, embrulhe a skill num MCP server. Qualquer cliente MCP (Claude Code, Codex, Cursor, Cline) pode chamar como tool, sem saber que por trás é uma 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();

Use case: skills como API. Sua skill /grill-me vira um endpoint que qualquer agente — ou até seu CI — chama via HTTP/MCP. Centraliza a lógica, evita duplicação.

Skills não precisam ser interativas. Em CI/CD você roda em modo batch (não-interativo, com input fixo, output em arquivo). Útil pra revisão automática de PR, geração de docs, validação de migrations.

Cenário concreto: quando um PR quebra testes, dispare a skill /tdd automaticamente. Ela analisa o erro, propõe um fix e abre um commit no próprio PR. O dev acorda no dia seguinte com o build 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 e Continue não têm o conceito de skill nativo. Eles têm rules, conventions ou system prompts. A boa notícia: o conteúdo de uma skill cabe perfeitamente nesses 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");

Limitação: agentes sem conceito de skill carregam o conteúdo o tempo todo (sem ativação dinâmica). Pra skills curtas, sem problema. Pra skills longas, considere quebrar em rules menores e específicas por contexto.

A composição mais poderosa hoje: skill orquestra, MCP server executa. A skill guia o modelo no quando e como; o MCP server entrega 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 │
└──────────────┘   └───────────────┘   └──────────────┘

Cross-runtime é um trabalho em andamento. Algumas coisas já funcionam bem; outras ainda dependem de gambiarra. Mapa honesto do território:

Você chegou ao fim. Recap das três trilhas, num parágrafo cada — pra fixar o caminho percorrido.