Install

Add the marketplace: /plugin marketplace add gagoar/gago-plugins
Install greenhorn: /plugin install greenhorn@gago-plugins. The helper plugins unmistakable and iceberg install with it, because plugin.json declares them as dependencies. If one is missing, the skill stops and prints the command to install it.
Run it on a file: /greenhorn:explain path/to/text.md

The two commands

/greenhorn:explain rewrites a text for a reader who is new to the system. It takes a file path or pasted text. It never changes your file. It writes the draft to .greenhorn/draft.md in your working directory.

/greenhorn:test only finds the places where such a reader would stop. It rewrites nothing.

Both take --profile smart-outsider, --profile adjacent-engineer or --profile new-hire.

What explain does, in order

Dependency check. Stop when asd-ste100 or iceberg:edit is missing.
Input and profile. Get the text and pick who the reader is.
Stumble pass. The greenhorn-reader agent gets the text and the profile. It has no tools and no repository access. It lists each stumble with a question. It writes one sentence for what it thinks the text says.
Ground pass. Claude answers each stumble from the code, the linked issue or the docs. An answer with no source goes to an unsure list and becomes a question for you.
Rewrite. One-sentence gist, one concrete example with real values, then the mechanism. The rewrite defines each term at first use as "X is a Y that does Z". An analogy appears only with a stated limit.
Check. scripts/check-text.ts runs.
Polish. The asd-ste100 skill, then iceberg:edit --no-em-dash.
Lint loop. At most 3 rounds. Explain never weakens the text to pass.
Report. The final text, the stumbles, the unsure list and the warnings that remain.

If the stumble pass finds nothing and the gist matches your intent, explain prints the text unchanged. A text that already reads well gets worse when you add scaffolding.

Reader profiles

A profile says who is reading. There are three.

Profile	Who it is
`smart-outsider`	A sharp reader from another field. Does not know the domain and does not read code.
`adjacent-engineer`	An engineer who writes code but is new to this product. This is the default.
`new-hire`	A person who knows the company and its customers but has not met this system yet.

Each profile has a knows list and a doesNotKnow list. The reader agent uses both.

The config file

Copy greenhorn.config.example.json to greenhorn.config.json in your working directory. The schema is schema/greenhorn.schema.json. The file sets the default profile and the limits.

Limit	Default
`maxTerms`	5
`glossaryThreshold`	3
`maxDefinitionWords`	25
`requireExample`	true
`analogyNeedsLimit`	true

These numbers are untested defaults. They are guesses until the human eval says otherwise.

The checks

node scripts/check-text.ts [--json] [--config PATH] [--profile NAME] [--disable id,id] [--] [FILE...]

If you give no file, it reads stdin. Exit 0 means no hard failure. Exit 1 means a hard failure. Exit 2 means a usage error.

Check	Level	What it finds
`circular-definition`	hard	A definition that uses its own term, or a term that the text defines later
`no-example`	hard	No closed code block with text in it, no "Example" line with content and no Before and After pair of labels
`unclosed-fence`	warn	A code fence that never closes
`term-before-definition`	warn	A term used before the line that defines it
`undefined-repeated-term`	warn	A code-font name or an all-capitals acronym used 3 or more times and never defined. It skips paths, file names, flags, calls, assignments and universal terms such as PR, API and README. It gives false alarms
`too-many-terms`	warn	More defined terms than the limit
`long-definition`	warn	A definition longer than the limit
`analogy-without-limit`	warn	"like a" or "think of ... as" with no "unlike", "differs from", "breaks down", "the difference is" or "but ... not" in the next two sentences

A hard check fails the run. A warn check only reports. Each warn check can be wrong.

Local use, no CI

greenhorn runs on your machine, inside your Claude Code session. The scripts use only Node built-in modules. Node 22.18 or later runs them unchanged. There is no build step and no network call. The plugin collects no data.

You can run the checker alone, by hand, on any Markdown file. It needs no CI.

FAQ

Does it prove my text is clear?
No. The reader is a model. It finds likely stumbles. A real newcomer is the final test.

Will it invent a definition when it does not know one?
No. A term that the code, the issue or the docs do not support goes to the unsure list. You get the question.

Why does it want an example in every text?
The checker fails a text with no example. The method puts one real example before the mechanism. This is a hypothesis, not a proven rule.

Why only 5 terms?
It is a default, not a finding. Change maxTerms in your config.

Where does my text go?
It goes to the Claude model in your session, like any prompt. The reader agent gets only the text and the profile.

Can I use my own style flags?
The polish step uses --no-em-dash and no other flag.

Where do I report a bug?
Open an issue on GitHub.