SkillPedia Skills Encyclopedia
中文 EN

Skills 2026-09-27 21:08 UTC

ai-readyv1.3.0

Version [v1.3.0] committed by johnpapa. Update Category: Feature Addition & Enhancement. Commit details: Item-by-item review of references/: cut duplicates, narrative asides, and three stale-terminology bugs (#62). This update introduces new capabilities and module extensions.

johnpapa c251292 johnpapa/ai-ready

CommitRaw commit message

Item-by-item review of references/: cut duplicates, narrative asides, and three stale-terminology bugs (#62)

* references/agents-md.md: remove a real internal duplicate and three sections SKILL.md already absorbed

Same test as the SKILL.md pass: does removing this change what the
agent does, and is it stated more completely somewhere else already?

The internal duplicate: `## Never merges without a human` was defined
twice in this one file. Once inline (with its own "it will be
challenged... it is not banned" reasoning) right before the template,
and again in a separate `## Defining` section a few dozen lines later,
with the exact same blockquote repeated. Merged into one treatment, and
folded in the one genuinely new thing the second copy had -- the
distinction between `## Done means` (what a change must satisfy to be
finished) and this section (what it cannot decide alone) -- as an
opening line rather than its own heading and paragraph.

Three sections turned out to be near-complete duplicates of what
SKILL.md's Step 2 already states, likely left behind when Step 2 was
rewritten in an earlier pass and this reference was never re-trimmed to
match:

- The discoverability-test lead-in (SKILL.md already has the full rule
  and the exact "surprising... conventional" phrasing). Trimmed to a
  one-line pointer back to SKILL.md, keeping the verdict table --
  genuinely additive worked examples SKILL.md doesn't have.
- "Structure and stack sections are the ones to be ruthless about..."
  -- near-verbatim duplicate of SKILL.md's surprising/conventional
  language. Cut outright.
- The entire `## Length` section -- SKILL.md's Step 2 already states
  the 20-30 starting point, the 150 ceiling-not-target distinction, and
  the "gets worse as it gets longer" reasoning, in full. Cut, and fixed
  the one dangling reference in "Report this honestly" that assumed the
  cut section's context ("well past the target" -> "well past 150
  lines", so the sentence still stands alone).

Kept, because they're genuinely not duplicated anywhere: the verdict
table, "two rules with no room for judgment" (positive framing,
split-by-scope), the placement table with its own reasoning column,
the OpenAI-monorepo color, "report this honestly," and the full Done-
means / Never-merges-without-a-human generation detail.

136 -> 103 lines (-24%), 1,316 -> 1,048 words.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XE2pKUgGXWbcqbD44mPpSy

* references/reviewer-agents.md: cut two duplicates of SKILL.md's Step 4c, one internal

"Why three, and when it should not be three" restated SKILL.md's own
skip-condition rule almost exactly -- "generate only the ones whose
question can come back no here: skip test-integrity in a repo with no
tests, skip blast-radius where nothing is hard to undo. Say what you
skipped and why" already lives in Step 4c. Trimmed to keep only the
genuinely additive framing (why three isn't a fixed principle) and the
agent-to-question mapping table, with a pointer back to Step 4c for the
skip conditions instead of restating them.

Generation rules' "Never overwrite" bullet duplicated Step 4c's own
closing line ("if the repo already has agents covering these concerns,
leave them and flag drift instead") -- cut. "Keep them narrow" also
duplicated itself against this same file's "Writing a fourth one"
section, both saying "a repo-specific reviewer is a separate file" a
few lines apart. Trimmed to the narrow-remit point only, pointing at
Writing a fourth one for the rest instead of repeating it.

Left untouched: the opening adversarial-agents distinction (written
this session, addresses a real point of confusion), the four mechanics
(now the sole copy, since SKILL.md's restatement of these was cut in
the same session for the same reason), the three literal agent-body
templates (the actual deliverable, not prose to trim), and Writing a
fourth one's four-question checklist (operationalizes the mechanics
into a pass/fail test, which is a different job than restating them).

158 -> 152 lines, 1,246 -> 1,174 words.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XE2pKUgGXWbcqbD44mPpSy

* references/github-discovery.md: fix stale AGENTS.md reference, cut a superlative and a narrative tail

- Real bug: the PR-review-comments table row still said conventions belong in
  "copilot-instructions.md" — stale since PR #37 moved to the single-source-of-truth
  AGENTS.md architecture. Fixed to `AGENTS.md`.
- Cut the "highest-value" superlative and its *Why?* paragraph in 0c, the fifth
  instance of a pattern already removed 4x during the SKILL.md review. Folded the
  one non-redundant fact (a maintainer repeating a comment = an undocumented
  convention) into the lead sentence.
- Trimmed a narrative tail off the closing line of 0c ("turning repeated review
  feedback... into guidance that applies before the next pull request is written
  instead of after") — restates what the section just explained, changes nothing
  an agent does.

69 lines / 823 words -> 68 lines / 783 words.

* references/detection-tables.md: fix a stale drift-check row, cut four narrative *Why?* asides

- Real bug: the drift-detection table asked to check `copilot-instructions.md` for "new
  conventions from PR reviews" and "maintenance matrix" coverage. Under the single-source-of-truth
  architecture (PR #37, and SKILL.md Step 2), both of those live in `AGENTS.md` —
  `copilot-instructions.md` is only a short pointer to it. Moved that check onto the `AGENTS.md`
  row and replaced the `copilot-instructions.md` row with the check that actually applies: has
  the pointer drifted into its own copy of the conventions (the Step 1d duplication failure mode)?
- Cut the monorepo `*Why?*` under manifest detection — redundant with the fuller, more specific
  one under "Monorepo area detection" below; added no instruction of its own.
- Cut the VS Code extension `*Why?*` — narrative justification for a heuristic already fully
  stated above (the detection check plus the three flavors).
- Trimmed the multi-app-collection and course/tutorial `*Why?*` asides down to their one
  actionable sentence each ("don't invent workspace tooling where none exists" /
  what a course repo's product actually is), cutting the restated framing around them.

215 lines / 2,526 words -> 211 lines / 2,465 words.

* references/report-template.md: fix a stale section name used 3x, cut two rule duplicates and two *Why?* asides

- Real bug: three rules referenced a "What I Did" section and one referenced "What To Do
  Next" — neither exists in the template, in README.md, or in examples/sample-report-peacock.md.
  The actual sections are "What I'd Like To Do" and "What's Next?". An agent following these
  rules literally would look for headings that don't exist. Fixed all four references.
- Cut two "Report template rules" bullets (issue/PR attribution, doc-sync-on-change) that
  restate SKILL.md's General Rules almost verbatim — that file is guaranteed context, this one
  is conditional, so the fuller statement stays there. Trimmed the matching restatement in the
  11b PR-creation flow to just the summary/score instruction; the literal template still shows
  `Assisted by [ai-ready]` in the actual PR comment (kept — deliverable, not restatement).
- Cut the HTML report *Why?* and the closing *Why?* on the single-PR-comment rule — both
  restate reasoning for an instruction already given in full, directive form just above.

227 lines / 1,736 words -> 221 lines / 1,615 words.

* references/agents-md.md: restore the load-bearing guard and the 20–30 line target lost with ## Length

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PuNQuoLvQF4hVY9JUFnJA1

---------

Co-authored-by: Claude <noreply@anthropic.com>