@stefafafan/skm 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 stefafafan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,130 @@
+# skm
+
+`skm` is a package manager of [Agent Skills](https://agentskills.io), supporting both project and global-level skills.
+
+> [!WARNING]
+> This package is in beta. There may be breaking changes.
+
+## Motivation
+
+Agent Skills are convenient, but there are 2 points to consider:
+
+1. Which version skill did I just download? How should I update them?
+2. People make skills with different naming conventions--should I rename them?
+
+`skm` solves these problems by storing metadata of installed skills and having the ability to alias skills with your favorite names.
+
+## Installation
+
+### Globally
+
+```bash
+npm install -g @stefafafan/skm
+```
+
+### Run Directly
+
+```bash
+npx @stefafafan/skm
+```
+
+## Setup
+
+### For projects
+
+Initialize a project with `skills.json` and `skills.lock.json`
+
+```bash
+skm init --project
+```
+
+Add your favorite skills.
+
+```bash
+skm add https://github.com/stefafafan/skills --project
+```
+
+Rename a skill locally if you prefer a different key name.
+
+```bash
+skm rename pin-github-actions gha-pinner --project
+```
+
+Add and commit your files.
+
+```bash
+git add skills.json skills.lock.json
+git commit
+```
+
+### For global settings
+
+Basically the same, but with `--global`
+
+```bash
+skm init --global
+```
+
+```bash
+skm add stefafafan/skills --global
+```
+
+```bash
+skm list --global
+```
+
+## Commands
+
+Call `help` subcommand for more information.
+
+```bash
+skm help
+```
+
+Show help for specific subcommands.
+
+```bash
+skm help add
+```
+
+## Supported source formats
+
+Currently this tool assumes the skills are on GitHub.
+
+```bash
+# Installing a skill in a specific path.
+skm add https://github.com/stefafafan/skills/tree/main/skills/pin-github-actions
+
+# Installing all skills in a repository (shorthand)
+skm add stefafafan/skills
+
+# Installing all skills in a repository (full URL)
+skm add https://github.com/stefafafan/skills
+```
+
+Repository-wide imports discover every nested directory containing `SKILL.md`.
+
+## Metadata files used
+
+The following files are used by `skm`
+
+- `skills.json`
+  - user-facing intent
+- `skills.lock.json`
+  - resolved commit hash and integrity data
+- `.skm/`
+  - internal state and stored contents
+- `.agents/skills/`
+  - the derived skills
+
+The intended manifest-first flow is:
+
+1. Change `skills.json` with `skm` commands or by editing it directly.
+2. Run `skm install --project`.
+3. Let `skills.lock.json` and `.agents/skills/` reconcile automatically.
+
+It is recommended to add the following to `.gitignore`
+
+```sh
+.skm
+```

package/dist/src/cli.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_1 = require("./index");
+void (0, index_1.main)(process.argv.slice(2)).then((code) => {
+    process.exitCode = code;
+});

package/dist/src/commands/add.js

@@ -0,0 +1,149 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runAddCommand = runAddCommand;
+const promises_1 = require("node:fs/promises");
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+const errors_1 = require("../errors");
+const hash_1 = require("../hash");
+const manifest_1 = require("../manifest");
+const scope_1 = require("../scope");
+const source_1 = require("../source");
+const store_1 = require("../store");
+const materialize_1 = require("../materialize");
+const fs_1 = require("../fs");
+async function runAddCommand(options) {
+    const scope = await (0, scope_1.resolveScope)({
+        cwd: options.cwd,
+        homeDir: options.homeDir,
+        xdgConfigHome: options.xdgConfigHome,
+        explicitScope: options.scope,
+    });
+    const manifest = await (0, manifest_1.readManifest)(scope.manifestPath);
+    const lockfile = await (0, manifest_1.readLockfile)(scope.lockfilePath);
+    const parsedSource = (0, source_1.parseSource)(options.source);
+    const requestedRef = options.requestedRef ?? (0, source_1.defaultRequestedRef)(parsedSource);
+    const tempRoot = await (0, promises_1.mkdtemp)(node_path_1.default.join(node_os_1.default.tmpdir(), "skm-add-"));
+    try {
+        if (parsedSource.kind === "github-repo") {
+            if (options.canonicalName) {
+                throw new errors_1.SkmError("--as is not supported for repo-wide imports", 2);
+            }
+            const checkedOut = await (0, source_1.checkoutSourceRepo)({
+                source: parsedSource,
+                requestedRef,
+                githubBaseUrl: options.githubBaseUrl,
+            }, tempRoot);
+            const discoveredSkills = await (0, source_1.discoverSkillsInRepo)(checkedOut.checkoutDir);
+            if (discoveredSkills.length === 0) {
+                throw new errors_1.SkmError(`No skills found in repository ${options.source}`, 4);
+            }
+            const seenCanonicalNames = new Set();
+            for (const discoveredSkill of discoveredSkills) {
+                if (seenCanonicalNames.has(discoveredSkill.canonicalName)) {
+                    throw new errors_1.SkmError(`Duplicate canonical name discovered: ${discoveredSkill.canonicalName}`, 5);
+                }
+                seenCanonicalNames.add(discoveredSkill.canonicalName);
+            }
+            const strategy = options.strategy ?? "wrap";
+            const addedSkills = [];
+            for (const discoveredSkill of discoveredSkills) {
+                const integrity = await (0, hash_1.hashDirectory)(discoveredSkill.absoluteDir);
+                const storeDir = await (0, store_1.storeSkill)(scope.storeDir, discoveredSkill.absoluteDir, integrity);
+                const canonicalSource = (0, source_1.canonicalTreeUrl)(parsedSource, requestedRef, discoveredSkill.relativeDir);
+                manifest.skills[discoveredSkill.canonicalName] = {
+                    source: canonicalSource,
+                    requested: requestedRef,
+                    strategy,
+                };
+                lockfile.skills[discoveredSkill.canonicalName] = {
+                    resolved: checkedOut.resolved,
+                    integrity,
+                };
+                await (0, materialize_1.materializeSkill)({
+                    canonicalName: discoveredSkill.canonicalName,
+                    sourceDir: storeDir,
+                    generatedSkillsDir: scope.generatedSkillsDir,
+                    manifestSource: options.source,
+                    resolved: checkedOut.resolved,
+                    strategy,
+                });
+                addedSkills.push({
+                    name: discoveredSkill.canonicalName,
+                    status: "added",
+                    source: canonicalSource,
+                    requested: requestedRef,
+                    resolved: checkedOut.resolved,
+                });
+            }
+            await (0, manifest_1.writeManifest)(scope.manifestPath, manifest);
+            await (0, manifest_1.writeLockfile)(scope.lockfilePath, lockfile);
+            return {
+                kind: "summary",
+                command: "add",
+                scope: scope.kind,
+                summary: `Added ${discoveredSkills.length} skill(s) to ${scope.kind} scope`,
+                details: [
+                    { label: "source", value: options.source },
+                    { label: "requested", value: requestedRef },
+                ],
+                skills: addedSkills,
+            };
+        }
+        const fetched = await (0, source_1.fetchSkillToTempDir)({
+            source: parsedSource,
+            requestedRef,
+            githubBaseUrl: options.githubBaseUrl,
+        }, tempRoot);
+        const integrity = await (0, hash_1.hashDirectory)(fetched.skillDir);
+        const storeDir = await (0, store_1.storeSkill)(scope.storeDir, fetched.skillDir, integrity);
+        const canonicalName = options.canonicalName ?? parsedSource.defaultName;
+        const strategy = options.strategy ?? "wrap";
+        manifest.skills[canonicalName] = {
+            source: options.source,
+            requested: requestedRef,
+            strategy,
+        };
+        lockfile.skills[canonicalName] = {
+            resolved: fetched.resolved,
+            integrity,
+        };
+        await (0, manifest_1.writeManifest)(scope.manifestPath, manifest);
+        await (0, manifest_1.writeLockfile)(scope.lockfilePath, lockfile);
+        await (0, materialize_1.materializeSkill)({
+            canonicalName,
+            sourceDir: storeDir,
+            generatedSkillsDir: scope.generatedSkillsDir,
+            manifestSource: options.source,
+            resolved: fetched.resolved,
+            strategy,
+        });
+        return {
+            kind: "summary",
+            command: "add",
+            scope: scope.kind,
+            summary: `Added ${canonicalName} to ${scope.kind} scope`,
+            details: [
+                { label: "source", value: options.source },
+                { label: "requested", value: requestedRef },
+                { label: "strategy", value: strategy },
+            ],
+            skills: [
+                {
+                    name: canonicalName,
+                    status: "added",
+                    source: options.source,
+                    requested: requestedRef,
+                    resolved: fetched.resolved,
+                    integrity,
+                },
+            ],
+        };
+    }
+    finally {
+        await (0, fs_1.removeIfExists)(tempRoot);
+    }
+}

package/dist/src/commands/init.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runInitCommand = runInitCommand;
+const manifest_1 = require("../manifest");
+const scope_1 = require("../scope");
+async function runInitCommand(options) {
+    const scope = options.scope === "global"
+        ? await (0, scope_1.resolveScope)({
+            cwd: options.cwd,
+            homeDir: options.homeDir,
+            xdgConfigHome: options.xdgConfigHome,
+            explicitScope: "global",
+        })
+        : await (0, scope_1.resolveScope)({
+            cwd: options.cwd,
+            homeDir: options.homeDir,
+            xdgConfigHome: options.xdgConfigHome,
+            explicitScope: "project",
+            allowCreateProject: true,
+        });
+    await (0, manifest_1.initManifest)(scope.manifestPath, options.force);
+    await (0, manifest_1.initLockfile)(scope.lockfilePath, options.force);
+    return {
+        kind: "summary",
+        command: "init",
+        scope: scope.kind,
+        summary: `Initialized ${scope.kind} manifest at ${scope.manifestPath}`,
+        details: [
+            { label: "manifest", value: scope.manifestPath },
+            { label: "lockfile", value: scope.lockfilePath },
+        ],
+    };
+}

package/dist/src/commands/inspect.js

@@ -0,0 +1,58 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runInspectCommand = runInspectCommand;
+const node_path_1 = __importDefault(require("node:path"));
+const errors_1 = require("../errors");
+const manifest_1 = require("../manifest");
+const scope_1 = require("../scope");
+async function runInspectCommand(options) {
+    const scope = await (0, scope_1.resolveScope)({
+        cwd: options.cwd,
+        homeDir: options.homeDir,
+        xdgConfigHome: options.xdgConfigHome,
+        explicitScope: options.scope,
+    });
+    const manifest = await (0, manifest_1.readManifest)(scope.manifestPath);
+    const lockfile = await (0, manifest_1.readLockfile)(scope.lockfilePath);
+    const entry = (0, manifest_1.mergeSkillState)(manifest, lockfile)[options.canonicalName];
+    if (!entry) {
+        throw new errors_1.SkmError(`Skill ${options.canonicalName} not found in ${scope.kind} scope`, 1);
+    }
+    let overriddenByProjectSkill = "no";
+    if (scope.kind === "global") {
+        const projectRoot = await (0, scope_1.findProjectRoot)(options.cwd);
+        if (projectRoot) {
+            try {
+                const projectManifest = await (0, manifest_1.readManifest)((0, scope_1.projectScope)(projectRoot).manifestPath);
+                if (projectManifest.skills[options.canonicalName]) {
+                    overriddenByProjectSkill = "yes";
+                }
+            }
+            catch {
+                overriddenByProjectSkill = "no";
+            }
+        }
+    }
+    return {
+        kind: "inspect",
+        name: options.canonicalName,
+        scope: scope.kind,
+        details: [
+            { label: "canonical local name", value: options.canonicalName },
+            { label: "scope", value: scope.kind },
+            { label: "source", value: entry.source },
+            { label: "requested ref", value: entry.requested ?? "" },
+            { label: "resolved commit", value: entry.resolved ?? "" },
+            { label: "integrity hash", value: entry.integrity ?? "" },
+            {
+                label: "materialized path",
+                value: node_path_1.default.join(scope.generatedSkillsDir, options.canonicalName),
+            },
+            { label: "strategy", value: entry.strategy ?? "wrap" },
+            { label: "overridden by project skill", value: overriddenByProjectSkill },
+        ],
+    };
+}

package/dist/src/commands/install.js

@@ -0,0 +1,114 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runInstallCommand = runInstallCommand;
+const promises_1 = require("node:fs/promises");
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+const errors_1 = require("../errors");
+const fs_1 = require("../fs");
+const hash_1 = require("../hash");
+const materialize_1 = require("../materialize");
+const manifest_1 = require("../manifest");
+const scope_1 = require("../scope");
+const source_1 = require("../source");
+const store_1 = require("../store");
+async function runInstallCommand(options) {
+    const scope = await (0, scope_1.resolveScope)({
+        cwd: options.cwd,
+        homeDir: options.homeDir,
+        xdgConfigHome: options.xdgConfigHome,
+        explicitScope: options.scope,
+    });
+    const manifest = await (0, manifest_1.readManifest)(scope.manifestPath);
+    const lockfile = await (0, manifest_1.readLockfile)(scope.lockfilePath);
+    const tempRoot = await (0, promises_1.mkdtemp)(node_path_1.default.join(node_os_1.default.tmpdir(), "skm-install-"));
+    const reconciledSkills = [];
+    try {
+        for (const name of Object.keys(lockfile.skills)) {
+            if (!(name in manifest.skills)) {
+                delete lockfile.skills[name];
+                await (0, fs_1.removeIfExists)(node_path_1.default.join(scope.generatedSkillsDir, name));
+            }
+        }
+        for (const [canonicalName, entry] of Object.entries(manifest.skills)) {
+            let lockEntry = lockfile.skills[canonicalName];
+            const parsedSource = (0, source_1.parseSource)(entry.source);
+            const requestedRef = entry.requested ?? (0, source_1.defaultRequestedRef)(parsedSource);
+            if (!lockEntry) {
+                const fetched = await (0, source_1.fetchSkillToTempDir)({
+                    source: parsedSource,
+                    requestedRef,
+                    githubBaseUrl: options.githubBaseUrl,
+                }, tempRoot);
+                const integrity = await (0, hash_1.hashDirectory)(fetched.skillDir);
+                const storedPath = await (0, store_1.storeSkill)(scope.storeDir, fetched.skillDir, integrity);
+                lockEntry = {
+                    resolved: fetched.resolved,
+                    integrity,
+                };
+                lockfile.skills[canonicalName] = lockEntry;
+                await (0, materialize_1.materializeSkill)({
+                    canonicalName,
+                    sourceDir: storedPath,
+                    generatedSkillsDir: scope.generatedSkillsDir,
+                    manifestSource: entry.source,
+                    resolved: lockEntry.resolved,
+                    strategy: entry.strategy ?? "wrap",
+                });
+                reconciledSkills.push({
+                    name: canonicalName,
+                    status: "installed",
+                    source: entry.source,
+                    requested: requestedRef,
+                    resolved: lockEntry.resolved,
+                    integrity,
+                });
+                continue;
+            }
+            const integrity = lockEntry.integrity;
+            let materialSource = (0, store_1.storePath)(scope.storeDir, integrity);
+            if (!(await (0, fs_1.pathExists)(materialSource))) {
+                const fetched = await (0, source_1.fetchSkillToTempDir)({
+                    source: parsedSource,
+                    requestedRef: lockEntry.resolved,
+                    githubBaseUrl: options.githubBaseUrl,
+                }, tempRoot);
+                const actualIntegrity = await (0, hash_1.hashDirectory)(fetched.skillDir);
+                if (actualIntegrity !== integrity) {
+                    throw new errors_1.SkmError(`Integrity mismatch for ${canonicalName}: expected ${integrity}, got ${actualIntegrity}`, 4);
+                }
+                materialSource = await (0, store_1.storeSkill)(scope.storeDir, fetched.skillDir, integrity);
+            }
+            await (0, materialize_1.materializeSkill)({
+                canonicalName,
+                sourceDir: materialSource,
+                generatedSkillsDir: scope.generatedSkillsDir,
+                manifestSource: entry.source,
+                resolved: lockEntry.resolved,
+                strategy: entry.strategy ?? "wrap",
+            });
+            reconciledSkills.push({
+                name: canonicalName,
+                status: "installed",
+                source: entry.source,
+                requested: requestedRef,
+                resolved: lockEntry.resolved,
+                integrity,
+            });
+        }
+        await (0, manifest_1.writeLockfile)(scope.lockfilePath, lockfile);
+        return {
+            kind: "summary",
+            command: "install",
+            scope: scope.kind,
+            summary: `Installed ${Object.keys(manifest.skills).length} skill(s) for ${scope.kind} scope`,
+            skills: reconciledSkills,
+        };
+    }
+    finally {
+        await (0, fs_1.removeIfExists)(tempRoot);
+    }
+}

package/dist/src/commands/list.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runListCommand = runListCommand;
+const manifest_1 = require("../manifest");
+const scope_1 = require("../scope");
+async function runListCommand(options) {
+    const listedSkills = await collectSkills(options);
+    const projectNames = new Set(listedSkills.filter((skill) => skill.scope === "project").map((skill) => skill.name));
+    const rows = listedSkills.map((skill) => ({
+        name: skill.name,
+        scope: skill.scope,
+        source: skill.entry.source,
+        requested: skill.entry.requested,
+        resolved: skill.entry.resolved,
+        effective: skill.scope === "global" && projectNames.has(skill.name) ? "overridden" : "active",
+    }));
+    return {
+        kind: "list",
+        all: options.all,
+        rows,
+    };
+}
+async function collectSkills(options) {
+    if (!options.all) {
+        const scope = await (0, scope_1.resolveScope)({
+            cwd: options.cwd,
+            homeDir: options.homeDir,
+            xdgConfigHome: options.xdgConfigHome,
+            explicitScope: options.scope,
+        });
+        const manifest = await (0, manifest_1.readManifest)(scope.manifestPath);
+        const lockfile = await (0, manifest_1.readLockfile)(scope.lockfilePath);
+        return Object.entries((0, manifest_1.mergeSkillState)(manifest, lockfile)).map(([name, entry]) => ({
+            name,
+            scope: scope.kind,
+            entry,
+        }));
+    }
+    const homeDir = options.homeDir ?? process.env.HOME;
+    const projectRoot = await (0, scope_1.findProjectRoot)(options.cwd);
+    const manifests = [];
+    if (homeDir) {
+        const global = (0, scope_1.globalScope)(homeDir, options.xdgConfigHome);
+        manifests.push({
+            scope: "global",
+            manifestPath: global.manifestPath,
+            lockfilePath: global.lockfilePath,
+        });
+    }
+    if (projectRoot) {
+        const project = (0, scope_1.projectScope)(projectRoot);
+        manifests.push({
+            scope: "project",
+            manifestPath: project.manifestPath,
+            lockfilePath: project.lockfilePath,
+        });
+    }
+    const rows = [];
+    for (const manifestTarget of manifests) {
+        try {
+            const manifest = await (0, manifest_1.readManifest)(manifestTarget.manifestPath);
+            const lockfile = await (0, manifest_1.readLockfile)(manifestTarget.lockfilePath);
+            for (const [name, entry] of Object.entries((0, manifest_1.mergeSkillState)(manifest, lockfile))) {
+                rows.push({ name, scope: manifestTarget.scope, entry });
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    return rows.sort((left, right) => left.name.localeCompare(right.name) || left.scope.localeCompare(right.scope));
+}

package/dist/src/commands/remove.js

@@ -0,0 +1,36 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runRemoveCommand = runRemoveCommand;
+const node_path_1 = __importDefault(require("node:path"));
+const errors_1 = require("../errors");
+const fs_1 = require("../fs");
+const manifest_1 = require("../manifest");
+const scope_1 = require("../scope");
+async function runRemoveCommand(options) {
+    const scope = await (0, scope_1.resolveScope)({
+        cwd: options.cwd,
+        homeDir: options.homeDir,
+        xdgConfigHome: options.xdgConfigHome,
+        explicitScope: options.scope,
+    });
+    const manifest = await (0, manifest_1.readManifest)(scope.manifestPath);
+    const lockfile = await (0, manifest_1.readLockfile)(scope.lockfilePath);
+    if (!(options.canonicalName in manifest.skills)) {
+        throw new errors_1.SkmError(`Skill ${options.canonicalName} not found in ${scope.kind} scope`, 1);
+    }
+    delete manifest.skills[options.canonicalName];
+    delete lockfile.skills[options.canonicalName];
+    await (0, manifest_1.writeManifest)(scope.manifestPath, manifest);
+    await (0, manifest_1.writeLockfile)(scope.lockfilePath, lockfile);
+    await (0, fs_1.removeIfExists)(node_path_1.default.join(scope.generatedSkillsDir, options.canonicalName));
+    return {
+        kind: "summary",
+        command: "remove",
+        scope: scope.kind,
+        summary: `Removed ${options.canonicalName} from ${scope.kind} scope`,
+        skills: [{ name: options.canonicalName, status: "removed" }],
+    };
+}