把仓库翻了个底朝天:它凭什么敢按「工作流」而不是「工具」分目录

原创2026-10-29 20:17:561,755 阅读

把仓库翻了个底朝天:它凭什么敢按「工作流」而不是「工具」分目录

大多数 Agent 技能仓库的目录长这样:pdf/、excel/、github/、notion/、browser/。按工具切,按集成切,按"我能连上什么"切。这是最省事的分法,因为每加一个工具就多一个文件夹,互不打扰。

BAMA 走的不是这条路。它把 21 个技能塞进 start、plan、code、design、ship 五个目录,然后用一句"idea -> research -> clone -> app-brief -> user-stories -> new-mac-app -> ..."把所有技能串成一条线。

这篇文章想回答的问题很具体:这套目录结构的信息到底藏在哪几层文件里,跨技能的依赖靠什么声明,以及这种组织方式到底付出了什么代价。所有结论都来自仓库里的真实文件,不做推测性美化。

BAMA 项目 banner:标题为 Build Any Mac App,下方是 Swift 6.2、SwiftUI、SwiftData、Liquid Glass、Local data 五个标签,底部一排应用图标

目录分层:五个文件夹回答的是"这是哪一类问题"

先看事实。仓库根目录下 skills/ 有五个一级子目录,共 21 个 SKILL.md:

阶段目录 技能数 内容
skills/start 3 bama(路由器)、app-brief、new-mac-app
skills/plan 3 research、clone、user-stories
skills/code 5 swift-swiftui、os-integrations、performance、improve-architecture、agent-cli
skills/design 7 ux-design、mac-design、design-system、layout-grid、design-kit、design-from-app、app-icon
skills/ship 3 build-and-verify、test-mac-app、improve-loop

这 21 个技能一共 2649 行 SKILL.md,加上同目录下的参考文件(patterns.md、recipes.md、parts.md、accessibility.md 等)3692 行,整个 skills/ 目录 103 个文件。平均一个技能的正文约 126 行,这是一个刻意压过的数字:正文超过这个量级,agent 就会开始在长文里丢条件。

关键在于,这五层不是按"工具"切的,而是按"当前缺什么"切的。swift-swiftui 里没有一句"使用 Xcode",performance 里没有一句"打开 Instruments 界面",因为它们要回答的不是"用哪个工具",而是"写 Swift 时哪里会错""卡顿该按什么顺序排查"。工具的对应关系被下沉到了具体的命令里,而命令属于正文细节,不属于目录语义。

这也解释了一个容易被忽略的现象:start 里放着三个时间上并不相邻的东西。路由器 bama 是入口,app-brief 是写简报,new-mac-app 是搭建脚手架。它们之间隔着整个 plan 阶段。所以五层目录描述的不是"第几步",而是"这件事在哪一层被解决"。

登记顺序暴露了真实意图

如果只看磁盘,你会以为 start -> plan -> code -> design -> ship 就是执行顺序。但 .claude-plugin/plugin.json 里的 skills 数组被打乱了:

"skills": [
  "./skills/start/bama",
  "./skills/plan/research",
  "./skills/plan/clone",
  "./skills/start/app-brief",
  "./skills/plan/user-stories",
  "./skills/start/new-mac-app",
  "./skills/code/swift-swiftui",
  ...
]

start/app-brief 被插在 plan/clone 之后,start/new-mac-app 被插在 plan/user-stories 之后。这不是手滑,这是在按 skills/start/bama/SKILL.md 里的那条流水线重新排序:

idea -> research -> clone (optional) -> app-brief -> user-stories -> new-mac-app
     -> mac-design + design-system + app-icon -> improve-loop (ux, code, design, verify, commit) -> repeat

于是仓库里同时存在两套顺序,各自负责不同的问题:

  • 目录顺序回答"这个技能归属哪一类问题",用于人找文件、用于 scripts/link-skills.sh 用 skills/*/*/ 批量软链。
  • 登记顺序回答"先做哪个",用于插件安装后技能列表的呈现顺序。
  • router 的顺序回答"用户现在站在哪一步、下一步该调谁",用于运行时决策。

三套顺序并不一致,而且这种不一致是设计出来的。分层不等于时序,这是第一个需要记住的点。

三层各管什么:场景层、技能层、说明层

拆开看,仓库实际有四个层次,只是其中一层是"复制粘贴"出来的。

第一层,场景层:skills/<stage>/ 五个目录。它的职责单一,就是给技能一个归属,让人能在 103 个文件里快速定位。注意 scripts/link-skills.sh 的实现:

for skill in "$repo"/skills/*/*/; do
  skill=${skill%/}
  name=${skill:t}
  ln -sfn "$skill" "$target/$name"
done

通配写死为两级。这意味着"stage/name"这个结构是被工具硬编码依赖的,任何人往 skills/ 里塞第三层,这个脚本会静默跳过,不会报错。场景层因此不只是一个视觉分组,它是一个接口。

第二层,技能层:skills/<stage>/<name>/SKILL.md 加上它的附属资产。附属资产的三种去向在 AGENTS.md 里写得非常死:

References sit next to SKILL.md (recipes.md, patterns.md) and are linked relatively. Scripts go in scripts/, templates in template/.

这条约定解决的是 agent 的上下文预算问题:正文只放每条分支都要用的内容,只有部分分支需要的内容推到同级文件后面挂链接。mac-design 把 542 行的 patterns.md、198 行的 toolbars.md、117 行的 menus.md 推到正文之外,正文只有 196 行;design-kit 的正文 127 行,把 477 行的组件代码放进了 parts.md。这不是为了好看,而是为了让"读哪个技能"这件事的初始成本保持恒定。

第三层,说明层(对外注册):plugin.json、README.md 的技能表、router 的三张分派表、agents/openai.yaml。这四份东西内容高度重叠,但各自面向不同读者:plugin.json 面向插件加载器,README.md 面向人,router 面向 agent 的运行时决策,openai.yaml 面向 Codex 的技能列表显示。

第四层,说明层(对内约束):AGENTS.md 与 .claude/CLAUDE.md。这两份文件是同一份内容的两份拷贝,AGENTS.md 开头就写着 "keep them identical"。里面放着写作规则:description 必须是上下文指针、每个步骤以可检查条件收尾、每个技能以 "Done when" 结尾、禁止 em dash、用主动语态。

四层加起来,说明层承担的其实是"把同一个事实广播到四个消费端"的职责。这正是下一节要谈的代价的来源。

一条工作流横跨几个技能,依赖靠什么声明

答案可能让人失望:没有任何声明。

improve-loop 是整个仓库最复杂的技能,它的循环体是:

pick story -> plan -> code -> ./build.sh -> snapshot -> compare -> fix -> commit -> update STORIES.md

在这个循环里,它调用了 7 个其他技能:ux-design、swift-swiftui、mac-design、os-integrations、build-and-verify、test-mac-app、improve-architecture。但打开 skills/ship/improve-loop/SKILL.md 的 frontmatter,只有 name、description、argument-hint 三项,没有任何 dependencies 字段。

依赖关系全部写在正文的自然语言里:

Follow the `swift-swiftui` and `mac-design` skills, the story's `UX:`
block, and `design/DESIGN-SYSTEM.md` if the app has one. System hooks follow
`os-integrations`.

或者更直白的调用指令:

Yet, call the Skill tool with `ux-design` first.

全仓库这种 Call the Skill tool with 的写法共 19 处,分布在 14 个文件里。这是唯一的"调用约定",它靠三件事成立:

一是固定的措辞。 AGENTS.md 明确规定:One skill calls another with "Call the Skill tool with \`".` 措辞固定,才能被 agent 稳定识别为动作而非描述。

二是磁盘文件构成的隐式接口。 真正把 21 个技能粘在一起的不是函数签名,是 docs/ 下的六个文件。仓库里对它们的引用次数可以直接数出来:

契约文件 被引用次数 谁写 谁读
docs/BRIEF.md 15 app-brief user-stories、new-mac-app、ux-design、design-system
docs/STORIES.md 9 user-stories、improve-loop improve-loop、ux-design
docs/GLOSSARY.md 6 ux-design improve-loop
docs/screens/INDEX.md 8 clone user-stories、app-brief
docs/research/*.md 5 research app-brief、user-stories
docs/FIXLOG.md 3 improve-loop improve-architecture

这套契约的精妙之处在于它是单向且可幂等的。research 写 docs/research/<topic>.md,格式在技能正文里给了模板;clone 写 docs/screens/INDEX.md,末尾必须是三张表(导航图、命令图、数据模型猜测);app-brief 的第一步是"如果 docs/research/ 或 docs/screens/INDEX.md 存在,先读它们,跳过它们已经回答的问题"。下游不需要知道上游怎么实现的,只需要知道文件在哪、长什么样。

三是每个技能结尾的 "Done when"。 这是流水线可编排的前提。app-brief 的结尾是"docs/BRIEF.md exists, fits on one page, and has every section";clone 的结尾是"INDEX.md has a section per PNG, the three maps exist, and docs/STORIES.md covers every screen";user-stories 的结尾是一句更狠的断言:"every main job in the brief, every 'Version one: yes' row in the research matrix, and every screen in the index maps to a story or a Dropped line"。

把这 21 个 "Done when" 排在一起,你会发现它们构成了一条可验证的链:上游的完成条件,恰好是下游的输入前提。这是用自然语言模拟出来的类型系统,只是校验发生在 agent 的推理里,而不是编译器里。

代价一:复用性下降,因为技能绑定的是位置

按工作流分目录,最直接的代价是技能不再是"能力单元",而是"流水线上的工位"。

skills/ship/build-and-verify/SKILL.md 里写死了这些:

./build.sh            # release build, installs ~/Applications/<AppName>.app
tools/snap.sh
swift tools/check-layout.swift /tmp/<AppName>-shots/*-layout.json

这三个路径来自 skills/start/new-mac-app/template/。也就是说,build-and-verify 只有在"由 new-mac-app 生成的项目"里才能开箱即用。技能自己也承认了这个边界,第 16 行留了一条逃生通道:

App not made from the `new-mac-app` template (Xcode, XcodeGen, a menu bar
utility, Swift 5)? Map the commands below with <a href="https://link.gitcode.com/i/f9ed3859835456733a069932ebbf69db" target="_blank">existing-app.md</a> first.

那个 existing-app.md 有 130 行,本质是一份"如何把这套流水线迁移到别人的项目结构上"的适配说明。复用不是不可能,但复用的成本被外化成了一个额外文档,而不是内建在技能里。

同样的耦合出现在 layout-grid:它的第一条规则是"每个 padding、spacing、size 都来自 Space:xs 4, sm 8, md 12, lg 16, xl 20, xxl 24, section 32",而 Space 定义在模板的 Sources/<App>/UI/Grid.swift 里(141 行)。技能正文明确写了迁移路径:

For an app made before this skill, copy `UI/Grid.swift`,
`tools/grid-lint.sh`, and `tools/check-layout.swift` from the `new-mac-app`
skill's template, and the layout file line from its `Snapshot.swift`.

需要连代码带工具连快照逻辑一起搬。这就是"工位化"的代价:技能的边界不是能力边界,而是工程边界。它没法被单独摘出来放进另一个项目,因为它依赖一整套脚手架约定。

代价还体现在目录层级被工具硬编码这一点上。link-skills.sh 的 skills/*/*/ 只认两级,意味着你无法为大型技能加一个 scripts/ 子目录分组,也无法引入 skills/code/swift/concurrency/ 这种更细的层次,除非同时改脚本。分层带来的表达力,被消费端的两级假设反向锁死了。

代价二:维护面变宽,一个技能要改四处

AGENTS.md 的 "Adding a skill" 只有四步,但第三步暴露了真实工作量:

1. Create `skills/<stage>/<name>/SKILL.md` and `agents/openai.yaml`.
2. Add it to `plugin.json` `skills`, the README table, and the router
   (`skills/start/bama/SKILL.md`).
3. Run `claude plugin validate . --strict`.
4. Keep `version` in `plugin.json` at 1.0.0 until the first release.

第 2 步横跨三个文件,加上第 1 步的 openai.yaml,实际是五个改动点。而这五个点里没有一个是自动生成的:plugin.json 是手写 JSON 数组,README 是手写 HTML 表格里嵌 <samp> 标签,router 是三张手写 Markdown 表格。仓库当前的状态是三者对得上(21 个 SKILL.md、21 条 plugin.json 条目、21 个 <samp> 标签),但这份一致性靠的是人工和 validate --strict,不是靠构建期检查。

这种重复已经开始产生可见的熵。router 的 Design 表里,design-system 出现了两次:

| An accent or brand color, a color picker, tokens | `design-system` |
| Their own parts and feel, not Apple's: buttons, rows, sidebar, icons | `design-kit` |
| The look of an app they name, or screenshots of one | `design-from-app` |
| One set of colors, radii, motion, and controls for the whole app | `design-system` |

两条触发语的边界需要读者自己判断("品牌色"和"整套颜色/圆角/动效"到底算不算同一件事)。这不是致命问题,但它精确地展示了广播式维护的典型症状:同一份技能元数据被抄写了四遍,任何一次局部修改都可能只落在其中三处。

权限声明的不均匀是第二个症状。21 个技能里只有 3 个在 frontmatter 声明了 allowed-tools:

技能 声明的工具
new-mac-app Bash(*/new-app.sh *) Bash(git *) Bash(swift *) Read Write Edit
build-and-verify Bash(./build.sh*) Bash(swift *) Bash(tools/*) Bash(*/Contents/MacOS/*) Bash(open *) Read
app-icon Bash(tools/make_icon.sh) Bash(tools/icon_review.sh) Bash(./build.sh *) Read Edit Write

这三个恰好是最需要跑命令的三个。剩下的 18 个没有声明,意味着权限边界在这 18 个技能里是"由 agent 默认行为决定"的。这种不均匀不是疏忽,更像是"按需收紧":只有真会执行构建、签名、截图这些有副作用的操作时,才值得付出维护白名单的成本。但它确实让"这个技能的权限范围是什么"这个问题,没法在 21 个技能上得到一致答案。

第三个症状更隐蔽,也是我认为最能说明问题的一处:.claude/CLAUDE.md 和 AGENTS.md 是两份必须保持一致的拷贝文件。仓库里已经有一份 AGENTS.md 明确写着 "keep them identical",但仍然需要两个物理文件,因为两个不同的 agent 生态读不同的文件名。这是分层结构的必然后果:你的组织方式越贴近工作流,你就越需要把同一份事实翻译给不同消费端。

为什么还是值得这么分

代价清单列完了,但结论不该是"别这么干"。回到具体场景:这是一个把"从零到 Dock 上一个能跑的 Mac app"当作唯一目标的仓库,21 个技能全部服务于同一类项目、同一套脚手架、同一条流水线。在这种前提下,按工具分目录反而会制造伪复用——swift-swiftui 和 mac-design 之间没有"工具边界",它们是同一次编码行为的不同侧面,硬拆成工具目录只会让 agent 在两者之间来回跳。

真正让这套分层站得住的,是三件可以被验证的事:

它承认了顺序,并且把顺序写在了两个地方。 plugin.json 存登记序,router 存决策序,两者允许不一致,因为前者服务加载器,后者服务运行时。分层负责归属,顺序负责执行,两件事被分开了。

它把技能间的耦合从代码依赖换成了文件契约。 六个 docs/ 文件、一个 design/ 目录、固定的模板格式,构成了跨技能的事实总线。耦合没有消失,但变得可见、可检查、可单独修复:契约文件坏了,下游全坏;契约文件对了,上游怎么实现无所谓。

它给每个工位装了验收条件。 21 个 "Done when" 是这套结构能够被"无人值守地跑"的唯一原因。improve-loop 敢写 "The loop works with no one watching, because every step checks itself",前提就是每一步都有退出判据:构建过、快照看过、验收行对上、栅格检查 PASS。没有这些条件,工作流分层只是一张好看的图。

如果要给这套组织方式一句判词,大概是:它不适合做技能市场,适合做技能流水线。 技能市场要的是可组合的能力单元,所以按工具切、按输入输出切;流水线要的是上下文恰好够用的工位,所以按阶段切、按缺口切。BAMA 选择了后者,代价写在 existing-app.md 里,收益写在 specs/ 那 12 份"给 agent 就能直接开工"的构建计划里。

值得一提的是,specs/ 本身就是这套分层红利最直接的兑现:每份 spec 固定五段(Brief、How it works、Stories、Gotchas、Done when),前两段直接喂给 app-brief 和 user-stories 跳过访谈,后两段喂给 improve-loop 避免重踩坑。当你的目录按工作流分好了,一份文档就能同时被多个阶段消费,这才是"按工作流组织"最终省下来的东西。

登录后查看全文
bama