🔷 Anatomía de Claude Code

Markdown que Claude Code inyecta en el system prompt. Existe en tres niveles: ~/.claude/CLAUDE.md (global), ./CLAUDE.md (raíz del proyecto) y subdir/CLAUDE.md (alcance de carpeta). Todo se concatena en orden.

Equivocarte en la jerarquía hace que una instrucción del proyecto sobrescriba una global sin que te des cuenta. O peor: que una instrucción global ahogue una preferencia específica del proyecto.

CLAUDE.md de usuario vs. CLAUDE.md del proyecto, precedencia, "las instrucciones directas tienen precedencia sobre todo", tamaño ideal (<2KB), comandos de build/test al principio.

Carpeta con convención fija: agents/ (sub-agents .md), skills/ (carpetas con SKILL.md), commands/ (slash commands), settings.json, settings.local.json, hooks/.

Quien no conoce la estructura coloca el archivo en el lugar equivocado y Claude simplemente no lo ve. La convención es estricta: nombre correcto, carpeta correcta, o no funciona.

Convención sobre configuración, gitignore parcial, separación entre usuario y proyecto (misma estructura en ~/.claude/ e ./.claude/).

Archivo JSON con configuración de comportamiento: permisos (permitir/denegar por herramienta), modelo predeterminado, variables de entorno, hooks, includeCoAuthoredBy, theme, statusLine.

Es donde reduces la fricción de permisos (auto-allow para comandos comunes), cambias de modelo (Haiku para tareas rápidas) e inyectas hooks de eventos.

Permisos mediante regex/glob, settings.local.json (no va al git), variables de entorno con el prefijo CLAUDE_, override en cascada user → project → local.

Comandos de shell activados por el harness en eventos del agente: antes/después del uso de una herramienta, al detenerse, al recibir un prompt, al iniciar la sesión. Se EJECUTAN, no dependen de que Claude los recuerde.

Es la única forma de garantizar un comportamiento determinista ("ejecutar siempre lint antes de hacer commit"). Memory/prompt no bastan: Claude puede olvidarlo. Un hook no lo olvida.

Eventos compatibles (PreToolUse, PostToolUse, Stop, SessionStart, UserPromptSubmit), matchers por nombre de tool, exit code 0/no 0, fail-open vs fail-close.

Archivos markdown en .claude/commands/ que se convierten en comandos slash. El nombre del archivo se convierte en el comando (review.md → /review). Reciben argumentos opcionales ($ARGUMENTS).

Las tareas que repites se convierten en un solo comando. Hacer commit con un mensaje estandarizado, abrir un PR, generar un changelog: todo se convirtió en un slash.

Frontmatter con description y allowed-tools, namespace global vs. proyecto, $ARGUMENTS e $1/$2, encadenamiento con bash backtick-bang.

Reglas en settings.json que controlan qué tools/comandos puede ejecutar Claude sin preguntar. Tres niveles: allow (permite), deny (bloquea), ask (pregunta cada vez).

Los permisos mal configurados generan fricción (preguntar por todo) o riesgo (dar demasiados permisos). El equilibrio es permitir la lectura y el análisis, y pedir confirmación para escribir o realizar acciones destructivas.

Estándar glob (Bash(ls:*), Bash(git status:*)), modos de permiso (default, acceptEdits, plan, bypassPermissions), lista permitida de MCP (mcp__servidor).

Plan mode es un modo en el que Claude planifica sin editar, ideal para un refactor grande. Output styles cambian el tono de la respuesta (verbose, concise, explanatory). Ambos ajustan el comportamiento sin cambiar el prompt.

¿Empiezas una tarea compleja? Primero Plan mode y luego la ejecución. ¿Quieres respuestas cortas? Output style concise. ¿Detalles? explanatory. Cambiar el tono no genera ninguna fricción.

/plan, /output-style, personalización mediante .claude/output-styles/*.md, aislamiento del modo por sesión.

Carpeta en .claude/skills/<nome>/ que contiene SKILL.md (con frontmatter YAML: name, description, allowed-tools opcional), y subcarpetas convencionales scripts/, references/, assets/.

Es la forma moderna de empaquetar comportamiento. Más limpio que inflar CLAUDE.md, más reutilizable que un slash command y se activa mediante una descripción en lugar de una invocación manual.

Frontmatter mínimo (name + description), tamaño ideal del body, references como deep-dive de carga diferida, scripts para acciones deterministas.

El campo description del frontmatter es lo que el agente usa para decidir si invoca la skill. Una descripción vaga = skill ignorada. Una descripción con los activadores correctos = skill activada en el momento oportuno.

La causa más común de que una skill "no funcione" es una description deficiente. No es un bug, es un fallo de coincidencia semántica. Hay patrones claros que funcionan (use when..., trigger phrases, examples).

Patrón "Use when X": enumera frases reales que usa el usuario como disparadores, ejemplos directos; evita redundancias con el nombre.

Archivos en .claude/agents/<nome>.md: frontmatter (name, description, tools, model) + cuerpo con el system prompt de la persona. Claude principal delega tareas mediante la herramienta Task; el sub-agent se ejecuta de forma aislada.

El sub-agent aísla el contexto (no contamina el del agente principal), puede ejecutarse en paralelo y es la forma de contar con especialistas (code-reviewer, security-auditor, etc.) sin un prompt enorme.

Auto-dispatch mediante descripción, paralelismo (varios sub-agents simultáneos), restricción de tools por sub-agent, modelo dedicado (Haiku para búsquedas, Opus para análisis).

Conectar Claude a servicios externos mediante Model Context Protocol. Server declarado en .mcp.json (proyecto) o ~/.claude.json (global). Las herramientas se convierten en mcp__server__tool.

MCP es la forma de darle superpoderes a Claude: acceso a Slack, Gmail, GitHub y bases de datos, sin necesidad de implementar herramientas personalizadas.

transporte stdio vs HTTP, allowlist ("enabledMcpjsonServers": [...]), descubrimiento de herramientas, variables de entorno y secretos mediante variables.

Sintaxis específica de Claude Code: dentro de SKILL.md o commands, código entre crase-bang (`!cmd`) se ejecuta en el shell y el resultado se incorpora al prompt. Codex no es compatible.

Es la forma de crear una skill dinámica: "leer el último log", "listar branches", "obtener la versión actual" — sin necesitar una tool call adicional. Pero es una feature exclusiva: ten cuidado al portar.

Ejecución en build-time de la skill, security implications (no interpolar input no confiable), polyskill convierte en prosa de fallback en Codex.

Campos en el frontmatter de la skill: disable-model-invocation impide la activación automática (solo se ejecuta cuando se invoca explícitamente); allowed-tools restringe qué herramientas puede usar la skill.

Las Skills peligrosas (que ejecutan acciones destructivas) necesitan invocación explícita. Las Skills enfocadas deben tener una superficie de herramientas restringida para evitar sorpresas.

Principio de privilegio mínimo, invocación opt-in, allowlist de tools, model override (ejecutar una skill con Haiku para ahorrar).

Claude Code admite plugins (paquete con skills + agents + commands + hooks) que se instalan desde un marketplace. Cada plugin puede tener su propio namespace (plugin:skill-name).

Es cómo aprovechas el trabajo de otros (claude-mem, context-mode, superpowers, etc.) y cómo publicas el tuyo. Distribución estandarizada.

manifiesto plugin.json, marketplace.json, namespace plugin:skill, versionado (estilo npm), actualización mediante /plugins.