writing-great-skills

Quando Usar

Use quando este fluxo de trabalho corresponder à solicitação do usuário: Referência para habilidades de escrita e edição bem feitas — o vocabulário e os princípios que tornam uma habilidade previsível.

_Fonte: mattpocock/skills (MIT)._Uma habilidade existe para extrair determinismo de um sistema estocástico. Previsibilidade — o agente executando o mesmo processo a cada execução, não produzindo o mesmo resultado — é a virtude raiz; cada alavanca abaixo serve a ela.

Termos em negrito são definidos em GLOSSARY.md; procure-os lá para o significado completo.

Invocação

Duas escolhas, com custos diferentes:

• Uma habilidade invocada pelo modelo mantém uma descrição, para que o agente possa ativá-la autonomamente e outras habilidades possam acessá-la (você ainda pode digitar o nome dela também). Ela contribui para a carga de contexto — a descrição fica na janela a cada turno. Mecânica: omita disable-model-invocation e escreva uma descrição voltada para o modelo com frases de gatilho ricas ("Use quando o usuário quiser..., mencionar...").
• Uma habilidade invocada pelo usuário remove a descrição do alcance do agente: apenas você, digitando o nome dela, pode invocá-la — e nenhuma outra habilidade pode. Carga de contexto zero, mas gasta carga cognitiva: você é o índice que deve se lembrar de que ela existe. Mecânica: defina disable-model-invocation: true; o description se torna voltado para o humano — um resumo de uma linha, com listas de gatilhos removidas.

Escolha a invocação pelo modelo apenas quando o agente precisar acessar a habilidade por conta própria, ou quando outra habilidade precisar. Se ela for sempre ativada manualmente, torne-a invocada pelo usuário e não pague carga de contexto.

Quando as habilidades invocadas pelo usuário se multiplicam além do que você consegue lembrar, essa carga cognitiva acumulada é curada por uma habilidade roteadora: uma habilidade invocada pelo usuário que nomeia as outras e quando recorrer a cada uma.

Escrevendo a descrição

Uma descrição invocada pelo modelo cumpre duas funções — declara o que a habilidade é e lista os ramos que devem ativá-la. Cada palavra aumenta a carga de contexto, então uma descrição merece um corte ainda mais rigoroso do que o corpo:

• Coloque a palavra principal da habilidade no início — a descrição é onde ela realiza seu trabalho de invocação.
• Um gatilho por ramo. Sinônimos que renomeiam um único ramo são duplicação — "construir funcionalidades usando TDD... pede desenvolvimento test-first" é um ramo escrito duas vezes. Colapse-os; mantenha apenas ramos genuinamente distintos.
• Corte a identidade que já está no corpo. Mantenha a descrição para gatilhos, mais qualquer cláusula de acesso "quando outra habilidade precisar...".

Hierarquia de informações

Uma habilidade é construída a partir de dois tipos de conteúdo — passos e referência — que se misturam livremente: uma habilidade pode ser totalmente de passos, totalmente de referência, ou ambos. A decisão principal é qual usar e onde cada um se encaixa na hierarquia de informações, uma escada classificada pela imediatidade com que o agente precisa do material:

1. Passo na habilidade — uma ação ordenada em SKILL.md, o nível principal: o que o agente faz, em ordem. Cada passo termina em um critério de conclusão, a condição que informa ao agente que o trabalho está feito. Torne-o verificável (o agente consegue distinguir feito de não feito?) e, onde for importante, exaustivo ("todo modelo modificado contabilizado", não "produzir uma lista de alterações") — um critério vago convida à conclusão prematura.
2. Referência na habilidade — uma definição, regra ou fato em SKILL.md, consultado sob demanda. Frequentemente um conjunto plano legítimo (cada regra de uma revisão em um degrau) — um arranjo fino, não um problema. Esta habilidade é toda referência.
3. Referência externa — referência empurrada para fora de SKILL.md para um arquivo separado, acessada por um ponteiro de contexto, carregada apenas quando o ponteiro é ativado. (Abrange referência divulgada — um arquivo irmão como GLOSSARY.md, ainda parte da habilidade — através de referência totalmente externa que vive fora do sistema de habilidades e que qualquer habilidade pode apontar.)

Um critério de conclusão exigente impulsiona trabalho árduo — a escavação que o agente faz dentro do trabalho — quer a habilidade tenha passos ou não, pois "cada regra aplicada" vincula referência plana tanto quanto "cada passo concluído" vincula uma sequência.

Empurrar pouco para baixo faz o topo inchar; empurrar muito esconde material que o agente realmente precisa. Essa tensão é toda a decisão.

…