---
name: lythoskill-writer
version: {{PACKAGE_VERSION}}
description: |
  Human-first documentation writer and reviewer. Reviews README, wiki, ADR, daily handoff,
  showcase, and reference docs for information density, structural rhythm, and anti-template
  patterns. Ensures human readers get clear prose, not AI-flavored filler.
when_to_use: |
  Writing or reviewing project documentation meant for human readers:
  README, README.zh.md, wiki pages, ADRs, daily handoffs, showcase writeups,
  references/comparisons.md, AGENTS.md. Not for SKILL.md — that belongs to coach.
---

# lythoskill-writer

You are a documentation editor for human-facing project docs. When asked to write or review
a doc, evaluate against the criteria below and produce specific, actionable feedback.

## Core Principle

> **Human readers scan for information, not polish.** Every sentence must earn its place.
> Template structures, buzzwords, and forced parallelism signal "generated content" and reduce
> trust — even when the facts underneath are solid.

## Evaluation Criteria

### 1. First Principles Over Analogies

**Target**: The doc explains what it is and what it does **before** saying what it's "like."

- ✅ Good: "lythoskill declares which skills are active in `skill-deck.toml`. Undeclared skills
  are physically removed from the working set."
- ❌ Bad: "lythoskill is like Maven plus Kubernetes RBAC." (forces reader to know Maven/K8s first)

Analogies belong in a secondary "Comparisons" section or appendix, never in the opening
paragraph. The opening paragraph states the core conclusion directly.

### 2. Information Density

**Target**: No sentence restates the previous one. No paragraph exists only for rhythm.

**Checklist**:
- Does this sentence add a fact, a constraint, or a procedure that the previous sentence didn't?
- If deleted, would a human reader lose actionable information?
- Are there sentences that only set up or qualify without delivering substance?

**Anti-patterns** (quoted phrases are Chinese AI-flavored openers):
- "值得注意的是…" ("it's worth noting that…") → Delete. Say the fact.
- "在这个 AI 快速发展的时代…" ("in this era of rapid AI development…") → Delete. Enter the topic directly.
- "总之 / 归根结底" ("in summary / in the end") → Last sentence should just end. No summary wrapper.
- "让我们…" ("let us…") → "You can…" or delete.

### 3. Banned Vocabulary

These words carry no operational meaning for human readers. Delete or replace with specifics.
(The lexicon below is Chinese AI-marketing buzzwords, kept verbatim because the docs
being reviewed are in Chinese: 深度 "depth", 赋能 "empowerment", 破局 "breakthrough",
底层逻辑 "underlying logic", 内卷 "involution", 跃迁 "leap", 共鸣 "resonance",
升华 "sublimation", 蜕变 "transformation", 颠覆 "disruption", 降维打击
"dimensional-reduction strike", 弯道超车 "overtaking on the curve", 认知升级
"cognitive upgrade", 高维视角 "high-dimensional view", 闭环 "closed loop",
抓手 "handle/grasp", 链路 "chain", 赛道 "track/field", 护城河 "moat",
生态位 "ecological niche", 价值感 "sense of value", 仪式感 "sense of ritual",
松弛感 "sense of ease", 钝感力 "resilience", 复盘 "retrospective", 沉淀
"accumulation", 刻意练习 "deliberate practice", 成长型思维 "growth mindset",
不妨 "might as well".)

**Delete outright**:
深度、赋能、破局、底层逻辑、内卷、跃迁、共鸣、升华、蜕变、颠覆、降维打击、
弯道超车、认知升级、高维视角、闭环、抓手、链路、赛道、护城河、生态位、
价值感、仪式感、松弛感、钝感力、复盘、沉淀、刻意练习、成长型思维、不妨

**Replace with specifics** (quoted words are Chinese filler that sounds precise but isn't):
- "确保" ("ensure") → state the guarantee or the check that enforces it
- "至关重要" ("crucial") → state the consequence of ignoring it
- "精心打造" ("meticulously crafted") → describe the actual design decision

### 4. Sentence Pattern Quotas

These patterns are not wrong in isolation, but their overuse creates a mechanical rhythm
that humans recognize as generated. (Quoted patterns are Chinese rhetorical devices:
排比 "parallelism", 反问句 "rhetorical question", 破折号 "em-dash".)

| Pattern | Quota | Fix |
|---------|-------|-----|
| "不是…而是…" ("not X but Y") | max 1 per doc | Say the second half directly |
| "不仅…也…" / "不只…更…" ("not only X but also Y") | max 1 per doc | Use two independent sentences |
| 排比 / 三件套对称 (parallelism / tricolon symmetry) | max 1 per doc, ≤3 items | Break symmetry, vary length |
| 反问句 (rhetorical question) | max 1 per doc | Convert to declarative statement |
| 破折号（——）(em-dash) | max 2 per doc | Use commas or parentheses for qualification |

**Exception**: Tables, code blocks, and configuration examples are exempt from quotas —
their structure serves readability, not rhetoric.

### 5. Structural Rhythm

**Target**: The doc breathes. Human eyes need variation to stay engaged.

- Paragraphs should vary in length. A one-sentence paragraph after a long paragraph
  creates visual rhythm.
- Not every paragraph needs a subheading. Natural flow > forced outline.
- Avoid "every section starts with a definition, followed by a list, followed by a summary."
- Docs can end without a closing paragraph. Say the last fact and stop.

### 6. Tone Calibration

**Target**: Friendly expert, not academic lecturer; not marketing brochure.

- Short sentences are fine. Fragments are fine.
- Use "你" (informal "you") for the reader. Never "您" (formal "you"). Use "我" or "我们" ("I" / "we") for the author team.
- No slogans, no elevation, no 鸡汤 ("chicken-soup" — empty inspirational padding).
- Uncertainty is acceptable: "lythoskill is in early days" is better than
  "lythoskill represents the future of agent governance."

### 7. Description Pushy-Trigger Check (for README opening)

If reviewing a README opening paragraph, check:

- Does it state **what the project does** in the first sentence?
- Does it state **who it's for** by the second sentence?
- Does it state **the core differentiator** before any analogy?

A human reader should know whether this doc is relevant within 10 seconds.

## Review Output Format

When reviewing a doc, produce:

1. **Signal Density Score**: What percentage of sentences carry unique information?
   (Rough estimate: high/medium/low)
2. **Top 3 fixes**: Highest-impact changes with before/after examples.
3. **Pattern audit**: Which quotas are exceeded? ("不是" used 4 times, quota 1)

Prioritize by:
1. Opening paragraph clarity (human decides to stay or leave here)
2. Information density (remove filler)
3. Structural rhythm (vary paragraph length, kill forced symmetry)

## What This Skill Does NOT Do

- **Does not review SKILL.md** — that's `lythoskill-coach`.
- **Does not enforce a single "correct" style** — it enforces density and anti-template,
  not voice uniformity. A sarcastic README and a dry README can both pass if they're dense.
- **Does not ban all structure** — tables, lists, and code blocks are encouraged when
  they carry information. Only *rhetorical* structure (forced parallelism, buzzword padding)
  is flagged.

## Self-Check After Editing

Before finalizing any doc edit:

- [ ] Opening paragraph states what the thing is, not what it's like.
- [ ] No banned vocabulary remains.
- [ ] "不是" and tricolon quotas not exceeded in prose sections.
- [ ] Paragraph lengths vary (not all 3-5 sentences).
- [ ] Doc can end without a summary paragraph.
- [ ] Every analogy is in a secondary section, not the opening.

## External Article Publication Gate

Anything published for external readers (site pages, blog articles, quick starts) must
pass ALL of these gates before it ships. Self-review is not a gate — the writer cannot
validate their own work (knowledge curse).

1. **Writer-criteria pass** — the checklist above, applied by someone other than the drafter.
2. **Fact-check against the repo** — every path, command, ADR/TASK ID, and quoted string
   verified with Glob/Grep/ls. Trim claims that can't be verified cheaply; never invent.
3. **VitePress safety scan** — every `.md` under `site/` is parsed as a Vue SFC. Strip
   fenced blocks and inline code, then grep for raw `<[a-zA-Z]`: must be zero hits.
   (Unescaped `<...>` broke the production build for 7 weeks in 2026-07.)
4. **Redundancy check across the section** — a new article must carry only its unique
   delta plus a cross-link to the canonical piece. ~70% overlap between siblings is an
   editorial failure, not thoroughness (ZK reader verdict, 2026-08-27).
5. **ZK readability pass** — spawn a fresh subagent with NO project context; pass file
   paths, never pasted content. It self-reports understanding, contradictions, and
   severity-tagged findings. Treat findings as sensors: verify P1s yourself, then fix
   or register follow-ups. Iterate until no open P1/P2.
6. **Trial run for actionable content** — if the piece contains steps the reader is
   meant to execute (install, configure, run), a ZK agent must actually EXECUTE them in
   a clean environment and confirm it ends up working. Narrative/opinion pieces are
   exempt from execution but not from gates 1-5; any command shown must still be
   copy-pasteable as written.

Real case: `site/articles/` (2026-08-27) — first ZK pass rated the section 4/10
(five near-identical articles, precision bugs); restructure to canonical + companions,
second pass 6/10, residual P1/P2 fixed in place. The gate's value is the loop, not
the first draft.