QUESTIONS.mdAskName what is known, open, or blocked.
A Research Notebook Your Coding Agent Can Use
Research practice · Agent skills · Open source
I keep a second repository beside each research project. It is made of Markdown files: one per experiment, one per cross-experiment finding, plus short indexes for open questions, priorities, claims, and publication work. The files are shared context between me and my coding agents.
lab-notebook/ Choose a file to see the question it owns.
Where does this project stand now?
A one-page snapshot that points to evidence, open questions, next actions, and publication blockers without copying their contents.
The record survives the session
Experiment trackers are good at metrics and hyperparameters. A research project also needs the reason a condition existed, what was expected before the run, why an anomaly matters, and which claim the result can support. Those facts often live in chat history or in the researcher's memory. Neither is reliable shared context.
A text notebook gives those facts an address. An agent can answer “Have we already tested this?”, register a new experiment in the local format, or trace a sentence in a paper back to the jobs that support it. Git gives the record dates and diffs. Obsidian, ripgrep, an editor, or a plain file browser can read the same files.
Each record has one job
experiments/TestKeep method, predictions, runs, and results together.
findings/SynthesizeCombine evidence only when a conclusion spans experiments.
CLAIMS.mdArgueLink paper-sized claims to direct evidence and scope.
Other files appear when they earn a role. GLOSSARY.md stabilizes local terms,
BIBLIOGRAPHY.md annotates related work, and plans/ holds bounded
campaigns that must survive several sessions or move between agents. The separation matters
more than the filenames: one record owns each fact, and short indexes point to it.
Predictions and outcomes stay together
Record ranges, nulls, controls, and decision branches before inspecting outcomes.
Place observed values beside each prediction, then record scope and uncertainty.
Follow the recorded branch without reconstructing intent from a vanished chat.
Job completion and evidence processing are different states. A finished run is not processed until its outputs have been checked, the notebook update validates, and the durable write succeeds. Weft can provide that distinction directly. Setup adds a small processed-job ledger for SkyPilot, Slurm, Dagu, Pueue, and other backends that do not.
Documentation
The essay is the why. The docs hold the how.
The workflow guide covers setup, experiments, completed jobs, synthesis, durable campaign plans, literature archiving, and handoffs with a synthetic example. The paired reference catalogs every file and directory, runner and ledger rules, and the experiment and plan schemas.
Install it, then start small
npx skills add osteele/agent-skills -s research-lab-notebook -yUse $research-lab-notebook to add a research notebook to this project. Jobs run through Slurm.
Substitute your runner. The public collection contains no autonomous research loop, unattended plan executor, code-audit hooks, private compute configuration, or job runner implementation. The notebook works when every job is launched by hand.
The useful idea is smaller: research context belongs in durable, inspectable files. Once the context exists, both a human and an agent can pick up the work without asking a vanished session what happened.
Guide and reference Repository and installation Agent Skills specification