@hagicode/skillsbase 0.1.0-dev.20260406025440.0.0.local → 0.1.0-dev.3.1.cbbc838

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HagiCode
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,78 +1,132 @@
-# skillsbase
+# @hagicode/skillsbase
 
-`skillsbase` 是一个独立 Node CLI，用于初始化和维护“别的 skills 仓库”。
-重点是：本仓库只放 CLI 代码与模板，不提交受管 `skills/` 内容。
-当前源码使用 `TypeScript + Vite 8`。
+[中文文档](./README.zh-CN.md)
 
-## Commands
+[![npm version](https://img.shields.io/npm/v/%40hagicode%2Fskillsbase?logo=npm&color=cb3837)](https://www.npmjs.com/package/@hagicode/skillsbase)
+[![npm downloads](https://img.shields.io/npm/dm/%40hagicode%2Fskillsbase?logo=npm&color=2d8cf0)](https://www.npmjs.com/package/@hagicode/skillsbase)
+[![license](https://img.shields.io/badge/license-MIT-ffd43b)](./LICENSE)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D22.12.0-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
+
+`skillsbase` is a standalone Node.js CLI for bootstrapping and maintaining managed skills repositories.
+It ships the CLI and templates only. The generated `skills/` content belongs in the target repository, not in this package repository.
+
+## Install
+
+Requirements:
+
+- Node.js `>= 22.12.0`
+- npm `>= 10.9.2`
+
+Install globally:
 
 ```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
+npm install --global @hagicode/skillsbase
 ```
 
-开发期常用：
+Then run:
 
 ```bash
-npm run build
-npm run cli -- --help
-npm test
-npm run smoke
-node ./bin/skillsbase.mjs <command> --repo /path/to/target-repo
+skillsbase --help
+```
+
+## Quick Start
+
+Initialize a managed repository:
+
+```bash
+skillsbase init --repo /path/to/target-repo
+```
+
+Sync managed skills from `sources.yaml`:
+
+```bash
+skillsbase sync --repo /path/to/target-repo
+```
+
+Add one skill and sync immediately:
+
+```bash
+skillsbase add documentation-writer --repo /path/to/target-repo
 ```
 
-打包产物仍为 `dist/cli.mjs`，`bin/skillsbase.mjs` 只负责发布态加载与开发态回退。
+Remove one skill and sync immediately:
 
-## npm Publish
+```bash
+skillsbase remove documentation-writer --repo /path/to/target-repo
+```
+
+Generate managed GitHub Actions assets:
+
+```bash
+skillsbase github_action --repo /path/to/target-repo --kind all
+```
 
-- 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`
+## Commands
+
+| Command | Purpose | Example |
+| --- | --- | --- |
+| `init` | Create the managed repository baseline. | `skillsbase init --repo ./my-skills-repo` |
+| `sync` | Reconcile managed skills from `sources.yaml`. | `skillsbase sync --repo ./my-skills-repo` |
+| `sync --check` | Validate drift without writing files. | `skillsbase sync --check --repo ./my-skills-repo` |
+| `add <skill-name>` | Add a skill to a source block, then run sync. | `skillsbase add documentation-writer --repo ./my-skills-repo` |
+| `remove <skill-name>` | Remove a skill from a source block, then run sync. | `skillsbase remove documentation-writer --repo ./my-skills-repo` |
+| `github_action` | Generate managed GitHub Actions workflow or action files. | `skillsbase github_action --repo ./my-skills-repo --kind workflow` |
+
+Global options:
 
-发布依赖 npm Trusted Publishing；仓库侧需要在 npm 绑定此 GitHub repository。
+- `--repo <path>`: target repository path, defaults to the current directory
+- `--help`, `-h`: show help
+- `--version`, `-v`: show version
 
-## Managed Repo Contract
+## Managed Repository 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。
+`skillsbase` manages files in the target repository, including:
 
-以上文件属于 **目标 skills 仓库**，不属于本 CLI 仓库本身。
+- `sources.yaml`: the single source of truth for source roots, naming rules, include lists, and defaults
+- `skills/<name>/SKILL.md`: managed skill output converted from installed source content
+- `skills/<name>/.skill-source.json`: source, conversion, target-path, and install metadata
+- `docs/maintainer-workflow.md`: maintainer guidance generated from the bundled templates
+- `.github/workflows/skills-sync.yml`: reusable workflow for validation and sync checks
+- `.github/actions/skillsbase-sync/action.yml`: reusable composite action
 
 ## Non-Interactive Defaults
 
-- 目标仓库默认为当前工作目录。
-- `init` 默认来源根目录：
+- The target repository defaults to the current working directory.
+- `init` defaults the source roots to:
   - first-party: `$HOME/.agents/skills`
   - system: `$HOME/.codex/skills/.system`
-- `add` 默认写入第一个已声明 source block。
-- `github_action` 默认 `--kind workflow`。
-- 若上下文不足以安全写入，命令直接失败并给出诊断；不会进入交互提问。
+- `add` writes to the first declared source block unless `--source <key>` is provided.
+- `remove` deletes from the only matching source block automatically; if multiple source blocks include the same skill, pass `--source <key>`.
+- `add`, `remove`, and `sync` accept `--allow-missing-sources` to keep path-resolution behavior consistent in CI or repo-external execution.
+- `github_action` defaults to `--kind workflow`.
+- When the CLI does not have enough context to write safely, it fails with diagnostics instead of prompting interactively.
 
-## Usage Notes
+## Development
 
-- `sync` 会执行“安装到当前仓库 -> 转换 -> 卸载临时产物 -> 对账写盘”闭环。
-- `sync --check` 不修改最终仓库状态；若发现漂移则返回非零退出码。
-- `sync --allow-missing-sources` 可在来源根目录暂缺时跳过该来源。
-- `github_action` 仅覆盖带 `Managed by skillsbase CLI` 标记的文件；冲突文件需显式 `--force`。
+Common commands for working on this package:
 
-## Development
+```bash
+npm run build
+npm run cli -- --help
+npm test
+npm run smoke
+npm run pack:check
+```
+
+The published entry point is `bin/skillsbase.mjs`. In development, `npm run cli -- <args>` runs the TypeScript entry directly.
+
+## Publishing Notes
+
+The GitHub Actions workflow supports two npm authentication modes:
+
+- Preferred: npm trusted publishing via GitHub Actions OIDC
+- Fallback: `NPM_TOKEN` repository secret mapped to `NODE_AUTH_TOKEN`
+
+Before relying on trusted publishing, make sure the npm package settings for `@hagicode/skillsbase` trust the `HagiCode-org/skillsbase` repository.
+Use workflow filename `npm-publish.yml` in npm trusted publisher settings, not the full `.github/workflows/...` path.
+If the package has not been published before, that is still acceptable as long as the `hagicode` scope already exists and the publishing identity can create `@hagicode/skillsbase`.
+The npm docs currently require Node.js `>= 22.14.0` and npm `>= 11.5.1` for trusted publishing.
+
+## License
 
-- `npm test`
-  跑 CLI 单测。
-- `npm run smoke`
-  在临时目录创建一个示例 managed repo，验证 `init -> sync -> sync --check -> github_action`。
+MIT. See [LICENSE](./LICENSE).

package/README.zh-CN.md

@@ -0,0 +1,127 @@
+# @hagicode/skillsbase
+
+[English README](./README.md)
+
+[![npm version](https://img.shields.io/npm/v/%40hagicode%2Fskillsbase?logo=npm&color=cb3837)](https://www.npmjs.com/package/@hagicode/skillsbase)
+[![npm downloads](https://img.shields.io/npm/dm/%40hagicode%2Fskillsbase?logo=npm&color=2d8cf0)](https://www.npmjs.com/package/@hagicode/skillsbase)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D22.12.0-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
+
+`skillsbase` 是一个独立的 Node.js CLI，用于初始化并维护受管 skills 仓库。
+本仓库只提供 CLI 与模板，不提交目标仓库中的 `skills/` 产物。
+
+## 安装
+
+要求：
+
+- Node.js `>= 22.12.0`
+- npm `>= 10.9.2`
+
+全局安装：
+
+```bash
+npm install --global @hagicode/skillsbase
+```
+
+安装后可直接执行：
+
+```bash
+skillsbase --help
+```
+
+## 快速开始
+
+初始化受管仓库：
+
+```bash
+skillsbase init --repo /path/to/target-repo
+```
+
+按 `sources.yaml` 同步技能：
+
+```bash
+skillsbase sync --repo /path/to/target-repo
+```
+
+添加单个技能并立即同步：
+
+```bash
+skillsbase add documentation-writer --repo /path/to/target-repo
+```
+
+删除单个技能并立即同步：
+
+```bash
+skillsbase remove documentation-writer --repo /path/to/target-repo
+```
+
+生成受管 GitHub Actions 资产：
+
+```bash
+skillsbase github_action --repo /path/to/target-repo --kind all
+```
+
+## 命令
+
+| 命令 | 用途 | 示例 |
+| --- | --- | --- |
+| `init` | 创建受管仓库基础结构 | `skillsbase init --repo ./my-skills-repo` |
+| `sync` | 按 `sources.yaml` 对账并同步技能 | `skillsbase sync --repo ./my-skills-repo` |
+| `sync --check` | 只校验漂移，不写文件 | `skillsbase sync --check --repo ./my-skills-repo` |
+| `add <skill-name>` | 将技能写入 source block 后执行同步 | `skillsbase add documentation-writer --repo ./my-skills-repo` |
+| `remove <skill-name>` | 从 source block 删除技能后执行同步 | `skillsbase remove documentation-writer --repo ./my-skills-repo` |
+| `github_action` | 生成受管 GitHub Actions 工作流或 action 文件 | `skillsbase github_action --repo ./my-skills-repo --kind workflow` |
+
+全局选项：
+
+- `--repo <path>`：目标仓库路径，默认当前目录
+- `--help`、`-h`：显示帮助
+- `--version`、`-v`：显示版本
+
+## 受管仓库约定
+
+`skillsbase` 会在目标仓库中管理以下文件：
+
+- `sources.yaml`：来源根目录、命名规则、包含列表与默认值的单一真相源
+- `skills/<name>/SKILL.md`：由安装源内容转换得到的受管技能输出
+- `skills/<name>/.skill-source.json`：来源、转换、目标路径与安装元数据
+- `docs/maintainer-workflow.md`：由模板生成的维护说明
+- `.github/workflows/skills-sync.yml`：用于校验与同步检查的工作流
+- `.github/actions/skillsbase-sync/action.yml`：可复用 composite action
+
+## 非交互默认行为
+
+- 目标仓库默认是当前工作目录。
+- `init` 默认来源根目录为：
+  - first-party：`$HOME/.agents/skills`
+  - system：`$HOME/.codex/skills/.system`
+- `add` 默认写入第一个已声明的 source block；如需指定，传 `--source <key>`。
+- `remove` 若仅命中一个 source block，会直接删除；若同名技能存在于多个 source block，必须显式传 `--source <key>`。
+- `add`、`remove`、`sync` 均接受 `--allow-missing-sources`，以便在 CI 或仓库外 cwd 下保持一致的路径解析与失败语义。
+- `github_action` 默认使用 `--kind workflow`。
+- 若上下文不足以安全写入，CLI 会直接失败并输出诊断，不会进入交互提问。
+
+## 开发
+
+常用命令：
+
+```bash
+npm run build
+npm run cli -- --help
+npm test
+npm run smoke
+npm run pack:check
+```
+
+发布入口为 `bin/skillsbase.mjs`。开发期可用 `npm run cli -- <args>` 直接运行 TypeScript 入口。
+
+## 发布说明
+
+GitHub Actions 发布流支持两种 npm 认证模式：
+
+- 推荐：GitHub Actions OIDC 的 npm trusted publishing
+- 兜底：仓库 `NPM_TOKEN` secret，经 `NODE_AUTH_TOKEN` 注入
+
+若使用 trusted publishing，需先在 npm 的 `@hagicode/skillsbase` 包设置中，将 `HagiCode-org/skillsbase` 配置为 trusted publisher。
+在 npm trusted publisher 设置里填写的 workflow filename 应为 `npm-publish.yml`，不要填完整的 `.github/workflows/...` 路径。
+如果这个包还没有首发，只要 npm 上已经存在 `hagicode` scope，且当前发布身份有权创建 `@hagicode/skillsbase`，也仍然可以正常发布。
+npm 官方当前要求 Node.js `>= 22.14.0` 且 npm `>= 11.5.1`。

package/dist/cli.mjs

@@ -25,12 +25,14 @@ function printCommandUsage(stdout) {
 		"  init            Create the managed repository baseline",
 		"  sync            Reconcile managed skills from sources.yaml",
 		"  add             Add a skill to a source block and sync",
+		"  remove          Remove a skill from 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",
+		"  --repo <path>               Target repository path (default: current directory)",
+		"  --allow-missing-sources     Skip missing local source roots during sync/add/remove",
+		"  --help, -h                  Show help",
+		"  --version, -v               Show version",
 		""
 	].join("\n"));
 }
@@ -168,6 +170,56 @@ function validateSource(source) {
 		include: [...source.include]
 	};
 }
+function isRemoteRepositorySource(source) {
+	return source.kind === "github-repository";
+}
+function buildSourcePath(source, originalName) {
+	if (isRemoteRepositorySource(source)) return `${source.root}@${originalName}`;
+	return path.join(source.root, originalName);
+}
+function resolveSourceRoot(repoPath, source) {
+	if (isRemoteRepositorySource(source) || path.isAbsolute(source.root)) return source.root;
+	return path.resolve(repoPath, source.root);
+}
+function resolveSourcePath(repoPath, source, originalName) {
+	if (isRemoteRepositorySource(source)) return buildSourcePath(source, originalName);
+	return path.join(resolveSourceRoot(repoPath, source), originalName);
+}
+function cloneSource(source) {
+	return {
+		...source,
+		include: [...source.include ?? []]
+	};
+}
+function cloneManifestWithSources(manifest, sources) {
+	return {
+		...manifest,
+		sources: sources.map(cloneSource)
+	};
+}
+function sortInclude(include) {
+	return [...include].sort((left, right) => left.localeCompare(right));
+}
+function assertManifestHasSources(manifest) {
+	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`."] });
+}
+function getSourceKeys(manifest) {
+	return manifest.sources.map((source) => source.key).join(", ");
+}
+function findSourceByKey(manifest, sourceKey) {
+	const source = manifest.sources.find((candidate) => candidate.key === sourceKey);
+	if (!source) throw new CliError(`Unknown source key: ${sourceKey}`, { details: [`Declared sources: ${getSourceKeys(manifest)}`] });
+	return source;
+}
+function findSourcesBySkill(manifest, skillName) {
+	return manifest.sources.filter((source) => source.include.includes(skillName));
+}
+function buildMissingSkillError(skillName, options = {}) {
+	const matchingKeys = options.matchingKeys ?? [];
+	const details = options.sourceKey ? [`skill: ${skillName}`, `source: ${options.sourceKey}`] : [`skill: ${skillName}`];
+	if (matchingKeys.length > 0) details.push(`matching sources: ${matchingKeys.join(", ")}`);
+	return new CliError(options.sourceKey == null ? `Skill "${skillName}" is not declared in sources.yaml.` : `Skill "${skillName}" is not declared in source "${options.sourceKey}".`, { details });
+}
 function createManifest(repoPath, options = {}) {
 	return {
 		version: 1,
@@ -258,7 +310,7 @@ async function loadManifest(repoPath) {
 		const sourceStartMatch = /^  - key:\s*(.+)$/.exec(line);
 		if (sourceStartMatch) {
 			currentSource = {
-				key: parseScalar(sourceStartMatch[1]),
+				key: String(parseScalar(sourceStartMatch[1])),
 				include: []
 			};
 			manifest.sources.push(currentSource);
@@ -300,19 +352,25 @@ async function saveManifest(manifest) {
 }
 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))
-		});
+	for (const source of manifest.sources) {
+		const resolvedSourceRoot = resolveSourceRoot(repoPath, source);
+		for (const originalName of source.include ?? []) {
+			const targetName = `${source.targetPrefix ?? ""}${originalName}`;
+			entries.push({
+				sourceKey: source.key,
+				sourceLabel: source.label,
+				sourceKind: source.kind,
+				remoteSource: isRemoteRepositorySource(source),
+				sourceRoot: source.root,
+				sourcePath: buildSourcePath(source, originalName),
+				resolvedSourceRoot,
+				resolvedSourcePath: resolveSourcePath(repoPath, source, 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) {
@@ -325,19 +383,49 @@ function buildManifestEntries(manifest, repoPath = manifest.repoPath) {
 	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 } : {
+	assertManifestHasSources(manifest);
+	const selectedSource = options.sourceKey == null ? manifest.sources[0] : findSourceByKey(manifest, options.sourceKey);
+	return cloneManifestWithSources(manifest, manifest.sources.map((source) => {
+		if (source.key !== selectedSource.key) return source;
+		return {
 			...source,
-			include: [...source.include]
-		})
-	};
+			include: sortInclude(new Set(source.include ?? []).add(skillName))
+		};
+	}));
+}
+function removeSkillFromManifest(manifest, skillName, options = {}) {
+	assertManifestHasSources(manifest);
+	const selectedSource = options.sourceKey == null ? null : findSourceByKey(manifest, options.sourceKey);
+	if (selectedSource != null) {
+		if (!selectedSource.include.includes(skillName)) {
+			const matchingKeys = findSourcesBySkill(manifest, skillName).map((source) => source.key);
+			throw buildMissingSkillError(skillName, {
+				sourceKey: selectedSource.key,
+				matchingKeys
+			});
+		}
+		return cloneManifestWithSources(manifest, manifest.sources.map((source) => {
+			if (source.key !== selectedSource.key) return source;
+			return {
+				...source,
+				include: sortInclude(source.include.filter((candidate) => candidate !== skillName))
+			};
+		}));
+	}
+	const matchingSources = findSourcesBySkill(manifest, skillName);
+	if (matchingSources.length === 0) throw buildMissingSkillError(skillName);
+	if (matchingSources.length > 1) {
+		const matchingKeys = matchingSources.map((source) => source.key).sort((left, right) => left.localeCompare(right));
+		throw new CliError(`Skill "${skillName}" is declared in multiple sources.`, { details: [`matching sources: ${matchingKeys.join(", ")}`, `Use \`skillsbase remove ${skillName} --source <key>\` to disambiguate.`] });
+	}
+	const [uniqueSource] = matchingSources;
+	return cloneManifestWithSources(manifest, manifest.sources.map((source) => {
+		if (source.key !== uniqueSource.key) return source;
+		return {
+			...source,
+			include: sortInclude(source.include.filter((candidate) => candidate !== skillName))
+		};
+	}));
 }
 function buildMetadata(manifest, entry, installRecord) {
 	return {
@@ -362,6 +450,24 @@ function buildMetadata(manifest, entry, installRecord) {
 //#endregion
 //#region src/lib/installer.ts
 var execFile$1 = promisify(execFile);
+var INSTALL_TIMEOUT_MS = 18e4;
+var REMOTE_INSTALL_RETRIES = 3;
+var NPM_ENV_KEYS_TO_UNSET = [
+	"INIT_CWD",
+	"npm_command",
+	"npm_config_local_prefix",
+	"npm_config_prefix",
+	"npm_execpath",
+	"npm_lifecycle_event",
+	"npm_lifecycle_script",
+	"npm_package_json",
+	"npm_prefix"
+];
+function toInstallReference(entry) {
+	if (entry.remoteSource) return entry.sourcePath;
+	if (path.isAbsolute(entry.sourcePath) || entry.sourcePath.startsWith(`.${path.sep}`) || entry.sourcePath === ".") return entry.sourcePath;
+	return `.${path.sep}${entry.sourcePath}`;
+}
 function buildNpxArgs(manifest, subcommand, extraArgs) {
 	return [
 		"--yes",
@@ -377,7 +483,25 @@ function renderExecFailure(error) {
 	}
 	return String(error);
 }
+async function execSkillsAdd(repoPath, manifest, installReference, options) {
+	const childEnv = { ...options.env ?? process.env };
+	for (const key of NPM_ENV_KEYS_TO_UNSET) delete childEnv[key];
+	childEnv.INIT_CWD = repoPath;
+	await execFile$1("npx", buildNpxArgs(manifest, "add", [
+		installReference,
+		"--agent",
+		manifest.installAgent,
+		"--copy",
+		"-y"
+	]), {
+		cwd: repoPath,
+		env: childEnv,
+		maxBuffer: 16 * 1024 * 1024,
+		timeout: INSTALL_TIMEOUT_MS
+	});
+}
 async function installIntoCurrentRepository(repoPath, manifest, entry, options = {}) {
+	const installReference = toInstallReference(entry);
 	const installPath = path.join(repoPath, ".agents", "skills", entry.originalName);
 	const lockPath = path.join(repoPath, "skills-lock.json");
 	const snapshot = {
@@ -385,52 +509,36 @@ async function installIntoCurrentRepository(repoPath, manifest, entry, options =
 		lockPath,
 		installTree: await snapshotTree(installPath),
 		lockText: await readFileIfExists(lockPath),
-		installReference: entry.sourcePath
+		installReference
 	};
-	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
-		});
+	const attempts = entry.remoteSource ? REMOTE_INSTALL_RETRIES : 1;
+	const failures = [];
+	for (let attempt = 1; attempt <= attempts; attempt += 1) try {
+		await execSkillsAdd(repoPath, manifest, installReference, options);
+		failures.length = 0;
+		break;
 	} catch (error) {
-		throw new CliError(`skills install failed for ${entry.originalName}.`, { details: [renderExecFailure(error)] });
+		failures.push(`attempt ${attempt}/${attempts}: ${renderExecFailure(error)}`);
+		await restoreSnapshot(snapshot);
+		if (attempt === attempts) break;
 	}
+	if (failures.length > 0) throw new CliError(`skills install failed for ${entry.originalName}.`, { details: failures });
 	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,
+		installReference,
 		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;
-	}
+async function cleanupInstalledSkill(repoPath, _manifest, entry, installState, _options = {}) {
 	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)) });
+		throw new CliError(`Cleanup failed for ${entry.originalName}.`, { details: [restoreMessage] });
 	}
-	if (removeError) throw new CliError(`skills uninstall failed for ${entry.originalName}.`, { details: [renderExecFailure(removeError)] });
 }
 async function snapshotTree(rootPath) {
 	if (!await pathExists(rootPath)) return null;
@@ -524,14 +632,15 @@ async function convertInstalledSkill(_manifest, entry, installState) {
 //#endregion
 //#region src/lib/sync-engine.ts
 async function assertSourceState(entry, allowMissingSources) {
-	if (!await pathExists(entry.sourceRoot)) {
+	if (entry.remoteSource) return { skip: false };
+	if (!await pathExists(entry.resolvedSourceRoot)) {
 		if (allowMissingSources) return {
 			skip: true,
-			reason: `missing source root: ${entry.sourceRoot}`
+			reason: `missing source root: ${entry.resolvedSourceRoot}`
 		};
-		throw new CliError(`Managed source root does not exist: ${entry.sourceRoot}`, { details: ["Use `skillsbase sync --allow-missing-sources` to skip missing roots."] });
+		throw new CliError(`Managed source root does not exist: ${entry.resolvedSourceRoot}`, { 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}`] });
+	if (!await pathExists(entry.resolvedSourcePath)) throw new CliError(`Managed skill is missing from source root: ${entry.resolvedSourcePath}`, { details: [`source: ${entry.sourceKey}`, `skill: ${entry.originalName}`] });
 	return { skip: false };
 }
 async function assertManagedTargetWritable(manifest, entry) {
@@ -713,10 +822,16 @@ async function writeGithubActions(repoPath, options = {}) {
 	if (kind === "workflow" || kind === "all") targets.push({
 		relativePath: path.join(".github", "workflows", "skills-sync.yml"),
 		template: path.join("workflows", "skills-sync.yml")
+	}, {
+		relativePath: path.join(".github", "workflows", "skills-manage.yml"),
+		template: path.join("workflows", "skills-manage.yml")
 	});
-	if (kind === "action" || kind === "all") targets.push({
+	if (kind === "workflow" || kind === "action" || kind === "all") targets.push({
 		relativePath: path.join(".github", "actions", "skillsbase-sync", "action.yml"),
 		template: path.join("actions", "skillsbase-sync", "action.yml")
+	}, {
+		relativePath: path.join(".github", "actions", "skillsbase-manage", "action.yml"),
+		template: path.join("actions", "skillsbase-manage", "action.yml")
 	});
 	if (targets.length === 0) throw new CliError(`Unsupported github_action kind: ${kind}`, { details: ["Supported values: workflow, action, all."] });
 	const items = [];
@@ -826,6 +941,30 @@ async function runInitCommand(context) {
 	});
 }
 //#endregion
+//#region src/commands/remove.ts
+async function runRemoveCommand(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 remove` requires a skill name.", { details: ["Usage: `skillsbase remove <skill-name> [--source <key>]`."] });
+	const nextManifest = removeSkillFromManifest(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,
+		command: "remove",
+		title: `skillsbase remove ${skillName}`,
+		items: [`manifest updated: ${path.relative(repoPath, nextManifest.manifestPath) || "sources.yaml"}`, ...result.items]
+	};
+}
+//#endregion
 //#region src/commands/sync.ts
 async function runSyncCommand(context) {
 	const repoFlag = typeof context.flags.repo === "string" ? context.flags.repo : void 0;
@@ -898,6 +1037,7 @@ var commandMap = new Map([
 	["init", runInitCommand],
 	["sync", runSyncCommand],
 	["add", runAddCommand],
+	["remove", runRemoveCommand],
 	["github_action", runGithubActionCommand],
 	["github-action", runGithubActionCommand]
 ]);
@@ -965,5 +1105,5 @@ async function runCli(argv, environment = {}) {
 //#endregion
 //#region src/cli-entry.ts
 var exitCode = await runCli(process.argv.slice(2));
-process.exitCode = exitCode;
+process.exit(exitCode);
 //#endregion

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@hagicode/skillsbase",
-  "version": "0.1.0-dev.20260406025440.0.0.local",
+  "version": "0.1.0-dev.3.1.cbbc838",
   "description": "Managed skills repository CLI",
+  "license": "MIT",
   "homepage": "https://github.com/HagiCode-org/skillsbase#readme",
   "bugs": {
     "url": "https://github.com/HagiCode-org/skillsbase/issues"
@@ -19,17 +20,20 @@
     "bin",
     "dist",
     "templates",
-    "README.md"
+    "README.md",
+    "README.zh-CN.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:resolve-dev-version": "node ./scripts/resolve-dev-version.mjs",
+    "publish:verify-readiness": "node ./scripts/verify-publish-readiness.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"
+    "smoke": "node --import tsx ./scripts/smoke.mjs",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
   },
   "engines": {
     "node": ">=22.12.0",

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

@@ -0,0 +1,96 @@
+# Managed by skillsbase CLI.
+
+name: skillsbase-manage
+description: Run a managed add, remove, or sync operation for a skillsbase repository
+
+inputs:
+  node-version:
+    description: Node.js version used for maintenance
+    required: false
+    default: "{{NODE_VERSION}}"
+  operation:
+    description: Maintenance operation to run (`add`, `remove`, or `sync`)
+    required: true
+  skill-name:
+    description: Skill name for `add` or `remove`
+    required: false
+    default: ""
+  source:
+    description: Optional source key for `add` or `remove`
+    required: false
+    default: ""
+  allow-missing-sources:
+    description: Skip missing local roots during the operation
+    required: false
+    default: "false"
+  run-tests:
+    description: Whether to run npm test after the maintenance command
+    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: Upgrade npm
+      shell: bash
+      run: npm install --global npm@10.9.2
+
+    - name: Install skillsbase
+      shell: bash
+      run: npm install --global @hagicode/skillsbase
+
+    - name: Run maintenance command
+      shell: bash
+      env:
+        OPERATION: ${{ inputs.operation }}
+        SKILL_NAME: ${{ inputs.skill-name }}
+        SOURCE: ${{ inputs.source }}
+        ALLOW_MISSING_SOURCES: ${{ inputs.allow-missing-sources }}
+      run: |
+        set -euo pipefail
+
+        base_args=(--repo .)
+        if [[ "${ALLOW_MISSING_SOURCES}" == "true" ]]; then
+          base_args+=(--allow-missing-sources)
+        fi
+
+        case "${OPERATION}" in
+          add|remove)
+            if [[ -z "${SKILL_NAME}" ]]; then
+              echo "::error::skill-name is required when operation=${OPERATION}."
+              exit 1
+            fi
+
+            command=(skillsbase "${OPERATION}" "${SKILL_NAME}" "${base_args[@]}")
+            if [[ -n "${SOURCE}" ]]; then
+              command+=(--source "${SOURCE}")
+            fi
+            ;;
+          sync)
+            command=(skillsbase sync "${base_args[@]}")
+            ;;
+          *)
+            echo "::error::Unsupported operation: ${OPERATION}."
+            exit 1
+            ;;
+        esac
+
+        printf 'Running:'
+        printf ' %q' "${command[@]}"
+        printf '\n'
+        "${command[@]}"
+
+    - name: Run tests
+      if: ${{ inputs.run-tests == 'true' }}
+      shell: bash
+      run: npm test

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

@@ -26,6 +26,14 @@ runs:
       shell: bash
       run: npm ci
 
+    - name: Upgrade npm
+      shell: bash
+      run: npm install --global npm@10.9.2
+
+    - name: Install skillsbase
+      shell: bash
+      run: npm install --global @hagicode/skillsbase
+
     - name: Run tests
       if: ${{ inputs.run-tests == 'true' }}
       shell: bash
@@ -33,4 +41,4 @@ runs:
 
     - name: Run sync check
       shell: bash
-      run: node ./bin/skillsbase.mjs sync --check
+      run: skillsbase sync --check --repo .

package/templates/docs/maintainer-workflow.md

@@ -2,19 +2,31 @@
 
 # Maintainer Workflow
 
-结论是：维护流以 `init -> add -> sync -> github_action` 为主。
+The maintainer flow is `init -> add/remove -> sync -> github_action`.
 
 ## Lifecycle
 
 1. `skillsbase init`
-2. `skillsbase add <skill-name>`
+2. `skillsbase add <skill-name>` or `skillsbase remove <skill-name>`
 3. `skillsbase sync`
 4. `skillsbase github_action --kind all`
 
+## GitHub Maintenance Path
+
+Use `.github/workflows/skills-manage.yml` only for explicit non-interactive maintenance from GitHub UI.
+
+- `operation` chooses `add`, `remove`, or `sync`
+- `skill-name` is required for `add` and `remove`
+- `source` is optional and maps to `--source`
+- `allow-missing-sources` maps to `--allow-missing-sources`
+- `run-tests` controls the post-operation `npm test`
+- The workflow does not commit, push, or open pull requests
+
 ## Notes
 
-- `sources.yaml` 是单一真相源。
-- `skills/` 仅保存受管输出。
-- `.skill-source.json` 记录来源与转换元数据。
-- `skillsbase sync --check` 只校验，不改仓库。
-- 缺少来源根目录时，可用 `skillsbase sync --allow-missing-sources` 跳过。
+- `sources.yaml` is the single source of truth.
+- `skills/` stores managed output only.
+- `.skill-source.json` records source and conversion metadata.
+- `skillsbase sync --check` validates drift without writing files.
+- If a source root is unavailable, use `skillsbase sync --allow-missing-sources` to skip it.
+- Local CLI commands remain the primary maintainer path.

package/templates/skills/README.md

@@ -2,8 +2,8 @@
 
 # Managed Skills
 
-此目录只存放受管 skill 输出。
+This directory contains managed skill output only.
 
-- 每个 skill 目录必须包含 `SKILL.md`
-- 每个受管目录必须包含 `.skill-source.json`
-- 不要手改受管文件；变更应回到 `sources.yaml` 与上游来源
+- Every skill directory must include `SKILL.md`
+- Every managed directory must include `.skill-source.json`
+- Do not edit managed files by hand; make changes in `sources.yaml` and the upstream source instead

package/templates/workflows/skills-manage.yml

@@ -0,0 +1,54 @@
+# Managed by skillsbase CLI.
+
+name: Skills Manage
+
+on:
+  workflow_dispatch:
+    inputs:
+      operation:
+        description: Operation to run (`add`, `remove`, or `sync`)
+        required: true
+        type: choice
+        default: sync
+        options:
+          - add
+          - remove
+          - sync
+      skill-name:
+        description: Skill name for `add` or `remove`
+        required: false
+        type: string
+      source:
+        description: Optional source key for `add` or `remove`
+        required: false
+        type: string
+      allow-missing-sources:
+        description: Skip missing local roots during the operation
+        required: false
+        type: boolean
+        default: false
+      run-tests:
+        description: Run `npm test` after the maintenance command
+        required: false
+        type: boolean
+        default: true
+
+permissions:
+  contents: read
+
+jobs:
+  manage:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Run skillsbase maintenance
+        uses: ./.github/actions/skillsbase-manage
+        with:
+          node-version: {{NODE_VERSION}}
+          operation: ${{ inputs.operation }}
+          skill-name: ${{ inputs.skill-name }}
+          source: ${{ inputs.source }}
+          allow-missing-sources: ${{ inputs.allow-missing-sources }}
+          run-tests: ${{ inputs.run-tests }}

package/templates/workflows/skills-sync.yml

@@ -23,17 +23,8 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v4
 
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
+      - name: Run skillsbase validation
+        uses: ./.github/actions/skillsbase-sync
         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
+          run-tests: "true"