# Explain

> Explain scriptorium itself, a named skill, or a named MANUSCRIPT_STATE field. With no argument, gives a whole-system overview (what scriptorium is, what each skill does, how the shared state ties them together). With an argument, drills into that skill or field — what it does, what it consumes, what it produces, and the grounding notes behind its design. Reads SKILL.md frontmatter and the referenced grounding files; no manuscript content is consumed. Use when the user wants to understand scriptorium before invoking it, or when a leaf skill has prompted them with "want a tour of <skill> before you run it?"

- Skill: `seandavi/explain` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add seandavi/explain`
- Raw SKILL.md: https://api.skillmd.com/api/skills/seandavi/explain/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: seandavi (https://skillmd.com/u/seandavi)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/seandavi/explain

---


# 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.

## 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.

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`),
   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

```markdown
# 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

```markdown
# 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

```markdown
# 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

```markdown
# 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.