Esta guía te muestra cómo crear, usar y gestionar Habilidades de Agente en Claude Code. Las Habilidades son capacidades modulares que extienden la funcionalidad de Claude a través de carpetas organizadas que contienen instrucciones, scripts y recursos.

​
Prerrequisitos

  • Claude Code versión 1.0 o posterior
  • Familiaridad básica con Claude Code

​
¿Qué son las Habilidades de Agente?

Las Habilidades de Agente empaquetan experiencia en capacidades descubribles. Cada Habilidad consiste en un archivo SKILL.md con instrucciones que Claude lee cuando es relevante, además de archivos de apoyo opcionales como scripts y plantillas. Cómo se invocan las Habilidades: Las Habilidades son invocadas por el modelo—Claude decide autónomamente cuándo usarlas basándose en tu solicitud y la descripción de la Habilidad. Esto es diferente de los comandos de barra, que son invocados por el usuario (escribes explícitamente /comando para activarlos). Beneficios:
  • Extienden las capacidades de Claude para tus flujos de trabajo específicos
  • Comparten experiencia a través de tu equipo vía git
  • Reducen la necesidad de prompts repetitivos
  • Componen múltiples Habilidades para tareas complejas
Aprende más en la descripción general de Habilidades de Agente.
Para una inmersión profunda en la arquitectura y aplicaciones del mundo real de las Habilidades de Agente, lee nuestro blog de ingeniería: Equipping agents for the real world with Agent Skills.

​
Crear una Habilidad

Las Habilidades se almacenan como directorios que contienen un archivo SKILL.md.

​
Habilidades Personales

Las Habilidades Personales están disponibles en todos tus proyectos. Almacénalas en ~/.claude/skills/: 
mkdir -p ~/.claude/skills/mi-nombre-de-habilidad
Usa Habilidades personales para:
  • Tus flujos de trabajo y preferencias individuales
  • Habilidades experimentales que estás desarrollando
  • Herramientas de productividad personal

​
Habilidades de Proyecto

Las Habilidades de Proyecto se comparten con tu equipo. Almacénalas en .claude/skills/ dentro de tu proyecto: 
mkdir -p .claude/skills/mi-nombre-de-habilidad
Usa Habilidades de proyecto para:
  • Flujos de trabajo y convenciones del equipo
  • Experiencia específica del proyecto
  • Utilidades y scripts compartidos
Las Habilidades de Proyecto se registran en git y están automáticamente disponibles para los miembros del equipo.

​
Habilidades de Plugin

Las Habilidades también pueden provenir de plugins de Claude Code. Los plugins pueden incluir Habilidades que están automáticamente disponibles cuando el plugin está instalado. Estas Habilidades funcionan de la misma manera que las Habilidades personales y de proyecto.

​
Escribir SKILL.md

Crea un archivo SKILL.md con frontmatter YAML y contenido Markdown: 
---
name: Nombre de Tu Habilidad
description: Breve descripción de lo que hace esta Habilidad y cuándo usarla
---

# Nombre de Tu Habilidad

## Instrucciones
Proporciona orientación clara, paso a paso para Claude.

## Ejemplos
Muestra ejemplos concretos de usar esta Habilidad.
El campo description es crítico para que Claude descubra cuándo usar tu Habilidad. Debe incluir tanto lo que hace la Habilidad como cuándo Claude debería usarla. Ve la guía de mejores prácticas para orientación completa de autoría.

​
Agregar archivos de apoyo

Crea archivos adicionales junto a SKILL.md: 
mi-habilidad/
├── SKILL.md (requerido)
├── reference.md (documentación opcional)
├── examples.md (ejemplos opcionales)
├── scripts/
│   └── helper.py (utilidad opcional)
└── templates/
    └── template.txt (plantilla opcional)
Referencia estos archivos desde SKILL.md: 
Para uso avanzado, ve [reference.md](reference.md).

Ejecuta el script auxiliar:
```bash
python scripts/helper.py input.txt
```
Claude lee estos archivos solo cuando es necesario, usando divulgación progresiva para gestionar el contexto eficientemente.

​
Restringir acceso a herramientas con allowed-tools

Usa el campo de frontmatter allowed-tools para limitar qué herramientas puede usar Claude cuando una Habilidad está activa: 
---
name: Lector de Archivos Seguro
description: Lee archivos sin hacer cambios. Usa cuando necesites acceso de solo lectura a archivos.
allowed-tools: Read, Grep, Glob
---

# Lector de Archivos Seguro

Esta Habilidad proporciona acceso de solo lectura a archivos.

## Instrucciones
1. Usa Read para ver contenidos de archivos
2. Usa Grep para buscar dentro de archivos
3. Usa Glob para encontrar archivos por patrón
Cuando esta Habilidad está activa, Claude solo puede usar las herramientas especificadas (Read, Grep, Glob) sin necesidad de pedir permiso. Esto es útil para:
  • Habilidades de solo lectura que no deberían modificar archivos
  • Habilidades con alcance limitado (ej., solo análisis de datos, sin escritura de archivos)
  • Flujos de trabajo sensibles a la seguridad donde quieres restringir capacidades
Si allowed-tools no se especifica, Claude pedirá permiso para usar herramientas como normal, siguiendo el modelo de permisos estándar.
allowed-tools solo se soporta para Habilidades en Claude Code.

​
Ver Habilidades disponibles

Las Habilidades son automáticamente descubiertas por Claude desde tres fuentes:
  • Habilidades Personales: ~/.claude/skills/
  • Habilidades de Proyecto: .claude/skills/
  • Habilidades de Plugin: incluidas con plugins instalados
Para ver todas las Habilidades disponibles, pregunta directamente a Claude: 
¿Qué Habilidades están disponibles?
o 
Lista todas las Habilidades disponibles
Esto mostrará todas las Habilidades de todas las fuentes, incluyendo Habilidades de plugin. Para inspeccionar una Habilidad específica, también puedes revisar el sistema de archivos: 
# Listar Habilidades personales
ls ~/.claude/skills/

# Listar Habilidades de proyecto (si estás en un directorio de proyecto)
ls .claude/skills/

# Ver el contenido de una Habilidad específica
cat ~/.claude/skills/mi-habilidad/SKILL.md

​
Probar una Habilidad

Después de crear una Habilidad, pruébala haciendo preguntas que coincidan con tu descripción. Ejemplo: Si tu descripción menciona “archivos PDF”: 
¿Puedes ayudarme a extraer texto de este PDF?
Claude decide autónomamente usar tu Habilidad si coincide con la solicitud—no necesitas invocarla explícitamente. La Habilidad se activa automáticamente basándose en el contexto de tu pregunta.

​
Depurar una Habilidad

Si Claude no usa tu Habilidad, revisa estos problemas comunes:

​
Hacer la descripción específica

Muy vago: 
description: Ayuda con documentos
Específico: 
description: Extrae texto y tablas de archivos PDF, llena formularios, fusiona documentos. Usa cuando trabajas con archivos PDF o cuando el usuario menciona PDFs, formularios, o extracción de documentos.
Incluye tanto lo que hace la Habilidad como cuándo usarla en la descripción.

​
Verificar ruta de archivo

Habilidades Personales: ~/.claude/skills/nombre-habilidad/SKILL.md Habilidades de Proyecto: .claude/skills/nombre-habilidad/SKILL.md Verifica que el archivo existe: 
# Personal
ls ~/.claude/skills/mi-habilidad/SKILL.md

# Proyecto
ls .claude/skills/mi-habilidad/SKILL.md

​
Revisar sintaxis YAML

YAML inválido previene que la Habilidad se cargue. Verifica el frontmatter: 
cat SKILL.md | head -n 10
Asegúrate de:
  • --- de apertura en línea 1
  • --- de cierre antes del contenido Markdown
  • Sintaxis YAML válida (sin tabs, indentación correcta)

​
Ver errores

Ejecuta Claude Code con modo debug para ver errores de carga de Habilidades: 
claude --debug

​
Compartir Habilidades con tu equipo

Enfoque recomendado: Distribuir Habilidades a través de plugins. Para compartir Habilidades vía plugin:
  1. Crea un plugin con Habilidades en el directorio skills/
  2. Agrega el plugin a un marketplace
  3. Los miembros del equipo instalan el plugin
Para instrucciones completas, ve Agregar Habilidades a tu plugin. También puedes compartir Habilidades directamente a través de repositorios de proyecto:

​
Paso 1: Agregar Habilidad a tu proyecto

Crea una Habilidad de proyecto: 
mkdir -p .claude/skills/habilidad-equipo
# Crear SKILL.md

​
Paso 2: Hacer commit a git

git add .claude/skills/
git commit -m "Agregar Habilidad de equipo para procesamiento de PDF"
git push

​
Paso 3: Los miembros del equipo obtienen Habilidades automáticamente

Cuando los miembros del equipo hacen pull de los últimos cambios, las Habilidades están inmediatamente disponibles: 
git pull
claude  # Las Habilidades ahora están disponibles

​
Actualizar una Habilidad

Edita SKILL.md directamente: 
# Habilidad Personal
code ~/.claude/skills/mi-habilidad/SKILL.md

# Habilidad de Proyecto
code .claude/skills/mi-habilidad/SKILL.md
Los cambios toman efecto la próxima vez que inicies Claude Code. Si Claude Code ya está ejecutándose, reinícialo para cargar las actualizaciones.

​
Remover una Habilidad

Elimina el directorio de la Habilidad: 
# Personal
rm -rf ~/.claude/skills/mi-habilidad

# Proyecto
rm -rf .claude/skills/mi-habilidad
git commit -m "Remover Habilidad no usada"

​
Mejores prácticas

​
Mantener Habilidades enfocadas

Una Habilidad debería abordar una capacidad: Enfocado:
  • “Llenado de formularios PDF”
  • “Análisis de datos Excel”
  • “Mensajes de commit Git”
Muy amplio:
  • “Procesamiento de documentos” (dividir en Habilidades separadas)
  • “Herramientas de datos” (dividir por tipo de datos u operación)

​
Escribir descripciones claras

Ayuda a Claude a descubrir cuándo usar Habilidades incluyendo disparadores específicos en tu descripción: Clara: 
description: Analiza hojas de cálculo Excel, crea tablas dinámicas, y genera gráficos. Usa cuando trabajas con archivos Excel, hojas de cálculo, o analizando datos tabulares en formato .xlsx.
Vaga: 
description: Para archivos

​
Probar con tu equipo

Haz que compañeros de equipo usen Habilidades y proporcionen retroalimentación:
  • ¿Se activa la Habilidad cuando se espera?
  • ¿Son claras las instrucciones?
  • ¿Faltan ejemplos o casos extremos?

​
Documentar versiones de Habilidad

Puedes documentar versiones de Habilidad en tu contenido SKILL.md para rastrear cambios a lo largo del tiempo. Agrega una sección de historial de versiones: 
# Mi Habilidad

## Historial de Versiones
- v2.0.0 (2025-10-01): Cambios importantes en API
- v1.1.0 (2025-09-15): Agregadas nuevas características
- v1.0.0 (2025-09-01): Lanzamiento inicial
Esto ayuda a los miembros del equipo a entender qué cambió entre versiones.

​
Solución de problemas

​
Claude no usa mi Habilidad

Síntoma: Haces una pregunta relevante pero Claude no usa tu Habilidad. Revisar: ¿Es la descripción suficientemente específica? Descripciones vagas hacen el descubrimiento difícil. Incluye tanto lo que hace la Habilidad como cuándo usarla, con términos clave que los usuarios mencionarían. Muy genérico: 
description: Ayuda con datos
Específico: 
description: Analiza hojas de cálculo Excel, genera tablas dinámicas, crea gráficos. Usa cuando trabajas con archivos Excel, hojas de cálculo, o archivos .xlsx.
Revisar: ¿Es válido el YAML? Ejecuta validación para revisar errores de sintaxis: 
# Ver frontmatter
cat .claude/skills/mi-habilidad/SKILL.md | head -n 15

# Revisar problemas comunes
# - Falta --- de apertura o cierre
# - Tabs en lugar de espacios
# - Strings sin comillas con caracteres especiales
Revisar: ¿Está la Habilidad en la ubicación correcta? 
# Habilidades Personales
ls ~/.claude/skills/*/SKILL.md

# Habilidades de Proyecto
ls .claude/skills/*/SKILL.md

​
La Habilidad tiene errores

Síntoma: La Habilidad se carga pero no funciona correctamente. Revisar: ¿Están disponibles las dependencias? Claude instalará automáticamente las dependencias requeridas (o pedirá permiso para instalarlas) cuando las necesite. Revisar: ¿Tienen los scripts permisos de ejecución? 
chmod +x .claude/skills/mi-habilidad/scripts/*.py
Revisar: ¿Son correctas las rutas de archivos? Usa barras diagonales (estilo Unix) en todas las rutas: Correcto: scripts/helper.py Incorrecto: scripts\helper.py (estilo Windows)

​
Múltiples Habilidades entran en conflicto

Síntoma: Claude usa la Habilidad incorrecta o parece confundido entre Habilidades similares. Ser específico en descripciones: Ayuda a Claude a elegir la Habilidad correcta usando términos disparadores distintos en tus descripciones. En lugar de: 
# Habilidad 1
description: Para análisis de datos

# Habilidad 2
description: Para analizar datos
Usa: 
# Habilidad 1
description: Analiza datos de ventas en archivos Excel y exportaciones CRM. Usa para reportes de ventas, análisis de pipeline, y seguimiento de ingresos.

# Habilidad 2
description: Analiza archivos de log y datos de métricas del sistema. Usa para monitoreo de rendimiento, depuración, y diagnósticos del sistema.

​
Ejemplos

​
Habilidad Simple (archivo único)

commit-helper/
└── SKILL.md

---
name: Generando Mensajes de Commit
description: Genera mensajes de commit claros desde diffs de git. Usa cuando escribes mensajes de commit o revisas cambios preparados.
---

# Generando Mensajes de Commit

## Instrucciones

1. Ejecuta `git diff --staged` para ver cambios
2. Sugeriré un mensaje de commit con:
   - Resumen bajo 50 caracteres
   - Descripción detallada
   - Componentes afectados

## Mejores prácticas

- Usa tiempo presente
- Explica qué y por qué, no cómo

​
Habilidad con permisos de herramientas

code-reviewer/
└── SKILL.md

---
name: Revisor de Código
description: Revisa código para mejores prácticas y problemas potenciales. Usa cuando revisas código, verificas PRs, o analizas calidad de código.
allowed-tools: Read, Grep, Glob
---

# Revisor de Código

## Lista de verificación de revisión

1. Organización y estructura del código
2. Manejo de errores
3. Consideraciones de rendimiento
4. Preocupaciones de seguridad
5. Cobertura de pruebas

## Instrucciones

1. Lee los archivos objetivo usando la herramienta Read
2. Busca patrones usando Grep
3. Encuentra archivos relacionados usando Glob
4. Proporciona retroalimentación detallada sobre calidad del código

​
Habilidad Multi-archivo

pdf-processing/
├── SKILL.md
├── FORMS.md
├── REFERENCE.md
└── scripts/
    ├── fill_form.py
    └── validate.py
SKILL.md: 
---
name: Procesamiento de PDF
description: Extrae texto, llena formularios, fusiona PDFs. Usa cuando trabajas con archivos PDF, formularios, o extracción de documentos. Requiere paquetes pypdf y pdfplumber.
---

# Procesamiento de PDF

## Inicio rápido

Extraer texto:
```python
import pdfplumber
with pdfplumber.open("doc.pdf") as pdf:
    text = pdf.pages[0].extract_text()
```

Para llenado de formularios, ve [FORMS.md](FORMS.md).
Para referencia detallada de API, ve [REFERENCE.md](REFERENCE.md).

## Requisitos

Los paquetes deben estar instalados en tu entorno:
```bash
pip install pypdf pdfplumber
```
Lista los paquetes requeridos en la descripción. Los paquetes deben estar instalados en tu entorno antes de que Claude pueda usarlos.
Claude carga archivos adicionales solo cuando es necesario.

​
Próximos pasos

Mejores prácticas de autoría

Escribe Habilidades que Claude pueda usar efectivamente

Descripción general de Habilidades de Agente

Aprende cómo funcionan las Habilidades a través de productos Claude

Comenzar con Habilidades de Agente

Crea tu primera Habilidad