1. 基本信息
| 项目 | 内容 |
|---|---|
| 名称 | variant-annotation-gptomics-bioskills |
| 作者/维护者 | GPTomics（GitHub 组织，自述为专注生物学的 AI 研究实验室）；主要维护者 djemec |
| 来源链接 | https://github.com/GPTomics/bioSkills/tree/main/variant-calling/variant-annotation |
| 许可证 | MIT（GitHub API 确认，仓库根 LICENSE 文件） |
| GitHub Stars | 1,126（GitHub API；数字属整个 bioSkills 合集，不代表本技能自身热度） |
| Forks | 193（同上，合集整体） |
| 最新版本 | 仓库无该子目录专属版本标签；该路径最近一次相关提交为 2026-07-10，此前另有多次提交横跨 2026-01～07 |
| 安装方式 | 见第 10 章 |
2. 功能介绍与亮点
variant-annotation 教 agent 用 bcftools annotate/csq、Ensembl VEP、SnpEff、ANNOVAR 四款主流引擎给 VCF 变异标注功能后果、人群频率与致病性预测分数，核心贡献是把“注释结果为什么会漂移”这个容易被忽视的问题讲透：
- 点破“一个变异只有一个真实注释”的误区：技能明确指出，变异的注释后果不是变异本身的固有属性，而是（变异、转录本模型、引擎、引擎版本、参数集）这个元组共同决定的结果；换任意一个元素，报告出的功能后果、HGVS 表示乃至下游 ACMG PVS1 判定都可能改变。据此给出的原则是“锚定”而非“找到唯一正确答案”——固定基因组版本、转录本集（GRCh38 上优先 MANE Select）、引擎+版本、预测器+版本、gnomAD 版本，并把这些参数写进报告。
- 四引擎选型对照：bcftools annotate/csq、VEP、SnpEff、ANNOVAR 各自的转录本集合、剪接区宽度、上下游窗口、HGVS 位移规则与后果严重性排序均不同，技能逐项列出差异来源（并引用 McLaren 2016、Cingolani 2012、Wang 2010 三篇方法学论文）。
- gnomAD 频率解读陷阱：区分 v2（GRCh37，141,456 人）/v3/v4（GRCh38，约 73 万外显子组+7.6 万基因组）三个版本口径差异，指出应使用按人群分层的最高频率（grpmax）而非单一全局等位基因频率阈值做良性判定，并列举隐性遗传病携带者、晚发外显不全疾病、体细胞克隆造血污染三类“gnomAD 里出现≠良性”的例外情形。
- 附完整 Python（cyvcf2 解析 VEP CSQ/SnpEff ANN 字段）与 bash（norm→VEP MANE 优先注释→按 HIGH/MODERATE 后果筛选）两套可运行代码模式，以及一张“症状-原因-修复”结构的常见错误对照表，正文引用 15 篇正式学术文献（含 REVEL、AlphaMissense、CADD、SpliceAI 等预测工具的原始论文）。
3. 适用场景
所属分类：数据分析与可视化（技能产出是对 VCF 变异数据的功能注释、频率标注与致病性打分，属对基因组数据做结构化分析的范畴）。
适用人群：拿到 VCF 变异文件后需要选择合适注释引擎、锁定转录本集与预测器版本、并正确解读 gnomAD 人群频率避免误判良恶性的临床基因组学分析师与生信研究人员；尤其适合需要为 ACMG PVS1/PP3/BP4 等下游分类条款准备可复现证据的场景。
4. 跨 Agent 兼容性
| Agent 生态 | 结论 | 依据 |
|---|---|---|
| Claude Code | 原生支持 | 仓库提供 install-claude.sh，支持全局/按项目/按类别安装 |
| Codex | 原生支持 | 仓库提供 install-codex.sh，用法与 Claude Code 版本一致 |
| OpenClaw | 原生支持 | 仓库提供专用 install-openclaw.sh |
| Hermes Agent | 原生支持 | Hermes 官方生物信息学技能网关文档将 bioSkills 列为其两个开源技能库之一（“385 reference skills”，直接指向 GPTomics/bioSkills 仓库），并在 variant-calling 类目下按名列出 variant-annotation；用户经 hermes skills install official/research/bioinformatics 安装该网关后可直接取用本技能 |
5. 推荐理由
VEP、SnpEff、ANNOVAR、bcftools 是四款几乎人人都听说过的注释工具，但多数使用者默认“跑一遍就有唯一正确答案”，很少意识到换引擎、换转录本集、换版本会得到不同结果，更容易在报告致病性时误用单一全局 gnomAD 频率阈值。这个技能把“注释是非确定性的”这一核心原则、四引擎差异来源与三类“频率里出现≠良性”的真实陷阱一次讲透，并配好可直接运行的代码模式，能帮助使用者产出经得起复现检验的注释结果，而不是“跑出来就信”。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 7 | GPTomics 是小型专业研究团队，非广为人知的一线厂商；本技能路径在 LobeHub 技能市场有独立收录页（bio-variant-annotation），且被 Hermes Agent 官方生物信息学网关按名收录，构成子技能自身可查证的独立第三方证据 |
| 可用性 | 8 | 文档详实（正文+四引擎对照+常见错误表+15 篇学术引用），版本兼容性说明清晰，该路径近期仍有独立提交（最近一次 2026-07-10），但需预先安装 VEP/SnpEff/ANNOVAR 等外部注释引擎与数据库缓存才能实际跑通，非开箱即用 |
| 安全性 | 9 | 全文仅为本地 CLI/Python 代码模式（bcftools、VEP、SnpEff、ANNOVAR、cyvcf2），未见任何联网外发、API Key 索取或可疑指令，MIT 许可证明确 |
安全检查清单： ① shell 命令执行：技能本身不含自动执行脚本，所有 bash/Python 代码模式需用户/agent 在自己环境中手动运行 ② 联网外发数据：正文未见任何网络请求代码；注释流程依赖预先下载到本地的 VEP 缓存、ANNOVAR 数据库等离线资源，不在运行时联网外发数据 ③ API key/凭据：不需要 ④ 可疑指令：通读全文未发现 prompt injection 或其他可疑指令 ⑤ 作者/组织信誉：GPTomics 为 GitHub 组织，主要维护者 djemec 长期主导仓库提交，无刷星或造假迹象 ⑥ License：MIT，明确 ⑦ 最近维护时间：该技能路径最近提交 2026-07-10，约一个月前；仓库整体最近 push 于 2026-07-25，在近 3 个月维护窗口内
7. 跟同类 Skills 相比的优势
| 竞品 | 定位 | 与本技能的差异 |
|---|---|---|
genomic-variant-interpretation（awslabs/hcls-agent-skills） |
AWS 官方出品，把 ACMG/AMP 变异分类框架固化为零依赖单文件技能 | 处理的是注释完成后的下一步——ACMG/AMP 临床分类打分；本技能专注更上游的功能注释本身（选引擎、锁转录本、读频率），两者是同一变异解读流水线上前后相接、职责不重叠的两个环节 |
ngs-analysis（openai/plugins） |
OpenAI 官方出品，先探测本地测序文件类型再路由到对应处理流程 | 面向整条 NGS 流程的广度路由（FASTQ/BAM/VCF 各阶段），不含变异注释引擎选型、转录本集陷阱或 gnomAD 版本口径这类深度专项知识；本技能是单一环节的深度专家 |
同合集 variant-normalization（bioSkills） |
变异标准化（左对齐、拆分多等位基因位点） | 是注释前的必要预处理步骤，本技能正文明确将其列为前置依赖；两者顺序相接而非功能重叠 |
同合集 clinical-interpretation（bioSkills） |
ACMG/AMP 与 AMP/ASCO/CAP 框架下的最终致病性分类 | 是注释完成后的下一步，本技能正文明确注明“不含 ACMG 组合规则或最终分类，请见 clinical-interpretation” |
8. 用户评价
该技能在 LobeHub 技能市场已有独立收录页，但截至目前评论区与评分区均显示暂无内容，尚无具名用户评价。
9. 其他补充
所属仓库 bioSkills 根目录下共含 65 个功能类目目录（GitHub API 实测核实），README 自述约 561 个子技能。variant-calling 类目下与本技能相邻的还有 gatk-variant-calling、deepvariant、structural-variant-calling、vcf-basics、vcf-manipulation、vcf-statistics 等技能，彼此通过 SKILL.md 内的 “Related Skills” 区块互相引用，显示该合集在变异处理方向有统一的架构设计而非零散堆砌。
10. 安装使用方式
- Claude Code（推荐）：
git clone https://github.com/GPTomics/bioSkills.git && cd bioSkills && ./install-claude.sh --categories "variant-calling"按类别安装，或不带参数全量安装；也可手动把variant-calling/variant-annotation/目录复制到.claude/skills/ - Codex：同一仓库下运行
./install-codex.sh - OpenClaw：运行专用的
./install-openclaw.sh - Hermes Agent：运行
hermes skills install official/research/bioinformatics安装官方生物信息学网关后即可取用 - 安装后注意事项：技能本身零额外安装，但运行其推荐代码需预先装好 VEP（含离线缓存）、SnpEff、ANNOVAR（含数据库）与 bcftools/cyvcf2 等工具；无需重启 agent；对话中出现“变异注释”“VEP/SnpEff/ANNOVAR”“gnomAD 频率解读”等关键词或直接引用技能名即可触发
11. 注意事项
- 技能提供的是引擎选型、转录本口径与频率解读的方法与代码模式，不代替用户预先安装 VEP/SnpEff/ANNOVAR 及其配套数据库
- 文档明确警示：不同引擎、不同转录本集、不同版本会对同一变异给出不同注释结果，比对多份历史报告前必须先确认各自锁定的引擎版本与转录本集是否一致
- 技能本身不含 ACMG/AMP 最终致病性分类逻辑，需配合同合集
clinical-interpretation技能完成完整的变异解读流程 - 合集仓库整体 1,126 stars 与 193 forks 覆盖数百个子技能，不代表本技能个体的采用热度