botholomew 0.9.7 → 0.9.8

package/README.md

@@ -38,7 +38,8 @@ through MCP servers wired up via [MCPX](https://github.com/evantahler/mcpx).
   Slack, GitHub) or connect through an MCP gateway like
   [Arcade.dev](https://www.arcade.dev/) to reach hundreds of
   authenticated services without managing each server yourself.
-  Reusable workflows are defined as markdown "skills" (slash commands).
+  Reusable workflows are defined as markdown "skills" (slash commands)
+  that the chat agent can also create, edit, and search at runtime.
 - **Safe by default.** The agent has no shell and no direct filesystem
   access. Out of the box, everything it can touch lives in `.botholomew/`;
   every external capability is a MCP server you explicitly add.
@@ -47,7 +48,8 @@ through MCP servers wired up via [MCPX](https://github.com/evantahler/mcpx).
   back into the queue automatically.
 - **Self-modifying.** The agent maintains its own `beliefs.md` and
   `goals.md` — it learns, updates its priors, and revises its goals as it
-  works.
+  works. It can also author its own slash-command skills mid-conversation,
+  turning prompts you keep retyping into durable project assets.
 
 ---
 
@@ -209,7 +211,8 @@ Topics worth understanding in detail:
 - **[Persistent context](docs/persistent-context.md)** — `soul.md`,
   `beliefs.md`, `goals.md`, frontmatter flags, and agent self-modification.
 - **[Skills (slash commands)](docs/skills.md)** — reusable prompt templates
-  with positional arguments and tab completion.
+  with positional arguments and tab completion; the chat agent can also
+  create, edit, and search them at runtime.
 - **[MCPX integration](docs/mcpx.md)** — configuring external servers and
   how MCP tools are merged into the agent's toolset.
 - **[Configuration](docs/configuration.md)** — every key in `config.json`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "botholomew",
-  "version": "0.9.7",
+  "version": "0.9.8",
   "description": "An autonomous AI agent for knowledge work — works your task queue while you sleep.",
   "type": "module",
   "bin": {

package/src/chat/agent.ts

@@ -46,12 +46,18 @@ const CHAT_TOOL_NAMES = new Set([
   "list_schedules",
   "update_beliefs",
   "update_goals",
+  "capabilities_refresh",
   "mcp_list_tools",
   "mcp_search",
   "mcp_info",
   "mcp_exec",
   "read_large_result",
   "spawn_worker",
+  "skill_list",
+  "skill_read",
+  "skill_write",
+  "skill_edit",
+  "skill_search",
 ]);
 
 export function getChatTools() {
@@ -108,6 +114,7 @@ You do NOT execute long-running work directly — enqueue tasks for a background
 Use the available tools to look up tasks, threads, schedules, and context when the user asks about them. Context items live under a drive (disk / url / agent / google-docs / github / …); use \`context_list_drives\` to discover which drives have content, then \`context_tree\`, \`context_info\`, \`context_search\`, or \`context_refresh\` as needed.
 When multiple tool calls are independent of each other (i.e., one does not depend on the result of another), call them all in a single response. They will be executed in parallel, which is faster than calling them one at a time.
 You can update the agent's beliefs and goals files when the user asks you to.
+You can author and refine slash-command skills (reusable prompt templates stored in \`.botholomew/skills/\`) via \`skill_list\`, \`skill_search\`, \`skill_read\`, \`skill_write\`, and \`skill_edit\`. New or edited skills are usable as \`/<name>\` on the user's next message.
 Format your responses using Markdown. Use headings, bold, italic, lists, and code blocks to make your responses clear and well-structured.
 `;
 

package/src/chat/session.ts

@@ -104,6 +104,10 @@ export async function sendMessage(
   userMessage: string,
   callbacks: ChatTurnCallbacks,
 ): Promise<void> {
+  // Hot-reload skills so any skill the agent created/edited last turn (or any
+  // out-of-band edit) is visible to slash-command dispatch this turn.
+  session.skills = await loadSkills(session.projectDir);
+
   // Log and append user message
   await withDb(session.dbPath, (conn) =>
     logInteraction(conn, session.threadId, {

package/src/skills/writer.ts

@@ -0,0 +1,63 @@
+import matter from "gray-matter";
+import { BUILTIN_SLASH_COMMANDS } from "./commands.ts";
+import type { SkillArgDef } from "./parser.ts";
+
+export const RESERVED_SKILL_NAMES = new Set(
+  BUILTIN_SLASH_COMMANDS.map((c) => c.name),
+);
+
+const MAX_NAME_LENGTH = 64;
+
+export type ValidateNameResult =
+  | { ok: true; normalized: string }
+  | { ok: false; reason: "empty" | "invalid" | "reserved" | "too_long" };
+
+export function validateSkillName(raw: string): ValidateNameResult {
+  if (typeof raw !== "string" || raw.trim() === "") {
+    return { ok: false, reason: "empty" };
+  }
+
+  const normalized = raw
+    .toLowerCase()
+    .replace(/[^a-z0-9-]/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-+|-+$/g, "");
+
+  if (normalized === "") return { ok: false, reason: "invalid" };
+  if (normalized.length > MAX_NAME_LENGTH)
+    return { ok: false, reason: "too_long" };
+  if (RESERVED_SKILL_NAMES.has(normalized))
+    return { ok: false, reason: "reserved" };
+
+  return { ok: true, normalized };
+}
+
+export interface SkillFileInput {
+  name: string;
+  description: string;
+  arguments: SkillArgDef[];
+  body: string;
+}
+
+export function buildSkillFileContent(input: SkillFileInput): string {
+  const data: Record<string, unknown> = {
+    name: input.name,
+    description: input.description,
+  };
+
+  if (input.arguments.length > 0) {
+    data.arguments = input.arguments.map((a) => {
+      const out: Record<string, unknown> = {
+        name: a.name,
+        description: a.description,
+        required: a.required,
+      };
+      if (a.default !== undefined) out.default = a.default;
+      return out;
+    });
+  } else {
+    data.arguments = [];
+  }
+
+  return matter.stringify(input.body, data);
+}

package/src/tools/registry.ts

@@ -32,9 +32,16 @@ import { listSchedulesTool } from "./schedule/list.ts";
 // Search tools
 import { searchGrepTool } from "./search/grep.ts";
 import { searchSemanticTool } from "./search/semantic.ts";
+// Skill tools
+import { skillEditTool } from "./skill/edit.ts";
+import { skillListTool } from "./skill/list.ts";
+import { skillReadTool } from "./skill/read.ts";
+import { skillSearchTool } from "./skill/search.ts";
+import { skillWriteTool } from "./skill/write.ts";
 // Task tools
 import { completeTaskTool } from "./task/complete.ts";
 import { createTaskTool } from "./task/create.ts";
+import { deleteTaskTool } from "./task/delete.ts";
 import { failTaskTool } from "./task/fail.ts";
 import { listTasksTool } from "./task/list.ts";
 import { updateTaskTool } from "./task/update.ts";
@@ -54,6 +61,7 @@ export function registerAllTools(): void {
   registerTool(waitTaskTool);
   registerTool(createTaskTool);
   registerTool(updateTaskTool);
+  registerTool(deleteTaskTool);
   registerTool(listTasksTool);
   registerTool(viewTaskTool);
 
@@ -88,6 +96,13 @@ export function registerAllTools(): void {
   registerTool(searchGrepTool);
   registerTool(searchSemanticTool);
 
+  // Skill
+  registerTool(skillListTool);
+  registerTool(skillReadTool);
+  registerTool(skillWriteTool);
+  registerTool(skillEditTool);
+  registerTool(skillSearchTool);
+
   // Thread
   registerTool(listThreadsTool);
   registerTool(viewThreadTool);

package/src/tools/skill/edit.ts

@@ -0,0 +1,114 @@
+import { join } from "node:path";
+import { z } from "zod";
+import { getSkillsDir } from "../../constants.ts";
+import { parseSkillFile } from "../../skills/parser.ts";
+import type { ToolDefinition } from "../tool.ts";
+
+const PatchSchema = z.object({
+  start_line: z.number().describe("1-based inclusive start line"),
+  end_line: z
+    .number()
+    .describe("1-based inclusive end line (0 to insert without replacing)"),
+  content: z
+    .string()
+    .describe("Replacement text (empty string to delete lines)"),
+});
+
+const inputSchema = z.object({
+  name: z.string().describe("Skill name (case-insensitive)"),
+  patches: z.array(PatchSchema).describe("Patches to apply"),
+});
+
+const outputSchema = z.object({
+  name: z.string(),
+  path: z.string().nullable(),
+  applied: z.number(),
+  content: z.string(),
+  is_error: z.boolean(),
+  error_type: z.string().optional(),
+  message: z.string().optional(),
+  next_action_hint: z.string().optional(),
+});
+
+function applyPatches(
+  raw: string,
+  patches: Array<{ start_line: number; end_line: number; content: string }>,
+): string {
+  const lines = raw.split("\n");
+  const sorted = [...patches].sort((a, b) => b.start_line - a.start_line);
+
+  for (const patch of sorted) {
+    if (patch.end_line === 0) {
+      const insertLines = patch.content === "" ? [] : patch.content.split("\n");
+      lines.splice(patch.start_line - 1, 0, ...insertLines);
+    } else {
+      const deleteCount = patch.end_line - patch.start_line + 1;
+      const insertLines = patch.content === "" ? [] : patch.content.split("\n");
+      lines.splice(patch.start_line - 1, deleteCount, ...insertLines);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+export const skillEditTool = {
+  name: "skill_edit",
+  description:
+    "[[ bash equivalent command: patch ]] Apply git-style line-range patches to a skill file (user-defined slash command). Operates on the whole file (frontmatter + body). Patches whose result would not parse as a valid skill are rejected without writing. Use skill_read first to inspect current line numbers.",
+  group: "skill",
+  inputSchema,
+  outputSchema,
+  execute: async (input, ctx) => {
+    const normalized = input.name.toLowerCase();
+    const filePath = join(getSkillsDir(ctx.projectDir), `${normalized}.md`);
+
+    const file = Bun.file(filePath);
+    if (!(await file.exists())) {
+      return {
+        name: normalized,
+        path: null,
+        applied: 0,
+        content: "",
+        is_error: true,
+        error_type: "not_found",
+        message: `Skill not found: ${input.name}`,
+        next_action_hint:
+          "Use skill_list to see available skills, or skill_write to create one.",
+      };
+    }
+
+    const original = await file.text();
+    const updated = applyPatches(original, input.patches);
+
+    try {
+      const parsed = parseSkillFile(updated, filePath);
+      if (parsed.name !== normalized) {
+        throw new Error(
+          `frontmatter name '${parsed.name}' no longer matches filename '${normalized}'`,
+        );
+      }
+    } catch (err) {
+      return {
+        name: normalized,
+        path: filePath,
+        applied: 0,
+        content: original,
+        is_error: true,
+        error_type: "invalid_skill",
+        message: `Patched content failed validation: ${err instanceof Error ? err.message : String(err)}`,
+        next_action_hint:
+          "Check that frontmatter YAML stays valid and the file still has a name/description.",
+      };
+    }
+
+    await Bun.write(filePath, updated);
+
+    return {
+      name: normalized,
+      path: filePath,
+      applied: input.patches.length,
+      content: updated,
+      is_error: false,
+    };
+  },
+} satisfies ToolDefinition<typeof inputSchema, typeof outputSchema>;

package/src/tools/skill/list.ts

@@ -0,0 +1,63 @@
+import { basename } from "node:path";
+import { z } from "zod";
+import { loadSkills } from "../../skills/loader.ts";
+import type { ToolDefinition } from "../tool.ts";
+
+const inputSchema = z.object({
+  limit: z
+    .number()
+    .optional()
+    .default(100)
+    .describe("Max number of skills to return (default 100)"),
+  offset: z
+    .number()
+    .optional()
+    .default(0)
+    .describe("Skip the first N skills (default 0)"),
+});
+
+const outputSchema = z.object({
+  skills: z.array(
+    z.object({
+      name: z.string(),
+      description: z.string(),
+      arguments: z.array(z.string()),
+      filename: z.string(),
+      path: z.string(),
+    }),
+  ),
+  total: z.number(),
+  is_error: z.boolean(),
+});
+
+export const skillListTool = {
+  name: "skill_list",
+  description:
+    "[[ bash equivalent command: ls ]] List skills (user-defined slash commands) loaded from .botholomew/skills/. Returns name, description, argument names, and file path for each.",
+  group: "skill",
+  inputSchema,
+  outputSchema,
+  execute: async (input, ctx) => {
+    const skills = await loadSkills(ctx.projectDir);
+    const sorted = [...skills.values()].sort((a, b) =>
+      a.name.localeCompare(b.name),
+    );
+
+    const total = sorted.length;
+    const offset = input.offset ?? 0;
+    const limit = input.limit ?? 100;
+    const page = sorted.slice(offset, offset + limit);
+
+    return {
+      skills: page.map((s) => ({
+        name: s.name,
+        description: s.description,
+        arguments: s.arguments.map((a) => a.name),
+        filename: basename(s.filePath),
+        path: s.filePath,
+      })),
+      total,
+      is_error: false,
+    };
+  },
+} satisfies ToolDefinition<typeof inputSchema, typeof outputSchema>;

package/src/tools/skill/read.ts

@@ -0,0 +1,72 @@
+import { z } from "zod";
+import { loadSkills } from "../../skills/loader.ts";
+import type { ToolDefinition } from "../tool.ts";
+
+const inputSchema = z.object({
+  name: z.string().describe("Skill name (case-insensitive)"),
+});
+
+const ArgSchema = z.object({
+  name: z.string(),
+  description: z.string(),
+  required: z.boolean(),
+  default: z.string().optional(),
+});
+
+const outputSchema = z.object({
+  name: z.string(),
+  path: z.string().nullable(),
+  raw: z.string().nullable(),
+  description: z.string(),
+  arguments: z.array(ArgSchema),
+  body: z.string(),
+  is_error: z.boolean(),
+  error_type: z.string().optional(),
+  message: z.string().optional(),
+  next_action_hint: z.string().optional(),
+});
+
+export const skillReadTool = {
+  name: "skill_read",
+  description:
+    "[[ bash equivalent command: cat ]] Read a skill file (user-defined slash command) by name. Returns the raw file contents plus parsed fields. Returns a not_found error with the list of available names when the skill doesn't exist.",
+  group: "skill",
+  inputSchema,
+  outputSchema,
+  execute: async (input, ctx) => {
+    const skills = await loadSkills(ctx.projectDir);
+    const skill = skills.get(input.name.toLowerCase());
+
+    if (!skill) {
+      const available = [...skills.keys()].sort();
+      const hint =
+        available.length > 0
+          ? `Available: ${available.join(", ")}. Use skill_list to browse.`
+          : "No skills exist yet. Use skill_write to create one.";
+      return {
+        name: input.name,
+        path: null,
+        raw: null,
+        description: "",
+        arguments: [],
+        body: "",
+        is_error: true,
+        error_type: "not_found",
+        message: `Skill not found: ${input.name}`,
+        next_action_hint: hint,
+      };
+    }
+
+    const raw = await Bun.file(skill.filePath).text();
+
+    return {
+      name: skill.name,
+      path: skill.filePath,
+      raw,
+      description: skill.description,
+      arguments: skill.arguments,
+      body: skill.body,
+      is_error: false,
+    };
+  },
+} satisfies ToolDefinition<typeof inputSchema, typeof outputSchema>;

package/src/tools/skill/search.ts

@@ -0,0 +1,165 @@
+import { z } from "zod";
+import { loadSkills } from "../../skills/loader.ts";
+import type { SkillDefinition } from "../../skills/parser.ts";
+import type { ToolDefinition } from "../tool.ts";
+
+const inputSchema = z.object({
+  query: z
+    .string()
+    .describe(
+      "Search query (matched against name, description, body, and arg metadata)",
+    ),
+  top_k: z
+    .number()
+    .optional()
+    .default(10)
+    .describe("Maximum number of results to return (default 10)"),
+});
+
+const outputSchema = z.object({
+  results: z.array(
+    z.object({
+      name: z.string(),
+      description: z.string(),
+      score: z.number(),
+      match_fields: z.array(z.string()),
+      snippet: z.string(),
+    }),
+  ),
+  is_error: z.boolean(),
+  hint: z.string().optional(),
+});
+
+const SNIPPET_RADIUS = 60;
+
+function countOccurrences(haystack: string, needle: string): number {
+  if (needle === "") return 0;
+  let count = 0;
+  let from = 0;
+  while (true) {
+    const idx = haystack.indexOf(needle, from);
+    if (idx === -1) break;
+    count++;
+    from = idx + needle.length;
+  }
+  return count;
+}
+
+function buildSnippet(body: string, term: string): string {
+  const lower = body.toLowerCase();
+  const idx = lower.indexOf(term);
+  if (idx === -1) return body.slice(0, SNIPPET_RADIUS * 2);
+
+  const start = Math.max(0, idx - SNIPPET_RADIUS);
+  const end = Math.min(body.length, idx + term.length + SNIPPET_RADIUS);
+  const prefix = start > 0 ? "…" : "";
+  const suffix = end < body.length ? "…" : "";
+  return prefix + body.slice(start, end) + suffix;
+}
+
+interface ScoreEntry {
+  skill: SkillDefinition;
+  score: number;
+  matchFields: Set<string>;
+  firstBodyTerm: string | null;
+}
+
+function scoreSkill(skill: SkillDefinition, terms: string[]): ScoreEntry {
+  const name = skill.name.toLowerCase();
+  const desc = skill.description.toLowerCase();
+  const body = skill.body.toLowerCase();
+  const matchFields = new Set<string>();
+  let score = 0;
+  let firstBodyTerm: string | null = null;
+
+  for (const term of terms) {
+    if (term === "") continue;
+    if (name.includes(term)) {
+      score += 10;
+      matchFields.add("name");
+    }
+    if (desc.includes(term)) {
+      score += 5;
+      matchFields.add("description");
+    }
+    for (const arg of skill.arguments) {
+      if (arg.name.toLowerCase().includes(term)) {
+        score += 3;
+        matchFields.add("argument_name");
+      }
+      if (arg.description.toLowerCase().includes(term)) {
+        score += 2;
+        matchFields.add("argument_description");
+      }
+    }
+    const bodyHits = Math.min(countOccurrences(body, term), 5);
+    if (bodyHits > 0) {
+      score += bodyHits;
+      matchFields.add("body");
+      if (firstBodyTerm === null) firstBodyTerm = term;
+    }
+  }
+
+  return { skill, score, matchFields, firstBodyTerm };
+}
+
+export const skillSearchTool = {
+  name: "skill_search",
+  description:
+    "Keyword search over skills (user-defined slash commands). Matches against name, description, body, and argument metadata. Returns top-K ranked matches. Use skill_read after finding a match.",
+  group: "skill",
+  inputSchema,
+  outputSchema,
+  execute: async (input, ctx) => {
+    const skills = await loadSkills(ctx.projectDir);
+    const terms = input.query
+      .toLowerCase()
+      .split(/\s+/)
+      .filter((t) => t.length > 0);
+
+    if (skills.size === 0) {
+      return {
+        results: [],
+        is_error: false,
+        hint: "No skills exist yet. Use skill_write to create one.",
+      };
+    }
+
+    if (terms.length === 0) {
+      return {
+        results: [],
+        is_error: false,
+        hint: "Empty query. Provide one or more keywords, or use skill_list to browse.",
+      };
+    }
+
+    const scored = [...skills.values()].map((s) => scoreSkill(s, terms));
+    const matched = scored
+      .filter((e) => e.score > 0)
+      .sort((a, b) => b.score - a.score)
+      .slice(0, input.top_k ?? 10);
+
+    if (matched.length === 0) {
+      return {
+        results: [],
+        is_error: false,
+        hint: "No matches. Try broader terms, or use skill_list to browse.",
+      };
+    }
+
+    const fallbackTerm = terms[0] ?? "";
+    return {
+      results: matched.map((e) => {
+        const snippetTerm = e.firstBodyTerm ?? fallbackTerm;
+        return {
+          name: e.skill.name,
+          description: e.skill.description,
+          score: e.score,
+          match_fields: [...e.matchFields].sort(),
+          snippet: buildSnippet(e.skill.body, snippetTerm),
+        };
+      }),
+      is_error: false,
+    };
+  },
+} satisfies ToolDefinition<typeof inputSchema, typeof outputSchema>;

package/src/tools/skill/write.ts

@@ -0,0 +1,180 @@
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { z } from "zod";
+import { getSkillsDir } from "../../constants.ts";
+import { parseSkillFile } from "../../skills/parser.ts";
+import {
+  buildSkillFileContent,
+  validateSkillName,
+} from "../../skills/writer.ts";
+import type { ToolDefinition } from "../tool.ts";
+
+const ArgInputSchema = z.object({
+  name: z
+    .string()
+    .min(1)
+    .describe("Argument name (referenced as $1, $2, … in the body)"),
+  description: z.string().optional().describe("Argument description"),
+  required: z
+    .boolean()
+    .optional()
+    .default(false)
+    .describe("Whether the argument is required"),
+  default: z
+    .string()
+    .optional()
+    .describe("Default value when the argument is omitted"),
+});
+
+const inputSchema = z.object({
+  name: z
+    .string()
+    .describe(
+      "Skill name (slash-command identifier). Will be normalized to lowercase + [a-z0-9-]. Reserved: help, skills, clear, exit.",
+    ),
+  description: z
+    .string()
+    .describe("Short description shown in /skills and /help"),
+  body: z
+    .string()
+    .describe(
+      "Prompt-template body (markdown). Use $ARGUMENTS or $1..$9 for argument substitution.",
+    ),
+  arguments: z
+    .array(ArgInputSchema)
+    .optional()
+    .describe("Argument definitions (positional)"),
+  on_conflict: z
+    .enum(["error", "overwrite"])
+    .optional()
+    .default("error")
+    .describe(
+      "What to do if a skill with this name already exists. Defaults to 'error'.",
+    ),
+});
+
+const outputSchema = z.object({
+  name: z.string().nullable(),
+  path: z.string().nullable(),
+  ref: z.string().nullable(),
+  created: z.boolean(),
+  is_error: z.boolean(),
+  error_type: z.string().optional(),
+  message: z.string().optional(),
+  next_action_hint: z.string().optional(),
+});
+
+export const skillWriteTool = {
+  name: "skill_write",
+  description:
+    "[[ bash equivalent command: tee ]] Create or overwrite a skill file (user-defined slash command) at .botholomew/skills/<name>.md. Fails with path_conflict when the file exists unless on_conflict='overwrite'. Reserved names (help, skills, clear, exit) are rejected. The generated file is parsed to validate before being written.",
+  group: "skill",
+  inputSchema,
+  outputSchema,
+  execute: async (input, ctx) => {
+    const nameCheck = validateSkillName(input.name);
+    if (!nameCheck.ok) {
+      const errorType =
+        nameCheck.reason === "reserved" ? "reserved_name" : "invalid_name";
+      const message =
+        nameCheck.reason === "reserved"
+          ? `'${input.name}' is reserved by a built-in slash command (help, skills, clear, exit).`
+          : nameCheck.reason === "too_long"
+            ? `Skill name too long (max 64 chars after normalization).`
+            : `'${input.name}' is not a valid skill name. After normalization (lowercase, [a-z0-9-], trimmed hyphens) it is empty.`;
+      return {
+        name: null,
+        path: null,
+        ref: null,
+        created: false,
+        is_error: true,
+        error_type: errorType,
+        message,
+        next_action_hint:
+          "Pick a different name made of lowercase letters, digits, and hyphens.",
+      };
+    }
+
+    const normalized = nameCheck.normalized;
+    const body = input.body.trim();
+    if (body === "") {
+      return {
+        name: normalized,
+        path: null,
+        ref: null,
+        created: false,
+        is_error: true,
+        error_type: "empty_body",
+        message: "Skill body is empty.",
+        next_action_hint:
+          "Provide a non-empty prompt template using $ARGUMENTS or $1..$9.",
+      };
+    }
+
+    const args = (input.arguments ?? []).map((a) => ({
+      name: a.name,
+      description: a.description ?? "",
+      required: a.required ?? false,
+      default: a.default,
+    }));
+
+    const skillsDir = getSkillsDir(ctx.projectDir);
+    const filePath = join(skillsDir, `${normalized}.md`);
+
+    const raw = buildSkillFileContent({
+      name: normalized,
+      description: input.description,
+      arguments: args,
+      body,
+    });
+
+    try {
+      const parsed = parseSkillFile(raw, filePath);
+      if (parsed.name !== normalized) {
+        throw new Error(
+          `frontmatter name '${parsed.name}' does not match expected '${normalized}'`,
+        );
+      }
+    } catch (err) {
+      return {
+        name: normalized,
+        path: null,
+        ref: null,
+        created: false,
+        is_error: true,
+        error_type: "invalid_skill",
+        message: `Generated skill content failed validation: ${err instanceof Error ? err.message : String(err)}`,
+        next_action_hint:
+          "Check description and body for unusual characters that break YAML.",
+      };
+    }
+
+    const onConflict = input.on_conflict ?? "error";
+    const existed = await Bun.file(filePath).exists();
+
+    if (existed && onConflict === "error") {
+      return {
+        name: normalized,
+        path: filePath,
+        ref: `skill:${normalized}`,
+        created: false,
+        is_error: true,
+        error_type: "path_conflict",
+        message: `Skill '${normalized}' already exists at ${filePath}.`,
+        next_action_hint:
+          "Retry with on_conflict='overwrite' to replace, or use skill_edit for a partial change.",
+      };
+    }
+
+    await mkdir(skillsDir, { recursive: true });
+    await Bun.write(filePath, raw);
+
+    return {
+      name: normalized,
+      path: filePath,
+      ref: `skill:${normalized}`,
+      created: !existed,
+      is_error: false,
+    };
+  },
+} satisfies ToolDefinition<typeof inputSchema, typeof outputSchema>;

package/src/tools/task/delete.ts

@@ -0,0 +1,54 @@
+import { z } from "zod";
+import { deleteTask, getTask } from "../../db/tasks.ts";
+import { logger } from "../../utils/logger.ts";
+import type { ToolDefinition } from "../tool.ts";
+
+const inputSchema = z.object({
+  id: z.string().describe("ID of the task to delete"),
+});
+
+const outputSchema = z.object({
+  deleted_id: z.string().nullable(),
+  message: z.string(),
+  is_error: z.boolean(),
+});
+
+export const deleteTaskTool = {
+  name: "delete_task",
+  description:
+    "[[ bash equivalent command: rm ]] Delete a task permanently. Refuses in_progress tasks; wait for the worker to finish or run `botholomew task reset <id>` first.",
+  group: "task",
+  inputSchema,
+  outputSchema,
+  execute: async (input, ctx) => {
+    const existing = await getTask(ctx.conn, input.id);
+    if (!existing) {
+      return {
+        deleted_id: null,
+        message: `Task ${input.id} not found`,
+        is_error: true,
+      };
+    }
+    if (existing.status === "in_progress") {
+      return {
+        deleted_id: null,
+        message: `Cannot delete task ${input.id}: it is currently in_progress (claimed by ${existing.claimed_by ?? "unknown"}). Wait for the worker to finish, or reset it first via \`botholomew task reset ${input.id}\`.`,
+        is_error: true,
+      };
+    }
+    const ok = await deleteTask(ctx.conn, input.id);
+    if (!ok) {
+      return {
+        deleted_id: null,
+        message: `Failed to delete task ${input.id}`,
+        is_error: true,
+      };
+    }
+    logger.info(`Deleted task: ${existing.name} (${existing.id})`);
+    return {
+      deleted_id: existing.id,
+      message: `Deleted task "${existing.name}" (${existing.id})`,
+      is_error: false,
+    };
+  },
+} satisfies ToolDefinition<typeof inputSchema, typeof outputSchema>;