Skilleton

Deterministic AI skill dependency management for teams

Manage AI skills like npm packages - with project manifests, lockfiles, and reproducible installations.

Why this exists

• Keep skills with code – manifests + lockfiles are versioned right beside your source tree.
• Deterministic installs – CI and every teammate pull the exact same commits.
• Zero shared state – nothing lives in a global registry; installs happen from git.
• Privacy-first – no telemetry, no cloud calls, easy to audit.

Quickstart

# Add a skill to your project
skilleton add Mindrally/skills/jest

# Install all skills (like npm install)
skilleton install

# Team member gets exact same versions
git pull  # Gets skilleton.json + skilleton.lock.json
skilleton install  # Installs exact pinned versions

Skill input formats

Skilleton supports several ways to specify skills:

Root repository skills

For skills that live at the root of a repository:

skilleton add mhdcodes/react-query-skill
# => repo: https://github.com/mhdcodes/react-query-skill, path: .

Monorepo skills

For skills inside a monorepo, make the subpath explicit:

# Three-segment shorthand
skilleton add mindrally/skills/jest
# => repo: https://github.com/mindrally/skills, path: jest

# Longer paths in monorepos
skilleton add owner/monorepo/path/to/skill
# => repo: https://github.com/owner/monorepo, path: path/to/skill

# Explicit URL form
skilleton add https://github.com/owner/monorepo/path/to/skill
# => repo: https://github.com/owner/monorepo, path: path/to/skill

Note: Skilleton resolves skill refs via git ls-remote and requires a local git installation. It respects your local git credentials for private repositories.

How it works

skilleton.json (commit this):

{
  "skills": [
    {
      "name": "jest",
      "repo": "Mindrally/skills",
      "path": "jest",
      "ref": "47f47c1"
    }
  ]
}

skilleton.lock.json (commit this):

{
  "skills": {
    "jest": {
      "name": "jest",
      "repo": "Mindrally/skills",
      "path": "jest",
      "ref": "47f47c1",
      "commit": "abc123def456...",
      "timestamp": "2025-01-01T00:00:00Z"
    }
  }
}

And add the following to your .gitignore:

.skilleton/

Commands

skilleton add <owner/skill[@ref]>    # Add skill and update manifest
skilleton install                    # Reconcile lockfile with manifest, then install all skills
skilleton update                     # Refresh lockfile; reinstall only changed skills
skilleton list [--format=table|json] # Show installed skills
skilleton describe <skill>           # Inspect metadata, install tree, SKILL.md header
skilleton audit                      # Placeholder for future audit functionality

Programmatic usage

Skilleton can also be used from scripts via the package API:

import { createEnvironment, AddCommand, InstallCommand } from 'skilleton';

async function run() {
  const env = createEnvironment(process.cwd());

  const add = new AddCommand();
  await add.run(env, { positional: ['mindrally/skills/jest@main'], flags: {} });

  const install = new InstallCommand();
  await install.run(env, { positional: [], flags: {} });
}

run().catch((error) => {
  console.error(error);
  process.exit(1);
});

Lockfile behavior