Ir al contenido
LUNES, NOVIEMBRE 16, 2026NOTICIAS TECNOLÓGICAS INDEPENDIENTES, Reseñas y guías prácticas
ACERCA DE
ÚLTIMAS NOTICIAS /

Agent Skills y servidores MCP explicados: cómo instalarlos, actualizarlos y arreglarlos en OpenCode, Claude Code, Codex y otros agentes de IA

LEE LA GUÍA
Agentes de IAGM / 997

Agent Skills y servidores MCP explicados: cómo instalarlos, actualizarlos y arreglarlos en OpenCode, Claude Code, Codex y otros agentes de IA

Agent Skills y servidores MCP, explicados fácil: instálalos, actualízalos y repáralos en OpenCode, Claude Code, Codex y más, con la CLI npx paso a paso.

Agent skills and MCP servers explained: a tech.grahammiranda.com title card with SKILL.md, npx skills, MCP servers and .agents/skills, and a terminal running npx skills check and opencode mcp add

Un agente de programación con IA recién salido de la caja es como un nuevo empleado brillante en su primera mañana. Sabe razonar, escribir código y ejecutar comandos, pero no sabe cómo trabaja tu equipo y no tiene llaves de tus sistemas. Habilidades de agente y servidores MCP cubren exactamente esas dos lagunas. Una habilidad es un manual escrito que el agente toma del estante cuando una tarea lo necesita. Un servidor MCP es un juego de llaves: un pequeño programa que permite al agente usar algo a lo que antes no podía llegar, como tus issues de GitHub, un navegador real o documentación actualizada.

Esta guía explica ambos conceptos en lenguaje sencillo y después te muestra cómo instalarlos, actualizarlos, eliminarlos y solucionar sus problemas en OpenCode, Claude Code, Codex, Gemini CLI, Cursor, GitHub Copilot y Hermes Agent. Casi todo funciona igual en todas partes, porque ambos son ya estándares abiertos. En el lado de las habilidades, una pequeña herramienta de línea de comandos lo une todo, npx skills, y la recorreré comando a comando.

No soy desarrollador de formación. Dirijo una pequeña empresa de TI en Alemania y construyo software con agentes de IA, así que aprendí casi todo esto de la forma en que probablemente lo harás tú: rompiendo cosas. La parte 6 está hecha a partir de mis propias sesiones de terminal en un Mac y una Raspberry Pi, incluida la vez en que la herramienta me dijo que todas mis habilidades estaban al día cuando no había conseguido comprobar ni una sola.

Todo lo que sigue se comprobó con la documentación oficial de cada agente y, para la competencias CLI, con el código fuente publicado de las versiones 1.5.18 a 1.8.1, el 15 de noviembre de 2026. Estas herramientas cambian cada semana: la CLI publicó dos versiones solo esta semana, y OpenCode llegó a la 2.3.0 el 13 de noviembre. Los números de versión y los comportamientos se señalan donde es probable que cambien. Compruébalos antes de fiarte de ellos.

Aviso: Ninguna empresa mencionada en este artículo lo patrocinó, lo revisó ni lo aprobó, y no contiene enlaces de afiliado. Los productos se nombran solo en el texto; las imágenes usan mis propios logos.


Resumen — Agent Skills y servidores MCP en diez puntos

  • Una skill es una carpeta con un archivo SKILL.md archivo: un nombre y una descripción arriba, las instrucciones debajo y, opcionalmente, scripts o archivos de referencia. Los agentes leen solo la descripción hasta que una tarea necesita la habilidad, así que una habilidad sin usar cuesta unos 100 tokens de la atención del agente.
  • Un servidor MCP le da al agente nuevas herramientas, como GitHub, un navegador o documentación en vivo. Las descripciones de las herramientas pueden viajar con cada petición, así que conecta solo los servidores que uses. Claude Code ahora las aplaza hasta que hacen falta, y OpenCode las agrupa por servidor.
  • La regla general: las normas de la casa para cada tarea van en AGENTS.md; el conocimiento necesario para algunas tareas se convierte en una habilidad; el acceso en vivo a un sistema necesita un servidor MCP; y si ya existe una buena herramienta de línea de comandos, una habilidad que le enseñe al agente esa herramienta suele ser más barata que un servidor.
  • Ambos son estándares abiertos bajo la Agentic AI Foundation de la Linux Foundation: MCP desde diciembre de 2025 y Agent Skills desde el 22 de octubre de 2026. Una habilidad escrita para un agente suele funcionar en los demás.
  • .agents/skills es la carpeta compartida. Codex, OpenCode, Cursor, Gemini CLI y GitHub Copilot leen todos .agents/skills en un proyecto y ~/.agents/skills en tu carpeta personal. Claude Code solo lee .claude/skills, y Hermes Agent lee ~/.hermes/skills además de las carpetas que añadas.
  • npx skills es el npm de las skills. La CLI de código abierto de Vercel (versión 1.8.1) instala skills en 79 agentes: npx skills add owner/repo, -g para todos los proyectos, -a opencode -a claude-code para elegir los agentes, npx skills ls para listarlas y npx skills remove para desinstalarlas.
  • Para ver si tus skills están al día, ejecuta npx skills@latest check. Desde la versión 1.7.5 (2 de noviembre de 2026) solo informa; npx skills update instala. En versiones anteriores, check ejecutaba la actualización en silencio.
  • Nunca te fíes de la marca verde por sí sola. Cuando el límite de GitHub de 60 solicitudes anónimas por hora bloqueó todas las comprobaciones en mi Mac, la CLI siguió mostrando “Todas las skills globales están al día”. Ejecuta gh auth login o define GITHUB_TOKEN, y lee las líneas con ✗.
  • Nunca uses sudo con skills ni con agentes, y no ejecutes la CLI desde tu carpeta personal. Root tiene su propia carpeta personal, así que sudo crea un segundo almacén de skills invisible; y desde ~ la CLI confunde tu carpeta personal con un proyecto.
  • Trata las skills y los servidores MCP como software que instalas. Una auditoría de febrero de 2026 sobre 3.984 skills públicas encontró fallos de seguridad en el 36,82% de ellas y confirmó cargas maliciosas en 76. Lee antes de instalar, prioriza las skills de los propios creadores de la herramienta, fija las versiones y mantén las herramientas de riesgo en “preguntar”.

Los cuatro bloques básicos de un vistazo

Bloque Qué es, en una línea Piénsalo como Cuándo lo lee el agente Cuánto cuesta Ejemplo
AGENTS.md (CLAUDE.md en Claude Code) Un archivo Markdown con las normas de la casa para un proyecto El manual del empleado Al principio de cada sesión, completo Toda su extensión, en cada petición “Usa ortografía británica. Ejecuta las pruebas antes de decir que has terminado.”
Skill Una carpeta con una SKILL.md receta, más scripts y referencias opcionales Una ficha de receta en un archivador Nombre y descripción al principio; la receta completa solo cuando una tarea la necesita Unos 100 tokens por skill hasta que se usa “Cómo escribimos las notas de la versión”
Servidor MCP Un pequeño programa que le da al agente nuevas herramientas Un juego de llaves y adaptadores La lista de herramientas al principio (a menos que tu agente la aplace); las herramientas individuales cuando se llaman Las descripciones de las herramientas, a menudo en cada petición Los issues de GitHub, un navegador real, la documentación actual de las librerías
Plugin o extensión Un paquete de skills, servidores MCP y a veces hooks Un kit de bienvenida Depende de lo que haya dentro La suma de sus partes Superpowers, el kit de inicio de un proveedor
Habilidades de agentes y servidores MCP explicados: AGENTS.md como el manual que siempre se carga, las habilidades como fichas de recetas que se cargan bajo demanda, los servidores MCP como herramientas para GitHub, un navegador y documentación en vivo, y los plugins como paquetes
Cuatro bloques, un agente. El manual siempre está abierto, las fichas de recetas se sacan del archivador cuando hacen falta y los servidores MCP son las llaves de todo lo que queda fuera de la terminal.

Índice


Parte 1 — Agent Skills y servidores MCP en lenguaje llano

La imagen del recién contratado

Imagina que contratas a alguien brillante. El primer día le darías tres cosas: un manual breve con las reglas que todos siguen, un archivador de recetas para los trabajos que tu equipo hace a su manera y un juego de llaves y tarjetas para que pueda entrar en los sistemas que necesita. A algunas personas también les darías un kit de bienvenida que junta unas cuantas recetas y llaves.

Los agentes de IA necesitan exactamente lo mismo, y cada pieza ya tiene un nombre estándar:

  • El manual es AGENTS.md (Claude Code llama a su versión CLAUDE.md).
  • Las recetas son las skills.
  • Las llaves son los servidores MCP.
  • Los kits de bienvenida son plugins, a los que algunos agentes llaman extensiones.

El resto de esta guía trata de las recetas y las llaves, porque ahí es donde vive la mayor parte de la confusión.

Qué es una skill

Una skill es una carpeta. Dentro hay un archivo obligatorio, SKILL.md, y, de forma opcional, cualquier otra cosa que necesite la tarea:

release-notes/
├── SKILL.md          ← obligatorio: nombre, descripción, instrucciones
├── references/       ← opcional: documentos más largos, se leen solo cuando hacen falta
├── scripts/          ← opcional: código que el agente puede ejecutar
└── assets/           ← opcional: plantillas, imágenes, archivos de datos

El SKILL.md archivo tiene un encabezado breve entre dos --- líneas (ese encabezado se llama front matter), seguidas de instrucciones simples:

---
name: release-notes
description: Escribe las notas de "Novedades" de la App Store a partir de los commits recientes. Úsala cuando te pidan notas de versión, un changelog o un texto de "novedades".
---

# Notas de versión

1. Lee los commits desde la última etiqueta de git.
2. Conserva solo los cambios que un usuario notaría.
3. Escribe de tres a cinco viñetas breves en lenguaje claro, con menos de 400 caracteres en total.

El estándar abierto pide dos campos. El nombre solo puede usar letras minúsculas, números y guiones, puede tener como máximo 64 caracteres y debe coincidir con el nombre de la carpeta. La descripción puede tener hasta 1.024 caracteres y debería decir qué hace la skill y cuándo usarla, porque la descripción es lo que usa el agente para decidir si abre la skill o no.

Por qué puedes instalar docenas de skills: el truco de las tres capas

Las skills se cargan por capas, lo que el estándar llama divulgación progresiva. Piensa en una estantería:

  1. Las contraportadas. Cuando empieza una sesión, el agente solo lee el nombre y la descripción de cada skill. La especificación reserva unos 100 tokens para eso por skill. (Un token es más o menos una palabra corta o parte de una; es la unidad con la que los modelos cuentan su memoria de trabajo.)
  2. El capítulo. Cuando una tarea coincide con una descripción, el agente lee entero el SKILL.md. El estándar recomienda mantenerlo por debajo de 5.000 tokens y 500 líneas.
  3. El apéndice. Los archivos de referencia y los scripts solo se cargan si las instrucciones los mencionan.

Por eso cien skills sin usar cuestan mucho menos que un único manual largo. Pero no son gratis: las descripciones se acumulan y los agentes les ponen un tope. Codex limita su lista inicial de skills al 2 % de la memoria de trabajo del modelo (8.000 caracteres si no puede determinar el tamaño), y Claude Code corta el texto del listado de cada skill a 1.536 caracteres. Instala lo que vayas a usar.

Qué es un servidor MCP

MCP, el Model Context Protocol, es un estándar abierto para conectar agentes de IA con herramientas y datos. Anthropic lo presentó en noviembre de 2024 y lo cedió a la nueva Agentic AI Foundation de la Linux Foundation en diciembre de 2025, junto con AGENTS.md de OpenAI y goose de Block.

En Servidor MCP es un programa pequeño que le dice a tu agente: “estas son las herramientas que ofrezco”. Un servidor de GitHub podría ofrecer create_issue y search_code; un servidor de navegador ofrece navigate y take_screenshot; un servidor de documentación ofrece query_docs. Tu agente es el cliente MCP: le muestra la lista al modelo y, cuando el modelo quiere usar una herramienta, el agente comprueba tus permisos, pide al servidor que la ejecute y le devuelve el resultado.

Los servidores son de dos tipos:

  • Servidores locales se ejecutan en tu propio ordenador. El agente los inicia con un comando como npx @playwright/mcp@latest y se comunica con ellos mediante la entrada y la salida del programa (el nombre técnico es stdio).
  • Servidores remotos se ejecutan en los ordenadores del proveedor. Te conectas con una dirección web, como https://mcp.context7.com/mcp, y normalmente inicias sesión a través del navegador o pegas una clave de API. El nombre técnico de la conexión es Streamable HTTP.

Ahí está el problema. Cada herramienta viene con un nombre, una descripción y una lista de parámetros, escritos para que el modelo los lea. A menos que tu agente los aplace, esas descripciones viajan con cada petición, y veinte servidores con diez herramientas cada uno hacen que cada respuesta sea más lenta, más cara y menos centrada. La parte 7 muestra qué hace cada agente al respecto.

AGENTS.md y los plugins, en breve

AGENTS.md es un archivo Markdown simple en la carpeta raíz de tu proyecto que el agente lee al inicio de cada sesión: el propósito del proyecto, sus comandos, sus reglas innegociables. OpenCode, Codex, Cursor y GitHub Copilot lo leen directamente. Claude Code lee CLAUDE.md en su lugar, y su documentación sugiere un CLAUDE.md que simplemente importa el otro archivo con una línea que dice @AGENTS.md. Como se carga cada vez, mantenlo corto y mueve todo lo específico de una tarea a las skills.

Plugins agrupan las demás piezas. Un plugin de Claude Code puede contener skills, subagentes, hooks (scripts que se ejecutan con eventos) y servidores MCP y LSP. Codex, Cursor, GitHub Copilot CLI y Hermes Agent también tienen plugins, y Gemini CLI los llama extensiones. La parte 9 los trata.

Un glosario de bolsillo

Término Qué significa aquí
Agente (o harness) El programa con el que hablas: OpenCode, Claude Code, Codex, etc. Ejecuta el modelo, lee archivos y llama a herramientas
Modelo La IA que piensa, como GLM, Claude o GPT
Ventana de contexto La memoria de trabajo del modelo para una petición. Todo lo que cargas compite por ella
Token La unidad en la que los modelos cuentan el texto; aproximadamente una palabra corta o parte de ella
Skill Una carpeta con una SKILL.md archivo que enseña al agente una tarea
Front matter El encabezado al principio de SKILL.md, entre dos --- líneas
Servidor MCP Un programa que ofrece herramientas al agente mediante el Model Context Protocol
Herramienta Una acción que ofrece un servidor MCP, como create_issue
stdio / Streamable HTTP Cómo se comunica el agente con un servidor local y con un servidor remoto
OAuth El flujo de “Iniciar sesión con…” en tu navegador que da al agente un token sin que tengas que pegar una contraseña
Ámbito de proyecto / ámbito global Instalado solo para un proyecto o para todos los proyectos de tu ordenador
Archivo de bloqueo Un recibo que indica qué instalaste, de dónde y una huella de cada skill
Enlace simbólico Un acceso directo a una carpeta. El CLI de skills guarda una copia real y enlaza a ella los agentes

Parte 2 — ¿Skill, servidor MCP o AGENTS.md? El test de cinco preguntas

Cuando quieras que un agente haga algo mejor, haz estas preguntas en orden y detente en el primer “sí”. La pregunta 4 es la única con una pregunta de seguimiento:

  1. ¿Debe cumplirse en cada una de las tareas de este proyecto? Ponlo en AGENTS.md. “Usa ortografía británica” y “ejecuta las pruebas antes de decir que has terminado” van aquí.
  2. ¿Debe aplicarse a la fuerza, no solo sugerirse? Usa una regla de permisos o un hook. Las skills y AGENTS.md son instrucciones, y un modelo puede ignorar las instrucciones. “Nunca hagas push a main” necesita una deny regla.
  3. ¿Es un conocimiento que solo importa para algunas tareas? Escribe o instala una skill. Las rutinas de publicación, las listas de revisión, la voz de tu marca y tu flujo de trabajo test-first son todas skills.
  4. ¿Necesita el agente acceso en vivo a un sistema que está fuera de sus archivos? Tus informes de fallos detrás de un inicio de sesión, un navegador que pueda controlar, una app de gestión de proyectos. Si es así, haz la pregunta 5 antes de ir a por un servidor.
  5. ¿Existe ya una buena herramienta de línea de comandos para ese sistema? Si la respuesta es sí, una skill que enseñe al agente esa herramienta suele ser mejor que un servidor: el agente ya sabe ejecutar comandos, un CLI no cuesta nada hasta que se usa, y su salida se puede filtrar antes de que llegue al modelo. Si no hay un buen CLI, si tu agente no puede ejecutar comandos o si la tarea es interactiva (como controlar un navegador), añade un servidor MCP.

Aquí tienes el test aplicado a diez deseos cotidianos:

Quieres que el agente… Utilice Por qué
Usar siempre ortografía británica AGENTS.md Se aplica a todas las tareas
No hacer push nunca a la rama main Una regla de permisos Debe imponerse, no solo sugerirse
Escribir las notas de versión a tu manera Una skill Conocimiento que se necesita de vez en cuando
Seguir un flujo de trabajo test-first estricto Una skill (Superpowers tiene una) Un procedimiento para algunas tareas
Leer y registrar issues de GitHub Una skill que enseña gh, o el servidor MCP de GitHub gh sale más barato; el servidor encaja mejor con los agentes que no pueden ejecutar comandos
Consultar la documentación actual de una biblioteca Un servidor MCP (Context7) o su CLI con una skill (ctx7) Datos en vivo en ambos casos
Navega por tu aplicación web y haz capturas de pantalla Un servidor MCP (Playwright) Necesita un navegador en marcha que el agente pueda manejar
Revisa los fallos de anoche Un servidor MCP (Sentry) Datos en directo detrás de un inicio de sesión
Genera un informe PDF a partir de tu plantilla Una skill con un script y la plantilla en assets/ Un procedimiento más una herramienta incluida
Mantén alejado de tus .env archivos Una regla de permisos Hay que hacerlo cumplir

Las skills y los servidores MCP no son rivales. Las mejores configuraciones los combinan: una skill explica cuando y cómo cómo usar las herramientas de un servidor, y el servidor hace el trabajo. Codex incluso permite que una skill declare los servidores MCP de los que depende, indicándolos de forma opcional agents/openai.yaml archivo.

Habilidad, servidor MCP o AGENTS.md: un flujo de cinco preguntas que manda las reglas de todas las tareas a AGENTS.md, las reglas obligatorias a los permisos, los conocimientos a las habilidades y el acceso al sistema en vivo a una habilidad de CLI o a un servidor MCP
Cinco preguntas, en orden. La mayoría de los deseos acaban siendo skills; un servidor se gana su sitio cuando el agente necesita acceso en directo y no existe ninguna buena herramienta de línea de comandos.

Parte 3 — Dónde busca skills cada agente

Todos los agentes buscan en dos tipos de sitio. Carpetas del proyecto viven dentro de tu repositorio, así que las skills viajan con el código y tus compañeros de equipo también las tienen. Carpetas personales viven en tu carpeta personal y se aplican a todos los proyectos de tu ordenador. La mayoría de las herramientas llaman a las instalaciones personales globales.

En 2026 los agentes convergieron en una única ubicación compartida: .agents/skills en un proyecto y ~/.agents/skills en tu carpeta personal. Coloca allí una skill y la mayoría de los agentes la encuentran sin ningún trabajo extra.

Agente Carpetas del proyecto Carpetas personales Invocar una skill tú mismo Conviene saber
OpenCode .opencode/skills, .agents/skills, .claude/skills ~/.config/opencode/skills, ~/.agents/skills, ~/.claude/skills Mencionar @skill-id en tu prompt El ID es el nombre de la carpeta. Limita las skills con el skill permiso
Claude Code .claude/skills ~/.claude/skills /skill-name No lee .agents/skills. Las skills de plugins aparecen como /plugin-name:skill-name
Codex .agents/skills, en todas las carpetas desde donde arrancas hasta la raíz del repositorio ~/.agents/skills, además de /etc/codex/skills para administradores $skill-nameo /skills Trae de serie un ~/.gemini/skills
Gemini CLI .agents/skills, .gemini/skills ~/.agents/skills, /skills list /skills list; el modelo te pide permiso antes de activar uno .agents/skills gana cuando dos skills comparten nombre
Cursor .agents/skills, .cursor/skills (y lee .claude/skills y .codex/skills) ~/.agents/skills, ~/.cursor/skills /skill-name A rutas limita un skill a los archivos que coincidan
GitHub Copilot .github/skills, .agents/skills, .claude/skills ~/.copilot/skills, ~/.agents/skills Carga los skills cuando son relevantes Funciona en Copilot CLI, el agente en la nube y el modo agente de VS Code y JetBrains
Hermes Agent .hermes/skills, .agents/skills, después de ejecutar hermes skills trust ~/.hermes/skills, más las carpetas que aparezcan en skills.external_dirs /skill-name, y hasta cinco seguidas Analiza cada instalación del hub en busca de contenido malicioso

Rutas tomadas de la documentación de cada agente el 15 de noviembre de 2026. Los agentes añaden ubicaciones con frecuencia; consulta la página de skills de tu agente si algo no aparece.

Tres detalles que evitan confusiones

  • Claude Code es la excepción. Solo lee .claude/skills y ~/.claude/skills. La CLI de skills se encarga de esto por ti creando un enlace desde la carpeta de Claude Code hasta la copia compartida. Si copias los skills a mano, tendrás que ponerlos (o un enlace simbólico) en la carpeta de Claude Code tú mismo.
  • Hermes Agent mantiene su propia biblioteca. Su carpeta principal es ~/.hermes/skills. Para que lea también la carpeta compartida, añádela en ~/.hermes/config.yaml:

yaml skills: external_dirs: - ~/.agents/skills

O instala con la CLI de skills e incluye -a hermes-agent. Elige un solo método, no los dos, o tendrás cada skill dos veces. – Los nombres duplicados causan sorpresas silenciosas. Cada agente tiene su propia regla para decidir qué copia gana. OpenCode registra sus carpetas en un orden fijo y gana la última, y la de tu proyecto .opencode/skills queda al final. Claude Code hace lo contrario: un skill personal gana a un skill de proyecto con el mismo nombre. Gemini CLI prefiere el del espacio de trabajo al de usuario y .agentes a .gemini, y Codex simplemente muestra los dos. La solución es aburrida y fiable: no tengas dos skills con el mismo nombre.

OpenCode tiene dos extras que conviene conocer. Un solo archivo Markdown en la raíz de una carpeta de skills (como skills/review.md) también cuenta como skill, y un competencias array en opencode.jsonc puede añadir carpetas extra o incluso un catálogo web de skills. Mi guía de OpenCode cubre sus permisos de skills con más detalle.

Dónde buscan las habilidades los agentes de IA: la carpeta compartida .agents/skills que leen Codex, OpenCode, Cursor, Gemini CLI y GitHub Copilot, con enlaces a .claude/skills de Claude Code y a ~/.hermes/skills de Hermes Agent
Una sola carpeta compartida cubre a la mayoría de los agentes. Claude Code siempre necesita un enlace, y Hermes Agent necesita uno para las skills globales; la CLI de skills crea los dos.

Parte 4 — La competencias CLI de skills: npm para Agent Skills, paso a paso

Puedes instalar skills copiando carpetas de un lado a otro, y para una o dos eso vale. Más allá de eso, quieres un gestor de paquetes: algo que sepa dónde mira cada agente, que guarde una copia en vez de cinco, que recuerde de dónde salió cada skill y que sepa decirte cuándo hay una versión más nueva. Eso es lo que competencias hace. Es una herramienta de línea de comandos de código abierto (MIT) de Vercel Labs, se ejecuta con npx skills, y su directorio de skills públicas está en skills.sh.

Los datos que importan a 15 de noviembre de 2026:

  • Versión 1.8.1, publicada el 11 de noviembre. Va rápido: de la 1.7.5 a la 1.8.1 pasaron nueve días.
  • Necesita Node.js 22.20 o posterior.
  • Admite 79 agentes, incluidos OpenCode, Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot y Hermes Agent.
  • Se instala desde GitHub (owner/repo), GitLab, Azure Repos, cualquier dirección Git, una carpeta local o un enlace de descarga directa a una SKILL.md o un archivo.

Paso 0 — Comprueba Node.js y pide siempre la versión más reciente

node --version      # necesita v22.20.0 o posterior

Si eso imprime una versión anterior o “command not found”, instala la versión LTS actual desde nodejs.org. En un Mac con Homebrew, brew install node también funciona. En una Raspberry Pi, la versión que aparece en la lista de paquetes del propio sistema operativo suele ser demasiado antigua, así que usa los instaladores enlazados en esa misma página.

Después automatiza una costumbre: escribe npx skills@latest en lugar de npx skills para todo lo que compruebe o actualice. El simple npx puede reutilizar una copia que descargó hace semanas y, con esta herramienta, la versión que ejecutas cambia lo que hacen los comandos (la parte 5 explica el ejemplo más claro).

Paso 1 — Mira antes de instalar

npx skills@latest add vercel-labs/agent-skills --list

--list muestra cada skill del repositorio con su descripción y no instala nada. Luego abre el repositorio en el navegador y lee el SKILL.md de todo lo que estés a punto de instalar, además de los scripts que tenga al lado. En skills.sh, la página de cada skill también muestra los resultados de la auditoría de seguridad (parte 11).

Paso 2 — Instala una skill para los agentes que usas

# Una skill, para OpenCode y Claude Code, en el proyecto actual
npx skills add vercel-labs/agent-skills --skill web-design-guidelines -a opencode -a claude-code

# La misma skill para todos los proyectos de este ordenador
npx skills add vercel-labs/agent-skills --skill web-design-guidelines -g -a opencode -a claude-code

# Fija una etiqueta de versión o un commit completo, para que las actualizaciones sean deliberadas
npx skills add owner/[email protected] --skill my-skill

Omite --skill y -a y la CLI te pregunta de forma interactiva: qué skills, qué agentes y si enlazar o copiar. Aquí es donde acaba todo:

Alcance La única copia real Enlaces para los agentes con carpeta propia El registro de lo que instalaste
Proyecto (por defecto) ./.agents/skills/<name> p. ej. ./.claude/skills/<name> para Claude Code ./skills-lock.json
Global (-g) ~/.agents/skills/<name> p. ej. ~/.claude/skills/<name>, ~/.hermes/skills/<name> ~/.agents/.skill-lock.json

La CLI guarda una única copia real en .agents/skills, que la mayoría de los agentes lee directamente, y crea enlaces (symlinks, básicamente accesos directos) para los agentes que buscan en otro sitio. Una sola copia significa una sola actualización. Si tu sistema no maneja bien los symlinks, algo que puede pasar en Windows, añade --copy para obtener copias independientes en su lugar.

Paso 3 — Ver qué hay instalado

npx skills ls              # las skills de este proyecto
npx skills ls -g           # tus skills globales
npx skills ls -a opencode  # solo lo que recibe OpenCode
npx skills ls --json       # legible por máquina, para scripts

Para las skills de proyecto, las versiones actuales también muestran un estado: rastreada (coincide con el archivo de bloqueo), modificada (la has editado tú o el agente), sin rastrear (sin entrada en el bloqueo, como una skill que escribiste a mano) o ausente (está en el archivo de bloqueo pero no en el disco).

Paso 4 — Encontrar skills

npx skills find                    # búsqueda interactiva
npx skills find seo                # buscar por palabra clave
npx skills find react --owner vercel   # solo los repositorios de una organización

O explora skills.sh, que ordena las skills por número de instalaciones y las agrupa por tema. La skill más instalada hoy allí es find-skills del propio repositorio de Vercel, que enseña a tu agente a buscar skills por su cuenta. Los recuentos de instalaciones cambian cada día, así que toma la clasificación como una pista, no como una reseña.

Paso 5 — Probar una skill sin instalarla

npx skills use vercel-labs/agent-skills@web-design-guidelines

Esto imprime un prompt ya preparado para esa skill, que puedes pasar por una tubería o pegar en un agente del mismo ordenador. Añade --agent claude-code y la CLI inicia Claude Code con la skill cargada. Es una buena forma de probar una skill antes de que pase a formar parte de tu configuración.

Paso 6 — Eliminar skills

npx skills remove web-design-guidelines            # de este proyecto
npx skills rm --global web-design-guidelines       # de tus skills globales
npx skills remove --agent claude-code my-skill     # solo de un agente
npx skills remove vercel-labs/agent-skills         # todo lo que venga de esa fuente
npx skills remove                                  # elegir de una lista

npx skills remove --all elimina todas las skills registradas en el archivo de bloqueo y se salta las carpetas que no instaló, como las skills que escribiste tú, así que no borrará tu propio trabajo.

Paso 7 — Crea las tuyas

npx skills init my-skill crea my-skill/SKILL.md a partir de una plantilla. La parte 10 recorre un ejemplo completo.

Toda la herramienta en una tarjeta

Quiero… Comando
Ver qué ofrece un repositorio npx skills@latest add owner/repo --list
Instalar una skill en este proyecto npx skills add owner/repo --skill name
Instalar para todos los proyectos add -g
Elegir los agentes add -a opencode -a claude-code (o --agent '*' para todos)
Instalar sin preguntas add -y
Fijar una versión npx skills add owner/[email protected] --skill name
Listar las skills instaladas npx skills ls · npx skills ls -g
Buscar en npx skills find keyword
Buscar actualizaciones (solo lectura) npx skills@latest check · add -g o -p
Instalar las actualizaciones npx skills update · -g · -p · -y · o nombra las skills
Eliminar npx skills remove name · add -g para global
Restaurar las skills de un proyecto desde su archivo de bloqueo npx skills install
Crear una skill nueva npx skills init name

Comandos de skills 1.8.1. npx skills install (un alias de experimental_install) y el experimental_sync comando para las skills que se distribuyen dentro de paquetes npm están marcados como experimentales y pueden cambiar.

La chuleta de la CLI npx skills: los comandos add, list, find, use, check, update, remove e init con sus opciones más útiles, las ubicaciones de instalación por proyecto y global, y los dos archivos de bloqueo
La CLI de skills en una ficha. Dos hábitos hacen la mayor parte del trabajo: --list antes de instalar, y @latest siempre que compruebes o actualices.

¿Qué es un archivo de bloqueo y debería hacer commit de él?

Un archivo de bloqueo es un recibo. Para cada skill registra de dónde vino y una huella de su carpeta (técnicamente un hash: un código corto que cambia cada vez que cambia cualquier archivo de la carpeta). La CLI mantiene dos tipos:

  • skills-lock.json en un proyecto. Haz commit en Git. En otro ordenador, o para un compañero de equipo, npx skills install restaura exactamente las mismas skills, y --frozen-lockfile (el valor predeterminado en CI) se niega a continuar si algo difiere. Eso hace que las skills de un proyecto sean reproducibles, como package-lock.json hace con el código.
  • ~/.agents/.skill-lock.json para tus skills globales. Pertenece a tu cuenta de usuario (o vive en $XDG_STATE_HOME/skills/.skill-lock.json si has definido esa variable). No lo edites a mano, y ten en cuenta que cada usuario de un equipo tiene el suyo, lo cual importa en la Parte 6.

Telemetría, en resumen

La CLI envía datos de uso anónimos. Según su documentación, los nombres de repositorios de GitHub y de skills solo se incluyen cuando GitHub confirma que el repositorio es público; también pueden nombrarse otros tipos de fuente. Para desactivarla, añade export DISABLE_TELEMETRY=1 (o DO_NOT_TRACK=1) a tu perfil del shell. Eso también desactiva las consultas de auditoría de seguridad que la CLI hace para las skills públicas, así que decide qué valoras más.

Otros instaladores que encontrarás

La CLI de skills no es la única forma de entrar. Varios agentes y herramientas tienen sus propios instaladores, y todos siguen el mismo estándar abierto:

Herramienta Ejemplo Conviene saberlo
GitHub CLI (gh skill, versión 2.90 o posterior, en vista previa) gh skill install owner/repo skill-name --agent claude-code gh skill preview muestra una skill antes de instalarla; --pin fija una versión
Hermes Agent hermes skills install <identifier> Su hub incluye skills.sh, y cada instalación pasa un análisis de seguridad
Gemini CLI gemini skills install <git-url> --scope workspace para un solo proyecto; pide consentimiento a menos que pases --consent
Codex $skill-installer <name> Una skill de sistema integrada
Claude Code /plugin install name@marketplace Los plugins agrupan skills con servidores MCP y hooks (Parte 9)

Una regla evita la mayoría de los quebraderos de cabeza: actualiza una skill con la misma herramienta con la que la instalaste. Cada instalador guarda sus propios registros, y ninguno sabe lo que hicieron los demás.


Parte 5 — “Mi pack de skills se actualizó hace dos días. ¿Cómo sé si lo tengo?”

Esa fue exactamente mi pregunta cuando Superpowers, la popular biblioteca de skills de Jesse Vincent, anunció una actualización. npx skills ls enumera nombres, no versiones, así que no puede decírtelo. Así es como la CLI lo sabe en realidad.

Cómo funciona la comprobación

Cuando instalas una skill, la CLI guarda la huella de su carpeta en el archivo de bloqueo. Cuando compruebas, le pregunta a la fuente (normalmente GitHub) por la huella de esa misma carpeta hoy. Misma huella: está al día. Distinta: hay una actualización. No compara números de versión ni fechas, por eso funciona incluso con skills que no tienen ninguna de las dos cosas.

cd /tmp                        # o una carpeta de proyecto, pero nunca tu carpeta personal
npx skills@latest check -g     # tus skills globales

cd ~/code/my-app
npx skills@latest check -p     # las skills de este proyecto

Un resultado típico en 1.8.1 es así:

↑ brainstorming tiene una actualización
↑ writing-plans tiene una actualización
2 skill(s) se pueden actualizar; ejecuta npx skills update para instalarlas

check también informa de las skills de proyecto cuyos archivos ya no coinciden con el archivo de bloqueo (tiene cambios locales), y sale con un código de error siempre que algo esté desactualizado o modificado, así que puedes usarlo para detener una compilación de CI que se ha desviado.

check cambió en noviembre, así que ejecuta la última versión

Desde la versión 1.7.5 (2 de noviembre de 2026), check solo informa. En versiones anteriores, desde al menos la 1.5.18 hasta la 1.7.4, check era simplemente otro nombre para update: preguntaba “Update scope?” e instalaba las actualizaciones sobre la marcha. Si has usado npx skills check antes de noviembre y te preguntabas por qué estaba “actualizando” cosas, esa es la razón. Usa npx skills@latest check y obtendrás el comportamiento de solo lectura.

Dos detalles más que hacen tropezar a la gente:

  • check elige un ámbito por sí solo. Si la carpeta en la que estás contiene un skills-lock.json archivo, o una .agents/skills carpeta con una skill dentro, comprueba las proyecto skills; de lo contrario comprueba las globales globales. Añade -g o -p para indicar cuál quieres.
  • No existe la opción “actualizar todo desde un solo repositorio”. O actualizas todo en un ámbito, o nombras las skills.

Luego actualiza

npx skills update                      # pregunta: proyecto, global o ambos
npx skills update -g                   # todas las skills globales
npx skills update -p                   # todas las skills del proyecto
npx skills update brainstorming writing-plans -g   # solo estas
npx skills update -y                   # sin preguntas: el proyecto si estás en uno; si no, global

Lee los cambios antes de actualizar algo importante. Abre el historial de commits del repositorio en GitHub y mira qué ha cambiado en las carpetas de skills: una actualización son nuevas instrucciones que tu agente seguirá con tus permisos.

Si lo instalaste como plugin, actualízalo como plugin

Muchos paquetes de skills se distribuyen ahora como plugins, y Superpowers es un buen ejemplo. Su README enumera una ruta de instalación distinta para casi cada agente:

Agente Instalación de Superpowers, según su README Cómo se actualiza
Claude Code /plugin install superpowers@claude-plugins-official Automáticamente, desde el marketplace oficial de Anthropic
Codex CLI /plugins, busca “superpowers”, Instalar plugin A través del gestor de plugins
Cursor /add-plugin superpowers en el chat del agente A través del gestor de plugins
Gemini CLI gemini extensions install https://github.com/obra/superpowers gemini extensions update superpowers
GitHub Copilot CLI copilot plugin marketplace add obra/superpowers-marketplace, entonces copilot plugin install superpowers@superpowers-marketplace A través del gestor de plugins
Hermes Agent hermes plugins install obra/superpowers --enable A través del gestor de plugins
OpenCode Añade "superpowers@git+https://github.com/obra/superpowers.git" en la lista de plugins de opencode.json, como describe su guía de instalación de OpenCode Al reiniciar; vacía la caché de paquetes de OpenCode si no aparece una versión nueva, o añade #v5.0.3etiquetas de ese estilo para fijar la versión

Según el README de Superpowers y su guía de instalación de OpenCode, comprobado el 15 de noviembre de 2026.

Instalé Superpowers en mi Mac con npx skills -g, así que el mío se actualiza a través del CLI de skills. Eso está bien. Lo que no está bien es instalar el mismo paquete por dos canales: acabas con dos copias de cada skill con nombres idénticos y sin forma de saber cuál elegirá el agente.

Cómo funciona npx skills check: el archivo de bloqueo guarda una huella de cada carpeta de habilidades, check la compara con la misma carpeta en el origen e informa de las actualizaciones, y update las instala
check compara huellas, no números de versión. Desde la versión 1.7.5 solo informa; update es el comando que cambia algo.

Parte 6 — Cinco problemas reales de mi Mac y mi Raspberry Pi, y cómo resolverlos

Todo lo de esta parte me pasó a mí en el verano de 2026, con la versión 1.5 del CLI. Desde entonces he comprobado cada problema con el código fuente de la versión actual, la 1.8.1, para que sepas cuáles están corregidos y cuáles siguen doliendo. La salida de terminal es real; la he acortado y he quitado los nombres de las máquinas.

Problema 1: “All global skills are up to date” (todas las skills globales están actualizadas), cuando no se comprobó nada

En mi Mac, npx skills check salió esto:

graham@mac my-app % npx skills check
◇  Update scope
│  Both
Checking for skill updates…
Global Skills
Checking skills from source: anthropics/skills
│  GitHub API request limit reached; checking existing gh authentication…
  ✗ Failed to fetch tree for anthropics/skills
Checking skills from source: vercel-labs/skills
  ✗ Failed to fetch tree for vercel-labs/skills
…                                  (six more sources, every one ✗)
Checking skills from source: obra/superpowers
  ✗ Failed to fetch tree for obra/superpowers
✓ All global skills are up to date

Qué pasó. Para comprobar un repositorio, el CLI pide a la API de GitHub la lista de archivos del repositorio. GitHub permite 60 solicitudes anónimas por hora por dirección de internet, y mi cupo de esa hora ya se había agotado (la herramienta lo dice en la primera línea), así que todas las consultas fallaron. La última línea solo cuenta las actualizaciones que la herramienta encontró, y no había encontrado ninguna, así que imprimió una marca verde. La versión antigua además intentaba tomar prestado un inicio de sesión del CLI de GitHub por detrás (esa es la línea “checking existing gh authentication”); como todas las peticiones seguían fallando, por lo visto no había ningún inicio de sesión que tomar prestado.

¿Está corregido? En parte. La versión 1.8.1 se esfuerza más antes de rendirse: primero anónimo, luego un token de tu entorno y después el inicio de sesión del propio CLI de GitHub mediante gh api, y para comprobar actualizaciones una descarga Git normal como último recurso. Pero el código fuente de la 1.8.1 muestra que, cuando una fuente sigue sin poder comprobarse, la línea de resumen sigue contando solo las actualizaciones que encontró. Todavía puede aparecer una marca verde debajo de cruces rojas, así que lee las líneas ✗.

La solución. Dale un inicio de sesión al CLI, lo que eleva el límite a 5.000 solicitudes por hora:

  1. Lo más fácil: instala el GitHub CLI y ejecuta gh auth login. Las versiones actuales del CLI de skills piden gh que haga la llamada a la API para que nunca veas tus credenciales.
  2. O usa un token: crea un token de acceso personal de grano fino con acceso de solo lectura a repositorios públicos, luego añádelo a tu perfil de shell (~/.zshrc en un Mac, ~/.bashrc en una Raspberry Pi):

bash export GITHUB_TOKEN="github_pat_…" # read-only, public repositories

Abre una terminal nueva después. Trata el token como una contraseña: nunca lo pegues en un chat, en una skill ni en un archivo al que hagas commit. 3. Actualiza y vuelve a comprobar: npx skills@latest check -g.

Problema 2: sudo me dio dos almacenes de skills y un error de npm

En mi Raspberry Pi había cogido la costumbre de escribir sudo su primero. Esto es lo que produjo:

graham@pi:~ $ sudo su
root@pi:/home/graham# npx skills update
npm error config prefix cannot be changed from project config: /home/graham/.npmrc.
◇  Update scope
│  Both
Checking for skill updates…
Global Skills
…
Found 6 global update(s)
…
Project Skills
Updating for: Universal, Claude Code, Hermes Agent
Refreshing 7 skill(s)…

Y un momento después, de vuelta como mi usuario normal:

graham@pi:~ $ ls ~/.agents/skills | wc -l
7
graham@pi:~ $ sudo ls /root/.agents/skills | wc -l
37

Qué pasó. sudo su te convierte en root, y root tiene su propia carpeta home, /root. Las skills se guardan por usuario, así que las skills globales de root están en /root/.agents/skills y las mías en /home/graham/.agents/skills. Todas las instalaciones globales que había hecho como root habían ido al almacén de root: 37 skills allí, 7 en el mío. Si tus agentes se ejecutan como tu usuario normal, que es lo habitual, todo lo que hay en el almacén de root les resulta invisible.

El error de npm tiene la misma causa. Como root, el archivo de ajustes personales de npm es /root/.npmrc, así que el /home/graham/.npmrc que está en la carpeta en la que estaba se lee como un proyecto archivo de ajustes en su lugar. El propio código de npm se niega a que un archivo de proyecto cambie el ajuste prefix , y registra exactamente ese error. Hay un tercer riesgo que no verás de inmediato: todo lo que root escriba dentro de tu carpeta home acaba siendo propiedad de root, y tu usuario normal no podrá actualizarlo después.

La solución.

  1. Sal de root: tipo exit. A partir de ahora, ejecuta la CLI y tus agentes como tú mismo.
  2. Averigua qué usuario usan tus agentes. La carpeta home que contenga sus ajustes es la que importa:

bash ls -d ~/.claude ~/.config/opencode ~/.hermes 2>/dev/null sudo ls -d /root/.claude /root/.config/opencode /root/.hermes 2>/dev/null

  1. Reinstala las skills de root como tú mismo, desde sus fuentes originales. Copiar los archivos arrastraría la propiedad de root y registros obsoletos. Reinstalar escribe un archivo de bloqueo limpio. Primero lista las fuentes que usó root:

bash sudo grep '"source"' /root/.agents/.skill-lock.json | sort -u

Luego, desde una carpeta de proyecto o /tmp, ejecuta npx skills add <owner/repo> -g -a <your agents> para cada una que sigas queriendo. 4. Recupera la propiedad de tus propias carpetas, por si root escribió en ellas:

bash sudo chown -R "$(id -un)":"$(id -gn)" ~/.agents ~/.claude ~/.hermes ~/.config/opencode 2>/dev/null

  1. Solo cuando todo funcione como tu usuario, borra la copia de root con sudo rm -rf /root/.agents.

Si usas sudo porque las instalaciones globales de npm fallan sin él, arregla eso en su lugar: apunta el prefix de npm a una carpeta tuya (npm config set prefix ~/.npm-global, y luego añade ~/.npm-global/bin a tu PATH). Eso es casi seguro lo que la prefix línea de mi propio .npmrc estaba haciendo.

Problema 3: ejecútalo desde tu carpeta personal y se convierte en un “proyecto”

De vuelta como yo mismo, en mi carpeta personal:

graham@pi:~ $ npx skills check
Need to install the following packages:
[email protected]
Ok to proceed? (y) y
…
Global Skills
No global skills tracked in lock file.
Install skills with npx skills add <package> -g
Project Skills
Updating for: Universal, Claude Code, Hermes Agent
Refreshing 7 skill(s)…

Qué pasó. El CLI decide que una carpeta es un proyecto si contiene un skills-lock.json archivo o una .agents/skills carpeta con una skill dentro. Tu carpeta personal contiene ~/.agents/skills, porque ahí es donde viven las skills globales, así que desde ~ el CLI ve un proyecto. Y si alguna vez ejecutaste npx skills add en tu carpeta personal sin -g, creaste allí una instalación de proyecto de verdad, con su propio ~/skills-lock.json, cuya carpeta de skills es exactamente la misma que usa la instalación global. Eso es lo que había pasado en mi Pi: siete skills registradas como un “proyecto” en mi carpeta personal y nada en absoluto en mi propio archivo de bloqueo global.

“No global skills tracked in lock file” tiene tres causas habituales: nunca instalaste con -g, instalaste con -g como otro usuario (root, mediante sudo), o se borró el archivo de bloqueo. Si has leído por ahí que un generate-lock comando lo reconstruye, no existe: ese comando no está en la versión 1.5 ni en la 1.8.

La solución.

  • Ejecuta el CLI desde una carpeta de proyecto o /tmp, nunca desde ~, y pasa -g o -p para que no pueda adivinar.
  • Para desenredar un “proyecto” de la carpeta personal, reinstala las skills que quieras con -g desde otra carpeta (acaban en el mismo sitio, ahora registradas en tu archivo de bloqueo global) y luego borra ~/skills-lock.json. No ejecutes npx skills remove de ~ para esto: en tu carpeta personal, la carpeta del proyecto y la carpeta global son la misma carpeta.

Problema 4: “No se encontraron skills coincidentes” por culpa de los dos puntos

graham@pi:~ $ npx skills remove ckm:banner-design ckm:brand ckm:design \
  ckm:design-system ckm:slides ckm:ui-styling
◇  Encontradas 7 skills instaladas únicas
■  No se encontraron skills coincidentes para: ckm:banner-design, ckm:brand, ckm:design, ckm:design-system, ckm:slides, ckm:ui-styling

Qué pasó. Esas skills se muestran como ckm:banner-design, pero los dos puntos son un carácter arriesgado en el nombre de una carpeta, así que la CLI las guardó como ckm-banner-design: pasa el nombre a minúsculas y convierte en guion cualquier cosa que no sea letra, dígito, punto o guion bajo. La versión 1.5.18 comparaba lo que yo escribía con los nombres de carpeta tal cual, así que no coincidía nada.

¿Está corregido? Sí. Las versiones actuales convierten tu entrada de la misma forma antes de comparar, así que ckm:brand y ckm-brand funcionan las dos, y cuando no coincide nada, la 1.8.1 imprime los nombres que son están instalados.

La solución. Correr npx skills ls (o ls ~/.agents/skills) para ver los nombres reales, o ejecuta npx skills remove sin argumentos y elige de la lista. Ojo también con el ámbito: desde una carpeta de proyecto, si quitas una skill que está registrada en tu lock global, ahora te dice que añadas -g.

Problema 5: fallan seis skills, una del mismo repositorio funciona

Actualizando 7 skill(s)…
✗ No se pudieron comprobar las skills eliminadas de nextlevelbuilder/ui-ux-pro-max-skill
Actualizando ckm:banner-design…
  ✗ No se pudo actualizar ckm:banner-design
…                                  (cinco ✗ más)
Actualizando ui-ux-pro-max…
  ✓ ui-ux-pro-max actualizada

Qué pasó. Para actualizar una skill, la CLI vuelve a buscarla en su repositorio de origen. Seis de mis siete skills de ese repositorio no se encontraron, mientras que la séptima se actualizó sin problema. Cuando fallan casi todas las skills de una misma fuente y una sola funciona, lo normal es que las que faltan se hayan renombrado, movido o eliminado en origen. El README de ese repositorio describe hoy una única skill, ui-ux-pro-max, y menciona banners, identidad de marca y presentaciones solo como funciones de un nivel de pago, lo que encaja con que las seis hayan salido del repositorio gratuito.

La solución. Mira qué ofrece ahora la fuente y elimina lo que ya no está:

npx skills add nextlevelbuilder/ui-ux-pro-max-skill --list
npx skills remove ckm-banner-design ckm-brand ckm-design ckm-design-system ckm-slides ckm-ui-styling

Las versiones actuales de la CLI detectan las skills que se han eliminado en origen y ofrecen limpiarlas durante una actualización, y quitan del archivo lock las skills que faltan cuando desinstalas. Ya que estás, busca duplicados: si también tienes una skill brand normal junto a ckm-brand, quédate con una. Dos skills con descripciones casi idénticas confunden la elección del agente y gastan su presupuesto de listado.

Extra: Claude Code no ve una skill que instaló la CLI

  • Revisa el enlace. Claude Code solo lee sus propias carpetas, así que ls -la ~/.claude/skills (o .claude/skills en el proyecto) debería mostrar la skill, normalmente como un enlace a .agents/skills. Varias versiones 1.5 corrigieron fallos con los enlaces de Claude Code (1.5.16 y 1.5.20), así que si falta, reinstala con npx skills@latest add … -a claude-code.
  • Comprueba que el archivo empieza bien. La apertura --- del front matter debe ser la primera línea de SKILL.md, o Claude Code tratará todo el archivo como texto plano.
  • Recarga. Claude Code detecta al momento las skills editadas, pero una carpeta de skills creada después de empezar la sesión necesita /reload-skills. Luego /skills enumera lo que está cargado.
Solución de problemas de npx skills: cinco errores reales con sus arreglos, desde un falso todo actualizado tras un límite de peticiones de GitHub hasta sudo creando un segundo almacén de habilidades, una carpeta personal tratada como proyecto y habilidades eliminadas en el origen
Cinco errores, cinco soluciones. La mayoría se reduce a las mismas dos reglas: lee las líneas ✗ y nunca ejecutes la CLI como root ni desde tu carpeta personal.

Parte 7 — Servidores MCP sin jerga

Qué pasa cuando conectas un servidor

  1. Añades el servidor a la configuración de tu agente: un comando para un servidor local, una dirección web para uno remoto.
  2. Cuando empieza una sesión, el agente lanza el servidor local o se conecta al remoto, e inicia sesión si el servidor lo requiere.
  3. El servidor enumera sus herramientas, y el agente pasa sus descripciones al modelo.
  4. Cuando una tarea necesita una herramienta, el modelo la pide, tu agente comprueba tus reglas de permisos (y puede preguntarte), el servidor hace el trabajo y el resultado vuelve a la conversación.

¿Local o remoto?

Servidor local (stdio) Servidor remoto (Streamable HTTP)
Se ejecuta En tu ordenador, iniciado por el agente En los ordenadores del proveedor
Añades Un comando, como npx @playwright/mcp@latest Una dirección, como https://mcp.context7.com/mcp
Inicio de sesión Normalmente una clave API en una variable de entorno Normalmente OAuth en tu navegador, o una clave en una cabecera
Necesita Node.js, Python o Docker, según el servidor Conexión a internet
Lo mejor para Cosas de tu máquina: un navegador, archivos, una base de datos local Servicios en la nube: GitHub, Sentry, documentación, herramientas del proyecto
Ojo con Se ejecuta con todos los permisos de tu usuario Tus datos van a ese proveedor

Puede que todavía veas un tercer tipo, SSE, en guías más antiguas. La documentación de Claude Code lo marca como obsoleto; usa la dirección HTTP cuando un servidor ofrezca las dos.

Una nota sobre las versiones

La especificación actual de MCP, publicada el 28 de julio de 2026, es la mayor revisión desde que se lanzó el protocolo: su núcleo ahora no tiene estado, lo que permite ejecutar servidores remotos detrás de balanceadores de carga normales. Rara vez tendrás que preocuparte, porque clientes y servidores acuerdan qué revisión hablar y los servidores antiguos siguen funcionando. OpenCode es el único sitio donde podrías verlo: cada servidor tiene un protocolo ajuste (legacy por defecto, autoo 2026-07-28), y la agrupación de conexiones solo funciona con la revisión más reciente.

La factura del contexto, y cómo mantenerla pequeña

Cada herramienta que ofrece un servidor llega con una descripción escrita para el modelo. En palabras del propio OpenCode, “Las herramientas MCP consumen contexto del modelo, así que añade solo los servidores que necesites.” Dos agentes suavizan ahora el coste de forma predeterminada:

  • Claude Code usa la búsqueda de herramientas. Al inicio de una sesión solo carga los nombres de las herramientas y las instrucciones de cada servidor, y trae la definición completa de una herramienta cuando Claude la busca de verdad.
  • OpenCode usa Code Mode, que agrupa las herramientas de cada servidor tras una sola entrada en lugar de listar cada herramienta por separado. Está activado a menos que pongas "codemode": false en un servidor.

En todos los demás casos, y además de esos valores predeterminados, estos son tus controles:

Agente Desactivar un servidor Ocultar las herramientas que no quieras
OpenCode "disabled": trueo /mcps para una sesión A deny regla en <server>_<tool> en los permisos
Claude Code claude mcp remove <name> (/mcp muestra el estado) A deny regla de permisos en mcp__<server>__<tool>; ENABLE_TOOL_SEARCH decide cuánto se carga de antemano
Codex enabled = false enabled_tools y disabled_tools
Gemini CLI gemini mcp disable <name> (añade --session para una sesión) includeTools y excludeTools
Cursor El interruptor del servidor en Personalizar (Los administradores pueden definir listas de herramientas permitidas)
Hermes Agent enabled: false tools.include y tools.exclude

Mi regla: dos a cinco servidores que usas cada semana superan a veinte que quizá uses algún día. Elimina el resto; puedes volver a añadirlos en un minuto.

Cuatro servidores que merece la pena probar primero

Servidor Qué le aporta a tu agente Tipo Dirección o comando Inicio de sesión
Context7 Documentación actual y específica de cada versión para bibliotecas y frameworks populares Remoto https://mcp.context7.com/mcp No hace falta ninguna; una clave de API gratuita amplía los límites
GitHub (oficiales) Incidencias, pull requests, búsqueda de código, Actions Remoto https://api.githubcopilot.com/mcp/ OAuth si tu agente lo admite, o un token de acceso personal
Playwright Un navegador real que el agente puede abrir, recorrer con clics y capturar en pantalla Local npx @playwright/mcp@latest Ninguno
Sentry Tus errores y caídas reales Remoto https://mcp.sentry.dev/mcp OAuth

Dónde encontrar más:

  • El oficial MCP Registry, mantenido por los colaboradores del protocolo, enumera los servidores publicados.
  • La propia documentación de tus herramientas. La mayoría de los servicios ya publican un servidor oficial; busca “MCP” en su documentación.
  • El catálogo de tu agente. Hermes Agent tiene hermes mcp catalog, y muchos plugins de Claude Code traen sus propios servidores.

Prefiere los servidores publicados por la empresa que gestiona el servicio. Un servidor cualquiera llamado “github-mcp-pro” merece la misma desconfianza que una extensión de navegador cualquiera.

La opción más ligera: una herramienta de línea de comandos más una skill

Antes de añadir un servidor, comprueba si una herramienta de línea de comandos hace el trabajo. El propio Context7 ofrece ambas rutas: el servidor MCP de arriba, o una pequeña CLI con una skill (npx ctx7 setup --opencode, que necesita Node.js 22.13 o posterior). La propia herramienta de GitHub gh más una skill breve cubre la mayor parte de lo que hace su servidor.

Un servidor tiene sentido cuando tu agente no puede ejecutar comandos (una aplicación de chat de escritorio, por ejemplo), el servicio no tiene una buena CLI, o la tarea es interactiva, como manejar un navegador. Una CLI más una skill tiene sentido cuando la herramienta ya existe: no cuesta nada hasta que se usa, y su salida se puede recortar antes de que llegue al modelo. Mi guía de OpenCode defiende lo mismo para el desarrollo de aplicaciones.


Parte 8 — Añadir un servidor MCP en seis agentes: recetas para copiar y pegar

Cada receta añade los mismos dos servidores: Context7 (remoto) y Playwright (local). Cambia cualquier otro servidor de la misma forma. Cuando un agente tiene tanto un comando como un archivo de configuración, el comando simplemente escribe el archivo por ti.

OpenCode

opencode mcp add context7 --url https://mcp.context7.com/mcp
opencode mcp add playwright -- npx @playwright/mcp@latest
opencode mcp list

Añade --global para que un servidor esté disponible en todos los proyectos. En opencode.jsonc la misma configuración se ve así:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "context7": {
        "type": "remote",
        "url": "https://mcp.context7.com/mcp",
        "oauth": false
        // Con una clave de API gratuita, añade:
        // "headers": { "Authorization": "Bearer {env:CONTEXT7_API_KEY}" }
      },
      "playwright": {
        "type": "local",
        "command": ["npx", "@playwright/mcp@latest"]
      }
    }
  }
}
  • Los secretos se introducen como {env:NAME}; OpenCode no expande un $NAME.
  • Los servidores remotos prueban OAuth automáticamente; oauth: false es para servidores que usan una clave o ninguna. Inicia sesión con opencode mcp auth <name>, y por SSH, pega en el prompt la URL de callback de la página del navegador que falló.
  • Dentro de una sesión, /mcps conecta, desconecta o inicia sesión en los servidores.
  • Cada herramienta se convierte en una acción de permiso llamada <server>_<tool>, así que { "action": "playwright_*", "resource": "*", "effect": "ask" } hace que cada acción del navegador pregunte primero.

Claude Code

claude mcp add --transport http context7 https://mcp.context7.com/mcp
claude mcp add playwright -- npx @playwright/mcp@latest
claude mcp list

El -- separa las opciones de Claude Code del propio comando del servidor. Los servidores usan por defecto ámbito local (tú, en este proyecto). Añade --scope user para todos tus proyectos, o --scope project para escribir un .mcp.json archivo que puedes commitear para tu equipo:

{
  "mcpServers": {
    "context7": {
      "type": "http",
      "url": "https://mcp.context7.com/mcp"
    },
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}
  • .mcp.json expande ${VAR} y ${VAR:-default}, así las claves se quedan en tu entorno y no en Git.
  • /mcp dentro de una sesión muestra el estado de cada servidor y gestiona el inicio de sesión OAuth.
  • Claude Code pregunta antes de usar los servidores del .mcp.json, así un repositorio clonado no puede añadir los suyos sin avisar.

Codex

Codex guarda los servidores en ~/.codex/config.toml, o en .codex/config.toml dentro de un proyecto que hayas marcado como de confianza:

[mcp_servers.context7]
url = "https://mcp.context7.com/mcp"

[mcp_servers.playwright]
command = "npx"
args = ["@playwright/mcp@latest"]
  • Los servidores remotos también se pueden añadir con codex mcp add context7 --url https://mcp.context7.com/mcpy codex mcp login <name> ejecuta un inicio de sesión OAuth.
  • Para una clave, bearer_token_env_var = "CONTEXT7_API_KEY" la lee de tu entorno.
  • Ajusta un servidor con enabled_tools y disabled_tools; startup_timeout_sec (10 segundos por defecto) ayuda a que los servidores lentos arranquen.

Gemini CLI

gemini mcp add -t http context7 https://mcp.context7.com/mcp
gemini mcp add playwright npx @playwright/mcp@latest
gemini mcp list

gemini mcp add escribe en los ajustes del proyecto por defecto; añade -s user para todos los proyectos. En settings.json:

{
  "mcpServers": {
    "context7": { "httpUrl": "https://mcp.context7.com/mcp" },
    "playwright": { "command": "npx", "args": ["@playwright/mcp@latest"] }
  }
}
  • httpUrl es para Streamable HTTP; url significa el tipo SSE antiguo.
  • Deja trust desactivado. Si lo pones en verdadero, se salta todas las confirmaciones de ese servidor.
  • Gemini CLI elimina las variables que parecen secretos (nombres que contienen TOKEN, SECRET, PASSWORD o KEY) del entorno de un servidor, a menos que las incluyas en su env bloque.
  • OAuth necesita un navegador en la misma máquina. En una carpeta que no es de confianza, los servidores locales permanecen desconectados hasta que ejecutes gemini trust.

Cursor

Cursor lee .cursor/mcp.json en un proyecto y ~/.cursor/mcp.json para todo:

{
  "mcpServers": {
    "context7": { "url": "https://mcp.context7.com/mcp" },
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}
  • Los servidores locales necesitan "type": "stdio".
  • Los secretos se introducen como ${env:NAME}.
  • Activa y desactiva los servidores con sus interruptores en Personalizar.

Hermes Agent

Hermes lee mcp_servers en ~/.hermes/config.yaml:

mcp_servers:
  context7:
    url: "https://mcp.context7.com/mcp"
  playwright:
    command: "npx"
    args: ["@playwright/mcp@latest"]
  • Correr /reload-mcp después de editar, y hermes mcp test context7 para ver exactamente qué respondió un servidor.
  • Para los servicios OAuth, añade auth: oauth a una entrada HTTP. En una máquina sin pantalla, Hermes ofrece pegado manual, reenvío de puertos SSH o un flujo de inicio de sesión en el dispositivo.
  • Hermes pasa a los servidores locales solo las variables que indiques en env más una base segura, no todo el entorno de tu shell.
  • Las herramientas aparecen como mcp_<server>_<tool>; fíltralas con tools.include o tools.exclude.

Comprueba que funciona, en cualquier agente

Haz una pregunta que solo el servidor pueda responder: “Usa Context7 para consultar cómo definir una ruta en la versión actual de Next.js y dime qué herramienta has llamado.” Luego pide algo visible: “Abre example.com con Playwright y describe la página.” Si el agente dice que no tiene esas herramientas, lista los servidores (Lista de MCP de OpenCode, claude mcp list, gemini mcp list, hermes mcp test) y busca una conexión fallida o un inicio de sesión que nunca terminó.

Cómo añadir un servidor MCP en OpenCode, Claude Code, Codex, Gemini CLI, Cursor y Hermes Agent: el mismo servidor Context7 en el formato de comando o de configuración de cada agente, además de un comando de servidor local
Un servidor, seis dialectos. Las ideas son idénticas; solo cambian los nombres de archivo y los corchetes.

Parte 9 — Plugins: skills y servidores MCP en una sola caja

Instalar diez skills y tres servidores uno a uno acaba cansando. Los plugins los agrupan, y la mayoría de los agentes ya tienen algún tipo de sistema de plugins.

Plugins de Claude Code

Un plugin de Claude Code puede contener skills, subagentes, hooks, servidores MCP y servidores de lenguaje. Los plugins vienen de marketplaces, que son simplemente catálogos alojados en un repositorio Git:

/plugin marketplace add anthropics/skills
/plugin install document-skills@anthropic-agent-skills

Dentro de una sesión, /plugin install primero abre los detalles del plugin para que veas exactamente qué añade antes de elegir un ámbito: tú (todos los proyectos), este repositorio para todos, o este repositorio solo para ti. Desde tu shell, claude plugin install <name>@<marketplace> hace lo mismo sin una sesión.

Tres funciones que conviene conocer:

  • El coste de contexto es visible. Para los plugins del marketplace oficial de Anthropic, el panel de detalles estima qué añade el plugin a cada mensaje y qué añade cuando se usa. claude plugin details <name> muestra la cifra por sesión de todo lo que tengas instalado.
  • Actualizaciones. El marketplace oficial de Anthropic actualiza los plugins automáticamente; los marketplaces de terceros no, a menos que lo actives. claude plugin update <name>@<marketplace> actualiza un plugin a mano.
  • Los plugins sin usar se marcan. La pestaña Installed agrupa los plugins que no has usado recientemente, lo que facilita una buena limpieza a fondo.

Plugins en otros lugares

  • Codex distribuye skills reutilizables mediante plugins (/plugins en la CLI), y un plugin también puede incluir conexiones a servidores MCP.
  • Gemini CLI los llama extensiones: gemini extensions install <git-url> y gemini extensions update <name>.
  • GitHub Copilot CLI (copilot plugin install) y Hermes Agent (hermes plugins install) tienen comandos de plugin, y Cursor tiene /add-plugin en el chat del agente.
  • OpenCode los plugins son paquetes JavaScript o TypeScript listados en el lista de plugins ajuste de su configuración, que puede registrar skills y herramientas. Superpowers se instala así.

Las dos reglas que mantienen sana una configuración de plugins

  1. Un canal por paquete. Si un paquete de skills existe como plugin y como skills simples, elige uno. Dos copias significan nombres duplicados y un agente que coge la que ve primero.
  2. Actualiza donde lo instalaste. La CLI de skills no sabe nada de plugins, y los gestores de plugins no saben nada de ~/.agents/skills.

Parte 10 — Escribe tu primer skill en diez minutos

La mejor primera skill resuelve una tarea que repites. Aquí tienes una creada a partir de la parte 6: una skill que permite a cualquier agente comprobar si tus skills tienen actualizaciones de forma segura, sin usar nunca sudo ni fiarte de una marca verde a ciegas.

Paso 1 — Crea la carpeta

mkdir -p ~/skills-drafts && cd ~/skills-drafts
npx skills init skills-housekeeping

Eso crea skills-housekeeping/SKILL.md a partir de una plantilla. Sustituye su contenido por esto:

---
name: skills-housekeeping
description: Comprueba si las skills de agente instaladas tienen actualizaciones y problemas con la CLI npx skills, y explica los resultados en lenguaje sencillo. Úsala cuando te pregunten si las skills están al día, para actualizar skills, o cuando una skill instalada parece faltar.
metadata:
  author: graham-miranda
  version: "1.0"
---

# Mantenimiento de skills

## Reglas
- No ejecutes nunca ningún comando con sudo.
- No ejecutes nunca `npx skills update` ni `npx skills remove` sin preguntar antes.
- Ejecuta los comandos desde /tmp o desde una carpeta de proyecto, nunca desde la carpeta personal.

## Comprobación
1. Ejecuta `cd /tmp && npx skills@latest check -g` para las skills globales.
2. Si el proyecto actual tiene un archivo skills-lock.json, ejecuta también `npx skills@latest check -p` en la carpeta del proyecto.
3. Trata cada línea que empiece por ✗ como «no comprobada», aunque una línea posterior diga que todo está al día.

## Informe
- Enumera las skills con actualizaciones, las skills con cambios locales y todo lo que no se haya podido comprobar.
- Si alguna comprobación falla, sugiere `gh auth login`, o un GITHUB_TOKEN con acceso de solo lectura a repositorios públicos.
- Pregunta antes de actualizar. Luego ejecuta `npx skills update -g` (o `-p`) e informa de lo que ha cambiado.

Paso 2 — Compruébala con el estándar

  • Nombre: skills-housekeeping usa solo letras minúsculas y guiones, tiene menos de 64 caracteres y coincide con el nombre de la carpeta. Las tres cosas son obligatorias.
  • Descripción: dice qué lo que hace la skill y cuando para usarla, y contiene las palabras que la gente escribe de verdad («al día», «actualizar skills», «falta»). La descripción es la única parte que el agente ve antes de decidir, así que hace la mayor parte del trabajo. El estándar permite hasta 1.024 caracteres; apunta a una o dos frases.
  • Longitud: muy por debajo de las 500 líneas recomendadas. Cuando una skill crece, mueve el detalle a references/ y remite a él desde las instrucciones.

El proyecto Agent Skills publica un validador de referencia, skills-ref, que comprueba el front matter y las reglas de nombres: skills-ref validate ./skills-housekeeping.

Paso 3 — Instálala para todos los agentes a la vez

La CLI de skills también instala desde una carpeta local:

npx skills add ./skills-housekeeping -g -a opencode -a claude-code -a codex

Eso pone la copia real en ~/.agents/skills/skills-housekeeping (que OpenCode y Codex leen directamente) y añade un enlace en ~/.claude/skills para Claude Code.

Paso 4 — Pruébalo

Pídelo con palabras sencillas: “¿Están actualizadas mis skills?” Una skill bien descrita se detecta automáticamente. Si no es así, llámala por su nombre para descartar un problema de carga: @skills-housekeeping en OpenCode, /skills-housekeeping en Claude Code, $skills-housekeeping en Codex. Si se carga por su nombre pero nunca por sí sola, el problema es la descripción: añade las frases que usas de verdad.

Paso 5 — Compártela

Sube la carpeta a un repositorio de GitHub, preferiblemente dentro de una skills/ carpeta (skills/skills-housekeeping/SKILL.md). Así cualquiera puede instalarla con npx skills add your-name/your-repo. La CLI busca skills en skills/ y en las carpetas habituales de agentes, hasta tres niveles de profundidad.

Extras específicos de cada agente, y cuándo evitarlos

Varios agentes entienden campos adicionales del front matter. Claude Code tiene disable-model-invocation (solo tú puedes activar la skill) y context: fork (ejecutarla en un subagente); Cursor tiene rutas (solo para los archivos que coincidan); OpenCode puede ocultar una skill al modelo con metadata ajustado a opencode/autoinvoke: false. Son útiles, pero lo que viaja son los campos estándar. La propia documentación de Claude Code señala que fuera de Claude Code, en las subidas a claude.ai o en la Skills API, solo se aceptan los campos estándar y cualquier otro da error. Para las skills que compartas, cíñete a nombre, descripción, license, compatibility, metadata y el experimental allowed-tools.

Anatomía de una habilidad de agente: el front matter de SKILL.md que se lee al arrancar, unos 100 tokens, las instrucciones que se leen cuando coincide una tarea, y las referencias, scripts y recursos que solo se leen cuando hacen falta
Tres capas: la etiqueta, la receta y el apéndice. Solo la primera se carga siempre, y por eso las buenas descripciones importan más que unas instrucciones largas.

Parte 11 — Mantenerte a salvo: las skills y los servidores son software

Es fácil pensar que una skill es “solo un archivo Markdown”. No lo es, en realidad. Son instrucciones que tu agente seguirá con tus permisos, a menudo con scripts que ejecutará en tu máquina. Y un servidor MCP local es un programa que se ejecuta como tú.

Las cifras de este año son para tomárselas en serio. El estudio ToxicSkills de Snyk, publicado en febrero de 2026, analizó 3.984 skills de agentes públicas: El 36,82 % tenía al menos un fallo de seguridad, el 13,4 % tenía uno crítico y 76 contenían cargas maliciosas confirmadas. El problema se concentró en ClawHub, el mercado comunitario de OpenClaw, donde una auditoría anterior de 2.857 skills, también publicada por Snyk, había encontrado 341 maliciosas, cerca del 12 % del registro en aquel momento. En cambio, las 100 skills más populares de skills.sh no activaron ninguna de las comprobaciones de inyección de prompt ni de código malicioso de Snyk. La popularidad no es una prueba, pero ayuda.

MCP tiene su propia versión del riesgo. La documentación de Claude Code advierte de que los servidores que descargan contenido externo pueden exponerte a inyección de prompts: una página web, el comentario de una incidencia o un informe de fallos que contiene texto dirigido a tu agente y no a ti.

Diez hábitos que te mantienen a salvo

  1. Léelo antes de instalar. Utilice npx skills add owner/repo --list, gh skill preview, o simplemente abre el SKILL.md y sus scripts en GitHub.
  2. Prefiere a los creadores y a autores conocidos. Las skills de Expo para Expo, las de Vercel para Next.js, el servidor MCP oficial de un fabricante para su propio servicio.
  3. Revisa las auditorías. Cada skill de skills.sh muestra los resultados de tres escáneres: Gen Agent Trust Hub, Socket y Snyk. “Pendiente” significa que nadie lo ha mirado todavía.
  4. Fija la versión de todo lo importante. npx skills add owner/[email protected]o gh skill install … --pin v1.2.3, así las actualizaciones llegan cuando tú decidas.
  5. Revisa las actualizaciones como código. npx skills check, luego lee los cambios en GitHub y después npx skills update.
  6. Filtra las skills de terceros. En OpenCode, las reglas usan la skill acción y gana la última coincidencia:

jsonc "permissions": [ { "action": "skill", "resource": "*", "effect": "ask" }, { "action": "skill", "resource": "skills-housekeeping", "effect": "allow" }, { "action": "playwright_*", "resource": "*", "effect": "ask" } ]

Hermes Agent escanea cada instalación desde el hub, y --force no puede anular un veredicto de “peligroso”. Gemini CLI te pide consentimiento antes de activar una skill. 7. Dale a los servidores el menor acceso que funcione. Tokens de solo lectura y con permisos detallados; un token distinto por servidor; las herramientas de escritura y borrado en “preguntar” o filtradas. 8. Mantén los secretos fuera de las skills y de la configuración que se sube al repositorio. Usa variables de entorno ({env:NAME} en OpenCode, ${VAR} en la configuración de Claude Code .mcp.json, ${env:NAME} en Cursor), nunca claves pegadas. 9. Ten cuidado con la configuración de proyecto de otras personas. Un repositorio clonado puede traer su propia .mcp.json o sus skills. Claude Code pregunta antes de usar los servidores del proyecto, Gemini CLI mantiene los servidores locales desconectados en carpetas que no son de confianza, y Hermes Agent carga las skills del proyecto solo después de hermes skills trust. No aceptes esos avisos con el piloto automático. 10. Desinstala lo que no uses. Cada skill y cada servidor que no usas es superficie de ataque que pagas en contexto.

Lista de comprobación de seguridad de habilidades de agentes y MCP: las cifras de ToxicSkills de Snyk para 3.984 habilidades públicas y diez hábitos seguros, desde leer antes de instalar y fijar versiones hasta tokens con privilegios mínimos
Una skill son instrucciones que tu agente sigue con tus permisos. Instálala con el mismo cuidado que dedicarías a cualquier otro programa.

Parte 12 — Una rutina semanal de dos minutos

Las skills y los servidores se desfasan. Una pequeña rutina los mantiene al día:

# Skills globales, desde una carpeta neutra
cd /tmp && npx skills@latest check -g

# Cada proyecto en el que estés trabajando
cd ~/code/my-app && npx skills@latest check -p

# Después de leer qué ha cambiado en origen:
npx skills update -g

Una vez al mes, dedica cinco minutos más:

  • Poda. npx skills ls -g y elimina lo que no hayas usado. En Claude Code, el panel de plugins enumera los plugins que no has usado recientemente.
  • Haz una lista de tus servidores. Lista de MCP de OpenCode, claude mcp list, gemini mcp list o hermes mcp test para cada uno. Elimina todo lo que hayas olvidado añadir.
  • Rota los tokens que diste a los servidores, sobre todo a los que pueden escribir.

Dos máquinas, una configuración

Ejecuto agentes en un Mac y en una Raspberry Pi, y tres hábitos los mantienen sincronizados:

  1. El mismo enfoque en ambas: tu usuario normal, nunca sudo, y el CLI ejecutado desde una carpeta de proyecto o /tmp.
  2. Las skills de proyecto viajan con Git. Confirmar .agents/skills y skills-lock.json; en la otra máquina, npx skills install restaura exactamente las mismas versiones.
  3. Las skills globales vienen de un script. Mantenga su npx skills add … -g comandos en un pequeño archivo de shell y ejecútalo en cada máquina. También sirve como documentación de aquello en lo que confías.

En una máquina headless como una Pi, configura GITHUB_TOKEN en ~/.bashrc para que las comprobaciones de actualización no alcancen el límite anónimo. Los inicios de sesión en el navegador requieren cuidado: OpenCode te deja pegar la URL de callback en su prompt, Hermes Agent ofrece pegado inverso, reenvío de puertos SSH o un flujo de dispositivo, mientras que el flujo OAuth de Gemini CLI necesita un navegador en la misma máquina.


Parte 13 — ¿Qué configuración deberías elegir? Cinco escenarios

1. “Acabo de empezar con OpenCode.”

Instalar como máximo tres skills y un servidor MCP. Context7 es un buen primer servidor, y una skill de release o de revisión que encaje con tu forma de trabajar es una buena primera skill. Mantén las skills de terceros en preguntar en los permisos de OpenCode hasta que confíes en ellas. Mi guía de OpenCode cubre el resto de la configuración.

2. “Uso OpenCode y Claude Code en paralelo, quizá también Hermes Agent.”

Instala las skills globalmente con el CLI y nombra cada agente: npx skills add owner/repo -g -a opencode -a claude-code -a hermes-agent. Una copia, tres agentes. Los servidores MCP no comparten un archivo de configuración común, así que añade cada uno a cada agente y guarda la lista en un sitio donde la encuentres. Mi comparativa de OpenCode, Hermes Agent y OpenClaw explica en qué destaca cada agente, y mi comparativa de harness de programación con IA cubre 28 de ellos lado a lado.

3. “Mi equipo comparte un repositorio.”

Utilice alcance de proyecto: haz commit de .agents/skills, skills-lock.json, y la configuración de MCP (opencode.jsonc, .mcp.json o .cursor/mcp.json) sin secretos dentro. Cada persona guarda las claves en su propio entorno. En CI, npx skills install --frozen-lockfile falla si las skills de alguien se desvían, y npx skills check -p falla cuando hay actualizaciones pendientes.

4. “Mis agentes se ejecutan en una Raspberry Pi o en un servidor.”

Un usuario normal, sin sudo, nunca. Conjunto GITHUB_TOKEN, prefiere servidores remotos que acepten un token en una cabecera (o que ofrezcan un inicio de sesión en el dispositivo) y ejecuta la comprobación semanal desde /tmp. La parte 6 es tu lista de comprobación.

5. “Mi código no debe salir de mi máquina.”

Utilice solo servidores MCP locales, y sáltate los servidores remotos de documentación y de búsqueda de código. Desactiva la telemetría de la CLI (DISABLE_TELEMETRY=1), lee cada skill que instales y recuerda que el modelo en sí puede seguir siendo un modelo en la nube: la privacidad depende de dónde se modelo ejecuta también. Mi guía para ejecutar LLM en un MacBook cubre lo que cuesta de verdad la vía totalmente local.


Preguntas frecuentes

¿Qué son las habilidades de agente?

Las agent skills son carpetas que enseñan a un agente de IA a hacer un trabajo concreto. Cada una contiene un SKILL.md archivo con un nombre, una descripción e instrucciones paso a paso, además de scripts opcionales y archivos de referencia. El agente solo lee las descripciones al principio de una sesión y carga las instrucciones completas de una skill cuando una tarea coincide. Las skills siguen un estándar abierto, así que casi todas funcionan igual en OpenCode, Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot y Hermes Agent.

¿Qué es un servidor MCP?

Un servidor MCP es un programa pequeño que da a un agente de IA herramientas nuevas mediante el Model Context Protocol, un estándar abierto que ahora acoge la Agentic AI Foundation de la Linux Foundation. Los servidores locales se ejecutan en tu ordenador y los inicia el agente; los servidores remotos se ejecutan en los ordenadores de un proveedor y se llega a ellos mediante una dirección web, normalmente con un inicio de sesión en el navegador. Algunos ejemplos son el servidor oficial de GitHub, Context7 para documentación actualizada y Playwright para controlar un navegador.

¿Qué diferencia hay entre las agent skills y los servidores MCP?

Una skill le da al agente conocimientos prácticos: instrucciones escritas sobre cómo hacer un trabajo, que solo se cargan cuando hacen falta. Un servidor MCP le da al agente capacidades: herramientas que llegan a sistemas fuera de la terminal, como GitHub, un navegador o un rastreador de fallos. Usa una skill para procedimientos y convenciones, un servidor MCP para el acceso en vivo a un sistema, y AGENTS.md para las reglas que se aplican a todas las tareas. Si ya existe una buena herramienta de línea de comandos, una skill que le enseñe a usarla suele ser más barata que un servidor.

¿Funcionan las habilidades igual en OpenCode, Claude Code y Codex?

En gran medida, porque los tres siguen el estándar Agent Skills. La diferencia está en dónde buscan. Codex y OpenCode leen las .agents/skills y ~/.agents/skills carpetas compartidas; OpenCode también lee .opencode/skills y las carpetas de Claude Code. Claude Code solo lee .claude/skills y ~/.claude/skills. Algunos campos adicionales del front matter, como el de Claude Code context: fork, solo funcionan en un agente, así que las skills compartidas deberían ceñirse a los campos estándar.

¿Cómo instalo una habilidad con npx skills?

Correr npx skills add owner/repo --list para ver las skills que ofrece un repositorio y luego npx skills add owner/repo --skill skill-name -a opencode -a claude-code para instalar una para los agentes que uses. Añade -g para tenerla disponible en todos los proyectos. Necesitas Node.js 22.20 o posterior. Sin flags, la CLI te pregunta qué skills y qué agentes quieres y si enlazar o copiar los archivos.

¿Dónde instala habilidades npx skills?

Las instalaciones por proyecto ponen la copia real en .agents/skills/<name> dentro de tu proyecto y la registran en skills-lock.json. Las instalaciones globales (-g) la ponen en ~/.agents/skills/<name> y la registran en ~/.agents/.skill-lock.json. Los agentes que leen .agents/skills usan esa copia directamente; para los agentes con su propia carpeta, como Claude Code (.claude/skills) o Hermes Agent (~/.hermes/skills), la CLI crea un enlace a ella.

¿Cómo sé si mis habilidades están al día?

Correr npx skills@latest check -g para las skills globales, o npx skills@latest check -p dentro de un proyecto. La CLI compara la huella de la carpeta de cada skill en tu archivo de bloqueo con la misma carpeta en origen y enumera cualquier skill que tenga una actualización, sin instalar nada. Desde la versión 1.7.5 (2 de noviembre de 2026), check solo informa; npx skills update instala. Ejecútalo desde una carpeta de proyecto o /tmp, no desde tu carpeta personal.

¿Por qué dice npx skills que todas las habilidades están al día cuando la comprobación falló?

Porque el resumen solo cuenta las actualizaciones que ha encontrado. Si el límite de GitHub de 60 solicitudes anónimas a la API por hora bloquea todas las consultas, la CLI imprime una línea ✗ por cada fuente y aun así puede terminar con “Todas las skills globales están al día”. Inicia sesión con gh auth login o configura un token de solo lectura GITHUB_TOKEN para subir el límite a 5.000 solicitudes por hora, actualiza con npx skills@latest, y lee siempre las líneas con ✗.

¿Debo usar sudo con npx skills?

No. Las skills se guardan por usuario, y root tiene su propia carpeta personal, así que sudo instala las skills en /root/.agents/skills, donde los agentes que se ejecutan como tu usuario normal nunca las ven. También puede dejar archivos propiedad de root en tus propias carpetas y provocar errores de npm como “prefix cannot be changed from project config” (no se puede cambiar el prefijo desde la configuración del proyecto). Ejecuta el CLI y tus agentes como tu usuario normal.

¿Cómo añado un servidor MCP a OpenCode?

Correr opencode mcp add <name> --url <address> para un servidor remoto, o opencode mcp add <name> -- <command> para uno local, y luego compruébalo con Lista de MCP de OpenCode. Añade --global para usarlo en todos los proyectos. Los mismos ajustes pueden estar en mcp.servers en opencode.jsonc, con los secretos escritos como {env:NAME}. Usa opencode mcp auth <name> para iniciar sesión, y /mcps dentro de una sesión para conectar o desconectar servidores.

¿Cuántos servidores MCP debería instalar?

Solo los que uses de verdad, normalmente dos o cinco. Las herramientas de cada servidor vienen con descripciones que el modelo tiene que leer, lo que consume contexto y puede hacer que las respuestas sean más lentas y menos centradas. Claude Code aplaza las definiciones de herramientas hasta que se necesitan y OpenCode las agrupa por servidor, lo que ayuda, pero los servidores sin usar siguen añadiendo riesgo y desorden. Elimina todo lo que no hayas usado en un mes.

¿Es seguro instalar habilidades de agente?

Tan seguras como su origen. Una skill son instrucciones que tu agente sigue con tus permisos, a menudo con scripts que ejecuta. El estudio de Snyk de febrero de 2026 sobre 3.984 skills públicas encontró fallos de seguridad en el 36,82% y confirmó cargas maliciosas en 76. Lee una skill y sus scripts antes de instalarla, prefiere las skills de los propios creadores de la herramienta, consulta los resultados de auditoría en skills.sh, fija las versiones y mantén las skills de terceros en “preguntar” en los permisos de tu agente.

¿Qué es skills-lock.json?

Es el archivo de bloqueo del proyecto que escribe el CLI de skills cuando instalas skills en un proyecto. Registra de dónde vino cada skill y una huella de sus archivos. Súbelo a Git: en otro ordenador, npx skills install restaura exactamente las mismas skills, y --frozen-lockfile da error si algo no coincide. Las skills globales tienen un archivo de bloqueo aparte en ~/.agents/.skill-lock.json, uno por cuenta de usuario.

¿Qué es skills.sh?

skills.sh es el directorio público de skills para agentes de Vercel. Ordena las skills por instalaciones, las agrupa por tema y muestra los resultados de auditoría de seguridad de Gen Agent Trust Hub, Socket y Snyk para cada una. Instalas skills desde él con el npx skills add owner/repo comando que muestra. El comando del propio CLI npx skills find busca en el directorio desde tu terminal.

Conclusión

Habilidades de agente y servidores MCP responden a dos preguntas distintas. Las skills responden a “¿cómo hacemos esto aquí?”: son tarjetas de recetas baratas y portátiles que solo se cargan cuando hacen falta. Los servidores MCP responden a “¿puedes llegar a ese sistema?”: son llaves potentes que consumen contexto y merecen el mismo cuidado que cualquier software que instales. AGENTS.md contiene las pocas reglas que se aplican a todo, y los permisos imponen lo que nunca debe ocurrir.

Si te llevas cinco cosas de esta guía, que sean estas:

  1. Pon las skills compartidas en .agents/skills y deja que npx skills las enlace a los agentes que buscan en otros sitios.
  2. Correr npx skills@latest check desde una carpeta de proyecto o /tmp, lee las líneas con ✗ y actualiza a conciencia.
  3. Inicia sesión en GitHub (gh auth login) en cada máquina que compruebe si hay actualizaciones.
  4. Nunca uses sudo con skills ni con agentes.
  5. Empieza con tres skills y un servidor, y añade más solo cuando una tarea real los necesite.

Las skills y los servidores convierten a un generalista ingenioso en un colega que conoce tu forma de trabajar y puede llegar a tus herramientas. El truco está en darle exactamente lo que necesita, y nada que no necesite.


¿Usas skills o servidores MCP que no haya mencionado? Me gustaría saber cuáles se han ganado un sitio permanente en tu configuración y qué mensajes de error te hicieron buscar. Las correcciones son bienvenidas: este artículo se actualiza cuando cambian las herramientas, lo que, a juzgar por este año, será a menudo.

Aviso: Ninguna empresa mencionada en este artículo lo patrocinó, lo revisó ni lo aprobó, y no contiene enlaces de afiliado. Los productos se nombran solo en el texto; las imágenes usan mis propios logos.

Última actualización: 15 de noviembre de 2026.

Añade tu señal.

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *

es_ESEspañol