Skip to content

docs: SKILL.md is a release asset now, so the hedge saying it is not comes out - #69

Merged
p4gs merged 1 commit into
mainfrom
docs/skill-asset-published
Sep 11, 2026
Merged

p4gs merged 1 commit into
mainfrom
docs/skill-asset-published

Conversation

@p4gs

@p4gs p4gs commented Sep 11, 2026

Copy link
Copy Markdown
Owner

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, and #67's own
commit 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, attaches
17 assets including SKILL.md (20678 bytes) and SKILL.md.sigstore.json —
read off the live releases API before anything here was edited, not inferred
from the workflow. v0.3.1 was 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_TAG constants 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

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.
  • §2 of docs/skill.md is no longer prefaced "read this whole section in the
    future tense"
    .
  • The "a release publishes 17 assets" claim no longer carries an
    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.
  • 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.

templates/skills/sscsb/SKILL.md and .claude/skills/sscsb/SKILL.md are held
byte-identical by tests/skill_docs.rs; both carry the same edit and cmp
agrees.

What to check

Measured under the isolation prefix CLAUDE.md mandates, with --no-fail-fast
— 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.

passed failed
before (origin/main) 988 33
after 987 33

The failure set is byte-identical by diff, and the single missing pass is
exactly every_surface_showing_the_recipe_discloses_that_the_asset_is_not_published_yet
by name — comm over the two runs' passing-test lists returns that one line and
nothing else. tests/skill_docs.rs goes 38 → 37; 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 the sandbox does not provide. None reads a
documentation surface. They are the same 33 on main.

cargo fmt --check and cargo clippy --all-targets --locked -- -D warnings
are both clean.

One thing worth knowing

cargo test passed with a leftover that only clippy caught. 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. Running only the
suite would have shipped it.

…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
p4gs force-pushed the docs/skill-asset-published branch 2 times, most recently from 2fc0dc0 to ea1a3c1 Compare September 11, 2026 16:03
@p4gs
p4gs merged commit 8cad3f0 into main Sep 11, 2026
20 checks passed
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