How imbad0202/academic-research-skills works
1. What this repo is
This is not an application server; it is a Claude Code skill suite. The core product is a set of markdown-defined agents, modes, commands, and validation rules that extend Claude Code for academic research, paper writing, peer review, and end-to-end pipeline orchestration.
2. Top-level product boundaries
The repository is organized into four major skill subsystems:
- deep-research for research discovery and evidence gathering
- academic-paper for drafting and revising papers
- academic-paper-reviewer for multi-perspective review and calibration
- academic-pipeline for orchestrating the full research-to-publication workflow
Each subsystem has its own SKILL.md, agent prompts, examples, and reference protocols, which makes them independently deployable as Claude Code skills.
3. Distribution / packaging layer
The repo also contains the packaging surface for Claude Code:
- .claude-plugin/ for marketplace metadata and plugin manifest
- commands/ for /ars-* slash commands that map to modes
- agents/ for plugin-exposed agent entrypoints
- hooks/ for session bootstrap behavior
This layer is what turns the markdown content into an installable plugin rather than just a cloned repository.
4. Shared contract and policy layer
shared/ is the central governance boundary. It holds reusable schemas, rubrics, protocols, templates, and policy artifacts used across all four skill suites. This includes:
- JSON Schema contracts for passports, audits, reviewer outputs, benchmark reports, sprint contracts
- shared rubrics and reasoning frameworks
- policy data and disclosure/provenance guidance
- handoff schemas that define what downstream agents are allowed to consume
Architecturally, this is the repo’s “type system” and compliance layer.
5. Primary execution flow
User input enters through Claude Code and is routed by skill/mode selection into one of the skill suites. From there, agent prompts drive a staged workflow:
- intake / planning / research
- synthesis or drafting
- review or verification
- formatting / disclosure / finalization
- optional post-run audit or process summary
The important diagram boundary is that the LLM conversation is orchestrated by stage contracts, not free-form prompting.
6. Academic pipeline as the highest-level orchestrator
academic-pipeline is the repo’s main system-of-systems controller. It models a multi-stage workflow with explicit checkpoints, including mandatory integrity gates and a final process summary stage. It consumes outputs from the other skill suites and converts them into a staged research-to-paper lifecycle with tracked state, provenance, and user confirmation points.
7. Evidence and provenance flow
The repo is heavily centered on Material Passport and provenance artifacts. These travel through the pipeline as structured inputs/outputs and carry:
- literature corpus entries
- timeline and citation provenance
- claim audit results
- reset ledgers and compliance histories
- integrity / temporal / contamination signals
This is the main data backbone for cross-session continuity and auditability.
8. Research and citation verification subsystem
deep-research and parts of academic-pipeline integrate external evidence sources and verification tooling. The scripts reference:
- Semantic Scholar
- OpenAlex
- Crossref
These are used for reference validation, deduplication, source matching, contamination detection, and claim-level checks. The architecture explicitly separates advisory evidence from hard-blocking output gates.
9. Writing and publication subsystem
academic-paper is the document-generation side: it handles drafting, abstracting, literature reviews, revision coaching, citation formatting, LaTeX/PDF hardening, and disclosure generation. Its outputs are manuscript artifacts, formatting conversions, and revision-tracking templates, rather than research evidence itself.
10. Review and evaluation subsystem
academic-paper-reviewer is a distinct read-only subsystem for evaluation. It produces peer-review reports, editorial decisions, and calibration outputs using rubric-based scoring and multiple reviewer roles. The key boundary is that this subsystem does not modify the manuscript; it assesses it and generates review artifacts.
11. Python tooling and deterministic checks
scripts/ contains the operational layer: schema linters, integrity auditors, migration utilities, external API clients, and end-to-end checks. These scripts enforce the contracts defined in shared/ and are wired into CI. In architecture terms, they are the repo’s deterministic guardrails around otherwise probabilistic LLM behavior.
12. Tests, fixtures, and release governance
tests/ and scripts/fixtures/ provide the validation harness for routing, phase boundaries, audit logic, temporal verification, and pattern protection. GitHub Actions workflows in .github/workflows/ continuously enforce spec consistency, pytest coverage, freshness, and release-related checks. This is a repo where documentation, schemas, tests, and prompts are all first-class architectural elements.
13. External/runtime dependencies that matter
The repo depends on Claude Code as the runtime host, with optional document tooling like Pandoc and tectonic for DOCX/PDF output. For data verification it reaches out to bibliographic and citation services, and for plugin distribution it uses GitHub-hosted marketplace metadata. These dependencies matter because they shape what is generated locally versus what is verified externally.
14. How to draw the diagram
A correct architecture diagram should show:
- Claude Code as the host runtime at the top
- four skill subsystems underneath
- shared/ as the common contract/policy layer across all of them
- scripts/ and CI as the enforcement/verification layer
- external citation and metadata APIs as the evidence sources
- artifacts flowing through passports, audits, reviews, and final manuscripts
The most important structural idea is that this repo is a contract-driven LLM workflow platform, not a monolithic application.
Main entry points: academic-pipeline/SKILL.md Paper pipeline · deep-research/SKILL.md Deep research · README.md Shared contracts · academic-paper/SKILL.md Academic paper
Components 20
Claude Code host
Plugin packaging and session entrypoints that load the skill suite into Claude Code.
- Claude Code · Conversation runtime that loads the plugin and routes user requests into skills.
- Plugin pack · Marketplace metadata and plugin manifest that package the repository as an installable skill suite.
.claude-plugin/plugin.json - Slash commands · /ars-* command surface that maps user intent into modes and workflows.
commands/ars-full.md - Agent entrypoints · Top-level agents exposed to Claude Code for routing, synthesis, and reporting.
agents/research_architect_agent.md - Session hooks · Hook configuration that initializes session behavior and orchestration defaults.
hooks/hooks.json
Skill suites
Independent markdown-defined subsystems for research, writing, review, and orchestration.
- Deep research · Discovery, evidence gathering, source verification, and synthesis for research tasks.
deep-research/SKILL.md - Academic paper · Drafting, revision, citation handling, structure, and publication-oriented manuscript generation.
academic-paper/SKILL.md - Paper reviewer · Read-only peer review and editorial evaluation with multi-perspective rubrics.
academic-paper-reviewer/SKILL.md - Paper pipeline · System-of-systems workflow that stages research-to-publication with checkpoints and summaries.
academic-pipeline/SKILL.md
Shared contracts
Reusable schemas, rubrics, policies, and handoff protocols that constrain all skills.
- Shared contracts · Central schema and policy boundary for passports, audits, reviewers, disclosures, and handoffs.
shared/contracts/README.md - Rubrics & policy · Rubrics, compliance checkpoints, cross-model verification, and disclosure policies used across skills.
shared/compliance_checkpoint_protocol.md - Passport flow · Material passport, citation provenance, timeline, reset ledger, and audit result artifacts that carry state across stages.
shared/contracts/passport/literature_corpus_entry.schema.json
Checks and CI
Deterministic scripts, fixtures, tests, and workflows that validate repo contracts and workflows.
- Deterministic checks · Schema linters, auditors, migration utilities, and end-to-end validators that enforce repo contracts.
scripts/check_pipeline_integrity.py - Corpus adapters · Import adapters for Zotero, Obsidian, and folder scans that normalize literature corpus inputs.
scripts/adapters/zotero.py - CI workflows · GitHub Actions gates for spec consistency, freshness, pytest, and release-related checks.
.github/workflows/spec-consistency.yml - Fixtures · Golden inputs and expected outputs that exercise routing, integrity, temporal, and pattern-protection behaviors.
tests/fixtures/issue_133_routing/README.md
External sources
Runtime and evidence services used for citation lookup, document rendering, and marketplace distribution.
- Semantic Scholar · Bibliographic source used for source verification and reference matching.
- OpenAlex · External metadata source used for literature discovery and deduplication.
- Crossref · Reference metadata and citation validation source used by research tooling.
- Pandoc/tectonic · Optional document-conversion and PDF-hardening tools for manuscript output.
Connections 29
- Claude Code → Plugin pack: loads · Claude Code installs the repository as a plugin package.
- Plugin pack → Slash commands: exposes · Marketplace packaging surfaces slash commands to the host.
- Plugin pack → Agent entrypoints: exposes · Plugin metadata exposes entrypoint agents for orchestration.
- Plugin pack → Session hooks: boots · Plugin bootstrap config wires session initialization behavior.
- Claude Code → Deep research: routes to · User requests are routed into the research skill when discovery is needed.
- Claude Code → Academic paper: routes to · User requests are routed into the writing skill for drafting and revision.
- Claude Code → Paper reviewer: routes to · User requests are routed into the review skill for evaluation only.
- Claude Code → Paper pipeline: routes to · End-to-end workflows are routed into the pipeline orchestrator skill.
- Deep research → Shared contracts: consumes · Research outputs are constrained by shared schemas and handoff contracts.
- Academic paper → Shared contracts: consumes · Manuscript artifacts use shared writer and disclosure schemas.
- Paper reviewer → Shared contracts: consumes · Review artifacts follow shared reviewer and audit schemas.
- Paper pipeline → Shared contracts: consumes · Pipeline state and passports are governed by shared contracts.
- Shared contracts → Passport flow: defines · Passport-related schemas define the repository’s provenance backbone.
- Rubrics & policy → Paper reviewer: guides · Rubrics shape reviewer scoring, calibration, and editorial decisions.
- Rubrics & policy → Academic paper: guides · Writing protocols guide drafting, disclosure, and formatting choices.
- Rubrics & policy → Paper pipeline: guides · Integrity gates and stage protocols govern pipeline checkpoints.
- Paper pipeline → Passport flow: moves · Pipeline stages carry passports, audits, timelines, and reset ledgers.
- Deep research → Semantic Scholar: queries · Research tooling consults bibliographic search and verification APIs.
- Deep research → OpenAlex: queries · Research tooling consults metadata sources for discovery and deduplication.
- Deep research → Crossref: queries · Research tooling validates and enriches citation metadata.
- Academic paper → Pandoc/tectonic: renders with · Paper outputs can be hardened into DOCX/PDF via document tooling.
- Deterministic checks → Shared contracts: validates · Scripts enforce schema and contract consistency across the repository.
- Deterministic checks → Passport flow: audits · Integrity scripts verify passports, claim audits, and temporal constraints.
- Corpus adapters → Passport flow: ingests into · Corpus adapters normalize external literature into passport-compatible structures.
- CI workflows → Deterministic checks: runs · GitHub Actions execute the repo’s validation scripts.
- Fixtures → Deterministic checks: exercise · Golden fixtures drive checks for routing, integrity, and phase boundaries.
- Paper pipeline → Deep research: consumes outputs · The orchestrator consumes research artifacts and evidence packets.
- Paper pipeline → Academic paper: consumes outputs · The orchestrator consumes draft and revision artifacts.
- Paper pipeline → Paper reviewer: consumes outputs · The orchestrator consumes review and calibration artifacts.