Repository navigation
Give the Pages site real metadata, and put claim_auditor back on it - #2
Merged
Merged
Conversation
The repository description, the README and the Pages site each kept their own
copy of the same facts, with nothing keeping them in agreement. They now come
from one file, .github/repository-metadata.yml, and .github/seo/seo.py
generates the rest: the <head> block and resource links in docs/index.html, a
facts block in the README, robots.txt, sitemap.xml, and the IndexNow key file.
The generator only rewrites regions between seo:*:begin / seo:*:end markers and
refuses to run when a marker is missing, so hand-written prose is never
restructured.
Validation is about truth rather than shape: canonical_url has to be this
repository's real Pages URL, topics have to meet GitHub's format and describe
the software rather than praise it, runnable_scripts has to equal the number of
CLIs actually present in scripts/, and content_updated has to be a real date
that is not in the future. `verify` then checks the built output -- one
non-duplicate title, a self-referencing canonical that og:url agrees with, a
1280x640 og:image that exists, JSON-LD that parses, sitemap URLs that match the
manifest, and internal links that resolve to real files.
Two things this repository claims are now enforced rather than asserted:
- network_surfaces is [], and `verify` fails if any script under scripts/
starts making network calls. The "zero dependencies, nothing phones home"
claim in the README is checked on every push.
- runnable_scripts is 7. The Pages site listed six tools and omitted
claim_auditor.py entirely, which the sibling repositories both run in CI to
audit their documentation against their code. It is on the page now.
The primary search phrase is "Claude Agent Skill validator", used once each in
the title, the opening line, one heading and the repository description, rather
than the vaguer "QA skill for Claude skills" the title carried before.
Deployment moves from branch-serving to Actions so those gates can block a bad
deploy, and so IndexNow is notified only after a deploy actually succeeds --
and only when content_updated moved, which keeps restyles from spending crawl
budget. Every third-party action is pinned to a full-length SHA and permissions
default to contents: read.
Two assets still need a human: the Google Search Console and Bing verification
files, which need tokens only the account holder can obtain. `verify` warns
until they are committed, and .github/seo/README.md says exactly where they go.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…ling Adding .github/seo/seo.py to this repository made claim_auditor report five contradictions against skill-vision itself, and none of them were real. Among them: the CI badge line at the top of the README, and a paragraph in references/skill-structure-specification.md that describes what the Agent Skills spec requires of any skill rather than saying anything about this one. The cause is scope. A reach claim like "every script runs offline" is a claim about what the skill does when a user invokes it. Claude cannot invoke anything under .github/ -- allowed-tools reaches scripts/ -- so workflow and release tooling is not part of the surface those claims describe. Auditing prose against it produces findings with no honest fix: a repository whose CI talks to an API would have to caveat every offline sentence it contains, including sentences about someone else's software. That is the false-positive failure mode this file's own docstring calls out as being as bad as a false negative, because it is what teaches people to stop reading the output. .github/ now joins __pycache__, .git, tests/ and test_*.py in the set of paths that are in the repository but are not the skill. A networked script under scripts/ is still caught; there is a test for each direction so the exclusion cannot quietly widen. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The generator was more machinery than three single-page static sites justify,
and shipping it in every repository put a networked script inside the skill
bundle -- which set off this repository's own claim_auditor against five
sentences, none of them actually wrong. Removed: .github/seo/seo.py, the Pages
deploy workflow, the drift workflow, and the IndexNow key file. The exclusion
added to claim_auditor.py to work around it is reverted too; with nothing
networked in the tree it has nothing to work around.
What is kept is what the exercise actually found:
- The Pages site listed six tools and omitted claim_auditor.py, which both
sibling repositories run in CI to audit their documentation against their
code. Seven scripts, seven rows.
- "the QA skill for Claude skills" describes the software in words nobody
searches for. The title, the opening line, one heading and the repository
description now say "Claude Agent Skill validator" -- once each.
- Topics: best-claude-skills and must-have-skills promote rather than
describe, which is not what GitHub topics are for; codebase-mapping and
mermaid-codebase duplicated codebase-map and mermaid. Sixteen left, all
naming something the software does.
The page keeps a static <head>: one descriptive title, a distinct meta
description, a self-referencing canonical that og:url matches, Open Graph tags,
a 1280x640 social preview, and honest SoftwareSourceCode JSON-LD. Plain HTML,
nothing generating it.
.github/repository-metadata.yml stays, with a header saying plainly what it now
is: a record rather than a checked contract. Nothing reads it. It exists so the
next change to the description, topics or page metadata has one file to consult.
Adds .claude/ to .gitignore.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
AlveeeRahman
changed the title
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.
Gives the Pages site proper metadata and fixes what it was getting wrong. No new tooling, no new workflows.
The corrections
claim_auditor.pywas missing from the Pages site. It listed six tools; there are seven. The omitted one is the tool both sibling repositories run in their own CI to audit documentation against code — an odd one to leave off the page that sells the suite.best-claude-skillsandmust-have-skillspromote rather than describe, which is not what GitHub topics are for;codebase-mappingandmermaid-codebaseduplicatedcodebase-mapandmermaid. Sixteen remain, each naming something the software does.The Pages site
docs/index.htmlgets a proper static<head>: a descriptive title carrying the primary phrase, a distinct meta description, a self-referencingrel="canonical"thatog:urlmatches, Open Graph tags, a 1280×640 social preview, and honestSoftwareSourceCodeJSON-LD. Plain HTML — nothing generates it.Also adds a project-resources block linking releases, the security policy, the contributing guide, the sample skill and the expected validator output.
Also here
.github/repository-metadata.yml— a plain record of the canonical URL, primary phrase, description, topics, supported Python, script count and network surfaces ([], since nothing here opens a connection). Its header says plainly that nothing reads it and no CI job enforces it; it exists so the next change has one file to consult..claude/added to.gitignore.docs/assets/social-preview.svgis the editable source for the PNG.scripts/andtests/are untouched — all 196 tests still pass.Applied outside this PR
The repository description, homepage (was empty) and topics are already updated on github.com to match.
Still needs a human
Upload
docs/assets/social-preview.pngat Settings → General → Social preview. GitHub exposes no API for it, so it is the one step that cannot be scripted.🤖 Generated with Claude Code