Habilidades de Claude Code: Crea Flujos de Trabajo Personalizados para Tu Asistente de Codificación AI

Claude Code viene con un asistente AI de propósito general. Las habilidades te permiten especializarlo. Una habilidad es un archivo markdown que enseña a Claude Code cómo manejar un tipo específico de tarea: desplegar en Kubernetes, escribir migraciones de base de datos, revisar pull requests o seguir las convenciones de codificación de tu equipo.

La diferencia entre "escríbeme un componente React" y "escríbeme un componente React siguiendo nuestro sistema de diseño, usando nuestros hooks personalizados, con límites de error adecuados y atributos de accesibilidad" es una habilidad.

Qué Son Realmente las Habilidades

Una habilidad es un archivo markdown en .claude/commands/ (a nivel de proyecto) o ~/.claude/commands/ (global). Cuando escribes /skill-name en Claude Code, el contenido del archivo se inyecta en la conversación como instrucciones.

.claude/
  commands/
    deploy.md          # /deploy
    review-pr.md       # /review-pr
    write-test.md      # /write-test

Eso es todo. Sin sintaxis especial, sin compilación, sin SDK. Solo markdown que describe cómo hacer algo.

Escribiendo Tu Primera Habilidad

Aquí tienes un ejemplo práctico: una habilidad que hace cumplir las convenciones de mensajes de commit de tu equipo.

Crea .claude/commands/commit.md:

# Flujo de Trabajo de Commit

## Pasos
1. Ejecuta `git diff --staged` para ver qué se está comiteando
2. Analiza los cambios y clasifícalos: feat, fix, refactor, docs, test, chore
3. Escribe un mensaje de commit siguiendo nuestra convención:
   - Formato: `type(scope): description`
   - Scope es el nombre del paquete o módulo
   - La descripción está en modo imperativo, minúsculas, sin punto final
   - El cuerpo explica POR QUÉ, no QUÉ
4. Si los cambios afectan varios scopes, crea commits separados
5. Ejecuta `git commit -m "mensaje"` con el mensaje generado

## Reglas
- Nunca uses `--no-verify` para saltarte los hooks
- Nunca modifiques commits ya publicados
- Si fallan los tests en pre-commit, arregla el problema primero

## Ejemplos
- `feat(billing): add stripe webhook handler`
- `fix(auth): handle expired refresh tokens`
- `refactor(api): extract rate limiter to shared package`

Ahora /commit le da a Claude Code un flujo de trabajo estructurado en lugar de una instrucción vaga como "comitea mis cambios".

Patrones de Diseño de Habilidades

El Patrón de Lista de Verificación

Ideal para tareas con múltiples pasos de verificación.

# Lista de Verificación Pre-Despliegue

Antes de desplegar, verifica cada punto:

- [ ] `pnpm typecheck` pasa
- [ ] `pnpm test` pasa
- [ ] No hay declaraciones console.log en código de producción
- [ ] Variables de entorno documentadas en .env.example
- [ ] Las migraciones de base de datos son reversibles
- [ ] Los cambios en la API son compatibles hacia atrás

Si alguna verificación falla, detente y reporta el problema. No continúes con el despliegue.

El Patrón de Árbol de Decisiones

Ideal para tareas donde el enfoque depende del contexto.

# Flujo de Trabajo para Corrección de Bugs

1. Reproduce el bug (encuentra o escribe un test que falle)
2. Identifica la causa raíz:
   - Si es un error de tipo → corrige la definición de tipo en la fuente
   - Si es una condición de carrera → añade bloqueo/secuenciación adecuada
   - Si falta validación → añade validación de esquema en el límite
   - Si es un error lógico → corrige y añade test de regresión
3. Verifica que la corrección no rompa tests existentes
4. Escribe un test que hubiera detectado este bug

El Patrón de Plantilla

Ideal para generar resultados consistentes.

# Nuevo Endpoint API

Crea un nuevo endpoint API siguiendo nuestras convenciones:

## Estructura de Archivos
- Manejador de ruta: `apps/api/src/routes/{resource}/{action}.ts`
- Esquema: `apps/api/src/schemas/{resource}.ts`
- Test: `apps/api/src/routes/{resource}/__tests__/{action}.test.ts`

## Elementos Requeridos
- Esquema Zod para validación de solicitudes
- Middleware de autenticación
- Limitación de tasa
- Respuestas de error estructuradas usando errorResponse()
- Respuestas de éxito usando successResponse()
- Comentarios de documentación OpenAPI

Instalando Habilidades de la Comunidad

El ecosistema de Claude Code tiene una biblioteca creciente de habilidades comunitarias. Instálalas con:

npx add-skill username/repo-name -y

Colecciones populares de habilidades:

• coreyhaines31/marketingskills (29 habilidades de marketing/SEO)
• hedging8563/lemondata-api-skill (Integración API de LemonData)

Las habilidades instaladas aparecen en ~/.claude/commands/ y funcionan en todos los proyectos.

Habilidades de Proyecto vs Globales

Ubicación	Alcance	Uso
.claude/commands/	Solo este proyecto	Convenciones del proyecto, flujos de trabajo de despliegue
~/.claude/commands/	Todos los proyectos	Preferencias personales, herramientas generales

Las habilidades de proyecto deben ser comiteadas en tu repositorio para que todo el equipo se beneficie. Las habilidades globales son para preferencias personales de flujo de trabajo.

Avanzado: Habilidades con Hooks

Las habilidades pueden referenciar hooks (comandos shell que se ejecutan en eventos específicos) para aplicar reglas automáticamente:

# Verificación Pre-Commit

Antes de cualquier commit, los siguientes hooks se ejecutan automáticamente:
- `pre-commit`: ejecuta typecheck + lint
- `post-commit`: actualiza el changelog

Si un hook falla, investiga el error y corrige el problema.
No uses --no-verify para saltarte los hooks.

Los hooks se configuran en .claude/settings.json:

{
  "hooks": {
    "pre-commit": "pnpm typecheck && pnpm lint-staged"
  }
}

Consejos para Habilidades Efectivas

1. Sé específico con rutas de archivos y convenciones de nombres. "Crear un componente" es vago. "Crear un componente en src/components/ui/ usando nomenclatura PascalCase" es accionable.

2. Incluye ejemplos de salida correcta. Claude Code aprende mejor con ejemplos que con reglas abstractas.

3. Define qué NO hacer. "Nunca uses el tipo any" es más fácil de hacer cumplir que "usa tipos adecuados".

4. Mantén las habilidades enfocadas. Una habilidad por flujo de trabajo. Una habilidad de 200 líneas que cubre todo es menos útil que cinco habilidades de 40 líneas que manejan bien cada tarea.

5. Versiona tus habilidades. A medida que evolucionan tus convenciones, actualiza las habilidades. Las habilidades desactualizadas son peores que no tener habilidades porque aplican patrones antiguos.

Impacto en el Mundo Real

Los equipos que adoptan habilidades reportan mejoras consistentes:

• Los ciclos de revisión de código disminuyen porque las convenciones se aplican antes de la revisión
• El tiempo de incorporación se reduce porque los desarrolladores nuevos reciben la misma guía que los veteranos
• La calidad del código generado por AI mejora porque la AI tiene contexto explícito sobre los estándares del proyecto

La inversión es pequeña (30 minutos para escribir tus primeras habilidades) y el beneficio se acumula con cada interacción.

---

Construye con AI, guiado por tus propias reglas. lemondata.cc provee la infraestructura API para herramientas de desarrollo impulsadas por AI.