Crear un Skill

Los skills son instrucciones estructuradas que guían a tu asistente de IA a través de flujos de trabajo repetibles. Cada skill es un archivo SKILL.md con frontmatter YAML y secciones en markdown.

Estructura de un Skill

Un skill vive en su propio directorio bajo .claude/skills/ (nivel de proyecto) o se distribuye desde src/rai_cli/skills_base/ (nivel de framework).

.claude/skills/
  my-custom-skill/
    SKILL.md

Frontmatter Requerido

Todo SKILL.md comienza con frontmatter YAML:

---
name: rai-my-skill
description: >
  Descripción de un párrafo de qué hace este skill y cuándo usarlo.

license: MIT

metadata:
  raise.work_cycle: utility       # utility | epic | story | session
  raise.frequency: as-needed      # always | as-needed | once
  raise.fase: "0"                 # Fase ShuHaRi
  raise.prerequisites: ""         # Skills previos requeridos
  raise.next: ""                  # Skill sugerido siguiente
  raise.gate: ""                  # Gate a verificar antes de ejecutar
  raise.adaptable: "true"         # Puede personalizarse por proyecto
  raise.version: "2.2.3"          # Versión del framework
  raise.visibility: public        # public | private
---

Secciones Requeridas

Tras el frontmatter, incluye estas secciones en markdown:

1. Purpose — Qué hace el skill y por qué existe
2. Context — Cuándo usar, cuándo omitir, inputs necesarios
3. Steps — Pasos numerados con bloques <verification> después de cada uno
4. Output — Qué artifacts produce el skill
5. Quality Checklist — Criterios de verificación como lista de checkboxes

Bloques de Verificación

Cada paso debe terminar con un gate de verificación:

### Paso 1: Hacer la Cosa

Instrucciones para este paso.

<verification>
Resultado esperado que confirma la completitud del paso.
</verification>

<if-blocked>
Qué hacer si este paso falla.
</if-blocked>

Convenciones de Nombres

Los nombres de skills siguen el patrón {dominio}-{acción}: - rai-story-start — dominio story, acción start - rai-debug — dominio utilitario, acción única - rai-discover-scan — dominio discovery, acción scan

Valida un nombre antes de crear:

rai skill check-name my-skill-name

Scaffold de un Skill

Usa el CLI para generar el esqueleto:

rai skill scaffold my-custom-skill

Esto crea el directorio y una plantilla SKILL.md con todas las secciones requeridas.

Skill Sets

Los skill sets permiten a los equipos personalizar qué skills están activos. La forma más fácil de gestionarlos es con el skill /rai-skillset-manage:

/rai-skillset-manage

O directamente con el CLI:

# Listar skill sets disponibles
rai skill set list

# Crear un set personalizado
rai skill set create my-team-set

# Comparar contra los built-ins
rai skill set diff my-team-set

Validar

Verifica que tu skill cumple los requisitos estructurales:

rai skill validate my-custom-skill

Esto verifica campos del frontmatter, secciones requeridas y convenciones de nombres.