@xmem-ai/memcode 4.0.2

package/dist/skills/bundled/updateConfig.js

@@ -0,0 +1,475 @@
+import { toJSONSchema } from "zod/v4";
+import { SettingsSchema } from "../../utils/settings/types.js";
+import { jsonStringify } from "../../utils/slowOperations.js";
+import { registerBundledSkill } from "../bundledSkills.js";
+function generateSettingsSchema() {
+  const jsonSchema = toJSONSchema(SettingsSchema(), {
+    io: "input",
+    unrepresentable: "any"
+  });
+  return jsonStringify(jsonSchema, null, 2);
+}
+const SETTINGS_EXAMPLES_DOCS = `## Settings File Locations
+
+Choose the appropriate file based on scope:
+
+| File | Scope | Git | Use For |
+|------|-------|-----|---------|
+| \`~/.memcode/settings.json\` | Global | N/A | Personal preferences for all projects |
+| \`.memcode/settings.json\` | Project | Commit | Team-wide hooks, permissions, plugins |
+| \`.memcode/settings.local.json\` | Project | Gitignore | Personal overrides for this project |
+
+Settings load in order: user -> project -> local (later overrides earlier).
+
+## Settings Schema Reference
+
+### Permissions
+\`\`\`json
+{
+  "permissions": {
+    "allow": ["Bash(npm:*)", "Edit(.memcode)", "Read"],
+    "deny": ["Bash(rm -rf:*)"],
+    "ask": ["Write(/etc/*)"],
+    "defaultMode": "default" | "plan" | "acceptEdits" | "dontAsk",
+    "additionalDirectories": ["/extra/dir"]
+  }
+}
+\`\`\`
+
+**Permission Rule Syntax:**
+- Exact match: \`"Bash(npm run test)"\`
+- Prefix wildcard: \`"Bash(git:*)"\` - matches \`git status\`, \`git commit\`, etc.
+- Tool only: \`"Read"\` - allows all Read operations
+
+### Environment Variables
+\`\`\`json
+{
+  "env": {
+    "DEBUG": "true",
+    "MY_API_KEY": "value"
+  }
+}
+\`\`\`
+
+### Model & Agent
+\`\`\`json
+{
+  "model": "sonnet",  // or "opus", "haiku", full model ID
+  "agent": "agent-name",
+  "alwaysThinkingEnabled": true
+}
+\`\`\`
+
+### Attribution (Commits & PRs)
+\`\`\`json
+{
+  "attribution": {
+    "commit": "Custom commit trailer text",
+    "pr": "Custom PR description text"
+  }
+}
+\`\`\`
+Set \`commit\` or \`pr\` to empty string \`""\` to hide that attribution.
+
+### MCP Server Management
+\`\`\`json
+{
+  "enableAllProjectMcpServers": true,
+  "enabledMcpjsonServers": ["server1", "server2"],
+  "disabledMcpjsonServers": ["blocked-server"]
+}
+\`\`\`
+
+### Plugins
+\`\`\`json
+{
+  "enabledPlugins": {
+    "formatter@memcode-tools": true
+  }
+}
+\`\`\`
+Plugin syntax: \`plugin-name@source\` where source is \`memcode-marketplace\`, \`memcode-plugins-official\`, or \`builtin\`.
+
+### Other Settings
+- \`language\`: Preferred response language (e.g., "japanese")
+- \`cleanupPeriodDays\`: Days to keep transcripts (default: 30; 0 disables persistence entirely)
+- \`respectGitignore\`: Whether to respect .gitignore (default: true)
+- \`spinnerTipsEnabled\`: Show tips in spinner
+- \`spinnerVerbs\`: Customize spinner verbs (\`{ "mode": "append" | "replace", "verbs": [...] }\`)
+- \`spinnerTipsOverride\`: Override spinner tips (\`{ "excludeDefault": true, "tips": ["Custom tip"] }\`)
+- \`syntaxHighlightingDisabled\`: Disable diff highlighting
+`;
+const HOOKS_DOCS = `## Hooks Configuration
+
+Hooks run commands at specific points in memCode's lifecycle.
+
+### Hook Structure
+\`\`\`json
+{
+  "hooks": {
+    "EVENT_NAME": [
+      {
+        "matcher": "ToolName|OtherTool",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "your-command-here",
+            "timeout": 60,
+            "statusMessage": "Running..."
+          }
+        ]
+      }
+    ]
+  }
+}
+\`\`\`
+
+### Hook Events
+
+| Event | Matcher | Purpose |
+|-------|---------|---------|
+| PermissionRequest | Tool name | Run before permission prompt |
+| PreToolUse | Tool name | Run before tool, can block |
+| PostToolUse | Tool name | Run after successful tool |
+| PostToolUseFailure | Tool name | Run after tool fails |
+| Notification | Notification type | Run on notifications |
+| Stop | - | Run when memCode stops (including clear, resume, compact) |
+| PreCompact | "manual"/"auto" | Before compaction |
+| PostCompact | "manual"/"auto" | After compaction (receives summary) |
+| UserPromptSubmit | - | When user submits |
+| SessionStart | - | When session starts |
+
+**Common tool matchers:** \`Bash\`, \`Write\`, \`Edit\`, \`Read\`, \`Glob\`, \`Grep\`
+
+### Hook Types
+
+**1. Command Hook** - Runs a shell command:
+\`\`\`json
+{ "type": "command", "command": "prettier --write $FILE", "timeout": 30 }
+\`\`\`
+
+**2. Prompt Hook** - Evaluates a condition with LLM:
+\`\`\`json
+{ "type": "prompt", "prompt": "Is this safe? $ARGUMENTS" }
+\`\`\`
+Only available for tool events: PreToolUse, PostToolUse, PermissionRequest.
+
+**3. Agent Hook** - Runs an agent with tools:
+\`\`\`json
+{ "type": "agent", "prompt": "Verify tests pass: $ARGUMENTS" }
+\`\`\`
+Only available for tool events: PreToolUse, PostToolUse, PermissionRequest.
+
+### Hook Input (stdin JSON)
+\`\`\`json
+{
+  "session_id": "abc123",
+  "tool_name": "Write",
+  "tool_input": { "file_path": "/path/to/file.txt", "content": "..." },
+  "tool_response": { "success": true }  // PostToolUse only
+}
+\`\`\`
+
+### Hook JSON Output
+
+Hooks can return JSON to control behavior:
+
+\`\`\`json
+{
+  "systemMessage": "Warning shown to user in UI",
+  "continue": false,
+  "stopReason": "Message shown when blocking",
+  "suppressOutput": false,
+  "decision": "block",
+  "reason": "Explanation for decision",
+  "hookSpecificOutput": {
+    "hookEventName": "PostToolUse",
+    "additionalContext": "Context injected back to model"
+  }
+}
+\`\`\`
+
+**Fields:**
+- \`systemMessage\` - Display a message to the user (all hooks)
+- \`continue\` - Set to \`false\` to block/stop (default: true)
+- \`stopReason\` - Message shown when \`continue\` is false
+- \`suppressOutput\` - Hide stdout from transcript (default: false)
+- \`decision\` - "block" for PostToolUse/Stop/UserPromptSubmit hooks (deprecated for PreToolUse, use hookSpecificOutput.permissionDecision instead)
+- \`reason\` - Explanation for decision
+- \`hookSpecificOutput\` - Event-specific output (must include \`hookEventName\`):
+  - \`additionalContext\` - Text injected into model context
+  - \`permissionDecision\` - "allow", "deny", or "ask" (PreToolUse only)
+  - \`permissionDecisionReason\` - Reason for the permission decision (PreToolUse only)
+  - \`updatedInput\` - Modified tool input (PreToolUse only)
+
+### Common Patterns
+
+**Auto-format after writes:**
+\`\`\`json
+{
+  "hooks": {
+    "PostToolUse": [{
+      "matcher": "Write|Edit",
+      "hooks": [{
+        "type": "command",
+        "command": "jq -r '.tool_response.filePath // .tool_input.file_path' | { read -r f; prettier --write \\"$f\\"; } 2>/dev/null || true"
+      }]
+    }]
+  }
+}
+\`\`\`
+
+**Log all bash commands:**
+\`\`\`json
+{
+  "hooks": {
+    "PreToolUse": [{
+      "matcher": "Bash",
+      "hooks": [{
+        "type": "command",
+        "command": "jq -r '.tool_input.command' >> ~/.memcode/bash-log.txt"
+      }]
+    }]
+  }
+}
+\`\`\`
+
+**Stop hook that displays message to user:**
+
+Command must output JSON with \`systemMessage\` field:
+\`\`\`bash
+# Example command that outputs: {"systemMessage": "Session complete!"}
+echo '{"systemMessage": "Session complete!"}'
+\`\`\`
+
+**Run tests after code changes:**
+\`\`\`json
+{
+  "hooks": {
+    "PostToolUse": [{
+      "matcher": "Write|Edit",
+      "hooks": [{
+        "type": "command",
+        "command": "jq -r '.tool_input.file_path // .tool_response.filePath' | grep -E '\\\\.(ts|js)$' && npm test || true"
+      }]
+    }]
+  }
+}
+\`\`\`
+`;
+const HOOK_VERIFICATION_FLOW = `## Constructing a Hook (with verification)
+
+Given an event, matcher, target file, and desired behavior, follow this flow. Each step catches a different failure class - a hook that silently does nothing is worse than no hook.
+
+1. **Dedup check.** Read the target file. If a hook already exists on the same event+matcher, show the existing command and ask: keep it, replace it, or add alongside.
+
+2. **Construct the command for THIS project - don't assume.** The hook receives JSON on stdin. Build a command that:
+   - Extracts any needed payload safely - use \`jq -r\` into a quoted variable or \`{ read -r f; ... "$f"; }\`, NOT unquoted \`| xargs\` (splits on spaces)
+   - Invokes the underlying tool the way this project runs it (npx/bunx/yarn/pnpm? Makefile target? globally-installed?)
+   - Skips inputs the tool doesn't handle (formatters often have \`--ignore-unknown\`; if not, guard by extension)
+   - Stays RAW for now - no \`|| true\`, no stderr suppression. You'll wrap it after the pipe-test passes.
+
+3. **Pipe-test the raw command.** Synthesize the stdin payload the hook will receive and pipe it directly:
+   - \`Pre|PostToolUse\` on \`Write|Edit\`: \`echo '{"tool_name":"Edit","tool_input":{"file_path":"<a real file from this repo>"}}' | <cmd>\`
+   - \`Pre|PostToolUse\` on \`Bash\`: \`echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | <cmd>\`
+   - \`Stop\`/\`UserPromptSubmit\`/\`SessionStart\`: most commands don't read stdin, so \`echo '{}' | <cmd>\` suffices
+
+   Check exit code AND side effect (file actually formatted, test actually ran). If it fails you get a real error - fix (wrong package manager? tool not installed? jq path wrong?) and retest. Once it works, wrap with \`2>/dev/null || true\` (unless the user wants a blocking check).
+
+4. **Write the JSON.** Merge into the target file (schema shape in the "Hook Structure" section above). If this creates \`.memcode/settings.local.json\` for the first time, add it to .gitignore - the Write tool doesn't auto-gitignore it.
+
+5. **Validate syntax + schema in one shot:**
+
+   \`jq -e '.hooks.<event>[] | select(.matcher == "<matcher>") | .hooks[] | select(.type == "command") | .command' <target-file>\`
+
+   Exit 0 + prints your command = correct. Exit 4 = matcher doesn't match. Exit 5 = malformed JSON or wrong nesting. A broken settings.json silently disables ALL settings from that file - fix any pre-existing malformation too.
+
+6. **Prove the hook fires** - only for \`Pre|PostToolUse\` on a matcher you can trigger in-turn (\`Write|Edit\` via Edit, \`Bash\` via Bash). \`Stop\`/\`UserPromptSubmit\`/\`SessionStart\` fire outside this turn - skip to step 7.
+
+   For a **formatter** on \`PostToolUse\`/\`Write|Edit\`: introduce a detectable violation via Edit (two consecutive blank lines, bad indentation, missing semicolon - something this formatter corrects; NOT trailing whitespace, Edit strips that before writing), re-read, confirm the hook **fixed** it. For **anything else**: temporarily prefix the command in settings.json with \`echo "$(date) hook fired" >> /tmp/memcode-hook-check.txt; \`, trigger the matching tool (Edit for \`Write|Edit\`, a harmless \`true\` for \`Bash\`), read the sentinel file.
+
+   **Always clean up** - revert the violation, strip the sentinel prefix - whether the proof passed or failed.
+
+   **If proof fails but pipe-test passed and \`jq -e\` passed**: the settings watcher isn't watching \`.memcode/\` - it only watches directories that had a settings file when this session started. The hook is written correctly. Tell the user to open \`/hooks\` once (reloads config) or restart - you can't do this yourself; \`/hooks\` is a user UI menu and opening it ends this turn.
+
+7. **Handoff.** Tell the user the hook is live (or needs \`/hooks\`/restart per the watcher caveat). Point them at \`/hooks\` to review, edit, or disable it later. The UI only shows "Ran N hooks" if a hook errors or is slow - silent success is invisible by design.
+`;
+const UPDATE_CONFIG_PROMPT = `# Update Config Skill
+
+Modify memCode configuration by updating settings.json files.
+
+## When Hooks Are Required (Not Memory)
+
+If the user wants something to happen automatically in response to an EVENT, they need a **hook** configured in settings.json. Memory/preferences cannot trigger automated actions.
+
+**These require hooks:**
+- "Before compacting, ask me what to preserve" -> PreCompact hook
+- "After writing files, run prettier" -> PostToolUse hook with Write|Edit matcher
+- "When I run bash commands, log them" -> PreToolUse hook with Bash matcher
+- "Always run tests after code changes" -> PostToolUse hook
+
+**Hook events:** PreToolUse, PostToolUse, PreCompact, PostCompact, Stop, Notification, SessionStart
+
+## CRITICAL: Read Before Write
+
+**Always read the existing settings file before making changes.** Merge new settings with existing ones - never replace the entire file.
+
+## CRITICAL: Use AskUserQuestion for Ambiguity
+
+When the user's request is ambiguous, use AskUserQuestion to clarify:
+- Which settings file to modify (user/project/local)
+- Whether to add to existing arrays or replace them
+- Specific values when multiple options exist
+
+## Decision: Config Tool vs Direct Edit
+
+**Use the Config tool** for these simple settings:
+- \`theme\`, \`editorMode\`, \`verbose\`, \`model\`
+- \`language\`, \`alwaysThinkingEnabled\`
+- \`permissions.defaultMode\`
+
+**Edit settings.json directly** for:
+- Hooks (PreToolUse, PostToolUse, etc.)
+- Complex permission rules (allow/deny arrays)
+- Environment variables
+- MCP server configuration
+- Plugin configuration
+
+## Workflow
+
+1. **Clarify intent** - Ask if the request is ambiguous
+2. **Read existing file** - Use Read tool on the target settings file
+3. **Merge carefully** - Preserve existing settings, especially arrays
+4. **Edit file** - Use Edit tool (if file doesn't exist, ask user to create it first)
+5. **Confirm** - Tell user what was changed
+
+## Merging Arrays (Important!)
+
+When adding to permission arrays or hook arrays, **merge with existing**, don't replace:
+
+**WRONG** (replaces existing permissions):
+\`\`\`json
+{ "permissions": { "allow": ["Bash(npm:*)"] } }
+\`\`\`
+
+**RIGHT** (preserves existing + adds new):
+\`\`\`json
+{
+  "permissions": {
+    "allow": [
+      "Bash(git:*)",      // existing
+      "Edit(.memcode)",    // existing
+      "Bash(npm:*)"       // new
+    ]
+  }
+}
+\`\`\`
+
+${SETTINGS_EXAMPLES_DOCS}
+
+${HOOKS_DOCS}
+
+${HOOK_VERIFICATION_FLOW}
+
+## Example Workflows
+
+### Adding a Hook
+
+User: "Format my code after memCode writes it"
+
+1. **Clarify**: Which formatter? (prettier, gofmt, etc.)
+2. **Read**: \`.memcode/settings.json\` (or create if missing)
+3. **Merge**: Add to existing hooks, don't replace
+4. **Result**:
+\`\`\`json
+{
+  "hooks": {
+    "PostToolUse": [{
+      "matcher": "Write|Edit",
+      "hooks": [{
+        "type": "command",
+        "command": "jq -r '.tool_response.filePath // .tool_input.file_path' | { read -r f; prettier --write \\"$f\\"; } 2>/dev/null || true"
+      }]
+    }]
+  }
+}
+\`\`\`
+
+### Adding Permissions
+
+User: "Allow npm commands without prompting"
+
+1. **Read**: Existing permissions
+2. **Merge**: Add \`Bash(npm:*)\` to allow array
+3. **Result**: Combined with existing allows
+
+### Environment Variables
+
+User: "Set DEBUG=true"
+
+1. **Decide**: User settings (global) or project settings?
+2. **Read**: Target file
+3. **Merge**: Add to env object
+\`\`\`json
+{ "env": { "DEBUG": "true" } }
+\`\`\`
+
+## Common Mistakes to Avoid
+
+1. **Replacing instead of merging** - Always preserve existing settings
+2. **Wrong file** - Ask user if scope is unclear
+3. **Invalid JSON** - Validate syntax after changes
+4. **Forgetting to read first** - Always read before write
+
+## Troubleshooting Hooks
+
+If a hook isn't running:
+1. **Check the settings file** - Read ~/.memcode/settings.json or .memcode/settings.json
+2. **Verify JSON syntax** - Invalid JSON silently fails
+3. **Check the matcher** - Does it match the tool name? (e.g., "Bash", "Write", "Edit")
+4. **Check hook type** - Is it "command", "prompt", or "agent"?
+5. **Test the command** - Run the hook command manually to see if it works
+6. **Use --debug** - Run \`memcode --debug\` to see hook execution logs
+`;
+function registerUpdateConfigSkill() {
+  registerBundledSkill({
+    name: "update-config",
+    description: 'Use this skill to configure the memCode harness via settings.json. Automated behaviors ("from now on when X", "each time X", "whenever X", "before/after X") require hooks configured in settings.json - the memCode runtime executes these from settings, so memory/preferences cannot fulfill them. Also use for: permissions ("allow X", "add permission", "move permission to"), env vars ("set X=Y"), hook troubleshooting, or any changes to settings.json/settings.local.json files. Examples: "allow npm commands", "add bq permission to global settings", "move permission to user settings", "set DEBUG=true", "when memcode stops show X". For simple settings like theme/model, use Config tool.',
+    allowedTools: ["Read", "Edit", "Write", "Grep", "Bash"],
+    userInvocable: true,
+    async getPromptForCommand(args) {
+      if (args.startsWith("[hooks-only]")) {
+        const req = args.slice("[hooks-only]".length).trim();
+        let prompt2 = HOOKS_DOCS + "\n\n" + HOOK_VERIFICATION_FLOW;
+        if (req) {
+          prompt2 += `
+
+## Task
+
+${req}`;
+        }
+        return [{ type: "text", text: prompt2 }];
+      }
+      const jsonSchema = generateSettingsSchema();
+      let prompt = UPDATE_CONFIG_PROMPT;
+      prompt += `
+
+## Full Settings JSON Schema
+
+\`\`\`json
+${jsonSchema}
+\`\`\``;
+      if (args) {
+        prompt += `
+
+## User Request
+
+${args}`;
+      }
+      return [{ type: "text", text: prompt }];
+    }
+  });
+}
+export {
+  registerUpdateConfigSkill
+};

package/dist/skills/bundled/verify/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: verify
+description: Verify a code change by choosing and running the right local checks, inspecting results, and reporting concrete evidence. Use when the user asks to verify, test, smoke-test, check a fix, confirm behavior, or validate a CLI/server/frontend change.
+---
+
+# Verify
+
+Verify the current change with evidence, not assumptions.
+
+## Workflow
+
+1. Identify what changed from the user's request, recent edits, and `git diff` when available.
+2. Pick the narrowest check that exercises the changed behavior.
+3. Prefer existing project commands and documented workflows over inventing new checks.
+4. For CLI changes, run the relevant command or help path and inspect stdout/stderr.
+5. For server/API changes, start or use the local service only when needed, then hit the affected route with a focused request.
+6. For frontend changes, use available browser automation or a lightweight local request to confirm the affected UI path.
+7. If a check fails, inspect the failure and fix the issue when it is in scope.
+8. Report exactly what was checked, what passed or failed, and any risk left unverified.
+
+## Rules
+
+- Do not claim verification from reading code alone unless the user explicitly only asked for static review.
+- Do not run broad or expensive suites when a focused check proves the behavior.
+- Do not leave long-running dev servers or background checks running.
+- If a required check cannot be run, state the blocker and the next best evidence gathered.

package/dist/skills/bundled/verify/examples/cli.md

@@ -0,0 +1,9 @@
+# CLI Verification Example
+
+Use this pattern for command-line changes:
+
+1. Inspect package scripts, Makefile targets, or nearby documentation for the intended command.
+2. Run the smallest command that covers the changed path, such as `memcode --help`, a subcommand help page, or a focused fixture command.
+3. Capture exit code, stdout, and stderr.
+4. If behavior changed, compare the output against the expected user-facing result.
+5. Report the exact command and outcome.

package/dist/skills/bundled/verify/examples/server.md

@@ -0,0 +1,9 @@
+# Server Verification Example
+
+Use this pattern for server or API changes:
+
+1. Identify the affected route or handler.
+2. Start the local server only if no existing process is already serving the app.
+3. Send a focused request with `curl`, PowerShell `Invoke-WebRequest`, or the project�s existing client/test helper.
+4. Check status code, response body, and relevant logs.
+5. Stop any server you started before finishing.

package/dist/skills/bundled/verify.js

@@ -0,0 +1,25 @@
+import { parseFrontmatter } from "../../utils/frontmatterParser.js";
+import { registerBundledSkill } from "../bundledSkills.js";
+import { SKILL_FILES, SKILL_MD } from "./verifyContent.js";
+const { frontmatter, content: SKILL_BODY } = parseFrontmatter(SKILL_MD);
+const DESCRIPTION = typeof frontmatter.description === "string" ? frontmatter.description : "Verify a code change does what it should by running the app.";
+function registerVerifySkill() {
+  registerBundledSkill({
+    name: "verify",
+    description: DESCRIPTION,
+    userInvocable: true,
+    files: SKILL_FILES,
+    async getPromptForCommand(args) {
+      const parts = [SKILL_BODY.trimStart()];
+      if (args) {
+        parts.push(`## User Request
+
+${args}`);
+      }
+      return [{ type: "text", text: parts.join("\n\n") }];
+    }
+  });
+}
+export {
+  registerVerifySkill
+};

package/dist/skills/bundled/verifyContent.js

@@ -0,0 +1,12 @@
+import cliMd from "./verify/examples/cli.md";
+import serverMd from "./verify/examples/server.md";
+import skillMd from "./verify/SKILL.md";
+const SKILL_MD = skillMd;
+const SKILL_FILES = {
+  "examples/cli.md": cliMd,
+  "examples/server.md": serverMd
+};
+export {
+  SKILL_FILES,
+  SKILL_MD
+};

package/dist/skills/bundledSkills.js

@@ -0,0 +1,124 @@
+import { constants as fsConstants } from "fs";
+import { mkdir, open } from "fs/promises";
+import { dirname, isAbsolute, join, normalize, sep as pathSep } from "path";
+import { logForDebugging } from "../utils/debug.js";
+import { getBundledSkillsRoot } from "../utils/permissions/filesystem.js";
+const bundledSkills = [];
+function registerBundledSkill(definition) {
+  const { files } = definition;
+  let skillRoot;
+  let getPromptForCommand = definition.getPromptForCommand;
+  if (files && Object.keys(files).length > 0) {
+    skillRoot = getBundledSkillExtractDir(definition.name);
+    let extractionPromise;
+    const inner = definition.getPromptForCommand;
+    getPromptForCommand = async (args, ctx) => {
+      extractionPromise ??= extractBundledSkillFiles(definition.name, files);
+      const extractedDir = await extractionPromise;
+      const blocks = await inner(args, ctx);
+      if (extractedDir === null) return blocks;
+      return prependBaseDir(blocks, extractedDir);
+    };
+  }
+  const command = {
+    type: "prompt",
+    name: definition.name,
+    description: definition.description,
+    aliases: definition.aliases,
+    subcommands: definition.subcommands,
+    hasUserSpecifiedDescription: true,
+    allowedTools: definition.allowedTools ?? [],
+    argumentHint: definition.argumentHint,
+    whenToUse: definition.whenToUse,
+    model: definition.model,
+    disableModelInvocation: definition.disableModelInvocation ?? false,
+    directOutput: definition.directOutput,
+    userInvocable: definition.userInvocable ?? true,
+    contentLength: 0,
+    // Not applicable for bundled skills
+    source: "bundled",
+    loadedFrom: "bundled",
+    hooks: definition.hooks,
+    skillRoot,
+    context: definition.context,
+    agent: definition.agent,
+    isEnabled: definition.isEnabled,
+    isHidden: !(definition.userInvocable ?? true),
+    progressMessage: "running",
+    getPromptForCommand
+  };
+  bundledSkills.push(command);
+}
+function getBundledSkills() {
+  return [...bundledSkills];
+}
+function clearBundledSkills() {
+  bundledSkills.length = 0;
+}
+function getBundledSkillExtractDir(skillName) {
+  return join(getBundledSkillsRoot(), skillName);
+}
+async function extractBundledSkillFiles(skillName, files) {
+  const dir = getBundledSkillExtractDir(skillName);
+  try {
+    await writeSkillFiles(dir, files);
+    return dir;
+  } catch (e) {
+    logForDebugging(
+      `Failed to extract bundled skill '${skillName}' to ${dir}: ${e instanceof Error ? e.message : String(e)}`
+    );
+    return null;
+  }
+}
+async function writeSkillFiles(dir, files) {
+  const byParent = /* @__PURE__ */ new Map();
+  for (const [relPath, content] of Object.entries(files)) {
+    const target = resolveSkillFilePath(dir, relPath);
+    const parent = dirname(target);
+    const entry = [target, content];
+    const group = byParent.get(parent);
+    if (group) group.push(entry);
+    else byParent.set(parent, [entry]);
+  }
+  await Promise.all(
+    [...byParent].map(async ([parent, entries]) => {
+      await mkdir(parent, { recursive: true, mode: 448 });
+      await Promise.all(entries.map(([p, c]) => safeWriteFile(p, c)));
+    })
+  );
+}
+const O_NOFOLLOW = fsConstants.O_NOFOLLOW ?? 0;
+const SAFE_WRITE_FLAGS = process.platform === "win32" ? "wx" : fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_EXCL | O_NOFOLLOW;
+async function safeWriteFile(p, content) {
+  const fh = await open(p, SAFE_WRITE_FLAGS, 384);
+  try {
+    await fh.writeFile(content, "utf8");
+  } finally {
+    await fh.close();
+  }
+}
+function resolveSkillFilePath(baseDir, relPath) {
+  const normalized = normalize(relPath);
+  if (isAbsolute(normalized) || normalized.split(pathSep).includes("..") || normalized.split("/").includes("..")) {
+    throw new Error(`bundled skill file path escapes skill dir: ${relPath}`);
+  }
+  return join(baseDir, normalized);
+}
+function prependBaseDir(blocks, baseDir) {
+  const prefix = `Base directory for this skill: ${baseDir}
+
+`;
+  if (blocks.length > 0 && blocks[0].type === "text") {
+    return [
+      { type: "text", text: prefix + blocks[0].text },
+      ...blocks.slice(1)
+    ];
+  }
+  return [{ type: "text", text: prefix }, ...blocks];
+}
+export {
+  clearBundledSkills,
+  getBundledSkillExtractDir,
+  getBundledSkills,
+  registerBundledSkill
+};