Software Crafters® 2026 | Creado con 🖤 para elevar el nivel de la conversación sobre programación en español | Legal
Durante un tiempo el enfoque para guiar a los agentes de IA dependía de la herramienta que usaras.
En Cursor tenías reglas. Ficheros .mdc dentro de .cursor/rules/ con dos sabores: las que se cargaban siempre y las que el agente activaba según el contexto. Luego llegaron los comandos. Ficheros .mdc dentro de .cursor/commands/ que se invocaban con @nombre. Reglas por un lado, comandos por otro. Dos conceptos diferentes, dos carpetas diferentes, dos formas de pensar diferentes.
Si querías usar otro agente, otro editor, otra herramienta... empezabas de cero. Las reglas de Cursor no valían para Codex. Los comandos de Cursor no valían para nada fuera de Cursor. Todo lo que habías construido quedaba atado a una sola herramienta.
Eso se ha acabado.
La industria ha convergido en un formato común llamado Skills. Lo propuso Anthropic, pero hoy lo implementan Claude Code, OpenCode, Codex de OpenAI, Antigravity... y desde hace poco, también Cursor. Un formato, múltiples herramientas. Si construyes tus skills bien, funcionan en todas partes sin tocar nada.
La idea detrás es simple pero poderosa: ya no hay "reglas" por un lado y "comandos" por otro. Ahora todo es una skill. Una unidad de conocimiento o comportamiento que el agente puede usar. Puede ser una instrucción de cómo escribir código, un flujo interactivo paso a paso, o un agente autónomo que ejecuta una tarea completa.
Bien.
Antes de entrar en los tipos, vamos a ver qué es una skill por dentro.
Una skill es una carpeta con un fichero SKILL.md dentro. Nada más. La carpeta vive en .claude/skills/ y el SKILL.md tiene dos partes: un frontmatter YAML con los metadatos y el cuerpo en markdown con las instrucciones.
--- name: action-tdd description: This skill should be used when implementing features using TDD. allowed-tools: Read, Write, Edit, Bash --- ## Proceso 1. Razona el caso de uso antes de escribir nada 2. Escribe el test en rojo 3. Implementa el mínimo para que pase 4. Verifica verde 5. Refactoriza si hace falta 6. Reevalúa si hay más casos
El name es el identificador. El description le dice al agente cuándo activarla: no es un campo decorativo, es lo que el agente lee para decidir si esa skill aplica a lo que estás haciendo. Y allowed-tools limita qué herramientas puede usar cuando la ejecuta. Si es una skill de TDD, puede leer, escribir y ejecutar tests. No necesita navegar por la web ni lanzar subagentes.
Opcionalmente, la carpeta puede tener subcarpetas: references/ para documentación de apoyo, templates/ para plantillas, scripts/ para utilidades que la skill necesite. El SKILL.md los referencia cuando los necesita. Pero lo único obligatorio es el SKILL.md.
La especificación oficial (agentskills.io) no define tipos. Define un conjunto de propiedades que puedes combinar como quieras. Pero en la práctica, trabajando en proyectos reales, he aterrizado cuatro tipos que cubren todos los casos. Los diferencio por prefijo.
guidelines/ — Conocimiento internoSon las reglas de arquitectura, naming, testing, frontend... El agente las carga automáticamente cuando detecta que son relevantes. Si estás trabajando en el frontend, carga las de frontend. Si estás en el dominio, las de arquitectura hexagonal. Tú no haces nada. El agente lo decide solo.
--- name: architecture-hexagonal description: Hexagonal architecture conventions. Auto-loaded when working with domain, application or infrastructure layers. --- # Arquitectura Hexagonal El dominio nunca depende de infraestructura. Los repositorios son interfaces en dominio, las implementaciones en infraestructura. Los use cases orquestan, no implementan.
Fíjate que no tienen allowed-tools porque no ejecutan nada. Son conocimiento puro.
La diferencia con el CLAUDE.md es importante. El CLAUDE.md se carga siempre, en todas las sesiones, sin excepción. Las guidelines se cargan solo cuando el agente detecta que aplican. Esto importa porque no quieres saturar el contexto del agente con reglas que no vienen al caso. Si estás escribiendo CSS, no necesitas las reglas de arquitectura hexagonal del backend.
En la práctica, van dentro de una subcarpeta guidelines/ precisamente para que no aparezcan como comandos invocables con /. Son conocimiento interno, no workflows. El agente sabe que están ahí porque las referencias en el CLAUDE.md.
action- — Prácticas guiadasSon workflows que el agente sigue paso a paso. Lo que antes eran "comandos" en Cursor, pero más potentes. Tanto tú como el agente pueden activarlos.
Escribes /action-tdd y el agente entra en el ciclo completo de TDD sin que tengas que recordarle cada paso. O el agente detecta que estás implementando una feature y activa la skill solo, sin que tú se lo pidas.
--- name: action-tdd description: What the skill does in one sentence. Triggers: "implement", "add feature", "create use case". allowed-tools: Read, Write, Edit, Bash, Glob, Grep ---
Fíjate en el campo description. La convención es: frase principal en quince palabras o menos, luego Triggers: con las frases que el agente usará para decidir si la activa solo. Sin ese campo bien escrito, el agente no sabe cuándo invocarla.
command- — Solo invocables por usuarioEstos solo se activan cuando tú los llamas. El agente no puede activarlos por su cuenta, por mucho que le parezca buena idea.
--- name: command-deploy description: Deploy to staging or production allowed-tools: Read, Bash disable-model-invocation: true ---
El disable-model-invocation: true es lo que hace la diferencia. Sin ese flag, el agente podría decidir hacer un deploy porque "parece el momento adecuado". No quieres eso. Son para operaciones con consecuencias externas que quieres controlar tú: publicar un artículo, enviar un email, hacer un deploy, modificar infraestructura.
task- — Agentes autónomosLas tasks lanzan un subagente con su propio contexto aislado. No es el mismo agente que está trabajando contigo: es otra instancia con su propio system prompt, su propio contexto limpio. Hace su trabajo y te devuelve un resumen. No contamina tu conversación.
--- name: task-code-review description: Review code quality after changes. Triggers: "review code", "check quality". context: fork agent: code-reviewer allowed-tools: Read, Glob, Grep, Task ---
El context: fork es lo que le dice al agente que esto va en un contexto aislado. Y agent: apunta al fichero en .claude/agents/ que define qué es ese subagente, qué herramientas tiene, qué modelo usa.
La tabla resumen:
| Tipo | Prefijo | Quién activa | disable-model-invocation |
|---|---|---|---|
| Guidelines | guidelines/ | Claude automáticamente | no aplica |
| Action | action- | Usuario o Claude | false |
| Command | command- | Solo usuario con / | true |
| Task | task- | Claude o usuario | false |
Esto es lo que tiene sentido en un proyecto real:
.claude/skills/ ├── guidelines/ ← No aparecen en / │ ├── architecture-hexagonal/ │ ├── design-principles/ │ ├── testing-standards/ │ ├── frontend-patterns/ │ └── git-strategy/ ├── action-tdd/ ← /action-tdd ├── action-plan/ ← /action-plan ├── task-code-review/ ← /task-code-review ├── task-architecture-review/ ← /task-architecture-review └── command-deploy/ ← /command-deploy
Las guidelines van en su subcarpeta. El agente sabe que existen porque las referencias en el CLAUDE.md del proyecto. Sin esa referencia, el agente tiene que explorar las carpetas para descubrir qué tiene disponible. Con ella, ya sabe de entrada qué herramientas tiene y cuándo usar cada una.
Cuando abres Claude Code y escribes /, solo ves los comandos que realmente vas a usar. Nada mezclado.
Hay un problema que aparece cuando llevas un tiempo construyendo skills: empiezas a olvidar las convenciones. ¿Qué campos lleva el frontmatter de una task? ¿Cómo se escribía el description para que el agente lo active bien? ¿Va context: fork o context: "fork"?
Para esto he creado una es una skill que crea skills.
Se invoca con /action-meta-skill y funciona en dos modos: create y review.
El SKILL.md de la meta-skill es sencillo. No tiene la lógica dentro: la delega a subcarpetas.
--- name: action-meta-skill description: Create, review, or improve skills following agentskills.io conventions. Triggers: "create a skill", "new skill", "review skill", "crear skill". argument-hint: "[create | review]" allowed-tools: Read, Glob, Grep, Write, Edit, Bash, Task, AskUserQuestion --- # Manage Skills Create new skills or review and improve existing ones. For type conventions, frontmatter templates, and naming rules, see `references/templates.md`.
Y así quedan sus subcarpetas:
action-meta-skill/ ├── SKILL.md ← Flujo principal (create / review) ├── references/ │ ├── templates.md ← Plantillas de frontmatter por tipo │ └── review-checklist.md ← Checklist de validación manual └── scripts/ ├── scaffold-skill.ts ← Genera la estructura de carpetas └── validate-skill.ts ← Valida una skill automáticamente
Esto es lo que la especificación llama progressive disclosure: el SKILL.md tiene el flujo principal y se mantiene ligero. Los detalles pesados —plantillas, checklists, scripts— van en carpetas de apoyo. El agente los lee cuando los necesita, no todo de golpe.
El modo create funciona así: te pregunta qué tipo de skill quieres, el nombre, la descripción, qué herramientas necesita, si acepta argumentos. Con eso, ejecuta scaffold-skill.ts que genera la carpeta con el SKILL.md ya relleno con el frontmatter correcto según el tipo.
El modo review ejecuta validate-skill.ts sobre una skill existente. Comprueba que el frontmatter sea válido, que el name siga la convención de nomenclatura, que la description tenga trigger phrases, que el SKILL.md no supere las quinientas líneas. Cosas que de otro modo tendrías que revisar a mano.
El resultado es que crear una skill nueva pasa de ser "recuerdo el formato, lo consulto en la documentación, lo escribo a mano" a ser una conversación con el agente de dos minutos que termina con los ficheros ya creados.
Es el tipo de herramienta que parece un capricho hasta que la usas. Después no entiendes cómo creabas skills a mano.
El verdadero valor de las Skills no es el formato en sí. Es que es el mismo formato para todas las herramientas.
Lo que construyes hoy con Claude Code te funciona mañana en OpenCode o en Codex. No tienes que migrar nada. No tienes que volver a aprender nada. El conocimiento que le das al agente —la arquitectura que sigues, el ciclo de TDD que practicas, los workflows que automatizas— viaja contigo independientemente de la herramienta.
Eso, a largo plazo, vale mucho más que cualquier feature de cualquier IDE.
¿Quiéres leer más artículos como éste? Pues suscríbete a la newsletter