跳转至

2026-07-02

今日主题

  • Skills CLI skill 发现与过滤

新增认知

Skills CLI skill 发现与过滤

  • 脉络：梳理了 skills CLI 从 GitHub 仓库发现 skill 的完整流程——
    discoverSkills() 会扫描 .claude/skills/、.agents/skills/ 等 agent 项目目录。
    现有过滤 isInstalledProjectSkill() 依赖源仓库存在 skills-lock.json，但大多数 skill 源码仓库不会维护它，
    导致形同虚设。正确的方案是 metadata.internal: true，这是 SKILL.md frontmatter 层面的标记，不依赖外部文件。

  • metadata.internal 隐藏自用 skill：
    在 SKILL.md 的 YAML frontmatter 中设置 metadata.internal: true，
    该 skill 就不会被 skills add 发现和安装，
    除非用户显式设置 INSTALL_INTERNAL_SKILLS=1 或用 @skill-name 语法精确指定。
    这是 skills.ts:84-87 已有的机制，不依赖仓库内的 lock 文件，是最干净的方案。
    已在 yungyu/notes 的 rollup-notes skill 上验证可行。

  • AGENT_PROJECT_SKILL_DIRS 列表：
    skills.ts:11-35 定义了 23 个会被扫描的 agent 项目目录（如 .claude/skills/、.agents/skills/、.codex/skills/ 等）。
    这些目录下的 skill 在发现时会被检查是否在 isInstalledProjectSkill 列表中，但该检查依赖 skills-lock.json，
    实际很少生效。

  • 容器目录深度遍历规则：
    skills.ts:224 中 deepContainerDirs 集合使 skills/、agent 项目目录等容器目录多走一层深度，
    以支持 skills///SKILL.md 的目录布局。根目录只走一层，
    避免意外发现 examples/foo/SKILL.md 等无关文件。