La mayoría de los desarrolladores usan Claude Code como un autocompletado de terminal ligeramente más inteligente. Escriben un prompt, Claude genera código, lo copian a su editor. Funciona. Pero están dejando el 80% de la herramienta sobre la mesa.
Claude Code tiene un stack completo de extensibilidad: CLAUDE.md, slash commands, skills, hooks, subagentes, MCP y plugins. Cada capa resuelve un problema distinto. Entender cuál usar y cuándo es lo que separa al desarrollador que reacciona del que construye un sistema.
Esta guía recorre cada una de esas capas — desde lo más básico hasta lo más avanzado — con ejemplos concretos que puedes implementar hoy.
1. CLAUDE.md: El archivo que cambia todo
Antes de tocar cualquier feature avanzada, necesitas tener tu CLAUDE.md en orden.
Este archivo es la "constitución" de tu proyecto. Se carga automáticamente al inicio de cada sesión y ancla el comportamiento de Claude sin que tengas que re-explicar tu arquitectura, tus convenciones o tus comandos cada vez.
Un CLAUDE.md mínimo que vale la pena tener:
# Proyecto: mi-api
## Build
npm run build
## Lint
npm run lint -- --fix
## Test
npm test
## Convenciones
- TypeScript strict mode
- No default exports
- Formato de commits: feat/fix/chore(scope): descripción
- Variables de entorno en .env.example, nunca hardcodeadas
Archivos anidados por directorio
Claude Code también descubre CLAUDE.md en subdirectorios. Cuando Claude lee archivos de un directorio que contiene su propio CLAUDE.md, ese archivo se carga automáticamente en el contexto.
mi-proyecto/
├── CLAUDE.md # Reglas generales del proyecto
├── src/
│ ├── db/
│ │ └── CLAUDE.md # Patrones de base de datos
│ └── components/
│ └── CLAUDE.md # Guías de componentes
└── tests/
└── CLAUDE.md # Convenciones de testing
Esto mantiene tu contexto principal limpio hasta que realmente necesitas ese conocimiento especializado.
Regla de oro: Para proyectos personales, deja que Claude mantenga el CLAUDE.md. Para cualquier cosa que te importe, mantenlo tú.
2. Slash Commands: Atajos deterministas que tú invocas
Los slash commands son prompts guardados que invocas con /comando. Son como macros para tu flujo de trabajo.
Los built-ins manejan la higiene de sesión: /clear, /compact, /context, /hooks. La parte interesante son los comandos personalizados.
Para crear uno, añade un archivo .md en .claude/commands/:
mkdir -p .claude/commands
cat > .claude/commands/review-pr.md << 'EOF'
Obtén el diff del PR $ARGUMENTS usando `gh pr diff`.
Revisa: errores de lógica, problemas de seguridad, manejo de errores ausente.
No comentes estilo ni convenciones de nombres.
Produce una lista estructurada: Crítico / Importante / Menor.
EOF
Lo invocas: /review-pr 142. Claude obtiene el diff, ejecuta la revisión y formatea la salida exactamente como lo especificaste.
Los slash commands también pueden orquestar flujos complejos — lanzar subagentes en paralelo, ejecutar investigación y luego generar artefactos. Todo desde un archivo markdown.
La distinción clave: Los slash commands son invocados por ti. Las skills (que veremos después) son invocadas por Claude automáticamente según el contexto. Si estás empezando desde cero, usa el formato de skills (.claude/skills/nombre/SKILL.md) que soporta tanto invocación manual (/nombre) como autónoma.
3. Skills: Contexto que Claude carga automáticamente
Las skills son el cambio arquitectónico. A diferencia de los comandos que invocas manualmente, las skills son invocadas por el modelo — Claude las usa autónomamente basándose en el contexto.
Ubicación: .claude/skills/ para alcance de proyecto, ~/.claude/skills/ para alcance personal en todos tus proyectos.
Cada skill es un directorio con un archivo SKILL.md. El frontmatter YAML controla cuándo Claude la carga:
---
name: generate-commit-messages
description: Genera mensajes de commit claros a partir de git diffs.
Usar cuando se escriban mensajes de commit o se revisen cambios staged.
---
## Instrucciones
1. Ejecuta `git diff --staged` para ver los cambios
2. Escribe un mensaje de commit: resumen en menos de 50 caracteres,
descripción detallada debajo
3. Usa tiempo presente. Explica qué cambió, no lo que hiciste.
La description es crítica. Si es vaga, dispara falsos positivos y Claude carga una skill que no aplica, desperdiciando contexto. Sé específico: nombra el escenario exacto.
Un directorio de skill también puede contener scripts, archivos de referencia y plantillas. El SKILL.md le indica a Claude que los use. Esto es lo que hace que las skills sean genuinamente poderosas para flujos complejos.
Budget de contexto: Las descripciones de skills compiten por un presupuesto de caracteres (2% de la ventana de contexto, con un mínimo de 16,000). Si tienes muchas skills, ejecuta /context para verificar que no estén siendo excluidas.
4. Hooks: Reglas deterministas que Claude no puede ignorar
CLAUDE.md es una sugerencia. Los hooks son una obligación.
Los hooks son scripts que se ejecutan automáticamente en puntos específicos del ciclo de vida de Claude Code. Se configuran en .claude/settings.json:
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "npx prettier --write $FILE_PATH"
}
]
}
],
"Stop": [
{
"hooks": [
{
"type": "command",
"command": "echo \"$(date): $CONVERSATION_SUMMARY\" >> ~/.claude/activity.log"
}
]
}
]
}
}
Eventos principales del ciclo de vida
| Evento | Cuándo se dispara |
|---|---|
SessionStart |
Al iniciar o reanudar una sesión |
UserPromptSubmit |
Cuando envías un prompt, antes de que Claude lo procese |
PreToolUse |
Antes de que una herramienta se ejecute. Puede bloquearla |
PostToolUse |
Después de que una herramienta se ejecuta exitosamente |
Stop |
Cuando Claude termina de responder |
PreCompact |
Antes de la compactación de contexto |
SessionEnd |
Cuando la sesión termina |
Estrategia práctica de hooks
Bloquea al submit, no al write. Evita hooks que bloqueen en cada operación Edit o Write — deja que Claude complete su razonamiento y luego valida el resultado final. Bloquear a mitad de edición rompe la cadena de pensamiento del modelo.
Casos de uso ideales para hooks:
- Formateo automático con Prettier o Black
- Logging de actividad de sesión
- Validación pre-commit (correr tests antes de permitir
git commit) - Notificaciones de escritorio cuando tareas largas terminan
- Bloqueo de comandos destructivos (
rm -rf)
5. Subagentes: Aislamiento de contexto para tareas complejas
El concepto es simple: una tarea compleja requiere X tokens de entrada, acumula Y tokens de contexto de trabajo y produce Z tokens de respuesta. Los subagentes externalizan el trabajo a agentes especializados que solo devuelven la respuesta final, manteniendo tu contexto principal limpio.
Los archivos de subagentes viven en .claude/agents/ con el mismo patrón de frontmatter YAML que las skills.
El trade-off es real. Si construyes un subagente de testing, ocultas todo el contexto de pruebas del agente principal. Ya no puede razonar holísticamente sobre un cambio. Los subagentes no son gratis.
Úsalos cuando:
- Necesitas ejecutar ramas de investigación en paralelo
- Una tarea requiere tool calls en sandbox que no deberían contaminar la sesión principal
- Quieres mantener una sesión principal limpia en una tarea de larga duración
- Vas a hacer un escaneo masivo del repositorio
6. MCP: Conectando Claude Code a tus herramientas externas
MCP (Model Context Protocol) es un estándar abierto que conecta Claude Code a servicios externos — GitHub, bases de datos, browsers, APIs internas. El servidor maneja la integración; Claude maneja el razonamiento sobre qué hacer con ella.
Los tres transportes
# HTTP (recomendado para servidores remotos)
claude mcp add --transport http notion https://mcp.notion.com/mcp
# Stdio (ideal para herramientas locales)
claude mcp add --transport stdio github -- npx -y @modelcontextprotocol/server-github
# Con autenticación
claude mcp add --transport http secure-api https://api.example.com/mcp \
--header "Authorization: Bearer tu-token"
Lo que puedes hacer con MCP
- Implementar features desde tu issue tracker: "Agrega la feature descrita en JIRA ENG-4521 y crea un PR en GitHub"
- Analizar datos de monitoreo: "Revisa Sentry y Statsig para ver el uso de la feature ENG-4521"
- Consultar bases de datos: "Encuentra los emails de 10 usuarios aleatorios que usaron la feature ENG-4521 en PostgreSQL"
- Integrar diseños: "Actualiza nuestro template de email según los nuevos diseños de Figma"
- Automatizar flujos: "Crea drafts en Gmail invitando a esos 10 usuarios a una sesión de feedback"
Gestión de servidores
claude mcp list # Listar servidores
claude mcp get github # Detalles de un servidor
claude mcp remove github # Eliminar un servidor
/mcp # Panel de estado dentro de Claude Code
7. Plugins: Flujos empaquetados y compartibles
Un plugin es una colección de slash commands, agentes, skills y hooks empaquetados juntos. Un marketplace es una colección de plugins de la misma fuente — Anthropic mantiene uno oficial.
/plugin install nombre@marketplace
/reload-plugins
Antes de instalar cualquier plugin de la comunidad: Los plugins pueden incluir código tanto en skills como en hooks. Nunca instales ni dejes que Claude ejecute código que no hayas revisado primero. Esto aplica especialmente a los hooks, que se ejecutan con tus credenciales.
Ecosistema comunitario
- Claude Code Tresor: 8 skills autónomas + 8 agentes expertos + 4 comandos de workflow. Ideal para empezar.
- Skills Library: 26+ paquetes de dominio: marketing, producto, project management, engineering.
- Skill Factory: Genera skills personalizadas para tu stack específico.
8. Disciplina de sesión: Lo que realmente importa
Las herramientas solo funcionan si la sesión se mantiene limpia.
-
Usa
/clearcon frecuencia. Cada vez que empiezas algo nuevo, limpia el chat. No necesitas todo ese historial comiéndote los tokens. -
/compactes la opción intermedia. Resume contexto antiguo sin descartarlo. Útil cuando estás a mitad de una tarea y el contexto se está alargando. - La regla de oro: Empieza limpio, acota la tarea, limpia al terminar.
Todo lo demás — hooks aplicando quality gates, skills cargando contexto relevante, comandos codificando tu proceso — funciona mejor cuando la sesión no está cargando peso muerto de hace tres problemas.
El stack completo en acción
Imagina este flujo de trabajo:
-
CLAUDE.mddefine las convenciones del proyecto (TypeScript strict, no default exports, testing con Vitest) - Un hook
PostToolUseformatea automáticamente cada archivo editado con Prettier - Una skill
code-reviewerse activa al guardar archivos y sugiere mejoras de seguridad y rendimiento - Un slash command
/review-prorquesta la revisión completa de un PR usandogh pr diff - Un subagente
test-engineergenera tests con contexto aislado sin contaminar la sesión principal - Un servidor MCP de GitHub permite crear PRs, revisar issues y hacer checkout de ramas sin salir de Claude Code
- Un hook
Stopregistra un resumen de cada sesión para referencia futura
Cada capa resuelve un problema específico. La magia está en combinarlas.
Próximos pasos
No necesitas implementar todo de una vez. Empieza por lo que te da el mayor retorno con el menor esfuerzo:
-
Hoy: Crea tu
CLAUDE.mdcon comandos de build, lint, test y 3-5 convenciones clave - Esta semana: Añade 2-3 hooks (formateo automático + logging de sesión)
- Este mes: Crea tu primera skill para una tarea repetitiva de tu flujo
- Cuando tengas un flujo estable: Empaqueta todo en un plugin para compartir con tu equipo
La diferencia entre usar Claude Code como un asistente de código glorificado y tener un sistema de desarrollo aumentado por IA no está en el modelo — está en cómo lo configuras.
¿Quieres llevar la automatización de tu empresa al siguiente nivel? En Guayoyo Tech construimos soluciones de IA agéntica, integraciones enterprise y automatizaciones a medida. Conversemos.
Top comments (0)