Claude Code skills y plugins: un mismo set en cada repo

Las skills de Claude Code son archivos SKILL.md con instrucciones que el agente carga cuando una tarea las necesita. Un plugin empaqueta skills, agentes y hooks como una unidad que se instala en muchos repositorios. Las nuestras van en un solo plugin, wizrd (nuestro plugin y CLI internos para Claude Code, no son públicos), activado en la configuración versionada de cada repositorio, y un validador en la CI hace fallar el repositorio cuando una skill está rota.

Esa configuración nació de un desorden: copias de las mismas skills en varios repositorios, cada una un poco distinta. A continuación explicamos cómo funcionan las skills y los plugins, cómo cargamos un plugin en todas partes y qué se rompió por el camino.

¿Qué son las skills y los plugins de Claude Code?

Una skill es una carpeta con un archivo, SKILL.md. Arriba va el frontmatter con name y description, debajo las instrucciones. La documentación de Claude Code lo dice claramente: las descripciones de las skills se cargan en el contexto para que Claude sepa qué hay disponible, y el contenido completo de la skill solo se carga cuando se usa. También puede ejecutar una skill usted mismo como /name.

Un plugin es un directorio de skills, agentes, hooks o servidores MCP que Claude Code instala y carga como una unidad. Su manifiesto está en .claude-plugin/plugin.json. Las skills de un plugin reciben un espacio de nombres, así que nuestra skill de revisión se ejecuta como /wizrd:review y nunca choca con un /review propio del proyecto.

Dónde va cada pieza:

La última columna es la que más importa. Una skill le dice al agente cómo hacer bien una tarea. No obliga a nada. Lo que tiene que cumplirse va en un hook, una regla de lint o la CI.

¿Por qué metimos todas nuestras skills en un solo plugin?

Nuestro repositorio de empresa contiene todos los repositorios de clientes y de servicios como submódulos. Una sesión iniciada dentro de un repositorio de cliente no veía las skills de la empresa, porque Claude Code busca las skills del proyecto solo hasta la raíz del repositorio en el que está.

Así que las skills se copiaban. Varios repositorios de clientes tenían sus propias versiones de plan, execute y review. Cuando las comparamos, cada copia se había separado de las demás. Nadie lo decidió. Simplemente pasó, un pequeño arreglo cada vez, en un repositorio y no en el siguiente.

La solución no fue más disciplina. Fue un plugin que se carga en todas partes. Desde entonces, una sesión en el repositorio de la empresa, en uno de cliente o en uno de servicio recibe las mismas skills, agentes y hooks. Un cambio llega en un PR, y las copias antiguas se borraron en PR complementarios.

¿Cómo se carga un plugin en cada repositorio?

Un plugin necesita un hogar, llamado marketplace. No es más que un archivo .claude-plugin/marketplace.json que enumera los plugins y de dónde descargar cada uno. El nuestro enumera un plugin, el propio repositorio:

{
  "name": "digitaliko",
  "plugins": [{ "name": "wizrd", "source": "./" }]
}

El repositorio que lo usa activa el plugin en su .claude/settings.json versionado. Por ejemplo, cuando el repo del plugin es un submódulo en plugins/wizrd:

{
  "enabledPlugins": { "wizrd@digitaliko": true },
  "extraKnownMarketplaces": {
    "digitaliko": { "source": { "source": "directory", "path": "plugins/wizrd" } }
  }
}

El orden que volveríamos a seguir:

Los hooks viajan igual. Nuestro plugin incluye un saludo en SessionStart y dos hooks PreToolUse sobre Bash: uno bloquea la atribución a la IA en commits y PR, otro bloquea los push que el operador no puede hacer. Sus rutas empiezan por ${CLAUDE_PLUGIN_ROOT}, así que se resuelven en cada repositorio. Por qué importa lo explicamos en Hooks de Claude Code que en silencio no hacen nada.

¿Qué necesita una skill para funcionar en un equipo?

Menos de lo que pensábamos al principio. Un frontmatter real de nuestro plugin, con la descripción acortada:

---
name: issue
description: Create GitHub issues at the right level following the canonical labels and issue-body spec. Triggers on /wizrd:issue, gh issue, file issue, create issue, log a task.
allowed-tools: Bash, Read
audience: both
---

Tres campos llevan el peso:

• description con palabras clave reales. El modelo decide por esta línea si carga la skill. "Ayuda con issues" se carga al azar. Las palabras que la gente escribe de verdad la cargan cuando toca.
• audience: human, agent o both. Es un campo nuestro, no de Claude Code. Una skill que un agente ejecuta solo nunca debe esperar a una persona. Nuestro validador avisa cuando una skill marcada como agent o both hace una pregunta emergente o espera una aprobación. Un agente pregunta en GitHub.
• Nombres claros. Dos de nuestras skills se diferenciaban en una letra y hacían cosas opuestas. Les cambiamos el nombre.

Durante un tiempo también exigimos secciones fijas en cada skill: un playbook, un control de calidad, autoridad de decisión. En su mayoría repetían el cuerpo. Quitamos el requisito y recortamos las skills a las instrucciones que cambian el comportamiento. Ahora el validador solo pide name, description y audience.

¿Qué se rompió por el camino?

Casi todo en silencio. Las cosas pasaban mientras ya no comprobaban nada.

• Un cambio de nombre que habría pasado la CI para siempre. Cuando el plugin nos dio un espacio de nombres, el prefijo antiguo de cada skill sobraba, así que lo quitamos. Nuestro control de referencias a skills borradas tenía ese prefijo fijo en su expresión regular. Si lo hubiéramos dejado, tras el cambio no habría encontrado nada y habría seguido en verde para siempre.
• El validador daba por obsoletas skills vivas. Construía su lista de skills a partir de una carpeta local. Tras el paso al plugin, un repositorio de cliente que mencionaba plan o review no tenía nada local con qué compararlo, y su CI se puso en rojo. La solución fue leer también las skills del propio plugin.
• Skills que nadie usaba. Algunas skills llevaban meses sin ejecutarse. Cada una seguía en el contexto en cada turno, porque los nombres y descripciones de las skills de un plugin se cargan siempre. Las borramos. Tres variantes de una skill pasaron a ser una skill con modos, y nuestra propia skill para escribir skills dejó paso al skill-creator integrado.

La mayoría de estos arreglos fueron borrados. Es el patrón que vemos una y otra vez: un plugin compartido hace visible lo que sobra, porque ahora todos lo cargan en cada sesión.

Personales o compartidas: ¿qué skills van en el plugin?

No todas las skills tienen que compartirse. La forma en que a una persona le gusta trabajar puede quedarse en su propio ~/.claude/skills/. Lo que todo el equipo necesita va en el plugin: la planificación, la revisión, abrir issues, los pasos por los que pasa una entrega a un cliente.

Nuestro plugin es interno, así que no lo puede instalar. Nuestro Claude Code production starter público no tiene skills. Contiene la capa que va debajo: reglas para el agente, hooks y un control en la CI. Por ahí empezaríamos.

¿Cuáles de estas cosas ya tiene su equipo?

Qué va en las reglas junto a las skills lo explicamos en CLAUDE.md y AGENTS.md: reglas para el código de IA en un equipo.

¿Quiere una configuración compartida para los agentes de su equipo?

Configuramos skills, hooks, reglas y CI directamente en los repositorios del equipo como parte de AI-native SDLC para equipos de desarrollo. ¿A su equipo le faltan más manos que reglas? Vea un desarrollador sénior para su equipo. La mayor parte de nuestro código la escribe la IA. Un sénior revisa cada cambio y responde de lo que corre en producción. Desde 2023 hemos entregado más de 15 proyectos en producción.

Le respondemos en un plazo de dos días laborables con algunas preguntas sobre su trabajo. Después acordamos qué hacemos primero.

Si prefiere hablar antes, reserve una llamada introductoria de 15 minutos.

¿Cuántas copias de la misma skill viven hoy en sus repositorios?

Preguntas frecuentes

¿Qué son las skills de Claude Code?

Una skill es una carpeta con un archivo SKILL.md: un frontmatter con nombre y descripción y, debajo, las instrucciones. Claude Code mantiene la descripción en el contexto y carga las instrucciones completas solo cuando una tarea las necesita o cuando usted ejecuta la skill como /nombre.

¿Qué diferencia hay entre una skill y un plugin?

Una skill es un conjunto de instrucciones. Un plugin es un directorio que empaqueta skills, agentes, hooks y servidores MCP como una unidad, con un manifiesto en .claude-plugin/plugin.json. Las skills de un plugin tienen espacio de nombres, así que las nuestras se ejecutan como /wizrd:review.

¿Cómo comparto las skills de Claude Code con mi equipo?

Póngalas en un plugin, publique el plugin en un marketplace y actívelo en el .claude/settings.json versionado de cada repositorio. Todos tienen la misma versión y un cambio llega a todas partes en un PR, en lugar de en copias que se van separando.

¿Muchas skills ralentizan Claude Code?

Cada skill que el modelo puede invocar por su cuenta mantiene su nombre y su descripción en el contexto en cada turno. Eso cuesta tokens aunque no se ejecute nada. Borramos las skills que nadie usa y mantenemos las descripciones cortas y concretas.

¿Debe una skill sustituir a los hooks o a los controles de CI?

No. Una skill son instrucciones que el agente puede seguir. Lo que tiene que cumplirse va en un hook, una regla de lint, un test o la CI, donde el agente no se lo puede saltar.