Skill Repo

What Is This?

Skill Repo solves the dependency management problem for Agent Skills — the portable instruction format used by Claude Code, Cursor, Gemini CLI, Codex, and other AI coding agents.

Today, skills are standalone folders. They can't declare dependencies, don't have versions, and break when shared across teams. Skill Repo fixes this by treating skills as npm packages with a pnpm-style content-addressable store.

Key Features

• 📦 Skills as npm packages — Each skill gets a package.json with a "skill": "SKILL.md" field
• 🔗 Dependency resolution — Skills can depend on other skills, resolved recursively
• 🏷️ Versioning — semver + content hash ([email protected])
• ⛓️ Chain triggering — ## Dependent Skills table auto-appended to each SKILL.md
• 💾 Content-addressable store — pnpm-style dedup, same content stored once
• 🖥️ Multi-platform install — Hard-link to .claude/skills/, .cursor/skills/, etc.
• 🔄 Incremental reinstall — Only reprocess changed skills (~4.6x faster)

How It Works

┌─────────────────────────────────────────────────┐
│  Your Project                                   │
│  package.json:                                  │
│    dependencies:                                │
│      "@skills/brainstorming": "^1.0.0"          │
│      "@skills/tdd": "^2.0.0"                    │
│                                                 │
│  $ skillmodule install --platform claude          │
│                                                 │
│  .skills/                                       │
│  ├── .content-store/                            │
│  │   ├── [email protected]/SKILL.md     │
│  │   ├── [email protected]/SKILL.md               │
│  │   └── [email protected]/SKILL.md        │
│  ├── brainstorming/SKILL.md  → hardlink         │
│  └── tdd/SKILL.md            → hardlink         │
│                                                 │
│  .claude/skills/                                │
│  ├── brainstorming/SKILL.md  → hardlink         │
│  └── tdd/SKILL.md            → hardlink         │
└─────────────────────────────────────────────────┘

Each installed SKILL.md gets a ## Dependent Skills table appended, enabling chain triggering — agents can discover and load transitive dependencies automatically.

Quick Start

# Install CLI
pnpm install && pnpm build

# Init a skill → generates package.json from SKILL.md
skillmodule init ./my-skill

# Batch init all skills
skillmodule init --all ./skills

# Install skill tree (after npm/pnpm install of dependencies)
skillmodule install

# Install + link to Claude Code
skillmodule install --platform claude

# View dependency tree
skillmodule tree

# Validate skill format
skillmodule validate ./my-skill

# Publish to npm
skillmodule publish ./my-skill

Project Structure

skill-repo/
├── skills/                 # 14 Agent Skills (from superpowers)
│   ├── brainstorming/
│   ├── test-driven-development/
│   ├── systematic-debugging/
│   └── ...
├── src/                    # skillmodule CLI source
│   ├── commands/           # init, install, publish, tree, validate
│   ├── core/               # Parser, resolver, hasher, rewriter, store, installer
│   └── types/              # TypeScript type definitions
├── tests/                  # 47 unit tests + benchmarks
├── examples/               # 5 scenario examples
└── docs/                   # Design documentation

CLI Commands

| Command | Description | |---------|-------------| | skillmodule init [dir] | Generate package.json from SKILL.md frontmatter | | skillmodule install | Resolve deps → hash → rewrite → store → link | | skillmodule publish [dir] | Publish skill package to npm | | skillmodule tree | Visualize dependency tree | | skillmodule validate [dir] | Validate skill package format |

See the CLI section below for full documentation.

Examples

| Example | Scenario | |---------|----------| | basic | Single skill init + validate | | monorepo | Layered dependencies with dedup | | duplicate-name | Same name under different scopes | | multi-version | Multiple versions coexisting | | platform-install | Multi-platform hard-link install |

Design

The full design document is at docs/skill-package-manager-design.md, covering:

• Core architecture and content-addressable store
• package.json skill field specification
• Version + hash strategy (pnpm-inspired)
• Dependency resolution and cycle detection
• SKILL.md rewrite rules for chain triggering
• Multi-platform installation with parent-directory gate
• Incremental install via lock file

References

• superpowers — Agentic skills framework with chain skill invocation
• dingtalk-workspace-cli — Skill installation to platform directories
• Agent Skills spec — SKILL.md format standard
• pnpm — Content-addressable storage and dependency management

License

MIT