🎯 Capturar el intent
skill-creator empieza por entender la intención antes de escribir una sola línea. Si la conversación ya contiene el workflow que la persona quiere capturar (dice "convierte esto en una skill"), extráelo primero de los mensajes anteriores: las herramientas usadas, la secuencia de pasos, las correcciones que hizo, los formatos de entrada y salida que aparecieron. Solo después pídele que complete los huecos, y confirma antes de continuar.
¿Qué permite hacer esta skill a Claude?
La capacidad central. No "ayudar con hojas de cálculo", sino "calcular el margen de ganancia y agregar la columna en un xlsx".
¿Cuándo debe activarse?
Qué frases y contextos del usuario activan la skill. Eso se convierte en el corazón de la description.
¿Cuál es el formato de salida esperado?
¿Un archivo? ¿Un informe con secciones fijas? ¿Código? Definirlo pronto evita retrabajo.
¿Vale la pena preparar casos de prueba?
Las skills con resultados que se pueden verificar objetivamente (transformar un archivo, extraer datos, generar código) se benefician de las pruebas. Los resultados subjetivos (estilo, arte) generalmente no las necesitan. Sugiere la opción predeterminada y deja que el usuario decida.
💡 Cuidado con la jerga
skill-creator lo usan personas con niveles muy distintos de familiaridad técnica. Términos como "JSON" y "assertion" solo deberían aparecer sin explicación si hay indicios claros de que la persona los conoce. En caso de duda, define el término en una frase breve.
🔎 Entrevistas e investigación
Con el intent capturado, profundiza. Pregunta proactivamente sobre casos límite, formatos de entrada y salida, archivos de ejemplo, criterios de éxito y dependencias. Espera para escribir test prompts solo después de cerrar esta parte — una entrevista mal hecha genera una skill que cubre el caso ideal y falla en el resto.
✗ Entrevista superficial
- ✗Asume que solo hay un formato de entrada
- ✗Ignora lo que pasa con una entrada vacía o malformada
- ✗Nunca pide archivos de ejemplo reales
- ✗No define qué cuenta como "salió bien"
- ✗Deja el trabajo de investigación sobre los hombros del usuario
✓ Entrevista que prepara el terreno
- ✓Mapea todos los formatos plausibles de entrada y salida
- ✓Explora casos límite antes de programar
- ✓Recopila ejemplos concretos del dominio
- ✓Establece criterios de éxito explícitos
- ✓Investigación en paralelo mediante subagentes/MCP
Llega con el contexto preparado
Revisa los MCP disponibles. Si alguno es útil para la investigación —buscar documentación, encontrar skills parecidas, recopilar buenas prácticas—, investiga en paralelo mediante subagents (cuando los haya) o inline. La idea es reducir la fricción para el usuario: llegar con la tarea hecha en vez de preguntarlo todo desde cero.
📝 Escribir el SKILL.md
A partir de la entrevista, completa los componentes del archivo. El SKILL.md es un frontmatter YAML (con name e description obligatorios) seguido del cuerpo en Markdown.
Los componentes
- •name: el identificador de la skill
- •description: qué hace Y cuándo usarla. Es el mecanismo principal de activación: todo «cuándo usarla» va aquí, no en el cuerpo.
- •compatibility: herramientas/dependencias requeridas (opcional, rara vez necesario)
- •el resto de la skill :) — el cuerpo con las instrucciones
La Description debe ser un poco "pushy"
Hoy Claude tiende a subdisparar skills — no usarlas cuando serían útiles. Para combatir esto, la description debe enumerar contextos concretos de uso, aunque el usuario no lo pida explícitamente.
Débil vs. insistente:
# Fraca description: How to build a simple fast dashboard to display internal Anthropic data. # Pushy description: How to build a simple fast dashboard to display internal Anthropic data. Make sure to use this skill whenever the user mentions dashboards, data visualization, internal metrics, or wants to display any kind of company data, even if they don't explicitly ask for a 'dashboard.'
🎯 Recordatorio de la anatomía
Progressive disclosure en 3 niveles: (1) metadata name+description siempre en el contexto (~100 palabras); (2) cuerpo del SKILL.md cuando se activa, idealmente <500 líneas; (3) recursos empaquetados que se cargan bajo demanda. La description es el activador.
✍️ Estilo de escritura
La forma en que escribes el cuerpo de la skill importa tanto como lo que escribes. Prefiere el imperativo, usa theory of mind y explica el por qué de cada instrucción en vez de amontonar MUST en mayúsculas. Mantén la skill general, sin limitarla a ejemplos específicos.
✗ Estilo demasiado intrusivo
- ✗"SIEMPRE haz X. NUNCA hagas Y." en mayúsculas
- ✗Reglas rígidas sin ninguna razón
- ✗Instrucciones basadas en un único ejemplo
- ✗Trata el modelo como un ejecutor ciego
✓ Estilo que respeta el modelo
- ✓Imperativo claro: "Empieza por entender..."
- ✓Explica por qué importa cada paso
- ✓Generaliza a muchos casos
- ✓Usa theory of mind: apuesta por la inteligencia
Por qué evitar los MUSTs a gritos
Los LLM actuales son inteligentes: tienen una buena theory of mind y, con un buen harness, van más allá de las instrucciones literales. Si te encuentras escribiendo ALWAYS o NEVER en mayúsculas, o usando estructuras muy rígidas, es una yellow flag: reformula y explica la razón para que el modelo entienda por qué importa. Es más humano, más potente y más eficaz.
👀 Hacer un borrador y releerlo con ojos nuevos
No te atasques buscando el borrador perfecto. Escribe un primer borrador y luego vuelve a leerlo con ojos nuevos y mejora. El ciclo borrador → revisar → mejorar ocurre durante la propia escritura, incluso antes de cualquier prueba.
Escribe el borrador
Ponlo todo por escrito sin editar. Primero, rapidez; después, pulido.
Vuelve a leer con distancia
Míralo como si fueras otra persona leyendo. ¿Qué resulta ambiguo? ¿Qué hace que el modelo pierda tiempo sin necesidad?
Mejora
Elimina redundancias, reformula lo que estaba rígido y explica por qué lo que quedó era vago.
💡 Consejo
skill-creator repite este consejo en varios puntos: "escribe un borrador y luego míralo con ojos nuevos para mejorarlo". Se aplica a todo el SKILL.md y a cada revisión futura en el ciclo de iteración.
📦 Cuándo bundlear
No todo vive dentro del SKILL.md. Los recursos incluidos (scripts/, references/, assets/) se cargan bajo demanda. La regla práctica: si 3 ejecuciones repiten el mismo script, extrae en scripts/; los docs grandes van a references/.
Anatomía de una skill:
skill-name/ ├── SKILL.md (required) │ ├── YAML frontmatter (name, description) │ └── Markdown instructions └── Bundled Resources (optional) ├── scripts/ # código p/ tarefas repetitivas ├── references/ # docs carregadas sob demanda └── assets/ # templates, ícones, fontes
Señales de que es hora de agrupar
- •3 invocaciones independientes escribieron lo mismo
create_docx.py→ conviértete enscripts/y dile a la skill que lo use - •El cuerpo de SKILL.md está cerca de las 500 líneas → agrega una capa de jerarquía con referencias claras
- •Documento de referencia extenso (>300 líneas) → incluye un índice/TOC
- •La skill admite varios dominios → organízalos por variante en
references/(aws.md, gcp.md, azure.md)
🎯 Por qué agrupar scripts repetidos
Escribir una vez, poner en scripts/ y apuntar la skill a él evita que cada invocación futura tenga que reinventar la rueda. Los scripts se ejecutan sin necesidad de cargar todo el contenido en el contexto: es más rápido, más confiable y reutilizable entre iteraciones.
✅ Resumen del módulo
Próximo:
4.2 — 🔁 Probar, evaluar e iterar — escribe test prompts realistas, ejecútalos con skill vs. baseline, evalúa e itera hasta que la skill funcione mucho más allá de los ejemplos.