🧰 Habilidades de IA (Skills)

Um pacote de instruções e processo que ensina o agente a fazer algo de um jeito específico.

É a unidade de reuso: você escreve uma vez e o agente repete certo.

Skill = conhecimento + processo empacotados.

Frontmatter (nome, descrição, flags) no topo; corpo com as instruções reais.

A descrição é o que o modelo vê para decidir invocar; o corpo é o que ele executa.

Descrição = gatilho; corpo = execução.

Skill que só roda quando você a chama explicitamente — você decide o quando.

Procedures não vazam descrição e mantêm você no controle do fluxo.

Procedure = invocação humana, processo fixo.

Skill que o próprio modelo decide acionar quando reconhece a situação na descrição.

Abilities automatizam, mas cobram contexto — a descrição fica sempre carregada.

Ability = invocação do modelo, autonomia.

A mesma skill pode ser exposta como procedure ou como ability — muda só o gatilho.

Escolher a porta certa equilibra controle, automação e custo de contexto.

Duas portas para o mesmo conteúdo.

Critério simples: você quer disparar manualmente (procedure) ou deixar o modelo reconhecer (ability)?

Evita pagar contexto por automação que você nem usa.

Controle → procedure; reconhecimento → ability.

Toda skill invocável pelo modelo vaza sua descrição no context window, mesmo sem ser usada.

O contexto é finito; cada descrição carregada custa espaço e atenção.

Descrição = imposto fixo de contexto.

Cem skills viram cem descrições competindo por espaço no contexto.

Acumular skills "por garantia" degrada o desempenho de todas.

Mais skills = mais ruído no contexto.

`disable model invocation: true` → a skill só roda quando você chama, sem vazar descrição.

Permite ter a skill disponível sem pagar o custo de contexto dela.

Procedure oculta = custo zero quando ociosa.

Saber quais skills você tem e quando chamá-las pode morar em você, não no contexto.

Você vira o índice vivo das skills, liberando o context window.

Memória humana > descrição carregada.

Skills curtas e diretas — descrição mínima, corpo focado — custam menos e disparam melhor.

Excesso de instrução entope o contexto e confunde o modelo.

Menos é mais em descrição e corpo.

Revisar periodicamente quais skills estão sempre carregadas e cortar as ociosas.

Auditoria mantém o contexto limpo e o desempenho alto.

Auditar → esconder → enxugar.

Skill stateless começa do zero toda vez; stateful guarda estado entre sessões.

Ensino que retém exige memória — sem estado, não há continuidade.

Estado = continuidade entre sessões.

Um arquivo que fixa a missão de aprendizado: o que você quer aprender e por quê.

Dá norte à skill — toda sessão sabe para onde está indo.

mission.md = alvo de aprendizagem persistente.

Registro do que você já aprendeu, acertou e errou ao longo das sessões.

Permite à skill adaptar o ritmo e revisar o que não fixou.

Histórico de aprendizado guia o próximo passo.

A skill gera lições em HTML — material navegável feito sob medida para você.

Conteúdo concreto e revisitável bate explicação efêmera no chat.

Lição como artefato durável.

O estado vive em arquivos locais — não depende do context window para lembrar.

Memória no disco sobrevive a resets e não cobra contexto.

Disco = memória barata e durável.

O padrão da Teach skill — missão + registro + lições + estado — serve a qualquer skill com memória.

Você pode recriar o conceito para suas próprias skills stateful.

Receita reutilizável de skill com estado.

A faixa entre o que você já sabe e o que ainda não consegue sozinho — onde o aprendizado acontece.

Ensinar dentro da ZDP mantém você desafiado sem frustrar.

ZDP = dificuldade calibrada.

Conhecimento é uma rede de conceitos com pré-requisitos, não uma lista linear.

Mapear o grafo revela o que ensinar antes do quê.

Nós = conceitos; arestas = pré-requisitos.

A skill escolhe um caminho linear pelo grafo: a ordem que respeita os pré-requisitos.

Sequenciar bem evita lacunas e sobrecarga.

Grafo → rota linear ensinável.

Perguntas que forçam recall ativo — lembrar custa esforço e por isso fixa.

Recall ativo retém muito mais que reler.

Testar-se > revisar passivamente.

Revisar em intervalos crescentes, na hora em que você quase esqueceria.

É o método mais eficiente para memória de longo prazo.

Espaçar revisões combate o esquecimento.

A skill ajusta ritmo, exemplos e revisões ao seu histórico individual.

Ensino adaptado retém mais que conteúdo genérico.

Adaptar ao aluno > tamanho único.

Uma skill que vira o jogo: o agente te entrevista, fazendo perguntas até entender o que você quer.

Extrai de você os detalhes que faltam antes que o código saia errado.

IA pergunta; você responde; entendimento sobe.

Pocock usa a grill-me no lugar do plan mode — entrevista antes de qualquer plano.

Um plano sobre suposições erradas é pior que nenhum plano.

Entrevistar > planejar no escuro.

A grill-me cabe em 4-5 frases — é minúscula e mesmo assim transforma o fluxo.

Prova que skill boa não precisa ser longa; precisa ser certeira.

Poder por foco, não por tamanho.

A entrevista alinha você e a IA sobre o objetivo antes que uma linha seja escrita.

Corrigir entendimento no início custa minutos; no fim, custa retrabalho.

Alinhar cedo é barato.

O resultado da grill-me é um entendimento compartilhado do problema entre você e o agente.

Entendimento comum é o que faz a delegação funcionar.

Mesma imagem do alvo dos dois lados.

Por ser tão curta, a grill-me é fácil de adaptar ao seu projeto e estilo.

Uma skill que você ajusta vira parte do seu harness pessoal.

Pequena = fácil de customizar.

Um pipeline: a grill-me extrai a visão, vira um PRD, que vira issues acionáveis.

Cada etapa entrega a próxima pronta — da ideia ao backlog sem fricção.

Entrevista → especificação → tarefas.

A saída de uma procedure alimenta a próxima — skills se encaixam como elos.

Encadear procedures dá fluxos confiáveis e repetíveis.

Procedures como elos de uma corrente.

Entre cada procedure do pipeline, você revisa e ajusta antes de seguir.

O humano nos pontos certos mantém o pipeline no rumo.

Checkpoints humanos entre etapas.

Se você deu as mesmas instruções 3 vezes, é hora de empacotá-las numa skill.

DRY (don't repeat yourself) vale para o seu próprio processo, não só para código.

Repetição = sinal de skill faltando.

Uma skill empacotada pode ser distribuída para todo o time usar do mesmo jeito.

Skills viram o conhecimento institucional executável da equipe.

Skill = processo compartilhável.

Skills úteis podem ser publicadas e melhoradas pela comunidade (mattpocock/skills, aihero.dev).

Você ganha das skills dos outros e devolve as suas.

Open source de skills compõe.