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

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                    # Install exact versions from lockfile  
skilleton update                     # Refresh lockfile and reinstall
skilleton list [--format=table|json] # Show installed skills
skilleton describe <skill>           # Inspect metadata, install tree, SKILL.md header
skilleton validate                   # Check skill structure and security

List Command

The list command shows all installed skills with their repository, path, ref, and commit information. It supports two output formats:

Table format (default):

skilleton list
# ┌─────────┬───────────────────────┬───────────────────────────────────────┬───────────┬───────────┐
# │ (index) │ Name                  │ Repo                                  │ Path      │ Commit    │
# ├─────────┼───────────────────────┼───────────────────────────────────────┼───────────┼───────────┤
# │ 0       │ typescript-magician   │ https://github.com/mcollina/skills    │ skills/...│ 3e2ffbb   │
# │ 1       │ jest                  │ https://github.com/Mindrally/skills   │ jest      │ 47f47c1   │
# └─────────┴───────────────────────┴───────────────────────────────────────┴───────────┴───────────┘

JSON format (for scripts/parsing):

skilleton list --format=json
# [
#   {
#     "name": "typescript-magician",
#     "repo": "https://github.com/mcollina/skills",
#     "path": "skills/typescript-magician",
#     "ref": "3e2ffbb",
#     "commit": "3e2ffbb90fda9e31d84011c765252b00bfc2d4d6"
#   }
# ]

Describe Command

Use describe when you need rich details about a specific skill:

skilleton describe typescript-magician
# Name: typescript-magician
# Repo: https://github.com/mcollina/skills
# Path: skills/typescript-magician
# Ref: main
# Commit: 3e2ffbb90fda9e31d84011c765252b00bfc2d4d6
# Install path: .skilleton/skills/typescript-magician
#
# Folder structure:
#   README.md
#   SKILL.md
#   rules/
#   rules/rule.md
#
# SKILL.md header:
# ---
# name: typescript-magician
# description: ...
# ---

It falls back gracefully if the skill is missing from the manifest, not yet installed, or lacks a SKILL.md file.

Installation

npm install -g skilleton

# or run directly with npx
npx skilleton add <owner/skill[@ref]>

Acknowledgments

Special thanks to Brian and Giuseppe for their valuable insights that inspired the creation of Skilleton.

Privacy

No telemetry, no phone home. Skills are cached locally, manifests are yours to control.

License

MIT - see LICENSE