Skip to content

Universal SEO skill for Claude Code. 26 sub-skills + 19 sub-agents covering technical SEO, E-E-A-T, schema, GEO/AEO, agent readiness (Lighthouse Agentic Browsing, WebMCP, llms.txt), backlinks, local SEO, e-commerce, international SEO, Google APIs, and PDF/Excel reporting. 9 optional extensions for live SEO data.

docs: alt text is descriptive, not a keyword slot; tag verification steps

Agrici Danielc88337f64f67
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 3867caa..7a74462 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -63,8 +63,9 @@ jobs:
- name: Run pytest
env:
- # The live GitHub API tests run on one leg only, so the matrix does
- # not triple the calls. gh honors GH_TOKEN, which keeps sync_flow.py
+ # The live GitHub API tests run on the 3.10 leg only, so the matrix
+ # does not triple the calls (the portability job also runs them on
+ # Windows and macOS). gh honors GH_TOKEN, which keeps sync_flow.py
# clear of the anonymous 60/hr per-IP rate limit on shared runners.
CLAUDE_SEO_NETWORK_TESTS: ${{ matrix.python-version == '3.10' && '1' || '' }}
GH_TOKEN: ${{ github.token }}
diff --git a/SECURITY.md b/SECURITY.md
index 888340f..ada2946 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -47,7 +47,7 @@ claude-seo is a research and audit toolkit that runs on a user's workstation. It
2. **Tampered install.** A modified plugin install, GitHub release, or manual install script could deliver altered files. Plugin install is the default path; `curl ... | bash` is the legacy/manual path, so signature verification of release artifacts remains a defence-in-depth concern.
- **Mitigation status:** SHA-256 manifest tooling (`scripts/release_sign.py`, `scripts/verify_release.py`) shipped in v2.0.0, but the install scripts do not verify a manifest yet and releases do not attach one. Installer verification is planned for v2.5.0. Until then, install by cloning the release tag explicitly (`git clone --branch vX.Y.Z`), check the tag signature with `git tag -v vX.Y.Z`, and inspect the diff against the previous release.
+ **Mitigation status:** SHA-256 manifest tooling (`scripts/release_sign.py`, `scripts/verify_release.py`) shipped in v2.0.0, but the install scripts do not verify a manifest yet and releases do not attach one. Installer verification is planned for v2.5.0. Until then, install by cloning the release tag explicitly (`git clone --branch vX.Y.Z`), check the tag signature, and inspect the diff against the previous release. Release tags are SSH-signed. To verify one locally, put the maintainer's signing key from `https://api.github.com/users/AgriciDaniel/ssh_signing_keys` in an allowed-signers file as `[email protected] namespaces="git" <key>`, then run `git -c gpg.ssh.allowedSignersFile=<file> tag -v vX.Y.Z` and look for `Good "git" signature`.
3. **Local privilege escalation against stored credentials.** The OAuth token at `~/.config/claude-seo/oauth-token.json` is the most sensitive on-disk artifact.
diff --git a/skills/seo-content-brief/SKILL.md b/skills/seo-content-brief/SKILL.md
index 90c0d5b..53e6908 100644
--- a/skills/seo-content-brief/SKILL.md
+++ b/skills/seo-content-brief/SKILL.md
@@ -108,7 +108,8 @@ Read `references/keyword-density.md` for the full rules. Summary:
3. URL slug
4. Meta description
5. First paragraph / first 100 words
-6. At least one image alt text
+
+Image alt text describes the image; it is not a required keyword placement.
**Primary keyword does NOT need to appear in:**
- Every H2 or H3 (subtopics carry context naturally if H1 covers it)
diff --git a/skills/seo-content-brief/references/keyword-density.md b/skills/seo-content-brief/references/keyword-density.md
index 4a0edd0..ea759f2 100644
--- a/skills/seo-content-brief/references/keyword-density.md
+++ b/skills/seo-content-brief/references/keyword-density.md
@@ -27,7 +27,8 @@ The primary keyword MUST appear in all of these:
3. **URL slug** (lowercase, hyphenated)
4. **Meta description** (naturally integrated)
5. **First paragraph / first 100 words** (establishes topic immediately)
-6. **At least one image alt text** (reinforces topic for image search)
+
+Image alt text is not on this list. Write it to describe the image; the topic appears there only when the image actually shows it.
## Locations Where It Is NOT Required
@@ -56,5 +57,5 @@ The primary keyword MUST appear in all of these:
1. **Exact-match obsession:** Using the exact phrase every time instead of natural variations. Google understands synonyms and related terms.
2. **Heading stuffing:** Putting the primary keyword in every H2 and H3. One H1 mention plus 1-2 H2 mentions is sufficient.
3. **Ignoring first 100 words:** The opening paragraph is the highest-value placement after the title and H1.
-4. **Forgetting image alt text:** A free placement opportunity that also helps image search rankings.
+4. **Forgetting image alt text:** Every meaningful image needs descriptive alt text that names its subject. It helps accessibility and image search; it is not a keyword slot.
5. **Counting density at all:** "Web design", "website design", and "site design" all describe the same topic. Judge whether the page covers the topic clearly, not how often one exact string appears.
diff --git a/skills/seo-page/SKILL.md b/skills/seo-page/SKILL.md
index c0b2df1..8ab3e22 100644
--- a/skills/seo-page/SKILL.md
+++ b/skills/seo-page/SKILL.md
@@ -53,7 +53,7 @@ metadata:
- Never recommend HowTo (deprecated) or FAQ for rich results (retired May 2026); existing FAQPage need not be removed, use QAPage for genuine Q&A
### Images
-- Alt text: present, descriptive, includes keywords where natural
+- Alt text: present and descriptive, naming the image's subject; the topic appears only where it naturally fits
- File size: flag >200KB (warning), >500KB (critical)
- Format: recommend WebP/AVIF over JPEG/PNG
- Dimensions: width/height set for CLS prevention