skillpm 0.0.1 → 0.0.4

package/README.md

@@ -1,12 +1,12 @@
-# skillpm — npm for Agent Skills
+# skillpm — Package manager for Agent Skills. Built on npm.
 
 [![npm](https://img.shields.io/npm/v/skillpm)](https://www.npmjs.com/package/skillpm)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Docs](https://img.shields.io/badge/docs-skillpm.dev-blue)](https://skillpm.dev)
 
-The [Agent Skills spec](https://agentskills.io) defines what a skill is — but not how to publish, install, version, or share them. There's no registry, no dependency management, no way for one skill to build on another.
+The [Agent Skills spec](https://agentskills.io) defines what a skill is — but not how to publish, install, version, or share them. There's no registry, no dependency management, no way for one skill to build on another. Without dependencies, skills become monoliths — authors duplicate instructions because there's no way to reuse another skill.
 
-**skillpm** fills that gap by mapping Agent Skills onto npm's ecosystem. Same `package.json`, same `node_modules/`, same registry. Skills become npm packages you can publish, install, version, and depend on — just like any other package.
+**skillpm** fills that gap. It's a lightweight orchestration layer — ~630 lines of code, 3 runtime dependencies — that maps Agent Skills onto npm's ecosystem. Same `package.json`, same `node_modules/`, same registry. Skills become npm packages you can publish, install, version, and depend on — just like any other package. Small skills that compose, not monoliths that overlap.
 
 ## Quick start
 
@@ -33,20 +33,22 @@ When you run `skillpm install <skill>`:
 
 1. **npm install** — npm handles resolution, download, lockfile, `node_modules/`
 2. **Scan** — skillpm scans `node_modules/` for packages containing `skills/*/SKILL.md`
-3. **Link** — for each skill found, skillpm calls [`skills`](https://www.npmjs.com/package/skills) to wire it into 37+ agent directories (Claude, Cursor, VS Code, Codex, etc.)
+3. **Link** — for each skill found, skillpm calls [`skills`](https://www.npmjs.com/package/skills) to wire it into agent directories (Claude, Cursor, VS Code, Codex, and many more)
 4. **MCP config** — skillpm collects `skillpm.mcpServers` from all skills (transitively) and configures each via [`add-mcp`](https://github.com/neondatabase/add-mcp)
 
 That's it. Agents see the full skill tree with MCP servers configured.
 
 ## What's missing from the spec — and what skillpm adds
 
+skillpm doesn't reinvent anything. It orchestrates three battle-tested tools: npm, [`skills`](https://www.npmjs.com/package/skills), and [`add-mcp`](https://github.com/neondatabase/add-mcp).
+
 | The spec doesn't define... | skillpm adds... |
 |---|---|
 | A registry | Publish to npmjs.org with `skillpm publish` |
 | An install command | `skillpm install` resolves the full dependency tree |
 | Dependency management | Standard `package.json` `dependencies` — npm handles semver, lockfiles, audit |
 | Versioning | npm semver, `package-lock.json`, reproducible installs |
-| Agent wiring | Auto-links skills into 37+ agent directories via [`skills`](https://www.npmjs.com/package/skills) |
+| Agent wiring | Links skills into agent directories via [`skills`](https://www.npmjs.com/package/skills) |
 | MCP server config | Collects and configures MCP servers transitively via [`add-mcp`](https://github.com/neondatabase/add-mcp) |
 
 ## Commands
@@ -71,73 +73,7 @@ mkdir my-skill && cd my-skill
 skillpm init
 ```
 
-This creates a `package.json` (with the `"agent-skill"` keyword) and `skills/<name>/SKILL.md`. Edit the SKILL.md to define your skill.
-
-A skill is just an npm package with a `SKILL.md` inside a `skills/<name>/` subdirectory:
-
-```
-my-skill/
-├── package.json                 # keywords: ["agent-skill"], deps, skillpm.mcpServers
-├── README.md
-└── skills/
-    └── my-skill/
-        ├── SKILL.md             # Skill definition
-        ├── scripts/             # Optional scripts
-        ├── references/          # Optional docs
-        └── assets/              # Optional templates/data
-```
-
-### Skill dependencies
-
-Skill dependencies go in standard `package.json` `dependencies` — npm handles everything:
-
-```json
-{
-  "name": "my-skill",
-  "version": "1.0.0",
-  "keywords": ["agent-skill"],
-  "dependencies": {
-    "some-other-skill": "^1.0.0"
-  },
-  "skillpm": {
-    "mcpServers": ["@anthropic/mcp-server-filesystem"]
-  }
-}
-```
-
-| Field | Purpose | Resolved by |
-|---|---|---|
-| `dependencies` | Skill packages on npm | npm (semver, lockfile, `node_modules/`) |
-| `skillpm.mcpServers[]` | MCP servers to configure | `add-mcp` |
-
-### SKILL.md format
-
-```yaml
----
-name: my-skill
-description: What this skill does and when to use it.
-license: MIT
-allowed-tools: Bash Read
----
-
-# My Skill
-
-## When to use this skill
-...
-
-## Instructions
-...
-```
-
-Version comes from `package.json` — don't duplicate it in SKILL.md.
-
-### Publishing
-
-```bash
-skillpm publish
-```
-
-This validates the `"agent-skill"` keyword is present, then delegates to `npm publish`. Your skill will be discoverable on npmjs.org via [`keywords:agent-skill`](https://www.npmjs.com/search?q=keywords:agent-skill).
+See the full [Creating Skills](https://skillpm.dev/creating-skills/) guide for package structure, SKILL.md format, dependencies, and publishing.
 
 ## What are Agent Skills?
 

package/dist/cli.js

@@ -7,7 +7,7 @@ import { publish } from './commands/publish.js';
 import { sync } from './commands/sync.js';
 import { mcp } from './commands/mcp.js';
 import { log } from './utils/index.js';
-const VERSION = '0.0.1';
+const VERSION = '0.0.4';
 const HELP = `
 skillpm — Agent Skill package manager
 

package/dist/commands/install.d.ts

@@ -1,2 +1,2 @@
 export declare function install(args: string[], cwd: string): Promise<void>;
-export declare function wireSkills(cwd: string): Promise<void>;
+export declare function wireSkills(scanRoot: string, wireTarget?: string): Promise<void>;

package/dist/commands/install.js

@@ -1,5 +1,22 @@
 import { npm, npx, log } from '../utils/index.js';
 import { scanNodeModules, collectMcpServers } from '../scanner/index.js';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { dirname } from 'node:path';
+import { homedir } from 'node:os';
+const execFileAsync = promisify(execFile);
+function isGlobalFlag(args) {
+    return args.includes('-g') || args.includes('--global');
+}
+/**
+ * Resolve the node_modules root to scan. For global installs, uses `npm root -g`.
+ */
+async function resolveNodeModulesRoot(args, cwd) {
+    if (!isGlobalFlag(args))
+        return cwd;
+    const { stdout } = await execFileAsync('npm', ['root', '-g']);
+    return dirname(stdout.trim());
+}
 export async function install(args, cwd) {
     // Step 1: npm install
     const npmArgs = ['install', ...args];
@@ -17,11 +34,15 @@ export async function install(args, cwd) {
         process.exit(1);
     }
     // Step 2: Scan for skills and wire them
-    await wireSkills(cwd);
+    const scanRoot = await resolveNodeModulesRoot(args, cwd);
+    // For global installs, wire skills into user's home directory (not the npm prefix)
+    const wireTarget = isGlobalFlag(args) ? homedir() : cwd;
+    await wireSkills(scanRoot, wireTarget);
 }
-export async function wireSkills(cwd) {
+export async function wireSkills(scanRoot, wireTarget) {
+    const wireCwd = wireTarget ?? scanRoot;
     // Scan node_modules/ for SKILL.md packages
-    const skills = await scanNodeModules(cwd);
+    const skills = await scanNodeModules(scanRoot);
     if (skills.length === 0) {
         log.info('No skill packages found in node_modules/');
         return;
@@ -31,13 +52,16 @@ export async function wireSkills(cwd) {
     for (const skill of skills) {
         log.info(`Linking ${log.skill(skill.name, skill.version)} into agent directories`);
         try {
-            await npx(['skills', 'add', skill.skillDir, '--all', '-y'], { cwd });
+            await npx(['skills', 'add', skill.skillDir, '--all', '-y'], { cwd: wireCwd });
             log.success(`Linked ${skill.name}`);
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
             log.warn(`Failed to link ${skill.name}: ${msg}`);
         }
+        if (skill.legacy) {
+            log.warn(`${skill.name}: SKILL.md is at package root. Move to skills/<name>/SKILL.md for full compatibility. See https://skillpm.dev/creating-skills/`);
+        }
     }
     // Collect and configure MCP servers
     const mcpServers = collectMcpServers(skills);
@@ -46,7 +70,7 @@ export async function wireSkills(cwd) {
         for (const server of mcpServers) {
             log.info(`Configuring MCP server: ${server}`);
             try {
-                await npx(['add-mcp', server, '-y'], { cwd });
+                await npx(['add-mcp', server, '-y'], { cwd: wireCwd });
                 log.success(`Configured ${server}`);
             }
             catch (err) {
@@ -55,5 +79,33 @@ export async function wireSkills(cwd) {
             }
         }
     }
+    // Wire agent definitions via add-agent
+    for (const skill of skills) {
+        for (const agentFile of skill.agents) {
+            log.info(`Wiring agent from ${log.skill(skill.name, skill.version)}`);
+            try {
+                await npx(['add-agent', agentFile, '--package', skill.name], { cwd: wireCwd });
+                log.success(`Wired agent ${agentFile}`);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                log.warn(`Failed to wire agent: ${msg}`);
+            }
+        }
+    }
+    // Wire prompts/instructions via add-prompt
+    for (const skill of skills) {
+        for (const promptFile of skill.prompts) {
+            log.info(`Wiring prompt from ${log.skill(skill.name, skill.version)}`);
+            try {
+                await npx(['add-prompt', promptFile, '--package', skill.name], { cwd: wireCwd });
+                log.success(`Wired prompt ${promptFile}`);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                log.warn(`Failed to wire prompt: ${msg}`);
+            }
+        }
+    }
 }
 //# sourceMappingURL=install.js.map

package/dist/commands/list.js

@@ -11,7 +11,8 @@ export async function list(cwd) {
     for (const skill of skills) {
         const frontmatter = await readSkillMd(skill.skillDir);
         const description = frontmatter?.description ?? '';
-        console.log(`  ${log.skill(skill.name, skill.version)}`);
+        const legacyTag = skill.legacy ? ' (legacy)' : '';
+        console.log(`  ${log.skill(skill.name, skill.version)}${legacyTag}`);
         if (description) {
             console.log(`    ${description}`);
         }

package/dist/commands/uninstall.js

@@ -1,10 +1,25 @@
-import { npm, log } from '../utils/index.js';
+import { npm, npx, log } from '../utils/index.js';
 import { wireSkills } from './install.js';
 export async function uninstall(args, cwd) {
     if (args.length === 0) {
         log.error('Usage: skillpm uninstall <skill> [skill...]');
         process.exit(1);
     }
+    // Clean up agents/prompts for removed packages before npm uninstall
+    for (const pkg of args) {
+        try {
+            await npx(['add-agent', '--remove-package', pkg], { cwd });
+        }
+        catch {
+            // Ignore — package may not have had agents
+        }
+        try {
+            await npx(['add-prompt', '--remove-package', pkg], { cwd });
+        }
+        catch {
+            // Ignore — package may not have had prompts
+        }
+    }
     log.info(`Running npm uninstall ${args.join(' ')}`);
     try {
         const result = await npm(['uninstall', ...args], { cwd });

package/dist/manifest/schema.d.ts

@@ -14,7 +14,13 @@ export interface SkillInfo {
     name: string;
     version: string;
     path: string;
-    /** Path to the skills/<name>/ subdirectory containing SKILL.md */
+    /** Path to the directory containing SKILL.md */
     skillDir: string;
     mcpServers: string[];
+    /** True if SKILL.md is at package root instead of skills/<name>/ */
+    legacy?: boolean;
+    /** Paths to agent definition .md files in agents/ */
+    agents: string[];
+    /** Paths to prompt/instruction .md files in prompts/ */
+    prompts: string[];
 }

package/dist/scanner/index.js

@@ -1,6 +1,19 @@
 import { readdir, access } from 'node:fs/promises';
 import { join } from 'node:path';
 import { readPackageJson, parseSkillpmField } from '../manifest/index.js';
+/**
+ * Scan a directory for .md files (used for agents/ and prompts/ dirs).
+ */
+async function scanMdFiles(dir) {
+    let entries;
+    try {
+        entries = await readdir(dir);
+    }
+    catch {
+        return [];
+    }
+    return entries.filter((e) => e.endsWith('.md')).map((e) => join(dir, e));
+}
 /**
  * Scan node_modules/ for packages that contain a skills/<name>/SKILL.md file.
  * Returns metadata for each discovered skill package.
@@ -48,14 +61,14 @@ async function tryReadSkill(pkgDir) {
     const pkg = await readPackageJson(pkgDir);
     if (!pkg)
         return null;
-    // Look for skills/*/SKILL.md
+    // Preferred: look for skills/*/SKILL.md
     const skillsDir = join(pkgDir, 'skills');
     let skillSubdirs;
     try {
         skillSubdirs = await readdir(skillsDir);
     }
     catch {
-        return null;
+        skillSubdirs = [];
     }
     for (const sub of skillSubdirs) {
         const skillDir = join(skillsDir, sub);
@@ -66,15 +79,38 @@ async function tryReadSkill(pkgDir) {
             continue;
         }
         const skillpm = parseSkillpmField(pkg);
+        const agents = await scanMdFiles(join(pkgDir, 'agents'));
+        const prompts = await scanMdFiles(join(pkgDir, 'prompts'));
         return {
             name: pkg.name,
             version: pkg.version,
             path: pkgDir,
             skillDir,
             mcpServers: skillpm?.mcpServers ?? [],
+            agents,
+            prompts,
         };
     }
-    return null;
+    // Fallback: root SKILL.md (legacy format)
+    try {
+        await access(join(pkgDir, 'SKILL.md'));
+    }
+    catch {
+        return null;
+    }
+    const skillpm = parseSkillpmField(pkg);
+    const agents = await scanMdFiles(join(pkgDir, 'agents'));
+    const prompts = await scanMdFiles(join(pkgDir, 'prompts'));
+    return {
+        name: pkg.name,
+        version: pkg.version,
+        path: pkgDir,
+        skillDir: pkgDir,
+        mcpServers: skillpm?.mcpServers ?? [],
+        legacy: true,
+        agents,
+        prompts,
+    };
 }
 /**
  * Collect all MCP server requirements from all discovered skills (transitive).

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "skillpm",
-  "version": "0.0.1",
-  "description": "npm for Agent Skills",
+  "version": "0.0.4",
+  "description": "Package manager for Agent Skills. Built on npm.",
   "type": "module",
   "bin": {
-    "skillpm": "./dist/cli.js"
+    "skillpm": "dist/cli.js"
   },
   "scripts": {
     "build": "tsc",
@@ -52,7 +52,7 @@
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@types/node": "^25.3.0",
+    "@types/node": "^25.3.1",
     "eslint": "^10.0.2",
     "prettier": "^3.8.1",
     "typescript": "^5.9.3",