Install

npx skills add Tradelord223/plain-english -g

The installer finds the plain-english skill and lets you choose the agents that should use it. The skill is Markdown: no runtime, API key, account, or telemetry.

Then ask your agent:

Explain what changed in plain English. Keep the exact file names and validation results.

Prefer a manual install? Use the guide for Cursor, Claude Code, Codex, or Grok Build.

See the difference

Without Plain English

In auth.ts, the authentication middleware implementation now facilitates the rejection of expired JWTs prior to downstream request handling.

With Plain English

auth.ts now rejects expired JWTs before the app handles the request.

Same fact. Fewer obstacles.

The skill also changes the explanation for the reader without changing the underlying behavior:

Reader Explanation
Backend engineer The endpoint is idempotent: the idempotency key returns the first payment response instead of creating a second charge.
Store owner Retrying with the same request key returns the first result instead of charging the customer twice.

Why this is different

Most “plain language” prompts are word-swap lists. That is dangerous in technical work because the easy synonym is often wrong.

Blind replacement What Plain English does instead
serialize → “turn into JSON” Names JSON only when the format is known to be JSON
deploy → “put live” Names the real target: local, staging, or production
idempotent → “safe to run twice” Explains the actual retry and duplicate-effect guarantee
should → must Preserves whether something is advice or a requirement
“likely cause” → “cause” Keeps uncertainty when the evidence is incomplete

Plain English simplifies the explanation, not the evidence.

What it improves

  • Change summaries that lead with the user-visible result
  • Status updates that separate done, in progress, and blocked
  • Error reports that distinguish a confirmed cause from a likely one
  • Handoffs that keep exact files, commands, decisions, and open work
  • How/why answers that match the reader's technical background
  • Walkthroughs with clear actions, checkpoints, and recovery steps

It does not rewrite code, commands, raw logs, or load-bearing technical specifications. It does not invent facts, hide failed checks, or remove caveats to make an answer shorter.

How it works

Before sending a user-facing answer, the skill makes the agent:

  1. Infer whether the reader is expert, mixed, nontechnical, or unknown.
  2. Preserve facts, certainty, obligations, conditions, scope, and exact names.
  3. Explain the behavior instead of applying a jargon dictionary.
  4. Lead with the outcome, answer, or blocker.
  5. Cut anything that does not help the reader understand, act, or verify.

The canonical instructions live in skills/plain-english/SKILL.md.

Built to stay honest

  • One source of truth: platform copies are generated from one canonical skill.
  • Cross-platform drift checks: CI verifies Cursor, Claude Code, Codex, and Grok stay synchronized.
  • Behavior contract: ten adversarial cases cover uncertainty, must-versus-should, staging-versus-live, unknown formats, exact errors, expert terminology, and incomplete validation.
  • Open source: MIT licensed, with no service dependency.

Read the behavior cases, changelog, or v1.2.0 release notes.

Supported agents

Agent Skill path
Cursor skills/plain-english/
Claude Code .claude/skills/plain-english/
OpenAI Codex .agents/skills/plain-english/
Grok Build .grok/skills/plain-english/

The open Agent Skills installer can install the canonical skill into supported hosts. Platform copies remain in the repository for native and manual installs.

Help more people find it

If Plain English makes one handoff, error report, or code explanation easier to use, star the repository. Stars help other builders find useful open Agent Skills.

Issues and focused pull requests are welcome. See CONTRIBUTING.md before changing the skill contract or platform copies.

License

MIT © 2026 Raqz