## 0、2026-05-15 更新：v2.0.3 稳定版已完成工程化修复
这篇帖子最初发布之后，有朋友对这个 Skill 做了一次比较认真、也比较专业的测评。
我后来重新把这些意见逐条复查了一遍，结论是：其中有些问题确实存在，尤其是：
- 主 `SKILL.md` 过重，更像产品说明书，不够像 Skill 的路由入口；
- 文档承诺和脚手架实际产物存在不一致；
- 版本、发布包、校验流程还不够统一；
- 缺少可以重复验证的自检机制。
所以我没有只改文案，而是把它重新做了一轮工程化收敛。
目前稳定版已经更新到 `v2.0.3`，这次主要完成了：
- 把 `SKILL.md` 重写成轻量路由入口；
- 新增 `references/` 资源层，把长方法论下沉；
- 修正 full / minimal 两种安装模式的真实产物；
- 默认 full 模式继续创建完整 `30.knowledge/` Knowledge Palace v2；
- 新增 `CLAUDE.md` / `AGENTS.md` 薄适配器；
- 新增 `scripts/validate_skill.py` 自检脚本；
- 新增可复现打包脚本，并统一源码、文档、发布包版本；
- 额外修复了 ClawHub 上传兼容性问题，发布了 `v2.0.3` 稳定版。
这次更新的重点不是“把 Skill 写得更长”，而是让它更像一个可以长期维护、可以验证、可以发布的工程化 Skill。
1、Skill 简介
你有没有遇到过这种情况：
每次打开一个新的 AI 工具，都要重新解释一遍：
- 我是做什么的；
- 我喜欢什么样的回答；
- 我的项目是什么背景；
- 哪些东西可以改，哪些不能乱动；
- 我希望你先看哪些文件，再开始工作。
解释一次还好，解释十次之后就很烦。
所以我做了一个 Skill，叫 **Personal API**。
它的作用很简单：
把“你这个人”和“你的知识系统”整理成一套 AI 能读懂的接口文档。
AI 不再从零认识你，而是先读取你的 `ME.md` 和 `AGENT.md`，快速理解你的身份、偏好、协作规则和知识系统。
GitHub：
[GitHub - beiyuii/personal-api-skill](https://github.com/beiyuii/personal-api-skill)
2、我为什么要做它
我自己经常同时使用 Claude Code、Codex、Cursor、ChatGPT、Gemini 这一类 AI 工具。
但最大的问题是：
AI 很强，但它每次都像第一次见我。
它不知道我正在做什么，不知道我的表达偏好，不知道我希望它先分析再动手，也不知道我的 Obsidian 知识库里哪些内容是身份档案，哪些内容是可以整理的工作资料。
于是我经常要重复说：
- 回答要通俗一点；
- 不要乱改我的核心身份文件；
- 先读项目结构再下结论；
- 输出最好带路径和证据；
- 我的知识库是分层的，不要当普通文件夹乱处理。
这些话其实不是任务内容，而是“协作前置条件”。
所以我想：
能不能把这些前置条件固定下来，让 AI 每次开始工作前都先读取？
这就是 Personal API 的来源。
3、这个 Skill 到底做了什么
现在的 Personal API 不只是生成两个文件，而是分成两层。
第一层：个人身份层
它负责让 AI 快速理解“你是谁、你希望怎么协作”。
核心文件包括：
- `ME.md`
- `AGENT.md`
- `CLAUDE.md`
- `AGENTS.md`
其中：
- `ME.md` 是你的个人身份说明书；
- `AGENT.md` 是你的协作规则说明书；
- `CLAUDE.md` 和 `AGENTS.md` 是给不同 Agent 运行时使用的薄适配器。
简单说：
`ME.md` 让 AI 理解“我是谁”；
`AGENT.md` 告诉 AI “怎么和我配合”。
第二层：知识生产层
默认 full 模式下，它还会创建完整的 `30.knowledge/` Knowledge Palace v2 结构，用来承接长期知识整理、资料编译、研究归档和输出沉淀。
也就是说：
`ME.md` 解决“AI 怎么理解我”；
`AGENT.md` 解决“AI 怎么和我协作”；
`30.knowledge/` 解决“这些协作结果后续怎么长期沉淀”。
4、适合谁用
我觉得这个 Skill 特别适合这些人：
- 经常使用 AI 编程工具的人；
- 有自己的 Obsidian 知识库的人；
- 经常在不同 AI 工具之间切换的人；
- 不想每次都重复解释自己偏好的人；
- 希望 AI 更像长期协作者，而不是一次性问答工具的人；
- 想把自己的经验、偏好、工作流沉淀成长期系统的人。
如果你也经常觉得：
“这个 AI 能力是有的，但它不懂我。”
那这个 Skill 可能就适合你。
5、使用步骤
使用方式很直接。
先指定你的 Obsidian vault 路径：
```bash
export OBSIDIAN_VAULT_PATH=“/path/to/your/vault”
然后运行：
bash scripts/setup.sh
默认 full 模式会生成完整结构：
your-vault/
├── ME.md
├── AGENT.md
├── CLAUDE.md
├── AGENTS.md
├── .gitignore
├── 00.context/
├── 10.identity/
├── 20.skills/
├── 30.knowledge/
│ ├── 00.system/
│ ├── 10.capture/
│ ├── 20.intelligence/
│ ├── 30.research/
│ ├── 40.notes/
│ ├── 50.frameworks/
│ ├── 60.projects/
│ ├── 70.outputs/
│ └── 90.archive/
├── 40.memory-stream/
└── 50.maps/
如果你只想先体验轻量身份层，也可以运行：
bash scripts/setup.sh --minimal
--minimal 只创建身份层、薄适配器和基础导航，不创建 30.knowledge/。
安装完成后，你只需要把 ME.md 和 AGENT.md 里的占位内容改成自己的真实信息。
以后每次使用 AI 时，可以直接说：
先读取我的
ME.md和AGENT.md，理解我的背景、偏好和协作规则，然后再开始处理任务。
如果 AI 要处理你的知识库内容，则应先读取：
30.knowledge/00.system/methodology.md
6、使用前后对比
使用前
AI 每次都是这样的：
- 不知道你是谁；
- 不知道你的项目背景；
- 不知道你的表达偏好；
- 不知道哪些文件不能改；
- 不知道你的知识库结构；
- 需要你不断补充上下文。
你花了很多时间，不是在完成任务，而是在“重新介绍自己”。
使用后
AI 可以先读取一套稳定上下文：
- 先理解你的身份；
- 再理解你的协作规则；
- 再进入具体任务；
- 输出更贴合你的习惯；
- 不同 AI 工具之间也能共享同一套个人上下文。
这带来的感觉是：
AI 不再像一个临时外包，而更像一个已经了解你工作方式的长期协作者。
7、我后来补上的工程化能力
这次重做之后，我更在意的已经不只是“它能不能用”，而是“它能不能长期维护”。
所以我补了几件事。
1. 轻量路由入口
主 SKILL.md 不再塞满所有说明，而是只保留：
- 触发场景；
- workflow 路由；
- 资源读取顺序；
- 验证入口；
- 版本历史。
这样它更像一个真正的 Skill 入口，而不是一篇越写越长的产品说明书。
2. references 资源层
我把原来堆在主文档里的长说明拆到了 references/ 下，包括：
architecture.mdvault-layout.mdoperation-boundaries.mdmaintenance.md
这样做的好处是：
- 主入口更轻；
- 细节可以按需读取；
- 后续维护时不容易牵一发动全身。
3. 脚手架和文档对齐
之前测评里指出过一个很关键的问题：
文档里说会生成的文件，脚本实际上并没有全部生成。
这次我把它补齐了。
现在 full 模式会真实生成：
CLAUDE.mdAGENTS.md00.context/projects/project-overview.md10.identity/thinking-models.md10.identity/strengths-gaps.md- 完整
30.knowledge/ 30.knowledge/00.system/methodology.md
这样用户看到的、脚本做的、发布包里的内容，终于是一致的。
4. 自检程序
这次我专门补了一个：
python scripts/validate_skill.py
它会检查：
SKILL.md、README、CHANGELOG、发布包版本是否一致；- full 模式是否真的创建完整
30.knowledge/； --minimal是否真的不创建30.knowledge/；- 文档声明路径和脚本产物是否一致；
- zip 文件名、包内版本、包内容清单是否一致。
这一步很重要，因为很多“看起来完整”的 Skill，真正一发布就会在这里暴露问题。
5. 可复现发布
现在发布包不再靠手工整理，而是通过脚本生成：
bash scripts/package_skillhub.sh
这样可以避免出现：
- 源码是一套；
- README 是一套；
- 发布包又是另一套。
我现在更希望它像一个小型产品，而不是一个“我本地能跑”的文件夹。
8、我真实验证了什么
这次我不只做了静态检查，还实际在临时目录里重新执行过安装流程。
我验证了：
- full 模式可以生成完整
30.knowledge/体系； - minimal 模式不会生成
30.knowledge/； - 发布包解压后重新执行，也能得到同样结果；
- 自检脚本通过；
- 打包后的 SkillHub zip 也通过一致性校验。
对应校验命令：
bash -n scripts/setup.sh
python scripts/validate_skill.py
bash scripts/package_skillhub.sh
python scripts/validate_skill.py --dist dist/skillhub/personal-api-2.0.3-skillhub.zip
也就是说，这一版不只是“我觉得它应该可以”，而是已经做过了可重复验证。
9、我的一点思考
我做这个 Skill 的时候，越来越觉得：
未来真正重要的，可能不是“写一个更长的 Prompt”，而是建立一套属于自己的 AI 上下文基础设施。
Prompt 是一次性的。
但个人上下文应该是长期的、可维护的、可版本化的。
Personal API 想解决的就是这个问题：
不是让 AI 记住某一句提示词，而是让 AI 拥有一个稳定入口来理解你。
我现在更愿意把它定义成：
一个“把个人上下文工程化”的 Skill，
而不只是一个ME.md/AGENT.md模板生成器。
它现在已经不只是我自己在用的想法验证，而是一套可以安装、可以验证、可以维护、可以继续迭代的结构。
10、当前版本与链接
当前稳定版：v2.0.3
GitHub：
GitHub - beiyuii/personal-api-skill
欢迎大家试用，也欢迎继续给我提建议。
尤其是如果你也在用 Obsidian、AI 编程工具、个人知识库，或者正在尝试搭建自己的第二大脑，我很想知道你会怎么改这个 Skill。
