A file-based research notebook gives a coding agent somewhere durable to read and write between sessions. Experiments, results, open questions, decisions, and publication claims stay in Markdown beside the project. The notebook complements metric trackers such as Weights & Biases and MLflow; it records the reasoning those systems do not.
This repository packages the system as portable Agent Skills. It does not assume a particular coding agent, compute cluster, or job service.
Current documented contract: v0.4.0.
The skills CLI can install the
collection for Claude Code, Codex, Cursor, OpenCode, and many other agents:
Install the notebook skill into the current project:
npx skills add osteele/agent-skills --skill research-lab-notebook -yList the available skills without installing them:
npx skills add osteele/agent-skills --listInstall globally for specific agents:
npx skills add osteele/agent-skills -g -a claude-code -a codex -yAdd the optional reference archiver too:
npx skills add osteele/agent-skills \
--skill research-lab-notebook \
--skill download-research-references \
-yThe CLI uses a shared canonical copy when possible, so one update can serve several agents. Project installs travel with the project configuration; global installs are available across projects.
Try the notebook skill without installing it:
npx skills use osteele/agent-skills@research-lab-notebookMaintain an installation with:
npx skills update research-lab-notebook
npx skills remove research-lab-notebookAdd -g to update or remove the global installation. Set
DISABLE_TELEMETRY=1 if you do not want the CLI to send its anonymous install
telemetry. See the skills CLI
for its current agent list and options.
Clone the repository, then copy or symlink each directory under skills/ into
your agent's skills directory. Common global locations include
~/.claude/skills/ for Claude Code and ~/.codex/skills/ for Codex. Project
installs usually live under the corresponding hidden directory in the project.
Review any skill before installing it. Skills are instructions that an agent may follow with your file, shell, and network permissions.
| Skill | Purpose |
|---|---|
research-lab-notebook |
Creates, adapts, validates, and operates the notebook. It covers experiments, findings, campaign plans, publication claims, and connections to Weft, SkyPilot, Slurm, Dagu, Pueue, local processes, or another backend. |
download-research-references |
Archives open-access papers cited by a LaTeX or Typst draft into references/ and maintains BIBLIOGRAPHY.md. |
After installation, ask your agent:
Use $research-lab-notebook to add a research notebook to this project. Our jobs run through Slurm.
Some agents use $research-lab-notebook for explicit skill invocation. In an
agent without that syntax, say “Use the installed research-lab-notebook skill”
instead.
Substitute another runner or your own system. The notebook skill inspects the backend, writes a small adapter contract into the project instructions, and chooses processed-state storage itself. It uses a runner's native feature only when that feature is durable and queryable. Otherwise it creates a ledger keyed by backend and job ID; the prompt does not need to mention the ledger.
The core evidence path is deliberately small:
research question
-> experiment (hypothesis, method, predictions, runs, results)
-> finding (only when evidence spans experiments)
-> claim and publication plan
The baseline contains four top-level files and two directory indexes. Add other files only when their question becomes real:
| File | Question it answers | Add it when |
|---|---|---|
STATUS.md |
Where does the project stand now? | Baseline |
QUESTIONS.md |
What is known, open, or blocked? | Baseline |
PRIORITIES.md |
What should happen next? | Baseline |
CHANGELOG.md |
What was learned or decided, and when? | Baseline |
GLOSSARY.md |
What do project-specific terms, symbols, and acronyms mean? | Terminology needs a stable definition |
BIBLIOGRAPHY.md |
Which papers matter, what do they say, and how are they relevant? | Related work is being tracked or cited |
CLAIMS.md |
Which claims belong to each paper, what role do they play, and what supports them? | A publication argument needs evidence tracking |
PUBLICATION.md |
What blocks each paper, and where might it go? | A paper enters active preparation |
COMPANION-DOCS.md |
Which reports, guides, presentations, or IP documents accompany the research? | Several non-paper artifacts need an index |
QA.md |
Which questions should a presentation be ready to answer? | Preparing a talk or defense |
The directories separate records with different lifecycles:
| Directory | Contents | Add it when |
|---|---|---|
experiments/ |
One mutable record per experiment: prediction, method, runs, results, interpretation, and conclusion. | Baseline |
findings/ |
Dated, immutable syntheses that integrate evidence across experiments. | Baseline; it may remain empty until evidence spans experiments |
plans/ |
Versioned contracts for bounded, multi-step research campaigns. | Work spans experiments, phases, agents, or sessions |
reports/ |
Longer living analyses and their figures. | A synthesis is too large or too changeable for a finding |
papers/ |
Notebook-resident manuscripts authored by the project, plus their shared BibTeX file. | Drafting a paper inside the notebook |
references/ |
Downloaded cited papers and source notes. PDFs are an ignored reading cache; tracked indexes and metadata may live beside them. | Archiving or annotating literature |
kb/ |
Stable methodology, terminology, comparisons, and other reusable project knowledge. | Material should be maintained as reference, not evidence |
causal-models/ |
Working mechanism hypotheses kept distinct from observed findings. | Several interventions inform one mechanism hypothesis |
jobs/processed/ |
Fallback processed-job ledger. | Setup detects no suitable native processed state |
Each experiment keeps its a priori predictions next to observed outcomes. The record makes exploratory and confirmatory work distinguishable and gives later agent sessions the decision context that would otherwise disappear.
The repository includes a runnable gradient-accumulation example that asks whether accumulation reproduces true large-batch training. Its record grows like this:
QUESTIONS.md
RQ1: Does accumulation preserve optimization behavior at fixed effective batch?
plans/completed/2026-08-12-accumulation-controls.md
Phase 1: one cheap smoke test; continue only if loss curves are finite
Phase 2: three seeds for true-batch and accumulated-batch conditions
experiments/EXP-001-accumulation-pilot.md
Prediction written before the run: final validation loss differs by < 0.02
Run: slurm/48152; artifact: results/EXP-001/metrics.json
findings/2026-08-16-accumulation-matches-large-batch.md
Synthesis across EXP-001 and EXP-002, with effect sizes and scope limits
CLAIMS.md
C1 major, gradient-accumulation-note: accumulation matches true batches in the toy simulator
The plan does not hold the result, the finding does not rewrite the prediction, and the claim does not silently expand beyond the tested scale. Each file owns one part of the argument.
Files under plans/ are not the same thing as Claude Code or Codex planning
interfaces. An agent-native plan helps organize and approve the current coding
task. A notebook plan is a version-controlled research artifact:
| Agent-native plan | plans/*.md campaign plan |
|---|---|
| Coordinates one agent task or conversation | Coordinates a research objective across experiments and phases |
| Optimized for the current agent's next actions | Readable by humans, other agents, CI, schedulers, or a custom harness |
| May end when the task or session ends | Survives context resets, agent changes, and many sessions |
| Tracks implementation steps | Tracks evidence, dependencies, gates, risks, stop conditions, and required notebook updates |
| Approval usually starts the current task | Never grants new authority for compute, destructive actions, publication, or external writes |
One agent can draft a campaign, a researcher can approve its scope, a separate
agent or harness can execute one authorized phase, and a later agent can review
the evidence and resume at next_action. Status and history live in version
control instead of one provider's conversation state. Native planning modes are
still useful: use them to reason about creating or executing a durable campaign
plan. See the plan specification.
The skills describe a job runner by capability rather than command name. An adapter should tell the agent how to:
- submit a bounded job tagged with the experiment ID;
- inspect status and logs;
- retrieve immutable outputs and provenance;
- cancel a job when authorized;
- determine whether a completed job has been processed; and
- mark processing complete only after notebook updates are durable.
Weft can provide the processed distinction directly. The other runners below track execution, not whether evidence has entered the notebook, so setup adds the ledger automatically.
| Runner | Best fit | What it manages | Separate processed ledger? |
|---|---|---|---|
| Weft | Single-researcher jobs across workstations, shared servers, and GPU rentals | Placement, source and input staging, execution, logs, artifacts, and native processed tags | No, when native state is retained and queryable |
| SkyPilot | Portable AI jobs across clouds, Kubernetes, Slurm, and existing machines | Infrastructure provisioning, managed jobs, recovery, and teardown | Yes |
| Slurm | Multi-user Linux clusters with centrally administered resources | Allocation, queueing, execution, monitoring, and optional accounting | Yes |
| Dagu | Self-hosted workflows that run locally, through SSH, or on containers/Kubernetes | Scheduling, DAGs, retries, logs, notifications, and run history | Yes |
| Pueue | Persistent sequential or parallel commands on one machine | A durable command queue, groups, dependencies, status, and logs | Yes |
SkyPilot and Slurm also need project-specific artifact locations. Dagu and Pueue need an artifact convention or wrapper when outputs are not already written to durable storage. The notebook skill records these mappings rather than teaching its core operating rules provider-specific syntax.
This public collection does not contain:
- an autonomous research loop;
- unattended plan execution;
- code-audit hooks or research-script lint rules;
- credentials, hostnames, personal paths, project rosters, or private venue notes; or
- a job runner implementation.
Those choices belong to each lab's environment and risk model. The notebook is useful even when every job is launched by hand.
MIT. See LICENSE.