让 AI Agent 真正读懂你的资料：我开源了 source-skill-pipeline

让 AI Agent 真正读懂你的资料：我开源了 source-skill-pipeline

你有没有遇到过这种情况：

你把一个 GitHub 仓库、产品文档、OpenAPI 文件，甚至一份 PDF 丢给 AI Agent，希望它以后能稳定理解这套资料。但结果往往是：第一次回答还不错，第二次开始泛化，第三次已经在猜。

这不是某个模型"不够聪明"。

很多时候，问题在于我们没有把知识源变成一个可复用、可触发、可验证的 Skill。

所以我做了一个开源项目：

GitHub: rockyyve/source-skill-pipeline

source-skill-pipeline 是一个工作流型 Skill。它的目标很直接：把任意知识源，转换成可靠的 Claude / Codex Skill。

它不是再写一个"万能提示词"。它更像是一条技能生产流水线：先从真实 source evidence 里生成草稿，再经过优化、校验、评测和打包，最后得到一个可以安装、可以复用、也更不容易乱触发的 Skill。

为什么需要一条 Skill 生产流水线？

现在越来越多开发者开始给 AI Agent 配 Skill。

一个好的 Skill，通常能解决三件事：

1. 告诉 Agent 什么时候应该使用它。
2. 告诉 Agent 应该读取哪些资料。
3. 告诉 Agent 遇到不同情况时怎么行动。

听起来很简单，但手写起来很容易翻车。

最常见的问题有几个：

• 只复制 README，缺少真实工作流。
• Skill 描述太宽，导致 Agent 误触发。
• 生成的命令、API、路径没有证据来源。
• 文档很长，SKILL.md 被塞成一坨。
• 没有 eval prompts，后续改动无法验证。
• 本机缺工具时，流程直接中断。

这些问题在小项目里不明显。一旦你要把一个真实仓库、产品文档站、API spec、团队 handbook 或多份资料做成 Skill，就会非常明显。

source-skill-pipeline 想解决的正是这个问题：让"从资料到 Skill"这件事变得可重复、可降级、可审查。

它到底是什么？

一句话概括：

source-skill-pipeline 是一个把任意知识源转换成可靠 AI Skill 的工作流型 Skill。

它会把整个过程拆成两个阶段：

1. 分析阶段 ：用 skill-seekers 或等价方式读取知识源，生成基于证据的 draft skill。
2. 优化阶段 ：用 skill-create、skill-creator 或手工优化流程，校验、收敛、评测并打包最终 Skill。

重点不是某个工具必须存在。

重点是保住这个契约：

draft 必须来自真实资料；最终 Skill 必须经过优化和验证。

这也是这个项目和"让 AI 帮我写个 SKILL.md"的区别。

支持哪些知识源？

项目设计时没有把目标限定在代码仓库。

只要是 skill-seekers 支持，或者可以被人工 fallback 解析的 source，都可以进入这条流水线。

当前 README 中列出的典型 source 包括：

• 本地代码仓库
• GitHub repository
• 文档网站
• PDF / Word / EPUB / PPTX
• OpenAPI / Swagger 规格
• Jupyter Notebook / HTML / AsciiDoc / man page
• RSS / Atom feed
• YouTube 或本地视频
• Confluence / Notion
• Slack / Discord 等 chat export
• 多个资源组合成的 unified source set

这意味着它既能做"项目专属 Skill"，也能做"API 使用 Skill""产品文档 Skill""团队 onboarding Skill"。

工作流长什么样？

整体流程可以理解成这样：

flowchart TD A["提供 source 或 source set"] --> B["发现本机可用工具"] B --> C{"skill-seekers 可用？"} C -- "是" --> D["生成 3 个推荐 Skill 名称"] C -- "否" --> E["询问是否安装 skill-seekers"] E --> F{"安装成功？"} F -- "是" --> D F -- "否" --> G["按 source 类型 fallback 分析"] D --> H["用户选择或自定义名称"] H --> I["从真实资料生成 draft skill"] G --> I I --> J["规范化 Skill 目录"] J --> K{"skill-create / skill-creator 可用？"} K -- "是" --> L["优化、评测、校验"] K -- "否" --> M["手工执行 skill-creator 风格优化"] L --> N["打包 .skill"] M --> N N --> O["报告产物、fallback 和置信检查"]

这里有几个设计点我觉得很重要。

1. 先发现工具，而不是假设工具都在

项目里有一个辅助脚本：

python scripts/discover_skill_tools.py

它会检查当前环境里是否存在这些命令：

skill-seekers
skill-create
skill-creator
claude
codex

同时，它还会查看 skill-seekers --help，判断本机实际支持哪些 source 类型。

这一步看似朴素，但很关键。

不同开发者的本机环境差异很大。有人装了 skill-seekers，有人只装了 skill-creator，有人两个都没有。与其写死一条"理想路径"，不如先探测，再选择最合适的执行路线。

2. 名称先收敛，避免 Skill 变成一堆临时目录

生成 Skill 时，命名会影响后续安装、触发和维护。

source-skill-pipeline 会先根据 source 标题、repo 名、URL、文件名或业务目标，生成 3 个 kebab-case 推荐名。

比如：

stripe-api
api-integration
payments-docs

然后用户选择一个，或者提供自定义名称。

最终目录名和 SKILL.md frontmatter 里的 name 会统一成：

<selected-name>-skill

如果用户已经写了 -skill 后缀，就不会重复追加成 -skill-skill。

这类小规则非常适合交给流水线处理。因为它不难，但靠人手维护很容易漏。

3. draft 不是事实，source evidence 才是事实

这是我在做这个项目时最想强调的一点。

AI 生成的 draft 只能是起点。它可能结构漂亮，语气顺滑，但这不代表它一定正确。

所以这个 Skill 的设计原则之一是：

Source evidence first.

命令、API、路径、流程、约束，都应该能追溯到真实资料。

如果是代码仓库，就从 README、manifest、配置、入口、测试、文档里找证据。

如果是 OpenAPI，就解析 endpoint、认证方式、schema、example 和常见集成流程。

如果是文档站，就提取标题、术语、流程、示例和决策边界。

这比"根据项目名字猜一个 Skill"可靠得多。

4. fallback 是一等路径

很多工具型工作流的问题是：只要某个依赖不存在，整条链路就断了。

source-skill-pipeline 的思路不是这样。

skill-seekers 是首选分析器，但缺少时会先询问是否安装。如果无法安装、用户不想安装，或者当前环境不适合安装，就进入 fallback。

skill-create 可以提高优化效率，但缺少它也不应该阻塞任务。此时可以使用 skill-creator 或手工执行同类优化：

• snapshot 原始 draft
• 改进 SKILL.md 描述和触发条件
• 增加真实 eval prompts
• 检查 frontmatter 和命名
• 尽可能执行 eval 或轻量人工审查
• 打包最终 Skill

这点对真实开发很有用。

因为工具链永远不会在每台机器上都刚好完整。

怎么开始用？

先克隆仓库：

git clone https://github.com/rockyyve/source-skill-pipeline.git

如果你的 Agent 支持本地 Skill 目录，可以把这个仓库作为一个 Skill 目录安装或引用。

如果你使用 .skill 包，也可以按 README 里的方式打包：

mkdir -p dist
zip -r dist/source-skill-pipeline.skill source-skill-pipeline \
  -x 'source-skill-pipeline/evals/*' \
  -x '*/__pycache__/*' \
  -x '*.DS_Store'

如果你本机有 skill-creator 的打包脚本，也可以使用对应脚本打包。

然后，你可以这样调用：

请使用 source-skill-pipeline，把当前目录这个项目做成一个 skill。
先给我 3 个推荐名称，我选一个后再继续。

或者处理一个 GitHub repo：

请使用 source-skill-pipeline，把这个 GitHub repo 做成项目专属 skill：
https://github.com/example/example-app
重点提取开发命令、目录结构、测试方式和常见任务流程。

处理 OpenAPI：

把 ./specs/payments.yaml 做成一个 API 使用 skill。
重点让之后的 agent 能快速理解认证、核心 endpoint、请求响应 schema 和常见集成流程。

处理混合资料：

把 docs 网站、GitHub repo 和 Notion handbook 合成一个 onboarding skill。
输出前请说明用了哪些 source、哪些 fallback，以及哪些事实来自证据。

一个典型输出应该包含什么？

我理想中的最终 Skill，不应该只有一个 SKILL.md。

更合理的结构大概是：

your-project-skill/
├── SKILL.md
├── README.md
├── references/
│   └── source-map.md
├── scripts/
│   └── optional-helper.py
└── evals/
    └── evals.json

其中：

• SKILL.md 放高频、必要、运行时需要的指令。
• references/ 放较长的资料映射、命令表、API 细节。
• scripts/ 放可执行辅助脚本。
• evals/ 放维护和验证用例。

这里也有一个非常实用的原则：

不要把所有东西都塞进 SKILL.md。

SKILL.md 越臃肿，触发越不稳定，维护越痛苦。

真正长的知识应该放到 references/。运行时入口只需要告诉 Agent：什么时候用、先读什么、怎么决策、不要做什么。

适合谁？

如果你只是偶尔让 AI 看一下 README，这个项目可能有点重。

但如果你符合下面任意一种情况，它就很适合你：

• 你维护多个项目，希望每个项目都有专属 Agent Skill。
• 你有一套内部文档，希望 Agent 能稳定遵循。
• 你经常把 OpenAPI、PDF、Notion、Confluence 转成 AI 可用知识。
• 你在做团队 onboarding，希望新人和 Agent 都能快速理解上下文。
• 你正在写自己的 Skill，希望有一条可验证的生产流程。
• 你不想每次都手写一份"差不多能用"的 SKILL.md。

它尤其适合那些已经开始认真使用 AI Coding Agent 的开发者。

因为这类人通常会很快意识到：上下文本身也是工程资产。

它目前的边界

作为一个开源项目，source-skill-pipeline 还处在比较早期的阶段。

所以我不想把它包装成"全自动、零成本、适配所有场景"的神器。

更准确地说，它现在提供的是一套清晰的工作流约束：

• 优先从真实 source evidence 出发。
• 优先使用 skill-seekers 做 source 分析。
• 优先使用 skill-create / skill-creator 做优化和评测。
• 缺工具时不直接失败，而是进入 fallback。
• 输出前检查命名、frontmatter、证据引用和 eval prompts。

这套约束本身就很有价值。

因为 AI 生成内容很容易，但生成可维护的 Skill 很难。

为什么我推荐你试试？

我做这个项目的初衷，是想把"个人经验"变成"可复用流程"。

以前我们做 Skill，很多判断都靠直觉：

• 这个 Skill 该什么时候触发？
• README 里的哪些信息应该进 runtime？
• 哪些长内容应该放到 references？
• 命令是不是来自真实资料？
• 没有某个工具时要不要停？
• 怎么验证它真的能用？

source-skill-pipeline 把这些问题变成了一条明确流水线。

它未必替你省掉所有思考，但能帮你少踩很多重复的坑。

如果你也在做 Claude / Codex Skill，或者正在把团队知识搬进 AI Agent，我建议你可以从一个小项目试起：

1. 选一个你熟悉的 GitHub repo。
2. 用 source-skill-pipeline 生成一个项目专属 Skill。
3. 看它提取了哪些 evidence。
4. 看 eval prompts 能否覆盖真实任务。
5. 再决定要不要推广到团队资料库。

最后

项目地址：

github.com/rockyyve/so...

如果你对 AI Agent、Codex / Claude Skill、团队知识工程感兴趣，欢迎 star、试用、提 issue。

也欢迎在评论区交流：

• 你现在是怎么管理 Agent Skill 的？
• 你最想把哪类资料变成 Skill？
• 你更需要自动分析、优化评测，还是打包发布？

我会继续迭代这个项目，也希望它能成为大家构建可靠 AI Skill 的一条基础流水线。