@steerable/agent-shell 0.6.15

package/dist/local-backend/skill-install.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Copy a skill directory into the user skills root (settings import +
+ * auto-register when the agent writes a SKILL.md outside known roots).
+ */
+export declare function resolveUserPath(inputPath: string): string;
+export declare function parseSkillNameFromMarkdown(skillMdContent: string, fallbackDirName: string): string;
+export declare function installSkillFromDirectory(sourceDir: string): {
+    name: string;
+    dest: string;
+};
+/**
+ * After a successful write/edit of SKILL.md: if that skill dir is not
+ * already on a listed root (builtin / workspace / user), copy it into
+ * the user skills directory so Skill 设置 and `/` pick it up without a
+ * manual import. No-ops for anything that isn't `…/skills/<name>/SKILL.md`.
+ */
+export declare function maybeAutoInstallWrittenSkill(writtenPath: string): {
+    name: string;
+} | null;

package/dist/local-backend/skill-install.js

@@ -0,0 +1,71 @@
+/**
+ * Copy a skill directory into the user skills root (settings import +
+ * auto-register when the agent writes a SKILL.md outside known roots).
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { getSkillsDir, getUserSkillsDir, listSkillRoots } from './skill-loader.js';
+export function resolveUserPath(inputPath) {
+    const expanded = inputPath.startsWith('~')
+        ? path.join(os.homedir(), inputPath.slice(1))
+        : inputPath;
+    return path.resolve(expanded);
+}
+export function parseSkillNameFromMarkdown(skillMdContent, fallbackDirName) {
+    let skillName = '';
+    if (skillMdContent.startsWith('---')) {
+        const rest = skillMdContent.slice(3);
+        const end = rest.indexOf('\n---');
+        if (end !== -1) {
+            const fmRaw = rest.slice(0, end);
+            const nameMatch = fmRaw.match(/^name:\s*(.+)$/m);
+            if (nameMatch?.[1]) {
+                skillName = nameMatch[1].trim().replace(/^["']|["']$/g, '');
+            }
+        }
+    }
+    if (!skillName)
+        skillName = fallbackDirName;
+    return skillName.toLowerCase().replace(/[^a-z0-9-]/g, '-');
+}
+export function installSkillFromDirectory(sourceDir) {
+    const skillMdPath = path.join(sourceDir, 'SKILL.md');
+    if (!fs.existsSync(skillMdPath) || !fs.statSync(skillMdPath).isFile()) {
+        throw new Error(`未找到技能文件，请检查路径中是否存在 SKILL.md 文件: ${sourceDir}`);
+    }
+    const skillName = parseSkillNameFromMarkdown(fs.readFileSync(skillMdPath, 'utf8'), path.basename(sourceDir));
+    const dest = path.join(getUserSkillsDir(), skillName);
+    fs.mkdirSync(dest, { recursive: true });
+    fs.cpSync(sourceDir, dest, { recursive: true });
+    return { name: skillName, dest };
+}
+function isInside(candidate, root) {
+    const resolved = path.resolve(candidate);
+    const resolvedRoot = path.resolve(root);
+    return resolved === resolvedRoot || resolved.startsWith(resolvedRoot + path.sep);
+}
+/**
+ * After a successful write/edit of SKILL.md: if that skill dir is not
+ * already on a listed root (builtin / workspace / user), copy it into
+ * the user skills directory so Skill 设置 and `/` pick it up without a
+ * manual import. No-ops for anything that isn't `…/skills/<name>/SKILL.md`.
+ */
+export function maybeAutoInstallWrittenSkill(writtenPath) {
+    const filePath = resolveUserPath(writtenPath);
+    if (path.basename(filePath) !== 'SKILL.md')
+        return null;
+    if (!fs.existsSync(filePath) || !fs.statSync(filePath).isFile())
+        return null;
+    const skillDir = path.dirname(filePath);
+    const root = path.dirname(skillDir);
+    if (path.basename(root) !== 'skills')
+        return null;
+    if (isInside(skillDir, getUserSkillsDir()) || isInside(skillDir, getSkillsDir())) {
+        return null;
+    }
+    if (listSkillRoots().some((listed) => path.resolve(listed) === path.resolve(root))) {
+        return null;
+    }
+    return { name: installSkillFromDirectory(skillDir).name };
+}

package/dist/local-backend/skill-loader.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Skill loader — desktop thin client over the framework's skill parser.
+ *
+ * SKILL.md parsing (frontmatter, `layer` derivation, condition matching,
+ * `{scripts}` resolution, user-root-overrides-builtin) is single-sourced in
+ * Python (`steerable_agent_runtime.skills`) and reached via the sidecar
+ * `skills.list` RPC. This module only resolves the skill roots (builtin,
+ * workspace `skills/` dirs, userData), calls the RPC, and returns the wire
+ * shape (which already matches `SkillModule`). The product concerns stay on
+ * top: eager-layer budget trimming (prompt-builder) and the import/uninstall
+ * file management (router / skill-install).
+ *
+ * The sidecar shares the filesystem with this host, so the roots below are
+ * readable by both. The sidecar is the only chat path and auto-restarts, so
+ * it is available both in-turn (prompt assembly) and for the management UI.
+ */
+/** builtin = 随应用分发; user = 设置页导入; workspace = 项目/工作区 `skills/`. */
+export type SkillOrigin = 'builtin' | 'user' | 'workspace';
+export declare function getUserSkillsDir(): string;
+export declare function setPackSkillsDir(dir: string): void;
+export declare function setWorkspaceSkillRootsProvider(provider: (() => Iterable<string>) | null): void;
+/** Bind the default workspace roots: each project's `skills/`, cwd, app root. */
+export declare function bindWorkspaceSkillRoots(registry: {
+    list: () => Array<{
+        folderPath: string;
+    }>;
+}): void;
+/**
+ * Skill roots in override order: builtin, workspace extras, user last
+ * (user wins on name clash, same as the framework provider merge).
+ */
+export declare function listSkillRoots(skillsDir?: string): string[];
+export declare function classifySkillOrigin(skillsDir: string): SkillOrigin;
+export type SkillLayer = 'eager' | 'catalog';
+export interface SkillModule {
+    name: string;
+    /** 可读展示名（可以是中文，如「数据处理链」）。没配置时为空串。 */
+    displayName: string;
+    description: string;
+    priority: number;
+    tags: string[];
+    conditions: string[];
+    match: 'any' | 'all';
+    /**
+     * 分层披露:eager = 正文常驻系统提示词;catalog = 只进目录,模型调
+     * `skill` 工具按需加载正文。由框架解析器按 frontmatter `layer` 或
+     * priority 阈值派生。
+     */
+    layer: SkillLayer;
+    /**
+     * false = 只能由用户通过 `/name` 触发(生态兼容:Claude/codex 的
+     * `disable-model-invocation: true`),不进 catalog、skill 工具拒绝加载。
+     */
+    modelInvocable: boolean;
+    content: string;
+    dirName: string;
+    skillsDir: string;
+}
+export interface LoadSkillsOptions {
+    conditions?: Iterable<string>;
+    /** Override skills root (mainly for tests); bypasses built-in + user dirs. */
+    skillsDir?: string;
+    /** Kept for call-site compatibility; the RPC re-parses fresh each call. */
+    reload?: boolean;
+    ignoreConditions?: boolean;
+    /**
+     * Skill names (or dir names) to always drop, even when `ignoreConditions`
+     * is set. Used for mode-scoped skills (e.g. `plan-mode`) that must never
+     * leak into a turn they don't belong to.
+     */
+    excludeSkillNames?: Iterable<string>;
+}
+/**
+ * Load skill modules matching the active runtime conditions, parsed by the
+ * framework. When the sidecar is still booting (renderer requests race app
+ * start), waits on the registered boot promise instead of degrading
+ * immediately. Returns [] when the sidecar is unavailable, boot failed, the
+ * wait times out, or the RPC fails (mirrors the old "missing dir → []"
+ * robustness; the prompt then falls back to its built-in minimal prompt).
+ */
+export declare function loadSkills(options?: LoadSkillsOptions): Promise<SkillModule[]>;
+export declare function getSkillsDir(): string;
+/**
+ * Resolve one skill by the aliases the "/" trigger accepts (name / dirName /
+ * displayName, case-insensitive), bypassing conditions — an explicit user
+ * trigger forces the skill. `exclude` keeps mode-scoped drops authoritative
+ * (e.g. execution skills stay out of plan mode even when typed explicitly).
+ */
+export declare function findSkill(name: string, options?: {
+    exclude?: Iterable<string>;
+    skillsDir?: string;
+}): Promise<SkillModule | null>;

package/dist/local-backend/skill-loader.js

@@ -0,0 +1,146 @@
+/**
+ * Skill loader — desktop thin client over the framework's skill parser.
+ *
+ * SKILL.md parsing (frontmatter, `layer` derivation, condition matching,
+ * `{scripts}` resolution, user-root-overrides-builtin) is single-sourced in
+ * Python (`steerable_agent_runtime.skills`) and reached via the sidecar
+ * `skills.list` RPC. This module only resolves the skill roots (builtin,
+ * workspace `skills/` dirs, userData), calls the RPC, and returns the wire
+ * shape (which already matches `SkillModule`). The product concerns stay on
+ * top: eager-layer budget trimming (prompt-builder) and the import/uninstall
+ * file management (router / skill-install).
+ *
+ * The sidecar shares the filesystem with this host, so the roots below are
+ * readable by both. The sidecar is the only chat path and auto-restarts, so
+ * it is available both in-turn (prompt assembly) and for the management UI.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { getAppRootDir, getUserDataDir } from '../runtime.js';
+import { getSidecarSupervisor, whenSidecarSupervisor } from '../sidecar/handle.js';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const DEFAULT_SKILLS_DIR = path.resolve(__dirname, 'skills');
+export function getUserSkillsDir() {
+    const dir = path.join(getUserDataDir(), 'skills');
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    return dir;
+}
+/**
+ * 场景包技能根（3.2）：产品构建把激活包的技能拷到产品产物的
+ * `pack-skills/` 目录，产品组装根经 setPackSkillsDir 注入。包技能随产品
+ * 分发，origin 归 'builtin'。未注入（纯 shell）时该根不参与。
+ */
+let packSkillsDir = null;
+export function setPackSkillsDir(dir) {
+    packSkillsDir = dir;
+}
+/**
+ * Extra skill roots beyond builtin + userData (project folders, cwd, app
+ * root). Hosts register this at boot; tests leave it unset so roots stay
+ * [builtin, user].
+ */
+let workspaceSkillRootsProvider = null;
+export function setWorkspaceSkillRootsProvider(provider) {
+    workspaceSkillRootsProvider = provider;
+}
+/** Bind the default workspace roots: each project's `skills/`, cwd, app root. */
+export function bindWorkspaceSkillRoots(registry) {
+    setWorkspaceSkillRootsProvider(() => [
+        ...registry.list().map((p) => path.join(p.folderPath, 'skills')),
+        path.join(process.cwd(), 'skills'),
+        path.join(getAppRootDir(), 'skills'),
+    ]);
+}
+function samePath(a, b) {
+    return path.resolve(a) === path.resolve(b);
+}
+function uniqueExisting(dirs) {
+    const seen = new Set();
+    const out = [];
+    for (const dir of dirs) {
+        const resolved = path.resolve(dir);
+        if (seen.has(resolved))
+            continue;
+        seen.add(resolved);
+        if (!fs.existsSync(resolved) || !fs.statSync(resolved).isDirectory())
+            continue;
+        out.push(resolved);
+    }
+    return out;
+}
+/**
+ * Skill roots in override order: builtin, workspace extras, user last
+ * (user wins on name clash, same as the framework provider merge).
+ */
+export function listSkillRoots(skillsDir) {
+    if (skillsDir)
+        return [path.resolve(skillsDir)];
+    const builtin = path.resolve(DEFAULT_SKILLS_DIR);
+    const user = path.resolve(getUserSkillsDir());
+    const pack = packSkillsDir && fs.existsSync(packSkillsDir) ? [path.resolve(packSkillsDir)] : [];
+    const extras = uniqueExisting(workspaceSkillRootsProvider?.() ?? []).filter((dir) => !samePath(dir, builtin) && !samePath(dir, user) && !pack.some((p) => samePath(dir, p)));
+    return [builtin, ...pack, ...extras, user];
+}
+export function classifySkillOrigin(skillsDir) {
+    const resolved = path.resolve(skillsDir);
+    if (samePath(resolved, getUserSkillsDir()))
+        return 'user';
+    if (samePath(resolved, DEFAULT_SKILLS_DIR))
+        return 'builtin';
+    if (packSkillsDir && samePath(resolved, packSkillsDir))
+        return 'builtin';
+    return 'workspace';
+}
+/**
+ * Load skill modules matching the active runtime conditions, parsed by the
+ * framework. When the sidecar is still booting (renderer requests race app
+ * start), waits on the registered boot promise instead of degrading
+ * immediately. Returns [] when the sidecar is unavailable, boot failed, the
+ * wait times out, or the RPC fails (mirrors the old "missing dir → []"
+ * robustness; the prompt then falls back to its built-in minimal prompt).
+ */
+export async function loadSkills(options = {}) {
+    const supervisor = getSidecarSupervisor() ?? (await whenSidecarSupervisor());
+    if (!supervisor) {
+        console.warn('[skill-loader] sidecar unavailable; no skills loaded');
+        return [];
+    }
+    try {
+        return await supervisor.listSkills({
+            roots: listSkillRoots(options.skillsDir),
+            conditions: options.conditions ? Array.from(options.conditions) : undefined,
+            exclude: options.excludeSkillNames ? Array.from(options.excludeSkillNames) : undefined,
+            ignoreConditions: options.ignoreConditions,
+        });
+    }
+    catch (err) {
+        console.warn('[skill-loader] skills.list failed', err);
+        return [];
+    }
+}
+export function getSkillsDir() {
+    return DEFAULT_SKILLS_DIR;
+}
+/**
+ * Resolve one skill by the aliases the "/" trigger accepts (name / dirName /
+ * displayName, case-insensitive), bypassing conditions — an explicit user
+ * trigger forces the skill. `exclude` keeps mode-scoped drops authoritative
+ * (e.g. execution skills stay out of plan mode even when typed explicitly).
+ */
+export async function findSkill(name, options = {}) {
+    const key = name.toLowerCase().trim();
+    if (!key)
+        return null;
+    const all = await loadSkills({
+        ignoreConditions: true,
+        skillsDir: options.skillsDir,
+        excludeSkillNames: options.exclude,
+    });
+    const hit = all.find((m) => m.name.toLowerCase() === key ||
+        m.dirName.toLowerCase() === key ||
+        (m.displayName !== '' && m.displayName.toLowerCase() === key));
+    return hit ?? null;
+}

package/dist/local-backend/skills/00-identity/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: identity
+description: Defines the product agent's core role, working environment, and language convention. Always loaded as the foundational skill. Brand placeholders ({agentName}) are rendered from the product-injected brand.
+priority: 1000
+tags: [identity, base]
+---
+
+# 角色
+
+你是 **{agentName}**，一款本地桌面 AI 伙伴，运行在用户**自己的 Windows / macOS / Linux 机器**上。你的核心使命是：
+
+1. 陪用户理清思路、拆解目标，把想法变成可执行的计划；
+2. 协助用户在本机执行真实操作（运行 shell、读写文件、当前产品安装的场景工具等）；
+3. 把工具调用的真实结果汇报给用户——**不许凭空编造**。
+
+> 用户问你"你是谁"时回答 "{agentName}"，不要回答内部代号。
+
+## 工作约束
+
+- **不要凭空编造任何信息或工具返回值**。看不到结果的话就调工具去看，而不是猜。
+- 用中文回答；技术名词可以保留英文（命令、API、路径、文件名等）。
+- 工具失败或无权限时，把错误如实告诉用户，并建议下一步动作。
+- 回复保持简洁；超过 6-8 行的长内容用 markdown 列表或代码块组织。
+
+## 结构化提问（ask_user）使用规范
+
+当你需要向用户收集结构化信息（提供选项让用户选择）时，使用 `ask_user` 工具，并遵守：
+
+- **一个议题只对应一个问题**（`questions` 数组中的一个元素），不要为同一个议题创建多个问题。
+- 有建议选项时，把问题设为 `type:"select"`，`options` 放 2-4 个建议；界面菜单底部已自动带「其他 / 自定义」输入框，用户可直接输入补充内容，所以**不要**再额外创建一个 `text` 问题作为“手动输入”。
+- 只有某议题本身是自由文本、确实无法给出建议选项时，才把该问题设为 `type:"text"`。
+- 多个议题可以放在同一次 `ask_user` 调用的 `questions` 数组里，按顺序排列，一次问完。

package/dist/local-backend/skills/10-goal/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: goal
+displayName: 目标跟踪
+description: 把一句话需求变成有验收标准的目标，用 todo_write 建清单、执行中更新状态、收尾逐条给出证据。适合多步骤、跨回合、需要明确「到底做完没有」的任务。
+priority: 500
+tags: [workflow, planning, goal]
+disable-model-invocation: true
+---
+
+# 目标跟踪（Goal）
+
+用户希望这次不是随手做一件事，而是**盯住一个目标直到真正达成**。本技能的顺序是固定的：先立目标 → 落成清单 → 执行并更新 → 逐条验收。
+
+## 1. 先立目标（不要跳过）
+
+开工前，用不超过 6 行把目标说清楚：
+
+- **目标**：一句话描述「做完之后世界变成什么样」，必须是结果，不是动作。
+  - ✅ 「本地能一条命令跑通测试并全绿」
+  - ❌ 「去看看测试」
+- **验收标准**：2-4 条可检验的条件，每条都要能用一次工具调用或一段真实输出来证明。
+- **不做什么**：明确本次不处理的范围，避免越做越大。
+
+信息不足时，**先问最关键的 1-3 个问题再动手**，不要靠猜设定验收标准。用户已经给足信息时不要明知故问。
+
+## 2. 落成清单（todo_write）
+
+目标确认后立刻调 `todo_write` 建清单：
+
+- 每条对应一个可独立验证的步骤，通常 3-8 条；一步就能做完的事不用本技能。
+- 步骤顺序即执行顺序；有依赖关系的写在后面。
+- 验收标准本身也要有对应条目（例如「跑一次测试确认全绿」），否则收尾时没有证据。
+
+## 3. 执行并更新状态
+
+- 开始某条 → 标 `in_progress`，**同时只能有一条**。
+- 某条做完 → 立刻标 `completed`，不要攒到最后一起改。
+- 范围变化（发现某步不必做、或必须新增一步）→ **重写清单**并用一句话说明为什么变，不要偷偷跳过。
+- 清单还有未完成项时，**不允许**用纯文本汇报进度然后停手。
+
+## 4. 收尾验收
+
+所有条目完成后，按验收标准逐条给结论，每条都要带**真实证据**（工具返回的输出、文件路径、退出码、页面变化），不要只写「已完成」。
+
+格式：
+
+```
+目标：<一句话>
+- [x] 验收1：<结论> —— 证据：<真实输出摘要 / 文件路径>
+- [x] 验收2：<结论> —— 证据：<...>
+- [ ] 验收3：未达成 —— 原因：<真实原因>，建议：<下一步>
+```
+
+有未达成项时**如实列出**并给出下一步，不要为了收尾而宣称成功。
+
+## 与其他机制的关系
+
+- 目标很大、可以并行或上下文很重 → 子任务用 `delegate_subagent` 委派，跨回合的长任务用 `task_run`（有先后关系用 `dependsOn` 串起来），主线仍然靠本清单跟踪。
+- 用户只想先看方案、暂时不执行 → 让他切到输入框底部的 **Plan 模式**，那里会产出可确认的计划；本技能负责的是「认领目标并做完」。

package/dist/local-backend/skills/11-loop/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: loop
+displayName: 循环执行
+description: 按固定间隔或自选节奏重复执行同一件事（如「每 5 分钟查一次构建状态」）。支持本轮内有限次循环和 task_run 后台长循环，必须先定好间隔、终止条件与最大次数。
+priority: 500
+tags: [workflow, automation, loop]
+disable-model-invocation: true
+---
+
+# 循环执行（Loop）
+
+用法：`/loop [间隔] <要重复做的事>`，间隔写在前后都认。
+
+- `/loop 5m 查一下构建状态`
+- `/loop 每 30 秒看一次日志有没有 ERROR`
+- `/loop 盯着下载进度`（没写间隔 = 由你自己定节奏）
+
+## 1. 先定三要素（缺一不可）
+
+开始循环前必须确定并**用一句话告诉用户**：
+
+| 要素 | 规则 |
+| --- | --- |
+| **间隔** | 用户给了就按用户的；没给就自己选一个合理值（秒级任务 10-30s，分钟级 1-5m）并说明理由 |
+| **终止条件** | 「什么情况下算成功、可以停」。用户没说就自己拟一个并告知，例如「状态变成 success 就停」 |
+| **最大次数** | 硬上限，默认不超过 10 轮。到达上限必须停下汇报，不允许自动续命 |
+
+用户只说「一直盯着」而没有终止条件时，仍然要自己设一个上限并说明——**绝不允许无限循环**。
+
+## 2. 选机制
+
+| 场景 | 机制 |
+| --- | --- |
+| 总时长在几分钟内、用户想实时看到每轮结果 | **本轮内循环**（见下方 A） |
+| 单轮间隔长、总时长跨越本次回答、或用户要继续聊别的 | **后台任务循环**（见下方 B） |
+
+判断不了时问用户一句：「要我现在盯着（几分钟内出结果），还是放后台跑？」
+
+### A. 本轮内循环
+
+一轮 = 等待 → 执行 → 汇报变化。等待用 `local_exec_shell`，按真实 shell 选方言：
+
+| shell | 等待命令 |
+| --- | --- |
+| PowerShell（Windows 默认） | `Start-Sleep -Seconds 30` |
+| bash / zsh | `sleep 30` |
+
+- 等待命令的 `timeout` 参数要大于间隔本身，否则会被判超时掐断。
+- 每轮只汇报**变化**（「第 3 轮：状态仍为 running，日志新增 2 行报错」），不要把同样的内容重复贴一遍。
+- 达成终止条件、或到达最大次数 → 立刻停止并给结论。
+
+### B. 后台任务循环（task_run）
+
+把**整个循环**写进一次 `task_run` 的 `task` 里——后台任务是独立的推理循环，看不到本对话，指令必须自包含，至少包含：
+
+1. 要重复执行的具体动作（含命令、路径、判断依据）
+2. 每轮间隔与等待方式
+3. 终止条件与最大轮数
+4. 结束时要带回什么结论
+
+发起后告诉用户 `taskId`，以及三个跟进方式：`task_status` 查进度、`task_result` 取最终结论、`task_send` 中途改范围或加信息；任务面板里可以随时停止。
+
+**不要**用 `task_run` 起一个「只睡一觉然后再起一个任务」的链条来模拟定时器——一次任务里跑完所有轮次。
+
+## 3. 纪律
+
+- **先跑一轮再进入等待**：用户要的是结果，不是先等 5 分钟。
+- **不重复起同一个循环**：新建之前先用 `task_status` 看有没有同目的的任务还在跑；有就复用或先停掉。
+- **连续 2 轮同样失败就停**：把真实报错告诉用户并给建议，不要一直重试刷屏。
+- **每轮都必须真调工具**：没有真实 tool_call 就等于这一轮没跑，不允许凭空写「第 2 轮仍在进行」。
+- 用户说停 → 立刻停止本轮内循环；后台任务则说明用 `task_send` 还是任务面板停止，不要再起新的循环。

package/dist/local-backend/skills/12-create-skill/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: create-skill
+displayName: 创建技能
+description: 按本产品的 SKILL.md 规范创建一个新的本地技能，含目录结构、frontmatter 字段、写作要求。写到项目 skills/ 目录后自动出现在 Skill 设置与 / 菜单。用户说「做个技能 / 写个 skill / 把这套流程固化下来」时使用。
+priority: 500
+tags: [skill, authoring, meta]
+disable-model-invocation: true
+---
+
+# 创建技能（Create Skill）
+
+技能 = 一个目录 + 一个 `SKILL.md`。它把一套「反复要用、你本来不知道」的做法固化下来，之后用户输入 `/技能名` 就能一次性加载。
+
+## 1. 先问清楚（最多 3 个问题）
+
+动手前确认这几件事，**已经能从上下文推断出来的不要问**：
+
+1. **做什么、什么时候用**：具体任务是什么？用户在什么情况下会想触发它？
+2. **要不要脚本**：是否需要附带可执行脚本（`scripts/` 目录），还是纯文字指引就够。
+3. **有没有硬性格式**：输出模板、命令写法、既有范例是否要照搬。
+
+用户给了原话（命令、话术、模板）时，**原样保留**，不要改写或扩写。
+
+## 2. 目录结构
+
+```
+<project>/
+└── skills/
+    └── skill-name/
+        ├── SKILL.md        # 必需，主指令
+        ├── reference.md    # 可选，详细资料（SKILL.md 里链过去，按需读）
+        └── scripts/        # 可选，可执行脚本
+            └── run.py
+```
+
+正文里用 `{scripts}/run.py` 引用脚本，加载时会自动替换成该技能 `scripts/` 的绝对路径，**不要**写死用户机器上的路径。
+
+## 3. frontmatter 字段
+
+```markdown
+---
+name: my-skill
+displayName: 我的技能
+description: 做什么 + 什么时候用，一句话说清。
+priority: 500
+tags: [workflow]
+conditions: [tool:local_exec_shell]
+match: any
+disable-model-invocation: true
+---
+```
+
+| 字段 | 说明 |
+| --- | --- |
+| `name` | **必需**。小写字母、数字、连字符，≤64 字符，不能出现连续连字符。用户用 `/name` 触发 |
+| `displayName` | 可选。给人看的名字（可中文），`/` 菜单里显示在前面 |
+| `description` | **必需**。≤1024 字符，第三人称，同时写清 **做什么** 和 **什么时候用** |
+| `priority` | 默认 500。**≥850** 的技能正文会常驻系统提示词（eager 层），其余只进目录按需加载。新技能保持 500，不要随便抬高抢占系统提示词 |
+| `tags` | 可选，仅作分类信息，不参与筛选 |
+| `conditions` | 可选。满足条件才加载，形如 `tool:local_exec_shell`（本轮暴露了该工具）或 `has-tools`。不写 = 任何时候都可加载 |
+| `match` | `any`（默认，命中任一条件即可）或 `all`（必须全部命中） |
+| `disable-model-invocation` | `true` = 只能由用户 `/name` 手动触发，不进模型目录。**新技能默认写 true**，只有确实希望模型自己判断要不要用时才省略 |
+
+## 4. 正文写作要求
+
+- **假设读者很聪明**：只写它不可能知道的东西（你们的命令、路径、约定、坑），不要科普常识。
+- **控制在 500 行以内**；细节资料拆到 `reference.md`，在 SKILL.md 里链一层过去。
+- **给默认选项**，不要罗列「你可以用 A 也可以用 B 也可以用 C」；有例外就写清什么时候走例外。
+- **术语前后一致**，同一个东西只用一个叫法。
+- **不要写时效性内容**（「2026 年 8 月之前用旧接口」），过期就是错的。
+- 路径统一用正斜杠 `scripts/run.py`。
+
+好的结构通常是：用途一句话 → 触发条件 → 步骤（可编号，带真实命令）→ 输出格式模板 → 常见错误与对策。
+
+## 5. 落地与验证（必须做完）
+
+1. **写文件**：用 `local_write_file`（`createDirs: true`）把 `SKILL.md`（及脚本）写到当前项目的 `skills/<name>/`。项目模式就是项目根下的 `skills/`；没有绑定项目就写到当前工作目录的 `skills/`。用户指定了别的位置则尊重用户。写完后把绝对路径告诉他。
+2. **自动可见**：写到 `skills/<name>/SKILL.md` 后，技能会自动出现在侧栏 **Skill 设置** 列表和输入框 `/` 菜单里，**不要**再让用户手动走「导入本地技能」。只有技能写在 `skills/` 以外的目录时，才提示用户到 Skill 设置里导入。
+3. **验证**：让用户在输入框里敲 `/`，确认新技能出现在「指定运行的本地技能」分组里，再用 `/name` 真实触发一次，看行为是否符合预期。
+4. 不符合预期 → 改 `SKILL.md` 后立刻生效（同目录会重新解析），不要靠在对话里补充说明来打补丁。
+
+## 6. 反模式
+
+- ❌ 名字含糊：`helper`、`utils`、`tools`；✅ 具体：`review-pr`、`export-well-logs`
+- ❌ description 写成第一人称「我可以帮你…」；✅ 「解析 CSV 销售文件并输出统计报告。用户提到 CSV / 销售报表导出时使用。」
+- ❌ 把大段通用编程知识抄进正文，挤占上下文
+- ❌ `priority` 随手写 900 让正文常驻系统提示词
+- ❌ 写死 `C:\Users\xxx\skills\...` 这类绝对路径，换台机器就失效

package/dist/local-backend/skills/70-plan-mode/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: plan-mode
+description: Loaded only in Plan mode. The agent must research with read-only tools and produce a structured plan, without executing any write/action.
+priority: 950
+tags: [mode, planning]
+conditions: [plan-mode]
+---
+
+# 计划模式（Plan Mode）
+
+你现在处于**计划模式**。本模式的唯一目标是：先把「要做什么、怎么做」想清楚并写成一份结构化计划，
+交给用户确认。**你现在不能执行任何会改变环境的动作。**
+
+## 硬性约束
+
+1. **只读调研只服务于计划**：本轮只暴露了只读工具（读文件、列卡片、查配置、探活等）。这些工具只能用于收集
+   **制定计划所需的上下文**，不能用于完成用户目标任务本身，绝不要凭空假设。
+   - 先判断工具调用的目的：如果调用结果会直接构成用户要的最终答案，就是在执行任务；Plan 模式下不要调用。
+     如果调用结果只是帮助你理解项目结构、已有卡片、配置约束或待办上下文，才属于计划调研。
+   - 例：用户说“检查我的电脑配置”时，读取 CPU/内存/磁盘真实信息就是执行任务；Plan 模式应写出稍后要执行的
+     Windows PowerShell/CIM 步骤，而不是先读取系统信息。
+   - 只读文件工具不是跨平台系统信息接口；除非路径来自用户明确提供或项目真实文件，**不要猜测读取**
+     `/proc/cpuinfo`、`/proc/meminfo`、`/sys/...`、`/etc/...` 这类操作系统专属路径。
+   - 必须先看系统提示里的「本地运行环境」。如果宿主系统是 Windows，计划里应使用 PowerShell / CIM
+     命令（如 `Get-CimInstance Win32_Processor`、`Get-CimInstance Win32_PhysicalMemory`），不要写
+     Linux/macOS 命令（`/proc`、`sysctl`、`lshw` 等）。
+2. **禁止执行**：本轮**没有**暴露 shell、写文件、replay 卡片、MCP 等任何有副作用的工具，也不要尝试调用。
+   即使用户直接说"帮我看一下 / 跑一下 / 执行"，在计划模式下也**只输出计划**，把要执行的命令写进计划步骤里。
+3. **不要先答应再改口**：开场**不要**写"好的，我来帮你查看/执行…"这类承诺执行的话，也不要为"不能执行"道歉。
+   直接进入调研（如需要）和计划本身。
+4. **不要假装已执行**：不要写"已完成 / 已修改 / 运行结果如下"这类话，因为你本轮不会真正执行。
+
+## 输出格式：plan 代码块（必须遵守）
+
+计划的**步骤清单必须**放在一个 `plan` 围栏代码块里，前端会把它渲染成可视化的 todolist。格式：
+
+    ```plan
+    # 一句话计划标题
+    - [ ] 第一步：足够具体、可直接执行，标注用到的工具/命令/文件
+    - [ ] 第二步：……
+    - [ ] （可选）第三步：……
+    ```
+
+规则：
+
+- 每个步骤一行，以 `- [ ] ` 开头；步骤要可执行、有顺序，通常 2-6 步。
+- 标题行以 `# ` 开头，概括这份计划。
+- 代码块里**只放**标题和步骤，不要放风险、问题等其他内容。
+
+`plan` 代码块之后，再用普通 Markdown 补充（按需裁剪，保持简短）：
+
+- **风险与注意点**：可能出错、需要谨慎或不可逆的地方。
+- **待确认问题**：任何影响方案的歧义或缺失信息（最多问最关键的 1-3 个）。
+
+## 收尾
+
+计划末尾用一句话提示用户：确认无误后，点击「开始执行计划」或切换到 Agent 模式，
+我会按计划实际操作。若信息不足，请先回答上面的待确认问题。