【Skill 测评】Personal API：别再让 AI 每次都重新认识你

[大模型善后工程师-K叔]

原贴：【Skill 创作】Personal API：别再让 AI 每次都重新认识你
作者： 用户54561

---

哇喔，很有意思的skill。

好的，回到skill上，首先说，我没法在内容层面上去评价skill的好坏，这个很多时候超出了我的能力，但是我可以在一些实现的技巧或者方法论上去给出一些建议。

一句话结论

personal-api-skill 的产品表达和内容成熟度较高，模板与脚手架也有明显实用价值；但如果按我的标准来看，它目前更像“高质量产品说明 + 安装包”，还没有完全收敛成“结构化、可路由、可验证、可发布”的 Skill。

复杂度判断

结论：复杂 Skill

判断依据：

• 存在多个阶段性产物：SKILL.md、模板、脚手架、README、变更记录、示意图
• 存在多个稳定用户意图：搭建 vault、安装身份层、给 AI 建协作契约、引入 Knowledge Palace 方法论
• 存在多个独立资源层：安装脚本、模板、产品文档、方法论文档
• 明显预计持续扩展：CHANGELOG.md 已有 1.x → 2.x 演进，且已从“身份模板”扩大为“知识系统脚手架”

因此，若要继续长期维护，建议补出 workflow 映射，而不是继续把所有能力堆进单一说明文档。

主要优点

1. 产品定位非常清楚

SKILL.md 开头的价值主张很强，能快速说明这个 Skill 解决什么问题，以及为什么不是普通模板集合。尤其是 “identity contract + behavior contract + navigation layer” 这组三元抽象，很适合作为传播和触发入口。

2. 资源组合是有实用闭环的

这个 Skill 不是纯说明文档，而是完整打通了：

• 主文档
• 模板
• 脚手架
• 双语 README
• 图示资产

这使它具备较强的落地能力，而不是停留在概念层。

3. 边界意识较强

Track A / Track B 的分离、ME.md 不允许 AI 代写、隐私提醒、批量删除需要确认，这些都说明作者对 AI 协作中的权限边界有明确意识。

参考：

• SKILL.md
• templates/methodology.md

4. 安装脚本安全性和可重复执行性不错

setup.sh 使用 set -euo pipefail，并通过 copy_if_missing / ensure_file 保留已有文件，整体风格偏稳健，适合对真实 vault 执行。

参考：

• scripts/setup.sh

主要问题

P0. 当前 Skill 缺少版本信息

当前 SKILL.md 在 frontmatter 中没有顶层 version 字段，而是把版本放在 metadata.version 内。

文档中也缺少：

• 头部 > **版本**: vX.Y.Z
• 文末 ## 版本历史

这个在版本管理或者发布上可能不够硬

P0. 主 SKILL.md 不是“路由层”，而是 README / manifesto / 操作手册的混合体

按 我的理解，主 SKILL.md 应主要承载：

• 触发边界
• workflow 路由
• 关键动作
• 校验入口

但当前 SKILL.md 将以下内容长期常驻在正文：

• 产品宣传和 elevator pitch
• 六种方法论解释
• 完整目录结构
• AI 操作边界
• frontmatter 规范
• FAQ
• Tips

这使得主文档更像“完整产品说明书”，而不是一个上下文节制的 Skill 路由层。

同时，文中没有 ## @工作流:、### @步骤N:、HTML 注释元数据、- @动作: 等结构化标记，不利于机器稳定解析。

P0. 文档承诺与脚手架实际产出不一致

这是当前最重要的工程一致性问题之一。

SKILL.md 的目录结构中明确展示了以下文件：

• CLAUDE.md
• AGENTS.md
• 00.context/projects/project-overview.md
• 10.identity/thinking-models.md
• 10.identity/strengths-gaps.md

但 scripts/setup.sh 实际不会创建这些文件。

这会导致两个后果：

1. 用户按文档理解安装结果时，会期待一套比实际更完整的输出
2. 后续 AI 若按文档去读取这些路径，可能碰到不存在文件

更好的做法只有两种：

• 要么脚本补齐这些文件
• 要么文档把它们明确标注为“可选扩展，不由脚手架自动生成”

证据：

• SKILL.md
• scripts/setup.sh

P1. CHANGELOG.md、frontmatter 和当前文件清单之间存在漂移

CHANGELOG.md 中声明新增了：

• frontmatter.metadata.use_cases
• frontmatter.metadata.examples
• .gitignore

但当前 SKILL.md 的 frontmatter 中并没有 use_cases 或 examples；正文里虽然存在 Prompt examples 章节，但它不是变更记录中声称的 frontmatter 元数据。

此外，当前 Skill 目录文件清单中也没有看到 .gitignore。

这类“变更记录说有，当前产物里没有”的漂移，会降低维护可信度。

证据：

• CHANGELOG.md
• SKILL.md

P1. 模板完成度不完全一致

templates/ME.md 和 templates/methodology.md 都有更完整的 frontmatter 结构，但 templates/AGENT.md 的 frontmatter 仅包含：

• layer
• description

同时，AGENT.md 里还保留了 3 个未具体化的场景项：

• 用户要求创意 / 发散
• 用户要求严谨 / 收敛
• 涉及敏感信息

占位本身并非问题，因为这是供用户填写的模板；但这三个场景恰好是高频边界条件，如果保持纯空位，实际交付的“行为契约”就会在关键时刻最不明确。

建议至少把这三项改成“带默认推荐写法的模板”，而不是完全留白。

证据：

• templates/AGENT.md

P1. 缺少专门的工程校验脚本

当前 Skill 有安装脚本，但没有 scripts/validate_skill.py 一类的工程校验入口。

对于这个 Skill，最有价值的可执行检查其实很多，例如：

• SKILL.md 中声明的关键路径是否被 setup.sh 实际创建
• 模板文件是否齐全
• --minimal 模式是否跳过 30.knowledge/
• 目标 vault 上的产出结构是否与文档一致
• README 中提到的关键文件是否都存在

这些规则如果只写在文档里，不写成校验脚本，长期维护时很容易漂移。

P2. 资源分层清楚，但未对齐命名和入口习惯

目前目录大致是：

• templates/
• scripts/
• docs/
• README*

这在产品仓库里完全合理，但从规范看，仍然存在两个可改进点：

1. docs/ 更像“资产 + 参考”混合区，职责边界不够显式
2. 主文档没有明确说明“什么时候应加载哪个资源”

例如：

• 需要真正安装时才读 scripts/setup.sh
• 需要填写身份层时读 templates/ME.md
• 需要限定 AI 行为时读 templates/AGENT.md
• 需要在 30.knowledge/ 下执行整理动作时读 templates/methodology.md

这些入口关系在内容上是存在的，但没有被主 Skill 正式建模成路由规则。

工作流重构建议

如果按复杂 Skill 标准重构，我建议先拆成以下 4 个 workflow：

工作流	类型	做什么	不做什么	上游	下游	失败回流	可否单独触发
安装 Personal API	主 workflow	检查 vault 前置条件，执行 setup.sh，说明 full/minimal 差异	不负责填写个人信息	用户提供 vault 路径	填写模板、校验结构	路径错误或模板缺失时回到前置检查	是
填写身份契约	主 workflow	指导用户完成 ME.md / AGENT.md 的关键字段	不直接代写用户真实身份内容	安装完成	AI onboarding、长期协作	信息不完整时回到用户补充	是
启动知识生产轨	主 workflow	指导 AI 在 30.knowledge/ 下按 methodology 运作	不修改 Track A 核心身份内容	安装完成 + methodology 已就位	日常整理 / 编译 / 周月复盘	边界不清时回到 methodology 判定	是
校验与维护	子 workflow	检查脚手架产物、路径存在性、模板版本一致性、月度健康检查	不代替业务内容整理	任意阶段	持续维护	发现漂移时回到文档或脚本修正	否

优化建议

第一优先级

1. 给 SKILL.md 补齐 version 顶层字段、头部版本块、文末版本历史。
2. 把当前大段说明型内容下沉，主文档只保留触发边界、workflow 路由、关键资源入口。
3. 让 setup.sh 与目录结构文档保持一致，二选一：
   • 补脚手架输出
   • 缩文档承诺

第二优先级

1. 增加 scripts/validate_skill.py。
2. 明确资源路由关系，告诉执行者何时读取：
   • templates/ME.md
   • templates/AGENT.md
   • templates/methodology.md
   • README.md
3. 修正 CHANGELOG.md 与当前 frontmatter / 文件清单之间的漂移。

第三优先级

1. 为 templates/AGENT.md 的 3 个关键场景补默认推荐模板。
2. 若要完全对齐 kz-skill-creator，可考虑把：
   • 方法论说明
   • vault 结构参考
   • AI 边界说明
     拆到 references/ 中。
3. 给复杂 Skill 增加 design.md，保存 workflow 映射表和重构决策。

建议的重构方向

如果目标是“保留现有产品表达，同时提高 Skill 工程化程度”，建议采用下面的折中方案：

• SKILL.md
  • 只保留触发边界
  • 定义 3-4 个 workflow
  • 显式声明资源入口
  • 提供验证入口
• references/
  • architecture.md
  • vault-layout.md
  • operation-boundaries.md
• templates/
  • 保留现有 3 个模板
• scripts/
  • 保留 setup.sh
  • 新增 validate_skill.py
• docs/
  • 只放图片 / 视觉资产

这样既不破坏它的产品感，也能更接近“轻主文档 + 重资源层 + 可校验”结构。

总评

从“产品完成度”看，我会给这个 Skill 较高评价；从规范的 Skill 工程化程度”看，我会给中等评价。

它最强的地方是：

• 价值主张清晰
• 模板、脚手架、方法论之间已经形成闭环
• AI 权限边界意识强
• 文档写作质量高，传播性强

它最需要补的地方是：

• 结构化标记
• 版本与验证闭环
• 路由层与说明层分离
• 文档承诺与脚手架产出一致性

如果后续目标是“对外长期维护、多人复用、持续迭代”，建议优先补工程化；如果目标只是“作为一个高质量可安装仓库继续使用”，那它现在已经有很强的实用价值。