@netnodeag/kraftwerk 0.6.0 → 0.8.0

package/README.md

@@ -153,6 +153,7 @@ model: sonnet          # optional; harness default when omitted
 effort: medium         # optional: low | medium | high | xhigh | max
 workflows: [tagline, website-check]
 knowledge: [customer-support]   # OKF bundles the member consults & maintains
+skills: [report-html]           # optional allowlist; omit = all skills, [] = none
 ```
 
 Sessions with a member are ordinary chats scoped `{ kind: "team", member }`,
@@ -169,6 +170,29 @@ options and the thinking budget via `MAX_THINKING_TOKENS`; codex gets a
 `--model`/`--thinking` flags. Members are created and edited in the UI (or by
 editing the files — the definition is read fresh for each new session).
 
+### Skills in chat
+
+Chats — general ones and team sessions — can use skills: Claude-style
+instruction packages, one folder per skill with a `SKILL.md` (YAML
+frontmatter `name` + `description`, then the instructions). Two roots are
+discovered, with a project skill shadowing a same-named user skill:
+
+```
+<project>/.claude/skills/<name>/SKILL.md   # git-tracked, per project
+~/.claude/skills/<name>/SKILL.md           # personal, per user
+```
+
+Every chat lists its visible skills as context ("## Your skills"), so the
+agent reaches for one when the request matches. Typing `/` in the composer
+opens an autocomplete over them; sending `/<name> <args>` expands the
+skill's SKILL.md into the prompt — which is why this works identically on
+claude, codex, and pi. Natively on top of that, claude discovers
+`.claude/skills` itself (a team member's `skills:` allowlist narrows that
+via ACP session options) and pi loads each visible skill folder via
+`--skill`. Team members take an optional `skills:` list in `agent.yml`:
+omitted means all discovered skills, an empty list means none, otherwise
+it's the allowlist. `GET /api/skills` returns what's discovered.
+
 ### Routines — scheduled prompts
 
 A member can have routines: cron-scheduled prompts, like standing orders for
@@ -405,8 +429,9 @@ Living examples:
 [`../agent-playground/src/workflows/tagline/`](../agent-playground/src/workflows/tagline/)
 and [`../agent-playground/src/workflows/pitch/`](../agent-playground/src/workflows/pitch/);
 `check`/`if` in [`../agent-playground/src/workflows/helpdesk-check/`](../agent-playground/src/workflows/helpdesk-check/).
-v1 is deliberately linear — approval loops, AGENTS.md-style context files
-and skills stay on the roadmap; anything non-linear is a TS workflow.
+v1 is deliberately linear — approval loops and AGENTS.md-style context files
+stay on the roadmap (skills exist in chat, not in workflow runs); anything
+non-linear is a TS workflow.
 
 ### MCP servers alongside the workflow
 

package/dist/cli/doctor.js

@@ -1,5 +1,5 @@
 import { spawnSync } from "node:child_process";
-import { readFile } from "node:fs/promises";
+import { readFile, stat } from "node:fs/promises";
 import path from "node:path";
 import chalk from "chalk";
 import { resolveProject } from "../config.js";
@@ -67,9 +67,46 @@ export async function runDoctor(cwd) {
     else {
         report("ok", `kraftwerk ${pkg.version}`, latest === pkg.version ? "latest on npm" : `ahead of npm (latest: ${latest})`);
     }
-    // Project.
-    const project = await resolveProject(cwd);
+    // Project. resolveProject throws on a malformed kraftwerk.yml (bad YAML,
+    // non-mapping, unknown keys, non-string values) — surface that as a check.
+    let project;
+    try {
+        project = await resolveProject(cwd);
+    }
+    catch (err) {
+        report("fail", "kraftwerk.yml invalid", err.message.split("\n")[0]);
+        console.log(chalk.red("\n1 problem(s) found."));
+        process.exit(1);
+    }
     report("info", `Project root: ${project.root}`, project.configPath ? path.basename(project.configPath) : "no kraftwerk.yml (fallback: workflows folder or .git)");
+    // Project config: well-formed (guaranteed by the parse above) and the
+    // configured paths actually exist.
+    if (!project.configPath) {
+        report("warn", "no kraftwerk.yml", "recommended as project root marker — `kraftwerk init` scaffolds one");
+    }
+    else {
+        const cfg = project.config;
+        const keys = Object.keys(cfg);
+        report("ok", `${path.basename(project.configPath)} well-formed`, keys.length ? keys.map((k) => `${k}: ${cfg[k]}`).join(", ") : "empty — defaults apply");
+        if (!cfg.name)
+            report("info", "name not set in kraftwerk.yml", "inspector header falls back to the folder name");
+        const isDir = async (p) => (await stat(p).catch(() => null))?.isDirectory() ?? false;
+        for (const key of ["workflows", "knowledge", "agents", "output"]) {
+            const value = cfg[key];
+            if (!value)
+                continue;
+            const abs = path.resolve(project.root, value);
+            if (await isDir(abs))
+                continue;
+            if (key === "output") {
+                report("info", `output: ${value}`, "directory not created yet — appears on first run");
+            }
+            else {
+                report("fail", `${key}: ${value}`, "configured directory does not exist");
+                failures++;
+            }
+        }
+    }
     const found = project.workflowsRoot ? await discoverWorkflows(cwd) : [];
     if (!project.workflowsRoot) {
         report("warn", "no workflows root", "expected src/workflows/ or workflows/ — `kraftwerk init` scaffolds one");

package/dist/cli/init.js

@@ -2,16 +2,23 @@ import { appendFile, mkdir, readFile, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
 import chalk from "chalk";
 import { SCHEMA_URL } from "../config.js";
+import { initBundle, writeConcept } from "../okf.js";
 /**
  * `kraftwerk init` — make any repository a kraftwerk consumer in one
- * command: kraftwerk.yml (root marker + config), workflows/ with a runnable
- * example, and an output/ ignore entry. Everything is idempotent: existing
- * files are left untouched and reported.
+ * command: kraftwerk.yml (root marker + config), a kraftwerk-data/ tree with
+ * a runnable example workflow, a starter team agent ("max"), a demo
+ * knowledge bundle, and an output ignore entry. Everything is idempotent:
+ * existing files are left untouched and reported.
  */
-const CONFIG_TEMPLATE = `# kraftwerk project config — also marks the project root for the CLI.
+const DATA_DIR = "kraftwerk-data";
+const configTemplate = (name) => `# kraftwerk project config — also marks the project root for the CLI.
 # All fields optional. Docs: https://github.com/NETNODEAG/kraftwerk
-workflows: workflows   # where workflows live
-output: output         # where run artifacts land (git-ignored)
+name: ${JSON.stringify(name)}   # display name, shown in the inspector header + browser tab
+icon: "⚡"   # emoji shown as the inspector favicon
+workflows: ${DATA_DIR}/workflows   # where workflows live
+output: ${DATA_DIR}/output         # where run artifacts land (git-ignored)
+knowledge: ${DATA_DIR}/knowledge   # OKF knowledge bundles
+agents: ${DATA_DIR}/agents         # team agent definitions
 `;
 const WORKFLOW_TEMPLATE = `# yaml-language-server: $schema=${SCHEMA_URL}
 name: hello
@@ -38,6 +45,34 @@ const PROMPT_TEMPLATE = `Request: \${{ request }}
 Answer the request and write the answer to answer.md
 (Markdown, with a short heading).
 `;
+const AGENT_YML_TEMPLATE = `name: Max - Workflow Runner
+emoji: 🛠️
+description: Runs and explains this project's workflows
+harness: claude
+model: sonnet
+effort: medium
+workflows:
+  - hello
+knowledge:
+  - demo-customer-support
+`;
+const AGENT_SYSTEM_TEMPLATE = `You are Max, this project's workflow runner. You run and explain the
+project's kraftwerk workflows, and you consult the knowledge bundles you
+have access to before answering questions they cover.
+`;
+const DEMO_BUNDLE = "demo-customer-support";
+const DEMO_CONCEPT = `---
+type: Playbook
+title: Refund handling
+description: How support handles refund requests.
+tags: [ support, refunds ]
+---
+
+# Steps
+
+1. Check the order in the shop backend.
+2. Refunds under CHF 50 are approved directly.
+`;
 export async function runInit(cwd) {
     const exists = async (p) => !!(await stat(p).catch(() => null));
     const created = [];
@@ -52,20 +87,36 @@ export async function runInit(cwd) {
         await writeFile(abs, content);
         created.push(rel);
     };
-    await put("kraftwerk.yml", CONFIG_TEMPLATE);
-    await put("workflows/hello/workflow.yml", WORKFLOW_TEMPLATE);
-    await put("workflows/hello/prompts/assistant.md", PERSONA_TEMPLATE);
-    await put("workflows/hello/prompts/answer.md", PROMPT_TEMPLATE);
-    // .gitignore: append output/ if it's not covered yet.
+    await put("kraftwerk.yml", configTemplate(path.basename(path.resolve(cwd))));
+    await put(`${DATA_DIR}/workflows/hello/workflow.yml`, WORKFLOW_TEMPLATE);
+    await put(`${DATA_DIR}/workflows/hello/prompts/assistant.md`, PERSONA_TEMPLATE);
+    await put(`${DATA_DIR}/workflows/hello/prompts/answer.md`, PROMPT_TEMPLATE);
+    // Team agent "max".
+    await put(`${DATA_DIR}/agents/max/agent.yml`, AGENT_YML_TEMPLATE);
+    await put(`${DATA_DIR}/agents/max/system.md`, AGENT_SYSTEM_TEMPLATE);
+    // Demo knowledge bundle, through the canonical OKF write path so
+    // index.md and log.md come out consistent.
+    const knowledgeRoot = path.join(cwd, DATA_DIR, "knowledge");
+    const bundleRel = `${DATA_DIR}/knowledge/${DEMO_BUNDLE}/`;
+    if (await exists(path.join(knowledgeRoot, DEMO_BUNDLE))) {
+        skipped.push(bundleRel);
+    }
+    else {
+        await initBundle(knowledgeRoot, DEMO_BUNDLE);
+        await writeConcept(knowledgeRoot, DEMO_BUNDLE, "playbooks/refunds", DEMO_CONCEPT, "kraftwerk-init");
+        created.push(bundleRel);
+    }
+    // .gitignore: append the output dir if it's not covered yet.
+    const outputEntry = `${DATA_DIR}/output`;
     const gitignorePath = path.join(cwd, ".gitignore");
     const gitignore = (await readFile(gitignorePath, "utf8").catch(() => null)) ?? null;
     if (gitignore === null) {
-        await writeFile(gitignorePath, "output/\n");
+        await writeFile(gitignorePath, `${outputEntry}/\n`);
         created.push(".gitignore");
     }
-    else if (!gitignore.split("\n").some((l) => l.trim().replace(/\/$/, "") === "output")) {
-        await appendFile(gitignorePath, `${gitignore.endsWith("\n") ? "" : "\n"}output/\n`);
-        created.push(".gitignore (output/ added)");
+    else if (!gitignore.split("\n").some((l) => l.trim().replace(/\/$/, "") === outputEntry)) {
+        await appendFile(gitignorePath, `${gitignore.endsWith("\n") ? "" : "\n"}${outputEntry}/\n`);
+        created.push(`.gitignore (${outputEntry}/ added)`);
     }
     else {
         skipped.push(".gitignore");

package/dist/cli/kraftwerk.js

@@ -17,7 +17,7 @@ import { runUi } from "./ui.js";
 /**
  * kraftwerk — the kraftwerk CLI.
  *
- *   kraftwerk init                    scaffold kraftwerk.yml + workflows/ + example
+ *   kraftwerk init                    scaffold kraftwerk.yml + kraftwerk-data/ (workflow, agent, knowledge)
  *   kraftwerk list                    discover + list workflows (--json, --from)
  *   kraftwerk run [workflow] [text]   run one (prompts interactively if omitted)
  *   kraftwerk runs [show <id>]        inspect past runs from their traces
@@ -129,7 +129,7 @@ program
     .option("--from <source>", "Workflows from a git remote: github:org/repo[@ref] or git URL")
     .option("--sandbox", "Run inside the Docker sandbox container (image: kraftwerk-runner)")
     .option("--ssh", "Forward the SSH agent + known_hosts into the sandbox (only with --sandbox)")
-    .option("--run-id <id>", "Pin the run folder name (output/<id>), e.g. for external triggers")
+    .option("--run-id <id>", "Pin the run folder name (output/runs/<id>), e.g. for external triggers")
     .action(async (name, requestParts, opts) => {
     const machine = !!opts.json;
     const fail = (code, message) => {
@@ -172,8 +172,10 @@ program
     }
     if (opts.sandbox) {
         const { runSandboxed } = await import("../runner/docker.js");
+        const { resolveProject } = await import("../config.js");
         const handle = await runSandboxed({
             projectRoot: baseDir,
+            outputDir: opts.from ? undefined : (await resolveProject(baseDir)).outputDir,
             workflowPath: entry.path,
             workflowName: workflow.name,
             request,
@@ -184,17 +186,14 @@ program
         console.log(chalk.dim(`sandbox ${handle.containerName} → ${handle.runDir}`));
         process.exit(await handle.finished);
     }
-    if (opts.runId) {
-        process.env.KRAFTWERK_RUN_DIR = path.resolve("output", opts.runId);
-    }
-    else if (!process.env.KRAFTWERK_RUN_DIR) {
+    if (opts.runId || !process.env.KRAFTWERK_RUN_DIR) {
         // Root the run dir explicitly: at the project's output dir (honors
         // kraftwerk.yml `output:` and works from subdirs); for remote runs at
         // the caller's cwd — never inside the clone cache.
-        const { runStamp } = await import("../workflow.js");
+        const { newRunId, runDirFor } = await import("../workflow.js");
         const { resolveProject } = await import("../config.js");
         const outBase = opts.from ? path.resolve("output") : (await resolveProject(baseDir)).outputDir;
-        process.env.KRAFTWERK_RUN_DIR = path.join(outBase, `run-${runStamp()}`);
+        process.env.KRAFTWERK_RUN_DIR = runDirFor(outBase, opts.runId ?? newRunId(workflow.name));
     }
     // Machine/quiet mode: workflow narration must not pollute stdout — the
     // engine logs via console.log, so reroute it for the duration of the run.
@@ -225,7 +224,7 @@ program
 });
 program
     .command("init")
-    .description("Scaffold the project: kraftwerk.yml, workflows/ with an example, .gitignore")
+    .description("Scaffold the project: kraftwerk.yml, kraftwerk-data/ (example workflow, agent max, demo knowledge), .gitignore")
     .action(async () => {
     await runInit(process.cwd());
 });
@@ -248,7 +247,7 @@ runs
 runs
     .command("show")
     .description("Show one run in detail: phases, gates, cost")
-    .argument("<runId>", "Folder name under output/, see `kraftwerk runs`")
+    .argument("<runId>", "Folder name under output/runs/, see `kraftwerk runs`")
     .option("--json", "Machine-readable output (all trace events)")
     .action(async (runId, opts) => {
     await showRun(process.cwd(), runId, opts);

package/dist/cli/runs.js

@@ -4,6 +4,7 @@ import chalk from "chalk";
 import Table from "cli-table3";
 import { resolveProject } from "../config.js";
 import { fmtDuration, fmtTokens } from "../stats.js";
+import { runDirFor } from "../workflow.js";
 async function readRun(dir) {
     const tracePath = path.join(dir, "trace.jsonl");
     const raw = await readFile(tracePath, "utf8").catch(() => null);
@@ -37,12 +38,18 @@ async function readRun(dir) {
 }
 async function collectRuns(cwd) {
     const { outputDir } = await resolveProject(cwd);
-    const entries = await readdir(outputDir, { withFileTypes: true }).catch(() => []);
+    // New runs live under <output>/runs/; legacy run-* folders sit at the root.
+    const dirs = [
+        ...(await readdir(path.join(outputDir, "runs"), { withFileTypes: true }).catch(() => []))
+            .filter((e) => e.isDirectory())
+            .map((e) => path.join(outputDir, "runs", e.name)),
+        ...(await readdir(outputDir, { withFileTypes: true }).catch(() => []))
+            .filter((e) => e.isDirectory() && e.name.startsWith("run-"))
+            .map((e) => path.join(outputDir, e.name)),
+    ];
     const runs = [];
-    for (const entry of entries) {
-        if (!entry.isDirectory())
-            continue;
-        const info = await readRun(path.join(outputDir, entry.name));
+    for (const dir of dirs) {
+        const info = await readRun(dir);
         if (info)
             runs.push(info);
     }
@@ -83,7 +90,7 @@ export async function listRuns(cwd, opts = {}) {
 }
 export async function showRun(cwd, id, opts = {}) {
     const { outputDir } = await resolveProject(cwd);
-    const dir = path.join(outputDir, id);
+    const dir = runDirFor(outputDir, id);
     if (!(await stat(dir).catch(() => null))) {
         console.error(chalk.red(`Run "${id}" not found under ${outputDir}.`));
         process.exit(2);

package/dist/cli/ui.js

@@ -42,11 +42,10 @@ function ensureBuilt() {
 }
 export async function runUi(cwd, opts) {
     const staticDir = ensureBuilt();
-    const outputDir = opts.output
-        ? path.resolve(cwd, opts.output)
-        : (await resolveProject(cwd)).outputDir;
+    const project = await resolveProject(cwd);
+    const outputDir = opts.output ? path.resolve(cwd, opts.output) : project.outputDir;
     const port = Number(opts.port ?? "1981");
-    await startInspector({ outputDir, staticDir, port });
+    await startInspector({ outputDir, staticDir, port, projectRoot: project.root });
     console.log(`${chalk.green("✔")} Inspector: ${chalk.cyan(`http://localhost:${port}`)} ` +
         chalk.dim(`(output: ${outputDir})`));
 }

package/dist/config.d.ts

@@ -9,6 +9,8 @@
  *
  * All fields are optional — a valid kraftwerk.yml may be empty:
  *
+ *   name: my-project           # display name (inspector header, "environment")
+ *   icon: "⚡"                  # emoji shown as inspector favicon
  *   workflows: src/workflows   # workflows root, relative to the file
  *   output: output             # run-artifact directory, relative to the file
  *   knowledge: knowledge       # OKF knowledge-bundle root, relative to the file
@@ -18,6 +20,10 @@
 export declare const SCHEMA_URL = "https://raw.githubusercontent.com/NETNODEAG/kraftwerk/main/kraftwerk/schema/workflow.schema.json";
 export declare const CONFIG_FILENAMES: string[];
 export interface ProjectConfig {
+    /** Display name of the project ("environment"), shown in the inspector header. */
+    name?: string;
+    /** Emoji used as the inspector favicon (browser-tab icon). */
+    icon?: string;
     /** Workflows root relative to the project root. */
     workflows?: string;
     /** Run-artifact directory relative to the project root. Default: output */

package/dist/config.js

@@ -12,6 +12,8 @@ import { parse } from "yaml";
  *
  * All fields are optional — a valid kraftwerk.yml may be empty:
  *
+ *   name: my-project           # display name (inspector header, "environment")
+ *   icon: "⚡"                  # emoji shown as inspector favicon
  *   workflows: src/workflows   # workflows root, relative to the file
  *   output: output             # run-artifact directory, relative to the file
  *   knowledge: knowledge       # OKF knowledge-bundle root, relative to the file
@@ -83,10 +85,10 @@ async function loadConfig(configPath) {
     if (raw === null || raw === undefined)
         return {};
     if (typeof raw !== "object" || Array.isArray(raw)) {
-        throw new Error(`${path.basename(configPath)}: expected a mapping (workflows, output, knowledge)`);
+        throw new Error(`${path.basename(configPath)}: expected a mapping (name, icon, workflows, output, knowledge, agents)`);
     }
     const config = raw;
-    const known = ["workflows", "output", "knowledge", "agents"];
+    const known = ["name", "icon", "workflows", "output", "knowledge", "agents"];
     for (const key of Object.keys(config)) {
         if (!known.includes(key)) {
             throw new Error(`${path.basename(configPath)}: unknown key "${key}" (allowed: ${known.join(", ")})`);

package/dist/harnesses/claude.js

@@ -8,7 +8,6 @@ function invokeClaude(inv) {
     ];
     const args = [
         "-p",
-        "--chrome",
         "--output-format", "stream-json",
         "--verbose",
         "--model", inv.model,

package/dist/inspector/chat/acp.js

@@ -118,11 +118,19 @@ export async function startAcpBackend(agent, cwd, hooks, tuning = {}) {
         clientCapabilities: { fs: { readTextFile: false, writeTextFile: false } },
         clientInfo: { name: "kraftwerk-inspector", version: "1.0.0" },
     });
+    // Claude-only session options ride on _meta.claudeCode.options (the
+    // adapter spreads them into the Agent SDK options): model override,
+    // skill allowlist (undefined = all discovered skills), extra work dirs.
+    const claudeOptions = {
+        ...(tuning.model ? { model: tuning.model } : {}),
+        ...(tuning.skills ? { skills: tuning.skills } : {}),
+        ...(tuning.addDirs?.length ? { additionalDirectories: tuning.addDirs } : {}),
+    };
     const session = await conn.newSession({
         cwd,
         mcpServers: [],
-        ...(agent === "claude" && tuning.model
-            ? { _meta: { claudeCode: { options: { model: tuning.model } } } }
+        ...(agent === "claude" && Object.keys(claudeOptions).length
+            ? { _meta: { claudeCode: { options: claudeOptions } } }
             : {}),
     });
     const sessionId = session.sessionId;

package/dist/inspector/chat/backend.d.ts

@@ -25,6 +25,12 @@ export interface BackendHooks {
 export interface BackendTuning {
     model?: string;
     effort?: string;
+    /** claude: restrict native skill discovery to these names (undefined = all). */
+    skills?: string[];
+    /** pi: skill folders to load explicitly via --skill. */
+    skillDirs?: string[];
+    /** claude: extra directories the session may work in (e.g. project root for run chats). */
+    addDirs?: string[];
 }
 export interface ChatBackend {
     /** Send one user message; resolves with the stop reason at turn end. */

package/dist/inspector/chat/pi.js

@@ -11,6 +11,7 @@ export function startPiBackend(cwd, hooks, tuning = {}) {
     const tuningArgs = [
         ...(tuning.model ? ["--model", tuning.model] : []),
         ...(tuning.effort ? ["--thinking", tuning.effort] : []),
+        ...(tuning.skillDirs ?? []).flatMap((dir) => ["--skill", dir]),
     ];
     return {
         prompt(text) {

package/dist/inspector/chat/sessions.d.ts

@@ -19,6 +19,10 @@ export declare function postMessage(id: string, text: string): Promise<{
 export declare function resolvePermission(id: string, requestId: string, optionId: string | null): Promise<{
     error?: string;
 }>;
+/** Delete a chat: kill its backend, drop the live state, remove its folder. */
+export declare function deleteChat(id: string): Promise<{
+    error?: string;
+}>;
 export declare function cancelChat(id: string): Promise<{
     error?: string;
 }>;

package/dist/inspector/chat/sessions.js

@@ -1,12 +1,14 @@
 import { randomUUID } from "node:crypto";
+import { promises as fs } from "node:fs";
 import { getOutputDir, getProjectRoot } from "../context.js";
 import { knowledgeIndex } from "../knowledge.js";
 import { getRun, listRuns, safeRunDir } from "../runs.js";
+import { listSkills, readSkill } from "../skills.js";
 import { listWorkflows } from "../workflows.js";
 import { getMember } from "../team.js";
 import { startAcpBackend } from "./acp.js";
 import { startPiBackend } from "./pi.js";
-import { appendEvent, listChatMetas, newChatId, readEvents, readMeta, writeMeta } from "./store.js";
+import { appendEvent, listChatMetas, newChatId, readEvents, readMeta, safeChatDir, writeMeta, } from "./store.js";
 const states = new Map();
 async function loadState(id) {
     const existing = states.get(id);
@@ -42,6 +44,54 @@ function emit(state, ev) {
         fn(stored);
     return stored;
 }
+/* ---------- skills ---------- */
+/**
+ * Skills visible to a chat: every discovered skill (project + user
+ * .claude/skills), narrowed by the team member's allowlist when the chat
+ * is a team session (absent allowlist = all, empty = none).
+ */
+async function availableSkills(scope) {
+    const all = await listSkills().catch(() => []);
+    if (scope.kind !== "team" || all.length === 0)
+        return all;
+    const member = await getMember(scope.member).catch(() => null);
+    if (!member || member.skills === undefined)
+        return all;
+    const allowed = new Set(member.skills.map((n) => n.toLowerCase()));
+    return all.filter((s) => allowed.has(s.name.toLowerCase()));
+}
+/** "## Your skills" context block (empty when no skills are visible). */
+function skillsBlock(skills) {
+    if (skills.length === 0)
+        return "";
+    const lines = skills
+        .map((s) => `- /${s.name}${s.description ? `: ${s.description}` : ""} — ${s.path}`)
+        .join("\n");
+    return (`## Your skills\nSkills are reusable instruction packages (a SKILL.md per skill). When the ` +
+        `user's request matches one, read its SKILL.md file and follow the instructions in it. The user ` +
+        `can also invoke one explicitly by starting a message with /<skill-name>.\n${lines}`);
+}
+/**
+ * Explicit skill invocation: a message starting with /<skill-name> is
+ * expanded into the skill's SKILL.md instructions (the stored user_message
+ * keeps the original "/name args" text). Unknown names pass through as-is.
+ */
+async function expandSkillInvocation(scope, text) {
+    const m = /^\/([A-Za-z0-9][\w-]*)[ \t]*([\s\S]*)$/.exec(text);
+    if (!m)
+        return text;
+    const skills = await availableSkills(scope);
+    const skill = skills.find((s) => s.name.toLowerCase() === m[1].toLowerCase());
+    if (!skill)
+        return text;
+    const body = await readSkill(skill);
+    if (!body.trim())
+        return text;
+    const args = m[2].trim();
+    return (`The user invoked the skill "${skill.name}" (${skill.path}). Follow the skill's instructions:\n\n` +
+        `<skill name="${skill.name}">\n${body.trim()}\n</skill>\n\n` +
+        `Arguments the user passed to the skill: ${args || "(none)"}`);
+}
 /* ---------- scope context ---------- */
 /** "## Your knowledge" block for a team member's connected OKF bundles. */
 async function teamKnowledgeContext(member) {
@@ -65,7 +115,8 @@ async function teamKnowledgeContext(member) {
         `Never hand-edit index.md or log.md, and never add \`verified\` yourself — verification is the human's ` +
         `click in the UI.\n\n`);
 }
-async function scopeContext(scope, agent) {
+/** Base context per scope; scopeContext() appends the shared skills block. */
+async function baseScopeContext(scope, agent) {
     if (scope.kind === "team") {
         const member = await getMember(scope.member).catch(() => null);
         if (!member) {
@@ -90,7 +141,7 @@ async function scopeContext(scope, agent) {
                         : "") +
                     `\nRun a workflow with:\n` +
                     `  KRAFTWERK_YES=1 npx kraftwerk run <workflow> "<request>"\n` +
-                    `The command blocks until the run finishes; artifacts land in output/run-*/ — tell the user the ` +
+                    `The command blocks until the run finishes; artifacts land in output/runs/*/ — tell the user the ` +
                     `run id and summarize the result. Confirm with the user before starting a long or expensive run ` +
                     `unless they clearly asked for it.\n\n`
                 : "") +
@@ -141,7 +192,7 @@ async function scopeContext(scope, agent) {
             .map((r) => `- ${r.id} — ${r.workflow ?? "?"} [${r.status}] ${r.request ?? ""}`.trim())
             .join("\n");
         return (`You are the assistant inside the kraftwerk inspector, a UI for a workflow-as-code agent framework. ` +
-            `The consumer project root is ${getProjectRoot()}; run outputs live in ${getOutputDir()} (one run-* folder per run, each with a trace.jsonl and working files).\n\n` +
+            `The consumer project root is ${getProjectRoot()}; run outputs live in ${getOutputDir()} (one folder per run under runs/, each with a trace.jsonl and working files).\n\n` +
             `Workflows in this project:\n${wfLines || "(none)"}\n\nRecent runs:\n${runLines || "(none)"}\n\n` +
             `Answer questions about workflows and runs by reading these files. Do not modify run outputs unless asked.`);
     }
@@ -160,16 +211,41 @@ async function scopeContext(scope, agent) {
     }
     return "";
 }
+async function scopeContext(scope, agent) {
+    const [base, skills] = await Promise.all([
+        baseScopeContext(scope, agent),
+        availableSkills(scope),
+    ]);
+    const block = skillsBlock(skills);
+    if (!block)
+        return base;
+    return base ? `${base}\n\n${block}` : block;
+}
 /* ---------- backend lifecycle ---------- */
 /** Team chats carry the member's model/effort; resolved live so edits apply to new backends. */
-async function backendTuning(scope) {
-    if (scope.kind !== "team")
-        return {};
-    const member = await getMember(scope.member).catch(() => null);
-    return {
-        ...(member?.model ? { model: member.model } : {}),
-        ...(member?.effort ? { effort: member.effort } : {}),
-    };
+async function backendTuning(scope, agent) {
+    const tuning = {};
+    if (scope.kind === "team") {
+        const member = await getMember(scope.member).catch(() => null);
+        if (member?.model)
+            tuning.model = member.model;
+        if (member?.effort)
+            tuning.effort = member.effort;
+        // Claude discovers skills natively; a defined allowlist narrows that.
+        if (agent === "claude" && member?.skills)
+            tuning.skills = member.skills;
+    }
+    // Run chats live in the run folder — grant claude the project root so
+    // project-level skills and files stay reachable.
+    if (scope.kind === "run" && agent === "claude")
+        tuning.addDirs = [getProjectRoot()];
+    // pi loads skills only when told: hand it every visible skill folder.
+    if (agent === "pi") {
+        const skills = await availableSkills(scope);
+        if (skills.length > 0)
+            tuning.skillDirs = skills.map((s) => s.dir);
+    }
+    return tuning;
 }
 async function ensureBackend(state) {
     if (state.backend)
@@ -199,7 +275,7 @@ async function ensureBackend(state) {
         },
     };
     const { agent, cwd } = state.meta;
-    const tuning = await backendTuning(state.meta.scope);
+    const tuning = await backendTuning(state.meta.scope, agent);
     state.backend =
         agent === "pi"
             ? startPiBackend(cwd, hooks, tuning)
@@ -263,7 +339,10 @@ export async function postMessage(id, text) {
         try {
             const backend = await ensureBackend(state);
             const context = isFirst ? await scopeContext(state.meta.scope, state.meta.agent) : "";
-            const promptText = context ? `<context>\n${context}\n</context>\n\n${text}` : text;
+            // "/<skill> args" expands to the skill's instructions for the agent;
+            // the thread keeps the short form the user typed.
+            const body = await expandSkillInvocation(state.meta.scope, text);
+            const promptText = context ? `<context>\n${context}\n</context>\n\n${body}` : body;
             const stopReason = await backend.prompt(promptText);
             emit(state, { type: "turn_end", stopReason });
         }
@@ -291,6 +370,18 @@ export async function resolvePermission(id, requestId, optionId) {
     resolve(optionId);
     return {};
 }
+/** Delete a chat: kill its backend, drop the live state, remove its folder. */
+export async function deleteChat(id) {
+    const state = await loadState(id);
+    if (!state)
+        return { error: "not found" };
+    for (const resolve of state.pendingPermissions.values())
+        resolve(null);
+    state.backend?.dispose();
+    states.delete(id);
+    await fs.rm(safeChatDir(id), { recursive: true, force: true });
+    return {};
+}
 export async function cancelChat(id) {
     const state = await loadState(id);
     if (!state)