alterlab-ieu/alterlab-academic-skills

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.