5.1 Agent Skills, dor e arquitetura polyskill

🎯O que você ganha aqui

Mapa mental completo do polyskill — por que existe, qual problema ataca, como funciona por dentro. Sem isso, o CLI da próxima aula vira "comandos decorados". Com isso, é arquitetura clara.

Conteúdo detalhado

📐 A spec aberta Agent Skills (agentskills.io)

Padrão originado na Anthropic e liberado como spec aberta. Hoje adotado por 40+ ferramentas. Define o formato canônico de skill: SKILL.md + frontmatter YAML + corpo markdown + convenção de pastas.

Os 4 pilares — o que TODOS os runtimes concordam

Nome do arquivo: SKILL.md — não inventar variações

Frontmatter YAML com no mínimo name e description

Corpo em markdown padrão

Pastas convencionadas: scripts/, references/, assets/

💡Por que isso importa

Tudo que você escreve dentro desses 4 pilares funciona em qualquer runtime compatível. Tudo FORA (allowed-tools, backtick-bang, openai.yaml, model override) vira amarra a um runtime específico — e aí mora o trabalho do polyskill.

Conceitos-chave

Spec aberta
agentskills.io

40+ runtimes
Adoção ampla

4 pilares
Núcleo portable

Extras = amarra
Fora dos 4 = runtime

😩 A dor — manter duas skills divergentes

Sem entender a dor, polyskill parece overkill. Esta é a história que TODO mundo que usa os dois runtimes vive:

Dia 1 — Cria skill no Claude

Funciona perfeito. Você está contente.

Dia 2 — Copia/adapta pro Codex

Move pra .agents/skills/, remove backtick-bang, ajusta description. Funciona nos dois. Você ainda está contente.

Semana 2 — Melhora a do Claude (esquece a do Codex)

Acha um caso de uso novo, adiciona instruções no Claude. Esquece de propagar.

Semana 3 — Melhora a do Codex (esquece a do Claude)

Estava no Codex, viu um bug, corrigiu. Esquece de levar pro Claude.

Mês 1 — Duas skills DIFERENTES

As versões divergiram em 4 pontos. Você não lembra qual está certa. Cada vez que você melhora uma, joga fora a melhoria da outra. Fonte de verdade ambígua.

💀Custos invisíveis do drift

• Tempo perdido decidindo "qual versão é a boa"
• Bugs voltam (você corrigiu numa versão, esqueceu na outra)
• Feature funciona num agente, não no outro
• Time fica confuso (skill se comporta diferente)
• Documentação fica desatualizada nos dois lados

Conceitos-chave

Drift orgânico
Inevitável sem tooling

Fork acidental
Versões divergentes

Source ambígua
Qual é a boa?

Custo cognitivo
Decisão constante

💡 A ideia central — uma source, vários alvos

Polyskill resolve a dor como um compilador resolve "código portável". Você escreve a skill UMA vez no formato canônico portable (definition.md). O polyskill compila pra dist/claude/ e dist/codex/, cada um otimizado pro runtime alvo.

Analogia direta — Babel/TypeScript

TypeScript:

source.ts → tsc → source.js (ES5) + source.js (ES2020)

Babel:

source.jsx → babel → source.js (target: ie11) + source.js (modern)

Polyskill:

definition.md → polyskill build → dist/claude/SKILL.md + dist/codex/SKILL.md

Mesma metáfora: source canônica, compilação seletiva por alvo, output otimizado.

Como fica a estrutura

minha-skill/
├── definition.md          ← SOURCE canônica (você edita aqui)
├── scripts/
├── references/
├── assets/
└── dist/                  ← OUTPUTS (gerados pelo polyskill build)
    ├── claude/
    │   └── minha-skill/
    │       └── SKILL.md  ← versão Claude (com allowed-tools, backtick-bang...)
    └── codex/
        └── minha-skill/
            ├── SKILL.md  ← versão Codex (sem bang, description front-loaded)
            └── agents/
                └── openai.yaml  ← sidecar gerado automaticamente

🎯O "aha moment"

Você nunca edita dist/. Só edita definition.md. Roda polyskill build. O dist/ reflete. Roda polyskill install. Os dois runtimes têm a versão fresca. Uma única fonte de verdade.

Conceitos-chave

Source canônica
definition.md

Compilação
polyskill build

dist/ gerada
Não editar à mão

Otimização/target
Por adapter

🧱 As 3 peças — IR, adapters, CLI

Por dentro, polyskill tem três peças. Entendendo isso, você vê que adicionar Gemini/Cursor/Copilot é UM arquivo — o adapter. Não rewrite.

🏛️

1. IR (Representação Interna)

Versão neutra de tudo que uma skill precisa ser, SEM amarração a runtime específico. É o esperanto do polyskill.

🔌

2. Adapters

Um arquivo TypeScript por runtime. Cada adapter implementa parse() + emit() + validate(). Plug → suporta. Remove → some.

⚡

3. CLI

O que você executa no terminal. Orquestra os adapters via registry. Não sabe de detalhes de runtime — pergunta pro adapter.

Arquitetura visual

┌──────────────────┐

│ definition.md │ ← VOCÊ edita

└────────┬─────────┘

│

▼

┌──────────────────┐ ┌─ portable adapter ─┐

│ Parse (portable)│ ──▶│ parse() / emit() │

└────────┬─────────┘ └────────────────────┘

│

▼

┌──────────────────┐

│ IR (neutral) │ ← representação interna

└────────┬─────────┘

│ split por target

├──────────────┬──────────────┐

▼ ▼ ▼

┌──────────────┐ ┌──────────────┐ ┌──────────────┐

│claude adapter│ │codex adapter │ │gemini adapter│ ← 1 arquivo cada

│ emit() │ │ emit() │ │ emit() │

└──────┬───────┘ └──────┬───────┘ └──────┬───────┘

▼ ▼ ▼

dist/claude/ dist/codex/ dist/gemini/

A interface Adapter

interface Adapter {
  name: string;

  // Lê o formato do runtime e devolve IR
  parse(path: string): IR;

  // Pega IR e escreve no formato do runtime
  emit(ir: IR, outputDir: string): void;

  // Roda regras específicas do runtime (lint)
  validate(ir: IR): ValidationResult;
}

// Registrar é literalmente uma linha:
register(new CodexAdapter());

🚀Por que isso escala

Quando Gemini CLI ganhar tração, alguém implementa src/adapters/gemini.ts com parse/emit/validate, registra no registry, abre PR. Polyskill ganha suporte ao Gemini sem mudar uma linha do core. Mesma coisa pra Cursor, Copilot, o-que-vier.

Conceitos-chave

IR neutra
Sem runtime amarra

parse+emit+validate
Contrato do adapter

Registry pattern
Plug-in dinâmico

Open core
Adapter via PR

🔁 Round-trip — Claude ↔ portable ↔ Codex

Adapter "lê E escreve". Você pode importar skill existente do Claude (--from claude), virar portable, daí emitir pros dois. Não precisa começar do zero.

Fluxos de round-trip

# Caso 1: começou no Claude, quer portable

~/.claude/skills/x/ ──▶ claude.parse() ──▶ IR ──▶ portable.emit() ──▶ ./x/definition.md

# Caso 2: começou no Codex, quer portable

~/.agents/skills/x/ ──▶ codex.parse() ──▶ IR ──▶ portable.emit() ──▶ ./x/definition.md

# Caso 3: tem portable, quer pros dois

./x/definition.md ──▶ portable.parse() ──▶ IR ──▶ claude.emit() + codex.emit()

Importação Claude → portable

$ polyskill import \
  ~/.claude/skills/x \
  --from claude

Lê SKILL.md + scripts + references. Gera definition.md preservando tudo.

Importação Codex → portable

$ polyskill import \
  ~/.agents/skills/x \
  --from codex

Lê SKILL.md + sidecar openai.yaml. Normaliza pra portable.

Lossless quando possível, lossy quando precisa

Round-trip preserva quase tudo:

✓ scripts/, references/, assets/ passam intactos nos dois sentidos
✓ Frontmatter portable (name, description) preserva
✓ Body markdown preserva

Coisas runtime-specific viram marcadores na IR:

⚠️ Backtick-bang do Claude → IR marca como "dynamic injection" → emit pro Codex vira prosa
⚠️ Sidecar openai.yaml do Codex → IR marca como "mcp deps" + "branding" → emit pro Claude vira allowed-tools

Conceitos-chave

Bidirecional
Lê E escreve

--from claude/codex
Flag de origem

Lossless dirs
scripts/refs/assets

Lossy semantic
Bang → prosa

🛡️ Drift policy — o seguro contra atropelar

Toda vez que faz build, polyskill calcula hash dos arquivos de output. No build seguinte, se algum arquivo de destino foi editado à mão fora do polyskill, o build ABORTA com erro. Você decide.

O fluxo de drift

polyskill build → gera dist/claude/x/SKILL.md, grava hash em .polyskill-hashes

Você edita à mão ~/.claude/skills/x/SKILL.md (ajuste específico)

Dias depois: polyskill build de novo

Polyskill compara hash: drift detectado. Aborta com mensagem clara.

Você escolhe: --force (sobrescreve, perde ajuste) OU polyskill reconcile (inspeciona, decide).

✓ Por que isso é seguro

• Nunca sobrescreve trabalho seu silenciosamente
• Drift é VISTO, não escondido
• Você sempre tem a opção de force OU reconcile
• Edição em produção fica detectável no próximo build

✗ Sem drift policy seria…

• Ajuste à mão sumiria no build seguinte
• Você nunca saberia (sem erro)
• Confiança no tool cairia
• Voltaria pra manutenção manual de qualquer jeito

Exemplo de output

$ polyskill build
✗ Drift detected!

The following targets have been modified outside polyskill:
  - ~/.claude/skills/x/SKILL.md (last hash: a3f9...; current: 8d2b...)

Options:
  - Run `polyskill build --force` to overwrite (loses local edits)
  - Run `polyskill reconcile` to inspect and merge

Build aborted.

Conceitos-chave

Hash file
.polyskill-hashes

No silent loss
Aborta antes

--force
Opt-in sobrescrever

reconcile
Merge interativo

🦜 A meta-skill — polyskill como skill

Detalhe poético: o polyskill se distribui usando ele mesmo. Vem como skill instalável nos dois runtimes. Você invoca em linguagem natural; a skill chama o CLI por baixo, traduzindo seu pedido em comandos.

🔷 Claude Code

/polyskill converte minha skill
y-compare pra funcionar nos dois
runtimes

Skill recebe NL, traduz pra:

$ polyskill import \
    ~/.claude/skills/y-compare \
    --from claude
$ polyskill build

🟣 Codex

$polyskill converte minha skill
y-compare pra funcionar nos dois
runtimes

Mesma skill, mesma tradução:

$ polyskill import \
    ~/.agents/skills/y-compare \
    --from codex
$ polyskill build

Caminhos de instalação — A vs B

Caminho A — drag & drop

Copia skill/dist/claude/polyskill pra ~/.claude/skills/ e skill/dist/codex/polyskill pra ~/.agents/skills/. Sem CLI. Só a meta-skill funciona; comandos que ela precisa rodar quebram.

Caminho B — source + CLI

Clona repo, npm install && npm run build && npm link. CLI completo no PATH. Pra construir suas próprias skills, B é obrigatório.

💡O dogfooding completo

Polyskill resolve o problema "skills cross-runtime" usando uma skill cross-runtime gerada por ele mesmo. Se a meta-skill funciona nos dois runtimes, o polyskill prova que serve. Se quebra num, é prova ao contrário. Honestidade arquitetural.

Conceitos-chave

Meta-skill
Polyskill como skill

NL interface
Sem decorar flag

Caminho A vs B
Sem CLI / com

Dogfooding
Usa o próprio tool

🎯Resumo do módulo

✓

Agent Skills é spec aberta com 4 pilares portáveis — SKILL.md, name+description, body markdown, dirs convencionados.

✓

Drift sem tooling é inevitável — uma semana basta pra divergir.

✓

Source canônica → targets compilados — analogia direta com Babel/TypeScript.

✓

3 peças: IR + Adapters + CLI — adicionar runtime é UM arquivo.

✓

Round-trip bidirecional — começa do Claude ou do Codex, vai pros dois.

✓

Drift policy = hash + reconcile — nunca sobrescreve silencioso.

✓

Meta-skill dogfoods polyskill — usa o próprio formato pra se distribuir.

Próximo módulo:

5.2 — CLI polyskill na prática (init, import, build, install, validate, reconcile)

← Voltar para Trilha 5 Próximo: 5.2 →