🏗️ Claude Best Practices — 29 Agentes, 174 Skills, 58 Reglas y 22 Hooks
El repo que no es una lista: es una fábrica de configuración
abhayla/claude-best-practicesse autodenomina hub: un repositorio de patrones reutilizables de Claude Code que se instalan en tu proyecto, no se leen.
- Números verificados en
core/.claude/: 29 agentes, 174 skills, 58 reglas y 22 hooks.- 10 plugins publicados en su propio marketplace, instalables con
/plugin install.- Ocho workflows orquestados (
/test-pipeline,/development-loop,/debugging-loop,/code-review-workflow…) con contratos entre pasos.- MIT, creado el 9-mar-2026 y actualizado el 23-oct-2026. Sigue vivo.
Tres juegos de cifras en el mismo README
- Tabla auto-generada (arriba): 29 / 174 / 58 / 22. Coincide con los archivos reales.
- Bloque «Repository Structure» (más abajo): 39 agentes (incl. 9 deprecated), 164 skills, 47 reglas, 11 hooks. Está obsoleto.
- Texto de los plugins: «13 skills + 5 agentes», «17 skills + 7 agentes»… que se solapan con el total.
Y un cuarto matiz: parte de las 174 skills son punteros a plugins, no workflows funcionales. El README lo avisa, pero no dice cuántas. Queda por confirmar.
🧭 Qué es y qué no es
| Es | No es |
|---|---|
| Un hub de patrones que se copian o provisionan | Una lista de enlaces |
Un sistema de distribución con plugins y /update-practices | Un repo de prompts sueltos |
Un generador de patrones para tu código (/synthesize-project) | Una configuración oficial de Anthropic |
| Un conjunto opinado con goals, trust score y contratos | Un toolkit neutro y minimalista |
| MIT y mantenido desde marzo | Un proyecto con comunidad (5 ⭐, 0 forks) |
La diferencia con los otros catálogos: aquí no eliges una skill y la pegas. Ejecutas un instalador que detecta tu stack y copia lo que encaja, o dejas que analice tu código y escriba reglas nuevas para tu repo.
flowchart LR H["🏗️ core/.claude<br/>29 agentes · 174 skills<br/>58 reglas · 22 hooks"] --> A["Opción A<br/>copiar todo"] H --> B["Opción B<br/>recommend.py --provision"] H --> C["Opción C<br/>/synthesize-project"] A --> P["Tu .claude/"] B --> P C --> P P --> U["🔄 /update-practices"] H --> M["🧩 Marketplace<br/>10 plugins"] M --> P
🔢 Los números, comprobados
| Componente | core/ (se distribuye) | .claude/ (solo el hub) | README auto |
|---|---|---|---|
| Agentes | 29 | 7 | 29 |
| Skills | 174 | 44 | 174 |
| Reglas | 58 | 6 | 58 |
| Hooks | 22 | 23 | 22 |
Los dos
.claude/no son lo mismo
core/.claude/es lo que se copia a tu proyecto..claude/en la raíz es la configuración operativa del propio hub — sus skills de escaneo, curación y sincronización. Si copias la raíz en vez decore/, te llevas la maquinaria interna.
Los 29 agentes, por trabajo
| Grupo | Agentes | Para qué |
|---|---|---|
| Calidad y revisión | code-reviewer, quality-gate-evaluator, security-auditor, anthropic-multi-agent-reviewer, visual-inspector | Revisar diff, auditar seguridad, evaluar gates, inspeccionar UI |
| Testing | test-scout, tester, test-healer, test-failure-analyzer, fastapi-api-tester | Clasificar tests, ejecutar, arreglar y analizar fallos |
| Planificación y ejecución | planner-researcher, plan-executor, project-manager, parallel-worktree-orchestrator, workflow-master-template | Del PRD al plan, y del plan a los worktrees |
| Stack | android-build-fixer, android-compose, android-kotlin-reviewer, flutter-dart, fastapi-database-admin | Especialistas por tecnología |
| Git y GitHub | git-manager, github-issue-manager | Ramas, PRs, issues, dedupe |
| Sesión y contexto | session-summarizer, context-reducer | Resumir sesiones y recortar contexto |
| Investigación | web-research-specialist, karpathy-advisor | Buscar fuera y contrastar decisiones |
| Autoría y docs | skill-author, docs-manager | Escribir skills y mantener documentación |
| Debug | debugger | Diagnóstico estructurado |
Las 58 reglas: lo que de verdad vale
No son 58 ficheros de relleno. Estas tres justifican el repo por sí solas:
| Regla | La idea | Por qué importa |
|---|---|---|
dod-verbs.md | Un criterio de aceptación necesita verbo preciso + barra de completitud. «Reporta el score» se cumple imprimiendo un score. | Mata el «hecho» de mínimos |
decision-authority.md | Decide y reporta en lo reversible; pregunta solo ante bifurcación consecuente. ≥95% de confianza → procede. | Convierte la autonomía en una regla, no en un impulso |
human-approval-gates.md | Puertas explícitas antes de construir y antes de desplegar | Evita el despliegue sorpresa |
El resto cubre testing (23 KB), orquestación de agentes (19 KB), seguridad, Git, contexto, stacks concretos (FastAPI, Android, Compose, Vue, Prisma, Hono, Bun/Elysia, Firebase) y meta-reglas sobre cómo escribir reglas (rule-writing-meta, rule-curation).
dod-verbs.mdes el complemento exacto de Opus 5.5 Dev🧭 Opus 5.5 Dev dice «define Done = X». Esta regla dice cómo se escribe esa X para que un ejecutor autónomo no la cumpla por el camino más barato. Van juntas.
Los 22 hooks
| Hook | Qué hace |
|---|---|
secret-scanner | PreToolUse en Write|Edit: bloquea AWS keys, PEM, tokens de GitHub, Google, etc. |
dangerous-command-blocker | Corta comandos destructivos antes de ejecutarlos |
auto-format | Formatea tras editar |
auto-git, auto-pr, session-git-landing | Ramas, commits, PRs y aterrizaje de sesión |
branch-choice-gate, stale-branch-reaper | Elegir rama y limpiar ramas muertas |
context-window-monitor, context-window-statusline | Avisar y mostrar el contexto consumido |
session-concurrency-guard, session-reminder, session-governance-status | Evitar sesiones pisándose |
no-overask-guard | 23 KB para que el agente no pregunte de más |
turn-origin, verifier-edge-guard | Trazabilidad y verificación |
team-task-* (3) | Tareas de equipo: creadas, completadas, idle |
Son bash real: leen el JSON de PreToolUse por stdin, usan jq y devuelven exit 2 para bloquear con el mensaje de vuelta a Claude. No son pseudocódigo.
🧩 Los 10 plugins
El hub publica su propio marketplace (claude-best-practices) y se instala desde GitHub sin clonar:
/plugin marketplace add abhayla/claude-best-practices
/plugin install prompt-auto-enhance@claude-best-practices| Plugin | Qué trae |
|---|---|
prompt-auto-enhance | Pipeline de diagnóstico y refuerzo de prompts |
branch-lifecycle | Ciclo de rama, commit, push, PR y merge + sesiones |
auto-google-analytics | GA4 para proyectos web |
fable-operating-manual | Disciplina de razonamiento inyectada por hook |
loop-engineering | Bucle DISCOVER → PLAN → EXECUTE → VERIFY → SHIP · 13 skills + 5 agentes |
cbp-workflows | Code review, documentación y autoría de skills · 16 + 4 |
cbp-build-test-workflows | Development loop + test pipeline de tres carriles · 17 + 7 |
cbp-learning-workflow | Aprendizaje y auto-mejora · 5 + 2 |
cbp-react-stack | Vitest/Jest y patrones React/RN · 6 skills |
cbp-python-stack | pytest, FastAPI test/migrate/deploy · 4 + 2 |
Instala plugins, no copies a ciegas
El propio README avisa: una skill «graduada» a plugin queda en
core/como puntero. Si la copias, te llevas el texto que dice «instala el plugin», no el workflow. Para esas, el marketplace es la vía correcta.
🚀 Instalación: tres niveles
| Opción | Comando | Cuándo |
|---|---|---|
| A · Copiar todo | cp -r core/.claude/ /tu/proyecto/.claude/ | Rápido; luego borras lo que no uses |
| B · Provisión inteligente | PYTHONPATH=. python scripts/recommend.py --local /tu/proyecto --provision | Detecta stacks y copia solo lo que encaja |
| C · Síntesis completa | B + /synthesize-project --skip-hub dentro del proyecto | Además genera patrones de tu código |
Stacks detectados: fastapi-python, android-compose, ai-gemini, firebase-auth, react-nextjs, flutter, vue-nuxt, bun-elysia. Los patrones universales no llevan prefijo.
Para actualizar: /update-practices dentro del proyecto.
Lo que hace distinto a /synthesize-project
- Lee tus ficheros de configuración, entry points y tests.
- Identifica 10-20 convenciones de tu código.
- Te las enseña y espera aprobación.
- Genera reglas, skills y agentes con frontmatter válido.
- En modo remoto (
--repo owner/name), abre un PR en el repo objetivo.
Es la diferencia entre «usar las reglas de otro» y «tener reglas que solo aplican a tu repo»: que todos los endpoints pasen por ApiResult[T], que añadir una entidad Room toque seis archivos.
🧠 El detalle técnico que más me interesa: skill-at-T0
El hub documenta un límite real de la plataforma: Claude Code no pasa la herramienta Agent a los subagentes. Un subagente lanzado no puede lanzar otros subagentes; cualquier Agent() dentro de su cuerpo se inlinea en silencio.
Su solución: mover la orquestación a la sesión T0 del usuario. La skill se inyecta ahí, y desde ahí despacha workers planos en un solo mensaje, que es el único punto realmente paralelo.
T0 (tu sesión)
├── project-manager-agent (PRD → producción, solo T0)
├── /test-pipeline → scout, tester, api-tester, visual-inspector,
│ failure-analyzer, issue-manager, fixers
├── /development-loop ├── /session-continuity
├── /debugging-loop ├── /learning-self-improvement
├── /code-review-workflow └── /skill-authoring-workflow
└── /documentation-workflowY deja 8 agentes workflow-master marcados deprecated: true que no deben despacharse. Es raro ver un repo que documente su propia deuda así, con specs v2.2 y contratos entre pasos (config/workflow-contracts.yaml, 19 KB).
⚖️ Lectura crítica
Lo bueno:
- Es un sistema, no una lista: distribución por stacks, marketplace de plugins,
/update-practicesy CI de validación. - Los números que presume son reales (29/174/58/22), y la tabla se genera sola desde
registry/patterns.json. - Reglas con sustancia, no obviedades:
dod-verbs,decision-authority,human-approval-gates. - Hooks funcionales con
jq, stdin y exit codes correctos, no ejemplos. - Documenta límites de la plataforma con enlaces a issues de Anthropic y una solución concreta.
/synthesize-projectes el diferenciador real: patrones derivados de tu código, con aprobación humana.- Mantenido desde marzo, con 21 issues abiertos y workflows de sincronización.
Lo que hay que tener en cuenta:
- 5 ⭐ y 0 forks. Es la configuración personal de una persona, publicada con mucho rigor. No hay validación comunitaria.
- 29 MB y 3.221 entradas en el árbol. Es un repo grande para lo que aporta a un proyecto pequeño.
- 174 skills es un problema, no un argumento. Cada skill suma su descripción al contexto de descubrimiento: más skills, más ruido y peor enrutado. Instala por stack, no «todo».
- Parte son punteros a plugins; el número de skills funcionales es menor y no está declarado (
por confirmar). - El README se contradice entre la tabla automática y el bloque de estructura. Señal de documentación que crece más rápido que su mantenimiento.
- Ficheros enormes:
prompt-auto-enhance/SKILL.md55 KB,writing-skills41 KB,lessons.md110 KB,CLAUDE.md41 KB. Leerlos cuesta contexto. - Opinado y con jerga propia: goals, trust score, fable, T0, lane, gate. Sin su
docs/no se entiende. - Dependencia de Python para la provisión inteligente y la síntesis.
- Escribe en proyectos de terceros vía GitHub Actions (
sync-to-projects.yml) si los registras. Potente y peligroso a la vez. - Todo en inglés, incluidas las reglas que luego condicionan cómo te habla el agente.
- Los topics del repo (
5w-status-active,5w-time) parecen residuos de su propio flujo, no taxonomía.
La lectura de fondo
Este repo responde a una pregunta que los demás catálogos ni se plantean: ¿cómo mantienes 174 skills sin que se pudran? Su respuesta es un pipeline — registry, contratos, validación en CI, plugins versionados, síntesis desde el código y actualización con un comando. Eso es más valioso que las skills concretas. Pero también es su trampa: es un sistema para gente que quiere un sistema, con 29 MB, jerga propia y una sola persona detrás. Si solo quieres tres reglas buenas, llévate
dod-verbs,decision-authorityy elsecret-scanner. Si quieres montar tu propio hub, este es el plano.
🆚 No confundir con la otra «Claude Code Best Practices»
Esta (abhayla) | La de shanraisshan | |
|---|---|---|
| Qué es | Hub instalable con agentes, skills, reglas, hooks y plugins | Guía de subagentes, skills, hooks, MCP y memoria |
| Formato | Repo grande con scripts, CI y marketplace | Documento de referencia |
| Para qué | Provisionar un proyecto | Entender cómo funciona Claude Code |
| Coste | 29 MB y decisiones de diseño | Lectura |
🔗 Enlaces
- Repositorio — claude-best-practices
- Catálogo completo en
core/.claude/README.md - Getting started
- Instalar los plugins en un proyecto
- Reglas de completitud (
dod-verbs) - Autoridad de decisión (
decision-authority) - Filtro de secretos (
secret-scanner)
🔗 Notas relacionadas
- 🧭 Opus 5.5 Dev — el «Done = X» que aquí se convierte en regla escrita.
- 🧠 Claude Code Best Practices — la guía conceptual, no el hub instalable.
- 🗺️ Awesome Claude Code — el mapa general de herramientas y skills.
- 🧰 Awesome Claude Code Toolkit — otro kit de agentes y hooks, más pequeño.
- 🧰 Claude Skills (Rezvani) — el catálogo masivo de skills.
- 📥 Vault Ingest — cómo se guardó esta nota.