ssinder/bioinformatics-agent-skills · 上手攻略

  • 仓库：ssinder/bioinformatics-agent-skills
  • 链接：https://github.com/ssinder/bioinformatics-agent-skills
  • 分类：agent / computational-biology / Agent Skills 标准
  • 作者：spark
  • 更新：2026-10-30

0. 自检清单

项 状态
GitHub URL 已 fetch ✅ README（main 分支）+ API 元数据已拉取
文档站 ✅ ssinder.github.io/bioinformatics-agent-skills/（GitHub Pages）
README 关键子模块 anchor ✅ skills/（17 个技能包）、packages/biopipe_core + packages/biopipe（共享层与 CLI）、scripts/validate_skills.py、scripts/init_skill.py、tests/、docs/、7 条 CI 流水线
仓库元数据 Python；34 stars / 1 fork（API 于 2026-10-30 读取，卡片记 33 → 已增长）；MIT License；创建 2026-10-25，push 2026-10-27
规范 anchor ✅ 遵循开放的 Agent Skills 标准（agentskills.io）

⚠️ 版本浮动提示：仓库无 release / tag（API 未列 releases），"版本"只能锚定 main 分支 commit。技能内部用 metadata.version: "1.0" + metadata.last-reviewed: "2026-10-25" 做单技能版本标记（bulk-rnaseq 的 frontmatter 已核）。

1. 是什么

这是一个面向计算生物学的 Agent Skills 技能库——把 17 个真实的科研工作流打包成标准化 SKILL.md 包，让 Claude Code、Cursor、Codex 等任何支持 Agent Skills 标准的宿主 AI 编程助手"变成计算生物学家的研究搭档"。

一句话概括它的立场：

多数 AI 助手能写 scanpy 代码，但它们不知道单细胞数据过滤前线粒体基因百分比该降到多少、DESeq2 的 padj 为什么突然全变成 NA、RMSF 曲线的第一个尖峰对应哪个柔性环。

这些才是本项目携带的东西。 每个技能除了脚本，还带三样：

  • references/methodology.md —— 参数选择背后的科学推理
  • references/troubleshooting.md —— 常见故障的根因
  • SKILL.md 里的 Validation 段 —— 怎么检查结果是对的

项目自称由一个私有档案里的 217 个真实科研脚本重构而来，重构后变成 17 个可独立安装的技能、58 个 Python 文件、900 个测试用例。作者强调"从 217 降到 58 不是能力缩减——去掉的是重复和脚手架"。

一个技能包的目录结构（docs/SKILL_SPEC.md 严格规定）：

skills/<skill-name>/
├── SKILL.md              # 必需，Agent Skills 标准格式
├── scripts/              # 可执行脚本，路径参数化 + logger 化
│   └── <entry>.py
├── references/           # 可选但推荐
│   └── *.md
├── requirements.txt      # 可选
└── README.md             # 可选

2. 解决什么问题

痛点不是"AI 不会调 API"，而是AI 不知道什么时候不该调、也不知道调完之后怎么验证。

具体三个层次：

  1. 触发问题：你要做 RNA-seq 差异分析，得先知道该用哪个包、该按什么顺序调、每个参数取什么值。现在这些散落在几十篇文档和某个人的脑子里。
  2. 验证问题：AI 跑完给你一张图和一个 p 值表，它不会告诉你 size factor 落在 0.5 意味着某个样本建库出问题，也不会告诉你"火山图两侧不对称"是个危险信号。
  3. 可复现问题：没有固定随机种子、没有记录参数、没有版本锁定，跑两次结果不一样。

这个项目通过把领域知识写进可被 Agent 读取的结构化文档来解决第一和第二个问题，通过固定种子 + 记录参数 + 版本锁定 + 写入 run metadata 来解决第三个。

覆盖范围：转录组、单细胞、蛋白结构、分子动力学、蛋白对接（HDOCK / LightDock）、链间接触分析 + PyMOL 可视化、抗菌肽设计、ML 肽生成、文献挖掘、NCBI BioProject 元数据、发表级图表。

3. 快速安装

⚠️ 要求 Python 3.9+。文档站明确说："核心安装只需要 requests + pyyaml，其余全部通过 optional extras 提供"。

方式一：装成 Claude Code 技能（最直接）

git clone https://github.com/ssinder/bioinformatics-agent-skills.git
cp -r bioinformatics-agent-skills/skills/* ~/.claude/skills/

重启 Claude Code，技能即被自动发现。然后直接说 "run a bulk RNA-seq differential expression analysis"，它会自己加载 bulk-rnaseq 技能。

Cursor / Codex 等宿主同理，把 skills/ 目录放到各自约定的技能目录即可（具体路径本文未逐个核实，见坑 8）。

方式二：作为 Python 包 + CLI

pip install -e .
biopipe --list                      # 列出全部技能
biopipe bulk-rnaseq --help         # 单个技能的用法

方式三：直接调脚本

export PYTHONPATH="$PWD/packages"

# 肽的理化性质
python skills/peptide-design/scripts/analyze_peptides.py \
    --input peptides.fasta --output results/peptide_stats.csv

# ROC 曲线
python skills/scientific-figures/scripts/make_figures.py roc \
    --input metrics.csv --output figures/roc.png

# 文献检索
python skills/literature-search/scripts/search_literature.py \
    --topic "antimicrobial peptide delivery" --source pubmed --max-results 50

开发环境

git clone https://github.com/ssinder/bioinformatics-agent-skills.git
cd bioinformatics-agent-skills
pip install -e ".[dev]"

python -m pytest tests -v              # 跑测试
python scripts/validate_skills.py      # 校验所有技能
python scripts/validate_skills.py --strict   # 把警告当失败

4. 核心用法

4.1 一次完整的 bulk RNA-seq 差异分析

（skills/bulk-rnaseq/SKILL.md 的 Quick Start 原文命令）

export PYTHONPATH="$PWD/packages"
python skills/bulk-rnaseq/scripts/run_pipeline.py \
    --input  /data/fastq \
    --output /results/rnaseq \
    --transcriptome /ref/transcriptome.fa \
    --tx2gene /ref/tx2gene.tsv \
    --metadata /data/metadata.csv \
    --go-annotation /ref/go_annotation.csv \
    --group-a treated --group-b control

八步工作流：FastQC 质控 → fastp 过滤 → Salmon 定量 → counts 矩阵构建 → DESeq2 差异分析 → GO/KEGG 富集 → 可视化 → 报告。

最有价值的设计是双后端：--backend python 用内置纯 NumPy/SciPy 实现（size factor 归一化、Cox-Reid 离散度估计、趋势拟合、MAP 收缩、Wald 检验、BH 校正），--backend r 调 Rscript + Bioconductor DESeq2。两者输出同一套列名的结果表，可直接互换对比。

跳过外部工具、直接从已有 Salmon 结果开始：

python skills/bulk-rnaseq/scripts/run_pipeline.py \
    --input /data/fastq --output /results/rnaseq \
    --skip-qc --skip-trimming --skip-quant \
    --quant-dir /results/rnaseq/03_salmon \
    --tx2gene /ref/tx2gene.tsv \
    --metadata /data/metadata.csv \
    --group-a treated --group-b control --backend python

单独构建 counts 矩阵：

python skills/bulk-rnaseq/scripts/build_counts_matrix.py \
    --quant-dir /results/rnaseq/03_salmon \
    --tx2gene /ref/tx2gene.tsv \
    --output /results/counts

关键参数：--design（默认 ~condition）、--alpha（默认 0.05）、--lfc-threshold（默认 1.0）、--min-counts（默认 10）、--min-gene-set / --max-gene-set（默认 5 / 500）、--threads（默认 8）。

产出目录结构清晰：04_counts/（counts.csv / tpm.csv / fpkm.csv）、05_deseq2/（deseq2_results_full.csv 含 baseMean/log2FoldChange/lfcSE/stat/pvalue/padj/significant/direction、size_factors.csv、dispersions.csv）、06_enrichment/enrichment_{BP,CC,MF}.csv、07_figures/Figure{1..5}_*.{pdf,png}（300 DPI）、08_report/analysis_report.txt、run_manifest.json。

4.2 Validation 段：技能真正的差异点

bulk-rnaseq 的验证清单值得完整读一遍——它就是"AI 不会告诉你的那部分"：

  • counts 矩阵：各样本列和是否接近（差异过大 = 测序深度差异大，要查 size factor）；确认 gene ID 与注释文件 ID 空间一致。
  • size factor：应集中在 1 附近（0.5–2）。出现极端值通常意味着某样本建库或测序异常。
  • 火山图：显著点应呈对称双翼；MA 图应大致平坦。大量点集中在 log2FC = 0 附近是正常的。
  • p 值分布：期望绝大多数 padj > 0.05；若几乎全部显著，多半是分组标签写反或存在批次混杂。
  • 离散度：落在下限（1e-8 附近）说明该基因数据量不足，p 值不可用。
  • 富集：检查 Overlap_Genes 与 Term_Genes 的比例与背景基因数；min_gene_set 太小会得到大量无意义的极小 term。
  • 交叉验证：同一数据用 --backend python 和 --backend r 各跑一次，比较 log2FC 排序与显著基因集合是否基本一致。

4.3 无依赖也能跑的核心算法

设计原则之一是 "Self-contained —— 核心算法以纯 Python 实现"。举几个具体例子：

  • molecular-dynamics：自带的纯 numpy DCD 与 PDB 轨迹解析器 + Kabsch-Sander 对齐 + SVD-PCA + RMSD 矩阵的层次聚类 + 几何氢键检测 + RMSF + 回转半径 + Ramachandran + 链间接触 + Shrake-Rupley SASA。没装 OpenMM 也能解析轨迹、算 RMSD/PCA。
  • protein-structure：自带 PDB 解析器 + DSSP 二级结构。
  • protein-interactions：解析 PLIP XML。
  • protein-docking-lightdock：GSO 群智能优化 + DFIRE 打分解析。
  • peptide-design：分子量、等电点、Kyte-Doolittle 疏水性、不稳定指数、MMseqs2 聚类去冗余。

4.4 其它常用技能

技能 关键能力
ena-download ENA Portal API 取 FASTQ，支持 HTTP Range 断点续传 + MD5 校验
single-cell-rnaseq QC 过滤、CP10K 归一化、HVG、PCA、Leiden 聚类、UMAP、细胞注释
alphafold-db 从 API 动态解析当前 PDB/CIF 下载 URL（不硬编码模型版本）、批量下载、pLDDT 质量过滤、校验 content-type（避免把 HTML 错误页当结构文件）
protein-docking-hdock HTTP 表单提交作业、Docking Score、置信度公式、区分"排队中"与"完成"
pymol-structure-visualization 网格空间划分、氢键/盐桥/疏水/π-π/阳离子-π 分类、热点残基、Mermaid 网络图、PyMOL 脚本生成
peptide-design 理化性质 + 基于 GO 词和序列特征的抗菌/非抗菌判别
ml-peptide-generation PepMLM-650M 掩码语言模型、非法残基（X/B/Z）过滤、伪困惑度排序、可复现随机种子
bio-database-fetch PubChem PUG-REST 批量属性（100 ID/请求）、CAS 号提取、完整分类谱系、无浏览器依赖
literature-search PubMed + OpenAlex + Semantic Scholar、DOI 去重、RIS/BibTeX/GB/T 7714 导出
bioproject-search NCBI E-utilities API（非爬网页），标题/描述/物种关键词过滤
paper-fulltext-extract GROBID → TEI、章节树/图/参考文献解析、JSON/MD/HTML 输出、语料检索、引言首句提取
scientific-figures ROC、混淆矩阵、热图、火山图、SHAP 摘要、统一发表风格

4.5 技能规范（docs/SKILL_SPEC.md，严格强制）

SKILL.md 的 YAML frontmatter 必须包含：

---
name: <skill-name>          # 小写连字符，与目录名一致
description: <第三人称描述；必须包含 "This skill should be used when..." 说明触发时机>
license: MIT
compatibility: <运行时要求，如 Python 3.9+ 及关键依赖>
metadata:
  version: "1.0"
  last-reviewed: "2026-10-25"
  skill-author: sinder
---

description 的要求：第三人称写法、必须同时说明做什么和何时触发（含触发关键词，英文关键词必须出现，因为用户可能用英文提问）、长度 100–400 字符、禁用第二人称（不许写 "Use this skill when"）。

正文必须有 8 个 ## 二级标题：Overview / When to Use This Skill / Quick Start / Workflow / Parameters / Outputs / Validation / References。

脚本的硬性规则：

  1. 顶部插入 sys.path.insert(0, str(Path(__file__).resolve().parents[3] / "packages")) 并 from biopipe_core import get_logger, get_config, SkillError
  2. 绝不硬编码绝对路径，所有输入输出路径来自命令行参数
  3. 绝不裸用 print()，改用 get_logger("biopipe.<skill-name>")
  4. 统一用 biopipe_core.cli.bootstrap_cli(description, skill_name, main) 作入口，main(args) 返回退出码，必须暴露 --input / --output 等业务参数
  5. 每个脚本必须有 shebang + 编码声明 + 带用法示例的模块 docstring
  6. 必须有 if __name__ == "__main__":
  7. 没有输入文件时必须能 --help 干净退出（不依赖真实数据）
  8. 不依赖重型第三方库的模块，import 时优雅降级（缺 scanpy/matplotlib 时给清晰错误，而不是抛 ImportError 栈）

5. 典型适用场景

  • 让 AI 助手做正经的生物信息分析：不是"帮我写个 scanpy 代码"，而是"跑一次 bulk RNA-seq 差异分析并出发表级图表"，且结果可信。
  • 可复现性要求高的课题组：固定种子 + 记录参数 + 版本锁定 + 900 个测试。
  • 把私人脚本资产标准化：从一堆散落的 .py 变成可被发现、可触发、有文档、有测试的技能库。docs/migration-map.md 是很好的模板——它完整记录了 217 个脚本的映射关系、每一处重写理由和每一处修复的科学缺陷。
  • 跨 AI 助手迁移能力：因为遵循开放标准，同一套技能可以在 Claude Code / Cursor / Codex 之间搬家。
  • 不想装 R / Bioconductor 的环境：--backend python 的纯 NumPy/SciPy 实现是刻意设计的降级路径。

6. 坑与注意

坑 1：AI 助手不一定会主动加载技能。 现象：技能装好了，但你问的方式不含触发关键词，它就不用；影响：明明有技能却没用上；修复：技能 description 里已内置英文+中文触发词（如 "RNA-seq"、"bulk RNA-seq"、"转录组"、"差异表达"、"DEG"、"DESeq2"、"Salmon"、"counts matrix"、"GO 富集"、"KEGG 富集"、"pathway enrichment"），提问时带上这些词命中率更高。

坑 2：pip install -e . 后 biopipe 命令找不到。 现象：CLI 不在 PATH；影响：方式二不可用；修复：确认 editable 安装成功，或直接用方式三的 export PYTHONPATH="$PWD/packages" + python skills/<name>/scripts/<entry>.py。

坑 3：脚本要靠 PYTHONPATH 才能 import 到共享层。 现象：ModuleNotFoundError: biopipe_core；影响：直接调脚本全挂；修复：显式 export PYTHONPATH="$PWD/packages"（README 的示例都带这一行，但方式一的 cp -r 安装不保证宿主能自动解析）。

坑 4：环境里没有 R / Bioconductor 时，--backend r 会失败。 现象：调用 Rscript 报错；影响：双后端交叉验证做不了；修复：改用 --backend python（默认），或自行装 R + DESeq2。注意 README 明确说"多数 AI 助手能写 scanpy 代码"但不假设你的环境有 R。

坑 5：外部工具缺失（fastqc / fastp / salmon）。 现象：完整流程在中途报错；影响：跑不动全流程；修复：要么装这些工具，要么用 --skip-qc --skip-trimming --skip-quant 复用已有定量结果。

坑 6：scanpy / matplotlib 缺失时的导入期报错。 现象：ImportError 栈；影响：skill 整体不可用；修复：项目规范要求"不依赖重型库的模块必须优雅降级，给清晰错误而不是栈"——但只对符合规范的模块生效，第三方可选依赖仍可能直接抛栈，装之前先看该技能的 requirements.txt。

坑 7：.claude/skills/ 是 Claude Code 专用路径，Cursor / Codex 路径不同。 现象：复制过去后技能不被发现；影响：方式一"失效"；修复：查各宿主自己的技能目录约定。⚠️ 本文未逐个核实 Cursor / Codex 的确切路径，仅依据 README 声明"works with Claude Code, Cursor, Codex"。

坑 8：biopipe --list 与 README 的技能表可能不完全同步。 现象：README 列 17 个技能，实际 --list 数量对不上；影响：困惑；修复：以 --list 为准；README 徽章写的是 "Skills-17"。

坑 9：网络请求需要显式参数，不能默认联网。 现象：脚本默认行为与预期不符；影响：不可预期的网络调用；修复：docs/SKILL_SPEC.md 明确"不允许把网络请求作为脚本默认行为"，涉及联网的技能必须显式传参。

坑 10：NCBI E-utilities 要求提供联系邮箱。 现象：检索被限流或拒绝；影响：literature-search / bioproject-search / bio-database-fetch 不可用；修复：按 NCBI 使用政策提供 contact email。

坑 11：legacy 仓库曾泄露飞书 App Secret。 现象：历史提交 a3e456c 引入的 10 个文件含明文凭据，而该仓库当时是公开的；影响：凭据可被从 git history 中提取；修复：有效补救是在飞书开发者控制台重置 App Secret（已做，旧值立即失效）；代码侧清理保留在 security/credential-cleanup 分支。⚠️ 本项目已明确不修改原仓库，你也应避免把密钥写进任何 SKILL.md 或脚本。

坑 12：安全扫描器的正则曾有漏洞。 现象：原 ci_security_scan.py 匹配 \b(secret)\b，因下划线和字母都是单词字符，APP_SECRET 整个漏检；影响：凭据扫描形同虚设；修复：正则已修，并用 32 个回归测试锁定行为，其中包含一个反向验证金丝雀（把正则改回旧形式，测试立刻失败）。这是本仓库 CI 设计里最值得学的一点。

坑 13：17 个技能并非原 217 个脚本的一一对应。 现象：找某个特定脚本时找不到对应技能；影响：误以为能力缺失；修复：查 docs/migration-map.md——pptx_create 被归档重定向（→ workbuddy-pptx）、feishu_bot 做安全清理、omics_analyze 和 rnaseq_r 是空目录；另有 3 处无一对一映射（search_pubmed+search_openalex 合并为一个 literature-search；afdb_download 的模型提取合并进 alphafold-db；plip_interact 独立成 protein-interactions）。

坑 14：重构时修掉的科学性缺陷，别自己再踩一遍。 现象：某些脚本看着"简单"其实是原实现有 bug；影响：得出错误科学结论；修复：migration map 记录的缺陷清单极有价值——例如 pymol-structure-visualization 原用 cmd.select(f"{a} within {cutoff} of {b}") 选邻近残基再取笛卡尔积，两个关键原子相距 15 Å 也会被报成"接触"；ASP/GLU 被列为氢键供体（羧酸根在生理 pH 无氢，系统性高估氢键数）；所有 HIS 被算作正电荷（咪唑仅约 4% 质子化，盐桥高估约 25×）；配体（LIG/HEM）被强行塞进残基分类表，苯环配体会被报成"疏水残基"；bulk-rnaseq 的 design 误指定导致 padj 全 NA，静默产出无意义的差异表达结果；molecular-dynamics 平衡化协议不完整，未经能量最小化就进入生产模拟。

坑 15：仓库很新，无 release / 无 tag。 ⚠️ 仓库创建于 2026-10-25，push 停在 2026-10-27，仅 1 个 fork、0 个 open issue、1 个 subscriber。"成熟度"在仓库卡里被标为 experimental，这是准确的——它更像一个高完成度的方法论样板，而不是久经考验的工具。复现请记录 commit hash。

坑 16（⚠️ 待补）：部分数字口径来自仓库自述，未独立交叉验证。 "217 → 58 脚本"、"900 个测试"、"7 条 CI 流水线"、"17 个技能"这些数字均取自 README / 文档站原文（已 fetch）。本轮未逐项核对 tests/ 目录实际用例数与 CI workflow 文件数。

7. 与同类对比

维度 bioinformatics-agent-skills Claude Code 内置技能 MCP 生物信息服务器 纯 prompt 模板 Bioconductor / Galaxy 工作流
形态 Agent Skills 标准包（SKILL.md + scripts + references） Anthropic 官方技能集 工具调用协议（JSON-RPC） 纯文本 图形界面 / R 包
领域深度 带 methodology + troubleshooting + validation 通用开发任务 取决于服务器实现 无 完整但需用户自己搭
可复现性 固定种子 + 记录参数 + 版本锁定 无保证 取决于服务器 无 R 环境可复现但配置重
离线可用 核心纯 Python 实现可离线 — 需服务器在线 — 需本地装
依赖负担 核心仅 requests + pyyaml 宿主自带 需跑服务 无 重
可移植性 开放标准，跨宿主 绑定 Claude Code 跨宿主（协议层） 跨宿主 跨宿主
上手成本 cp -r 或 pip install -e . 内置 需部署 + 配置 最低 高

核心差异：它不是"给 AI 装工具"，而是给 AI 装判断力。MCP 服务器解决的是"AI 能调用什么"，本项目解决的是"AI 知道什么时候该调、参数怎么取、结果怎么验"。两者可以叠加而非互斥。

与纯 prompt 模板比：prompt 模板把知识写在对话里，AI 可能不看；SKILL.md 是结构化、有触发描述、有验证清单、可被工具读取的包，这是它对 Agent 工作流更友好的原因。

与 Galaxy / Nextflow 比：那些是给"人"用的流水线引擎，强调 DAG 编排和大规模复现；本项目是给"Agent"用的，强调可被语义触发、每次都有验证清单、单技能可独立安装。

8. 一句话推荐结论

如果你是想让 AI 助手真正接手生物信息分析而不是"帮你写段代码"，这个库的思路是对的——把方法学、根因和验证清单一起打包进 Agent Skills 标准格式，是目前少见的做法；但仓库仅创建一周、无 release、依赖生态仍需你自查，建议先拿 bulk-rnaseq 或 literature-search 单个技能试水，验证 --help 与 Validation 清单在你环境里确实能跑通，再考虑全量安装。

附：来源清单

  • https://raw.githubusercontent.com/ssinder/bioinformatics-agent-skills/main/README.md（README 全文，已 fetch）
  • https://raw.githubusercontent.com/ssinder/bioinformatics-agent-skills/main/docs/SKILL_SPEC.md（技能规范契约全文，已 fetch）
  • https://raw.githubusercontent.com/ssinder/bioinformatics-agent-skills/main/docs/migration-map.md（217→58 映射表 + 缺陷修复清单 + 安全事件，已 fetch）
  • https://raw.githubusercontent.com/ssinder/bioinformatics-agent-skills/main/skills/bulk-rnaseq/SKILL.md（单技能 SKILL.md 完整格式与 Validation 段，已 fetch）
  • https://ssinder.github.io/bioinformatics-agent-skills/（官方文档站，已 fetch）
  • https://api.github.com/repos/ssinder/bioinformatics-agent-skills（元数据：Python / 34 stars / MIT / pushed 2026-10-27 / 13 个 topics）
  • 仓库卡 organized/repo_cards/4736-ssinder-bioinformatics-agent-skills.md