Claude Code desde cero en español: comandos, skills, MCP y subagentes

Claude Code es el agente de código de Anthropic: corre en tu terminal, lee tu repositorio, edita archivos, ejecuta comandos y usa herramientas externas, todo desde una conversación. Para un desarrollador hispanohablante es la forma más directa de dejar de copiar y pegar código y empezar a delegar tareas completas: refactors, tests, documentación y automatizaciones. Esta guía te lleva de cero a un flujo de trabajo real: instalación, comandos que usas todos los días, skills, MCP, subagentes, hooks y modo headless para CI.

Qué es Claude Code y qué resuelve

Claude Code no es un chatbot pegado a tu editor: es un agente que trabaja en tu repositorio. Recibe una instrucción, explora el proyecto, edita archivos, ejecuta comandos y te muestra un diff antes de confirmar. La documentación oficial lo define como un agente de codificación conversacional que vive en la terminal, y sus tres capacidades clave son:

• Contexto del proyecto: entiende la estructura del repo, no solo el archivo abierto.
• Acciones reales: edita, ejecuta tests y comandos git por ti, con tu permiso.
• Extensibilidad: skills, MCP y subagentes para adaptarlo a tu forma de trabajar.

Instalación y autenticación

npm install -g @anthropic-ai/claude-code
claude --version

Después de instalar, ejecuta claude en la carpeta de tu proyecto. En el primer inicio te pide autenticación: puedes usar tu cuenta de Claude (plan Pro o Max) o una API key de Anthropic. Para entornos de equipo o CI, la autenticación por API key es la recomendada porque no depende de una sesión interactiva.

Comandos clave que usas todos los días

Comando	Qué hace	Cuándo usarlo
/help	Muestra la ayuda de comandos	Siempre que dudes de una opción
/init	Crea el archivo CLAUDE.md del proyecto	Al empezar un repo, para darle contexto permanente
/clear	Limpia el historial de la conversación	Cuando cambias de tarea por completo
/compact	Resume la conversación para liberar contexto	En sesiones largas que se acercan al límite
/model	Cambia el modelo de la sesión	Para alternar entre velocidad y capacidad
/mcp	Gestiona servidores MCP conectados	Para ver o probar herramientas externas
/agents	Trabaja con subagentes	Para tareas paralelas y acotadas
/hooks	Configura hooks de automatización	Para correr checks automáticos en cada edición
/cost	Muestra el costo acumulado de la sesión	Para controlar gasto en sesiones grandes

El flujo típico es: abres claude, describes la tarea en lenguaje natural —"arregla el bug del formulario y agrega un test"— y el agente propone cambios que tú apruebas o rechazas. Siempre puedes pedir que explique qué hizo y por qué.

Skills: el conocimiento que persiste

Una skill es un paquete de instrucciones y referencias que Claude Code carga cuando la tarea la requiere. Se guardan en .claude/skills/ dentro del proyecto (o en ~/.claude/skills/ para uso global). Cada skill es una carpeta con un archivo SKILL.md:

---
name: revisar-es
description: Revisar código aplicando convenciones de estilo y mensajes en español
---

Revisa los archivos cambiados y verifica: nombres de variables descriptivos,
mensajes de error en español, y que los commits sigan la convención del repo.

La descripción es la que decide cuándo se activa: el agente la lee y usa la skill cuando la tarea coincide. Las skills convierten tu forma de trabajar —convenciones, checklists, prompts de QA— en algo reutilizable entre proyectos y sesiones.

MCP: conectar herramientas externas

MCP (Model Context Protocol) le da a Claude Code acceso a servidores de herramientas: bases de datos, APIs, navegadores, CMS. Se agregan desde la terminal o con /mcp:

claude mcp add github --transport http https://mcp.github.com/mcp
claude mcp list

Cada servidor expone herramientas que el agente puede invocar como funciones nativas. La regla práctica: agrega pocos servidores, con permisos mínimos, y revisa qué herramientas expone cada uno antes de conectarlo.

Subagentes y hooks: paralelismo y control

Los subagentes son sesiones acotadas que trabajan en tareas específicas —revisar un módulo, escribir tests, investigar una librería— mientras la conversación principal mantiene el objetivo. Son ideales para dividir trabajo grande sin perder el hilo.

Los hooks ejecutan comandos automáticamente en momentos del ciclo de vida: antes de editar, después de cada herramienta, al terminar. Un ejemplo típico: correr linter y tests después de cada edición, para que el agente corrija sus propios errores antes de que tú los veas.

Modo headless: Claude Code sin interfaz

El modo headless (claude -p "tu prompt") ejecuta una tarea sin abrir la interfaz interactiva, ideal para automatizar:

claude -p "Revisa los cambios pendientes y escribe un mensaje de commit"

Se usa en scripts, CI y cron jobs: una tarea, una respuesta, sin sesión. Es la misma capacidad del agente, pero embebida en tu automatización.

Primera sesión: un ejemplo guiado

Para ver todo junto, corre esta secuencia en un proyecto pequeño:

1. claude dentro del repo, y /init para que el agente lea el proyecto y genere el CLAUDE.md con su estructura y comandos.
2. Pide una tarea acotada: "Agrega validación de entrada al formulario de login y un test para el caso de email vacío".
3. Revisa el plan que propone antes de aprobar: qué archivos tocará y por qué.
4. Acepta la edición, corre los tests y, si fallan, pide: "Corrige los tests que rompiste".
5. Cierra la tarea con /clear y empieza la siguiente con el contexto limpio.

Este ciclo —instrucción, plan, aprobación, verificación— es la forma correcta de trabajar con Claude Code. El error más común del principiante es aceptar cambios sin revisarlos y sin correr los tests; el agente es rápido, pero rápido también para romper cosas que no le pediste verificar.

Problemas comunes y cómo resolverlos

• npm install -g falla por permisos: usa sudo solo si es necesario o configura el prefix de npm en tu directorio de usuario; la documentación oficial cubre la instalación en cada sistema.
• La autenticación no avanza: verifica tu plan (Pro/Max) o que la API key tenga crédito; en equipos, la autenticación por API key evita depender de sesiones interactivas.
• El agente no usa una skill: revisa que el name y la description del SKILL.md sean precisos; la descripción es lo que el agente lee para decidir cuándo activarla.
• La sesión se vuelve lenta: usa /compact para resumir el contexto o /clear si cambiaste de tarea.
• No ves los servidores MCP: claude mcp list te muestra el estado; si un servidor falla, el mensaje de error suele indicar si es transporte, autenticación o URL.

Checklist de verificación antes de usarlo en producción

1. claude --version responde y la autenticación está activa.
2. Ejecutaste /init y el CLAUDE.md refleja tu proyecto.
3. Probaste una tarea pequeña y revisaste el diff completo antes de aprobar.
4. claude mcp list muestra solo los servidores que necesitas.
5. Corriste una sesión con /cost para saber cuánto gastaste.
6. Configuraste hooks de linter/tests si el repo los tiene.

Claude Code reemplaza el trabajo mecánico, no el criterio: tú decides qué se aprueba. Para conectarle herramientas externas sin romper nada, lee la guía de MCP explicado con ejemplos y para ver el protocolo aplicado a bases de datos y APIs, MCP con Python. Si partes de cero con agentes, el curso gratuito de instalación te deja el primer agente funcionando, y el hub de construcción de agentes tiene el resto del camino.