--- name: linsir2/project-incarnation source: https://app.decimal.ai/s/linsir2-project-incarnation@1/SKILL.md source_sha256: b21a942d0f63 --- # 项目化身术 > 不做文档复印机，只做判断压缩机。 ## 核心理念 项目化身不是“介绍这个东西是什么”，而是把一个对象压缩成一份**可继续做判断的认知器官**。 一个合格的技术化身，至少要让后续的 agent / harness / 人类读者只靠这一份 `SKILL.md` 就知道： 1. 这个对象到底在保护什么真相 2. 它最常反对什么错误 3. 它遇到新问题时先看什么证据 4. 它在哪些地方必须闭嘴或降置信度 5. 它的判断为什么不是通用废话，而是这个对象独有的判断 **关键区分**： - 不是复制文档，而是提炼判断 - 不是列功能点，而是提炼取舍 - 不是写“它很厉害”，而是写“它会如何反对你” - 不是生成一堆附属文件，而是生成一个**自包含**的 `SKILL.md` 最终产物只有： ```text // └── SKILL.md ``` 其中 `` 指的是**agent 运行时可直接发现和加载的安装目录**，例如： ```text /.agents/skills/ /.codex/skills/ $CODEX_HOME/skills/ ~/.codex/skills/ ``` 不生成 `constitution.yaml`、`sources.jsonl`、`bundle-spec.json`、`evals.md`、`references/`、`scripts/`。 如果一个子 skill 需要靠一堆旁路文件才能成立，那它还不是技术化身，只是半成品。 ## 什么叫“高知识密度” 知识密度不是“信息多”，而是“删一句就少一分预测力”。 蒸馏时，优先保留这些东西： - **判断晶体**：这个对象反复保护的原则与偏好 - **决策启发式**：遇到选择时它倾向怎么切 - **默认反对项**：它会本能抵抗什么 - **边界条件**：什么时候它应该 abstain - **证据路径**：遇到事实型问题时它先查什么 - **内在张力**：它不是永远正确，它也有矛盾、版本漂移和代价 删掉这些东西： - API 或 feature 的流水账 - 把 README 改写一遍 - 所有人都同意的正确废话 - 没有来源支撑的“气质描述” - 不能提升未来判断质量的背景材料 ## 技术化身的判定标准 只有同时满足下列条件，才能算“技术化身”： ### 1. 有预测力 读完这份 skill，应该能大致推断这个对象在一个**新问题**上的倾向，而不只是复述旧观点。 ### 2. 有反对力 它不只是会赞同，还会明确指出什么方案违背了自己的核心判断。 ### 3. 有边界 它知道什么时候该说“这不归我管”或“证据不够，先查”。 ### 4. 有时效意识 项目、技术栈、SDK 都会变。skill 必须明确版本范围与调研截止时间。 ### 5. 有证据脊柱 核心判断必须能追溯到对象的一手或准一手材料。无法追溯的内容，只能作为弱推断。 ### 6. 可单文件运行 把 `SKILL.md` 单独复制走，下游仍然能知道它是谁、怎么想、凭什么、何时闭嘴。 ## 什么时候用 这些请求都应该触发： - 给这个 repo 做个化身 - 把这个技术栈蒸馏成 skill - 把这个项目做成技术人格 - 把这个 framework 的 maintainer judgment 压成一个 skill - 把现有 skill 升级成更高知识密度的技术化身 - 把一个工程方法论做成能参与讨论的子 skill ## Phase 0: 入口分流 收到请求后，先判断输入类型： | 输入 | 路径 | 默认重点 | | --- | --- | --- | | 明确 repo / 本地项目 / GitHub 仓库 | 项目蒸馏 | 维护者判断、架构边界、历史取舍 | | 明确框架 / SDK / 技术栈 | 技术栈蒸馏 | 核心抽象、API 边界、迁移与坑点 | | 明确方法论 / 工程哲学 | 方法论蒸馏 | 原则、案例、反模式、适用条件 | | 已有 skill | 升级路径 | 读取旧 skill，补足证据、边界、预测力 | | 用户只说“我想要一种能力” | 诊断路径 | 先判断该蒸馏哪个对象，再进入对应路径 | 如果用户没有指定输出位置，默认**安装**到 runtime skill root，而不是普通内容目录。 推荐优先级： 1. 如果当前项目已经有 `/.agents/skills/`，写到： ```text /.agents/skills//SKILL.md ``` 2. 否则如果当前项目已经有 `/.codex/skills/`，写到： ```text /.codex/skills//SKILL.md ``` 3. 否则如果当前处于一个明确项目根内，默认创建并写到： ```text /.agents/skills//SKILL.md ``` 如果当前不在一个明确项目根内，就回退到： ```text $CODEX_HOME/skills//SKILL.md ``` 如果拿不到 `$CODEX_HOME`，再回退到： ```text ~/.codex/skills//SKILL.md ``` 路径角色约定： - `authoring root`：authoring/compiler 类 skill 的 canonical 位置，例如 `/authoring/` - `runtime skill root`：运行时子 skill 的安装位置，例如 `/.agents/skills/`、`/.codex/skills/`、`$CODEX_HOME/skills/` - `trace root`：运行痕迹与回放资产的位置，例如 `/traces/` 在这个 skill 里，`.agents/skills/`、`.codex/skills/` 这类 runtime 目录**就是默认安装目标**，不是可忽略的 adapter。 不要再把普通 `./skills/` 当默认落点，除非用户明确要求只导出、不安装。 `` 规则： - 项目：repo 名或系统名 - 技术栈：官方名称转 kebab-case - 方法论：能代表其判断风格的清晰短名 - 已有 skill 升级：沿用原 slug ## Phase 0.5: 开工前的四个锚点 在调研前，先把以下四个锚点明确下来。四个锚点不清，后面都会漂： 1. **蒸馏对象是谁** - 不是“整个编程世界”，而是具体项目、框架、方法论或 skill 2. **它要保护什么** - 不是“帮助用户”，而是一个更尖锐的真相，例如“边界清晰优于魔法便利” 3. **它主要要处理什么问题** - 架构取舍、迁移判断、API 设计、性能边界、工程文化、项目方向 4. **它不负责什么** - 例如“只代表 React 核心团队判断，不代表所有前端最佳实践” 如果用户没有明确这些信息，按最合理的默认假设推进，但必须把假设写进最终 skill。 ## Phase 1: 来源采集 这里的目标不是“搜很多资料”，而是拿到足以支撑判断的**证据骨架**。 ### 来源优先级 #### 项目蒸馏 优先读： 1. repo 根文档：`README`、`docs/`、`ADR`、架构说明 2. 代码与边界：入口文件、核心模块、关键配置、测试 3. 历史决策：重要 PR、issue、release notes、changelog 4. 维护者声音：维护者博客、访谈、RFC、discussion 5. 真实摩擦：外部批评、迁移吐槽、常见坑 #### 技术栈蒸馏 优先读： 1. 官方文档与核心概念页 2. migration guide / upgrade guide / release notes 3. 官方 API 边界说明 4. maintainer 写作、RFC、设计讨论 5. 社区争议、踩坑案例、反对者批评 先做一个**对象一致性检查**： - 用户说的对象，是否真的是代码里实际在用的那个对象 - 还是它的相邻底座 / 上游协议 / 近亲实现 - 还是“项目叙事上叫 A，实际实现更接近 B” 如果出现这种错位，例如： - 名义上说是 FastAPI，实际主体是 Starlette - 名义上说是 LangGraph，实际更像自定义 DAG runtime - 名义上说是 React，实际只是消费了部分 React 生态约束 不要硬把 B 蒸成 A。 正确做法是： - 明确写出**对象名**与**实际实现面**的差异 - 区分哪些判断是该对象独有的，哪些只是可迁移的相邻 discipline - 在 `不适用问题`、`误判警报` 或 `诚实边界` 中显式写出这层错位 - 对缺席的原生概念，不要强行要求它们出现 例如： - 目标是 FastAPI，但项目其实是 Starlette + Pydantic 那么可以用 FastAPI skill 的“契约 / I-O / 部署纪律”去审， 但不能强行要求 `Depends`、`APIRouter`、自动 OpenAPI 全部存在。 #### 方法论蒸馏 优先读： 1. 原著、官方文章、长文 2. 长访谈 / 演讲 / 问答 3. 具体决策案例 4. 有力度的批评与反例 #### 现有 skill 升级 优先读： 1. 旧 `SKILL.md` 2. 它引用或暗示的上游对象 3. 该对象最近变化的关键材料 ### 永久黑名单 这些内容不能当主来源： - AI 摘要站 - SEO 拼装博客 - 无法追溯原文的搬运总结 - 只会喊“最佳实践”的空洞经验贴 - 没有署名、没有版本、没有具体案例的二手拼接 如果弱来源里碰巧有价值线索，只能当线索，不可直接当结论。 ### 最小来源门槛 如果没到门槛，就继续采集，不要渲染： #### 项目 - 至少 1 个架构/边界来源 - 至少 1 个维护者判断来源 - 至少 1 个真实决策或迁移来源 - 至少 1 个代码或测试层证据 - 至少 1 个外部摩擦来源 #### 技术栈 - 至少 1 个核心概念来源 - 至少 1 个 API / contract 来源 - 至少 1 个迁移或 breaking change 来源 - 至少 1 个 maintainer judgment 来源 - 至少 1 个争议或坑点来源 #### 方法论 - 至少 2 个一手文本 - 至少 1 个长对话或演讲 - 至少 1 个实际案例 - 至少 1 个有力度的反方材料 ## Phase 2: 提炼“智慧晶体” 只有在来源足够后，才进入压缩。 你的任务不是做摘要，而是从材料里挖出下面这些东西： ### 2.1 核心判断晶体（3-7个） 每个晶体都要回答： - 它到底在保护什么判断 - 这个判断出现了几次，在哪些不同来源里出现 - 它会如何改变真实决策 - 它默认反对什么 - 它因此放弃了什么，或要求你承担什么代价 - 它的适用边界在哪里 每个晶体还必须带 4 个元标签： - **证据级别**：`primary` / `mixed` / `inferred` - **时效敏感度**：`low` / `medium` / `high` - **排他性说明**：为什么这不是通用正确话，而是这个对象自己的判断 - **置信度**：`low` / `medium` / `high` **判断晶体通过标准**： 1. **反复出现**：不是一次性表态 2. **跨场景复现**：能在文档、代码、决策、争议里看见影子 3. **能推新问题**：可以外推到未见过的问题 4. **有排他性**：不是人人都会说的套话 5. **有代价**：坚持它会牺牲什么 五条里少于三条，不配叫“晶体”。 ### 2.2 决策启发式（5-10条） 用 `如果 X，则优先 Y` 的形式写。 好启发式的特征： - 可以直接参与现实决策 - 不只是价值宣言 - 能看出对象的偏好顺序 - 最好能绑定具体情境或经典取舍 ### 2.3 默认反对项（3-7条） 一个对象的智慧，不只在它推什么，也在它会本能反对什么。 例如： - 边界漂移 - 隐式魔法 - 过度抽象 - 版本不兼容却装作兼容 - 把单机问题硬吹成平台问题 默认反对项必须尽量具体，最好能对应实际争议或历史决策。 ### 稳定内核 vs 版本敏感层 任何项目、技术栈、SDK 类子 skill，都必须显式拆成两层： - **稳定内核**：短期版本波动下大概率仍成立的判断 - **版本敏感层**：一旦 release、maintainer stance、breaking change、运行时模型变化，就要重查的判断 如果对象是方法论而不是技术栈，可以把第二层改写成： - **语境敏感层**：受时代、产业结构、组织规模、工具环境影响很大的判断 没有这层切分，更新时就只能整份 skill 一起重写。 ### 2.4 诚实边界（至少 3 条） 必须明确： - 哪类问题它不适合回答 - 哪类问题它必须先看最新资料 - 哪类问题它只能给条件性判断 ### 2.5 内在张力（2-5 条） 任何值得蒸馏的对象都有内在张力。没有张力，通常说明蒸馏得太浅。 常见张力： - 简洁 vs 灵活 - 显式 vs 易用 - 性能 vs 可维护 - 稳定 API vs 快速演进 - 维护者意志 vs 社区多样性 ### 2.6 证据锚点 最终 skill 必须自带一组紧凑的证据锚点。 格式建议： ```markdown - [E1] React docs, “Thinking in React”, 2024-xx-xx - [E2] Maintainer comment in issue #1234, 2025-xx-xx - [E3] Release notes v3.0, breaking change rationale ``` 后文的重要判断可以引用 `[E1] [E3]`，不需要再依赖外部 `sources.jsonl`。 ### 误判警报（Confusion Pairs） 每个子 skill 都必须有一组 `误判警报`，说明它最容易在哪些相邻问题上被误用。 格式建议： - `不要把 X 问题误当成 Y 问题` - `当用户其实在问 A 时，这个 skill 最多只能回答到 B` - `这个对象和相邻对象 C 看起来很像，但它们真正分叉在 D` 这部分的目的不是谦虚，而是降低 harness 或用户把错误 skill 拉进来强答的概率。 ### Watchlist 每个子 skill 都必须列出 3-5 个 `watchlist` 触发器。 不是“以后记得更新”，而是“发生这些事时必须重查”。 典型触发器： - maintainer judgment 明显变化 - 核心 release 引入 breaking change - 安全 / 性能 / 运行时模型发生结构性变化 - 关键依赖升级导致上游 contract 变化 - 社区争议重心改变，导致默认反对项需要改写 ## Phase 2.5: 密度闸门 提炼完之后，先不要写子 skill。先做下面这些检查。 ### 1. 删除测试 删掉任意一条判断，如果对子 skill 的未来判断几乎没影响，说明它是废话，应该删。 ### 2. 反对测试 问自己：这个 skill 面对一个错误方案时，会具体怎么反驳？ 如果只能说“视情况而定”，说明蒸馏还不够。 ### 3. 预测测试 给它一个对象没明确回答过、但足够接近的新问题。 如果它无法给出带边界的倾向判断，说明知识还没有压实。 ### 4. 边界测试 给它一个明显越界的问题。 如果它还在硬答，说明边界 section 是假的。 ### 5. 时效测试 问：这个问题是否依赖今天的版本、最新 API、最近 release、当前 maintainer stance？ 如果依赖，但 skill 没有提醒要先查，说明缺乏时效意识。 只有闸门通过后，才进入渲染。 ## Phase 3: 渲染子 skill 子 skill 必须是**单文件、自包含、可直接读取**的。 这不是“推荐骨架”，而是**required minimum contract**。 缺任何一项，都不算合格的技术化身。 最小契约如下： ```markdown --- name: description: | <一句话说明：它保护什么真相，擅长什么问题，边界在哪> --- # <显示名> > <一句锋利的角色定义> ## 角色定位 <它到底保护什么判断。不要写空泛使命。> ## 版本与时效性 - 版本范围：<例如 React 19 / 项目 main branch as of 2026-04-09> - 调研截止： - 权威来源类型： ## 适用问题 - <它最该处理的问题> ## 不适用问题 - <它不该硬答的问题> ## 稳定内核 - <短期版本波动下仍成立的判断> ## 版本敏感层 - <一旦 release / maintainer stance / runtime model 变化就要重查的判断> ## 语境敏感层（方法论对象用这个替代上一节） - <一旦时代、组织规模、产业结构、工具环境变化就要重查的判断> ## 核心判断晶体 ### 1. <晶体名> - 判断： - 为什么这很重要： - 默认反对： - 代价/取舍： - 适用边界： - 证据级别： - 时效敏感度： - 排他性说明：<为什么这是它，不是通用套话> - 置信度： - 证据锚点：<如 [E1] [E4]> ## 决策启发式 - 如果 X，则优先 Y，因为 ... ## 默认反对项 - <它会本能抵抗什么，以及为什么> ## 回答工作流（Agentic Protocol） ### Step 1: 问题分类 - 框架型问题：可直接按判断晶体回答 - 事实型问题：先查最新资料再回答 - 源码型问题：先读相关代码/测试/配置再回答 ### Step 2: 按这个对象的习惯收集证据 - <这一节必须由判断晶体反推，不许写成通用模板> ### Step 3: 输出结构 - 先给判断 - 再给理由 - 再说取舍 - 最后说边界 / 是否还需要查证 ## 内在张力 - <它的矛盾、代价、版本敏感点> ## 诚实边界 - <什么时候 abstain，什么时候降置信度> ## 误判警报 - <最容易把什么问题误判成什么问题> ## Watchlist - <发生什么事件时必须重查或重蒸馏> ## 证据锚点 - [E1] ... - [E2] ... ``` ### 第零要求：独立性优先 `SKILL.md` 应该被视为未来 subagent 的： - prompt - persona - reasoning contract 它也是**唯一语义来源**。 不要为了 harness 再写第二套语义字段、参数块或平行配置。 如果删掉任何面向 harness 的辅助提示，子 skill 本身仍然必须完整成立。 ### 最重要的要求：Step 2 必须“对象化” 子 skill 里的 `回答工作流（Agentic Protocol）` 不能是通用模板，必须是从对象本身的判断晶体反推出来的证据路径。 例如： - 如果蒸馏对象强调**边界清晰**，Step 2 就必须去查模块边界、扩展点、public contract - 如果它强调**运行时稳定性**，Step 2 就必须看 release notes、迁移说明、故障案例 - 如果它强调**最小复杂度**，Step 2 就必须先看方案是否引入额外层级、状态面、配置面 - 如果它高度依赖**maintainer taste**，Step 2 就必须优先看 maintainer comment、RFC、历史拒绝案例 如果 Step 2 和判断晶体没关系，这个子 skill 就还是假人格。 ### 第二个最重要的要求：更新协议必须“触发器化” 不要写： - `后续继续关注` - `以后需要更新` 要写成： - `如果 FastAPI minor release 改了 response validation，就重查晶体 1/2` - `如果 maintainer 开始推荐新的 extension boundary，就重查晶体 3` - `如果组织规模从 5 人变成 500 人，就重查方法论的语境敏感层` 没有触发器，watchlist 就只是礼貌备注，不是协议。 ### 第三个最重要的要求：协同靠可归约性，不靠第二套字段 当子 skill 被拿去做多-agent讨论时，harness 只应要求它的回答**可稳定归约**为以下六槽： - 判断 - 依据 - 代价/取舍 - 异议 - 需查证 - 置信度 这六槽是运行时协同接口，不是子 skill 必须显式照抄的正文模板。 原则： - 约束可归约性，不约束表面格式 - 让 harness 读正文的高价值结构，不让 harness 逼作者再写第二份灵魂 - 人格与判断留在 `SKILL.md` - 编排与轮次留给 harness ## Phase 4: 验证 生成完 `SKILL.md` 后，至少做以下四种验证： ### 4.1 历史回放测试 选 2-3 个真实历史决策或争议，让子 skill 来解释： - 它是否能给出接近对象原始判断的解释 - 它是否能指出背后的取舍，而不只是复述结果 ### 4.2 新问题外推测试 给一个对象没明确回答过、但足够接近的新问题。 期望输出： - 有倾向 - 有理由 - 有边界 - 必要时会要求先查证据 ### 4.3 越界测试 给一个明显不归它管的问题。 期望输出： - 明确 abstain 或降置信度 - 说明为什么这超出它的知识边界 ### 4.4 单文件测试 假设下游只读取这一份 `SKILL.md`： - 能否知道它的版本范围 - 能否知道它的证据类型 - 能否知道它会如何查事实 - 能否知道它的局限 - 能否知道什么内容稳定、什么内容易腐 - 能否知道它最容易被误用在哪 - 能否知道发生什么变化时必须重查 - 能否把它的回答稳定归约为：判断 / 依据 / 代价 / 异议 / 需查证 / 置信度 只要有一项答不上来，就继续补，不要交付。 ## 更新模式 当用户说“更新这个 skill”时： 1. 先定位**已安装的** `SKILL.md` 2. 标出哪些判断是稳定内核，哪些是版本敏感层 3. 只更新这些内容： - 版本范围 - 调研截止时间 - 最近的 maintainer judgment - 新出现的 breaking change / controversy / anti-pattern - `误判警报` 是否需要改写 - `watchlist` 的触发器是否已经触发 4. 不要重写整个 skill，除非旧 skill 的骨架本身是错的 ## 特殊场景 ### 场景 A：蒸馏本地 repo 如果用户给的是本地项目，必须优先读： - 入口文件 - 核心模块 - 测试 - 配置 - 最近的关键提交或 PR 不要只靠 README 推断架构。 ### 场景 B：蒸馏技术栈 如果对象是 FastAPI、Rails、React、LangGraph 这种技术栈，必须同时覆盖： - 核心抽象 - 公开边界 - 迁移路径 - 维护者反复强调的判断 - 社区高频坑点 如果真实对象只是该技术栈的相邻实现或底座： - 先写清楚错位 - 再区分“对象独有判断”与“可迁移 discipline” - 不要因为名字相近，就要求原生特性必须全部在场 ### 场景 C：从已有 skill 升级 已有 skill 常见问题： - 会说话，但没有证据 - 有口吻，但没有边界 - 有价值观，但没有预测力 - 有 section，但没有真实反对项 - 有判断，但没有稳定/易腐分层 - 有证据，但没有误判警报和 update trigger 升级时优先修这些，不要急着美化文案。 ### 场景 D：蒸馏完成后直接安装 默认目标不是“生成一个文件给用户手动搬运”，而是**直接把 skill 安装到 runtime skill root**。 执行顺序： 1. 先确定 runtime skill root（`.codex/skills/`、`.agents/skills/`、`$CODEX_HOME/skills/`） 2. 再写入 `/SKILL.md` 3. 如果你临时写到了普通工作目录，最终也要移动或复制到安装目录 4. 最终汇报时明确： - 安装到了哪里 - slug 是什么 - 下游应如何触发它 ## 禁忌 - 不要再生成 bundle 思维 - 不要让产物依赖多文件配套 - 不要把 README 改写成 skill - 不要把“通用最佳实践”伪装成对象判断 - 不要丢掉版本与调研时间 - 不要省略反对项与边界 - 不要为了语气像而牺牲判断密度 - 不要把证据留在脑子里，至少要压成 `证据锚点` - 不要默认只写到普通 `skills/` 目录却不安装到 runtime skill root ## 最终交付判断 这个 skill 的交付物是： - 一个高知识密度、单文件、自包含、并且已安装到 runtime skill root 的 `SKILL.md` 不是： - bundle - seat 配置包 - runtime contract 文件集 - 只会“像它说话”的角色卡 - 一个留在普通目录、还要用户手动搬运的半成品 - 一篇好看的项目介绍