# AEOForge AI-Ready — Agent Skill

> Use this skill when a developer asks to "make my site AI-ready", "make my content
> citable", "set up llms.txt/schema", or "check if AI can read/use my site" — and you
> have local repo access. Everything lands in the repo and the chat; no dashboard needed.

## When to use

- New site pre-launch: bake in crawlability, schema, and llms.txt from the first commit.
- Existing repo AI-readiness pass: audit the live/preview site, then fix in code.
- Content authoring with citations: research-grounded drafts written in-repo, scored to 80+.
- Agent-operability check: whether delegated agents can read the site, operate forms, and see commerce schema.

## Setup (once)

1. Get a free API key via [`/onboarding`](https://aeoforged.com/onboarding) (issues a key + MCP config). Export it:
   ```bash
   export AEOFORGE_API_KEY="aeo_sk_YOUR_KEY_HERE"
   ```
2. Wire up MCP (recommended) — configs and docs:
   - Cursor: `https://aeoforged.com/skills/aeoforge-cursor-mcp.json`
   - Claude Code: `https://aeoforged.com/skills/aeoforge-claude-mcp.json`
   - Docs: `https://aeoforged.com/docs/mcp` · `https://aeoforged.com/docs/skills`
3. Or call raw REST with the bearer token, and read `GET /api/v1/onboard` first for the full tool catalog, scoring rules, and response headers:
   ```bash
   curl -H "Authorization: Bearer $AEOFORGE_API_KEY" https://aeoforged.com/api/v1/onboard
   ```

> Fit Check is REST-only (`POST /api/v1/fit-check`) — there is no `aeo_fit_check` MCP tool. Every other step below has both a REST route and an `aeo_*` MCP alias.

**API base:** every `/api/…` path in this file lives on `https://aeoforged.com` (so `POST /api/v1/fit-check` means `POST https://aeoforged.com/api/v1/fit-check`). Never send these to `localhost`, a dev server, a preview deploy, or the site you are working on, and never look for them in the repo you have open — the project has its own `/api/` routes that have nothing to do with AEOForge.

## The AI-ready loop (the core workflow)

1. **DIAGNOSE** — all free, read-only:
   - `POST /api/v1/fit-check` — platform fingerprint, page count, connectability, content velocity, deterministic package recommendation (REST-only).
   - `aeo_diagnose` (`POST /api/v1/diagnose`) — site-wide audit: discover pages, score, benchmark, action plan. Async → 202 + `poll_url`; poll `GET /api/v1/tool-runs/{run_id}`.
   - `aeo_crawlability` (`POST /api/v1/crawlability`) — robots.txt for 11 AI bots, meta noai, X-Robots-Tag, llms.txt, sitemap, JS rendering.
   - `aeo_agent_ready` (`POST /api/v1/agent-ready`) — probe-based operability for delegated agents (read/forms/booking/transact).
   - → Summarize findings in chat, ranked by impact.

2. **FIX REPO** — apply crawlability/robots fixes, `<title>`/meta description, canonical, and Open Graph tags in the codebase, using each finding's evidence and acceptance criteria. Commit per fix.

3. **FILES** — write the machine-readable surface into the repo:
   - `aeo_package` `mode:llms-txt` (3 cr) → write `llms.txt` + `llms-full.txt` into `public/`.
   - `aeo_package` `mode:jsonld` (free) → embed JSON-LD (Article / FAQ / Organization) in the page head. `aeo_schema` (free) is the granular alias.
   - `aeo_agent_policy` (3 cr) → write `AGENT-POLICY.md` + robots agent-allow rules.

4. **VERIFY** — re-run the free checks (`aeo_diagnose`, `aeo_crawlability`, `aeo_agent_ready`) against the deployed preview and report before/after in chat. Nothing is "done" until the re-check passes.

5. **CONTENT (optional)** — grounding gate is enforced, so research comes first:
   - `aeo_research` (10 cr) — **REQUIRED before writing.** AEOForge only allows citations from sources returned by research.
   - Draft in-repo with inline markdown citations `[Source](https://...)` drawn from the research allow-list — only research URLs count.
   - `aeo_score` (free) at most 3 times; if still below 80, stop and report weakest dimensions.
   - `aeo_schema` (free) — JSON-LD for the finished piece.
   - Shortcut for weak agents: `aeo_create` (20 cr) researches, drafts, strips hallucinated citations, and grounds in one call.

6. **DISTRIBUTE (optional)** — agent-authored kits:
   - `aeo_authority` `mode:distribution_candidates` (free) → scan the live site, review `candidates[]`, pick the best published URL.
   - `aeo_authority` `mode:distribution` (3 cr) → write the LinkedIn/X/carousel/newsletter kit into `./distribution/<slug>/` for the user to post.

## Credit costs

Costs below match live tool pricing from `GET /api/v1/onboard` / `GET /api/v1/me` (credit balance + plan). Free tools are free forever on this loop; credit-metered tools spend research/writing/generation credits — buy packs from `/settings/billing` after you have an account.

| Step | Tool | Cost |
|------|------|------|
| DIAGNOSE | `fit_check` (REST-only) | Free |
| DIAGNOSE | `aeo_diagnose` | Free |
| DIAGNOSE | `aeo_crawlability` | Free |
| DIAGNOSE | `aeo_agent_ready` | Free |
| FILES | `aeo_package` `mode:jsonld` / `aeo_schema` | Free |
| FILES | `aeo_package` `mode:llms-txt` / `aeo_llms_txt` | 3 cr |
| FILES | `aeo_agent_policy` | 3 cr |
| CONTENT | `aeo_score` | Free |
| CONTENT | `aeo_research` | 10 cr |
| CONTENT | `aeo_create` (one-call grounded draft) | 20 cr |
| DISTRIBUTE | `aeo_authority` `mode:distribution_candidates` | Free |
| DISTRIBUTE | `aeo_authority` `mode:distribution` | 3 cr |

## Honesty rules (repeat to the user when relevant)

- **Research-grounded citations only.** Citations require research-retrieved sources; hallucinated URLs are stripped. To recover from an ungrounded draft: run `POST /api/v1/research` (`aeo_research`) for the topic, weave the returned sources in as inline citations (only research URLs count), then re-score to confirm — or call `aeo_create` for a grounded draft in one step.
- **Readiness ≠ citation.** No tool here guarantees AI citations. We make a site readable, crawlable, and agent-operable; whether an engine cites it is never guaranteed.
- **Visibility is a proxy.** Any visibility/share-of-voice number is a Brave-search proxy, labelled as such — not a confirmed ChatGPT/Perplexity/Google citation.
- **llms.txt is emerging.** It is an emerging proposal, not a ranking lever; ship it as a machine-readable convenience, not a guaranteed signal.