writing-great-skills
Skill0 starsChanged 50 days agoMITView on GitHub
Referência p/ escrever e editar skills bem — o vocabulário e princípios que tornam uma skill previsível. Chame ao criar/revisar SKILL.md, decidir invocação model vs user, ou diagnosticar skill que não dispara/derrapa.
104 other projects use a version of this.
Adopted by
Most recently taken up by
- Kcalb0708/claude_skillstheir own version, first seen Nov 16, 2026
- richard12511/claude-skillstheir own version, first seen Nov 16, 2026
- lhotwll217/owner-operatortheir own version, first seen Nov 16, 2026
- sgaabdu4/appwrite-backendtheir own version, first seen Nov 13, 2026
- matheus3006/my-claude-skillstheir own version, first seen Nov 8, 2026
- LeonardiFranco/skillstheir own version, first seen Nov 8, 2026
Used with
Projects with it also use decision-mapping, batch-grill-me and 8 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
FabienDehopreSkilldecision-mapping
Turn a loose idea into a sequenced map of investigation tickets, then drive them to resolution one at a time.
Also in 7 projects that use this
boyingliu01Skillbatch-grill-me
A relentless interview that asks every frontier question at once, round by round. Thin alias of `grilling` (#540) — upstream mattpocock/skills absorbed this protocol into grilling; XP-Gate keeps this name as the sprint-flow Phase 2 entry point so orchestration docs stay stable.
Also in 7 projects that use this
simo97Skilledit-article
The user will invoke this skill to help them edit an article.
Also in 18 projects that use this
simo97Skillrequest-refactor-plan
Use this skill when user wants to create a refactor plan.
Also in 17 projects that use this
RoentekSkillloop-me
Grill me about specs for the workflows I want to build, within this workspace.
Also in 19 projects that use this
LesaniSkillwriting-beats
Shape an article as a journey of beats, choose-your-own-adventure style. The user picks a starting beat from the raw material, you write only that beat, then offer options for where to pivot next, beat by beat, until the article reaches a natural end. Use when the user has raw material and wants to assemble it as a narrative rather than an argument.
Also in 19 projects that use this
- +3 more from simo97
Other versions104 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 104
- GreyDGL/PentestGPT★ 16ksame name
- Akylas/OSS-DocumentScanner★ 2.6ksame name
- Aniket-508/termcn★ 1.2ksame name
- stevesolun/ctx★ 583same name
- aws/graph-explorer★ 492same name
- Akylas/oss-weather★ 478same name
- sveltejs/ai-tools★ 337same name
- sveltejs/mcp★ 337same name
- ninehills/skills★ 280same name
- loulanyue/skills★ 231same name
94 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository12 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- content-design-reviewSkill
- content-designSkill
- councilSkill
- debateSkill
- diagnoseSkill
- grill-meSkill
- office-hoursSkill
- pre-mortemSkill
- traceSkill
- writing-fragmentsSkill
- writing-shapeSkill
The file
Files
Skill: Writing Great Skills
Skill existe p/ arrancar determinismo de sistema estocástico. Previsibilidade — o agente tomar o mesmo processo toda run, não produzir o mesmo output — é a virtude-raiz; toda alavanca abaixo serve a ela.
É a referência de qualidade da forma-skill. Complementa a skill
content-design(front-load de artefato).
Invocação — 2 escolhas, custos diferentes
- Model-invoked: mantém description → agente dispara autônomo E outras skills alcançam. Custa context load (description no contexto todo turno). Mecânica: omitir
disable-model-invocation, description rica em triggers ("Use quando o user…, menciona…"). - User-invoked: tira description do alcance do agente — só você, digitando o nome, invoca. Zero context load, mas gasta cognitive load (você é o índice que lembra que existe). Mecânica:
disable-model-invocation: true; description vira humana (resumo 1 linha, triggers removidos).
Escolha model só quando o agente precisa alcançar sozinho, ou outra skill precisa. Se só dispara à mão → user-invoked, zero context load. Quando user-invoked multiplicam além do que você lembra, essa cognitive load acumulada cura-se com router skill (uma user-invoked que nomeia as outras).
Escrevendo a description
Faz 2 jobs — dizer o que a skill é, e listar os branches que a disparam. Cada palavra aumenta context load → poda mais dura que o corpo:
- Front-load a leading word — a description é onde ela faz o trabalho de invocação.
- Um trigger por branch. Sinônimos que renomeiam um branch = duplicação. Colapse; só branches genuinamente distintos.
- Corte identidade que já está no corpo. Só triggers + cláusula "quando outra skill precisa…".
Trigger metadata (OpenHands)
Description é prosa; o dispatch fica mais confiável quando os triggers são explícitos e escopados, como microagent OpenHands. Três campos no frontmatter, além da description:
trigger(keywords, não frase) — lista de palavras-gatilho literais que o agente casa, não parágrafo em prosa. Prosa infla context load e dispara fuzzy; keyword casa determinística. Um keyword por branch (mesma regra da description).- Escopo — global vs project — microagent OpenHands é knowledge (sempre no alcance) ou repo (só naquele repo). Espelhe: skill de domínio declara escopo via
tags:→ não polui context fora do domínio. Sem escopo = global = paga context load toda sessão. Declare escopo estreito por padrão. - Anti-trigger (
negative) — diga quando NÃO disparar. Sem isso, keyword genérico ("revisar") canibaliza turnos vizinhos. Um anti-trigger corta o falso-positivo mais provável (ex: negative "single technical question").
Hierarquia de informação
Skill = steps + reference, misturam livre. Escada por urgência:
- In-skill step — ação ordenada no SKILL.md, tier primário. Cada step fecha num completion criterion checável (dá p/ saber done de não-done?) e, onde importa, exaustivo ("todo model modificado contabilizado", não "produza lista"). Critério vago convida premature completion.
- In-skill reference — definição/regra/fato consultado sob demanda. Muitas vezes peer-set legitimamente flat (toda regra numa mesma rung).
- External reference — reference empurrado p/ arquivo separado, alcançado por context pointer, carregado só quando o pointer dispara.
Empurra pouco → topo incha; empurra demais → esconde o que o agente precisa. Essa tensão é a decisão inteira. Progressive disclosure = o movimento escada abaixo (p/ arquivo linkado) p/ o topo ficar legível. Branch é o teste mais limpo: inline o que todo branch precisa, esconde atrás de pointer o que só alguns alcançam. A redação do pointer, não o alvo, decide quando/quão confiável o agente alcança. Co-location: mantenha definição, regras e caveats de um conceito sob um heading, não espalhados.
Quando dividir (granularity)
Cada corte gasta uma das 2 loads → divida só quando compensa.
- Por invocação — separe skill model-invoked quando há leading word distinta que deve dispará-la, ou outra skill precisa alcançar. Paga context load da description sempre-carregada.
- Por sequência — divida run de steps quando os steps à frente tentam o agente a apressar o da frente (premature completion). Escondê-los força mais legwork na tarefa atual.
Poda
- Single source of truth: cada significado num lugar autoritativo — mudar comportamento = edit de um lugar.
- Relevance: cada linha ainda pesa no que a skill faz?
- No-ops frase a frase: rode o no-op test em cada frase isolada; falhou → delete a frase inteira, não apare palavras. Seja agressivo.
Leading words
Conceito compacto já vivo no pretraining que o agente pensa-com ao rodar a skill (ex: lesson, fog of war, tracer bullets, tight, red). Repetido, acumula definição distribuída e ancora uma região de comportamento em pouquíssimos tokens, recrutando priors que o modelo já tem. Serve previsibilidade 2×: no corpo ancora execução (mesmo comportamento toda vez que a palavra aparece); na description ancora invocação (linguagem compartilhada em prompts/docs/código → dispara mais confiável). Cace refactor: "fast, deterministic, low-overhead" → tight; "loop em que você acredita" → red (gate fuzzy vira estado binário observável). Ganha 2×: menos tokens E hook mais afiado.
Failure modes (diagnóstico)
- Premature completion — fecha step antes de done, atenção escorrega p/ estar done. Defesa em ordem: afiar completion criterion (barato); só se irredutivelmente fuzzy E você observa a pressa, esconda post-completion steps dividindo.
- Duplication — mesmo significado em >1 lugar. Custa manutenção, tokens, e infla a proeminência do significado na escada.
- Sediment — camadas velhas que assentam porque adicionar parece seguro e remover parece arriscado. Destino default sem disciplina de poda.
- Sprawl — skill longa demais mesmo com toda linha viva. Cura = a escada (disclose reference atrás de pointer, divida por branch/sequência).
- No-op — linha que o modelo já obedece por default. Teste: muda comportamento vs default? Leading word fraca (seja thorough quando já é) é no-op; conserto = palavra mais forte (relentless), não outra técnica.
Exemplo
Input (description crua, submetida a review):
description: "Esta skill ajuda o usuário a escrever testes. Ela é muito útil e
thorough. Use quando precisar de testes, criar testes, gerar testes unitários,
escrever testes, ou testar código."Diagnóstico aplicando os princípios:
- "Esta skill ajuda o usuário a escrever testes" → identidade que repete no corpo → cortar.
- "muito útil e thorough" → no-op (o modelo já tenta ser útil) → deletar.
- "criar testes / gerar testes / escrever testes / testar código" → sinônimos do mesmo branch → duplication, colapsar em um.
- Falta leading word front-loaded.
Output (podado, um trigger por branch, leading word na frente):
description: "Write fast, isolated unit tests. Use quando o user pede testes de
uma função nova, ou pede cobertura para código sem testes."Completion
- Invocação escolhida (model vs user) pelo custo certo (context vs cognitive load)
- Description front-load leading word, um trigger por branch, sem identidade duplicada do corpo
- Steps com completion criterion checável; reference disclosed onde incha
- Podado: single source of truth, relevance, no-ops deletados frase a frase
- Leading words caçadas onde restatements colapsam
Relacionado
- Skill
content-design— front-load de artefato persistido
Adaptado de mattpocock/skills (writing-great-skills).
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

