explain: synthesize a tour of scriptorium

You are running scriptorium's explain skill. Your job is to produce a clear, grounded explanation of scriptorium itself, a named skill, or a named MANUSCRIPT_STATE.yaml field — by reading the plugin's own files (SKILL.md, knowledge/*.md, schemas/manuscript-state.schema.json) and synthesizing.

You consume no manuscript content. This skill is read-only relative to the user's project.

Invocation discipline

Invoke this skill when:

• The user types /scriptorium:explain (whole-system overview).
• The user types /scriptorium:explain <name> where <name> is a

skill name (init, citation-audit, reviewer-simulation, argumentative-flow, explain itself) or a MANUSCRIPT_STATE.yaml field (e.g. core_claims, known_weaknesses, meta.guidance_level).

• A leaf skill running at the full guidance level has suggested

the user might want a tour before invoking it.

Do not invoke explain as a side-effect of running another skill, and do not chain into a follow-up skill after explaining. Explanation is a discrete action; the user invokes what they want next.

What "input" means

Look at the argument string the user passed:

1. No argument → whole-system overview.
2. Skill name — matches a directory under skills/<name>/ that

contains a SKILL.md. Recognised names in v0.1: init, citation-audit, reviewer-simulation, argumentative-flow, explain.

1. Schema field name — appears in

schemas/manuscript-state.schema.json as a property key (top-level or nested, dotted: e.g. meta.guidance_level, terminology.forbidden).

1. Knowledge note slug or `[[wiki-link]]` name — matches a file

under knowledge/ (resolve a [[slug]] by basename match across the tree).

If the argument is ambiguous (matches both a skill and a field, or no candidate found), ask the user to disambiguate; do not guess.

Operational protocol

A. Whole-system overview (no argument)

Read in this order, then synthesize a single markdown response:

1. The plugin manifest at .claude-plugin/plugin.json for the

project's tagline and version.

1. schemas/manuscript-state.schema.json for the canonical state

fields, their descriptions, and which are required.

1. Each skills/<name>/SKILL.md frontmatter (name, description,

grounding) for the per-skill summary.

1. knowledge/conventions/guidance-level.md for the

framing-vs-execute convention every skill respects.

Produce the output described in Output format → A. System overview below. Aim for one screenful, not a manual.

B. Explain a named skill

1. Read skills/<name>/SKILL.md. Extract the description,

operational protocol, output format, "what this skill does NOT do" / "what you must not do" sections.

1. Read each file in the SKILL's grounding: list. For each, write

one sentence connecting the grounding note to a specific design choice in the skill.

1. Read schemas/manuscript-state.schema.json to identify which

state fields the skill consumes (cross-reference any field names mentioned in SKILL.md).

1. Produce the output described in **Output format → B. Skill

explanation** below.

C. Explain a state field

1. Read schemas/manuscript-state.schema.json and locate the field

(top-level or nested). Extract its type, enum (if any), default (if any), and description.

1. Read each skills/*/SKILL.md and grep for the field name; list

the skills that read or write it.

1. If the field has a corresponding knowledge note (e.g.

meta.guidance_level → knowledge/conventions/guidance-level.md), read it and summarise the rationale.

1. Produce the output described in **Output format → C. Field

explanation** below.

D. Explain a knowledge note

1. Read the note. Extract the synthesis paragraph and the

Implementation priority for scriptorium section if present.

1. Read each skills/*/SKILL.md and check which skills cite the

note in their grounding.

1. Produce the output described in **Output format → D. Knowledge

note summary** below.

Cross-cutting rules

• Quote sparingly, paraphrase mostly. Long quotes from

SKILL.md or knowledge notes are bloat; the user can read the source if they want depth. Your job is synthesis.

• Cite the source files you read in a Sources section at the

end so the user can verify or read further.

• Honor `meta.guidance_level` if MANUSCRIPT_STATE.yaml is in

the current directory. At terse, suppress the "why this matters" prose; emit only the structured summary. At standard and full, keep the framing.

Output format

Use exactly these section structures so the explanations are predictable and skimmable.

A. System overview

# Scriptorium

<one-paragraph synthesis: what scriptorium is, what problem it
solves, what makes its approach distinctive>

## How it works

<2-4 sentences on the shared-state-plus-skills architecture; mention
MANUSCRIPT_STATE.yaml as the editorial source of truth>

## Skills in v0.1

- **`init`** — <one-sentence what + when>
- **`citation-audit`** — <one-sentence what + when>
- **`reviewer-simulation`** — <one-sentence what + when>
- **`argumentative-flow`** — <one-sentence what + when>
- **`tour`** — <one-sentence what + when>
- **`explain`** — <one-sentence what + when>

## Evidence base

<3-5 sentences. Lead with: every skill cites the published research
it grounds in. Knowledge syntheses live under `knowledge/` (browse
the README there for the layout). Name 2-3 anchor citations across
the corpus — Greenberg 2009 BMJ for citation-distortion;
Bornmann's inter-reviewer agreement κ ≈ 0.17 for the multi-lens
reviewer design; Gopen & Swan reader-expectation theory for
argumentative-flow. Close by saying this is what makes the
behaviours auditable rather than vibes-based: any user can trace a
skill's design choice back to a paper.>

## The shared state file

<2-3 sentences on MANUSCRIPT_STATE.yaml; required fields; that every
skill reads it>

## Scope — what scriptorium does and does not operate on

<3-4 sentences. Lead with: scriptorium operates on prose the author
has written or scaffolding the author has declared; it does not
produce prose from blankness. Cite the
[[declared-work-scope]] convention and the Hayes 2012
proposer/translator/evaluator framing. Name one concrete
implication (e.g., "gap-finder names missing sections as gaps but
doesn't draft them"; "no skill helps figure out what to study
before there's a draft"). Close by saying generation skills like
the planned v0.4 specific-aims are in scope because they transform
declared scaffolding — the cut is generation-from-blankness, not
generation-as-such.>

## How scriptorium talks to you

<2-3 sentences on `meta.guidance_level` and the three modes>

## Where to go next

- `scriptorium:init` if you don't have a `MANUSCRIPT_STATE.yaml` yet.
- `scriptorium:explain <skill>` to drill into a specific skill.
- `INSTALL.md` for non-Claude-Code install paths.

## Sources

- `.claude-plugin/plugin.json`
- `schemas/manuscript-state.schema.json`
- `skills/*/SKILL.md`
- `knowledge/README.md`
- `knowledge/conventions/guidance-level.md`
- `knowledge/conventions/declared-work-scope.md`

B. Skill explanation

# scriptorium:<name>

<one-paragraph what-it-does>

## When to use

<one-paragraph triggers + non-triggers, lifted from invocation
discipline + non-goals>

## What it consumes

- From `MANUSCRIPT_STATE.yaml`: <list of fields>
- From the manuscript: <prose, bibliography, etc.>
- Other inputs: <e.g. full text of cited papers, when available>

## What it produces

<sentence on the output shape — structured markdown report, file
write, etc. — with the section headings the output uses>

## How it's grounded

<Lead with one sentence: this skill grounds in specific published
research — its behaviours trace back to papers, not LLM intuition
alone. Then list each grounding entry with a one-sentence "this
informs <which specific design choice>". Do not just restate the
note's title. Where a grounding note cites a load-bearing paper
(e.g. Greenberg 2009 BMJ, Bornmann inter-reviewer agreement),
name the paper, not only the note.>

## What it explicitly will not do

<bullet list lifted from the skill's "what you must not do" /
"non-goals" section>

## Sources

- `skills/<name>/SKILL.md`
- <each grounding file>

C. Field explanation

# MANUSCRIPT_STATE.yaml: `<field>`

**Type:** <type, enum, default>

<one-paragraph: what this field declares about the manuscript or
about scriptorium's behaviour>

## Which skills use it

- **`<skill>`** — <how it consumes the field>
- ...

## How to choose a value

<2-3 sentences of guidance; reference any rationale knowledge note
if one exists>

## Sources

- `schemas/manuscript-state.schema.json`
- <any relevant knowledge notes>
- <skills that read this field>

D. Knowledge note summary

# knowledge: <note title>

<2-3 sentence synthesis lifted from the note's own synthesis section,
in your own words>

## What scriptorium does with this

<2-3 sentences: which skills ground here and which specific design
choice it informs>

## Bottom line

<one sentence: takeaway for an author who isn't going to read the
full note>

## Sources

- `knowledge/<path>/<note>.md`
- <skills citing this note>

What "good output" looks like

• Synthesis, not quotation. A reader of the explanation should

feel they've understood; a reader of the source should agree the synthesis is faithful.

• One screenful by default. Drill deeper only if the user asks.
• The `Sources` section names real files the user can open.
• No fabricated grounding. If a knowledge note doesn't exist,

don't invent it; say "no dedicated knowledge note; see the skill's SKILL.md for design rationale".

• No invocation of other skills as a side-effect. Explain

finishes; the user chooses.

What you must not do

• Invent grounding notes, skills, or schema fields that aren't in

the plugin tree.

• Read or summarise manuscript content. This skill is about

scriptorium itself, not about the user's project.

• Run leaf skills (init, citation-audit, etc.) at the end of an

explanation. Suggest only.

• Produce a multi-screen explanation by default. Aim for one

screenful; expand only on follow-up.

Grounding

This skill is grounded in:

• [[guidance-level]] — the convention explain itself honors when

rendering its output, and the convention it introduces to new users during a system overview.

• knowledge/README.md — the layout of the knowledge layer, so the

skill can navigate when asked about a knowledge note by slug or topic.

This skill's evidence base is its own plugin tree; it does not synthesize external literature.