explain · git:20261020.c0b2662 · 2026-10-20 · sha256 e9b1c913c1e72e9d
explain git:20261020.c0b2662A
Immutable. This exact content never changes and is served at /api/v1/blob/e9b1c913c1e72e9d.
--- 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/../..`). A Claude Code plugin install and a repo checkout have the whole tree. 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` and `knowledge/conventions/declared-work-scope.md`. 3. **GitHub `main`** — for other `knowledge/` notes and other skills' `SKILL.md`, fetch `https://raw.githubusercontent.com/seandavi/scriptorium/main/<path>`. Without a local `skills/` tree, take the list of skill names from the lifecycle table 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. `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.