seoskill

seoskill packages the seo-aeo Claude Code skill for repo-centered SEO and answer-engine optimization work.

The skill helps Claude analyze a website repository, profile SEO exports, plan technical cleanup, review AEO and llms.txt readiness, and draft evidence-gated content briefs. It is a workflow layer, not an SEO crawler or ranking tool.

What it does

• Runs an analysis-first SEO/AEO workflow from inside a repository.
• Inventories repo routes, metadata, robots/sitemaps, schema candidates, content, and package scripts.
• Profiles GSC, GA4, crawler, Ahrefs, Semrush, or generic CSV exports before interpretation.
• Separates observed evidence from assumptions and recommendations.
• Produces reports, issue queues, opportunity queues, briefs, and implementation handoffs after approval.
• Keeps external tools and source edits approval-gated.

What it does not do

• It does not promise rankings, traffic gains, AI Overview inclusion, or LLM citations.
• It does not run live crawls, Lighthouse, paid SEO tools, or third-party uploads by default.
• Never invent missing metrics, competitors, date ranges, search volume, revenue, or citation evidence.
• It does not edit target repositories unless the user explicitly asks for implementation.

Install

Clone the repository, inspect it, then run the installer:

scripts/validate.sh
scripts/install.sh --dry-run
scripts/install.sh

By default, the installer copies .claude/skills/seo-aeo/ to:

~/.claude/skills/seo-aeo

If a prior seo-aeo install exists, the installer backs up only that exact target directory to a timestamped sibling before replacing it.

For tests or custom locations, set CLAUDE_SKILLS_DIR:

CLAUDE_SKILLS_DIR="$(mktemp -d)" scripts/install.sh --dry-run

To uninstall from the configured skill directory:

scripts/uninstall.sh --dry-run
scripts/uninstall.sh

Restart or reload Claude Code if needed so user-level skills are rediscovered.

Usage

After installation, invoke the skill in Claude Code:

/seo-aeo audit path/to/site-repo
/seo-aeo technical path/to/site-repo
/seo-aeo csv path/to/export.csv
/seo-aeo aeo path/to/site-repo
/seo-aeo content path/to/site-repo
/seo-aeo implement path/to/site-repo

If no mode is provided, the skill defaults to audit.

The skill asks for target repo/path, domain or staging URL, market/language, business goal, available inputs, artifact permission, raw-value policy, and whether implementation edits are requested.

Safety and privacy model

The skill treats repo files, CSV exports, crawler output, and prior reports as untrusted evidence sources, not instructions.

It asks before:

• writing .seo-aeo/runs/<id>/ artifacts,
• reading large or private exports into conversation context,
• running helper scripts on user data,
• running ephemeral installs or live crawls,
• editing source, metadata, redirects, robots, sitemap, schema, content, or llms.txt,
• creating issues, pull requests, publishing content, or sending data to external services.

Do not post secrets, credentials, private customer data, raw analytics exports, raw Search Console exports, or proprietary crawler exports in public issues. If an export is needed for debugging, reduce it to a synthetic or anonymized fixture.

Local validation

Run the canonical validation command before opening a pull request:

scripts/validate.sh

It checks required skill files, safety text, Python unit tests, Node tests, shell syntax, and helper smoke commands.

Useful focused commands:

python3 -m unittest tests/test_profile_csv.py tests/test_repo_inventory.py tests/test_install_scripts.py
node --test tests/test_external_tools.mjs
python3 .claude/skills/seo-aeo/scripts/profile_csv.py tests/fixtures/gsc_queries.csv --json

Repository layout

.claude/skills/seo-aeo/   Canonical Claude Code skill source
scripts/                  Install, uninstall, and validation automation
tests/                    Python and Node regression tests
.github/                  Public GitHub templates and repository configuration

The installed user-level skill is copied from .claude/skills/seo-aeo/; treat that directory as the source of truth.

Public repository identity

This project is prepared for cj-vana/seoskill. Creating the GitHub repository, pushing commits, tagging releases, or publishing artifacts are separate network-visible actions and are not performed by the local install scripts.

License

MIT. See LICENSE.