Claude Code Skills: La Receta Secreta para Enseñarle a la IA Tu Forma de Trabajar

TL;DR: Los Skills de Claude Code son como las recetas de la nonna: instrucciones cuidadosamente escritas que se transmiten para que otros sepan exactamente cómo hacer las cosas a tu manera. Mientras MCP es como la despensa bien surtida (los ingredientes), los Skills son las recetas que te enseñan cómo combinarlos con amor y maestría.

El arte de transmitir conocimiento

Mamma mia, cuando trabajo con Claude, me recuerda a cuando enseño a cocinar a mis sobrinos. Claude es increíblemente capaz, como un chef con talento natural, pero no conoce mis secretos, mis técnicas, o mi forma especial de hacer las cosas.

¿Cómo le transmites a Claude que en tu equipo:

Los commits siguen Conventional Commits con scopes específicos (como seguir la receta exacta de la nonna)
Las PRs deben incluir screenshots para cambios de UI (como la foto del plato terminado)
El código pasa por un linter custom antes de commitear (como probar la salsa antes de servir)
Los deploys requieren aprobar un checklist de seguridad (como verificar que el horno esté a la temperatura correcta)

Podrías explicar esto cada vez, como repetir las instrucciones en cada cena familiar. O podrías escribirlo una vez, con cuidado y dedicación, en un Skill - tu receta personal que se transmite de generación en generación.

¿Qué son los Skills?

Un Skill es como un libro de recetas de familia: un directorio con un archivo SKILL.md que contiene todos los secretos necesarios.

Imagina la estructura como los ingredientes de una buena receta:

Frontmatter YAML: Los metadatos, como la información nutricional - cuándo usar esta receta y para cuántas personas
Contenido Markdown: Las instrucciones paso a paso que Claude sigue con cuidado, como seguir la ricetta della nonna

my-skill/
├── SKILL.md           # La receta principal (requerido)
├── template.md        # Variaciones opcionales
├── examples/
│   └── sample.md      # Fotos del plato terminado
└── scripts/
    └── validate.sh    # Herramientas especiales de cocina

Ejemplo básico: Explain Code

Bella! Este skill enseña a Claude a explicar código como yo enseño a cocinar: con paciencia, amor y buenas comparaciones.

---
name: explain-code
description: Explains code with visual diagrams and analogies. Use when explaining how code works, teaching about a codebase, or when the user asks "how does this work?"
---

When explaining code, always include:

1. **Start with an analogy**: Compare the code to something from everyday life
2. **Draw a diagram**: Use ASCII art to show the flow, structure, or relationships
3. **Walk through the code**: Explain step-by-step what happens
4. **Highlight a gotcha**: What's a common mistake or misconception?

Keep explanations conversational.

Ahora, cuando preguntas "¿Cómo funciona este código?", Claude automáticamente:

Empieza con una analogía (como comparar una función con preparar ragù)
Dibuja un diagrama ASCII (el plano de la cocina)
Explica paso a paso (como los pasos de una receta)
Resalta errores comunes (como olvidar salar el agua de la pasta - che disastro!)

O puedes invocarlo directamente: /explain-code src/auth/login.ts

Skills vs Comandos vs Subagents

Claude Code tiene tres formas de extender funcionalidad, como tres tipos diferentes de ayudantes en la cocina. Déjame explicarte con cariño cuál usar:

Aspecto	Skills	Comandos	Subagents
Qué es	Archivo Markdown con instrucciones	Legacy: mismo que Skills pero en `.claude/commands/`	Agente aislado con prompt y contexto propios
Cuándo se carga	Solo cuando es relevante o lo invocas	Solo cuando lo invocas	Se crea bajo demanda
Contexto	Acceso a conversación actual	Acceso a conversación actual	Contexto aislado (sin historial)
Archivos de apoyo	✅ Soporta múltiples archivos	❌ Solo un archivo	✅ Puede precargar skills
Uso típico	Workflows, guías, procedimientos	Legacy (usar Skills en su lugar)	Tareas aisladas (research, planning)
Invocación	`/skill-name` o automático	`/comando`	`Task` tool o `context: fork` en skill

La receta simple:

Skills: Cuando quieres enseñar cómo hacer algo (como transmitir una receta)
Subagents: Cuando quieres delegar una tarea completa a alguien en otra cocina
Comandos: Non usare - están en desuso, como técnicas antiguas que ya no usamos

Skills vs MCP: La Despensa y las Recetas

Ah, questa è la domanda importante! En nuestro post sobre MCP, vimos cómo MCP conecta a sistemas externos. Ahora déjame explicarte cómo se complementan, como la pasta y el sugo.

La diferencia conceptual

Imagina que estás preparando una gran cena:

MCP conecta Claude CON los ingredientes (la despensa, el refrigerador, las herramientas de cocina) Skills enseñan a Claude CÓMO cocinar (las recetas, las técnicas, los secretos de familia)

Como dice Simon Willison, con la sabiduría de un maestro pastelero:

"Si Claude Skills son sobre enseñar a la IA cómo hacer algo, MCP es sobre darle acceso a lo que necesita para hacerlo."

Es como la diferencia entre tener acceso a la despensa (MCP) y saber preparar la receta perfecta de lasagna della nonna (Skills).

Ejemplo práctico: GitHub

Con MCP (los ingredientes y herramientas):

// MCP Server para GitHub - como abrir la despensa
server.tool({
  name: 'create_issue',
  description: 'Create a GitHub issue',
  inputSchema: { /* ... */ },
  async handler({ title, body, labels }) {
    return await github.issues.create({ title, body, labels });
  }
});

Con Skill (la receta familiar):

---
name: bug-report
description: Create a detailed bug report following team standards
---

When creating a bug report:

1. **Title format**: `[BUG] Component: Short description`
2. **Required sections**:
   - Steps to reproduce
   - Expected vs actual behavior
   - Environment (OS, browser, version)
   - Screenshots (if UI bug)
3. **Labels**: Always add `bug` + severity (`P0`, `P1`, `P2`)
4. **Mention**: Tag @team-backend if server-side, @team-frontend if client-side

Use the GitHub MCP to create the issue with this format.

La magia (ah, che bella!): El Skill usa MCP para acceder a los ingredientes (GitHub), pero agrega el conocimiento artesanal de cómo tu equipo prepara cada plato. Es como tener acceso a los tomates más frescos (MCP) y saber exactamente cómo convertirlos en la salsa perfecta (Skill).

Comparación arquitectónica

Aspecto	Skills	MCP
Propósito	Conocimiento procedimental (las recetas)	Conectividad a sistemas (la despensa)
Alcance	Instrucciones, workflows	Herramientas, datos, APIs
Complejidad	Markdown + YAML (simple como escribir una receta)	Protocolo cliente-servidor (como instalar una cocina industrial)
Tokens	Eficiente (solo carga relevantes)	Costoso (GitHub MCP: ~50K tokens)
Creación	Si sabes Markdown, puedes crear (como escribir una recetta)	Requiere protocolo completo (como ser ingeniero)
Ejemplo	"Cómo hacer code reviews"	"Acceso a base de datos Postgres"

Cuándo usar cada uno

Usa Skills cuando:

Necesitas explicar cómo se hace algo en tu equipo (como transmitir una técnica)
Quieres embeber mejores prácticas (los secretos de la nonna)
Defines workflows o procedimientos (la receta paso a paso)
El conocimiento es mayormente textual/instruccional (las instrucciones escritas)

Usa MCP cuando:

Necesitas conectar a un sistema externo (abrir la despensa)
Requieres acceso a datos en tiempo real (ingredientes frescos del mercado)
Integras con APIs o servicios (proveedores especializados)
Necesitas ejecutar acciones en sistemas externos (usar el horno profesional)

Úsalos juntos (la combinazione perfetta):

---
name: deploy
description: Deploy to production following safety checklist
---

Before deploying:

1. Run test suite: `npm test`
2. Check deployment status via Vercel MCP
3. Verify staging environment via monitoring MCP
4. Execute deploy via Vercel MCP
5. Monitor metrics for 5 minutes via Datadog MCP

If any metric spikes >10%, rollback immediately.

Este skill orquesta varios MCPs con el procedimiento correcto, como un chef que coordina múltiples estaciones en la cocina siguiendo el servicio perfecto.

El poder de los Skills: Casos de uso

1. Code reviews consistentes

Como revisar que cada plato salga perfecto de la cocina:

---
name: review-pr
description: Review a pull request following code quality standards
context: fork
agent: Explore
---

Review this PR for:

1. **Code quality**:
   - No console.logs in production code
   - Proper error handling (no silent failures)
   - TypeScript strict mode compliance

2. **Testing**:
   - New features have tests
   - Edge cases covered
   - No skipped tests without TODO comment

3. **Documentation**:
   - Public APIs have JSDoc
   - README updated if new feature
   - CHANGELOG.md entry added

4. **Performance**:
   - No unnecessary re-renders (React)
   - Database queries optimized
   - Images compressed

Provide specific file:line references for issues.

2. Generación de visualizaciones

Como crear un menú visual hermoso para tus comensales:

---
name: codebase-visualizer
description: Generate interactive tree view of project structure
allowed-tools: Bash(python *)
---

Generate interactive HTML visualization:

```bash
python ~/.claude/skills/codebase-visualizer/scripts/visualize.py .

This creates codebase-map.html with:

Collapsible directory tree
File sizes and types
Color-coded by extension


El script Python genera un HTML autocontenido con:
- Resumen de estadísticas (archivos, tamaños, tipos)
- Gráfico de barras por tipo de archivo
- Árbol interactivo expandible/colapsable

*Bellissimo!* Como presentar los ingredientes organizados y listos para cocinar.

### 3. Context injection dinámico

Como preparar el mise en place antes de cocinar:

```yaml
---
name: pr-summary
description: Summarize changes in current pull request
context: fork
agent: Explore
---

## Pull request context
- PR diff: !`gh pr diff`
- PR comments: !`gh pr view --comments`
- Changed files: !`gh pr diff --name-only`

## Your task
Summarize this PR:
1. What changed (high-level)
2. Why (infer from commit messages)
3. Potential risks
4. Suggested review focus areas

El syntax !`command` ejecuta el comando antes de enviar el prompt a Claude. Claude recibe el resultado real, como tener todos los ingredientes preparados y medidos antes de empezar a cocinar.

4. Workflows con subagents

Como enviar a un ayudante a investigar los mejores ingredientes:

---
name: deep-research
description: Research a topic thoroughly across the codebase
context: fork
agent: Explore
---

Research $ARGUMENTS thoroughly:

1. Find relevant files using Glob and Grep
2. Read and analyze the code
3. Summarize findings with specific file:line references
4. Identify patterns and conventions

Con context: fork, el skill se ejecuta en un subagente aislado - como tener un sous chef investigando en otra parte de la cocina mientras tú continúas preparando el plato principal. Perfetto!

Arquitectura de Skills: Los Niveles de Organización

Como organizar las recetas de familia en diferentes niveles:

Niveles de scope

Ubicación	Path	Aplica a
Enterprise	Configuración admin	Toda la organización (el restaurante completo)
Personal	`~/.claude/skills/<name>/SKILL.md`	Todos tus proyectos (tu libro de recetas personal)
Proyecto	`.claude/skills/<name>/SKILL.md`	Solo este proyecto (recetas para esta cena específica)
Plugin	`<plugin>/skills/<name>/SKILL.md`	Donde está instalado el plugin (recetas del chef invitado)

Prioridad: Enterprise > Personal > Proyecto

Como en la cocina, las reglas de la casa (Enterprise) tienen prioridad sobre las preferencias personales.

Control de invocación

Por defecto, tanto tú como Claude pueden invocar un skill, como tener una receta disponible para todos en la cocina:

Tú: /skill-name
Claude: Automáticamente cuando es relevante (como un chef experto que sabe cuándo usar cada técnica)

Dos campos controlan esto con cuidado:

disable-model-invocation: true: Solo tú puedes invocarlo (recetas delicadas que solo el chef principal ejecuta)

---
name: deploy
description: Deploy to production
disable-model-invocation: true  # Solo manual, no automático
---

user-invocable: false: Solo Claude puede invocarlo (conocimiento de base que Claude usa automáticamente)

---
name: legacy-system-context
description: Background knowledge about legacy monolith
user-invocable: false  # Conocimiento, no acción
---

Restricción de herramientas

Como delimitar qué utensilios puede usar un ayudante:

---
name: safe-reader
description: Read files without modifying anything
allowed-tools: Read, Grep, Glob  # Solo lectura
---

Cuando este skill está activo, Claude solo puede usar Read, Grep y Glob - como un ayudante que solo puede leer las recetas pero no modificarlas. Seguridad con amor.

Mejores prácticas: La Sabiduría de la Nonna

✅ Hacer (con amore)

Descripciones claras: Como etiquetar cada frasco en la despensa - Claude las usa para decidir cuándo cargar el skill
```
description: "Explains code with diagrams. Use when user asks 'how does this work?'"
```
Mantener SKILL.md enfocado: < 500 líneas. Como una receta que cabe en una página - usa archivos de apoyo para detalles adicionales
```
For complete API reference, see [api-reference.md](api-reference.md)
```

Ejemplos concretos: Como mostrar la foto del plato terminado

See examples/good-commit-message.md for format examples

Argumentos descriptivos: Como indicar "2 cucharadas" en lugar de solo "un poco"
```
argument-hint: [issue-number]
```

❌ Evitar (questi errori, no!)

Skills demasiado genéricos: "Ayuda con desarrollo" → Como decir "comida" sin especificar qué plato
Instrucciones ambiguas: "Hacer lo mejor posible" → Como decir "cocinar hasta que esté listo" sin temperatura ni tiempo
Cargar todo en memoria: Como traer toda la despensa a la mesa - usa archivos de apoyo para referencias extensas
Skills sin descripción: Como recetas sin título - Claude no sabrá cuándo usarlos

Skills vs Projects de Claude.ai

Si usas Claude.ai (la web app), conoces Projects: contexto compartido con instrucciones personalizadas y documentos. Déjame explicarte la diferencia con una metáfora culinaria:

Diferencia clave:

Projects (claude.ai): Como tener todos los ingredientes siempre en la mesa - contexto permanente que nunca se guarda
Skills (Claude Code): Como un recetario organizado - solo sacas la receta que necesitas en cada momento

Skills son más eficientes en tokens porque solo se cargan cuando son relevantes, como solo sacar de la despensa los ingredientes que necesitas para el plato actual. Projects mantienen todo el contexto cargado siempre, como tener toda la despensa abierta permanentemente.

¿Se complementan? Certo che sì! Usa Projects para contexto de alto nivel sobre un proyecto largo (el menú completo de la semana), y Skills para workflows específicos del día a día (la receta del plato de hoy).

Conclusión: El Ecosistema Completo

Ahora tienes todas las herramientas, tesoro. Las piezas del puzzle, como los ingredientes perfectamente organizados:

MCP (ver post): Conecta Claude a sistemas externos - la despensa bien surtida
Skills: Enseña a Claude cómo usar esos sistemas - las recetas de la nonna
Subagents: Delega tareas completas - los ayudantes trabajando en otras estaciones
Hooks: Automatiza workflows - los temporizadores y recordatorios de la cocina

En la práctica (la recetta completa):

---
name: release
description: Create a new release following our process
hooks:
  post-commit: !`npm run build`
---

Create release for $ARGUMENTS:

1. Update CHANGELOG.md (read via filesystem)
2. Bump version in package.json
3. Run tests via Jest MCP
4. Build production via build hook (post-commit)
5. Create GitHub release via GitHub MCP
6. Deploy to Vercel via Vercel MCP
7. Notify team via Slack MCP

Monitor deployment metrics for 10 minutes.

Este skill orquesta múltiples MCPs, usa hooks para builds automáticos, y podría ejecutarse en un subagent para aislamiento - como dirigir una cocina completa con múltiples estaciones, cada una siguiendo su receta perfectamente coordinada.

El poder real: No estás solo usando IA. Estás enseñándole tu forma de trabajar, transmitiendo tu conocimiento como la nonna transmite sus recetas a las nuevas generaciones. Con paciencia, amor y dedicación.

Che bello! Estás creando un legado de conocimiento, una tradición que perdurará.

Referencias

Documentación oficial:

Comparaciones técnicas:

Posts relacionados:

MCP: De Function Calling a un Estándar Universal - Nuestro post sobre Model Context Protocol

¿Ya estás usando Skills? ¿Qué receta familiar creaste para tu equipo? Me encantaría conocer los flujos de trabajo y secretos que has creado para tus propios proyectos, cara.

Juli Pompilli Código con amor y dedicación 🍝