claude-skills / research-agent

research-agent v0.7.9

Orchestrates a multi-agent research pipeline. Takes comma-separated topics, spins up parallel research workers, and produces peer-reviewed papers with optional Haskell formal verification, a Vercel-deployed website, multi-platform social posts, and end-to-end Slack notifications.

View source on GitHub

Install

From inside Claude Code:

/plugin marketplace add YonedaAI/claude-skills
/plugin install research-agent@local-skills

Usage

/research-agent "topic-a,topic-b,topic-c" --perspective "your framing"

Options

Flag	Description	Default
`--perspective "..."`	Framing perspective for all papers	Inferred from project context
`--project <name>`	Project directory name	Derived from first topic
`--project-path <path>`	Where to create the project	Current working directory
`--github-org <org>`	GitHub organization	`YonedaAI`
`--no-haskell`	Skip Haskell formal verification	Enabled
`--no-website`	Skip website build + Vercel deploy	Enabled
`--no-social`	Skip social media posts	Enabled
`--slack-channel <ID>`	Slack channel for notifications	`$RESEARCH_SLACK_CHANNEL`

Pipeline

Eight phases. Each phase has mandatory checkpoints — a missing review or skipped gate is a hard failure, not a warning.

Phase 1: Setup ──> Phase 2: Knowledge Base ──> Phase 3: Workers (parallel)
                                                  │
                              ┌───────────────────┼───────────────────┐
                              ▼                   ▼                   ▼
                         Topic A              Topic B              Topic N
                         Draft (20+ pages)    Draft (20+ pages)    Draft (20+ pages)
                         Gemini Peer Review   Gemini Peer Review   Gemini Peer Review
                         Claude Fix           Claude Fix           Claude Fix
                         Codex LaTeX Check    Codex LaTeX Check    Codex LaTeX Check
                         Claude Fix           Claude Fix           Claude Fix
                         Compile PDF          Compile PDF          Compile PDF
                         Cover Image          Cover Image          Cover Image
                         Slack ✓              Slack ✓              Slack ✓
                              │                   │                   │
                              └───────────────────┼───────────────────┘
                                                  ▼
Phase 4: Synthesis ──> Phase 5: Haskell Verify ──> Phase 6: Website + Vercel
                                                          │
                                                   Phase 7: Social Posts
                                                          │
                                                   Phase 8: Git + GitHub + Slack Summary

Phases

Project setup

Creates the project directory, initializes git, pins the commit author from $RESEARCH_GIT_AUTHOR.

Knowledge base

The knowledge-base-builder agent reads source files (LaTeX, Markdown, PDFs) and produces a structured .knowledge-base.md that every worker reads before drafting.

Parallel research workers

One research-worker per topic, spawned in parallel. Each one drafts an arxiv-style ≥20-page LaTeX paper, accompanying Haskell code, runs Gemini peer review and Codex formatting check, fixes issues, compiles to PDF, generates a cover image, and notifies Slack.

Synthesis

The synthesis-agent reads every worker's output and produces a unifying paper that draws cross-cutting themes and emergent properties.

Haskell verification

The haskell-verifier compiles each topic's Haskell module with GHC, runs its tests, and routes failures through Codex for repair. Optional — disable with --no-haskell.

Website + Vercel

The website-builder generates a Next.js 14 dark-themed static site with paper cards, individual paper pages, KaTeX math rendering, and PDF downloads. Designed 1200×630 OG cards are generated and validated, the site is reviewed by Codex, then deployed to Vercel under the project's slug subdomain.

Social posts

The social-posts agent writes platform-tuned posts for Twitter/X, LinkedIn, Facebook, and Bluesky — respecting each platform's character limits, formatting rules, and audience tone.

Finalize

Generates the project README, runs the pipeline-validator hard gate (OG image dimensions, Slack message URL safety, .vercel-url integrity, artifact presence), commits and pushes to a new GitHub repo, and sends a final Slack summary.

Agents

knowledge-base-builder

Sonnet

Reads source files, extracts structured summaries, writes the canonical knowledge base every worker reads before drafting.

research-worker

Opus · spawned per topic

Drafts an arxiv-style LaTeX paper plus optional Haskell code. Runs its own Gemini peer review loop and Codex formatting check before handing off.

synthesis-agent

Opus

Reads every completed worker output and produces a unifying paper that draws cross-cutting themes and shows compositional structure.

haskell-verifier

Opus

Compiles each topic's Haskell module with GHC, runs tests, and routes failures through Codex for repair. Ensures formal verification code actually compiles.

website-builder

Sonnet

Builds a Next.js 14 dark-themed research site with KaTeX math rendering, paper cards, PDF downloads, and OG meta tags. Deploys to Vercel under the project slug.

og-image-generator

Haiku

Renders 1200×630 designed social cards with the paper title, accent stripe, and project tag — not letterboxed PDF thumbnails.

social-posts

Sonnet

Generates platform-tuned posts for Twitter/X, LinkedIn, Facebook, and Bluesky with the right tone and character limits per platform.

pipeline-validator

Haiku · hard gate

The pre-Slack constraint checker. Validates OG dimensions and pixel std-dev, scans the proposed Slack message text for bare URLs and unbalanced bold markers, cross-checks the deployed Vercel URL, and confirms required artifacts exist before the final notification is sent.

Review pipeline

Every paper goes through two mandatory, externally-enforced review cycles.

Gemini peer review via the gemini CLI (model is $RESEARCH_GEMINI_MODEL, default gemini-3.1-pro) — adversarial review by an external LLM, not self-review. Saved to reviews/$TOPIC-review-round-N.md. Iteration runs until the verdict is ACCEPT or MINOR REVISIONS (max 4 rounds).
Codex formatting check — LaTeX compilation, references, styling. Each worker invokes the codex:rescue skill and applies fixes. Max 2 fix iterations per cycle.

After all workers complete, an orchestrator-level pass verifies every reviews/$TOPIC-review.md exists with substantive content. The website also gets its own Codex review before Vercel deploy. The pipeline-validator agent then hard-gates the final Slack notification on OG image quality, message URL safety, and artifact integrity.

Output structure

project/
├── papers/latex/*.tex          # LaTeX sources with GrokRxiv sidebar
├── papers/pdf/*.pdf            # Compiled PDFs
├── reviews/*.md                # Gemini peer review feedback
├── src/*/                      # Haskell formal verification code
├── images/*.png                # Cover images (300 DPI)
├── docs/papers/*.html          # Pandoc HTML conversions
├── website/                    # Next.js 14 static site (deployed to Vercel)
│   └── public/og/*.png         # 1200×630 designed OG cards
├── posts/{twitter,linkedin,facebook,bluesky}/
│                               # Platform-specific social posts
├── .knowledge-base.md          # Structured knowledge base
└── README.md                   # Project overview

Configuration

All configuration is via environment variables. Sensible defaults are baked in — none are required for a basic run.

Environment variables (21+)

Env Var	Default	Purpose
`RESEARCH_AUTHOR_NAME`	`Matthew Long`	Paper author name
`RESEARCH_AUTHOR_EMAIL`	`matthew@yonedaai.com`	Author contact email
`RESEARCH_AUTHOR_URL`	`https://yonedaai.com`	Author website
`RESEARCH_COLLABORATION`	`The YonedaAI Collaboration`	Collaboration line in author block
`RESEARCH_INSTITUTION`	`YonedaAI Research Collective`	Institution line
`RESEARCH_LOCATION`	`Chicago, IL`	Author location
`RESEARCH_GITHUB_ORG`	`YonedaAI`	GitHub org for repo creation
`RESEARCH_SLACK_CHANNEL`	`C0AK269AVSA`	Slack channel for notifications
`RESEARCH_GEMINI_MODEL`	`gemini-3.1-pro`	Gemini model for peer review
`RESEARCH_WORKER_MODEL`	`opus`	Model for research-worker / synthesis
`RESEARCH_UTILITY_MODEL`	`sonnet`	Model for utility agents
`RESEARCH_GEMINI_BIN`	fnm absolute path	Absolute path to `gemini` CLI (fnm shims aren't active in agent subshells)
`RESEARCH_CODEX_BIN`	fnm absolute path	Absolute path to `codex` CLI
`RESEARCH_GIT_AUTHOR`	`Matthew <mlong@magneton.io>`	Git author for every commit (RFC 2822)
`RESEARCH_GIT_AUTHOR_NAME`	parsed	Override the parsed name
`RESEARCH_GIT_AUTHOR_EMAIL`	parsed	Override the parsed email

Requirements

Claude Code with plugins enabled
gemini CLI (model configurable via $RESEARCH_GEMINI_MODEL)
pdflatex for LaTeX compilation
pandoc for LaTeX → HTML conversion
ghc / cabal / stack for Haskell verification
vercel CLI for deployment
pdftoppm from poppler for cover image generation
ImageMagick (magick) for OG card rendering
Codex plugin (codex@openai-codex)
Slack MCP for notifications