Prefix controller-managed skills with controller- and hide them from the slash picker (#173)

germanescobar · web-flow · commit ed0ea64b1a81 · 2026-06-21T18:52:37.000-05:00
The five app-managed skills installed into every provider's user home on startup are agent-facing, not user-invokable. Today they live under unprefixed names (`browser`, `integrations`, `search-skills`, `skill-creator`, plus the partially-prefixed `controller-scripts`) and render in the `/` picker as ordinary `scope: "user"` skills, so a user typing `/` sees half the visible items being app-managed with no visual cue. Rename them under a consistent `controller-` prefix (`controller-browser`, `controller-integrations`, `controller-search-skills`, `controller-skill-creator`, and `controller-scripts` grandfathered as the only exception to avoid a double prefix), update each `name:` frontmatter to match the directory name, refresh the bodies' self-references and collision examples, and bump the `MANAGED_MARKER` comment to reference this issue so future renames can detect unowned files. The disk provider now detects `MANAGED_MARKER` and tags the resulting metadata with a new `scope: "managed"` value (extends `SkillScope` on both server and client). `mergeSkillMetadata` keeps managed entries reachable for body lookup — the agent still needs to `readBody` them — and the chat composer's `/` picker filters them out of the popover so they no longer mix in with user-invokable skills. A user who types `/controller-browser` manually and submits still gets the body prepended; the server-side slash path is intentionally left permissive. After upgrading, manually remove the old `~/.{anita,codex,claude}/skills/` directories named `browser`, `integrations`, `search-skills`, or `skill-creator` — their previous `MANAGED_MARKER` would otherwise leave them visible as regular user-authored skills. Closes #159
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,33 @@ All notable changes to this project are documented here.
 
 ## [Unreleased]
 
+### Changed
+
+- **Renamed controller-managed skills to a `controller-` prefix and hid them
+  from the `/` picker** (#159). The five app-managed skills installed into
+  each provider's user home on startup
+  (`browser` → `controller-browser`,
+  `integrations` → `controller-integrations`,
+  `controller-scripts` (grandfathered — no double prefix),
+  `search-skills` → `controller-search-skills`,
+  `skill-creator` → `controller-skill-creator`) now live under
+  `controller-`-prefixed directories, with matching `name:` frontmatter and
+  `MANAGED_MARKER` (now references issue #159 so future renames can detect
+  unowned files). The disk provider tags any `SKILL.md` carrying the
+  marker with `scope: "managed"`, and the chat composer filters
+  `scope: "managed"` entries out of the `/` autocomplete popover so users
+  no longer see agent-facing skills mixed in with their own. The agent
+  still discovers the body through the filesystem location, so a user who
+  types `/controller-browser` manually and submits still gets the body
+  prepended. Existing per-agent and unified skills are unaffected. **Note:**
+  after upgrading, manually remove the old `~/.{anita,codex,claude}/skills/`
+  directories named `browser`, `integrations`, `search-skills`, or
+  `skill-creator` (or simply `rm -rf ~/.anita/skills/browser` etc.); they
+  carry the previous marker comment and would otherwise be re-read as
+  regular user-authored skills.
+
+
+
 ### Changed
 
 - **Updated session-file ownership comments to reflect post-#152 / #163
diff --git a/client/src/api.ts b/client/src/api.ts
@@ -668,7 +668,12 @@ export async function fetchAgentProviders(): Promise<AgentProviderInfo[]> {
   return res.json();
 }
 
-export type SkillScope = "unified" | "user" | "system" | "repo";
+export type SkillScope =
+  | "unified"
+  | "user"
+  | "system"
+  | "repo"
+  | "managed";
 
 export interface AgentSkill {
   name: string;
diff --git a/client/src/pages/SessionView.tsx b/client/src/pages/SessionView.tsx
@@ -3666,9 +3666,16 @@ export function SessionView({
   }, [message]);
   const filteredSkills = useMemo(() => {
     if (skillQuery === null) return [];
+    // Hide controller-managed skills (e.g. `controller-browser`) from the
+    // `/` picker. They are still in `availableSkills` so a user can type the
+    // name manually and submit; the server-side slash path will prepend the
+    // body either way. Managed skills are agent-facing, not user-invokable.
+    const userVisible = availableSkills.filter(
+      (entry) => entry.scope !== "managed"
+    );
     const needle = skillQuery.token.toLowerCase();
-    if (!needle) return availableSkills;
-    return availableSkills.filter((entry) =>
+    if (!needle) return userVisible;
+    return userVisible.filter((entry) =>
       entry.name.toLowerCase().startsWith(needle)
     );
   }, [availableSkills, skillQuery]);
diff --git a/server/lib/__tests__/managed-skills.test.ts b/server/lib/__tests__/managed-skills.test.ts
@@ -76,10 +76,10 @@ test("managed skills use a single `<cliPath> <surface> <command>` convention", a
     // `<cliPath> <surface> <command>`. Never a bare subcommand, never a
     // double-prefixed surface.
     const cases = [
-      { name: "browser", surface: "browser" },
-      { name: "integrations", surface: "integrations" },
-      { name: "search-skills", surface: "skills" },
-      { name: "skill-creator", surface: "skills" },
+      { name: "controller-browser", surface: "browser" },
+      { name: "controller-integrations", surface: "integrations" },
+      { name: "controller-search-skills", surface: "skills" },
+      { name: "controller-skill-creator", surface: "skills" },
     ] as const;
 
     for (const provider of [".anita", ".codex", ".claude"]) {
@@ -143,7 +143,7 @@ test("browser, integrations, and skills bodies advertise concrete commands", asy
     );
 
     const anitaBrowser = readFileSync(
-      path.join(os.homedir(), ".anita", "skills", "browser", "SKILL.md"),
+      path.join(os.homedir(), ".anita", "skills", "controller-browser", "SKILL.md"),
       "utf-8"
     );
     assert.match(
@@ -156,7 +156,13 @@ test("browser, integrations, and skills bodies advertise concrete commands", asy
     );
 
     const anitaIntegrations = readFileSync(
-      path.join(os.homedir(), ".anita", "skills", "integrations", "SKILL.md"),
+      path.join(
+        os.homedir(),
+        ".anita",
+        "skills",
+        "controller-integrations",
+        "SKILL.md"
+      ),
       "utf-8"
     );
     assert.match(
@@ -169,7 +175,13 @@ test("browser, integrations, and skills bodies advertise concrete commands", asy
     );
 
     const anitaSearchSkills = readFileSync(
-      path.join(os.homedir(), ".anita", "skills", "search-skills", "SKILL.md"),
+      path.join(
+        os.homedir(),
+        ".anita",
+        "skills",
+        "controller-search-skills",
+        "SKILL.md"
+      ),
       "utf-8"
     );
     assert.match(
@@ -182,7 +194,13 @@ test("browser, integrations, and skills bodies advertise concrete commands", asy
     );
 
     const anitaSkillCreator = readFileSync(
-      path.join(os.homedir(), ".anita", "skills", "skill-creator", "SKILL.md"),
+      path.join(
+        os.homedir(),
+        ".anita",
+        "skills",
+        "controller-skill-creator",
+        "SKILL.md"
+      ),
       "utf-8"
     );
     assert.match(
@@ -191,3 +209,54 @@ test("browser, integrations, and skills bodies advertise concrete commands", asy
     );
   });
 });
+
+test("managed skills install under controller-prefixed directory names", async () => {
+  await withIsolatedHomes(async () => {
+    await installManagedSkills();
+
+    // Each managed skill should land in a `controller-`-prefixed directory
+    // (or stay as the grandfathered `controller-scripts`). The marker comment
+    // references issue #159 so future renames can detect unowned files.
+    const expected: Array<{ dir: string; name: string }> = [
+      { dir: "controller-browser", name: "controller-browser" },
+      { dir: "controller-integrations", name: "controller-integrations" },
+      { dir: "controller-scripts", name: "controller-scripts" },
+      { dir: "controller-search-skills", name: "controller-search-skills" },
+      { dir: "controller-skill-creator", name: "controller-skill-creator" },
+    ];
+
+    for (const provider of [".anita", ".codex", ".claude"]) {
+      for (const { dir, name } of expected) {
+        const skillFile = path.join(
+          os.homedir(),
+          provider,
+          "skills",
+          dir,
+          "SKILL.md"
+        );
+        assert.ok(
+          existsSync(skillFile),
+          `expected ${skillFile} to be installed`
+        );
+        const body = readFileSync(skillFile, "utf-8");
+        // The `name:` frontmatter must match the directory name so
+        // `extractSkillInvocation` and the disk loader see consistent names.
+        const frontmatterMatch = /^---\nname:\s*([^\n]+)\n/m.exec(body);
+        assert.ok(
+          frontmatterMatch,
+          `${skillFile} is missing a 'name:' frontmatter line`
+        );
+        assert.equal(
+          frontmatterMatch[1].trim(),
+          name,
+          `${skillFile} frontmatter name does not match the directory name`
+        );
+        // The body must carry the up-to-date managed marker.
+        assert.ok(
+          body.includes("<!-- managed-by: coding-orchestrator (issue #159) -->"),
+          `${skillFile} is missing the current MANAGED_MARKER`
+        );
+      }
+    }
+  });
+});
diff --git a/server/lib/__tests__/skills.test.ts b/server/lib/__tests__/skills.test.ts
@@ -458,3 +458,71 @@ test("unified skills appear in listMetadata above per-agent skills", async () =>
     rmSync(orchestratorHome, { recursive: true, force: true });
   });
 });
+
+// ---------------------------------------------------------------------------
+// Controller-managed skills: scope and dedupe behavior (issue #159)
+// ---------------------------------------------------------------------------
+
+const MANAGED_MARKER = "<!-- managed-by: coding-orchestrator (issue #159) -->";
+
+test("per-agent SKILL.md with MANAGED_MARKER is surfaced as scope 'managed'", async () => {
+  await withProviderHome("anita", async (home, provider) => {
+    // A managed skill lives in the user home with the marker comment in the
+    // body. The loader should tag its metadata as `scope: "managed"` so the
+    // `/` picker can hide it.
+    makeSkillFile(
+      path.join(home, ".anita/skills"),
+      "controller-browser",
+      { name: "controller-browser", description: "Drive the preview browser" },
+      `${MANAGED_MARKER}\n# controller-browser\nbody`
+    );
+    const metadata = await provider.listMetadata(os.tmpdir());
+    assert.equal(metadata.length, 1);
+    assert.equal(metadata[0].name, "controller-browser");
+    assert.equal(metadata[0].scope, "managed");
+  });
+});
+
+test("a user-authored SKILL.md in the same directory keeps scope 'user'", async () => {
+  await withProviderHome("anita", async (home, provider) => {
+    // No marker → regular user skill. The scope should not be silently
+    // upgraded to "managed" just because the directory looks controlled.
+    makeSkillFile(
+      path.join(home, ".anita/skills"),
+      "my-skill",
+      { name: "my-skill", description: "Mine" },
+      "# my-skill\nbody"
+    );
+    const metadata = await provider.listMetadata(os.tmpdir());
+    assert.equal(metadata.length, 1);
+    assert.equal(metadata[0].scope, "user");
+  });
+});
+
+test("mergeSkillMetadata keeps managed entries for body lookup (unified still wins)", () => {
+  const unified = [skillMeta("imagegen", "unified", "u")];
+  const perAgent = [
+    skillMeta("controller-browser", "managed", "managed browser"),
+    skillMeta("github-issues", "user", "user skill"),
+  ];
+  const merged = mergeSkillMetadata(unified, perAgent);
+  // Unified renders first; managed + user entries follow in their original
+  // order. The managed entry must remain reachable so the agent can
+  // `readBody` it on demand.
+  assert.deepEqual(merged.map((entry) => [entry.name, entry.scope]), [
+    ["imagegen", "unified"],
+    ["controller-browser", "managed"],
+    ["github-issues", "user"],
+  ]);
+});
+
+test("extractSkillInvocation matches the renamed controller- names", () => {
+  assert.deepEqual(extractSkillInvocation("/controller-browser do it"), {
+    skillName: "controller-browser",
+    rest: "do it",
+  });
+  assert.deepEqual(extractSkillInvocation("/controller-search-skills find x"), {
+    skillName: "controller-search-skills",
+    rest: "find x",
+  });
+});
diff --git a/server/lib/managed-skills.ts b/server/lib/managed-skills.ts
@@ -11,11 +11,12 @@ import os from "node:os";
 import path from "node:path";
 import { controllerCliInstalledPath } from "./controller-cli.js";
 
-const MANAGED_MARKER = "<!-- managed-by: coding-orchestrator (issue #109) -->";
+export const MANAGED_MARKER =
+  "<!-- managed-by: coding-orchestrator (issue #159) -->";
 
 function buildIntegrationsSkillBody(cliPath: string): string {
   return `---
-name: integrations
+name: controller-integrations
 description: Discover and use the third-party services the user connected in Controller (APIs, MCP servers, native CLIs) through a uniform gateway. Use whenever a task needs an external service — search for a capability, then call it. Credentials are injected by Controller; you never see or handle secrets.
 ---
 
@@ -28,6 +29,11 @@ Integrations. You reach them through the Controller CLI, invoked by its absolute
 path (it is not on your PATH). Every command below is run as
 \`${cliPath} integrations <command>\`.
 
+This skill is managed by the Controller app (directory name
+\`controller-integrations\`). It is hidden from the \`/\` picker — the agent
+discovers the body through the filesystem location, not via a user-invoked
+slash command.
+
 Controller holds the credentials and injects them server-side when making the
 call — there is no token for you to read, and you must never ask the user to
 paste one into the chat. Authentication is set up in the UI.
@@ -93,7 +99,7 @@ the integration, then retry.
 
 function buildBrowserSkillBody(cliPath: string): string {
   return `---
-name: browser
+name: controller-browser
 description: Drive the visible in-app preview browser to open pages, read the rendered DOM, and click or type — use it to verify UI/web work instead of guessing.
 ---
 
@@ -106,6 +112,11 @@ browser CLI. Use it to verify front-end and web work: open a localhost dev
 server or a project HTML file, read what actually rendered, and interact with
 the page. The user sees everything you do in the Preview tab.
 
+This skill is managed by the Controller app (directory name
+\`controller-browser\`). It is hidden from the \`/\` picker — the agent
+discovers the body through the filesystem location, not via a user-invoked
+slash command.
+
 Invoke the CLI by its absolute path — it is not on your PATH. Every command
 below is run as \`${cliPath} browser <command>\`:
 
@@ -147,6 +158,11 @@ ${MANAGED_MARKER}
 
 # Controller Scripts
 
+This skill is managed by the Controller app (directory name
+\`controller-scripts\`). It is hidden from the \`/\` picker — the agent
+discovers the body through the filesystem location, not via a user-invoked
+slash command.
+
 Controller resolves native scripts from the project's root
 \`.coding-orchestrator/\` directory:
 
@@ -322,14 +338,19 @@ When migrating, translate those JSON commands into native shell scripts at
 
 function buildSearchSkillsBody(cliPath: string): string {
   return `---
-name: search-skills
+name: controller-search-skills
 description: Search and activate unified skills from the Controller catalog. Use when the user asks for a capability that might already be configured as a unified skill, or when you want to reuse an existing skill for the current turn.
 ---
 
 ${MANAGED_MARKER}
 
 # Search Skills
 
+This skill is managed by the Controller app (directory name
+\`controller-search-skills\`). It is hidden from the \`/\` picker — the agent
+discovers the body through the filesystem location, not via a user-invoked
+slash command.
+
 Controller hosts an app-owned catalog of unified skills in Settings → Skills.
 These skills are available to every agent and take precedence over per-agent
 skills with the same name. You can search the catalog and activate a skill so
@@ -395,14 +416,19 @@ interface ManagedSkill {
 
 function buildSkillCreatorSkillBody(cliPath: string): string {
   return `---
-name: skill-creator
+name: controller-skill-creator
 description: Create a new unified skill in the Controller catalog by interviewing the user, drafting a SKILL.md, and writing it via the Controller CLI. Use when the user asks to build a new skill, document a recurring workflow, or turn a one-off conversation into a reusable skill.
 ---
 
 ${MANAGED_MARKER}
 
 # Skill Creator
 
+This skill is managed by the Controller app (directory name
+\`controller-skill-creator\`). It is hidden from the \`/\` picker — the agent
+discovers the body through the filesystem location, not via a user-invoked
+slash command.
+
 You help the user create a new unified skill in Controller's app-owned
 catalog at \`~/coding-orchestrator/skills/<name>/SKILL.md\`. Skills created
 here are available to every agent immediately and surface in the \`/\`
@@ -493,8 +519,8 @@ fails on duplicate names so it cannot be used as an edit path.
 
 - Unified skills take precedence over per-agent skills with the same name,
   so creating a skill called \`browser\` would shadow the managed
-  \`browser\` skill. Confirm with the user before claiming a name that
-  might collide with a built-in.
+  \`controller-browser\` skill. Confirm with the user before claiming a name
+  that might collide with a built-in.
 - The CLI writes to \`~/coding-orchestrator/skills/<name>/SKILL.md\`. Do
   not try to write the file directly — let the CLI perform validation.
 - Skill activation (\`/name\`) prepends the body to the user's next
@@ -535,11 +561,11 @@ export async function installManagedSkills(): Promise<void> {
   // bare CLI path here.
   const cli = controllerCliInstalledPath();
   const skills: ManagedSkill[] = [
-    { name: "browser", body: buildBrowserSkillBody(cli) },
-    { name: "integrations", body: buildIntegrationsSkillBody(cli) },
+    { name: "controller-browser", body: buildBrowserSkillBody(cli) },
+    { name: "controller-integrations", body: buildIntegrationsSkillBody(cli) },
     { name: "controller-scripts", body: CONTROLLER_SCRIPTS_SKILL_BODY },
-    { name: "search-skills", body: buildSearchSkillsBody(cli) },
-    { name: "skill-creator", body: buildSkillCreatorSkillBody(cli) },
+    { name: "controller-search-skills", body: buildSearchSkillsBody(cli) },
+    { name: "controller-skill-creator", body: buildSkillCreatorSkillBody(cli) },
   ];
 
   for (const { dir } of providerHomes()) {
diff --git a/server/lib/skills.ts b/server/lib/skills.ts
