Skip to content

Make the After examples read better - #332

Merged
blader merged 1 commit into
mainfrom
polish-after-examples
Nov 10, 2026
Merged

blader merged 1 commit into
mainfrom
polish-after-examples

Conversation

@blader

@blader blader commented Nov 10, 2026 •

Copy link
Copy Markdown
Owner

Why

The After examples are the skill's proof that it works, and the two in the README are the first thing a visitor reads. Several still read stiffly after #331. The README's top example ran three clauses into one sentence, the Lisbon example closed a paragraph on a stock phrase, and five examples in SKILL.md used abstract or passive phrasing a person would not choose.

What changed

Example text only. No rule, pattern, or Before text changes. Every fact in each Before is still in its After.

README, top example

Before this PR After this PR
For months our own team passed around files named final_v7.docx, so we built a way for two people to edit the same doc at once, and each sees the other's changes live. For months our own team passed around files named final_v7.docx, and we got sick of it. Now two people can edit the same doc at once and see each other's changes as they type.

README, Lisbon example

  • "The views from the top were worth the climb" becomes "the views from the top made up for it", joined to the sentence about the stairs.
  • The custard tarts get their own paragraph instead of trailing the tram.
  • "my favorite" becomes "the best one I had", and "liked best" becomes "liked most" so "best" is not used twice in a row.

SKILL.md

Pattern Before this PR After this PR
1 The heavy beat adds to the aggressive tone. The heavy beat makes the song sound more aggressive.
1 No external system confirms which choice is right, although the choices still have different consequences. The choices differ, but no outside system will tell you which one is right.
5 Session tokens are rotated every 24 hours, in place, and clients refresh transparently. Session tokens rotate in place every 24 hours, and clients refresh transparently.
18 The gallery has four separate spaces and more than 3,000 square feet. It has four separate spaces and more than 3,000 square feet.
19 The update improves the interface, speeds up load times through optimized algorithms, and adds end-to-end encryption. The update adds a new interface, faster algorithms, and end-to-end encryption.

SKILL.md goes from 5,233 to 5,226 words. The CHANGELOG.md note under Unreleased now counts 15 reworked examples in SKILL.md and both README examples. Users see the new examples the next time they install or sync the skill.

What to decide

Whether these read better. That is a judgment of taste, and no model eval was run. This commit was pushed to the #331 branch a few minutes after #331 merged, so it missed that PR and is here on its own.

Validation

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

To check it, read the two After examples in the README on this branch, then the five changed lines in the SKILL.md diff. For each one, look for two things: every fact in the Before is still there, and the sentence is one a person would say aloud.

🤖 Generated with Claude Code

https://claude.ai/code/session_01MfuoZmv32PFqiaYKaAVSFc

README: the top example breaks one three-clause sentence into three,
and the Lisbon example gets shorter sentences, one more paragraph
break, and no stock "worth the climb" line. Both keep every fact from
their Before text.

SKILL.md: reword five stiff After examples (patterns 1, 5, 18, 19).
SKILL.md is now 5,226 words.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MfuoZmv32PFqiaYKaAVSFc
@blader
blader merged commit a7ade02 into main Nov 10, 2026
1 check passed
@blader blader mentioned this pull request Nov 10, 2026
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