{"slug":"readability-guidance","title":"readability-guidance","summary":"Surfaces Han's shared Human-Readable Output Standard — the readability rule and the writing-voice profile — into the calling skill's own context, so the caller drafts in voice and runs its self-check against the current standard sourced from one canonical copy. Use when a prose-p","platform":"Claude","tags":[],"authorName":"LLM Mart","authorSlug":"llm-mart","score":0,"source":"github","price":null,"verified":false,"createdAt":"2026-10-15T13:11:54.054114Z","repo":{"url":"https://github.com/testdouble/han","stars":303,"forks":24,"license":"MIT","updatedAt":"2026-10-14T20:22:28Z"},"bodyHtml":"<hr>\n<h2>name: readability-guidance\ndescription: &gt;\nSurfaces Han's shared Human-Readable Output Standard — the readability rule and the writing-voice profile — into the\ncalling skill's own context, so the caller drafts in voice and runs its self-check against the current standard\nsourced from one canonical copy. Use when a prose-producing skill needs the shared readability standard available in\ncontext before it drafts. Governs the shape of a written deliverable, where explanation-guidance governs what a run\nsays to a person in a turn. Runs in the caller's context and hands control straight back; it does not produce a\ndeliverable of its own, rewrite anything, or judge the caller's work. Does not run the adversarial rewrite pass —\ndispatch the readability-editor agent for that, or use edit-for-readability to rewrite an existing target. Does not\ncover explaining technical work to a reader who will not implement it — use explanation-guidance for that.\nallowed-tools: Read, Bash(bash \"$/scripts/han-config-dir.sh\")</h2>\n<h2>Project Context</h2>\n<ul>\n<li>personal config directory: !<code>bash \"${CLAUDE_PLUGIN_ROOT}/scripts/han-config-dir.sh\" 2&gt;/dev/null || echo \"$HOME/.claude\"</code></li>\n<li>project .han/config.md: !<code>cat .han/config.md 2&gt;/dev/null || echo \"\"</code></li>\n</ul>\n<p>As your first action, use the Read tool on <code>.han/config.md</code> inside the <code>personal config directory</code> path above. A read\nthat returns no file is no personal configuration: continue silently. When that file or the <code>project .han/config.md</code>\nprobe supplies content, apply it per <a href=\"../../references/config-rule.md\">config-rule.md</a>, which governs precedence\nbetween the two files, relative-path resolution, and what to do with a file that reads but cannot be used.</p>\n<h1>Readability Guidance</h1>\n<p>You have invoked <code>readability-guidance</code> to source the shared readability standard before you draft prose. This skill\nsurfaces the standard into your own context and hands control back. It is a means to writing your deliverable, not the\ndeliverable itself: apply what it surfaces while you draft and self-check, then RETURN to the workflow that called you\nand finish it.</p>\n<p>This skill is <strong>inline</strong> — it runs in your context, not an isolated one, so the standard it surfaces stays available to\nyou after it returns. Do not treat anything here as a stopping point or a final answer.</p>\n<h2>Which outputs this standard covers</h2>\n<p>A structured specification, plan, phased build, work-item list, coding standard, or test plan is reader-facing whenever a\nhuman reads it end to end — to approve it, follow it, or build from it — even when downstream skills also consume it. Only\nan artifact consumed purely as a pipeline input, with no human reading it end to end, falls outside the standard. If a\nhuman reads your deliverable end to end, apply the standard to it.</p>\n<h2>Step 1: Resolve the writing-voice source, then read the standard</h2>\n<p>First resolve which writing-voice profile this run uses:</p>\n<ul>\n<li>When either <code>.han/config.md</code> probe supplied a <code>writing-voice</code> value, resolve it and check that the file exists. A\nrelative value resolves against the folder holding the file that declared it: the working directory for the project\nfile, and the <code>personal config directory</code> the probe reported for the personal file. A full path is used as it stands,\nand a leading <code>~</code> expands to the home directory. When both files supply a value, the project file's wins.\n<ul>\n<li>When the file exists, it is the writing-voice profile for this run, used in place of the built-in profile.</li>\n<li>When the file does not exist, warn the user that the configured writing-voice file was not found, naming which of\nthe two configuration files declared it, and ask whether to use the built-in Han voice or skip the writing voice\nentirely for this run. Honor the answer: fall back to the built-in profile, or proceed with no voice profile at all.</li>\n</ul>\n</li>\n<li>When neither probe supplied a <code>writing-voice</code> value, the built-in profile at\n<code>${CLAUDE_PLUGIN_ROOT}/references/writing-voice.md</code> applies.</li>\n</ul>\n<p>Then read the reference files, in this order, so their full content enters your context:</p>\n<ol>\n<li><code>${CLAUDE_PLUGIN_ROOT}/references/readability-rule.md</code> — the Human-Readable Output Standard: the audience frame, the\noutput properties, the length guidance, the prose-only and fidelity rules, and the standardized self-check.</li>\n<li>The resolved writing-voice profile — the configured file, or the built-in\n<code>${CLAUDE_PLUGIN_ROOT}/references/writing-voice.md</code>, whose \"Avoided words and phrases\" and \"AI slop to avoid\"\nsections are the authoritative vocabulary blocklist the rule points to. A configured profile stands in for the\nbuilt-in one wholesale: apply whatever voice and vocabulary guidance it carries. When the user chose to skip the\nwriting voice, read only the readability rule and apply it with no voice profile and no vocabulary blocklist.</li>\n</ol>\n<p>Do not paraphrase or summarize the files in place of reading them — the surfaced content is the point.</p>\n<h2>Step 2: Hold the audience frame while you draft</h2>\n<p>While you draft, write for a capable reader who did not do this work and lacks the author's context. If the calling\nskill names a specific reader (an engineer implementing a fix, a PR reviewer, a non-technical stakeholder), write for\nthat reader instead and keep the technical specifics that reader needs. The frame governs how a fact is said, never\nwhether a required fact appears.</p>\n<h2>Step 3: Apply the standard in stages, then continue</h2>\n<p>The standard takes effect in stages, never as one stacked instruction block:</p>\n<ul>\n<li><strong>Draft into your template</strong> so the structural rules (main point first, descriptive headings, one idea per paragraph,\nnumbered-vs-bullet lists, progressive disclosure, technical detail after the prose) are built in.</li>\n<li><strong>After the draft exists, run the standardized self-check</strong> from the readability rule over the prose regions only —\nnever inside code fences, diagram bodies, rendered markup, or citation identifiers. Correct every failure before\npresenting. On a skill that runs no separate rewrite pass, the fidelity criterion is the only fact-preservation guard\nthe output has, so it is not optional.</li>\n<li><strong>If your workflow is a synthesis skill</strong>, dispatch <code>han-communication:readability-editor</code> for the adversarial rewrite\nafter your full draft exists, as the standard reserves that pass for synthesis output. This skill does not run that\nrewrite.</li>\n</ul>\n<p>The standard is now in your context. Proceed to the next step of the skill that invoked you and produce its deliverable.</p>\n","files":[{"path":"SKILL.md","sizeBytes":6542,"isText":true}],"reviewScore":null,"reviewSummary":null,"trust":{"provenance":"trusted-source-unreviewed","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow.","bodySource":null},"bodyLocked":false,"purchaseUrl":null,"sourceUrl":null,"report":{"provenance":"trusted-source-unreviewed","screen":{"ran":true,"outcome":"clean","suspicious":0,"notes":0,"hiddenCharacters":false},"virusScan":{"engine":"clamav","status":"clean","scannedAt":"2026-10-15T13:12:02.851108Z","sha256":"02A457FB90D349A796FBF3932F17AEFEE96E444F50E5C7F2B25996A5F02FE5EB","sizeBytes":2788},"review":null,"source":{"repositoryUrl":"https://github.com/testdouble/han","path":"han-communication/skills/readability-guidance","license":"MIT","commit":"abba73a773528905a8f3d15956029394746e5c7f","subtreeSha":"1E9A96D7A80053DCFAD93A8E4C902288CA7F95966EE31F2E1560CC9569ABEB5E","lastSyncedAt":"2026-10-15T13:11:53.672149Z"},"reviewedAt":"2026-10-15T13:12:21.053285Z","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow."},"install":[{"target":"skills-cli","command":"npx skills add https://github.com/testdouble/han/tree/main/han-communication/skills/readability-guidance"},{"target":"claude-code","command":"claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install testdouble-han@llmmart"},{"target":"git","command":"git clone https://github.com/testdouble/han.git"}]}