matcha

                             ) )
                            ( (
                         .---------.
                         |         |\     █▀▄▀█ ▄▀▀▄ ▀▀█▀▀ ▄▀▀▀ █  █ ▄▀▀▄ 
                         |         | |    █ ▀ █ █▄▄█   █   █    █▀▀█ █▄▄█
                         |         | |    ▀   ▀ ▀  ▀   ▀   ▀▀▀▀ ▀  ▀ ▀  ▀
                         |         |/
                          \_______/              抹 茶

For when you don't follow what Claude just told you about your own PR.

A Claude Code skill that adapts how Claude writes for you: the level of English, the domain knowledge it assumes, and the amount of professional jargon — never the facts.

Install

Claude Code — from the CLI (or in a session, drop claude and use /plugin …):

claude plugin marketplace add jaysonmulwa/matcha
claude plugin install matcha@matcha

Adds /matcha:matcha. A SessionStart hook applies your level each session; /plugin update keeps it current.

Or copy it by hand — commands stay bare /matcha, and you update it yourself:

git clone https://github.com/jaysonmulwa/matcha
cp -r matcha/skills/matcha ~/.claude/skills/

Codex, Cursor, Windsurf, Cline, Kiro, Gemini, OpenCode

These get matcha's request-driven half only — the grid, the five levels, the fidelity rules. The persistent level (set) is Claude-Code-only; here you name the level per request. Rules are one shared body (AGENTS.md canonical, vendor files mirror it).

Codex — from the CLI:

codex plugin marketplace add jaysonmulwa/matcha
codex plugin add matcha@matcha

Others — copy the file your tool reads into your project:

Tool	File
Cursor	.cursor/rules/matcha.mdc
Windsurf	.windsurf/rules/matcha.md
Cline	.clinerules/matcha.md
Kiro	.kiro/steering/matcha.md
Gemini CLI · OpenCode	AGENTS.md

Use

/matcha set plain          # any of the five levels — persists across sessions
/matcha rewrite familiar   # one-shot, config untouched
/matcha status             # check what's configured
/matcha set off            # remove everything it wrote

(Prefix with matcha: if you installed the plugin — /matcha:matcha set plain.)

Inert until you set a level. set writes two files: ~/.claude/matcha.md and a marker-delimited block in ~/.claude/CLAUDE.md. Nothing outside the markers is touched, and set off removes both.

No level needed for one-shots — just ask: "simplify this", "rewrite for my exec".

The five levels

Level	English	Domain framing
basic	≤14 words/sentence, ~1,000 common words	mechanisms explained, every term glossed
plain	≤20 words/sentence, everyday vocabulary	mechanisms explained, obscure terms glossed
full	uncapped	mechanisms explained, terms glossed
familiar	uncapped	mechanism in one clause
expert	uncapped	terms used directly, internals shown, terse, no analogies

Your default sits around familiar.

The grid

The grid is the idea the whole skill rests on. Two knobs, independent of each other:

• linguistic — can the reader parse the English?
• conceptual — do they know the domain?

Across, conceptual difficulty rises. Down, linguistic difficulty rises. The five levels are an L-shaped path through the grid — ①②③ raise the English, ③④⑤ drop the hand-holding.

	novice	familiar	expert
basic	① basic	·	·
plain	② plain	·	·
full	③ full →	④ familiar →	⑤ expert

The · cells are real, just off the ladder: low English, high domain knowledge — an L2 engineer who wants short sentences and no hand-holding. Ask for them in words: "short sentences, but assume I know Kubernetes."

One statement, all nine cells

The grid below renders the same PR summary in every cell — across, the reader is assumed to know more; down, the English gets harder.

A Redis cache on /auth/token, TTL 5 minutes, DB fallback on miss, invalidated on password change, intended to cut DB load and latency (not measured).

	novice	familiar	expert
basic	"Logins should get faster. The app now saves recent login checks for a short time, so it does not repeat slow work. If you change your password, the saved check is cleared."	"We added a cache (a fast, short-term memory store) for login checks. Repeat logins can skip the database for up to 5 minutes. A password change clears the cached entry."	"Added Redis cache on /auth/token. TTL 5 min. DB path kept as fallback on miss. Invalidation on password change. Goal: lower DB load and login latency."
plain	"Login speed should improve. The system now keeps recent login results on hand for a few minutes instead of recomputing them each time. Changing your password clears the stored result, so old credentials can't be reused."	"Auth responses are now cached in Redis for 5 minutes, so repeated logins skip the database lookup. Cache entries are invalidated on password change, and the database path remains as fallback."	"Redis cache added on /auth/token, 5-min TTL, DB fallback on miss, invalidation on password change. Motivation: DB load and p-latency reduction — intended, not yet measured."
full	"Login latency should drop: the endpoint now retains recent verification results for five minutes rather than recomputing them on every request. A password change immediately clears the retained result, so revoked credentials cannot ride on a stale entry."	"The auth endpoint now employs a Redis-backed cache (5-minute TTL) that eliminates redundant database round-trips for repeat authentications; entries are invalidated on password change and the database path is preserved as fallback."	"Introduced a Redis cache on /auth/token: 5-min TTL, database fallback on miss, invalidation on credential change. Expected effect is reduced DB load and login latency; no benchmark accompanies the PR."

Walking one concept down the ladder

The grid above shows every cell at once. This shows the exact commands — start strict, then get easier. Explaining Byzantine fault tolerance: keeps a system correct when some parts fail or lie · needs more than two-thirds of parts honest (the 3f+1 rule) · used in blockchains and flight control.

/matcha set expert

BFT: consensus under arbitrary node behavior, not just crash-stop. Safety holds for f faulty of n ≥ 3f+1 (the PBFT bound). Contrast Raft/Paxos, which assume n ≥ 2f+1 and no lying.

/matcha rewrite plain

Byzantine fault tolerance lets a distributed system agree even when some nodes fail arbitrarily — crashing, or sending conflicting information. It tolerates up to f bad nodes given at least 3f+1 total, i.e. over two-thirds honest.

/matcha rewrite basic

Byzantine fault tolerance keeps a system working when some parts fail or lie. Think of generals who must agree while some send false orders. (That's an analogy, not the real thing.) The honest parts still reach one decision — as long as more than two-thirds stay honest.

Couldn't simplify: the exact rule n ≥ 3f+1 and the names PBFT / Raft / Paxos — kept as-is rather than rounded into something false.

The analogy shows up only at basic and is flagged; n ≥ 3f+1 survives as a formula until basic, where it's named as held-back rather than faked into "most parts" (which would be wrong — the bound is two-thirds, not half).

Related literature

Loose inspirations, not conformance claims — each taken narrower than the source. Full notes in the PRD appendix.

Source	What we took
CEFR	The band structure, and the scale L2 readers already know themselves by. Levels are "CEFR-informed", never CEFR-conformant.
NGSL · Oxford 3000	Word-frequency lists as the vocabulary mechanism — inverted: they target acquisition (stretch the learner); we target comprehension (stay in range).
Flesch-Kincaid	A two-variable readability proxy. An instrument and a disagreement-detector, never ground truth.
Coh-Metrix	The negative result: deleting connectives ("because", "so") improves FK while lowering comprehension. Shorten sentences; never strip connectives.
Dreyfus	Expertise changes which objects exist for the reader — a novice sees steps, an expert sees "a rollback". Lineage, not authority.
Expertise reversal (Sweller / Kalyuga)	Unsolicited scaffolding measurably harms readers who already hold the schema. Hence no unsolicited analogies at expert.
GOV.UK style guide · ISO 24495-1	The register model: complex content in plain language that never infantilizes. Simple English is not childish English.

---

docs/design.md — how it's built, what it can't do. skills/matcha/SKILL.md is the canonical source; an installed copy under ~/.claude/skills/ is a deployment of it.