🔄 Portabilidade Cross-Platform

Assim como o Java prometeu "write once, run anywhere" para codigo, o padrao Agent Skills promete o mesmo para instrucoes de agentes AI. A ideia e que voce invista tempo criando uma skill de qualidade que funcione em qualquer plataforma que adote o padrao.

Na pratica, portabilidade total ainda requer algum trabalho de adaptacao. Mas o investimento compensa: em vez de manter 3-4 arquivos de instrucao diferentes, voce mantem um SKILL.md central e gera os formatos especificos quando necessario.

Para suportar todas as plataformas simultaneamente, organize seu repositorio com diretorios dedicados para cada agente, alem do SKILL.md universal na raiz. Esta e a estrutura recomendada para maximo alcance.

meu-projeto/
│
├── SKILL.md                    # Fonte de verdade (universal)
│
├── AGENTS.md                   # Para GitHub Copilot + OpenAI Codex
│
├── .github/
│   └── copilot/
│       └── instructions.md    # Copilot repo-level (opcional)
│
├── .cursor/
│   └── rules/
│       └── main.mdc           # Para Cursor (.mdc format)
│
├── .agents/
│   └── skills/
│       └── coding.md          # Para OpenAI Codex
│
├── .claude/
│   └── settings.json          # Config Claude Code (se necessario)
│
└── src/
    └── AGENTS.md              # Instrucoes especificas para /src

Testar se uma skill funciona corretamente em diferentes agentes e essencial antes de publicar. Cada plataforma interpreta instrucoes de forma ligeiramente diferente, e o que funciona perfeitamente no Claude Code pode ter nuances no Copilot.

Marketplaces de skills sao plataformas para descobrir, compartilhar e distribuir skills universais. Eles criam um ecossistema onde desenvolvedores podem aproveitar o trabalho da comunidade em vez de criar tudo do zero.

O agent-skills-cli e uma ferramenta de linha de comando para gerenciar o ciclo de vida completo de skills: criar, validar, converter entre formatos e publicar em marketplaces.

# Instalar
npm install -g agent-skills-cli

# Criar nova skill interativamente
agent-skills init

# Validar SKILL.md
agent-skills validate ./SKILL.md

# Converter SKILL.md para outros formatos
agent-skills convert ./SKILL.md --to agents.md
agent-skills convert ./SKILL.md --to cursorrules
agent-skills convert ./SKILL.md --to mdc

# Gerar todos os formatos de uma vez
agent-skills sync ./SKILL.md

# Publicar no marketplace
agent-skills publish ./SKILL.md

# Buscar skills no marketplace
agent-skills search "react typescript"

# Instalar skill do marketplace
agent-skills install @community/nextjs-expert

Vamos colocar tudo em pratica com um guia passo-a-passo completo para criar, testar e publicar sua primeira skill universal que funciona em todas as plataformas.

# 1. Inicializar skill
npx agent-skills-cli init
# Responda: name, description, globs, tags

# 2. Editar conteudo
# Abra SKILL.md e adicione suas instrucoes

# 3. Validar
npx agent-skills-cli validate ./SKILL.md

# 4. Gerar formatos para todas plataformas
npx agent-skills-cli sync ./SKILL.md

# 5. Testar localmente
# Abra projeto no Claude Code, Copilot, Cursor
# Valide que comportamento e consistente

# 6. Commitar e publicar
git add SKILL.md AGENTS.md .cursor/rules/main.mdc
git commit -m "feat: add universal coding skill"
git push

# 7. (Opcional) Publicar no marketplace
npx agent-skills-cli publish ./SKILL.md

---
name: fullstack-typescript
description: |
  Fullstack TypeScript expert. Use quando trabalhando com
  projetos TypeScript que incluem frontend React e backend Node.
version: 1.0.0
globs:
  - "**/*.ts"
  - "**/*.tsx"
alwaysApply: false
tags:
  - typescript
  - react
  - nodejs
  - fullstack
---

# Fullstack TypeScript Expert

Voce e um especialista em TypeScript fullstack.

## Principios
- TypeScript strict mode em todo codigo
- Functional programming quando possivel
- Testes para toda logica de negocio
- Error handling explicito (never throw untyped)

## Frontend (React)
- Server Components por padrao
- Client Components com "use client" apenas se necessario
- Zod para validacao de forms
- TanStack Query para data fetching

## Backend (Node.js)
- Express ou Fastify para APIs
- Prisma para ORM
- Zod para validacao de input
- Structured logging com pino

## Testes
- Vitest para unit tests
- Playwright para E2E
- Minimo 80% coverage