技能放置与来源策略¶

本文档定义了生成、导入和精选技能应放置的位置、如何识别它们，以及哪些内容会被发布。

技能类型与放置¶

精选技能位于仓库的 skills/ 目录下。安装清单仅引用精选路径。生成和导入的技能位于用户主目录下，且永远不会被发布。

精选技能¶

位置：skills/<skill-name>/，根目录包含 SKILL.md。

• 包含在 manifests/install-modules.json 的路径中。
• 由 scripts/ci/validate-skills.js 验证。
• 无来源文件。在 SKILL.md frontmatter 中使用 origin（ECC、community）进行归属说明。

学习技能¶

位置：~/.claude/skills/learned/<skill-name>/。

由 continuous-learning（evaluate-session 钩子、/learn 命令）创建。默认路径可通过 skills/continuous-learning/config.json → learned_skills_path 配置。

• 不在仓库中。不发布。
• 必须包含与 SKILL.md 同级的 .provenance.json。
• 当目录存在时，在运行时加载。

导入技能¶

位置：~/.claude/skills/imported/<skill-name>/。

来自外部来源（URL、文件复制等）的用户安装技能。目前尚不存在自动导入器；放置位置遵循约定。

• 不在仓库中。不发布。
• 必须包含与 SKILL.md 同级的 .provenance.json。

演化技能（持续学习 v2）¶

位置：~/.claude/homunculus/evolved/skills/（全局）或 ~/.claude/homunculus/projects/<hash>/evolved/skills/（按项目）。

由 instinct-cli evolve 从聚类本能生成。与学习/导入系统是相互独立的。

• 不在仓库中。不发布。
• 来源继承自源本能；无需单独的 .provenance.json。

来源元数据¶

学习技能和导入技能需要。文件：技能目录中的 .provenance.json。

必需字段：

模式：schemas/provenance.schema.json。验证：scripts/lib/skill-evolution/provenance.js → validateProvenance。

验证器行为¶

validate-skills.js¶

范围：仅精选技能（仓库中的 skills/）。

• 如果 skills/ 不存在：退出 0（没有需要验证的内容）。
• 对于每个子目录：必须包含非空的 SKILL.md。
• 不触及学习/导入/演化根目录。

validate-install-manifests.js¶

范围：仅精选路径。模块中的所有 paths 必须存在于仓库中。

• 生成/导入根目录不在范围内。清单不引用它们。
• 路径缺失 → 错误。没有可选路径处理。

使用生成根目录的脚本¶

scripts/skills-health.js、scripts/lib/skill-evolution/health.js、会话钩子：它们会探测 ~/.claude/skills/learned 和 ~/.claude/skills/imported。缺失的目录被视为空目录；不报错。

可发布与仅限本地¶

只有精选技能会出现在安装清单中，并在安装期间被复制。

实施路线图¶

1. 策略文档和来源模式（本次更改）。
2. 为学习技能写入路径（evaluate-session、/learn 输出）添加来源验证，使新的学习技能始终获得 .provenance.json。
3. 更新 instinct-cli evolve，在生成演化技能时写入可选来源信息。
4. 如需要，将 scripts/validate-provenance.js 添加到 CI，用于任何不得包含学习/导入内容的仓库路径。
5. 在 CONTRIBUTING.md 或用户文档中记录学习/导入根目录，以便贡献者知道不要提交它们。