🧩 Skills

Una skill es un directorio dentro de ~/.claude/skills/ con obligatoriamente un archivo SKILL.md en la raíz. La carpeta puede contener subcarpetas (scripts/, prompting/, references/) y archivos auxiliares.

Entender que una skill es una carpeta —y no solo un archivo— cambia la forma en que organizas el conocimiento. Separas las reglas (SKILL.md) de la ejecución (scripts/) y de la documentación (references/), y mantienes todo modular y fácil de mantener.

Directorio raíz en ~/.claude/skills/nome-da-skill/; SKILL.md obligatorio; subcarpetas opcionales pero recomendadas para skills complejas; nombre del directorio en kebab-case.

El frontmatter YAML en la parte superior del SKILL.md define los metadatos de la skill: name (identificador único), description (qué hace y cuándo activarlo), y opcionalmente triggers (frases de activación explícitas).

El frontmatter es el "contrato" de la skill con el agente. Una description débil hace que la skill nunca se active o se active cuando no debe. Un frontmatter bien escrito garantiza que Claude Code sepa exactamente cuándo invocar la skill.

Bloque delimitado por ---; campos name e description obligatorios; descripción en lenguaje natural; YAML válido sin tabulaciones.

Después del frontmatter, el SKILL.md contiene el cuerpo en Markdown con: flujo de trabajo (secciones numeradas), reglas estrictas («NUNCA hagas X»), ejemplos de uso adecuado e inadecuado, referencias a archivos auxiliares y puntos de confirmación antes de acciones irreversibles.

El cuerpo es el cerebro de la skill. Aquí es donde programas el comportamiento detallado: el orden de los pasos, qué verificar y cómo informar los resultados. Un buen cuerpo reemplaza decenas de prompts manuales repetitivos.

Secciones con ## para el flujo; listas - para los pasos; bloques ``` para el código; tablas para comparar lo bueno y lo malo; reglas estrictas destacadas (**NUNCA**); referencias a ./scripts/ y ./references/.

Las skills globales están en ~/.claude/skills/ y están disponibles en cualquier proyecto. Las skills locales del proyecto pueden estar en .claude/skills/ en la raíz del repo: alcance limitado al proyecto.

Separar las skills globales (utilidades reutilizables) de las skills del proyecto (lógica específica del repo) evita la contaminación del namespace y garantiza que las skills sensibles de un cliente no se filtren a otros proyectos.

Global: ~/.claude/skills/; Local: .claude/skills/; Lo local sobrescribe lo global con el mismo nombre; las skills se aplican al contexto activo.

Claude Code recorre el directorio de skills e inyecta los metadatos (name + description) en el contexto del sistema. Cuando el mensaje del usuario coincide con la description, el agente usa la herramienta Skill para cargar y ejecutar el SKILL.md completo.

Entender el mecanismo de descubrimiento explica por qué la description es el campo más crítico. El agente no lee el cuerpo de la skill hasta que decide activarla: la descripción es la única señal de relevancia disponible en el momento de decidir.

Escaneo automático al iniciar; inyección de metadatos en el system prompt; coincidencia semántica entre description y solicitud del usuario; activación lazy (el cuerpo solo se lee cuando se activa).

Skill = comportamiento especializado reutilizable con estado y reglas (ej.: formato-curso). Prompt = instrucción puntual sin persistencia. Comando slash = atajo de teclado para prompts repetitivos. Las skills cargan contexto, scripts y referencias; los prompts y comandos no.

Elegir la herramienta equivocada cuesta tiempo. ¿Un workflow complejo de 10 pasos se convirtió en un prompt? Olvidarás algunos pasos. ¿Lo convertiste en una skill? El agente garantiza que se ejecute por completo cada vez.

Skill: persistente, con varios archivos y reglas; Prompt: sin estado, integrado y descartable; Comando slash: atajo rápido; Usa una skill cuando: el flujo sea complejo, haya reglas estrictas o se necesiten scripts auxiliares.

El campo description del frontmatter es analizado semánticamente por el agente. Compara el mensaje del usuario con todas las descriptions disponibles y activa la skill más relevante. Una description deficiente = skill invisible.

Si no entiendes cómo el agente usa la description, escribirás skills que nunca se activan o que compiten entre sí. La description es el único «anuncio» de la skill: debe ser clara, específica y cubrir los casos de uso reales.

Match semántico (no literal); description como «anuncio»; especificidad > generalidad; incluir un verbo de acción («Usa cuando...», «Activar al...»); cubrir variaciones en el lenguaje del usuario.

Las frases desencadenantes son cláusulas explícitas en la description que enumeran los escenarios de activación: "Usa cuando el usuario pida crear páginas HTML de cursos", "Activa al mencionar rutas, módulos o INEMA.CLUB". Son la "lista de casos de uso" de la skill.

Las frases de activación explícitas hacen que el comportamiento de activación sea predecible y auditable. Sin ellas, activar la skill se vuelve una adivinanza. Con ellas, puedes probar: «si digo X, ¿debería activarse la skill Y?»

Prefijos estándar: "Usa cuando", "Activar al", "TRIGGER when"; enumera contextos (no solo palabras clave); incluye sinónimos del dominio; separa con punto y coma para mayor claridad.

Las cláusulas SKIP en la description enumeran los casos en los que la skill NO debe activarse, aunque haya una superposición temática. Ej.: "SKIP: el archivo importa openai, código genérico sin SDK Anthropic". Delimita el alcance con precisión quirúrgica.

Las skills demasiado genéricas se activan para todo y añaden ruido. SKIP crea límites claros: la skill se especializa en X, no en todo lo que superficialmente parece X. Reduce los conflictos entre skills y mejora la precisión.

Prefijo "SKIP:" explícito; lista de casos excluidos; complementa el TRIGGER; cuanto más específica sea la skill, menos necesitas SKIP; prueba de negación ("si haces Y, no debe activarse").

El nombre de la carpeta y del campo name en el frontmatter siguen kebab-case: letras minúsculas, palabras separadas por guion. Ej.: formato-curso, ads-skill, n8n-code-python.

Kebab-case es seguro para URL y para sistemas de archivos, y se lee fácilmente en la terminal. Permite comandos slash automáticos (/formato-curso) y referencias sin comillas en scripts bash. Mezclar convenciones genera errores silenciosos.

Todo en minúsculas; separador con guion; sin espacios, guiones bajos ni camelCase; nombre descriptivo (2-4 palabras); coherencia entre carpeta y frontmatter name; evita abreviaturas ambiguas.

Una buena description combina: (1) lo que hace la skill en 1 frase, (2) frases desencadenantes que cubren varias formulaciones, (3) SKIP para delimitar el alcance. Ej. de la skill claude-api: "Build, debug, and optimize Claude API apps. TRIGGER when: code imports anthropic/SDK. SKIP: openai, other-provider SDK."

Leer ejemplos reales acelera el aprendizaje más que cualquier teoría. Los patrones que funcionan en producción revelan matices que la documentación teórica omite: tamaño ideal, nivel de especificidad y equilibrio TRIGGER/SKIP.

Lo ideal son 3-6 líneas de description; frase resumen + TRIGGER + SKIP; probar con 5 preguntas reales antes de publicar; revisar después de usarla 10 veces en la práctica.

Las descriptions malas son: (1) demasiado genéricas — «Ayuda con código» (todo es código), (2) ambiguas — «Úsala cuando necesites IA» (toda skill usa IA), (3) demasiado técnicas — «Procesa tokens mediante API» (el usuario no piensa así), (4) sin TRIGGER/SKIP — dejan que el agente adivine.

Los errores en la descripción causan problemas silenciosos: la skill existe, pero nunca se usa o, peor aún, se activa en contextos equivocados y produce resultados inesperados. Identificar los antipatrones evita horas de depuración.

Antipatrones: vago, circular, demasiado técnico, sin referencias contextuales; prueba de «1 frase»: ¿alguien sin conocimientos de la skill puede saber cuándo usarla con solo leer la description?

La subcarpeta scripts/ contiene archivos .sh (o .py, .js) que el agente puede ejecutar mediante Bash. Cada script realiza una tarea atómica: verificar dependencias, procesar archivos, llamar APIs, dar formato a la salida. El SKILL.md hace referencia a cada script por su ruta relativa.

Los scripts externalizan la lógica operativa de SKILL.md y lo mantienen legible. Un script de 50 líneas no debería estar incluido en el markdown: debe ir en scripts/ y SKILL.md solo debe describir cuándo y cómo llamarlo.

Scripts atómicos (1 script = 1 responsabilidad); nómbralos con verbo-sustantivo (check-deps.sh, analyze-video.sh); se necesita chmod +x; ruta relativa en SKILL.md (./scripts/check.sh).

Archivos reference.md (o en references/) contienen documentación detallada: especificaciones de API, tablas de decisión, ejemplos extensos, historial de decisiones. El SKILL.md los menciona, pero no duplica el contenido — "consulta reference.md para ver la tabla completa".

SKILL.md debe ser corto y fácil de revisar: el agente lo lee completo cada vez que se activa. Los detalles extensos en SKILL.md aumentan el consumo de tokens y dificultan la lectura. Las References se cargan cuando se necesitan.

SKILL.md corto (50-150 líneas); references largos (sin límite); enlace explícito en SKILL.md; subcarpeta references/ para varios archivos; README.md que explique cada archivo de la carpeta.

El archivo .env.example lista las variables de entorno necesarias con valores de ejemplo (nunca reales). El usuario copia en .env y completa. Los scripts leen de $VARNAME — nunca hardcoded. SKILL.md indica al agente que verifique si existe .env antes de usar la skill.

Las claves de API en el código o en los registros son vulnerabilidades graves. .env.example es el estándar de la industria: documenta lo necesario sin exponer secretos. Una skill que respeta esto no filtra credenciales por accidente.

.env.example en el repo (sin valores reales); .env real en .gitignore; los scripts usan os_environ o source .env; paso de verificación en SKILL.md ("comprobar si existe .env"); regla estricta: "NUNCA registrar una API key".

Progressive disclosure es el principio de mostrar primero lo esencial y profundizar cuando sea necesario. En el contexto de las skills: SKILL.md contiene el flujo principal + enlaces a los detalles; references/ y scripts/ contienen los detalles. El agente decide cuándo profundizar en la documentación adicional.

Un SKILL.md de 500 líneas es difícil de leer, cuesta muchos tokens y puede tener contradicciones internas. La divulgación progresiva obliga a ser claro: lo que siempre se necesita va en el archivo principal; lo que rara vez se necesita queda en los detalles.

Nivel 1 (SKILL.md): flujo, reglas críticas, referencias; Nivel 2 (references/): especificaciones detalladas, tablas extensas; Nivel 3 (scripts/): implementación; enlaces explícitos entre niveles; SKILL.md se lee siempre, los detalles se leen cuando son relevantes.

Las hard rules son restricciones absolutas escritas en MAYÚSCULAS en SKILL.md: "NUNCA registrar la API key", "SIEMPRE pedir confirmación antes de eliminar", "JAMÁS parafrasear la transcripción: solo textual". Se diferencian de las guidelines (sugerencias): son inviolables.

Las hard rules protegen contra los errores más costosos: filtración de datos, gasto innecesario de créditos, pérdida irreversible de archivos. Son la red de seguridad de la skill: cuanto más crítica sea la skill, más importantes son las hard rules.

Formato: «NUNCA», «SIEMPRE», «JAMÁS» en mayúsculas; sección dedicada «## Hard Rules» en SKILL.md; 3-7 reglas (más de eso se vuelve ruido); cada regla con una justificación breve; probar cada regla con un caso adversarial.

Los gates de confirmación son puntos de control en el flujo de la skill donde el agente se detiene y pregunta al usuario antes de ejecutar una acción costosa, irreversible o de gran impacto. Ej.: "¿Confirmas que quieres generar el video? (esto usa 10 créditos Arcads)". Se implementan como pasos explícitos en el SKILL.md.

Los gates ahorran dinero y tiempo. Una skill de generación de video sin gate puede iniciar 50 generaciones accidentales en un bucle. El costo de confirmar es cero; el costo de no confirmar puede ser enorme. Los gates también aumentan la confianza del usuario en la skill.

Gate antes de acciones costosas ($$); gate antes de acciones irreversibles (delete, publish); mostrar el costo/impacto estimado; ofrecer la opción de cancelar; documentar los gates en la sección "Flujo" del SKILL.md.

La ads-skill hace 2 cosas distintas: (1) Análisis: extrae frames+audio de un video UGC mediante ffmpeg, identifica la estructura narrativa HOOK→SHOW→PROOF→CTA y produce un informe viral; (2) Generación: recibe 4 inputs (imagen/audio/video/actor) y genera un nuevo anuncio mediante la API de Arcads, dirigiéndolo al mejor modelo.

Ver una skill con dos capacidades complementarias muestra cómo agrupar funcionalidades relacionadas en lugar de crear 2 skills separadas. El análisis y la generación son inseparables en el flujo de trabajo de ads: el análisis define los datos de entrada para la generación.

Skill multimodal (procesa video/audio/imagen); ffmpeg para extraer fotogramas; estructura UGC de 15s: [0-2s HOOK][2-6s SHOW][6-11s PROOF][11-14s CTA][14-15s LOGO]; API de Arcads para la generación.

La skill elige entre 4 modelos: Seedance 2.0 (predeterminado, mejor sincronización labial), Veo 3.1 (frame inicial bloqueado, consistencia visual), Sora 2 (videos largos/cinematográficos), Kling 3.0 (contenido silencioso/estético). La lógica de enrutamiento queda en prompting/model-routing.md.

El enrutamiento inteligente dentro de una skill muestra cómo el SKILL.md puede contener lógica de decisión no trivial. En vez de que tengas que conocer 4 modelos, la skill abstrae la elección con reglas claras.

Seedance: estándar para UGC con voz; Veo: cuando el fotograma de referencia es crítico; Sora: >30s o estilo cinematográfico; Kling: sin audio, enfoque visual; reglas en un archivo de enrutamiento dedicado.

La ads-skill tiene: SKILL.md (frontmatter + flujo + hard rules), scripts/arcads_check.sh, arcads_analyze.sh, arcads_actors.sh, arcads_upload.sh, arcads_generate.sh, arcads_talking.sh, arcads_status.sh + prompting/ con 3 archivos + reference.md + .env.example.

La estructura de la ads-skill es una plantilla de referencia para cualquier skill que integre una API externa. Los 7 scripts cubren el ciclo completo: check (dependencias) → analyze (input) → actors (opciones) → upload (medios) → generate (job) → talking (variante) → status (polling).

Scripts con nombres que llevan el prefijo de la API (arcads_*); ciclo check→analyze→upload→generate→status; prompting/ con 3 archivos (viral-analysis, ugc-formulas, model-routing); reference.md con la documentación de la API.

Las 3 reglas estrictas de ads-skill: (1) NUNCA parafrasear la transcripción del video: siempre verbatim; (2) SIEMPRE ejecutar el "dialogue gate" antes de generar (confirmar los datos con el usuario para no gastar créditos de Arcads en vano); (3) NUNCA registrar la API key en ningún resultado ni registro de depuración.

Estas 3 reglas protegen: (1) la integridad del contenido viral (parafrasear arruina el timing); (2) el presupuesto (generar video cuesta dinero real); (3) la seguridad (filtrar API keys = cuenta comprometida). Son lo mínimo indispensable para usar la skill en producción.

Verbatim: copiar el texto exacto, sin resumirlo ni reescribirlo; dialogue gate: pantalla de confirmación con costo estimado; API key: leer de $ARCADS_API_KEY, nunca imprimirla; 3 reglas = fáciles de recordar y comprobar.

El framework UGC de 15s: [0-2s GANCHO] pattern-interrupt que detiene el scroll; [2-6s MUESTRA] demostración del producto/beneficio; [6-11s PRUEBA] número/resultado/prueba social; [11-14s CTA] llamada a la acción clara; [14-15s LOGO] marca. La skill identifica y extrae cada segmento automáticamente.

El framework UGC de 15s es el estándar de oro para los anuncios virales en dispositivos móviles. Entenderlo te permite evaluar un UGC existente, identificar sus puntos débiles y regenerar los segmentos problemáticos: exactamente lo que hace la skill.

HOOK (0-2s): sorpresa, pregunta, contradicción; SHOW (2-6s): demo real, no imágenes de stock; PROOF (6-11s): número concreto, no vago; CTA (11-14s): 1 acción específica; LOGO (14-15s): branding rápido.

La ads-skill pone en práctica todos los conceptos: (3.1) carpeta con SKILL.md + anatomía completa; (3.2) description con TRIGGER para "analizar UGC" + SKIP para videos no publicitarios + nombre kebab-case; (3.3) 7 scripts atómicos + 3 references + .env.example + progressive disclosure + 3 hard rules + dialogue gate.

Ver los conceptos en código real elimina la ambigüedad de la teoría. Cada decisión de diseño de ads-skill tiene una razón, y entender el "por qué" de cada elección te prepara para crear tus propias skills de producción.

Teoría (3.1-3.3) → implementación (ads-skill); cada elemento de la skill se corresponde con un concepto; una buena skill = checklist de los módulos anteriores; tu próxima skill: copia la estructura y adapta el dominio.