seandavi/scriptorium/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.

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.

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.

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

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

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.

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

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, meta.overrides → knowledge/conventions/author-authority.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
 
<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