Wiki AI

ZCode Skills 系统

5分钟阅读

一个 ZCode skill = 一个含 SKILL.md 的目录，frontmatter 至少 name + description，可选 references/、scripts/、assets/。规范见 skill-creator-plugin/skills/skill-creator/SKILL.md 与 docs/skills-product.md。

发现目录与优先级

skill-creator/SKILL.md:41-48 给出优先级：

<project>/.zcode/skills/<name>/SKILL.md   ← 最高
<project>/.agents/skills/<name>/SKILL.md
~/.zcode/skills/<name>/SKILL.md
~/.agents/skills/<name>/SKILL.md          ← 最低（与其它工具共享位置）

实现 adapters/src/skills/roots.ts 的 resolveDefaultSkillRoots()：

  • workspace skills 从 workingDirectory 沿 git worktree 根逐级向上遍历，每层都合并 .zcode/skills 与 .agents/skills（同层 .zcode 优先），而不是找到 .zcode/skills 就跳过 .agents。
  • 优先级：extraRoots（project）→ user → project 各级 → extraResolvedRoots。
  • 含 ~/ 展开与相对路径处理。

扫描实现：packages/services/src/skills/skillDiscoveryWalk.ts（深度优先、跳过 node_modules 与点目录、限制深度、软链 realpath 去重）；CLI 侧对应 adapters/src/skills/scan.ts。扫描策略常量收敛在 @zcode/shared，桌面与 agent 端共用。

加载（NodeSkillAdapter）

adapters/src/skills/index.ts：

  • 渐进披露三层：元数据（name+description）始终在 context → SKILL.md body 命中后才加载 → references/scripts/assets 按需读取。
  • discoverSkills()：解析每个 SKILL.md 的 frontmatter，产出 SkillMetadata；按路径去重，路径才是安装项身份（同名不同路径并存）。
  • parseSkill()：无 frontmatter 时按目录名加载；description 上限 1024；safeToAutoLoad 仅在 frontmatter key 全属 {name, description, when_to_use, license, metadata} 时为 true。
  • 插件贡献的 skill 加限定名 <plugin>:<skill>，向上最多 5 层找 .zcode-plugin/.claude-plugin/.codex-plugin/.cursor-plugin/plugin.json 解析 pluginName。
  • 禁用：disabledPaths（config.json 的 skill.<path>.enable=false），动态工作流灰度即用此机制。
  • 技能门控：CreateWorkflow/AmendWorkflow/FillWorkflowHole/SaveWorkflow/EvalWorkflowSnippet 在 dynamic-workflows 技能加载前拒绝运行。

bundled-skills（系统内置技能包）

apps/zcode-cli/packages/bundled-skills/（无 package.json，仅 README.md + skills/）：

  • 不是插件：不进官方市场、无启停、不可卸载、不出现在设置页与 $ 引用面板。
  • 作为 source:"bundled", scope:"system" 的技能根被每会话发现。
  • 当前唯一技能：dynamic-workflows（SKILL.md + patterns.md + examples.md），服务 CreateWorkflow。详见 dynamic-workflow。
  • 三种运行形态：dev/Electron 原地读取；SEA 二进制内嵌到 zcode-bundled-skills/ 前缀，首启按内容 hash 解压到 ~/.zcode/cli/bundled-skills/<hash>/；远端由 prepare-prebuilds.mjs stage 到远端 zcode.cjs 旁。
  • 解析器 bootstrap/src/app/bundled-skills.ts：BUNDLED_SKILL_ROOT_PRIORITY = 1_000_000（排所有插件根之后，用户/项目/插件同名技能可覆盖）。

skill-creator-plugin

提供 skill-creator 技能（SKILL.md 159 行），“创作-试用-迭代”循环：捕获意图 → 撰写 SKILL.md → 2–3 个真实测试 prompt → 与用户一起看输出 → 改进 → 循环。要点：description 是主触发信号（“write descriptions a little bit pushy”）、渐进披露、避免 ALL-CAPS 硬规则、把重复 helper 脚本沉淀到 scripts/。当前 ZCode 不并行 spawn 评测 subagent。

.agents/skills/（仓库根）

ZCode 自身开发用的 workspace 技能目录（同时被运行时发现），共 10 个：agent-browser、ai-elements、architecture-governance、dep-refs、dogfood、e2e-case-lifecycle、electron、feature-boundary-planner、react-best-practices、zcode-large-task-fixture。CLI 子目录另有 apps/zcode-cli/.agents/skills/（opentui、vercel-react-best-practices、vercel-react-view-transitions）。

skills-lock.json 锁定其中 4 个外部技能来源与内容 hash：agent-browser、ai-elements、dogfood（均 vercel-labs/agent-browser 或 vercel/ai-elements）+ electron。

ZCode skill vs Claude Code skill

维度ZCodeClaude Code
Manifest.zcode-plugin/plugin.json（兼容 .claude-plugin / .codex-plugin / .cursor-plugin）.claude-plugin/plugin.json
目录.zcode/skills + .agents/skills（workspace/user 双层，逐级向上合并）.claude/skills 等
限定名插件技能为 <plugin>:<skill>无此限定
frontmattername/description 必填；when_to_use/license/metadata 白名单内才 safeToAutoLoadname/description 为主
发现策略与桌面端共用 @zcode/shared 扫描策略各自实现
导入设置页”从外部 Agent 导入”支持 16 个来源（Claude/Codex/OpenCode/OpenClaw/Augment/Continue/Goose/Qwen/Trae/Kiro/Roo/CodeBuddy…），软链或复制无对应
内置技能bundled-skills 不可卸载、不进市场无此机制
商店官方市场 + CDN zip + Personal SourceMarketplace 机制不同

safeToAutoLoad 的保守判断意味着带扩展 frontmatter 的旧技能仍可加载但不自动注入。

相关页面

关系图谱

反向链接