Project Context
- personal config directory: !
bash "${CLAUDE_PLUGIN_ROOT}/scripts/han-config-dir.sh" 2>/dev/null || echo "$HOME/.claude"
- project .han/config.md: !
cat .han/config.md 2>/dev/null || echo ""
As your first action, use the Read tool on .han/config.md inside the personal config directory path above. A read
that returns no file is no personal configuration: continue silently. When that file or the project .han/config.md
probe supplies content, apply it per config-rule.md, which governs precedence
between the two files, relative-path resolution, and what to do with a file that reads but cannot be used.
Readability Guidance
You have invoked readability-guidance to source the shared readability standard before you draft prose. This skill
surfaces the standard into your own context and hands control back. It is a means to writing your deliverable, not the
deliverable itself: apply what it surfaces while you draft and self-check, then RETURN to the workflow that called you
and finish it.
This skill is inline — it runs in your context, not an isolated one, so the standard it surfaces stays available to
you after it returns. Do not treat anything here as a stopping point or a final answer.
Which outputs this standard covers
A structured specification, plan, phased build, work-item list, coding standard, or test plan is reader-facing whenever a
human reads it end to end — to approve it, follow it, or build from it — even when downstream skills also consume it. Only
an artifact consumed purely as a pipeline input, with no human reading it end to end, falls outside the standard. If a
human reads your deliverable end to end, apply the standard to it.
Step 1: Resolve the writing-voice source, then read the standard
First resolve which writing-voice profile this run uses:
- When either
.han/config.md probe supplied a writing-voice value, resolve it and check that the file exists. A
relative value resolves against the folder holding the file that declared it: the working directory for the project
file, and the personal config directory the probe reported for the personal file. A full path is used as it stands,
and a leading ~ expands to the home directory. When both files supply a value, the project file's wins.
- When the file exists, it is the writing-voice profile for this run, used in place of the built-in profile.
- When the file does not exist, warn the user that the configured writing-voice file was not found, naming which of
the two configuration files declared it, and ask whether to use the built-in Han voice or skip the writing voice
entirely for this run. Honor the answer: fall back to the built-in profile, or proceed with no voice profile at all.
- When neither probe supplied a
writing-voice value, the built-in profile at
${CLAUDE_PLUGIN_ROOT}/references/writing-voice.md applies.
Then read the reference files, in this order, so their full content enters your context:
${CLAUDE_PLUGIN_ROOT}/references/readability-rule.md — the Human-Readable Output Standard: the audience frame, the
output properties, the length guidance, the prose-only and fidelity rules, and the standardized self-check.- The resolved writing-voice profile — the configured file, or the built-in
${CLAUDE_PLUGIN_ROOT}/references/writing-voice.md, whose "Avoided words and phrases" and "AI slop to avoid"
sections are the authoritative vocabulary blocklist the rule points to. A configured profile stands in for the
built-in one wholesale: apply whatever voice and vocabulary guidance it carries. When the user chose to skip the
writing voice, read only the readability rule and apply it with no voice profile and no vocabulary blocklist.
Do not paraphrase or summarize the files in place of reading them — the surfaced content is the point.
Step 2: Hold the audience frame while you draft
While you draft, write for a capable reader who did not do this work and lacks the author's context. If the calling
skill names a specific reader (an engineer implementing a fix, a PR reviewer, a non-technical stakeholder), write for
that reader instead and keep the technical specifics that reader needs. The frame governs how a fact is said, never
whether a required fact appears.
Step 3: Apply the standard in stages, then continue
The standard takes effect in stages, never as one stacked instruction block:
- Draft into your template so the structural rules (main point first, descriptive headings, one idea per paragraph,
numbered-vs-bullet lists, progressive disclosure, technical detail after the prose) are built in.
- After the draft exists, run the standardized self-check from the readability rule over the prose regions only —
never inside code fences, diagram bodies, rendered markup, or citation identifiers. Correct every failure before
presenting. On a skill that runs no separate rewrite pass, the fidelity criterion is the only fact-preservation guard
the output has, so it is not optional.
- If your workflow is a synthesis skill, dispatch
han-communication:readability-editor for the adversarial rewrite
after your full draft exists, as the standard reserves that pass for synthesis output. This skill does not run that
rewrite.
The standard is now in your context. Proceed to the next step of the skill that invoked you and produce its deliverable.