**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: 1. **Frontmatter YAML**: Los metadatos, como la información nutricional - cuándo usar esta receta y para cuántas personas 2. **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. ```yaml --- 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](/es/posts/mcp-model-context-protocol), 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): ```typescript // 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): ```yaml --- 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): ```yaml --- 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: ```yaml --- 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: ```yaml --- 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: ```yaml --- 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) ```yaml --- 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) ```yaml --- 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: ```yaml --- 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) 1. **Descripciones claras**: Como etiquetar cada frasco en la despensa - Claude las usa para decidir cuándo cargar el skill ```yaml description: "Explains code with diagrams. Use when user asks 'how does this work?'" ``` 2. **Mantener SKILL.md enfocado**: < 500 líneas. Como una receta que cabe en una página - usa archivos de apoyo para detalles adicionales ```markdown For complete API reference, see [api-reference.md](api-reference.md) ``` 3. **Ejemplos concretos**: Como mostrar la foto del plato terminado ```yaml See examples/good-commit-message.md for format examples ``` 4. **Argumentos descriptivos**: Como indicar "2 cucharadas" en lugar de solo "un poco" ```yaml argument-hint: [issue-number] ``` ### ❌ Evitar (questi errori, *no!*) 1. **Skills demasiado genéricos**: "Ayuda con desarrollo" → Como decir "comida" sin especificar qué plato 2. **Instrucciones ambiguas**: "Hacer lo mejor posible" → Como decir "cocinar hasta que esté listo" sin temperatura ni tiempo 3. **Cargar todo en memoria**: Como traer toda la despensa a la mesa - usa archivos de apoyo para referencias extensas 4. **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: 1. **MCP** ([ver post](/es/posts/mcp-model-context-protocol)): Conecta Claude a sistemas externos - la despensa bien surtida 2. **Skills**: Enseña a Claude *cómo* usar esos sistemas - las recetas de la nonna 3. **Subagents**: Delega tareas completas - los ayudantes trabajando en otras estaciones 4. **Hooks**: Automatiza workflows - los temporizadores y recordatorios de la cocina **En la práctica** (la recetta completa): ```yaml --- 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**: - [Claude Code Skills Documentation](https://code.claude.com/docs/en/skills) - [Agent Skills Open Standard](https://agentskills.io) **Comparaciones técnicas**: - [Claude Skills vs MCP - Simon Willison](https://simonwillison.net/2025/Oct/16/claude-skills/) - [Skills vs MCP - Armin Ronacher](https://lucumr.pocoo.org/2025/12/13/skills-vs-mcp/) - [Skills Explained - Claude Blog](https://claude.com/blog/skills-explained) - [Skills vs Dynamic MCP Loadouts](https://lucumr.pocoo.org/2025/12/13/skills-vs-mcp/) **Posts relacionados**: - [MCP: De Function Calling a un Estándar Universal](/es/posts/mcp-model-context-protocol) - 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 🍝*

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