ATHEORY.AI
← Back to Writing

Skillex beyond Node: packs and a universal install

Skillex started in Node. The model worked. Packs and a universal install carry it into the rest of the polyglot world we actually work in — with Go as the first proof the resolver model travels.

Jeremy Harper

Skillex started with a deliberately narrow target. Node packages, npm dependency graphs, monorepo workspaces — the ecosystem where the package-management problem we were trying to solve was loudest, and where the cost of getting it wrong was easiest to measure in tokens. Pick the loudest version of the problem, prove the model works there, then expand.

The model works. We’ve been running it ourselves on everything from small single-package repos to very large monorepos, and teams outside of ATHEORY are starting to try it on their own projects with the same shape of results. Packages are shipping skillex/public and skillex/private skill exports. Agents are getting the right slice of guidance on the first query instead of grovelling through directory trees. The properties we said we’d deliver if you let us own indexing — determinism, version-correctness, scoped retrieval — they show up on every refresh, whether the repo is a single library or a multi-team workspace with thousands of files.

But almost no real codebase is Node-only. Our own environment runs Skillex itself in Go, the website pipeline in Node, deployment tooling in shell, parts of the agent runtime in something else again. Lock the value at the npm boundary and you’ve shipped a tool that only works in half the rooms it needs to work in — including the room where Skillex itself is being built.

So this release is the bridge. Skillex is no longer a Node package skill indexer. It’s a polyglot project utility with a single distribution format — packs — that any ecosystem can adopt, and the install paths to match. The internal resolver model is now language-agnostic; Go is the first ecosystem we’ve added native support for, mostly to prove out the abstraction on a codebase we know intimately. It won’t be the last.

Packs, briefly

A pack is a skillex/pack.yaml manifest plus its skill files. The manifest declares which skills exist, what activates them (files present, dependencies declared, detectors firing), and what scope each one applies to. Refresh picks the manifests up, evaluates the activation rules against your repo, and indexes the resulting skills individually.

That sentence describes three distribution channels at once. Repos can commit a project-local pack at skillex/pack.yaml. Packages can ship skillex/pack.yaml alongside the existing skillex/public and skillex/private directories. Go modules can ship the same file inside their module tree, and the new Go resolver will find them through go.mod boundaries without touching the network or mutating module state. Same format, three places it can live.

Here’s a minimal project pack — a single Docker skill that activates when there’s a Dockerfile in the repo:

name: docker
version: 1.0.0
description: Docker guidance for repositories with Dockerfiles.

detectors:
  docker:
    matches:
      - file:
          path: Dockerfile
      - file:
          path: Dockerfile.*

skills:
  - file: docker.md
    activate-when:
      detector: docker
    scope: subtree

And the same format used by a published package, activating its skills whenever it’s a declared dependency in some boundary:

name: "@acme/foo"
version: 1.0.0
skills:
  - file: usage.md
    activate-when:
      dependency-declared:
        - source: npm-package
          name: "@acme/foo"
    scope: boundary

There are six scope strategies, four activation conditions, and a small extensible detector registry. The full schema, the table of every scope, and the activation reference live in the Skillex README. The point isn’t to enumerate them here — it’s that one file format covers “project conventions,” “library guidance,” and “framework knowledge” without any of them needing a different mechanism.

Universal install

Same release, install whichever way fits the repo:

# Standalone binary — recommended, works in any repo
curl -fsSL https://raw.githubusercontent.com/atheory-ai/skillex/main/install.sh | sh

# Pin as a dev dependency in a Node project
npm install --save-dev @atheory-ai/skillex
# or: pnpm add -D @atheory-ai/skillex
# or: yarn add -D @atheory-ai/skillex

# Install via the Go toolchain
go install github.com/atheory-ai/skillex/cmd/skillex@latest

Each path resolves to the same binary. The npm path uses npm’s optionalDependencies mechanism so only the binary for your platform downloads. The go install path is the first non-npm install option that produces a Skillex CLI matching the published release. The shell installer is what we recommend on hosts where Skillex is a platform utility rather than a per-project tool.

Native polyglot support, starting with Go

Go is the first ecosystem we built native resolver support for. It was the obvious test case: Skillex itself is written in Go, so we get to drink our own coffee while we prove the abstraction. The resolver reads go.mod, walks dependency boundaries, and finds module-shipped skillex/pack.yaml files in the resolved module roots. It respects replace directives. It picks up vendor-ed modules. It does none of this over the network — it works against whatever modules are already available locally. Same indexing pass, same SQLite registry, same query interface. From the agent’s side, asking “what skills apply to internal/auth/handler.go?” looks identical to asking the same question about a TypeScript file.

There’s a satisfying loop in this one. Skillex is built in Go, and now the Skillex repo itself can be driven by Skillex — repo conventions, the resolver’s non-obvious behavior in internal/, contributor guidance for the indexing pipeline, the testing playbook for new resolvers. We’ve been using it mostly on our Node projects up to this point; the team building Skillex now gets the same agent experience we’ve been shipping to everyone else, on the codebase that produces it.

The work also generalised. The scanner now treats Node and Go as two implementations of one resolver interface. Adding the next ecosystem — Python, Rust, Ruby — is incremental rather than rewriting the world, which is the bit that matters more than which language we picked second.

What this means for existing projects

If you’re already running Skillex against a Node repo: nothing changes. The skillex/public and skillex/private directories still work exactly as before. Existing rules in your skillex.json still resolve the same way. Refresh produces the same indexed catalog you’ve been querying.

What you get for free, when you upgrade:

  • The option to commit a project-local pack at skillex/pack.yaml for repo-wide skills that activate on file or dependency conditions instead of hard-coded paths.
  • Detectors as a richer alternative to file globs. detector: docker reads better in a manifest than the glob equivalent and survives ecosystem drift.
  • The ability to add a Go module to the same repo and have its skills indexed alongside the Node skills.

If you’re authoring a library — Node or Go — and you’ve been hoping for a way to ship skills alongside your code without your consumers having to find and copy a docs directory, this is that. Drop a skillex/pack.yaml in your published artifact and Skillex will index it on the consumer side at refresh time.

Where to go from here

  • README — installation, configuration, the full pack schema, and the activation/scope reference tables.
  • CHANGELOG — every change in this release, including the detector registry details and the Go fixture coverage.
  • Skillex on npm — the dev-dependency install path.
  • Skillex on GitHub — releases, issues, the install script source.

Skillex is open source under the same terms as the rest of ATHEORY.AI. If you want it to support an ecosystem we haven’t tackled yet, open an issue. The resolver interface is genuinely extensible — that was the point of generalising the scanner — and we’d rather merge a community resolver than build every one of them ourselves.