scholaraio: Skill for Claude Code

Scientific Tool Onboarding

Overview

先判断一个科学工具是否值得进入 ScholarAIO；只有通过 2.x integration gate 后，接入目标才是形成这三个层次的闭环，而不是“写一份长教程”：

• toolref 能查官方接口和参数
• 对应 skill 能指导 agent 何时使用、如何验证
• CLI 在真实使用中足够稳，不只是测试能过

规范参考：

• 公开接入说明统一参照 docs/guide/toolref-onboarding.md
• 产品边界与准入门统一参照 docs/design-docs/2.x-public-contract.md
• 运行时行为统一参照 scientific-runtime skill

When to Use

适用于：

• 新增一个科学计算工具到 scholaraio toolref
• 升级某个工具的官方文档源或版本策略
• 发现现有 scientific skill 过重，需要改成 toolref-first

不适用于：

• 只写一篇一次性笔记
• 只修一个小 typo

Core Workflow

0. 先过 2.x integration gate

不要因为用户提到一个项目、它很热门，或官方文档可抓取，就默认把它接入 ScholarAIO。先逐项确认：

• 它解决的是已经出现的核心学术任务，而不是增加一个新的平台类别
• 当前 agent 原生能力与已有 ScholarAIO 路径不能充分完成这个任务
• 没有另一套重叠适配器在做同一件事，并且有明确维护责任
• 依赖、凭据和运行时可以保持可选并与 core install 隔离
• 可以设计固定语料或端到端 smoke 来证明用户任务确实改善
• 缺凭据、断网、上游漂移或服务不可用时，能给出可执行错误或 fallback

任何一项不满足时，优先采用外部 recipe、用户自管工具或 sidecar；不要继续下面的内置接入流程。升级既有工具时也要重新过门，不因历史存在而自动保留。

1. 再定“官方真源”

优先级：

• 官方文档站
• 官方源码仓库中的文档目录
• 官方维护的 README / man page / PDF

不要优先用：

• 博客
• 第三方教程
• 论坛帖子

要求：

• 记录文档 URL、版本策略、格式（RST / HTML / man / Markdown / PDF）
• 判断适合 git 抓取还是 manifest 抓取

经验判断：

• 如果官方文档天然按源码版本演进、结构稳定、页面很多，优先 git
• 如果官方文档是独立文档站、页面总数可控、但抓取噪音和网络波动明显，优先 manifest
• 不要为了“理论更完整”强行选 git；用户在乎的是 agent 能不能顺手查到
• 如果文档站有“总目录页 / 命令索引页 / 手册页目录”，优先把它作为自动发现种子，而不是手写所有子页面

当前项目里的经验：

• QE / LAMMPS / GROMACS 更适合 git + parser
• OpenFOAM / Bioinformatics 更适合 manifest + curated entry pages

2. 再定“接入粒度”

问自己三个问题：

• 用户会按什么名词来查：求解器、命令、参数、字典、子工具？
• page_name 应该怎么命名，未来最稳？
• program / section / title 该怎样存，show/search 才顺手？

经验规则：

• page_name 要服务 CLI 使用体验，不要只服务抓取方便
• 一个大页面如果天然包含很多独立参数，应该拆页
• 如果工具本来就是多子工具工具链，允许一个 top-level tool 下挂多个 program
• program 要优先贴近用户会说出的名字，而不是内部类名或目录名
• section 要反映用户排查问题时的思路，例如 solver / dictionary / variant-calling

从现有工具得到的粒度经验：

• QE：程序名 + namelist + 参数名，这样 show qe pw ecutwfc 才顺
• LAMMPS：命令家族一定要做 alias 聚合，不然 fix npt 这种自然输入会漂走
• GROMACS：mdp 参数页必须尽量保留 options，不然会变成只有变量名的空页
• OpenFOAM：不要一上来想抓完整站点，先抓 solver / dictionary / post-processing 关键页
• Bioinformatics：要承认它是 toolchain，不是单软件；先解决“路由到哪个子工具”