Skillex

The Problem

Agent skills are broken in two ways: delivery and maintenance.

The discovery problem

You've written the guidance: repo conventions, API patterns, migration notes, dev workflows. Maybe they're in CLAUDE.md, AGENTS.md, cursor rules, or scattered markdown files. The content might even be good.

But the agent still has to find it.

Discovery burns context. The agent reads through every skill file looking for what's relevant. In a project with dozens of guides across multiple packages, that's thousands of tokens spent on content that doesn't apply to what the developer is actually working on.

Discovery is non-deterministic. The agent decides what looks relevant based on its own judgment. Ask the same question twice, get different context loaded. Different context means different answers. You can't reproduce the behavior. You can't debug it.

Discovery loads the wrong things. Skills meant for package contributors end up in consumer context. Migration guides for v1 get loaded when you're on v3. Repo-wide conventions dilute package-specific guidance. The more skills you add, the worse the signal-to-noise ratio gets.

The irony: the more effort you put into writing skills, the harder it becomes for the agent to use them well.

The maintenance problem

Skills today are detached from the code they describe.

You write a usage guide for your library. A consumer copies it into their CLAUDE.md. You release a new version with breaking changes. Their guide is now wrong, and nobody knows.

Multiply that across every package, every consumer, every version. Skills get copy-pasted between repos, between teams, between projects. They fork immediately and drift forever. There's no mechanism to update them. There's no way to know they're stale.

For package publishers, it's even worse. You want to give your users great agent context: API patterns, migration paths, gotchas. But there's no way to deliver it. You can put a markdown file in your repo and hope someone finds it. You can write documentation and hope someone copies the relevant parts. But you can't ship skills with your package so they arrive automatically when someone installs it.

The result: every team rebuilds the same guidance from scratch, maintains it in isolation, and watches it rot.

The Workarounds Make It Worse

Teams are smart. They see these problems and try to solve them. But the solutions create their own overhead.

Tables of contents. You organize skills into groups with index files: a top-level file that lists categories, each category links to sub-topics, each sub-topic links to the actual guidance. You're essentially publishing a book: chapters, sections, indices, hoping the agent navigates the tree correctly and lands on the right page.

Except now you're maintaining the structure on top of maintaining the content. Every time you add a skill, you update the index. Every time you reorganize, you rebuild the tree. And the agent still has to parse the hierarchy, follow the right links, and make judgment calls about which branch to take. One wrong turn and it loads the wrong context anyway.

Shared Git repos. The index files get complex enough that you put them in a dedicated repository. The skills collection becomes its own project. Teams across the organization pull it into their repos as a submodule, a copied directory, or a manual sync.

Now you have a coordination problem. Is everyone on the same version? Did someone update the collection last week and forget to notify downstream? Is the team working on the checkout feature using the same skills as the team working on the payment feature? When the collection updates, who pulls it? Who validates it still works?

You're manually managing dependencies. Think about that. You're versioning, distributing, and synchronizing shared code artifacts across projects by hand. This is the exact problem package managers solved decades ago. But for skills, teams are back to copying tarballs and hoping for the best.

The table of contents approach doesn't scale because it's still discovery at runtime. You just made the discovery path more structured. The shared repo approach doesn't scale because it's manual dependency management without any of the tooling that makes dependency management work.

What actually works is what the software ecosystem already figured out: publish skills with the package, resolve them through the dependency graph, and scope them automatically.

What Skillex Does

Skillex moves skill resolution from runtime to build time.

skillex refresh scans your project, resolves your dependencies, discovers their skill exports, applies scope rules, and builds a SQLite index. Every skill is tagged with its topics, its scope, its source package, and its visibility.

At runtime, the agent doesn't browse. It queries.

skillex query --path packages/app-a/src/auth.ts --topic error-handling

One call. Returns exactly the skills that apply to that file, that topic, that context. No browsing. No guessing. No context pollution.

The right skills. Nothing else.

Skills That Travel With Your Code

Skillex solves the maintenance problem by making skills part of the package itself.

If you publish a library, you can now ship agent skills alongside your code. Add "skillex": true to your package.json and drop Markdown files in skillex/public/ and skillex/private/. When someone installs your package, your skills arrive with it, automatically discovered, automatically scoped, automatically versioned.

No more hoping consumers find your docs. No more writing migration guides that never reach the people who need them. Your skills are in the package.

my-package/
  package.json            ← "skillex": true
  skillex/
    public/
      usage.md
      usage.test.md
      migrations.md
      migrations.test.md
    private/
      architecture.md
      architecture.test.md

Public skills are for consumers: API patterns, configuration guides, migration notes. They're linked when someone depends on your package. The consumer never copies them. They never go stale. They're always the version that matches the installed code.

Private skills are for maintainers: architecture decisions, build workflows, testing conventions. They're linked when someone is working inside your source tree. Contributors get the right context without you maintaining a separate onboarding doc.

The scoping is automatic. You declare what's public and what's private. Skillex determines which to serve based on the developer's context. A consumer working in app-a/src/auth.ts gets your public skills. A contributor working in my-package/src/ gets your private skills. Never mixed up. Never the wrong audience.

Version-correct by default

Install @acme/foo@2.3.1, get the skills that shipped with 2.3.1. Upgrade to 3.0.0, get the new skills, including the migration guide for the upgrade you just made. Automatically.

In monorepos where different workspaces depend on different versions of the same package, each workspace gets skills for its resolved version. No conflicts. No manual management. No stale copies.

The copy-paste era is over. Skills update when packages update. The source of truth lives with the code. Everyone consuming the package gets the same, correct guidance, always.

Stay in Control

Skills shape your agent's behavior. As agent-driven development grows, so does the surface area of what's influencing your AI. You need to know what's in there and have granular control over it.

Full visibility. skillex doctor shows every skill in your system: where it came from, what scope it applies to, whether it has tests, whether it has proper metadata. You see the complete picture.

Controlled ingestion. External skills come through skillex get, which fetches, runs a safety review checking for prompt injection, file manipulation, and exfiltration, and vendors skills into your repo. You inspect and approve before anything enters your system.

Scoped delivery. Rules in skillex.yaml determine which skills apply to which paths. You control what context your agents receive. Narrow it, broaden it, remove it. The agent only sees what you've explicitly scoped.

Testable. Every skill has a co-located .test.md file with validation scenarios. skillex test validate checks structure in CI. Agents self-evaluate against the scenarios at runtime. Skills that stop producing correct guidance get caught.

Auditable. The registry is a SQLite database, a deterministic build artifact. Same repo state, same index. Vendor skills are committed to the repo with source URLs tracked in frontmatter. You can diff every change.

Confidence comes from knowing exactly what skills are active, what they're telling your agents, and whether they're still accurate. Skillex gives you that.

How It Works

1. Initialize

skillex init

Detects your project structure, creates scope rules, sets up the registry, and writes an AGENTS.md section that teaches your agent how to query skillex. Interactive setup with sensible defaults.

2. Refresh

skillex refresh

Scans dependencies, discovers skill exports via package.json, resolves versions, applies scope rules, and builds .skillex/index.db. Everything indexed. Everything queryable. Deterministic and offline.

3. Query

skillex query --path packages/app-a/src/auth.ts
skillex query --topic migration --tags breaking-change
skillex query --package @acme/foo --format content

Filter by file path, topic, tag, or package. Flags compose as intersection. Returns full content or metadata summaries. The agent gets exactly what it needs in one call.

4. Serve

Three interface layers, same registry:

MCP Server — skillex mcp exposes skills as resources and query as a typed tool. Native integration for Cursor, Claude Code, and other MCP-capable harnesses. The agent discovers skills through the protocol itself.

CLI — JSON output to stdout, diagnostics to stderr. Every agent harness can run shell commands.

AGENTS.md — Auto-generated manifest with available scopes, topics, tags, and query examples. MCP-first instructions with CLI fallback. The agent reads it once and knows how to use skillex.

Skill Testing

Every skill has a co-located test file:

# Tests: usage.md

## Validation: Basic API usage
Prompt: "How do I initialize the client?"
Success criteria:
  - Response references the Client constructor
  - Response includes the required config object
  - Response does not expose internal implementation

skillex test validate checks structure: are tests present, well-formed, properly paired? The agent checks behavior: does the skill actually produce correct guidance? Both run in CI.

skillex refresh --check
skillex test validate --check

Two commands. Two CI gates. Catch regressions before they reach developers.

Import External Skills Safely

skillex get https://github.com/someone/react-patterns

Fetches, reviews for safety, converts to skillex format, and vendors into skillex/vendor/. Source tracked in frontmatter. Committed to your repo. Auditable.

skillex import ./legacy-rules/ --batch

Same pipeline for local files. Migrate Cursor rules, Windsurf rules, or any existing markdown guidance into managed, tested, queryable skills.

No more unmanaged copy-paste. Everything goes through the pipeline.

Works for Every Node.js Project

Single package repos — Scope skills, test them, query them instantly. Even without a monorepo, you get structured skill management and the end of context pollution.

Monorepos — Where skillex shines brightest. Dependency boundaries, workspace-aware scope rules, version-correct resolution across pnpm, yarn, and npm workspaces. Different workspaces, different versions, correct skills everywhere.

Package publishers — Ship skills alongside your code. Your consumers get context that's always accurate for the version they installed. No separate documentation to maintain. No guides that drift from the implementation.

CLI

skillex init              # Bootstrap repo or package
skillex refresh           # Scan, link, build registry
skillex query             # Retrieve by path, topic, tag, package
skillex test validate     # Validate skill test structure
skillex get <url>         # Fetch and vendor external skills
skillex import <file>     # Import local files as skills
skillex doctor            # Full diagnostics and health check
skillex mcp               # Start MCP server

Single Go binary. macOS, Linux, Windows. Also available as an npm package.

Get Started

npm install -g skillex
skillex init
skillex refresh
skillex query --path src/index.ts

Or download the binary from releases.

Philosophy

Two things are broken with agent skills today. First: agents discover context by reading through everything, which is slow, non-deterministic, and gets worse as you add more skills. Second: skills are disconnected from the code they describe, so they're always being copied, always drifting, always stale somewhere.

Skillex fixes both. Skills are indexed at build time and served through structured queries. No browsing. Skills ship with packages and update when packages update. No copying.

The agent never browses. It asks for what it needs. And it gets exactly that, nothing more, nothing less.