| name | doc-readability |
| description | Evaluates documentation readability, structure, and compliance with docs/spec/AGENTS.md conventions. Use when reviewing doc quality, auditing formatting compliance, checking a page before publishing, or running a readability audit across the specification. |
Documentation Readability Evaluation
Evaluate readability and spec-layer compliance for: $ARGUMENTS
Parse the arguments to determine scope.
Accepted inputs:
- A single page path (e.g.,
docs/spec/evm/dual-gas-model.md) — evaluate that page.
- A directory (e.g.,
docs/spec/evm/) — evaluate all pages in that directory.
all — evaluate every page listed in docs/spec/SUMMARY.md and docs/mega-evme/SUMMARY.md.
Default (no arguments): evaluate all pages.
Setup
Before evaluating any page:
- Read
docs/spec/AGENTS.md — the authoritative writing rules for this specification.
- Read
docs/spec/SUMMARY.md — the spec page inventory.
- Read
docs/mega-evme/SUMMARY.md — the mega-evme page inventory.
Note: Pages under docs/mega-evme/ follow reference-doc conventions, not spec-page conventions.
They may omit frontmatter spec fields, Specification/Constants sections, and normative RFC 2119 language.
Apply Structural Lint, Cross-Linking, and Formatting checks as normal, but adapt Page Structure Compliance and Normative Language checks to reference-doc expectations.
Evaluation Checklist
1. Structural Lint
2. Page Structure Compliance
Concept pages MUST follow this section order (per docs/spec/AGENTS.md):
# Page Title
Abstract
## Motivation
## Specification
## Constants
## Rationale
## Security Considerations
## Spec History
3. Normative Language
4. Constants and Formulas
5. Spec Versioning
6. Cross-Linking
7. Formatting
Output Format
## Readability
**Scope**: {what was evaluated}
**Pages evaluated**: {count}
### Summary
| Result | Count |
|--------|-------|
| Pass | N |
| Fail | N |
| Total findings | N |
### Per-Category Results
For each page, report pass/fail per checklist category.
Categories with no findings still appear as "Pass" — do not silently omit them.
| Category | Result | Findings |
|----------|--------|----------|
| Structural Lint | Pass / Fail | N |
| Page Structure Compliance | Pass / Fail | N |
| Normative Language | Pass / Fail | N |
| Constants and Formulas | Pass / Fail | N |
| Spec Versioning | Pass / Fail | N |
| Cross-Linking | Pass / Fail | N |
| Formatting | Pass / Fail | N |
### Findings
#### R-001: {short description}
- **Severity**: Blocker | Major | Minor
- **Page**: {path}
- **Rule**: {which check failed}
- **Evidence**: {excerpt or description}
- **Suggested fix**: {concrete edit}
#### R-002: ...
Severity definitions:
- Blocker: Content violates core spec conventions — implementation details in Specification section, normative keywords in Rationale, spec linking to external user/dev docs.
- Major: Missing frontmatter, heading hierarchy violations, wrong hint block style, missing required sections.
- Minor: Multi-sentence lines, missing glossary links, suboptimal block usage, minor formatting drift.
Rules
- Evaluate against the
docs/spec/AGENTS.md rules as written. Do not invent additional style rules.
- When a page has zero findings, still count it as "Pass" in the summary.
- Sort findings by severity (Blocker first), then by page.
- Do NOT fix the issues yourself unless the user explicitly asks. This skill produces a report, not edits.
- If a finding is ambiguous (could be intentional), note it as Minor with "Review: may be intentional".
