@piramilan/seo-expert 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,66 @@
+# Changelog
+
+All notable changes to the SEO Expert skill are documented here.
+
+This project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] — 2026-05-13
+
+One-line install via `npx`. Same skill content as 0.1.0; new way to deliver it.
+
+### Added
+- `package.json` — npm package metadata. Published as `@piramilan/seo-expert` to the public registry.
+- `bin/seo-expert.js` — zero-dependency Node CLI. Drives:
+  - `npx @piramilan/seo-expert install <tool>` for file-based installs (Cursor, Cline, Windsurf, Aider, continue.dev, Claude Code)
+  - `npx @piramilan/seo-expert copy <tool>` for clipboard-based installs (ChatGPT, Claude Project, Gemini, Perplexity)
+  - `npx @piramilan/seo-expert` for the interactive picker
+  - `list`, `info`, `help` subcommands for discovery
+- Existing-file backup on install — any pre-existing `.cursorrules` / `CONVENTIONS.md` / `.clinerules` is renamed to `<file>.bak.<timestamp>` before being overwritten.
+- Cross-platform clipboard support (macOS `pbcopy`, Linux `wl-copy`/`xclip`/`xsel`, Windows `clip`) with a `seo-expert-adapter.md` file fallback when none is available.
+
+### Changed
+- `README.md` rewritten as a one-stop install guide with table of contents, npx primary path, and inline manual paths per AI tool.
+- `INSTALL.md` adds a "Quickest path — one-line npx" section at the top and corrects the manual Claude Code clone path to `~/.claude/skills/seo-expert`.
+- Skill content under `core/`, `adapters/`, `prompts/`, `sources/`, and `SKILL.md` is unchanged from v0.1.0 — `npx @piramilan/seo-expert@0.1.0` and `@0.2.0` ship identical guidance.
+
+### Requirements
+- Node ≥ 18 for the `npx` flow (zero deps, uses only `node:` built-ins).
+- Manual install paths require no runtime — just file copy.
+
+[0.2.0]: https://github.com/Piramilan/seo-expert/releases/tag/v0.2.0
+
+## [0.1.0] — 2026-05-13
+
+Initial public release.
+
+### Added
+- `SKILL.md` — canonical skill definition with frontmatter, six-step universal flow, task → playbook routing table, eight operating principles, six-part output contract, and guardrails.
+- `core/ai-seo-operating-system.md` — audits, AI visibility, measurement, paid-AI-surface guidance.
+- `core/technical-seo.md` — crawl, index, schema, performance, Search Console workflow, citation targeting.
+- `core/content-strategy.md` — briefs, topic clusters, content refresh, visual pipeline, AI-assisted internal linking.
+- `core/local-seo.md` — Google Business Profile, map pack behavior signals, location pages, review acquisition.
+- `core/programmatic-seo.md` — six pattern recipes, validation, monitoring, kill-switch failure modes, "when NOT to go programmatic".
+- `core/video-derived-lessons.md` — generated lessons keyed by 8 topic tags with source links.
+- `prompts/universal-ai-seo-prompts.md` — 9 ready-to-paste prompt templates (audit, page rewrite, content brief, technical, schema, local, programmatic, measurement, authority).
+- `adapters/claude-project-instructions.md` — Claude.ai / Claude Desktop.
+- `adapters/chatgpt-instructions.md` — ChatGPT Custom GPT / Project.
+- `adapters/gemini-gem-instructions.md` — Gemini Gem.
+- `adapters/perplexity-space-instructions.md` — Perplexity Space.
+- `adapters/coding-agent-rules.md` — Cursor / Cline / Windsurf / Aider / continue.dev.
+- `sources/video-index.md` — public source-video metadata index.
+- `INSTALL.md` — per-tool setup walkthrough.
+
+### Principles enforced by all adapters
+- Answer-first structure
+- Entities over keywords
+- Extractability (H2/H3 questions, short paragraphs, tables, FAQ blocks)
+- Source-backed claims
+- AI visibility separated from traditional ranking
+- Conversion outcomes over vanity metrics
+- Diagnose before prescribing
+- Verify, then ship
+
+### Guardrails
+- No bought reviews · no faked engagement · no link farms · no hidden text · no doorway pages · no generated-content spam · no keyword stuffing · no schema mismatched with visible content · no reproduction of raw third-party transcripts
+
+[0.1.0]: https://github.com/Piramilan/seo-expert/releases/tag/v0.1.0

package/INSTALL.md

@@ -0,0 +1,196 @@
+# Install — SEO Expert Skill
+
+Five-minute setup per AI tool. Pick the tool(s) you use; the skill operates the same way in each.
+
+This file is the deep walkthrough. The [README](README.md) has the same content in a more compact form — pick whichever you prefer.
+
+---
+
+## Quickest path — one-line `npx` (Node ≥ 18)
+
+The package ships every adapter and playbook. The CLI either drops the right files into your project / home, or copies the adapter to your clipboard for web-based AI tools.
+
+```bash
+# Interactive menu
+npx @piramilan/seo-expert
+
+# Coding agents (drops the rules file into the current directory)
+npx @piramilan/seo-expert install cursor      # → .cursorrules
+npx @piramilan/seo-expert install cline       # → .clinerules
+npx @piramilan/seo-expert install windsurf    # → .windsurfrules
+npx @piramilan/seo-expert install aider       # → CONVENTIONS.md
+npx @piramilan/seo-expert install continue    # → .continue/seo-expert.md
+
+# Anthropic CLI (installs to ~/.claude/skills/seo-expert/)
+npx @piramilan/seo-expert install claude-code
+
+# Web-based AI tools — copies the adapter to clipboard + prints next steps
+npx @piramilan/seo-expert copy chatgpt
+npx @piramilan/seo-expert copy claude-project
+npx @piramilan/seo-expert copy gemini
+npx @piramilan/seo-expert copy perplexity
+
+# Discovery
+npx @piramilan/seo-expert list
+npx @piramilan/seo-expert info
+npx @piramilan/seo-expert help
+```
+
+**Pin a version for reproducible setups:**
+
+```bash
+npx @piramilan/seo-expert@0.2.0 install cursor
+```
+
+**Safety notes:**
+
+- Existing target files (`.cursorrules`, `CONVENTIONS.md`, etc.) are backed up to `<file>.bak.<timestamp>` before being overwritten.
+- Clipboard copy works on macOS (`pbcopy`), Linux (`wl-copy` / `xclip` / `xsel`), Windows (`clip`). If none are available, the adapter is written to `seo-expert-adapter.md` in the current directory.
+- Zero runtime dependencies — the CLI uses only Node built-ins.
+
+If you can't run Node, skip to the manual path for your tool below.
+
+---
+
+## Claude Code (developers, agencies, anyone using Claude in the terminal)
+
+```bash
+# Clone into the Claude Code skills directory
+git clone https://github.com/Piramilan/seo-expert.git ~/.claude/skills/seo-expert
+```
+
+Then restart Claude Code (or open a new conversation). The skill auto-invokes when you ask SEO questions because of the `description:` in `SKILL.md` frontmatter.
+
+**Test it:**
+```
+audit https://example.com for AI visibility
+```
+
+---
+
+## Claude Project (claude.ai or Claude Desktop)
+
+1. Go to **claude.ai → Projects → New Project**
+2. Open [adapters/claude-project-instructions.md](adapters/claude-project-instructions.md), copy the block under `## Instructions (paste this)`
+3. Paste into the Project's **Custom instructions** field
+4. Upload to the Project's knowledge:
+   - `SKILL.md`
+   - `core/ai-seo-operating-system.md`
+   - `core/technical-seo.md`
+   - `core/content-strategy.md`
+   - `core/local-seo.md`
+   - `core/programmatic-seo.md`
+   - `core/video-derived-lessons.md`
+   - `prompts/universal-ai-seo-prompts.md`
+   - `sources/video-index.md`
+5. Save.
+
+**Test it:** `Audit https://example.com for SEO`
+
+---
+
+## ChatGPT — Custom GPT (Plus/Pro/Team users)
+
+1. Go to **chatgpt.com → My GPTs → Create a GPT → Configure**
+2. Name: `SEO Expert`
+3. Description: `Senior SEO + AI-SEO consultant. Audits, content briefs, page rewrites, schema, local SEO, programmatic SEO, AI visibility.`
+4. Open [adapters/chatgpt-instructions.md](adapters/chatgpt-instructions.md), copy the block under `## Instructions (paste this)` → paste into **Instructions**
+5. **Conversation starters** (copy these into the four starter slots):
+   - `Audit this URL for SEO and AI visibility: `
+   - `Rewrite this page section for AI extractability: `
+   - `Build a content brief for the query: `
+   - `Plan programmatic pages for the pattern: `
+6. **Knowledge** — upload the same 9 files listed in the Claude Project section above
+7. **Capabilities** — enable Web Browsing (lets the GPT fetch URLs you give it). Enable Code Interpreter only if you want it to validate JSON-LD locally.
+8. **Save** → publish to *Only me*, *Anyone with the link*, or *Everyone* (the GPT Store).
+
+**Test it:** start a new chat with the GPT and use one of the conversation starters.
+
+### ChatGPT Project (alternative, simpler, no Custom GPT)
+1. **chatgpt.com → Projects → New Project**
+2. Paste the same instructions block into the Project's instructions
+3. Drop the same 9 files into Project files
+4. Same conversation starters work.
+
+---
+
+## Gemini Gem
+
+1. **gemini.google.com → Gems → New Gem**
+2. Open [adapters/gemini-gem-instructions.md](adapters/gemini-gem-instructions.md), copy the block under `## Instructions (paste this)` → paste into the Gem's instructions
+3. Gems do not accept attached files the way Custom GPTs do. **Embed the playbook content inline:**
+   - Copy the contents of `SKILL.md` and each `core/*.md` into the Gem's instructions, or
+   - Paste the file you need at the start of each conversation (faster for long-context tasks)
+4. Save.
+
+**Test it:** *"Read https://example.com and audit it for SEO and AI visibility."* Gemini will fetch the URL and apply the embedded playbooks.
+
+---
+
+## Perplexity Space
+
+1. **perplexity.ai → Spaces → Create a Space**
+2. Open [adapters/perplexity-space-instructions.md](adapters/perplexity-space-instructions.md), copy the block under `## Instructions (paste this)` → paste into the Space's instructions
+3. Add to the Space library (Perplexity supports `.md`):
+   - `SKILL.md`
+   - All 6 `core/*.md` files
+   - `prompts/universal-ai-seo-prompts.md`
+   - `sources/video-index.md`
+4. Save.
+
+**Why Perplexity is special:** it does live web search and cites every claim. Use it for *current-state* audits where you want fresh evidence (rank tracking, AI-answer surface, competitor backlinks).
+
+**Test it:** *"Audit https://example.com — pull current SERP citations and AI-answer state, then apply the SEO Expert playbook."*
+
+---
+
+## Cursor / Cline / Windsurf / Aider / continue.dev (coding agents)
+
+For agents that edit your repo's marketing pages, schema, sitemaps, or meta tags.
+
+1. In your project root:
+   - **Cursor:** save [adapters/coding-agent-rules.md](adapters/coding-agent-rules.md) as `.cursorrules` (or `.cursor/rules/seo-expert.md`)
+   - **Cline:** save as `.clinerules`
+   - **Windsurf:** save as `.windsurfrules`
+   - **Aider:** save as `CONVENTIONS.md`, then run `aider --read CONVENTIONS.md`
+   - **continue.dev:** copy the block into `.continue/config.json` `systemMessage` or `rules`
+2. (Optional) Vendor the `core/*.md` playbooks into your repo under `docs/seo-expert/core/` so the agent can read depth when needed
+3. Commit and push.
+
+**What it does:** any time the agent edits a `.html`, `.jsx`, `.tsx`, `.mdx`, `.vue`, `.svelte`, `_app.*`, `_document.*`, `Header.*`, `Footer.*`, or `Head.*` file — or `sitemap.xml`, `robots.txt`, `manifest.*` — it automatically applies the SEO Expert defaults (single `<h1>`, schema parity with visible content, canonical, OG, Twitter Card, redirect maps).
+
+**Test it:** ask the agent to *"add SEO meta tags and JSON-LD to the pricing page"*. Confirm the diff matches the Output Contract.
+
+---
+
+## How to verify your install worked
+
+Run this prompt in any installed tool:
+
+> Diagnose, then return the six-part output contract for this URL: `https://example.com`. Skip detailed recommendations — I just want to confirm the skill is wired up.
+
+The response should contain six labeled sections (Diagnosis · Prioritized recommendations · Concrete examples · Verification steps · Risks/assumptions/dependencies · Source references). If any section is missing, the adapter wasn't fully pasted or files weren't uploaded.
+
+---
+
+## Updating
+
+When this repo cuts a new release (see [CHANGELOG.md](CHANGELOG.md)):
+
+- **Claude Code:** `git pull` in the skill directory
+- **Claude Project / ChatGPT GPT / Perplexity Space:** re-upload the changed files
+- **Gemini Gem:** re-paste the changed playbook content
+- **Coding agents:** `git pull` if vendored, or replace the rules file
+
+Pin to a tag (`git checkout v0.1.0`) if you want a stable surface.
+
+---
+
+## Need help?
+
+Open an issue on the repo with:
+- Which AI tool you're installing in
+- What step failed
+- The output you got vs. what you expected
+
+PRs to improve this install guide are welcome.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Milan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,320 @@
+# SEO Expert
+
+> One portable SEO + AI-SEO/GEO skill that works the same way in **Claude**, **ChatGPT**, **Gemini**, **Perplexity**, and coding agents (**Cursor**, **Cline**, **Windsurf**, **Aider**).
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Version](https://img.shields.io/badge/version-0.2.0-green.svg)](CHANGELOG.md)
+[![npm](https://img.shields.io/badge/npm-%40piramilan%2Fseo--expert-red.svg)](https://www.npmjs.com/package/@piramilan/seo-expert)
+[![Skill](https://img.shields.io/badge/skill-seo--expert-purple.svg)](SKILL.md)
+
+A senior SEO + AI-search consultant in skill form. Diagnose before prescribing, return prioritized recommendations against a six-part output contract, and refuse fake-signal tactics. Built on hand-written playbooks plus a corpus of video-derived SEO lessons.
+
+---
+
+## Table of contents
+
+- [What it does](#what-it-does)
+- [Output contract](#output-contract)
+- [Install — one-line `npx` (recommended)](#install--one-line-npx-recommended)
+- [Install — manual paths (no Node required)](#install--manual-paths-no-node-required)
+  - [Claude Code](#claude-code)
+  - [Claude Project / Desktop](#claude-project--desktop)
+  - [ChatGPT (Custom GPT / Project)](#chatgpt-custom-gpt--project)
+  - [Gemini Gem](#gemini-gem)
+  - [Perplexity Space](#perplexity-space)
+  - [Cursor / Cline / Windsurf / Aider / continue.dev](#cursor--cline--windsurf--aider--continuedev)
+- [Verify your install](#verify-your-install)
+- [Update an existing install](#update-an-existing-install)
+- [Repo layout](#repo-layout)
+- [Operating principles](#operating-principles)
+- [Guardrails](#guardrails)
+- [Quick example](#quick-example)
+- [Versioning, contributing, license](#versioning-contributing-license)
+
+---
+
+## What it does
+
+Ask any of the following in your AI tool and the skill auto-routes to the right playbook:
+
+- **SEO audit** of a site, page, or section
+- **Content brief**, topic cluster plan, or editorial calendar
+- **Page rewrite** for AI-answer extractability and traditional ranking
+- **Technical SEO** review (crawl, index, schema, performance, internal links)
+- **Schema markup** plan with JSON-LD that mirrors visible content
+- **Local SEO** plan (Google Business Profile, reviews, map pack, service pages)
+- **Programmatic SEO** plan (template + data + indexability rules)
+- **AI visibility / GEO / AEO / LLMO** strategy (ChatGPT, Perplexity, Gemini, Claude, Copilot, AI Overviews)
+- **Measurement** plan (Search Console + GA4 + AI-referral tracking)
+- **Authority / backlink / citation** plan
+
+## Output contract
+
+Every deliverable from the skill contains, in order:
+
+1. **Diagnosis** — what was observed, what's missing, what's assumed
+2. **Prioritized recommendations** — ordered by impact ÷ effort, each naming a specific page/section/asset
+3. **Concrete examples** — rewritten section, schema snippet, internal-link plan, or page template
+4. **Verification steps** — tool, expected timeframe, signal to watch
+5. **Risks, assumptions, dependencies**
+6. **Source references** when drawing from the video corpus
+
+If a critical input is missing, the skill asks one specific question rather than guessing.
+
+---
+
+## Install — one-line `npx` (recommended)
+
+Requires Node ≥ 18. The package ships every adapter and playbook; the CLI places them where each AI tool expects them or copies them to your clipboard.
+
+**Interactive menu** — pick a tool from a list:
+
+```bash
+npx @piramilan/seo-expert
+```
+
+**Direct install per tool** — one command, done:
+
+```bash
+# Coding agents (drops the rules file into your current project directory)
+npx @piramilan/seo-expert install cursor      # → .cursorrules
+npx @piramilan/seo-expert install cline       # → .clinerules
+npx @piramilan/seo-expert install windsurf    # → .windsurfrules
+npx @piramilan/seo-expert install aider       # → CONVENTIONS.md
+npx @piramilan/seo-expert install continue    # → .continue/seo-expert.md
+
+# Anthropic CLI (installs to ~/.claude/skills/seo-expert/)
+npx @piramilan/seo-expert install claude-code
+
+# Web-based AI tools — copies the adapter to your clipboard + prints next steps
+npx @piramilan/seo-expert copy chatgpt
+npx @piramilan/seo-expert copy claude-project
+npx @piramilan/seo-expert copy gemini
+npx @piramilan/seo-expert copy perplexity
+```
+
+**Discovery commands:**
+
+```bash
+npx @piramilan/seo-expert list      # list every supported tool
+npx @piramilan/seo-expert info      # version + repo info
+npx @piramilan/seo-expert help      # full CLI usage
+```
+
+**Safety notes:**
+
+- If a target file (`.cursorrules`, `CONVENTIONS.md`, etc.) already exists, the CLI backs it up to `<file>.bak.<timestamp>` before writing.
+- Clipboard copy works on macOS (`pbcopy`), Linux (`wl-copy` / `xclip` / `xsel`), and Windows (`clip`). If none are available, the CLI writes `seo-expert-adapter.md` to the current directory so you can copy it manually.
+- Pin a specific version for reproducible setups: `npx @piramilan/seo-expert@0.2.0 install cursor`.
+
+---
+
+## Install — manual paths (no Node required)
+
+If you can't run `npx` or want to install without touching a terminal, every adapter is a plain Markdown file you can copy by hand. Pick your tool:
+
+### Claude Code
+
+The Anthropic CLI auto-loads skills from `~/.claude/skills/<name>/`.
+
+```bash
+git clone https://github.com/Piramilan/seo-expert.git ~/.claude/skills/seo-expert
+```
+
+Restart Claude Code (or open a new conversation). Ask any SEO question — the skill auto-routes because of the `description:` in [SKILL.md](SKILL.md) frontmatter.
+
+**Test it:** `Audit https://example.com for SEO and AI visibility`
+
+---
+
+### Claude Project / Desktop
+
+1. Go to **[claude.ai](https://claude.ai) → Projects → New Project**.
+2. Open [adapters/claude-project-instructions.md](adapters/claude-project-instructions.md). Copy the block under **`## Instructions (paste this)`** into the Project's **Custom instructions** field.
+3. Upload these files to the Project's knowledge base:
+   - [SKILL.md](SKILL.md)
+   - [core/ai-seo-operating-system.md](core/ai-seo-operating-system.md)
+   - [core/technical-seo.md](core/technical-seo.md)
+   - [core/content-strategy.md](core/content-strategy.md)
+   - [core/local-seo.md](core/local-seo.md)
+   - [core/programmatic-seo.md](core/programmatic-seo.md)
+   - [core/video-derived-lessons.md](core/video-derived-lessons.md)
+   - [prompts/universal-ai-seo-prompts.md](prompts/universal-ai-seo-prompts.md)
+   - [sources/video-index.md](sources/video-index.md)
+4. Save.
+
+**Test it:** `Audit https://example.com for SEO`
+
+---
+
+### ChatGPT (Custom GPT / Project)
+
+1. Go to **[chatgpt.com](https://chatgpt.com) → My GPTs → Create a GPT → Configure**. (For a Project instead, go to **Projects → New Project**.)
+2. **Name:** `SEO Expert`. **Description:** *Senior SEO + AI-SEO consultant. Audits, content briefs, page rewrites, schema, local SEO, programmatic SEO, AI visibility.*
+3. Open [adapters/chatgpt-instructions.md](adapters/chatgpt-instructions.md). Copy the block under **`## Instructions (paste this)`** → paste into **Instructions**.
+4. **Conversation starters** (paste into the four starter slots):
+   - `Audit this URL for SEO and AI visibility: `
+   - `Rewrite this page section for AI extractability: `
+   - `Build a content brief for the query: `
+   - `Plan programmatic pages for the pattern: `
+5. **Knowledge** — upload the same 9 files listed in the Claude Project section above.
+6. **Capabilities** — enable Web Browsing (so the GPT can fetch URLs you give it). Code Interpreter is optional.
+7. **Save** → publish to *Only me*, *Anyone with the link*, or *Everyone* (GPT Store).
+
+**Test it:** start a new chat with one of the conversation starters.
+
+---
+
+### Gemini Gem
+
+1. **[gemini.google.com](https://gemini.google.com) → Gems → New Gem**.
+2. Open [adapters/gemini-gem-instructions.md](adapters/gemini-gem-instructions.md). Copy the block under **`## Instructions (paste this)`** → paste into the Gem's instructions.
+3. Gems don't support attached files like Custom GPTs do. **Embed the playbook content inline:**
+   - Copy the contents of [SKILL.md](SKILL.md) and each `core/*.md` into the Gem's instructions, or
+   - Paste the file you need at the start of each conversation (faster for long-context tasks).
+4. Save.
+
+**Test it:** *"Read https://example.com and audit it for SEO and AI visibility."* Gemini will fetch the URL and apply the embedded playbooks.
+
+---
+
+### Perplexity Space
+
+1. **[perplexity.ai](https://perplexity.ai) → Spaces → Create a Space**.
+2. Open [adapters/perplexity-space-instructions.md](adapters/perplexity-space-instructions.md). Copy the block under **`## Instructions (paste this)`** → paste into the Space's instructions.
+3. Add the 9 files (same list as the Claude Project section) to the Space library.
+4. Save.
+
+**Why Perplexity is special:** it does live web search and cites every claim. Use it for *current-state* audits where you want fresh evidence.
+
+**Test it:** *"Audit https://example.com — pull current SERP citations and AI-answer state, then apply the SEO Expert playbook."*
+
+---
+
+### Cursor / Cline / Windsurf / Aider / continue.dev
+
+For coding agents editing your marketing pages, schema, sitemaps, or meta tags.
+
+In your project root, save [adapters/coding-agent-rules.md](adapters/coding-agent-rules.md) as the right filename for your agent:
+
+| Agent | File path |
+| --- | --- |
+| Cursor | `.cursorrules` (or `.cursor/rules/seo-expert.md`) |
+| Cline | `.clinerules` |
+| Windsurf | `.windsurfrules` |
+| Aider | `CONVENTIONS.md` — then run `aider --read CONVENTIONS.md` |
+| continue.dev | `.continue/seo-expert.md` (or paste into `.continue/config.json` `rules`) |
+
+**One command shortcut** (from your project root):
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/Piramilan/seo-expert/main/adapters/coding-agent-rules.md > .cursorrules
+```
+
+Commit and push. The agent now applies SEO defaults automatically when editing any `.html`, `.jsx`, `.tsx`, `.mdx`, `.vue`, `.svelte`, `Head.*`, `_app.*`, `_document.*` file — or `sitemap.xml`, `robots.txt`, `manifest.*`.
+
+**Test it:** ask the agent *"add SEO meta tags and JSON-LD to the pricing page"* and confirm the diff matches the six-part Output Contract.
+
+---
+
+## Verify your install
+
+Run this prompt in any installed tool:
+
+> Diagnose, then return the six-part output contract for `https://example.com`. Skip detailed recommendations — I just want to confirm the skill is wired up.
+
+The response must contain six labeled sections: Diagnosis · Prioritized recommendations · Concrete examples · Verification steps · Risks/assumptions/dependencies · Source references. If any section is missing, the adapter wasn't fully pasted or the knowledge files weren't uploaded.
+
+---
+
+## Update an existing install
+
+When a new release cuts (see [CHANGELOG.md](CHANGELOG.md)):
+
+- **`npx` users:** the next `npx @piramilan/seo-expert install <tool>` automatically pulls the latest version. Pin with `@x.y.z` if you don't want updates.
+- **Claude Code (manual clone):** `cd ~/.claude/skills/seo-expert && git pull`
+- **Claude Project / ChatGPT GPT / Perplexity Space:** re-upload only the files that changed (see the version's CHANGELOG diff).
+- **Gemini Gem:** re-paste the changed playbook content.
+- **Coding agents:** `git pull` if vendored, or re-run the curl one-liner to overwrite `.cursorrules` / equivalent.
+
+Pin to a specific version for reproducible installs:
+
+```bash
+npx @piramilan/seo-expert@0.2.0 install cursor
+```
+
+---
+
+## Repo layout
+
+```
+seo-expert/
+├── SKILL.md                          ← canonical skill (entry point)
+├── INSTALL.md                        ← per-tool walkthrough (mirror of this README's install sections)
+├── README.md                         ← you are here
+├── CHANGELOG.md                      ← versioned release notes
+├── LICENSE                           ← MIT
+├── package.json                      ← npm metadata + bin field
+├── bin/
+│   └── seo-expert.js                 ← npx CLI (zero deps, Node ≥ 18)
+├── core/
+│   ├── ai-seo-operating-system.md    ← audits, AI visibility, measurement
+│   ├── technical-seo.md              ← crawl, index, schema, performance, Search Console
+│   ├── content-strategy.md           ← briefs, clusters, refresh, internal linking
+│   ├── local-seo.md                  ← GBP, map pack, reviews, location pages
+│   ├── programmatic-seo.md           ← templated page sets, validation, kill switches
+│   └── video-derived-lessons.md      ← generated lessons by topic (with source links)
+├── prompts/
+│   └── universal-ai-seo-prompts.md   ← 9 ready-to-paste prompt templates
+├── adapters/
+│   ├── claude-project-instructions.md
+│   ├── chatgpt-instructions.md
+│   ├── gemini-gem-instructions.md
+│   ├── perplexity-space-instructions.md
+│   └── coding-agent-rules.md
+└── sources/
+    └── video-index.md                ← public source-video metadata index
+```
+
+---
+
+## Operating principles
+
+Rules the skill follows on every task:
+
+- **Answer-first structure** — lead with the direct answer, then proof
+- **Entities over keywords** — each page is the canonical home for a named entity
+- **Extractability** — H2/H3 questions, short paragraphs, comparison tables, FAQ blocks
+- **Source-backed claims** — statistics and definitions cite a source
+- **Separate AI visibility from traditional ranking** when both are in scope
+- **Conversion outcomes, not vanity metrics** — every recommendation maps to revenue/leads/calls
+- **Diagnose before prescribing** — name the page, query, or signal first
+- **Verify, then ship** — every recommendation includes how to confirm it worked
+
+## Guardrails
+
+No bought reviews · no faked map-pack engagement · no link farms · no hidden text · no doorway pages · no generated-content spam · no keyword stuffing · no schema that doesn't match visible content · no reproducing raw third-party transcripts. If asked, the skill refuses and recommends the durable equivalent.
+
+---
+
+## Quick example
+
+> **You:** Audit `example.com` for SEO and AI visibility.
+>
+> **Skill returns:**
+> 1. Diagnosis with specific findings (empty H1, missing schema, no AI-crawler policy, etc.)
+> 2. Prioritized fixes in tiers (this week / this month / this quarter)
+> 3. Concrete HTML rewrites + JSON-LD blocks ready to ship
+> 4. Verification steps (Rich Results Test, Search Console, GA4 filters)
+> 5. Risks (schema-mismatch, thin pages, competitor positioning)
+> 6. Source links to the video corpus
+
+---
+
+## Versioning, contributing, license
+
+**Semver.** See [CHANGELOG.md](CHANGELOG.md). Pin to a tag (`v0.2.0`) or to an npm version (`@piramilan/seo-expert@0.2.0`) if you want a stable surface.
+
+**Contributing.** Issues and PRs welcome. Useful contributions: new playbooks (`core/*.md`), new adapters (a new AI tool), new prompt templates (`prompts/*.md`), and edits that tighten existing guidance. Keep the six-part Output Contract intact — that's the skill's identity. See `.github/PULL_REQUEST_TEMPLATE.md` for the checklist.
+
+**License.** [MIT](LICENSE). Use it, fork it, ship it inside your product, charge for it. Attribution appreciated, not required.