skillpm 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 skillpm contributors
+
+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,157 @@
+# skillpm — npm for Agent Skills
+
+[![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.
+
+**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.
+
+## Quick start
+
+```bash
+# Install a skill (no global install needed)
+npx skillpm install <skill-name>
+
+# List installed skills
+npx skillpm list
+
+# Scaffold a new skill package
+npx skillpm init
+```
+
+Or install globally for convenience:
+
+```bash
+npm install -g skillpm
+```
+
+## How it works
+
+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.)
+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
+
+| 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) |
+| MCP server config | Collects and configures MCP servers transitively via [`add-mcp`](https://github.com/neondatabase/add-mcp) |
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `skillpm install [skill...]` | Install skill(s) + full dependency tree, wire into agent dirs |
+| `skillpm uninstall <skill...>` | Remove skill(s) and clean up |
+| `skillpm list` | List installed skill packages |
+| `skillpm init` | Scaffold a new skill package |
+| `skillpm publish` | Publish to npmjs.org (validates `"agent-skill"` keyword) |
+| `skillpm sync` | Re-wire agent directories without reinstalling |
+| `skillpm mcp add <source...>` | Configure MCP server(s) across agents |
+| `skillpm mcp list` | List configured MCP servers |
+
+Aliases: `i` for `install`, `rm`/`remove` for `uninstall`, `ls` for `list`.
+
+## Creating a skill
+
+```bash
+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).
+
+## What are Agent Skills?
+
+Agent Skills are modular, reusable packages of instructions, scripts, and resources that AI agents can dynamically load to extend their capabilities. They follow an [open standard](https://agentskills.io) adopted by Claude, Codex, Cursor, Gemini CLI, Augment, and others.
+
+## Development
+
+```bash
+npm install           # install dependencies
+npm run build         # compile TypeScript
+npm test              # run tests
+npm run lint          # lint
+```
+
+## License
+
+MIT

package/dist/cli.d.ts

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

package/dist/cli.js

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+import { install } from './commands/install.js';
+import { uninstall } from './commands/uninstall.js';
+import { list } from './commands/list.js';
+import { init } from './commands/init.js';
+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 HELP = `
+skillpm — Agent Skill package manager
+
+Usage:
+  skillpm install [skill...]     Install skill(s) + wire into agent directories
+  skillpm uninstall <skill...>   Remove skill(s) and clean up
+  skillpm list                   List installed skill packages
+  skillpm init                   Scaffold a new skill package
+  skillpm publish [args...]      Publish to npmjs.org (wraps npm publish)
+  skillpm sync                   Re-wire agent directories without reinstalling
+  skillpm mcp add <source...>    Configure MCP server(s) across agents
+  skillpm mcp list               List configured MCP servers
+  skillpm --help                 Show this help
+  skillpm --version              Show version
+`;
+async function main() {
+    const args = process.argv.slice(2);
+    const cwd = process.cwd();
+    if (args.length === 0 || args.includes('--help') || args.includes('-h')) {
+        console.log(HELP.trim());
+        return;
+    }
+    if (args.includes('--version') || args.includes('-v')) {
+        console.log(VERSION);
+        return;
+    }
+    const command = args[0];
+    const rest = args.slice(1);
+    switch (command) {
+        case 'install':
+        case 'i':
+            await install(rest, cwd);
+            break;
+        case 'uninstall':
+        case 'remove':
+        case 'rm':
+            await uninstall(rest, cwd);
+            break;
+        case 'list':
+        case 'ls':
+            await list(cwd);
+            break;
+        case 'init':
+            await init(cwd);
+            break;
+        case 'publish':
+            await publish(rest, cwd);
+            break;
+        case 'sync':
+            await sync(cwd);
+            break;
+        case 'mcp':
+            if (rest.length === 0) {
+                log.error('Usage: skillpm mcp <add|list> [args...]');
+                process.exit(1);
+            }
+            await mcp(rest[0], rest.slice(1), cwd);
+            break;
+        default:
+            log.error(`Unknown command: ${command}`);
+            console.log(HELP.trim());
+            process.exit(1);
+    }
+}
+main().catch((err) => {
+    log.error(err.message);
+    process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/dist/commands/init.d.ts

@@ -0,0 +1 @@
+export declare function init(cwd: string): Promise<void>;

package/dist/commands/init.js

@@ -0,0 +1,51 @@
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { npm, log } from '../utils/index.js';
+export async function init(cwd) {
+    // Run npm init
+    log.info('Initializing package...');
+    try {
+        await npm(['init', '-y'], { cwd });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        log.error(`npm init failed: ${msg}`);
+        process.exit(1);
+    }
+    // Read the generated package.json to add "agent-skill" keyword
+    const pkgPath = join(cwd, 'package.json');
+    const { readPackageJson } = await import('../manifest/index.js');
+    const pkg = await readPackageJson(cwd);
+    const name = pkg?.name ?? 'my-skill';
+    // Add "agent-skill" keyword to package.json
+    const rawPkg = JSON.parse(await readFile(pkgPath, 'utf-8'));
+    const keywords = rawPkg.keywords ?? [];
+    if (!keywords.includes('agent-skill')) {
+        keywords.push('agent-skill');
+    }
+    rawPkg.keywords = keywords;
+    await writeFile(pkgPath, JSON.stringify(rawPkg, null, 2) + '\n', 'utf-8');
+    // Create skills/<name>/SKILL.md
+    const skillName = name.replace(/^@[^/]+\//, ''); // strip scope for dir name
+    const skillDir = join(cwd, 'skills', skillName);
+    await mkdir(skillDir, { recursive: true });
+    const skillMd = `---
+name: ${skillName}
+description: TODO — describe what this skill does and when to use it.
+---
+
+# ${skillName}
+
+## When to use this skill
+
+TODO
+
+## Instructions
+
+TODO
+`;
+    await writeFile(join(skillDir, 'SKILL.md'), skillMd, 'utf-8');
+    log.success(`Created skills/${skillName}/SKILL.md`);
+    log.success(`Skill package initialized. Edit skills/${skillName}/SKILL.md to define your skill.`);
+}
+//# sourceMappingURL=init.js.map

package/dist/commands/install.d.ts

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

package/dist/commands/install.js

@@ -0,0 +1,59 @@
+import { npm, npx, log } from '../utils/index.js';
+import { scanNodeModules, collectMcpServers } from '../scanner/index.js';
+export async function install(args, cwd) {
+    // Step 1: npm install
+    const npmArgs = ['install', ...args];
+    log.info(`Running npm ${npmArgs.join(' ')}`);
+    try {
+        const result = await npm(npmArgs, { cwd });
+        if (result.stderr)
+            process.stderr.write(result.stderr);
+        if (result.stdout)
+            process.stdout.write(result.stdout);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        log.error(`npm install failed: ${msg}`);
+        process.exit(1);
+    }
+    // Step 2: Scan for skills and wire them
+    await wireSkills(cwd);
+}
+export async function wireSkills(cwd) {
+    // Scan node_modules/ for SKILL.md packages
+    const skills = await scanNodeModules(cwd);
+    if (skills.length === 0) {
+        log.info('No skill packages found in node_modules/');
+        return;
+    }
+    log.info(`Found ${skills.length} skill package(s)`);
+    // Wire each skill into agent directories via skills CLI
+    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 });
+            log.success(`Linked ${skill.name}`);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            log.warn(`Failed to link ${skill.name}: ${msg}`);
+        }
+    }
+    // Collect and configure MCP servers
+    const mcpServers = collectMcpServers(skills);
+    if (mcpServers.length > 0) {
+        log.info(`Configuring ${mcpServers.length} MCP server(s)`);
+        for (const server of mcpServers) {
+            log.info(`Configuring MCP server: ${server}`);
+            try {
+                await npx(['add-mcp', server, '-y'], { cwd });
+                log.success(`Configured ${server}`);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                log.warn(`Failed to configure MCP server ${server}: ${msg}`);
+            }
+        }
+    }
+}
+//# sourceMappingURL=install.js.map

package/dist/commands/list.d.ts

@@ -0,0 +1 @@
+export declare function list(cwd: string): Promise<void>;

package/dist/commands/list.js

@@ -0,0 +1,24 @@
+import { scanNodeModules } from '../scanner/index.js';
+import { readSkillMd } from '../manifest/index.js';
+import { log } from '../utils/index.js';
+export async function list(cwd) {
+    const skills = await scanNodeModules(cwd);
+    if (skills.length === 0) {
+        log.info('No skill packages installed');
+        return;
+    }
+    console.log(`\n${skills.length} skill package(s) installed:\n`);
+    for (const skill of skills) {
+        const frontmatter = await readSkillMd(skill.skillDir);
+        const description = frontmatter?.description ?? '';
+        console.log(`  ${log.skill(skill.name, skill.version)}`);
+        if (description) {
+            console.log(`    ${description}`);
+        }
+        if (skill.mcpServers.length > 0) {
+            console.log(`    MCP servers: ${skill.mcpServers.join(', ')}`);
+        }
+    }
+    console.log();
+}
+//# sourceMappingURL=list.js.map

package/dist/commands/mcp.d.ts

@@ -0,0 +1 @@
+export declare function mcp(subcommand: string, args: string[], cwd: string): Promise<void>;

package/dist/commands/mcp.js

@@ -0,0 +1,33 @@
+import { npx, log } from '../utils/index.js';
+export async function mcp(subcommand, args, cwd) {
+    switch (subcommand) {
+        case 'add': {
+            if (args.length === 0) {
+                log.error('Usage: skillpm mcp add <source>');
+                process.exit(1);
+            }
+            for (const source of args) {
+                log.info(`Configuring MCP server: ${source}`);
+                try {
+                    await npx(['add-mcp', source, '-y'], { cwd });
+                    log.success(`Configured ${source}`);
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    log.error(`Failed to configure MCP server ${source}: ${msg}`);
+                }
+            }
+            break;
+        }
+        case 'list': {
+            log.info('Listing MCP servers is not yet supported by add-mcp.');
+            log.info('Check your agent config files directly (.cursor/mcp.json, etc.)');
+            break;
+        }
+        default:
+            log.error(`Unknown mcp subcommand: ${subcommand}`);
+            log.error('Usage: skillpm mcp <add|list> [args...]');
+            process.exit(1);
+    }
+}
+//# sourceMappingURL=mcp.js.map

package/dist/commands/publish.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Validate a skill package is ready to publish.
+ * Returns an array of error messages (empty = valid).
+ */
+export declare function validatePublish(cwd: string): Promise<string[]>;
+export declare function publish(args: string[], cwd: string): Promise<void>;

package/dist/commands/publish.js

@@ -0,0 +1,79 @@
+import { readdir, access } from 'node:fs/promises';
+import { join } from 'node:path';
+import { npm, npx, log } from '../utils/index.js';
+import { readPackageJson } from '../manifest/index.js';
+/**
+ * Validate a skill package is ready to publish.
+ * Returns an array of error messages (empty = valid).
+ */
+export async function validatePublish(cwd) {
+    const errors = [];
+    // 1. Check package.json exists and has required fields
+    const pkg = await readPackageJson(cwd);
+    if (!pkg) {
+        return ['No package.json found. Run "skillpm init" or "npm init" first.'];
+    }
+    if (!pkg.keywords || !pkg.keywords.includes('agent-skill')) {
+        errors.push('package.json must include "agent-skill" in keywords. Add it manually or run "skillpm init".');
+    }
+    // 2. Find skills/<name>/SKILL.md
+    const skillsDir = join(cwd, 'skills');
+    let skillSubdirs;
+    try {
+        skillSubdirs = await readdir(skillsDir);
+    }
+    catch {
+        errors.push('No skills/ directory found. Create skills/<name>/SKILL.md with your skill definition.');
+        return errors;
+    }
+    let foundSkillDir = null;
+    for (const sub of skillSubdirs) {
+        const candidate = join(skillsDir, sub);
+        try {
+            await access(join(candidate, 'SKILL.md'));
+            foundSkillDir = candidate;
+            break;
+        }
+        catch {
+            continue;
+        }
+    }
+    if (!foundSkillDir) {
+        errors.push('No SKILL.md found in skills/ subdirectories. Create skills/<name>/SKILL.md.');
+        return errors;
+    }
+    // 3. Validate against the Agent Skills spec via skills-ref
+    try {
+        await npx(['skills-ref', 'validate', foundSkillDir]);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        errors.push(`SKILL.md spec validation failed: ${msg}`);
+    }
+    return errors;
+}
+export async function publish(args, cwd) {
+    const errors = await validatePublish(cwd);
+    if (errors.length > 0) {
+        log.error('Publish validation failed:');
+        for (const err of errors) {
+            log.error(`  • ${err}`);
+        }
+        process.exit(1);
+    }
+    log.info('Publishing to npmjs.org...');
+    try {
+        const result = await npm(['publish', ...args], { cwd });
+        if (result.stderr)
+            process.stderr.write(result.stderr);
+        if (result.stdout)
+            process.stdout.write(result.stdout);
+        log.success('Published');
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        log.error(`npm publish failed: ${msg}`);
+        process.exit(1);
+    }
+}
+//# sourceMappingURL=publish.js.map

package/dist/commands/sync.d.ts

@@ -0,0 +1 @@
+export declare function sync(cwd: string): Promise<void>;

package/dist/commands/sync.js

@@ -0,0 +1,8 @@
+import { log } from '../utils/index.js';
+import { wireSkills } from './install.js';
+export async function sync(cwd) {
+    log.info('Re-scanning and re-wiring agent directories...');
+    await wireSkills(cwd);
+    log.success('Sync complete');
+}
+//# sourceMappingURL=sync.js.map

package/dist/commands/uninstall.d.ts

@@ -0,0 +1 @@
+export declare function uninstall(args: string[], cwd: string): Promise<void>;

package/dist/commands/uninstall.js

@@ -0,0 +1,24 @@
+import { npm, 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);
+    }
+    log.info(`Running npm uninstall ${args.join(' ')}`);
+    try {
+        const result = await npm(['uninstall', ...args], { cwd });
+        if (result.stderr)
+            process.stderr.write(result.stderr);
+        if (result.stdout)
+            process.stdout.write(result.stdout);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        log.error(`npm uninstall failed: ${msg}`);
+        process.exit(1);
+    }
+    // Re-wire to clean up stale symlinks
+    await wireSkills(cwd);
+}
+//# sourceMappingURL=uninstall.js.map

package/dist/manifest/index.d.ts

@@ -0,0 +1,12 @@
+import type { SkillPackageJson, SkillpmField } from './schema.js';
+export declare function readPackageJson(pkgDir: string): Promise<SkillPackageJson | null>;
+export declare function parseSkillpmField(pkg: SkillPackageJson): SkillpmField;
+export interface SkillMdFrontmatter {
+    name: string;
+    description: string;
+    license?: string;
+    compatibility?: string;
+    metadata?: Record<string, unknown>;
+    'allowed-tools'?: string;
+}
+export declare function readSkillMd(skillDir: string): Promise<SkillMdFrontmatter | null>;

package/dist/manifest/index.js

@@ -0,0 +1,31 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import matter from 'gray-matter';
+import { SkillpmFieldSchema } from './schema.js';
+export async function readPackageJson(pkgDir) {
+    try {
+        const raw = await readFile(join(pkgDir, 'package.json'), 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export function parseSkillpmField(pkg) {
+    const result = SkillpmFieldSchema.safeParse(pkg.skillpm);
+    if (!result.success) {
+        throw new Error(`Invalid skillpm field in ${pkg.name}: ${result.error.message}`);
+    }
+    return result.data;
+}
+export async function readSkillMd(skillDir) {
+    try {
+        const raw = await readFile(join(skillDir, 'SKILL.md'), 'utf-8');
+        const { data } = matter(raw);
+        return data;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/manifest/schema.d.ts

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+export declare const SkillpmFieldSchema: z.ZodOptional<z.ZodObject<{
+    mcpServers: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>>;
+export type SkillpmField = z.infer<typeof SkillpmFieldSchema>;
+export interface SkillPackageJson {
+    name: string;
+    version: string;
+    keywords?: string[];
+    dependencies?: Record<string, string>;
+    skillpm?: SkillpmField;
+}
+export interface SkillInfo {
+    name: string;
+    version: string;
+    path: string;
+    /** Path to the skills/<name>/ subdirectory containing SKILL.md */
+    skillDir: string;
+    mcpServers: string[];
+}

package/dist/manifest/schema.js

@@ -0,0 +1,8 @@
+import { z } from 'zod';
+export const SkillpmFieldSchema = z
+    .object({
+    mcpServers: z.array(z.string()).optional(),
+})
+    .strict()
+    .optional();
+//# sourceMappingURL=schema.js.map

package/dist/scanner/index.d.ts

@@ -0,0 +1,11 @@
+import type { SkillInfo } from '../manifest/schema.js';
+/**
+ * Scan node_modules/ for packages that contain a skills/<name>/SKILL.md file.
+ * Returns metadata for each discovered skill package.
+ */
+export declare function scanNodeModules(cwd: string): Promise<SkillInfo[]>;
+/**
+ * Collect all MCP server requirements from all discovered skills (transitive).
+ * Deduplicates entries.
+ */
+export declare function collectMcpServers(skills: SkillInfo[]): string[];

package/dist/scanner/index.js

@@ -0,0 +1,92 @@
+import { readdir, access } from 'node:fs/promises';
+import { join } from 'node:path';
+import { readPackageJson, parseSkillpmField } from '../manifest/index.js';
+/**
+ * Scan node_modules/ for packages that contain a skills/<name>/SKILL.md file.
+ * Returns metadata for each discovered skill package.
+ */
+export async function scanNodeModules(cwd) {
+    const nodeModulesDir = join(cwd, 'node_modules');
+    const skills = [];
+    let entries;
+    try {
+        entries = await readdir(nodeModulesDir);
+    }
+    catch {
+        return skills;
+    }
+    for (const entry of entries) {
+        if (entry.startsWith('.'))
+            continue;
+        if (entry.startsWith('@')) {
+            // Scoped package — scan one level deeper
+            const scopeDir = join(nodeModulesDir, entry);
+            let scopedEntries;
+            try {
+                scopedEntries = await readdir(scopeDir);
+            }
+            catch {
+                continue;
+            }
+            for (const scopedEntry of scopedEntries) {
+                const pkgDir = join(scopeDir, scopedEntry);
+                const skill = await tryReadSkill(pkgDir);
+                if (skill)
+                    skills.push(skill);
+            }
+        }
+        else {
+            const pkgDir = join(nodeModulesDir, entry);
+            const skill = await tryReadSkill(pkgDir);
+            if (skill)
+                skills.push(skill);
+        }
+    }
+    return skills;
+}
+async function tryReadSkill(pkgDir) {
+    const pkg = await readPackageJson(pkgDir);
+    if (!pkg)
+        return null;
+    // Look for skills/*/SKILL.md
+    const skillsDir = join(pkgDir, 'skills');
+    let skillSubdirs;
+    try {
+        skillSubdirs = await readdir(skillsDir);
+    }
+    catch {
+        return null;
+    }
+    for (const sub of skillSubdirs) {
+        const skillDir = join(skillsDir, sub);
+        try {
+            await access(join(skillDir, 'SKILL.md'));
+        }
+        catch {
+            continue;
+        }
+        const skillpm = parseSkillpmField(pkg);
+        return {
+            name: pkg.name,
+            version: pkg.version,
+            path: pkgDir,
+            skillDir,
+            mcpServers: skillpm?.mcpServers ?? [],
+        };
+    }
+    return null;
+}
+/**
+ * Collect all MCP server requirements from all discovered skills (transitive).
+ * Deduplicates entries.
+ */
+export function collectMcpServers(skills) {
+    const servers = new Set();
+    for (const skill of skills) {
+        for (const server of skill.mcpServers) {
+            servers.add(server);
+        }
+    }
+    return [...servers];
+}
+//# sourceMappingURL=index.js.map

package/dist/utils/exec.d.ts

@@ -0,0 +1,13 @@
+export interface ExecResult {
+    stdout: string;
+    stderr: string;
+}
+export declare function run(command: string, args: string[], opts?: {
+    cwd?: string;
+}): Promise<ExecResult>;
+export declare function npm(args: string[], opts?: {
+    cwd?: string;
+}): Promise<ExecResult>;
+export declare function npx(args: string[], opts?: {
+    cwd?: string;
+}): Promise<ExecResult>;

package/dist/utils/exec.js

@@ -0,0 +1,17 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+export async function run(command, args, opts) {
+    const { stdout, stderr } = await execFileAsync(command, args, {
+        cwd: opts?.cwd,
+        maxBuffer: 10 * 1024 * 1024,
+    });
+    return { stdout, stderr };
+}
+export async function npm(args, opts) {
+    return run('npm', args, opts);
+}
+export async function npx(args, opts) {
+    return run('npx', ['--yes', ...args], opts);
+}
+//# sourceMappingURL=exec.js.map

package/dist/utils/index.d.ts

@@ -0,0 +1,2 @@
+export { run, npm, npx } from './exec.js';
+export * as log from './log.js';

package/dist/utils/index.js

@@ -0,0 +1,3 @@
+export { run, npm, npx } from './exec.js';
+export * as log from './log.js';
+//# sourceMappingURL=index.js.map

package/dist/utils/log.d.ts

@@ -0,0 +1,5 @@
+export declare function info(msg: string): void;
+export declare function success(msg: string): void;
+export declare function warn(msg: string): void;
+export declare function error(msg: string): void;
+export declare function skill(name: string, version?: string): string;

package/dist/utils/log.js

@@ -0,0 +1,17 @@
+import pc from 'picocolors';
+export function info(msg) {
+    console.log(pc.blue('ℹ'), msg);
+}
+export function success(msg) {
+    console.log(pc.green('✓'), msg);
+}
+export function warn(msg) {
+    console.log(pc.yellow('⚠'), msg);
+}
+export function error(msg) {
+    console.error(pc.red('✗'), msg);
+}
+export function skill(name, version) {
+    return version ? `${pc.bold(name)}@${pc.dim(version)}` : pc.bold(name);
+}
+//# sourceMappingURL=log.js.map

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "skillpm",
+  "version": "0.0.1",
+  "description": "npm for Agent Skills",
+  "type": "module",
+  "bin": {
+    "skillpm": "./dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src/",
+    "format": "prettier --write 'src/**/*.ts'",
+    "prepublishOnly": "npm run lint && npm run build && npm test"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.test.*",
+    "!dist/**/*.map",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "agent-skills",
+    "skills",
+    "ai-agents",
+    "cli",
+    "npm"
+  ],
+  "homepage": "https://skillpm.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sbroenne/skillpm.git"
+  },
+  "bugs": {
+    "url": "https://github.com/sbroenne/skillpm/issues"
+  },
+  "author": "sbroenne",
+  "license": "MIT",
+  "workspaces": [
+    "packages/*"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "gray-matter": "^4.0.3",
+    "picocolors": "^1.1.1",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^25.3.0",
+    "eslint": "^10.0.2",
+    "prettier": "^3.8.1",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.56.1",
+    "vitest": "^4.0.18"
+  }
+}