skill-authoring

Skill Authoring

Guía para crear skills que realmente cambien el comportamiento del agente, no documentos que nunca se lean.

Principio fundamental: un skill es una instrucción operativa, no un artículo. Si el agente no actúa de manera diferente después de cargar este skill, el skill ha fallado.

Cómo Usar Este Skill

Este skill se usa mediante conversación, no de una sola vez. El flujo es:

1. El usuario activa el skill (ejemplo: "usa el skill skill-authoring, quiero crear un skill para mi agente").
2. El agente deja de escribir y comienza la entrevista del Paso 1: una pregunta por turno, espera la respuesta.
3. Después de que se hayan respondido las cinco preguntas, el agente ejecuta los Pasos 2 al 5 y muestra el borrador al usuario.
4. Una vez que el usuario está de acuerdo, el agente escribe el archivo (Paso 6), luego ejecuta la prueba de activación (Paso 7) y la lista de verificación (Paso 8).

Reglas para el agente:

• No escribas SKILL.md antes de que se hayan respondido las cinco preguntas del Paso 1. Un borrador prematuro detiene la entrevista.
• No hagas las cinco preguntas a la vez. Una por turno, con un breve ejemplo en cada pregunta.
• Si el usuario solo quiere un "ejemplo rápido", haz solo las preguntas 1 y 4, y luego continúa.
• Menciona al principio que el resultado final es un único archivo SKILL.md listo para usar.

Cuándo Está Activo Este Skill

• El usuario dice "crear skill", "hacer skill", "cómo crear un skill", "skill para mi agente".
• El usuario tiene una idea para una capacidad del agente pero no sabe cómo plasmarla.
• Un skill existente nunca se activa o el agente no lo sigue.
• Se necesita decidir: ¿esto debe ser un skill, un agente, un comando o un gancho?

Para buscar skills existentes, usa primero skill-scout. Para auditar skills acumulados, usa skill-stocktake.

Paso 0 - Reglas Básicas Antes de Escribir

Un skill de calidad tiene cuatro propiedades:

Propiedad	Significado
Específico	Resuelve un tipo de trabajo, no "todo sobre backend"
Operativo	Contiene pasos, comandos, ejemplos reales, no teoría
Con disparador	description incluye palabras que realmente usa el usuario
Limitado	Menos de 500 líneas; idealmente 100-250 líneas

Si la idea del skill no cumple estas cuatro, mejora primero la idea, no escribas el archivo.

Paso 1 - Captura el Problema Real, No la Función

No empieces con "skill para testing". Empieza con un fallo concreto.

Haz estas cinco preguntas al usuario (una por una, no todas a la vez):

1. ¿Qué está haciendo el agente mal o de forma inconsistente ahora? Da un ejemplo real.
2. ¿Cuándo ocurre eso? (escribiendo código, revisando PR, desplegando, respondiendo al usuario, analizando datos)
3. ¿Cómo es el resultado correcto? Muestra un ejemplo de salida que el usuario considere buena.
4. ¿Qué información no sabe el agente y se le debe dar a través de este skill? (convenciones del equipo, secuencia de pasos, trampas)
5. ¿Qué no debe hacer el agente al ejecutar este skill?

Las respuestas a las preguntas 4 y 5 son el contenido real del skill. Las respuestas a las preguntas 1 y 2 son el contenido de description.

Si el usuario no puede responder a la pregunta 1, detén el proceso. Aún no es necesario crear un skill, solo hay un deseo. Dilo.

Paso 2 - Elige la Forma Correcta

No conviertas todo en un skill. Elige la forma más económica que resuelva el problema.

Necesidad	Forma	Razón
Conocimiento/convenciones usadas repetidamente al escribir código	Skill	Se carga automáticamente, no necesita ser invocado
Trabajo independiente de múltiples pasos con contexto separado	Agente	Se puede ejecutar en paralelo, tiene su propio contexto
Acción que el usuario activa conscientemente con argumentos	Comando	/{nombre} explícito, no automático
Comportamiento automático en eventos (antes de commit, después de editar)	Gancho	Se ejecuta sin decisión del modelo
Reglas cortas que aplican a todo el trabajo	Regla	Siempre activo, sin disparador
Explicación larga para ser leída por humanos	Documento	No necesita ser cargado por el agente

Regla práctica:

• ¿Necesita disparador? Skill.
• ¿Necesita contexto separado o herramientas limitadas? Agente.
• ¿Necesita ser invocado manualmente con parámetros? Comando.
• ¿Necesita ejecutarse sin ser solicitado? Gancho.
• ¿Necesita ser siempre correcto, nunca violado? Regla.
• ¿Necesita ser leído por humanos, no por el agente? Documento.

Si dudas entre skill y regla: si el contenido tiene menos de 10 líneas y aplica en todas partes, es una regla.

Paso 3 - Busca Duplicados Primero

Antes de escribir, busca primero. La carpeta de skills varía según el arnés - ajústala a la del usuario:

Arnés	Carpeta de skills
Claude Code	~/.claude/skills/ o .claude/skills/ en el proyecto
OpenCode	~/.config/opencode/skills/ o .opencode/skills/
Cursor	.cursor/skills/
Codex	.agents/skills/

# skills ya instalados (cambia <carpeta-skills> según la tabla anterior)
grep -ril "palabras-clave" <carpeta-skills> --include=SKILL.md

# si estás dentro de un repo que tiene una carpeta skills/
grep -ril "palabras-clave" skills --include=SKILL.md

Si el usuario no sabe dónde está su carpeta de skills, explica la tabla anterior y pídele que elija el arnés que usa. No adivines.

Si ya existe un skill muy similar, elige: usarlo tal cual, extender el existente, o crear uno nuevo. Skills duplicados confunden al agente al elegir y sobrecargan el contexto.

Paso 4 - Escribe description (La Parte Más Decisiva)

description es la única parte que el agente lee para decidir si cargar el skill o no. Un error aquí significa un skill muerto.

Fórmula:

[actividad que se realiza] + [contexto desencadenante] + [palabras clave que usa el usuario] + [cuándo NO usarlo]

Ejemplo malo:

description: Ayuda con testing

Ejemplo bueno:

description: Patrones de prueba React con Vitest y Testing Library - renderizado, eventos de usuario, mock de red y aserciones de accesibilidad. Úsalo al escribir o corregir pruebas de componentes React. No para E2E (usa e2e-testing).

Reglas:

• Menciona palabras que realmente escribe el usuario, no términos internos.
• Menciona los límites para que el skill no usurpe el trabajo de otros skills.
• Una línea, sin saltos de línea dentro de la cadena.
• Evita palabras genéricas sueltas como "código", "ayuda", "varios".

Prueba rápida: cierra el archivo, lee solo description. Si tú como agente no sabes exactamente cuándo cargarlo, reescríbelo.

Paso 5 - Organiza el Contenido

El orden de las secciones que funciona:

---
name: nombre-skill
description: <fórmula del Paso 4>
metadata:
  origin: ECC
---

# Título

Un párrafo: qué cambia este skill en el comportamiento del agente.

## Cuándo Está Activo
Lista de disparadores concretos.

## Contenido Principal
Pasos de trabajo, tabla de decisiones o reglas. Esto es el 70% del skill.

## Ejemplos
Un ejemplo incorrecto, un ejemplo correcto. Reales, no marcadores de posición.

## Anti-Patrones
Errores que se deben evitar, con una breve razón.

## Lista de Verificación
Casillas de verificación verificables.

## Skills Relacionados
De dos a cuatro nombres de skills.

Reglas de redacción del contenido:

• Frases imperativas ("Haz X"), no descripciones pasivas ("X se puede hacer").
• Tablas para decisiones, listas numeradas para secuencias, bloques de código para comandos.
• Cada regla debe ser verificable - "escribe código limpio" no lo es, "función de máximo 50 líneas" sí.
• Sin marcadores de posición como [insertar aquí], TODO, o ... en las partes que ejecuta el agente.
• Sin identidades de productos externos copiadas textualmente - toma la idea, reescríbela con tu propio contexto.
• Sin secretos: claves API, tokens, rutas personales absolutas, nombres internos de empresas.

Límite de longitud: 500 líneas (máximo estricto 800). Si es más, divídelo en dos skills o mueve los detalles a references/ en la misma carpeta de skills.

Paso 6 - Escribe el Archivo

Antes de escribir, pregunta dos cosas:

1. Idioma del skill - el idioma que usa el usuario a diario, o inglés para portabilidad? Sigue la respuesta, no elijas al azar.
2. Nombre de la carpeta - sugiere un nombre en kebab-case descriptivo (ejemplo: test-componentes-react), pide aprobación.

Luego escribe en <carpeta-skills>/<nombre>/SKILL.md. Reglas que no se pueden incumplir:

• name: en el frontmatter debe ser exactamente igual que el nombre de la carpeta. Sin esto, algunos arneses rechazan cargar el skill.
• Muestra el borrador completo al usuario primero, luego guarda. No guardes en secreto.
• Sin marcadores de posición (TODO, [insertar aquí], ...) en las partes que ejecutará el agente.
• Después de guardar, informa la ruta completa y una frase sobre cómo activarlo: "Después de esto, pídele al agente que use el skill <nombre> cuando ."

Paso 7 - Prueba Antes de Usar

Tres pruebas mínimas. No te saltes ninguna.

Prueba 1 - Disparador positivo (activación) Dale al agente una tarea que debería activar este skill, sin mencionar el nombre del skill.

"Por favor, escribe una prueba para el componente LoginButton."

Aprueba si el skill se carga. Falla si description carece de palabras clave.

Prueba 2 - Disparador negativo (no activación) Dale una tarea similar pero que no sea su dominio.

"Por favor, escribe una prueba E2E para el flujo de inicio de sesión."

Aprueba si el skill NO se carga (o el agente elige otro skill adecuado). Falla si description es demasiado amplia.

Prueba 3 - Ejecución Pídele al agente que realice una tarea que realmente active el skill, luego compara la salida con la de sin el skill.

Sin skill: el agente escribe pruebas de estilo X
Con skill: el agente escribe pruebas de estilo Y (según las convenciones del equipo)

Aprueba si hay una diferencia de comportamiento demostrable. Si la salida es idéntica, el skill es inútil - bórralo o combínalo.

Paso 8 - Lista de Verificación Listo para Enviar

• El archivo está en <carpeta-skills>/{nombre}/SKILL.md, y name: es exactamente igual que el nombre de la carpeta
• description es una sola línea, contiene las palabras clave del usuario y los límites de alcance
• description no usa bloques literales (|), solo una cadena en línea
• Hay una sección "Cuándo Está Activo" explícita
• Cada regla es verificable, no hay "escribe buen código"
• Hay al menos un ejemplo incorrecto y uno correcto
• Hay un anti-patrón
• Menos de 500 líneas
• No hay secretos, tokens o rutas personales absolutas
• Las pruebas 1, 2 y 3 se han ejecutado y se han registrado los resultados
• El Paso 3 se ha ejecutado, no hay duplicados
• Menciona 2-4 skills relacionados al final

Validación automática solo si está disponible en el repositorio del usuario:

# ECC / repositorio que tiene un validador de skills
node scripts/ci/validate-skills.js

Si no hay validador, verifica manualmente las cuatro cosas que fallan con más frecuencia: name: coincide con la carpeta, description en una línea, líneas menores a 500, y sin marcadores de posición. Dile al usuario que se usa esta verificación manual.

Plantilla Lista para Usar

---
name: nombre-skill
description: <actividad> - <alcance>. Úsalo cuando <disparador concreto>. No para <fuera de alcance>.
metadata:
  origin: ECC
---

# Nombre del Skill

Qué cambia en el comportamiento del agente después de cargar este skill.

## Cuándo Está Activo
- <disparador 1>
- <disparador 2>

## Pasos
1. <primer paso que se pueda ejecutar directamente>
2. <segundo paso>
3. <verificación>

## Ejemplos
Incorrecto: <código o respuesta que suele aparecer>
Correcto: <versión deseada, con una breve razón>

## Anti-Patrones
- <error> - <por qué es malo>

## Lista de Verificación
- [ ] <algo que se pueda verificar con máquina o a simple vista>

## Skills Relacionados
- `<skill-a>`, `<skill-b>`

Anti-Patrones de Creación de Skills

• Skill sin disparador. description vago, el skill nunca se carga. Esta es la causa más común de fracaso.
• Skill muro de texto. 900 líneas de teoría sin un solo comando. El agente lo carga y lo ignora.
• Skill "sé útil". Sin conocimiento específico, el resultado es idéntico a no tener skill.
• Skill duplicado. Dos skills reclaman el mismo dominio; el agente elige al azar.
• Copiar el skill de otra persona íntegramente. Incluye instrucciones ocultas y dependencias que no conoces.
• Skill con secretos o rutas personales. Se difunde cuando el skill se comparte.
• Escribir un skill para un solo evento. Si solo se usa una vez, no es un skill, es documentación o un comando.
• Crear un skill antes de buscar. Siempre ejecuta el Paso 3.

Cuándo NO Es Necesario Crear un Skill

Díselo claramente al usuario si se cumple alguna de estas condiciones:

• El problema es un error en el código, no falta de conocimiento del agente.
• Solo se necesita una ejecución única - basta con dar instrucciones directas.
• El contenido tiene menos de 10 líneas de reglas generales - es una regla.
• Basta con añadirlo al AGENTS.md o CLAUDE.md del proyecto.
• Ya existe un skill que cubre el 80% de la necesidad - amplía el existente.

Skills Relacionados

• skill-scout - busca skills existentes antes de crear uno nuevo
• skill-stocktake - audita la calidad de los skills acumulados
• skill-comply - mide si el agente sigue realmente el skill
• agent-harness-construction - diseña herramientas y límites de acción del agente