convez.ai
SkillProdutividadeIntermediário
scottTomaszewski

Documentação de Repositórios para Agentes

scottTomaszewski/documenting-repos-for-agents

Docs canonicalizadas e verificadas que sobrevivem entre agentes

Ver no GitHub
InicialPluginScore · de 0 a 100

Uma skill Claude Code que cria e mantém um substrato persistente de documentação markdown em repositórios, permitindo que agentes novos se integrem rapidamente sem re-escanear o projeto inteiro. Implementa uma taxonomia canônica de arquivos organizados por tempo de vida, com verificação de drift e suporte a handoffs entre sessões.

Instalação

$npx convez-ai scottTomaszewski/documenting-repos-for-agents

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
3

Casos de uso

  • Onboarding rápido de novos agentes em repositórios sem re-varredura
  • Manutenção de documentação viva sincronizada com mudanças do código
  • Captura sistemática de lógica não óbvia, workarounds e gotchas
  • Handoff de contexto entre sessões de agentes via docs estruturadas

Veredito

Solução prática e bem pensada para o problema real de documentação que apodrece em projetos. A abordagem de taxonomia canônica + verificação de drift é sensata; o design mostra compreensão profundo de como agentes falham em contexto. Recomendado para equipes que usam Claude Code intensivamente.

README

A tradução para o português deste README ainda está na fila.

documenting-repos-for-agents

A Claude Code skill for setting up — and keeping current — a persistent markdown doc substrate in a repo, so a fresh agent with zero context can orient and start working without re-scanning the whole tree, and so work state survives across sessions.

It's the creation counterpart to the creating-handoffs skill: that one routes session state through a repo's living docs; this one creates those living docs in the first place. The two share one taxonomy and meet at the same paths.

What it does

Capable agents already write reasonable docs unprompted. The problem is they write bespoke, unverified ones — every agent invents different file names and collapses everything into one log that rots. This skill makes the output canonical, lifespan-routed, and verified instead.

It imposes one predictable file taxonomy, routed by how long each fact lives:

FileHoldsLifespan
CLAUDE.md (root)small router: what this is, key commands, where things live, conventions, pointersstable
ARCHITECTURE.mdthe "don't re-scan" quickstart: mental model, core data flows, module mapsemi-stable
docs/*.mddeep references + funky logic / gotchas, one topic per fileper-subsystem
FOLLOWUPS.md (root)small deferred findings — the lightweight queuechurns
ROADMAP.md (root)larger planned / in-flight effortschurns
docs/handoffs/HANDOFF.mdephemeral "you are here" session state — owned by creating-handoffsper-session

Key ideas:

  • Canonical names, every repo. Predictability is the point — the next agent (and the creating-handoffs skill) always knows where to look.
  • A deliberate funky-logic sweep. Workarounds, magic numbers, and non-obvious decisions get a definite home (a precise inline comment, or a docs/ entry) — instead of being captured only by luck.
  • Anti-rot maintenance. A "when you change X, update Y" sync agreement written into CLAUDE.md, plus a re-runnable drift check. Docs only save tokens if they're trusted.
  • Cold-start verification. Before declaring the docs done, a reader (subagent, or a manual fresh pass) sees only the docs and tries to onboard — whatever it gets wrong is a gap. You have the context; you can't see your own blind spots.

See SKILL.md for the full skill and DESIGN.md for the rationale and the RED→GREEN→REFACTOR record it was built with.

Contents

FileRoleInstalls to
SKILL.mdThe skill~/.claude/skills/documenting-repos-for-agents/SKILL.md
DESIGN.mdDesign rationale + test record (not installed)—
install.shSymlinks the skill into ~/.claude—

There's no command file: Claude Code auto-generates a /documenting-repos-for-agents slash command from the skill.

Install

Clone the repo wherever you like, then symlink the skill into ~/.claude. Symlinks mean a git pull updates your installed copy instantly.

Quick way (recommended)

git clone <repo-url> documenting-repos-for-agents
cd documenting-repos-for-agents
./install.sh

install.sh is idempotent, creates the needed directories, backs up any existing non-symlink file, and links from this clone — so it works no matter where you cloned it.

Manual way

REPO="$(pwd)"   # run from inside the clone
mkdir -p ~/.claude/skills/documenting-repos-for-agents
ln -sfn "$REPO/SKILL.md" ~/.claude/skills/documenting-repos-for-agents/SKILL.md

Start a new Claude Code session afterward so the skill is picked up.

Usage

  • /documenting-repos-for-agents — set up (or refresh) the doc substrate in the current repo.
  • The skill also triggers automatically when a repo lacks docs, when a fresh agent has to re-scan the tree to get oriented, or when onboarding/architecture/gotchas live only in code.

Updating

cd documenting-repos-for-agents && git pull

The symlink points at the clone, so the new version is live in your next session — no reinstall needed.

Uninstall

rm -r ~/.claude/skills/documenting-repos-for-agents
Ver o original no GitHub

Bom para

Relacionados