Skills y Plugins de Claude: Un Análisis Técnico de Contenido vs. Contenedor

Los términos “skill de Claude” y “plugin de Claude” a menudo se usan indistintamente, creando confusión para los desarrolladores que intentan extender Claude Code. La realidad es que no son lo mismo. Entender la distinción no es solo algo académico; es fundamental para construir, instalar y depurar comportamientos personalizados de manera efectiva.

En SkillProof, trabajamos con estas mecánicas a diario. No solo leemos la documentación; instalamos y ejecutamos skills en trabajo real, tanto desde carpetas sin procesar como desde paquetes de plugins. De los 1877 skills que hemos probado hasta la fecha, solo 1159 (62%) pasaron nuestra evaluación. Otros 624 necesitaron configuración, un skill complementario o una integración antes de funcionar, y 94 obtuvieron una puntuación por debajo de la línea de base sin skill, ya sea porque no se pudieron ejecutar en absoluto o porque se ejecutaron y te dejaron en una situación peor que no instalar nada. Esta experiencia nos da una perspectiva clara y basada en la realidad sobre la diferencia entre un skill y un plugin de Claude, y cuál deberías usar.

La forma más sencilla de verlo es esta: un skill es el contenido (el conjunto de instrucciones que enseña a Claude un nuevo comportamiento). Un plugin es un contenedor (un paquete de distribución que puede agrupar uno o más skills, junto con otros tipos de extensiones).

Este artículo separa los dos conceptos, utilizando las rutas de archivo y los comandos exactos que usamos en nuestras pruebas diarias. Cubriremos qué es un skill, qué es un plugin, cómo se instalan y cuándo construir uno en lugar del otro.

¿Qué es un Skill de Claude Code? La Unidad Atómica de Comportamiento

Un skill de Claude es el bloque de construcción más fundamental. Es, literalmente, una carpeta que contiene un archivo llamado SKILL.md. Eso es todo. El nombre de la carpeta se convierte en el identificador del skill.

El archivo SKILL.md tiene una estructura simple de dos partes:

1. Frontmatter YAML: Un bloque en la parte superior del archivo, encerrado por ---, que define los metadatos del skill. El campo que importa es description. name es opcional y por defecto toma el nombre del directorio, y hay una docena de otros campos opcionales (allowed-tools, when_to_use, model, paths y similares) que la mayoría de los skills nunca usan.
2. Instrucciones en Markdown: Debajo del frontmatter, escribes markdown simple que explica la tarea a Claude. Este es tu prompt, tu conjunto de instrucciones sobre cómo realizar el comportamiento.

Es crucial destacar que el formato SKILL.md no incluye sintaxis compleja para definir funciones de herramientas, esquemas de API o tipos de parámetros. No hay un bloque obligatorio para ejemplos de tipo few-shot. Todo el sistema se basa en el lenguaje natural.

El campo más importante en el frontmatter es description. No es solo para lectores humanos; es el activador principal del skill. Cuando le das una tarea a Claude, este escanea los campos description de todos los skills instalados para encontrar una coincidencia. Si la descripción de tu tarea coincide con la description de un skill, Claude carga las instrucciones en markdown de ese skill en su contexto para guiar su respuesta. Si lo omites, Claude recurre al primer párrafo del cuerpo, que rara vez está escrito para funcionar como un activador.

Este es un punto de fallo frecuente que documentamos en nuestras pruebas. Hemos visto muchos skills con instrucciones brillantes en el cuerpo del markdown que Claude nunca usa porque la description en el frontmatter era demasiado vaga, demasiado específica o simplemente no existía. Un skill con una descripción como "Aids in development" casi nunca se activará. Para un análisis más profundo sobre qué hace que un skill sea bueno, consulta nuestra guía sobre qué son los skills de Claude.

Cómo Instalar un Skill sin Procesar

Si un skill es solo una carpeta, instalarlo es tan simple como copiar esa carpeta al lugar correcto. Claude Code busca skills en dos ubicaciones:

1. Global: ~/.claude/skills/
2. Específica del proyecto: <your-project-directory>/.claude/skills/

Los skills en el directorio global están disponibles en cualquier proyecto que abras con Claude Code. Los skills en un directorio específico del proyecto solo se cargan cuando estás trabajando dentro de ese proyecto. Esto es útil para tareas específicas de una única base de código.

Para instalar un skill que has descargado de un repositorio de Git, el proceso es una operación directa de archivos. Por ejemplo, después de clonar un repositorio que contiene un skill, ejecutarías:

# Example: Installing a skill into the global directory
cp -r path/to/cloned-repo/the-skill-folder ~/.claude/skills/

Claude Code monitorea esos directorios de skills, por lo que un skill que agregues, edites o elimines se detecta dentro de la sesión actual sin necesidad de reiniciar. La excepción es un directorio de skills que no existía cuando comenzó la sesión; si creas uno, sí necesitas reiniciar para que Claude Code comience a monitorearlo.

No hay una interfaz de línea de comandos especial para instalar un skill sin procesar, y no hay un flag --skill que apunte a Claude a un archivo SKILL.md para una única ejecución. Copiar la carpeta es la instalación.

Este enfoque directo y basado en archivos es cómo instalamos la mayoría de los skills listados en nuestro catálogo. Es simple, transparente y fácil de depurar. Puedes encontrar ejemplos de instalación más detallados en nuestra guía para instalar skills de Claude.

¿Qué es un Plugin de Claude? Un Paquete de Distribución

Si un skill es el contenido, un plugin es la caja de envío. Un plugin es un directorio autocontenido de componentes, que generalmente lleva un manifiesto .claude-plugin/plugin.json que contiene sus metadatos de identidad (nombre, descripción, versión, autor) y puede apuntar a dónde residen sus componentes.

Esta es la diferencia principal entre un skill y un plugin de Claude: un plugin está diseñado para ser un paquete. Aunque puede contener un solo skill, su verdadero poder reside en su capacidad para empaquetar múltiples extensiones relacionadas. Un plugin puede incluir:

• Skills: Una o más carpetas SKILL.md.
• Agents: Subagentes especializados a los que el agente principal de Claude puede delegar trabajo.
• Slash Commands: Comandos / personalizados que puedes ejecutar directamente en la interfaz de chat de Claude Code.
• Hooks: Scripts que se ejecutan automáticamente en ciertos puntos del ciclo de vida de la sesión.
• MCP Servers: Conexiones a un servidor de Model Context Protocol, para que un plugin pueda configurar una integración externa como parte de su instalación en lugar de dejar que lo configures manualmente. Para más información sobre esto, consulta nuestro análisis de skills vs. MCP.
• LSP Servers: Conexiones a un servidor de lenguaje que proporcionan a Claude errores de tipo y navegación de código.

Un plugin no es solo un envoltorio para un único skill. Es un kit de herramientas completo. Por ejemplo, un plugin para un framework de testing específico podría empaquetar un skill para escribir nuevas pruebas, un slash command para ejecutarlas y un hook para ejecutar pruebas antes de cada commit. El skill es solo una pieza del rompecabezas.

Cómo Funcionan los Plugins y los Marketplaces

Debido a que los plugins son paquetes más complejos, su proceso de instalación es diferente. No se copian manualmente las carpetas de los plugins. Se hace a través de marketplaces: un marketplace es un repositorio de Git que contiene un archivo .claude-plugin/marketplace.json que lista los plugins que ofrece.

Anthropic gestiona un marketplace oficial, claude-plugins-official, que Claude Code añade por ti automáticamente al inicio, además de un marketplace de la comunidad en anthropics/claude-plugins-community que añades tú mismo y cuyos plugins han pasado una validación automatizada y un control de seguridad. Pero el sistema no es cerrado: cualquiera puede publicar un marketplace poniendo un marketplace.json en un repositorio, y nada te impide añadirlo. La inclusión en el catálogo oficial queda a discreción de Anthropic; todo lo que está fuera de él tiene la calidad que el mantenedor haya decidido darle.

Para instalar un plugin, añades su marketplace y luego instalas el plugin por su nombre:

1. Añadir el marketplace:

   /plugin marketplace add anthropics/claude-code
   

2. Instalar el plugin:

   /plugin install commit-commands@claude-code-plugins
   

Luego, ejecuta /reload-plugins para activarlo en la sesión actual.

Sin embargo, la gestión de plugins no se limita a la interfaz interactiva. Existe un grupo de comandos de shell claude plugin (con el alias claude plugins) que cubre install, uninstall, enable, disable, update, list, details, init y validate: la forma documentada de instalar sin el paso interactivo, y lo que usas al crear scripts para la configuración de un equipo:

claude plugin install commit-commands@claude-code-plugins --scope project

También existen los flags --plugin-dir y --plugin-url para cargar un plugin solo para una sesión, que es la forma de probar algo antes de comprometerse a usarlo.

La distinción entre un marketplace y un directorio curado es importante aquí, y no es el mismo eje que skill versus plugin. Un marketplace es un canal de distribución: te dice que un plugin existe y lo instala. El filtrado, cuando ocurre, es automatizado. Nada de esto te dice si la herramienta funcionará en tu tarea.

Skills vs. Plugins de Claude Code: Una Comparación Directa

Para que la distinción quede perfectamente clara, aquí hay una comparación directa de los atributos clave:

Característica	Skill sin Procesar	Plugin
Definición	Una carpeta con un archivo SKILL.md que define un único comportamiento.	Un directorio autocontenido de componentes, que actúa como un paquete.
Archivo Principal	SKILL.md	.claude-plugin/plugin.json
Alcance	Un único conjunto de instrucciones para una tarea.	Un paquete de skills, agentes, comandos, hooks, servidores MCP y LSP.
Instalación	Copia manual: cp -r ... ~/.claude/skills/	/plugin install <name>@<market>, o claude plugin install
Distribución	Compartición directa de carpetas, repositorio de Git.	A través de un Marketplace (un repo de Git con un manifiesto).
Caso de Uso	Uso personal, herramientas de un solo propósito, prototipado rápido.	Distribución en equipo, kits de herramientas complejos, comportamientos de varias partes.

Cómo Prueba SkillProof Ambos

Nuestra metodología de pruebas es agnóstica al método de instalación. Ya sea que un skill llegue como una carpeta sin procesar o dentro de un paquete de plugin, nuestro proceso es el mismo. Lo instalamos y luego evaluamos el rendimiento de las instrucciones subyacentes de SKILL.md contra un conjunto estandarizado de tareas.

El método de distribución no cambia el comportamiento del skill. Un archivo SKILL.md mal escrito funcionará igual de mal tanto si lo copias manualmente como si lo instalas con /plugin install.

De hecho, un fallo recurrente que encontramos es un paquete que se instala perfectamente pero contiene un skill que nunca se activa. La instalación se completa sin errores, el skill aparece en la lista, y luego Claude nunca lo utiliza, porque la description en su SKILL.md es demasiado escasa para coincidir con algo que un usuario realmente escribiría. Nada en la instalación informa de esto. Solo lo descubres al darle a Claude la tarea que el skill debía manejar y ver cómo responde como si el skill no estuviera allí, que es exactamente la prueba que realizamos.

Esto es parte de por qué 624 de los 1877 skills que hemos probado reciben un veredicto de "Funciona con configuración" en lugar de ser aprobados: cumplen su función, pero no de forma inmediata, y el empaquetado tiende a ocultar la razón.

¿Debería Crear un Skill o un Plugin?

Esto nos lleva a la pregunta práctica: cuando tienes un nuevo comportamiento para Claude, ¿deberías crear un skill o un plugin?

La respuesta es directa: empieza siempre por crear un skill.

1. Crea tu archivo your-skill-name/SKILL.md. Concéntrate en escribir instrucciones claras y efectivas y una description precisa y fácil de activar. Pruébalo localmente copiándolo en ~/.claude/skills/.

2. Itera sobre el archivo SKILL.md hasta que funcione de manera fiable. Esto es el 99% del trabajo. El contenido de este archivo es lo que aporta el valor.

Solo después de tener un skill probado y funcional deberías considerar empaquetarlo como un plugin. La decisión de crear un plugin debe estar impulsada por las necesidades de distribución, no por la complejidad del skill en sí.

Empaqueta como un plugin si:

• Estás distribuyendo más de un componente. Por ejemplo, un skill para generar documentación de API y un slash command /generate-docs para activarlo en todo el proyecto.
• Necesitas distribuir un conjunto de skills a un equipo con un único y simple comando de instalación.
• Estás construyendo una extensión más avanzada que depende de hooks, subagentes u otras características exclusivas de los plugins.

Si tienes un único skill para tu uso personal, crear un plugin es una sobrecarga innecesaria. Una carpeta de skill sin procesar en ~/.claude/skills/ es más simple y directa.

Conclusión: Céntrate en el Skill, no en el Envoltorio

La conclusión principal es que el rendimiento proviene de la calidad del archivo SKILL.md, no de su empaquetado. Un plugin es un mecanismo de distribución, no una garantía de calidad. Como muestran nuestros datos, incluso los skills empaquetados de forma limpia fallan: 94 de los que hemos probado obtuvieron una puntuación inferior a la que Claude consigue sin ningún skill instalado.

La diferencia entre los skills y los plugins de Claude no es una cuestión de bueno vs. malo, sino de alcance y propósito. Uno es la instrucción; el otro es la caja en la que se envía.

Lecturas relacionadas: para profundizar en el lado del empaquetado (manifiestos, estructura de marketplace y qué revisar antes de añadir el repositorio de alguien), consulta nuestra guía de plugins de Claude Code. Para el lado del contenido, qué son los skills de Claude explica cómo funciona el formato antes de que escribas el primero.

Encontrar los 1159 skills que realmente pasan nuestras pruebas es la razón por la que creamos SkillProof. Si quieres saltarte el proceso de prueba y error, nuestro catálogo de skills de codificación probados es un buen punto de partida. Si prefieres instalar un conjunto que ya ha sido probado en conjunto, vendemos paquetes de diez basados en roles (Developer Toolkit, Writer Pack, Security & Code Review y otros cinco) por $10 cada uno en /bundles.