Add a background git-worktrees skill

Hide the recipe from slash and use_skill listing while keeping resolve by
name for implement and linear-issue-workflow.

Closes CL-7013

Author: TheGreatAxios

docs/ARCHITECTURE.md

@@ -416,19 +416,20 @@ Primary is Skywalker. Bundled skill bodies that are operator slashes are **actio
 | `.claude/skills/`     | Claude Code workspace skills                                                                                                            |
 | `.codex/skills/`      | Codex workspace skills                                                                                                                  |
 
-Each `<base>/<skill-name>/SKILL.md` is one skill. Discovery dedupes by directory name: the first base dir that provides a given name wins, so an enabled plugin skill shadows a project-local skill of the same name. Plugin dirs are passed in discovery order (repo first), so a first-party catalog name wins over a later marketplace or project skill of the same name. `resolveSkillBody(cwd, ref, pluginDirs)` resolves a skill's body using the same ordered list (it accepts a bare name or a `plugin:name` ref, keying on the name).
+Each `<base>/<skill-name>/SKILL.md` is one skill. Discovery dedupes by directory name: the first base dir that provides a given name wins, so an enabled plugin skill shadows a project-local skill of the same name. Plugin dirs are passed in discovery order (repo first), so a first-party catalog name wins over a later marketplace or project skill of the same name. Skills with `disable-model-invocation: true` are omitted from the returned listing but still claim the name (first-wins), so a lower-priority same-name skill cannot leak into the listing. `resolveSkillBody(cwd, ref, pluginDirs)` resolves a skill's body using the same ordered list (it accepts a bare name or a `plugin:name` ref, keying on the name) and **does not** hard-fail on `disable-model-invocation` — explicit `use_skill("name")` still loads background libraries.
 
 #### SKILL.md format
 
-A skill file begins with a YAML frontmatter block, followed by the body that holds the instructions. Discovery parses `description`; `loadSkillCommands` also reads `user-invocable`. The skill's identifier (what `use_skill` and `/<skill-name>` take) is its directory name. A skill with no `SKILL.md` or an empty body is skipped.
+A skill file begins with a YAML frontmatter block, followed by the body that holds the instructions. Discovery parses `description` and `disable-model-invocation`; `loadSkillCommands` also reads `user-invocable`. The skill's identifier (what `use_skill` and `/<skill-name>` take) is its directory name. A skill with no `SKILL.md` or an empty body is skipped.
 
-| Field            | Required     | Description                                                                                                                                        |
-| ---------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `description`    | yes          | One-line summary shown in the prompt's lazy skills listing and the slash picker                                                                    |
-| `name`           | conventional | Conventionally matches the directory name; the directory name is what is actually used as the identifier                                           |
-| `user-invocable` | no           | When `false`, `loadSkillCommands` skips slash synthesis; the skill remains `use_skill` only. Untagged skills still become slashes (marketplace BC) |
+| Field                       | Required     | Description                                                                                                                                                                                                 |
+| --------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `description`               | yes          | One-line summary shown in the prompt's lazy skills listing and the slash picker                                                                                                                             |
+| `name`                      | conventional | Conventionally matches the directory name; the directory name is what is actually used as the identifier                                                                                                    |
+| `user-invocable`            | no           | When `false`, `loadSkillCommands` skips slash synthesis; the skill remains `use_skill` only. Untagged skills still become slashes (marketplace BC)                                                          |
+| `disable-model-invocation`  | no           | When `true`, `discoverSkills` omits the skill from the lazy listing (but still claims the name for first-wins). Explicit `resolveSkillBody` / `use_skill("name")` still loads the body. Does not affect slash emission. |
 
-There are no `type` or `disable-model-invocation` fields required for model invocation — a skill body is plain instruction text. `argument-hint` on frontmatter is preserved for the slash picker (greyed arg guidance). Multi-step orchestration is a separate mechanism (see Workflows above), not a skill `type`.
+There is no skill `type` field required for model invocation — a skill body is plain instruction text. Background libraries (e.g. `git-worktrees`) set both `user-invocable: false` and `disable-model-invocation: true` so they are absent from slash and listing, yet recipes can still `use_skill("git-worktrees")`. `argument-hint` on frontmatter is preserved for the slash picker (greyed arg guidance). Multi-step orchestration is a separate mechanism (see Workflows above), not a skill `type`.
 
 #### Loading (model and operator)
 

docs/PLUGINS.md

@@ -309,10 +309,14 @@ shape.
   become slashes (marketplace backward compatibility). Frontmatter
   `argument-hint` is preserved so the TUI can show greyed arg guidance (e.g.
   `/create-issue` → `[description] [--from-doc]`). This is an additional
-  surface: `discoverSkills` is unchanged, so the model can still auto-invoke any
-  skill via `use_skill` — including first-party recipes that are not operator
-  slashes (`dispatch`, `git-rebase`, `linear-issue-workflow`, `style`,
-  `philosophy`, `typescript`, `opsh`). The slash command is a direct user entry
+  surface: `discoverSkills` skips skills with `disable-model-invocation: true`
+  from the lazy listing (those stay loadable via explicit `use_skill` /
+  `resolveSkillBody`), so the model does not auto-suggest background libraries.
+  First-party recipes that are not operator slashes remain listed for
+  `use_skill` when they only set `user-invocable: false` (`dispatch`,
+  `git-rebase`, `linear-issue-workflow`, `style`, `philosophy`, `typescript`,
+  `opsh`). Background libs such as `git-worktrees` set both flags. The slash
+  command is a direct user entry
   point on top.
 - **First-party catalog.** `plugins/corbits-skills/` (id `corbits-skills`,
   kind `command`, `defaultEnabled: true`) is the bundled skill catalog. Origin

plugins/corbits-skills/skills/git-worktrees/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: git-worktrees
+user-invocable: false
+disable-model-invocation: true
+description: Create a git worktree from origin/<default-branch> and tear it down. Background library — load via use_skill("git-worktrees"); absent from slash and use_skill listing.
+---
+
+# git-worktrees
+
+Background recipe. Skywalker loads via `use_skill("git-worktrees")` and copies commands into an intern brief. Intern executes via `run_shell`. Skywalker does not run the git.
+
+## Create from origin/<default-branch>
+
+```bash
+git symbolic-ref refs/remotes/origin/HEAD | sed 's@^refs/remotes/origin/@@'
+git fetch origin
+git worktree add ../worktree/<branch-name> -b <branch-name> origin/<default-branch>
+```
+
+Always base new branches on `origin/<default-branch>` (whatever the repository uses). After creating the worktree, intern `cd`s into it and installs local dependencies (`bun install` when the project uses Bun; otherwise follow developer docs). Worktrees do not share `node_modules`.
+
+## Teardown
+
+```bash
+cd <path-to-main-repo>
+git fetch origin
+git worktree remove ../worktree/<branch-name>
+git branch -d <branch-name>
+```
+
+If the worktree directory was already deleted: `git worktree prune`.

plugins/corbits-skills/skills/linear-issue-workflow/SKILL.md

@@ -21,23 +21,15 @@ If the scope is unclear, `ask_operator` before proceeding. Do not guess.
 
 Read `branchName` from the issue (call `mcp__linear__get_issue` again if needed).
 
-Spawn `task(agent="intern")` with this sequenced `run_shell` list copied into the brief. Intern executes; Skywalker does not run the git.
+Load `use_skill("git-worktrees")`. Copy the create-from-origin/<default-branch> recipe into an intern brief (substitute `<branch-name>`). Spawn `task(agent="intern")`. Intern executes; Skywalker does not run the git.
 
-```bash
-git symbolic-ref refs/remotes/origin/HEAD | sed 's@^refs/remotes/origin/@@'
-git fetch origin
-git worktree add ../worktree/<branch-name> -b <branch-name> origin/<default-branch>
-```
-
-Always base new branches on `origin/<default-branch>` (whatever the repository uses). After creating the worktree, intern `cd`s into it and installs local dependencies from developer documentation. Worktrees do not share `node_modules`.
-
-If intern fails, stop and `ask_operator`. If the operator rejects the issue before implementation, intern tears down the worktree (Phase 7 commands) rather than leaving it stranded.
+If intern fails, stop and `ask_operator`. If the operator rejects the issue before implementation, intern tears down the worktree via the git-worktrees teardown recipe rather than leaving it stranded.
 
 ## Phase 3: Plan, attach, mark In Progress
 
 1. Spawn `task(agent="explore")` if the codebase map is not already known. Brief it with the absolute worktree path (it must work there) and the issue: where changes go, existing patterns, related code.
 2. Follow the `/implement` loop's greybeard step (Phase 4) for the approach. Present the plan to the operator and `ask_operator` whether to proceed. Do not start implementation until approved.
-3. If the operator rejects the plan and the issue cannot be salvaged, intern tears down the worktree (Phase 7) rather than leaving it stranded.
+3. If the operator rejects the plan and the issue cannot be salvaged, intern tears down the worktree via the git-worktrees teardown recipe rather than leaving it stranded.
 4. Attach the plan to the Linear issue. **Do not post the plan as a comment** — comments are for discussion, not archives.
 
    Spawn `task(agent="build")` with a mechanical brief to write the approved plan to the worktree's `tmp/plan-<ISSUE-ID>.md` (do not commit it). Intern captures byte size with `wc -c`. Primary then:
@@ -130,16 +122,7 @@ Phase 6 ends when the PR is open. Phase 7 runs **after the PR is merged** and **
 2. Re-read the issue with `mcp__linear__get_issue`. Flip checkboxes the merged PR actually completed on `main` via `mcp__linear__save_issue`. Never check a box on intent.
 3. `mcp__linear__save_comment` with PR URL, merge SHA, and CI-green confirmation. Short. Present-tense facts.
 4. If every outcome checkbox is checked, set state to `Done` with `mcp__linear__save_issue`. Otherwise leave In Progress.
-5. Only then intern cleans up:
-
-```bash
-cd <path-to-main-repo>
-git fetch origin
-git worktree remove ../worktree/<branch-name>
-git branch -d <branch-name>
-```
-
-If the worktree directory was already deleted: `git worktree prune`.
+5. Only then intern cleans up: load `use_skill("git-worktrees")` and copy the teardown recipe into an intern brief (substitute `<branch-name>` and `<path-to-main-repo>`).
 
 ## Linear MCP tool reference
 

src/extensions/skills.ts

@@ -50,13 +50,25 @@ function stripFrontmatter(raw: string): string {
   return raw.slice(end + 3).trim();
 }
 
-function parseSkillFrontmatter(raw: string): { name?: string; description?: string } {
+function parseSkillFrontmatter(raw: string): {
+  name?: string;
+  description?: string;
+  disableModelInvocation?: boolean;
+} {
   const block = frontmatterBlock(raw);
   if (block === undefined) return {};
-  const out: { name?: string; description?: string } = {};
+  const out: {
+    name?: string;
+    description?: string;
+    disableModelInvocation?: boolean;
+  } = {};
   for (const line of block.split("\n")) {
-    const match = /^(name|description):\s*(.+)$/.exec(line.trim());
+    const trimmed = line.trim();
+    const match = /^(name|description):\s*(.+)$/.exec(trimmed);
     if (match) out[match[1] as "name" | "description"] = match[2]!.trim();
+    if (/^disable-model-invocation:\s*true\s*$/.test(trimmed)) {
+      out.disableModelInvocation = true;
+    }
   }
   return out;
 }
@@ -136,11 +148,15 @@ export async function resolveSkillBody(
 // Discover every available skill (name + one-line description) for the lazy
 // listing in the system prompt. Deduped by name: the first base dir that
 // provides a skill wins, so a higher-precedence dir shadows a lower one.
+// Skills with `disable-model-invocation: true` are omitted from the listing
+// but still occupy the name in `seen` so a lower-priority same-name skill
+// cannot leak in. Explicit `use_skill` / `resolveSkillBody` loads still work.
 export async function discoverSkills(
   cwd: string,
   pluginDirs: string[] = [],
 ): Promise<SkillSummary[]> {
-  const seen = new Map<string, SkillSummary>();
+  const seen = new Set<string>();
+  const skills: SkillSummary[] = [];
   for (const base of skillBaseDirs(cwd, pluginDirs)) {
     const entries = await readdir(base, { withFileTypes: true }).catch(() => undefined);
     if (entries === undefined) continue;
@@ -149,8 +165,11 @@ export async function discoverSkills(
       const raw = await readRaw(join(base, entry.name, "SKILL.md"));
       if (raw === undefined) continue;
       const fm = parseSkillFrontmatter(raw);
-      seen.set(entry.name, { name: entry.name, description: fm.description ?? "" });
+      // First-wins: claim the name even when skipping the listing.
+      seen.add(entry.name);
+      if (fm.disableModelInvocation) continue;
+      skills.push({ name: entry.name, description: fm.description ?? "" });
     }
   }
-  return [...seen.values()];
+  return skills;
 }

src/plugins/skill-commands.ts

@@ -11,9 +11,9 @@ import { splitFrontmatter } from "./frontmatter.js";
 // body (plus args) to the agent. Convention/internal skills opt out with
 // `user-invocable: false` in frontmatter and are not emitted as slash commands.
 // Untagged skills still become slash commands (marketplace BC).
-// `disable-model-invocation` does not affect slash emission. A skill authored
-// as `skills/<name>/SKILL.md` is still model-invoked via the `use_skill` tool;
-// `discoverSkills` is unchanged, so the model can still auto-invoke any skill.
+// `disable-model-invocation` does not affect slash emission — that flag only
+// skips the skill from `discoverSkills` lazy listing. Explicit `use_skill` /
+// `resolveSkillBody` still loads the body by name.
 
 const COMMAND_NAME_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/;
 
@@ -60,7 +60,8 @@ export async function loadSkillCommands(
       continue;
     }
     // Opt-out of the slash surface. Untagged skills still emit a command
-    // (marketplace BC); `disable-model-invocation` does not affect this.
+    // (marketplace BC); `disable-model-invocation` does not affect this —
+    // it only skips discoverSkills listing (see src/extensions/skills.ts).
     if (frontmatter["user-invocable"] === false) continue;
 
     const name =

tests/unit/corbits-skills-catalog.test.ts

@@ -17,6 +17,7 @@ const SKILL_DIRS = [
   "typescript",
   "interview",
   "git-rebase",
+  "git-worktrees",
   "refactor",
   "pull-request-review",
   "create-issue",
@@ -27,6 +28,7 @@ const SKILL_DIRS = [
 
 const SPAWN_RECIPE_SKILLS = ["implement", "scribe", "review", "dispatch", "plan"] as const;
 
+/** use_skill listing + resolve; not slash. No disable-model-invocation. */
 const USE_SKILL_ONLY = [
   "dispatch",
   "git-rebase",
@@ -37,6 +39,9 @@ const USE_SKILL_ONLY = [
   "opsh",
 ] as const;
 
+/** Background libs: absent from slash and use_skill listing; explicit resolve only. */
+const BACKGROUND_ONLY = ["git-worktrees"] as const;
+
 const SLASH_SKILLS = [
   "implement",
   "refactor",
@@ -52,6 +57,7 @@ const SLASH_SKILLS = [
 const BANNED_TOKENS = ["TaskCreate", "@greybeard", 'intent="general"'] as const;
 
 const USER_INVOCABLE_FALSE = "user-invocable: false";
+const DISABLE_MODEL_INVOCATION = "disable-model-invocation: true";
 
 async function listFilesRecursive(dir: string): Promise<string[]> {
   const out: string[] = [];
@@ -82,8 +88,8 @@ test("corbits-skills plugin has no agents directory", () => {
   expect(existsSync(join(pluginRoot, "agents"))).toBe(false);
 });
 
-test("corbits-skills catalog lists 16 skills with name and description", async () => {
-  expect(SKILL_DIRS).toHaveLength(16);
+test("corbits-skills catalog lists 17 skills with name and description", async () => {
+  expect(SKILL_DIRS).toHaveLength(17);
   const entries = await readdir(join(pluginRoot, "skills"), { withFileTypes: true });
   const dirs = entries
     .filter((entry) => entry.isDirectory())
@@ -114,13 +120,41 @@ test("create-issue selects Linear MCP, GitHub gh, and MEMORY.md preference", asy
   expect(skill).toContain("Preferred issue tracker:");
 });
 
-test("use_skill-only skills set user-invocable: false", async () => {
+test("use_skill-only skills set user-invocable: false without disable-model-invocation", async () => {
   for (const name of USE_SKILL_ONLY) {
     const skill = await Bun.file(join(pluginRoot, "skills", name, "SKILL.md")).text();
     expect(skill).toContain(USER_INVOCABLE_FALSE);
+    expect(skill).not.toContain(DISABLE_MODEL_INVOCATION);
+  }
+});
+
+test("background-only skills set both exclusion flags", async () => {
+  for (const name of BACKGROUND_ONLY) {
+    const skill = await Bun.file(join(pluginRoot, "skills", name, "SKILL.md")).text();
+    expect(skill).toContain(USER_INVOCABLE_FALSE);
+    expect(skill).toContain(DISABLE_MODEL_INVOCATION);
+  }
+});
+
+test("only background libs carry disable-model-invocation", async () => {
+  for (const name of SKILL_DIRS) {
+    const skill = await Bun.file(join(pluginRoot, "skills", name, "SKILL.md")).text();
+    if ((BACKGROUND_ONLY as readonly string[]).includes(name)) {
+      expect(skill).toContain(DISABLE_MODEL_INVOCATION);
+    } else {
+      expect(skill).not.toContain(DISABLE_MODEL_INVOCATION);
+    }
   }
 });
 
+test("linear-issue-workflow references use_skill(git-worktrees)", async () => {
+  const skill = await Bun.file(
+    join(pluginRoot, "skills/linear-issue-workflow/SKILL.md"),
+  ).text();
+  expect(skill).toContain('use_skill("git-worktrees")');
+  expect(skill).not.toContain("git worktree add");
+});
+
 test("slash skills do not set user-invocable: false", async () => {
   for (const name of SLASH_SKILLS) {
     const skill = await Bun.file(join(pluginRoot, "skills", name, "SKILL.md")).text();