Skills personalizadas

Las skills son comandos slash que automatizan flujos de trabajo completos con Claude Code. Cuando escribes /implement en tu terminal, Claude Code lee las instrucciones de la skill correspondiente y ejecuta una secuencia de pasos predefinida: leer la tarea, escribir codigo, ejecutar tests, mover el item a la columna correcta.

Almirant incluye skills integradas que cubren los flujos mas comunes, pero puedes crear tus propias skills para adaptarlas a las necesidades de tu equipo.

Skills integradas

Almirant incluye estas skills por defecto:

Skill	Descripcion
/implement	Lee el work item asignado, implementa el codigo necesario y mueve la tarea a la columna Review
/review-task	Revisa la implementacion actual comparandola con la definicion del work item y su definition of done
/validate	Pipeline completo de validacion: revision de codigo + ejecucion de tests + capturas de pantalla
/test-task	Genera tests automaticos para la implementacion actual y los ejecuta
/pr	Crea un Pull Request en GitHub a partir de la rama actual con descripcion generada
/ideate	Inicia una sesion de brainstorming interactiva y crea work items a partir de las ideas
/create-tasks	Crea work items bien estructurados con titulo, descripcion, criterios de aceptacion y estimacion

Como funciona cada skill

/implement

1. Lee el work item asignado desde Almirant via MCP
2. Analiza la descripcion, criterios de aceptacion y definition of done
3. Explora el codigo existente para entender el contexto
4. Implementa los cambios necesarios
5. Mueve el work item a la columna Review

/review-task

1. Obtiene el work item y su definition of done desde Almirant
2. Lee los cambios implementados en el codigo
3. Compara la implementacion con los criterios de aceptacion
4. Genera un informe detallado con hallazgos y sugerencias

/validate

1. Ejecuta /review-task para revisar la implementacion
2. Ejecuta los tests del proyecto
3. Si hay interfaz, toma capturas de pantalla para verificacion visual
4. Genera un reporte consolidado con el resultado de cada paso

/test-task

1. Lee el work item para entender que se debe probar
2. Analiza la implementacion actual
3. Genera tests unitarios y/o de integracion
4. Ejecuta los tests y reporta los resultados

/pr

1. Analiza los commits y cambios en la rama actual
2. Genera un titulo y descripcion para el Pull Request
3. Crea el PR en GitHub con la informacion generada

/ideate

1. Inicia un dialogo interactivo para explorar ideas
2. Hace preguntas para refinar los conceptos
3. Convierte las ideas en work items estructurados en Almirant

/create-tasks

1. Recibe una descripcion de alto nivel de lo que se necesita
2. Descompone el trabajo en tareas granulares
3. Crea los work items en Almirant con toda la informacion necesaria

Crear skills personalizadas

Las skills se definen como archivos Markdown dentro del directorio .claude/skills/ de tu proyecto.

Ubicacion

tu-proyecto/
  .claude/
    skills/
      implement.md
      review-task.md
      mi-skill-custom.md    # <-- tu skill personalizada

Estructura de una skill

Cada archivo de skill tiene dos partes:

1. Frontmatter: metadatos en formato YAML (nombre y descripcion)
2. Instrucciones: pasos que Claude Code debe seguir, escritos en Markdown

---
name: mi-skill
description: Breve descripcion de lo que hace esta skill
---

## Instrucciones para el agente

1. Paso uno: descripcion detallada
2. Paso dos: descripcion detallada
3. Paso tres: descripcion detallada

Ejemplo: skill de deploy

---
name: deploy-staging
description: Despliega la rama actual al entorno de staging
---

## Instrucciones

1. Verifica que no haya cambios sin commitear ejecutando `git status`
2. Ejecuta el linter con `bun run lint` y corrige errores si los hay
3. Ejecuta los tests con `bun run test` y verifica que pasen
4. Haz push de la rama actual a origin
5. Ejecuta el deploy a staging con `bun run deploy:staging`
6. Verifica que el deploy fue exitoso revisando la URL de staging
7. Reporta el resultado al usuario con la URL del entorno

Ejemplo: skill de documentacion

---
name: document-feature
description: Genera documentacion tecnica para una feature implementada
---

## Instrucciones

1. Lee el work item asociado a la feature desde Almirant usando MCP
2. Identifica los archivos nuevos o modificados en la implementacion
3. Para cada componente/modulo nuevo:
   - Genera un JSDoc con descripcion, parametros y ejemplos
   - Si es un hook, documenta los valores de retorno
   - Si es un endpoint, documenta request/response
4. Actualiza el README del dominio si existe
5. Crea un comentario en el work item con el resumen de la documentacion generada

Ejemplo: skill de migracion de base de datos

---
name: db-migrate
description: Genera y aplica migraciones de base de datos de forma segura
---

## Instrucciones

1. Lee los cambios pendientes en los archivos de schema (`backend/packages/database/src/schema/`)
2. Genera la migracion con `bun run db:generate`
3. Revisa el SQL generado en la carpeta de migraciones
4. Si el SQL contiene operaciones destructivas (DROP, ALTER con perdida de datos),
   advierte al usuario y espera confirmacion antes de continuar
5. Aplica la migracion con `bun run db:migrate`
6. Verifica que la migracion se aplico correctamente

Buenas practicas

Instrucciones claras y especificas

Escribe instrucciones que no dejen lugar a ambiguedades. En lugar de "revisa el codigo", especifica que archivos o patrones debe revisar.

# Menos efectivo
1. Revisa el codigo
2. Haz los cambios necesarios

# Mas efectivo
1. Lee todos los archivos en `src/domains/[feature]/` para entender la estructura
2. Verifica que los componentes presentacionales no contengan useState ni useEffect
3. Si encuentras logica en componentes .tsx, extraela a un custom hook en `application/hooks/`

Usa herramientas MCP en las instrucciones

Referencia las herramientas MCP de Almirant para que la skill interactue con tu tablero.

1. Usa la herramienta `get_work_item` para leer la tarea asignada
2. Implementa los cambios segun la descripcion
3. Usa `update_work_item` para mover la tarea a la columna "Review"

Incluye condiciones y validaciones

Define que debe hacer la skill cuando algo falla o cuando hay condiciones especiales.

3. Ejecuta los tests con `bun run test`
   - Si fallan tests, analiza los errores e intenta corregirlos
   - Si no puedes corregirlos despues de 2 intentos, reporta los fallos al usuario
4. Si el work item tiene la etiqueta "needs-review", no muevas automaticamente a Done

Mantener skills enfocadas

Cada skill debe hacer una cosa bien. Si necesitas un flujo complejo, divide en varias skills y combinalas manualmente.

Consejo

Empieza duplicando una skill integrada y modificandola para tu caso de uso. Es mas facil adaptar algo existente que crear desde cero.

Importante

Las skills son instrucciones para la IA, no scripts ejecutables. Claude Code las interpreta y decide como ejecutar cada paso. Escribe las instrucciones pensando en un desarrollador que las lee por primera vez.

Compartir skills con tu equipo

Como las skills viven en .claude/skills/, se versionan con Git junto al resto del proyecto. Cualquier miembro del equipo que clone el repositorio tendra acceso a las mismas skills.

Para mantener consistencia:

1. Documenta cada skill con una descripcion clara en el frontmatter
2. Usa convenciones de nombrado consistentes (kebab-case)
3. Agrupa skills relacionadas con prefijos: deploy-staging.md, deploy-production.md
4. Revisa las skills en code review como cualquier otro archivo del proyecto