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.

Everything below is derived from the skill files and the eval cases at the source revision. No skill was run while building this page, so the examples are quoted, not reproduced.

start with the job

the draft in front of you, and what it needs
SituationPassWhy 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

portability as written
SkillPortable as it standsWhat 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

humanize, 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

The 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 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. humanize and writing-review both 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-review treats 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-interview exists 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

These 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.

quoted from humanize/SKILL.md
OriginalEditedDocumented 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

The 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

A 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