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.
3. 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).
4. 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.

Locating scriptorium files

Every path this skill reads (.claude-plugin/plugin.json, schemas/..., skills/<name>/SKILL.md, knowledge/...) is relative to the scriptorium root. Resolve each one in this order and use the first that exists:

1. The scriptorium install — two levels above this skill's directory (skills/explain/../..), but only if .claude-plugin/plugin.json exists there. A Claude Code plugin install and a repo checkout have the whole tree. An npx skills install sits in an agent directory such as .claude/skills/ or .agents/skills/; that skills/ holds the user's skills, not scriptorium's, so skip this step.
2. The bundled copy — assets/<path> inside this skill's directory. A standalone npx skills add install carries .claude-plugin/plugin.json, schemas/manuscript-state.schema.json, knowledge/README.md, knowledge/conventions/guidance-level.md, knowledge/conventions/declared-work-scope.md and knowledge/conventions/author-authority.md.
3. GitHub main — for other knowledge/ notes and other skills' SKILL.md, fetch https://raw.githubusercontent.com/seandavi/scriptorium/main/<path>. Without a scriptorium install, take the list of skill names from the "What ships today" list in README.md fetched the same way.

Say which source you used: in the Sources section, mark each file not read from the scriptorium install with (bundled copy) or (GitHub main). If a file is in none of the three (for example, no network), say so; do not reconstruct it from memory.

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.
2. schemas/manuscript-state.schema.json for the canonical state fields, their descriptions, and which are required.
3. Each skills/<name>/SKILL.md frontmatter (name, description, grounding) for the per-skill summary.
4. knowledge/conventions/guidance-level.md for the framing-vs-execute convention every skill respects.
5. knowledge/conventions/declared-work-scope.md and knowledge/conventions/author-authority.md for the scope default and how the author overrides it.

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.
2. 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.
3. Read schemas/manuscript-state.schema.json to identify which state fields the skill consumes (cross-reference any field names mentioned in SKILL.md).
4. 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.
2. Read each skills/*/SKILL.md and grep for the field name; list the skills that read or write it.
3. If the field has a corresponding knowledge note (e.g. meta.guidance_level → knowledge/conventions/guidance-level.md, meta.overrides → knowledge/conventions/author-authority.md), read it and summarise the rationale.
4. 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.
2. Read each skills/*/SKILL.md and check which skills cite the note in their grounding.
3. 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

<4-5 sentences. Lead with: by default, 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"). Say 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. Close with the [[author-authority]]
convention: the cut is a default, not a rule. The author can
override a policy or scope guard for one run or for the project
(`meta.overrides`); accuracy guards, such as never inventing a
citation, stay fixed.>

## 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`
- `knowledge/conventions/author-authority.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.
• [[author-authority]] — the guard kinds and meta.overrides, so the overview presents the scope cut as the author's overridable default and keeps accuracy guards fixed.
• 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.