Guía Completa de Habilidades en Claude Code: Automatiza tu Flujo de Trabajo

¿Imagina poder enseñarle a Claude exactamente cómo tu equipo trabaja? No solo pedir ayuda genérica, sino tener un asistente que entienda tus estándares de revisión de código, tus formatos de commits preferidos, incluso tu esquema de base de datos. Eso es exactamente lo que hacen las Habilidades en Claude Code.

Las Habilidades son archivos Markdown que enseñan a Claude cómo realizar tareas específicas en tu contexto. Funcionan automáticamente cuando los necesitas, sin que tengas que invocarlos explícitamente. Es como tener un colega experto que siempre sabe exactamente qué hacer, porque ya conoce tus estándares internos.

Para los fundadores de startups, esto significa una cosa crucial: puedes escalar tu equipo técnico sin contratar más desarrolladores. Una única Habilidad bien diseñada puede multiplicar la productividad de todo tu equipo de ingeniería.

Núcleo de las Habilidades: Cómo Funcionan en la Práctica

Las Habilidades funcionan de manera simple pero poderosa. Cuando le haces una pregunta a Claude, el sistema busca automáticamente si hay una Habilidad que coincida con lo que necesitas. Si existe, Claude la aplica al instante. No necesitas recordar comandos especiales ni configuraciones complicadas.

Dónde Viven tus Habilidades

La ubicación donde guardas una Habilidad determina quién puede usarla. Piensa en esto como círculos concéntricos de acceso:

Habilidades Empresariales (para toda tu organización): Se configuran a través de ajustes gestionados. Perfectas para estándares que todos en tu empresa deben seguir—como tu guía de revisión de código o estándares de seguridad.

Habilidades Personales (solo para ti): Se guardan en ~/.claude/skills/. Estas son tus atajos privados, como instrucciones para generar documentación en tu estilo particular.

Habilidades de Proyecto (para tu repositorio): Se guardan en .claude/skills/ dentro de tu proyecto. Cualquiera que trabaje en el repositorio las obtiene automáticamente. Ideal para estándares específicos del proyecto.

Habilidades de Plugins: Vienen incluidas con plugins que instalas. Se distribuyen ampliamente y funcionan en múltiples proyectos.

Si dos Habilidades comparten el nombre, prevalece la más específica. Las empresariales ganan sobre las personales, que ganan sobre las de proyecto, que ganan sobre las de plugins. Así que si necesitas una excepción, simplemente crea una versión más específica.

Cuándo Usar Habilidades (y Cuándo No)

Las Habilidades no son la única forma de personalizar Claude Code. Hay varias opciones, y cada una brilla en situaciones diferentes.

Usa Habilidades cuando quieras que Claude aplique automáticamente conocimiento especializado. Por ejemplo: "Revisa mis PRs usando nuestros estándares internos" o "Genera commits en nuestro formato específico". Claude decide cuándo usarlas basándose en lo que haces.

Usa Comandos de Barra cuando quieras crear prompts reutilizables que invocas explícitamente escribiendo /comando. Por ejemplo, /deploy staging que despliega automáticamente a tu entorno de staging. Tú tienes el control total sobre cuándo se ejecutan.

Usa CLAUDE.md para instrucciones que aplican a todo tu proyecto. Es como una configuración global—establecer "usar modo estricto de TypeScript" o "siempre usar esta estructura de directorios".

Usa Subagentes cuando necesitas que Claude delegue trabajo a un contexto completamente separado con sus propias herramientas. Piensa en esto como darle a Claude un colega especializado que maneja ciertos tipos de trabajo de forma independiente.

Usa Hooks para ejecutar scripts en eventos específicos. Por ejemplo, ejecutar linting automáticamente cuando guardas un archivo.

Usa Servidores MCP para conectar Claude a herramientas y datos externos—como tu base de datos o servicios en la nube.

La diferencia fundamental: Habilidades = Enseñanza, ** Herramientas = Acceso**. Las Habilidades le dicen a Claude cómo hacer algo según tus reglas. Las herramientas le permiten acceder a datos o ejecutar acciones.

Tu Primer Paso: Crear tu Primera Habilidad

Crear una Habilidad es sorprendentemente simple. Necesitas un solo archivo: SKILL.md. Vamos a construir un ejemplo real que puedes usar inmediatamente.

Imaginemos que tu equipo siempre quiere explicaciones de código que incluyan diagramas visuales y analogías del mundo real. Sin una Habilidad, obtendrías explicaciones genéricas. Con una Habilidad, Claude siempre incluirá ambas cosas, automáticamente.

Crear tu Primer Archivo de Habilidad

Crea una carpeta llamada code-explainer en .claude/skills/ (si esta carpeta no existe, créala). Dentro, crea un archivo llamado SKILL.md:

---
name: code-explainer
description: Explain code using ASCII diagrams and real-world analogies. Use this when Claude needs to explain code concepts, algorithms, or architecture.
---

# Code Explainer

## Instructions

When explaining code, always include three elements:

1. **ASCII Diagram**: Create a visual representation of how the code works
2. **Real-World Analogy**: Compare the concept to something familiar
3. **Step-by-Step Breakdown**: Walk through the logic clearly

## Example

For a caching system, you might draw:

[Request] → [Cache Check] → [Cache Hit?] → [Return Cached] or [Compute & Store]

Then compare it to: "Like a librarian remembering which books people ask for most often"

Ese es todo el archivo. No es magia complicada. Es simplemente decirle a Claude: "Cuando expliques código, siempre incluye estos tres elementos."

Ahora, cuando le pidas a Claude que explique código en tu proyecto, automáticamente incluirá diagramas y analogías sin que tengas que pedirlo cada vez.

Estructura Profunda: Configurar Habilidades Profesionales

A medida que crecen tus Habilidades, necesitas más control. Aquí está cómo construir Habilidades profesionales que escalen con tu startup.

El Formato Completo de SKILL.md

Tu archivo SKILL.md tiene dos secciones: metadatos YAML en la parte superior (entre marcadores ---) e instrucciones Markdown después:

---
name: your-skill-name
description: Brief description of what this Skill does and when to use it
allowed-tools: Read, Grep, Glob
model: claude-sonnet-4-20250514
context: fork
agent: general-purpose
user-invocable: true
---

# Your Skill Name

## Instructions
Your detailed guidance here...

Cada campo controla un aspecto diferente de cómo funciona tu Habilidad:

name (requerido): El identificador de tu Habilidad. Usa solo minúsculas, números y guiones. Máximo 64 caracteres. Debe coincidir exactamente con el nombre de tu carpeta.

description (requerido): La descripción es crítica. Claude lee esto para decidir si tu Habilidad es relevante. Una descripción vaga como "Ayuda con documentos" no le dice a Claude cuándo usarla. Una descripción fuerte dice tanto qué hace como cuándo usarla.

allowed-tools: Una lista de herramientas que Claude puede usar sin pedirte permiso cuando esta Habilidad está activa. Perfecto para Habilidades de solo lectura. Si omites esto, Claude usará sus permisos estándar y te pedirá aprobación según sea necesario.

model: Especifica qué modelo de Claude usar cuando esta Habilidad está activa. Útil si una Habilidad necesita un modelo más potente o más rápido.

context: fork: Ejecuta la Habilidad en un subagente aislado con su propio historial de conversación. Ideal para Habilidades que hacen mucho trabajo sin saturar tu conversación principal.

user-invocable: Controla si la Habilidad aparece en el menú de comandos de barra /. Establécelo en false para Habilidades que Claude usa automáticamente pero que los usuarios no deberían invocar manualmente.

Archivos de Soporte y Divulgación Progresiva

Las Habilidades complejas consumen contexto. Para mantener las cosas eficientes, usa divulgación progresiva: pon lo esencial en SKILL.md y referencia documentación detallada en archivos separados que Claude carga solo cuando sea necesario.

Imagina una Habilidad para procesar PDFs. Tu estructura podría verse así:

pdf-processing/
├── SKILL.md              (resumen y inicio rápido)
├── FORMS.md              (instrucciones detalladas de rellenado de formularios)
├── REFERENCE.md          (detalles completos de la API)
└── scripts/
    ├── fill_form.py      (utilidad para rellenar campos)
    └── validate.py       (validador de PDFs)

En tu SKILL.md, haces referencia a estos archivos para que Claude sepa que existen:

## Quick Start

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

For detailed form filling instructions, see FORMS.md
For complete API reference, see REFERENCE.md

Claude carga estos archivos solo cuando realmente los necesita, manteniéndose enfocado. Es como tener documentación de referencia disponible sin saturar la memoria de trabajo.

### Restringir Herramientas para Seguridad

Para una Habilidad que solo lee archivos sin modificarlos, usa `allowed-tools`:

```yaml
---
name: reading-files-safely
description: Read files without making changes. Use for read-only file access to code reviews or documentation analysis.
allowed-tools: Read, Grep, Glob
---

Ahora Claude solo puede usar esas tres herramientas. Si intenta escribir un archivo, obtiene un error en lugar de pedirte permiso. Es una forma de "seguridad por diseño"—la Habilidad no puede hacer daño incluso si lo intenta.

Ejecutar Habilidades en Contexto Bifurcado

Para Habilidades que hacen mucho trabajo sin abrumar tu conversación principal, usa context: fork:

---
name: code-analysis
description: Analyze code quality and generate detailed reports in isolation
context: fork
agent: general-purpose
---

Esto ejecuta la Habilidad en un subagente completamente separado. Claude completa el trabajo, genera un informe, y tu conversación principal permanece limpia. Es como tener un colega en una sala separada haciendo un análisis profundo y luego traerte los resultados.

Habilidades en la Práctica: Patrones del Mundo Real

Veamos patrones reales que funcionan para startups.

El Patrón Simple: Ayuda de Commits

Una Habilidad mínima para mejorar los mensajes de commit:

---
name: commit-helper
description: Generate clear commit messages from git diffs. Use when writing commits or reviewing staged changes.
---

# Commit Message Helper

## Instructions

1. Run `git diff --staged` to see changes
2. Suggest a message with:
   - Summary under 50 characters
   - Detailed description
   - Affected components

## Best Practices

- Use present tense
- Explain what and why, not how
- Reference tickets if applicable

Cuando le pides a Claude "Help me write a commit message", automáticamente ejecuta esto. Obtienes commits consistentes en todo tu equipo sin documentación complicada.

El Patrón Avanzado: Procesamiento de PDFs con Scripts

Para Habilidades más complejas, combina documentación con scripts ejecutables:

---
name: pdf-processing
description: Extract text, fill forms, merge PDFs. Use when working with PDF files, forms, or document extraction. Requires pypdf and pdfplumber packages.
allowed-tools: Read, Bash(python:*)
---

# PDF Processing

## Quick Start

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

To fill forms, see FORMS.md
For detailed API reference, see REFERENCE.md

Requirements

pip install pypdf pdfplumber

Form Filling Utility

Validate and fill forms automatically:

python scripts/fill_form.py template.pdf data.json output.pdf

Aquí, Claude puede ejecutar scripts Python sin cargar el código entero en el contexto. Es eficiente y seguro.

### El Patrón Organizacional: Habilidades de Equipo

Para startups con equipos distribuidos, crea Habilidades que estandaricen cómo trabaja el equipo. Por ejemplo, estándares de revisión de código:

```yaml
---
name: code-review-standards
description: Apply our team's code review standards when reviewing pull requests. Use when reviewing code, PRs, or discussing code quality.
user-invocable: false
---

# Code Review Standards

Our team uses these principles:

## Performance
- Queries should use indexes
- Avoid N+1 database queries
- Monitor bundle size

## Security
- All user input must be validated
- Use parameterized queries
- Never log passwords or tokens

## Testing
- New features need unit tests
- Critical paths need integration tests
- Aim for 80%+ coverage

Con user-invocable: false, Claude la usa automáticamente durante revisiones sin que aparezca en el menú de comandos. Es perfecto para estándares que quieres que Claude siempre aplique.

Control Avanzado: Visibilidad y Permisos

A veces quieres que Claude use una Habilidad automáticamente, pero que el usuario no pueda invocarla manualmente. O lo opuesto: quieres que el usuario pueda invocarla, pero que Claude no la descubra automáticamente.

Aquí está cómo controlar exactamente quién puede hacer qué:

Setting	Menú de Barra	Herramienta Skill	Auto-descubrimiento	Cuándo Usar
user-invocable: true (defecto)	✓ Visible	✓ Permitido	✓ Sí	Habilidades para uso general del equipo
user-invocable: false	✗ Oculto	✓ Permitido	✓ Sí	Habilidades que Claude debe usar pero no exposición manual
disable-model-invocation: true	✓ Visible	✗ Bloqueado	✓ Sí	Habilidades para uso manual, no automático por Claude

Para una Habilidad interna que solo Claude debe usar:

---
name: internal-review-standards
description: Apply our internal code review standards
user-invocable: false
---

Los usuarios nunca la ven, pero Claude la aplica automáticamente en revisiones.

Distribuyendo Habilidades: De Personal a Empresarial

A medida que crecen tus Habilidades, necesitas distribuirlas a tu equipo.

Para un proyecto específico: Confirma .claude/skills/ en tu repositorio. Cuando los desarrolladores clonan, obtienen las Habilidades automáticamente. Perfecto para estándares específicos del proyecto.

Para múltiples proyectos: Crea un Plugin con tus Habilidades en un directorio skills/ y distribúyelo a través del marketplace de plugins de tu equipo. Cada proyecto puede instalarlo.

Para toda tu empresa: Los administradores pueden implementar Habilidades en toda la organización usando configuraciones gestionadas. Establece estándares de codificación globales, pautas de seguridad, formatos de documentación—una sola vez, accesible a todos.

Solución de Problemas: Cuando las Cosas No Funcionan

Tu Habilidad No Se Activa

El 90% de los problemas aquí es una descripción vaga. Claude lee description para decidir si usar tu Habilidad. Si dice "Ayuda con documentos", Claude no sabe cuándo es relevante.

Una buena descripción responde dos preguntas:

1. ¿Qué hace? Acciones específicas (extraer, llenar, revisar)
2. ¿Cuándo se usa? Palabras clave que los usuarios dirían (PDF, formulario, PR, código)

Malo: "Helps with documents"
Bueno: "Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDFs, forms, or document extraction."

Las palabras clave en la descripción buena (PDF, formularios, extracción) son lo que los usuarios realmente mencionan cuando necesitan la Habilidad.

Tu Habilidad No Carga

Verifica la ruta: Las Habilidades deben estar exactamente en el lugar correcto con el nombre exacto SKILL.md (sensible a mayúsculas):

• Personal: ~/.claude/skills/my-skill/SKILL.md
• Proyecto: .claude/skills/my-skill/SKILL.md
• Empresa: Consulta tus guías de configuración gestionada

Verifica YAML: El frontmatter debe comenzar con --- en la línea 1 (sin líneas en blanco antes), terminar con --- antes del contenido, e usar espacios para indentación (no tabulaciones).

---
name: my-skill
description: What this does
---

# Your content starts here

Usa modo debug: Ejecuta claude --debug para ver errores de carga.

Conflictos Entre Habilidades

Si Claude usa la Habilidad equivocada, tus descripciones probablemente sean demasiado similares. Diferencia cada descripción con términos desencadenantes específicos:

En lugar de dos Habilidades que ambas mencionan "análisis de datos", diferencia:

• Una: "Datos de ventas en archivos Excel y exportaciones de CRM"
• Otra: "Archivos de registro del sistema y métricas de infraestructura"

Cuanto más específicos, mejor matchea Claude la Habilidad correcta.

Habilidades de Plugins No Aparecen

Si instalaste un plugin pero sus Habilidades no aparecen, borra la caché:

rm -rf ~/.claude/plugins/cache

Reinstala el plugin. Esto obliga a Claude a volver a registrar todas las Habilidades.

Verifica que la estructura sea:

my-plugin/
├── .claude-plugin/
│   └── plugin.json
└── skills/
    └── my-skill/
        └── SKILL.md

Potenciando tu Startup: El Impacto Real

Para un fundador de startup, las Habilidades significan una cosa: escala sin agregar headcount. Una Habilidad bien diseñada que estandariza cómo tu equipo revisa código, escribe commits, o estructura documentación multiplica la productividad de cada ingeniero.

Aquí está el impacto real:

Un desarrollador que pasaba 30 minutos diarios escribiendo commits o esperando revisiones de código. Con Habilidades, eso desaparece. Claude genera commits automáticamente, revisa cambios según tus estándares, identifica problemas antes de que los vea un humano. Ahora tu desarrollador tiene 30 minutos más para construir.

Multiplica eso por todo tu equipo. Si tienes 5 desarrolladores, eso es 2.5 horas de ingeniería recuperadas cada día. En una startup donde cada hora cuenta, eso es la diferencia entre lanzar una semana antes o después.

Las Habilidades son también tu defensa contra la deuda técnica. Estándares documentados que Claude siempre aplica significan que no importa quién escriba código, es consistente. Nuevos contratados siguen automáticamente los estándares del equipo. Tu base de código permanece limpia a medida que creces.

Conclusión: Tu Próximo Paso

Crea tu primera Habilidad hoy. No necesita ser perfecta. Una Habilidad simple que mejore un solo flujo de trabajo vale más que ninguna Habilidad.

Comienza con algo pequeño: tal vez una Habilidad que mejore cómo tu equipo revisa código, o que estandarice tus mensajes de commit. Una vez que veas el impacto, expandirás naturalmente a más Habilidades.

La verdadera magia sucede cuando tus Habilidades se vuelven la forma en que trabaja tu equipo—no algo adicional, sino la forma en que haces las cosas. Ese es el momento en que una startup pequeña compite como si fuera más grande, porque cada ingeniero trabaja como si tuviera un conjunto de expertos al lado.

---

Original source: Agent Skills - Claude Code Docs

powered by osmu.app