v2
暂无简介
- License 许可
- GPL-3.0
- 最近更新
- 2026-11-15
- Stars
- ★ 6
- Forks
- 0
02 资源文件 132
- 参考文档architecture.md31.8 KB
- 参考文档btw-side-question.md10.6 KB
- 参考文档commands.md24.8 KB
- 参考文档compact/compact-phase-memory-plan.md16.7 KB
- 参考文档compact/e2e.md6.0 KB
- 参考文档compact/plan.md21.1 KB
- 参考文档compact/README.md17.0 KB
- 参考文档core-adapters-boundary-plan.md13.0 KB
- 参考文档count-lint.md2.2 KB
- 参考文档custom-commands.md16.9 KB
- 参考文档debug-execution-gantt.md4.7 KB
- 参考文档debug-observability.md12.6 KB
- 参考文档expert-workflow-todo.md16.1 KB
- 参考文档expert-workflow.md23.1 KB
- 参考文档extension-discovery-priority.md3.8 KB
- 参考文档hooks.md21.2 KB
- 参考文档i18n.md6.1 KB
- 参考文档ink-tui-renderer.md5.8 KB
- 参考文档input-history.md5.5 KB
- 参考文档live-session-updates.md13.4 KB
- 参考文档local-setting-migrations.md9.0 KB
- 参考文档logging.md15.3 KB
- 参考文档loop/architecture.md21.7 KB
- 参考文档loop/goal-background-task-notification-plan.md18.3 KB
- 参考文档loop/interfaces.md29.5 KB
- 参考文档loop/meta-user-context.md28.5 KB
- 参考文档loop/model-anomaly-fallbacks.md9.6 KB
- 参考文档loop/output-state-rotation.md13.5 KB
- 参考文档loop/plan.md6.3 KB
- 参考文档loop/runtime-active-target-loop-plan.md27.1 KB
- 参考文档loop/runtime-command-queue-plan.md21.1 KB
- 参考文档loop/system-prompt-contract.md18.8 KB
- 参考文档loop/tool-calling-loop.md23.2 KB
- 参考文档loop/turn-steering.md32.9 KB
- 参考文档mcp-node-fallback.md10.2 KB
- 参考文档mcp.md14.8 KB
- 参考文档memory/README.md59.8 KB
- 参考文档message-attachments.md45.7 KB
- 参考文档model/anthropic-reasoning-history-replay.md9.2 KB
- 参考文档model/anthropic-stream-compat.md15.1 KB
- 参考文档model/glm-5.2-reasoning-depth-plan.md17.8 KB
- 参考文档model/glm-5.2-reasoning-depth.md7.4 KB
- 参考文档model/http-proxy.md13.1 KB
- 参考文档model/lite-model-plan.md5.6 KB
- 参考文档model/model-capability-resolution.md1.6 KB
- 参考文档model/models-dev-catalog-source.md1.1 KB
- 参考文档model/provider-warning-output.md1.4 KB
- 参考文档model/README.md53.9 KB
- 参考文档model/session-features-header.md24.5 KB
- 参考文档model/stream-error-retry.md24.3 KB
- 参考文档model/streaming-tool-execution-and-recovery.md23.0 KB
- 参考文档model/token-usage.md5.2 KB
- 参考文档multi-workspace.md12.6 KB
- 参考文档native-conversation-metrics.md1.2 KB
- 参考文档network-capture-debug.md6.0 KB
- 参考文档permission-broker.md10.9 KB
- 参考文档permission-responder-race.md9.4 KB
- 参考文档plugin-compat.md27.3 KB
- 参考文档pre-commit-quality-gate.md2.2 KB
- 参考文档rewind-compact.md22.6 KB
- 参考文档rewind/plan.md18.2 KB
- 参考文档runtime-refactor.md2.1 KB
- 参考文档sea-cross-target-packaging.md14.1 KB
- 参考文档sea-smb-upload.md4.8 KB
- 参考文档session-event-store-retention.md9.7 KB
- 其他session-eventlog.example.jsonl6.6 KB
- 参考文档session-idle-deactivation.md13.8 KB
- 参考文档session-persistence.md33.2 KB
- 参考文档session-runtime-lifecycle.md16.9 KB
- 参考文档session-target.md24.8 KB
- 参考文档session-title-generation.md9.3 KB
- 参考文档skill-command-enable-override.md2.2 KB
- 参考文档streaming-runtime-plan.md12.8 KB
- 参考文档tool/00-tool-change-chain.md171.1 KB
- 参考文档tool/01-read.md27.7 KB
- 参考文档tool/02-write.md6.8 KB
- 参考文档tool/03-edit.md12.5 KB
- 参考文档tool/04-bash.md38.5 KB
- 参考文档tool/05-webfetch.md16.1 KB
- 参考文档tool/06-ask-user-question.md11.2 KB
- 参考文档tool/07-subagent-background-plan.md11.1 KB
- 参考文档tool/07-subagent.md44.0 KB
- 参考文档tool/08-glob.md3.3 KB
- 参考文档tool/09-grep.md7.2 KB
- 参考文档tool/10-todo.md7.4 KB
- 参考文档tool/11-ripgrep-wasm-packaging.md3.9 KB
- 参考文档tool/12-input-normalization.md5.1 KB
- 参考文档tool/13-websearch.md7.5 KB
- 参考文档tool/14-apply-patch.md3.5 KB
- 参考文档tool/15-workflow.md5.7 KB
- 参考文档tool/16-plan-mode.md11.1 KB
- 参考文档tool/17-read-file-state-resume.md10.5 KB
- 参考文档tool/18-cli-tool-visibility-denylist.md25.7 KB
- 参考文档tool/19-tool-search.md63.5 KB
- 参考文档tool/20-node-repl-call-ledger.md12.8 KB
- 参考文档tool/README.md16.7 KB
- 参考文档tui-ask-user-question.md13.8 KB
- 参考文档tui-borderless-layout.md1.6 KB
- 参考文档tui-copy-registry.md4.1 KB
- 参考文档tui-file-mentions.md4.5 KB
- 参考文档tui-idle-logo-animation.md3.5 KB
- 参考文档tui-image-paste.md13.8 KB
- 参考文档tui-input-active-status.md4.0 KB
- 参考文档tui-input-session-panel.md4.8 KB
- 参考文档tui-markdown-rendering.md11.7 KB
- 参考文档tui-mode-switching.md7.0 KB
- 参考文档tui-model-selection.md7.7 KB
- 参考文档tui-mouse-scrollback.md6.6 KB
- 参考文档tui-multiline-input.md3.2 KB
- 参考文档tui-network-status-panel.md2.7 KB
- 参考文档tui-opentui-sea-packaging.md6.3 KB
- 参考文档tui-responsive-sidebar.md2.7 KB
- 参考文档tui-selection-copy.md1.6 KB
- 参考文档tui-selection-list.md8.4 KB
- 参考文档tui-sidebar-production-chrome.md3.2 KB
- 参考文档tui-sidebar-session-modified-files.md3.3 KB
- 参考文档tui-sidebar-workspace.md1.0 KB
- 参考文档tui-slash-command-suggestions.md4.8 KB
- 参考文档tui-theme.md6.3 KB
- 参考文档tui-thought-placeholder.md2.7 KB
- 参考文档tui-todo-display.md1.8 KB
- 参考文档tui-tool-call-detail-blocks.md7.6 KB
- 参考文档tui-transcript-message-rows.md1.7 KB
- 参考文档tui-turn-elapsed.md2.6 KB
- 参考文档turn-cancellation.md5.7 KB
- 参考文档usage-observability.md5.4 KB
- 参考文档visualize-reference-format.md1.6 KB
- 参考文档workflow-expert-runtime-split.md2.3 KB
- 参考文档workflow-failure-recovery.md3.3 KB
- 参考文档workflow-script.md13.0 KB
- 参考文档workflow-session-linking.md2.6 KB
- 参考文档zcode-protocol-agent-server.md8.6 KB
03 SKILL.md 正文
Skill Integration Plan
文档定位
本文是 ZCode v2 接入 skill 的实现级规划。它遵循当前 v2 架构原则:
- spec 先行,再进入 contracts 和实现。
- core 不直接读文件、扫目录、访问网络或读取环境变量。
- skill 和 MCP、plugin、subagent 一样,必须通过 capability、schema、权限和 trace 边界进入 agent runtime。
- skill 首先服务 NL -> Code 的专业知识按需加载,不在第一版承担远程市场、插件安装和子代理编排。
设计要点
模型入口与上下文:
- skill 入口是
Skilltool。启动时只给模型可用 skill 列表,不把完整正文塞进 system prompt;模型必须先调用 tool 才能获得完整指令。 - skill 列表有预算控制,并对单个描述做硬截断;超过预算时截断描述、降级或发 warning。
Skilltool 输入是 skill name 和可选 args;输出完整内容和 base directory,帮助模型按需读取 references/scripts。- 已加载 skill 会被记录,便于 compaction 后恢复 skill 内容。
能力域与权限:
- skill 作为独立能力域,有
SkillMetadata、SkillLoadOutcome、SkillRoot、SkillPolicy、SkillDependencies等明确模型。 - root 有 scope:repo、user、system、admin;配置规则可按 name 或 path enable/disable。
- 发现路径覆盖自有目录和兼容目录,project-local discovery 从当前目录向上扫到 worktree root。
- skill frontmatter 可携带
allowed-tools、model、effort、disable-model-invocation、when_to_use等运行时影响项。 - 权限不是只看 “读取 SKILL.md 是否安全”,而是看 skill 是否会改变工具白名单、模型、hook、fork 执行等行为:只有安全属性的简单 skill 自动放行,其它情况走 permission;规则可以按 skill name pattern 表达 allow/deny/ask。
- loader 用 filesystem abstraction,不把本地 I/O 暴露给 core。
第一版不做:
- 不把 skill 和 slash command 合流,只做
SKILL.md指令包。 - forked skill(
context: fork)依赖成熟 subagent runtime,第一版只预留 schema。 - remote / URL skill discovery 需要网络、缓存、签名/校验和审计,不进第一阶段。
- 不长期保留大正文,优先 metadata snapshot + 按需读取正文。
- product gating、env dependency prompt、root alias 渲染作为 Phase 2+;第一版只保留字段和诊断,不实现完整依赖补全。
当前实现核对(2026-05-08)
本轮核对确认 skill P0 主线已经落地,本文后续条目仍作为契约基准,但不应再把以下能力当作未实现缺口:
- Contracts:
packages/contracts/src/skills/index.ts已定义SkillRoot、SkillScope、SkillMetadata、SkillDiagnostic、SkillContent、SkillLoadOutcome、SkillPort和SkillConfig;packages/contracts/src/tools/skill.ts已提供Skilltool 的运行时 schema 与 provider JSON schema。 - Adapter loader:
packages/adapters/src/skills/index.ts已通过 Node adapter 发现从 cwd 向上到 worktree root 的.zcode/skills、.agents/skills、.claude/skills及对应 user roots,支持 config extra roots、flat YAML frontmatter、未知字段 diagnostics、同名优先级去重、正文按需读取和 100KB 截断。 - Core runtime:
packages/core/src/context/sections/skills.ts已把 skill metadata 渲染为meta_usersection,不把正文放进 system prompt;packages/core/src/tool/handlers/skill.ts已通过SkillPort加载正文,并声明只读、session side effect、runtime input/output schema、result budget、timeout、取消和 trace 传播。 - Bootstrap / CLI / ZCode app-server:
packages/bootstrap/src/index.ts已按 feature gate 和skills.*config 注入SkillPort;listZCodeSkills()复用同一 adapter;zcode skills/zcode skills list支持 human、--json和--verbosediagnostics;TUI/command-center 的裸/skill只读列举 skills,/skill <name> [task]会改写为必须先调用Skilltool 的 prompt;ZCode app-server 暴露/skill <skill-name> [task],裸/skill在 ZCode app-server 中返回 usage,不启动模型 turn。 - Tests:
packages/adapters/tests/skills.test.ts覆盖 discovery、正文加载和重复名优先级;packages/core/tests/skill-tool.test.ts与packages/core/tests/context-builder.test.ts覆盖 metadata 注入和Skilltool;packages/cli/tests/cli.unit.test.ts覆盖 CLI/TUI/skill;packages/bootstrap/tests/zcode-protocol.test.ts覆盖 ZCode app-server command 暴露、禁用和 prompt rewrite。
当前仍未落地,继续作为后续范围:
- TUI/debug projection 的 skill diagnostics 页面,以及显式
$skill-name/skill://...mention。 - 按具体 skill name 或 wildcard 的 allow/deny/ask 规则;当前
Skilltool 的权限声明仍是 tool-level low-risk 自动允许,没有根据 unsafe frontmatter、remote/plugin source 或 runtime modifier 字段动态升级为 ask。 - skill lifecycle 事件(
SkillRootsResolved/SkillLoaded等)、loaded-skill session snapshot、compact 后恢复完整 skill body,以及 diagnostics 的结构化观测面。 - bundled/system/plugin/admin/remote roots、dependency/env prompt、
context: fork、model/effortruntime modifier、allowed-toolsscoped suggestion 等 P1/P2 能力。
核心原则
ZCode skill 采用“两层加载”:
- metadata discovery:启动/turn 初始化时扫描 skill roots,只把 name、description、source、scope、path、policy 等轻量信息进入 context。
- content load:模型显式调用
Skilltool 后,才读取对应SKILL.md正文并注入当前会话。
这能同时满足 token 控制、权限可见、trace 可追踪和跨平台 I/O 收口。
分层边界
contracts 增加 skill contract:
SkillRootSkillScopeSkillMetadataSkillPolicySkillLoadOutcomeSkillDiagnosticSkillContentSkillPortSkillConfig
adapters 实现 Node skill loader:
- 扫描目录。
- 解析 YAML frontmatter。
- 读取正文。
- 处理 symlink、权限错误、路径规范化、大小写差异和 max bytes。
- 返回结构化 diagnostics。
core 增加 skill registry / manager:
- 保存当前 session 的 skill metadata snapshot。
- 供 context builder 渲染 available skills section。
- 注册
Skilltool contract。 Skilltool 只通过SkillPort加载正文,不直接读文件。
bootstrap 负责组装:
- 根据 config 生成 skill roots。
- 注入
SkillPort到 runtime/tool executor。 - 把 skill feature gate、权限配置和 context budget 传给 core。
文件格式
P0 只要求每个 skill 目录包含 SKILL.md:
my-skill/
SKILL.md
references/
scripts/
assets/
SKILL.md 必须有 YAML frontmatter:
---
name: my-skill
description: When this skill should be used
---
# My Skill
Workflow instructions.
P0 frontmatter:
name:必填。建议^[a-z0-9]+(-[a-z0-9]+)*$,长度 1-64。description:必填,长度 1-1024。when_to_use:可选,追加到描述预算中。license:可选,仅 metadata。metadata:可选,string map。
P1/P2 预留字段:
allowed-toolsmodeleffortcontext: inline | forkdisable-model-invocationpolicy.allow_implicit_invocationdependencies.toolsinterface
P0 对未知字段不报错,但写入 diagnostics,避免未来字段被静默误用。
Discovery Roots
P0 默认 roots:
- configured extra roots:
skills.roots[],按配置顺序优先。 - project native:从 cwd 开始逐级向上到 worktree root 的
<dir>/.zcode/skills/*/SKILL.md。 - project agent-compatible:从 cwd 开始逐级向上到 worktree root 的
<dir>/.agents/skills/*/SKILL.md。 - project Claude-compatible:从 cwd 开始逐级向上到 worktree root 的
<dir>/.claude/skills/*/SKILL.md。 - user native:
~/.openzwork/skills/*/SKILL.md - user agent-compatible:
~/.agents/skills/*/SKILL.md - user Claude-compatible:
~/.claude/skills/*/SKILL.md
Project discovery 使用 nearest-first 语义:先检查当前 working directory 的 native / agent-compatible / Claude-compatible roots,再检查父目录,直到包含 .git marker 的 worktree root;如果找不到 worktree root,则只使用传入 working directory 的 project roots,避免意外扫描到用户目录或文件系统根。
已实现的额外 roots:
- bundled skill pack(
bootstrap/src/app/bundled-skills.ts):随 CLI 内置的技能包apps/zcode-cli/packages/bundled-skills/skills/,以source: "bundled"、scope: "system"进入发现,与 plugin roots 并列注入 runtime、zcode skills list与协议 skill catalog。它不是 插件:不进市场目录、没有启停开关、不能卸载、不出现在 Settings 与$引用面板 (skills/referenceCatalog过滤bundled)。开发态/桌面态/ZCode Server 发行包沿官方插件同款 候选目录在入口旁原地读取(Server 发行包 stage 在runtime/packages/bundled-skills);SEA 按内容 hash 一次性解压到~/.openzwork/cli/bundled-skills/<hash>/。包内每个 文件都是必需资产,缺一拒绝整包并告警。首个成员是dynamic-workflows(docs/dynamic-workflow/authoring.md)。 - plugin-provided skill roots。
Plugin-provided skill roots are defined by
plugin-compat.md. They use the same SKILL.md file
format and enter discovery as source: "plugin" roots. Plugin loading does not
inline skill bodies; the existing Skill tool remains the only P0 path for
loading full plugin skill content into the model context.
P2 增加:
- remote URL discovery/cache。
- admin/managed policy roots。
优先级:
- session override / configured extra roots
- nearest project native
- nearest project compatible
- ancestor project native / compatible,按目录从近到远
- user native
- user compatible
- bundled/system
- admin/managed
同名 skill 默认取高优先级项,重复项进入 diagnostics。后续如果引入 plugin namespace,可支持 plugin:skill-name。
Context 注入
ContextBuilder 增加 Skills section,位于 user/project context 之后。工具说明不再作为
ContextBuilder section 注入 system prompt,而是随 model request 的 tools 数组提供。
内容只包含 metadata,不包含正文。初始格式:
## Skills
A skill is a set of local instructions stored in SKILL.md. Use the Skill tool to load full instructions only when relevant.
### Available Skills
- my-skill: When this skill should be used (file: /abs/path/to/SKILL.md)
### How To Use Skills
- If the task matches a skill description, call Skill with the skill name before doing the task.
- If the user types `/<skill-name>`, call Skill only when that exact skill appears in the available skills list. Do not guess missing skill names.
- After loading a skill, read only the referenced files you need.
- Resolve relative references from the skill base directory.
预算策略:
- P0:默认 1% context window 或 8k chars fallback。
- 单条 description 最大 250 chars。
- 超预算时先截断 description,再降级到 names-only,并记录 diagnostic/log。
- P1:引入 root alias(用短别名代替 skill root 绝对路径),减少长绝对路径成本。
Skill Tool
工具名采用 Skill,保持与现有 Read / Write / Edit / Bash 命名风格一致。
输入:
{
"name": "my-skill",
"args": "optional user/model supplied arguments"
}
P0 输出:
<skill_content name="my-skill">
# Skill: my-skill
...SKILL.md body...
Base directory for this skill: /abs/path/to/my-skill
Relative paths in this skill are relative to this base directory.
</skill_content>
工具 metadata:
readOnly: truedestructive: falseconcurrentSafe: truesideEffectScope: "session",因为它会改变当前会话上下文。riskLevel: "low"for safe inline skills。maxOutputBytes默认 100k。timeoutMs默认 30s。
权限策略:
- P0 只实现 inline load。
- safe skill 自动允许:只含 P0 safe frontmatter 字段,且 source 是 project/user/native/compatible。
- 出现
allowed-tools、model、effort、context: fork、hooks、dependencies、remote/plugin source 时,默认 ask。 - 明确 deny 的 skill 不出现在 available skills,也不能通过 tool load。
- 权限规则应支持
Skill(my-skill)和 wildcard,例如Skill(internal-*)。
P1 行为:
allowed-tools不直接绕过权限,只作为 permission suggestion 或 scoped allow rule。model/effort通过 runtime context modifier 生效,并记录 event。context: fork等 subagent runtime 稳定后再实现。
Manual Command
P0 增加 slash command:
/skill [<skill-name> [task...]]
语义:
- 不带参数的
/skill是只读 discovery,列举当前工作目录可发现的 skills;它不创建 app/session、不加载模型、不提交 prompt,也不调用Skilltool。 <skill-name>对应SKILL.mdfrontmatter 的name。[task...]可选。存在时,表示“使用该 skill 执行这个任务”;不存在时,表示“先加载该 skill 并基于 skill 指令响应当前 turn”。- 带
<skill-name>的 command 不直接读取 skill 文件,不绕过Skilltool、permission、trace 和 session persistence。 - command-center 只把用户输入改写成显式模型指令:先调用
Skilltool 加载<skill-name>,再继续原任务。 --prompt "/skill"和 TUI 输入/skill都返回 skill 列表;--prompt "/skill <name> ..."和 TUI 输入/skill <name> ...都改写成显式 Skill tool 调用要求。
P1 可增加 $skill-name explicit mention,但 P0 先用 slash command,避免和普通自然语言混淆。
CLI Discovery Commands
当前已实现只读 CLI 命令:
zcode skills list
zcode skills inspect <name>
语义:
skills list只做本地 skill discovery,不创建 session,不加载模型,不提交 prompt,也不调用Skilltool。- 发现逻辑必须复用 bootstrap 注入的
SkillPort/Node skill adapter 契约;CLI 只负责解析子命令、格式化输出和退出码,不直接遍历 skill 目录。 - 不带子命令的
zcode skills等价于zcode skills list。 - 普通输出展示 skill name、scope/source、description 和 path,便于用户复制
<skill-name>给/skill <name>使用。 --json输出{ skills, diagnostics, totalDiscovered, cwd },其中skills保留 name、description、whenToUse、scope、source、path、directory、rootPath。--verbose在普通输出后追加 discovery diagnostics;默认普通输出不打印 warning,避免正常使用时被可恢复诊断刷屏。skills inspect <name>只做本地 discovery 加单个 skill body 读取,不创建 session、不加载模型、不提交 prompt,也不调用Skilltool。skills inspect <name>必须复用 bootstrap 注入的SkillPort/Node skill adapter 契约;CLI 只负责解析子命令、格式化输出和退出码,不直接读取SKILL.md。skills inspect <name>普通输出展示 name、scope/source、path、directory、description、whenToUse、safe-to-auto-load、size/truncation 和去掉 frontmatter 后的正文。skills inspect <name> --json输出{ cwd, skill, diagnostics },其中skill保留 metadata、baseDirectory、content、bytesRead、sizeBytes 和 truncated。skills inspect <name> --verbose在普通输出后追加 discovery diagnostics;默认普通输出不打印 warning。- 未知
skills子命令或参数数量错误返回非 0,并打印Usage: zcode skills [list|inspect <name>]。
错误行为:
- discovery adapter 抛错时向 CLI 边界冒泡,由 CLI 输出
Error: <message>;--verbose可追加 stack。 skills inspect <name>找不到 skill 时返回非 0,并输出稳定的Skill not found: <name>错误;如果 skill 功能被配置禁用,返回非 0,并输出Skills are disabled.。- 单个 skill 的 frontmatter/read 诊断不导致命令失败,按 diagnostics 返回。
- 没有发现 skill 时返回 0,并输出
No skills found.;JSON 中skills为空数组。
Config
RuntimeConfig 增加候选字段:
features.skill
skills.enabled
skills.includeInstructions
skills.metadataBudget
skills.roots
skills.compatibility.claude
skills.compatibility.agents
skills.rules
Skill 配置不声明环境变量入口。需要调整 skill 开关、兼容目录或 metadata budget 时,走 config file、CLI/session override 或更高层的运行时配置契约。
新增 ZCODE_ 环境变量必须先补齐 spec,明确用途、优先级、错误行为和测试覆盖,避免把临时实现细节扩散成长期配置面。
Config 合并仍走 system/user/project/session/env/cli 优先级,core 不读取环境变量。
Events 与 Observability
新增或复用事件语义:
SkillRootsResolvedSkillDiscoveredSkillDiscoveryWarningSkillLoadRequestedSkillLoadedSkillLoadFailed
每个事件必须携带 traceId/sessionId/turnId。日志默认不记录完整 skill 正文,只记录 name、scope、source、path hash、size、truncated、durationMs。
需要在 context diagnostics 中暴露:
- total skill count
- included skill count
- omitted skill count
- truncated description count
- duplicate names
- parse/read errors
- disabled skills
安全与跨平台约束
- 所有路径解析使用
path/url/fsadapter,不手写分隔符。 SkillPort只接受 adapter 已规范化的 absolute path 或 stable skill id。- 禁止
Skilltool 读取 skill directory 之外的文件。 - references/scripts 不自动执行。模型若要运行脚本,必须显式走
Bash/ExecutionPort和权限。 - symlink 需要 canonical identity 去重;路径显示可保留用户可读路径。
- Windows 上要处理大小写、反斜杠、路径长度和权限错误。
- 大正文超出
maxOutputBytes时返回截断摘要和 diagnostic,后续进入 artifact/storage。
分阶段计划
Phase 0:Spec 与测试骨架
Status: completed. 本文档、contract 边界和 CLI/core/adapter 测试骨架已经存在。
- 新增本文档。
- 为 skill contract 设计测试样例 fixture。
- 明确 P0/P1/P2 字段边界。
验收:
- 文档覆盖设计要点与取舍结论。
- 后续实现任务可以按 contract 拆分。
Phase 1:Contracts
Status: completed for P0. packages/contracts/src/skills/index.ts 和 packages/contracts/src/tools/skill.ts 已提供共享类型、运行时 schema、provider JSON schema 和 diagnostics/error code;更细粒度 policy / dependency 字段仍保留为后续扩展。
- 在
packages/contracts/src/skills增加 skill schema/type。 - 给
RuntimeConfig增加最小 skills 配置。 - 增加 skill diagnostics/error code。
验收:
contracts类型可被 core/adapters/bootstrap 单独引用。- schema 覆盖 invalid frontmatter、duplicate、disabled、too large。
Phase 2:Adapter Loader
Status: completed for P0. Node loader 已支持 native/compatible project 与 user roots、extra roots、从 cwd 向上到 worktree root 的 project discovery、frontmatter diagnostics、重复名优先级、正文截断和取消前检查;symlink canonical 去重、remote/cache 和 plugin roots 尚未实现。
- 在
packages/adapters/src/skills实现 Node loader。 - 支持 P0 roots 和 frontmatter。
- 支持 max bytes、canonical path、diagnostics。
验收:
- adapter 单测覆盖 project/user/compat roots、重复 name、无权限、symlink、invalid YAML。
- 不引入 core 依赖。
Phase 3:Core Context 与 Registry
Status: completed for P0. ContextBuilder 已把 available skills 渲染为独立 meta_user section,内置 registry 已注册 Skill tool,并允许在没有 SkillPort 时省略该 tool;session 级 loaded-skill snapshot 和 compact 恢复仍未实现。
- core 增加
SkillRegistry/SkillManager。 ContextBuilder渲染 Skills section。- context diagnostics 记录预算与截断。
验收:
- fake skill snapshot 能渲染到 system prompt。
- 超预算不会丢失所有 skill name。
- core 仍不 import Node I/O。
Phase 4:Skill Tool
Status: completed for P0 inline load. Tool handler 已通过 SkillPort 读取正文并返回 <skill_content>,声明 output schema、result budget、timeout、取消和 trace 传播;按 skill name/policy 动态审批、unsafe frontmatter ask、runtime modifier 和 fork context 尚未实现。
- 注册
Skilltool。 - tool 通过
SkillPort加载正文。 - tool result 注入 message history。
- permission service 支持 skill pattern。
验收:
- fake model 调用
Skill后,下一轮 model 能看到 skill body。 - deny rule 下 skill 不出现在 available skills,直接调用也失败。
- unsafe frontmatter 走 ask,safe inline skill 自动 allow。
Phase 5:CLI/TUI
Status: partially completed. zcode skills / zcode skills list、zcode skills inspect <name>、--json、--verbose diagnostics、TUI/command-center 裸 /skill list、/skill <name> [task] prompt rewrite、ZCode app-server /skill <name> [task] 已实现。TUI/debug diagnostics projection 尚未实现。
zcode skills list:已实现,只读 discovery,不启动模型/session。zcode skills inspect <name>:已实现,只读 discovery 加正文读取,不启动模型/session,CLI 不直接读取SKILL.md。- TUI/debug projection 显示 skill discovery diagnostics。
验收:
- CLI 输出支持
--json。 - 错误包含 traceId 或 diagnostic code。
Phase 6:Advanced
- root alias 渲染。
- explicit mention:
$skill-name和skill://.../SKILL.md。 - bundled/system skills。
- plugin skill roots。
- skill dependency/env prompt。
- forked skill。
- remote URL discovery/cache。
推荐提交拆分
docs: add skill integration planrefactor(contracts): add skill contractsfeat(adapters): add node skill loaderfeat(core): render available skills in contextfeat(tool): add Skill toolfeat(permission): support skill permission rulesfeat(cli): add skills commandstest: add skill boundary coverage
暂不做
- 不在 P0 实现远程 skill 下载。
- 不在 P0 执行 skill scripts。
- 不在 P0 自动修改 tool allowlist。
- 不在 P0 实现 forked skill。
- 不在 P0 把 skill 和 slash command 合流。
04 同仓库更多 Skills
plugin-mcp-ping
E2E workspace Plugin skill marker
zcode-configuration-guide
Use when configuring ZCode's extension resources (MCP servers, slash commands, skills, hooks, and plugins) or instruction files such as AGENTS.md in the ZCode client. Explains where each resource is configured at the user and workspace scope, the discovery order, precedence, and merge rules, plus guidance on which location to choose. Use when someone asks how to add an MCP server, command, skill, hook, plugin, or AGENTS.md instructions, where a configuration file lives, why a configuration is not taking effect, or needs routing to a specific diagnostic skill.
diagnosing-skills
Use to diagnose and fix ZCode skill configuration problems in the ZCode client. Applies when a skill is not discovered, is installed but does not trigger automatically, is shadowed by a higher-precedence skill of the same name, is disabled by configuration, has a SKILL.md frontmatter error, fails to load because its description is too long, or disappears because the plugin providing it is disabled. Provides the discovery order, how to inspect skills in the client, common pitfalls, and a step-by-step localization and repair workflow.
diagnosing-plugins
Use to diagnose and fix ZCode plugin and marketplace problems in the ZCode client. Applies when a plugin is not listed, adding a marketplace or installing a plugin fails, a plugin is enabled but its skills or commands are missing, a built-in plugin still appears after being disabled, a plugin is not enabled as expected, a plugin.json manifest has a parse error, a plugin name is invalid, a dependency is unresolved or blocked across marketplaces, or a sensitive configuration value cannot be entered in the interface. Provides the plugin lifecycle, manifest schema, how to manage plugins in the client, and a step-by-step localization and repair workflow.
diagnosing-mcp
Use to diagnose and fix ZCode MCP (Model Context Protocol) server configuration problems in the ZCode client. Applies when an MCP server will not connect, its tools (mcp__server__tool) do not appear, it shows as disabled or failed, connections time out, a command cannot be found, template variables are not expanded, or a server defined in a configuration file has no effect. Provides configuration locations, how to inspect status in Settings, common pitfalls, and a step-by-step localization and repair workflow.
diagnosing-hooks
Use to diagnose and fix ZCode hook configuration problems in the ZCode client. Applies when a hook does not trigger, an event name is wrong, a matcher does not match a tool name, a script is not executable, template variables are not expanded, a timeout unit is mistaken (seconds versus milliseconds), the command and process field styles are mixed, a hook's JSON output fails validation, a hook blocks the session unexpectedly, or configuration-file hooks are not enabled. Provides configuration sources, the hooks.json schema, how to inspect hooks in the client, and a step-by-step localization and repair workflow.