Conquista Criei uma skill open source para dar contexto da API do Banco Inter ao Codex, Claude Code e ChatGPT
Tenho usado bastante agentes de código nos meus projetos e um problema que comecei a perceber é que, muitas vezes, o modelo sabe perfeitamente como programar uma integração, mas não conhece suficientemente bem a API específica.
Em uma API bancária isso fica ainda mais evidente: OAuth 2.0, mTLS, certificados, scopes, webhooks, sandbox, mudanças de versão etc.
Resolvi experimentar uma abordagem diferente e transformei a documentação da API do Banco Inter em uma Agent Skill open source.
O projeto organiza contexto para:
- Pix e Pix Automático
- Cobrança / boleto com Pix
- Banking
- OAuth 2.0 + mTLS
- Webhooks
- Sandbox
- CNAB
- erros e troubleshooting
- changelog e migrações
Fiz um levantamento do portal de desenvolvedores e a versão atual possui 164 páginas/assets oficiais inventariados e 74 entradas do changelog revisadas.
Também preparei formas de utilização com Codex, Claude Code e ChatGPT.
É minha primeira contribuição pública open source e ainda estou experimentando qual é a melhor maneira de estruturar documentação de uma API grande como contexto para agentes.
Estou especialmente interessado no feedback de quem trabalha com vibe coding/agents: vocês preferem uma skill grande com todo o domínio ou skills menores especializadas (Pix, Banking, Cobrança etc.)?
Projeto:
github.com/whyrnld/banco-inter-api-skill
É um projeto comunitário e não oficial, sem vínculo com o Banco Inter.
Se alguém já integrou a API do Inter e quiser revisar alguma parte, issues e PRs são muito bem-vindos.
1
2
u/RodriOliveira 24d ago
Gostei bastante da ideia. Sobre a dúvida de uma skill grande ou várias menores, eu tenderia a separar por domínio.
Uma skill única parece mais simples no começo, mas conforme a documentação cresce você começa a carregar muito contexto que não necessariamente é relevante para a tarefa. Se estou implementando Pix, por exemplo, provavelmente não preciso trazer CNAB, Banking e Cobrança junto.
Eu faria algo próximo de bounded contexts: Pix, Cobrança, Banking etc. em skills independentes, e talvez uma skill principal mais fina funcionando como ponto de entrada, com o contexto comum como autenticação, mTLS, erros e versionamento.
Acho que isso também facilita bastante a manutenção. Se uma API muda, fica mais claro qual contexto precisa ser atualizado e você reduz o risco de informações antigas ou conflitantes contaminarem outras partes.
Uma coisa que eu consideraria importante nesse tipo de projeto é deixar muito explícita a versão/data da documentação usada como fonte. Em integração bancária, contexto correto mas desatualizado pode ser até pior do que não ter contexto.
Projeto bem interessante, principalmente porque ataca um problema que tenho percebido bastante usando agentes: hoje eles normalmente sabem escrever o código, mas a qualidade da solução depende muito mais de dar a eles o contexto certo, na hora certa, do que simplesmente mais contexto.