--- title: "Skills de Claude Code: cómo crearlas y cuándo usarlas" excerpt: "Una skill es un procedimiento que Claude Code carga solo cuando lo necesita. Ideal para checklists y flujos repetibles (revisar un PR, hacer un release) que no quieres tener siempre en el contexto. Cómo se crea un SKILL.md, con un ejemplo real de Laravel." date: "2026-07-20T16:00:00.000Z" category: "Inteligencia Artificial" tech_article: true author: name: "angel cruz" picture: "https://angelcruzdevcdn.nyc3.cdn.digitaloceanspaces.com/images/me/angel-cruz.png" ogImage: url: "/images/open-graph/og-image.png" seo_title: "Skills de Claude Code: crear un SKILL.md (tutorial)" seo_description: "Qué es una skill en Claude Code, cómo crear un SKILL.md, dónde vive y cómo se invoca. La diferencia con CLAUDE.md, hooks y subagentes, con un ejemplo de Laravel." --- **Una skill de Claude Code es un conjunto de instrucciones (un archivo `SKILL.md`) que Claude carga solo cuando hace falta.** A diferencia del [CLAUDE.md](/post/claude-md-buenas-practicas), que se carga entero en cada sesión, el cuerpo de una skill no cuesta contexto hasta que se usa. Es perfecta para checklists y procedimientos de varios pasos que ejecutas de vez en cuando. ## Cuándo crear una skill Crea una skill cuando te descubres pegando las mismas instrucciones una y otra vez, o cuando una sección de tu CLAUDE.md dejó de ser un "dato" y se convirtió en un **procedimiento**: revisar un PR, hacer un release, correr una migración con sus comprobaciones. Eso no debería vivir siempre en el contexto (lo gastaría en cada sesión sin usarse casi nunca): debería cargarse solo cuando lo invocas. La regla mental: si es algo que Claude **debe saber siempre**, va en el CLAUDE.md. Si es algo que Claude **debe hacer a veces**, es una skill. ## El formato: SKILL.md Una skill es una carpeta con un archivo `SKILL.md`: frontmatter YAML (con la `description` que le dice a Claude cuándo usarla) más el cuerpo en markdown con las instrucciones. **El nombre de la carpeta se convierte en el comando** que escribes. ```markdown --- description: Resume los cambios sin commitear y marca lo riesgoso. Úsala cuando el usuario pregunte qué cambió o pida un mensaje de commit. --- ## Cambios actuales !`git diff HEAD` ## Instrucciones Resume los cambios de arriba en dos o tres bullets y lista los riesgos que veas (falta de manejo de errores, valores hardcodeados, tests por actualizar). ``` La línea `` !`git diff HEAD` `` (con backticks) usa **inyección dinámica de contexto**: Claude Code corre el comando y reemplaza la línea por su salida antes de que Claude lea la skill, así las instrucciones llegan con el diff ya incrustado. Y con `$ARGUMENTS` capturas lo que el usuario escriba después del nombre de la skill. ## Un ejemplo real: revisar un PR de Laravel Aquí es donde una skill brilla, porque el procedimiento es siempre el mismo y quieres que se ejecute igual cada vez. Una skill `revisar-pr` para un proyecto Laravel: ```markdown --- description: Revisa el PR actual en un proyecto Laravel. Úsala antes de aprobar o mergear. --- ## Estado !`git diff main...HEAD --stat` ## Instrucciones 1. Corre `./vendor/bin/pint --test` y reporta si el estilo falla. 2. Corre `php artisan test` y resume los tests rojos. 3. Revisa las migraciones nuevas: ¿son reversibles (`down()`)? ¿tocan tablas grandes sin cuidado? 4. Marca cualquier `env()` fuera de un archivo de config, credenciales hardcodeadas o queries en bucle (N+1). 5. Cierra con un veredicto: listo para mergear, o lista de cambios pendientes. ``` Ese procedimiento, con las comprobaciones propias de Laravel, no tiene por qué ocupar contexto en cada sesión. Vive en una skill y se activa cuando lo pides. ## Dónde viven y cómo se invocan | Ubicación | Ruta | Alcance | |---|---|---| | Personal | `~/.claude/skills//SKILL.md` | Todos tus proyectos | | Proyecto | `.claude/skills//SKILL.md` | Solo ese proyecto (se versiona con el repo) | | Plugin | `/skills//SKILL.md` | Donde el plugin esté activo | Se invocan de dos formas: **automática** (Claude la carga cuando tu pedido encaja con la `description`, por eso esa línea importa tanto) o **explícita** escribiendo `/nombre-de-la-skill`. Dato útil: los comandos personalizados se fusionaron con las skills, así que un `.claude/commands/deploy.md` y una skill `.claude/skills/deploy/SKILL.md` crean ambos el comando `/deploy` y funcionan igual; tus archivos de `.claude/commands/` siguen sirviendo. ## Skill, CLAUDE.md, hook o subagente Cuatro herramientas parecidas que conviene no confundir: - **[CLAUDE.md](/post/claude-md-buenas-practicas):** datos y reglas que quieres en cada sesión. - **Skill:** un procedimiento que se carga bajo demanda. - **[Hook](/post/hooks-claude-code):** un comando determinista que se dispara en un evento fijo (siempre, sin que el modelo decida). - **[Subagente](/post/subagentes-claude-code):** una tarea que corre en un contexto aislado. Mover procedimientos del CLAUDE.md a skills es, además, una de las mejores formas de [reducir tokens](/post/optimizar-claude-code-reducir-tokens): mantienes el contexto base pequeño y cargas el detalle solo cuando se usa. ## Preguntas frecuentes ### ¿Qué es una skill en Claude Code? Un archivo `SKILL.md` con instrucciones que Claude carga solo cuando son relevantes o cuando la invocas con `/nombre`. Sirve para empaquetar procedimientos repetibles. ### ¿En qué se diferencia del CLAUDE.md? El CLAUDE.md se carga completo en cada sesión (gasta contexto siempre); la skill se carga bajo demanda (no cuesta contexto hasta que se usa). Regla: dato siempre necesario, CLAUDE.md; procedimiento ocasional, skill. ### ¿Dónde se guardan las skills? En `~/.claude/skills//SKILL.md` (personales) o `.claude/skills//SKILL.md` (del proyecto), además de las que traen los plugins. ### ¿Cómo invoco una skill? Automáticamente, cuando tu pedido coincide con su `description`, o a mano escribiendo `/nombre-de-la-skill`. ### ¿Puedo pasarle datos o argumentos a una skill? Sí. Con `` !`comando` `` inyectas la salida de un comando (por ejemplo un `git diff`) y con `$ARGUMENTS` capturas el texto que escribas después del nombre de la skill. --- ## Sitemap Índice completo del sitio: [/sitemap.md](https://www.angelcruz.dev/sitemap.md) Canónico HTML: [https://www.angelcruz.dev/post/skills-claude-code](https://www.angelcruz.dev/post/skills-claude-code)