`skills/` 的四个分区：core / creative / meta / pipelines 各管什么

翻 OpenMontage 的时候，最容易卡住的一步不是安装，是「我该去读哪个 Markdown」。仓库把智能放在文本里，skills/ 下光 .md 就有 156 个，第一次点进去只会看到四个文件夹和一份 INDEX.md，很难判断该从哪里开始。

这四个文件夹的分法其实是有逻辑的，而且这个逻辑在流水线 manifest 里能对上号。

先搞清楚 skills/ 在整个知识体系里的位置

README 把知识分成三层，原文是这么写的：Layer 1 是 tools/ 加 pipeline_defs/，回答「有什么」——可执行的能力加编排；Layer 2 是 skills/，回答「怎么用」，也就是 OpenMontage 自己的约定和质量标准；Layer 3 是 .agents/skills/，回答「这项技术本身是怎么回事」，是外部技术的知识包。README 还说，每个工具都会声明它依赖哪些 Layer 3 skill。

这个划分决定了两个目录的性质完全不同。我们实读目录数出来：skills/ 下 156 个 .md，.agents/ 下 567 个 .md，相加 723 个，和 README 自称的 “700+ agent skill and production-knowledge files” 对得上；整个仓库的 .md 文件共 1084 个。也就是说，体量大头在 Layer 3 的外部技术知识包里，而 skills/ 这 156 个是这个项目自己的规矩。

先说一句边界：下面所有内容只到文件名为止。除了本文明确引用的 manifest 字段，这些 skill 文件的正文我们都没有读过，本文不会描述任何一个 skill 里具体写了什么。

四个分区，按实读的文件清单看

core/，6 个：color-grading.md、ffmpeg.md、hyperframes.md、remotion.md、subtitle-sync.md、whisperx.md。README 的架构图里给它的标注是 “Core tool skills”。从文件名能看出这一层对着的是具体技术栈：两套合成运行时（Remotion、HyperFrames）、后期与转码（FFmpeg）、转写（WhisperX）、调色、字幕对齐。这 6 个名字覆盖的是「片子最后怎么被做出来」这一段。

creative/，实读列出 29 个 .md 加一个 prompting/ 子目录。这一区里能按名字看出几个族：叙事与视觉技法有 storytelling.md、typography.md、cinematic.md、data-visualization.md、sound-design.md；长短片形态有 long-form.md、short-form.md；成组的 *-usage.md 明显对着某类工具的用法，比如 image-gen-usage.md、music-gen-usage.md、upscale-usage.md、lip-sync-usage.md、scene-detect-usage.md、stock-sourcing-usage.md；还有 video-gen-prompting.md、broll-planning.md、animation-pipeline.md、video-stitching.md、ink-theater.md 这些。prompting/ 子目录我们只知道它存在。

这里有一处可以自己核的对应关系：skills/creative/ink-theater.md 这个文件名，与仓库根目录下的 ink-theater/、以及 AGENT_GUIDE.md 里 Style Playbooks 一节下那个子标题 “Hand-drawn ‘doodle’ animation → Ink Theater / Ink Puppet” 是同一条线。目录、skill、契约标题三处的名字能对上。这三处的内部实现和正文我们都没读过，只说到名字对得上为止。

meta/，11 个：animation-runtime-selector.md、bespoke-composition.md、capability-extension.md、checkpoint-protocol.md、creative-intake.md、onboarding.md、reviewer.md、skill-creator.md、taste-direction.md、video-reference-analyst.md、voice-performance-director.md。README 给这一区的标注是 reviewer 与 checkpoint protocol。

meta 是四个分区里最值得多看两眼的：它管的不是「怎么做片子」，而是「这套流程本身怎么运转」。把这 11 个文件名和 AGENT_GUIDE.md 的章节标题并排放，能看出不少同名对应——契约里有 “First Interaction — Onboarding”、“Reviewer Protocol”、“Human Checkpoint Protocol”、“Reference Video Entry Point”，meta/ 里就分别躺着 onboarding.md、reviewer.md、checkpoint-protocol.md、video-reference-analyst.md。同样只说名字层面的对应，各节正文我们没有读过。

pipelines/，12 个子目录：animation、avatar-spokesperson、character-animation、cinematic、clip-factory、documentary-montage、explainer、hybrid、localization-dub、podcast-repurpose、screen-demo、talking-head。这一区一条流水线一个目录，README 的标注是 per-pipeline stage director skills，也就是每个阶段的导演 skill 放在这儿。

最后还有一份 skills/INDEX.md。

落到硬锚点：manifest 是怎么引用这四个分区的

上面这套分类，如果只看目录，很容易觉得是一种整理癖。真正让它变成结构的，是流水线 manifest 里的字段。

我们读了 pipeline_defs/documentary-montage.yaml 的前 70 行，它有一段 required_skills，是逐条写死的：

required_skills:
  - pipelines/documentary-montage/executive-producer
  - pipelines/documentary-montage/idea-director
  - pipelines/documentary-montage/scene-director
  - pipelines/documentary-montage/asset-director
  - pipelines/documentary-montage/edit-director
  - pipelines/documentary-montage/compose-director
  - meta/reviewer
  - meta/checkpoint-protocol

8 个必需 skill：1 个执行制片，加 idea / scene / asset / edit / compose 五个阶段导演，再加 meta/ 里的 reviewer 和 checkpoint-protocol。这就是分区的实际用法——pipelines/ 提供这条流水线专属的阶段指令，meta/ 提供跨流水线复用的评审与 checkpoint 协议，两者在同一份依赖清单里并列出现。

再往下，每个阶段自己也带 skill 字段。第一个阶段是这样：

stages:
  - name: idea
    skill: pipelines/documentary-montage/idea-director
    produces:
      - brief
    tools_available: []
    checkpoint_required: true
    human_approval_default: true
    # 这个阶段下面还有 review_focus 与 success_criteria 两段，此处略

这一个阶段用到的字段，基本就是 manifest 的阶段 schema：name、skill、produces（这个阶段产出哪个 artifact）、tools_available、checkpoint_required、human_approval_default，再加上面省略掉的 review_focus 与 success_criteria；后面的阶段还会出现 required_artifacts_in，比如第二个阶段 scene_plan 的 required_artifacts_in 里写的就是 brief——阶段之间靠 artifact 名字串起来，前一个阶段 produces 什么，后一个阶段就 required_artifacts_in 什么。

回到路径写法：pipelines/documentary-montage/idea-director，前缀就是 skills/ 下的分区名，相对的根由 config.yaml 里的 skills_dir: skills 指定。换句话说，四个分区名不是给人看的分类标签，它们是 manifest 里的路径前缀。

顺带一提这个阶段本身的两个硬事实：tools_available 是空数组 []，idea 阶段不调任何工具；checkpoint_required: true 且 human_approval_default: true，第一个阶段就要人批。

同一份 manifest 里还有两处和 skill 直接相关。一处是 orchestration 段，mode 是 executive-producer，紧跟的 skill 字段写的是 pipelines/documentary-montage/executive-producer——和 required_skills 的第一条完全一致，编排层自己也是靠一份 skill 驱动的。另一处是 extensions 段的四个开关：custom_scripts、custom_playbooks、custom_skills 都是 true，只有 custom_tools 是 false。也就是说这条流水线明确允许你往 skill 这一层加东西，却把自定义工具关掉了——想扩展它，动的应该是 Markdown 而不是 Python。

AGENT_GUIDE.md 的 Rule Zero 把路径规则又说了一遍，措辞更硬：agent 必须逐阶段执行，且在该阶段做任何工作之前先读 skills/pipelines/<pipeline>/<stage>-director.md；调任何带 agent_skills 字段的工具之前，先读 .agents/skills/ 里被引用的 skill。这两条路径正好把 Layer 2 和 Layer 3 的边界划开了：阶段级的指令去 skills/pipelines/ 找，工具级的技术知识去 .agents/skills/ 找。

契约的 Do NOT 里也有对应的两条：不许在没读阶段导演 skill 之前就生成素材，不许在没读 Layer 3 skill 的情况下调生成类工具。得说清楚，这些都是写给模型看的约束文本，是指令不是工程保障——写了「必须先读」，不等于你的 agent 一定会读。

pipelines/ 这一区的几处命名要对着看

如果你打算按流水线名去找 skill 目录，有几处得先知道，不然会找空。

我们数出来的三组数字并不整齐：pipeline_defs/ 下有 13 个 .yaml，skills/pipelines/ 下有 12 个子目录，而 README 的流水线表格是 11 行、正文另一处写的是 “12 production pipelines”。

逐条对下来能看清差在哪：pipeline_defs/ 那 13 个里有一个 framework-smoke.yaml，看名字是冒烟测试用的，不在 README 表里，skills/pipelines/ 下也没有同名目录；character-animation 在 pipeline_defs/ 和 skills/pipelines/ 里都有，但不在 README 的表格里（README 别处提到过这条流水线的 SVG/GSAP rig 输出）；还有一处命名不完全一致——manifest 叫 animated-explainer.yaml，对应的 skill 目录名却是 explainer。去掉 framework-smoke 后是 12 条，与 skills/pipelines/ 的 12 个目录、以及 README 正文的 “12 production pipelines” 吻合。

这些差异我只陈述，不推断哪个写法是对的、也不拿它评价这个项目。对你的实际影响只有一条：按 manifest 文件名去 skills/pipelines/ 下找目录，可能对不上，animated-explainer 就是个现成的例子。

那么该怎么用这份分区

给三个具体场景。

你想搞明白某条流水线怎么走，去 skills/pipelines/<流水线名>/，同时把它的 pipeline_defs/<流水线名>.yaml 打开对照——manifest 的 required_skills 会直接告诉你这条线依赖哪几份 skill，不用猜。注意目录名可能和 manifest 名不一致。

你想知道某个工具的用法约定，先在 creative/ 里按 *-usage.md 这个命名找；如果你要的是技术本身怎么回事，那不在 skills/ 里，在 .agents/skills/。

你要加东西。README 给的路径是：加一条新流水线三步——在 pipeline_defs/ 建 YAML manifest、在 skills/pipelines/<your-pipeline>/ 建阶段导演 skill、引用既有工具或按需新增；加一个新工具四步——在 tools/ 相应子目录下建 Python 文件、继承 BaseTool 并实现工具契约、registry 自动发现不需要手动注册、若工具需要使用指导再加一个 skill 文件。可以看出加流水线必须动 skills/pipelines/，而加工具时 skill 是可选的一步。

最后提醒一句边界。skills/ 里放的是 Markdown 指令，不是可执行代码；这个仓库的设计前提是没有代码编排器，编排由你的 AI 编码助手完成。所以这四个分区的价值取决于 agent 是否真的按 Rule Zero 去读它们，这一点仓库无法替你保证。另外，这些 skill 文件的正文我们一份都没读过，本文只到文件名与 manifest 字段这一层。

---

本文依据 OpenMontage 官方仓库（github.com/calesthio/OpenMontage）的 README、 AGENT_GUIDE.md、config.yaml、pipeline_defs/ 与 lib/ 下的治理模块整理，核对日 2026-08-09。 本文内容为仓库源码与文档口径，我们没有安装或运行过该系统，也没有调用过其中任何一个 provider API， 文中出现的成本数字均为项目方在 README 中自行标注的金额，非我们的实测结果。 该项目以 AGPL-3.0 发布，部分流水线在 manifest 中自标 stability: beta，请以仓库最新内容为准。