因为笔者的工作需要接触到一些奇奇怪怪的项目,屎山可以说见得太多了,所以为了能让开发效率高一点,所以就写了一个 skill,但是单文件的 skill 太长了,会导致越看越读的错误,经过不断的拆分,这个 skill 项目诞生了.
项目地址：WoJiSama/skill-based-architecture
这个项目不是又写了一份更长的提示词，也不是把 AGENTS.md、CLAUDE.md、.cursor/rules/ 的内容换个地方复制一遍。
它想解决的是一个更具体的问题：
当项目越来越大，AI Agent 到底应该在什么时候读哪些规则、跟哪个流程、记录哪些新经验，并且在上游模板更新时不覆盖下游项目自己的个性化规则？
我把这套东西做成了一个 meta-skill：把散落的项目规则、工作流、踩坑经验，整理成一个可激活、可路由、可验证、可持续维护的项目 skill 。
全文核心是三句话：
很多项目一开始只有一个入口文件：
AGENTS.md
CLAUDE.md
.cursor/rules/workflow.mdc
刚开始很好用，因为规则少，Agent 每次读一遍也不贵。
但项目跑久之后，常见情况会变成这样：
AGENTS.md # 写了一部分规则
CLAUDE.md # 又复制了一份，略有不同
CODEX.md # 再复制一份
.cursor/rules/*.mdc # Cursor 还有一份
README.md # 某些约定又埋在这里
docs/*.md # 还有历史记录、流程说明、坑点
表面上是“规则很多”，实际问题是：
| 现象 | 后果 |
|---|---|
| 多个入口文件写了重复路由 | 改一处漏三处，规则开始漂移 |
SKILL.md 越写越长 |
Agent 每次任务读整本书，token 浪费且容易漏重点 |
坑点只放在 references/ |
下次修同类 bug 时，Agent 根本不会自然读到 |
| description 写得太窄 | 用户说“这个接口报错了”，但 skill 只写 “fix bug”，可能不触发 |
| description 写得太宽 | 什么任务都触发，后面还要再猜真正意图 |
| 上游模板更新 | 下游项目自己慢慢写出来的规则不能被覆盖 |
所以这个项目的核心不是“让 Agent 多读点文档”，而是让 Agent 少读、读准、读对路径。
我不认为所有项目一上来都应该拆成 rules/、workflows/、references/。
如果一个 skill 只有几条稳定原则，单个 SKILL.md 就够了。参考 forrestchang/andrej-karpathy-skills 这类项目，核心价值不是目录复杂，而是规则写得克制、具体、可检查。
真正需要升级结构的信号是：
SKILL.md 开始超过 100-150 行。这时候才应该从“单文件”升级到“文件夹化 skill”。
目标结构是这样：
skills/<project>/
├── SKILL.md # 入口：激活后导航，不写百科
├── routing.yaml # 路由单一事实源
├── rules/ # 稳定约束：什么必须一直成立
├── workflows/ # 步骤流程：做一件事的顺序
├── references/ # 背景、架构、坑点、索引
└── docs/ # 可选：报告、提示词、对外材料
文件边界很简单：
| 内容类型 | 放哪里 |
|---|---|
| “必须 / 禁止 / 始终” | rules/ |
| “第一步 / 第二步 / 最后检查” | workflows/ |
| “为什么这样 / 这个坑怎么来的” | references/ |
| “对外说明 / 报告 / 提示词” | docs/ |
这个拆分不是为了看起来工程化，而是为了让 Agent 在不同任务里只加载最小必要上下文。
routing.yaml：路由只维护一份我后来发现长期维护最大的风险，不是某条规则写错，而是同一份路由在多个地方重复维护。
所以现在模板里把路由集中到 routing.yaml：
tasks:
- id: fix-bug
labels:
en: Fix bug
zh: 修复 bug / 排查异常
required_reads:
- rules/project-rules.md
- rules/coding-standards.md
workflow: workflows/fix-bug.md
trigger_examples:
- "这个接口报错了"
- "测试挂了"
- "fix this failing test"
然后由脚本生成或校验：
SKILL.md 里的 Always Read / Common TasksAGENTS.md、CLAUDE.md、CODEX.md、GEMINI.md 的薄壳入口.cursor/rules/workflow.mdc.cursor/skills/<name>/SKILL.md这样新增一个任务时，不再需要手动改五六个入口文件。
很多 skill 的 description 会陷入两个极端。
第一种是太窄：
description: Fix bug
用户说“这个接口报错了”“页面白屏了”“测试挂了”，不一定能触发。
第二种是太宽：
description: Helps with development
它可能什么任务都触发，后面路由压力反而变大。
我的处理方式是：description 写领域边界和真实用户表达，任务级细分交给 routing.yaml。
例如：
description: >
Use this skill when the user asks to organize project rules, clean up
scattered agent docs, improve skill routing, increase description trigger
accuracy, or maintain templates and thin shells.
Activate when task routes, trigger_examples, SKILL.md, AGENTS.md,
CLAUDE.md, Cursor rules, validation scripts, or upstream update workflows
need drift-resistant maintenance.
它不需要列出每一个 workflow 。它只需要回答一个问题：
这个用户请求，属于这个 skill 的领域吗？
激活之后，才由 routing.yaml 继续判断是修 bug 、改模板、更新 reference 、优化 description ，还是从上游升级。
不同工具读取入口不同：
| 工具 / Harness | 常见入口 |
|---|---|
| Claude Code | CLAUDE.md |
| Codex / AGENTS.md 工具 | AGENTS.md、CODEX.md |
| Cursor | .cursor/rules/*.mdc、.cursor/skills/<name>/SKILL.md |
| Gemini | GEMINI.md |
如果每个入口都复制完整规则，很快就会漂移。
所以这个项目采用“薄壳”：
## Quick Routing
Task routes live in `skills/<name>/routing.yaml`.
For every new task:
1. Read `skills/<name>/SKILL.md`.
2. Read `skills/<name>/routing.yaml`.
3. Match by `labels`, `trigger_examples`, and task intent.
4. Read only that route's `required_reads`, then follow its `workflow`.
5. If no route matches, use the `other` route.
薄壳只回答“从哪里开始、怎么路由”，规则正文仍然只放在 skill 目录里。
这样做还有一个额外好处：长会话压缩之后，结构化的 Quick Routing 比普通自然语言更容易保留下来。Agent 即使忘了前文，也还能重新找到路由入口。
很多项目的规则文档只会增加，不会筛选。
这个项目把任务结束定义成一个闭环：
AAR 只问四个问题：
但不是所有东西都记录。录入前要过门槛：
| 判断 | 说明 |
|---|---|
| 可重复 | 未来还可能再次遇到 |
| 代价高 | 不知道会明显浪费时间或造成错误 |
| 代码里看不出 | 只读代码不容易发现 |
通常至少满足 2 条才值得写进 skill 。
更重要的是：写进 references/ 还不够。高代价坑点必须出现在正常任务路径上，比如 workflow 的完成检查、SKILL.md 的 Known Gotchas ，或者某条 route 的 required reads 。
否则它只是“存起来了”，不是“会被激活”。
以前让 Agent 临场生成脚手架，很容易漏段：
SKILL.md 和薄壳路由不一致。所以这个项目把结构放进 templates/：
templates/
├── skill/ # 复制为 skills/<name>/
├── shells/ # AGENTS.md / CLAUDE.md / CODEX.md / GEMINI.md
├── hooks/ # 可选 SessionStart / PreToolUse hook
├── protocol-blocks/ # AAR 、Red Flags 、subagent contract 等
└── ANTI-TEMPLATES.md # 明确哪些东西禁止预制
这里有一条边界：
结构可以预制，内容禁止预制。
比如 routing.yaml 的字段结构可以预制，但具体任务、规则、坑点必须来自下游项目真实情况。
判断一个东西能不能放进模板，我用这个问题：
一个 Go 后端服务和一个 React 动画站，都会同意这块默认内容吗？
如果不会，就不应该预制。
人很难每次手动检查这些事情：
routing.yaml 引用的 workflow 是否存在。SKILL.md 和 Cursor 注册入口的 description 是否一致。<!-- FILL: --> 没填。SKILL.md 是否过长。所以模板里带了脚本：
bash skills/<name>/scripts/smoke-test.sh <name>
bash skills/<name>/scripts/sync-routing.sh <name> --check
bash skills/<name>/scripts/check-description-routing.sh <name>
bash skills/<name>/scripts/test-trigger.sh <name>
脚本不能替代理解，但能抓住大量“忘了改 / 改漏了 / 多处漂移”的问题。
这是我后来遇到的一个更实际的问题。
这个仓库是上游模板项目，会持续更新；但下游项目已经有自己慢慢沉淀出来的规则、流程、坑点。
如果上游升级时直接覆盖：
cp -R upstream/templates/skill/. skills/<name>/
那就会把下游项目自己的知识冲掉。这是不靠谱的。
所以现在模板里加入了 update-upstream 工作流。下游用户不需要自己 diff ，也不需要维护额外系统文件。他只要对 Agent 说类似这样的话：
上游 skill-based-architecture 更新了，帮我更新一下。
Agent 应该自己去做：
核心原则是：
上游负责结构演进，下游保留项目知识。
它提供的不是某一条神奇 prompt ，而是一套项目规则系统的工程结构：
| 能力 | 解决的问题 |
|---|---|
SKILL.md 入口 |
激活后快速导航，不把所有内容塞进入口 |
routing.yaml |
路由单一事实源，避免多入口重复维护 |
rules/ |
存稳定约束 |
workflows/ |
存可重复步骤 |
references/ |
存架构背景和高代价坑点 |
| 薄壳入口 | 兼容 Cursor 、Claude Code 、Codex 、Gemini 等工具 |
| AAR / Task Closure | 任务结束时捕获新经验和过时规则 |
| templates | 复制稳定结构，不让 Agent 临场生成漏段 |
| validation scripts | 自动检查占位符、路由、description 、薄壳漂移 |
| update-upstream workflow | 上游结构可升级，下游项目知识不被覆盖 |
一句话总结：
它把“写给 AI Agent 的散乱提示词”，升级成了一个可路由、可验证、可持续维护的项目规则系统。
https://github.com/WoJiSama/skill-based-architecture
欢迎一起提 issue 或 PR 。这个项目本身也在用自己的规则维护自己，但是楼主遇到了一些问题,这个也是在这里分享这个项目的原因就是,未来还可以做什么东西,这个项目目前值得做的内容非常多已经做完了,已经不知道未来还有什么可以发展的地方了,所以也希望能和大家一起头脑风暴
感觉大家
此内容由惯性聚合(RSS阅读器)自动聚合整理，仅供阅读参考。 原文来自 — 版权归原作者所有。