scientific agent skills

Abstract

Turn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000+ scientists worldwide. 165 ready-to-use validated skills plus 100+ scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.

The Problem

Scientific teams need a reusable catalogue of proven “agent skills” – discrete, validated operations (e.g., literature search, molecular‑dynamics setup, PK/PD modelling) that can be invoked by any LLM‑backed workflow engine. Maintaining those pieces as ad‑hoc scripts leads to duplication, version drift, and fragile integrations.

What This Does

The repository ships 163 ready‑to‑use skill specifications plus 100+ curated scientific data sources. Each skill lives under skills/<domain>/ and is described by a SKILL.md manifest together with optional reference files (e.g., references/api-endpoints.md). The plugin.json declares the package as an Agent‑Skills plugin, making the whole collection discoverable by any agent that implements the open Agent Skills standard (Cursor, Claude Code, Codex, Antigravity, etc.).

The test harness in tests/_contract/cli.py validates that every skill conforms to the schema defined in .github/workflows/skill-spec-validation.yml. Continuous‑integration pipelines (.github/workflows/skill-tests.yml, security-scan.yml) run those tests on every PR, ensuring new skills stay consistent.

How It Is Wired

scan_skills.py ──► load_skill_dirs() ──► read SKILL.md & references
               │
               └─► validate_schema() (uses jsonschema from pyproject.toml)
               │
               └─► register_skill() → plugin.json (Agent‑Skills manifest)

Entry point – The only executable script is scan_skills.py. Running it (python scan_skills.py) walks the skills/ tree, parses each SKILL.md, and writes a consolidated JSON manifest that agents consume.
Core functions – load_skill_dirs (in scan_skills.py) enumerates the 2 040 files under skills/. validate_schema pulls the JSON‑Schema from pyproject.toml ([tool.poetry.dependencies] jsonschema). register_skill updates plugin.json with the skill IDs and metadata.
External effects – No network calls or database writes occur during a normal scan; the only side‑effect is the generation of build/skill_manifest.json (created on‑the‑fly, not versioned).
Hub / blast radius – scan_skills.py is the single point that touches every skill file; a regression here could break validation for the whole catalogue. All other modules are passive data providers.
Unmapped wiring – The repository does not contain a runtime server or CLI that directly executes a skill; execution is delegated to the consuming agent (e.g., K‑Dense BYOK) which reads the manifest generated by the scan step.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/scientific-agent-skills
cd scientific-agent-skills

# Install the Python package (editable for development)
pip install -e .

# Generate the skill manifest that an Agent can import
python scan_skills.py   # produces build/skill_manifest.json

No additional configuration files are required. Agents that understand the Agent Skills spec simply point to the generated manifest (or to the repository itself, since plugin.json declares the package name and version).

If you prefer the pre‑built BYOK co‑scientist, follow its README; it pulls this repo as a dependency and handles the manifest generation automatically.

Real‑World Use

A downstream LLM orchestrator can request “run a differential‑expression analysis” by sending the skill ID scvi-tools/differential_expression to the Agent. The agent reads the corresponding SKILL.md (found under skills/scvi-tools/) to locate the required Python snippet, installs any listed pip packages, and executes the code in an isolated environment. The result (e.g., a CSV file) is returned to the orchestrator without the orchestrator needing to know the implementation details.

from agent_skills import load_manifest
manifest = load_manifest("build/skill_manifest.json")
result = agent.invoke(manifest["scvi-tools/differential_expression"], inputs)

Code Health & Issues

Low – Dependencies declared without lockfile – pyproject.toml lists packages but no poetry.lock or requirements.txt; reproducible builds rely on the resolver at install time.
Low – Secret‑shaped paths – skills/modal/references/secrets.md contains placeholder paths that could be confused with real secrets; no actual keys are committed, but the file should be renamed or documented as a template.

All other static checks (CI status badges, test count) show no critical failures. Documentation is extensive (237 Markdown files), and the CI pipelines validate skill schemas on every push.

The Bottom Line

The repo delivers a well‑organized, standards‑compliant catalogue of scientific agent skills, ready for consumption by any LLM‑based workflow engine. Its single‑point‑of‑truth scanning script is simple but critical; missing a lockfile and the presence of placeholder secret paths are the only notable gaps. Teams that need a plug‑and‑play skill library for AI‑assisted research will find it immediately usable, while developers extending the catalogue should focus on the scan_skills.py path to avoid broad impact.