O Modelo de Skill do Agente
Uma skill de agente é um playbook estruturado, escrito como um arquivo SKILL.md, que diz a um assistente de IA exatamente o que fazer, o que pedir e o que nunca fazer em uma tarefa específica de banco de dados.
Esta página constrói o modelo mental por trás dessa estrutura para equipes do PostgreSQL 18.4: por que uma skill tem a aparência que tem, como suas partes interagem e onde ela para e o julgamento humano começa.
Resumo
- Uma skill é um contrato operacional com partes fixas - gatilho, entradas, guardrails, saídas - que restringe um agente a um domínio de decisão por vez.
- Por Que Importa: Sem um contrato, um agente recorre a suposições genéricas de dados de treinamento, o que rotineiramente significa sintaxe desatualizada e padrões inseguros em um cluster moderno e com versão fixada.
- Conceitos Chave: domínio de decisão, guardrails, pin da stack, saída verificável, composição de skills.
- Quando Usar: Alcance este modelo sempre que estiver decidindo se uma tarefa pertence a uma invocação de skill, um runbook humano ou uma conversa simples com o agente.
- Limitações / Trade-offs: Uma skill apenas codifica o que seus autores já aprenderam, portanto é um artefato atrasado que deve ser atualizado após cada incidente relevante ou mudança de política.
- Tópicos Relacionados: pontuação de segurança de migração, revisão de plano EXPLAIN, drills de failover, triagem de incidentes.
Fundamentos
Uma skill existe para responder a uma única pergunta restrita de forma eficaz, e essa restrição é deliberada em vez de uma limitação.
Cada arquivo SKILL.md nomeia um único domínio de decisão - pontuação de risco de bloqueio de migração, crítica de plano EXPLAIN, um drill de failover Patroni ou triagem de incidente SEV1 - e não tenta cobrir conhecimento geral de banco de dados.
O próprio arquivo é estruturado, não em prosa, com seções fixas: o que a skill faz, quando invocá-la, suas entradas necessárias, suas saídas esperadas e seus guardrails.
Guardrails são a seção que torna uma skill diferente de um tutorial, porque um tutorial ensina um humano a pensar enquanto um guardrail diz a um agente o que ele nunca está autorizado a fazer, independentemente do contexto.
Uma analogia útil é a lista de verificação de um piloto: ela não explica a aerodinâmica, ela restringe uma decisão específica e repetível a um procedimento conhecido como seguro toda vez que é executada.
As skills vivem ao lado do repositório da plataforma ou aplicação, tipicamente sob um caminho como .cursor/skills/ ou um registro em toda a organização, para que viajem com o codebase que governam.
Páginas de cookbooks humanos em outros lugares deste site, como as seções EXPLAIN e de migração, permanecem a fonte autoritativa de conhecimento de banco de dados; uma skill apenas orquestra como um agente deve aplicar esse conhecimento no momento.
Mecânicas e Interações
A razão pela qual as skills precisam de um pin da stack é que os dados de treinamento de um modelo de linguagem têm um corte, e o Postgres continuou avançando além dele.
Sem um pin explícito, um agente usará padrões mais antigos - SERIAL em vez de IDENTITY, ou um simples CREATE INDEX onde CONCURRENTLY é necessário - porque esses padrões dominaram sua distribuição de treinamento.
Fixar a stack dentro do próprio arquivo de skill, em vez de confiar que o agente a infira, transforma uma suposição implícita em uma restrição explícita e auditável que acompanha cada invocação.
Guardrails interagem com as saídas de uma maneira específica: uma skill bem formada nunca permite que um agente reivindique sucesso sem produzir algo que um humano possa verificar independentemente, como uma consulta de verificação de bloqueio ou um log de migração de staging.
Esta é a diferença entre um agente afirmar "a migração do índice é segura" e um agente produzir a consulta real pg_locks que um revisor pode reexecutar para confirmar essa afirmação.
As skills também compõem, o que significa que a saída de uma invocação pode se tornar o gatilho para a próxima: uma pontuação de risco de migração acima de um limite pode passar para uma revisão EXPLAIN da consulta que o novo índice deve servir.
O trecho abaixo mostra a forma desse contrato de passagem como pode aparecer dentro da seção Outputs de um arquivo de skill, mantido intencionalmente pequeno, já que o ponto é a forma, não o playbook completo.
## Outputs
- Pontuação de risco de bloqueio (baixo/médio/alto)
- Alternativa DDL mais segura, se aplicável
- Consulta de verificação que um humano pode reexecutar em staging
## Guardrails
- Nunca sugira índice não-CONCURRENT em uma tabela de produção ativa
- Nunca execute DDL sem aprovação humana explícitaEssa estrutura é o que permite a um revisor confiar na saída sem derivá-la do zero.
Considerações Avançadas e Aplicações
A escolha de design mais consequente em um arquivo de skill é o que pertence aos guardrails versus o que pertence à orientação, e equipes maduras tendem a escrever seus guardrails diretamente a partir de pós-mortens.
Cada incidente SEV1 ou SEV2 que remonta a uma ação sugerida pelo agente é um candidato para uma nova linha de guardrail, o que significa que a seção de guardrails é efetivamente o histórico acumulado de quase-acidentes de uma equipe em forma executável.
A autoridade de uma skill também é limitada pelo escopo: uma skill de segurança de migração nunca deve se expandir silenciosamente para conselhos de otimização de consulta, porque misturar domínios de decisão erode a estreiteza que tornou o contrato confiável em primeiro lugar.
A política de invocação da equipe importa tanto quanto o conteúdo do arquivo, já que uma skill que qualquer pessoa pode acionar contra a produção sem um aprovador humano nomeado derrota completamente o modelo de guardrail.
Em escala, as organizações mantêm um registro de skills - um índice que mapeia cada skill à sua condição de gatilho e a uma rotação proprietária - para que "quem eu pergunto" e "qual skill se aplica" sejam respondidos da mesma forma todas as vezes.
À medida que o próprio Postgres evolui através de versões principais, cada pin da stack da skill se torna um passivo de manutenção que precisa ser revisitado na mesma cadência do calendário de atualização do próprio cluster.
| Abordagem | Força | Fraqueza | Melhor Ajuste |
|---|---|---|---|
| Sem skill, prompt ad hoc | Mais rápido para começar, zero manutenção | O agente usa suposições de dados de treinamento desatualizados todas as vezes | Perguntas exploratórias únicas, não tarefas operacionais repetidas |
| Skill sem guardrails aplicados | Criação mais rápida, menor sobrecarga de revisão | Nada impede um agente de propor uma ação insegura | Tarefas somente leitura de baixo risco, como consultas de documentação |
| Contrato de skill completo (gatilho + entradas + guardrails + saídas verificáveis) | Reprodutível, auditável, seguro para entregar a operadores menos experientes | Requer autoria contínua e manutenção orientada por pós-mortem | Qualquer decisão recorrente de alto risco: migrações, failover, resposta a incidentes |
Conceitos Equivocados Comuns
- "Uma skill substitui o runbook humano em que se baseia" - uma skill orquestra como um agente deve agir, enquanto a página do cookbook humano à qual ela se refere permanece a explicação autoritativa do porquê.
- "Skills e regras sempre ativas são a mesma coisa" - uma regra é uma restrição constante como "sem DDL de produção no chat", enquanto uma skill é um playbook invocado com suas próprias entradas e saídas; equipes tipicamente precisam de ambos.
- "Uma vez escrita, uma skill permanece correta" - o pin da stack e os guardrails de uma skill ficam desatualizados no momento em que a versão subjacente do Postgres, o conjunto de extensões ou o histórico de incidentes ultrapassam o que o arquivo assume.
- "Um agente seguindo uma skill pode ser confiável para executar DDL de produção sem supervisão" - mesmo uma skill bem guardrailed tem suas saídas projetadas para verificação humana antes da execução, não para ação autônoma.
- "Mais skills sempre significam mais segurança" - um registro de skills sobreposto ou mal escopado cria confusão sobre qual playbook realmente se aplica, o que por si só se torna um novo modo de falha.
FAQs
O que exatamente é uma "skill de agente" no contexto do trabalho com Postgres?
Um arquivo SKILL.md estruturado que restringe um assistente de IA a um domínio de decisão - como segurança de migração ou revisão EXPLAIN - com entradas explícitas, guardrails e saídas verificáveis.
Como uma skill difere de apenas fazer uma boa pergunta ao agente?
- Uma skill é escrita uma vez e reutilizada, enquanto um prompt é escrito a cada vez.
- Os guardrails de uma skill se aplicam independentemente de como o prompt de invocação é formulado.
- As saídas de uma skill são estruturadas para verificação; uma resposta ad hoc geralmente não é.
Por que uma skill precisa fixar a versão do PostgreSQL explicitamente?
Porque os dados de treinamento de um modelo de linguagem são anteriores aos idiomas atuais e, sem um pin explícito, ele usará sintaxe mais antiga e padrões menos seguros do que um cluster moderno realmente precisa.
Qual é a seção mais importante de um arquivo de skill?
A seção de guardrails, pois ela codifica as ações específicas que uma equipe já aprendeu - muitas vezes através de um pós-mortem - que um agente nunca deve tomar.
As skills podem chamar outras skills?
Sim - um padrão comum é a saída de uma skill se tornar o gatilho para uma segunda skill, como uma pontuação de migração passando para uma revisão EXPLAIN da consulta afetada.
Uma skill substitui as páginas do cookbook humano neste site?
Não - as páginas humanas permanecem a explicação autoritativa do conceito subjacente, e a skill apenas governa como um agente aplica esse conceito em um momento específico.
O que acontece se duas skills parecerem se aplicar à mesma tarefa?
Essa sobreposição é em si um sinal de que o registro de skills precisa ser apertado, pois a ambiguidade sobre qual playbook se aplica mina todo o propósito de ter skills estreitas e nomeadas.
Uma skill deve permitir que um agente execute DDL em produção automaticamente?
Não - mesmo uma skill totalmente guardrailed é projetada para produzir uma proposta e etapas de verificação para um humano aprovar, não para executar alterações sem supervisão.
Como as equipes decidem quando um novo guardrail é necessário?
A maioria das equipes escreve uma nova linha de guardrail diretamente de cada pós-mortem, transformando um quase-acidente específico ou incidente em uma restrição permanente para invocações futuras.
Onde os arquivos SKILL.md devem ficar em um repo?
Tipicamente ao lado do código da plataforma ou aplicação que eles governam, como .cursor/skills/, para que o playbook viaje com o mesmo histórico de versão do schema sobre o qual opera.
O que é uma "saída verificável" e por que ela é tão importante?
É uma saída que um humano pode executar e confirmar independentemente, como uma consulta de verificação de bloqueio, em vez de uma simples afirmação de sucesso que deve ser aceita como fé.
Este modelo é específico para Postgres ou se aplica a qualquer banco de dados?
Os domínios de decisão específicos aqui são com sabor de Postgres, mas a forma do contrato - gatilho, entradas, guardrails, saídas verificáveis - é um padrão geral para qualquer tarefa operacional repetida e de alto risco.
Relacionados
- Noções Básicas de Skills de Agente - os dez exemplos concretos dos quais o modelo desta página se generaliza.
- Skill de Segurança de Migração - uma skill completa construída sobre esta forma de contrato.
- Skill de Revisão EXPLAIN - o domínio de decisão do plano de consulta na prática.
- Skill de Drill de Failover - o domínio de decisão de HA na prática.
- Skill de Triagem de Incidentes - o domínio de decisão SEV1 na prática.
- Noções Básicas de Migrações - o cookbook humano ao qual uma skill de migração recorre.
Versões da Stack: Esta página foi escrita para clusters PostgreSQL 18.4 usando Patroni 3.x para alta disponibilidade; versões específicas de migration-runner e backup-tool referenciadas por skills individuais são fixadas em suas próprias páginas.