skillpm 0.0.4 → 0.0.6

package/README.md

@@ -21,12 +21,14 @@ npx skillpm list
 npx skillpm init
 ```
 
-Or install globally for convenience:
+Or install the CLI globally:
 
 ```bash
 npm install -g skillpm
 ```
 
+> **Note:** Skills are always workspace-local. This installs the `skillpm` CLI — not skills.
+
 ## How it works
 
 When you run `skillpm install <skill>`:
@@ -34,7 +36,8 @@ 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 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)
+4. **Configs** — for each skill with a `configs/` directory, skillpm copies agent definitions, rules, and prompts into the workspace (auto-prefixed to avoid conflicts)
+5. **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.
 
@@ -49,6 +52,7 @@ skillpm doesn't reinvent anything. It orchestrates three battle-tested tools: np
 | Dependency management | Standard `package.json` `dependencies` — npm handles semver, lockfiles, audit |
 | Versioning | npm semver, `package-lock.json`, reproducible installs |
 | Agent wiring | Links skills into agent directories via [`skills`](https://www.npmjs.com/package/skills) |
+| Config files | Copies agent definitions, rules, and prompts from `configs/` into the workspace |
 | MCP server config | Collects and configures MCP servers transitively via [`add-mcp`](https://github.com/neondatabase/add-mcp) |
 
 ## Commands

package/dist/commands/install.d.ts

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

package/dist/commands/install.js

@@ -1,23 +1,13 @@
 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());
-}
+import { copyConfigs } from '../configs/index.js';
 export async function install(args, cwd) {
+    // Reject global installs — skillpm is workspace-only
+    if (args.includes('-g') || args.includes('--global')) {
+        log.error('Global installs are not supported. skillpm works per-workspace with package.json and lockfiles.');
+        log.error('For global skills, use: npx skills add <path>');
+        process.exit(1);
+    }
     // Step 1: npm install
     const npmArgs = ['install', ...args];
     log.info(`Running npm ${npmArgs.join(' ')}`);
@@ -34,15 +24,11 @@ export async function install(args, cwd) {
         process.exit(1);
     }
     // Step 2: Scan for skills and wire them
-    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);
+    await wireSkills(cwd);
 }
-export async function wireSkills(scanRoot, wireTarget) {
-    const wireCwd = wireTarget ?? scanRoot;
+export async function wireSkills(cwd) {
     // Scan node_modules/ for SKILL.md packages
-    const skills = await scanNodeModules(scanRoot);
+    const skills = await scanNodeModules(cwd);
     if (skills.length === 0) {
         log.info('No skill packages found in node_modules/');
         return;
@@ -52,7 +38,7 @@ export async function wireSkills(scanRoot, wireTarget) {
     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: wireCwd });
+            await npx(['skills', 'add', skill.skillDir, '--all', '-y'], { cwd });
             log.success(`Linked ${skill.name}`);
         }
         catch (err) {
@@ -70,7 +56,7 @@ export async function wireSkills(scanRoot, wireTarget) {
         for (const server of mcpServers) {
             log.info(`Configuring MCP server: ${server}`);
             try {
-                await npx(['add-mcp', server, '-y'], { cwd: wireCwd });
+                await npx(['add-mcp', server, '-y'], { cwd });
                 log.success(`Configured ${server}`);
             }
             catch (err) {
@@ -79,31 +65,17 @@ export async function wireSkills(scanRoot, wireTarget) {
             }
         }
     }
-    // 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
+    // Copy configs/ files (agents, prompts, rules) into workspace
     for (const skill of skills) {
-        for (const promptFile of skill.prompts) {
-            log.info(`Wiring prompt from ${log.skill(skill.name, skill.version)}`);
+        if (skill.configsDir) {
+            log.info(`Copying config files from ${log.skill(skill.name, skill.version)}`);
             try {
-                await npx(['add-prompt', promptFile, '--package', skill.name], { cwd: wireCwd });
-                log.success(`Wired prompt ${promptFile}`);
+                const copied = await copyConfigs(skill.configsDir, cwd, skill.name, skill.configPrefix);
+                log.success(`Copied ${copied.length} config file(s) from ${skill.name}`);
             }
             catch (err) {
                 const msg = err instanceof Error ? err.message : String(err);
-                log.warn(`Failed to wire prompt: ${msg}`);
+                log.warn(`Failed to copy config files from ${skill.name}: ${msg}`);
             }
         }
     }

package/dist/commands/uninstall.js

@@ -1,23 +1,21 @@
-import { npm, npx, log } from '../utils/index.js';
+import { npm, log } from '../utils/index.js';
 import { wireSkills } from './install.js';
+import { removeConfigs } from '../configs/index.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
+    // Clean up wired files before npm uninstall
     for (const pkg of args) {
         try {
-            await npx(['add-agent', '--remove-package', pkg], { cwd });
+            const removed = await removeConfigs(cwd, pkg);
+            if (removed.length > 0) {
+                log.info(`Removed ${removed.length} config file(s) from ${pkg}`);
+            }
         }
         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
+            // Ignore — package may not have had configs
         }
     }
     log.info(`Running npm uninstall ${args.join(' ')}`);

package/dist/configs/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Copy all files from a skill's configs/ directory to the workspace,
+ * auto-prefixing filenames to avoid conflicts between installed skills.
+ *
+ * The prefix used is, in priority order:
+ *   1. `configPrefix` argument (from skillpm.configPrefix in package.json)
+ *   2. De-scoped package name (strips "@scope/" from scoped packages)
+ *
+ * Examples:
+ *   packageName="@mcaps/spt-iq-consumption", configPrefix="consumption"
+ *     → "consumption-briefing.md"
+ *   packageName="@mcaps/spt-iq-consumption", no configPrefix
+ *     → "spt-iq-consumption-briefing.md"
+ *   packageName="my-skill", no configPrefix
+ *     → "my-skill-briefing.md"
+ */
+export declare function copyConfigs(configsDir: string, cwd: string, packageName: string, configPrefix?: string): Promise<string[]>;
+/**
+ * Remove all config files for a package using the manifest.
+ */
+export declare function removeConfigs(cwd: string, packageName: string): Promise<string[]>;

package/dist/configs/index.js

@@ -0,0 +1,126 @@
+import { readdir, copyFile, mkdir, unlink, readFile, writeFile, stat } from 'node:fs/promises';
+import { join, relative, dirname, basename } from 'node:path';
+const MANIFEST_DIR = '.skillpm';
+const MANIFEST_FILE = 'manifest.json';
+/** Normalize path separators to forward slashes for cross-platform consistency. */
+function normalizePath(p) {
+    return p.replace(/\\/g, '/');
+}
+async function readManifest(cwd) {
+    try {
+        const raw = await readFile(join(cwd, MANIFEST_DIR, MANIFEST_FILE), 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return {};
+    }
+}
+async function writeManifest(cwd, manifest) {
+    const dir = join(cwd, MANIFEST_DIR);
+    await mkdir(dir, { recursive: true });
+    await writeFile(join(dir, MANIFEST_FILE), JSON.stringify(manifest, null, 2) + '\n');
+}
+/**
+ * Recursively collect all files in a directory, returning paths relative to the root.
+ */
+async function walkDir(dir, root) {
+    root ??= dir;
+    const files = [];
+    let entries;
+    try {
+        entries = await readdir(dir);
+    }
+    catch {
+        return files;
+    }
+    for (const name of entries) {
+        const full = join(dir, name);
+        const s = await stat(full);
+        if (s.isDirectory()) {
+            files.push(...(await walkDir(full, root)));
+        }
+        else {
+            files.push(normalizePath(relative(root, full)));
+        }
+    }
+    return files;
+}
+/**
+ * Strip npm scope from a package name.
+ * e.g. "@mcaps/spt-iq-consumption" → "spt-iq-consumption"
+ *      "spt-iq-consumption"       → "spt-iq-consumption"
+ */
+function stripScope(packageName) {
+    if (packageName.startsWith('@')) {
+        const slash = packageName.indexOf('/');
+        return slash >= 0 ? packageName.slice(slash + 1) : packageName;
+    }
+    return packageName;
+}
+/**
+ * Auto-prefix a filename with the resolved prefix to avoid conflicts.
+ * e.g. "reviewer.md" with prefix "my-skill" → "my-skill-reviewer.md"
+ */
+function prefixFilename(relPath, prefix) {
+    const dir = dirname(relPath);
+    const file = basename(relPath);
+    const prefixed = `${prefix}-${file}`;
+    return normalizePath(dir === '.' ? prefixed : join(dir, prefixed));
+}
+/**
+ * Copy all files from a skill's configs/ directory to the workspace,
+ * auto-prefixing filenames to avoid conflicts between installed skills.
+ *
+ * The prefix used is, in priority order:
+ *   1. `configPrefix` argument (from skillpm.configPrefix in package.json)
+ *   2. De-scoped package name (strips "@scope/" from scoped packages)
+ *
+ * Examples:
+ *   packageName="@mcaps/spt-iq-consumption", configPrefix="consumption"
+ *     → "consumption-briefing.md"
+ *   packageName="@mcaps/spt-iq-consumption", no configPrefix
+ *     → "spt-iq-consumption-briefing.md"
+ *   packageName="my-skill", no configPrefix
+ *     → "my-skill-briefing.md"
+ */
+export async function copyConfigs(configsDir, cwd, packageName, configPrefix) {
+    const prefix = configPrefix ?? stripScope(packageName);
+    const files = await walkDir(configsDir);
+    const copied = [];
+    for (const relPath of files) {
+        const prefixed = prefixFilename(relPath, prefix);
+        const src = join(configsDir, relPath);
+        const dest = join(cwd, prefixed);
+        await mkdir(dirname(dest), { recursive: true });
+        await copyFile(src, dest);
+        copied.push(prefixed);
+    }
+    // Update manifest
+    const manifest = await readManifest(cwd);
+    manifest[packageName] = copied;
+    await writeManifest(cwd, manifest);
+    return copied;
+}
+/**
+ * Remove all config files for a package using the manifest.
+ */
+export async function removeConfigs(cwd, packageName) {
+    const manifest = await readManifest(cwd);
+    const files = manifest[packageName];
+    if (!files || files.length === 0)
+        return [];
+    const removed = [];
+    for (const relPath of files) {
+        try {
+            await unlink(join(cwd, relPath));
+            removed.push(relPath);
+        }
+        catch {
+            // File already gone
+        }
+    }
+    delete manifest[packageName];
+    await writeManifest(cwd, manifest);
+    return removed;
+}
+//# sourceMappingURL=index.js.map

package/dist/manifest/schema.d.ts

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 export declare const SkillpmFieldSchema: z.ZodOptional<z.ZodObject<{
     mcpServers: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    configPrefix: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>>;
 export type SkillpmField = z.infer<typeof SkillpmFieldSchema>;
 export interface SkillPackageJson {
@@ -19,8 +20,13 @@ export interface SkillInfo {
     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[];
+    /** Path to configs/ directory if present (mirrors workspace layout) */
+    configsDir?: string;
+    /**
+     * Optional prefix override for config file naming.
+     * When set, used instead of the (de-scoped) package name.
+     * e.g. configPrefix: "consumption" → "consumption--briefing.md"
+     * Declared via skillpm.configPrefix in package.json.
+     */
+    configPrefix?: string;
 }

package/dist/manifest/schema.js

@@ -2,6 +2,7 @@ import { z } from 'zod';
 export const SkillpmFieldSchema = z
     .object({
     mcpServers: z.array(z.string()).optional(),
+    configPrefix: z.string().optional(),
 })
     .strict()
     .optional();

package/dist/scanner/index.js

@@ -1,19 +1,6 @@
 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.
@@ -57,10 +44,22 @@ export async function scanNodeModules(cwd) {
     }
     return skills;
 }
+async function hasDir(dir) {
+    try {
+        await access(dir);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 async function tryReadSkill(pkgDir) {
     const pkg = await readPackageJson(pkgDir);
     if (!pkg)
         return null;
+    // Check for configs/ directory
+    const configsDir = join(pkgDir, 'configs');
+    const hasConfigs = await hasDir(configsDir);
     // Preferred: look for skills/*/SKILL.md
     const skillsDir = join(pkgDir, 'skills');
     let skillSubdirs;
@@ -79,16 +78,14 @@ 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,
+            configsDir: hasConfigs ? configsDir : undefined,
+            configPrefix: skillpm?.configPrefix,
         };
     }
     // Fallback: root SKILL.md (legacy format)
@@ -99,8 +96,6 @@ async function tryReadSkill(pkgDir) {
         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,
@@ -108,8 +103,8 @@ async function tryReadSkill(pkgDir) {
         skillDir: pkgDir,
         mcpServers: skillpm?.mcpServers ?? [],
         legacy: true,
-        agents,
-        prompts,
+        configsDir: hasConfigs ? configsDir : undefined,
+        configPrefix: skillpm?.configPrefix,
     };
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillpm",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "description": "Package manager for Agent Skills. Built on npm.",
   "type": "module",
   "bin": {