Agent-Skills.md

Agent Skills: Explanatory Writing

Apply explanatory craft so that Explanation-quadrant prose reads clearly — one controlling metaphor, a concrete example beside every abstract claim, self-answered question pivots, short declaratives, coin-and-explain, a confident grounded close. Use when writing or improving an explainer, a blog-style or internal explanation, or broad-audience teaching prose (Diátaxis Explanation; not Reference or How-to). Trigger on "make this explainer clearer", "why does this read flat", "write a blog-style explanation", "add a worked example or metaphor", "tighten the rhythm of this prose". Executes the Meaningfy technical/educational register from `company-voice.md`. Owns texture, not document structure (`executive-communication`) or doc placement (`technical-writing`).

ai-codingID: meaningfy-ws/agent-skills/explanatory-writing

Repository

meaningfy-ws/agent-skills
meaningfy-wsLicense: GPL-3.0
21

Install this agent skill to your local

pnpm dlx add-skill https://github.com/meaningfy-ws/skillery/tree/HEAD/.opencode/skills/explanatory-writing

Skill Files

Browse the full folder contents for explanatory-writing.

Download Skill

Loading file tree…

.opencode/skills/explanatory-writing/SKILL.md

Skill Metadata

Name
explanatory-writing
Description
Apply explanatory craft so that Explanation-quadrant prose reads clearly — one controlling metaphor, a concrete example beside every abstract claim, self-answered question pivots, short declaratives, coin-and-explain, a confident grounded close. Use when writing or improving an explainer, a blog-style or internal explanation, or broad-audience teaching prose (Diátaxis Explanation; not Reference or How-to). Trigger on "make this explainer clearer", "why does this read flat", "write a blog-style explanation", "add a worked example or metaphor", "tighten the rhythm of this prose". Executes the Meaningfy technical/educational register from `company-voice.md`. Owns texture, not document structure (`executive-communication`) or doc placement (`technical-writing`).

Explanatory Writing

Overview

The craft that makes explanatory prose read clean: coherent, concrete, with momentum and warmth. It owns texture — how the sentences land — not structure and not placement. It executes the technical/educational register already defined in the Meaningfy house voice (company-voice.md); it adds the how-to-write-it-well layer that the voice profile does not carry, and restates none of its rules.

The voice baseline is inherited, never forked. Where a knob default and its linked house source disagree, the source wins (see references/knobs.md).

When to use — the Diátaxis fit-map

| Quadrant | Use the craft? | Why | |----------|----------------|-----| | Explanation (explainers, blog posts, internal notes, broad-audience teaching) | Yes — home | Understanding-oriented prose is exactly what these moves serve. | | Tutorial (framing/intro only) | Partial | Borrow direct address and "imagine…"; keep the steps literal and low-surprise. | | How-to (recipes) | No | Terse, goal-oriented. The texture bloats it. Keep only direct address + concrete naming. | | Reference (lookup) | No | Must stay dry and declarative. The craft is actively harmful here. |

If the request is Reference or How-to, decline and point back to technical-writing / how-to form.

The craft moves

The seven moves, each with a vetted before/after example, live in references/craft-moves.md. In short: one controlling metaphor · concrete-beside-abstract · self-answered question pivots · short declaratives · direct address · coin-and-explain · a confident grounded close.

The voice it executes

  • Register selection is not ours. Follow company-voice.md's rule: teach → technical/educational; decide → general/executive. This skill executes the technical/educational register and introduces no parallel dial.
  • Knobs are positive defaults, cross-linked to the house sources (primary company-voice.md; secondary the Writing-style section of technical-writing and clarity-gate) — see references/knobs.md.
  • The 8-axis voice schema (the diffable structure of a voice) is in references/voice-schema.md.

Self-check

Two scopes, do not confuse them:

  • Calibrating the skill (variant-batch). When tuning the rules or onboarding, generate 3–5 variants of the same piece, collect ~20–30 across a few prompts, and inspect the batch for drift against the fit-map and the knobs. Calibrate on accept/reject: when a variant reads punchier than the house standard, name what gave it away and tighten the rule. Runs today on existing Meaningfy docs; needs no corpus-capture project.
  • Checking one piece. For a single draft, the per-piece quick check below suffices.

Per-piece quick check:

  • One controlling metaphor, carried start to finish (not three half-metaphors)?
  • A concrete, named example beside every abstract claim?
  • At least one self-answered question as a pivot?
  • Short declaratives breaking the rhythm?
  • British English, no em dash, no overclaiming (knobs)? On short prose, British spelling often passes by absence of US forms; land at least one British marker where it falls naturally, rather than assuming "no violation" proves the register.
  • Register correct for purpose (teach vs decide)?

Boundary & Related Skills

Owns: the texture of Explanation-quadrant prose — the craft moves, the fit-map, the 8-axis schema, the positive-default knobs, and variant-batch validation.

Does NOT own: document structure / answer-first persuasion (executive-communication); doc placement, format, and type (technical-writing); the voice profile itself (company-voice.md, owned by executive-communication); the clarity check (clarity-gate).

Precedence when directives compete: structure > clarity > texture. If answer-first structure conflicts with a slow-burn metaphor lede, structure wins: lead with the answer, then apply texture beneath it.

Worked routing trace — request: "Write an explainer of how eVault sync works, for the docs site."

| Skill | Owns | Decides | |-------|------|---------| | technical-writing | placement & form | a docs/ Explanation page (AsciiDoc/Antora), not Reference; invokes the Explanation sub-mode | | explanatory-writing | texture | the metaphor, example-beside-claim, the question pivot, the rhythm, the close — under the knobs | | clarity-gate | the check | actionable · current · specific refs · single-source | | executive-communication | structure | not invoked here (no decision). If it were a recommendation, its answer-first pyramid would win by precedence |

Related: technical-writing, executive-communication, clarity-gate, writing-antipatterns (genre-conditional failure modes, including where this skill's own craft moves invert).