De SOP a Agente en 20 minutos: cómo estructuro las carpetas de mis skills de Claude Code

Cuando empecé a construir skills para agentes, todo vivía en un solo archivo SKILL.md. Funciona bien para los simples. Pero apenas un skill empieza a manejar un proceso de varios pasos, ese archivo único se convierte en un muro de texto difícil de mantener, difícil de iterar, y — lo más caro — difícil de procesar para el agente con eficiencia. Cada vez que invocas el skill, el agente carga el archivo entero, aunque la mayoría del contenido no aplique al paso en el que estás.

Esta semana tomé una clase corta sobre cómo estructurar skills. La idea, en una imagen:

mi-skill/
  SKILL.md
  steps/
    paso-1-hacer-la-cosa.md
    paso-2-hacer-la-siguiente.md
  references/
    credenciales.md
    voz-de-marca.md
    ejemplos.md
  scripts/
    deploy.py
    sync.sh

Para qué sirve cada carpeta

SKILL.md es el índice. Describe qué hace el skill, lista los pasos en orden y apunta a cada archivo. El agente lee este primero para entender el flujo completo, y luego abre cada paso conforme llega a él.

steps/ guarda un archivo markdown por paso. Cada archivo contiene las instrucciones completas de esa parte del proceso — qué hacer, qué llamadas API, qué cuidar. El agente lee cada paso solo cuando llega a él, así que no carga todo el pipeline en contexto al mismo tiempo.

references/ guarda material de soporte que el skill necesita — credenciales API, voz de marca, esquemas de datos, ejemplos. Estos se leen cuando un paso los referencia, no de entrada.

scripts/ guarda código que el agente puede ejecutar — TypeScript, Python, shell. Algunos skills no necesitan esto.

El beneficio es el mismo que en código modular: puedes reordenar pasos, saltarte uno, correr un solo paso aislado, o agregar pasos nuevos sin tocar nada más. Cuando algo se rompe, sabes exactamente qué archivo abrir. Y el agente no carga el proceso completo en su ventana de contexto — lee lo que necesita cuando lo necesita.

Si tu archivo de skill se está poniendo largo y pesado, esa es la señal. Pártelo.

Cómo lo aplicamos en nuestros propios agentes

Tomar la idea no sirve de nada si no la pasas al inventario real. En nuestro ~/.claude/skills/ tenemos más de 50 skills. Los nuestros (los que escribimos para operar GNB Labs y gabrielneuman.com) son seis:

Skill	Líneas en SKILL.md (antes)	Estado
naira	56	Ya modularizado (tiene skills/, templates/, docs/, scripts/)
assessment	451	Monolítico — refactorizado hoy
cotizar	382	Monolítico — siguiente
idea	297	Monolítico — borderline
session-management	95	Suficientemente chico
elias	53	Suficientemente chico

naira ya seguía el patrón sin que yo lo formalizara. assessment era un proceso de 8 pasos en 451 líneas — el caso de libro para aplicar la estructura. La paradoja: el agente lo cargaba completo cada vez que lo invocaba, aunque el paso 7 (guardar en MongoDB) no aplica hasta minutos después de empezar.

El antes y el después de assessment

Antes:

assessment/
  SKILL.md   # 451 líneas: identificar reunión, leer transcript,
             # extraer pain points, generar reporte, guardar,
             # publicar URL — todo junto en un muro

Después:

assessment/
  SKILL.md                                # ~70 líneas: índice + links
  steps/
    1-identificar-reunion.md
    2-resolver-vinculos-crm.md
    3-leer-transcript.md
    4-extraer-pain-points.md
    5-estructurar-payload.md
    6-confirmar-con-usuario.md
    7-guardar-mongodb.md
    8-reportar-al-usuario.md
  references/
    schema-payload.md                     # esquema de Mongo (no cambia)
    tools-catalogo.md                     # catálogo de herramientas con costos
    reglas-tono.md                        # reglas de voz, cuadrantes, coherencia
    ejemplo-conversacion.md               # flujo end-to-end de ejemplo
  scripts/
    create-assessment-template.ts         # template TypeScript reusable

SKILL.md quedó en ~70 líneas: descripción, mapa de los 8 pasos, links a referencias. Los pasos se leen on-demand. La voz de marca, el catálogo de herramientas y el esquema de Mongo viven en references/ — material que casi nunca cambia, separado del flujo. Y los scripts dejaron de ser bloques de código embebidos en markdown.

Por qué esto mejora la calidad de tus agentes

No es estético. Es una mejora en cuatro dimensiones medibles:

1. Menos contexto cargado al inicio = menos alucinación. Cuando el agente ve solo el índice y el paso actual, tiene foco. Cuando ve 451 líneas mezcladas, atiende cosas que no aplican y se le pasan detalles que sí.
2. Iterar es barato. Si quiero ajustar cómo se cuadran los ROI, abro steps/5-estructurar-payload.md o references/reglas-tono.md. No releo 451 líneas para encontrar la sección.
3. Los scripts dejan de ser markdown. Un .ts con tipos vivos vale más que un bloque de código pegado en un .md que nunca se ejecuta solo.
4. El skill se vuelve auditable. Cada paso es un archivo. Si algo sale mal, sé exactamente qué releer y qué cambiar.

Reglas que voy a aplicar de aquí en adelante

Después de hacer el ejercicio con assessment, estas son las reglas duras:

1. Si SKILL.md pasa de 200 líneas, partirlo. Es la regla práctica.
2. SKILL.md es índice, no contenido. Describe el skill, lista pasos, apunta a archivos. Si tiene instrucciones detalladas, va a steps/.
3. Un paso = un archivo. No mezclar dos pasos en un mismo archivo "porque son cortos".
4. Lo que no cambia va a references/. Voz de marca, esquemas de DB, plantillas de prompt. Si el agente lo va a leer raro vez, no merece estar en el flujo principal.
5. Código embebido se vuelve script. Si llevo más de 20 líneas de código dentro de un bloque markdown, mejor un archivo .ts o .sh aparte.
6. Cualquier skill nuevo nace con esta estructura. Aunque empiece con un solo paso, ya creo steps/.

De SOP a Agente Prompt: el prompt que puedes usar tú

La gran ganancia operativa viene cuando dejas de escribir SOPs en Notion para humanos y los conviertes en agentes. Pero la transición no es copiar y pegar el SOP en un prompt — es reestructurarlo para que el agente lo ejecute paso por paso, lea solo lo que necesita, y use herramientas externas cuando le toque.

Aquí va el prompt que uso para convertir un SOP existente (o crear uno nuevo) en un skill estructurado. Funciona en Claude (Code o Claude.ai), en ChatGPT con o1/Pro, y en Cursor:

ROL
Eres un arquitecto de agentes. Tu trabajo es convertir el SOP, la documentación
o la descripción de proceso que te voy a pegar en un Claude Code skill
modular siguiendo esta estructura:

  mi-skill/
    SKILL.md
    steps/<n>-<slug>.md    (un archivo por paso)
    references/<tema>.md   (lo que no cambia: esquemas, voz, catálogos)
    scripts/<nombre>.ts    (código ejecutable, no embebido en markdown)

REGLAS DURAS
1. SKILL.md = índice máximo 100 líneas. Frontmatter con `name` y
   `description` (una oración con triggers de uso). Lista numerada de
   pasos con links relativos. Lista de referencias con links. Nada
   de instrucciones detalladas en SKILL.md.
2. Un paso = un archivo. Cada paso describe qué hacer, qué inputs
   espera, qué outputs produce, y qué decisión tomar al final
   ("si X, ir al paso Y; si no, preguntar al usuario").
3. references/ guarda lo que NO cambia con cada ejecución: esquemas
   de datos, reglas de tono, catálogos, plantillas, ejemplos. El
   contenido que el agente va a consultar raro vez vive aquí.
4. Los bloques de código de >20 líneas se mueven a scripts/ con
   tipos y comentarios. SKILL.md y steps/ no llevan código embebido,
   llevan instrucciones que apuntan al script.
5. Pregúntame antes de inventar valores que no estén en el SOP
   (credenciales, costos, esquemas). Si el SOP no lo dice, márcalo
   como "[FALTA: pregunta al usuario]".
6. Idioma: español de México (sin voseo, sin "vos/tenés/podés").
   Tono directo. Sin "vamos a empoderar", sin "sinergia", sin relleno.

ENTREGABLE
Devuelve, en este orden:
  - SKILL.md completo
  - Cada steps/<n>-<slug>.md como archivo separado
  - Cada references/<tema>.md como archivo separado
  - Cada scripts/<nombre>.ts como archivo separado
  - Al final: una tabla con el mapeo "sección del SOP original →
    archivo en el skill" y una lista de huecos que detectaste
    ("[FALTA: ...]")

ANTES DE GENERAR
Hazme primero estas 3 preguntas y espera mi respuesta:
  1. ¿Cuál es el trigger del skill (qué frases del usuario lo invocan)?
  2. ¿Qué herramientas externas usa el skill (Mongo, Linear, Slack,
     Stripe, APIs, scripts locales)?
  3. ¿Hay un paso donde el agente DEBE pausar y pedir confirmación al
     usuario antes de continuar (cobros, mensajes públicos, escrituras
     destructivas)?

INPUT (pega tu SOP aquí abajo)
---
[PEGA AQUÍ EL SOP, DOCUMENTACIÓN, NOTAS DE LOOM, O DESCRIPCIÓN DEL PROCESO]

Pegas el SOP. El agente te hace 3 preguntas. Le respondes. Te entrega el skill modularizado.

Tip: si tienes un Loom o una transcripción de cómo haces el proceso a mano, eso vale más que un SOP redactado. Pega la transcripción cruda — el agente extrae mejor los pasos reales que los pasos idealizados.

Versión empaquetada: /agentiza

Para no tener que copiar-pegar el prompt cada vez, lo empaqueté como skill global en ~/.claude/skills/agentiza/. Ahora invoco /agentiza, pego el SOP o el SKILL.md viejo, y el skill ejecuta el flujo completo: las 3 preguntas, el mapeo de pasos, la separación de referencias y scripts, los huecos detectados, y los archivos listos para copiar.

El skill mismo está construido siguiendo el patrón que enseña — SKILL.md como índice, 6 pasos en steps/, 3 referencias (reglas duras, idioma y tono, anti-patrones), y 3 templates (SKILL.md.tpl, step.md.tpl, reference.md.tpl). Es el skill que crea otros skills.

Dogfooding: /reutiliza creado en 20 minutos

Apenas terminé de empaquetar /agentiza, lo probé con un caso real. Tenía un SOP en la cabeza que llevaba meses sin escribir: "cada vez que publico un blog o newsletter, debería sacar 1 LinkedIn + 5 X posts + 1 hilo + 5 IG + 5 insights + 1 newsletter". Sabía qué quería pero no lo había aterrizado.

Le dije a /agentiza: "crea skill nuevo para repurposing, este es el SOP". El skill hizo lo que estaba diseñado para hacer:

1. Identificó el modo (SOP nuevo, no modernizar uno viejo).
2. Hizo las 3 preguntas guiadas: trigger ("/reutiliza url-contenido"), herramientas externas (MongoDB en gnbsite), pausa de aprobación (no, escribe directo y alguien revisa después en el Content Factory).
3. Investigó el repo antes de inventar — encontró que /cms ya existe como Content Factory, descubrió que la colección cms_ideas ya está montada, leyó los tipos válidos en lib/cms/types.ts y vio que faltaban x, instagram, parentId, y un tipo nuevo para "insights sueltos para futuros newsletters".
4. Marcó los huecos como [FALTA] — no inventó schema. Me los reportó y me preguntó qué hacía: agregar tipos al CMS, o reutilizar tipos existentes con un campo plataformas.

En total fueron tres mensajes de ida y vuelta para tomar decisiones de schema. Después escribió:

~/.claude/skills/reutiliza/
  SKILL.md                              # ~50 líneas, índice
  steps/
    1-identificar-fuente.md
    2-extraer-mensaje-principal.md
    3-cargar-voz-de-marca.md
    4-generar-piezas.md
    5-validar-tono.md
    6-escribir-mongodb.md
    7-reportar-al-usuario.md
  references/
    piezas-spec.md                      # spec por pieza con longitud y estructura
    checklist-tono.md                   # anti-voseo, frases prohibidas, hooks
    schema-cms-ideas.md                 # schema con parentId + tipos nuevos
  scripts/
    create-repurposed.ts                # script ejecutable parametrizable

Y los cambios al CMS de gnbsite: 4 templates YAML nuevos (x.yaml, x-thread.yaml, instagram.yaml, newsletter-insights.yaml), tipos extendidos en lib/cms/types.ts, y campo parentId?: string agregado al Idea schema.

Tiempo total: ~20 minutos. La mayoría se fue investigando el repo y discutiendo decisiones de schema, no escribiendo markdown. Sin /agentiza me hubiera tardado una tarde entera y el skill habría nacido como muro de 400 líneas.

Lo más importante: el skill nació modular desde el día 1. No tendré que refactorizarlo en 3 meses cuando duela.

Lo que sigue

cotizar (382 líneas) e idea (297) son los próximos en migrar — con /agentiza ahora es trivial. La meta: que cualquier skill nuevo nazca con esta estructura, y que los viejos migren cuando los toque por otra razón.

Y este artículo va a ser el primer test real de /reutiliza. Cuando lo publique, voy a invocar /reutiliza https://www.gabrielneuman.com/blog/estructura-carpetas-skills-claude-code y el skill va a sembrar 14 ideas hijas en cms_ideas para que el Content Factory las recoja. Ya sabes qué hacer si las ves aparecer en el inbox.

La modularidad no es un capricho de orden. Es ancho de banda. Cada línea innecesaria que el agente carga al inicio es contexto que no usa para resolver tu problema. Si construyes skills para tu agente, parte el archivo. La señal es simple: si te da flojera abrirlo, también le da flojera al agente leerlo.