writing-great-skills

Uma skill existe para arrancar determinismo de um sistema estocástico. Previsibilidade — o agent seguir o mesmo processo toda execução, não produzir o mesmo output — é a virtude raiz; todo mecanismo abaixo a serve.

Termos em negrito estão definidos em GLOSSARY.md; consulte lá para o significado completo.

Invocation

Duas escolhas, trocando custos diferentes:

• Uma skill model-invoked mantém uma description, de forma que o agent pode dispará-la autonomamente e outras skills podem alcançá-la (você ainda pode digitar o nome). Ela contribui para context load — a description fica na janela todo turno. Mecânica: omita disable-model-invocation, e escreva uma description voltada para model com rich trigger phrasing ("Use when the user wants…, mentions…").
• Uma skill user-invoked remove a description do alcance do agent: só você, digitando o nome, pode invocá-la — e nenhuma outra skill pode. Zero context load, mas gasta cognitive load: você é o índice que precisa lembrar que ela existe. Mecânica: defina disable-model-invocation: true; a description vira human-facing — um resumo de uma linha, listas de triggers removidas.

Escolha model-invocation só quando o agent precisa alcançar a skill por conta própria, ou outra skill precisa. Se ela só é disparada à mão, torne user-invoked e pague zero context load.

Quando skills user-invoked se multiplicam além do que você consegue lembrar, esse cognitive load acumulado é curado por uma router skill: uma skill user-invoked que nomeia as outras e quando recorrer a cada uma.

Escrevendo a description

Uma description model-invoked faz dois trabalhos — declara o que a skill é, e lista os branches que devem dispará-la. Cada palavra aumenta context load, então uma description merece poda ainda mais dura que o corpo:

• Front-load a leading word da skill — a description é onde ela faz seu trabalho de invocação.
• Um trigger por branch. Sinônimos que renomeiam um único branch são duplication — "build features using TDD … asks for test-first development" é um branch escrito duas vezes. Colapse; mantenha só branches genuinamente distintos.
• Corte identidade que já está no corpo. Mantenha a description só para triggers, mais qualquer cláusula de alcance "when another skill needs…".

Hierarquia de informação

Uma skill é construída de dois tipos de conteúdo — steps e reference — que se misturam livremente: uma skill pode ser só steps, só reference, ou ambos. A decisão central é qual usar e onde cada um senta na information hierarchy, uma escada ranqueada por quão imediatamente o agent precisa do material:

1. In-skill step — uma ação ordenada em SKILL.md, o tier primário: o que o agent faz, em ordem. Cada step termina em um completion criterion, a condição que diz ao agent que o trabalho está feito. Torne checkable (o agent consegue distinguir feito de não-feito?) e, onde importa, exhaustive ("todo model modificado contabilizado", não "produza uma change list") — um critério vago convida premature completion.
2. In-skill reference — uma definição, regra ou fato em SKILL.md, consultado sob demanda. Frequentemente um set plano legítimo (toda regra de uma review num mesmo degrau) — um arranjo fino, não um smell. Esta skill é toda reference.
3. External reference — reference empurrada para fora de SKILL.md para um arquivo separado, alcançado por um context pointer, carregado só quando o pointer dispara. (Vai de reference disclosed — um arquivo irmão como GLOSSARY.md, ainda parte da skill — até reference external que vive fora do sistema de skills e qualquer skill pode apontar.)

Um completion criterion exigente dirige legwork profundo — a escavação que o agent faz dentro do trabalho — quer a skill tenha steps ou não, já que "toda regra aplicada" vincula reference plana tanto quanto "todo step feito" vincula uma sequência.

Empurre pouco demais para baixo e o topo incha; empurre demais e você esconde material que o agent realmente precisa. Essa tensão é toda a decisão.

Progressive disclosure é o movimento descendo a escada — para fora de SKILL.md para um arquivo linkado — para o topo ficar legível. Mecânica: um arquivo .md linkado na pasta da skill, nomeado pelo que contém (esta skill divulga suas definições completas para GLOSSARY.md). Algumas skills são usadas de mais de uma forma, e cada forma distinta é um branch — execuções diferentes tomando caminhos diferentes pela skill. Branching é o teste mais limpo de disclosure: inline o que todo branch precisa, e empurre por trás de um pointer o que só alguns branches alcançam. O wording de um context pointer, não seu alvo, decide quando e quão confiavelmente o agent alcança o material.

Onde a escada decide quão longe uma peça senta, co-location decide o que senta ao lado uma vez lá: mantenha a definição de um conceito, regras e caveats sob um heading em vez de espalhados, para que ler uma parte traga seus vizinhos junto.

Quando dividir

Granularity é quão finamente você divide skills, e cada corte gasta uma das duas loads, então divida só quando o corte valer. Dois cortes:

• Por invocation — separe uma skill model-invoked quando você tem uma leading word distinta que deve dispará-la sozinha, ou outra skill precisa alcançá-la. Você paga context load pela nova description sempre-carregada, então esse alcance independente precisa valer a pena.
• Por sequência — separe uma sequência de steps quando os steps ainda à frente (os post-completion steps de um step) tentam o agent a apressar o que está na frente (premature completion). Mantê-los fora de vista encoraja o agent a fazer mais legwork na tarefa atual.

Pruning

Mantenha cada significado em uma single source of truth: um lugar autoritativo, para que mudar o comportamento seja uma edição em um só lugar.

Cheque cada linha por relevance: ela ainda impacta o que a skill faz?

Depois cace no-ops frase por frase, não só linha por linha: rode o no-op test em cada frase isoladamente, e quando uma falhar, delete a frase inteira em vez de aparar palavras dela. Seja agressivo — a maioria da prosa que falha deve ir, não ser reescrita.