8 Agent Skills y mi primer servidor MCP publicado en npm

🇺🇸 Read this post in English

Llevo meses haciendo que mi agente resuelva los mismos problemas una y otra vez porque nunca me tomé el tiempo de escribirlos una sola vez, bien, y dejar que otros los reusaran. Ese es exactamente el tipo de deuda técnica que nadie pone en un roadmap. Así que publiqué alpha-skills: ocho Agent Skills instalables y mi primer servidor MCP en npm.

Dónde están las skills publicadas

El catálogo instalable vive en skills/, separado en tres categorías: external/ para APIs de terceros, local/ para homelab y flujos de trabajo, y general/ para utilidades transversales. Las tres son públicas: una skill en external/, una en local/ y seis en general/. local/ describe su ámbito de uso.

skills/
├── external/
│   └── nextdns-api/SKILL.md
├── local/
│   └── progressive-search/SKILL.md
└── general/
    ├── agent-context-generator/SKILL.md
    ├── nestjs-iam-patterns/SKILL.md
    ├── nestjs-advanced-patterns/SKILL.md
    ├── nestjs-graphql/SKILL.md
    ├── tuning-claude-code/SKILL.md
    └── obsidian-second-brain/SKILL.md

Las ocho skills

Tres categorías: external/ para servicios de terceros, local/ para infraestructura de homelab y workflows propios, general/ para utilidades transversales que no dependen de ningún servicio en particular.

Cada comando instala una skill. Ejecuta el de la que necesites.

1. nextdns-api

Referencia completa de la API REST de NextDNS: perfiles, seguridad/privacidad/control parental, listas de bloqueo y permitidas, analíticas, logs de consultas. Es la que respalda al MCP server que describo más abajo.

npx skills add Alpha018/alpha-skills -s nextdns-api

2. progressive-search

El workflow de descubrimiento que uso todo el tiempo: preguntas de código van a CodeGraph, preguntas de documentación van a QMD, y si ninguno responde cae a grep/find. Mantiene un grafo en sesión de lo ya encontrado para no repetir búsquedas.

npx skills add Alpha018/alpha-skills -s progressive-search

3. agent-context-generator

Genera, refresca o audita el CLAUDE.md/AGENTS.md de un proyecto basado en lo que el repo realmente tiene: dependencias reales, estructura real, scripts reales. No en una plantilla genérica que asume un stack que no existe.

npx skills add Alpha018/alpha-skills -s agent-context-generator

4. nestjs-iam-patterns

Patrones de auth/authz en NestJS: JWT access/refresh, sesiones con Passport y Redis, API keys, RBAC, permisos granulares, ABAC, Google Sign-In, TOTP/2FA. Liderada por una guía de decisión: qué patrón le corresponde a tu situación, no un catálogo de todos ellos.

npx skills add Alpha018/alpha-skills -s nestjs-iam-patterns

5. nestjs-advanced-patterns

Internals avanzados de NestJS: tokens de DI explícitos e implícitos, módulos dinámicos, discovery en runtime, providers durables, worker threads, circuit breaker, WebSocket gateways, y una tabla de decisión para elegir transporter en microservicios (TCP, Redis, MQTT, NATS, RabbitMQ, Kafka, gRPC).

npx skills add Alpha018/alpha-skills -s nestjs-advanced-patterns

6. nestjs-graphql

Una sola skill que cubre code-first y schema-first en NestJS, con una tabla de decisión que enruta cada tarea a exactamente un archivo de referencia para que el agente nunca cargue las dos mitades a la vez. Cubre subscriptions con PubSub/Redis, el problema N+1 resuelto con DataLoader, guards tipados, límites de profundidad y costo de queries, y una sección de hardening de producción verificada contra el código fuente real de Apollo Server, no contra lo que yo recordaba de memoria.

npx skills add Alpha018/alpha-skills -s nestjs-graphql

7. tuning-claude-code

Diseña todo el stack de configuración de Claude Code para un repo: CLAUDE.md tratado como presupuesto de tokens, reglas por path, subagentes personalizados, hooks determinísticos, una lista de MCP podada, worktrees paralelos y CI headless.

npx skills add Alpha018/alpha-skills -s tuning-claude-code

8. obsidian-second-brain

Guía de decisión para llevar un vault de Obsidian como sistema de conocimiento que efectivamente dura. Evita la teatralidad de productividad y la sobrecarga de plugins, elige un organizador líder (carpetas PARA para trabajo de entrega, enlaces Zettelkasten para generación de ideas) y dice explícitamente cuándo Obsidian no es la herramienta correcta.

npx skills add Alpha018/alpha-skills -s obsidian-second-brain

El estilo que comparten las skills

Ninguna de las skills de general/ se planificó con un manual de estilo desde el día uno. Pero después de la cuarta, el patrón ya era imposible de ignorar:

• Guía de decisión, no lista de features. La skill no vuelca todo lo que sabe. Abre con una tabla o un procedimiento corto que elige la opción correcta para tu situación real, y dice sin rodeos cuándo la herramienta no es la indicada.
• Progressive disclosure. El SKILL.md se mantiene como un procedimiento delgado (bajo 500 líneas). El detalle profundo va a references/*.md, y el cuerpo le dice al agente exactamente cuándo cargar cada uno.
• Descripciones orientadas a trigger, con evals. El campo description del frontmatter es el de mayor apalancamiento: uno vago significa que la skill nunca se activa. Cada skill trae un evals/trigger-eval.json con casos de should-trigger y should-not-trigger.
• ASCII plano, sin tics de IA. Todo archivo persistido pasa por una revisión anti-IA antes de quedar.

El primer servidor MCP

@alpha018/nextdns-mcp es un servidor MCP stdio, corrido vía npx, que expone la API de NextDNS: leer y actualizar la configuración de un perfil, gestionar entradas de listas, tirar analíticas, leer logs. Está construido sobre la misma referencia que respalda a nextdns-api, así que las dos piezas se mantienen sincronizadas a propósito.

Publicación en npm: el problema de trusted publishing

Acá está la parte que me costó más de diez commits de CI entender bien.

@semantic-release/npm no soporta OIDC trusted publishing. Su paso verifyConditions exige un NPM_TOKEN o un .npmrc preconfigurado sin importar qué tenga id-token: write en el workflow. Ese permiso solo compra firma de provenance a través del plugin, no autenticación.

La arquitectura que terminó funcionando son dos workflows compartidos, generalizados sobre cualquier paquete en mcp-servers/* en lugar de un par de archivos por paquete:

1. Validar los paquetes en cada PR

Workflow: pr-test-mcp-servers.yml

Detecta qué directorios cambiaron y ejecuta lint, typecheck, build y test para cada paquete, en Node 22 y 24.

2. Versionar y publicar desde main

Workflow: build-publish-mcp-servers.yml

En cada push a main, por paquete modificado y dentro de un solo job:

1. Ejecutar build y test.
2. Ejecutar npx semantic-release con npmPublish: false: actualizar versión, changelog, tag y release, sin necesitar autenticación de npm.
3. Comparar la versión local recién actualizada con npm view <pkg> version.
4. Si difieren, ejecutar npm publish --provenance directamente con el CLI de npm.

La separación que resolvió el problema: semantic-release se encarga del versionado; el CLI de npm realiza la publicación con OIDC.

Cuatro errores que me costaron tiempo real

1. La primera publicación es manual. Un paquete nuevo en npm no puede bootstrapearse vía OIDC bajo ninguna circunstancia. La primera versión hay que publicarla a mano, con login real, antes de que el Trusted Publisher se pueda siquiera vincular en npmjs.com.

2. La ruta de bin importa. npm publish descarta en silencio cualquier bin que empiece con ./. "./dist/index.js" se cae con solo un warning; hay que escribir "dist/index.js".

3. El owner distingue mayúsculas. La verificación de provenance de npm compara repository.url contra el owner del claim de OIDC de forma sensible a mayúsculas. github.com/alpha018/... falló contra el casing real del owner, que es Alpha018.

4. El nombre del workflow debe coincidir. El Trusted Publisher de npm fija el nombre exacto del archivo del workflow. Renombrarlo sin actualizar esa entrada hace que npm firme la provenance sin problema y después rechace el PUT del publish con un E404 que es idéntico, en forma, al de "Trusted Publisher no configurado".

Cuándo esta configuración no compensa

Si publicas un solo paquete y no piensas agregar más, este andamiaje es sobreingeniería. Un workflow simple con NPM_TOKEN en un secret resuelve lo mismo en quince minutos y sin OIDC. La complejidad de los dos workflows compartidos se paga sola recién cuando aparece un segundo o tercer paquete — antes de eso, es tiempo que le resta a escribir la skill que en realidad importa.

Agregar un segundo servidor MCP ahora es trivial: solo necesita su propio package.json y su propio .releaserc.json, los workflows compartidos lo levantan solos. El trabajo de resolver esto bien una vez se paga en cada paquete nuevo que llega después.

Si alguna de estas ocho skills te resuelve algo que venías reescribiendo cada semana, el repo es github.com/Alpha018/alpha-skills. Y si prefieres la versión con más detalle todavía sobre alguna en particular, algunas ya tienen su propio post extendido en Buy Me a Coffee.

Gracias por leer hasta acá — si pruebas alguna, cuéntame qué se rompió, porque seguro algo se rompe. ¿Cuál de las ocho te resuelve más el día a día?

💌 Agradecimientos Especiales

A una chica que, sin saberlo, me empujó a seguir creando y programando en mi tiempo libre. A quien alguna vez fue mi chispa: para “YLP”, con gratitud… y con cicatrices que también enseñan.