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 where `` 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// 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.

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

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

## How it works

## Skills in v0.1

- **`init`** — 
- **`citation-audit`** — 
- **`reviewer-simulation`** — 
- **`argumentative-flow`** — 
- **`tour`** — 
- **`explain`** — 

## Evidence base

## The shared state file

## Scope — what scriptorium does and does not operate on

## How scriptorium talks to you

## Where to go next

- `scriptorium:init` if you don't have a `MANUSCRIPT_STATE.yaml` yet.
- `scriptorium:explain ` 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

# scriptorium:

## When to use

## What it consumes

- From `MANUSCRIPT_STATE.yaml`: 
- From the manuscript: 
- Other inputs: 

## What it produces

## How it's grounded

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

## Sources

- `skills//SKILL.md`
- 

C. Field explanation

# MANUSCRIPT_STATE.yaml: ``

**Type:** 

## Which skills use it

- **``** — 
- ...

## How to choose a value

## Sources

- `schemas/manuscript-state.schema.json`
- 
- 

D. Knowledge note summary

# knowledge: 

## What scriptorium does with this

## Bottom line

## Sources

- `knowledge//.md`
- 

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.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: seandavi
• Source: seandavi/scriptorium
• License: MIT
• Homepage: https://seandavi.github.io/scriptorium/

Install and usage instructions live in the source repository linked above.