skills-manifest 0.2.0 → 0.3.0

package/README.md

@@ -9,10 +9,47 @@
 A lightweight manifest manager for [skills](https://github.com/vercel-labs/skills), enabling project-level skill synchronization and collaborative configuration.
 
 > [!IMPORTANT]
-> The `skills add <args>` command will not automatically update the `skills-manifest.json` file.
-> Since [skills](https://github.com/vercel-labs/skills) does not currently support project-level lock files, this project serves as a temporary solution for sharing and persisting skills across collaborative environments.
+> ~~The `skills add <args>` command will not automatically update the `skills-manifest.json` file.~~
+> ~~Since [skills](https://github.com/vercel-labs/skills) does not currently support project-level lock files, this project serves as a temporary solution for sharing and persisting skills across collaborative environments.~~
 
-## Install
+> Now you can use `skills add` to add skills to the manifest.
+
+## Init & sync with skills
+
+Run once in your project:
+
+```bash
+npx skills-manifest init
+```
+
+This will:
+
+- Install `skills` and `skills-manifest` as dev dependencies
+- Create `skills-manifest.json` and add a `prepare` script that runs `skills-manifest install`
+- Add `skills` to `.gitignore`
+
+Then run:
+
+```bash
+skills-manifest install
+```
+
+`install` syncs skills from the manifest and **injects a wrapper** into `node_modules/skills` so that:
+
+| When you run | skills-manifest also runs |
+|--------------|---------------------------|
+| `skills add <repo> [--skill ...]` | `skills-manifest add <repo> [...]` — the repo and skills are written to `skills-manifest.json` |
+| `skills remove <skills...>` | `skills-manifest remove` for each repo that had those skills |
+
+To add a skill **without** updating the manifest (e.g. one-off try), use:
+
+```bash
+skills add <repo> --skip-manifest
+```
+
+## Install (manual)
+
+Alternatively, install without `init`:
 
 ```bash
 pnpm add skills skills-manifest -D
@@ -30,9 +67,8 @@ pnpm add skills skills-manifest -D
     "vercel-labs/agent-skills": {
       "vercel-react-best-practices": true
     },
-    "https://github.com/vercel-labs": {
-      "find-skills": true
-    }
+    // or array of skills
+    "https://github.com/vercel-labs": ["find-skills"]
   }
 }
 ```
@@ -53,6 +89,16 @@ skills
 }
 ```
 
+## AGENTS.md for AI Agents
+
+After you have configured `skills-manifest.json` and run `skills-manifest install` to generate the skills tree, we recommend using [OpenSkills](https://github.com/numman-ali/openskills) to produce an `AGENTS.md` that AI agents can consume:
+
+```bash
+npx openskills sync
+```
+
+This keeps your installed skills in sync with an `AGENTS.md` (or custom output path) so agents that read it (e.g. Claude Code, Cursor, Windsurf) can discover and use the same skills. See [OpenSkills](https://github.com/numman-ali/openskills) for options such as `--universal` and `-o <path>`.
+
 ## License
 
 [MIT](./LICENSE) License © [Hairyf](https://github.com/hairyf)

package/dist/cli/index.mjs

@@ -1,16 +1,139 @@
+import { createRequire } from "node:module";
+import fs from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
 import { loadConfig } from "c12";
 import { defineCommand, runMain } from "citty";
+import { addDevDependency, installDependencies } from "nypm";
 import { x } from "tinyexec";
 
 //#region package.json
-var version = "0.2.0";
+var version = "0.3.0";
 
 //#endregion
 //#region src/cli/index.ts
-runMain(defineCommand({
+const require = createRequire(import.meta.url);
+async function patchSkillsCli() {
+	const cwd = process.cwd();
+	const cliPath = path.join(cwd, "node_modules", "skills", "bin", "cli.mjs");
+	try {
+		if (!(await fs.stat(cliPath)).isFile()) return;
+	} catch {
+		return;
+	}
+	if ((await fs.readFile(cliPath, "utf-8").catch(() => "")).includes("Injected by skills-manifest")) return;
+	let wrapperPath;
+	try {
+		const pkgJsonPath = require.resolve("skills-manifest/package.json");
+		wrapperPath = path.join(path.dirname(pkgJsonPath), "patches", "skills-cli.mjs");
+	} catch {
+		return;
+	}
+	try {
+		const wrapper = await fs.readFile(wrapperPath, "utf-8");
+		await fs.writeFile(cliPath, wrapper, "utf-8");
+	} catch {
+		console.warn("skills-manifest: failed to inject wrapper. Sync add/remove with manifest will not run.");
+	}
+}
+const DEFAULT_MANIFEST = {
+	agents: ["cursor", "claude-code"],
+	skills: {}
+};
+const init = defineCommand({
+	meta: {
+		name: "init",
+		description: "Initialize skills configuration"
+	},
+	async run() {
+		const cwd = process.cwd();
+		await addDevDependency(["skills", "skills-manifest"], { cwd });
+		await installDependencies({ cwd });
+		await patchSkillsCli();
+		const manifestPath = path.join(cwd, "skills-manifest.json");
+		if (!await fs.stat(manifestPath).catch(() => null)) {
+			const content = {
+				$schema: "https://raw.githubusercontent.com/hairyf/skills-manifest/main/skills-manifest.schema.json",
+				...DEFAULT_MANIFEST
+			};
+			await fs.writeFile(manifestPath, JSON.stringify(content, null, 2));
+		}
+		const gitignorePath = path.join(cwd, ".gitignore");
+		const gitignore = await fs.readFile(gitignorePath, "utf-8").catch(() => "");
+		if (!gitignore.split("\n").includes("skills")) await fs.appendFile(gitignorePath, gitignore.endsWith("\n") ? "skills\n" : "\nskills\n");
+		const pkgPath = path.join(cwd, "package.json");
+		const pkg = JSON.parse(await fs.readFile(pkgPath, "utf-8"));
+		const prepare = pkg.scripts?.prepare;
+		const cmd = "skills-manifest install";
+		if (!prepare) pkg.scripts = {
+			...pkg.scripts,
+			prepare: cmd
+		};
+		else if (!prepare.includes(cmd)) pkg.scripts.prepare = `${prepare} && ${cmd}`;
+		await fs.writeFile(pkgPath, JSON.stringify(pkg, null, 2));
+	}
+});
+const add = defineCommand({
+	meta: {
+		name: "add",
+		description: "Add repo and skills to manifest"
+	},
+	args: { repo: {
+		type: "positional",
+		description: "Repository (e.g. owner/repo or full URL)",
+		required: true
+	} },
+	async run({ args }) {
+		const { config, configFile } = await loadConfig({ configFile: "skills-manifest" });
+		if (!configFile) throw new Error("skills-manifest.json not found. Run `skills-manifest init` first.");
+		const repo = args.repo;
+		const skills = (args._ ?? []).slice(1);
+		const existing = config.skills[repo];
+		const existingList = Array.isArray(existing) ? existing : typeof existing === "object" && existing !== null ? Object.keys(existing).filter((k) => existing[k]) : [];
+		const skillsToAdd = [...new Set([...existingList, ...skills])];
+		config.skills[repo] = skillsToAdd;
+		const content = JSON.stringify(config, null, 2);
+		await fs.writeFile(configFile, content);
+		console.log(`Added ${repo} to skills-manifest.json`);
+	}
+});
+const remove = defineCommand({
+	meta: {
+		name: "remove",
+		description: "Remove repo or skills from manifest"
+	},
+	args: { repo: {
+		type: "positional",
+		description: "Repository (e.g. owner/repo or full URL)",
+		required: true
+	} },
+	async run({ args }) {
+		const { config, configFile } = await loadConfig({ configFile: "skills-manifest" });
+		if (!configFile) throw new Error("skills-manifest.json not found. Run `skills-manifest init` first.");
+		const repo = args.repo;
+		const skillsToRemove = (args._ ?? []).slice(1);
+		if (!(repo in config.skills)) throw new Error(`Repo ${repo} not found in manifest`);
+		if (skillsToRemove.length === 0) {
+			delete config.skills[repo];
+			console.log(`Removed ${repo} from skills-manifest.json`);
+		} else {
+			const existing = config.skills[repo];
+			const skillsToKeep = (Array.isArray(existing) ? existing : typeof existing === "object" && existing !== null ? Object.keys(existing).filter((k) => existing[k]) : []).filter((s) => !skillsToRemove.includes(s));
+			if (skillsToKeep.length === 0) {
+				delete config.skills[repo];
+				console.log(`Removed ${repo} from skills-manifest.json`);
+			} else {
+				config.skills[repo] = skillsToKeep;
+				console.log(`Removed skills from ${repo} in skills-manifest.json`);
+			}
+		}
+		const content = JSON.stringify(config, null, 2);
+		await fs.writeFile(configFile, content);
+	}
+});
+const install = defineCommand({
 	meta: {
 		name: "install",
-		version,
 		description: "Install skills"
 	},
 	async run() {
@@ -38,6 +161,37 @@ runMain(defineCommand({
 				"--yes"
 			], { nodeOptions: { stdio: "inherit" } });
 		}
+		const TARGET_MAP = {
+			cursor: ".cursor",
+			opencode: ".opencode"
+		};
+		const agents = path.join(process.cwd(), ".agents");
+		const fixedAgents = config.agents.filter((a) => a in TARGET_MAP);
+		for (const agent of fixedAgents) {
+			const dest = path.join(process.cwd(), TARGET_MAP[agent]);
+			await fs.rm(dest, {
+				recursive: true,
+				force: true
+			});
+			await fs.cp(agents, dest, {
+				recursive: true,
+				verbatimSymlinks: false
+			});
+		}
+		await patchSkillsCli();
+	}
+});
+runMain(defineCommand({
+	meta: {
+		name: "skills-manifest",
+		version,
+		description: "A lightweight manifest manager for skills"
+	},
+	subCommands: {
+		add,
+		init,
+		install,
+		remove
 	}
 }));
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "skills-manifest",
   "type": "module",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "A lightweight manifest manager for skills, enabling project-level skill synchronization and collaborative configuration.",
   "author": "Hairyf <wwu710632@gmail.com>",
   "license": "MIT",
@@ -28,7 +28,8 @@
   },
   "files": [
     "bin",
-    "dist"
+    "dist",
+    "patches"
   ],
   "peerDependencies": {
     "skills": "^1.2.0"
@@ -36,6 +37,7 @@
   "dependencies": {
     "c12": "^3.3.3",
     "citty": "^0.2.0",
+    "nypm": "^0.6.4",
     "tinyexec": "^1.0.2"
   },
   "devDependencies": {
@@ -56,7 +58,7 @@
     "vitest": "^4.0.15",
     "vitest-package-exports": "^0.1.1",
     "yaml": "^2.8.2",
-    "skills-manifest": "0.2.0"
+    "skills-manifest": "0.3.0"
   },
   "simple-git-hooks": {
     "pre-commit": "pnpm i --frozen-lockfile --ignore-scripts --offline && npx lint-staged"

package/patches/skills-cli.mjs

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+// Injected by skills-manifest install: sync add/remove with skills-manifest.json
+import { spawnSync } from 'node:child_process'
+import { existsSync, readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { dirname, join } from 'node:path'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const originalCli = join(__dirname, '..', 'dist', 'cli.mjs')
+const cwd = process.cwd()
+
+function runSkillsManifest(args) {
+  const inNodeModules = join(cwd, 'node_modules', 'skills-manifest', 'bin')
+  const inCwd = join(cwd, 'bin')
+  const binDir = existsSync(inNodeModules) ? inNodeModules : inCwd
+  const entry = existsSync(join(binDir, 'index.dev.mjs')) ? join(binDir, 'index.dev.mjs') : join(binDir, 'index.mjs')
+  if (!existsSync(entry)) return
+  const r = spawnSync(process.execPath, [entry, ...args], { stdio: 'inherit', cwd })
+  if (r.status !== 0) process.exit(r.status ?? 1)
+}
+
+const argv = process.argv.slice(2)
+const skipManifest = argv.includes('--skip-manifest')
+const forwardArgs = argv.filter(a => a !== '--skip-manifest')
+const cmd = forwardArgs[0]
+
+const result = spawnSync(process.execPath, [originalCli, ...forwardArgs], { stdio: 'inherit', cwd })
+if (result.status !== 0) process.exit(result.status ?? 1)
+
+if (cmd === 'add' && !skipManifest) {
+  const rest = forwardArgs.slice(1)
+  let repo = ''
+  const skills = []
+  for (let i = 0; i < rest.length; i++) {
+    if (rest[i] === '--skill' && rest[i + 1]) { skills.push(rest[i + 1]); i++; continue }
+    if (!rest[i].startsWith('-') && !repo) { repo = rest[i]; continue }
+  }
+  if (repo) runSkillsManifest(['add', repo, ...skills])
+} else if (cmd === 'remove') {
+  const rest = forwardArgs.slice(1)
+  const skillNames = []
+  for (const a of rest) { if (a.startsWith('-')) break; skillNames.push(a) }
+  if (skillNames.length === 0) process.exit(0)
+  const manifestPath = join(cwd, 'skills-manifest.json')
+  if (!existsSync(manifestPath)) process.exit(0)
+  const manifest = JSON.parse(readFileSync(manifestPath, 'utf-8'))
+  const repos = manifest.skills || {}
+  for (const [repo, list] of Object.entries(repos)) {
+    const arr = Array.isArray(list) ? list : (typeof list === 'object' && list !== null ? Object.keys(list).filter(k => list[k]) : [])
+    const toRemove = skillNames.filter(s => arr.includes(s))
+    if (toRemove.length > 0) runSkillsManifest(['remove', repo, ...toRemove])
+  }
+}
+process.exit(0)