scdenney/open-science-skills / plugin/skills/deliverable-open
deliverable-open
VerifiedOpens a deliverable (talk, course module, paper, book chapter, or referee report) for AI-assisted work across sessions. Interviews the author for the manifest, then scaffolds deliverable.yml, an append-only HANDOFF.md, a numbered planning/ wiki with open questions, an inbox/ for dictated braindumps, a gitignored checks/, and the house deck template for talks. Use when starting deadline-driven work that spans sessions, or when asked to open a deliverable, set up a talk, paper, or module for the pipeline, or make a manifest. Not for one-off tasks.
Deliverable open
Full guide: docs/deliverable-pipeline.md in the repository.
A deliverable gets the pipeline when it has a deadline, an audience, and more than one session of work. This skill writes the files the rest of the pipeline reads: check_deliverable.py (the deterministic gate), deliverable-intake (braindumps into the wiki), deliverable-lint (the editorial review), and the sitrep and finished session skills.
Where the tooling lives
-
Resolve the toolchain once, before any path below.
$DTOOLis the deliverable toolchain shipped with this library atplugin/tools/deliverable. Take the first that exists:$DELIVERABLE_TOOLS; the newest installed plugin copy,$(ls -d ~/.claude/plugins/cache/open-science-skills/oss/*/ 2>/dev/null | sort -V | tail -1)tools/deliverable; theplugin/tools/deliverabledirectory of anopen-science-skillscheckout; then a legacyproject_hygiene/scriptscheckout. Scripts are at$DTOOL/scripts/and kind profiles at$DTOOL/kinds/; keep them siblings, becauselint_prepare.pyresolves profiles relative to its own directory. If none exists, stop and name the paths you tried. -
Gate script:
$DTOOL/scripts/check_deliverable.py(or$DELIVERABLE_CHECK). Its docstring is the manifest reference; read it before writing a manifest. -
Hook installer:
$DTOOL/scripts/install-hooks.sh <repo>. -
Deck template:
$RES/deck-template/(self-contained HTML + PDF deck,content.md->src/build.py). -
Handoff format: the one
courses/hdw/HANDOFF.mduses; wiki format:courses/hdw/data-module/lecture-planning/00-README.md.
Kind profiles
One file per kind at $DTOOL/kinds/<kind>.md (talk, paper, module, chapter, review): the interview questions beyond the common five, the manifest defaults, the lint questions lint_prepare.py appends, the ship step, and the related skills. Read the profile for the deliverable's kind before round 1 and let it drive rounds 2 and 3; read only that one. One piece of research has one wiki: a paper's talk and referee response declare the paper's planning/ as their planning_dir and add their own numbered files to it, rather than opening a second wiki.
Rounds
Run the interview the way research-grill does: ask the whole frontier at once, numbered, each with a one-line "why this matters" and a recommended answer; facts you can look up (dates from a calendar file, the number snapshot in a manuscript, an existing planning directory) you look up. Two or three rounds usually suffice.
Round 1, always:
- Kind and root. Which directory is the deliverable? A talk is its own folder; a course module is the module folder (
hdw/data-module/), not the repo; a paper is the folder holdingmanuscript/; a chapter is its folder underchapters/. - Audience and deadline. Who reads or hears it, and when it ships. A talk names the panel and date; a module names the class dates; a paper names the venue and submission date.
- Claim and done-test. One sentence each.
claimis what the deliverable asserts;doneis what a finished one looks like ("15 slides, ten minutes, every number traced to the snapshot, published at the URL on the QR code"). - Sources of truth. The files nothing else may contradict:
content.mdandnotes.mdfor a talk,_data/course.ymlfor a course site,numbers.texandreferences.bibfor a paper, the canonical syllabus for a module. - Sections. How the deliverable divides for review:
content-keys(deck@N.*fields),latex(\section),markdown-headings,rmd-chunks, or an explicit list. Sections are logical; never split a source file to make them.
Round 2, from the answers:
- Checks. Which gate checks apply (see the script docstring):
citations(bib, scan files,cite_fieldsfor decks,reading_listsfor Markdown syllabi,verify_bibwhere fabricated entries are the risk),numbers(source, snapshot id, the data tables that copy it),factsandleaksfor a Jekyll site,deck_budget,prose_tells,build. - Knowledge base (research repos). If the repo has a
research-repolayout, setknowledge_base: sources/mdand addreferences.bibtosources_of_truth; the gate then warns when a cited work has no Markdown source, intake routes unknown sources toprocess-source, and lint checks claims against the sources. Ask once; default to setting it whensources/md/exists. - Planning wiki. Does a wiki already exist (
lecture-planning/,chapters/CLAUDE.md,planning/map.md)? Declare it asplanning_dir; never move it. Otherwise createplanning/. - Voice pin. The writing-toolkit commit the prose rules are pinned to:
git -C $RES/writing-toolkit rev-parse --short HEAD. - Night shift. Stays
enabled: falseat open. Say so; it is switched on only after one manualdeliverable-lintrun has been read.
What gets written
At the deliverable root:
deliverable.ymlwith every field the interview settled; comment the ones it did not.- A vendor-neutral
agent:block at the top of the manifest (Claude runs/oss:<name>, Codex runs$<name>; the shareddeliverable_context.pyprints it at session start for both):agent: on_braindump: deliverable-intake on_review_request: deliverable-lint on_session_end: finished preserve_raw_captures: true session_state: HANDOFF.md - Commons fields when the research commons exists (
$GH/research/commons/):commons_root(relative path),commons_tags(sorted lowercase slugs), and optionallycommons_revision(a full commit to pin). At session start only the commons INDEX lines matching the tags enter context, capped at twenty; cards and threads are read on demand. HANDOFF.mdwith the standard header and a first entry dated today: Decision (what was opened and why), Completed (the files created), Next actions (run the gate; first intake).planning/00-README.md(folder map, sources of truth, decisions recorded here) andplanning/08-open-questions.md(open list plus a resolved log) unless an existing wiki was declared; then add the manifest pointer to that wiki's index instead.inbox/README.md: "Raw captures. Dictate into a new dated file here; never edit a capture;deliverable-intakepromotes it and renames it*.done.md."checks/.gitignorecontaining*and!.gitignoreand!release.jsonand!citations.json.- For
--kind talkwith nosrc/present: copy the deck template'ssrc/,content.md,notes.md, andREADME.md, then setbuild.commandandsources_of_truthin the manifest accordingly.
Then offer each of the following, and do it only on a yes, since each writes outside the deliverable:
install-hooks.sh, if the repo has no.githooks/pre-commit.- Appending the deliverable's proper nouns (people, places, named theories, project names) to
~/.config/macwhspr/vocab.mdso dictation renders them correctly: one term per line, under a heading naming the deliverable. - Adding the manifest path to
~/.claude-assistant/config/deliverables.yml(the night-shift registry). Listing is not enabling. - Appending the canonical paragraph from
$DTOOL/notes/agents-pipeline-paragraph.mdto the repo-rootAGENTS.mdwhen it lacks a## Deliverable pipelinesection. That paragraph tells either vendor when to invoke which on-demand skill, and lets Codex, which has no hooks, start from the same context. If the repo has noAGENTS.md, say so and leave it; creating one is outside this skill.
Exit
Run python3 $DTOOL/scripts/check_deliverable.py --root <dir> once and show the result. Name the next step in one line: dictate the first braindump into inbox/, then /oss:deliverable-intake.
Notes
- Threshold: a deadline, an audience, more than one session. A four-hour referee report qualifies; a two-day analysis nobody reads does not.
- One manifest per deliverable; a course with six sessions is one deliverable with six sections, not six deliverables.
- Overleaf submodules: the manifest and the other house files live in the parent repository beside the submodule, never inside it.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |