Busque em todas as páginas da documentação
Um assistente de codificação de IA já sabe como escrever uma rota FastAPI, adicionar type hints ou configurar uma tarefa Celery em geral - esse conhecimento veio de seu treinamento, não de sua equipe.
O que ele não sabe por padrão é qual versão do Python seus serviços realmente executam, se sua equipe padroniza os padrões da v2 do Pydantic ou ainda mantém código v1, quais campos de log são obrigatórios, ou qual atalho um incidente passado ensinou a todos a nunca mais usar. Uma Skill de Agente é como uma equipe codifica essa lacuna - as decisões específicas, locais e com versão fixada - em algo que um assistente pode receber no exato momento em que precisa delas, em vez de esperar que um prompt mencione tudo isso.
Esta página é o modelo por trás das páginas de skill individuais nesta seção - Skill de Especialista em FastAPI, Skill de pytest / Testes, Skill de Type-Hinting, Skill de Empacotamento e Publicação, e as outras parecem skills separadas, mas todas são construídas a partir das mesmas três partes descritas aqui.
SKILL.md - que limita o comportamento padrão de um assistente de IA às convenções específicas de uma equipe para uma tarefa recorrente em Python.Um domínio de decisão é o escopo que uma única skill possui - "estruturar um serviço FastAPI", "revisar um PR quanto à cobertura de type-hint", "empacotar uma biblioteca para PyPI", "construir um pipeline de dados" - e a primeira regra do modelo é que uma skill cobre exatamente um domínio. Uma skill que tenta cobrir tudo deixa de ser um contrato específico e se torna um prompt vago e de propósito geral com formatação extra, o que anula o propósito.
Uma skill é invocada em um trigger - um momento no trabalho onde sua orientação específica se aplica, em vez de ficar passivamente como leitura de fundo, como uma página de wiki faz. "Novo microsserviço no monorepo", "estamos padronizando type hints antes de um rollout do mypy", "este PR afeta o pipeline de treinamento" são todos triggers; a skill existe especificamente para ser acessada naquele momento, não para ser consultada com antecedência.
Uma analogia útil é um protocolo de laboratório entregue a um novo assistente de pesquisa em seu primeiro dia. Ele não o ensina novamente como Python ou estatística funcionam, ele já sabe disso. Ele lhe diz exatamente quais convenções se aplicam aqui: qual seed aleatório fixar, qual divisão de validação usar, qual atalho um experimento passado provou ser um erro. Essa é a diferença entre uma skill e um tutorial - um tutorial constrói conhecimento geral; uma skill aplica conhecimento específico e local no exato momento em que é necessário.
Cada skill é construída a partir de três partes, e um arquivo SKILL.md que falte qualquer uma delas está mais próximo de um documento do que de uma skill:
pyproject.toml, módulos de roteador, uma suíte de testes). Isso é o que torna a saída de uma skill verificável em vez de apenas parecer plausível. trigger reconhecido ──▶ skill carregada ──▶ guardrails aplicados ──▶ saída produzida
│ │ │ │
"novo serviço fixação de stack + "Apenas Pydantic v2, pyproject.toml,
FastAPI necessário" árvore de decisão nunca DB síncrono em roteadores, testes,
para este domínio rota assíncrona" cmds de verificação
A fixação de stack - as versões exatas de Python, framework e bibliotecas que uma skill assume - existe porque os dados de treinamento de um assistente abrangem anos de histórico de API, e sem uma fixação explícita, ele não tem como saber de forma confiável qual era de orientação está atual para seu codebase agora. A Skill de Especialista em FastAPI declara sua fixação (Python 3.14, FastAPI 0.115+, Pydantic 2) em seu cabeçalho por exatamente essa razão; uma skill sem uma está implicitamente confiando que o modelo adivinhe corretamente, o que ele muitas vezes não fará.
O lado da saída do contrato é tão importante quanto o lado da entrada: as saídas de skill nesta seção são obrigadas a terminar em comandos verificáveis - uv run pytest, ruff check, mypy ou pyright, um curl para uma rota de saúde - especificamente para que um humano não fique avaliando a confiança da prosa de um assistente, mas possa executar algo objetivo e ver se realmente passa.
Os guardrails de uma skill estreitam o espaço de erros prováveis, mas não substituem a revisão - o modelo que produz saída sob a orientação de uma skill ainda é o mesmo modelo subjacente, aplicando o mesmo processo de raciocínio, apenas com melhor contexto local para raciocinar. Tratar a saída de uma skill como pré-aprovada porque seguiu um contrato é um erro; o contrato existe para tornar a saída verificável, não para tornar a verificação opcional.
Skills também envelhecem, da mesma forma que qualquer artefato com versão fixada. Uma skill escrita contra Pydantic v1 e Python 3.10 torna-se ativamente enganosa assim que um codebase muda para Pydantic v2 e Python 3.14, não neutra, ativamente errada, porque ela aplicará confiantemente padrões desatualizados (.dict() em vez de model_dump(), sem correspondência de padrões estruturais) a uma stack mais nova.
Há uma dimensão de segurança real específica para skills que estruturam código: um guardrail como "nunca cometer segredos reais, apenas placeholders .env.example" só é valioso se for explícito, porque um assistente genérico solicitado a "adicionar configuração para uma conexão de banco de dados" não tem como saber que a convenção da sua organização é um gerenciador de segredos em vez de uma string de conexão literal em um arquivo.
A divisão do Python entre engenharia de aplicativos e trabalho de dados/ML adiciona uma complicação específica do domínio que outros ecossistemas lidam com menos frequência: uma skill com escopo para "construir um pipeline de dados" ou "treinar um modelo PyTorch" geralmente precisa de guardrails em torno da reprodutibilidade (seeds fixos, versões de dataset fixadas, hiperparâmetros registrados) para os quais uma skill de serviço web não tem equivalente, é por isso que esta seção mantém esses como domínios de decisão claramente separados em vez de uma skill genérica de "escrever Python".
Skills são deliberadamente posicionadas como uma camada acima da documentação humana existente, não uma substituição para ela - cada página de skill nesta seção afirma diretamente que as páginas correspondentes do cookbook humano (fastapi/, pytest/, packaging-publishing/) permanecem autoritativas, e o trabalho de uma skill é direcionar um assistente para a convenção correta no momento certo, não se tornar a nova fonte da verdade em si.
| Abordagem | Força | Fraqueza | Melhor Ajuste |
|---|---|---|---|
| Prompt bruto, sem skill | Rápido para começar, sem sobrecarga de manutenção | Tende a padrões de treinamento genéricos; convenções repetidas (ou esquecidas) a cada vez | Tarefas únicas, de baixo risco, sem convenção da casa para violar |
| Skill de Agente (este modelo) | Codifica convenções específicas e com versão fixada; reutilizável em toda a equipe | Requer autoria e manutenção à medida que a stack evolui | Tarefas recorrentes, com escopo de domínio de decisão, com custo real por errar os padrões |
| Autonomia total do agente, sem revisão humana | Loop de iteração mais rápido, sem gargalo humano | Nenhuma verificação objetiva da saída; guardrails sozinhos não pegam tudo | Raramente apropriado para alterações de produção em Python, mesmo a saída guiada por skill se beneficia da revisão |
Um contrato estruturado SKILL.md - triggers, entradas/saídas, guardrails e uma fixação de stack - que limita o comportamento de um assistente de IA às convenções específicas de uma equipe para uma tarefa recorrente em Python.
A documentação é escrita para um humano ler e internalizar ao longo do tempo; uma skill é escrita para ser invocada em um trigger específico e para produzir uma saída verificável. Uma skill sem triggers, um contrato de entrada/saída e guardrails é funcionalmente apenas um documento com formatação extra.
Você pode, mas não escala - convenções são esquecidas, formuladas de forma inconsistente ou omitidas sob pressão de tempo, e o assistente silenciosamente volta aos seus padrões genéricos de treinamento sempre que uma instrução específica está faltando. Uma skill existe precisamente para que esse contexto não dependa de alguém se lembrar de digitá-lo corretamente toda vez.
Triggers (quando invocá-la), um contrato de entrada/saída (o que ela precisa e o que ela produz) e guardrails (limites explícitos sobre o que ela nunca deve fazer). Um SKILL.md faltando qualquer um dos três está mais próximo de um documento passivo do que de uma skill invocável.
Porque os dados de treinamento de um assistente abrangem vários anos de histórico de Python e de frameworks, e sem uma fixação explícita, ele não tem como saber de forma confiável qual era de orientação se aplica atualmente ao seu codebase; a fixação remove essa ambiguidade completamente.
É o escopo específico que uma skill possui: scaffolding, testes, empacotamento, pipelines de dados. Limitar uma skill a um domínio mantém seus triggers e guardrails específicos e verificáveis; uma skill que tenta cobrir tudo se degrada em um prompt geral vago.
Não, os guardrails de uma skill reduzem a probabilidade de um padrão incorreto, mas a saída ainda precisa passar pelas mesmas verificações objetivas (pytest, ruff, mypy) e pela mesma revisão humana que qualquer outra alteração. As saídas de skill são explicitamente exigidas para terminar em comandos verificáveis por esse motivo.
Sim, uma skill de pipeline ou treinamento de modelo normalmente protege a reprodutibilidade (seeds fixos, versões de dataset fixadas, hiperparâmetros registrados), enquanto uma skill de serviço web protege coisas como correção assíncrona e gerenciamento de segredos. Manter esses como domínios de decisão separados é deliberado.
Um assistente de codificação de IA, no momento em que sua condição de trigger é reconhecida, seja porque um humano o invocou explicitamente ou porque a ferramenta do assistente corresponde à tarefa atual a um trigger de skill conhecido.
Sim, e argumentavelmente mais rápido, porque uma skill desatualizada não apenas se torna obsoleta, mas aplica ativamente e confiantemente guardrails e fixações de versão antigas a uma stack mais nova, o que é pior do que nenhuma orientação.
Não deveria por design, skills são destinadas a direcionar e reforçar a documentação humana autoritativa, não a divergir dela. Uma skill que sai de sincronia com suas páginas de cookbook referenciadas é um sinal de que a própria skill precisa ser atualizada.
Não, um guardrail é uma instrução que molda o que o assistente deve evitar fazer ao produzir saída; um teste é uma verificação objetiva e automatizada executada na saída posteriormente. Guardrails reduzem a frequência com que um teste precisa pegar algo em primeiro lugar, mas não substituem a execução dele.
Uma tarefa única sem convenção repetida para codificar e sem custo real se o padrão genérico do assistente for usado; escrever uma skill para algo que só ocorrerá uma vez é sobrecarga pura sem retorno.
Versões da Stack: Esta página foi escrita para Python 3.14.0 (stable 3.14, maintenance 3.13), FastAPI 0.115+, Pydantic 2, e ruff 0.9+.
Revisado por Chris St. John·Última atualização: 15 de jul. de 2026