writing skills · choosing a pass
Six skills.
One job each.
Two of them apply a published standard and work on any text. Three need a voice profile before they mean anything. One is Shane’s and will not travel. This page sorts that out, then shows examples taken verbatim from the repository.
start with the job
five situations| Situation | Pass | Why that one |
|---|---|---|
| It reads machine-made and it is going out under your name | humanize |
Structural and vocabulary edits toward a voice, then a scored gate. Needs a profile. |
| The voice is right and the terminology is dated or careless | ms-style-pass |
Term substitutions, bias-free language, and headings only. It will not restructure your sentences. |
| A reader has to find something and act on it | plain-language |
Restructures for the reader’s task. The only skill that reorders the document. |
| A procedure or a warning has to survive translation | ste100 |
Controlled vocabulary and grammar, with sentence-length limits and safety rules. |
| Something is wrong and you do not yet know what | writing-review |
Diagnoses and ranks findings, and refuses to hand you a rewrite. |
The sixth, writing-interview, is not in that table because it is not an
edit. It runs before drafting, and it exists to stop an agent from supplying
material it does not have.
reusable, or Shane’s
what travels| Skill | Portable as it stands | What it depends on |
|---|---|---|
plain-language |
Yes | A published standard: ISO 24495-1:2023. Explicitly written not to impose Shane’s voice. |
ste100 |
Yes | A published standard: ASD-STE100. Written for technical documentation, not narrative. |
humanize |
With your own profile | Profiles/voice.md, which wins every disagreement with the skill. |
ms-style-pass |
With your own profile | The published style guide for terms; a profile for the voice it must not damage. |
writing-review |
With your own profile | The profile’s hard refusals, which bind the review, and its list of deliberate choices a review must not flag. |
writing-interview |
No | Shane’s own material: his trigger material, his questions, his vault, and a workflow that refuses to publish with open items. |
The split is deliberate rather than accidental. The two standards-based skills earn their portability by not caring whose voice the document is in. The three voice skills earn it by putting the author’s profile above their own defaults, which is the same precedence rule that makes them safe to run on someone else’s draft once the profile is theirs.
one at a time
what each refuseshumanize, the voice pass
Does. Reads the whole draft, applies structural edits first and vocabulary second, then runs a preservation pass, then scores the result against a vendored humanizer rubric. A score under 90 sends the passages that lost points back for a rewrite and a rescore, at most three times.
Refuses. Em-dashes anywhere, in any form. Em-dash lists, single-noun colon-reveals, and semicolons between independent clauses. “Simply”, “just”, “obviously”, “of course”, and “clearly”. Adding hedges, asides, or jokes to look human. Claiming a detector result. Restructuring the argument, beyond a flagged reorder inside a paragraph.
Protects. Accurate hedges already present, the confessional
or first-person opener, grounded asides, technical terms that are the right
word, and a fragment sequence that lands a build-up. Where a deduction lands on
protected text, the skill keeps the text and records
kept (−N): reason.
ms-style-pass, the terminology pass
Does. Substitutes terms from a Microsoft Writing Style Guide list filtered for developer content: blocklist for blacklist, allowlist for whitelist, primary and replica for master and slave, soundness check for sanity check. Fixes disability metaphors used figuratively, gendered defaults, “email”, “internet”, “website”, setup as a noun and set up as a verb, the Oxford comma, numerals from 10 up, and sentence-case headings. Adds H2 headings when a draft has none and needs them.
Refuses. Changes to sentence structure, tone, hedges, or
inline code. It also refuses scope creep by name: clarity edits belong to
humanize, and running both in the wrong order makes the second one
undo the first.
Judgment calls are reported. A term that is being discussed rather than used (“the old term was blacklist”) stays, and the changelog says why.
plain-language, the reader’s-task pass
Does. Applies the four governing principles of ISO 24495-1:2023. Readers get what they need, can understand it, can find it, and can use it. Kills nominalisations, fixes ambiguous references, orders information the way the reader will use it, and asks for a reader test where one is possible. When reviewing, it names the principle, quotes the passage, explains the failure in reader terms, and gives a revision.
Refuses. To work without a stated audience and purpose. It asks first, and it says so: you cannot apply Principle 1 without knowing who the readers are and what they need to do. It also refuses to dumb down or to strip information the reader needs to act correctly.
ste100, the controlled-language pass
Does. Applies ASD-STE100 to procedures, descriptions, and safety text. Procedural sentences cap at 20 words and descriptive ones at 25. One instruction per sentence. Active voice, simple tenses, no ambiguous participles, at most three nouns in a cluster, one topic per paragraph, and abbreviations defined at first use.
Refuses. To assert that a word is STE-approved when it cannot
check. The full dictionary is not loaded, so an uncertain word is flagged
needs verification with a likely substitute. It keeps technical
names and technical verbs regardless of the word list, and it will not shorten
a safety warning below the length that keeps it unambiguous.
Scope. Do not run it on narrative or marketing copy unless you asked for that. It is deliberately austere, and it flattens voice by design.
writing-review, the diagnosis
Does. Works down five layers in order: truth and scope,
substance, development, sentences, craft. Reports a piece-level diagnosis, then
passage findings, each carrying one of four verdicts: keep,
revise, ask-author, or cut. Runs five
tests before naming a finding: substance, flatten, relation, specificity, and
triad. Closes by collecting the open ask-author questions into one
list.
Refuses. To produce a replacement draft, to edit the file, or to stage anything. “This is ready” is a valid outcome, and the skill says so explicitly rather than manufacturing findings.
Ask-author is the load-bearing verdict. It is the alternative to inventing the missing detail, which the skill names as the easiest way to damage a draft while believing you improved it.
writing-interview, Shane’s skill
Why it exists. The profile’s own rule, as the skill quotes it: the voice is portable and the thinking is not. A model can reproduce cadence from a profile. It cannot reproduce what the author saw, measured, decided, or changed their mind about. So the interview comes first, and drafting waits.
The hard gate. No opening paragraph, no outline presented as settled, no rough angle to react to. Ask, then wait. For a piece that needs no personal material, the skill says it is the wrong tool and hands off rather than running the ceremony.
Shane-specific by construction. It names him, opens with a
prompt about what happened that made him want to write the piece, sweeps his
vault for prior material through the Obsidian CLI, and reports a provenance
block naming author material, model contribution, and open items. It also
assumes a publishing workflow that refuses to ship while a [TK]
is unresolved.
What travels. The procedure, if you rewrite the questions for your own material and your own sources. The skill as shipped does not, and it should not: the value is in interrogating a specific author, not in a generic interview ritual.
the order they run in
one sequenceThe README gives the sequence its drafting workflow uses, and this site keeps it as
written: interview → draft → humanize → ms-style-pass.
writing-review sits alongside as the read-only diagnostic and is the
agent-side input to the copy gate: it reports, the human decides.
plain-language and ste100 are outside that sequence
because they are not voice passes. Reach for them when the document’s job is
different, not as extra layers on a personal post.
The one order that is wrong: style before voice. ms-style-pass says
outright that it runs after humanize so it can fix terms without
disturbing structure the voice pass already settled.
what the voice profile has to supply
the requirementThe skills point at Profiles/voice.md. It is not in the repository, it
is not linked from this site, and its contents are not published here. That is the
requirement, not an omission: the skills are procedures, and the profile is the
author’s material.
From the skill files, four things depend on that file:
- Precedence.
humanizeandwriting-reviewboth state that the profile is authoritative for voice and wins where a skill’s defaults disagree. Without a profile, the defaults are all that is left, and the defaults describe Shane. - Hard refusals.
writing-reviewtreats the profile’s hard refusals as absolute, so a violation is a finding no matter how well it reads. Your profile’s refusals become your review’s floor. - Deliberate choices. The same skill lists choices a review must not flag: a landing fragment, a confessional opener, a functional proper noun, a header carrying the argument. Those come from knowing the author, not from the standard.
- No inference.
writing-interviewexists because the profile forbids generating author-voiced content without grounding in the author’s actual thoughts or notes.
So the practical requirement for reuse is a profile that states your refusals, your substitutions, the shapes your prose already takes, and the material an agent may not invent on your behalf. A profile that only says “write clearly and vary sentence length” gives the pass nothing to prefer, and the skill will fall back to Shane’s defaults while believing it followed yours.
a documented edit, verbatim
six rowsThese before-and-after rows are copied from the “Example patterns in practice” table
in skills/humanize/SKILL.md, where they are recorded as drawn from
actual edits. Nothing is paraphrased and no row is reconstructed.
| Original | Edited | Documented reason |
|---|---|---|
What you lose when you defer: auditability |
there's one thing you lose when you defer: your ability to audit the work |
Expands a single-noun reveal into a phrase |
It's not a failure; it's the mechanism. |
It's not a failure to find gaps here. That's the mechanism you need. |
Semicolon to period; expands the claim |
More specific. More examples. Closer to real use. |
More specific, with more examples, and closer to real use. |
Filler fragment sequence to prose. A fragment that lands a build-up stays. |
AX — Agent Experience — |
AX (Agent Experience) |
Em-dash definition to parenthetical |
Sharp edge if you try it: |
Beware if you try it. |
Coined label plus colon to plain imperative |
system prompt, prompt (on social) |
configuration, context |
Implementation vocabulary to the reader’s vocabulary. Not brevity: “configuration” is the same length. |
Read the fourth row carefully before applying the ban. The skill carries the em-dash example as the thing to remove, which is why the table can show one while the rule refuses them everywhere. The sixth row is scoped to short-form social in the source, and the source records that LinkedIn kept the implementation terms in the same batch.
a reproducible check
two eval casesThe repository’s eval cases record an input and what the skill must do with it.
Two of them are quoted here from skills/humanize/evals/evals.json, so
you can run the pass yourself and compare behaviour rather than reading a claim
about it.
Case 1, a filler fragment sequence
Input, verbatim:
Humanize this: "The approach is more specific. More actionable. Closer to the real problem."
The case expects the three fragments to merge into one sentence with all three qualities still present. Its assertions are that the fragments are joined into a single sentence rather than left standalone, and that more specific, more actionable, and closer to the real problem all survive.
Case 3, a false positive
Input, verbatim:
Humanize this: "The build finished in 40 minutes. The team shipped it the same day."
This one fails if the pass over-corrects. The sentences must stay committed, no hedge may be introduced (the assertion names so far, with any certainty, about, roughly, may, might, could, perhaps, seems, appears, and tends), “not only” must not appear, and the first sentence must remain a plain assertion rather than being softened to imply uncertainty.
Two of the fourteen cases in that file are false-positive cases like the second one, and they matter most: over-correction is the failure mode the skill was rewritten to prevent.
what is not on this page
one omissionA full worked pass, one draft shown before and after the whole humanize sequence, is not published here. The repository’s eval cases record prompts and expected behaviours, not a verbatim edited draft, so there is no such before-and-after to copy. Building one would mean inventing the after, and a fabricated example is worse than an absent one.
What is here instead: the six documented edit rows above, verbatim, and the two eval
cases you can run against the installed skill. The remaining cases are in
skills/*/evals/evals.json in the source repository.
where to go
after choosing-
Getting started
Marketplace installation as the README documents it, and the profile decision that comes before any voice pass.
-
Project introduction
What the plugin is, and what this site does not claim.
-
The six skill files
Each
SKILL.mdin full, with the references and eval cases beside them.