@hagicode/skillsbase 0.1.0-dev.20260406025440.0.0.local

package/README.md

@@ -0,0 +1,78 @@
+# skillsbase
+
+`skillsbase` 是一个独立 Node CLI，用于初始化和维护“别的 skills 仓库”。
+重点是：本仓库只放 CLI 代码与模板，不提交受管 `skills/` 内容。
+当前源码使用 `TypeScript + Vite 8`。
+
+## Commands
+
+```bash
+node ./bin/skillsbase.mjs init
+node ./bin/skillsbase.mjs sync
+node ./bin/skillsbase.mjs sync --check
+node ./bin/skillsbase.mjs add <skill-name>
+node ./bin/skillsbase.mjs github_action --kind all
+```
+
+开发期常用：
+
+```bash
+npm run build
+npm run cli -- --help
+npm test
+npm run smoke
+node ./bin/skillsbase.mjs <command> --repo /path/to/target-repo
+```
+
+打包产物仍为 `dist/cli.mjs`，`bin/skillsbase.mjs` 只负责发布态加载与开发态回退。
+
+## npm Publish
+
+- workflow: `.github/workflows/npm-publish-dev.yml`
+- `push` 到 `main` 时发布 `dev` dist-tag
+- GitHub Release `published` 且非 draft / prerelease 时发布 `latest`
+- 发布前会执行：
+  - `npm test`
+  - `npm run pack:check`
+- 当前包名：`@hagicode/skillsbase`
+
+发布依赖 npm Trusted Publishing；仓库侧需要在 npm 绑定此 GitHub repository。
+
+## Managed Repo Contract
+
+- `sources.yaml`
+  清单单一真相源，声明来源根目录、命名规则、包含列表与非交互默认值。
+- `skills/<name>/SKILL.md`
+  受管输出。内容来自当前仓库内临时 `npx skills add` 安装结果，再转换为最终形态。
+- `skills/<name>/.skill-source.json`
+  来源、转换、目标路径与安装元数据。
+- `.github/workflows/skills-sync.yml`
+  受管 workflow，执行 `npm test` 与 `skillsbase sync --check`。
+- `.github/actions/skillsbase-sync/action.yml`
+  可复用 composite action。
+
+以上文件属于 **目标 skills 仓库**，不属于本 CLI 仓库本身。
+
+## Non-Interactive Defaults
+
+- 目标仓库默认为当前工作目录。
+- `init` 默认来源根目录：
+  - first-party: `$HOME/.agents/skills`
+  - system: `$HOME/.codex/skills/.system`
+- `add` 默认写入第一个已声明 source block。
+- `github_action` 默认 `--kind workflow`。
+- 若上下文不足以安全写入，命令直接失败并给出诊断；不会进入交互提问。
+
+## Usage Notes
+
+- `sync` 会执行“安装到当前仓库 -> 转换 -> 卸载临时产物 -> 对账写盘”闭环。
+- `sync --check` 不修改最终仓库状态；若发现漂移则返回非零退出码。
+- `sync --allow-missing-sources` 可在来源根目录暂缺时跳过该来源。
+- `github_action` 仅覆盖带 `Managed by skillsbase CLI` 标记的文件；冲突文件需显式 `--force`。
+
+## Development
+
+- `npm test`
+  跑 CLI 单测。
+- `npm run smoke`
+  在临时目录创建一个示例 managed repo，验证 `init -> sync -> sync --check -> github_action`。

package/bin/skillsbase.mjs

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+
+import { spawn } from "node:child_process";
+import path from "node:path";
+import { access } from "node:fs/promises";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const moduleDir = path.dirname(fileURLToPath(import.meta.url));
+const bundledEntry = path.resolve(moduleDir, "..", "dist", "cli.mjs");
+const sourceEntry = path.resolve(moduleDir, "..", "src", "cli-entry.ts");
+
+async function canAccess(targetPath) {
+  try {
+    await access(targetPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+if (await canAccess(bundledEntry)) {
+  await import(pathToFileURL(bundledEntry).href);
+} else if (await canAccess(sourceEntry)) {
+  const exitCode = await new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, ["--import", "tsx", sourceEntry, ...process.argv.slice(2)], {
+      stdio: "inherit",
+      env: process.env,
+    });
+
+    child.on("error", reject);
+    child.on("exit", (code, signal) => {
+      if (signal) {
+        reject(new Error(`skillsbase CLI terminated with signal ${signal}.`));
+        return;
+      }
+
+      resolve(code ?? 1);
+    });
+  });
+
+  process.exitCode = exitCode;
+} else {
+  throw new Error("Unable to locate the skillsbase CLI entrypoint.");
+}

package/dist/cli.mjs

@@ -0,0 +1,969 @@
+import path from "node:path";
+import { promises } from "node:fs";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { fileURLToPath } from "node:url";
+import os from "node:os";
+//#region src/lib/output.ts
+var CliError = class extends Error {
+	exitCode;
+	details;
+	nextSteps;
+	constructor(message, options = {}) {
+		super(message);
+		this.name = "CliError";
+		this.exitCode = options.exitCode ?? 1;
+		this.details = options.details ?? [];
+		this.nextSteps = options.nextSteps ?? [];
+	}
+};
+function printCommandUsage(stdout) {
+	stdout.write([
+		"Usage: skillsbase <command> [options]",
+		"",
+		"Commands:",
+		"  init            Create the managed repository baseline",
+		"  sync            Reconcile managed skills from sources.yaml",
+		"  add             Add a skill to a source block and sync",
+		"  github_action   Generate managed GitHub Actions assets",
+		"",
+		"Global Options:",
+		"  --repo <path>   Target repository path (default: current directory)",
+		"  --help, -h      Show help",
+		"  --version, -v   Show version",
+		""
+	].join("\n"));
+}
+function printCommandResult(result, output) {
+	const lines = [
+		`## ${result.title ?? result.command}`,
+		"",
+		`repository: ${result.repository}`,
+		`exit_code: ${result.exitCode ?? 0}`
+	];
+	if (result.schema) lines.push(`schema: ${result.schema}`);
+	if (result.items?.length) {
+		lines.push("", "items:");
+		for (const item of result.items) lines.push(`- ${item}`);
+	}
+	if (result.nextSteps?.length) {
+		lines.push("", "next:");
+		for (const nextStep of result.nextSteps) lines.push(`- ${nextStep}`);
+	}
+	lines.push("");
+	output.write(`${lines.join("\n")}\n`);
+}
+//#endregion
+//#region src/lib/constants.ts
+var MANAGED_SIGNATURE = "Managed by skillsbase CLI";
+var DEFAULT_SKILLS_CLI_VERSION = "1.4.8";
+var DEFAULT_INSTALL_AGENT = "codex";
+var DEFAULT_SKILLS_ROOT = "skills";
+var DEFAULT_METADATA_FILE = ".skill-source.json";
+var DEFAULT_MANAGED_BY = "skillsbase";
+var DEFAULT_NODE_VERSION = "22.12.0";
+//#endregion
+//#region src/lib/files.ts
+async function pathExists(targetPath) {
+	try {
+		await promises.access(targetPath);
+		return true;
+	} catch {
+		return false;
+	}
+}
+async function readFileIfExists(targetPath, encoding = "utf8") {
+	if (!await pathExists(targetPath)) return null;
+	return promises.readFile(targetPath, encoding);
+}
+async function ensureDirectory(targetPath) {
+	await promises.mkdir(targetPath, { recursive: true });
+}
+async function listDirectories(rootPath) {
+	if (!await pathExists(rootPath)) return [];
+	return (await promises.readdir(rootPath, { withFileTypes: true })).filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort((left, right) => left.localeCompare(right));
+}
+async function collectRelativeFiles(rootPath, basePath = rootPath) {
+	const entries = await promises.readdir(rootPath, { withFileTypes: true });
+	const files = [];
+	for (const entry of [...entries].sort((left, right) => left.name.localeCompare(right.name))) {
+		const absolutePath = path.join(rootPath, entry.name);
+		if (entry.isDirectory()) {
+			files.push(...await collectRelativeFiles(absolutePath, basePath));
+			continue;
+		}
+		if (entry.isFile()) files.push(toPosix(path.relative(basePath, absolutePath)));
+	}
+	return files;
+}
+async function readTree(rootPath) {
+	const files = await collectRelativeFiles(rootPath);
+	const tree = /* @__PURE__ */ new Map();
+	for (const relativePath of files) tree.set(relativePath, await promises.readFile(path.join(rootPath, relativePath)));
+	return tree;
+}
+async function writeTree(rootPath, tree) {
+	await promises.rm(rootPath, {
+		recursive: true,
+		force: true
+	});
+	await promises.mkdir(rootPath, { recursive: true });
+	for (const [relativePath, content] of [...tree.entries()].sort(([left], [right]) => left.localeCompare(right))) {
+		const targetPath = path.join(rootPath, relativePath);
+		await promises.mkdir(path.dirname(targetPath), { recursive: true });
+		await promises.writeFile(targetPath, content);
+	}
+}
+async function removeIfEmptyUpward(startPath, stopPath) {
+	let currentPath = startPath;
+	const normalizedStop = path.resolve(stopPath);
+	while (currentPath.startsWith(normalizedStop) && currentPath !== normalizedStop) {
+		if (!await pathExists(currentPath)) {
+			currentPath = path.dirname(currentPath);
+			continue;
+		}
+		if ((await promises.readdir(currentPath)).length > 0) return;
+		await promises.rmdir(currentPath);
+		currentPath = path.dirname(currentPath);
+	}
+}
+function stableJson(value) {
+	return `${JSON.stringify(value, null, 2)}\n`;
+}
+function toPosix(filePath) {
+	return filePath.split(path.sep).join(path.posix.sep);
+}
+//#endregion
+//#region src/lib/manifest.ts
+function parseScalar(rawValue) {
+	const value = rawValue.trim();
+	if (value.length === 0) return "";
+	if (value === "true") return true;
+	if (value === "false") return false;
+	if (/^-?\d+$/.test(value)) return Number(value);
+	if (value.startsWith("\"") && value.endsWith("\"") || value.startsWith("'") && value.endsWith("'")) return value.slice(1, -1);
+	return value;
+}
+function quoteYamlString(value) {
+	if (value === "") return "\"\"";
+	if (/^[A-Za-z0-9._/@:+-]+$/.test(value)) return value;
+	return JSON.stringify(value);
+}
+function validateSource(source) {
+	for (const key of [
+		"key",
+		"label",
+		"kind",
+		"root",
+		"targetPrefix",
+		"include"
+	]) if (!(key in source)) throw new CliError(`Source "${source.key ?? "<unknown>"}" is missing key "${key}".`, { details: ["Repair `sources.yaml` or rerun `skillsbase init`."] });
+	if (!Array.isArray(source.include) || source.include.some((value) => typeof value !== "string")) throw new CliError(`Source "${source.key}" must define an include list.`, { details: ["Use `include: []` only via the CLI serializer; do not change its type."] });
+	return {
+		key: String(source.key),
+		label: String(source.label),
+		kind: String(source.kind),
+		root: String(source.root),
+		targetPrefix: String(source.targetPrefix),
+		include: [...source.include]
+	};
+}
+function createManifest(repoPath, options = {}) {
+	return {
+		version: 1,
+		skillsRoot: DEFAULT_SKILLS_ROOT,
+		metadataFile: DEFAULT_METADATA_FILE,
+		managedBy: DEFAULT_MANAGED_BY,
+		remoteRepository: options.remoteRepository ?? path.basename(repoPath),
+		staleCleanup: true,
+		skillsCliVersion: DEFAULT_SKILLS_CLI_VERSION,
+		installAgent: DEFAULT_INSTALL_AGENT,
+		sources: options.sources ?? [],
+		manifestPath: path.join(repoPath, "sources.yaml"),
+		repoPath
+	};
+}
+function serialiseManifest(manifest) {
+	const lines = [
+		"# Managed by skillsbase CLI.",
+		"# Edit source entries to add or remove managed skills.",
+		`version: ${manifest.version}`,
+		`skillsRoot: ${quoteYamlString(manifest.skillsRoot)}`,
+		`metadataFile: ${quoteYamlString(manifest.metadataFile)}`,
+		`managedBy: ${quoteYamlString(manifest.managedBy)}`,
+		`remoteRepository: ${quoteYamlString(manifest.remoteRepository)}`,
+		`staleCleanup: ${manifest.staleCleanup ? "true" : "false"}`,
+		`skillsCliVersion: ${quoteYamlString(manifest.skillsCliVersion ?? "1.4.8")}`,
+		`installAgent: ${quoteYamlString(manifest.installAgent ?? "codex")}`,
+		"sources:"
+	];
+	for (const source of manifest.sources) {
+		lines.push(`  - key: ${quoteYamlString(source.key)}`);
+		lines.push(`    label: ${quoteYamlString(source.label)}`);
+		lines.push(`    kind: ${quoteYamlString(source.kind)}`);
+		lines.push(`    root: ${quoteYamlString(source.root)}`);
+		lines.push(`    targetPrefix: ${quoteYamlString(source.targetPrefix ?? "")}`);
+		lines.push("    include:");
+		for (const skillName of source.include ?? []) lines.push(`      - ${quoteYamlString(skillName)}`);
+	}
+	return `${lines.join("\n")}\n`;
+}
+function validateManifest(manifest) {
+	for (const key of [
+		"version",
+		"skillsRoot",
+		"metadataFile",
+		"managedBy",
+		"remoteRepository",
+		"staleCleanup",
+		"sources"
+	]) if (!(key in manifest)) throw new CliError(`Missing required manifest key: ${key}`, { details: ["Run `skillsbase init` to recreate the baseline contract."] });
+	if (!Array.isArray(manifest.sources) || typeof manifest.version !== "number" || typeof manifest.skillsRoot !== "string" || typeof manifest.metadataFile !== "string" || typeof manifest.managedBy !== "string" || typeof manifest.remoteRepository !== "string" || typeof manifest.staleCleanup !== "boolean") throw new CliError("Manifest `sources` must be a list.", { details: ["Repair `sources.yaml` and try again."] });
+	return {
+		version: manifest.version,
+		skillsRoot: manifest.skillsRoot,
+		metadataFile: manifest.metadataFile,
+		managedBy: manifest.managedBy,
+		remoteRepository: manifest.remoteRepository,
+		staleCleanup: manifest.staleCleanup,
+		skillsCliVersion: typeof manifest.skillsCliVersion === "string" ? manifest.skillsCliVersion : DEFAULT_SKILLS_CLI_VERSION,
+		installAgent: typeof manifest.installAgent === "string" ? manifest.installAgent : DEFAULT_INSTALL_AGENT,
+		sources: manifest.sources.map(validateSource),
+		manifestPath: typeof manifest.manifestPath === "string" ? manifest.manifestPath : "",
+		repoPath: typeof manifest.repoPath === "string" ? manifest.repoPath : "",
+		skillsRootPath: typeof manifest.skillsRootPath === "string" ? manifest.skillsRootPath : void 0
+	};
+}
+async function loadManifest(repoPath) {
+	const manifestPath = path.join(repoPath, "sources.yaml");
+	if (!await pathExists(manifestPath)) throw new CliError("Missing `sources.yaml`.", { details: [`Repository: ${repoPath}`, "Run `skillsbase init` first, then retry the command."] });
+	const text = await promises.readFile(manifestPath, "utf8");
+	const manifest = { sources: [] };
+	const lines = text.split(/\r?\n/);
+	let currentSource = null;
+	let currentListKey = null;
+	for (const [index, rawLine] of lines.entries()) {
+		const line = rawLine.replace(/\s+$/, "");
+		const lineNumber = index + 1;
+		if (line.length === 0 || line.trimStart().startsWith("#")) continue;
+		const topLevelMatch = /^([A-Za-z][A-Za-z0-9]*):\s*(.*)$/.exec(line);
+		if (topLevelMatch && !line.startsWith(" ")) {
+			const [, key, value] = topLevelMatch;
+			if (key === "sources") {
+				currentSource = null;
+				currentListKey = null;
+			} else manifest[key] = parseScalar(value);
+			continue;
+		}
+		const sourceStartMatch = /^  - key:\s*(.+)$/.exec(line);
+		if (sourceStartMatch) {
+			currentSource = {
+				key: parseScalar(sourceStartMatch[1]),
+				include: []
+			};
+			manifest.sources.push(currentSource);
+			currentListKey = null;
+			continue;
+		}
+		const sourcePropertyMatch = /^    ([A-Za-z][A-Za-z0-9]*):\s*(.*)$/.exec(line);
+		if (sourcePropertyMatch && currentSource) {
+			const [, key, value] = sourcePropertyMatch;
+			if (value.length === 0) {
+				currentSource[key] = [];
+				currentListKey = key;
+			} else {
+				currentSource[key] = parseScalar(value);
+				currentListKey = null;
+			}
+			continue;
+		}
+		const listItemMatch = /^      - (.+)$/.exec(line);
+		if (listItemMatch && currentSource && currentListKey) {
+			const listValue = currentSource[currentListKey];
+			if (!Array.isArray(listValue)) throw new CliError(`Invalid list state for "${currentListKey}" at line ${lineNumber}.`);
+			listValue.push(parseScalar(listItemMatch[1]));
+			continue;
+		}
+		throw new CliError(`Unsupported sources.yaml syntax at line ${lineNumber}.`, { details: [rawLine] });
+	}
+	const validated = validateManifest(manifest);
+	return {
+		...validated,
+		manifestPath,
+		repoPath,
+		skillsRootPath: path.join(repoPath, validated.skillsRoot)
+	};
+}
+async function saveManifest(manifest) {
+	const nextText = serialiseManifest(manifest);
+	await promises.writeFile(manifest.manifestPath, nextText, "utf8");
+}
+function buildManifestEntries(manifest, repoPath = manifest.repoPath) {
+	const entries = [];
+	for (const source of manifest.sources) for (const originalName of source.include ?? []) {
+		const targetName = `${source.targetPrefix ?? ""}${originalName}`;
+		entries.push({
+			sourceKey: source.key,
+			sourceLabel: source.label,
+			sourceKind: source.kind,
+			sourceRoot: source.root,
+			sourcePath: path.join(source.root, originalName),
+			originalName,
+			targetName,
+			targetPath: path.join(repoPath, manifest.skillsRoot, targetName),
+			targetPathRelative: toPosix(path.join(manifest.skillsRoot, targetName))
+		});
+	}
+	const collisions = /* @__PURE__ */ new Map();
+	for (const entry of entries) {
+		const keys = collisions.get(entry.targetName) ?? [];
+		keys.push(entry.sourceKey);
+		collisions.set(entry.targetName, keys);
+	}
+	const duplicateTargets = [...collisions.entries()].filter(([, keys]) => keys.length > 1);
+	if (duplicateTargets.length > 0) throw new CliError(`Manifest target-name collision detected: ${duplicateTargets.map(([targetName, keys]) => `${targetName} (${keys.join(", ")})`).join(", ")}`, { details: ["Adjust `targetPrefix` or `include` entries in `sources.yaml`."] });
+	return entries.sort((left, right) => left.targetName.localeCompare(right.targetName));
+}
+function addSkillToManifest(manifest, skillName, options = {}) {
+	if (manifest.sources.length === 0) throw new CliError("Manifest does not declare any source blocks.", { details: ["Run `skillsbase init` first or add a source block to `sources.yaml`."] });
+	const selectedSource = options.sourceKey == null ? manifest.sources[0] : manifest.sources.find((source) => source.key === options.sourceKey);
+	if (!selectedSource) throw new CliError(`Unknown source key: ${options.sourceKey}`, { details: [`Declared sources: ${manifest.sources.map((source) => source.key).join(", ")}`] });
+	const include = new Set(selectedSource.include ?? []);
+	include.add(skillName);
+	selectedSource.include = [...include].sort((left, right) => left.localeCompare(right));
+	return {
+		...manifest,
+		sources: manifest.sources.map((source) => source.key === selectedSource.key ? { ...selectedSource } : {
+			...source,
+			include: [...source.include]
+		})
+	};
+}
+function buildMetadata(manifest, entry, installRecord) {
+	return {
+		schemaVersion: 1,
+		managed: true,
+		managedBy: manifest.managedBy,
+		sourceKey: entry.sourceKey,
+		sourceKind: entry.sourceKind,
+		sourceLabel: entry.sourceLabel,
+		sourceRoot: entry.sourceRoot,
+		sourcePath: entry.sourcePath,
+		originalName: entry.originalName,
+		targetName: entry.targetName,
+		targetPath: entry.targetPathRelative,
+		remoteRepository: manifest.remoteRepository,
+		installAgent: manifest.installAgent,
+		installReference: installRecord.installReference,
+		installedMetadata: installRecord.installedMetadata,
+		files: [...installRecord.files].sort((left, right) => left.localeCompare(right))
+	};
+}
+//#endregion
+//#region src/lib/installer.ts
+var execFile$1 = promisify(execFile);
+function buildNpxArgs(manifest, subcommand, extraArgs) {
+	return [
+		"--yes",
+		`skills@${manifest.skillsCliVersion}`,
+		subcommand,
+		...extraArgs
+	];
+}
+function renderExecFailure(error) {
+	if (error instanceof Error) {
+		const execError = error;
+		return execError.stderr ?? execError.stdout ?? execError.message;
+	}
+	return String(error);
+}
+async function installIntoCurrentRepository(repoPath, manifest, entry, options = {}) {
+	const installPath = path.join(repoPath, ".agents", "skills", entry.originalName);
+	const lockPath = path.join(repoPath, "skills-lock.json");
+	const snapshot = {
+		installPath,
+		lockPath,
+		installTree: await snapshotTree(installPath),
+		lockText: await readFileIfExists(lockPath),
+		installReference: entry.sourcePath
+	};
+	try {
+		await execFile$1("npx", buildNpxArgs(manifest, "add", [
+			entry.sourcePath,
+			"--agent",
+			manifest.installAgent,
+			"--copy",
+			"-y"
+		]), {
+			cwd: repoPath,
+			env: options.env,
+			maxBuffer: 16 * 1024 * 1024,
+			timeout: 6e4
+		});
+	} catch (error) {
+		throw new CliError(`skills install failed for ${entry.originalName}.`, { details: [renderExecFailure(error)] });
+	}
+	if (!await pathExists(installPath)) throw new CliError(`skills install did not create ${path.relative(repoPath, installPath)}.`, { details: ["The `npx skills` install output was not in the expected current-repository shape."] });
+	return {
+		installPath,
+		lockPath,
+		installReference: entry.sourcePath,
+		snapshot
+	};
+}
+async function cleanupInstalledSkill(repoPath, manifest, entry, installState, options = {}) {
+	let removeError = null;
+	try {
+		await execFile$1("npx", buildNpxArgs(manifest, "remove", [entry.originalName, "-y"]), {
+			cwd: repoPath,
+			env: options.env,
+			maxBuffer: 16 * 1024 * 1024,
+			timeout: 6e4
+		});
+	} catch (error) {
+		removeError = error;
+	}
+	try {
+		await restoreSnapshot(installState.snapshot);
+		await removeIfEmptyUpward(path.join(repoPath, ".agents", "skills"), repoPath);
+	} catch (restoreError) {
+		const restoreMessage = restoreError instanceof Error ? restoreError.message : String(restoreError);
+		throw new CliError(`Cleanup failed for ${entry.originalName}.`, { details: [restoreMessage, removeError ? renderExecFailure(removeError) : null].filter((value) => Boolean(value)) });
+	}
+	if (removeError) throw new CliError(`skills uninstall failed for ${entry.originalName}.`, { details: [renderExecFailure(removeError)] });
+}
+async function snapshotTree(rootPath) {
+	if (!await pathExists(rootPath)) return null;
+	const entries = await promises.readdir(rootPath, { withFileTypes: true });
+	const tree = /* @__PURE__ */ new Map();
+	for (const entry of entries) {
+		const absolutePath = path.join(rootPath, entry.name);
+		if (entry.isDirectory()) {
+			const nested = await snapshotTree(absolutePath);
+			if (!nested) continue;
+			for (const [relativePath, content] of nested.entries()) tree.set(path.join(entry.name, relativePath), content);
+			continue;
+		}
+		if (entry.isFile()) tree.set(entry.name, await promises.readFile(absolutePath));
+	}
+	return tree;
+}
+async function restoreSnapshot(snapshot) {
+	if (snapshot.installTree == null) await promises.rm(snapshot.installPath, {
+		recursive: true,
+		force: true
+	});
+	else {
+		await promises.rm(snapshot.installPath, {
+			recursive: true,
+			force: true
+		});
+		await promises.mkdir(snapshot.installPath, { recursive: true });
+		for (const [relativePath, content] of snapshot.installTree.entries()) {
+			const targetPath = path.join(snapshot.installPath, relativePath);
+			await promises.mkdir(path.dirname(targetPath), { recursive: true });
+			await promises.writeFile(targetPath, content);
+		}
+	}
+	if (snapshot.lockText == null) await promises.rm(snapshot.lockPath, { force: true });
+	else await promises.writeFile(snapshot.lockPath, snapshot.lockText, "utf8");
+	await removeIfEmptyUpward(path.dirname(snapshot.installPath), path.dirname(snapshot.lockPath));
+}
+//#endregion
+//#region src/lib/skill-converter.ts
+function rewriteSkillName(content, targetName) {
+	const frontmatterMatch = /^---\n([\s\S]*?)\n---/.exec(content);
+	if (!frontmatterMatch) throw new CliError("Installed SKILL.md is missing YAML frontmatter.", { details: ["The upstream skill must contain a valid `name` field."] });
+	if (!/^name:\s*.+$/m.test(frontmatterMatch[1])) throw new CliError("Installed SKILL.md frontmatter is missing a `name` field.");
+	const updatedFrontmatter = frontmatterMatch[1].replace(/^name:\s*.+$/m, `name: ${targetName}`);
+	return content.replace(frontmatterMatch[0], `---\n${updatedFrontmatter}\n---`);
+}
+async function convertInstalledSkill(_manifest, entry, installState) {
+	const installedPath = installState.installPath;
+	const skillPath = path.join(installedPath, "SKILL.md");
+	try {
+		await promises.access(skillPath);
+	} catch {
+		throw new CliError(`Installed skill is missing SKILL.md: ${entry.originalName}`);
+	}
+	const filePaths = await collectRelativeFiles(installedPath);
+	const outputTree = /* @__PURE__ */ new Map();
+	for (const relativePath of filePaths) {
+		if (relativePath === "hagicode-skill.json" || relativePath === ".skill-source.json") continue;
+		const absolutePath = path.join(installedPath, relativePath);
+		if (relativePath === "SKILL.md") {
+			const content = await promises.readFile(absolutePath, "utf8");
+			outputTree.set(relativePath, Buffer.from(rewriteSkillName(content, entry.targetName), "utf8"));
+			continue;
+		}
+		outputTree.set(relativePath, await promises.readFile(absolutePath));
+	}
+	const installedMetadataPath = path.join(installedPath, "hagicode-skill.json");
+	let installedMetadata;
+	try {
+		installedMetadata = JSON.parse(await promises.readFile(installedMetadataPath, "utf8"));
+	} catch {
+		installedMetadata = {
+			schemaVersion: 1,
+			source: entry.sourceRoot,
+			skillSlug: entry.originalName,
+			installReference: installState.installReference,
+			synthesizedBy: "skillsbase"
+		};
+	}
+	return {
+		files: [...outputTree.keys()].sort((left, right) => left.localeCompare(right)),
+		outputTree,
+		installedMetadata,
+		installReference: installState.installReference,
+		targetName: entry.targetName,
+		targetPath: entry.targetPath,
+		targetPathRelative: entry.targetPathRelative
+	};
+}
+//#endregion
+//#region src/lib/sync-engine.ts
+async function assertSourceState(entry, allowMissingSources) {
+	if (!await pathExists(entry.sourceRoot)) {
+		if (allowMissingSources) return {
+			skip: true,
+			reason: `missing source root: ${entry.sourceRoot}`
+		};
+		throw new CliError(`Managed source root does not exist: ${entry.sourceRoot}`, { details: ["Use `skillsbase sync --allow-missing-sources` to skip missing roots."] });
+	}
+	if (!await pathExists(entry.sourcePath)) throw new CliError(`Managed skill is missing from source root: ${entry.sourcePath}`, { details: [`source: ${entry.sourceKey}`, `skill: ${entry.originalName}`] });
+	return { skip: false };
+}
+async function assertManagedTargetWritable(manifest, entry) {
+	if (!await pathExists(entry.targetPath)) return;
+	const metadataPath = path.join(entry.targetPath, manifest.metadataFile);
+	if (!await pathExists(metadataPath)) throw new CliError(`Refusing to overwrite unmanaged directory: ${entry.targetPathRelative}`, { details: ["Add metadata manually or remove the conflicting directory first."] });
+	const metadata = JSON.parse(await promises.readFile(metadataPath, "utf8"));
+	if (!metadata.managed || metadata.managedBy !== manifest.managedBy) throw new CliError(`Refusing to overwrite unmanaged directory: ${entry.targetPathRelative}`, { details: [`Found metadata managedBy=${JSON.stringify(metadata.managedBy)}`] });
+}
+async function snapshotTargetDirectory(targetPath) {
+	if (!await pathExists(targetPath)) return null;
+	return {
+		path: targetPath,
+		tree: await readTree(targetPath)
+	};
+}
+async function restoreTargetDirectory(snapshot) {
+	if (snapshot == null) return;
+	await writeTree(snapshot.path, snapshot.tree);
+}
+async function compareTarget(manifest, entry, desiredTree, desiredMetadata) {
+	if (!await pathExists(entry.targetPath)) return [`missing target directory: ${entry.targetPathRelative}`];
+	const actualFiles = (await collectRelativeFiles(entry.targetPath)).sort((left, right) => left.localeCompare(right));
+	const desiredFiles = [...desiredTree.keys(), manifest.metadataFile].sort((left, right) => left.localeCompare(right));
+	if (JSON.stringify(actualFiles) !== JSON.stringify(desiredFiles)) return [`file set drift: ${entry.targetPathRelative}`];
+	const actualTree = await readTree(entry.targetPath);
+	for (const [relativePath, buffer] of desiredTree.entries()) {
+		const actual = actualTree.get(relativePath);
+		if (!actual || !actual.equals(buffer)) return [`file content drift: ${entry.targetPathRelative}/${relativePath}`];
+	}
+	const metadataPath = path.join(entry.targetPath, manifest.metadataFile);
+	if (await promises.readFile(metadataPath, "utf8") !== stableJson(desiredMetadata)) return [`metadata drift: ${entry.targetPathRelative}/${manifest.metadataFile}`];
+	return [];
+}
+async function reconcileStaleTargets(repoPath, manifest, declaredTargets, check) {
+	const changes = [];
+	const skillsRootPath = path.join(repoPath, manifest.skillsRoot);
+	const existingDirectories = await listDirectories(skillsRootPath);
+	for (const directoryName of existingDirectories) {
+		if (declaredTargets.has(directoryName)) continue;
+		const candidatePath = path.join(skillsRootPath, directoryName);
+		const metadataPath = path.join(candidatePath, manifest.metadataFile);
+		if (!await pathExists(metadataPath)) continue;
+		const metadata = JSON.parse(await promises.readFile(metadataPath, "utf8"));
+		if (!metadata.managed || metadata.managedBy !== manifest.managedBy) continue;
+		if (check) {
+			changes.push(`stale managed directory: ${path.posix.join(manifest.skillsRoot, directoryName)}`);
+			continue;
+		}
+		await promises.rm(candidatePath, {
+			recursive: true,
+			force: true
+		});
+		changes.push(`removed stale: ${path.posix.join(manifest.skillsRoot, directoryName)}`);
+	}
+	return changes;
+}
+async function executeSync(options) {
+	const { repoPath, manifest, check, allowMissingSources, env } = options;
+	const entries = buildManifestEntries(manifest, repoPath);
+	const items = [];
+	const skipped = [];
+	const declaredTargets = new Set(entries.map((entry) => entry.targetName));
+	const preparedEntries = [];
+	const checkSnapshots = /* @__PURE__ */ new Map();
+	await ensureDirectory(path.join(repoPath, manifest.skillsRoot));
+	if (check) for (const entry of entries) checkSnapshots.set(entry.targetPath, await snapshotTargetDirectory(entry.targetPath));
+	for (const entry of entries) {
+		if ((await assertSourceState(entry, allowMissingSources)).skip) {
+			skipped.push(`${entry.sourceKey}: ${entry.originalName}`);
+			continue;
+		}
+		const installState = await installIntoCurrentRepository(repoPath, manifest, entry, { env });
+		try {
+			const converted = await convertInstalledSkill(manifest, entry, installState);
+			const metadata = buildMetadata(manifest, entry, {
+				installReference: converted.installReference,
+				installedMetadata: converted.installedMetadata,
+				files: converted.files
+			});
+			preparedEntries.push({
+				entry,
+				converted,
+				metadata
+			});
+		} finally {
+			await cleanupInstalledSkill(repoPath, manifest, entry, installState, { env });
+		}
+	}
+	if (check) for (const prepared of preparedEntries) {
+		await restoreTargetDirectory(checkSnapshots.get(prepared.entry.targetPath) ?? null);
+		items.push(...await compareTarget(manifest, prepared.entry, prepared.converted.outputTree, prepared.metadata));
+	}
+	else for (const prepared of preparedEntries) {
+		await assertManagedTargetWritable(manifest, prepared.entry);
+		const nextTree = new Map(prepared.converted.outputTree);
+		nextTree.set(manifest.metadataFile, Buffer.from(stableJson(prepared.metadata), "utf8"));
+		await writeTree(prepared.entry.targetPath, nextTree);
+		items.push(`synced: ${prepared.entry.targetPathRelative}`);
+	}
+	items.push(...await reconcileStaleTargets(repoPath, manifest, declaredTargets, check));
+	if (skipped.length > 0) items.push(`skipped missing sources: ${skipped.join(", ")}`);
+	const driftDetected = check && items.some((item) => !item.startsWith("skipped "));
+	return {
+		command: "sync",
+		title: check ? "skillsbase sync --check" : "skillsbase sync",
+		repository: repoPath,
+		exitCode: driftDetected ? 1 : 0,
+		schema: "spec-driven",
+		items: items.length > 0 ? items : [check ? "no drift detected" : "nothing to sync"],
+		nextSteps: driftDetected ? ["skillsbase sync"] : []
+	};
+}
+//#endregion
+//#region src/commands/add.ts
+async function runAddCommand(context) {
+	const repoFlag = typeof context.flags.repo === "string" ? context.flags.repo : void 0;
+	const sourceFlag = typeof context.flags.source === "string" ? context.flags.source : void 0;
+	const repoPath = path.resolve(repoFlag ?? context.cwd);
+	const skillName = context.args[0];
+	if (!skillName) throw new CliError("`skillsbase add` requires a skill name.", { details: ["Usage: `skillsbase add <skill-name> [--source <key>]`."] });
+	const nextManifest = addSkillToManifest(await loadManifest(repoPath), skillName, { sourceKey: sourceFlag });
+	await saveManifest(nextManifest);
+	const result = await executeSync({
+		repoPath,
+		manifest: nextManifest,
+		env: context.env,
+		check: false,
+		allowMissingSources: context.flags["allow-missing-sources"] === true
+	});
+	return {
+		...result,
+		title: `skillsbase add ${skillName}`,
+		items: [`manifest updated: ${path.relative(repoPath, nextManifest.manifestPath) || "sources.yaml"}`, ...result.items]
+	};
+}
+//#endregion
+//#region src/lib/templates.ts
+var moduleDir = path.dirname(fileURLToPath(import.meta.url));
+var templateRootCandidates = [path.resolve(moduleDir, "..", "..", "templates"), path.resolve(moduleDir, "..", "templates")];
+async function resolveTemplateRoot() {
+	for (const candidate of templateRootCandidates) if (await pathExists(candidate)) return candidate;
+	throw new CliError("Unable to locate the bundled templates directory.");
+}
+async function renderTemplate(relativePath, variables) {
+	const templateRoot = await resolveTemplateRoot();
+	const templatePath = path.join(templateRoot, relativePath);
+	let content = await promises.readFile(templatePath, "utf8");
+	for (const [key, value] of Object.entries(variables)) content = content.replaceAll(`{{${key}}}`, value);
+	return content;
+}
+function managedMarkerFor(targetPath) {
+	if (targetPath.endsWith(".md")) return `<!-- ${MANAGED_SIGNATURE}. -->`;
+	return `# ${MANAGED_SIGNATURE}.`;
+}
+function isManagedContent(targetPath, content) {
+	return content.includes(managedMarkerFor(targetPath));
+}
+async function writeManagedFile(targetPath, content, options = {}) {
+	const marker = managedMarkerFor(targetPath);
+	if (!content.includes(marker)) throw new CliError(`Managed template is missing its marker: ${targetPath}`);
+	const current = await pathExists(targetPath) ? await promises.readFile(targetPath, "utf8") : null;
+	if (current === content) return {
+		status: "unchanged",
+		path: targetPath
+	};
+	if (current != null && !isManagedContent(targetPath, current) && !options.force) throw new CliError(`Refusing to overwrite unmanaged file: ${targetPath}`, { details: ["Use `--force` to replace the conflicting file."] });
+	await promises.mkdir(path.dirname(targetPath), { recursive: true });
+	await promises.writeFile(targetPath, content, "utf8");
+	return {
+		status: current == null ? "created" : "updated",
+		path: targetPath
+	};
+}
+async function writeGithubActions(repoPath, options = {}) {
+	const kind = options.kind ?? "workflow";
+	const variables = { NODE_VERSION: DEFAULT_NODE_VERSION };
+	const targets = [];
+	if (kind === "workflow" || kind === "all") targets.push({
+		relativePath: path.join(".github", "workflows", "skills-sync.yml"),
+		template: path.join("workflows", "skills-sync.yml")
+	});
+	if (kind === "action" || kind === "all") targets.push({
+		relativePath: path.join(".github", "actions", "skillsbase-sync", "action.yml"),
+		template: path.join("actions", "skillsbase-sync", "action.yml")
+	});
+	if (targets.length === 0) throw new CliError(`Unsupported github_action kind: ${kind}`, { details: ["Supported values: workflow, action, all."] });
+	const items = [];
+	for (const target of targets) {
+		const content = await renderTemplate(target.template, variables);
+		const status = await writeManagedFile(path.join(repoPath, target.relativePath), content, { force: Boolean(options.force) });
+		items.push(`${status.status}: ${target.relativePath}`);
+	}
+	return {
+		command: "github_action",
+		title: `skillsbase github_action --kind ${kind}`,
+		repository: repoPath,
+		exitCode: 0,
+		items,
+		nextSteps: []
+	};
+}
+//#endregion
+//#region src/commands/github-action.ts
+async function runGithubActionCommand(context) {
+	const repoFlag = typeof context.flags.repo === "string" ? context.flags.repo : void 0;
+	const kindFlag = typeof context.flags.kind === "string" ? context.flags.kind : void 0;
+	return writeGithubActions(path.resolve(repoFlag ?? context.cwd), {
+		kind: kindFlag ?? "workflow",
+		force: context.flags.force === true
+	});
+}
+//#endregion
+//#region src/lib/repo-init.ts
+function defaultRoots(options = {}) {
+	const home = os.homedir();
+	return {
+		firstPartyRoot: path.resolve(options.firstPartyRoot ?? path.join(home, ".agents", "skills")),
+		systemRoot: path.resolve(options.systemRoot ?? path.join(home, ".codex", "skills", ".system"))
+	};
+}
+async function createDefaultSource(key, label, kind, root, targetPrefix) {
+	return {
+		key,
+		label,
+		kind,
+		root,
+		targetPrefix,
+		include: await pathExists(root) ? await listDirectories(root) : []
+	};
+}
+async function initialiseRepository(repoPath, options = {}) {
+	await ensureDirectory(repoPath);
+	const roots = defaultRoots(options);
+	const manifestPath = path.join(repoPath, "sources.yaml");
+	const createdItems = [];
+	const preservedItems = [];
+	if (!await pathExists(manifestPath)) {
+		const sources = [await createDefaultSource("first-party", "First-party local skills", "first-party", roots.firstPartyRoot, ""), await createDefaultSource("system", "Mirrored system skills", "mirrored-system", roots.systemRoot, "system-")];
+		await saveManifest(createManifest(repoPath, {
+			remoteRepository: options.remoteRepository ?? path.basename(repoPath),
+			sources
+		}));
+		createdItems.push("sources.yaml");
+	} else preservedItems.push("sources.yaml");
+	await ensureDirectory(path.join(repoPath, "skills"));
+	await ensureDirectory(path.join(repoPath, "docs"));
+	await ensureDirectory(path.join(repoPath, ".github", "actions", "skillsbase-sync"));
+	await ensureDirectory(path.join(repoPath, ".github", "workflows"));
+	const writeStatuses = [];
+	for (const file of [{
+		relativePath: path.join("skills", "README.md"),
+		template: "skills/README.md",
+		variables: {}
+	}, {
+		relativePath: path.join("docs", "maintainer-workflow.md"),
+		template: "docs/maintainer-workflow.md",
+		variables: {}
+	}]) {
+		const content = await renderTemplate(file.template, file.variables);
+		const status = await writeManagedFile(path.join(repoPath, file.relativePath), content, { force: Boolean(options.force) });
+		writeStatuses.push(`${status.status}: ${file.relativePath}`);
+	}
+	const actionResult = await writeGithubActions(repoPath, {
+		kind: "all",
+		force: Boolean(options.force)
+	});
+	return {
+		command: "init",
+		title: "skillsbase init",
+		repository: repoPath,
+		exitCode: 0,
+		schema: "spec-driven",
+		items: [
+			...createdItems.map((item) => `created: ${item}`),
+			...preservedItems.map((item) => `preserved: ${item}`),
+			...writeStatuses,
+			...actionResult.items ?? []
+		],
+		nextSteps: ["skillsbase sync"]
+	};
+}
+//#endregion
+//#region src/commands/init.ts
+async function runInitCommand(context) {
+	const repoFlag = typeof context.flags.repo === "string" ? context.flags.repo : void 0;
+	return initialiseRepository(path.resolve(repoFlag ?? context.cwd), {
+		firstPartyRoot: typeof context.flags["first-party-root"] === "string" ? context.flags["first-party-root"] : void 0,
+		systemRoot: typeof context.flags["system-root"] === "string" ? context.flags["system-root"] : void 0,
+		remoteRepository: typeof context.flags["remote-repository"] === "string" ? context.flags["remote-repository"] : void 0,
+		force: context.flags.force === true
+	});
+}
+//#endregion
+//#region src/commands/sync.ts
+async function runSyncCommand(context) {
+	const repoFlag = typeof context.flags.repo === "string" ? context.flags.repo : void 0;
+	const repoPath = path.resolve(repoFlag ?? context.cwd);
+	return executeSync({
+		repoPath,
+		manifest: await loadManifest(repoPath),
+		check: context.flags.check === true,
+		allowMissingSources: context.flags["allow-missing-sources"] === true,
+		env: context.env
+	});
+}
+//#endregion
+//#region src/lib/parse-argv.ts
+var booleanFlags = new Set([
+	"help",
+	"version",
+	"check",
+	"allow-missing-sources",
+	"force"
+]);
+function parseArgv(argv) {
+	const result = {
+		command: null,
+		args: [],
+		flags: {},
+		help: false,
+		version: false
+	};
+	let index = 0;
+	while (index < argv.length) {
+		const token = argv[index];
+		if (result.command == null && !token.startsWith("-")) {
+			result.command = token;
+			index += 1;
+			continue;
+		}
+		if (token === "--help" || token === "-h") {
+			result.help = true;
+			index += 1;
+			continue;
+		}
+		if (token === "--version" || token === "-v") {
+			result.version = true;
+			index += 1;
+			continue;
+		}
+		if (token.startsWith("--")) {
+			const [flagName, inlineValue] = token.slice(2).split("=", 2);
+			if (booleanFlags.has(flagName)) {
+				result.flags[flagName] = inlineValue == null ? true : inlineValue !== "false";
+				index += 1;
+				continue;
+			}
+			const nextValue = inlineValue ?? argv[index + 1];
+			if (nextValue == null) throw new CliError(`Missing value for --${flagName}.`);
+			result.flags[flagName] = nextValue;
+			index += inlineValue == null ? 2 : 1;
+			continue;
+		}
+		if (token.startsWith("-")) throw new CliError(`Unsupported short option: ${token}`, { details: ["Use long-form flags for command options."] });
+		if (result.command != null) result.args.push(token);
+		index += 1;
+	}
+	return result;
+}
+//#endregion
+//#region src/cli.ts
+var commandMap = new Map([
+	["init", runInitCommand],
+	["sync", runSyncCommand],
+	["add", runAddCommand],
+	["github_action", runGithubActionCommand],
+	["github-action", runGithubActionCommand]
+]);
+function getErrorMessage(error) {
+	if (error instanceof Error) return error.message;
+	return String(error);
+}
+async function runCli(argv, environment = {}) {
+	const io = {
+		stdout: environment.stdout ?? process.stdout,
+		stderr: environment.stderr ?? process.stderr
+	};
+	const cwd = path.resolve(environment.cwd ?? process.cwd());
+	const env = {
+		...process.env,
+		...environment.env ?? {}
+	};
+	try {
+		const parsed = parseArgv(argv);
+		if (parsed.help || !parsed.command) {
+			printCommandUsage(io.stdout);
+			return 0;
+		}
+		if (parsed.version) {
+			io.stdout.write("skillsbase 0.1.0\n");
+			return 0;
+		}
+		const command = commandMap.get(parsed.command);
+		if (!command) throw new CliError(`Unknown command: ${parsed.command}`, {
+			exitCode: 1,
+			details: ["Use `skillsbase --help` to view supported commands."]
+		});
+		const result = await command({
+			cwd,
+			env,
+			io,
+			command: parsed.command,
+			args: parsed.args,
+			flags: parsed.flags,
+			rawArgv: argv
+		});
+		printCommandResult(result, io.stdout);
+		return result.exitCode ?? 0;
+	} catch (error) {
+		if (error instanceof CliError) {
+			printCommandResult({
+				command: "error",
+				title: error.message,
+				repository: cwd,
+				exitCode: error.exitCode ?? 1,
+				items: error.details ?? [],
+				nextSteps: error.nextSteps ?? []
+			}, io.stderr);
+			return error.exitCode ?? 1;
+		}
+		printCommandResult({
+			command: "error",
+			title: getErrorMessage(error),
+			repository: cwd,
+			exitCode: 1
+		}, io.stderr);
+		return 1;
+	}
+}
+//#endregion
+//#region src/cli-entry.ts
+var exitCode = await runCli(process.argv.slice(2));
+process.exitCode = exitCode;
+//#endregion

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@hagicode/skillsbase",
+  "version": "0.1.0-dev.20260406025440.0.0.local",
+  "description": "Managed skills repository CLI",
+  "homepage": "https://github.com/HagiCode-org/skillsbase#readme",
+  "bugs": {
+    "url": "https://github.com/HagiCode-org/skillsbase/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/HagiCode-org/skillsbase.git"
+  },
+  "type": "module",
+  "packageManager": "npm@10.9.2",
+  "bin": {
+    "skillsbase": "./bin/skillsbase.mjs"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "templates",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "vite build",
+    "clean": "rm -rf dist",
+    "cli": "node --import tsx ./src/cli-entry.ts",
+    "pack:check": "node ./scripts/verify-package.mjs",
+    "publish:prepare-dev-version": "node ./scripts/prepare-dev-version.mjs",
+    "publish:verify-release": "node ./scripts/verify-release-version.mjs",
+    "test": "node --import tsx --test ./tests/*.test.ts",
+    "smoke": "node --import tsx ./scripts/smoke.mjs"
+  },
+  "engines": {
+    "node": ">=22.12.0",
+    "npm": ">=10.9.2"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true,
+    "registry": "https://registry.npmjs.org/"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "tsx": "^4.20.6",
+    "typescript": "^5.9.3",
+    "vite": "^8.0.0"
+  }
+}

package/templates/actions/skillsbase-sync/action.yml

@@ -0,0 +1,36 @@
+# Managed by skillsbase CLI.
+
+name: skillsbase-sync
+description: Validate a managed skillsbase repository and run sync in check mode
+
+inputs:
+  node-version:
+    description: Node.js version used for validation
+    required: false
+    default: "{{NODE_VERSION}}"
+  run-tests:
+    description: Whether to run npm test before sync --check
+    required: false
+    default: "true"
+
+runs:
+  using: composite
+  steps:
+    - name: Setup Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: ${{ inputs.node-version }}
+        cache: npm
+
+    - name: Install dependencies
+      shell: bash
+      run: npm ci
+
+    - name: Run tests
+      if: ${{ inputs.run-tests == 'true' }}
+      shell: bash
+      run: npm test
+
+    - name: Run sync check
+      shell: bash
+      run: node ./bin/skillsbase.mjs sync --check

package/templates/docs/maintainer-workflow.md

@@ -0,0 +1,20 @@
+<!-- Managed by skillsbase CLI. -->
+
+# Maintainer Workflow
+
+结论是：维护流以 `init -> add -> sync -> github_action` 为主。
+
+## Lifecycle
+
+1. `skillsbase init`
+2. `skillsbase add <skill-name>`
+3. `skillsbase sync`
+4. `skillsbase github_action --kind all`
+
+## Notes
+
+- `sources.yaml` 是单一真相源。
+- `skills/` 仅保存受管输出。
+- `.skill-source.json` 记录来源与转换元数据。
+- `skillsbase sync --check` 只校验，不改仓库。
+- 缺少来源根目录时，可用 `skillsbase sync --allow-missing-sources` 跳过。

package/templates/skills/README.md

@@ -0,0 +1,9 @@
+<!-- Managed by skillsbase CLI. -->
+
+# Managed Skills
+
+此目录只存放受管 skill 输出。
+
+- 每个 skill 目录必须包含 `SKILL.md`
+- 每个受管目录必须包含 `.skill-source.json`
+- 不要手改受管文件；变更应回到 `sources.yaml` 与上游来源

package/templates/sources.yaml

@@ -0,0 +1,25 @@
+# Managed by skillsbase CLI.
+# This template documents the expected manifest shape. The CLI serializes the real file.
+version: 1
+skillsRoot: skills
+metadataFile: .skill-source.json
+managedBy: skillsbase
+remoteRepository: "{{REMOTE_REPOSITORY}}"
+staleCleanup: true
+skillsCliVersion: 1.4.8
+installAgent: codex
+sources:
+  - key: first-party
+    label: "First-party local skills"
+    kind: first-party
+    root: "{{FIRST_PARTY_ROOT}}"
+    targetPrefix: ""
+    include:
+      - "{{FIRST_PARTY_EXAMPLE}}"
+  - key: system
+    label: "Mirrored system skills"
+    kind: mirrored-system
+    root: "{{SYSTEM_ROOT}}"
+    targetPrefix: system-
+    include:
+      - "{{SYSTEM_EXAMPLE}}"

package/templates/workflows/skills-sync.yml

@@ -0,0 +1,39 @@
+# Managed by skillsbase CLI.
+
+name: Skills Sync
+
+on:
+  workflow_dispatch:
+  pull_request:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+concurrency:
+  group: skills-sync-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: {{NODE_VERSION}}
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run tests
+        run: npm test
+
+      - name: Validate managed repository state
+        run: node ./bin/skillsbase.mjs sync --check