platform-skills

O repositório platform-skills ensina a cada agente de código como trabalhar no Airframe. Uma skill é um conjunto de instruções que um agente de código carrega quando sua tarefa corresponde: onde fica uma mudança, como o catálogo funciona, que forma têm as raízes de um produto, como as coisas são nomeadas, o que cada regra de política recusa e o que fazer no lugar. Cada skill vem com testes que as verificações reais da plataforma rodam, então uma skill que deixa de corresponder às regras falha aqui antes de confundir alguém.

Para que serve

Um agente de código que não conhece as regras da plataforma as aprende do jeito lento: escreve uma mudança, o pipeline a recusa, ele lê a mensagem e tenta de novo. As skills dão as regras a ele desde o início, então sua primeira tentativa costuma ser a correta. São as mesmas regras que uma pessoa lê nestas páginas, escritas para um agente de código agir sobre elas.

O que ele contém

Cinco skills, cada uma uma pasta com suas instruções, SKILL.md, e seus testes:

airframe-platform: como uma mudança vira infraestrutura, do airframe validate até a produção, e o que um agente de código nunca faz. É a que deve ser carregada primeiro.
airframe-catalog: os arquivos do catálogo, o que deriva deles, quem aprova o quê, e as mensagens das verificações do catálogo com suas correções.
airframe-infra: as raízes de um produto, os módulos do golden path, e o que os módulos não cobrem.
airframe-naming: como cada recurso, nome de host, rótulo e prefixo de estado é nomeado.
airframe-policies: cada regra de política, seu nível, sua mensagem como é impressa, e a alternativa correta.

Uma pessoa instala uma skill com um comando por skill, e as instruções para um agente de código do repositório de um produto apontam para elas. Há mais skills previstas, como uma para serviços e outra para pipelines, à medida que seus módulos e regras se assentam.

Como ele se conecta

Ele é testado contra o pacote de políticas. Os exemplos de uma skill são raízes de Terraform, arquivos de pipeline, Dockerfiles, entradas do catálogo e resumos de custo que o pacote de políticas, o terraform validate ou as verificações do catálogo precisam aceitar ou recusar, com a mensagem que a skill cita.
Ele fixa uma versão. Os testes rodam contra o pacote de políticas no commit do control-plane da versão que as skills fixam, e uma versão nova os roda de novo antes de ser permitida.
Ele nomeia caminhos reais. Um teste verifica se os caminhos de repositório listados no tests/references de uma skill existem na branch main desse repositório, então um arquivo movido quebra a skill aqui e não no trabalho de um agente de código.

Quem o muda, e como

As mudanças são merge requests aprovados pela equipe de plataforma, com a aprovação do controle obrigatória; este foi o primeiro repositório que o controle de aprovação passou a exigir, em 2026-09-28. O pipeline roda quatro jobs: skills:policy, skills:validate, skills:catalog e skills:references, e o GitLab só integra uma mudança quando eles passam.

Há dois limites que vale conhecer. Quatro das cinco skills trazem exemplos que esses jobs verificam; airframe-platform ainda não traz nenhum: só os caminhos que ela nomeia são verificados, não o que ela diz sobre o comportamento da plataforma. E se um agente de código carrega ou não uma skill depende do agente e de quem o usa: as verificações da plataforma valem do mesmo jeito.

O repositório não tem raízes e não custa nada parado.

Onde fica

No repositório platform-skills: