Repo Hygiene
gg-mo/repo-hygiene
Skills para manter codebases limpos e bem documentados durante edições de IA
Ver no GitHubConjunto de skills que mantém repositórios saudáveis enquanto agentes de IA trabalham neles. Injeta práticas de higiene em momentos críticos: orientação inicial, documentação, testes, validação de commits e limpeza de código legado. Complementa fluxos de TDD e planejamento com disciplinas técnicas de baixo nível.
Instalação
npx convez-ai gg-mo/repo-hygiene1 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
Casos de uso
- Garantir documentação automática em novas funções e APIs
- Validar qualidade de commits antes de push com regras de higiene
- Orientar agentes de IA em repositórios desconhecidos antes de editar
- Manter arquivos compactos e refatorar quando ultrapassam limite de linhas
- Aplicar limpeza estruturada em codebases legados em fases revisáveis
Veredito

Skill bem arquitetada que resolve um problema real: manter padrões de qualidade enquanto agentes de IA editam código. A abordagem modular com triggers em momentos específicos (não a cada keystroke) é eficiente. Recomendado para equipes que usam Claude Code, Cursor ou Codex e precisam de guardrails automáticos de higiene.
README
A tradução para o português deste README ainda está na fila.
Repo Hygiene
A small, opinionated skill set that keeps codebases healthy as coding agents work in them. Modeled on Superpowers: one bootstrap skill is injected at session start, and five sub-skills auto-trigger at the right moments.
It complements Superpowers — Superpowers gives you the workflow disciplines (brainstorming, TDD, debugging, planning); repo-hygiene gives you the lower-level hygiene that should hold across every change:
- Orient before you edit
- Docstring what you write
- Keep files from sprawling
- Update docs when you change public surface
- Test what you ship
- Write commit messages that explain WHY
- Verify before you commit
- Clean up existing codebases in reviewable phases
How it works
A SessionStart hook injects skills/using-repo-hygiene/SKILL.md into the system context of every conversation. That bootstrap tells the agent which sub-skill applies at which moment. The agent then invokes the relevant sub-skill via the harness's Skill (or equivalent) tool when its trigger fires.
The skills don't trigger on every keystroke — they trigger at meaningful moments: starting work in a new repo, writing a new function, changing a public API, committing.
Skill catalog
| Skill | Triggers when |
|---|---|
using-repo-hygiene | Bootstrap — loaded into every session |
orienting-to-repo | Starting substantive work in an unfamiliar repo |
writing-docstrings | Writing or modifying any function, method, class, or source file |
keeping-files-small | About to add lines to a file already >400 lines, or your edit pushes one past that |
keeping-docs-fresh | Changing a public API surface (renames, signature changes, new flags/routes/env vars, schema migrations) |
testing-new-code | Adding business logic, branching code, public API, or fixing a bug |
writing-commit-messages | Drafting any commit message |
gating-commits | About to commit, merge, or push |
cleaning-existing-codebase | User asks to "clean up" or apply repo-hygiene to an existing project |
Each SKILL.md is the canonical source — read those for the rules. The bootstrap stays lightweight so it can ride in every session without burning context.
Quickstart
Installation differs by harness. Pick the section for the agent you use.
Claude Code
The plugin lives in this repo. To register it as a development marketplace:
/plugin marketplace add gg-mo/repo-hygiene
/plugin install repo-hygiene@repo-hygiene-dev
Or for a local checkout:
/plugin marketplace add /path/to/repo-hygiene
/plugin install repo-hygiene@repo-hygiene-dev
Codex CLI / Codex App
The Codex manifest lives in .codex-plugin/plugin.json. Install via the plugins UI by pointing to this repo, or via:
codex plugin install https://github.com/gg-mo/repo-hygiene
Cursor
cursor plugin install https://github.com/gg-mo/repo-hygiene
The Cursor-specific hook config is at hooks/hooks-cursor.json.
OpenCode
opencode plugin install repo-hygiene
The OpenCode adapter is .opencode/plugins/repo-hygiene.js. It registers skills/ with OpenCode's skill loader and transforms the first user message of each session to include the bootstrap.
Gemini CLI
gemini extension install gg-mo/repo-hygiene
The Gemini entry file GEMINI.md imports the bootstrap skill via @-reference. Tool-name mappings (e.g. TodoWrite → equivalent) are documented inside the bootstrap.
GitHub Copilot CLI
copilot plugin install gg-mo/repo-hygiene
The shared SessionStart hook auto-detects Copilot CLI via the COPILOT_CLI=1 environment variable and emits the SDK-standard additionalContext JSON.
Local install (no plugin)
If you don't want to register a plugin, drop the skills into your local Claude Code skills directory:
# User-level (applies to all your sessions)
cp -r skills/* ~/.claude/skills/
# Project-level (applies only inside this repo)
cp -r skills/* /path/to/your/project/.claude/skills/
You'll lose the SessionStart auto-bootstrap (so using-repo-hygiene won't auto-load), but the sub-skills will still be discoverable by the Skill tool when their descriptions match.
Bypass
A user can suppress any hygiene skill for one turn by including #hygiene-skip <reason> in their message. The agent acknowledges the bypass and proceeds. This is for the cases where the skill would be genuinely wrong — not a way to disable hygiene permanently.
How the skills were built
Each sub-skill was developed via the TDD-for-skills cycle from superpowers:writing-skills:
- RED — dispatch a subagent with a representative scenario, no skill loaded; document its baseline behavior verbatim.
- GREEN — write the skill addressing the specific failure modes observed.
- REFACTOR — re-test with the skill loaded; tighten any new rationalizations.
The baseline scenarios surfaced honest admissions like "without this nudge I'd treat 'ship it' as authorization to commit whatever's staged" and "user said commit, so commit." The skills are tuned against those exact failure modes. See CLAUDE.md for how to test changes when contributing.
Repo layout
.
├── .claude-plugin/ # Claude Code plugin manifest + marketplace
├── .codex-plugin/ # Codex CLI / App manifest
├── .cursor-plugin/ # Cursor manifest
├── .opencode/plugins/ # OpenCode JS adapter
├── hooks/
│ ├── hooks.json # Claude Code SessionStart registration
│ ├── hooks-cursor.json # Cursor SessionStart registration
│ ├── run-hook.cmd # Polyglot batch/bash wrapper (Windows + Unix)
│ └── session-start # Bash script that injects the bootstrap
├── skills/
│ ├── using-repo-hygiene/ # Bootstrap (loaded at session start)
│ ├── orienting-to-repo/
│ ├── writing-docstrings/
│ ├── keeping-files-small/
│ ├── keeping-docs-fresh/
│ ├── testing-new-code/
│ ├── writing-commit-messages/
│ ├── gating-commits/
│ └── cleaning-existing-codebase/
├── gemini-extension.json # Gemini CLI extension manifest
├── GEMINI.md # Gemini bootstrap entry (@-imports the skill)
├── CLAUDE.md # Contributor guidelines
├── AGENTS.md # → CLAUDE.md (symlink)
├── package.json # OpenCode entry + npm metadata
└── README.md
Contributing
See CLAUDE.md. Short version: skills are documentation that shapes agent behavior. Don't edit them without the RED → GREEN → REFACTOR cycle. One problem per PR.
License
MIT. See LICENSE.