@hagicode/skillsbase 0.1.2 → 0.1.3

package/README.md

@@ -48,6 +48,12 @@ Add one skill and sync immediately:
 skillsbase add documentation-writer --repo /path/to/target-repo
 ```
 
+Remove one skill and sync immediately:
+
+```bash
+skillsbase remove documentation-writer --repo /path/to/target-repo
+```
+
 Generate managed GitHub Actions assets:
 
 ```bash
@@ -62,6 +68,7 @@ skillsbase github_action --repo /path/to/target-repo --kind all
 | `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:
@@ -88,6 +95,8 @@ Global options:
   - first-party: `$HOME/.agents/skills`
   - system: `$HOME/.codex/skills/.system`
 - `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.
 

package/README.zh-CN.md

@@ -48,6 +48,12 @@ skillsbase sync --repo /path/to/target-repo
 skillsbase add documentation-writer --repo /path/to/target-repo
 ```
 
+删除单个技能并立即同步：
+
+```bash
+skillsbase remove documentation-writer --repo /path/to/target-repo
+```
+
 生成受管 GitHub Actions 资产：
 
 ```bash
@@ -62,6 +68,7 @@ skillsbase github_action --repo /path/to/target-repo --kind all
 | `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` |
 
 全局选项：
@@ -88,6 +95,8 @@ skillsbase github_action --repo /path/to/target-repo --kind all
   - 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 会直接失败并输出诊断，不会进入交互提问。
 

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"));
 }
@@ -183,6 +185,41 @@ 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,
@@ -346,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 {
@@ -383,6 +450,19 @@ 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;
@@ -403,6 +483,23 @@ 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);
@@ -414,22 +511,18 @@ async function installIntoCurrentRepository(repoPath, manifest, entry, options =
 		lockText: await readFileIfExists(lockPath),
 		installReference
 	};
-	try {
-		await execFile$1("npx", buildNpxArgs(manifest, "add", [
-			installReference,
-			"--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,
@@ -438,26 +531,14 @@ async function installIntoCurrentRepository(repoPath, manifest, entry, options =
 		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;
@@ -741,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 = [];
@@ -854,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;
@@ -926,6 +1037,7 @@ var commandMap = new Map([
 	["init", runInitCommand],
 	["sync", runSyncCommand],
 	["add", runAddCommand],
+	["remove", runRemoveCommand],
 	["github_action", runGithubActionCommand],
 	["github-action", runGithubActionCommand]
 ]);
@@ -993,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,6 +1,6 @@
 {
   "name": "@hagicode/skillsbase",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Managed skills repository CLI",
   "homepage": "https://github.com/HagiCode-org/skillsbase#readme",
   "bugs": {

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,10 @@ 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

package/templates/docs/maintainer-workflow.md

@@ -2,15 +2,26 @@
 
 # Maintainer Workflow
 
-The maintainer flow is `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` is the single source of truth.
@@ -18,3 +29,4 @@ The maintainer flow is `init -> add -> sync -> github_action`.
 - `.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/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,20 +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: Install skillsbase
-        run: npm install --global @hagicode/skillsbase
-
-      - name: Run tests
-        run: npm test
-
-      - name: Validate managed repository state
-        run: skillsbase sync --check --repo .
+          run-tests: "true"