skills-manifest 0.2.1 → 0.3.1

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
@@ -52,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/add-CmzBK4br.mjs

@@ -0,0 +1,32 @@
+import fs from "node:fs/promises";
+import { loadConfig } from "c12";
+import { defineCommand } from "citty";
+
+//#region src/cli/add.ts
+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`);
+	}
+});
+
+//#endregion
+export { add as t };

package/dist/cli/add.d.mts

@@ -0,0 +1,12 @@
+import * as citty6 from "citty";
+
+//#region src/cli/add.d.ts
+declare const add: citty6.CommandDef<{
+  readonly repo: {
+    readonly type: "positional";
+    readonly description: "Repository (e.g. owner/repo or full URL)";
+    readonly required: true;
+  };
+}>;
+//#endregion
+export { add };

package/dist/cli/add.mjs

@@ -0,0 +1,3 @@
+import { t as add } from "../add-CmzBK4br.mjs";
+
+export { add };

package/dist/cli/index.mjs

@@ -1,63 +1,27 @@
-import fs from "node:fs/promises";
-import path from "node:path";
-import process from "node:process";
-import { loadConfig } from "c12";
+import { t as add } from "../add-CmzBK4br.mjs";
+import { t as init } from "../init-4enI_4o6.mjs";
+import { t as install } from "../install-CmdQl0XL.mjs";
+import { t as remove } from "../remove-ByCBLakw.mjs";
+import { t as sync } from "../sync-1OE33hei.mjs";
 import { defineCommand, runMain } from "citty";
-import { x } from "tinyexec";
 
 //#region package.json
-var version = "0.2.1";
+var version = "0.3.1";
 
 //#endregion
 //#region src/cli/index.ts
 runMain(defineCommand({
 	meta: {
-		name: "install",
+		name: "skills-manifest",
 		version,
-		description: "Install skills"
+		description: "A lightweight manifest manager for skills"
 	},
-	async run() {
-		const { config } = await loadConfig({ configFile: "skills-manifest" });
-		const repos = Object.keys(config.skills);
-		for (const repo of repos) {
-			if (typeof config.skills[repo] === "boolean") {
-				await x("skills", [
-					"add",
-					repo,
-					"--agent",
-					...config.agents,
-					"--all",
-					"--yes"
-				], { nodeOptions: { stdio: "inherit" } });
-				continue;
-			}
-			await x("skills", [
-				"add",
-				repo,
-				"--skill",
-				...Array.isArray(config.skills[repo]) ? config.skills[repo] : Object.keys(config.skills[repo]).filter((skill) => config.skills[repo][skill] === true),
-				"--agent",
-				...config.agents,
-				"--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
-			});
-		}
+	subCommands: {
+		add,
+		init,
+		install,
+		remove,
+		sync
 	}
 }));
 

package/dist/cli/init.d.mts

@@ -0,0 +1,6 @@
+import * as citty1 from "citty";
+
+//#region src/cli/init.d.ts
+declare const init: citty1.CommandDef<citty1.ArgsDef>;
+//#endregion
+export { init };

package/dist/cli/init.mjs

@@ -0,0 +1,3 @@
+import { t as init } from "../init-4enI_4o6.mjs";
+
+export { init };

package/dist/cli/install.d.mts

@@ -0,0 +1,6 @@
+import * as citty0 from "citty";
+
+//#region src/cli/install.d.ts
+declare const install: citty0.CommandDef<citty0.ArgsDef>;
+//#endregion
+export { install };

package/dist/cli/install.mjs

@@ -0,0 +1,3 @@
+import { t as install } from "../install-CmdQl0XL.mjs";
+
+export { install };

package/dist/cli/patch.d.mts

@@ -0,0 +1,5 @@
+//#region src/cli/patch.d.ts
+/** Replace node_modules/skills/bin/cli.mjs with wrapper (add/remove sync with skills-manifest.json, add --skip-manifest) */
+declare function patchSkillsCli(): Promise<void>;
+//#endregion
+export { patchSkillsCli };

package/dist/cli/patch.mjs

@@ -0,0 +1,3 @@
+import { t as patchSkillsCli } from "../patch-C3hgBcHP.mjs";
+
+export { patchSkillsCli };

package/dist/cli/remove.d.mts

@@ -0,0 +1,12 @@
+import * as citty3 from "citty";
+
+//#region src/cli/remove.d.ts
+declare const remove: citty3.CommandDef<{
+  readonly repo: {
+    readonly type: "positional";
+    readonly description: "Repository (e.g. owner/repo or full URL)";
+    readonly required: true;
+  };
+}>;
+//#endregion
+export { remove };

package/dist/cli/remove.mjs

@@ -0,0 +1,3 @@
+import { t as remove } from "../remove-ByCBLakw.mjs";
+
+export { remove };

package/dist/cli/sync.d.mts

@@ -0,0 +1,6 @@
+import * as citty4 from "citty";
+
+//#region src/cli/sync.d.ts
+declare const sync: citty4.CommandDef<citty4.ArgsDef>;
+//#endregion
+export { sync };

package/dist/cli/sync.mjs

@@ -0,0 +1,3 @@
+import { t as sync } from "../sync-1OE33hei.mjs";
+
+export { sync };

package/dist/index.d.mts

@@ -1,2 +1,2 @@
-import { n as Skills, r as SkillsManifest, t as Repo } from "./index-OGqMIJuf.mjs";
+import { n as Skills, r as SkillsManifest, t as Repo } from "./index-DeyN5X2A.mjs";
 export { Repo, Skills, SkillsManifest };

package/dist/init-4enI_4o6.mjs

@@ -0,0 +1,48 @@
+import { t as patchSkillsCli } from "./patch-C3hgBcHP.mjs";
+import fs from "node:fs/promises";
+import { defineCommand } from "citty";
+import path from "node:path";
+import process from "node:process";
+import { addDevDependency, installDependencies } from "nypm";
+
+//#region src/cli/init.ts
+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));
+	}
+});
+
+//#endregion
+export { init as t };

package/dist/install-CmdQl0XL.mjs

@@ -0,0 +1,62 @@
+import { t as patchSkillsCli } from "./patch-C3hgBcHP.mjs";
+import fs from "node:fs/promises";
+import { loadConfig } from "c12";
+import { defineCommand } from "citty";
+import path from "node:path";
+import process from "node:process";
+import { x } from "tinyexec";
+
+//#region src/cli/install.ts
+const TARGET_MAP = {
+	cursor: ".cursor",
+	opencode: ".opencode"
+};
+const install = defineCommand({
+	meta: {
+		name: "install",
+		description: "Install skills"
+	},
+	async run() {
+		const { config } = await loadConfig({ configFile: "skills-manifest" });
+		const repos = Object.keys(config.skills);
+		for (const repo of repos) {
+			if (typeof config.skills[repo] === "boolean") {
+				await x("skills", [
+					"add",
+					repo,
+					"--agent",
+					...config.agents,
+					"--all",
+					"--yes"
+				], { nodeOptions: { stdio: "inherit" } });
+				continue;
+			}
+			await x("skills", [
+				"add",
+				repo,
+				"--skill",
+				...Array.isArray(config.skills[repo]) ? config.skills[repo] : Object.keys(config.skills[repo]).filter((skill) => config.skills[repo][skill] === true),
+				"--agent",
+				...config.agents,
+				"--yes"
+			], { nodeOptions: { stdio: "inherit" } });
+		}
+		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();
+	}
+});
+
+//#endregion
+export { install as t };

package/dist/patch-C3hgBcHP.mjs

@@ -0,0 +1,34 @@
+import { createRequire } from "node:module";
+import fs from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+
+//#region src/cli/patch.ts
+const require = createRequire(import.meta.url);
+/** Replace node_modules/skills/bin/cli.mjs with wrapper (add/remove sync with skills-manifest.json, add --skip-manifest) */
+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.");
+	}
+}
+
+//#endregion
+export { patchSkillsCli as t };

package/dist/remove-ByCBLakw.mjs

@@ -0,0 +1,42 @@
+import fs from "node:fs/promises";
+import { loadConfig } from "c12";
+import { defineCommand } from "citty";
+
+//#region src/cli/remove.ts
+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);
+	}
+});
+
+//#endregion
+export { remove as t };

package/dist/sync-1OE33hei.mjs

@@ -0,0 +1,18 @@
+import { t as syncFromSkills } from "./utils-m5dGqHGZ.mjs";
+import { defineCommand } from "citty";
+import process from "node:process";
+
+//#region src/cli/sync.ts
+const sync = defineCommand({
+	meta: {
+		name: "sync",
+		description: "Sync manifest from skills CLI argv (internal)"
+	},
+	async run() {
+		const idx = process.argv.indexOf("sync");
+		await syncFromSkills(idx < 0 ? [] : process.argv.slice(idx + 1));
+	}
+});
+
+//#endregion
+export { sync as t };

package/dist/types/index.d.mts

@@ -1,2 +1,2 @@
-import { n as Skills, r as SkillsManifest, t as Repo } from "../index-OGqMIJuf.mjs";
+import { n as Skills, r as SkillsManifest, t as Repo } from "../index-DeyN5X2A.mjs";
 export { Repo, Skills, SkillsManifest };

package/dist/utils/index.d.mts

@@ -0,0 +1,8 @@
+//#region src/utils/index.d.ts
+interface SyncFromSkillsOptions {
+  cwd?: string;
+}
+/** Parse skills CLI-style argv and sync manifest (used by skills-cli patch). */
+declare function syncFromSkills(argv: string[], options?: SyncFromSkillsOptions): Promise<void>;
+//#endregion
+export { SyncFromSkillsOptions, syncFromSkills };

package/dist/utils/index.mjs

@@ -0,0 +1,3 @@
+import { t as syncFromSkills } from "../utils-m5dGqHGZ.mjs";
+
+export { syncFromSkills };

package/dist/utils-m5dGqHGZ.mjs

@@ -0,0 +1,58 @@
+import fs from "node:fs/promises";
+import { loadConfig } from "c12";
+import path from "node:path";
+import process from "node:process";
+
+//#region src/utils/index.ts
+/** Parse skills CLI-style argv and sync manifest (used by skills-cli patch). */
+async function syncFromSkills(argv, options = {}) {
+	const cmd = argv[0];
+	if (cmd !== "add" && cmd !== "remove") return;
+	const cwd = options.cwd ?? process.cwd();
+	const configPath = path.join(cwd, "skills-manifest.json");
+	try {
+		await fs.access(configPath);
+	} catch {
+		return;
+	}
+	const { config, configFile } = await loadConfig({
+		configFile: "skills-manifest",
+		cwd
+	});
+	if (!configFile) return;
+	if (cmd === "add") {
+		const rest = argv.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) return;
+		const existing = config.skills[repo];
+		const existingList = Array.isArray(existing) ? existing : typeof existing === "object" && existing !== null ? Object.keys(existing).filter((k) => existing[k]) : [];
+		config.skills[repo] = [...new Set([...existingList, ...skills])];
+	} else {
+		const skillNames = argv.slice(1).filter((a) => !a.startsWith("-"));
+		if (skillNames.length === 0) return;
+		for (const [repo, list] of Object.entries(config.skills)) {
+			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) continue;
+			const kept = arr.filter((s) => !toRemove.includes(s));
+			if (kept.length === 0) delete config.skills[repo];
+			else config.skills[repo] = kept;
+		}
+	}
+	await fs.writeFile(configFile, JSON.stringify(config, null, 2));
+}
+
+//#endregion
+export { syncFromSkills as t };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "skills-manifest",
   "type": "module",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "description": "A lightweight manifest manager for skills, enabling project-level skill synchronization and collaborative configuration.",
   "author": "Hairyf <wwu710632@gmail.com>",
   "license": "MIT",
@@ -28,14 +28,16 @@
   },
   "files": [
     "bin",
-    "dist"
+    "dist",
+    "patches"
   ],
   "peerDependencies": {
-    "skills": "^1.2.0"
+    "skills": "^1.3.4"
   },
   "dependencies": {
     "c12": "^3.3.3",
     "citty": "^0.2.0",
+    "nypm": "^0.6.4",
     "tinyexec": "^1.0.2"
   },
   "devDependencies": {
@@ -48,7 +50,7 @@
     "lint-staged": "^16.2.7",
     "publint": "^0.3.16",
     "simple-git-hooks": "^2.13.1",
-    "skills": "^1.2.0",
+    "skills": "^1.3.4",
     "tsdown": "^0.17.3",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
@@ -56,7 +58,7 @@
     "vitest": "^4.0.15",
     "vitest-package-exports": "^0.1.1",
     "yaml": "^2.8.2",
-    "skills-manifest": "0.2.1"
+    "skills-manifest": "0.3.1"
   },
   "simple-git-hooks": {
     "pre-commit": "pnpm i --frozen-lockfile --ignore-scripts --offline && npx lint-staged"

package/patches/skills-cli.mjs

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import { join, dirname } from 'node:path';
+
+const require = createRequire(import.meta.url);
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+const argv = process.argv.slice(2);
+const skipManifest = argv.includes('--skip-manifest');
+const forwardArgs = argv.filter(arg => arg !== '--skip-manifest');
+const [cmd] = forwardArgs;
+
+// 1. 执行主 CLI 程序
+const mainResult = spawnSync(process.execPath, [join(__dirname, '../dist/cli.mjs'), ...forwardArgs], { stdio: 'inherit' });
+
+if (mainResult.status === 0 && !skipManifest && ['add', 'remove'].includes(cmd)) {
+  try {
+    const binPath = require.resolve('skills-manifest/bin/skills-manifest', { paths: [process.cwd()] });
+    spawnSync(process.execPath, [binPath, 'sync', ...forwardArgs], { stdio: 'inherit' });
+  } catch {
+    console.warn('skills-manifest: failed to sync from skills. Sync add/remove with manifest will not run.')
+  }
+}
+
+process.exit(mainResult.status ?? 1);