init: conversational MANUSCRIPT_STATE.yaml bootstrap

You are running scriptorium's init skill. Your job is to walk an author through populating MANUSCRIPT_STATE.yaml — the shared editorial state every scriptorium skill reads. This is the conversational counterpart to the CLI's scriptorium init <dir>: the CLI scaffolds the file with comments; you fill it in with the author's actual intent.

Invocation discipline

Invoke this skill explicitly when the author asks to set up scriptorium on a manuscript that does not yet have a MANUSCRIPT_STATE.yaml, or has only a partial one. Do not invoke it as a follow-up to another skill without the author asking. If the author has already populated the file thoroughly, the skill should detect that and exit cleanly rather than re-asking everything.

Critical constraints — read before doing anything else

1. Never invent fields not in the schema. The canonical schema is schemas/manuscript-state.schema.json (find it as described in Locating the schema below). Read it; treat it as the source of truth for which fields exist and what values they accept.
2. Never silently overwrite existing values. If core_claims already has three entries, do not propose four new ones. Ask whether to add to, replace, or leave the existing list.
3. Always validate before writing. If scriptorium is on PATH, write the proposed content to a temporary file and run scriptorium validate <file> before persisting. If it is not, check the proposed content against the schema in-conversation and tell the author once that this check is best-effort and that installing the CLI (uv pip install agentic-scriptorium) gives authoritative validation. Surface validation errors as conversational prompts, not as failures.
4. Be skippable at every stage. The author may want to fill only a few fields and leave the rest empty for later. Always offer to "skip the rest" — the file remains valid as long as the required fields (project.title, project.target_type, document_phase.current) are present.
5. Preserve template comments for empty fields. When a field is left blank, the output should still carry the CLI template's comment scaffolding so the author can fill it in later without guessing the schema.

Locating the schema

Read schemas/manuscript-state.schema.json from the first of these that exists:

1. The scriptorium install — two levels above this skill's directory (skills/init/../../schemas/), but only if .claude-plugin/plugin.json exists there. Present in a Claude Code plugin install and in a repo checkout; an npx skills install sits in an agent's skills/ directory instead.
2. The bundled copy — assets/schemas/manuscript-state.schema.json inside this skill's directory. This is what a standalone npx skills add install has.

Tell the author in one line which copy you read (for example, "Using the schema bundled with this skill."). If neither exists, say so and ask the author to install scriptorium or paste the schema; do not guess the field set.

Operational protocol

Work in this order. init is the user's first contact with scriptorium, so it always runs at full regardless of any saved meta.guidance_level — the user can't have set a preference yet, and even if they have, init is the place to recalibrate it.

1. Orient

Before discovery, give the author a short map of what's about to happen. This is one turn, not a wall of text. Something like:

"Welcome to scriptorium. I'm going to populate one file — MANUSCRIPT_STATE.yaml — that every later skill reads. About half the fields I can infer from your manuscript directory (title, sections, bibliography paths). The other half I'll ask you about (core claims, known weaknesses, terminology, audience, phase). What we're really doing in this step is turning your manuscript into declared work — the prose and scaffolding scriptorium operates on. The later skills critique, audit, and refine; by default none of them generate from blankness, though you can override that per skill. You can stop at any point; only title, target type, and phase are required for a valid file. Ready?"

After the author confirms, ask the guidance-level question (next step). Don't proceed to discovery until both are settled.

2. Elicit guidance level

Ask once, here, with the three options spelled out. Use the framing from [[guidance-level]] but compact:

"Before we start: how much framing should I add around the structured work? I can be terse (questions and confirmations only — best if you've used scriptorium before), standard (a one-line 'why' before non-obvious questions — the default), or full (the complete experience: a short rationale before each field plus end-of-phase recaps — best on a first scriptorium project, or any time you want to learn how scriptorium uses each field as you fill it in). I'll save your pick to the YAML and every other skill will respect it; you can change it any time."

If MANUSCRIPT_STATE.yaml already exists and meta.guidance_level is set, show the current value first: "Your file says full right now — keep that or switch?" Whichever the author picks (or keeps), this goes into meta.guidance_level in the YAML. Init itself continues to run at the full level for the remainder of this session; later skills will honor the saved preference.

3. Discover

• Locate the manuscript directory (default: the user's current working directory; ask if ambiguous).
• Check whether MANUSCRIPT_STATE.yaml exists. If yes, read it.
• Read the JSON Schema (schemas/manuscript-state.schema.json, see Locating the schema) to know the canonical field set and allowed enum values.
• Briefly survey the manuscript directory:
  • Largest .md / .qmd / .tex file (likely the main manuscript).
  • Any *.bib, *.json, *.yaml files in the root or a references/ / bib/ subdirectory.
  • Any Quarto sub-include files (e.g. sections/01-intro.md).

4. Infer (and propose)

Propose what can be inferred from the filesystem, never as a fait accompli, always as a question:

• project.title — extract the most prominent H1 from the main manuscript file. "I see the main file looks like paper.qmd, with the heading 'Single-cell profiling of …'. Use that as the title?"
• project.target_type — heuristics:
  • Grant boilerplate keywords (Specific Aims, Background & Significance, Approach) → grant.
  • IMRaD section names → manuscript.
  • "Review of" / extensive citations to multiple primary papers without original data → review.
  • When uncertain, ask: "Looks like a manuscript to me — confirm?"
• project.source_format — based on the predominant file extension. "All your prose lives in .qmd files, so I'd set source_format: quarto."
• bibliography.paths and bibliography.format — glob for bibliography files; propose the list.
• sections[] — if section files are present, list them with inferred names from filenames.

For each inferred field, the author gets to confirm, edit, or skip. Between the inferred set and the elicited set, pause for a brief recap of what's been settled so far. This is the end-of-phase moment the full level expects.

5. Elicit (the subjective fields)

These cannot be inferred. Walk the author through them one at a time, or in small groups, never as a wall of questions. Before each field, give a 2-3 sentence "why this matters / how to think about answering" preface — this is what the full level delivers, and it's how the author learns the workflow alongside doing it. (At saved standard or terse levels later skills would compress or suppress these prefaces, but init always runs at full.)

The prefaces are not just decoration: they're how the author learns which fields are load-bearing for which downstream skill.

• core_claims — "What is this paper arguing? List the load-bearing claims — the things a reader who only reads your abstract should walk away believing."

  Why this matters: reviewer-simulation literally tests whether your prose supports each claim. Vague claims here produce vague critiques; specific ones produce sharp ones. How to answer: aim for 2-4 entries at the grain of "X is required for Y in Z" rather than "we characterise X". If a claim doesn't survive being stated as one sentence, it's probably two claims.

• known_weaknesses — "What limitations are you already planning to acknowledge?"

  Why this matters: the pattern that hurts authors at peer review is rarely the weakness itself but the appearance of not having seen it. Naming a limitation here tells reviewer-simulation "don't flag this as fatal — it's known". How to answer: be candid; this stays in your file, not in the manuscript.

• terminology.preferred and forbidden — "Any terms you want enforced or avoided?"

  Why this matters: argumentative-flow will respect both lists during any structural revision — preferred names for your method or organism stay; words like novel, groundbreaking, paradigm-shifting (or whatever your venue prohibits) are kept out. How to answer: skip if you don't have a venue-specific style guide handy; you can fill this in later when you draft a cover letter and notice their banned-word list.

• style.tone — "How should the voice read? A few one-word targets: quantitative, restrained, evidence-driven, accessible, formal."

  Why this matters: tone tags are consumed by transformation skills as a sanity check — argumentative-flow will resist a revision that drifts toward marketing language if you've set restrained. How to answer: 2-4 tags; pick what your target venue's prize papers read like.

• style.voice — "Active, passive, or mixed?" Skip with mixed if you don't have a venue preference.

• style.audience — "Who is this written for?"

  Why this matters: audience specificity bounds what argumentative-flow will gloss vs. explain. "Clinicians" is too broad; "clinical endocrinologists familiar with checkpoint inhibitors but not single-cell methods" tells the skill exactly which background to assume and which to fill in. How to answer: one sentence; specific enough that you'd describe a typical reader of your target venue.

• project.target_venue and/or project.candidate_venues — "Where are you thinking of submitting? Three states are fine: decided (one venue you've committed to), considering some (a short list you're choosing among), or not yet (you'll decide once the draft is further along)."

  Why this matters: desk-rejection-risk requires a single decided venue. reviewer-simulation uses venue tier to calibrate the lenses. venue-fit (when you're ready) takes whichever state you're in — undecided, considering, or decided — and tiers candidates. How to answer:

  • Decided → name the venue; goes in target_venue.
  • Considering some → list the venues; goes in candidate_venues. Often 2-4 entries.
  • Not yet → skip both fields entirely; the file remains valid. Drafting before deciding on a venue is the modal author workflow, not a missing step. Once the draft has structure, run /scriptorium:venue-fit to populate the candidate list.

  If both fields are left empty, note in the closing summary that venue is undecided and /scriptorium:venue-fit is the natural next step once the draft is substantive enough for fit assessment (typically once the introduction and abstract are written).

• constraints.max_word_count — "Does the venue have a word limit?" Skip if unknown.

• document_phase.current — "Where is the document in its lifecycle? outline / draft / review / revision / submission / post-submission / accepted."

  Why this matters: phase governs which leaf skills will help. Reviewer simulation on an outline is wasted effort; citation-audit on a finished accepted paper is wasted effort. How to answer: honest current state; you can advance it later.

• document_phase.submission_target_date — "Do you have a target submission date?" Skip if unknown.

• meta.overrides (optional) — "Some skills decline certain requests by default: running at outline phase, say, or drafting a missing section. If you already know you want a skill to proceed past one of those for this whole project, I can record that here. Most people skip this."

  Why this matters: policy and scope guards are defaults the author can override ([[author-authority]]). An entry here lets the named skills proceed without asking; they still state the concern each run and list the guard under "Overrides applied". Accuracy guards, such as never inventing a citation, cannot be overridden. How to answer: skip unless you have a specific guard in mind; you can add one later, when a skill names it.

  Never propose or pre-fill entries. Record only a guard the author names, with the skills it applies to ("*" for every skill that declares it) and an optional note. Guard ids are listed under guards: in each skill's manifest.yaml; scriptorium validate rejects unknown ids, accuracy guards, and skills that don't declare the guard.

If the file already has values for any of these, show them first and ask whether to update, add to, or leave alone.

6. Confirm

When the author is done elicitating (or has chosen to skip the rest):

• Show the full proposed YAML content as a diff against the existing file (or against the blank template if the file is new).
• Validate the proposed content against the schema — with scriptorium validate when the CLI is on PATH, in-conversation otherwise (constraint 3). If validation fails, surface the specific errors and propose fixes conversationally — "the schema expects target_type to be one of manuscript / grant / review / preprint / book-chapter / thesis / white-paper / other; I had clinical-study. Switch to manuscript?"

7. Write

Only on explicit author confirmation. Preserve template comments for fields left empty so the author can fill them in later without guessing the schema.

If MANUSCRIPT_STATE.yaml does not exist yet, prefer running the CLI to scaffold the blank first, then merge the elicited values in:

scriptorium init <manuscript-dir>

If the CLI is not on PATH, write the file directly.

8. Suggest next steps

Based on document_phase.current, suggest sensible follow-up skills:

• outline / draft — "The leaf skills don't yet help much at this phase. Come back once you have full draft sections."
• review / revision — "Run citation-audit to check existing references; run reviewer-simulation for a pressure test before you circulate."
• submission — "Before submission, an argumentative-flow pass on the discussion section often catches structural issues a final reader will notice."

Independently of phase, if both project.target_venue and project.candidate_venues are empty, also suggest:

"Venue is undecided in your state file. When the draft is substantive enough to assess fit (typically once the introduction and abstract are written), run /scriptorium:venue-fit to tier candidate venues."

If project.target_venue is set, optionally suggest /scriptorium:desk-rejection-risk as the next step once the draft is at submission phase.

If meta.guidance_level is full, also offer:

"If you'd like a tour of any skill before you run it, try /scriptorium:explain <skill> — it summarises what the skill does, what it consumes from MANUSCRIPT_STATE.yaml, and what it produces."

These are suggestions, not auto-invocations. The author chooses.

Output format

This skill produces a conversation, not a markdown report. The only file written is MANUSCRIPT_STATE.yaml. When the conversation ends, emit a short summary message to the author:

Wrote MANUSCRIPT_STATE.yaml. Validated against the schema (X fields
populated, Y left for later). Next: <suggested skill> when you're ready.

What "good output" looks like

• The session opens with orientation, not the first question. The author should always know what they're walking into before they walk into it.
• Guidance level is set before any other elicited field. The author's pick controls every later skill's tone; setting it first means the user has chosen the contract for the rest of the conversation, including this one's elicit phase.
• Inferred fields appear as confirmable proposals, not silent decisions. The author always sees "here's what I think; OK?"
• Subjective fields are elicited one or two at a time, never as a single intimidating questionnaire. Each elicited field carries a short "why this matters" preface — that's how the full level lets the author learn the workflow as they go.
• Existing values are respected. If a field already has content, the skill shows it before asking.
• Validation errors become conversational prompts, never raw jsonschema error dumps.
• The author can stop at any point with a valid file.
• The next-step suggestion is keyed to document_phase.current — early phases get "come back later"; mature phases get specific skill suggestions.

What you must not do

• Invent fields not in the schema.
• Silently overwrite existing values.
• Write the file before the author confirms.
• Propose or pre-fill meta.overrides entries. Record only guards the author names.
• Validate after writing (validation must precede the write so the author never receives a broken file).
• Ask a wall of questions. The conversation should feel like a collaborator helping the author think, not a survey form.
• Auto-invoke the v0.1 leaf skills (citation-audit, reviewer-simulation, argumentative-flow) when the conversation ends. Suggest only; the author invokes.

Grounding

This skill is grounded in:

• schemas/manuscript-state.schema.json — the canonical field set and enum values the elicitation steers toward. Read at runtime so the skill stays in sync with schema evolution.
• [[guidance-level]] — the three-level convention init both introduces to the author and writes to meta.guidance_level. Init itself always runs at full; the level it sets controls every later skill.
• [[author-authority]] — the guard kinds and the meta.overrides entry init offers, opt-in and never pre-filled. Init's orientation calls the declared-work boundary a default for the same reason.
• [[common-critiques-taxonomy]] — informs why certain fields matter for downstream skills. known_weaknesses, target_venue, and core_claims are the load-bearing inputs for reviewer-simulation; capturing them well here makes that skill's output much sharper.

This skill does not need deep evidence-base grounding — it is a utility for getting an author to a state where the evidence-grounded skills can run.