Skip to content

Allow added specifics and rework the After examples - #331

Merged
blader merged 1 commit into
mainfrom
allow-added-specifics
Nov 10, 2026
Merged

blader merged 1 commit into
mainfrom
allow-added-specifics

Conversation

@blader

@blader blader commented Nov 10, 2026 •

Copy link
Copy Markdown
Owner

Why

Specific detail is much of what makes writing read like a person wrote it. Since 2.9.0 (#189) the skill has forbidden adding any fact that is not in the source. That rule came from #187, which reported that the skill's examples added details. The report showed those details were absent from the Before text. It did not show they were false.

The ban had two costs. Rewrites stayed generic where a concrete detail would have helped. And many After examples contradicted the rule or ended up vaguer than the text they replaced.

What changed

The rule. The skill may now add a specific detail it knows to be true. It must still keep every claim the original made.

Where Before After
Opening line Keep what it says. Do not make anything up. Keep what it says.
Step 2 Do not add a fact, name, number, date, quote, or citation unless it comes from the source or the user. Where the text is generic, add a specific detail you know to be true.
Step 3 asks whether the rewrite added or dropped a fact; an unsupported addition is an error asks whether the rewrite dropped or changed a fact; a lost or changed claim is an error
Pattern 14 Name the relationship the source gives. Name the relationship. If you do not know it, keep the vague wording.
Pattern 17 When the source text names the real source and what it said, use that. When you know the real source and what it said, name it.

Step 2 keeps one sentence from the old rule: "If a sentence needs a detail you do not have, ask for it or write a simpler sentence." The README's "It does not make things up" paragraph now states the new behavior.

The After examples. 11 change in SKILL.md and one in the README.

Pattern What was wrong Fix
2, 6, 20 The After was vaguer than its Before, or did not parse Rewritten to be as concrete as the Before
17 "for its unusual characteristics"; two of four outlets kept for no reason Names what is unusual about the Haolai River; names one source and what it said
18 "over 3,000 square feet" became "3,000" Keeps "more than 3,000"
23 Both Afters used "not documented in the available sources", a phrase on pattern 23's own watch list Plain wording
26 Ended with "Let me know if that works", a pattern 22 phrase, and gave the decision second Leads with the decision; drops the phrase
1, 3 An awkward clause; the watch word "actually" Reworded

The Haolai River detail is checked against its Wikipedia article. The pattern 17 example about a New York Times interview is the one #189 removed; it describes an unnamed, made-up person.

What to decide

  1. This reverses a rule, with no model eval. The skill may now add a detail that turns out to be wrong. "You know to be true" in step 2 is the only guard.
  2. Version. I left the version at 3.1.0 with a note under Unreleased. This should ship as a major version.

Validation

python3 scripts/validate-package.py, npx --yes skills@1.5.20 add . --list, and claude plugin validate . pass. SKILL.md goes from 5,298 to 5,233 words. This builds on #330, which is merged.

To check it, read the diff of SKILL.md: five rule lines and eleven After examples.

🤖 Generated with Claude Code

https://claude.ai/code/session_01MfuoZmv32PFqiaYKaAVSFc

Drop the ban on adding a fact that is not in the source. Where the
text is generic, the skill now adds a specific detail it knows to be
true. It still keeps every claim the original made, and a lost or
changed claim is still an error. Patterns 14 and 17 follow the same
change, and the README says the same.

Rework 11 After examples in SKILL.md and one in the README. Several
were vaguer than the text they replaced, used phrases from the skill's
own watch lists, or changed a stated fact. Pattern 26's After now leads
with the decision, as its rule says.

SKILL.md goes from 5,298 to 5,233 words.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MfuoZmv32PFqiaYKaAVSFc
@blader
blader changed the base branch from clarify-skill-and-readme-wording to main November 10, 2026 01:19
@blader
blader merged commit e97c2c4 into main Nov 10, 2026
1 check passed
This was referenced 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