skill-creator

Skill Creator

Una habilidad para crear nuevas habilidades y mejorarlas de forma iterativa.

A alto nivel, 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
• Redacta un borrador de la habilidad
• Crea algunas indicaciones de prueba y ejecuta claude-con-acceso-a-la-habilidad sobre ellas
• Ayuda al usuario a evaluar los resultados tanto cualitativa como cuantitativamente
  • Mientras se ejecutan las pruebas en segundo plano, redacta algunas evaluaciones cuantitativas si no las hay (si ya existen, puedes usarlas tal cual o modificarlas si crees que algo debe cambiar). Luego explícalas al usuario (o si ya existían, explica las que ya existen)
  • Usa el script eval-viewer/generate_review.py para mostrar los resultados al usuario para que los examine, y también permítele ver las métricas cuantitativas
• Reescribe la habilidad basándote en la retroalimentación de la evaluación del usuario sobre los resultados (y también si hay fallos evidentes que se hagan patentes en las comparativas cuantitativas)
• Repite hasta que estés satisfecho
• Amplía el conjunto de pruebas y vuelve a intentarlo a mayor escala

Tu trabajo al usar esta habilidad es averiguar en qué parte del proceso se encuentra el usuario y luego intervenir para ayudarlo a avanzar en estas etapas. Por ejemplo, tal vez digan "Quiero hacer una habilidad para X". Puedes ayudar a precisar lo que quieren decir, redactar un borrador, escribir los casos de prueba, determinar cómo quieren evaluar, ejecutar todas las indicaciones y repetir.

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

Por supuesto, siempre debes ser flexible y si el usuario dice algo como "No necesito ejecutar un montón de evaluaciones, solo acompáñame", puedes hacerlo.

Luego, una vez que la habilidad esté lista (pero, de nuevo, el orden es flexible), también puedes ejecutar el mejorador de descripción de habilidades, para lo cual tenemos un script separado, para optimizar la activación de la habilidad.

¿Vale? Vale.

Comunicación con el usuario

Es probable que el creador de habilidades sea utilizado por personas con niveles muy variados de familiaridad con la jerga de programación. Si no has oído (y cómo podrías, ya que es muy reciente), hay una tendencia ahora en la que el poder de Claude está inspirando a fontaneros a abrir sus terminales, a padres y abuelos a buscar en Google "cómo instalar npm". Por otro lado, la mayoría de los usuarios probablemente tengan una alfabetización informática bastante buena.

Así que presta atención a las señales de contexto para saber cómo formular tu comunicación. Por defecto, para que te hagas una idea:

• "evaluación" y "comparativa" están en el límite, pero están bien
• Para "JSON" y "aserción" necesitas ver señales serias de que el usuario sabe lo que son antes de usarlos sin explicarlos

Está bien explicar brevemente los términos si tienes dudas, y si no estás seguro de si el usuario los entenderá, siéntete libre de aclararlos con una breve definición.

---

Crear una habilidad

Capturar la intención

Empieza por entender la intención del usuario. La conversación actual podría contener ya un flujo de trabajo que el usuario quiera capturar (por ejemplo, dicen "convierte esto en una habilidad"). Si es así, extrae las respuestas del historial de la conversación primero: las herramientas utilizadas, la secuencia de pasos, las correcciones que hizo el usuario, los formatos de entrada/salida observados. Es posible que el usuario necesite completar los vacíos, y debe confirmar antes de pasar al siguiente paso.

1. ¿Qué debería permitir hacer esta habilidad a Claude?
2. ¿Cuándo debería activarse esta habilidad? (qué frases/contextos del usuario)
3. ¿Cuál es el formato de salida esperado?
4. ¿Deberíamos configurar casos de prueba para verificar que la habilidad funciona? 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 los necesitan. Sugiere el valor predeterminado apropiado según el tipo de habilidad, pero deja que el usuario decida.

Entrevista e investigación

Pregunta proactivamente sobre casos límite, formatos de entrada/salida, archivos de ejemplo, criterios de éxito y dependencias. Espera a que esta parte esté resuelta antes de escribir indicaciones de prueba.

Revisa los MCPs disponibles; si son útiles para la investigación (buscar documentación, encontrar habilidades similares, consultar mejores prácticas), investiga en paralelo mediante subagentes si están disponibles, o en línea si no. Ven preparado con contexto para reducir la carga sobre el usuario.

Redactar el SKILL.md

Basado en la entrevista al usuario, completa estos componentes:

• name: Identificador de la habilidad
• description: Cuándo activarse, qué hace. Este es el mecanismo principal de activación: incluye tanto lo que hace la habilidad como los contextos específicos para cuándo usarla. Toda la información de "cuándo usar" va aquí, no en el cuerpo. Nota: actualmente Claude tiene tendencia a "infra-activar" las habilidades, es decir, a no usarlas cuando serían útiles. Para combatir esto, haz que las descripciones de las habilidades sean un poco "insistentes". Por ejemplo, en lugar de "Cómo construir un panel rápido y simple para mostrar datos internos de Anthropic.", podrías escribir "Cómo construir un panel rápido y simple para mostrar datos internos de Anthropic. Asegúrate de usar 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 pide explícitamente un 'panel'."
• compatibility: Herramientas necesarias, dependencias (opcional, rara vez necesario)
• el resto de la habilidad :)

Guía para escribir habilidades

Anatomía de una habilidad

skill-name/
├── SKILL.md (obligatorio)
│   ├── Frontmatter YAML (nombre, descripción obligatorios)
│   └── Instrucciones en Markdown
└── Recursos empaquetados (opcional)
    ├── scripts/    - Código ejecutable para tareas deterministas/repetitivas
    ├── references/ - Documentos cargados en contexto según sea necesario
    └── assets/     - Archivos utilizados en la salida (plantillas, iconos, fuentes)

Divulgación progresiva

Las habilidades utilizan un sistema de carga de tres niveles:

1. Metadatos (nombre + descripción) - Siempre en contexto (~100 palabras)
2. Cuerpo del SKILL.md - En contexto cada vez que se activa la habilidad (<500 líneas ideal)
3. Recursos empaquetados - Según sea necesario (ilimitado, los scripts pueden ejecutarse sin cargarse)

Estos recuentos de palabras son aproximados y puedes extenderlos si es necesario.

Patrones clave:

• Mantén SKILL.md por debajo de 500 líneas; si te acercas a este límite, añade una capa adicional de jerarquía junto con indicaciones claras sobre dónde debe ir el modelo que usa la habilidad a continuación.
• Haz referencia clara a archivos desde SKILL.md con orientación sobre cuándo leerlos
• Para archivos de referencia grandes (>300 líneas), incluye una tabla de contenido

Organización por dominio: Cuando una habilidad admite múltiples dominios/marcos de trabajo, organiza por variante:

cloud-deploy/
├── SKILL.md (flujo de trabajo + selección)
└── references/
    ├── aws.md
    ├── gcp.md
    └── azure.md

Claude lee solo el archivo de referencia relevante.

Principio de ausencia de sorpresa

No hace falta decirlo, pero las habilidades 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 debe sorprender al usuario en su intención si se describe. No accedas a solicitudes para crear habilidades engañosas o diseñadas para facilitar el acceso no autorizado, la exfiltración de datos u otras actividades maliciosas. Cosas como "rolear como un XYZ" están bien.

Patrones de escritura

Prefiere usar la forma imperativa en las instrucciones.

Definición de formatos de salida - Puedes hacerlo así:

## Estructura del informe
Usa SIEMPRE esta plantilla exacta:
# [Título]
## Resumen ejecutivo
## Hallazgos clave
## Recomendaciones

Patrón de ejemplos - Es útil incluir ejemplos. Puedes formatearlos así (pero si "Entrada" y "Salida" están en los ejemplos, quizás quieras desviarte un poco):

## Formato del mensaje de commit
**Ejemplo 1:**
Entrada: Añadida autenticación de usuario con tokens JWT
Salida: feat(auth): implementar autenticación basada en JWT

Estilo de escritura

Intenta explicar al modelo por qué las cosas son importantes en lugar de usar obligaciones pesadas. Usa la teoría de la mente y trata de que la habilidad sea general y no demasiado estrecha a ejemplos específicos. Empieza redactando un borrador y luego míralo con ojos frescos y mejóralo.

Casos de prueba

Después de redactar el borrador de la habilidad, propón 2-3 indicaciones de prueba realistas, del tipo que un usuario real diría. Compártelas con el usuario: [no tienes que usar este lenguaje exacto] "Aquí tienes algunos casos de prueba que me gustaría probar. ¿Te parecen correctos, o quieres añadir más?" Luego ejecútalos.

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

{
  "skill_name": "example-skill",
  "evals": [
    {
      "id": 1,
      "prompt": "Indicación de tarea del usuario",
      "expected_output": "Descripción del resultado esperado",
      "files": []
    }
  ]
}

Consulta references/schemas.md para el esquema completo (incluyendo el campo assertions, que añadirás más tarde).

Ejecutar y evaluar casos de prueba

Esta sección es una secuencia continua: no te detengas a medio camino. NO uses /skill-test ni ninguna otra habilidad de prueba.

Coloca los resultados en <skill-name>-workspace/ como directorio hermano del directorio de la habilidad. Dentro del espacio de trabajo, organiza los resultados por iteración (iteration-1/, iteration-2/, etc.) y dentro de cada una, cada caso de prueba tiene su propio directorio (eval-0/, eval-1/, etc.). No crees todo esto de antemano, solo crea directorios a medida que avanzas.

Paso 1: Lanzar todas las ejecuciones (con-habilidad Y línea base) en el mismo turno

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

Ejecución con habilidad:

Ejecuta esta tarea:
- Ruta de la habilidad: <ruta-de-la-habilidad>
- Tarea: <indicación de evaluación>
- Archivos de entrada: <archivos de evaluación si los hay, o "ninguno">
- Guardar salidas en: <espacio-de-trabajo>/iteration-<N>/eval-<ID>/with_skill/outputs/
- Salidas a guardar: <lo que le importa al usuario, p.ej., "el archivo .docx", "el CSV final">

Ejecución de línea base (misma indicación, pero la línea base depende del contexto):

• Crear una nueva habilidad: sin ninguna habilidad. Misma indicación, sin ruta de habilidad, guardar en without_skill/outputs/.
• Mejorar una habilidad existente: la versión anterior. Antes de editar, haz una instantánea de la habilidad (cp -r <ruta-habilidad> <espacio-de-trabajo>/skill-snapshot/), luego apunta el subagente de línea base a la instantánea. Guarda en old_skill/outputs/.

Escribe un eval_metadata.json para cada caso de prueba (las aserciones pueden estar vacías por ahora). Dale a cada evaluación un nombre descriptivo basado en lo que está probando, no solo "eval-0". Usa este nombre también para el directorio. Si esta iteración usa indicaciones de evaluación nuevas o modificadas, crea estos archivos para cada nuevo directorio de evaluación; no asumas que se heredan de iteraciones anteriores.

{
  "eval_id": 0,
  "eval_name": "nombre-descriptivo-aqui",
  "prompt": "La indicación de tarea del usuario",
  "assertions": []
}

Paso 2: Mientras las ejecuciones están en curso, redacta aserciones

No esperes simplemente a que terminen las ejecuciones; puedes usar este tiempo de manera productiva. Redacta aserciones cuantitativas para cada caso de prueba y explícalas al usuario. Si ya existen aserciones en evals/evals.json, revísalas y explica qué verifican.

Las buenas aserciones son objetivamente verificables y tienen nombres descriptivos; deben leerse claramente en el visor de comparativas para que alguien que vea los resultados de un vistazo entienda inmediatamente qué verifica cada una. Las habilidades subjetivas (estilo de escritura, calidad de diseño) se evalúan mejor cualitativamente; no fuerces aserciones en cosas que necesitan juicio humano.

Actualiza los archivos eval_metadata.json y evals/evals.json con las aserciones una vez redactadas. También explica al usuario lo que verá en el visor: tanto las salidas cualitativas como la comparativa cuantitativa.

Paso 3: A medida que las ejecuciones se completan, captura los datos de temporización

Cuando cada tarea de subagente se complete, recibirás una notificación que contiene total_tokens y duration_ms. Guarda estos datos inmediatamente en timing.json en el directorio de la ejecución:

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

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

Paso 4: Calificar, agregar y lanzar el visor

Una vez que todas las ejecuciones hayan terminado:

1. Califica cada ejecución: lanza un subagente calificador (o califica en línea) que lea agents/grader.md y evalúe cada aserción contra las salidas. Guarda los resultados en grading.json en cada directorio de ejecución. La matriz de expectativas en grading.json debe usar los campos text, passed y evidence (no name/met/details u otras variantes); el visor depende de estos nombres de campo exactos. Para aserciones que se puedan verificar mediante programación, escribe y ejecuta un script en lugar de hacerlo a ojo: los scripts son más rápidos, más fiables y se pueden reutilizar entre iteraciones.

2. Agrega en una comparativa: ejecuta el script de agregación desde el directorio del creador de habilidades:

   python -m scripts.aggregate_benchmark <espacio-de-trabajo>/iteration-N --skill-name <nombre>
   

   Esto produce benchmark.json y benchmark.md con tasa_de_aciertos, tiempo y tokens para cada configuración, con media ± desviación estándar y el delta. Si generas benchmark.json manualmente, consulta references/schemas.md para el esquema exacto que espera el visor. Coloca cada versión con_habilidad antes de su contraparte de línea base.

3. Realiza un análisis: lee los datos de la comparativa y detecta patrones que las estadísticas agregadas podrían ocultar. Consulta agents/analyzer.md (la sección "Análisis de resultados de la comparativa") para saber qué buscar: cosas como aserciones que siempre pasan independientemente de la habilidad (no discriminatorias), evaluaciones con alta varianza (posiblemente inestables) y compensaciones de tiempo/tokens.

4. Lanza el visor con ambas salidas cualitativas y datos cuantitativos:

   nohup python <ruta-del-creador-de-habilidades>/eval-viewer/generate_review.py
   

…

[truncado para la traducción]