aeoptimize 0.5.2 → 0.6.0

package/skills/aeo-scan/SKILL.md

@@ -1,78 +1,31 @@
 ---
 name: aeo-scan
-description: Use when auditing a website or build output for AI search readiness, checking AI readability scores, or diagnosing why content isn't being cited by AI assistants like ChatGPT, Perplexity, or Google AI Overview
+description: Use when auditing a website or build output for deterministic content-readiness regressions and evidence-bounded discovery checks
 ---
 
-# AEO Scan — AI Readability Audit
+# AEO Scan — Content Readiness Audit
 
-Scan a website or build directory and produce an interactive AI readability report. Supports multi-AI scoring with gemini and copilot CLIs.
-
-## Scoring Dimensions (0-100)
-
-| Dimension | Max | What it measures |
-|-----------|-----|------------------|
-| Structure | 25 | Heading hierarchy, paragraph length, FAQ presence, list usage |
-| Citability | 25 | Self-contained statements, data/stats, definitions, attribution |
-| Schema | 20 | JSON-LD presence, completeness, AI-relevant types |
-| AI Metadata | 15 | llms.txt, robots.txt AI config, meta description |
-| Content Density | 15 | Content vs boilerplate, keyword stuffing, uniqueness |
+Run aeoptimize against a URL or build directory. The deterministic report is suitable for regression checks; optional Gemini, Copilot, or Claude reviews are experimental and do not predict ranking, indexing, rich results, visibility, or citation.
 
 ## Workflow
 
-1. **Identify target.** Ask the user for a URL or directory path. If in a project with a build output (e.g., `dist/`, `out/`, `.next/`, `build/`), suggest scanning that.
-
-2. **Detect AI CLIs.** Check which AI tools are available:
-   ```
-   which gemini && which copilot
-   ```
-   Report which are found. If both are available, offer multi-AI scoring.
-
-3. **Run scan.** Choose based on available CLIs:
+1. Identify the URL, file, or build directory.
+2. Run the deterministic scan with machine-readable output:
 
-   **If external AI CLIs available:**
-   ```
-   npx aeoptimize scan <target> --multi-ai --json
-   ```
-   This runs the rule engine + dispatches gemini/copilot for parallel scoring.
-
-   **If no external CLIs:**
-   ```
+   ```bash
    npx aeoptimize scan <target> --json
+   npx aeoptimize scan <directory> --dir --json
    ```
-   Then use the `aeo-ai-scorer` agent to add Claude's AI-level analysis on top of the rule engine score.
-
-4. **Present results.** Show:
-   - **Consensus score** (rule engine + AI weighted average)
-   - **Per-scorer breakdown** (Rule Engine, Claude, Gemini, Copilot — whichever are available)
-   - Dimensions scoring below 60% of their max
-   - All critical issues
-   - **AI insights** — each AI's one-sentence summary of the biggest issue
-
-5. **Discuss improvements.** For each weak dimension, explain:
-   - Why it matters for AI search visibility
-   - Concrete steps to improve
-   - Expected score impact
-   - Cross-reference insights from different AI scorers if they agree/disagree
-
-6. **Deep analysis (optional).** If the user wants detailed per-page analysis, dispatch the `aeo-analyzer` agent with the page HTML and scan report. It provides issue-by-issue breakdown with before/after examples.
-
-7. **Offer next steps:**
-   - Score below 50? Suggest running `/aeo-transform` on the worst pages
-   - Missing llms.txt or schema? Suggest `/aeo-generate`
-   - Score above 80? Congratulate and suggest monitoring over time
-
-## Multi-AI Scoring Methodology
 
-| Scenario | Weighting |
-|----------|-----------|
-| Rule engine + 2+ AIs | 50% rule engine + 50% AI average |
-| Rule engine + 1 AI | 60% rule engine + 40% AI |
-| Rule engine only | 100% rule engine |
+3. Report the deterministic score, methodology version, critical findings, and heuristic limitations.
+4. Use `--multi-ai` only when the user explicitly asks for a subjective review. Label the result an experimental blend and keep the deterministic score separate.
+5. Prioritize sourced quantitative claims, unintentional `noindex`, malformed or misleading structured data, and reproducible content regressions.
+6. Suggest `/aeo-generate` only for an optional artifact preview. State that `llms.txt` is an unscored proposal.
 
-## Important
+## Boundaries
 
-- Always run the CLI with `--json` for machine-readable output
-- Present scores visually with context, not just numbers
-- Focus discussion on high-impact fixes first
-- If scanning a URL fails (CORS, timeout), suggest scanning the local build output instead
-- When using Claude as AI scorer (no external CLIs), dispatch the `aeo-ai-scorer` agent
+- FAQ content and `llms.txt` have no score impact.
+- A score increase is not evidence of a ranking or citation increase.
+- Generated schema must match visible content and current feature documentation.
+- If a URL scan fails, use an authorized local build instead of bypassing access controls.
+- Always use `--json` when another tool will consume the result.

package/skills/aeo-transform/SKILL.md

@@ -1,84 +1,32 @@
 ---
 name: aeo-transform
-description: Use when restructuring website content for better AI citation — splitting long paragraphs, adding FAQ schema, removing keyword stuffing, improving heading structure, or injecting structured data into HTML or Markdown files
+description: Use when proposing evidence-bounded readability and structure edits without inventing content, ranking claims, or structured data
 ---
 
-# AEO Transform — AI-Friendly Content Restructuring
+# AEO Transform — Evidence-Bounded Content Restructuring
 
-Transform SEO-optimized content into AI-search-ready format using language understanding. This skill uses your Claude subscription — no additional API costs.
-
-## Transformation Strategies
-
-| Strategy | What it does | Impact |
-|----------|-------------|--------|
-| **Split paragraphs** | Break long paragraphs (>150 words) into self-contained statements | High |
-| **Extract FAQ** | Find implicit Q&A content and convert to explicit FAQ with schema | High |
-| **Remove keyword stuffing** | Replace repeated keywords with natural synonyms | High |
-| **Improve headings** | Rewrite vague headings as specific, question-format headings | Medium |
-| **Add structured data** | Inject JSON-LD based on content analysis | Medium |
-| **Fix dangling references** | Rewrite paragraphs starting with "This", "It", "They" to be self-contained | Medium |
+Propose focused edits while preserving meaning, voice, provenance, and recoverability.
 
 ## Workflow
 
-1. **Identify targets.** Ask the user which files to transform. If unsure, suggest running `/aeo-scan` first to find the lowest-scoring pages.
-
-2. **Read and analyze.** For each file:
-   - Read the full content
-   - Run `npx aeoptimize scan <file> --json` to get the current score
-   - Identify which strategies apply based on the issues found
-
-3. **Transform incrementally.** Apply one strategy at a time:
-   - Show the proposed change as a diff
-   - Explain why this change improves AI readability
-   - Wait for user approval before applying
-   - Move to the next strategy
-
-4. **Preserve voice.** Critical rules:
-   - Never invent new content or add claims not in the original
-   - Preserve the author's writing style and tone
-   - Only restructure — do not rewrite meaning
-   - Keep all existing data, quotes, and references intact
-
-5. **Verify improvement.** After all transforms:
-   - Re-run `npx aeoptimize scan <file> --json`
-   - Show before/after score comparison
-   - Highlight which dimensions improved
-
-## Strategy Details
-
-### Split Paragraphs
-For each paragraph over 150 words:
-- Identify distinct ideas within the paragraph
-- Split at natural boundaries (topic shifts, "Additionally", "However")
-- Ensure each new paragraph is self-contained (has its own subject, not just "It..." or "This...")
-
-### Extract FAQ
-Look for patterns like:
-- Heading followed by a short answer paragraph
-- "What is X?" / "How does X work?" patterns in body text
-- Implicit questions answered in the content
-
-Convert to:
-- Explicit `<h3>` question headings
-- Concise answer paragraphs
-- FAQPage JSON-LD schema
+1. Read one authorized file and run the deterministic scan.
+2. Classify each finding as an official requirement, deterministic check, heuristic, or experiment.
+3. Show a focused diff before changing the file.
+4. Change only what improves readability, factual provenance, or a documented technical requirement.
+5. Rerun the same scan and report the reproducible output change separately from any external outcome.
 
-### Remove Keyword Stuffing
-When a word appears >3% of content (excluding stop words):
-- Replace some occurrences with synonyms or related terms
-- Remove redundant mentions that don't add meaning
-- Ensure remaining usage feels natural
+## Allowed transformations
 
-### Fix Dangling References
-For paragraphs starting with pronouns/conjunctions:
-- Replace "This feature" with "[Product name]'s feature"
-- Replace "It provides" with "[Subject] provides"
-- Replace "However," with a self-contained restatement
+- Split a long paragraph where comprehension improves.
+- Repair a genuinely confusing document outline; multiple H1 elements are not automatically wrong.
+- Cite or remove unsupported quantitative claims.
+- Reduce repetitive wording without changing meaning.
+- Propose structured data only when it matches visible content and current documentation.
+- Clarify genuine reader questions without auto-generating FAQ schema.
 
-## Important
+## Boundaries
 
-- Always show diffs before applying changes
-- Transform one file at a time, one strategy at a time
-- Score comparison before/after is mandatory
-- This skill is interactive — never batch-transform without review
-- Supports `.html` and `.md` files
+- Never invent facts, statistics, sources, quotes, authors, dates, or benefits.
+- Never describe a score increase as evidence of ranking, indexing, rich results, or citation.
+- Never batch-transform files without explicit scope.
+- Preserve a reviewable diff and the user's original voice.