fix(skills): select help from an explicitly tagged release #112

jercik · 2026-10-04T04:21:28Z

jercik commented

2026-10-04 04:21:28 +00:00

Selects @latest for general CLI help and the documented release for release-specific READMEs, following the existing package-runner rule. The Agent Rule template in verify-readme and the npx example format in verify-unixy-cli now both name the tag.

Follows #109, which has merged.

Selects `@latest` for general CLI help and the documented release for release-specific READMEs, following the existing package-runner rule. The Agent Rule template in `verify-readme` and the npx example format in `verify-unixy-cli` now both name the tag. Follows [#109](https://code.j4k.dev/j4k-oss/agent-skills/pulls/109), which has merged.

jercik added 1 commit

2026-10-04 04:21:28 +00:00

fix: select release help with an explicit package tag

commit-msg / commitlint (pull_request) Successful in 22s

Details

Node tests / node:test (pull_request) Successful in 3m4s

Details

Review / Review (pull_request_target) Successful in 4m6s

Details

8b56c3fd9a

jercik referenced this pull request

2026-10-04 04:23:13 +00:00

fix(skills): source pointers should match the documented release #109

forgejo-actions commented

2026-10-04 04:25:33 +00:00

Review 01M484489Q6YK4HG29HASKMAS0 — head 311c3e40e6b5649629a728f2180a738495618c65

Review — j4k-oss/agent-skills @ `fac8684948`

Scope: diff against base tree 457b2484ee2a
Status: dispatched — coverage complete (5/5 slots terminal)
Facts: current review-wide projection

Computed under:

{
  "abandonment": "abandonment-v1",
  "anchor_recipe": 1,
  "batch_policy": "batch-v1",
  "coverage": "coverage-v3",
  "dispatch_policy": "dispatch-v2",
  "grounder_version": 1,
  "grounding_read_rule": "grounding-read-v1",
  "promotion_policy": "promotion-v1",
  "report": "report-v4",
  "tally": "tally-v1",
  "triage_settle": "triage-settle-v2"
}

Findings (2)

medium — The catalog description copies the project-type set defined in Inputs

claim: 01M484DR5RRF8P13K96PYWQY1X
anchor: skills/verify-readme/SKILL.md (snippet)

description: Audit, rewrite, or draft a repository's README.md — CLI tool, library, application, config/dotfiles repo, or monorepo.

lens: writing-quality · arm: default
verdicts: 1 valid / 0 invalid / 0 uncertain
- pass 01M484FAXBWDZ7G4HNH240Y5HB · valid: The exact-grounded description enumerates project types. The reviewer names skills/verify-readme/SKILL.md Inputs as the defining source and lists its categories: CLI tool, Library, Application / service, Config / dotfiles repo, and Monorepo. The body compares them with the description categories and reports no category unique to either inventory. This supplies the path and entries required by the restated-sets standard, even though the source comparison is reviewer-supplied rather than grounded. No stated exception applies: the description is a routing catalog copy, not the classification source or a table of contents. Removing the enumeration and routing by repository README preserves scope without a second inventory. Medium severity fits an agreeing copy.
disposition: none

The description creates a second inventory of supported project types. A change to the classification rules must also update this catalog sentence, and nothing in the examined files flags a missed update. The inventories agree now, so the cost is maintaining a copy that can silently become stale.

The “Inputs” section defines the classification set and the signals for choosing each member: CLI tool, Library, Application / service, Config / dotfiles repo, and Monorepo. The description covers CLI tool, library, application, config/dotfiles repo, and monorepo. These names cover the same categories; no category appears in only one inventory. The description supplies no classification signal or member-specific detail. The review’s restated-sets standard requires prose to refer to the defining source rather than repeat its members, even when the copy agrees.

Remove the project-type enumeration from the description and scope the routing rule to a repository README. For example: “Use when the user asks to audit, improve, rewrite, or draft a repository README, including requests about README quality.” The “Inputs” section remains the source for project classification. This preserves the broad README scope without another inventory to maintain.

I compared the complete frontmatter description with the classification rules in skills/verify-readme/SKILL.md and read its section-specific instructions. This is a static inventory comparison; no skill execution was needed.

The matching category coverage establishes the current agreement. An independent authoritative contract that requires the catalog to enumerate categories could justify the copy, but none is provided in the examined material.

low — The skill description spends catalog context on its method before giving the routing rule

claim: 01M484CKP8VWHY24PWYNF131F6
anchor: skills/verify-readme/SKILL.md (snippet)

description: Audit, rewrite, or draft a repository's README.md — CLI tool, library, application, config/dotfiles repo, or monorepo. Applies a universal section order and cross-checks the one-liner against `package.json#description`. Use when the user wants to review, improve, rewrite, or write a README, or mentions "verify readme", "review readme", "rewrite readme", "write readme", "README quality", or "check my README".

lens: writing-quality · arm: default
verdicts: 1 valid / 0 invalid / 0 uncertain
- pass 01M484FAXBWDZ7G4HNH240Y5HB · valid: The exact-grounded description starts with Audit, rewrite, or draft and includes the universal section order and package.json description cross-check before its Use when clause. The installed packaging reference requires a capability description to begin with Use when and forbids method or contents summaries. Its user-request trigger clause establishes capability routing. The proposed repository-README routing sentence preserves the review/improve/rewrite/write intents without copying project classifications; literal phrases are covered by those intents. I reassessed the historical valid verdict: its concrete packaging comparison still applies, and the current correction avoids its project-type enumeration. Low severity fits.
disposition: none

The persistent skill description asks the selecting agent to read a summary of the audit method before reaching the condition for using the skill. That material consumes catalog context on tasks where the skill is never loaded, although it does not distinguish a matching README request.

The description opens with a summary of the README work and then says it applies a universal section order and cross-checks the one-liner against package.json#description. Only afterward does it introduce “Use when” and the user-request triggers. The installed writing standard’s references/skill-packaging.md requires capability descriptions to begin with “Use when …” and describe routing conditions rather than the method or contents. The body already defines the section order and description-parity check.

Replace the description with: “Use when the user asks to audit, improve, rewrite, or draft a repository README, including requests about README quality.” Keep the audit method in the body. This preserves the request boundary while removing implementation detail from discovery and making the selection condition immediate.

I read the full skill, its declared writing-style dependency, the caller in skills/verify-unixy-cli/references/arg5-readme-quality.md, and the repository README’s explanation that capability descriptions occupy the initial catalog while bodies load after selection. I also read the installed packaging reference in full. No routing experiment was run; this is a direct comparison with the packaging contract.

The existing request-trigger clause and body establish that the shorter routing description preserves the documented task scope. Evidence that method wording distinguishes this skill from another README capability could justify retaining that distinction in the routing condition; no such distinction is stated here.

Other claims

grounding-pending (0)
ungrounded (0)
rejected (0)
duplicate-of (0)
unadjudicated (2)
- 01M484BNEZ1MJBMJ0V1PN7RKZN low — The Agent Rule checklist repeats the template instead of stating only its exception
- 01M484C2SMR4HHHE1E8C4CHCM4 low — The pipeline paragraph repeats the help checklist and verification instructions

Coverage

Coverage pass: 01M48448B9FQT14AXXRQNAWDJM
Accounting: complete
Slot health: healthy

lens	part	arm	unit status	runs	loss
general-bug	whole	default	no-claims	1	no
writing-quality	whole	default	claims-emitted	1	no
test-trimming	whole	default	no-claims	1	no
restated-sets	whole	default	no-claims	1	no
project-docs	whole	default	no-claims	1	no

**Review** `01M484489Q6YK4HG29HASKMAS0` — head `311c3e40e6b5649629a728f2180a738495618c65` # Review — j4k-oss/agent-skills @ fac8684948ea Scope: diff against base tree `457b2484ee2a` Status: dispatched — coverage complete (5/5 slots terminal) Facts: current review-wide projection Computed under: ```json { "abandonment": "abandonment-v1", "anchor_recipe": 1, "batch_policy": "batch-v1", "coverage": "coverage-v3", "dispatch_policy": "dispatch-v2", "grounder_version": 1, "grounding_read_rule": "grounding-read-v1", "promotion_policy": "promotion-v1", "report": "report-v4", "tally": "tally-v1", "triage_settle": "triage-settle-v2" } ``` ## Findings (2) ### medium — The catalog description copies the project-type set defined in Inputs - claim: `01M484DR5RRF8P13K96PYWQY1X` - anchor: `skills/verify-readme/SKILL.md` (snippet) ``` description: Audit, rewrite, or draft a repository's README.md — CLI tool, library, application, config/dotfiles repo, or monorepo. ``` - lens: writing-quality · arm: default - verdicts: 1 valid / 0 invalid / 0 uncertain - pass `01M484FAXBWDZ7G4HNH240Y5HB` · valid: The exact-grounded description enumerates project types. The reviewer names skills/verify-readme/SKILL.md Inputs as the defining source and lists its categories: CLI tool, Library, Application / service, Config / dotfiles repo, and Monorepo. The body compares them with the description categories and reports no category unique to either inventory. This supplies the path and entries required by the restated-sets standard, even though the source comparison is reviewer-supplied rather than grounded. No stated exception applies: the description is a routing catalog copy, not the classification source or a table of contents. Removing the enumeration and routing by repository README preserves scope without a second inventory. Medium severity fits an agreeing copy. - disposition: none > The description creates a second inventory of supported project types. A change to the classification rules must also update this catalog sentence, and nothing in the examined files flags a missed update. The inventories agree now, so the cost is maintaining a copy that can silently become stale. > > The “Inputs” section defines the classification set and the signals for choosing each member: CLI tool, Library, Application / service, Config / dotfiles repo, and Monorepo. The description covers CLI tool, library, application, config/dotfiles repo, and monorepo. These names cover the same categories; no category appears in only one inventory. The description supplies no classification signal or member-specific detail. The review’s restated-sets standard requires prose to refer to the defining source rather than repeat its members, even when the copy agrees. > > Remove the project-type enumeration from the description and scope the routing rule to a repository README. For example: “Use when the user asks to audit, improve, rewrite, or draft a repository README, including requests about README quality.” The “Inputs” section remains the source for project classification. This preserves the broad README scope without another inventory to maintain. > > I compared the complete frontmatter description with the classification rules in `skills/verify-readme/SKILL.md` and read its section-specific instructions. This is a static inventory comparison; no skill execution was needed. > > The matching category coverage establishes the current agreement. An independent authoritative contract that requires the catalog to enumerate categories could justify the copy, but none is provided in the examined material. ### low — The skill description spends catalog context on its method before giving the routing rule - claim: `01M484CKP8VWHY24PWYNF131F6` - anchor: `skills/verify-readme/SKILL.md` (snippet) ``` description: Audit, rewrite, or draft a repository's README.md — CLI tool, library, application, config/dotfiles repo, or monorepo. Applies a universal section order and cross-checks the one-liner against `package.json#description`. Use when the user wants to review, improve, rewrite, or write a README, or mentions "verify readme", "review readme", "rewrite readme", "write readme", "README quality", or "check my README". ``` - lens: writing-quality · arm: default - verdicts: 1 valid / 0 invalid / 0 uncertain - pass `01M484FAXBWDZ7G4HNH240Y5HB` · valid: The exact-grounded description starts with Audit, rewrite, or draft and includes the universal section order and package.json description cross-check before its Use when clause. The installed packaging reference requires a capability description to begin with Use when and forbids method or contents summaries. Its user-request trigger clause establishes capability routing. The proposed repository-README routing sentence preserves the review/improve/rewrite/write intents without copying project classifications; literal phrases are covered by those intents. I reassessed the historical valid verdict: its concrete packaging comparison still applies, and the current correction avoids its project-type enumeration. Low severity fits. - disposition: none > The persistent skill description asks the selecting agent to read a summary of the audit method before reaching the condition for using the skill. That material consumes catalog context on tasks where the skill is never loaded, although it does not distinguish a matching README request. > > The description opens with a summary of the README work and then says it applies a universal section order and cross-checks the one-liner against `package.json#description`. Only afterward does it introduce “Use when” and the user-request triggers. The installed writing standard’s `references/skill-packaging.md` requires capability descriptions to begin with “Use when …” and describe routing conditions rather than the method or contents. The body already defines the section order and description-parity check. > > Replace the description with: “Use when the user asks to audit, improve, rewrite, or draft a repository README, including requests about README quality.” Keep the audit method in the body. This preserves the request boundary while removing implementation detail from discovery and making the selection condition immediate. > > I read the full skill, its declared writing-style dependency, the caller in `skills/verify-unixy-cli/references/arg5-readme-quality.md`, and the repository README’s explanation that capability descriptions occupy the initial catalog while bodies load after selection. I also read the installed packaging reference in full. No routing experiment was run; this is a direct comparison with the packaging contract. > > The existing request-trigger clause and body establish that the shorter routing description preserves the documented task scope. Evidence that method wording distinguishes this skill from another README capability could justify retaining that distinction in the routing condition; no such distinction is stated here. ## Other claims - grounding-pending (0) - ungrounded (0) - rejected (0) - duplicate-of (0) - unadjudicated (2) - `01M484BNEZ1MJBMJ0V1PN7RKZN` low — The Agent Rule checklist repeats the template instead of stating only its exception - `01M484C2SMR4HHHE1E8C4CHCM4` low — The pipeline paragraph repeats the help checklist and verification instructions ## Coverage Coverage pass: 01M48448B9FQT14AXXRQNAWDJM Accounting: complete Slot health: healthy | lens | part | arm | unit status | runs | loss | | --- | --- | --- | --- | --- | --- | | general-bug | whole | default | no-claims | 1 | no | | writing-quality | whole | default | claims-emitted | 1 | no | | test-trimming | whole | default | no-claims | 1 | no | | restated-sets | whole | default | no-claims | 1 | no | | project-docs | whole | default | no-claims | 1 | no |

🚀 1

forgejo-actions reviewed

2026-10-04 04:25:33 +00:00

skills/verify-readme/SKILL.md Outdated

					
				@ -166,3 +166,3 @@

				- State when and why to use the tool.

				Why `npx -y <tool> --help` instead of an embedded flag reference: the agent reads the selected package's help text rather than an embedded flag copy, including on fresh machines, CI, and containers.

				Read the selected package's help so the options match the release the agent runs, without maintaining an embedded flag copy.

low — Agent Rule rationale is rewritten as a bare imperative with no clear subject, so it reads as an extra instruction

What I examined: the "Agent Rule template (CLI only)" section of skills/verify-readme/SKILL.md, which the diff changed, and the rest of the skill for context. The section shows a template block, then lists what "The block must:" do: start with # Rule:, "Make npx -y <tool>@latest --help the first instruction; use @<documented-release> instead of @latest for a README describing a specific release.", and "State when and why to use the tool." The diff replaced the old rationale line, "Why npx -y <tool> --help instead of an embedded flag reference: the agent reads the selected package's help text rather than an embedded flag copy, including on fresh machines, CI, and containers.", with the anchored sentence.

What goes wrong: this skill is read by the agent that audits or writes the README. Everything else in the skill that uses the imperative mood is addressed to that agent. The new sentence also starts with an imperative, "Read the selected package's help", but it actually explains why the Agent Rule points at --help, and the action belongs to a different agent: the one that later follows the published rule. It sits right after the "must" list, so a literal reader can take it as one more step. The auditing agent might run the tool's --help itself, or add a "read the help" sentence to the rule block alongside the required first instruction. The old wording marked the line as rationale with "Why ...:" and named "the agent" as the subject. The rewrite dropped both. "The selected package" also has nothing to refer to now that the sentence no longer mentions the @latest/@<documented-release> choice. The writing skill says rationale should help the agent adapt a rule, and that conditions should attach to the action they govern. Here the sentence's mood points the reader at the wrong action.

Proposed correction: state it as rationale with an explicit subject, for example: "Pointing at --help gives the agent options that match the release it runs, and leaves the README no flag copy to maintain." This keeps both reasons the new text carries (version-matched options, no copy to maintain) and removes the ambiguous imperative. The dropped "fresh machines, CI, and containers" clause follows from npx -y and doesn't need restoring.

Evidence basis: static reading of the file. Nothing was executed. To refute this, show that readers of this skill consistently read the sentence as rationale rather than as an instruction to themselves.

lens writing-quality · arm default · tally 1 valid / 0 invalid / 0 uncertain
claim 01M42JDWEE9K7E9FFABFYNWYRW of review 01M42JAJ27EN7CHQDHHH635YKR

**low** — Agent Rule rationale is rewritten as a bare imperative with no clear subject, so it reads as an extra instruction > What I examined: the "Agent Rule template (CLI only)" section of skills/verify-readme/SKILL.md, which the diff changed, and the rest of the skill for context. The section shows a template block, then lists what "The block must:" do: start with `# Rule:`, "Make <code>npx -y <tool>@latest --help</code> the first instruction; use <code>@<documented-release></code> instead of `@latest` for a README describing a specific release.", and "State when and why to use the tool." The diff replaced the old rationale line, "Why <code>npx -y <tool> --help</code> instead of an embedded flag reference: the agent reads the selected package's help text rather than an embedded flag copy, including on fresh machines, CI, and containers.", with the anchored sentence. > > What goes wrong: this skill is read by the agent that audits or writes the README. Everything else in the skill that uses the imperative mood is addressed to that agent. The new sentence also starts with an imperative, "Read the selected package's help", but it actually explains why the Agent Rule points at `--help`, and the action belongs to a different agent: the one that later follows the published rule. It sits right after the "must" list, so a literal reader can take it as one more step. The auditing agent might run the tool's `--help` itself, or add a "read the help" sentence to the rule block alongside the required first instruction. The old wording marked the line as rationale with "Why ...:" and named "the agent" as the subject. The rewrite dropped both. "The selected package" also has nothing to refer to now that the sentence no longer mentions the `@latest`/<code>@<documented-release></code> choice. The writing skill says rationale should help the agent adapt a rule, and that conditions should attach to the action they govern. Here the sentence's mood points the reader at the wrong action. > > Proposed correction: state it as rationale with an explicit subject, for example: "Pointing at `--help` gives the agent options that match the release it runs, and leaves the README no flag copy to maintain." This keeps both reasons the new text carries (version-matched options, no copy to maintain) and removes the ambiguous imperative. The dropped "fresh machines, CI, and containers" clause follows from `npx -y` and doesn't need restoring. > > Evidence basis: static reading of the file. Nothing was executed. To refute this, show that readers of this skill consistently read the sentence as rationale rather than as an instruction to themselves. lens `writing-quality` · arm `default` · tally 1 valid / 0 invalid / 0 uncertain claim `01M42JDWEE9K7E9FFABFYNWYRW` of review `01M42JAJ27EN7CHQDHHH635YKR`

👍 1

Fixed in b006bd5f29: rationale now names the agent and describes matching release options without an extra imperative.

Fixed in b006bd5f298efddddbf9b0bdf91d9a68bfb72191: rationale now names the agent and describes matching release options without an extra imperative.

jercik marked this conversation as resolved

jercik added 1 commit

2026-10-04 04:27:13 +00:00

fix: keep CLI help examples on the selected release

commit-msg / commitlint (pull_request) Successful in 17s

Details

Node tests / node:test (pull_request) Successful in 2m6s

Details

Review / Review (pull_request_target) Successful in 2m51s

Details

b006bd5f29

jercik commented

2026-10-04 04:28:29 +00:00

Replying to review comment #112139

Review 01M42JAJ27EN7CHQDHHH635YKR, report-only claim 01M42JE3SD0J2SDMNR2PHXHQBM: fixed in b006bd5f298efddddbf9b0bdf91d9a68bfb72191. ARG3's npx help example now uses @latest and describes the existing documented-release alternative, matching the repository's package-runner rule and the README template. No new package-selection policy was introduced. The claim appeared only in the summary, with no matching inline conversation anchor; no per-claim native transition is asserted.

> Replying to review comment #112139 Review `01M42JAJ27EN7CHQDHHH635YKR`, report-only claim `01M42JE3SD0J2SDMNR2PHXHQBM`: fixed in `b006bd5f298efddddbf9b0bdf91d9a68bfb72191`. ARG3's npx help example now uses `@latest` and describes the existing documented-release alternative, matching the repository's package-runner rule and the README template. No new package-selection policy was introduced. The claim appeared only in the summary, with no matching inline conversation anchor; no per-claim native transition is asserted.

jercik referenced this pull request

2026-10-06 07:45:00 +00:00

fix(skills): source pointers should match the documented release #109

jercik added 1 commit

2026-10-06 08:08:48 +00:00

chore: merge fix/version-matched-source-pointers into release-help branch

commit-msg / commitlint (pull_request) Successful in 22s

Details

Node tests / node:test (pull_request) Successful in 3m10s

Details

Review / Review (pull_request_target) Successful in 10m7s

Details

0bbe0bb30f

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

jercik referenced this pull request

2026-10-07 11:57:55 +00:00

fix(skills): source pointers should match the documented release #109

jercik changed target branch from fix/version-matched-source-pointers to main

2026-10-08 08:20:52 +00:00

jercik added 1 commit

2026-10-08 08:22:37 +00:00

chore: merge main into release-help branch

Review / Review (pull_request_target) Successful in 6s

Details

commit-msg / commitlint (pull_request) Successful in 16s

Details

Node tests / node:test (pull_request) Successful in 2m2s

Details

311c3e40e6

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

jercik commented

2026-10-08 08:22:43 +00:00

Merged main into the branch at 311c3e4 after #109 landed. The net diff against main is now only the two @latest / documented-release edits in verify-readme and verify-unixy-cli.

Conclusions on the review of 0bbe0bb:

Both findings (the verify-readme catalog description) are moot. The description line came from the branch's older base; after the merge it matches main (shortened in #125), and this PR no longer touches it.
Unadjudicated 01M484BNEZ1MJBMJ0V1PN7RKZN (Agent Rule checklist repeats the template): not a defect this PR introduces. The checklist and template layering predates it; the PR only changes the @latest wording in one bullet and the rationale sentence.
Unadjudicated 01M484C2SMR4HHHE1E8C4CHCM4 (pipeline paragraph repeats the help checklist): not a defect this PR introduces. The text in arg3-help-content-quality.md is the existing "Help should include" list with its "How to verify" step; this PR changes one npx example line there. Declined.

Merged `main` into the branch at 311c3e4 after #109 landed. The net diff against `main` is now only the two `@latest` / documented-release edits in `verify-readme` and `verify-unixy-cli`. Conclusions on the review of 0bbe0bb: - Both findings (the `verify-readme` catalog description) are moot. The description line came from the branch's older base; after the merge it matches `main` (shortened in #125), and this PR no longer touches it. - Unadjudicated `01M484BNEZ1MJBMJ0V1PN7RKZN` (Agent Rule checklist repeats the template): not a defect this PR introduces. The checklist and template layering predates it; the PR only changes the `@latest` wording in one bullet and the rationale sentence. - Unadjudicated `01M484C2SMR4HHHE1E8C4CHCM4` (pipeline paragraph repeats the help checklist): not a defect this PR introduces. The text in `arg3-help-content-quality.md` is the existing "Help should include" list with its "How to verify" step; this PR changes one npx example line there. Declined.

🚀 1

jercik merged commit 01b0b29e9d into main

2026-10-08 11:17:14 +00:00

jercik deleted branch fix/release-help-command-selection

2026-10-08 11:17:14 +00:00

jercik referenced this pull request from a commit

2026-10-08 11:17:14 +00:00

fix(skills): select help from an explicitly tagged release (#112)

Sign in to join this conversation.

No reviewers

No labels

No milestone