🔌 Module 3.3 — Integration with other agents

You write a skill for Claude Code. Works perfectly. Then your colleague uses Codex and asks: "how do I run this here?". Short answer: doesn’t run. Long answer: each agent has its own syntax — frontmatter, tool format, and permission system. Copying and pasting isn't enough.

The skill polyskill (present in the repo) solves the envelope problem. You write a single source and it emits builds specific to each runtime. Think of it as "Babel for 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

Practical advantage: you edit a paragraph in the single source, run polyskill build and both builds come out consistent. A production bug is a git diff, not a "which copy did I fix this in again?".

Before porting a skill, it's worth understanding where the two differ. Spoiler: on the surface they’re the same (Markdown + frontmatter); in the details, they’re quite different.

The practical rule: if your skill only reads files and writes markdown, it’s trivially portable. If it orchestrates parallel subagents with hooks, will need serious adaptation — it will probably become two skills.

Instead of asking the other agent to understand your skill format, wrap the skill in an MCP server. Any MCP client (Claude Code, Codex, Cursor, Cline) can call it as a tool without knowing there's a skill behind it.

// 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 as an API. Your skill /grill-me becomes an endpoint that any agent — or even your CI — can call via HTTP/MCP. Centralizes the logic and avoids duplication.

Skills don’t need to be interactive. In CI/CD, you run them in batch (non-interactive, with fixed input and output to a file). Useful for automatic PR reviews, docs generation, and migration validation.

Concrete scenario: when a PR breaks tests, automatically trigger the /tdd skill. It analyzes the error, proposes a fix, and opens a commit in the PR itself. The developer wakes up the next day to a green build.

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 and Continue don’t have the native skill concept. They have rules, conventions or system prompts. The good news: a skill’s content fits these formats perfectly.

// 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");

Limitation: agents without The skill concept loads the content all the time (with no dynamic activation). For short skills, that’s fine. For long skills, consider breaking them into smaller rules specific to each context.

The most powerful combination today: the skill orchestrates; the MCP server executes. The skill guides the model through the when e how; the MCP server provides specialized tools (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 is a work in progress. Some things already work well; others still depend on workarounds. An honest map of the landscape:

You’ve reached the end. A recap of the three tracks, one paragraph each—to reinforce the path you took.