本地技能（Agent Skills）

技能是包含 SKILL.md 的文件夹，用来提供任务方法、参考材料和模板。Wisp 支持 Agent Skills 格式，采用渐进加载：先提供摘要，使用时再读取正文与参考材料。

添加与使用

1. 在桌面端 设置 → 技能 → 添加技能文件夹，选择包含 SKILL.md 的目录。选择目录会解析文本并建立版本索引，不会运行脚本。
2. 新技能默认禁用。核对名称、来源、环境要求及警告后，点 启用；仅启用你信任且允许发送给所选模型的材料，不要放入密钥或密码。
3. 对话输入框的 技能 可主动选择最多 3 个技能。发送任务时实际加载所选正文；其他已启用技能只给模型摘要，模型可按需选择加载。
4. 文件修改后点 刷新，新版本在下一次任务生效。刷新失败会禁用技能并显示错误；修复、刷新后需要重新启用。
5. 禁用 或 移除 阻止旧任务后续读取。移除只删 Wisp 配置，不删除磁盘技能文件。

不自动扫描项目或用户目录。项目文件读取权限与技能启用相互独立。相同目录不能重复添加，不同来源的同名技能以稳定 ID 区分。启用状态在本地持久保存，重启恢复；历史记录只回显，不重新读取技能。

最小目录

review-notes/
  SKILL.md
  references/
    checklist.md
  assets/
    template.txt

SKILL.md 示例：

---
name: review-notes
description: 阅读研究笔记，按清单提取结论和待核实问题。
---
先阅读 references/checklist.md，再整理结论。需要时读取 assets/template.txt。

名称必须与目录名一致，使用小写字母、数字与单连字符，不超过 64 字符；描述为 1–1024 字符。支持 YAML 多行文本和 license、compatibility、文本键值 metadata。拒绝重复字段、YAML 别名和自定义标签。环境要求仅展示，不自动检测或安装依赖。

首版最多 30 个技能；每目录最多 200 个扫描条目、5 层子目录；单份 UTF-8 文本最多 64 KiB，总可索引文本最多 2 MiB。不截断正文后假称完整加载。隐藏路径、node_modules、scripts 不索引；二进制、超大或链接资源会标为不可读，调用时说明原因。

模型工具与版本

• skill_load({ skillId })：读取本轮目录中的技能正文，返回名称、来源、版本与资源相对路径。
• skill_read_resource({ skillId, path })：当前 Agent 先加载该技能，再读取一个索引内文本资源。

两个工具都是只读，无工具审批。无启用技能时不注入技能目录或工具。tool_introspect 仍列出本轮实际工具定义。

每轮开始固定技能摘要、文件内容哈希和启用代次。读取前后检查目录身份、文件版本及启用代次；旧描述不会配上修改后的正文。即使文件未改变，刷新或禁用再启用也使旧任务的读取资格失效，需开始新任务。新加入的资源也必须刷新后才能使用。已发送给模型的内容不能撤回，禁用不会抹除已保存的工具结果。

主动选择的正文与目录摘要只加入当轮模型上下文，不伪装成普通聊天消息、不复制进下一轮私有历史。模型主动读取的工具结果按既有工具历史保存。加载事件只记录技能名称、来源与版本，父/子任务分别归属，历史回显不触发读取。可重试的失败任务保留主动选择 ID，并按新任务的可用范围重新校验；已经请求过工具的任务仍按原有规则禁止自动重放。

子 Agent 继承父任务固定的可用技能版本，不自动复制父任务已经加载的正文。agent_spawn 可携带 skillIds 主动选择最多 3 个；否则子任务只有目录摘要，自行按需加载。各自的加载状态、事件与取消信号隔离。

权限边界

技能是低于应用固定规则的任务材料，不是授权。allowed-tools 仅作为兼容性警告，不新增工具、不免除文件变更或 MCP 审批，不扩大项目范围。资源解析限定所选技能根，拒绝路径穿越、符号链接、硬链接、非普通文件和 Wisp 私有数据目录。

技能加载工具不读取或执行 scripts。另提供经审批的完整 ZIP 安装与托管脚本执行，安装默认禁用、运行默认关闭且不是 OS 沙箱。不提供任意 shell、在线市场或自动更新。包含脚本的技能不能仅凭加载就宣称其执行流程成功。若技能依赖额外第三方工具，仍受已有工具可用范围及用户审批约束。

Electron 是唯一生产目标。qa.html 的“技能管理与选择（仅内存）”提供明确的目录选择替身、启停刷新与加载来源回显，只用于 UI 验证；不读取真实目录或调用模型。