Elites Skills Architect

Convierte una idea aproximada en un skill que funciona: descubrimiento, especificación, validación, ejecuciones de prueba, revisión humana, ajuste de descripción y empaquetado. Cada afirmación sobre un skill está respaldada por un script o una ejecución evaluada, no por leerlo una vez y sentirse bien al respecto.

Por dónde empezar

Ocho etapas. Encuentra dónde está el usuario y comienza allí:

Descubrimiento: obtener un problema concreto y los datos necesarios para escribir la especificación
Detectar problemas: demasiado simple, demasiado amplio, superposiciones, contradicciones
Categorizar: creación de documentos, automatización de flujos de trabajo o mejora de MCP
Construir y validar: frontmatter, cuerpo, carpeta, evaluaciones, scripts/validate_spec.py
Probar y revisar: ejecutar las evaluaciones, mostrar los resultados, calificarlos, poner a prueba cualquier regla que el skill imponga
Mejorar: corregir el patrón detrás de la retroalimentación, no el caso aislado
Ajuste de descripción: pruebas de activación y scripts/optimize_description.py
Empaquetar: scripts/package_skill.py

Ajusta tu ritmo al usuario. Alguien que dice "servidor MCP" y "frontmatter" sin que se lo pidan quiere rapidez. Alguien que dice "Quiero que Claude haga mis facturas" quiere que lo guíen una pregunta a la vez. Español claro, sin jerga que ellos no hayan usado primero.

Todos los scripts son Python 3.9 o superior de la biblioteca estándar, se ejecutan desde la raíz del skill:

cd <ruta-a-elites-skills-architect>
python3 scripts/validate_spec.py <carpeta-del-skill>

Etapa 1: Descubrimiento

Lee references/discovery-questions.md para el banco de preguntas y las preguntas de seguimiento para respuestas débiles. Pregunta en lotes de dos o tres, basa las respuestas, nunca vomites la lista.

Lote 1, problema: el único resultado que el skill debe producir; de 5 a 10 frases que los usuarios dirían realmente; lo que el skill NO debe manejar. Lote 2, datos: entradas y su formato; qué tiene el usuario cuando funcionó; qué suele salir mal con la entrada. Lote 3, flujo de trabajo: orden de los pasos; dependencias; caminos si/entonces; qué pasa con los pasos 1 y 2 cuando el paso 3 falla. Lote 4, integraciones: servidores MCP, APIs, funciones integradas de Claude, autenticación y límites de tasa. Lote 5, resiliencia: los tres fallos de ejecución más probables; el mensaje en fallo total.

Deja de preguntar cuando puedas hacer las cuatro sin adivinar: escribir la descripción con frases de activación reales, enumerar cada paso en orden, nombrar tres modos de fallo con su manejo, y explicar el skill lo suficientemente bien para que otro desarrollador lo construya.

Si el usuario ya tiene el conocimiento escrito (un manual, documentación de API, una guía de estilo, páginas web guardadas), impórtalo en lugar de volver a escribir:

python3 scripts/import_sources.py <archivos-o-carpetas> --skill <carpeta-del-skill> --dry-run

Convierte Markdown, texto y HTML guardado en archivos de referencia, divide los largos en los encabezados, escribe un sources-index.md junto a ellos e imprime las líneas "lee X cuando Y" para el cuerpo. Nunca descarga nada; guarda las páginas primero.

Etapa 2: Detectar problemas antes de construir

Demasiado simple: Claude ya lo hace. Un skill se gana su lugar cuando hay lógica de dominio o un formato que aplicar cada vez. Pregunta si lo hay.
Demasiado amplio: varios flujos de trabajo no relacionados. Sugiere una división; los skills pequeños se activan de manera más confiable. Pregunta cuál va primero.
Superposición: cercano a docx, pptx, xlsx, pdf o diseño frontend. Dilo y pregunta si extender o construir algo diferente.
Imposible o inseguro: dilo claramente y ofrece la versión factible más cercana.
Contradicción: "totalmente automático" antes, "pregúntame primero" ahora. Resuélvelo antes de escribir una línea.

Etapa 3: Categorizar

Lee references/categories-and-patterns.md. Elige uno:

Categoría 1, creación de documentos y activos: crea archivos con las funciones integradas de Claude. Los lotes 1 y 2 de descubrimiento son suficientes.
Categoría 2, automatización de flujos de trabajo: pasos ordenados entre herramientas, puertas de validación, fallo parcial o reversión. Los cinco lotes.
Categoría 3, mejora de MCP: envuelve un servidor MCP existente con juicio y valores predeterminados. Lotes 1, 2 y 4.

Informa al usuario la categoría y por qué. Las mezclas están bien; elige la principal para la descripción y la estructura de carpetas.

Etapa 4: Construir y validar

Lee references/worked-example.md una vez antes de generar cualquier cosa, para que la salida coincida con ese nivel de detalle. Usa references/spec-output-template.md como esqueleto.

4a: Frontmatter

Lee references/yaml-rules.md. Lo que el validador comprueba (errores a menos que se marque):

name: kebab-case, sin "claude" ni "anthropic"; coincide con el nombre de la carpeta (advertencia, error con --portable)
description: de 1 a 1024 caracteres; verbo de acción, qué hace, cuándo usarlo, de 3 a 8 frases de activación entre comillas dobles, un alcance negativo (la longitud es un error; verbo, frases y alcance negativo son advertencias)
sin corchetes angulares, tabulaciones, comillas tipográficas ni guiones que no sean el guion
sin apóstrofos en la descripción (advertencia; algunos analizadores de carga los han rechazado)
tags como una sola cadena, tags: "a, b, c", nunca [a, b, c] (advertencia); cita valores de metadatos que parezcan números, version: "1.0"

Haz que la descripción sea insistente. En nuestras pruebas, Claude deja un skill sin usar con más frecuencia de lo que lo elige erróneamente, así que añade "también se activa cuando alguien menciona ..." para las solicitudes indirectas.

4b: Cuerpo

Máximo 500 líneas, imperativo, y explica por qué, no solo qué. Orden: propósito de una línea; cuándo usar y cuándo no; pasos numerados con una comprobación después de cada uno; dos o tres ejemplos (frase, acciones, resultado); manejo de errores con causa y respuesta; mejores prácticas breves. Mueve cualquier cosa más grande a references/ y apunta con "lee X cuando Y".

4c: Carpeta

nombre-del-skill/
  SKILL.md
  evals/evals.json        casos de prueba, ver references/schemas.md
  scripts/                lógica determinista que el modelo no debería volver a derivar
  references/             material profundo cargado bajo demanda
  assets/                 plantillas y muestras

Sin README.md dentro de la carpeta del skill; la documentación vive en SKILL.md y references/.

4d: Plan de prueba y evaluaciones

Escribe 5 o más consultas que deberían activar y 5 o más consultas que NO deberían activar. Las consultas buenas son específicas y suenan como una persona: "vale, iniciando el rediseño del checkout el lunes, configura el sprint en Linear, 2 semanas, equipo frontend". Los mejores negativos comparten palabras con los positivos pero quieren otra cosa: consejo en lugar de acción, informes en lugar de creación.

Escribe 2 o 3 evaluaciones en evals/evals.json (formato en references/schemas.md). Cada expectativa es una oración verificable. Muéstralas al usuario antes de ejecutar nada.

4e: Validar

python3 scripts/validate_spec.py <carpeta-del-skill>
python3 scripts/validate_spec.py <carpeta-del-skill> --json     # para herramientas
python3 scripts/validate_spec.py <carpeta-del-skill> --strict   # las advertencias también fallan
python3 scripts/validate_spec.py <carpeta-del-skill> --portable # para agentes que no sean Claude

Comprueba las reglas de frontmatter, la longitud del cuerpo, las secciones anteriores, los marcadores de posición dejados, evals.json, pressure-evals.json cuando esté presente, y que cada ruta scripts/... o references/... que el cuerpo mencione exista. Corrige cada error. Nunca muestres una especificación que falle. --portable añade las reglas de la especificación de Open Agent Skills (el nombre de la carpeta debe coincidir, los valores de metadatos deben ser texto) para skills que también se ejecutarán en otros agentes.

Etapa 5: Probar y revisar

Una secuencia; no te detengas a mitad.

5a: Ejecutar las evaluaciones

Estructura del espacio de trabajo (árbol completo en references/schemas.md):

<carpeta-del-skill>-workspace/iteration-1/eval-<id>/<configuration>/run-<k>/outputs/

Escribe eval_metadata.json en cada carpeta eval-<id>/. Luego ejecuta cada evaluación:

Con subagentes (Claude Code, Cowork): inicia las ejecuciones con skill y sin skill para cada evaluación en el mismo turno. Cada ejecutor lee el skill, realiza la solicitud, guarda archivos en outputs/, escribe outputs/user_notes.md para cualquier cosa de la que no estuviera seguro, y outputs/metrics.json. Guarda timing.json de la notificación de tarea de inmediato; los números no se conservan en ningún otro lugar.
Sin subagentes (claude.ai): lee SKILL.md y realiza cada solicitud tú mismo, una a la vez, en las mismas carpetas.

5b: Redactar aserciones mientras las ejecuciones están en marcha

Añade expectativas medibles a eval_metadata.json y evals/evals.json. Explica cada una al usuario en una oración. Omite aserciones para el gusto; una persona juzga esas.

5c: Mostrar los resultados antes de juzgarlos

python3 eval-viewer/review.py <carpeta-del-skill>-workspace/iteration-1 --skill-name <nombre>

La página se abre en el navegador, funciona sin conexión, y guarda la retroalimentación en feedback.json en el espacio de trabajo mientras el usuario escribe. En Cowork, o cuando un servidor no es posible, añade --static review.html; la retroalimentación se descarga como un archivo. Abre el visor primero y mira los resultados tú mismo después. No cambies el skill antes de que el usuario haya reaccionado.

5d: Calificar y comparar (subagentes)

Califica cada ejecución con agents/grader.md. Usa un modelo diferente del que ejecutó la evaluación cuando puedas; un modelo es un mal juez de su propio trabajo.

Agrega:

python3 scripts/aggregate_benchmark.py <carpeta-del-skill>-workspace/iteration-1 --skill-name <nombre>

Vuelve a abrir el visor con --benchmark <iteration>/benchmark.json para la pestaña Benchmark. Para patrones que los promedios ocultan, ejecuta agents/analyzer.md tarea 2.

5e: Prueba de presión (skills que imponen una regla)

Cuando el valor del skill es una regla que debe cumplirse (un formato, una comprobación, un paso de aprobación), lee references/pressure-tests.md y escribe de 3 a 5 escenarios en evals/pressure-evals.json: una situación concreta, dos o más presiones (fecha límite, un jefe, el cliente lo pidió, horas ya invertidas), y una elección forzada que incluya un compromiso tentador.

python3 scripts/pressure_eval.py --skill-path <carpeta-del-skill> \
  --scenarios <carpeta-del-skill>/evals/pressure-evals.json --runs 3 --model <id-del-modelo> \
  --output <carpeta-del-skill>-workspace/pressure-results.json \
  --report <carpeta-del-skill>-workspace/pressure-report.md --dry-run

Elimina --dry-run después de que el usuario apruebe el número de llamadas. Cada escenario se ejecuta sin y con el skill. "El skill no se sostiene" significa que el informe contiene las excusas que Claude dio: contrarresta cada una en el skill (nómbrala, di por qué está mal, di qué hacer), luego vuelve a ejecutar. "Pasa, pero la línea de base también pasa" significa que el escenario es demasiado fácil para probar algo.

Etapa 6: Mejorar

Encuentra el patrón detrás de la retroalimentación y corrígelo; tres indicaciones de prueba no son el mundo. Lee las transcripciones, no solo los resultados, y elimina instrucciones que hicieron que el modelo perdiera pasos. Si estás escribiendo SIEMPRE o NUNCA en mayúsculas, detente y explica la razón en su lugar; un modelo con la razón llega más lejos que un modelo con la regla. Cuando cada ejecución escribió el mismo helper, ponlo en scripts/ y dilo. Cuidado con un skill que pasa sus tres evaluaciones y nada más.

Luego: aplica los cambios, vuelve a ejecutar todas las evaluaciones en iteration-2/, abre el visor con --previous-workspace iteration-1 para que el usuario vea lo antiguo y lo nuevo lado a lado, lee la retroalimentación, repite. Detente cuando el usuario esté contento, la retroalimentación esté vacía, o el progreso se haya estancado.

Para una llamada rigurosa de antiguo contra nuevo, usa agents/comparator.md (un juez A/B ciego con una verificación de intercambio) y luego agents/analyzer.md tarea 1 para explicar el resultado. Opcional; el bucle de revisión suele ser suficiente.

Etapa 7: Ajuste de descripción

La descripción es lo que hace que Claude elija el skill. Ajústala una vez que el skill en sí funcione.

7a: Consultas de activación

Escribe 20 consultas en evals/trigger-evals.json: aproximadamente la mitad deberían activar, la mitad no deberían. Incluye lenguaje informal, nombres de archivos, contexto personal. Los negativos valiosos son los casi aciertos. Muestra la lista al usuario y cambia lo que pidan cambiar; las consultas malas producen una descripción mala.

7b: Contar antes de gastar

python3 scripts/trigger_eval.py --skill-path <carpeta-del-skill> --eval-set <carpeta-del-skill>/evals/trigger-evals.json --dry-run

Cada ejecución es una llamada claude -p. Informa al usuario el número y obtén un sí.

7c: Medir

python3 scripts/trigger_eval.py --skill-path <carpeta-del-skill> \
  --eval-set <carpeta-del-skill>/evals/trigger-evals.json \
  --runs-per-query 3 --workers 4 --model <id-del-modelo> \
  --output <carpeta-del-skill>-workspace/trigger-results.json --verbose

El script instala el skill en un proyecto desechable y ejecuta Claude allí solo con la configuración de ese proyecto, por lo que nada toca el proyecto real del usuario y sus otros skills no pueden interferir. Lee el resumen: las consultas perdidas (falsos negativos) significan que la descripción es demasiado estrecha; las activadas erróneamente significan que es demasiado amplia. Una consulta cuyas ejecuciones todas dieron error se informa como desconocida, nunca como un acierto.

7d: Optimizar (solo Claude Code)

python3 scripts/optimize_description.py --skill-path <carpeta-del-skill> \
  --eval-set <carpeta-del-skill>/evals/trigger-evals.json --model <id-del-modelo> \
  --max-iterations 4 --results-dir <carpeta-del-skill>-workspace/description-runs --verbose

Divide las consultas una vez en conjuntos de entrenamiento y reservados, evalúa, pide a Claude una mejor descripción usando solo los fallos de entrenamiento, valida el candidato con las mismas reglas que validate_spec.py, y repite. El ganador es la iteración con la mejor puntuación de entrenamiento; los empates van al texto más corto. La puntuación del conjunto reservado se informa pero nunca se usa para elegir, por lo que sigue siendo una comprobación honesta: si es mucho más baja que la puntuación de entrenamiento, la descripción está ajustada a las consultas de entrenamiento. Escribe results.json, report.md y best-description.txt, y sale con 0 solo cuando el ganador pasa cada consulta de entrenamiento. En claude.ai, lee los fallos y reescribe a mano en su lugar.

7e: Aplicar

Pega el ganador en SKILL.md, muestra al usuario antes y después con las puntuaciones, y ejecuta scripts/validate_spec.py de nuevo.

Etapa 8: Empaquetar

python3 scripts/package_skill.py <carpeta-del-skill> --output dist/
python3 scripts/package_skill.py --inspect dist/<nombre-del-skill>.skill

El empaquetado primero valida y rechaza en caso de errores (y en caso de advertencias a menos que --allow-warnings). El archivo es reproducible e imprime un SHA-256. Dale al usuario la ruta, o el archivo en sí mismo.

Referencias

Lee los archivos en references/ para obtener detalles adicionales sobre:

preguntas de descubrimiento,
categorías y patrones,
ejemplo de trabajo,
plantilla de salida de especificación,
reglas YAML,
esquemas para evals,
pruebas de presión,
y más.

elitesalgorithm/elites-skills-architect

¿Qué es elites-skills-architect?

Preguntar en tu IA favorita

Documentación