Skip to content

Rewrite unclear sentences in the skill and README - #330

Merged
blader merged 2 commits into
mainfrom
clarify-skill-and-readme-wording
Nov 10, 2026
Merged

blader merged 2 commits into
mainfrom
clarify-skill-and-readme-wording

Conversation

@blader

@blader blader commented Nov 10, 2026 •

Copy link
Copy Markdown
Owner

Why

Zonder Labs' write-up on AI slop names faults that make text hard to read. Two of them showed up in SKILL.md and README.md: wording that is vague or coined, and sentences that bury the point or say nothing. An agent reads every word of SKILL.md on each use, so an unclear line there costs something every time.

What changed

Wording only, in the prose of SKILL.md and README.md. No pattern was added, removed, or renumbered. Users get the new wording the next time they install or sync the skill. The version stays 3.1.0, with a note under Unreleased in CHANGELOG.md.

Coined terms became plain words. Three were unclear enough that I recovered their meaning from the commits that introduced them (34ca949 and eda497e):

Before After
claim that things happen at once claim that two things happen at the same time
shape edits under §6, §9, and §19 edits under §6, §9, and §19
because repetition is handled by rule instead of by ear (clause removed)

"Riders", "the move", and "send-off" are gone too. Pattern 15 is renamed from "Shallow -ing riders" to "Shallow -ing phrases" in both files.

Sentences that announced or repeated are cut, and two late points moved up.

  • Removed "Two rules follow from this.", "Nothing here needs rewriting.", and the second half of "Vary sentence length; real writing alternates short and long."
  • Step 3 now asks first whether the rewrite added or dropped a fact. That check used to come third of five.
  • Pattern 26 now gives "Lead with the decision" in its second sentence. It used to come third.

README. Three sentences now say what Humanizer does: it does not try to get past AI detectors, it may merge, split, or reorder sentences while drafting, and it numbers the patterns from strongest to weakest. The install section gives /humanizer as the only command and no longer lists /humanizer:humanizer or /skill:humanizer.

SKILL.md goes from 5,316 to 5,298 words, under the 5,500 cap.

An earlier commit on this branch also rewrote passive pattern descriptions to start with "The writer". The second commit takes that back out: the descriptions are about text, so the text is a fine subject.

What to decide

These are changes to a prompt, and I did not run a model eval on them. The reviewer decides whether each rewrite keeps its rule's meaning. Three lines deserve the closest read, because they changed order or dropped a clause: step 3 in "How to work", the Problem line of pattern 7, and the Problem line of pattern 26.

Validation

python3 scripts/validate-package.py, npx --yes skills@1.5.20 add . --list, and claude plugin validate . pass.

To check it, read the diff of SKILL.md. It changes 11 lines, and each is a sentence replaced or removed in place.

#318 edits some of the same lines and will need a rebase after this merges.

🤖 Generated with Claude Code

https://claude.ai/code/session_01MfuoZmv32PFqiaYKaAVSFc

blader and others added 2 commits November 9, 2026 16:53
Name who acts in passive and subjectless lines, replace coined terms
("riders", "shape edits", "by rule instead of by ear", "send-off",
"dressing") with plain words, and cut sentences that only announced or
repeated a neighbor. Step 3 now checks for added or dropped facts
first, and pattern 26 gives its instruction second instead of third.

Pattern 15 is renamed "Shallow -ing phrases". The README gives
/humanizer as the only command. No pattern was added, removed, or
renumbered. SKILL.md goes from 5,316 to 5,327 words.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MfuoZmv32PFqiaYKaAVSFc
The pattern descriptions are about text, so the text is a fine subject.
Restore the original Problem lines and "Why" bullets, and keep the
plain-word replacements, the cut sentences, and the reordered step 3
and pattern 26. In pattern 7 the unclear cause clause is dropped
instead of rewritten. SKILL.md is now 5,298 words, down from 5,316.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MfuoZmv32PFqiaYKaAVSFc
@blader
blader merged commit b8baa17 into main Nov 10, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant