agentleFS
goul4rtgoul4rt/quick-guardrails-ia/.claude/skills/writing-agents-md/SKILL.md

writing-agents-md

Skill12 starsChanged 4 months agoMITView on GitHub

Use when asked to write, rewrite, or bootstrap a repo's agent context file (AGENTS.md / CLAUDE.md), e.g. "escreva o CLAUDE.md", "crie o AGENTS.md", "documente os padrões do repo para o agente", or when applying-guardrails reaches block 1 of the CHECKLIST with no context file.

6 other projects use a version of this.

Adopted by

Most recently taken up by

  • Other versions6 projects use a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 6

    1. compozy/compozy★ 2.9ksame name
    2. pedronauck/skills★ 655same name
    3. annatchijova/SKILLS★ 9same name
    4. dougcunha/TokenHound★ 3same name
    5. johannschopplich/skills★ 1same name
    6. RedKenrok/skills★ 1same name

    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 repositoryOne other file it gives its agents.

The file

Files
SKILL.md

Escrevendo o AGENTS.md de um repo

Referência: doc 01 do quick-guardrails-ia (três níveis acima deste arquivo, se veio via plugin). O resultado é sempre este par:

  • AGENTS.md: o contrato. Fonte única, lida por Codex, Cursor, Copilot e pelo Claude Code.
  • CLAUDE.md: @AGENTS.md na primeira linha, e abaixo só o que é exclusivo do Claude Code (hooks, skills, plan mode). Vazio abaixo do import é o caso normal.

Nunca o conteúdo nos dois arquivos: contratos duplicados divergem em silêncio.

O fluxo tem quatro fases, nesta ordem. Cada uma termina com o artefato dela entregue.

Fase 1: fatos (você descobre, não pergunta)

Levante o que o repo responde sozinho: stack, comandos reais de build/test/lint/dev (rode-os; comando que falha não entra), estrutura de alto nível, convenções visíveis em código (nomes, padrão de serviço, testes), README, CONTRIBUTING, contexto que já exista (CLAUDE.md, AGENTS.md, .cursorrules, .github/copilot-instructions.md) e git log recente. Em repo grande, delegue a varredura a um subagente e fique só com a conclusão.

Artefato: lista de fatos com a evidência de cada um (arquivo:linha ou comando + saída), e a lista separada do que parece decisão mas o código não explica.

Fase 2: entrevista (decisão se pergunta)

Rode as skills grilling e domain-modeling (juntas, é o que o /grill-with-docs do pacote mattpocock-skills faz) sobre a segunda lista da Fase 1: por que este padrão, qual gotcha já mordeu, o que o agente nunca deve fazer aqui. Uma pergunta por vez, cada uma com a sua hipótese a partir do código.

  • Termo do domínio resolvido vai para o CONTEXT.md, na hora.
  • Decisão já tomada em código vira ADR em docs/adr/ só se passar nos três critérios: difícil de reverter, surpreendente sem contexto, fruto de trade-off real. As outras viram uma linha no AGENTS.md ou nada.
  • Sem as skills instaladas: conduza a entrevista inline com as mesmas regras e avise que claude plugins install mattpocock-skills deixa isso reproduzível.

Artefato: CONTEXT.md e ADRs escritos, e as respostas que viram regra.

Fase 3: escrita

Escreva o AGENTS.md seguindo o doc 01: postura no topo, regras checáveis num diff (com ✅/❌ quando couber), gotchas com o porquê, válvulas de escape nomeadas, regras de STOP, comandos que você rodou na Fase 1. Teto declarado no próprio arquivo, abaixo de 200 linhas. O que é longo e só vale para parte do código vira ponteiro (docs/adr/, CONTEXT.md, .claude/rules/ por caminho), não texto inline.

Não entra: estrutura de pastas que o ls mostra, boas práticas genéricas, instrução de ferramenta da máquina do dev (rtk e afins vivem na config global), e qualquer coisa que o humano não confirmou.

Depois crie o CLAUDE.md com @AGENTS.md e, se houver, a seção exclusiva do Claude Code.

Fase 4: auditoria

Rode a skill claude-md-improver (plugin claude-md-management) sobre o par. Aplique o que ela apontar de comando faltando, comando quebrado ou regra vaga; recuse o que ela sugerir que viole o teto ou repita o código. Em conflito, o doc 01 vence.

Entregue em branch + PR, com o relatório da auditoria no corpo. O merge é do dono.

Erros comuns

ErroCorreção
Escrever regra que o humano não confirmou ("parece que usam X")Vira pergunta na Fase 2 ou fica de fora
Um ADR por decisão encontradaSó os que passam nos três critérios; o resto é uma linha ou nada
AGENTS.md como symlink de CLAUDE.md, ou conteúdo copiado nos doisAGENTS.md é a fonte; CLAUDE.md importa com @AGENTS.md
Colar a árvore de pastas e a lista de dependênciasO agente lê o repo; o arquivo carrega só o que o repo não diz

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.