skills-package-manager 0.1.1

package/README.md

@@ -0,0 +1,105 @@
+# skills-pm
+
+Core library and CLI for managing agent skills.
+
+## CLI Usage
+
+### `skills add`
+
+Add skills to your project.
+
+```bash
+# Interactive — clone repo, discover skills, select via multiselect prompt
+skills add owner/repo
+skills add https://github.com/owner/repo
+
+# Non-interactive — add a specific skill by name
+skills add owner/repo --skill find-skills
+
+# Direct specifier — skip discovery
+skills add https://github.com/owner/repo.git#path:/skills/my-skill
+skills add file:./local-source#path:/skills/my-skill
+```
+
+#### How it works
+
+When given `owner/repo` or a GitHub URL:
+
+1. Shallow-clones the repository into a temp directory
+2. Scans for `SKILL.md` files (checks root, then `skills/`, `.agents/skills/`, etc.)
+3. Presents an interactive multiselect prompt (powered by [@clack/prompts](https://github.com/bombshell-dev/clack))
+4. Writes selected skills to `skills.json` and resolves `skills-lock.yaml`
+5. Cleans up the temp directory
+
+### `skills install`
+
+Install all skills declared in `skills.json`:
+
+```bash
+skills install
+```
+
+This resolves each skill from its specifier, materializes it into `installDir` (default `.agents/skills/`), and creates symlinks for each `linkTarget`.
+
+## Programmatic API
+
+```typescript
+import { addCommand, installCommand, listRepoSkills } from 'skills-pm'
+
+// Add a skill
+await addCommand({
+  cwd: process.cwd(),
+  specifier: 'vercel-labs/skills',
+  skill: 'find-skills',
+})
+
+// Install all skills from skills.json
+await installCommand({ cwd: process.cwd() })
+
+// List skills in a GitHub repo (clone + scan)
+const skills = await listRepoSkills('vercel-labs', 'skills')
+// => [{ name: 'find-skills', description: '...', path: '/skills/find-skills' }]
+```
+
+## Specifier Format
+
+```
+<source>#[ref&]path:<skill-path>
+```
+
+| Part | Description | Example |
+|------|-------------|---------|
+| `source` | Git URL or `file:` path | `https://github.com/o/r.git`, `file:./local` |
+| `ref` | Optional git ref | `main`, `v1.0.0`, `HEAD` |
+| `path` | Path to skill directory within source | `/skills/my-skill` |
+
+### Resolution Types
+
+- **`git`** — Clones the repo, resolves commit hash, copies skill files
+- **`file`** — Reads from local filesystem, computes content digest
+
+## Architecture
+
+```
+src/
+├── bin/           # CLI entry points (skills-pm, skills)
+├── cli/           # CLI runner and interactive prompts
+├── commands/      # add, install command implementations
+├── config/        # skills.json / skills-lock.yaml read/write
+├── github/        # Git clone + skill discovery (listSkills)
+├── install/       # Skill materialization, linking, pruning
+├── specifiers/    # Specifier parsing and normalization
+└── utils/         # Hashing, filesystem helpers
+```
+
+## Build
+
+```bash
+pnpm build    # Builds with Rslib (ESM output + DTS)
+```
+
+## Test
+
+```bash
+pnpm test     # Runs tests with Rstest
+```

package/dist/113.js

@@ -0,0 +1,355 @@
+import { cp as promises_cp, lstat, mkdir, mkdtemp, readFile, readdir, rm as promises_rm, symlink, writeFile } from "node:fs/promises";
+import node_path from "node:path";
+import yaml from "yaml";
+import { createHash } from "node:crypto";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { tmpdir } from "node:os";
+async function readSkillsLock(rootDir) {
+    const filePath = node_path.join(rootDir, 'skills-lock.yaml');
+    try {
+        const raw = await readFile(filePath, 'utf8');
+        return yaml.parse(raw);
+    } catch (error) {
+        if ('ENOENT' === error.code) return null;
+        throw error;
+    }
+}
+async function readSkillsManifest(rootDir) {
+    const filePath = node_path.join(rootDir, 'skills.json');
+    try {
+        const raw = await readFile(filePath, 'utf8');
+        const json = JSON.parse(raw);
+        return {
+            installDir: json.installDir ?? '.agents/skills',
+            linkTargets: json.linkTargets ?? [],
+            skills: json.skills ?? {}
+        };
+    } catch (error) {
+        if ('ENOENT' === error.code) return null;
+        throw error;
+    }
+}
+function parseSpecifier(specifier) {
+    const firstHashIndex = specifier.indexOf('#');
+    const secondHashIndex = firstHashIndex >= 0 ? specifier.indexOf('#', firstHashIndex + 1) : -1;
+    if (secondHashIndex >= 0) throw new Error('Invalid specifier: multiple # fragments are not supported');
+    const hashIndex = firstHashIndex;
+    const sourcePart = hashIndex >= 0 ? specifier.slice(0, hashIndex) : specifier;
+    const fragment = hashIndex >= 0 ? specifier.slice(hashIndex + 1) : '';
+    if (!sourcePart) throw new Error('Specifier source is required');
+    if (!fragment) return {
+        sourcePart,
+        ref: null,
+        path: ''
+    };
+    const parts = fragment.split('&').filter(Boolean);
+    let ref = null;
+    let parsedPath = '';
+    for (const part of parts){
+        if (part.startsWith('path:')) {
+            parsedPath = part.slice(5);
+            continue;
+        }
+        if (null === ref) ref = part;
+    }
+    return {
+        sourcePart,
+        ref,
+        path: parsedPath
+    };
+}
+function normalizeSpecifier(specifier) {
+    const parsed = parseSpecifier(specifier);
+    const type = parsed.sourcePart.startsWith('file:') ? 'file' : parsed.sourcePart.startsWith('npm:') ? 'npm' : 'git';
+    const skillPath = parsed.path || '/';
+    const skillName = node_path.posix.basename(skillPath);
+    const normalized = parsed.ref ? `${parsed.sourcePart}#${parsed.ref}&path:${skillPath}` : parsed.path ? `${parsed.sourcePart}#path:${skillPath}` : parsed.sourcePart;
+    return {
+        type,
+        source: parsed.sourcePart,
+        ref: parsed.ref,
+        path: skillPath,
+        normalized,
+        skillName
+    };
+}
+function sha256(content) {
+    return `sha256-${createHash('sha256').update(content).digest('hex')}`;
+}
+const execFileAsync = promisify(execFile);
+async function resolveGitCommit(url, ref) {
+    const target = ref ?? 'HEAD';
+    const { stdout } = await execFileAsync('git', [
+        'ls-remote',
+        url,
+        target
+    ]);
+    const line = stdout.trim().split('\n')[0];
+    const commit = line?.split('\t')[0]?.trim();
+    if (!commit) throw new Error(`Unable to resolve git ref ${target} for ${url}`);
+    return commit;
+}
+async function createLockEntry(cwd, specifier) {
+    const normalized = normalizeSpecifier(specifier);
+    if ('file' === normalized.type) {
+        const sourceRoot = node_path.resolve(cwd, normalized.source.slice(5));
+        return {
+            skillName: normalized.skillName,
+            entry: {
+                specifier: normalized.normalized,
+                resolution: {
+                    type: 'file',
+                    path: sourceRoot
+                },
+                digest: sha256(`${sourceRoot}:${normalized.path}`)
+            }
+        };
+    }
+    if ('git' === normalized.type) {
+        const commit = await resolveGitCommit(normalized.source, normalized.ref);
+        return {
+            skillName: normalized.skillName,
+            entry: {
+                specifier: normalized.normalized,
+                resolution: {
+                    type: 'git',
+                    url: normalized.source,
+                    commit,
+                    path: normalized.path
+                },
+                digest: sha256(`${normalized.source}:${commit}:${normalized.path}`)
+            }
+        };
+    }
+    throw new Error(`Unsupported specifier type in 0.1.0 core flow: ${normalized.type}`);
+}
+async function syncSkillsLock(cwd, manifest, existingLock) {
+    const nextSkills = {};
+    for (const specifier of Object.values(manifest.skills)){
+        const { skillName, entry } = await createLockEntry(cwd, specifier);
+        nextSkills[skillName] = entry;
+    }
+    return {
+        lockfileVersion: '0.1',
+        installDir: manifest.installDir ?? '.agents/skills',
+        linkTargets: manifest.linkTargets ?? [],
+        skills: nextSkills
+    };
+}
+async function writeSkillsLock(rootDir, lockfile) {
+    const filePath = node_path.join(rootDir, 'skills-lock.yaml');
+    await writeFile(filePath, yaml.stringify(lockfile), 'utf8');
+}
+async function writeSkillsManifest(rootDir, manifest) {
+    const filePath = node_path.join(rootDir, 'skills.json');
+    const nextManifest = {
+        installDir: manifest.installDir ?? '.agents/skills',
+        linkTargets: manifest.linkTargets ?? [],
+        skills: manifest.skills
+    };
+    await writeFile(filePath, `${JSON.stringify(nextManifest, null, 2)}\n`, 'utf8');
+}
+async function addCommand(options) {
+    const normalized = normalizeSpecifier(options.specifier);
+    const existingManifest = await readSkillsManifest(options.cwd) ?? {
+        installDir: '.agents/skills',
+        linkTargets: [],
+        skills: {}
+    };
+    const existing = existingManifest.skills[normalized.skillName];
+    if (existing && existing !== normalized.normalized) throw new Error(`Skill ${normalized.skillName} already exists with a different specifier`);
+    existingManifest.skills[normalized.skillName] = normalized.normalized;
+    await writeSkillsManifest(options.cwd, existingManifest);
+    const existingLock = await readSkillsLock(options.cwd);
+    const lockfile = await syncSkillsLock(options.cwd, existingManifest, existingLock);
+    await writeSkillsLock(options.cwd, lockfile);
+    return {
+        skillName: normalized.skillName,
+        specifier: normalized.normalized
+    };
+}
+async function ensureDir(dirPath) {
+    await mkdir(dirPath, {
+        recursive: true
+    });
+}
+async function replaceSymlink(target, linkPath) {
+    await promises_rm(linkPath, {
+        recursive: true,
+        force: true
+    });
+    await symlink(target, linkPath);
+}
+async function writeJson(filePath, value) {
+    await writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+}
+async function linkSkill(rootDir, installDir, linkTarget, skillName) {
+    const absoluteTarget = node_path.join(rootDir, installDir, skillName);
+    const absoluteLink = node_path.join(rootDir, linkTarget, skillName);
+    await ensureDir(node_path.dirname(absoluteLink));
+    await replaceSymlink(absoluteTarget, absoluteLink);
+}
+async function readInstallState(rootDir) {
+    const filePath = node_path.join(rootDir, '.agents/skills/.skills-pm-install-state.json');
+    try {
+        return JSON.parse(await readFile(filePath, 'utf8'));
+    } catch  {
+        return null;
+    }
+}
+async function writeInstallState(rootDir, value) {
+    const dirPath = node_path.join(rootDir, '.agents/skills');
+    await ensureDir(dirPath);
+    const filePath = node_path.join(dirPath, '.skills-pm-install-state.json');
+    await writeJson(filePath, value);
+}
+async function materializeLocalSkill(rootDir, skillName, sourceRoot, sourcePath, installDir) {
+    const relativeSkillPath = sourcePath.replace(/^\//, '');
+    const absoluteSkillPath = node_path.join(sourceRoot, relativeSkillPath);
+    const skillDocPath = node_path.join(absoluteSkillPath, 'SKILL.md');
+    let skillDoc = '';
+    try {
+        skillDoc = await readFile(skillDocPath, 'utf8');
+    } catch  {
+        throw new Error(`Invalid skill at ${absoluteSkillPath}: missing SKILL.md`);
+    }
+    if (!skillDoc) throw new Error(`Invalid skill at ${absoluteSkillPath}: missing SKILL.md`);
+    const targetDir = node_path.join(rootDir, installDir, skillName);
+    await ensureDir(node_path.dirname(targetDir));
+    await promises_cp(absoluteSkillPath, targetDir, {
+        recursive: true,
+        force: true
+    });
+    await writeJson(node_path.join(targetDir, '.skills-pm.json'), {
+        name: skillName,
+        installedBy: 'skills-pm',
+        version: '0.1.0'
+    });
+}
+const materializeGitSkill_execFileAsync = promisify(execFile);
+async function materializeGitSkill(rootDir, skillName, repoUrl, commit, sourcePath, installDir) {
+    const checkoutRoot = await mkdtemp(node_path.join(tmpdir(), 'skills-pm-git-checkout-'));
+    try {
+        await materializeGitSkill_execFileAsync('git', [
+            'clone',
+            '--depth',
+            '1',
+            repoUrl,
+            checkoutRoot
+        ]);
+        if (commit && 'HEAD' !== commit) await materializeGitSkill_execFileAsync('git', [
+            'checkout',
+            commit
+        ], {
+            cwd: checkoutRoot
+        });
+        const skillDocPath = node_path.join(checkoutRoot, sourcePath.replace(/^\//, ''), 'SKILL.md');
+        await readFile(skillDocPath, 'utf8');
+        await materializeLocalSkill(rootDir, skillName, checkoutRoot, sourcePath, installDir);
+    } finally{
+        await promises_rm(checkoutRoot, {
+            recursive: true,
+            force: true
+        });
+    }
+}
+async function isManagedSkillDir(dirPath) {
+    try {
+        const marker = JSON.parse(await readFile(node_path.join(dirPath, '.skills-pm.json'), 'utf8'));
+        return marker?.installedBy === 'skills-pm';
+    } catch  {
+        return false;
+    }
+}
+async function pruneManagedSkills(rootDir, installDir, linkTargets, wantedSkillNames) {
+    const wanted = new Set(wantedSkillNames);
+    const absoluteInstallDir = node_path.join(rootDir, installDir);
+    try {
+        const entries = await readdir(absoluteInstallDir);
+        for (const entry of entries){
+            if (entry.startsWith('.')) continue;
+            const skillDir = node_path.join(absoluteInstallDir, entry);
+            if (await isManagedSkillDir(skillDir)) {
+                if (!wanted.has(entry)) {
+                    await promises_rm(skillDir, {
+                        recursive: true,
+                        force: true
+                    });
+                    for (const linkTarget of linkTargets){
+                        const linkPath = node_path.join(rootDir, linkTarget, entry);
+                        try {
+                            const stat = await lstat(linkPath);
+                            if (stat.isSymbolicLink() || stat.isDirectory() || stat.isFile()) await promises_rm(linkPath, {
+                                recursive: true,
+                                force: true
+                            });
+                        } catch  {}
+                    }
+                }
+            }
+        }
+    } catch  {}
+}
+function extractSkillPath(specifier, skillName) {
+    const marker = '#path:';
+    const index = specifier.indexOf(marker);
+    if (index >= 0) return specifier.slice(index + marker.length);
+    return `/${skillName}`;
+}
+async function installSkills(rootDir) {
+    const manifest = await readSkillsManifest(rootDir);
+    if (!manifest) return {
+        status: 'skipped',
+        reason: 'manifest-missing'
+    };
+    const currentLock = await readSkillsLock(rootDir);
+    const lockfile = await syncSkillsLock(rootDir, manifest, currentLock);
+    await writeSkillsLock(rootDir, lockfile);
+    const lockDigest = sha256(JSON.stringify(lockfile));
+    const state = await readInstallState(rootDir);
+    if (state?.lockDigest === lockDigest) return {
+        status: 'skipped',
+        reason: 'up-to-date'
+    };
+    const installDir = manifest.installDir ?? '.agents/skills';
+    const linkTargets = manifest.linkTargets ?? [];
+    await pruneManagedSkills(rootDir, installDir, linkTargets, Object.keys(lockfile.skills));
+    for (const [skillName, entry] of Object.entries(lockfile.skills)){
+        if ('file' === entry.resolution.type) await materializeLocalSkill(rootDir, skillName, entry.resolution.path, extractSkillPath(entry.specifier, skillName), installDir);
+        else if ('git' === entry.resolution.type) await materializeGitSkill(rootDir, skillName, entry.resolution.url, entry.resolution.commit, entry.resolution.path, installDir);
+        else throw new Error(`Unsupported resolution type in 0.1.0 core flow: ${entry.resolution.type}`);
+        for (const linkTarget of linkTargets)await linkSkill(rootDir, installDir, linkTarget, skillName);
+    }
+    await writeInstallState(rootDir, {
+        lockDigest,
+        installDir,
+        linkTargets,
+        installerVersion: '0.1.0',
+        installedAt: new Date().toISOString()
+    });
+    return {
+        status: 'installed',
+        installed: Object.keys(lockfile.skills)
+    };
+}
+async function installCommand(options) {
+    return installSkills(options.cwd);
+}
+async function runCli(argv) {
+    const [, , command, ...rest] = argv;
+    const cwd = process.cwd();
+    if ('add' === command) {
+        const specifier = rest[0];
+        if (!specifier) throw new Error('Missing required specifier');
+        return addCommand({
+            cwd,
+            specifier
+        });
+    }
+    if ('install' === command) return installCommand({
+        cwd
+    });
+    throw new Error(`Unknown command: ${command}`);
+}
+export { addCommand, installCommand, runCli };

package/dist/bin/skills-pm.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { runCli } from "../113.js";
+runCli(process.argv).catch((error)=>{
+    console.error(error instanceof Error ? error.message : error);
+    process.exitCode = 1;
+});

package/dist/bin/skills.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { runCli } from "../113.js";
+runCli(process.argv).catch((error)=>{
+    console.error(error instanceof Error ? error.message : error);
+    process.exitCode = 1;
+});

package/dist/index.js

@@ -0,0 +1 @@
+export { addCommand, installCommand, runCli } from "./113.js";

package/dist/src/bin/skills-pm.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/bin/skills.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/cli/runCli.d.ts

@@ -0,0 +1,16 @@
+export declare function runCli(argv: string[]): Promise<{
+    skillName: string;
+    specifier: string;
+} | {
+    readonly status: "skipped";
+    readonly reason: "manifest-missing";
+    readonly installed?: undefined;
+} | {
+    readonly status: "skipped";
+    readonly reason: "up-to-date";
+    readonly installed?: undefined;
+} | {
+    readonly status: "installed";
+    readonly installed: string[];
+    readonly reason?: undefined;
+}>;

package/dist/src/commands/add.d.ts

@@ -0,0 +1,5 @@
+import type { AddCommandOptions } from '../config/types';
+export declare function addCommand(options: AddCommandOptions): Promise<{
+    skillName: string;
+    specifier: string;
+}>;

package/dist/src/commands/install.d.ts

@@ -0,0 +1,15 @@
+export declare function installCommand(options: {
+    cwd: string;
+}): Promise<{
+    readonly status: "skipped";
+    readonly reason: "manifest-missing";
+    readonly installed?: undefined;
+} | {
+    readonly status: "skipped";
+    readonly reason: "up-to-date";
+    readonly installed?: undefined;
+} | {
+    readonly status: "installed";
+    readonly installed: string[];
+    readonly reason?: undefined;
+}>;

package/dist/src/config/readSkillsLock.d.ts

@@ -0,0 +1,2 @@
+import type { SkillsLock } from './types';
+export declare function readSkillsLock(rootDir: string): Promise<SkillsLock | null>;

package/dist/src/config/readSkillsManifest.d.ts

@@ -0,0 +1,2 @@
+import type { SkillsManifest } from './types';
+export declare function readSkillsManifest(rootDir: string): Promise<SkillsManifest | null>;

package/dist/src/config/syncSkillsLock.d.ts

@@ -0,0 +1,2 @@
+import type { SkillsLock, SkillsManifest } from './types';
+export declare function syncSkillsLock(cwd: string, manifest: SkillsManifest, existingLock: SkillsLock | null): Promise<SkillsLock>;

package/dist/src/config/types.d.ts

@@ -0,0 +1,43 @@
+export type SkillsManifest = {
+    $schema?: string;
+    installDir?: string;
+    linkTargets?: string[];
+    skills: Record<string, string>;
+};
+export type NormalizedSpecifier = {
+    type: 'git' | 'file' | 'npm';
+    source: string;
+    ref: string | null;
+    path: string;
+    normalized: string;
+    skillName: string;
+};
+export type SkillsLockEntry = {
+    specifier: string;
+    resolution: {
+        type: 'file';
+        path: string;
+    } | {
+        type: 'git';
+        url: string;
+        commit: string;
+        path: string;
+    } | {
+        type: 'npm';
+        packageName: string;
+        version: string;
+        path: string;
+        integrity?: string;
+    };
+    digest: string;
+};
+export type SkillsLock = {
+    lockfileVersion: '0.1';
+    installDir: string;
+    linkTargets: string[];
+    skills: Record<string, SkillsLockEntry>;
+};
+export type AddCommandOptions = {
+    cwd: string;
+    specifier: string;
+};

package/dist/src/config/writeSkillsLock.d.ts

@@ -0,0 +1,2 @@
+import type { SkillsLock } from './types';
+export declare function writeSkillsLock(rootDir: string, lockfile: SkillsLock): Promise<void>;

package/dist/src/config/writeSkillsManifest.d.ts

@@ -0,0 +1,2 @@
+import type { SkillsManifest } from './types';
+export declare function writeSkillsManifest(rootDir: string, manifest: SkillsManifest): Promise<void>;

package/dist/src/index.d.ts

@@ -0,0 +1,3 @@
+export { addCommand } from './commands/add';
+export { installCommand } from './commands/install';
+export { runCli } from './cli/runCli';

package/dist/src/install/installSkills.d.ts

@@ -0,0 +1,13 @@
+export declare function installSkills(rootDir: string): Promise<{
+    readonly status: "skipped";
+    readonly reason: "manifest-missing";
+    readonly installed?: undefined;
+} | {
+    readonly status: "skipped";
+    readonly reason: "up-to-date";
+    readonly installed?: undefined;
+} | {
+    readonly status: "installed";
+    readonly installed: string[];
+    readonly reason?: undefined;
+}>;

package/dist/src/install/installState.d.ts

@@ -0,0 +1,2 @@
+export declare function readInstallState(rootDir: string): Promise<any>;
+export declare function writeInstallState(rootDir: string, value: unknown): Promise<void>;

package/dist/src/install/links.d.ts

@@ -0,0 +1 @@
+export declare function linkSkill(rootDir: string, installDir: string, linkTarget: string, skillName: string): Promise<void>;

package/dist/src/install/materializeGitSkill.d.ts

@@ -0,0 +1 @@
+export declare function materializeGitSkill(rootDir: string, skillName: string, repoUrl: string, commit: string, sourcePath: string, installDir: string): Promise<void>;

package/dist/src/install/materializeLocalSkill.d.ts

@@ -0,0 +1 @@
+export declare function materializeLocalSkill(rootDir: string, skillName: string, sourceRoot: string, sourcePath: string, installDir: string): Promise<void>;

package/dist/src/install/pruneManagedSkills.d.ts

@@ -0,0 +1 @@
+export declare function pruneManagedSkills(rootDir: string, installDir: string, linkTargets: string[], wantedSkillNames: string[]): Promise<void>;

package/dist/src/specifiers/normalizeSpecifier.d.ts

@@ -0,0 +1,2 @@
+import type { NormalizedSpecifier } from '../config/types';
+export declare function normalizeSpecifier(specifier: string): NormalizedSpecifier;

package/dist/src/specifiers/parseSpecifier.d.ts

@@ -0,0 +1,5 @@
+export declare function parseSpecifier(specifier: string): {
+    sourcePart: string;
+    ref: string | null;
+    path: string;
+};

package/dist/src/utils/fs.d.ts

@@ -0,0 +1,4 @@
+export declare function ensureDir(dirPath: string): Promise<void>;
+export declare function replaceDir(from: string, to: string): Promise<void>;
+export declare function replaceSymlink(target: string, linkPath: string): Promise<void>;
+export declare function writeJson(filePath: string, value: unknown): Promise<void>;

package/dist/src/utils/hash.d.ts

@@ -0,0 +1 @@
+export declare function sha256(content: string): string;

package/dist/test/add.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/install.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/manifest.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/specifiers.test.d.ts

@@ -0,0 +1 @@
+export {};