claude-code-academic-workflow

claude-code-academic-workflow

Skill by ara.so — Claude Code Skills collection.

What This Is

A production-ready template for AI-assisted academic work using Claude Code. Provides specialized agents for reviewing slides, papers, and data analysis; quality scoring with 80/90/95 thresholds; adversarial QA loops; and reproducibility verification. Originally extracted from a PhD course, now community-maintained with 1200+ GitHub stars.

Core capabilities:

• Contractor mode — describe what you want, Claude plans and orchestrates specialized agents
• 18+ focused agents — proofreader, slide-auditor, pedagogy-reviewer, r-reviewer, domain-referee, methods-referee, editor
• Quality gates — scores 0-100, auto-blocks commits below 80
• Adversarial QA — critic + fixer loop until approval or 5 rounds
• Verification layers — claim verification, reproducibility audit, AI-voice detection, multi-referee variance sampling

Supported artifacts:

• LaTeX/Beamer slides (XeLaTeX)
• Research manuscripts (LaTeX)
• Quarto documents (HTML/PDF)
• R analysis scripts
• Data replication packages

Installation

1. Fork and Clone

# Fork on GitHub first, then:
git clone https://github.com/YOUR_USERNAME/claude-code-my-workflow.git my-project
cd my-project

2. Validate Prerequisites

./scripts/validate-setup.sh

Minimum requirements:

• Claude Code (CLI or VS Code extension)
• git
• Python 3 (pre-installed macOS/Linux; validation scripts only)

For LaTeX/Beamer demos:

• XeLaTeX (TeX Live 2020+)

For Quarto demos:

• Quarto 1.3+

For R analysis:

• R 4.0+
• Required packages: tidyverse, fixest, modelsummary

Recommended:

• GitHub CLI (gh)
• VS Code with Claude Code extension

3. Initialize with Starter Prompt

Start Claude Code and paste:

I am starting to work on [PROJECT NAME] in this repo. [Describe project in 2-3 sentences.] 
I've set up the Claude Code academic workflow from pedrohcgs/claude-code-my-workflow. 
Please read the configuration files (.claude/CLAUDE.md, .claude/rules/*.md, .claude/skills/*.md) 
and adapt them for my project. Set my name to [YOUR NAME], institution to [YOUR INSTITUTION], 
and configure the project metadata. Enter plan mode and start.

Claude will:

1. Read all configuration files
2. Update project metadata in .claude/project.yaml
3. Verify setup with /validate-setup
4. Enter contractor mode for your first task

Key Commands (Skills)

Slide Creation & Review

Create lecture slides:

/create-lecture "Introduction to Panel Data"

Compile LaTeX to PDF:

/compile-latex HelloWorld

Run quality review (slide-specific agents):

/slide-excellence Slides/MyLecture.tex

Adversarial QA loop:

/qa-beamer Slides/MyLecture.tex --rounds 5

Paper Review & Verification

Multi-agent peer review:

/review-paper manuscript.tex --peer

Adversarial review:

/review-paper manuscript.tex --adversarial

Multi-referee variance sampling (v1.9.0):

/review-paper manuscript.tex --variance 10

Runs 10 referees with sampled dispositions, reports decision distribution.

Verify claims against fabrication:

/verify-claims manuscript.tex

Chain-of-Verification with forked verifier. HIGH-WARN findings block /commit.

Audit reproducibility:

/audit-reproducibility manuscript.tex

Cross-checks every numeric claim against script output. Generates passport.yaml with PASS/FAIL/STALE status per claim.

Detect AI-voice patterns:

/humanize manuscript.tex

Read-only detection of boilerplate, hedging, sycophancy. Does NOT auto-rewrite.

Quarto Workflows

Deploy Quarto document:

/deploy HelloWorld

QA Quarto document:

/qa-quarto Quarto/MyDoc.qmd

R Analysis Review

Review R script quality:

/review-r analysis/main.R

Literature review for R packages:

/lit-review "fixest two-way fixed effects"

Quality & Reproducibility

Commit with quality gates:

/commit "Add panel data lecture" --require-score 80

Blocks if quality score < 80.

Create pull request:

/pr "Manuscript ready for review" --require-score 90

Blocks if quality score < 90.

Compress long session:

/compress-session

Distills conversation to structured note before auto-compaction. Preserves decisions, next actions, marks noise.

Promote learnings to shared memory:

/promote-memory

Five-critic council reviews personal-memory.md, promotes generic patterns to MEMORY.md.

Model & Cost Management

Set effort level:

/effort high

Options: low, medium, high, xhigh, max. Opus 4.8 defaults to high.

Check usage:

/cost
/usage

Goal-driven persistence (v1.9.0):

/goal "all tests pass and manuscript score > 90"

Keeps working across turns until fast model confirms condition.

Configuration Files

Project Metadata

.claude/project.yaml:

project:
  name: "My Research Project"
  author: "Your Name"
  institution: "Your University"
  course: "ECON 5000"  # or null for papers
  
quality:
  commit_threshold: 80
  pr_threshold: 90
  excellence_threshold: 95
  
paths:
  slides: "Slides"
  quarto: "Quarto"
  data: "Data"
  analysis: "R"

Agent Configuration

.claude/agents/ directory contains 18+ agent specs:

Example — R Reviewer (.claude/agents/r-reviewer.md):

---
agent: r-reviewer
focus: R code quality and best practices
model: sonnet-4.6
effort: medium
---

# R Code Reviewer

## Responsibilities
- tidyverse idiom compliance
- fixest usage patterns
- modelsummary output quality
- data.table efficiency
- statistical correctness

## Review Checklist
- [ ] No base R subsetting in tidyverse pipelines
- [ ] Fixed effects specified correctly
- [ ] Standard errors clustered appropriately
- [ ] Tables formatted for publication
- [ ] Code reproducible from raw data

Skills

Skills are in .claude/skills/. Frontmatter specifies triggers, effort, context, hooks:

Example — /create-lecture:

---
skill: create-lecture
description: Create Beamer lecture slides with quality review
triggers:
  - create lecture on
  - make slides about
  - build presentation for
effort: high
context: fork
hooks:
  - PreEdit
  - PostEdit
  - PreCompact
---

# Create Lecture

(implementation follows)

Rules

.claude/rules/ directory:

• core-principles.md — contractor mode, quality thresholds, verification discipline
• latex-rules.md — XeLaTeX compilation, Beamer best practices, TikZ prevention
• quarto-rules.md — rendering, deployment, cross-referencing
• r-rules.md — tidyverse style, fixest patterns, reproducibility
• meta-governance.md — MEMORY.md vs personal-memory.md distinction

Hooks

.claude/hooks/ directory enables event-driven workflows:

Example — PreCompact hook (.claude/hooks/pre-compact.yaml):

name: pre-compact
event: PreCompact
handler:
  type: command
  command: ./scripts/save-context-snapshot.sh
description: Save context before auto-compression

Real Code Examples

Creating Lecture Slides

User: Create a lecture on difference-in-differences with 2x2 design

Claude: [Enters plan mode]

PLAN:
1. Create Slides/DID-2x2.tex with Beamer template
2. Sections: Motivation, Framework, Identification, Estimation, Inference
3. Include numerical example with treatment/control, pre/post
4. Add R code snippet showing fixest::feols()
5. Run /slide-excellence for quality review
6. Run /qa-beamer for adversarial QA
7. Compile to PDF
8. Score and report

[Implements → reviews → fixes → scores 87 → presents summary]

User: just do it

Claude: [Runs /commit with quality gates passed]

Reproducibility Audit

User: /audit-reproducibility paper.tex

Claude: [Scans paper for numeric claims]

Found 47 claims:
- Table 2, Row 1, Col 2: "0.342 (0.089)" → R/analysis.R:156
- Table 3, Row 4, Col 1: "-1.23" → R/robustness.R:89
- Text line 234: "23% increase" → R/summary-stats.R:45

[Executes scripts, compares output]

FINDINGS:
✓ 44/47 claims verified
⚠ 2 STALE (script modified after paper)
✗ 1 FAIL (Table 3 Row 4: script produces -1.19, paper says -1.23)

passport.yaml updated. Quality score: 72 (below commit threshold).

Multi-Referee Variance

User: /review-paper paper.tex --variance 10

Claude: [Samples 10 referee dispositions, runs domain-referee + methods-referee + editor]

DECISION DISTRIBUTION (N=10):
- Accept: 2
- Minor Revision: 5
- Major Revision: 2
- Reject: 1

VARIANCE ANALYSIS:
- Methodological rigor concerns consistent across 8/10
- Contribution strength varies with reviewer disposition (ρ=0.83)
- Decision highly sensitive to prior belief about external validity

REPRESENTATIVE REVIEWS:
[Shows accept, minor, major, reject reviews with sampled contexts]

Recommendation: Address methodological concerns before submission.

R Code Review

User: /review-r analysis/main.R

Claude: [r-reviewer agent activated]

FINDINGS:
✓ tidyverse idioms correct
✓ fixest models specified properly
✗ Line 45: base R subsetting in dplyr pipeline
  Replace: df[df$year > 2010, ]
  With:    df %>% filter(year > 2010)
  
✗ Line 89: standard errors not clustered
  Add: , vcov = ~state

⚠ Line 134: modelsummary() missing stars_note = FALSE for publication

SCORE: 78/100 (below commit threshold)

[Presents fix plan]

Claim Verification

User: /verify-claims manuscript.tex

Claude: [Forked verifier with no draft access]

CHAIN-OF-VERIFICATION:

Claim 1: "Smith et al. (2023) find a 15% reduction"
- Citation exists: ✓
- Numerical match: ✗ (paper reports 12%, not 15%)
- Severity: HIGH-WARN

Claim 2: "Table 2 shows no significant effect"
- Cross-check with Table 2: ✓
- p-value > 0.05: ✓
- Severity: PASS

Claim 3: "consistent with Jones (2022)"
- Citation exists: ✓
- Conceptual alignment: ✓ (verified via abstract)
- Severity: PASS

Claim 4: "as discussed in Section 3"
- Internal reference exists: ✗ (no Section 3 discussion of this)
- Severity: MED-WARN

RESULT: 1 HIGH-WARN finding blocks /commit. Fix Claim 1 before proceeding.

Common Patterns

Session 1: Project Setup

1. Clone repo
2. Run ./scripts/validate-setup.sh
3. Start Claude, paste starter prompt
4. Describe first task (lecture or paper)
5. Approve plan
6. Let contractor mode orchestrate
7. Say "just do it" to auto-commit when score > 80

Slide Creation Workflow

/create-lecture "Topic Name"
  → Claude creates .tex, compiles, runs /slide-excellence, /qa-beamer
  → Reports score
  → You review findings or say "just do it"
  → Auto-commits if score ≥ 80

Paper Submission Workflow

1. /review-paper manuscript.tex --peer
   → domain-referee + methods-referee + editor in parallel
2. /verify-claims manuscript.tex
   → Catches fabrications
3. /audit-reproducibility manuscript.tex
   → Verifies all numbers against scripts
4. /humanize manuscript.tex
   → Flags AI-voice patterns (read-only)
5. Address findings
6. /review-paper manuscript.tex --variance 10
   → Sample decision distribution
7. /pr "Ready for submission" --require-score 90

Replication Package

1. /audit-reproducibility manuscript.tex
   → Generates passport.yaml with claim→script mappings
2. Review STALE/FAIL findings
3. Fix scripts or manuscript
4. Re-run until all PASS
5. /commit "Replication package verified"

Troubleshooting

XeLaTeX Compilation Fails

Symptom: /compile-latex errors with font not found

Fix:

# Rebuild font cache
sudo fc-cache -fv

# Or install missing fonts (example for Linux Libertine)
tlmgr install libertine

Quality Score Below Threshold

Symptom: "Score 76 below commit threshold 80"

Fix:

# Review findings
Show me the detailed findings from the last review

# Fix specific issues or override
/commit "Draft WIP" --override-score

Reproducibility Audit STALE Warnings

Symptom: "Script modified after paper written"

Fix:

# Re-run analysis
Rscript R/analysis.R

# Re-audit
/audit-reproducibility manuscript.tex

Prompt Cache Miss

Symptom: High cost for repeated operations

Fix:

# Check cache TTL (5-min API default, 1-hour on subscriptions)
/usage

# Batch related work to leverage cache
/create-lecture "Lecture 1"
/create-lecture "Lecture 2"  # reuses cached rules

Agent Parallel Review Hangs

Symptom: /review-paper --peer stalls

Fix:

# Monitor agent dashboard (v1.9.0+)
claude agents

# Or run sequentially
/review-paper manuscript.tex --peer --sequential

Memory Overflow on Long Sessions

Symptom: Context full, losing decisions

Fix:

# Manual compression before auto-compact
/compress-session

# Or promote learnings early
/promote-memory

HIGH-WARN Blocking Commit

Symptom: /verify-claims found fabricated citation, /commit blocked

Fix:

# Review specific finding
Show the HIGH-WARN finding details

# Fix the claim in manuscript
# Re-verify
/verify-claims manuscript.tex

# Commit once clear
/commit "Claims verified"

Environment Variables

No secrets required for core workflow. Optional for extensions:

# GitHub CLI (for /pr skill)
export GH_TOKEN="your_github_token"

# Anthropic API key (if using API directly, not Claude Code app)
export ANTHROPIC_API_KEY="your_api_key"

# R package library (optional custom path)
export R_LIBS_USER="~/R/library"

Version Compatibility

• Minimum Claude Code: 1.9.0 (for /goal, claude agents, /compress-session)
• Recommended models: Sonnet 4.6 (workhorse), Opus 4.8 (complex reasoning)
• Effort defaults: Opus 4.8 uses high by default (equivalent to prior xhigh)
• Permission modes: Auto mode requires Team/Enterprise/API + Opus 4.6+/Sonnet 4.6

Learn More

• Full guide: psantanna.com/claude-code-my-workflow
• GitHub: pedrohcgs/claude-code-my-workflow
• CHANGELOG: See CHANGELOG.md in repo for version history
• Community extensions: MixtapeTools, autoresearch, ClaudeCodeTools (see guide § The Ecosystem)