feat(ci): add GitHub Actions workflow for manual repository maintenance

Add skills-manage workflow and action template for non-interactive maintenance operations from GitHub UI. The new workflow supports add, remove, and sync operations with configurable parameters.

- Add skills-manage.yml workflow template with workflow_dispatch inputs for operation, skill-name, source, allow-missing-sources, and run-tests
- Add skillsbase-manage composite action template with Node setup, dependency installation, and CLI command execution
- Refactor skills-sync.yml to use the new skillsbase-sync composite action for consistency
- Add GithubActionTemplateTarget interface to templates.ts for type safety
- Update writeGithubActions function to generate both sync and manage workflow/action pairs
- Update maintainer-workflow.md documentation to describe the new GitHub Maintenance Path
- Add test assertions for new manage workflow and action files
- Add test for kind-specific generation to verify workflow and action pairing

Co-Authored-By: Hagicode <noreply@hagicode.com>
Signed-off-by: newbe36524 <newbe36524@qq.com>

Author: newbe36524

src/lib/templates.ts

@@ -26,6 +26,11 @@ interface WriteGithubActionsOptions extends WriteManagedFileOptions {
   kind?: GithubActionKind;
 }
 
+interface GithubActionTemplateTarget {
+  relativePath: string;
+  template: string;
+}
+
 async function resolveTemplateRoot(): Promise<string> {
   for (const candidate of templateRootCandidates) {
     if (await pathExists(candidate)) {
@@ -98,19 +103,31 @@ export async function writeGithubActions(
     NODE_VERSION: DEFAULT_NODE_VERSION,
   };
 
-  const targets: Array<{ relativePath: string; template: string }> = [];
+  const targets: GithubActionTemplateTarget[] = [];
   if (kind === "workflow" || kind === "all") {
-    targets.push({
-      relativePath: path.join(".github", "workflows", "skills-sync.yml"),
-      template: path.join("workflows", "skills-sync.yml"),
-    });
+    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({
-      relativePath: path.join(".github", "actions", "skillsbase-sync", "action.yml"),
-      template: path.join("actions", "skillsbase-sync", "action.yml"),
-    });
+  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) {

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

templates/docs/maintainer-workflow.md

@@ -2,19 +2,31 @@
 
 # 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.
 - `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.

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 }}

templates/workflows/skills-sync.yml

@@ -23,23 +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: Upgrade npm
-        run: npm install --global npm@10.9.2
-
-      - 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"

tests/skillsbase.test.ts

@@ -201,7 +201,9 @@ test("init creates the managed repository baseline", async () => {
   await fs.access(path.join(repoPath, "skills", "README.md"));
   await fs.access(path.join(repoPath, "docs", "maintainer-workflow.md"));
   await fs.access(path.join(repoPath, ".github", "workflows", "skills-sync.yml"));
+  await fs.access(path.join(repoPath, ".github", "workflows", "skills-manage.yml"));
   await fs.access(path.join(repoPath, ".github", "actions", "skillsbase-sync", "action.yml"));
+  await fs.access(path.join(repoPath, ".github", "actions", "skillsbase-manage", "action.yml"));
   assert.match(await read("sources.yaml", repoPath), /remoteRepository: example\/skillsbase/);
 });
 
@@ -500,15 +502,68 @@ test("github_action writes managed workflow and action assets", async () => {
   });
 
   assert.equal(result.exitCode, 0);
-  assert.match(await read(".github/workflows/skills-sync.yml", repoPath), /Managed by skillsbase CLI/);
+  const [syncWorkflow, manageWorkflow, syncAction, manageAction] = await Promise.all([
+    read(".github/workflows/skills-sync.yml", repoPath),
+    read(".github/workflows/skills-manage.yml", repoPath),
+    read(".github/actions/skillsbase-sync/action.yml", repoPath),
+    read(".github/actions/skillsbase-manage/action.yml", repoPath),
+  ]);
+
+  assert.match(syncWorkflow, /Managed by skillsbase CLI/);
+  assert.match(syncWorkflow, /uses: \.\/\.github\/actions\/skillsbase-sync/);
+  assert.match(syncWorkflow, /run-tests: "true"/);
+
+  assert.match(manageWorkflow, /workflow_dispatch:/);
+  assert.match(manageWorkflow, /operation:/);
+  assert.match(manageWorkflow, /skill-name:/);
+  assert.match(manageWorkflow, /allow-missing-sources:/);
+  assert.match(manageWorkflow, /uses: \.\/\.github\/actions\/skillsbase-manage/);
+
   assert.match(
-    await read(".github/actions/skillsbase-sync/action.yml", repoPath),
+    syncAction,
     /npm install --global @hagicode\/skillsbase/,
   );
   assert.match(
-    await read(".github/actions/skillsbase-sync/action.yml", repoPath),
+    syncAction,
     /skillsbase sync --check --repo \./,
   );
+  assert.match(manageAction, /operation:\n    description:/);
+  assert.match(manageAction, /skill-name:\n    description:/);
+  assert.match(manageAction, /allow-missing-sources:/);
+  assert.match(manageAction, /case "\$\{OPERATION\}" in/);
+  assert.match(manageAction, /command=\(skillsbase "\$\{OPERATION\}"/);
+  assert.match(manageAction, /command=\(skillsbase sync "\$\{base_args\[@\]\}"\)/);
+});
+
+test("github_action kind-specific generation keeps workflow and action pairs together", async () => {
+  const tempRoot = await createTempDir();
+  const workflowRepoPath = path.join(tempRoot, "workflow-repo");
+  await fs.mkdir(workflowRepoPath, { recursive: true });
+
+  const workflowResult = await runCommand({
+    cwd: workflowRepoPath,
+    args: ["github_action", "--repo", workflowRepoPath, "--kind", "workflow"],
+  });
+
+  assert.equal(workflowResult.exitCode, 0);
+  assert.equal(await exists(path.join(workflowRepoPath, ".github", "workflows", "skills-sync.yml")), true);
+  assert.equal(await exists(path.join(workflowRepoPath, ".github", "workflows", "skills-manage.yml")), true);
+  assert.equal(await exists(path.join(workflowRepoPath, ".github", "actions", "skillsbase-sync", "action.yml")), true);
+  assert.equal(await exists(path.join(workflowRepoPath, ".github", "actions", "skillsbase-manage", "action.yml")), true);
+
+  const actionRepoPath = path.join(tempRoot, "action-repo");
+  await fs.mkdir(actionRepoPath, { recursive: true });
+
+  const actionResult = await runCommand({
+    cwd: actionRepoPath,
+    args: ["github_action", "--repo", actionRepoPath, "--kind", "action"],
+  });
+
+  assert.equal(actionResult.exitCode, 0);
+  assert.equal(await exists(path.join(actionRepoPath, ".github", "actions", "skillsbase-sync", "action.yml")), true);
+  assert.equal(await exists(path.join(actionRepoPath, ".github", "actions", "skillsbase-manage", "action.yml")), true);
+  assert.equal(await exists(path.join(actionRepoPath, ".github", "workflows", "skills-sync.yml")), false);
+  assert.equal(await exists(path.join(actionRepoPath, ".github", "workflows", "skills-manage.yml")), false);
 });
 
 test("sync fails with actionable diagnostics when the manifest is missing", async () => {