sci-brain

Research skills for Claude Code, Codex, OpenCode, and pi. Point it at a research topic — it surveys the literature, builds a citable knowledge base on your disk, writes grounded reports, and brainstorms research ideas with you.

Skill question styles inspired by superpowers.

Install

Claude Code:

/plugin marketplace add QuantumBFS/sci-brain

Codex / OpenCode: clone this repo and symlink its skill directories into your agent's discovery path — see .codex/INSTALL.md or .opencode/INSTALL.md. Or simply tell your agent:

Install the plugin/skills from https://github.com/QuantumBFS/sci-brain

pi: install the npm package:

pi install npm:sci-brain

Start Here: Survey a Field

/survey asks one question to narrow your topic, then searches in parallel with up to seven strategies — landscape mapping, adjacent subfields, cross-vocabulary, cross-method, historical lineage, negative results, and benchmarks. You pick which directions are worth keeping; only those go into the knowledge base. Every BibTeX entry is verified against CrossRef or Semantic Scholar — never invented from memory. The same skill then fetches the papers and renders their full text, so it can turn the populated knowledge base into a structured assessment: what the technology is and why it matters, the main approaches with their state of the art and trade-offs, and the key open problems. It can also enter report mode directly for an existing KB.

Everything lands in one folder inside your project:

<project>/.knowledge/
  references.bib      verified BibTeX — point your LaTeX/Typst bibliography here
  INDEX.md            auto-generated table of contents
  NOTES.md            curated sub-themes, open problems, bottlenecks
  <id>_<slug>.md      full-text papers rendered to markdown
  .raw/               original PDFs, metadata, and optional sources (gitignored)
  .figures/           extracted figures (gitignored)

One-time setup for PDF rendering: python3 -m pip install --user pymupdf4llm. Add playwright (python3 -m playwright install chromium) only if you need the Sci-Hub fallback for paywalled DOIs.

Then: Brainstorm Ideas

/brainstorm-ideas

A Socratic research mentor. It first asks about your background — describe yourself, or point it at your Zotero library or Google Scholar profile so it can learn from your own papers. The better it knows you, the better its recommendations.

You can also pick a domain expert advisor (distilled from real scientists' conversations with AI — see the advisor list) who joins the session as a subagent and challenges your thinking.

If you ran /survey first, the brainstorm automatically picks up the knowledge base and grounds the conversation in it. At wrap-up it can write a structured ideas report with the full reasoning trail.

Also: Run Autonomous Research

/autoresearch is for pushing a research direction forward on its own. It runs a four-stage pipeline — topics → evidence base → sealed validator → scored attempt loop. Each cycle plots every attempt's raw score, while reports include a full-campaign overview and ranked, evidence-grounded next directions; if it gets stuck it refreshes its insights from /survey.

Also: Write Papers & Slides

/paper-writer drafts a real scientific manuscript from your actual results. It encodes the figures-first workflow — figures → telegram outline → body → polish, with abstract, intro, and conclusions written last. Unlike the ideas report from /brainstorm-ideas, it requires real results rather than open problems, and produces a submission-ready draft.

/slide-writer builds PDF slide decks in Typst + Touying for scientific talks, lectures, and briefings, from a browsable zoo of themes, layouts, and gadgets (rail pulls, callouts, theorem boxes, and more).

More Skills

Skill	What it does
/paper-reviewer	Review an existing manuscript against writing guidelines; verifies references
/figure-taste	Score a figure's visual design against an 18-rule rubric
/flow	Autonomous deep-thinker that attacks one hard goal via a search loop
/know-me-better	Index your Zotero / PDF folder / Google Scholar collection into the KB
/conversation-dump	Extract and classify research conversations from Claude Code or Codex histories
/incarnate	Import JSONL or Markdown conversations, distill thinking patterns, and capture a reusable advisor profile

Where Things Are Saved

• Project knowledge base — <project>/.knowledge/ (see layout above). Populated by /survey and /know-me-better.
• Advisor knowledge bases — advisors/<slug>/.knowledge/ — each advisor's private literature cache, same layout.
• Conversation logs — docs/discussion/ — timestamped per session; the next session picks up where you left off.
• Ideas reports — articles/ in your current directory, with a matching .bib file.

Want to Become an Advisor?

If you've used Claude Code or Codex for research conversations and want your thinking style captured as a reusable advisor profile, just tell your agent:

clone https://github.com/QuantumBFS/sci-brain,
invoke incarnate skill in the cloned repo to create my profile,
then submit a pr,
include all relevant chat history, interview output and the generated profile.

The whole process is interactive — you review everything before it's published, and you decide whether to include the raw conversation data (for research purposes) in the PR.

Upgrading from ≤ 0.2

⚠️ Breaking change in v0.3. Knowledge bases moved from per-topic registries (~/.claude/survey/<topic>/ with summary.md + references.bib) to one <project>/.knowledge/ per project, with references.bib living inside the KB. The fetch-papers skill was folded into /survey's fetch step. See CLAUDE.md § "Migrating from the pre-0.3 layout" for mv commands.

Four internal stages are now modes of their goal-level skill. Update explicit command references as follows:

Previous command	Current entry point
/survey-writer	/survey in Survey Report mode
/idea-writer	/brainstorm-ideas in Ideas Report mode
/import-dialog	/incarnate with Markdown dialog input
/soul-extraction	/incarnate in analysis-only mode

Contributors

Initiators: Lei Wang and Jin-Guo Liu

License

MIT. Feel free to adapt from the current codebase, BUT please acknowledge this package properly, thank you.