Habilidades, no subagentes

El consejo que circula es armar un equipo: un agente que planea, otro que implementa, otro que revisa. Suena a oficina y por eso convence — cada quien en lo suyo, cada quien con su instrucción. Anthropic le puso nombre a ese reparto y lo marcó como contraproducente: lo llama descomposición centrada en el problema.

El problema no es que los agentes sean malos. Es que dividir por tipo de trabajo obliga a que cada uno le cuente al siguiente lo que ya sabía, y esa cuenta nunca sale completa.

De «Building multi-agent systems: when and how to use them», del 23 de enero de 2026.

El subtítulo se llama «Skills, not subagents»

El 2 de septiembre de 2026, Anthropic publicó cómo arma los agentes de comercio que ya corren en producción con sus clientes de empresa. Uno de los subtítulos del índice se llama, literal, «Skills, not subagents». Debajo está la frase que sostiene esta página entera:

De «The anatomy of effective commerce agents». De la forma del sistema dice, en la misma página:

There is no intent router in front of it that segments the conversation and no set of domain specific agents behind it.

No hay adelante un enrutador de intención que parta la conversación, ni atrás un conjunto de agentes por dominio.

Por qué el reparto pierde

Dos palabras que van a volver en toda la página, y las dos se explican una sola vez, aquí. Un token es la unidad con la que Claude cuenta lo que lee y lo que escribe: no es una palabra, es un pedazo de palabra, y una palabra larga puede valer tres o cuatro. Tu límite semanal es cuántos de esos tokens te deja gastar tu plan antes de frenarte hasta que arranca la semana siguiente.

Cada vez que un agente le pasa la tarea a otro, lo que viaja es un resumen, no la sesión. El que recibe nunca sabe qué se probó antes y se descartó. Anthropic lo dice con una palabra que vale la pena traducir despacio: cada entrega pierde estado.

Every handoff to a subagent is a state-lossy operation, which often impacts the quality of the subagent’s response and, consequently, the overall response. On top of that, each handoff can cost several times the tokens and adds seconds of latency.

Cada entrega a un subagente es una operación que pierde estado, lo que muchas veces afecta la calidad de la respuesta del subagente y, en consecuencia, la respuesta completa. Encima, cada entrega puede costar varias veces los tokens y suma segundos de espera.

• Pierde estado: el subagente recibe un resumen, no la conversación. Lo que el primero exploró y descartó no llega, así que el segundo lo vuelve a explorar.
• Cuesta varias veces los tokens: duplicar el contexto en cada agente, los mensajes de coordinación entre ellos y el resumen de cada entrega se pagan aparte del trabajo.
• Suma segundos: cada entrega es una vuelta más antes de que algo se vea en tu pantalla.

En un equipo real la gente se acuerda de la junta anterior. Estos no. Repartir una sola tarea entre agentes que no se pasan el contexto es el error de verdad, y es el que se paga en calidad y en tokens.

Lo que se reparte y lo que se equipa

Anthropic acota sus propios números en la misma página: son guías prácticas de hoy, no límites de fondo, y se moverán conforme mejoren los modelos. El número tiene fecha porque le hace falta.

La letra chica va aquí, no al pie

Anthropic no dice «nunca varios». Su sección se titula «The case for starting with a single agent» —el caso a favor de EMPEZAR con un solo agente— y cierra con una frase que esta guía firma completa: «Our advice? Start with the simplest approach that works, and add complexity only when evidence supports it.» Empieza por lo más simple que funcione y agrega complejidad solo cuando la evidencia lo pida.

También nombra tres situaciones donde varios agentes sí ganan de forma consistente. Van aquí en una línea cada una, porque negarlas sería vender algo:

• Contexto contaminado: cuando la basura que junta una subtarea le estorba a la siguiente.
• Tareas paralelizables: cuando el trabajo se parte en pedazos que de verdad no se hablan entre sí.
• Especialización de herramientas: cuando separar mejora con cuál herramienta se queda cada quien.

Fuera de esas tres, «the coordination costs typically exceed the benefits»: el costo de coordinar se come el beneficio. Y ya estás usando subagentes sin saberlo, porque Claude Code trae dos de fábrica y los arranca solo. Los tres casos con su peaje, esos dos de fábrica y a qué guía irte en cada uno están en §09 · Cuándo sí se parte en dos. Esta sección solo los nombra.

Para quién NO es esta página

Cuatro lectores se van a topar con pared en algún punto de lo que sigue. Mejor saberlo en el primer minuto que en el vigésimo:

• Quien no abre la terminal. Todo esto son archivos de texto en una carpeta y frases que se escriben dentro de Claude Code. No hay versión de botones.
• Quien usa Claude desde el teléfono. La carpeta se puede armar igual, pero medir cuánto te cuesta cada habilidad —lo que hace la sección 3— solo sale desde la terminal de la computadora donde corre la sesión.
• Quien trabaja en una cuenta de empresa donde el administrador dejó bloqueadas las habilidades propias: ahí solo cargan las que la empresa aprobó, y las tuyas quedan fuera por más bien escritas que estén.
• Quien está en el plan gratis de claude.ai, que no incluye Claude Code. Se necesita Pro, Max, Team o Enterprise.

Nada de lo que sigue es un truco de prompt. Es una carpeta con archivos de texto que Claude lee al abrir, y que crece cuando algo se rompe dos veces. Lo que sigue es qué va adentro y en qué orden.

Antes de escribir un solo archivo, el agente tiene que saber a qué te dedicas. Y eso no sale de llenar una plantilla en blanco con los títulos que alguien más eligió: sale de que se lo cuentes, como se lo contarías a alguien que entra a trabajar contigo el lunes. Tú tienes el material; lo que no tienes es el formato. El prompt de abajo invierte los papeles para resolver justo eso.

Con una condición, y no es menor: esto se hace dentro de la carpeta donde de verdad trabajas —donde están tus documentos, tus notas, tus archivos de clientes—, no en una carpeta nueva y vacía que creaste para probar. El agente vive en una carpeta, no en el aire, y lo que escriba hoy solo se va a cargar solo si quedó guardado ahí.

La documentación lo dice sin rodeos: Claude Code carga esos archivos «from your current working directory and every directory above it» —desde la carpeta donde estás parado y todas las de arriba—. Está en la doc de memoria, verificado el 18 de septiembre de 2026.

Dónde se escribe esto

• Todo este paso ocurre en la terminal: esa ventana de texto sin botones que ya viene instalada en tu computadora. En Mac se abre con Cmd + espacio, escribiendo «terminal» y Enter.
• En Windows es la tecla de Windows, escribir «terminal» y Enter. Es la misma ventana con otro nombre.
• Dentro de esa ventana escribes un comando, das Enter, y lees lo que contesta. Nada más. El primero es el de abajo, y solo sirve para comprobar que Claude Code ya está ahí.

Si contesta con un número —algo como «2.1.277 (Claude Code)»—, ya lo tienes y puedes seguir. Si contesta «command not found», no está instalado en esta computadora: eso no se arregla aquí, se resuelve con el instalador de un clic y vuelves a este punto.

Cambia la ruta por la tuya. En Finder o en el Explorador puedes arrastrar la carpeta a la terminal y la ruta se escribe sola.

El detalle de /init, los niveles de CLAUDE.md y los imports tiene su propia guía en Estructura de Claude. Aquí solo importa por qué no es el arranque.

El prompt maestro

Vas a entrevistarme sobre mi trabajo para escribir la primera versión de la carpeta de este agente.

Cómo te quiero:

Eres el entrevistador, no el escritor. Todavía no escribas ningún archivo.
Hazme una pregunta a la vez y espera mi respuesta antes de pasar a la siguiente.
Si una respuesta mía te queda vaga, repregunta sobre esa misma antes de avanzar.
No avances hasta tener algo concreto: un nombre, un número, un ejemplo que de verdad pasó.
Si necesitas ver cómo escribo o cómo entrego, abre tú los archivos de esta carpeta en vez de pedirme que te pegue documentos.

Lo que tienes que sacarme, en este orden:

1. A qué me dedico y para quién: qué entrego y quién me paga por eso.
2. Qué tarea repito cada semana, y cuántas veces al mes la hago.
3. Cómo se ve esa tarea cuando salió bien: condiciones que se puedan revisar una por una, no adjetivos.
4. Cómo se ve cuando salió mal: el error concreto que ya cometí, no el error teórico.
5. Qué archivos, carpetas o sistemas toco para hacerla, y dónde viven.
6. Qué no debe pasar nunca: lo que no se toca, lo que no sale sin que yo lo lea, lo que no se promete.
7. Con qué palabras hablo yo: tres frases que sí digo y tres que jamás diría.

Para calibrar el nivel de detalle que quiero, así contestaría un despacho que manda cotizaciones: la tarea que repite es armar la cotización de un cliente nuevo, tres o cuatro por semana; bien hecha lleva el precio con IVA incluido, el alcance en viñetas, el plazo con fecha y la cláusula de anticipo; mal hecha va sin IVA, con el alcance en un párrafo y un «de 2 a 3 semanas» sin fecha; y lo que no debe pasar nunca es que salga una cotización con un precio que nadie revisó.

Cuando termines las siete, repíteme en cinco renglones lo que entendiste y pregúntame qué le falta.
Solo después de que yo te diga que está bien, escribe.

Qué me entregas al final, las tres cosas:

1. Un CLAUDE.md de menos de 200 líneas, escrito con mis palabras y no con las tuyas. Guárdalo tú, con ese nombre exacto, en la raíz de esta carpeta, y dime la ruta completa del archivo que quedó.
2. Una lista de habilidades candidatas: una línea por tarea repetida, ordenadas de más a menos veces al mes que la repito, con ese número al lado de cada una. Guárdala tú también, en habilidades-candidatas.md, en esta misma carpeta.
3. Cuál de esas conviene hacer primero, y el motivo en una sola frase. Esa va en el chat, no en un archivo.

Lo que no puedes hacer:

No inventes nada. Si no te lo dije, pregúntamelo.
Si ya preguntaste y sigue sin quedar claro, déjalo escrito como PENDIENTE en el archivo, en vez de rellenarlo con algo que suene bien.
No metas buenas prácticas genéricas. Si una línea serviría igual para cualquier otro oficio, bórrala.
No copies el ejemplo del despacho: es mi calibración de cuánto detalle quiero, no mi negocio.

Qué hacer con lo que salga

• El CLAUDE.md lo crea y lo guarda Claude, no tú: no abres un editor, no peleas con la extensión del archivo ni lo copias de la pantalla. Cuando termine te da la ruta; si quieres verlo, pídele que te lo enseñe.
• Queda en la raíz de esa misma carpeta, y ese es el único lugar donde se carga solo cada vez que abres el agente ahí.
• La lista de habilidades todavía no se toca. Se queda en su archivo, al lado del otro: se convierte en carpetas en la §05, no hoy.
• Lo que quedó marcado como PENDIENTE se queda marcado. Un hueco visible vale más que un dato inventado que en tres semanas vas a leer como si fuera cierto.

El tope de 200 líneas no es gusto de nadie, y qué va y qué no va dentro de ese archivo se revisa línea por línea en Quién es. Deja el archivo tal como salió y ábrelo ahí.

Cómo sabes que la entrevista salió bien

Hay una sola señal, y se revisa en dos minutos: el borrador menciona cosas que tú dijiste y que Claude no podía adivinar. Cuatro que deberías poder señalar con el dedo:

• Nombra a tus clientes, tus formatos o tus plazos como los nombras tú.
• Trae por lo menos un «nunca» que viene de algo que ya te pasó, no del sentido común.
• La lista de habilidades lleva números: cuántas veces al mes, no «frecuente» ni «ocasional».
• Reconoces tu forma de hablar en dos líneas por lo menos.

La entrevista se corre una vez, y se repite el día que cambies de oficio. Todo lo que sigue en esta página es qué hacer con lo que salió de aquí.

Todo lo que hace que tu agente sea tuyo son archivos de texto en dos lugares: la carpeta del proyecto, que viaja con el repositorio y la ve tu equipo, y tu carpeta personal, que se queda en esta máquina. Nada de esto es una base de datos ni una cuenta: son archivos que puedes abrir con cualquier editor, borrar y volver a escribir.

Este es el árbol completo, con la marca de qué se commitea. La columna de commit es la que trae la documentación oficial, no una recomendación de esta página.

Antes del árbol: cuatro cosas que no se ven

• La carpeta .claude/ está oculta, y esa es la primera sorpresa. El punto con el que empieza el nombre es lo que hace que el Finder no la muestre: si abres tu carpeta y no ves nada nuevo, no es que Claude no haya escrito; es que no la estás viendo. En el Finder de Mac los archivos ocultos se muestran con Cmd+Shift+punto, y con el mismo atajo se vuelven a esconder; en el Explorador de Windows, en la pestaña Vista, palomeando «Elementos ocultos». En la terminal se ven con ls -a en Mac y con dir /a en Windows.
• La raíz del proyecto es la carpeta principal, la que abres con Claude Code. Un archivo «en la raíz» va ahí mismo, al lado de CLAUDE.md, no adentro de una subcarpeta.
• Commit —la columna de la derecha— quiere decir guardar el archivo en el historial compartido del proyecto, el control de versiones, para que le llegue a tu equipo. Si trabajas solo y no usas control de versiones, no tienes que hacer nada con esa columna: los archivos funcionan igual.
• Los archivos terminados en .json son texto, no programas. JSON es un formato de llaves, comillas y dos puntos que se abre con cualquier editor; lo que Claude Code guarda ahí son ajustes, no código que corra.

En tu proyecto: lo que viaja con el repositorio

tu-proyecto/
├── CLAUDE.md                    ✓ commit   quién es. Se carga entera en cada sesión
├── .mcp.json                    ✓ commit   MCP del equipo. VA EN LA RAÍZ, no en .claude/
└── .claude/
    ├── settings.json            ✓ commit   permisos, hooks, variables, modelo
    ├── settings.local.json      ✗ ignorado tus ajustes de este proyecto, fuera de git
    ├── rules/*.md               ✓ commit   instrucciones por tema, con o sin paths:
    ├── skills/<nombre>/SKILL.md ✓ commit   qué sabe hacer. Una carpeta por habilidad
    ├── agents/*.md              ✓ commit   subagentes. Aquí viven; cuándo, en la §09
    ├── output-styles/*.md       ✓ commit   cómo habla
    └── workflows/*.js           ✓ commit   los escribe Claude desde /workflows, no tú

Diez renglones no son diez tareas. Al terminar esta guía vas a tener dos cosas en esa carpeta: CLAUDE.md y .claude/skills/. Nada más. No tienes que crear output-styles/, ni rules/, ni agents/ para completar el dibujo: cada uno aparece el día que te haga falta, y varios —workflows/, por ejemplo— los escribe Claude cuando se lo pides.

Tres cosas de ese árbol que se prestan a error

• .mcp.json va en la raíz del proyecto, al lado de CLAUDE.md, y nunca dentro de .claude/. La documentación lo dice con esas palabras: «Lives at the project root, not inside .claude/» —vive en la raíz del proyecto, no dentro de .claude/.
• settings.local.json es el único de la lista que no se commitea. Cuando Claude Code guarda ahí un ajuste en un repositorio que todavía no lo ignora, agrega el patrón a tus exclusiones globales de git.
• workflows/*.js no se escribe a mano: «Workflows are written by Claude and saved here from /workflows rather than authored from scratch» —los flujos los escribe Claude y se guardan aquí desde /workflows, en vez de escribirse desde cero. Tú corres /workflows y guardas la corrida; el archivo lo deja Claude.

En tu casa: lo tuyo, que nunca se commitea

Esta segunda carpeta vive en tu directorio personal —la virgulilla que encabeza la ruta, ~, es justo eso: tu carpeta de usuario, la que en una Mac se llama como tú— y aplica a todos tus proyectos en esta máquina. No viaja en git, no la ve tu equipo y no la ven las sesiones que no corren aquí. Es donde pones lo que es tuyo y no del proyecto.

~/.claude/
├── CLAUDE.md                    tus instrucciones para todos tus proyectos
├── skills/<nombre>/SKILL.md     tus habilidades, en cualquier carpeta que abras
├── agents/*.md                  tus subagentes
├── rules/*.md                   tus reglas, se cargan antes que las del proyecto
├── settings.json                tus ajustes globales
└── projects/<proyecto>/memory/
    └── MEMORY.md                la memoria automática. La escribe Claude, no tú

La memoria automática tampoco la escribes tú: Claude va guardando ahí lo que aprende de ti entre sesiones. De ese índice se cargan las primeras 200 líneas, o los primeros 25 KB, lo que ocurra primero; el resto queda en archivos por tema que Claude abre cuando los necesita.

Las tres confusiones que conviene desactivar hoy

• .mcp.json no va dentro de .claude/. Va en la raíz del proyecto, junto a CLAUDE.md.
• La memoria automática de ~/.claude/projects/<proyecto>/memory/ no es lo mismo que .claude/agent-memory/. La primera son las notas que Claude se deja a sí mismo en la conversación principal; la segunda solo se crea para un subagente que la pidió en su archivo.
• Los archivos de ~/.claude/skills/ no los ven las sesiones de nube, ni las rutinas, ni Cowork: «Cowork sessions and cloud sessions, including routines, don't read ~/.claude/skills/ on your machine» —las sesiones de Cowork y las de nube, rutinas incluidas, no leen el ~/.claude/skills/ de tu máquina. Si quieres que una habilidad exista ahí, va commiteada en el .claude/skills/ del repositorio o habilitada en tu cuenta de claude.ai.

AGENTS.md, y la trampa que trae

Si tu carpeta ya tiene un AGENTS.md —el archivo que usan otras herramientas de código— Claude Code lo lee como instrucciones del proyecto, sin que agregues un import ni toques un ajuste. Eso pide la versión 2.1.277 o más nueva.

La trampa está en que no se suman solos. Esta es la tabla completa de qué lee Claude según lo que tengas en la carpeta:

Los @path imports, y por qué no te ahorran nada

Un CLAUDE.md puede jalar otros archivos escribiendo @ruta/al/archivo en una línea. Sirve para no tener un archivo gigante, y el archivo importado puede a su vez importar otro, hasta un tope de cuatro saltos.

• No ahorran contexto. Es el dato que casi nadie publica y el que más caro sale creer al revés: «imported files still load and enter the context window at launch» —los archivos importados se cargan igual y entran en la ventana de contexto al arrancar. La ventana de contexto es todo lo que Claude puede tener presente a la vez en una conversación, y cuando se llena empieza a olvidar lo del principio. Partir un CLAUDE.md de 600 líneas en seis imports de 100 deja el mismo peso en cada sesión, solo mejor ordenado.
• Lo que sí ahorra es mover esa instrucción a una regla con paths: o a una habilidad, que cargan cuando hacen falta y no antes.
• Las rutas relativas se resuelven contra el archivo que tiene el import, no contra la carpeta desde la que abriste la sesión.
• Un import que sale de tu carpeta —por ejemplo, uno que apunta a tu directorio personal— dispara un diálogo de aprobación la primera vez, con la lista de archivos. Si dices que no, quedan apagados y el diálogo no vuelve.

Qué se carga cuándo, y qué te cobra por estar ahí

Esta es la tabla oficial de costo de contexto, traducida, sin la fila de inteligencia de código, que solo aplica si programas. Léela como el presupuesto de tu carpeta: cada cosa que agregas ocupa un lugar en la conversación, y ese lugar se paga aunque ese día no la uses.

Los dos renglones de subagentes tienen un tope y un peaje que se cuentan en Cuándo sí se parte en dos, que es también donde se decide si vale la pena tener uno.

Los dos comandos para ver tu propio costo

Ninguna cifra de esta página sustituye a medir tu carpeta. Son dos comandos, se corren dentro de una sesión y no escriben nada:

Dibuja tu contexto como una cuadrícula de colores y te dice qué se lo está comiendo: los archivos de memoria que cargaron, las herramientas pesadas, los avisos de capacidad. Con /context all se abre el desglose pieza por pieza.

Lista tus habilidades y te deja escribir para filtrarlas. La tecla t las ordena por cantidad de tokens, que es la vista que necesitas cuando el listado se pasó de presupuesto: arriba queda lo que más cobra.

El árbol completo, con cada archivo y su columna de commit, vive en la documentación de la carpeta .claude; ahí también están las piezas que esta página deja fuera por raras.

La tabla de carga y costo sale de la vista general de funcionalidades, y aquí va traducida con las mismas columnas.

Y la tabla de AGENTS.md, el tope de cuatro saltos y el diálogo de una sola vez salen de la documentación de memoria, que se lee en diez minutos y es la fuente de todo lo de arriba.

Con esto ya sabes dónde poner cada cosa y cuánto te va a cobrar. Lo que sigue es qué se escribe adentro, empezando por el archivo que se carga entero en cada sesión.

CLAUDE.md es un archivo de texto en la raíz de tu carpeta que Claude lee entero al empezar cada sesión, antes de que tú escribas la primera palabra. No es un prompt que mandas: es el contexto con el que arranca. Lo escribes tú, en español, sin formato especial.

Por eso adentro va lo que le tendrías que volver a explicar en cada conversación: quién eres, cómo hablas, qué reglas no se negocian en tu trabajo. Y por eso mismo no va todo lo demás: cada línea que dejas ahí se paga en cada sesión, incluso en las que no tienen nada que ver.

La señal para agregar una línea es sencilla: Claude se equivocó dos veces en lo mismo. Una vez es un mal día; dos veces es una convención que nunca le dijiste.

Doscientas líneas, y la pregunta que poda

El tope no es de estilo, es de comportamiento: pasadas las doscientas líneas el archivo se come más contexto y Claude te obedece menos, porque tus tres instrucciones que importan quedan enterradas entre cuarenta que no. Un CLAUDE.md inflado se lee entero y se ignora igual de entero.

Esa segunda cita es lo más útil de toda la sección, y es una prueba casera: línea por línea, pregúntate si quitarla haría que Claude se equivoque. Si la respuesta es no, córtala. «Escribe código limpio» no pasa la prueba. «Los precios de cotización se muestran con IVA incluido» sí: quítala y el error vuelve el martes.

Persuade, no obliga

Aquí está la idea que cambia cómo escribes el archivo, y la que casi nadie tiene: CLAUDE.md no es configuración. Es contexto. Lo que escribes ahí inclina a Claude, no lo amarra. La mayoría de las veces hace caso. En una sesión larga, en una instrucción ambigua o cuando el archivo ya creció de más, puede no hacerlo.

Las reglas de .claude/rules/ están en el mismo costal: son otro texto que Claude lee, con la misma fuerza y el mismo riesgo.

La frase sobre las reglas es de la página de la carpeta .claude, y la de CLAUDE.md de la de memoria; verificadas el 18 de septiembre de 2026.

Qué va adentro y qué no

Las tres primeras de la derecha son la lista de «si te encuentras haciendo esto, muévelo a otro lado» del blog de Anthropic sobre cómo dirigir a Claude Code. Las dos últimas salen de la doc: el material que solo hace falta a veces se carga solo desde una habilidad, y describir lo que ya está en la carpeta es gastar renglones en algo que Claude puede leer.

Uno real, de alguien que no programa

Así se ve completo el CLAUDE.md del despacho que manda cotizaciones. Son dieciocho renglones y ninguno se puede adivinar leyendo la carpeta: son decisiones del dueño, no hechos que estén escritos en algún archivo. Esto es para leerlo, no para copiarlo — el tuyo dice otras cosas.

# Despacho Mora — cotizaciones y propuestas a clientes

## Cómo hablo
Al cliente de usted, al proveedor de tú. Nombre de pila,
nunca “estimado cliente”.

## Reglas de toda cotización
- Los precios se muestran con IVA incluido, nunca el
  subtotal suelto.
- El plazo va con fecha de entrega, no con rango:
  “viernes 3 de octubre”, nunca “de 2 a 3 semanas”.
- Anticipo del 50%, escrito dentro de la propuesta.

## Dónde está cada cosa
- Cotizaciones anteriores: /Cotizaciones/AAAA-MM/, una
  carpeta por cliente. Ahí se ve cómo quedó la última.
- Tarifas vigentes: tarifas.xlsx. Es la única fuente,
  no las saques de una cotización vieja.

Fíjate en las dos últimas: no dicen cuánto cuesta la hora, dicen dónde viven las cotizaciones anteriores y cuál es el archivo que manda cuando hay dos precios parecidos. Un dato envejece; una regla de dónde buscar, no.

Si el tuyo ya creció —porque le fuiste pegando cosas cada vez que algo salió mal—, este prompt le aplica la prueba casera línea por línea y te propone el recorte. No toca nada hasta que tú apruebes.

Abre el CLAUDE.md de esta carpeta y recórrelo línea por línea.

Para cada línea dime dos cosas: si la quito, ¿te equivocarías en algo?, y ¿en qué exactamente te equivocarías? Si la respuesta es que no te equivocarías, propón cortarla.

Aparte, márcame los bloques que sean un procedimiento de varios pasos o material de referencia que solo hace falta a veces: esos no se cortan, se mueven a una habilidad. Dime cuáles son y con qué nombre los guardarías.

Márcame también cada línea escrita como prohibición, del estilo “nunca”, “jamás” o “no hagas”. Para cada una dime si de verdad no puede pasar nunca, porque esas no se sostienen escritas aquí.

Al final dime con cuántas líneas quedaría el archivo y enséñame la versión podada completa.

No modifiques ningún archivo todavía. Espera a que yo te diga cuáles cortes apruebo.

Para abrirlo y editarlo sin salir de la sesión hay un comando. Te lista los CLAUDE.md que tienes, en tu carpeta y en tu usuario, y abre el que elijas en tu editor; si todavía no existe, lo crea.

Hay un CLAUDE.md por carpeta, otro para todos tus proyectos y una forma de partirlo en pedazos que se cargan solos. Eso, más /init a fondo y los @imports, tiene dueño en la bóveda: Estructura Claude. Esta sección se queda con una sola carpeta y un solo archivo.

CLAUDE.md dice quién es tu agente. Una habilidad dice qué sabe hacer, paso por paso, y solo se le carga cuando hace falta. En concreto es una carpeta con un archivo SKILL.md adentro, puesta en .claude/skills/. No hay instalador, no hay registro, no hay nada que aprobar: existe porque la carpeta existe.

El archivo tiene dos partes. Arriba, entre dos líneas de tres guiones, va el frontmatter: unos pocos campos que le dicen a Claude cuándo usarla. Abajo, las instrucciones en español, como se las darías a alguien que entra a tu equipo el lunes.

Lo práctico de la comparación es que ya sabes escribir una guía de inducción. Los pasos, en orden, con lo que no se debe hacer y cómo se ve el resultado bueno. Eso es literalmente el cuerpo del archivo.

El comando sale del nombre de la carpeta

Este es el dato que más circula al revés. En una habilidad personal o de proyecto, lo que escribes con barra para invocarla es el nombre de la carpeta. El campo name del frontmatter no cambia eso: es la etiqueta que se ve en el listado de habilidades, y nada más.

cotizar/SKILL.md         →  /cotizar
cierre-de-mes/SKILL.md   →  /cierre-de-mes

Cuándo nace una habilidad

No se crea una por si acaso. La doc de Claude Code trae una tabla de señales, con el orden en que la mayoría de los equipos va agregando piezas, y dos de sus filas son exactamente el disparador de una habilidad:

Sigues escribiendo el mismo prompt para arrancar una tarea, o pegaste el mismo procedimiento de varios pasos por tercera vez. Ese es el momento. Ni antes, cuando todavía no sabes cómo se hace bien, ni mucho después, cuando ya te resignaste a pegarlo.

Cómo se ve en el despacho

• Armar la cotización de un cliente nuevo: tres o cuatro por semana, siempre el mismo pedido escrito otra vez con distinto nombre y distinto alcance. Esa es la primera, y es /cotizacion.
• La propuesta larga que acompaña a la cotización cuando el cliente es grande: los mismos apartados, en el mismo orden, con el mismo tono. Es /propuesta.

Qué va adentro del SKILL.md

La versión mínima cabe en una pantalla. Todos los campos son opcionales; el único que la doc marca como recomendado es description, porque es con lo que Claude decide si tu habilidad tiene algo que ver con lo que acabas de pedir.

---
description: Arma la cotización de un cliente nuevo. Úsala cuando me
  pidan precio, presupuesto o cuánto sale un proyecto.
when_to_use: cuánto le cobro a, hazme la cotización, presupuesto para
---

## Cómo armo una cotización

1. Pregunta cliente, alcance del trabajo y para cuándo la necesitan.
2. Calcula con las tarifas del archivo tarifas.xlsx de esta carpeta. Es la única fuente de precios.
3. El precio va con IVA incluido y el plazo lleva fecha, no «2 a 3 semanas».
4. El alcance, en viñetas. Cierra con la cláusula de anticipo.
5. Antes de mandarla, enséñame el precio y espera que lo confirme.

Los campos que de verdad vas a usar

Dos avisos sobre la pareja de arriba: description y when_to_use se suman y se cortan a 1,536 caracteres en el listado, así que el caso de uso principal va primero. Y el tope del archivo completo: la doc pide mantener SKILL.md por debajo de 500 líneas, y mover el material de referencia largo a archivos aparte en la misma carpeta. Campos verificados el 18 de septiembre de 2026.

Qué tan atada la dejas

Una habilidad puede ser una receta exacta o una dirección general. La decisión no es de estilo: depende de qué tan frágil sea la tarea. Anthropic lo explica pidiéndote que imagines a Claude recorriendo un camino.

La trampa está en darle libertad baja a todo por miedo. Una habilidad con veinte reglas rígidas para una tarea que admitía tres caminos no te protege: te entrega un resultado peor, y encima uno que vas a tener que corregir a mano.

Hoy dispara de menos, no de más

El consejo que más se repite es cuidar que la habilidad no se active sola a cada rato. Va al revés de lo que dice Anthropic en el creador de habilidades que ellos mismos publican:

Traducido: hoy Claude tiende a no usar las habilidades cuando servirían, así que la descripción va empujando, con las frases exactas con las que tú pides esa tarea. «Úsala cuando me pidan precio, presupuesto o cuánto sale» funciona; «cotizaciones» no. Y si de verdad quieres que no se dispare sola, existe el campo para eso, que es disable-model-invocation.

• Traducido: si te descubres escribiendo SIEMPRE o NUNCA en mayúsculas, o armando estructuras rigidísimas, eso es una bandera amarilla.
• El arreglo que pide Anthropic es reformular y explicar el porqué. En la cotización: en vez de «NUNCA mandes un precio sin revisar», escribe «enséñame el precio y espera que lo confirme, porque un precio mal puesto ya es un compromiso con el cliente».

Las dos citas de arriba salen del mismo archivo, el skill-creator que Anthropic publica en GitHub: la habilidad con la que ellos escriben habilidades.

Por qué las mayúsculas no bastan para que una regla se cumpla lo desarrolla quién es tu agente, que es su dueña.

Quiero convertir en una habilidad un procedimiento que ya te pedí a mano tres veces: [nómbralo en una frase].

Antes de escribir ningún archivo, pregúntame esto y espera mi respuesta:
1. Para qué sirve el procedimiento y quién recibe el resultado.
2. Los pasos que sigo hoy, en orden, y qué decido yo en cada uno.
3. Con qué frases exactas te lo pido normalmente. Quiero al menos tres, tal como las escribo, con mis abreviaturas y mis errores.
4. Cómo sé que quedó bien: qué tiene que estar presente en el resultado para darlo por bueno.
5. Qué no debe hacer nunca sin avisarme.

Hazme las cinco preguntas en un solo mensaje.

Después, con mis respuestas:
Propón el nombre de la carpeta y explícame por qué ese. Que sea corto y fácil de teclear.
Crea la carpeta en .claude/skills/ con ese nombre y escribe adentro el SKILL.md.
En el frontmatter pon description y when_to_use. La descripción va empujando: que diga qué hace y cuándo usarla, e incluye las frases exactas del punto 3.
En el cuerpo pon los pasos como instrucciones directas, no como explicación de por qué existen.
Si el procedimiento tiene efectos que no se deshacen —mandar un correo, publicar algo, cobrarle a alguien— agrega disable-model-invocation: true y dime en una línea qué cambia con eso.
Si el archivo se pasa de 500 líneas, saca el material de referencia a un archivo aparte en la misma carpeta y menciónalo desde el SKILL.md.

Al final:
Enséñame el SKILL.md completo en pantalla.
Dime qué le quitarías si tuvieras que dejarlo en la mitad de líneas, y por qué eso sobra.

No hace falta instalar nada previo ni un prompt especial para crear habilidades. La doc lo dice así: «Claude models understand the Skill format and structure natively» — los modelos de Claude entienden el formato de las habilidades de forma nativa. Le pides una habilidad y te devuelve el SKILL.md con su frontmatter y su cuerpo bien armados.

El precio de tenerlas: cada habilidad instalada paga su descripción en cada turno, la use o no. Cinco bien escritas rinden más que veinte guardadas por si acaso, y cómo medir lo que te está costando esa carpeta está en el mapa de la carpeta.

Esta sección llega hasta dónde empieza a rendir. Si quieres escribir habilidades a fondo —redactar la descripción, partir el archivo, probarla en sesión limpia—, eso tiene dueño: Creador de habilidades te acompaña paso por paso.

Y la guía oficial de Anthropic, traducida y completa, está en Guía de skills de Claude.

La referencia de campos, con todo lo que aquí quedó fuera, vive en la documentación de habilidades de Claude Code.

Puedes describirle tu estándar con adjetivos —«que suene profesional pero cercano», «que no quede largo»— y va a adivinar, porque un adjetivo no tiene medida. Enséñale tres cotizaciones tuyas que salieron bien y se acabó la adivinanza: ahí está el largo, el orden, el tono y lo que decides omitir, todo junto y sin traducir.

Es la pieza más corta de la carpeta y la que casi nadie agrega. También es la que más se nota cuando está.

Los tres van en pares: la entrada es el encargo en una línea; la salida es el trabajo entero, tal como lo entregaste. La frase es de las buenas prácticas de Agent Skills, en la sección del nivel de detalle.

La mitad del valor está en lo que NO metes

Casi todo el mundo hace esto al revés: junta los quince casos raros del año, los que le quemaron una vez, y los pega todos. Anthropic lo desaconseja por escrito.

• Tres ejemplos, no quince. Si el cuarto no enseña nada que no enseñen los tres primeros, sobra.
• Típicas, no excepcionales: la cotización que sale cada semana, no la del cliente imposible de marzo.
• Distintas entre sí. Tres cotizaciones del mismo cliente, del mismo monto y del mismo mes son un solo ejemplo escrito tres veces.
• Los casos raros se escriben como regla en una línea, no como ejemplo completo. Un caso raro ocupa el mismo espacio que uno típico y enseña mucho menos.

La frase es del post de ingeniería de contexto para agentes, publicado el 29 de septiembre de 2025.

Dónde vive el archivo

Al lado del SKILL.md, en la misma carpeta de la habilidad, y se llama examples.md. La documentación lo pone así, junto con el resto de los archivos de apoyo: el SKILL.md es lo único que se lee siempre, y los demás se cargan cuando hacen falta.

.claude/
└── skills/
    └── cotizar/
        ├── SKILL.md      ← lo único que se lee siempre
        ├── examples.md   ← tres pares de entrada y salida
        └── reference.md  ← el detalle largo, solo cuando hace falta

Dejarlo ahí no basta: un archivo que nadie nombra no se abre. Hay que decir en el SKILL.md qué contiene y cuándo abrirlo, y eso es una línea.

## Recursos
- examples.md — tres cotizaciones tuyas, con el encargo que
  originó cada una. Ábrelo antes de escribir la primera.

La regla, tal cual: nombra los archivos de apoyo desde el SKILL.md para que Claude sepa qué contiene cada uno y cuándo cargarlo. Está en la documentación de habilidades, en la sección de archivos de apoyo.

La misma cotización, con y sin los tres ejemplos

El encargo es idéntico en las dos columnas: «arma la cotización para el estudio de arquitectura que nos escribió ayer». Lo único que cambia es si la habilidad tiene al lado tres cotizaciones tuyas ya entregadas.

Nada de la columna derecha se pidió con adjetivos. Salió de leer tres cotizaciones terminadas.

Cómo se los das sin pegar nada

Tus tres cotizaciones buenas están en Word y en PDF, y un documento de dos páginas no se pega en una terminal. No hace falta: deja los tres archivos en una carpeta y dile dónde están. Abrir los archivos de tu disco es lo que el agente sabe hacer desde el primer prompt de esta guía.

• Junta las tres en una sola carpeta, con nombres que se entiendan: cotizacion-marzo-estudio.pdf, no documento-final-v3.pdf.
• Abre Claude Code en la carpeta del proyecto y dile la ruta tal cual, sin adornos: cotizaciones/2026/.
• Si alguno no se puede abrir como está, guárdalo como PDF o como texto en esa misma carpeta y vuelve a decírselo.
• Pegar el texto sigue sirviendo para lo corto —un correo, una ficha, un párrafo—: en ese caso va al final del prompt y ya.

Tengo tres cotizaciones mías que salieron bien. Son trabajo real, no ejemplos inventados.

Ábrelas tú: están en [la ruta de la carpeta, tal cual]. Léelas de ahí, no me pidas que te las pegue. Si alguna no se puede abrir, dime cuál y qué intentaste antes de seguir.

Qué quiero que hagas:
Léelas y dime qué tienen en común, pero no en adjetivos: en cosas que se puedan contar. Cómo abren. En qué orden van las partes. Cuánto miden. Qué información aparece siempre y en qué lugar. Qué información nunca aparece aunque yo la tuviera a mano. Cómo cierran.

Después escribe el archivo examples.md con tres pares: la entrada es el encargo en una sola línea, la salida es la cotización tal como se entregó, sin retocarla ni mejorarla.

Arriba de los tres pares deja un párrafo corto con el patrón que encontraste. Abajo, una línea que diga hasta dónde se puede apartar de ese patrón sin dejar de sonar a mí.

Lo que no quiero que te saltes:
Si las tres son demasiado parecidas entre sí —mismo cliente, mismo monto, mismo largo, misma semana— dímelo y no escribas el archivo. Prefiero traerte una cuarta distinta a que inventes un patrón que no está en lo que te di.

Si algo aparece en una sola de las tres, no lo conviertas en regla: márcalo como variación.

Los ejemplos son lo único de la carpeta que no le puedes pedir a Claude que invente. Todo lo demás se redacta; esto se recolecta. Tienen que ser tuyos, y tres bastan.

Claude se detiene cuando el trabajo parece terminado. Ahí está el problema entero: si no hay nada que le devuelva un pasa o un no pasa, «parece terminado» es la única señal que tiene, y cada error se queda esperando a que tú lo veas.

Un ejemplo le enseña el estándar; un chequeo lo verifica. Son dos piezas distintas y hacen falta las dos. Esta es la cuarta que entra a la carpeta, y la única que puede cerrar el ciclo sin ti. Hasta cierto punto, y ese punto se dice aquí con todas sus letras.

Qué cuenta como chequeo

Los cinco ejemplos son de programación, pero la definición no: lo único que pide es una señal que se pueda leer. En el despacho que cotiza, los cinco tienen equivalente. La batería de pruebas es tu lista de condiciones. El código con el que termina la compilación es el pasa o no pasa de esa lista. El revisor de estilo es tu plantilla. El archivo de referencia es una cotización anterior que salió bien. Y la captura contra el diseño es leer la nueva al lado de esa. La lista del despacho tiene cuatro condiciones:

Ninguna de las cuatro opina sobre si la cotización quedó bonita. Las cuatro se contestan con un sí o un no, y por eso sirven: no hay que discutirlas, hay que correrlas. La tuya se arma igual, con el oficio que sea: escribe lo que hoy revisas a mano antes de mandar cada trabajo.

El patrón, en tres palabras

Textual, de las buenas prácticas de habilidades: «Common pattern: Run validator → fix errors → repeat. This pattern greatly improves output quality» —patrón común: corre el validador, arregla los errores, repite; mejora mucho la calidad de lo que sale—.

La variante sin código: el validador es un documento

Esta es la que te sirve, y la doc la etiqueta así, aparte: la versión para habilidades sin código. Ahí el validador no es un programa, es un archivo —criterios.md, con tus cuatro condiciones, una por renglón— y el chequeo lo hace Claude leyendo y comparando. Dentro de la habilidad se ve así:

## Cómo se revisa

1. Escribe la cotización siguiendo criterios.md
2. Revísala contra la lista:
   - el precio trae el IVA incluido y lo dice
   - el alcance va en viñetas, no en párrafo
   - el plazo trae fecha, no una duración
   - está la cláusula de anticipo
3. Si encuentras algo:
   - anótalo con el renglón exacto
   - corrígelo
   - vuelve a revisar la lista completa
4. No entregues hasta que se cumplan todos los requisitos
5. Entrega

El checklist que se copia y se palomea

Para lo que lleva muchos pasos hay una vuelta de tuerca que se ve poco: en vez de que la lista se quede en el archivo, la habilidad le pide a Claude que la copie dentro de su respuesta y la vaya palomeando conforme avanza. Lo que estaba en un documento pasa a estar en la conversación, y ahí no se le pierde.

• Leí criterios.md completo antes de escribir.
• El precio trae el IVA incluido y el texto lo dice.
• El alcance va en viñetas y dice qué no incluye.
• El plazo trae fecha y está la cláusula de anticipo.

Textual: «For particularly complex workflows, provide a checklist that Claude can copy into its response and check off as it progresses» —para los flujos especialmente complejos, dale un checklist que Claude pueda copiar dentro de su respuesta e ir palomeando conforme avanza—.

Que enseñe la prueba, no que la afirme

«Ya lo revisé» no es una revisión, es una afirmación. La doc lo pide al revés: que muestre la evidencia —la salida del chequeo, el comando que corrió y qué devolvió, o la captura del resultado—. Revisar evidencia es más rápido que volver a verificar tú, y sirve para las corridas que no estuviste viendo.

Cómo se afina: dos sesiones, no una

El mecanismo oficial para mejorar una habilidad es este, y casi nadie lo cuenta: trabajas con una sesión para escribirla y la pruebas en otra distinta. La doc las llama Claude A y Claude B. Lo que Claude B falla vuelve a Claude A como corrección, con el detalle exacto: «cuando usó esta habilidad puso el plazo en semanas y no en fecha», no «quedó mal».

Y esto va antes de escribir de más

La instrucción está en mayúsculas en la propia doc: «Create evaluations BEFORE writing extensive documentation» —crea las evaluaciones antes de escribir documentación extensa—. Primero mides, luego escribes, y escribes solo lo que hizo falta.

• Corre tres cotizaciones reales sin la habilidad y anota en qué falla exactamente. Eso es tu línea base.
• Arma tres escenarios con esos huecos. Tres, no quince: son los que vas a volver a correr cada vez.
• Escribe lo mínimo que haga pasar los tres. Nada más.
• Vuelve a correrlos, compara contra la línea base y ajusta lo que siga sin moverse.

Así la habilidad resuelve problemas que tuviste, no problemas que te imaginaste que ibas a tener. Lo segundo es la forma más común de terminar con un archivo largo que no cambia nada.

Quiero agregarle a mi habilidad [nombre de la habilidad] un chequeo que devuelva pasa o no pasa, para que no me entregue nada sin haberse revisado.

No escribas nada todavía. Primero pregúntame, de una en una:

Cuando algo me sale mal en esta tarea, ¿cómo me entero? ¿Qué es lo primero que veo?
¿Qué me han devuelto corregido, y por qué?
¿Qué reviso yo a mano cada vez, antes de mandarlo?
¿Qué es obligatorio sí o sí, y qué es preferencia mía?

Con mis respuestas:

1. Convierte cada cosa que reviso a mano en una condición que se conteste con sí o no. Nada de "que esté bien escrito": quiero "no usa ninguna palabra de la lista prohibida".
2. Separa las obligatorias de las preferencias, y pregúntame si dudas de dónde va alguna.
3. Escribe las obligatorias en criterios.md, dentro de la carpeta de la habilidad, una condición por renglón, sin explicaciones.
4. Agrega a la habilidad el paso de revisión: leer ese archivo, comparar el borrador contra cada condición, anotar las que fallan con el pedazo exacto del texto que las incumple, corregir y volver a revisar la lista completa.
5. Cierra ese paso con el renglón que lo vuelve obligatorio: no entregues nada hasta que se cumplan todas.
6. Agrega que al entregar me muestre la tabla: cada condición, si pasó, y con qué pedazo del resultado la cumple. Quiero ver la evidencia, no que me digas que revisaste.

Cuando termines, enséñame criterios.md y el paso nuevo, y dime cuál de mis respuestas quedó fuera por no poder contestarse con un sí o un no.

Aquí el bucle se usa como una pieza más de la carpeta. Como mecánica general —qué estándar escribes, quién lo corre turno a turno y quién decide que ya está— tiene su propia guía en Loop de Verificación, y ahí se trata a fondo.

Las cuatro piezas anteriores le enseñan a tu agente qué sabe y cómo trabaja. Estas dos le cambian el alcance: una le da manos para tocar sistemas que hoy vive mirando por encima de tu hombro, y la otra es lo único de toda la carpeta que de verdad obliga.

Van juntas a propósito. En el momento en que tu agente puede escribir en tu CRM o mover un archivo de tu Drive, la frase «por favor nunca toques eso» deja de ser suficiente.

Las manos: cuando copias y pegas, ahí va un servidor

MCP son las siglas de Model Context Protocol. Un servidor MCP es un programa que conecta a Claude con un servicio —tu Drive, tu CRM, tu gestor de tickets— para que lo lea y escriba en él.

Qué cambia cuando está conectado

• Deja de trabajar con la foto que le pegaste y pasa a leer el sistema en vivo, con lo que haya ahí en ese momento.
• Puede escribir de vuelta: crear el borrador, abrir el ticket, actualizar la fila. No solo leer.
• Deja de inventar la estructura de tus datos, porque la ve. El campo se llama como se llama.

Conectar casi no cuesta contexto

Cuánto cuesta exactamente eso, con la cita y el número, está en La carpeta.

El criterio: qué conectas y qué dejas fuera

Que no cueste contexto no significa que puedas conectar todo. El problema real es de elección, no de espacio: con demasiadas herramientas encima, el agente ya no sabe cuál usar.

• Conecta el sistema del que copias y pegas. Ese es el disparador entero, y no hay otro.
• Deja fuera lo que consultas de vez en cuando y a mano. Un servidor que nunca se usa sigue apareciendo en la lista de opciones que el agente tiene que descartar.
• Si dos herramientas conectadas se parecen tanto que tú mismo no sabrías cuál te toca para una petición de las de siempre, ahí tocaste el techo: quita una.

A partir de cuántas herramientas empieza a doler esto, con su cita y su caso completo, es el tercer caso de Cuándo sí se parte en dos. Y son guías prácticas, no leyes: el encuadre ya dejó dicho que esos umbrales se mueven conforme mejoran los modelos.

Dos avisos antes de conectar nada

• Cada servicio pide sus propias credenciales —el ejemplo de la propia doc es un token personal de GitHub— y esas no se escriben en el archivo que compartes con tu equipo. El archivo admite referencias del tipo ${VAR}, y el valor vive en tu máquina como variable de entorno: un dato con nombre que guarda tu sistema y que los programas leen al arrancar. Así el equipo comparte la configuración sin compartir la llave de nadie.
• Un archivo de configuración compartido no conecta solo. La doc lo dice en seco: por seguridad, Claude Code pide aprobación en sesión interactiva antes de usar los servidores de scope de proyecto —los que quedaron declarados en el archivo del proyecto y no en tu configuración personal—. Hasta que alguien la da, el servidor aparece en la lista como pendiente de aprobación, no como conectado.

Ahí ves cuáles conectaron, cuáles piden que inicies sesión y cuáles fallaron. Es el paso que casi nadie hace después de agregar un servidor, y es el que te ahorra media hora preguntándote por qué no lo ve.

Conectar un servicio no es uno de los seis pasos de la corrida, y aquí no se hace: esta sección te deja el criterio y nada más. El paso a paso con capturas, servicio por servicio, está en Conectores de Claude, y lo abres el día que lo necesites.

Las cuatro formas de agregar un servidor y los scopes están en la página de MCP de la doc.

El candado: lo único que de verdad obliga

Esa es la otra mitad de lo que quedó dicho en Quién es: tu CLAUDE.md persuade, y escribir NUNCA en mayúsculas no protege nada. Aquí está la pieza que sí obliga, y es la única de las seis que lo hace.

Si quieres el argumento largo de por qué el texto sugiere y el candado obliga, esa discusión tiene su propia página en Las nuevas reglas del contexto. Lo que sigue aquí es cómo lo escribes sin programar.

El camino corto: una regla de permiso, sin ningún programa

Para lo que más se pide —«este archivo no se toca nunca»— ni siquiera hace falta un hook. Se escribe como una regla de permiso, tres líneas dentro del archivo .claude/settings.json de tu proyecto. No llama a ningún programa: la aplica Claude Code por su cuenta, antes de cada edición. Así se ve el candado sobre el archivo de precios:

{
  "permissions": {
    "deny": ["Edit(tarifas.xlsx)"]
  }
}

Eso es el candado completo. A partir de ahí, cualquier herramienta de edición que intente ese archivo se niega, y no hay conversación que la convenza.

Tres detalles que deciden si funciona

• Escribe la regla como Edit(...) o Read(...). Son las dos únicas formas de ruta que Claude Code consulta: una escrita para Write(...), NotebookEdit(...) o Glob(...) se acepta, avisa al arrancar y nunca se consulta. La revisión de ediciones contra estas reglas pide Claude Code 2.1.208 o más nueva.
• Edit(...) cubre todas las herramientas que editan archivos. Una regla Read(...) también bloquea editar y crear en esa ruta, pero deja fuera la edición de cuadernos, así que para lo que nadie debe cambiar la regla correcta es Edit(...).
• La ruta se escribe con la sintaxis de .gitignore: tarifas.xlsx para un archivo suelto, cotizaciones/** para la carpeta entera. Es el mismo archivo que tu CLAUDE.md declaró como única fuente de precios: si el candado cae sobre otra ruta, crees que lo pusiste y no lo pusiste.

Los patrones de ruta y la lista completa de reglas están en la página de permisos de la doc.

La vía avanzada: el hook vive dentro de la habilidad

Cuando lo que quieres no es «este archivo no se toca» sino «antes de tal acción, revisa tal cosa», ahí sí toca un hook. Tampoco obliga a abrir un settings.json: puede declararse en el frontmatter de la propia habilidad —el bloque de datos que va entre dos líneas de tres guiones, arriba del texto—, en el mismo formato que tendría en un settings.json. Este es el ejemplo de la documentación: una habilidad que, antes de cada comando de terminal, corre su propio guion de seguridad.

---
name: secure-operations
description: Perform operations with security checks
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/security-check.sh"
---

La descripción ya la tiene cualquier habilidad; lo nuevo es el bloque hooks. Y ojo con la última línea: ese security-check.sh no viene con Claude Code ni lo trae la doc, es un guion tuyo que tienes que escribir en la carpeta de la habilidad. Si no quieres escribir ninguno, quédate con la regla de permiso de arriba; si lo quieres, el prompt de abajo le pide a Claude el guion y el bloque juntos.

Dos cosas que conviene saber del hook de habilidad

• Queda registrado el resto de la sesión una vez que la habilidad se invoca —la invoques tú o Claude—, y sigue corriendo en los turnos posteriores, no solo en el turno de la habilidad.
• Si quieres que corra una sola vez, le pones once: true y Claude Code lo quita después de su primera corrida buena. Una corrida que falla, que bloquea o que se pasa de tiempo lo deja en su lugar, así que vuelve a correr en el siguiente evento que le toque.

El menú /hooks no edita nada

Quiero un candado para esta carpeta. No voy a editar JSON a mano: escríbelo tú.

Lo que no debe pasar nunca:
[Descríbelo aquí con tus palabras, en español. Por ejemplo: que se toque el archivo de precios, que se borre nada de la carpeta de clientes, que se publique algo sin que yo lo haya leído antes.]

Cómo lo quiero:
1. Empieza por lo más simple. Si alcanza con una regla deny en el archivo .claude/settings.json, escríbela así y no me armes un hook. Las rutas van como Edit(...) o Read(...).
2. Si de verdad hace falta un hook, declara el PreToolUse en el frontmatter de la habilidad que corresponda antes que en settings.json, y dime por qué la regla de permiso no alcanzaba.
3. Si tu hook llama a un guion, escríbeme también ese guion completo y dime en qué carpeta quedó. No me dejes apuntando a un archivo que no existe.
4. Antes de escribir nada, enséñame la regla o el hook y explícame en una sola frase qué va a bloquear y qué no va a bloquear. Espera mi sí.
5. Cuando ya esté escrito, dime cómo probarlo: qué te pido yo para que el candado salte, y qué debería ver en pantalla cuando salte.
6. Dime también cómo quitarlo: qué líneas borro, de qué archivo, y si hace falta reiniciar la sesión.

No agregues candados que no te pedí. Si mi descripción te queda ambigua, pregúntame antes de decidir por mí.

La lista completa de eventos y de campos está en la página de hooks de la doc, y es la fuente de todo lo de arriba.

Las manos son opcionales: si no copias datos de ningún lado, no conectes nada. El candado no lo es, en el momento en que tu agente puede escribir. Uno cuesta una decisión; el otro, tres líneas que le dictas en español.

Empezar por uno no es una regla moral, es el punto de partida. Llega un momento en que dejas de tener uno, y no tienes que adivinar cuándo: Anthropic nombró tres casos, y son tres, no una lista abierta. Abajo va cada uno con su señal, lo que cobra cruzar la línea, y a qué guía irte si el tuyo es uno de ellos.

Los tres casos, uno por uno

Las tres señales del caso 3 salen del mismo post de enero de 2026; la cita de los juegos de herramientas inflados es de Effective context engineering for AI agents, del 29 de septiembre de 2025.

Cruzar la línea cuesta tokens —de tres a diez veces más para la misma tarea—, y qué significa eso en tu límite semanal está arriba, en el encuadre. Lo que no está ahí es el peaje de abajo, que se cobra aunque nunca llegues a usar el subagente.

La pregunta que va antes de partir

Antes de abrir un subagente hay una pregunta más barata, y la trae la propia documentación: ¿lo que quieres es un encargo aislado, o es algo que vas a repetir? Si es lo segundo, hay una pieza que corre en la conversación de siempre y no arranca en blanco.

Dónde va cada cosa, según la doc

Lo que ni Anthropic ha cerrado

Eso lo escribió Anthropic al cerrar su investigación sobre agentes que trabajan durante horas, y en el mismo párrafo dice que le parece razonable que agentes especializados hagan mejor su parte. Así que la postura de esta guía es de orden, no de bando: uno primero porque es más barato de mantener y de corregir, y el segundo cuando puedas nombrar cuál de los tres casos es el tuyo. Si ya lo puedes nombrar, no estás rompiendo nada.

Si tu caso es uno de los tres, aquí sigue

Las cuatro figuras que pueden tomar varios agentes —abanico, debate, consenso y orquestador— están en Formaciones de agentes, con lo que cuesta cada una.

Repartir el trabajo entre varios y después revisarlo es el tema entero de Orquesta con Claude.

Y cuando esto pasa a ser un servicio que le cobras a alguien, el patrón de tres capas está en Ecosistema de agentes.

Si puedes nombrar tu caso, ya no estás partiendo por default, y eso era todo lo que esta sección tenía que dejarte.

Esto es el mapa de salida. Cada paso enlaza directo a su prompt, así que puedes correr los seis desde aquí: seis prompts, en el orden en que se corren, y en una frase qué tienes en la carpeta al terminar cada uno.

Ninguno toma más de veinte minutos. Los dos últimos ni siquiera se hacen el primer día: se hacen cuando aparece su disparador.

Los seis prompts, en orden

Del uno al cuatro se hacen de corrido, en una sesión. El cinco y el seis, el día que aparece su motivo, y no antes.

La conexión por MCP no está en esa lista a propósito: no es un paso del primer día, sino algo que agregas cuando la necesites, el día que te descubras copiando datos de una pestaña para que Claude los vea. Cómo se hace está en 08 · Las manos y el candado, junto al candado.

Cómo sabes que ya está

No hay una pantalla que te felicite. Las señales de que la carpeta funciona son estas cuatro, y se notan en el uso diario:

• El agente menciona cosas de tu oficio que no le dijiste en ese mensaje: el nombre de tu formato, tu regla del IVA, el cliente que siempre pide dos versiones.
• No te vuelve a preguntar lo que ya está escrito. Si sigue preguntando, es que esa respuesta vive en tu cabeza y no en la carpeta.
• Cuando entrega, enseña con qué evidencia cumplió: qué revisó, contra qué, y qué le dio pasa o no pasa.
• Cuando falla, falla igual dos veces. Un error que se repite idéntico te dice exactamente qué línea agregar; uno que cambia cada vez significa que todavía falta contexto, no una regla.

Así queda la carpeta, terminada

Esta es la carpeta del despacho que manda cotizaciones, el mismo ejemplo que recorre la página, cuando los seis pasos ya corrieron. Cinco archivos de texto, ninguno se instala, y cada uno guarda una cosa distinta:

despacho/
├── CLAUDE.md                 quién eres y cómo cotizas
└── .claude/
    ├── settings.json         la regla que niega tocar precios
    └── skills/
        └── cotizar/
            ├── SKILL.md      los pasos de una cotización
            ├── examples.md   tres cotizaciones tuyas reales
            └── criterios.md  las condiciones de bien hecha

habilidades-candidatas.md     la lista que salió de la entrevista;
                              lo que todavía no has construido

Eso es todo lo que hay, más la lista de pendientes que te dejó la entrevista. Si mañana algo de lo que entrega te sigue sin gustar, el archivo que hay que abrir ya tiene nombre: el dato que le faltó va en CLAUDE.md, el paso que se saltó va en el SKILL.md, y la condición que nadie revisó va en criterios.md.

The Architect, honestamente

The Architect es un plugin —un paquete que le agrega comandos y subagentes a Claude Code—, con licencia MIT, en su versión 2.5.0. Contado archivo por archivo el 18 de septiembre de 2026: 6 comandos, 3 subagentes, 14 formas de proyecto, una entrevista de 4 fases (Discovery, Deep dive, Architecture y Generate) y un plano de 20 secciones, con criterio de aceptación y comando de verificación en cada paso.

Cuándo sí, que es donde de verdad sirve

Llega un día en que lo que necesitas ya no es que alguien te ayude a trabajar: es un programa. Una app, un sitio, una automatización con su base de datos y su forma de cobrar. Ese día le pasas el proyecto y te devuelve el plano con el que otro Claude construye sin volver a preguntarte nada.

Aparta el rato antes de arrancarlo. El repo pone la entrevista completa en 40 a 60 minutos, y la fase 4 —la generación, después de que confirmas la arquitectura— en 20 a 30 minutos para un paquete y 10 a 15 para un archivo suelto, sin imprimir nada en pantalla mientras corre. El propio repo obliga a avisarlo antes de empezar: «A user who was not warned does not experience that as thorough. They experience it as hung…» — quien no fue advertido no lo vive como minuciosidad, lo vive como si se hubiera colgado. Déjalo correr, y cuenta con que ese rato continuo se come tu límite semanal más rápido que una tarde de mensajes cortos.

Se instala con dos comandos, dentro de Claude Code y no en la terminal. El primero agrega el marketplace, que es el catálogo desde el que Claude Code baja plugins; el del autor se llama soyenriquerocha, y por eso el segundo comando lleva ese nombre después del arroba.

Van en ese orden: el segundo falla si el primero no corrió.

El código está abierto y puedes contar los archivos tú: Hainrixz/the-architect en GitHub.

Y si quieres el recorrido largo —los seis comandos, qué hace cada fase y cómo se lee el plano—, está en la guía de The Architect.

Cierra la página aquí y abre tu carpeta. La primera versión cabe en veinte minutos, y la segunda la escribe el primer error que se repita.