git:20261020.0cd50db to git:20261020.3814215

---

name: explain

description: 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?"

grounding:

- knowledge/conventions/guidance-level.md

- knowledge/conventions/declared-work-scope.md

- knowledge/README.md

---

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

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.

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.

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

[[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

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