8 Agent Skills and my first MCP server published to npm

🇪🇸 Leer este post en Español I spent months watching my agent re-solve the exact same problems, over and over, because I never sat down and wrote them up once so anyone else could reuse them. That's the kind of technical debt nobody ever puts on a roadmap. So I published alpha-skills: eight installable Agent Skills and my first MCP server on npm. Where the published skills live The installable catalog lives in skills/, split into three categories: external/ for third-party APIs, local/ for homelab and workflows, and general/ for cross-project utilities. All three are public: one skill in external/, one in local/, and six in general/. local/ describes the use case. 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 The eight skills Three categories: external/ for third-party services, local/ for homelab infrastructure and personal workflows, general/ for cross-cutting utilities that don't depend on any one service. Skill Category Use it for nextdns-api external NextDNS API progressive-search local Code and documentation search agent-context-generator general Project context nestjs-iam-patterns general Authentication and permissions nestjs-advanced-patterns general NestJS internals and architecture nestjs-graphql general Code-first and schema-first GraphQL tuning-claude-code general Claude Code configuration obsidian-second-brain general Note organization and review Each command installs one skill. Run the command for the one you need. 1. nextdns-api A full reference for the NextDNS REST API: profiles, security/privacy/parental-control settings, denylist and allowlist management, analytics, query logs. This is the one the MCP server below is built directly against. npx skills add Alpha018/alpha-skills -s nextdns-api 2. progressive-search The discovery workflow I run constantly: code questions go to CodeGraph, doc questions go to QMD, and it falls back to grep/find when neither answers. It keeps an in-session graph of what's already been found so it never repeats a search. npx skills add Alpha018/alpha-skills -s progressive-search 3. agent-context-generator Generates, refreshes, or audits a project's CLAUDE.md/AGENTS.md, grounded in what the repo actually contains: real dependencies, real folder structure, real scripts. Not a generic template that assumes a stack you don't have. npx skills add Alpha018/alpha-skills -s agent-context-generator 4. nestjs-iam-patterns Auth and authz patterns for NestJS: JWT access/refresh, session auth with Passport and Redis, API keys, RBAC, granular permissions, ABAC, Google Sign-In, TOTP/2FA. Led by a decision guide for which pattern fits your actual situation, not a catalog of all of them. npx skills add Alpha018/alpha-skills -s nestjs-iam-patterns 5. nestjs-advanced-patterns Advanced NestJS internals: explicit and implicit DI tokens, dynamic modules, runtime discovery, durable providers, worker threads, circuit breaker, WebSocket gateways, and a decision table for picking a microservice transporter across TCP, Redis, MQTT, NATS, RabbitMQ, Kafka, gRPC. npx skills add Alpha018/alpha-skills -s nestjs-advanced-patterns 6. nestjs-graphql One skill covering both code-first and schema-first GraphQL in NestJS, with a decision table that routes every task to exactly one reference file so the agent never loads both halves at once. It covers subscriptions with PubSub/Redis, the N+1 problem solved with DataLoader, typed guards, query depth and cost limits, and a production-hardening section verified against Apollo Server's actual source, not against what I remembered. npx skills add Alpha018/alpha-skills -s nestjs-graphql 7. tuning-claude-code Designs the whole Claude Code configuration stack for a repo: CLAUDE.md treated as a token budget, path-scoped rules, custom subagents, deterministic hooks, a pruned MCP list, parallel worktrees, and headless CI. npx skills add Alpha018/alpha-skills -s tuning-claude-code 8. obsidian-second-brain A decision guide for running an Obsidian vault as a knowledge system that actually survives contact with real use. It steers away from productivity theater and plugin overload, picks one lead organizer (PARA folders for delivery work, Zettelkasten links for idea generation), and states plainly when Obsidian is the wrong tool. npx skills add Alpha018/alpha-skills -s obsidian-second-brain The style these skills share None of the general/ skills started from a written style guide. But by the fourth one, the pattern was impossible to miss: Decision guide, not feature list. The skill doesn't dump everything it knows. It opens with a table or a short procedure that picks the right option for your actual situation, and says plainly when the tool is the wrong choice. Progressive disclosure. SKILL.md stays a lean procedure (under 500 lines). Deep material moves to references/*.md, and the body tells the agent exactly when to load each one. Trigger-oriented descriptions, with evals. The description frontmatter field is the highest-leverage one: a vague one means the skill silently never fires. Every skill ships an evals/trigger-eval.json with should-trigger and should-not-trigger cases. Plain ASCII, no AI tics. Every file that gets persisted goes through a de-AI pass before it lands. The first MCP server @alpha018/nextdns-mcp is a stdio MCP server, run through npx, that exposes the NextDNS API: reading and updating a profile's settings, managing list entries, pulling analytics, reading logs. It's built on the same reference doc that backs nextdns-api, so the two stay in sync on purpose. Publishing to npm: the trusted publishing problem This is the part that cost me more than ten CI commits to get right. @semantic-release/npm doesn't support OIDC trusted publishing. Its verifyConditions step demands an NPM_TOKEN or a preconfigured .npmrc no matter what id-token: write is set to in the workflow. That permission only buys provenance signing through the plugin — not authentication. What actually worked is two shared workflows, generalized across every package under mcp-servers/* instead of one file pair per package: 1. Validate packages on every PR Workflow: pr-test-mcp-servers.yml Detects which package directories changed and runs lint, typecheck, build and test for each package, across Node 22 and 24. 2. Version and publish from main Workflow: build-publish-mcp-servers.yml On every push to main, for each changed package, within a single job: Run build and test. Run npx semantic-release with npmPublish: false: update the version, changelog, tag and release, without requiring npm authentication. Compare the freshly updated local version with npm view version. If they differ, run npm publish --provenance directly through the npm CLI. The split that solved it: semantic-release handles versioning; the npm CLI handles publishing through OIDC. Four gotchas that cost real time The first publish is manual. A brand-new npm package can't bootstrap through OIDC under any circumstances. The first version has to be published by hand, with a real login, before the Trusted Publisher link can even be added on npmjs.com. The bin path matters. npm publish silently drops any bin path starting with ./. "./dist/index.js" gets dropped with only a warning — write "dist/index.js" instead. Owner casing matters. npm's provenance verification checks repository.url against the OIDC claim's owner case-sensitively. github.com/alpha018/... failed against the real owner casing, which is Alpha018. The workflow filename must match. npm's Trusted Publisher config pins the exact workflow filename. Rename the file without updating that entry and npm signs the provenance fine, then rejects the publish PUT with an E404 that looks identical, in shape, to "Trusted Publisher not configured". When this setup is not worth it If you're publishing a single package and have no plan to add a second one, this whole scaffold is overengineering. A plain workflow with NPM_TOKEN in a secret solves the same problem in fifteen minutes, no OIDC required. The two shared workflows only pay for themselves once a second or third package shows up — before that, they're just time you're not spending on the skill that actually matters. Adding a second MCP server now is trivial: it only needs its own package.json and its own .releaserc.json, and both shared workflows pick it up automatically. Solving this properly once pays off in every package that comes after. If any of these eight skills fixes something you've been rewriting every week, the repo is github.com/Alpha018/alpha-skills. And if you want the deeper version of any single one, some already have their own extended write-up on Buy Me a Coffee. Thanks for reading this far — if you try one out, tell me what broke, because something always does. Which of the eight would fix the most for your day-to-day? 💌 Special Acknowledgments To a girl who, without knowing it, pushed me to keep creating and coding in my free time. To the one who was once my spark: for "YLP", with gratitude... and with scars that also teach.