28 de marzo de 2026

Claude Code: Skills — El conocimiento modular del agente

En el tutorial anterior vimos los hooks: mecanismos que garantizan cómo se comporta el agente. En este artículo vemos el complemento natural: Skills, que definen qué sabe el agente sobre dominios específicos de tu proyecto.

La distinción es importante. Un hook intercepta una acción y la bloquea o modifica. Una Skill carga un conjunto de instrucciones especializadas justo cuando son relevantes, convirtiéndolo en un experto temporal en ese dominio. No necesitas repetirle las convenciones de tu equipo, los patrones que usan, las herramientas disponibles, ni el flujo de trabajo esperado en cada sesión: la Skill lo sabe y lo aplica cuando la necesitas.

En este artículo veremos cómo funcionan internamente, cómo crearlas, los dos mecanismos de invocación, los archivos de soporte, cómo instalar Skills de la comunidad, y los 5 ejemplos prácticos de la serie — 3 específicos para Java con Gradle y 2 genéricos.

Sin más, vamos al tema.

Contenido

  1. ¿Qué es una Skill y cómo funciona internamente?
  2. Skills vs. CLAUDE.md vs. Hooks vs. Custom Commands
  3. Estructura de una Skill
  4. El frontmatter: la configuración que importa
  5. Los dos modos de invocación
  6. Archivos de soporte: templates, scripts y referencias
  7. Ubicaciones y jerarquía de carga
  8. Skills de la comunidad: el ecosistema
  9. 5 ejemplos prácticos
  10. Catálogo completo: las 18 Skills del repositorio
  11. Buenas prácticas y errores comunes
  12. Conclusión

¿Qué es una Skill y cómo funciona internamente?

Una Skill es un directorio que contiene un archivo SKILL.md — y opcionalmente scripts, templates y documentación de referencia — que Claude Code carga en el contexto de forma dinámica cuando detecta que la tarea actual es relevante para esa Skill.

Si el CLAUDE.md es el manual de onboarding general del proyecto, una Skill es el manual especializado de un área concreta: cómo escribir tests de integración, cómo hacer una migración de base de datos, cómo estructurar un PR. Cada manual solo se abre cuando lo necesitas.

El mecanismo interno es elegante. Claude Code mantiene una lista de Skills disponibles construida a partir del frontmatter de todos los archivos SKILL.md del proyecto. Cuando el agente recibe una tarea, compara la descripción de esa tarea contra las descripciones de las Skills disponibles. Si hay match, carga el SKILL.md de esa Skill usando bash — lo que significa que el contenido de la Skill entra al contexto bajo demanda, no al arrancar la sesión. Las Skills que no son relevantes para la tarea actual no consumen ni un token.

Este diseño tiene dos ventajas prácticas importantes:

  • Contexto eficiente: Una Skill puede referenciar documentos de 50 páginas. Claude solo lee las partes que necesita para la tarea específica, no el documento completo.
  • Scripts sin costo de contexto: Cuando una Skill incluye un script y el agente lo ejecuta, el código del script nunca entra al contexto — solo el output del script. Un script de 300 líneas que genera 2 líneas de output consume exactamente esas 2 líneas de contexto, no 300.

Skills vs. CLAUDE.md vs. Hooks vs. Custom Commands

Antes de entrar en la sintaxis, vale la pena tener claro cuándo usar cada mecanismo. Es una pregunta que surge frecuentemente.

Mecanismo Cuándo se carga Mejor para
CLAUDE.md Siempre, al inicio de cada sesión Convenciones globales del proyecto: estructura de paquetes, comandos de build, restricciones permanentes
Skill Bajo demanda, cuando la tarea es relevante Conocimiento especializado de dominio: cómo escribir tests, cómo hacer migraciones, patrones específicos de un módulo
Hook En eventos del ciclo de vida (edición, commit, etc.) Garantías de comportamiento: formateo automático, gates de calidad, protección de archivos
Custom Command Cuando el usuario lo invoca explícitamente con /nombre Flujos de trabajo repetitivos que el developer decide cuándo ejecutar

La diferencia práctica entre Skill y CLAUDE.md es de frecuencia y relevancia. Si una instrucción aplica a todo lo que hace el agente en este proyecto, va en el CLAUDE.md. Si aplica solo cuando el agente está haciendo una tarea específica, va en una Skill. Meter instrucciones de dominio muy específicas en el CLAUDE.md consume contexto innecesariamente en el 80% de las sesiones donde esa información no es relevante.

Estructura de una Skill

Cada Skill es un directorio con SKILL.md como punto de entrada. Los demás archivos son opcionales pero potentes: 

.claude/skills/
└── nombre-de-la-skill/
    ├── SKILL.md          # Requerido — instrucciones y frontmatter
    ├── examples/         # Ejemplos de output esperado
    │   └── sample.md
    ├── references/       # Documentación de referencia detallada
    │   ├── patterns.md
    │   └── api-reference.md
    ├── templates/        # Plantillas para que Claude complete
    │   └── template.md
    └── scripts/          # Scripts ejecutables
        └── validate.sh

Y la anatomía del SKILL.md tiene dos partes bien diferenciadas:

SKILL.md
Frontmatter YAML — configura el CÓMO
---
name: nombre-skill         # Se convierte en el slash command /nombre-skill
description: |             # Claude usa esto para decidir cuándo activar la skill
  Descripción de cuándo usar esta skill.
  Sé específico: "Usa cuando el usuario pida X o Y"
allowed-tools: "Bash, Read, Write"   # Herramientas disponibles durante la skill
version: "1.0.0"
author: "tu-nombre"
---
Contenido Markdown — define el QUÉ
# Título de la Skill
 
## Instrucciones
Cuando esta skill esté activa, Claude sigue estas instrucciones...
 
## Flujo de trabajo
1. Paso 1
2. Paso 2
 
## Referencias
Ver [patterns.md](references/patterns.md) para los patrones del equipo.

El frontmatter: la configuración que importa

El frontmatter YAML es lo que convierte un archivo Markdown ordinario en una Skill funcional. Estos son los campos disponibles:

CampoTipoDescripción
name string — requerido Identificador único. Se convierte en el slash command /nombre. Sin espacios, usar guiones.
description string — requerido Le dice a Claude cuándo activar la Skill automáticamente. Es el campo más importante para la invocación automática. Cuanto más descriptivo y natural, mejor.
allowed-tools string Herramientas disponibles durante la ejecución de la Skill. Restringe el scope de lo que puede hacer. Ej: "Read, Bash" para una Skill de solo lectura.
version string Semver. Útil para control de versiones en equipo.
author string Para Skills de equipo — quién la mantiene.
compatibility string Para Skills del estándar Agent Skills. Indica si la Skill es específica de Claude Code o portable a otros agentes.

El campo más crítico en la práctica es description. Claude lo usa para decidir si la Skill es relevante para una tarea. Una descripción vaga genera dos problemas opuestos: la Skill no se activa cuando debería, o se activa en momentos inapropiados. 

# ✗ Descripción vaga — activa en demasiados contextos o en ninguno
description: "Skill para código Java"
 
# ✓ Descripción específica — activa exactamente cuando debe
description: |
  Usa esta skill cuando el usuario pida escribir tests de integración
  con JUnit 5, Mockito o Testcontainers, o cuando pregunte cómo
  testear un servicio, repositorio o controlador Spring Boot.

Los dos modos de invocación

Automática
Claude decide cuándo cargarla

El agente compara la tarea actual con la description de cada Skill disponible. Si hay match semántico, carga la Skill sin que el developer haga nada. Es la forma preferida para Skills de dominio.

Manual
/nombre-skill

El developer invoca la Skill explícitamente con el slash command correspondiente al name del frontmatter. Útil cuando quieres activarla sin que Claude la detecte solo, o para Skills que son flujos de trabajo completos.

La invocación automática requiere que la descripción sea lo suficientemente específica. Si notas que Claude no está usando una Skill cuando debería, puedes invocarla manualmente con /nombre-skill para forzar la carga, y al mismo tiempo revisar si la descripción necesita ser más explícita. 

# Ver todas las Skills disponibles en el proyecto
> ¿Qué skills tienes disponibles?
 
# Invocar una Skill manualmente
> /tdd-spring
 
# Invocar una Skill con contexto adicional
> /tdd-spring Necesito testear el PaymentService con Testcontainers
Live reload: A diferencia de los hooks y el CLAUDE.md, las Skills se recargan en tiempo real. Puedes editar un SKILL.md durante una sesión activa y los cambios surten efecto inmediatamente sin reiniciar Claude Code.

Archivos de soporte: templates, scripts y referencias

Una Skill de un solo archivo SKILL.md ya es útil, pero el verdadero potencial está en los archivos de soporte. El patrón que la documentación oficial llama "Progressive Disclosure": el SKILL.md muestra solo lo necesario para que Claude decida qué hacer, y los archivos de soporte contienen el detalle al que Claude accede solo cuando lo necesita.

Referencias

Documentación detallada que el SKILL.md referencia con links Markdown. Claude lee estos archivos bajo demanda cuando necesita el detalle completo, no al cargar la Skill. 

# En SKILL.md:
Para los patrones de naming de tests del equipo, ver [naming-conventions.md](references/naming-conventions.md).
Para ejemplos de configuración de Testcontainers, ver [testcontainers-setup.md](references/testcontainers-setup.md).

Templates

Plantillas que Claude completa con el contexto del proyecto. Más consistente que pedirle que genere la estructura desde cero cada vez. 

# templates/service-test-template.java
@ExtendWith(MockitoExtension.class)
class {{ServiceName}}Test {
 
    @Mock
    private {{DependencyName}} {{dependencyVar}};
 
    @InjectMocks
    private {{ServiceName}} {{serviceVar}};
 
    @Test
    void {{methodName}}_{{condition}}_{{expectedResult}}() {
        // Arrange
 
        // Act
 
        // Assert
    }
}

Scripts

Scripts que Claude ejecuta como parte del flujo de la Skill. El punto clave: el código del script nunca entra al contexto, solo su output. Esto hace que las operaciones complejas sean muy eficientes en tokens. 

#!/bin/bash
# scripts/check-test-coverage.sh
# Corre los tests y extrae el porcentaje de cobertura del reporte de JaCoCo
./gradlew test jacocoTestReport -q 2>&1 | grep -E "Total.*[0-9]+%" | tail -1

Ubicaciones y jerarquía de carga

Claude Code busca Skills en múltiples ubicaciones, cargándolas todas simultáneamente. El orden de precedencia cuando hay conflicto de nombres:

UbicaciónAlcanceComando de slash
~/.claude/skills/ Global — todos tus proyectos /user:nombre
.claude/skills/ (raíz del proyecto) Proyecto completo /project:nombre o simplemente /nombre
packages/modulo/.claude/skills/ Submódulo específico (monorepos) Se carga automáticamente al editar archivos en ese submódulo

El soporte de subdirectorios es especialmente valioso en monorepos. Cuando el agente está trabajando en archivos dentro de packages/payments/, Claude Code carga automáticamente las Skills de packages/payments/.claude/skills/ además de las de la raíz. Sin configuración adicional, sin que el developer tenga que recordarlo.

Nota sobre --add-dir: Si usas la flag --add-dir para incluir directorios externos al proyecto, las Skills de esos directorios se cargan automáticamente, pero los archivos CLAUDE.md de esos directorios no se cargan por defecto. Para cargarlos también, activa la variable de entorno CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1.

Skills de la comunidad: el ecosistema

En diciembre de 2025, Anthropic publicó Agent Skills como un estándar abierto en agentskills.io. El mismo formato SKILL.md funciona en Claude Code, Cursor, Gemini CLI y otros agentes compatibles. OpenAI adoptó el mismo formato para Codex CLI. Esto significa que una Skill bien escrita puede usarse en múltiples herramientas sin modificación.

Además tenemos el sitio https://skills.sh/ con cientos de skills gratuitos listos para usarse con prácticamente cualquier agente y que cubren cualquier necesidad que puedas tener durante todas las etapas del ciclo de vida de desarrollo.

Instalar Skills oficiales de Anthropic

# Instalar una Skill oficial
npx skills add anthropics/claude-code --skill frontend-design
npx skills add anthropics/claude-code --skill pdf
npx skills add anthropics/claude-code --skill xlsx
 
# Ver Skills instaladas
npx skills list

Antigravity Awesome Skills

La colección más grande del ecosistema con más de 1,200 Skills compatibles con múltiples agentes: 

# Instalar toda la colección para Claude Code
npx antigravity-awesome-skills --claude
 
# Instalar solo un bundle por rol (recomendado)
npx antigravity-awesome-skills --bundle backend-developer --claude
Seguridad con Skills de terceros: Una Skill puede ejecutar scripts y acceder a herramientas de tu proyecto. Antes de instalar cualquier Skill de una fuente externa, revisa el contenido completo del directorio: el SKILL.md, todos los scripts en scripts/, y cualquier archivo que haga llamadas a URLs externas. Trata la instalación de una Skill como la instalación de una dependencia de código — con el mismo nivel de escrutinio.

5 ejemplos prácticos

Ejemplo 1 (Java / Gradle): Skill de TDD con Spring Boot

La Skill más útil para cualquier proyecto Spring Boot. Se activa automáticamente cuando pides escribir tests o cuando el agente detecta que está trabajando en una clase que no tiene cobertura. 

# .claude/skills/tdd-spring/SKILL.md
---
name: tdd-spring
description: |
  Usa esta skill cuando el usuario pida escribir tests unitarios o de integración
  para código Spring Boot, cuando pregunte cómo testear un servicio, repositorio
  o controlador, o cuando mencione JUnit 5, Mockito, Testcontainers o AssertJ.
allowed-tools: "Read, Write, Bash"
version: "1.0.0"
---
 
# TDD con Spring Boot
 
## Stack de testing
- JUnit 5 + AssertJ para assertions
- Mockito para mocking de dependencias
- Testcontainers para tests de integración con infraestructura real
 
## Convenciones de naming
Los métodos de test siguen el patrón:
`nombreMetodo_condicion_resultadoEsperado()`
 
Ejemplos correctos:
- `charge_withValidCard_returnsSuccessResponse()`
- `findById_whenUserNotExists_throwsNotFoundException()`
 
## Estructura base de un test unitario
Usa el template en [templates/unit-test.java](templates/unit-test.java).
 
## Tests de integración con Testcontainers
Ver [references/testcontainers-setup.md](references/testcontainers-setup.md)
para la configuración del proyecto.
 
## Reglas del equipo
- Siempre escribe el test ANTES de la implementación (TDD estricto)
- Cada test verifica exactamente una cosa
- No uses @SpringBootTest en tests unitarios — solo en tests de integración
- Los mocks se declaran con @Mock, no con Mockito.mock()
- Verifica cobertura antes de hacer commit: ./gradlew test jacocoTestReport
// .claude/skills/tdd-spring/templates/unit-test.java
@ExtendWith(MockitoExtension.class)
class {{ServiceName}}Test {
 
    @Mock
    private {{Repository}} {{repositoryVar}};
 
    @InjectMocks
    private {{ServiceName}} {{serviceVar}};
 
    @Test
    void {{method}}_{{condition}}_{{expected}}() {
        // Arrange
 
        // Act
 
        // Assert
        assertThat(actual).isEqualTo(expected);
    }
}

Ejemplo 2 (Java / Gradle): Skill de migraciones de base de datos

Una Skill que centraliza todo el conocimiento sobre las convenciones de migración del equipo: naming, estructura SQL, cómo usar Flyway, y el proceso de validación antes de aplicar. 

---
name: db-migration
description: |
  Usa esta skill cuando el usuario pida crear o modificar migraciones de base
  de datos, cuando mencione Flyway, cuando hable de cambios de schema, o cuando
  pregunte cómo agregar columnas, tablas, índices o constraints.
allowed-tools: "Read, Write, Bash"
version: "1.0.0"
---
 
# Migraciones de Base de Datos con Flyway
 
## Convención de naming obligatoria
`V{YYYYMMDDHHMMSS}__{descripcion_en_snake_case}.sql`
 
Ejemplo: `V20250315143022__add_payment_method_to_orders.sql`
 
## Directorio
`src/main/resources/db/migration/`
 
## Reglas críticas (NO negociables)
- Los archivos de migración versionados (V__) son INMUTABLES una vez aplicados
- Para corregir un error, crea una nueva migración — nunca edites una existente
- Toda migración debe tener su rollback documentado en un comentario al inicio
 
## Validar antes de aplicar
Corre siempre antes de hacer commit:
```bash
./gradlew flywayValidate
```
 
## Para referencias de tipos de datos PostgreSQL
Ver [references/postgres-types.md](references/postgres-types.md)
 
## Template de migración
Ver [templates/migration-template.sql](templates/migration-template.sql)

Ejemplo 3 (Java / Gradle): Skill de optimización de rendimiento Spring Boot

Una Skill especializada que se activa cuando el agente detecta problemas de rendimiento, queries N+1, o solicitudes de optimización. Incluye un script que analiza el build y detecta dependencias que afectan el startup time. 

---
name: spring-performance
description: |
  Usa esta skill cuando el usuario reporte lentitud en la aplicación, mencione
  queries N+1, lazy loading, tiempo de startup, memory leaks, o cuando pida
  optimizar el rendimiento de un servicio o repositorio Spring Boot.
allowed-tools: "Read, Write, Bash"
version: "1.0.0"
---
 
# Optimización de Rendimiento — Spring Boot
 
## Diagnóstico inicial
Antes de proponer cualquier solución, ejecuta el script de diagnóstico:
```bash
.claude/skills/spring-performance/scripts/diagnose.sh
```
 
## Las causas más comunes en este proyecto
 
### Queries N+1 en JPA
- Revisar todas las relaciones @OneToMany y @ManyToMany
- Verificar que usen FetchType.LAZY (nunca EAGER en colecciones)
- Usar @EntityGraph o JOIN FETCH para los casos donde necesitas la relación
 
### Startup lento
- Revisar auto-configuraciones innecesarias con --debug
- Considerar lazy initialization: spring.main.lazy-initialization=true
- Ver candidatos para exclusión en [references/autoconfig-exclusions.md](references/autoconfig-exclusions.md)
 
### Connection pool
- El proyecto usa HikariCP — ver configuración en [references/hikari-config.md](references/hikari-config.md)
- Pool size recomendado: (núcleos CPU * 2) + spindle_count
 
## Herramientas disponibles
- Spring Boot Actuator está habilitado en el perfil local
- Endpoint de métricas: http://localhost:8080/actuator/metrics
#!/bin/bash
# .claude/skills/spring-performance/scripts/diagnose.sh
# Análisis rápido de rendimiento — solo el output entra al contexto, no el script
set -uo pipefail
 
echo "=== SPRING BOOT PERFORMANCE SNAPSHOT ==="
echo ""
 
echo "--- Dependencies that may impact startup ---"
./gradlew dependencies --configuration runtimeClasspath -q 2>/dev/null \
  | grep -E "spring-boot-starter-|hibernate-|flyway-" \
  | sort -u | head -20
 
echo ""
echo "--- Test execution time (last run) ---"
find build/test-results -name "*.xml" 2>/dev/null \
  | xargs grep -h 'time=' 2>/dev/null \
  | grep -oP 'time="\K[0-9.]+' \
  | awk '{sum+=$1; count++} END {
      if (count>0) printf "Total: %.2fs across %d tests (avg: %.3fs/test)\n", sum, count, sum/count
    }'
 
echo ""
echo "--- Build scan (last build) ---"
ls -t build/reports/ 2>/dev/null | head -5

Ejemplo 4 (Genérico): Skill de code review

Una Skill que estandariza el proceso de code review del equipo. Se invoca manualmente con /code-review cuando el developer quiere una revisión antes de abrir un PR. 

---
name: code-review
description: |
  Usa esta skill cuando el usuario pida revisar código, hacer un code review,
  o preparar un PR. También se activa cuando el usuario pregunta "¿está bien
  este código?" o "¿qué mejorarías de esto?".
allowed-tools: "Read, Bash"
version: "1.0.0"
---
 
# Code Review
 
## Proceso estándar
1. Leer el diff completo: `git diff main...HEAD`
2. Revisar en este orden de prioridad:
   - **Crítico**: bugs, vulnerabilidades de seguridad, condiciones de carrera
   - **Mayor**: violaciones de arquitectura, acoplamiento excesivo, código sin tests
   - **Menor**: naming, duplicación, magic numbers, comentarios innecesarios
   - **Sugerencia**: mejoras de legibilidad, optimizaciones no críticas
 
## Formato de reporte
Para cada hallazgo:
```
[CRÍTICO|MAYOR|MENOR|SUGERENCIA] archivo.java:línea
Descripción del problema.
Sugerencia de corrección.
```
 
## Checklist obligatorio antes de aprobar
Ver [references/pr-checklist.md](references/pr-checklist.md)
 
## Criterios específicos del proyecto
- Toda clase pública tiene Javadoc
- No hay dependencias circulares entre módulos
- Los tests cubren los casos borde identificados en el review

Ejemplo 5 (Genérico): Skill de documentación técnica

Una Skill que garantiza que la documentación técnica generada por el agente sigue el estilo y estructura del equipo, con templates para ADRs, READMEs y documentación de APIs. 

---
name: technical-docs
description: |
  Usa esta skill cuando el usuario pida escribir documentación técnica, crear
  un ADR (Architecture Decision Record), actualizar un README, documentar una
  API, o escribir una guía de onboarding para el proyecto.
allowed-tools: "Read, Write"
version: "1.0.0"
---
 
# Documentación Técnica
 
## Tipos de documentación y sus templates
 
### ADR (Architecture Decision Record)
Usa [templates/adr-template.md](templates/adr-template.md)
Guarda en: `docs/adr/ADR-YYYY-NNN_titulo-en-kebab-case.md`
 
### README de módulo
Usa [templates/module-readme.md](templates/module-readme.md)
Secciones obligatorias: Overview, Setup, API, Configuration, Contributing
 
### Documentación de API REST
Genera en formato OpenAPI 3.1 cuando sea posible.
Ver [references/openapi-conventions.md](references/openapi-conventions.md)
 
## Estilo de escritura del equipo
- Voz activa, segunda persona ("Ejecuta el comando" no "El comando debe ejecutarse")
- Ejemplos concretos siempre — nunca documentación solo teórica
- Español para documentación interna, inglés para código y comentarios
- Los ejemplos de código deben ser ejecutables tal como están escritos

El repositorio que acompaña esta serie incluye 18 Skills listas para usar, organizadas en tres grupos. Las cinco del tutorial las vimos en detalle en la sección anterior. Las trece restantes las describimos aquí; el código completo — con sus scripts, templates y referencias — está disponible en GitHub.

Skills del tutorial (5)

SkillComandoSe activa cuando...Tipo
tdd-spring /tdd-spring Pides escribir tests con JUnit 5, Mockito o Testcontainers para código Spring Boot Java
db-migration /db-migration Pides crear migraciones Flyway, cambiar el schema o hablas de SQL Java
spring-performance /spring-performance Reportas lentitud, queries N+1, startup lento o connection pool agotado Java
code-review /code-review Pides revisar código, hacer un code review o preparar un PR para revisión Genérico
technical-docs /technical-docs Pides escribir un ADR, un README de módulo o documentación de API Genérico

Skills adicionales para Java/Gradle (8)

SkillComandoSe activa cuando...
java-migration-21 /java-migration-21 Pides migrar a Java 21, preguntas sobre virtual threads, records, sealed classes o pattern matching. Incluye script que detecta código incompatible.
spring-security /spring-security Configuras Spring Security 6, implementas JWT, OAuth2, CORS o preguntas cómo proteger endpoints. Incluye script de auditoría rápida de configuración.
jpa-patterns /jpa-patterns Trabajas con entidades JPA, repositorios Spring Data, fetching strategies o reportas problemas de rendimiento en queries. Incluye script de detección de N+1.
api-design /api-design Diseñas endpoints REST, defines contratos OpenAPI, implementas paginación o manejas errores HTTP. Incluye template de controller estándar.
refactoring /refactoring Pides refactorizar código, eliminar code smells o reducir complejidad ciclomática. Incluye script que detecta métodos largos, clases grandes y duplicación.
observability /observability Configuras logging estructurado, métricas con Micrometer, trazas distribuidas o Spring Boot Actuator en producción.
dependency-upgrade /dependency-upgrade Quieres actualizar dependencias Gradle, detectar versiones desactualizadas, evaluar breaking changes o migrar a una versión mayor de Spring Boot. Incluye script con Gradle Versions Plugin + OWASP.
pr-quality /pr-quality Vas a abrir un PR, quieres verificar que cumple los estándares del equipo, preparar la descripción, o hacer un chequeo de calidad completo antes de solicitar revisión. Incluye script que verifica tests, cobertura, Checkstyle y git history.

Skills genéricas (5)

SkillComandoSe activa cuando...
git-workflow /git-workflow Trabajas con ramas, haces commits, preparas PRs, necesitas hacer rebase o squash, o preguntas sobre el flujo de trabajo Git del equipo (Conventional Commits, branching strategy).
debugging /debugging Reportas un bug, un error inesperado o comportamiento incorrecto. Incluye script que captura el estado del entorno, últimos commits, tests fallidos y logs de error.
incident-response /incident-response Hay un incidente de producción, caída del servicio o bug crítico. Incluye script de primera respuesta y template de postmortem.
security-scan-backend /security-scan-backend Pides un escaneo de seguridad del backend, una auditoría de vulnerabilidades Java/Spring, o cuando mencionas OWASP, CVEs, SQL injection, XSS o autenticación débil. Orquesta SpotBugs + FindSecurityBugs, Semgrep y OWASP Dependency Check.
security-scan-frontend /security-scan-frontend Pides un escaneo de seguridad del frontend, auditoría de código JS/TS/React, o cuando mencionas XSS, CSP, dependencias npm vulnerables, secrets en código cliente o almacenamiento inseguro de tokens. Orquesta npm audit, ESLint Security y Semgrep.
Skill de PR y calidad de código: La Skill pr-quality merece una mención especial porque es el punto de cierre de todo el proceso de desarrollo. Su script corre ./gradlew test, verifica cobertura con JaCoCo, corre Checkstyle, valida que el historial de commits sigue Conventional Commits, y verifica que no hay archivos olvidados en el staging area. La Skill genera un reporte de preparación del PR y, si todo está en verde, propone automáticamente la descripción del PR con el formato del equipo.

Buenas prácticas y errores comunes

La descripción es el 80% del trabajo

Si una Skill no se activa automáticamente cuando debería, el problema está casi siempre en la descripción. Tres reglas prácticas:

  • Escribe la descripción como si describieras cuándo un developer le pediría esa ayuda al agente, en lenguaje natural
  • Incluye sinónimos y variaciones de la tarea: "testear", "escribir tests", "TDD", "JUnit"
  • Si el agente no la activa, invócala con /nombre-skill y luego ajusta la descripción para que sea más explícita

Mantén el SKILL.md enfocado

El SKILL.md debe ser una guía de entrada, no una enciclopedia. El detalle va en los archivos de references/. Un buen SKILL.md tiene entre 30 y 80 líneas de contenido (excluyendo el frontmatter). Si supera las 150 líneas, es señal de que debería dividirse en dos Skills o que el detalle debería moverse a referencias.

Versiona tus Skills como código

Las Skills del proyecto (.claude/skills/) van en Git. Trátalas como código: commits descriptivos cuando cambias una instrucción, PR de revisión para Skills que afectan al equipo completo, y un changelog si las cambias frecuentemente.

Errores comunes

ErrorConsecuenciaSolución
Descripción demasiado genérica La Skill se activa en tareas no relacionadas o nunca se activa Ser específico sobre qué tareas concretas deben activarla
Instrucciones contradictorias con el CLAUDE.md El agente recibe señales conflictivas y elige arbitrariamente Auditar que Skills y CLAUDE.md no se contradigan; la Skill tiene precedencia en su dominio
Scripts que producen output masivo El output del script satura el contexto Filtrar el output en el script: | tail -20, | grep -E "ERROR|WARN"
Skills de terceros sin revisar Posible ejecución de código malicioso o extracción de datos Revisar todos los archivos del directorio antes de instalar

Conclusión

Las Skills resuelven un problema que el CLAUDE.md no puede resolver de forma eficiente: el conocimiento especializado de dominio que solo es relevante en ciertos momentos. En lugar de meter todo en un solo archivo que se carga siempre, las Skills son módulos de conocimiento que el agente carga bajo demanda, cuando la tarea los necesita.

Los tres conceptos que marcan la diferencia entre usar Skills básicamente y usarlas bien:

  • La descripción del frontmatter es lo que determina si la invocación automática funciona. Inviértele tiempo.
  • Los archivos de soporte (referencias, templates, scripts) son lo que transforma una Skill de un prompt largo en un colaborador especializado con herramientas propias.
  • El estándar Agent Skills hace que las Skills que construyas sean portables. Vale la pena escribirlas con ese estándar en mente desde el principio.

El repositorio de la serie en GitHub contiene las 18 Skills descritas en este artículo, listas para copiar a cualquier proyecto Java/Gradle. Cada Skill incluye el SKILL.md, sus scripts de análisis, templates y referencias — todo lo necesario para que el agente tenga contexto especializado desde el primer día.

En el próximo artículo veremos Custom Commands en profundidad: argumentos dinámicos con $ARGUMENTS, integración con el sistema de Tasks, y cómo combinar Commands con Skills para crear flujos de trabajo completos y reutilizables.

© javatutoriales.com – Serie: Desarrollo Asistido por IA