🌱 Del intent al primer borrador
Captura lo que la persona quiere, investiga lo suficiente y conviértelo en un SKILL.md que desde el inicio esté bien escrito: en imperativo, con el porqué y sin MUSTs a gritos.
Antes de escribir una sola línea, skill-creator hace 4 preguntas: qué permite hacer la skill en Claude, cuándo debe activarse, cuál es el formato de salida esperado y si conviene preparar test cases.
La mayoría de las skills deficientes nace de una intención mal definida. Si la conversación ya contiene el workflow ("convierte esto en una skill"), extrae primero la información de los mensajes y pide solo lo que falte.
qué habilita · cuándo se activa · formato de salida · ¿necesita pruebas? · confirmar antes de continuar
Pregunta de forma proactiva sobre casos límite, formatos de entrada y salida, archivos de ejemplo, criterios de éxito y dependencias. Investiga en paralelo mediante subagentes cuando haya MCP útiles.
Llegar con el contexto preparado reduce la fricción para el usuario. Escribe los prompts de prueba solo después de cerrar esta parte: una entrevista mal hecha genera una skill que cubre el caso ideal y falla en el resto.
casos límite · formatos de entrada/salida · archivos de ejemplo · criterios de éxito · dependencias · investigación paralela
A partir de la entrevista, completa name (identificador), description (activador: qué hace Y cuándo usarla) y el cuerpo en Markdown con las instrucciones. Todo "cuándo usarla" va en la description, no en el cuerpo.
La description es el mecanismo principal de activación. Como Claude tiende a activar poco las skills, debe ser un poco insistente: enumera contextos concretos en los que debería intervenir incluso si el usuario no lo pide explícitamente.
name · description insistente · qué + cuándo · cuerpo <500 líneas · compatibilidad (rara)
Escribe en imperativo, usa theory of mind, explica por qué cada instrucción está ahí en vez de acumular MUSTs en mayúsculas y mantén la skill general en lugar de ceñirla a los ejemplos.
Los LLM actuales son inteligentes: si les explicas el porqué, van más allá de la instrucción mecánica y resuelven el caso real. ALWAYS/NEVER en mayúsculas es una señal de alerta: reformula explicando la razón.
imperativo · theory of mind · explicar por qué · evitar MUSTs · skill general, no específica
Escribe un primer borrador sin trabarte; después, vuelve a leerlo con ojos nuevos y mejóralo. Borrador → revisar → mejorar es un ciclo dentro de la propia escritura.
El primer borrador casi nunca es el mejor. Volver a leerlo con distancia revela instrucciones redundantes o ambiguas, o que hacen que el modelo pierda tiempo innecesariamente.
borrador rápido · releer con distancia · eliminar redundancias · claridad · iterar en la escritura
Decidir cuándo extraer recursos del SKILL.md: si 3 ejecuciones repiten el mismo script, conviértelo en scripts/; los docs grandes van a references/ se cargan a pedido.
Progressive disclosure: metadata siempre en el contexto, cuerpo cuando se activa, recursos solo cuando hacen falta. Empaquetar un script repetido ahorra reinventar la rueda en cada invocación futura.
scripts/ · references/ · assets/ · divulgación progresiva · regla de las 3 repeticiones · TOC en docs >300 líneas
🔁 Probar, evaluar e iterar
El corazón del ciclo: prompts de prueba realistas, ejecutar con-skill vs baseline, evaluar de forma cualitativa y cuantitativa, generalizar a partir del feedback y optimizar la description según la métrica de prueba.
Después del borrador, crea 2-3 test prompts realistas —el tipo de cosas que escribiría un usuario real— y muéstraselos al usuario para que los valide antes de ejecutarlos.
Los test prompts artificiales generan evaluaciones engañosas. Los prompts están en evals/evals.json sin assertions todavía — las assertions vienen después, mientras las runs están en marcha.
2-3 prompts · lenguaje de un usuario real · validar con el usuario · evals.json · todavía sin assertions
Para cada test case, lanza dos subagents en el mismo turno: uno con la skill y otro sin ella (baseline). Lánzalos todos de una vez para que terminen juntos.
Sin baseline no sabes si la skill aportó algo. Para una skill nueva, baseline = ninguna skill. Para una skill existente, baseline = la versión anterior (snapshot antes de editar).
with_skill · without_skill · mismo turno · snapshot de la versión anterior · workspace por iteración
Evaluar en dos frentes: cualitativa (revisar los resultados en el visor) y cuantitativa (aserciones verificables que generan un pass_rate). Las skills subjetivas se evalúan solo cualitativamente.
Las buenas aserciones son verificables objetivamente y tienen nombres descriptivos. No fuerces aserciones en aspectos que requieren criterio humano (estilo de escritura, diseño).
evaluación cualitativa en el visor · assertions verificables · pass_rate · nombres descriptivos · no sobreajustar a lo subjetivo
Generalizar a partir del feedback en vez de sobreajustarse poco a poco a los pocos ejemplos, mantener el prompt conciso y leer los transcripts (no solo los outputs finales).
La skill se usará un millón de veces en distintos prompts. Si solo funciona con los ejemplos de la prueba, es inútil. Evita cambios fiddly y MUSTs opresivos.
generalizar · no sobreajustar · mantener conciso · leer transcripts · explicar el porqué · un script repetido se convierte en un bundle
Aplicar la mejora → volver a ejecutar todos los casos de prueba en una nueva iteración → revisar con el usuario → leer los comentarios → repetir hasta satisfacerlo.
El ciclo termina cuando el usuario está satisfecho, todo el feedback está vacío o ya no logras avances significativos. Cada iteración va en un directorio propio.
aplicar → volver a ejecutar → revisar → repetir · iteration-N · previous-workspace · criterios para detenerse
Generar ~20 consultas de activación (mezcla de should-trigger y should-not-trigger), enfocarse en los near-misses, ejecutar el ciclo de optimización y elegir la descripción según la métrica del conjunto de prueba.
La description decide si se activa la skill. Los negativos obvios no prueban nada — los más valiosos son los near-misses que comparten palabras clave, pero necesitan otra cosa.
20 queries · should-trigger / should-not · near-misses · 60% train / 40% test · best_description según el test
⭐ Las mejores meta-skills (para crear skills)
Las herramientas de quienes CREAN skills: skill-creator (246k), find-skills (1,8M) y el patrón de scaffolding. Qué hace cada una, cuándo usarla y dónde encaja en el flujo.
Skill cuyo trabajo es ayudarte a trabajar con otras skills: descubrirlas, crearlas, probarlas, optimizarlas y empaquetarlas. Actúa un nivel por encima de la skill común.
Mucha gente crea sin comprobar si ya existe algo mejor y sin el ciclo de evals. Las meta-skills resuelven esto: descubrir antes, crear con método y validar con datos.
meta-skill · descubrir · crear · probar · optimizar · empaquetar
La meta-skill de Anthropic que orquesta todo el ciclo —draft → eval → iterate— e incluye un optimizador de description independiente.
Es el eje central del flujo de creación. Todo lo de los módulos 4.1 y 4.2 parte de ella; no improvises un proceso paralelo.
borrador → evaluación → iterar · scripts · aggregate_benchmark · run_loop · package_skill
La skill más instalada del catálogo (1.802.925, vercel-labs). Descubre skills relevantes para una tarea antes de que la crees desde cero.
Evita el error más costoso de quien crea: pasar horas escribiendo algo que ya existe y funciona mejor. Es el paso cero del flujo.
descubrimiento · usar / extender / crear · etapa cero · catálogo de 39.366 skills
Forma estándar de generar el esqueleto inicial — SKILL.md con frontmatter y las carpetas scripts/, references/, assets/ — en vez de escribirlo todo a mano.
Acelera el comienzo y evita la página en blanco. Pero crea solo las carpetas que vas a usar: las carpetas vacías confunden al modelo y violan la regla de "mantenerlo conciso".
esqueleto · frontmatter rellenado previamente · no crear todo de antemano · recortar boilerplate
La secuencia que evita retrabajo: find-skills (descubrir) → scaffolding (generar la base) → skill-creator (crear e iterar) → optimizador de description (afinar el disparador).
Las tres no compiten, se encadenan. Usarlas fuera de orden es donde nacen las skills con menos de 100 instalaciones.
descubrir → base → crear/iterar → optimizar → empaquetar · regla de oro
Un resumen de situación → herramienta: "necesito una skill para X" → find-skills; "voy a crearla" → skill-creator; "no se activa cuando debería" → optimizador de description.
Decisión rápida en el momento adecuado. Instala las tres y, como Claude tiende a activarlas menos de lo debido, menciónalas explícitamente las primeras veces hasta que se vuelva un reflejo.
situación → meta-skill · instalar las tres · pro tip para activarla · package_skill
🛠️ Cómo crear: recorrido completo con evals
Un ejemplo completo y detallado: intent (4 preguntas) → draft → test prompts → evals.json con assertions verificables → ejecución con-skill vs baseline → iteración. Plantillas JSON listas.
Las 4 preguntas aplicadas al caso «margem-xlsx»: qué habilita, cuándo se activa, formato de salida y si vale la pena probarla. Resultado verificable → vale la pena probarla.
La pregunta 4 decide el resto del walkthrough. Las transformaciones de archivos y la generación de código merecen evals; el estilo y el arte, no.
habilita · cuándo se activa · formato · vale la pena probar · extraer de la conversación · confirmar
Escribe el borrador completo: name, una description contundente (qué hace Y cuándo usarla) y el cuerpo en imperativo explicando por qué.
La description es el activador. "Modifica hojas de cálculo" se activa poco; enumerar verbos + contextos ("margen, ganancia... incluso sin pedir una columna") cubre los near-triggers.
name · description insistente · cuerpo imperativo · explicar por qué · no adivinar columnas
2-3 prompts como los escribiría un usuario real — con contexto, rutas y detalles — guardados en evals/evals.json, todavía sin assertions. Plantilla JSON lista.
Los prompts artificiales generan evaluaciones engañosas. Valida con el usuario antes de ejecutar: es barato y evita ejecutar todo en vano.
2-3 prompts · lenguaje real · rutas y contexto · evals.json · validar antes
Mientras se ejecutan las runs, escribe assertions objetivas y con nombres descriptivos en eval_metadata.json; verifícalas con un script, de preferencia. Hay una plantilla lista.
"la hoja de cálculo quedó bien" es subjetivo; "los valores coinciden con (C-D)/C" se puede verificar y permite distinguir with_skill de baseline.
afirmaciones verificables · nombre descriptivo · comprobadas por script · discriminan · no subjetivas
Dos subagents en el mismo turno por caso de prueba (con skill / sin skill = baseline), salida organizada por iteración y eval, con total_tokens y duration_ms en timing.json.
Iniciarlos al mismo tiempo evita sesgos. El timing solo se puede capturar cuando llega la notificación: procesa cada una en el momento.
with_skill / without_skill · mismo turno · workspace por iteración · timing.json
Timeline numerada: califica cada run → agrega el benchmark → abre el viewer antes de juzgar → lee el feedback y generaliza → vuelve a ejecutar en iteration-2.
En este caso, las 3 ejecuciones escribieron un calc_margem.py casi igual: una señal de que conviene incluirlo. En la iteración 2, el pass_rate subió y los tokens bajaron.
grading.json · aggregate_benchmark · generate_review · feedback · bundle de script repetido
🚀 Consejos avanzados: optimización de la descripción y benchmarking
El ciclo de optimización (división 60/40, near-misses, best_description según el test score), cómo funciona realmente el triggering, blind comparison y cómo leer el benchmark sin engañarte.
run_loop.py divide el eval set en 60% train / 40% test, evalúa la description (3 runs por query), propone mejoras basadas en lo que falló y vuelve a evaluar, hasta 5x.
La activación es estocástica; 3 ejecuciones dan una tasa de activación estable. Usa el model ID de la sesión para que la prueba coincida con lo que experimenta el usuario.
run_loop · 60/40 · 3 runs/query · proponer → reevaluar · model ID de la sesión · en segundo plano
~20 consultas realistas, la mitad should-trigger y la otra mitad should-not. Lo más valioso está en los casos límite: frases que comparten palabras, pero requieren otra cosa.
"Margen de error de una investigación" usa "margen", pero no se refiere a las ganancias en una hoja de cálculo — obliga a la descripción a discriminar. Los negativos obvios no enseñan nada.
should-trigger 8-10 · should-not 8-10 · casi coincidencias · evitar las obvias · trigger-eval.json
Las skills aparecen en available_skills con name + description, y Claude decide consultarlas, pero solo las consulta para tareas que no puede resolver fácilmente por su cuenta.
"Lee este PDF" puede no activarse ni siquiera con una descripción perfecta. Tus consultas de prueba deben ser sustanciales (de varios pasos y especializadas).
available_skills · solo tareas no triviales · consultas sustanciales · activación insuficiente · insistente
Darle dos resultados a un agente independiente sin decirle cuál es cuál, dejar que juzgue la calidad y luego analizar por qué ganó el elegido.
Por ser ciego, no favorece «lo nuevo» solo por ser nuevo. Es opcional y requiere subagents: guárdalo para cuando la duda sea costosa.
anonimizar · evaluar la calidad · por qué ganó · opcional · subagents · basta con revisión humana
El benchmark incluye pass_rate, tokens y tiempo por config, con promedio ± desviación y delta. La pasada de analista revela lo que el promedio oculta.
Una aserción que pasa con Y sin la skill no mide nada e infla el pass_rate; una desviación alta puede ser flaky; un pass_rate alto puede ocultar una explosión de tokens.
pass_rate · delta · no discriminante · varianza/flaky · costo de tokens/tiempo
Toma el best_description (elegido por el test score, no por el train), aplícalo en el frontmatter, muestra el antes y el después, y empaquétalo con package_skill.
Elegir según el train premiaría la description que memorizó los ejemplos. El held-out test simula el mundo real: es lo que distingue la generalización de destacar solo en el laboratorio.
best_description · test score > train · optimizar solo cuando esté lista · revisar el eval set · package_skill
Mapa de la ruta
Pregunta, investiga, escribe. Un borrador que desde el inicio use el imperativo y explique el porqué.
Ejecuta, mide, generaliza. El ciclo que convierte un borrador en una skill que funciona un millón de veces.
find-skills descubre, skill-creator crea, scaffolding genera la base. Las herramientas de quienes crean skills.
Del intent a evals.json con assertions. Un ejemplo completo, de principio a fin, con JSON listo para copiar.
Split 60/40, casos casi acertados, best_description según el test. Ajusta el disparo y lee el benchmark sin engañarte.