research-lab-skills

简体中文版 | 繁體中文版 | 日本語版

Research shouldn't reset every AI session.

What this is

Every new AI chat starts from zero — it doesn't know what you tried last week, what failed, why you changed direction, or what's still open. research-lab-skills is stateful research workflow infrastructure that fixes that: it keeps your experiments, failures, decisions, and evidence connected across sessions, then turns that accumulated history into progress/lab-meeting slides, structured research state, and context the formal literature/writing/review workflow can actually pick up from — instead of starting over from a blank prompt.

Built as Agent Skills. Claude Code is currently the verified reference client — see Platform status.

It combines two things: research infrastructure developed in this repository, and an upstream academic research pipeline — Academic Research Skills (ARS) by Cheng-I Wu (Imbad0202/academic-research-skills, CC BY-NC 4.0). See Upstream attribution below and THIRD_PARTY_NOTICES.md for the exact, path-by-path breakdown.

Why this is different

Persistent research memory

Experiments don't disappear into chat history. Every run gets a structured record — Goal, Setup, Results, Failures, Analysis — with explicit follows: links to prior entries and amended: records for post-hoc corrections, plus references to the slide decks generated from it. This is project-level research memory, not conversation memory: it lives in docs/research_log/ as files, not in a context window that gets cleared.

Stateful research model

Above the journal sits actual state, not just a folder of Markdown: research-project-init scopes a project into a charter (problem statement, scope, constraints, milestones, success/stop conditions) and registers it in agent-state, which tracks Projects, Research Questions, deduplicated Sources, and stance-tagged Evidence records with provenance back to where each claim came from. resource-resolver gives every skill a consistent way to find where a project's artifacts live. None of this resets between sessions.

Research history → editable progress slides

This isn't a "paste your paper, get slides" generator. /report-slides reads weeks of journal history and works out what changed, what failed, current metrics, decisions made, and what's next — then renders that as a deck: SVG source per slide, native/editable PPTX objects (tables and charts stay editable in PowerPoint, not flattened images), and a visual review/validation pass before you trust the output.

Daily research → academic handoff

When it's time to write, the formal pipeline doesn't start from a blank prompt — it starts from the research state and history already on record. That handoff point is where this repository's original work ends and the upstream Academic Research Skills pipeline (deep research, paper writing, peer review, full orchestration — by Cheng-I Wu) takes over.

How the pieces connect

flowchart TD
    A["Project initialization<br/>(research-project-init)"] --> B["Research questions / state<br/>(agent-state)"]
    B --> C["Experiments"]
    C --> D["Research log<br/>persistent memory"]
    D --> E["Progress slides<br/>(report-slides)"]
    D --> F["Evidence / provenance<br/>accumulated context"]
    E --> G["Academic workflow<br/>(upstream ARS)"]
    F --> G
    G --> H["Literature → Writing → Review → Revision"]

The emphasis is continuity, not agent counts: state accumulated in one phase is what the next phase actually reads from — nothing here is a fresh prompt.

Phase 1 — Daily experiment work (/mode exp)

/mode exp                       # start an experiment session
/research-log add               # log today's work (quick: 3 questions; full: 9 sections)
/report-slides                  # turn this week's journal into a progress presentation
/mode end                       # draft the next entry from today's git diff

The journal's follows: field links experiments into a traceable timeline. amended: records post-hoc corrections. slide_decks: updates automatically when slides are generated. These entries are the raw material for your methodology section when you eventually write the paper — capturing not just what worked, but why you tried it and what failed first.

Phase 2 — Literature exploration (/mode explore)

/mode explore
/ars-lit-review "your topic"    # literature review with PRISMA support (upstream ARS)
/ars-socratic                   # Socratic dialogue to sharpen your research question
/mode end                       # extract RQ + key findings into the log

Phase 3 — Writing and publication (/mode publish)

/mode publish
/ars-plan                       # Socratic-guided chapter planning (upstream ARS)
/ars-full                       # paper writing + citation verification (upstream ARS)
/ars-review                     # multi-perspective peer review (upstream ARS)
/ars-re-review                  # post-revision acceptance check (upstream ARS)
/ars-pipeline                   # full orchestrated pipeline with integrity gates (upstream ARS)

How the journal connects to the paper

→ See examples/ for a complete worked example: three journal entries showing the messy week-by-week process (failures, amended: corrections, unresolved problems), a 7-slide lab-meeting progress deck generated from those logs, and the JSON data file that drove the charts. The SVG slides also ship as a deck.pptx — every element editable in PowerPoint or Keynote.

Upstream attribution

Upstream ARS (Imbad0202/academic-research-skills by Cheng-I Wu, CC BY-NC 4.0) provides:

• Deep research (deep-research) — literature search, Socratic question-sharpening, systematic review
• Academic paper writing (academic-paper) — drafting, citation verification, revision coaching
• Peer review (academic-paper-reviewer) — multi-perspective review simulation
• Pipeline orchestration (academic-pipeline) — chaining the above with integrity gates

This repository's own contribution — independently developed here, not part of the upstream project:

• research-log, report-slides, research-mode — the daily research journal, progress-slide generation, and session-mode routing
• research-project-init, agent-state, resource-resolver — project scoping and the persistent state layer that keeps Projects, Questions, Sources, and Evidence connected across sessions
• The integration and packaging layer that installs both toolsets together and lets research state flow from the daily layer into the upstream pipeline

The upstream ARS agent pipeline itself was not developed in this repository. See THIRD_PARTY_NOTICES.md for the exact, path-by-path split, and NOTICE.md / LICENSE for the full licensing terms.

Installation

curl / PowerShell (recommended)

macOS / Linux / Git Bash / WSL:

# All skills (global)
curl -fsSL https://raw.githubusercontent.com/zi-yue-1129/research-lab-skills/main/install.sh | bash

# Project-local
curl -fsSL https://raw.githubusercontent.com/zi-yue-1129/research-lab-skills/main/install.sh | bash -s -- --local

# ARS skills only
curl -fsSL https://raw.githubusercontent.com/zi-yue-1129/research-lab-skills/main/install.sh | bash -s -- --ars-only

# Lab skills only
curl -fsSL https://raw.githubusercontent.com/zi-yue-1129/research-lab-skills/main/install.sh | bash -s -- --lab-only

# Uninstall
curl -fsSL https://raw.githubusercontent.com/zi-yue-1129/research-lab-skills/main/install.sh | bash -s -- uninstall

Windows (PowerShell) — native, no Git Bash or WSL required:

# All skills (global)
irm https://raw.githubusercontent.com/zi-yue-1129/research-lab-skills/main/install.ps1 | iex

# Flags require the script body, not a piped invocation — wrap it in a scriptblock:
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/zi-yue-1129/research-lab-skills/main/install.ps1))) -Local
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/zi-yue-1129/research-lab-skills/main/install.ps1))) -ArsOnly
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/zi-yue-1129/research-lab-skills/main/install.ps1))) -LabOnly
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/zi-yue-1129/research-lab-skills/main/install.ps1))) -Uninstall

Windows (cmd.exe):

powershell -Command "irm https://raw.githubusercontent.com/zi-yue-1129/research-lab-skills/main/install.ps1 | iex"

If antivirus/EDR blocks the command above: some security software flags the irm | iex pattern (download-and-execute) regardless of content — see git clone below, which avoids it entirely.

git clone

Works identically on macOS, Linux, and Windows, and avoids the curl | bash / irm | iex download-and-execute pattern that some antivirus/EDR software flags outright regardless of content:

git clone --depth 1 https://github.com/zi-yue-1129/research-lab-skills.git
cd research-lab-skills

macOS / Linux / Git Bash / WSL:

bash install.sh                # all skills (global)
bash install.sh --local        # project-local
bash install.sh --ars-only     # ARS skills only
bash install.sh --lab-only     # Lab skills only
bash install.sh uninstall      # uninstall

Windows (PowerShell):

powershell -ExecutionPolicy Bypass -File install.ps1                # all skills (global)
powershell -ExecutionPolicy Bypass -File install.ps1 -Local          # project-local
powershell -ExecutionPolicy Bypass -File install.ps1 -ArsOnly        # ARS skills only
powershell -ExecutionPolicy Bypass -File install.ps1 -LabOnly        # Lab skills only
powershell -ExecutionPolicy Bypass -File install.ps1 -Uninstall      # uninstall

Restart Claude Code after install. Lab skills: /research-log, /report-slides, /mode Academic skills: /ars-plan, /ars-full, /ars-lit-review, /ars-review, and more.

Note: an npm package (crs CLI) previously shipped alongside this repo. It is not currently maintained as a supported install path — use curl/ PowerShell/git clone above instead. The CLI source is still in the repo at bin/crs.js for reference.

Skills at a glance

Lab Skills

/research-log — Experiment Journal

Manages a structured journal in docs/research_log/ (one .md file per experiment).

Each entry is a Markdown file with YAML frontmatter tracking follows: links between experiments and slide_decks: updated automatically when slides are generated.

Agents proactively consult relevant history before starting new experiments, diagnosing anomalies, changing parameters, or launching costly reruns, even when /mode is not active.

/report-slides — Presentation Generator

Reads journal entries, proposes a slide outline for confirmation, then generates slides via three rendering paths:

• [A] Python script — data-driven slides: bar charts, tables, metric cards, timelines
• [B] Mermaid — diagram slides: flowcharts, architecture diagrams, state machines
• [C] Claude SVG — free-form slides: conceptual layouts, text-heavy content

Output: docs/slides/reports/YYYY-MM-DD_<deck-name>/

• slide01_title.svg, slide02_bar_chart.svg, … (editable SVG source files)
• deck.pptx — 16:9 PPTX with native SVG embedding. Every title, number, colour, and layout element is directly editable in PowerPoint or Keynote — no roundtripping back to source code.
• slide_data.json (Path A source, use --slide N to re-render one slide)

First-time project setup:

bash "$(find ~/.claude -path "*/report-slides/scripts/setup.sh" | head -1)"

Dependencies:

pip install python-pptx
npm install -g @mermaid-js/mermaid-cli   # optional, Mermaid diagrams only

Slide styles: default, minimal, dark, paper

bash "$(find ~/.claude -path "*/report-slides/scripts/set-style.sh" | head -1)" paper

/mode — Session Mode Routing

Declares active research mode to adjust which skills are prioritized and how sessions end:

End a session with /mode end to get a pre-filled journal entry draft.

Academic Research Skills (upstream ARS)

AI is your copilot, not the pilot. This tool won't write your paper for you. It handles the grunt work — hunting down references, formatting citations, verifying data, checking logical consistency — so you can focus on the parts that actually require your brain.

👉 docs/ARCHITECTURE.md — full pipeline view: flow diagram, stage-by-stage matrix, quality gates, and mode list.

👉 docs/SETUP.md — full setup guide: API keys, optional Pandoc/tectonic for DOCX/PDF, cross-model verification.

👉 docs/PERFORMANCE.md — per-mode token budgets, full-pipeline cost estimate (~$4–6 for a 15k-word paper).

Features at a glance

• Deep Research (/ars-full, /ars-lit-review, /ars-systematic-review) — 13-agent research team. Socratic guided mode, PRISMA systematic review, four-index citation triangulation (Semantic Scholar + OpenAlex + Crossref + arXiv), cross-model DA critique.
• Academic Paper (/ars-plan, /ars-outline, /ars-abstract) — 12-agent paper writing. Style Calibration, Writing Quality Check, three-layer citation anchors, LaTeX hardening, VLM figure verification, revision coaching.
• Academic Paper Reviewer (/ars-review, /ars-re-review) — 7-agent peer review. EIC + 3 dynamic reviewers + Devil's Advocate, concession threshold protocol, opt-in calibration mode, R&R traceability matrix.
• Academic Pipeline (/ars-pipeline) — 10-stage end-to-end orchestrator. Integrity gates at Stage 2.5 + 4.5, Material Passport, citation existence gate, Collaboration Depth Observer, score trajectory tracking.

Full pipeline

research-project-init (optional)
  → deep-research (socratic/full)
    → academic-paper (plan/full)
      → integrity check (Stage 2.5)
        → academic-paper-reviewer (full/guided)
          → academic-paper (revision)
            → academic-paper-reviewer (re-review, max 2 loops)
              → final integrity check (Stage 4.5)
                → academic-paper (format-convert → final output)

See examples/showcase/ for artifacts from a complete 10-stage pipeline run (peer review reports, integrity checks, final papers).

Examples

The examples/ directory contains a complete worked scenario — an NLP researcher working on cross-lingual automated essay scoring across three weeks of experiments.

Research journal (examples/research-log/) — three entries showing the full arc: a quick baseline log on day one, a full entry mid-project with failures and a post-hoc amended: correction, and a final-week entry with two amendments and open questions. The follows: chain links them into a traceable timeline.

Progress slides (examples/report-slides/) — a 7-slide weekly lab-meeting presentation generated from those journal entries. Slides cover: title, problem/approach, timeline (with amended badges), grouped bar chart, model comparison table (with DIF fairness markers), metric cards, and conclusion + next steps. All slides are SVG source files convertible to an editable deck.pptx — see examples/report-slides/README.md for the generation command.

File Structure

docs/research_log/
  INDEX.md                              ← auto-generated (do not edit)
  2026-05-15_backbone_v3.md

docs/slides/
  _style.md                             ← project default style (optional)
  reports/
    2026-05-19_weekly/
      slide01_title.svg
      deck.pptx
      slide_data.json

scripts/
  generate_slides.py                    ← copied from skill on first use
  to_pptx.py

Platform status

• Claude Code — verified reference client. Every skill, command, and workflow above has been built and run against it.
• Other Agent Skills clients (Codex, Cursor, Windsurf, Copilot, etc.) — compatibility not yet verified. The skills are built in the standard Agent Skills SKILL.md format and are designed to remain client-portable, but we don't claim behavioral parity with any other client without test evidence. docs/SETUP.md documents the one confirmed gap (Codex's imported-skills mechanism does not reproduce /report-slides' diagram generation — Issue #8).

Sources

• Lab skills and integration infrastructure (research-log, report-slides, research-mode, resource-resolver, agent-state, research-project-init, packaging/install layer) — original work by ZI-YUE, CHAO, this repository, CC BY-NC 4.0
• Academic Research Skills (deep-research, academic-paper, academic-paper-reviewer, academic-pipeline, and their supporting agents/, shared/, commands/, hooks/) — upstream Imbad0202/academic-research-skills by Cheng-I Wu, CC BY-NC 4.0

See LICENSE, NOTICE.md, and THIRD_PARTY_NOTICES.md (path-by-path detail, including directories split between the two) for full licensing and attribution detail.