# alterlab-ieu/alterlab-academic-skills architecture

> Architecture diagram of the GitHub repository alterlab-ieu/alterlab-academic-skills, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alterlab-ieu/alterlab-academic-skills
- Repository: https://github.com/alterlab-ieu/alterlab-academic-skills

## Overview

1. **What this repository is**
   - This is a **content-and-tooling repository for Claude “skills”**, not a conventional application.
   - The main product is a catalog of **210 domain-specific skill packs** organized for Claude Code, Claude.ai, and the open Agent Skills standard.

2. **Primary source-of-truth layer: `skills/`**
   - The architecture is centered on `skills/<domain>/<skill>/SKILL.md`.
   - Each skill directory is a bounded unit that may also include **references**, **assets**, **scripts**, and **evals**.
   - The repo is split into **16 domains** such as core, databases, bioinformatics, cheminformatics, clinical research, data science, visualization, writing tools, lab integrations, research tools, finance/economics, Turkish academia, faculty life, methodology, and others.

3. **Skill package anatomy**
   - A skill is usually composed of:
     - `SKILL.md`: the activation prompt and behavioral contract
     - `references/`: domain knowledge and procedures
     - `assets/`: reusable templates, styles, examples, or configs
     - `scripts/`: helper programs used by the skill
     - `evals/evals.json`: test cases proving the skill behaves as expected
   - This structure keeps **narrative guidance**, **procedural knowledge**, and **executable checks** separate but co-located.

4. **Core pipeline subsystem**
   - `skills/core/` is the cross-cutting orchestration layer.
   - It includes the major workflow skills: **Deep Research**, **Paper Writer**, **Paper Reviewer**, **Research Pipeline**, **Citation Verifier**, **Teaching Design**, **Thesis Supervisor**, **Link Health**, and **Workflow Orchestration**.
   - This is where the repository’s “multi-agent academic workflow” is assembled, including shared agent roles, slash commands, and integrity-focused workflows.

5. **Shared contracts and schemas**
   - `skills/core/shared/` contains reusable **handoff schemas** and JSON schemas for common outputs such as bibliographies, review reports, integrity reports, research briefs, synthesis, and revision roadmaps.
   - These shared schemas act as a boundary between skills: they let different skills exchange structured artifacts without tightly coupling them.

6. **Domain connector and analysis subsystem**
   - The large middle of the repository is a set of **specialized connector skills** for scientific databases, lab platforms, and analysis libraries.
   - Examples include PubMed, OpenAlex, Crossref-like citation workflows, UniProt, ChEMBL, GEO, Dask, scikit-learn, Scanpy, RDKit, Qiskit, OMERO, Benchling, and many others.
   - Architecturally, these skills are the “execution adapters” that bridge Claude into external APIs, research databases, and scientific Python ecosystems.

7. **Deterministic verification and eval layer**
   - Every skill ships with `evals/evals.json`, and the repository claims **210/210 eval coverage**.
   - The eval format is standardized on the **agentskills.io schema** and is used as a machine-checkable quality gate.
   - A standout subsystem is the **citation verifier**, which is explicitly deterministic and checks claimed references against scholarly services rather than relying only on model reasoning.

8. **Build, normalization, and generation scripts**
   - `scripts/` contains the repository’s build and maintenance pipeline:
     - catalog generation
     - marketplace generation
     - skill normalization and auditing
     - spec checking
     - bundle building
     - eval execution
   - These scripts transform the authored skill corpus into derived artifacts like `skills.json`, marketplace metadata, and release bundles.

9. **Distribution surfaces**
   - The repo supports three main delivery modes:
     - **Claude Code plugin** via `.claude-plugin/marketplace.json`
     - **Claude.ai bundles** via per-domain release zips
     - **Manual/project installs** by copying skills into `.claude/skills/` or `~/.claude/skills/`
   - That means the same source corpus is repackaged for different runtime environments, with bundle size/file-count constraints handled at release time.

10. **Generated catalog and site**
   - `skills.json` is the machine-readable inventory of the corpus.
   - `docs/site/index.html` and the GitHub Pages workflow publish a browsable catalog.
   - The catalog is therefore a **derived artifact** from the skill metadata, not a separate manually maintained dataset.

11. **CI and governance boundary**
   - `.github/workflows/` encodes the repo’s enforcement model:
     - link checking
     - pytest-based repository tests
     - spec conformance
     - skill validation
     - release packaging
     - GitHub Pages publishing
   - This is important architecturally because the repository treats **content correctness** and **schema conformity** as build-time guarantees.

12. **Tests as repository invariants**
   - `tests/` checks structural rules such as body length, frontmatter schema, eval presence, plugin agent registration, references hygiene, and script compileability.
   - These tests protect the corpus from drift: the repo is engineered to keep every skill package machine-loadable and consistently shaped.

13. **Provenance, documentation, and policy**
   - The repo includes extensive governance and provenance files: `PROVENANCE.md`, `THIRD_PARTY_NOTICES.md`, `CITATION.cff`, `CONTRIBUTING.md`, `SECURITY.md`, and design docs under `docs/design/`.
   - These are not just documentation; they define the trust boundary for reuse, attribution, and release history.

14. **How the data flows end-to-end**
   - Authoring starts in `skills/**/SKILL.md` plus local references/assets/scripts/evals.
   - Validation runs through tests and eval harnesses.
   - Build scripts generate the catalog, marketplace metadata, and distribution bundles.
   - CI gates the whole pipeline.
   - Consumers then install the skills via Claude Code, Agent Skills tooling, or Claude.ai bundles.

15. **Mental model for an architecture diagram**
   - Think of the repo as three layers:
     - **Content layer**: the skill corpus itself
     - **Tooling/validation layer**: scripts, schemas, tests, evals, CI
     - **Distribution layer**: plugin marketplace, bundles, generated catalog, GitHub Pages
   - The key architectural idea is that **skills are the product**, while the surrounding scripts and workflows ensure they remain portable, validated, and releasable.

Main entry points: [`skills/core`](https://github.com/alterlab-ieu/alterlab-academic-skills/tree/main/skills/core) (Core workflows), [`scripts`](https://github.com/alterlab-ieu/alterlab-academic-skills/tree/main/scripts) (Build scripts), [`skills`](https://github.com/alterlab-ieu/alterlab-academic-skills/tree/main/skills) (Skills tree), [`skills/core/shared/schemas`](https://github.com/alterlab-ieu/alterlab-academic-skills/tree/main/skills/core/shared/schemas) (Shared schemas)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_content["Skill corpus"]
  node_repo_root["Academic skills repo<br/>skill-corpus repository"]
  node_skills_tree["Skills tree<br/>skill corpus"]
  node_skill_pack["Skill pack<br/>package pattern"]
end

subgraph group_group_core["Core workflows"]
  node_core_orchestration["Core workflows<br/>orchestration layer"]
  node_deep_research["Deep research<br/>research workflow"]
  node_paper_writer["Paper writer<br/>writing workflow"]
  node_paper_reviewer["Paper reviewer<br/>review workflow"]
  node_research_pipeline["Research pipeline<br/>pipeline workflow"]
  node_citation_verifier["Citation verifier<br/>deterministic checker"]
  node_shared_schemas[("Shared schemas<br/>contracts")]
end

subgraph group_group_domains["Domain packs"]
  node_bioinformatics["Bioinformatics<br/>domain pack family"]
  node_cheminformatics["Cheminformatics<br/>domain pack family"]
  node_clinical_research["Clinical research<br/>domain pack family"]
  node_data_science["Data science<br/>analysis pack family"]
  node_databases["Databases<br/>connector pack family"]
  node_lab_integrations["Lab integrations<br/>connector pack family"]
  node_research_tools["Research tools<br/>research utility family"]
  node_writing_tools["Writing tools<br/>writing pack family"]
  node_visualization["Visualization<br/>viz pack family"]
  node_methodology["Methodology<br/>methods pack family"]
end

subgraph group_group_tooling["Tooling and validation"]
  node_distribution_build["Build scripts<br/>build pipeline"]
  node_ci_tests["CI and tests<br/>quality gate<br/>[workflows]"]
end

subgraph group_group_dist["Distribution"]
  node_catalog["Catalog<br/>generated inventory<br/>[skills.json]"]
  node_marketplace["Marketplace<br/>distribution metadata<br/>[marketplace.json]"]
  node_site["Catalog site<br/>published site<br/>[index.html]"]
  node_bundles["Release bundles<br/>package artifacts"]
end

subgraph group_group_governance["Governance"]
  node_governance_docs["Governance docs<br/>policy docs"]
end

node_repo_root -->|"contains"| node_skills_tree
node_skills_tree -->|"instantiates"| node_skill_pack
node_core_orchestration -->|"includes"| node_deep_research
node_core_orchestration -->|"includes"| node_paper_writer
node_core_orchestration -->|"includes"| node_paper_reviewer
node_core_orchestration -->|"includes"| node_research_pipeline
node_core_orchestration -->|"includes"| node_citation_verifier
node_deep_research -->|"uses"| node_shared_schemas
node_paper_writer -->|"uses"| node_shared_schemas
node_paper_reviewer -->|"uses"| node_shared_schemas
node_research_pipeline -->|"uses"| node_shared_schemas
node_citation_verifier -->|"uses"| node_shared_schemas
node_bioinformatics -->|"contains"| node_skill_pack
node_cheminformatics -->|"contains"| node_skill_pack
node_clinical_research -->|"contains"| node_skill_pack
node_data_science -->|"contains"| node_skill_pack
node_databases -->|"contains"| node_skill_pack
node_lab_integrations -->|"contains"| node_skill_pack
node_research_tools -->|"contains"| node_skill_pack
node_writing_tools -->|"contains"| node_skill_pack
node_visualization -->|"contains"| node_skill_pack
node_methodology -->|"contains"| node_skill_pack
node_distribution_build -->|"generates"| node_catalog
node_distribution_build -->|"generates"| node_marketplace
node_distribution_build -->|"builds"| node_bundles
node_distribution_build -->|"publishes"| node_site
node_ci_tests -->|"gates"| node_distribution_build
node_ci_tests -->|"checks"| node_skill_pack
node_governance_docs -->|"governs"| node_repo_root
node_governance_docs -->|"informs"| node_ci_tests
node_catalog -->|"derived from"| node_skills_tree
node_marketplace -->|"derived from"| node_skills_tree
node_site -->|"renders"| node_catalog
node_bundles -->|"packages"| node_skills_tree

click node_skills_tree "https://github.com/alterlab-ieu/alterlab-academic-skills/tree/main/skills"
click node_core_orchestration "https://github.com/alterlab-ieu/alterlab-academic-skills/tree/main/skills/core"
click node_deep_research "https://github.com/alterlab-ieu/alterlab-academic-skills/tree/main/skills/core/alterlab-deep-research"
click node_paper_writer "https://github.com/alterlab-ieu/alterlab-academic-skills/tree/main/skills/core/alterlab-paper-writer"
click node_paper_reviewer "https://github.com/alterlab-ieu/alterlab-academic-skills/tree/main/skills/core/alterlab-paper-reviewer"
click node_research_pipeline "https://github.com/alterlab-ieu/alterlab-academic-skills/tree/main/skills/core/alterlab-research-pipeline"
click node_citation_verifier "https://github.com/alterlab-ieu/alterlab-academic-skills/tree/main/skills/core/alterlab-citation-verifier"
click node_shared_schemas "https://github.com/alterlab-ieu/alterlab-academic-skills/tree/main/skills/core/shared/schemas"
click node_bioinformatics "https://github.com/alterlab-ieu/alterlab-academic-skills/tree/main/skills/bioinformatics"
click node_cheminformatics "https://github.com/alterlab-ieu/alterlab-academic-skills/tree/main/skills/cheminformatics"
click node_clinical_research "https://github.com/alterlab-ieu/alterlab-academic-skills/tree/main/skills/clinical-research"
click node_data_science "https://github.com/alterlab-ieu/alterlab-academic-skills/tree/main/skills/data-science"
click node_databases "https://github.com/alterlab-ieu/alterlab-academic-skills/tree/main/skills/databases"
click node_lab_integrations "https://github.com/alterlab-ieu/alterlab-academic-skills/tree/main/skills/lab-integrations"
click node_research_tools "https://github.com/alterlab-ieu/alterlab-academic-skills/tree/main/skills/research-tools"
click node_writing_tools "https://github.com/alterlab-ieu/alterlab-academic-skills/tree/main/skills/writing-tools"
click node_visualization "https://github.com/alterlab-ieu/alterlab-academic-skills/tree/main/skills/visualization"
click node_methodology "https://github.com/alterlab-ieu/alterlab-academic-skills/tree/main/skills/methodology"
click node_distribution_build "https://github.com/alterlab-ieu/alterlab-academic-skills/tree/main/scripts"
click node_catalog "https://github.com/alterlab-ieu/alterlab-academic-skills/blob/main/skills.json"
click node_marketplace "https://github.com/alterlab-ieu/alterlab-academic-skills/blob/main/.claude-plugin/marketplace.json"
click node_site "https://github.com/alterlab-ieu/alterlab-academic-skills/blob/main/docs/site/index.html"
click node_ci_tests "https://github.com/alterlab-ieu/alterlab-academic-skills/blob/main/.github/workflows"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_repo_root,node_skills_tree,node_skill_pack toneBlue
class node_core_orchestration,node_deep_research,node_paper_writer,node_paper_reviewer,node_research_pipeline,node_citation_verifier,node_shared_schemas toneAmber
class node_bioinformatics,node_cheminformatics,node_clinical_research,node_data_science,node_databases,node_lab_integrations,node_research_tools,node_writing_tools,node_visualization,node_methodology toneMint
class node_distribution_build,node_ci_tests toneRose
class node_catalog,node_marketplace,node_site,node_bundles toneIndigo
class node_governance_docs toneTeal
```

## Components

### Skill corpus

Authoritative skill packages organized by domain under skills/.

- **Academic skills repo**: skill-corpus repository · A catalog and tooling repository for Claude skill packs.
- [Skills tree](https://github.com/alterlab-ieu/alterlab-academic-skills/tree/main/skills): skill corpus · The source-of-truth package tree under skills/. · `skills`
- **Skill pack**: package pattern · A bounded skill directory centered on SKILL.md plus local references, assets, scripts, and evals.

### Core workflows

Cross-cutting orchestration, writing, research, and verification skills.

- [Core workflows](https://github.com/alterlab-ieu/alterlab-academic-skills/tree/main/skills/core): orchestration layer · Cross-cutting academic workflow skills and shared roles. · `skills/core`
- [Deep research](https://github.com/alterlab-ieu/alterlab-academic-skills/tree/main/skills/core/alterlab-deep-research): research workflow · Multi-agent literature and synthesis workflow. · `skills/core/alterlab-deep-research`
- [Paper writer](https://github.com/alterlab-ieu/alterlab-academic-skills/tree/main/skills/core/alterlab-paper-writer): writing workflow · Structured academic drafting and revision workflow. · `skills/core/alterlab-paper-writer`
- [Paper reviewer](https://github.com/alterlab-ieu/alterlab-academic-skills/tree/main/skills/core/alterlab-paper-reviewer): review workflow · Peer-review and editorial assessment workflow. · `skills/core/alterlab-paper-reviewer`
- [Research pipeline](https://github.com/alterlab-ieu/alterlab-academic-skills/tree/main/skills/core/alterlab-research-pipeline): pipeline workflow · Stateful end-to-end research execution and recovery workflow. · `skills/core/alterlab-research-pipeline`
- [Citation verifier](https://github.com/alterlab-ieu/alterlab-academic-skills/tree/main/skills/core/alterlab-citation-verifier): deterministic checker · Validates claimed references against scholarly services. · `skills/core/alterlab-citation-verifier`
- [Shared schemas](https://github.com/alterlab-ieu/alterlab-academic-skills/tree/main/skills/core/shared/schemas): contracts · Reusable handoff and JSON schemas for bibliographies, reviews, briefs, integrity reports, and revisions. · `skills/core/shared/schemas`

### Domain packs

Specialized connector and analysis skill families for different subject areas.

- [Bioinformatics](https://github.com/alterlab-ieu/alterlab-academic-skills/tree/main/skills/bioinformatics): domain pack family · Skills for genomics, proteomics, single-cell, imaging, and related bio workflows. · `skills/bioinformatics`
- [Cheminformatics](https://github.com/alterlab-ieu/alterlab-academic-skills/tree/main/skills/cheminformatics): domain pack family · Skills for molecular representation, modeling, docking, and compound analysis. · `skills/cheminformatics`
- [Clinical research](https://github.com/alterlab-ieu/alterlab-academic-skills/tree/main/skills/clinical-research): domain pack family · Skills for clinical reporting, decision support, and regulated document workflows. · `skills/clinical-research`
- [Data science](https://github.com/alterlab-ieu/alterlab-academic-skills/tree/main/skills/data-science): analysis pack family · Skills for statistical analysis, ML, simulation, and data engineering tools. · `skills/data-science`
- [Databases](https://github.com/alterlab-ieu/alterlab-academic-skills/tree/main/skills/databases): connector pack family · Skills that bridge Claude to external scientific, biomedical, and business databases. · `skills/databases`
- [Lab integrations](https://github.com/alterlab-ieu/alterlab-academic-skills/tree/main/skills/lab-integrations): connector pack family · Skills for laboratory platforms, automation systems, and experiment services. · `skills/lab-integrations`
- [Research tools](https://github.com/alterlab-ieu/alterlab-academic-skills/tree/main/skills/research-tools): research utility family · Search, evidence gathering, reference management, and meta-research tools. · `skills/research-tools`
- [Writing tools](https://github.com/alterlab-ieu/alterlab-academic-skills/tree/main/skills/writing-tools): writing pack family · Skills for scholarly writing, grants, slides, posters, citations, and templates. · `skills/writing-tools`
- [Visualization](https://github.com/alterlab-ieu/alterlab-academic-skills/tree/main/skills/visualization): viz pack family · Skills for figures, diagrams, infographics, and scientific plotting. · `skills/visualization`
- [Methodology](https://github.com/alterlab-ieu/alterlab-academic-skills/tree/main/skills/methodology): methods pack family · Skills for preregistration, transparency, and test selection safeguards. · `skills/methodology`

### Tooling and validation

Schemas, scripts, tests, and CI that normalize, validate, and build the corpus.

- [Build scripts](https://github.com/alterlab-ieu/alterlab-academic-skills/tree/main/scripts): build pipeline · Normalization, catalog generation, marketplace generation, eval running, and bundle building. · `scripts`
- [CI and tests](https://github.com/alterlab-ieu/alterlab-academic-skills/blob/main/.github/workflows): quality gate · Repository invariants enforced by tests and GitHub Actions workflows. · `.github/workflows`

### Distribution

Generated catalog and delivery surfaces for Claude Code, Claude.ai, and manual installs.

- [Catalog](https://github.com/alterlab-ieu/alterlab-academic-skills/blob/main/skills.json): generated inventory · Machine-readable corpus inventory derived from skill metadata. · `skills.json`
- [Marketplace](https://github.com/alterlab-ieu/alterlab-academic-skills/blob/main/.claude-plugin/marketplace.json): distribution metadata · Claude Code plugin marketplace manifest. · `.claude-plugin/marketplace.json`
- [Catalog site](https://github.com/alterlab-ieu/alterlab-academic-skills/blob/main/docs/site/index.html): published site · Browsable generated catalog published via GitHub Pages. · `docs/site/index.html`
- **Release bundles**: package artifacts · Per-domain bundles and zips for Claude.ai and install-time distribution.

### Governance

Docs and policy files defining provenance, contribution, and release trust boundaries.

- **Governance docs**: policy docs · Provenance, contribution, security, citation, and design documents.

## Connections

- Academic skills repo → Skills tree: contains · The repository centers on the skills corpus.
- Skills tree → Skill pack: instantiates · Each skill directory follows the same package anatomy.
- Core workflows → Deep research: includes · Core orchestration is built from major workflow skills.
- Core workflows → Paper writer: includes · Core orchestration is built from major workflow skills.
- Core workflows → Paper reviewer: includes · Core orchestration is built from major workflow skills.
- Core workflows → Research pipeline: includes · Core orchestration is built from major workflow skills.
- Core workflows → Citation verifier: includes · Integrity checking is a first-class core capability.
- Deep research → Shared schemas: uses · Research workflows exchange structured handoff artifacts.
- Paper writer → Shared schemas: uses · Writing workflows consume shared drafts and revision schemas.
- Paper reviewer → Shared schemas: uses · Review workflows use standardized review and decision schemas.
- Research pipeline → Shared schemas: uses · Pipeline state and integrity artifacts are schema-driven.
- Citation verifier → Shared schemas: uses · Citation checks emit structured integrity outputs.
- Bioinformatics → Skill pack: contains · Domain families are composed of many individual skill packs.
- Cheminformatics → Skill pack: contains · Domain families are composed of many individual skill packs.
- Clinical research → Skill pack: contains · Domain families are composed of many individual skill packs.
- Data science → Skill pack: contains · Domain families are composed of many individual skill packs.
- Databases → Skill pack: contains · Domain families are composed of many individual skill packs.
- Lab integrations → Skill pack: contains · Domain families are composed of many individual skill packs.
- Research tools → Skill pack: contains · Domain families are composed of many individual skill packs.
- Writing tools → Skill pack: contains · Domain families are composed of many individual skill packs.
- Visualization → Skill pack: contains · Domain families are composed of many individual skill packs.
- Methodology → Skill pack: contains · Domain families are composed of many individual skill packs.
- Build scripts → Catalog: generates · Catalog generation produces the machine-readable inventory.
- Build scripts → Marketplace: generates · Build scripts synthesize plugin marketplace metadata.
- Build scripts → Release bundles: builds · Scripts assemble release bundles for downstream installs.
- Build scripts → Catalog site: publishes · Derived site artifacts are produced from the same corpus.
- CI and tests → Build scripts: gates · CI validates specs, skills, evals, links, and packaging.
- CI and tests → Skill pack: checks · Tests enforce structural and content invariants across skills.
- Governance docs → Academic skills repo: governs · Repository policy and provenance documents define the trust boundary.
- Governance docs → CI and tests: informs · Governance expectations are enforced through CI and tests.
- Catalog → Skills tree: derived from · The catalog is generated from the skill metadata corpus.
- Marketplace → Skills tree: derived from · Marketplace metadata is generated from the same source corpus.
- Catalog site → Catalog: renders · The browsable site is a presentation layer over the catalog.
- Release bundles → Skills tree: packages · Release artifacts repurpose the authored skill corpus for other runtimes.