[建议 / Feature] ZCode Skill 发现机制问题反馈：不支持嵌套目录

[YunQuanya]

提交前确认 · Pre-submission checklist

• 我已搜索过现有 issue，确认这不是重复提议 / I searched existing issues and confirmed this isn't a duplicate.
• 我已阅读 CONTRIBUTING.md / I've read CONTRIBUTING.md.

问题类别 · Category

其他 / 不确定 · Other / Not sure

涉及的 Agent 框架 · Agent framework

ZCode Agent（自研）

使用场景 · Use case

ZCode Skill 发现机制问题反馈：不支持嵌套目录

反馈日期：2026-07-21
反馈类型：产品体验 / 兼容性
影响范围：所有从 Codex 迁移、或按 Codex 布局组织 skills 的用户

---

一、问题现象

ZCode 无法发现放在二级及更深目录下的 skill，导致用户本机已有的大量 skill 完全不可见。

具体表现：

• 用户在本机按 Codex 标准布局组织了 100+ 个 skill，路径为 ~/.agents/skills/skills/<skill-name>/SKILL.md
• ZCode 会话启动时，系统注入的"可用 skills 清单"里只出现 3 个一级 skill（find-skills、graphify、hatch-pet），二级 skills/ 子目录下的 99 个 skill 全部缺失
• 典型案例：commit-message-generator（提交信息生成）这个高频 skill 已安装但不可用，用户每次生成 commit message 都被迫手工走流程，或要求 AI 临场补救

---

二、根因

ZCode 的 skills 发现逻辑只扫描根目录的一级子目录，不递归。

对比 Codex 的行为（实测）：

# Codex 用整体软链指向 ~/.agents/skills，能递归发现所有 skill
~/.codex/skills → /Users/hy/.agents/skills

# Codex 看到的结构（递归扫描，全部可见）
~/.agents/skills/
├── find-skills/                    ✅ Codex 发现
├── graphify/                       ✅ Codex 发现
├── hatch-pet/                      ✅ Codex 发现
└── skills/                         📁 容器目录
    ├── 提交信息生成 commit-message-generator/   ✅ Codex 发现（递归到二级）
    ├── ajax错误信息提示 ajax-error-message/      ✅ Codex 发现
    └── ... (共 99 个)               ✅ Codex 发现

# ZCode 同样布局，只扫一级
~/.zcode/skills/  或  ~/.agents/skills/

# ZCode 看到的结构（仅一级）
├── find-skills/                    ✅ ZCode 发现
├── graphify/                       ✅ ZCode 发现
├── hatch-pet/                      ✅ ZCode 发现
└── skills/                         ❌ ZCode 当作单个 skill 处理
    └── (99 个 skill 全部不可见)

zcode-guide:diagnosing-skills 的官方诊断文档也明确写了："Directories beginning with . ... are skipped" 以及"扫描根目录的一级子目录"，但没有说明为什么不递归，也没有提供配置项绕过。

---

三、用户侧的临时绕过方案（不推荐长期使用）

目前用户只能手动在 ZCode 标准路径下为每个 skill 建软链：

# 为单个 skill 建软链
ln -s ~/.agents/skills/skills/<skill-name> ~/.zcode/skills/<skill-name>

# 批量建（脚本）
for d in ~/.agents/skills/skills/*/; do
  name=$(basename "$d")
  ln -sfn "$d" ~/.zcode/skills/"$name"
done

问题：

• 99 个 skill 就要建 99 个软链，目录污染严重
• 用户新增 skill 后必须重跑脚本，容易遗忘
• 软链在某些同步工具（iCloud、Dropbox）下行为异常
• 跨机器迁移配置时容易丢失软链

---

---

建议方案 · Proposal

四、建议的产品侧解决方案（任选其一）

方案 A（推荐）：支持递归扫描，对齐 Codex

修改 skills 发现逻辑，递归扫描根目录下所有层级的 SKILL.md。

• 优点：零配置，Codex 现有布局直接可用，迁移用户无感
• 风险：需要注意同名 skill 的优先级（深层 vs 浅层谁覆盖），建议"浅层优先"以保持向后兼容
• 建议优先级：高

方案 B：支持 extraRoots 配置项

在 ~/.zcode/cli/config.json 或 ~/.zcode/v2/config.json 中增加 skills.roots 数组：

{
  "skills": {
    "enabled": true,
    "roots": [
      "~/.agents/skills/skills",
      "~/my-team-skills"
    ]
  }
}

• 优点：用户可精确控制额外扫描路径，灵活
• 缺点：需要用户手动维护配置
• 建议优先级：中

方案 C：提供内置命令批量建软链

新增 /skill link <path> 命令，自动为指定路径下所有 skill 在 ~/.zcode/skills/ 建软链。

• 优点：实现成本低
• 缺点：治标不治本，软链本身有上述维护问题
• 建议优先级：低（作为过渡方案）

预期价值 · Expected value

五、期望的最终效果

用户从 Codex 迁移到 ZCode 后，无需调整 skill 目录结构、无需建软链、无需改配置，原有 ~/.agents/skills/ 下的所有 skill（含嵌套目录）自动被 ZCode 发现并可用。

---

六、复现步骤（供开发同学验证）

1. 准备一个 skill 放在二级目录：

   ~/.agents/skills/
   └── my-group/                    ← 容器目录（无 SKILL.md）
       └── test-skill/              ← 真正的 skill
           └── SKILL.md             ← 有合法 frontmatter
   

2. 启动 ZCode 新会话

3. 检查系统注入的可用 skills 清单：test-skill 不会出现

4. 对照测试：同样的布局在 Codex 中，test-skill 会出现

---

七、相关参考

• ZCode 官方诊断文档：zcode-guide:diagnosing-skills skill（明确写"只扫一级子目录"）
• Codex 行为：实测 ~/.codex/skills 整体软链到 ~/.agents/skills 可递归发现
• 本次实际问题记录：用户会话中 commit-message-generator skill 缺失，被迫人工生成提交信息

你认为的优先级 · Your perceived priority

None

你使用的 ZCode 版本 / 环境 · ZCode version / environment

zcode桌面版3.3.6 macOs：15.3.1

补充材料 · Additional context

No response

[github-actions]

👋 感谢你的反馈，我们已经收到。

• 维护者会在 3 个工作日内 给出首次响应。
• 状态保持为 status: 待评估，你可以随时补充信息。
• 信息不全时我们会打上 needs: 更多信息 标签并 @ 你。

---

👋 Thanks — we've received your issue.

• A maintainer will respond within 3 business days.
• Status stays at status: 待评估 (Triage); feel free to add context.
• If we need more details, we'll add needs: 更多信息 and ping you.