Una habilidad para crear nuevas habilidades y mejorarlas iterativamente.

En un nivel alto, el proceso de creación de una habilidad es el siguiente:

• Decide qué quieres que haga la habilidad y aproximadamente cómo debería hacerlo.
• Escribe un borrador de la habilidad.
• Cree algunas indicaciones de prueba y ejecute claude-with-access-to-the-skill en ellas
• Ayudar al usuario a evaluar los resultados tanto cualitativa como cuantitativamente.
  • Mientras las ejecuciones se realizan en segundo plano, redacte algunas evaluaciones cuantitativas si no las hay (si las hay, puede usarlas tal como están o modificarlas si cree que es necesario cambiar algo). Luego explícalos al usuario (o si ya existían, explícales los que ya existen)
  • Utilice el scripteval-viewer/generate_review.pypara mostrarle al usuario los resultados para que los vea y también permítale ver las métricas cuantitativas.
• Reescribir la habilidad basándose en los comentarios de la evaluación de los resultados por parte del usuario (y también si hay fallas evidentes que se hacen evidentes en los puntos de referencia cuantitativos)
• Repita hasta que esté satisfecho
• Amplíe el conjunto de pruebas y vuelva a intentarlo a mayor escala.

Su trabajo al utilizar esta habilidad es descubrir dónde se encuentra el usuario en este proceso y luego intervenir y ayudarlo a progresar a través de estas etapas. Entonces, por ejemplo, tal vez digan "Quiero desarrollar una habilidad para X". Puede ayudar a delimitar lo que quieren decir, escribir un borrador, escribir los casos de prueba, descubrir cómo quieren evaluar, ejecutar todas las indicaciones y repetir.

Por otro lado, tal vez ya tengan un borrador de la habilidad. En este caso, puede ir directamente a la parte de evaluación/iteración del ciclo.

Por supuesto, siempre debes ser flexible y si el usuario dice "No necesito realizar un montón de evaluaciones, solo vibra conmigo", puedes hacerlo en su lugar.

Luego, una vez finalizada la habilidad (pero nuevamente, el orden es flexible), también puede ejecutar el mejorador de descripción de la habilidad, para el cual tenemos un script completamente separado, para optimizar la activación de la habilidad.

¿Fresco? Fresco.

Comunicarse con el usuario

El creador de habilidades puede ser utilizado por personas con un amplio rango de familiaridad con la jerga de codificación. Si no lo has escuchado (y cómo podrías hacerlo, solo recientemente comenzó), ahora hay una tendencia en la que el poder de Claude está inspirando a los plomeros a abrir sus terminales, padres y abuelos a buscar en Google "cómo instalar npm". Por otro lado, la mayoría de los usuarios probablemente tengan bastantes conocimientos de informática.

¡Así que preste atención a las señales del contexto para comprender cómo expresar su comunicación! En el caso predeterminado, sólo para darle una idea:

• "evaluación" y "punto de referencia" están en el límite, pero está bien
• para "JSON" y "aserción", desea ver señales serias del usuario de que sabe cuáles son esas cosas antes de usarlas sin explicarlas.

Está bien explicar brevemente los términos si tiene dudas y siéntase libre de aclarar los términos con una definición breve si no está seguro de si el usuario la entenderá.

---

Creando una habilidad

Intención de captura

Empiece por comprender la intención del usuario. Es posible que la conversación actual ya contenga un flujo de trabajo que el usuario desea capturar (por ejemplo, dice "convierte esto en una habilidad"). Si es así, primero extraiga las respuestas del historial de conversaciones: las herramientas utilizadas, la secuencia de pasos, las correcciones que realizó el usuario, los formatos de entrada/salida observados. Es posible que el usuario necesite completar los espacios en blanco y debe confirmarlos antes de continuar con el siguiente paso.

1. ¿Qué debería permitirle hacer esta habilidad a Claude?
2. ¿Cuándo debería activarse esta habilidad? (qué frases/contextos de usuario)
3. ¿Cuál es el formato de salida esperado?
4. ¿Deberíamos configurar casos de prueba para verificar que la habilidad funcione? Las habilidades con resultados objetivamente verificables (transformaciones de archivos, extracción de datos, generación de código, pasos de flujo de trabajo fijos) se benefician de los casos de prueba. Las habilidades con resultados subjetivos (estilo de escritura, arte) a menudo no las necesitan. Sugiera el valor predeterminado apropiado según el tipo de habilidad, pero deje que el usuario decida.

Entrevista e investigación

Haga preguntas de forma proactiva sobre casos extremos, formatos de entrada/salida, archivos de ejemplo, criterios de éxito y dependencias. Espere a escribir las indicaciones de prueba hasta que haya resuelto esta parte.

Verifique los MCP disponibles: si son útiles para la investigación (buscar documentos, encontrar habilidades similares, buscar mejores prácticas), investigue en paralelo a través de subagentes si están disponibles; de lo contrario, en línea. Venga preparado con contexto para reducir la carga para el usuario.

Escribe la HABILIDAD.md

Según la entrevista del usuario, complete estos componentes:

• nombre: identificador de habilidad
• descripción: Cuándo activarse, qué hace. Este es el mecanismo desencadenante principal: incluye tanto lo que hace la habilidad como contextos específicos sobre cuándo usarla. Toda la información sobre "cuándo usarla" va aquí, no en el cuerpo. Nota: actualmente Claude tiene una tendencia a "desactivar menos" las habilidades, a no usarlas cuando serían útiles. Para combatir esto, haga que las descripciones de las habilidades sean un poco "agresivas". Entonces, por ejemplo, en lugar de "Cómo crear un panel rápido y simple para mostrar datos antrópicos internos", podría escribir "Cómo crear un panel rápido y simple para mostrar datos antrópicos internos. Asegúrese de utilizar esta habilidad siempre que el usuario mencione paneles, visualización de datos, métricas internas o quiera mostrar cualquier tipo de datos de la empresa, incluso si no solicita explícitamente un 'panel'".
• compatibilidad: herramientas necesarias, dependencias (opcionales, rara vez necesarias)
• el resto de la habilidad:)

Guía de escritura de habilidades

Anatomía de una habilidad

skill-name/
 SKILL.md (required)
    YAML frontmatter (name, description required)
    Markdown instructions
 Bundled Resources (optional)
     scripts/    - Executable code for deterministic/repetitive tasks
     references/ - Docs loaded into context as needed
     assets/     - Files used in output (templates, icons, fonts)

Divulgación progresiva

Las habilidades utilizan un sistema de carga de tres niveles:

1. Metadatos (nombre + descripción): siempre en contexto (~100 palabras)
2. SKILL.md body - En contexto cada vez que se activa una habilidad (<500 líneas ideal)
3. Recursos incluidos: según sea necesario (ilimitados, los scripts se pueden ejecutar sin cargar)

Estos recuentos de palabras son aproximados y puede ampliarlos si es necesario.

Patrones clave:

• Mantenga SKILL.md por debajo de 500 líneas; Si se está acercando a este límite, agregue una capa adicional de jerarquía junto con indicaciones claras sobre dónde debe ir el modelo que usa la habilidad a continuación para realizar el seguimiento.
• Archivos de referencia claramente desde SKILL.md con orientación sobre cuándo leerlos
• Para archivos de referencia grandes (>300 líneas), incluya una tabla de contenido

Organización del dominio: cuando una habilidad admite múltiples dominios/marcos, organícela por variante:

cloud-deploy/
 SKILL.md (workflow + selection)
 references/
     aws.md
     gcp.md
     azure.md

Claude lee sólo el archivo de referencia relevante.

Principio de falta de sorpresa

No hace falta decirlo, pero las skills no deben contener malware, código de explotación ni ningún contenido que pueda comprometer la seguridad del sistema. El contenido de una habilidad no debería sorprender al usuario en su intención si se describe. No acepte solicitudes para crear habilidades engañosas o habilidades diseñadas para facilitar el acceso no autorizado, la filtración de datos u otras actividades maliciosas. Sin embargo, cosas como un "juego de roles como XYZ" están bien.

Patrones de escritura

Prefiere usar la forma imperativa en las instrucciones.

Definir formatos de salida - Puedes hacerlo así:

## Report structure
ALWAYS use this exact template:
# [Title]
## Executive summary
## Key findings
## Recommendations

Patrón de ejemplos: es útil incluir ejemplos. Puede formatearlos así (pero si "Entrada" y "Salida" están en los ejemplos, es posible que desee desviarse un poco):

## Commit message format
**Example 1:**
Input: Added user authentication with JWT tokens
Output: feat(auth): implement JWT-based authentication

Estilo de escritura

Trate de explicarle al modelo por qué las cosas son importantes en lugar de los pesados ​​DEBERES. Utilice la teoría de la mente y trate de hacer que la habilidad sea general y no muy limitada a ejemplos específicos. Empiece por escribir un borrador y luego mírelo con ojos nuevos y mejórelo.

Casos de prueba

Después de escribir el borrador de habilidades, plantee 2 o 3 sugerencias de prueba realistas, el tipo de cosas que un usuario real diría. Compártelos con el usuario: [no es necesario utilizar este lenguaje exacto] "Aquí hay algunos casos de prueba que me gustaría probar. ¿Se ven bien o desea agregar más?" Luego ejecútelos.

Guarde los casos de prueba enevals/evals.json. No escribas afirmaciones todavía, solo las indicaciones. Redactarás afirmaciones en el siguiente paso mientras las ejecuciones están en progreso.

{
  "skill_name": "example-skill",
  "evals": [
    {
      "id": 1,
      "prompt": "User's task prompt",
      "expected_output": "Description of expected result",
      "files": []
    }
  ]
}

Consultereferences/schemas.mdpara ver el esquema completo (incluido el campoassertions, que agregará más adelante).

Ejecutar y evaluar casos de prueba.

Esta sección es una secuencia continua; no se detenga a mitad de camino. NO utilice/skill-testni ninguna otra habilidad de prueba.

Coloque los resultados en<skill-name>-workspace/como hermano del directorio de habilidades. Dentro del espacio de trabajo, organice los resultados por iteración (iteration-1/,iteration-2/, etc.) y dentro de eso, cada caso de prueba obtiene un directorio (eval-0/,eval-1/, etc.). No cree todo esto por adelantado, simplemente cree directorios sobre la marcha.

Paso 1: generar todas las carreras (con habilidad Y línea de base) en el mismo turno

Para cada caso de prueba, genera dos subagentes en el mismo turno: uno con la habilidad y otro sin ella. Esto es importante: no generes las carreras con habilidad primero y luego regreses para las líneas de base más tarde. Inicie todo a la vez para que todo termine aproximadamente al mismo tiempo.

Carrera con habilidad:

Execute this task:
- Skill path: <path-to-skill>
- Task: <eval prompt>
- Input files: <eval files if any, or "none">
- Save outputs to: <workspace>/iteration-<N>/eval-<ID>/with_skill/outputs/
- Outputs to save: <what the user cares about - e.g., "the .docx file", "the final CSV">

Ejecución de la línea base (el mismo mensaje, pero la línea base depende del contexto):

• Creando una nueva habilidad: ninguna habilidad en absoluto. El mismo mensaje, sin ruta de habilidad, guárdelo enwithout_skill/outputs/.
• Mejorar una habilidad existente: la versión anterior. Antes de editar, tome una instantánea de la habilidad (cp -r <skill-path> <workspace>/skill-snapshot/) y luego apunte el subagente de línea base a la instantánea. Guardar enold_skill/outputs/.

Escriba uneval_metadata.jsonpara cada caso de prueba (las afirmaciones pueden estar vacías por ahora). Asigne a cada evaluación un nombre descriptivo según lo que está probando, no solo "eval-0". Utilice este nombre también para el directorio. Si esta iteración utiliza mensajes de evaluación nuevos o modificados, cree estos archivos para cada nuevo directorio de evaluación; no asuma que se transfieren de iteraciones anteriores.

{
  "eval_id": 0,
  "eval_name": "descriptive-name-here",
  "prompt": "The user's task prompt",
  "assertions": []
}

Paso 2: mientras las ejecuciones están en progreso, redactar afirmaciones

No esperes simplemente a que terminen las ejecuciones: puedes utilizar este tiempo de forma productiva. Redacte afirmaciones cuantitativas para cada caso de prueba y explíquelas al usuario. Si ya existen aserciones enevals/evals.json, revíselas y explique qué verifican.

Las buenas afirmaciones son objetivamente verificables y tienen nombres descriptivos; deben leerse claramente en el visor de referencia para que alguien que mire los resultados comprenda inmediatamente lo que comprueba cada una. Las habilidades subjetivas (estilo de escritura, calidad del diseño) se evalúan mejor cualitativamente: no fuerces afirmaciones sobre cosas que necesitan juicio humano.

Actualice los archivoseval_metadata.jsonyevals/evals.jsoncon las aserciones una vez redactadas. Explique también al usuario lo que verá en el visor: tanto los resultados cualitativos como el punto de referencia cuantitativo.

Paso 3: cuando se completen las carreras, capture los datos de cronometraje

Cuando se completa cada tarea de subagente, recibe una notificación que contienetotal_tokensyduration_ms. Guarde estos datos inmediatamente entiming.jsonen el directorio de ejecución:

{
  "total_tokens": 84852,
  "duration_ms": 23332,
  "total_duration_seconds": 23.3
}

Esta es la única oportunidad de capturar estos datos: llegan a través de la notificación de la tarea y no persisten en ningún otro lugar. Procese cada notificación a medida que llega en lugar de intentar agruparlas.

Paso 4: calificar, agregar e iniciar el visor

Una vez realizadas todas las ejecuciones:

1. Calificar cada ejecución: genera un subagente calificador (o calificación en línea) que leeagents/grader.mdy evalúa cada afirmación con respecto a los resultados. Guarde los resultados engrading.jsonen cada directorio de ejecución. La matriz de expectativas grading.json debe usar los campostext,passedyevidence(noname/met/detailsu otras variantes); el visor depende de estos nombres de campo exactos. Para las afirmaciones que se pueden verificar mediante programación, escriba y ejecute un script en lugar de mirarlo a simple vista: los scripts son más rápidos, más confiables y se pueden reutilizar en iteraciones.

2. Agregar en punto de referencia: ejecute el script de agregación desde el directorio del creador de habilidades:

   python -m scripts.aggregate_benchmark <workspace>/iteration-N --skill-name <name>
   

   Esto producebenchmark.jsonybenchmark.mdcon pass_rate, tiempo y tokens para cada configuración, con stddev medio y delta. Si genera benchmark.json manualmente, consultereferences/schemas.mdpara conocer el esquema exacto que espera el espectador. Coloque cada versión de with_skill antes de su contraparte básica.

3. Realice una prueba de analista: lea los datos de referencia y los patrones de superficie que las estadísticas agregadas podrían ocultar. Consulteagents/analyzer.md(la sección "Análisis de resultados de referencia") para saber qué buscar: cosas como afirmaciones que siempre pasan independientemente de la habilidad (sin discriminación), evaluaciones de alta variación (posiblemente inestables) y compensaciones de tiempo/token.

4. Inicie el visor con resultados cualitativos y datos cuantitativos:

   nohup python <skill-creator-path>/eval-viewer/generate_review.py \
     <workspace>/iteration-N \
     --skill-name "my-skill" \
     --benchmark <workspace>/iteration-N/benchmark.json \
     > /dev/null 2>&1 &
   VIEWER_PID=$!
   

   Para la iteración 2+, pase también--previous-workspace <workspace>/iteration-<N-1>.

   Entornos de cowork/sin cabeza: Siwebbrowser.open()no está disponible o el entorno no tiene visualización, utilice--static <output_path>para escribir un archivo HTML independiente en lugar de iniciar un servidor. Los comentarios se descargarán como un archivofeedback.jsoncuando el usuario haga clic en "Enviar todas las reseñas". Después de la descarga, copiefeedback.jsonen el directorio del espacio de trabajo para continuar con la siguiente iteración.

Nota: utilice generate_review.py para crear el visor; no es necesario escribir HTML personalizado.

5. Dígale al usuario algo como: "Abrí los resultados en su navegador. Hay dos pestañas: 'Resultados' le permite hacer clic en cada caso de prueba y dejar comentarios, 'Benchmark' muestra la comparación cuantitativa. Cuando haya terminado, regrese aquí y hágamelo saber".

Lo que el usuario ve en el visor

La pestaña "Salidas" muestra un caso de prueba a la vez:

• Mensaje: la tarea que se asignó
• Salida: los archivos que produjo la habilidad, representados en línea cuando sea posible
• Resultado anterior (iteración 2+): sección contraída que muestra el resultado de la última iteración
• Calificaciones formales (si se ejecutó la calificación): sección contraída que muestra la afirmación de aprobado/reprobado
• Comentarios: un cuadro de texto que se guarda automáticamente a medida que escriben
• Comentarios anteriores (iteración 2+): sus comentarios de la última vez, que se muestran debajo del cuadro de texto

La pestaña "Benchmark" muestra el resumen de estadísticas: tasas de aprobación, tiempo y uso de tokens para cada configuración, con desgloses por evaluación y observaciones de analistas.

La navegación se realiza mediante botones anterior/siguiente o teclas de flecha. Cuando terminan, hacen clic en "Enviar todas las reseñas", lo que guarda todos los comentarios enfeedback.json.

Paso 5: lea los comentarios

Cuando el usuario te diga que ha terminado, leefeedback.json:

{
  "reviews": [
    {"run_id": "eval-0-with_skill", "feedback": "the chart is missing axis labels", "timestamp": "..."},
    {"run_id": "eval-1-with_skill", "feedback": "", "timestamp": "..."},
    {"run_id": "eval-2-with_skill", "feedback": "perfect, love this", "timestamp": "..."}
  ],
  "status": "complete"
}

Los comentarios vacíos significan que el usuario pensó que estaba bien. Centre sus mejoras en los casos de prueba en los que el usuario tuvo quejas específicas.

Elimina el servidor de visualización cuando hayas terminado:

kill $VIEWER_PID 2>/dev/null

---

Mejorando la habilidad

Este es el corazón del bucle. Ejecutó los casos de prueba, el usuario revisó los resultados y ahora necesita mejorar la habilidad en función de sus comentarios.

Cómo pensar en las mejoras

1. Generalice a partir de los comentarios. El panorama general que está sucediendo aquí es que estamos tratando de crear habilidades que se puedan usar un millón de veces (tal vez literalmente, tal vez incluso más, quién sabe) a través de muchos mensajes diferentes. Aquí usted y el usuario iteran solo unos pocos ejemplos una y otra vez porque ayuda a avanzar más rápido. El usuario conoce estos ejemplos a la perfección y le resulta rápido evaluar nuevos resultados. Pero si la habilidad que usted y el usuario están desarrollando conjuntamente funciona solo para esos ejemplos, es inútil. En lugar de introducir cambios complicados y excesivos o DEBE opresivamente restrictivos, si hay algún problema persistente, puede intentar diversificarse y utilizar diferentes metáforas, o recomendar diferentes patrones de trabajo. Es relativamente barato probarlo y tal vez consigas algo genial.

2. Mantén el mensaje magro. Quita las cosas que no están cumpliendo su peso. Asegúrese de leer las transcripciones, no solo los resultados finales: si parece que la habilidad hace que el modelo pierda mucho tiempo haciendo cosas que no son productivas, puede intentar deshacerse de las partes de la habilidad que lo hacen hacer eso y ver qué sucede.

3. Explique el por qué. Intente explicar el por qué detrás de todo lo que le pide al modelo que haga. Los LLM de hoy son inteligentes. Tienen una buena teoría de la mente y, cuando se les da un buen manejo, pueden ir más allá de las instrucciones de memoria y hacer que las cosas realmente sucedan. Incluso si los comentarios del usuario son concisos o frustrados, intente comprender realmente la tarea y por qué el usuario escribe lo que escribió, y lo que realmente escribió, y luego transmita esta comprensión a las instrucciones. Si te encuentras escribiendo SIEMPRE o NUNCA en mayúsculas, o usando estructuras súper rígidas, eso es una señal de alerta; si es posible, reformula y explica el razonamiento para que el modelo entienda por qué lo que estás pidiendo es importante. Ése es un enfoque más humano, poderoso y eficaz.

4. Busque trabajos repetidos en los casos de prueba. Lea las transcripciones de las ejecuciones de prueba y observe si todos los subagentes escribieron de forma independiente scripts de ayuda similares o adoptaron el mismo enfoque de varios pasos para algo. Si los 3 casos de prueba dieron como resultado que el subagente escribiera uncreate_docx.pyo unbuild_chart.py, esa es una fuerte señal de que la habilidad debería incluir ese script. Escríbalo una vez, póngalo enscripts/y dígale a la habilidad que lo use. Esto evita que cada invocación futura tenga que reinventar la rueda.

Esta tarea es bastante importante (¡estamos tratando de crear miles de millones al año en valor económico aquí!) y su tiempo para pensar no es el obstáculo; tómate tu tiempo y reflexiona realmente sobre las cosas. Sugeriría escribir un borrador de revisión y luego revisarlo de nuevo y realizar mejoras. Realmente haga todo lo posible para entrar en la cabeza del usuario y comprender lo que quiere y necesita.

El bucle de iteración

Después de mejorar la habilidad:

1. Aplica tus mejoras a la habilidad.
2. Vuelva a ejecutar todos los casos de prueba en un nuevo directorioiteration-<N+1>/, incluidas las ejecuciones de referencia. Si está creando una nueva habilidad, la línea de base siempre eswithout_skill(sin habilidad), que permanece igual en todas las iteraciones. Si está mejorando una habilidad existente, utilice su criterio sobre lo que tiene sentido como punto de referencia: la versión original con la que llegó el usuario o la iteración anterior.
3. Inicie el revisor con--previous-workspaceapuntando a la iteración anterior.
4. Espere a que el usuario revise y le diga que ya terminó.
5. Lea los nuevos comentarios, mejore nuevamente, repita

Continúe hasta:

• El usuario dice que está contento.
• Los comentarios están todos vacíos (todo se ve bien)
• No estás logrando un progreso significativo

---

Avanzado: comparación ciega

Para situaciones en las que desea una comparación más rigurosa entre dos versiones de una habilidad (por ejemplo, el usuario pregunta "¿la nueva versión es realmente mejor?"), existe un sistema de comparación ciega. Leaagents/comparator.mdyagents/analyzer.mdpara obtener más detalles. La idea básica es: dar dos resultados a un agente independiente sin decirle cuál es cuál, y dejar que juzgue la calidad. Luego analiza por qué ganó el ganador.

Esto es opcional, requiere subagentes y la mayoría de los usuarios no lo necesitarán. El circuito de revisión humana suele ser suficiente.

---

Descripción Optimización

El campo de descripción en SKILL.md frontmatter es el mecanismo principal que determina si Claude invoca una habilidad. Después de crear o mejorar una habilidad, ofrezca optimizar la descripción para una mayor precisión de activación.

Paso 1: generar consultas de evaluación de activación

Cree 20 consultas de evaluación: una combinación de debería activarse y no debería activarse. Guardar como JSON:

[
  {"query": "the user prompt", "should_trigger": true},
  {"query": "another prompt", "should_trigger": false}
]

Las consultas deben ser realistas y algo que un usuario de Claude Code o Claude.ai realmente escribiría. No solicitudes abstractas, sino solicitudes concretas y específicas y con una buena cantidad de detalles. Por ejemplo, rutas de archivos, contexto personal sobre el trabajo o situación del usuario, nombres y valores de columnas, nombres de empresas, URL. Un poco de historia de fondo. Algunos pueden estar en minúsculas o contener abreviaturas, errores tipográficos o lenguaje informal. Utilice una combinación de diferentes longitudes y céntrese en los casos extremos en lugar de hacerlos claros (el usuario tendrá la oportunidad de aprobarlos).

Malo:"Format this data","Extract text from PDF","Create a chart"

Bueno:"ok so my boss just sent me this xlsx file (its in my downloads, called something like 'Q4 sales final FINAL v2.xlsx') and she wants me to add a column that shows the profit margin as a percentage. The revenue is in column C and costs are in column D i think"

Para las consultas debería activar (8-10), piense en la cobertura. Quieres diferentes frases con la misma intención: algunas formales, otras informales. Incluya casos en los que el usuario no nombra explícitamente la habilidad o el tipo de archivo pero claramente lo necesita. Agregue algunos casos de uso poco comunes y casos en los que esta habilidad compite con otra pero debería ganar.

Para las consultas que no deberían activarse (8 a 10), las más valiosas son las que casi fallan: consultas que comparten palabras clave o conceptos con la habilidad pero que en realidad necesitan algo diferente. Piense en dominios adyacentes, frases ambiguas en las que una simple coincidencia de palabras clave se activaría pero no debería, y casos en los que la consulta toca algo que hace la habilidad, pero en un contexto donde otra herramienta es más apropiada.

La clave a evitar: no haga que las consultas que no deberían activarse sean obviamente irrelevantes. "Escribir una función de Fibonacci" como prueba negativa para una habilidad PDF es demasiado fácil: no prueba nada. Los casos negativos deberían ser realmente complicados.

Paso 2: Revisar con el usuario

Presente el conjunto de evaluación al usuario para que lo revise utilizando la plantilla HTML:

1. Lea la plantilla deassets/eval_review.html
2. Reemplace los marcadores de posición:
   • __EVAL_DATA_PLACEHOLDER__-> la matriz JSON de elementos de evaluación (sin comillas, es una asignación de variable JS)
   • __SKILL_NAME_PLACEHOLDER__-> el nombre de la habilidad
   • __SKILL_DESCRIPTION_PLACEHOLDER__-> descripción actual de la habilidad
3. Escriba en un archivo temporal (por ejemplo,/tmp/eval_review_<skill-name>.html) y ábralo:open /tmp/eval_review_<skill-name>.html
4. El usuario puede editar consultas, alternar activación debería, agregar/eliminar entradas y luego hacer clic en "Exportar conjunto de evaluación"
5. El archivo se descarga en~/Downloads/eval_set.json; consulte la carpeta Descargas para ver la versión más reciente en caso de que haya varias (por ejemplo,eval_set (1).json).

Este paso es importante: las consultas de evaluación incorrectas conducen a descripciones incorrectas.

Paso 3: ejecute el ciclo de optimización

Dígale al usuario: "Esto llevará algún tiempo; ejecutaré el ciclo de optimización en segundo plano y lo comprobaré periódicamente".

Guarde el conjunto de evaluación en el espacio de trabajo y luego ejecútelo en segundo plano:

python -m scripts.run_loop \
  --eval-set <path-to-trigger-eval.json> \
  --skill-path <path-to-skill> \
  --model <model-id-powering-this-session> \
  --max-iterations 5 \
  --verbose

Utilice el ID del modelo que aparece en el indicador del sistema (el que activa la sesión actual) para que la prueba de activación coincida con lo que el usuario realmente experimenta.

Mientras se ejecuta, siga periódicamente la salida para brindarle al usuario actualizaciones sobre en qué iteración se encuentra y cómo se ven las puntuaciones.

Esto maneja automáticamente el ciclo de optimización completo. Divide el conjunto de evaluación en 60% de entrenamiento y 40% de prueba retenida, evalúa la descripción actual (ejecutando cada consulta 3 veces para obtener una tasa de activación confiable) y luego llama a Claude para proponer mejoras basadas en lo que falló. Reevalúa cada nueva descripción tanto en el tren como en la prueba, iterando hasta 5 veces. Cuando termina, abre un informe HTML en el navegador que muestra los resultados por iteración y devuelve JSON conbest_description, seleccionado por la puntuación de la prueba en lugar de la puntuación del entrenamiento para evitar el sobreajuste.

Cómo funciona la activación de habilidades

Comprender el mecanismo de activación ayuda a diseñar mejores consultas de evaluación. Las habilidades aparecen en la listaavailable_skillsde Claude con su nombre + descripción, y Claude decide si consultar una habilidad según esa descripción. Lo importante que debe saber es que Claude solo consulta habilidades para tareas que no puede manejar fácilmente por sí solo: consultas simples de un solo paso como "leer este PDF" pueden no activar una habilidad incluso si la descripción coincide perfectamente, porque Claude puede manejarlas directamente con herramientas básicas. Las consultas complejas, de varios pasos o especializadas activan de manera confiable habilidades cuando la descripción coincide.

Esto significa que sus consultas de evaluación deben ser lo suficientemente sustanciales como para que Claude realmente se beneficie al consultar una habilidad. Consultas simples como "leer archivo X" son casos de prueba deficientes: no activarán habilidades independientemente de la calidad de la descripción.

Paso 4: aplica el resultado

Tomebest_descriptionde la salida JSON y actualice el frontmatter SKILL.md de la habilidad. Muestre al usuario antes/después e informe las puntuaciones.

---

Empaquetar y presentar (solo si la herramientapresent_filesestá disponible)

Compruebe si tiene acceso a la herramientapresent_files. Si no lo hace, omita este paso. Si lo hace, empaquete la habilidad y presente el archivo.skill al usuario:

python -m scripts.package_skill <path/to/skill-folder>

Después del empaquetado, dirija al usuario a la ruta del archivo.skillresultante para que pueda instalarlo.

---

Instrucciones específicas de Claude.ai

En Claude.ai, el flujo de trabajo principal es el mismo (borrador -> prueba -> revisión -> mejorar -> repetir), pero como Claude.ai no tiene subagentes, algunas mecánicas cambian. Esto es lo que debe adaptar:

Ejecución de casos de prueba: Sin subagentes significa que no hay ejecución paralela. Para cada caso de prueba, lea el SKILL.md de la habilidad y luego siga sus instrucciones para realizar la prueba usted mismo. Hazlos uno a la vez. Esto es menos riguroso que los subagentes independientes (usted escribió la habilidad y también la está ejecutando, por lo que tiene el contexto completo), pero es una verificación de cordura útil, y el paso de revisión humana lo compensa. Omita las carreras de referencia: simplemente use la habilidad para completar la tarea según lo solicitado.

Revisión de resultados: si no puedes abrir un navegador (por ejemplo, la máquina virtual de Claude.ai no tiene pantalla o estás en un servidor remoto), omite el revisor del navegador por completo. En su lugar, presente los resultados directamente en la conversación. Para cada caso de prueba, muestre el mensaje y el resultado. Si el resultado es un archivo que el usuario necesita ver (como.docx o.xlsx), guárdelo en el sistema de archivos e indíquele dónde está para que pueda descargarlo e inspeccionarlo. Solicite comentarios en línea: "¿Cómo se ve esto? ¿Algo que cambiarías?"

Evaluación comparativa: omita la evaluación comparativa cuantitativa: se basa en comparaciones de referencia que no son significativas sin subagentes. Centrarse en la retroalimentación cualitativa del usuario.

El ciclo de iteración: Igual que antes: mejore la habilidad, vuelva a ejecutar los casos de prueba, solicite comentarios, solo que sin el revisor del navegador en el medio. Aún puede organizar los resultados en directorios de iteración en el sistema de archivos, si tiene uno.

Optimización de la descripción: esta sección requiere la herramienta CLIclaude(específicamenteclaude -p) que solo está disponible en Claude Code. Omítelo si estás en Claude.ai.

Comparación ciega: Requiere subaagentes. Saltarlo.

Embalaje: El scriptpackage_skill.pyfunciona en cualquier lugar con Python y un sistema de archivos. En Claude.ai, puede ejecutarlo y el usuario puede descargar el archivo.skillresultante.

Actualizar una habilidad existente: es posible que el usuario le solicite que actualice una habilidad existente, no que cree una nueva. En este caso:

• Conserve el nombre original. Tenga en cuenta el nombre del directorio de la habilidad y el campo frontalname; utilícelos sin cambios. Por ejemplo, si la habilidad instalada esresearch-helper, genereresearch-helper.skill(noresearch-helper-v2).
• Copiar en una ubicación donde se pueda escribir antes de editar. La ruta de habilidad instalada puede ser de solo lectura. Copie a/tmp/skill-name/, edítelo allí y empaquete desde la copia.
• Si empaqueta manualmente, primero instale/tmp/, luego cópielo al directorio de salida; las escrituras directas pueden fallar debido a los permisos.

---

Instrucciones específicas para el cowork

Si estás en Cowork, lo principal que debes saber es:

• Tiene subagentes, por lo que el flujo de trabajo principal (generar casos de prueba en paralelo, ejecutar líneas de base, calificar, etc.) funciona. (Sin embargo, si tiene problemas graves con los tiempos de espera, está bien ejecutar las indicaciones de prueba en serie en lugar de en paralelo).
• No tiene un navegador ni una pantalla, por lo que cuando genere el visor de evaluación, use--static <output_path>para escribir un archivo HTML independiente en lugar de iniciar un servidor. Luego, ofrezca un enlace en el que el usuario pueda hacer clic para abrir el HTML en su navegador.
• Por alguna razón, la configuración de Cowork parece impedir que Claude genere el visor de evaluación después de ejecutar las pruebas, así que solo para reiterar: ya sea que esté en Cowork o en Claude Code, después de ejecutar las pruebas, siempre debe generar el visor de evaluación para que el humano mire los ejemplos antes de revisar la habilidad usted mismo e intentar hacer correcciones, usandogenerate_review.py(sin escribir su propio código html boutique). Lo siento de antemano, pero aquí usaré mayúsculas: GENERAR EL VISOR DE EVALUACIÓN ANTES de evaluar las entradas usted mismo. ¡Quieres ponerlos frente al humano lo antes posible!
• Los comentarios funcionan de manera diferente: dado que no hay ningún servidor en ejecución, el botón "Enviar todas las reseñas" del espectador descargaráfeedback.jsoncomo un archivo. Luego podrá leerlo desde allí (es posible que primero deba solicitar acceso).
• El empaquetado funciona:package_skill.pysolo necesita Python y un sistema de archivos.
• La optimización de la descripción (run_loop.py/run_eval.py) debería funcionar bien en Cowork ya que utilizaclaude -pa través de un subproceso, no un navegador, pero guárdelo hasta que haya terminado de crear la habilidad y el usuario esté de acuerdo en que está en buen estado.
• Actualizar una habilidad existente: es posible que el usuario le solicite que actualice una habilidad existente, no que cree una nueva. Siga las instrucciones de actualización en la sección claude.ai anterior.

---

Archivos de referencia

El directorio/agentes contiene instrucciones para subagentes especializados. Léelos cuando necesites generar el subagente correspondiente.

• agents/grader.md: cómo evaluar las afirmaciones frente a las salidas
• agents/comparator.md- Cómo hacer una comparación A/B ciega entre dos salidas
• agents/analyzer.md- Cómo analizar por qué una versión venció a otra

El directorio de referencias tiene documentación adicional:

• references/schemas.md: estructuras JSON para evals.json, grading.json, etc.

---

Repitiendo una vez más el bucle central aquí para enfatizar:

• Descubra de qué se trata la habilidad
• Redactar o editar la habilidad
• Ejecute claude-with-access-to-the-skill en las indicaciones de prueba
• Con el usuario, evalúe los resultados:
  • Cree benchmark.json y ejecuteeval-viewer/generate_review.pypara ayudar al usuario a revisarlos.
  • Ejecutar evaluaciones cuantitativas
• Repita hasta que usted y el usuario estén satisfechos.
• Empaquete la habilidad final y devuélvala al usuario.

Agregue pasos a su TodoList, si tiene tal cosa, para asegurarse de no olvidarlo. Si está en Cowork, escriba específicamente "Crear evaluaciones JSON y ejecutareval-viewer/generate_review.pypara que los humanos puedan revisar los casos de prueba" en su TodoList para asegurarse de que esto suceda.

¡Buena suerte!

Archivos de recursos

LICENCIA.txt

Descargar LICENCIA.txt

Recurso binario

agentes/analyzer.md

Descargar agentes/analyzer.md

Recurso binario

agentes/comparador.md

Descargar agentes/comparator.md

Recurso binario

agentes/grader.md

Descargar agentes/grader.md

Recurso binario

activos/eval_review.html

Descargar activos/eval_review.html

Recurso binario

eval-viewer/generate_review.py

Descargar eval-viewer/generate_review.py

Recurso binario

visor-eval/viewer.html

Descargar eval-viewer/viewer.html

Recurso binario

referencias/esquemas.md

Descargar referencias/schemas.md

Recurso binario

scripts/init.py

Descargar scripts/init.py

Recurso binario

scripts/aggregate_benchmark.py

Descargar scripts/aggregate_benchmark.py

Recurso binario

scripts/generate_report.py

Descargar scripts/generate_report.py

Recurso binario

scripts/improve_description.py

Descargar scripts/improve_description.py

Recurso binario

scripts/paquete_skill.py

Descargar scripts/package_skill.py

#!/usr/bin/env python3
"""
Skill Packager - Creates a distributable .skill file of a skill folder

Usage:
    python utils/package_skill.py <path/to/skill-folder> [output-directory]

Example:
    python utils/package_skill.py skills/public/my-skill
    python utils/package_skill.py skills/public/my-skill ./dist
"""

import fnmatch
import sys
import zipfile
from pathlib import Path
from scripts.quick_validate import validate_skill

# Patterns to exclude when packaging skills.
EXCLUDE_DIRS = {"__pycache__", "node_modules"}
EXCLUDE_GLOBS = {"*.pyc"}
EXCLUDE_FILES = {".DS_Store"}
# Directories excluded only at the skill root (not when nested deeper).
ROOT_EXCLUDE_DIRS = {"evals"}


def should_exclude(rel_path: Path) -> bool:
    """Check if a path should be excluded from packaging."""
    parts = rel_path.parts
    if any(part in EXCLUDE_DIRS for part in parts):
        return True
    # rel_path is relative to skill_path.parent, so parts[0] is the skill
    # folder name and parts[1] (if present) is the first subdir.
    if len(parts) > 1 and parts[1] in ROOT_EXCLUDE_DIRS:
        return True
    name = rel_path.name
    if name in EXCLUDE_FILES:
        return True
    return any(fnmatch.fnmatch(name, pat) for pat in EXCLUDE_GLOBS)


def package_skill(skill_path, output_dir=None):
    """
    Package a skill folder into a .skill file.

    Args:
        skill_path: Path to the skill folder
        output_dir: Optional output directory for the .skill file (defaults to current directory)

    Returns:
        Path to the created .skill file, or None if error
    """
    skill_path = Path(skill_path).resolve()

    # Validate skill folder exists
    if not skill_path.exists():
        print(f"❌ Error: Skill folder not found: {skill_path}")
        return None

    if not skill_path.is_dir():
        print(f"❌ Error: Path is not a directory: {skill_path}")
        return None

    # Validate SKILL.md exists
    skill_md = skill_path / "SKILL.md"
    if not skill_md.exists():
        print(f"❌ Error: SKILL.md not found in {skill_path}")
        return None

    # Run validation before packaging
    print("🔍 Validating skill...")
    valid, message = validate_skill(skill_path)
    if not valid:
        print(f"❌ Validation failed: {message}")
        print("   Please fix the validation errors before packaging.")
        return None
    print(f"✅ {message}\n")

    # Determine output location
    skill_name = skill_path.name
    if output_dir:
        output_path = Path(output_dir).resolve()
        output_path.mkdir(parents=True, exist_ok=True)
    else:
        output_path = Path.cwd()

    skill_filename = output_path / f"{skill_name}.skill"

    # Create the .skill file (zip format)
    try:
        with zipfile.ZipFile(skill_filename, 'w', zipfile.ZIP_DEFLATED) as zipf:
            # Walk through the skill directory, excluding build artifacts
            for file_path in skill_path.rglob('*'):
                if not file_path.is_file():
                    continue
                arcname = file_path.relative_to(skill_path.parent)
                if should_exclude(arcname):
                    print(f"  Skipped: {arcname}")
                    continue
                zipf.write(file_path, arcname)
                print(f"  Added: {arcname}")

        print(f"\n✅ Successfully packaged skill to: {skill_filename}")
        return skill_filename

    except Exception as e:
        print(f"❌ Error creating .skill file: {e}")
        return None


def main():
    if len(sys.argv) < 2:
        print("Usage: python utils/package_skill.py <path/to/skill-folder> [output-directory]")
        print("\nExample:")
        print("  python utils/package_skill.py skills/public/my-skill")
        print("  python utils/package_skill.py skills/public/my-skill ./dist")
        sys.exit(1)

    skill_path = sys.argv[1]
    output_dir = sys.argv[2] if len(sys.argv) > 2 else None

    print(f"📦 Packaging skill: {skill_path}")
    if output_dir:
        print(f"   Output directory: {output_dir}")
    print()

    result = package_skill(skill_path, output_dir)

    if result:
        sys.exit(0)
    else:
        sys.exit(1)


if __name__ == "__main__":
    main()

scripts/quick_validate.py

Descargar scripts/quick_validate.py

#!/usr/bin/env python3
"""
Quick validation script for skills - minimal version
"""

import sys
import os
import re
import yaml
from pathlib import Path

def validate_skill(skill_path):
    """Basic validation of a skill"""
    skill_path = Path(skill_path)

    # Check SKILL.md exists
    skill_md = skill_path / 'SKILL.md'
    if not skill_md.exists():
        return False, "SKILL.md not found"

    # Read and validate frontmatter
    content = skill_md.read_text()
    if not content.startswith('---'):
        return False, "No YAML frontmatter found"

    # Extract frontmatter
    match = re.match(r'^---\n(.*?)\n---', content, re.DOTALL)
    if not match:
        return False, "Invalid frontmatter format"

    frontmatter_text = match.group(1)

    # Parse YAML frontmatter
    try:
        frontmatter = yaml.safe_load(frontmatter_text)
        if not isinstance(frontmatter, dict):
            return False, "Frontmatter must be a YAML dictionary"
    except yaml.YAMLError as e:
        return False, f"Invalid YAML in frontmatter: {e}"

    # Define allowed properties
    ALLOWED_PROPERTIES = {'name', 'description', 'license', 'allowed-tools', 'metadata', 'compatibility'}

    # Check for unexpected properties (excluding nested keys under metadata)
    unexpected_keys = set(frontmatter.keys()) - ALLOWED_PROPERTIES
    if unexpected_keys:
        return False, (
            f"Unexpected key(s) in SKILL.md frontmatter: {', '.join(sorted(unexpected_keys))}. "
            f"Allowed properties are: {', '.join(sorted(ALLOWED_PROPERTIES))}"
        )

    # Check required fields
    if 'name' not in frontmatter:
        return False, "Missing 'name' in frontmatter"
    if 'description' not in frontmatter:
        return False, "Missing 'description' in frontmatter"

    # Extract name for validation
    name = frontmatter.get('name', '')
    if not isinstance(name, str):
        return False, f"Name must be a string, got {type(name).__name__}"
    name = name.strip()
    if name:
        # Check naming convention (kebab-case: lowercase with hyphens)
        if not re.match(r'^[a-z0-9-]+$', name):
            return False, f"Name '{name}' should be kebab-case (lowercase letters, digits, and hyphens only)"
        if name.startswith('-') or name.endswith('-') or '--' in name:
            return False, f"Name '{name}' cannot start/end with hyphen or contain consecutive hyphens"
        # Check name length (max 64 characters per spec)
        if len(name) > 64:
            return False, f"Name is too long ({len(name)} characters). Maximum is 64 characters."

    # Extract and validate description
    description = frontmatter.get('description', '')
    if not isinstance(description, str):
        return False, f"Description must be a string, got {type(description).__name__}"
    description = description.strip()
    if description:
        # Check for angle brackets
        if '<' in description or '>' in description:
            return False, "Description cannot contain angle brackets (< or >)"
        # Check description length (max 1024 characters per spec)
        if len(description) > 1024:
            return False, f"Description is too long ({len(description)} characters). Maximum is 1024 characters."

    # Validate compatibility field if present (optional)
    compatibility = frontmatter.get('compatibility', '')
    if compatibility:
        if not isinstance(compatibility, str):
            return False, f"Compatibility must be a string, got {type(compatibility).__name__}"
        if len(compatibility) > 500:
            return False, f"Compatibility is too long ({len(compatibility)} characters). Maximum is 500 characters."

    return True, "Skill is valid!"

if __name__ == "__main__":
    if len(sys.argv) != 2:
        print("Usage: python quick_validate.py <skill_directory>")
        sys.exit(1)
    
    valid, message = validate_skill(sys.argv[1])
    print(message)
    sys.exit(0 if valid else 1)

scripts/run_eval.py

Descargar scripts/run_eval.py

Recurso binario

scripts/run_loop.py

Descargar scripts/run_loop.py

Recurso binario

scripts/utils.py

Descargar scripts/utils.py

"""Shared utilities for skill-creator scripts."""

from pathlib import Path



def parse_skill_md(skill_path: Path) -> tuple[str, str, str]:
    """Parse a SKILL.md file, returning (name, description, full_content)."""
    content = (skill_path / "SKILL.md").read_text()
    lines = content.split("\n")

    if lines[0].strip() != "---":
        raise ValueError("SKILL.md missing frontmatter (no opening ---)")

    end_idx = None
    for i, line in enumerate(lines[1:], start=1):
        if line.strip() == "---":
            end_idx = i
            break

    if end_idx is None:
        raise ValueError("SKILL.md missing frontmatter (no closing ---)")

    name = ""
    description = ""
    frontmatter_lines = lines[1:end_idx]
    i = 0
    while i < len(frontmatter_lines):
        line = frontmatter_lines[i]
        if line.startswith("name:"):
            name = line[len("name:"):].strip().strip('"').strip("'")
        elif line.startswith("description:"):
            value = line[len("description:"):].strip()
            # Handle YAML multiline indicators (>, |, >-, |-)
            if value in (">", "|", ">-", "|-"):
                continuation_lines: list[str] = []
                i += 1
                while i < len(frontmatter_lines) and (frontmatter_lines[i].startswith("  ") or frontmatter_lines[i].startswith("\t")):
                    continuation_lines.append(frontmatter_lines[i].strip())
                    i += 1
                description = " ".join(continuation_lines)
                continue
            else:
                description = value.strip('"').strip("'")
        i += 1

    return name, description, content

Ver en GitHub

Ver en GitHub

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter (name, description required)
│   └── Markdown instructions
└── Bundled Resources (optional)
    ├── scripts/    - Executable code for deterministic/repetitive tasks
    ├── references/ - Docs loaded into context as needed
    └── assets/     - Files used in output (templates, icons, fonts)

cloud-deploy/
├── SKILL.md (workflow + selection)
└── references/
    ├── aws.md
    ├── gcp.md
    └── azure.md

## Report structure
ALWAYS use this exact template:
# [Title]
## Executive summary
## Key findings
## Recommendations

## Commit message format
**Example 1:**
Input: Added user authentication with JWT tokens
Output: feat(auth): implement JWT-based authentication

{
  "skill_name": "example-skill",
  "evals": [
    {
      "id": 1,
      "prompt": "User's task prompt",
      "expected_output": "Description of expected result",
      "files": []
    }
  ]
}

Execute this task:
- Skill path: <path-to-skill>
- Task: <eval prompt>
- Input files: <eval files if any, or "none">
- Save outputs to: <workspace>/iteration-<N>/eval-<ID>/with_skill/outputs/
- Outputs to save: <what the user cares about — e.g., "the .docx file", "the final CSV">

{
  "eval_id": 0,
  "eval_name": "descriptive-name-here",
  "prompt": "The user's task prompt",
  "assertions": []
}

{
  "total_tokens": 84852,
  "duration_ms": 23332,
  "total_duration_seconds": 23.3
}

{
  "reviews": [
    {"run_id": "eval-0-with_skill", "feedback": "the chart is missing axis labels", "timestamp": "..."},
    {"run_id": "eval-1-with_skill", "feedback": "", "timestamp": "..."},
    {"run_id": "eval-2-with_skill", "feedback": "perfect, love this", "timestamp": "..."}
  ],
  "status": "complete"
}

kill $VIEWER_PID 2>/dev/null

[
  {"query": "the user prompt", "should_trigger": true},
  {"query": "another prompt", "should_trigger": false}
]

python -m scripts.run_loop \
  --eval-set <path-to-trigger-eval.json> \
  --skill-path <path-to-skill> \
  --model <model-id-powering-this-session> \
  --max-iterations 5 \
  --verbose

python -m scripts.package_skill <path/to/skill-folder>