create-with-human-voice
create-with-human-voice is the voice-application workflow packet of the sk-doc family.
It takes prose you are writing or have written and brings it up to the Human Voice Rules,
or reports how far off it is without touching a byte.
The standard lives here and exists exactly once, at
references/hvr-rules.md. This packet owns both halves: the
standard itself, and the workflow that applies it, meaning what may be touched, in what
order, with what arithmetic, and how the result is proved. Nothing in this packet restates
a rule the standard already carries, and no consumer holds a second copy.
Keyword triggers: human voice rules, apply human voice, rewrite in human voice, make this sound human, sounds ai-generated, reads like ai wrote it, remove ai tells, ai writing tells, voice pass, de-ai the writing.
1. WHEN TO USE
Activation Triggers
- Someone says a draft reads like a machine wrote it, and wants it fixed.
- A document is about to ship and needs a voice pass before it does.
- Someone asks how a passage scores against the Human Voice Rules, without wanting edits.
- You are about to write documentation prose and want the standard in force from the first sentence rather than bolted on afterwards.
- A sibling workflow needs the HVR step of its own pipeline actually performed rather than gestured at.
When NOT to Use
- The target is a whole document needing structure, DQI and validators. That is
sk-create-quality-control, which owns the file-level audit. This mode owns the voice, and the audit calls it for that step.
- The artifact does not exist yet. A README, changelog, agent, command, catalog, playbook, benchmark, diagram or repo rule is scaffolded by its own sibling mode, which then applies this standard to the prose it produced.
- The text is code, output, a quotation or a generated file. A voice edit there is a defect, not an improvement.
- The request is about brand or product tone. The Human Voice Rules are a linguistic standard for documentation, not a tone-of-voice guide.
2. SMART ROUTING
sk-doc routes voice work here: the request names the Human Voice Rules, a voice pass, a rewrite in human voice or /create:with-human-voice.
The hub's mode signal selects this packet.
Two operations route here: apply, which edits, and score, which reports and does not.
The operation decides which resources load, and the scope gate decides which spans any edit may touch.
references/scope-and-exemptions.md loads first on every path, because what may be touched comes before what to change.
references/hvr-rules.md is the standard the scanner parses on every run, so it is read rather than copied.
An unmatched request returns UNKNOWN_FALLBACK with its checklist rather than guessing.
Read ROUTER.md before selecting skill-local resources; open only the matched files.
3. HOW IT WORKS
Score
- Gate the scope. Run
references/scope-and-exemptions.md over the target. Name every exempt span before reading for findings. A document about the standard scores catastrophically against itself, so confirm the target is not one.
- Run the mechanical pass.
python3 .skilled/skills/sk-doc/sk-create-with-human-voice/scripts/hvr_scan.py <target>
The scanner parses the term lists out of the standard on every run, so it never carries a
stale copy. Exit 0 means no hard blocker, 1 means at least one, 2 means it could not read
the standard and refuses to report a clean scan.
- Read the mechanical findings as candidates. Word sense decides, not spelling.
harness the noun is fine, harness the verb is not, and the scanner reports both.
- Run the judgment pass. Structure, sentence habits, content habits and voice. The scanner prints this list on every run precisely because it cannot check any of it.
- Compute the score under the precedence rule and the point table in
references/hvr-publish-supplement.md, using the point arithmetic in references/scoring-and-verification.md, or report hard blockers and density on a long document. The category weights in the publish supplement's sections 2 and 4 describe where attention goes, not a second arithmetic, and no run combines the two.
- Report using
assets/voice-report-template.md. Do not edit.
Apply
Steps 1 through 5 above, then:
- Edit only in-scope spans. Fix hard blockers first, then soft deductions, then the judgment findings. Leave every exempt span untouched.
- Re-run the scanner on the rewritten text. Rewriting introduces new tells: the sentence that loses
leverage reaches for utilise, and the three-item list becomes a four-item list whose fourth item says nothing.
- Report both numbers. A single after-score proves nothing about what the pass did.
Draft
Writing new prose is the same workflow with the passes moved earlier. Load the standard
before the first sentence, write, then run steps 2 through 9 on what came out. The order
is what changes, never the checks.
4. RULES
✅ ALWAYS
- Gate the scope before the first finding, and record every exemption in the report.
- Run the mechanical pass before the judgment pass.
- Treat a scanner finding as a candidate. Word sense decides whether it is a defect.
- Re-run the scanner after any rewrite and report the before and after numbers.
- State the length basis when quoting a number: an absolute score, or hard blockers plus density.
- Keep an accepted exception in the report, with the reason it was kept.
⛔ NEVER
- Change what a sentence claims to satisfy a word ban. Accuracy outranks the standard, and the exception gets recorded instead.
- Edit a quotation, an error string, a command, a generated file, a released changelog entry or a byte-pinned fixture.
- Score a document that is about the standard, including the standard itself, without saying that is what it is.
- Copy any part of
references/hvr-rules.md into another file, whether a sibling packet, a command asset or a repo rule. Reference the path.
- Report a clean scan the scanner refused to produce. Exit 2 is a failure, not a pass.
- Quote an absolute score for a document long enough that length alone drove it negative.
⚠️ ESCALATE IF
- The standard and accuracy conflict on something load-bearing, and the right call is the author's rather than yours.
- The target is frozen, generated or byte-pinned, and the request is to edit it anyway.
- The scanner exits 2, meaning the standard's shape moved and the parser needs updating before any scan can be trusted.
5. SUCCESS CRITERIA
- Every exempt span is named in the report rather than silently skipped.
- Both scan numbers appear on any run that edited text.
- No quotation, code sample, generated file or fixture changed.
- The judgment findings are answered by a reader, not implied by a clean mechanical result.
- Nothing from the standard was copied into another file.
6. INTEGRATION POINTS
| Consumer |
What it takes from here |
sk-create-quality-control |
Its HVR review step. The audit owns structure, DQI and validators, this mode owns the voice finding it reports |
Every sk-create-* sibling |
The voice pass over the prose their templates produce |
7. REFERENCES
Routed by references/README.md. Load
references/scope-and-exemptions.md first on every path. The standard itself is
references/hvr-rules.md, read rather than copied.
8. RELATED RESOURCES
| Resource |
Purpose |
references/hvr-rules.md |
The base. Voice directives, punctuation bans, structural patterns, term lists |
references/hvr-publish-supplement.md |
The supplement. Scoring, precedence, the pre-publish checklist and related resources |
README.md |
What the mode does, why the scanner over-reports, and how to verify it |
scripts/hvr_scan.py |
The mechanical pass, parsed from the standard at run time |
../sk-create-quality-control/SKILL.md |
The file-level audit whose HVR step this mode performs |
1---2name: sk-create-with-human-voice3description: Apply the Human Voice Rules to prose, or score prose against them, with a scope gate first and a re-scan after the rewrite.4allowed-tools: [Read, Write, Edit, Bash, Grep, Glob]5version: 1.2.6.06metadata:7 source: https://skillmd.com/skills/michelkerkmeester/sk-create-with-human-voice8---910# create-with-human-voice1112`create-with-human-voice` is the voice-application workflow packet of the `sk-doc` family.13It takes prose you are writing or have written and brings it up to the Human Voice Rules,14or reports how far off it is without touching a byte.1516**The standard lives here and exists exactly once**, at17[`references/hvr-rules.md`](references/hvr-rules.md). This packet owns both halves: the18standard itself, and the workflow that applies it, meaning what may be touched, in what19order, with what arithmetic, and how the result is proved. Nothing in this packet restates20a rule the standard already carries, and no consumer holds a second copy.2122Keyword triggers: `human voice rules`, `apply human voice`, `rewrite in human voice`, `make this sound human`, `sounds ai-generated`, `reads like ai wrote it`, `remove ai tells`, `ai writing tells`, `voice pass`, `de-ai the writing`.2324---2526## 1. WHEN TO USE2728### Activation Triggers2930- Someone says a draft reads like a machine wrote it, and wants it fixed.31- A document is about to ship and needs a voice pass before it does.32- Someone asks how a passage scores against the Human Voice Rules, without wanting edits.33- You are about to write documentation prose and want the standard in force from the first sentence rather than bolted on afterwards.34- A sibling workflow needs the HVR step of its own pipeline actually performed rather than gestured at.3536### When NOT to Use3738- **The target is a whole document needing structure, DQI and validators.** That is `sk-create-quality-control`, which owns the file-level audit. This mode owns the voice, and the audit calls it for that step.39- **The artifact does not exist yet.** A README, changelog, agent, command, catalog, playbook, benchmark, diagram or repo rule is scaffolded by its own sibling mode, which then applies this standard to the prose it produced.40- **The text is code, output, a quotation or a generated file.** A voice edit there is a defect, not an improvement.41- **The request is about brand or product tone.** The Human Voice Rules are a linguistic standard for documentation, not a tone-of-voice guide.4243---4445## 2. SMART ROUTING4647`sk-doc` routes voice work here: the request names the Human Voice Rules, a voice pass, a rewrite in human voice or `/create:with-human-voice`.48The hub's mode signal selects this packet.49Two operations route here: `apply`, which edits, and `score`, which reports and does not.50The operation decides which resources load, and the scope gate decides which spans any edit may touch.5152`references/scope-and-exemptions.md` loads first on every path, because what may be touched comes before what to change.53`references/hvr-rules.md` is the standard the scanner parses on every run, so it is read rather than copied.5455An unmatched request returns `UNKNOWN_FALLBACK` with its checklist rather than guessing.5657Read [`ROUTER.md`](./ROUTER.md) before selecting skill-local resources; open only the matched files.5859---6061## 3. HOW IT WORKS6263### Score64651. **Gate the scope.** Run `references/scope-and-exemptions.md` over the target. Name every exempt span before reading for findings. A document about the standard scores catastrophically against itself, so confirm the target is not one.662. **Run the mechanical pass.**6768```bash69python3 .skilled/skills/sk-doc/sk-create-with-human-voice/scripts/hvr_scan.py <target>70```7172The scanner parses the term lists out of the standard on every run, so it never carries a73stale copy. Exit 0 means no hard blocker, 1 means at least one, 2 means it could not read74the standard and refuses to report a clean scan.75763. **Read the mechanical findings as candidates.** Word sense decides, not spelling. `harness` the noun is fine, `harness` the verb is not, and the scanner reports both.774. **Run the judgment pass.** Structure, sentence habits, content habits and voice. The scanner prints this list on every run precisely because it cannot check any of it.785. **Compute the score** under the precedence rule and the point table in `references/hvr-publish-supplement.md`, using the point arithmetic in `references/scoring-and-verification.md`, or report hard blockers and density on a long document. The category weights in the publish supplement's sections 2 and 4 describe where attention goes, not a second arithmetic, and no run combines the two.796. **Report** using `assets/voice-report-template.md`. Do not edit.8081### Apply8283Steps 1 through 5 above, then:84857. **Edit only in-scope spans.** Fix hard blockers first, then soft deductions, then the judgment findings. Leave every exempt span untouched.868. **Re-run the scanner on the rewritten text.** Rewriting introduces new tells: the sentence that loses `leverage` reaches for `utilise`, and the three-item list becomes a four-item list whose fourth item says nothing.879. **Report both numbers.** A single after-score proves nothing about what the pass did.8889### Draft9091Writing new prose is the same workflow with the passes moved earlier. Load the standard92before the first sentence, write, then run steps 2 through 9 on what came out. The order93is what changes, never the checks.9495---9697## 4. RULES9899### ✅ ALWAYS1001011. Gate the scope before the first finding, and record every exemption in the report.1022. Run the mechanical pass before the judgment pass.1033. Treat a scanner finding as a candidate. Word sense decides whether it is a defect.1044. Re-run the scanner after any rewrite and report the before and after numbers.1055. State the length basis when quoting a number: an absolute score, or hard blockers plus density.1066. Keep an accepted exception in the report, with the reason it was kept.107108### ⛔ NEVER1091101. Change what a sentence claims to satisfy a word ban. Accuracy outranks the standard, and the exception gets recorded instead.1112. Edit a quotation, an error string, a command, a generated file, a released changelog entry or a byte-pinned fixture.1123. Score a document that is about the standard, including the standard itself, without saying that is what it is.1134. Copy any part of `references/hvr-rules.md` into another file, whether a sibling packet, a command asset or a repo rule. Reference the path.1145. Report a clean scan the scanner refused to produce. Exit 2 is a failure, not a pass.1156. Quote an absolute score for a document long enough that length alone drove it negative.116117### ⚠️ ESCALATE IF1181191. The standard and accuracy conflict on something load-bearing, and the right call is the author's rather than yours.1202. The target is frozen, generated or byte-pinned, and the request is to edit it anyway.1213. The scanner exits 2, meaning the standard's shape moved and the parser needs updating before any scan can be trusted.122123---124125## 5. SUCCESS CRITERIA126127- Every exempt span is named in the report rather than silently skipped.128- Both scan numbers appear on any run that edited text.129- No quotation, code sample, generated file or fixture changed.130- The judgment findings are answered by a reader, not implied by a clean mechanical result.131- Nothing from the standard was copied into another file.132133---134135## 6. INTEGRATION POINTS136137| Consumer | What it takes from here |138|---|---|139| `sk-create-quality-control` | Its HVR review step. The audit owns structure, DQI and validators, this mode owns the voice finding it reports |140| Every `sk-create-*` sibling | The voice pass over the prose their templates produce |141142---143144## 7. REFERENCES145146Routed by [`references/README.md`](references/README.md). Load147`references/scope-and-exemptions.md` first on every path. The standard itself is148[`references/hvr-rules.md`](references/hvr-rules.md), read rather than copied.149150---151152## 8. RELATED RESOURCES153154| Resource | Purpose |155|---|---|156| [`references/hvr-rules.md`](references/hvr-rules.md) | The base. Voice directives, punctuation bans, structural patterns, term lists |157| [`references/hvr-publish-supplement.md`](references/hvr-publish-supplement.md) | The supplement. Scoring, precedence, the pre-publish checklist and related resources |158| [`README.md`](README.md) | What the mode does, why the scanner over-reports, and how to verify it |159| [`scripts/hvr_scan.py`](scripts/hvr_scan.py) | The mechanical pass, parsed from the standard at run time |160| [`../sk-create-quality-control/SKILL.md`](../sk-create-quality-control/SKILL.md) | The file-level audit whose HVR step this mode performs |