Restructure skills as operating guides, verify July 2026 versions, add CI validation - #11
Merged
Merged
Conversation
Replace the reference to a bundled PDF that was never in the repo with links to Anthropic's online copy of the Complete Guide to Building Skills for Claude, plus the Skill authoring best practices docs. Point the Agent Skills and API links at their current canonical URLs (claude.com / platform.claude.com) instead of relying on redirects.
The skills described their technologies accurately but did not tell Claude how to do a job with them. Each one now covers the full procedure. Add to every skill: - Scope, with explicit exclusions. The four lakehouse skills named each other as triggers with no stated boundary, so a single question could pull in several at once. - Inspect First, replacing the old How To Use triage. Says what evidence to gather from the actual environment before recommending changes. - Safety, with concrete stop conditions instead of general caution. Covers the operations that destroy data: Iceberg orphan file removal against in-flight writes, Flink --allowNonRestoredState silently dropping state, compose down -v, Paimon snapshot expiry, Lance version cleanup. - Verify, defining observable completion. Previously no skill said how to prove the work succeeded. Rewrite descriptions to lead with capability and carry task and problem vocabulary rather than noun keyword lists, so activation matches how users actually phrase requests. Trim design rules that restate what a capable model already knows, funding the additions above. Version facts and update checklists are unchanged; they are still unverified for July. Add license: MIT to frontmatter.
Checks the structural rules the catalogue relies on: frontmatter parses as YAML, name matches its directory and is kebab case, description is within the 1024 character limit, required sections are present, SKILL.md stays under 500 lines, relative links resolve, no stray auxiliary files, no duplicate names, and the README table matches the skills on disk. The YAML check matters most. Descriptions now lead with verb phrases full of commas and colons, and an unescaped colon silently breaks discovery for the whole skill. Runs as a standalone script so contributors can check locally before opening a pull request, with CI running the same command.
Every claim checked against primary sources: project download pages, ASF dist, git tags, Maven Central, PyPI, Docker Hub, and the ASF committee registry. Corrections, not a blanket date bump. Fluss: graduated to a Top-Level Project on 15 July 2026 under Jark Wu, so it is no longer incubating. The Docker image was also wrong in a way that breaks on contact: fluss/fluss:0.9.1 does not exist and that repository is abandoned at 0.7.0 from June 2025. Correct image is apache/fluss:0.9.1-incubating, suffix included, with no latest tag. Flink: 2.3.0 shipped 25 June, 1.20.5 is the LTS, and 2.1.3 replaced 2.1.2. The Kubernetes Operator and Flink CDC both still top out at 2.2.x, so the greenfield recommendation now depends on whether either is in scope rather than defaulting to newest. Lance: two majors behind. Lance is 9.0.0, LanceDB Python is 0.36.0, the repository moved to lance-format/lance, and the Python floor is 3.10 not 3.9. Records the python-v* versus bare v* tag collision, since a bare v0.33.0 published 28 July is the Node client and will mislead the next person who checks. Paimon: 1.4.2 is stable. Notes that the project publishes no GitHub Releases, and says explicitly why Flink 2.3 is excluded. Docker Compose: Compose v5 is now a supported line alongside v2, current v5.3.1, so the V2-specific framing is gone. Adds pre_start for init containers. Postgres 18 and Redis 8 confirmed still current. Iceberg: engine v3 support was overstated. AWS is GA only for deletion vectors and row lineage on Spark-based services, and Athena does not support v3 at all. Iggy: all claims confirmed. Adds SDK and component image versions, which diverge sharply from the server version.
Firn covers the object-storage-backed vector and full-text search engine, including its split between the firnflow-api server and the embedded Python interface. Also retitles the Docker Compose README entry, since Compose v5 is now a supported line alongside v2.
Versions were already correct (server 0.9.4, Python 0.2.1). These are gaps found while verifying, each checked against the repository, its issues, or the package registries. Correctness, the two that can silently produce wrong results: - On 0.9.3 and earlier, a now()-style filter predicate is cached by its text while the cutoff it describes moves, so recency queries replay the first result set until the next write. Fixed in 0.9.4. - /upsert was an unconditional append before 0.9.0, so older namespaces can carry duplicate ids, and merge-insert into a target with duplicates is undefined behaviour in Lance. Upgrading does not dedupe. Backend support: Backblaze B2 fails because its S3 gateway returns 501 on If-None-Match, which is the compare-and-swap the commit path depends on. R2, Tigris and Spaces need path-style addressing. Also records that firnflow.io still advertises 0.5.0 while the code is at 0.9.4, so the website is not a usable source; the unindexed brute-force cost of roughly 25s p50 against roughly 979ms indexed; the ~250x multivector storage multiplier; the single-node limit; and that text or hybrid queries against a namespace with no FTS index return 500.
gordonmurray
force-pushed
the
update-skills-july-2026
branch
from
July 29, 2026 20:34
3a85afc to
5ad8ffb
Compare
Both issues raised in review of #11. pre_start was recommended unconditionally while the skill also treats Compose v2 as supported, so a v2 user following it would generate an invalid file. The key needs v5.3.0 or newer. Authoring rules now gate it on the CLI version and keep the one-shot init service plus service_completed_successfully as the v2 answer. Inspect First reads the version for that decision rather than only checking it is not V1, and the recent-additions list carries the version each key requires. The stray-file check only matched four hardcoded names, so notes.md, draft.py or tmp.txt passed while the PR claimed stray files were caught. Replaced with an allowlist: SKILL.md plus references/, scripts/ and assets/. Contents of those directories are not policed by name, and dotfiles are skipped as tooling. Verified against a fixture: the three filenames from the review and an unexpected directory all fail, while a skill with populated resource directories and a .gitkeep passes.
restart: on-failure[:max-retries] was swept into a blanket "none are available on Compose v2" line. Docker documents the restart policy with no version requirement, and the retry limit is long-standing; the February 2026 change was spec wording, not a new capability. Splits it out and records the full accepted value set, leaving the version gate on pre_start, build.no_cache_filter, and start --wait, which are genuinely v5-only.
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
1 participant
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.
Turns the catalogue from accurate reference articles into operating guides, verifies every version claim against primary sources, and adds CI so the structure cannot silently rot.
Restructure (
5a1cb18)The skills described their technologies well but never said how to do a job with one. Each now carries
Scopewith explicit exclusions,Inspect First,Safety, andVerify, alongside the existing facts and update checklist.Scopefixes a real problem: the four lakehouse skills all named each other as triggers with no stated boundary, so one question could pull in several at once.Safetyreplaces general caution with stop conditions on the operations that actually destroy things, such as Iceberg orphan file removal against in-flight writes, Flink--allowNonRestoredStatesilently dropping state, andcompose down -v.Verifywas absent everywhere; no skill previously said how to prove the work succeeded.Descriptions were noun-heavy keyword lists and now lead with capability and carry problem language, so a request like "my Iceberg reads got slow after the streaming job" matches. Generic rules a capable model already knows were cut to fund the additions.
Version verification (
03f6d2f,3a85afc)Checked against download pages, ASF dist, git tags, Maven Central, PyPI, Docker Hub, and the ASF committee registry. Corrections, not a date bump.
Three findings that would have cost someone real time:
fluss/fluss:0.9.1is not a real tag; that repository is abandoned at 0.7.0 from June 2025. Correct image isapache/fluss:0.9.1-incubating, suffix included.now()-style filter is cached by predicate text while the cutoff moves. Separately,/upsertwas an unconditional append before 0.9.0, and upgrading does not retroactively dedupe.Also: Iceberg overstated AWS v3 support and wrongly implied Athena has it; Flink 2.3.0 shipped but the Kubernetes Operator and CDC still top out at 2.2.x, which inverts the greenfield advice; Lance was two majors behind with the Python floor wrong at 3.9; Paimon is at 1.4.2; Compose has a v5 line now. Iggy needed no corrections.
CI validation (
8f05d56).github/scripts/validate_skills.pychecks frontmatter parses as YAML, name matches directory, description length, required sections, file size, relative links, duplicate names, stray auxiliary files, and README coverage.Built as a standalone script so it runs locally before a PR, not just in CI. Tested against a fixture of nine deliberately broken skills; every failure class is caught with a specific message and exit 1.
The YAML check earns its place: the new descriptions are dense with commas and colons, and an unescaped colon is valid-looking text that silently breaks discovery for an entire skill.
Also
Firn is added to the catalogue and the README table. README links now point at current canonical
claude.comURLs, and the stale reference to a PDF that was never in the repo is replaced with Anthropic's hosted copy.