Scientific Agent Skills 实战指南：把 AI Agent 变成可执行科研工作流的 AI Scientist

Scientific Agent Skills 是一个开源的 Agent Skills 技能库（当前版本 v2.65.0），收录了 163 个面向生物、化学、医学与科研工程领域的现成技能，让 Cursor、Claude Code、Codex、Google Antigravity 等任何支持开放 Agent Skills 标准的 AI Agent 都能直接执行多步骤科学工作流。读完本文，你将掌握该仓库的三种安装方式与手动接入方法、技能目录的组织结构与 SKILL.md 规范、可直接复制的科研级提示词范例，以及仓库自带的测试契约、安全扫描与贡献校验流程。

1. 仓库定位与整体构成

仓库根目录即一个标准的 Agent Plugins 1.0.0 包：根级 plugin.json 清单加上 skills/ 技能树，插件型客户端可以把整个技能集作为一个插件加载。可以从 plugin.json 确认其名称、版本与 MIT 许可，且版本号与 pyproject.toml 中 [project].version（2.65.0）保持一致——这一点由仓库级契约测试强制执行（见第 6 节）。

README 声明的技能构成如下：

类别	内容
100+ 科学与金融数据库	统一的 database-lookup 技能提供对 78 个公开数据库（PubChem、ChEMBL、UniProt、COSMIC、ClinicalTrials.gov、FRED、USPTO 等）的确定性、可溯源访问；另有 DepMap、Imaging Data Commons、PrimeKG、NCATS ARAX、US Treasury Fiscal Data、Hugging Science、OneKGPd、Genomic Intelligence 等专用技能；BioServices（约 40 个生物信息服务）、BioPython（39 个 NCBI 子库）、gget（20+ 基因组学数据库）进一步扩展覆盖面
70+ Python 包技能	针对 RDKit、Scanpy、PyTorch Lightning、scikit-learn、PyTDC、PathML、pydicom、NeuroKit2、PufferLib、QuTiP、GeoPandas、pymatgen、Qiskit、分子动力学（OpenMM/MDAnalysis）等包显式定义、版本感知的安全工作流
9 个平台集成技能	Benchling、DNAnexus、LatchBio、OMERO、Protocols.io、Open Notebook、Ginkgo Cloud Lab、LabArchives、Opentrons
30+ 分析与通信工具	文献综述、证据可追溯写作、保密同行评审、文档处理、Paperclip（全文论文 + FDA/PMDA/EMA 监管文件 + 试验注册表，行号级引用）、Paperzilla、Exa Search、无宏 PPTX 海报、幻灯片、示意图等
10+ 科研与临床工具	证据有界的假设生成、基金申请、临床决策支持评估、治疗计划格式化、PK/PD 建模与剂量设计、BIDS、ISO 标准证据准备、分析方法验证/转移（ICH Q2(R2)/Q14、ICH M10、USP、CLSI EP）

需要注意一个关键设计立场：显式技能只是"预文档化的优选路径"，并非能力上限——Agent 仍然可以安装和使用任何 Python 包、调用任何 API，技能的价值在于提供更强的版本化指导、示例与安全边界。

每个技能的标准内容：

• 完整文档（SKILL.md）
• 实用代码示例、用例与最佳实践
• 集成指南与参考资料
• 凡附带 scripts/ 的技能，必须有对应的测试套件，CI 会阻止"带工具却不带测试"的 PR

完整技能清单可查阅 docs/skills.md，跨领域工作流实例见 docs/examples.md。

2. 技能目录结构与 SKILL.md 规范

每个技能一个目录，目录名即技能名，且必须与 SKILL.md frontmatter 的 name 字段一致。以 skills/scanpy/SKILL.md 为例，其 frontmatter 结构为：

---
name: scanpy
description: Standard single-cell RNA-seq analysis pipeline. Use for QC, normalization,
  dimensionality reduction (PCA/UMAP/t-SNE), clustering, differential expression...
license: BSD-3-Clause
metadata:
  version: "1.5"
  skill-author: K-Dense Inc.
---

description 承担"何时触发该技能"的说明职责，metadata.version 必须是带引号的数字字符串（贡献规范强制要求）。目录布局（来自 AGENTS.md）：

plugin.json                 # Agent Plugins 清单（仓库根）
skills/<skill-name>/
├── SKILL.md        # 必需
├── references/     # 可选：长文档，按需加载
├── scripts/        # 可选：可执行辅助脚本
└── assets/        # 可选：模板与静态资源

两条容易踩坑的规则：测试绝不放在 skills/ 下（技能目录只交付 Agent 实际加载的内容，测试放在仓库级 tests/<skill-name>/）；图表也不放技能目录，生成的技能示意图统一放 docs/images/<skill-name>.png（本仓库每个技能都有一张 1536x864 的示意图存于此，见 docs/images/）。

SKILL.md 内部的引用一律使用相对技能根目录的一级相对路径。

3. 安装与接入：四条路径

前提条件（README 声明）：Python 3.13+（仅指仓库工具链，单个技能的依赖可支持更宽范围）、uv 包管理器、支持 Agent Skills 标准的客户端（Cursor / Claude Code / Gemini CLI / Codex / Google Antigravity 等）、macOS / Linux / Windows(WSL2)。uv 的安装方式：

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# 或 pip install uv，安装后验证
uv --version

3.1 Option 1：npx（受支持的宿主）

npx skills add K-Dense-AI/scientific-agent-skills

这是面向支持 Agent Skills 标准的宿主的通用安装器，覆盖当前版本的 Claude Code、Claude Cowork、Codex、Gemini CLI、Google Antigravity 与 Cursor；具体安装路径与可选元数据行为以宿主当前文档为准。

3.2 Option 2：GitHub CLI（gh skill，v2.90.0+）

# 交互式浏览并安装
gh skill install K-Dense-AI/scientific-agent-skills

# 只安装某个技能
gh skill install K-Dense-AI/scientific-agent-skills scanpy

# 指定目标宿主
gh skill install K-Dense-AI/scientific-agent-skills --agent cursor
gh skill install K-Dense-AI/scientific-agent-skills --agent claude-code
gh skill install K-Dense-AI/scientific-agent-skills --agent codex
gh skill install K-Dense-AI/scientific-agent-skills --agent gemini

gh skill 会自动安装到对应宿主的正确目录，并记录来源元数据以保证供应链完整性。版本固定与更新：

# 固定到 release 标签或 commit SHA，保证可复现安装
gh skill install K-Dense-AI/scientific-agent-skills --pin v2.65.0
gh skill install K-Dense-AI/scientific-agent-skills --pin abc123def

# 检查 / 更新已安装技能
gh skill update
gh skill update --all

3.3 Option 3：Agent Plugins（Cursor、Codex 等插件客户端）

仓库本身即有效插件包（根 plugin.json + skills/），支持该标准的客户端会发现 skills/ 下每个包含 SKILL.md 的直接子目录。

Cursor——把仓库符号链接或复制到本地插件目录后重载窗口，然后在 Customize 中确认插件与技能出现：

mkdir -p ~/.cursor/plugins/local
ln -s "$(pwd)" ~/.cursor/plugins/local/scientific-agent-skills

Codex——从本地检出安装（当前 CLI 参数名以 Codex 文档为准）：

codex plugins install .

3.4 手动接入其他 Agent Skills 宿主

npx skills add 通常安装到 ~/.agents/skills/（用户级）或 .agents/skills/（项目级）约定路径，需对照宿主文档确认。手动方式：

git clone https://github.com/K-Dense-AI/scientific-agent-skills.git ~/.agents/skills/scientific-agent-skills   # 用户级
git clone https://github.com/K-Dense-AI/scientific-agent-skills.git .agents/skills/scientific-agent-skills      # 项目级

Hermes 支持 skill taps 的版本可执行 hermes skills tap add K-Dense-AI/scientific-agent-skills。

两点实用建议：其一，163 个技能会占用相当多的常驻上下文，README 明确建议只安装主题子集而非全量；其二，对 NemoClaw 这类在默认拒绝出站网络的沙箱中运行 Agent 的宿主，技能可正常被发现加载，但任何需要网络的技能（uv 装包、Exa/NCBI 等 API 调用）必须先在宿主 TUI 中预批准相应域名。

安装完成后，兼容宿主即可从配置路径发现技能并在相关时自动使用；你也可以在提示词中直接提及技能名手动触发。

4. 六个开箱即用的科研提示词范例

README 提供了六组多技能编排提示词，共同模式是先声明"尽可能使用可用技能"，再把多步任务按技能边界拆写。以下是完整范例（节选三组）：

药物发现管线：EGFR 抑制剂优先级排序

Use available skills you have access to whenever possible. Query ChEMBL for EGFR inhibitors (IC50 < 50nM), analyze structure-activity relationships
with RDKit, generate improved analogs with datamol, perform virtual screening with DiffDock
against AlphaFold EGFR structure, search PubMed for resistance mechanisms, check COSMIC for
mutations, and create visualizations and a comprehensive report.

调用技能：database-lookup、rdkit、datamol、diffdock、paper-lookup、scientific-visualization。

单细胞 RNA-seq 全流程

Use available skills you have access to whenever possible. Load 10X dataset with Scanpy, perform QC and doublet removal, integrate with Cellxgene
Census data, identify cell types using NCBI Gene markers, run differential expression with
PyDESeq2, infer gene regulatory networks with Arboreto, enrich pathways via Reactome/KEGG,
and identify therapeutic targets with Open Targets.

调用技能：scanpy、cellxgene-census、database-lookup、pydeseq2、arboreto。

研究用途变异证据审查（合成/脱敏 VCF）

Use available skills you have access to whenever possible. Work only with authorized synthetic
or de-identified data. Parse the VCF with pysam, annotate variants with Ensembl VEP, retrieve
ClinVar/COSMIC/NCBI Gene/UniProt evidence, and verify literature sources. Build an evidence-
traceable research summary with scientific-writing. If clinical-reports is used, create only a
visibly marked draft structure from a verified source-fact manifest for qualified review; do not
diagnose, assess individual risk, recommend treatment, or determine trial eligibility.

调用技能：pysam、database-lookup、paper-lookup、scientific-writing、clinical-reports。注意其中明确写入了安全边界：只处理授权数据、只产出显式标记的草稿、不做个体诊断或治疗建议——这类"验证边界"写法贯穿仓库的临床与法规类技能。

其余三组（多组学标志物发现、虚拟筛选、系统生物学网络分析）以及更多领域用例见 docs/examples.md。

技能类别速览

仓库把 163 个技能划分为 20 个类别，README 中每个类别都给出了成员清单，代表性条目：

• 生物信息学与基因组学（27 个）：bulk RNA-seq 端到端编排、Scanpy/AnnData/scvi-tools/scVelo、gget、deepTools、TileDB-VCF、OneKGPd（3202 人 1000 Genomes 队列查询）、Pathway Enrichment（ORA/GSEA/ssGSEA via gseapy + g:Profiler）、Waypoint 微生物组基础模型等
• 化学信息与药物发现（10 个）：RDKit、Datamol、Molfeat、DeepChem、TorchDrug、DiffDock、OpenMM+MDAnalysis 分子动力学、Rowan 云量子化学、PyTDC 基准
• 临床研究与证据工作流（8 个）：PK/PD 建模（NCA、群体 PK、暴露-效应、生物等效性含 RSABE/ABEL、首次人体剂量、ICH M12 下 DDI 预测——纯 stdlib + numpy/scipy，不调用专有估算软件）、DepMap、Imaging Data Commons、PyHealth 等
• 医疗影像与数字病理（4 个）：pydicom 3.0.2 隐私优先本地预检、histolab 与 PathML 3.0.5 全切片研究分析、DeepSpot-M 虚拟空间转录组
• 机器学习与 AI（14 个）：PyTorch Lightning、Transformers、PufferLib 3.0/4.0 版本分离工作流、scikit-learn、PyMC、aeon、TimesFM 零样本时序预测等
• 材料、化学与物理（7 个）：pymatgen 拆分 wrapper/core + 有界 Materials Project 查询、COBRApy、Astropy、Cirq、PennyLane、Qiskit、QuTiP 5.3
• 科学与工程模拟（6 个）：build123d 实验室硬件 CAD、MATLAB/Octave 双工作流、FluidSim 0.9 有界 CFD、OpenPIV、SimPy 4.1.2、SymPy
• 数据分析与可视化（22 个）：Matplotlib、Seaborn、GeoPandas 1.1.4、GeoMaster、Dask、Polars、Vaex、NetworkX、LiteParse/MarkItDown/PDF/DOCX/PPTX/XLSX、Uncertainty & Units（pint 量纲检查 + GUM 不确定度预算）、Experimental Design（pyDOE3）、Statistical Power 等
• 实验室自动化（6 个）：PyLabRobot 离线优先规划、Opentrons 协议编写、Ginkgo Cloud Lab、Benchling/LabArchives LIMS 集成
• 科学数据库与数据访问（11 个技能 → 100+ 数据库）：database-lookup 一技能统一 78 库，含检索契约、分页/计数对账与端点溯源
• 基础设施与平台（11 个）：Modal 云计算、Optimize for GPU（CuPy/Numba CUDA/cuDF/cuML 等 12 库）、Nextflow、pacsomatic、OMERO、Get Available Resources、Autoskill 工作流挖掘、Pi Agent
• 研究方法与规划（13 个）：Scientific Brainstorming、非评分式 Hypothesis Generation、Arbor（假设树精化 + 留出测试门防过拟合）、What-If Oracle、Consciousness Council、Research Grants 等
• 法规与标准（2 个）：ISO 13485/14971/ISO-IEC 17025/ISO 15189 证据准备（按 --standard 剖面选择流程域）、ICH/USP/CLSI 框架下的分析方法验证与转移——仅产出证据准备物，明确声明永不构成认证、认可或方法放行决定

其余类别（蛋白质工程 4 个、多组学 3 个、神经科学 3 个、质谱 2 个、动物福利 1 个）与每个技能的版本锚定（如 NeuroKit2 0.2.13、pydicom 3.0.2、GeoPandas 1.1.4）均见 README 的 Available Skills 章节。

5. 测试契约：为什么"带脚本必带测试"能被机器强制

仓库不只是文档集合，其质量机制在 tests/ 下有完整实现。README 承诺的"CI 阻止无测试 PR"背后是三层机制：

第一层：仓库级契约测试 tests/_meta/test_repo_contract.py。该套件刻意不导入任何技能代码——用 ast 解析脚本而从不执行，因此可在单个解释器里安全地扫全仓库，且不需要任何科学包，每个 PR 数秒内跑完。它强制的规则包括：

• test_every_skill_with_scripts_has_a_test_suite：凡交付 scripts/ 的技能必须有 tests/<name>/ 目录；
• test_every_suite_has_a_test_file / test_no_test_suite_is_orphaned：测试目录必须有 test_*.py，且目录名必须对应 skills/ 下真实存在的技能；
• test_every_skill_with_scripts_has_a_requirements_entry：每个带脚本技能必须在 tests/skill-requirements.toml 中有 [skills.<name>] 条目（纯 stdlib 技能也要 packages = []）；
• 此外还校验 SKILL.md frontmatter 合规、本地链接可达、脚本可解析、无随附字节码、无硬编码本地路径、--help 行为，以及 plugin.json 与 pyproject.toml 的版本一致性。

第二层：逐技能隔离环境 tests/skill-requirements.toml 为每个技能声明依赖包与解释器版本。tests/run_all.py 的 --isolated 模式按该清单为每个技能构建一次性 uv 环境——文件头注释解释了这个设计的必要性：opentrons 钉死 numpy<2 且无 cp313 轮子、PyTDC 需要 Python 3.11、molfeat 上限 3.10，没有任何单一环境能同时容纳它们。逐技能运行还因为各技能 scripts/ 存在顶层模块同名而必须使用独立 pytest 进程。

第三层：三条常用命令（继承自 README 测试章节，可直接执行）：

# 结构契约与覆盖守卫——秒级完成，无需科学包
uv run python -m pytest tests/_meta -q

# 单个技能的套件
uv run --with pytest python -m pytest tests/<skill-name> -q

# 全部套件，各自在一次性环境中
uv run python tests/run_all.py --isolated

pyproject.toml 中还有一处值得注意的 pytest 配置：addopts = "--import-mode=importlib"，注释说明这是必需的——pytest 默认 prepend 模式会把 tests/ 放进 sys.path，使 tests/<skill>/ 变成可导入的命名空间包，让以所封装库命名的技能（neurokit2、simpy、qutip 等）在 importlib.util.find_spec() 眼中"看起来已安装"。

6. 安全：扫描、审阅与自我验证

README 的安全声明立场明确：技能可以指示 Agent 执行任意代码、安装包、发网络请求、改文件，因此审阅安装内容是用户自身责任。仓库侧的机制包括：

• 所有贡献经过评审，并对每个技能运行基于 LLM 的安全扫描（Cisco AI Defense Skill Scanner），检测提示注入、数据外泄与恶意代码模式；
• 扫描按周增量执行（未变更技能沿用历史结论），至少每 30 天或扫描器/模型变更时全量重扫，结果发布在 docs/security-report.md，策略与漏洞报告渠道见 SECURITY.md 与 docs/security-triage.md；
• 推荐用户自行扫描第三方技能：

uv pip install cisco-ai-skill-scanner
skill-scanner scan /path/to/skill --use-behavioral

官方给出的审阅清单：不要一次性安装全部技能、安装前通读 SKILL.md（它会说明用哪些包、连哪些外部服务）、检查贡献历史（K-Dense 署名的技能经过内部评审）、发现可疑行为立即开 issue。扫描干净只降低评审噪声，不构成无风险保证。

7. 故障排查要点

• 技能不加载：确认技能目录位置正确、每个技能目录含 SKILL.md、复制后重启 Agent/IDE；Cursor 可在 Settings → Rules 中确认发现状态。
• 缺 Python 依赖：查对应 SKILL.md 的依赖声明，uv pip install <package>。
• API 限流：多数数据库有限流，考虑缓存或批量请求。
• 认证错误：部分服务需要 API key，按 SKILL.md 的认证配置核对凭据。
• 路径变更（v2.43.0+）：自 v2.43.0 起技能位于 skills/ 而非 scientific-skills/（对齐 GitHub CLI 期望的 Agent Skills 布局），旧的 scientific-skills/<name> 拷贝路径与引用需更新为 skills/<name>。

8. 贡献流程中的校验命令

新增/修改技能需遵循 CONTRIBUTING.md 与 AGENTS.md：目录名即技能名、metadata.version 从 "1.0" 起、更新既有技能时递增版本号、带 scripts/ 的技能同步交付 tests/<name>/ 与 skill-requirements.toml 条目。提交前的两条标准校验命令（摘自 CONTRIBUTING.md）：

# 规范校验
uv run skills-ref validate ./skills/skill-name

# 安全扫描
uv pip install cisco-ai-skill-scanner
skill-scanner scan ./skills/skill-name --use-behavioral

范围取舍也值得留意：仓库只接收"单个科学包/数据库/平台/工作流"的窄技能，通用软件工程技能、挂个科学例子的通用基础设施、以及路由到其他技能的"编排器"技能通常被拒绝——这一点解释了为什么数据库访问被压成一个 78 库的 database-lookup 而非 78 个独立技能（常驻上下文成本降低约 13.9 倍）。

9. 引用与许可

仓库整体采用 MIT License（LICENSE.md，Copyright © 2026 K-Dense Inc.），但每个技能有独立许可，记录在该技能 SKILL.md 的 license 元数据字段中（例如 skills/scanpy/SKILL.md 声明 BSD-3-Clause），商业使用前需逐一核对。docx、pdf、pptx、xlsx 四个文档技能由 Anthropic 创建维护，vendored 自 anthropics/skills，各带 LICENSE.txt。

建议的引用实践：始终引用整个技能集，并单独引用实际支撑了你工作的具体技能（含其 metadata.version 与技能直链）。集合级 BibTeX：

@software{scientific_agent_skills_2026,
  author = {{K-Dense Inc.}},
  title = {Scientific Agent Skills: A Comprehensive Collection of Scientific Tools for AI Agents},
  year = {2026},
  url = {https://github.com/K-Dense-AI/scientific-agent-skills},
  note = {163 skills covering databases, packages, integrations, and analysis tools}
}

单技能引用示例（含版本号与技能级 URL）：

@software{scientific_agent_skills_astropy_2026,
  author = {{K-Dense Inc.}},
  title = {Astropy Skill for Scientific Agent Skills},
  year = {2026},
  url = {https://github.com/K-Dense-AI/scientific-agent-skills/tree/main/skills/astropy},
  note = {Version 1.0, part of Scientific Agent Skills}
}

10. 快速 FAQ 摘要

• 免费吗？ 仓库 MIT 许可，免费商用；但单个技能许可各异，以各自 SKILL.md 的 license 字段为准。
• 为什么打包在一起而不是独立包？ 科学天然跨学科，全量打包让基因组学、化学信息学、临床数据与机器学习能在一个工作流中组合，免去挑选和接线。
• 离线能用吗？ 数据库类技能需联网查询 API；包类技能装好依赖后可离线工作。
• 需要装全部 Python 包吗？ 不需要，各技能在 SKILL.md 中声明自己的依赖，按需安装。
• 支持哪些模型/宿主？ SKILL.md 遵循开放的 Agent Skills 标准；安装路径、发现机制与可选元数据支持因宿主和版本而异，以目标宿主当前文档为准。

综合来看，Scientific Agent Skills 的核心方法论是：用带 frontmatter 的 SKILL.md 把"怎么做"（版本锚定的工作流、脚本、安全边界）显式交付给 Agent，用仓库级契约测试把"质量下限"机器化，用安全扫描与独立许可把"信任边界"写清楚。对使用者的实际路径是：选一个主题子集 → npx skills add 或 gh skill install → 用第 4 节的提示词范式发起多步科研任务 → 对临床/法规类输出始终保留合格人员复核。