explain
/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
- Author
- seandavi ↗
- Repository
- scriptorium ↗
- Licence
- MIT
- Last repository change
- 20.10.2026
Assessment and security
- Files in this package
- 10
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 1
No signals detected. Repository changed on 20.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
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
Original author 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
How it works
- Invocation discipline
- What "input" means
- Locating scriptorium files
- Operational protocol
- Output format
- What "good output" looks like
- What you must not do
- Grounding
SKILL.md preview
--- 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/conventions/author-authority.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`, `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 ```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 <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 ```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. - [[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.
Files in this package (10)
- README.md 1 KB
- SKILL.md 14 KB
- manifest.yaml 3 KB
- prompt.md 5 KB
- assets/.claude-plugin/plugin.json 1 KB
- assets/knowledge/README.md 9 KB
- assets/knowledge/conventions/author-authority.md 11 KB
- assets/knowledge/conventions/declared-work-scope.md 13 KB
- assets/knowledge/conventions/guidance-level.md 8 KB
- assets/schemas/manuscript-state.schema.json 9 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · seandavi/scriptorium | 100 | MIT |
| crbnos/carbon | 100 | AGPL-3.0 |
| PerilloAI/flowtrace-plugin | 100 | Apache-2.0 |
| mickeyyaya/evolve-loop | 100 | Apache-2.0 |
| zenobi-us/dotfiles | 100 | MIT |
| imgly/agent-skills | 100 | MIT |
| marcel-bich/marcel-bich-claude-marketplace | 100 | MIT |
| nicodiansk/draw-it-out | 100 | MIT |
| ramboz/jig | 100 | MIT |
Database snapshot: 13.11.2026 · package version 0faf543cef65 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100tour
Conversational onboarding for new users. Three or four turns. Greets, asks what the user is working on (manuscript, grant, review, or exploring), walks through the relevant subset of scriptorium, shows an example MANUSCRIPT_STATE.yaml, and ends with a concrete next move (usually… - 100init
Conversationally bootstrap MANUSCRIPT_STATE.yaml for a new or existing manuscript directory. Infers what it can from the filesystem (title, sections, bibliography paths) and asks the author about the subjective fields (core_claims, known_weaknesses, terminology, audience).…