Repository navigation
docs: SKILL.md is a release asset now, so the hedge saying it is not comes out - #69
Merged
Merged
Conversation
…comes out `release.yml` had staged and signed `SKILL.md` for several releases, but no PUBLISHED tag carried it. A reader who ran the recipe's step 3 verbatim got `no such file or directory` from an otherwise-working document and reasonably concluded the mistake was theirs, so four surfaces — docs/skill.md, README.md, templates/skills/sscsb/SKILL.md and AGENTS.md — each disclosed the gap, and `every_surface_showing_the_recipe_discloses_that_the_asset_is_not_published_yet` held the sentence on all four so it could not be forgotten. That test carried its own removal instructions in a `WHEN_TO_DELETE` constant: delete the hedge only once a release contains SKILL.md, check with `gh release view`, and remove it from every surface at once together with the test and the `sscsb::skill` constants it reads. The precondition is met. `v0.4.0`, published 2026-09-11T15:27:02Z, attaches 17 assets including `SKILL.md` (20678 bytes) and `SKILL.md.sigstore.json` — checked against the live releases API before anything here was edited, not inferred from the workflow. `v0.3.1` was checked too and attaches exactly 15, which is what makes the older-tag note below a fact rather than a hedge. So the disclosure, the test, and `ASSET_PENDING_NOTICE` / `ASSET_PENDING_FIRST_TAG` all go, in one commit, as that constant required. What the deleted test also guarded is not lost: that `release.yml` still stages the asset is asserted by `replay()` itself, which every counting test runs through, and a comment where the test stood records why it left. The prose was rewritten, not merely cut, because deleting cleanly and reading correctly are different things. Steps 3, 5 and 6 were documented as "not runnable against a published tag, substitute a platform tarball"; they run against `SKILL.md` itself now, and the runnability table that existed only to say so is gone. Section 2 of docs/skill.md is no longer prefaced "read this whole section in the future tense", and the "a release publishes 17 assets" claim no longer carries an aspirational qualifier — it is simply true. Both worked examples move from `TAG=v0.3.1` to `TAG=v0.4.0` so the recipe is copy-pasteable end to end; nothing else in the tree bound that string. The one true thing the old section said survives under a heading that no longer reads as an apology — **Before you start: which tags the recipe runs against** — because `v0.3.1` and earlier really do attach 15 files and really do need a tarball substituted. Worth knowing for the next person: `cargo test` passed with a leftover the acceptance run caught only under clippy. `AGENTS_MD` in tests/skill_docs.rs existed solely for the deleted test, and dead code is a warning to `cargo test` and an error to `clippy -D warnings`. Run all three commands, not just the suite. Measured under the isolation prefix CLAUDE.md mandates, with `--no-fail-fast` because cargo otherwise stops at the first failing binary and never reaches tests/skill_docs.rs at all — which is how a baseline can look like 839/14 when it is really 988/33. Before: 988 passed / 33 failed. After: 987 passed / 33 failed, the failure set byte-identical by diff, and the single missing pass is exactly the deleted test by name. tests/skill_docs.rs goes 38 → 37 and every other binary is unchanged. The 33 failures are pre-existing and environmental — sast (opengrep/semgrep), scan (trivy/osv), sbom, grype, oras, cosign, slsa-verifier, dtrack and the registry typosquat lookups, all of which want scanner binaries or network egress this sandbox does not provide. None of them reads a documentation surface. `cargo fmt --check` and `cargo clippy --all-targets --locked -- -D warnings` are both clean. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
p4gs
force-pushed
the
docs/skill-asset-published
branch
2 times, most recently
from
September 11, 2026 16:03
2fc0dc0 to
ea1a3c1
Compare
3 of 6 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
release.ymlhad staged and signedSKILL.mdfor several releases, but noPUBLISHED tag carried it. A reader who ran the recipe's step 3 verbatim got
no such file or directoryfrom an otherwise-working document and reasonablyconcluded the mistake was theirs, so four surfaces —
docs/skill.md,README.md,templates/skills/sscsb/SKILL.mdandAGENTS.md— each disclosedthe gap, and
every_surface_showing_the_recipe_discloses_that_the_asset_is_not_published_yetheld the sentence on all four so it could not be forgotten. That test carried
its own removal instructions in a
WHEN_TO_DELETEconstant, and #67's owncommit message repeats them as the follow-up for whoever cut the release.
The precondition is met.
v0.4.0, published 2026-09-11T15:27:02Z, attaches17 assets including
SKILL.md(20678 bytes) andSKILL.md.sigstore.json—read off the live releases API before anything here was edited, not inferred
from the workflow.
v0.3.1was checked the same way and attaches exactly 15,which is what makes the older-tag note below a fact rather than a hedge.
So the disclosure, the test, and the
ASSET_PENDING_NOTICE/ASSET_PENDING_FIRST_TAGconstants all go, in one commit, as that constantrequired. What the deleted test also guarded is not lost: that
release.ymlstill stages the asset is asserted by
replay()itself, which every countingtest runs through, and a comment where the test stood records why it left.
The prose was rewritten, not merely cut
Deleting cleanly and reading correctly are different things.
substitute a platform tarball". They run against
SKILL.mditself now, andthe runnability table that existed only to say so is gone.
docs/skill.mdis no longer prefaced "read this whole section in thefuture tense".
aspirational qualifier — it is simply true, so the ordering guard that forced
it to be hedged at or before first use has nothing left to enforce.
TAG=v0.3.1toTAG=v0.4.0so the recipe iscopy-pasteable end to end. Nothing else in the tree bound that string.
longer reads as an apology — Before you start: which tags the recipe runs
against — because
v0.3.1and earlier really do attach 15 files and reallydo need a tarball substituted.
templates/skills/sscsb/SKILL.mdand.claude/skills/sscsb/SKILL.mdare heldbyte-identical by
tests/skill_docs.rs; both carry the same edit andcmpagrees.
What to check
Measured under the isolation prefix
CLAUDE.mdmandates, with--no-fail-fast— cargo otherwise stops at the first failing binary and never reaches
tests/skill_docs.rsat all, which is how a baseline can look like 839/14 whenit is really 988/33.
origin/main)The failure set is byte-identical by
diff, and the single missing pass isexactly
every_surface_showing_the_recipe_discloses_that_the_asset_is_not_published_yetby name —
commover the two runs' passing-test lists returns that one line andnothing else.
tests/skill_docs.rsgoes 38 → 37; every other binary isunchanged.
The 33 failures are pre-existing and environmental:
sast(opengrep/semgrep),scan(trivy/osv),sbom,grype,oras,cosign,slsa-verifier,dtrackand the registry typosquat lookups — all of which want scannerbinaries or network egress the sandbox does not provide. None reads a
documentation surface. They are the same 33 on
main.cargo fmt --checkandcargo clippy --all-targets --locked -- -D warningsare both clean.
One thing worth knowing
cargo testpassed with a leftover that only clippy caught.AGENTS_MDintests/skill_docs.rsexisted solely for the deleted test, and dead code is awarning to
cargo testand an error toclippy -D warnings. Running only thesuite would have shipped it.