agentleFS
Sign inStart free
seo-skillsseo-skills/geo-audit-skill/CLAUDE.md

geo-audit-skill

CLAUDE.md4 starsChanged 53 days agoMITView on GitHub

Guidance for Claude Code when working in this repository. A GEO (Generative Engine Optimization) audit toolkit: a deterministic Python CLI (geo, PyPI seomator-geo-audit) plus thin Claude Code skills that call it. The skills narrate; the CLI computes. The invariant everything else serves: no number reaches a user that did not come from the scorer. If a change makes a score depend on model output, it is the wrong change. All three, every time. CI runs exactly these on three operating…

The file

We split this CLAUDE.md into the rules it gives an agent

4 rules. About 0 are common, 3 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    The invariant everything else serves: no number reaches a user that did not come from the scorer.

    line 11
  2. Distinctive:

    All three, every time. CI runs exactly these on three operating systems.

    line 39
  3. Distinctive:

    Nothing is modified at install time: No shebang rewriting, no generated files in the install step.

    line 56
  4. Very specific:

    Not built without amending the project document first: multi-host generation, cross-machine sync, telemetry, consent flows, update checks, …

    line 76

≈ “Common” is an estimate: at least 1 in 5 of the 26,980 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

CLAUDE.md

Guidance for Claude Code when working in this repository.

What this is

A GEO (Generative Engine Optimization) audit toolkit: a deterministic Python CLI (geo, PyPI seomator-geo-audit) plus thin Claude Code skills that call it. The skills narrate; the CLI computes.

The invariant everything else serves: no number reaches a user that did not come from the scorer. If a change makes a score depend on model output, it is the wrong change.

Layout

PathContents
src/geo_audit/cli.pyArgument parsing, output mode, the exit-code decision. The only place that decides how a run ends.
src/geo_audit/commands/One module per command. Each returns an envelope and raises GeoError; none calls sys.exit or prints to stdout.
src/geo_audit/lib/Shared helpers, each existing exactly once: http, net, extract, robots, evidence, headers, ids, slug, browser.
src/geo_audit/scoring/model.py holds the signal types and the composite arithmetic; category modules hold the signals.
src/geo_audit/data/Weights, thresholds, tiers, crawler tokens, finding copy. Constants live here, not in code and not in prose.
src/geo_audit/copy.pyLiteral user-facing sentences. Golden tests assert them.
skills/<name>/SKILL.mdOne skill per directory, with sections/*.md loaded on demand.
skills/_shared/response-contract.mdThe block every skill embeds byte-identically.
tools/lint_skills.pySkill contract enforcement, including the key manifest.
tools/gen_docs.pyGenerates docs/commands.md and the marker regions in concept docs.
tests/fixtures/site/Synthetic fixture pages, authored here. Never captured from the web.

Before claiming anything works

.venv/bin/python -m pytest
.venv/bin/python tools/lint_skills.py
.venv/bin/python tools/gen_docs.py --check

All three, every time. CI runs exactly these on three operating systems.

Rules that are easy to break by accident

  • Constants go in data/. A threshold hardcoded in a scorer is a bug even when the number is right, because data_version stops describing the score.
  • A signal that could not be computed returns None, never 0. The composite divides by the max of the computed signals so that a missing capability lowers completeness rather than the score.
  • CLI output never contains page text. Derived signals, counts, and excerpts capped at 280 characters with backticks and angle brackets escaped. tests/ test_output_boundary.py enforces the rule; do not weaken it to make a report richer.
  • One helper, one home. Upstream's duplicated DEFAULT_HEADERS and duplicated block extraction are the failure mode this layout exists to prevent.
  • Skills reference no file paths. Templates and data are reached through CLI commands, which is what makes the shipped artifact equal the tested one.
  • Nothing is modified at install time. No shebang rewriting, no generated files in the install step.
  • No market statistics in prompts or CLI output. The skill lint rejects them. Market context belongs in docs, with a source and a date.

When editing a skill

The response-contract block between <!-- geo:response-contract:begin --> and <!-- geo:response-contract:end --> must stay byte-identical to skills/_shared/response-contract.md. Every backticked identifier must be one the CLI emits. Both are enforced by tools/lint_skills.py, which fails the build.

Versioning

VERSION is the single source; pyproject.toml, _version.py, both plugin manifests and every skill frontmatter must match it. The four contract versions (schema, scoring, data, normalizer) move independently and appear in every envelope.

Cut list (binding)

Not built without amending the project document first: multi-host generation, cross-machine sync, telemetry, consent flows, update checks, a self-update or data-update channel separate from PyPI, shell installers and ownership manifests, a SKILL.md template generator, crawl resume, alias and forwarding skills.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free