🤖 refactor: make /init a built-in agent skill

- Convert `/init` from a hardcoded slash command into a built-in agent skill.
- Allow `/{skill-name}` invocations with no trailing message (send a tiny default message).
- Update project “Initialize” banner to send `/init`.
- Document built-in skill precedence + `/init` override behavior.

Signed-off-by: Thomas Kosiewski <tk@coder.com>

---

<details>
<summary>📋 Implementation Plan</summary>

- Remove `/init` from the hardcoded slash-command registry + ChatInput branching.
- Treat `/init` as a normal **built-in agent skill** (discovered via `agentSkills.list`).
- Allow invoking a skill with **no trailing message** (e.g. `/init`) so it can fully replace “macro” slash commands.

- **Registry**: `/init` is a hardcoded slash command (`initCommandDefinition`) in `src/browser/utils/slashCommands/registry.ts`, parsed as `{ type: "init" }`.
- **UI special-case**: `src/browser/components/ChatInput/index.tsx` intercepts `parsed.type === "init"` and replaces the input text with `src/browser/assets/initMessage.txt` (`?raw`).
- **Project banner**: `src/browser/components/ProjectPage.tsx` restores the same text and auto-sends it; it also flips project-scope agent mode to `exec`.
- **Backend**: no special handling—`/init` ultimately becomes a normal user message containing a large prompt (currently wrapped in `<system>…</system>`).

- `src/browser/components/ChatInput/index.tsx`
  - Imports `initMessage` from `@/browser/assets/initMessage.txt?raw`.
  - Two `/init` special-cases: `handleSend` checks `parsed?.type === "init"` in both the **creation** path (~line 1402) and **workspace** path (~line 1567).
  - Two “skill invocation requires trailing message” toasts:
    - **Creation** skill path: toast around ~line 1421.
    - **Workspace** skill path: toast around ~line 1496.
- `src/browser/components/ProjectPage.tsx`
  - Imports `initMessage` from `@/browser/assets/initMessage.txt?raw` and uses it in the Agents init banner flow.
- `src/browser/utils/slashCommands/registry.ts`
  - Defines `initCommandDefinition` and registers it.
- `src/browser/utils/slashCommands/types.ts`
  - Includes `{ type: "init" }` in `ParsedCommand` union.
- `src/browser/utils/slashCommands/parser.test.ts`
  - Contains tests asserting `/init` parses to `{ type: "init" }`.

**Net LoC estimate (product code only): ~+30–80**

Core idea: make `init` a built-in skill and invoke it like any other skill. To support `/init` with no extra text, we must avoid sending an empty message because `AgentSession.sendMessage` rejects empty messages.

When the user invokes a skill with no trailing message, send a tiny default message (while still displaying the raw command via `muxMetadata.rawCommand`). Example:

- Raw input: `/init`
- Message sent to backend: `Run the "init" skill.`
- `muxMetadata`: `{ type: "agent-skill", rawCommand: "/init", skillName: "init", scope: "built-in" }`

This keeps the system general (no `/init` special casing) and satisfies the backend’s non-empty constraint.

Skill resolution already supports overrides in this order:

1. **Project**: `.mux/skills/<name>/SKILL.md`
2. **Global**: `~/.mux/skills/<name>/SKILL.md`
3. **Built-in**: `src/node/builtinSkills/<name>.md`

So yes—once `init` is shipped as a built-in skill, a user can override it by creating `~/.mux/skills/init/SKILL.md` (and a project can override that via `.mux/skills/init/SKILL.md`).

<details>
<summary>Tradeoff</summary>

This changes `/init` from an editable “template prefill” into an immediate command. If we still want editability later, we can add a separate “insert skill into input” UI affordance, but that’s not required for this cleanup.

</details>

1) **Allow skills to be sent without a message (creation + workspace ChatInput)**
   - In `src/browser/components/ChatInput/index.tsx`, update both “unknown slash command → agent skill” paths:
     - **Creation path** (~line 1421): remove the “Please add a message after /{skill}” toast + early return.
     - **Workspace path** (~line 1496): same.
     - If trailing text is empty, send a synthetic default message, e.g.

       ```ts
       const userText = afterPrefix.trimStart() || `Run the "${skillName}" skill.`;
       ```
     - Keep setting `muxMetadata = { type: "agent-skill", rawCommand: messageText, ... }` so the UI shows the original `/skill` (not the synthetic message).

2) **Add built-in skill `init`**
   - Create `src/node/builtinSkills/init.md` (frontmatter: `name: init`, description matching current `/init`).
   - Move/copy the existing `src/browser/assets/initMessage.txt` content into the skill body (keep as-is initially for minimal behavior change).
   - Regenerate bundled skill content (`scripts/gen_builtin_skills.ts` → `builtInSkillContent.generated.ts`).

   - Notes / gotchas:
     - Frontmatter must start at the very top of the file (`---` as first bytes).
     - Keep skill content < 1MB.

3) **Remove `/init` as a hardcoded slash command + UI branch**
   - Delete `initCommandDefinition` from `src/browser/utils/slashCommands/registry.ts`.
   - Remove `{ type: "init" }` from `src/browser/utils/slashCommands/types.ts`.
   - Remove the `parsed.type === "init"` branches in `ChatInput` (both creation + workspace).
   - Update/remove `/init` parsing expectations in `src/browser/utils/slashCommands/parser.test.ts`.
   - Result: `/init` will be parsed as an unknown command and then resolved via `agentSkills.list` as a skill.

4) **Update the project “Initialize” banner to invoke the skill**
   - In `src/browser/components/ProjectPage.tsx`:
     - Replace `restoreText(initMessage)` with `restoreText("/init")` (and keep the auto-send behavior).
     - Keep the existing “switch project-scope mode to exec” behavior.

5) **Remove the old browser asset**
   - Delete `src/browser/assets/initMessage.txt` and remove its imports once no longer referenced.

6) **Docs**
   - Update docs to reflect that `/init` is now just the `init` skill (and can be overridden by users/projects via `~/.mux/skills/init/SKILL.md` / `.mux/skills/init/SKILL.md`).

7) **Validation checklist**
   - Typing `/init` and hitting send triggers the init skill (no “empty message” backend error; no “add a message” toast).
   - Project page “Initialize” banner still runs init automatically.
   - `/init` appears once in suggestions (as a skill, not a hardcoded command).
   - Other skills still work both with and without trailing messages.

**Net LoC estimate (product code only): ~+20–60**

Keep “prefill editable template” UX, but fetch the template body from `agentSkills.get("init")` instead of a browser asset.
Tradeoff: still requires `/init`-specific behavior (or introducing a generalized “insert skill into input” feature).

<details>
<summary>Follow-up: reduce other “prompt template” slash commands</summary>

Once skills can be invoked with no trailing message, we can eliminate other *macro-style* slash commands by applying the same pattern:

- Move the instruction text into `src/node/builtinSkills/<name>.md`.
- Remove the hardcoded command definition + `ChatInput` branch.
- Let `/<name>` resolve via `agentSkills.list`.

Keep hardcoded slash commands only for **UI/backend actions** (clear history, model/provider settings, MCP management, etc.).

</details>

</details>

---
_Generated with `mux` • Model: `openai:gpt-5.2` • Thinking: `xhigh` • Cost: $30.06_

Change-Id: Iaf4c066db3fc75bf52993552b2d0d6ee9655bb28

Author: ThomasK33

docs/agents/agent-skills.mdx

@@ -16,12 +16,13 @@ This keeps the system prompt small while still making skills discoverable.
 
 ## Where skills live
 
-mux discovers skills from two roots:
+mux discovers skills from three roots:
 
 - **Project-local**: `<projectRoot>/.mux/skills/<skill-name>/SKILL.md`
 - **Global**: `~/.mux/skills/<skill-name>/SKILL.md`
+- **Built-in**: shipped with mux
 
-If a skill exists in both locations, **project-local overrides global**.
+If a skill exists in multiple locations, the precedence order is: **project-local > global > built-in**.
 
 <Info>
   mux reads skills using the active workspace runtime. For SSH workspaces, skills are read from the
@@ -82,7 +83,8 @@ mux injects an `<agent-skills>` block into the system prompt listing the availab
 
 You can apply a skill in two ways:
 
-- **Explicit (slash command)**: type `/{skill-name} ...` in the chat input. mux will send your message normally, but inject the skill content into the system context for that send.
+- **Explicit (slash command)**: type `/{skill-name}` (optionally followed by a message: `/{skill-name} ...`) in the chat input. mux will send your message normally (or a small default message if you omit one), and inject the skill content into the system context for that send.
+  - Example: `/init` runs the built-in `init` skill to bootstrap `AGENTS.md`. You can override it with `~/.mux/skills/init/SKILL.md` (or `.mux/skills/init/SKILL.md` for a single project).
   - Type `/` to see skills in the suggestions list.
 - **Agent-initiated (tool call)**: the agent can load skills on-demand.
 
@@ -107,7 +109,7 @@ agent_skill_read_file({ name: "my-skill", filePath: "references/template.md" });
 
 ## Current limitations
 
-- Slash command invocation supports only a single skill as the first token (for example `/{skill-name} ...`).
+- Slash command invocation supports only a single skill as the first token (for example `/{skill-name}` or `/{skill-name} ...`).
 - Skill bodies may be truncated when injected to avoid accidental mega-prompts.
 - `allowed-tools` is not enforced by mux (it is tolerated in frontmatter, but ignored).
 

src/browser/components/ChatInput/index.tsx

@@ -107,7 +107,6 @@ import {
 } from "./draftImagesStorage";
 import { RecordingOverlay } from "./RecordingOverlay";
 import { ReviewBlockFromData } from "../shared/ReviewBlock";
-import initMessage from "@/browser/assets/initMessage.txt?raw";
 
 // localStorage quotas are environment-dependent and relatively small.
 // Be conservative here so we can warn the user before writes start failing.
@@ -1395,16 +1394,9 @@ const ChatInputInner: React.FC<ChatInputProps> = (props) => {
       let creationMessageTextForSend = messageText;
       let creationOptionsOverride: Partial<SendMessageOptions> | undefined;
 
-      // Handle /init command in creation variant - populate input with init message
       if (messageText.startsWith("/")) {
         const parsed = parseCommand(messageText);
 
-        if (parsed?.type === "init") {
-          setInput(initMessage);
-          focusMessageInput();
-          return;
-        }
-
         if (isUnknownSlashCommand(parsed)) {
           const command = parsed.command;
           const maybeSkill = agentSkillDescriptors.find((skill) => skill.name === command);
@@ -1414,14 +1406,7 @@ const ChatInputInner: React.FC<ChatInputProps> = (props) => {
             const hasSeparator = afterPrefix.length === 0 || /^\s/.test(afterPrefix);
 
             if (hasSeparator) {
-              const userText = afterPrefix.trimStart();
-              if (!userText) {
-                pushToast({
-                  type: "error",
-                  message: `Please add a message after ${prefix}`,
-                });
-                return;
-              }
+              const userText = afterPrefix.trimStart() || `Run the "${maybeSkill.name}" skill.`;
 
               if (!api) {
                 pushToast({ type: "error", message: "Not connected to server" });
@@ -1489,14 +1474,7 @@ const ChatInputInner: React.FC<ChatInputProps> = (props) => {
           const hasSeparator = afterPrefix.length === 0 || /^\s/.test(afterPrefix);
 
           if (hasSeparator) {
-            const userText = afterPrefix.trimStart();
-            if (!userText) {
-              pushToast({
-                type: "error",
-                message: `Please add a message after ${prefix}`,
-              });
-              return;
-            }
+            const userText = afterPrefix.trimStart() || `Run the "${maybeSkill.name}" skill.`;
 
             skillInvocation = { descriptor: maybeSkill, userText };
             parsed = null;
@@ -1569,13 +1547,6 @@ const ChatInputInner: React.FC<ChatInputProps> = (props) => {
           return;
         }
 
-        // Handle /init command - populate input with init message
-        if (parsed.type === "init") {
-          setInput(initMessage);
-          focusMessageInput();
-          return;
-        }
-
         // Handle other non-API commands (help, invalid args, etc)
         const commandToast = createCommandToast(parsed);
         if (commandToast) {

src/browser/components/ProjectPage.tsx

@@ -16,7 +16,6 @@ import { ConfigureProvidersPrompt } from "./ConfigureProvidersPrompt";
 import { useProvidersConfig } from "@/browser/hooks/useProvidersConfig";
 import type { ProvidersConfigMap } from "@/common/orpc/types";
 import { AgentsInitBanner } from "./AgentsInitBanner";
-import initMessage from "@/browser/assets/initMessage.txt?raw";
 import { usePersistedState, updatePersistedState } from "@/browser/hooks/usePersistedState";
 import {
   getAgentIdKey,
@@ -201,16 +200,16 @@ export const ProjectPage: React.FC<ProjectPageProps> = ({
     // Switch project-scope mode to exec.
     updatePersistedState(getAgentIdKey(getProjectScopeId(projectPath)), "exec");
 
-    // Prefill the AGENTS bootstrap prompt and start the creation chat.
+    // Run the /init skill and start the creation chat.
     if (chatInputRef.current) {
-      chatInputRef.current.restoreText(initMessage);
+      chatInputRef.current.restoreText("/init");
       requestAnimationFrame(() => {
         void chatInputRef.current?.send();
       });
     } else {
       pendingAgentsInitSendRef.current = true;
       const pendingScopeId = getPendingScopeId(projectPath);
-      updatePersistedState(getInputKey(pendingScopeId), initMessage);
+      updatePersistedState(getInputKey(pendingScopeId), "/init");
     }
 
     setShowAgentsInitNudge(false);
@@ -222,7 +221,7 @@ export const ProjectPage: React.FC<ProjectPageProps> = ({
     if (pendingAgentsInitSendRef.current) {
       pendingAgentsInitSendRef.current = false;
       didAutoFocusRef.current = true;
-      api.restoreText(initMessage);
+      api.restoreText("/init");
       requestAnimationFrame(() => {
         void api.send();
       });

src/browser/utils/slashCommands/parser.test.ts

@@ -228,11 +228,15 @@ describe("plan commands", () => {
 });
 
 describe("init command", () => {
-  it("should parse /init", () => {
-    expectParse("/init", { type: "init" });
+  it("should parse /init as unknown-command (handled as a skill invocation)", () => {
+    expectParse("/init", {
+      type: "unknown-command",
+      command: "init",
+      subcommand: undefined,
+    });
   });
 
-  it("should reject /init with arguments", () => {
+  it("should parse /init with arguments as unknown-command", () => {
     expectParse("/init extra", {
       type: "unknown-command",
       command: "init",

src/browser/utils/slashCommands/registry.ts

@@ -447,23 +447,6 @@ const vimCommandDefinition: SlashCommandDefinition = {
   },
 };
 
-const initCommandDefinition: SlashCommandDefinition = {
-  key: "init",
-  description: "Bootstrap an AGENTS.md file in a new or existing project",
-  appendSpace: false,
-  handler: ({ cleanRemainingTokens }): ParsedCommand => {
-    if (cleanRemainingTokens.length > 0) {
-      return {
-        type: "unknown-command",
-        command: "init",
-        subcommand: cleanRemainingTokens[0],
-      };
-    }
-
-    return { type: "init" };
-  },
-};
-
 const planOpenCommandDefinition: SlashCommandDefinition = {
   key: "open",
   description: "Open plan in external editor",
@@ -715,7 +698,6 @@ export const SLASH_COMMAND_DEFINITIONS: readonly SlashCommandDefinition[] = [
   vimCommandDefinition,
   mcpCommandDefinition,
   idleCommandDefinition,
-  initCommandDefinition,
   debugLlmRequestCommandDefinition,
 ];
 

src/browser/utils/slashCommands/types.ts

@@ -38,7 +38,6 @@ export type ParsedCommand =
   | { type: "plan-show" }
   | { type: "plan-open" }
   | { type: "debug-llm-request" }
-  | { type: "init" }
   | { type: "unknown-command"; command: string; subcommand?: string }
   | { type: "idle-compaction"; hours: number | null }
   | null;

src/browser/assets/initMessage.txt src/node/builtinSkills/init.mdsrc/browser/assets/initMessage.txt renamed to src/node/builtinSkills/init.md

@@ -1,61 +1,71 @@
+---
+name: init
+description: Bootstrap an AGENTS.md file in a new or existing project
+---
+
 <system>
 Use your tools to create or improve an AGENTS.md file in the root of the workspace which will serve as a contribution guide for AI agents.
 If an AGENTS.md file already exists, focus on additive improvement (preserve intent and useful information; refine, extend, and reorganize as needed) rather than replacing it wholesale.
 Inspect the workspace layout, code, documentation and git history to ensure correctness and accuracy.
 
 Ensure the following preamble exists at the top of the file before any other sections. Do not include the surrounding code fence backticks; only include the text.
+
 ```md
 You are an experienced, pragmatic software engineering AI agent. Do not over-engineer a solution when a simple one is possible. Keep edits minimal. If you want an exception to ANY rule, you MUST stop and get permission first.
 ```
 
 Recommended sections:
+
 - Project Overview (mandatory)
-    - Basic details about the project (e.g., high-level overview and goals).
-    - Technology choices (e.g., languages, databases, frameworks, libraries, build tools).
+  - Basic details about the project (e.g., high-level overview and goals).
+  - Technology choices (e.g., languages, databases, frameworks, libraries, build tools).
 - Reference (mandatory)
-    - List important code files.
-    - List important directories and basic code structure tips.
-    - Project architecture.
+  - List important code files.
+  - List important directories and basic code structure tips.
+  - Project architecture.
 - Essential commands (mandatory)
-    - build
-    - format
-    - lint
-    - test
-    - clean
-    - development server
-    - other *important* scripts (use `find -type f -name '*.sh'` or similar)
+  - build
+  - format
+  - lint
+  - test
+  - clean
+  - development server
+  - other _important_ scripts (use `find -type f -name '*.sh'` or similar)
 - Patterns (optional)
-    - List any important or uncommon patterns (compared to other similar codebases), with examples (e.g., how to authorize an HTTP request).
-    - List any important workflows and their steps (e.g., how to make a database migration).
-    - Testing patterns.
+  - List any important or uncommon patterns (compared to other similar codebases), with examples (e.g., how to authorize an HTTP request).
+  - List any important workflows and their steps (e.g., how to make a database migration).
+  - Testing patterns.
 - Anti-patterns (optional)
-    - Search git history and comments to find recurring mistakes or forbidden patterns.
-    - List each pattern and its reason.
+  - Search git history and comments to find recurring mistakes or forbidden patterns.
+  - List each pattern and its reason.
 - Code style (optional)
-    - Style guide to follow (with link).
+  - Style guide to follow (with link).
 - Commit and Pull Request Guidelines (mandatory)
-    - Required steps for validating changes before committing.
-    - Commit message conventions (read `git log`, or use `type: message` by default).
-    - Pull request description requirements.
+  - Required steps for validating changes before committing.
+  - Commit message conventions (read `git log`, or use `type: message` by default).
+  - Pull request description requirements.
 
 You can add other sections if they are necessary.
 If the information required for mandatory sections isn't available due to the workspace being empty or sparse, add TODO text in its place.
 Optional sections should be scrapped if the information is too thin.
 
 Some investigation tips:
- - Read existing lint configs, tsconfig, and CI workflows to find any style or layout rules.
- - Search for "TODO", "HACK", "FIXME", "don't", "never", "always" in comments.
- - Examine test files for patterns.
- - Read PR templates and issue templates if they exist.
- - Check for existing CONTRIBUTING.md, CODE_OF_CONDUCT.md, or similar documentation files.
+
+- Read existing lint configs, tsconfig, and CI workflows to find any style or layout rules.
+- Search for "TODO", "HACK", "FIXME", "don't", "never", "always" in comments.
+- Examine test files for patterns.
+- Read PR templates and issue templates if they exist.
+- Check for existing CONTRIBUTING.md, CODE_OF_CONDUCT.md, or similar documentation files.
 
 Some writing tips:
+
 - Each "do X" should have a corresponding "don't Y" where applicable.
 - Commands should be easily copy-pastable and tested.
 - Terms or phrases specific to this project should be explained on first use.
 - Anything that is against the norm should be explicitly highlighted and called out.
 
 Above all things:
+
 - The document must be clear and concise. Simple projects should need less than 400 words, but larger and more mature codebases will likely need 700+. Prioritize completeness over brevity.
 - Don't include useless fluff.
 - The document must be in Markdown format and use headings for structure.
@@ -64,14 +74,16 @@ Above all things:
 - Maintain a professional, instructional tone.
 
 If the workspace is empty or sparse, ask the user for more information. Avoid hallucinating important decisions. You can provide suggestions to the user for language/technology/tool choices, but always respect the user's decision.
+
 - Project description and goals.
 - Language(s).
 - Technologies (database?), frameworks, libraries.
 - Tools.
 - Any other questions as you deem necessary.
 
 For empty or sparse workspaces ONLY, when finished writing/updating AGENTS.md, ask the user if they would like you to do the following:
+
 - initialize git IF it's not already set up (e.g., `git init`, `git remote add`, etc.)
 - write a concise README.md file
 - generate the bare minimum project scaffolding (e.g., initializing the package manager, writing a minimal build tool config)
-</system>
+  </system>