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; adescriptionvira 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: