---
name: aeoforge-agency-workflow
description: Repeatable workflow for producing AEO-optimised content using the AEOForge platform. Use when creating articles for agency clients.
---

# AEOForge Agency Content Production Workflow

## Overview

This skill defines the end-to-end process for producing a single AEO-optimised article for an agency client. Each step uses AEOForge's REST API or MCP tools. The agent (you) writes the content — AEOForge provides research intelligence, scoring feedback, and structured data.

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

**Craft over score:** live client pages and articles are for humans first. Treat `aeo_score` as feedback. FAQ and takeaways belong on articles when they recap the piece — never ship them onto a door or landing, or stack junk FAQ, just to raise numbers while killing voice or trust.

## Prerequisites

- AEOForge API key (Bearer `aeo_sk_...`) or MCP connection
- Client name and target keyword
- Client intelligence profile (load via `aeo_client_profile` or `GET /api/v1/client-profile/list`)
- Optional: brief, product context, target content type

## Workflow Steps

### Step 0: Load Client Profile

Before any work, load the client's intelligence profile. This contains brand voice, company knowledge, competitors, and audience data that must inform every piece of content.

If a profile exists: `GET /api/v1/client-profile/list?client_user_id=<id>`
If not: `POST /api/v1/client-profile` with the client's website URL. Cost: 5 credits.

### Step 1: Onboard (one-time per session)

Call `GET /api/v1/onboard` to receive the full product context, tool list, and scoring dimensions. Store the `context_hash` — it proves you consumed the onboarding material.

### Step 2: Create Project

Call `POST /api/v1/projects` with:
- `name`: Article title or topic
- `seed_keyword`: Target keyword
- `content_type`: `article` | `faq` | `product` | `guide`
- `brief`: Client brief or editorial direction
- `product_context`: About the client's product/service
- `client_name`: Client identifier for grouping

### Step 3: Research

Call `POST /api/v1/research` with the `keyword` and `project_id`. This runs live web research via Brave Search, returning structured entities, data points, competitor angles, and source URLs. Cost: 10 credits (standard) / 15 credits (deep).

For real-time progress, use `POST /api/v1/research/stream` (SSE).

### Step 4: Write the Article

Using the research output AND the client profile, write the article yourself (as the AI agent). Include:
- Direct answers to the target query in the first 2 sentences
- H2 sections with clear, factual subheadings (phrased as questions where natural)
- Data points and statistics from research with source attribution
- Named methods, frameworks, or entities from research
- Brand voice and tone from the client profile
- Product-specific terminology from the client profile

### Step 5: Score

Call `POST /api/v1/score` with the article markdown AND the research data. This returns an 8-dimension AEO score (0-100), grade (A+ through F), per-dimension breakdown, and actionable suggestions with specific fix locations.

**Target: 80+ for publication.** Below 70, iterate.

### Step 6: Iterate (if score < 80)

Read the suggestions from the score response. Focus on high-priority items first. Common fixes:
- Add missing entities flagged in the entity dimension
- Strengthen E-E-A-T signals (author attribution, methodology, expert quotes)
- Add structured data hooks (lists, tables, definition patterns)
- Improve direct answer clarity in the opening paragraph

Re-score after each iteration. At most 3 iterations; if still below 80, stop and report weakest dimensions.

### Step 7: Generate Schema

Call `POST /api/v1/schema` with the final article markdown. This generates JSON-LD structured data (Article, FAQPage, HowTo, etc.) tailored to the content. Free.

### Step 8: Verify Claims

Call `POST /api/v1/verify` to check factual claims against source material. Remove or qualify any unverifiable claims. Cost: 2 credits.

### Step 9: Publish and Track

Once the client approves the article:
1. Set `published_url` on the project via `PATCH /api/v1/projects/{id}`
2. Call `POST /api/v1/track` to register for citation monitoring
3. Citation checks: `aeo_track` uses a Brave-search visibility proxy (labelled as such). Retainer citation-board Monitoring measures ChatGPT, Perplexity, and Gemini for page citations.

## Quality Gates

| Metric | Minimum | Target |
|--------|---------|--------|
| AEO Score | 70 | 80+ |
| Grade | B | A or A+ |
| Word Count | 800 | 1000-1500 |
| Sources Referenced | 3 | 5+ |
| Schema Generated | Yes | Yes |
| Claims Verified | Yes | Yes |
| Client Profile Loaded | Yes | Yes |

## Cost Per Article

- Client Profile (once per client): 5 credits
- Research: 10 credits (standard) / 15 credits (deep)
- Score (2-3 iterations): 0 credits (free)
- Schema: 0 credits (free)
- Verify: 2 credits
- **Total: ~12-17 credits per article**

## Additional Tools

All tools are accessible via API key or MCP — confirm the live catalog and costs with `GET /api/v1/onboard`. Prefer the consolidated verbs for new work:

| Verb / Tool | Credits | Use Case |
|-------------|---------|----------|
| `aeo_diagnose` | Free | Site-wide audit: discover pages, score, benchmark competitors, action plan (async → 202 + poll) |
| `aeo_create` | 20 | End-to-end grounded article (research + draft + score gate) |
| `aeo_improve` | 2-8 | Transform existing content: voice, AEO rewrite, score-driven, freshness |
| `aeo_package` | 0-3 | JSON-LD, featured-snippet formatting, or llms.txt |
| `aeo_factcheck` | Free | Deterministic statistical claim verification against research |
| `aeo_visibility` | 10 | Estimate AI-answer share of voice (Brave web-search proxy) |
| `aeo_audit` | 5 | Single-URL AEO audit with improvement plan |
| `aeo_compare` | 3 | Head-to-head comparison of two articles |
| `aeo_cluster` | 5 | Group keywords into content strategy |
| `aeo_crawlability` | Free | Check AI bot access to a site |
| `aeo_import` | Free | Import an external article into a workspace for scoring/improvement |
| `aeo_moat_check` | 15 | Competitive gap analysis |
| `aeo_agent_ready` | Free | Probe-based agent-readiness audit |

Long-running tools (`diagnose`, `visibility`, `research`) return 202 by default. Poll `GET /api/v1/tool-runs/{run_id}` every ~15s until `status: "complete"` or `error`. On `likely_stalled` or `timeout`, retry once then stop.

Call `GET /api/v1/onboard` for the full tool catalog with costs.

## Site audit loop (agents)

For client site work — not just article production — run this loop after `aeo_diagnose` / `aeo_complete_audit`:

### A. Run audit and read the queue
1. Run a site audit (use `agency: true` when the caller needs deeper discovery and a site planner — costs come from the API response / onboard catalog).
2. Read the snapshot (or handoff `audit_engagement`) — note `sampling` when LLM depth is sampled.
3. Prioritize open action items: impact descending, effort ascending.

### B. Fix and verify
1. Claim items: `PATCH /api/v1/action-items/{id}` → `in_progress`.
2. Apply fixes (repo, CMS, or `preview-fix` → apply). Prefer craft over score on live marketing pages.
3. Mark `done`, then `POST /api/v1/verify-page` with `{ url, snapshot_id }`.
4. Passing items are promoted to `verified` (system-only — never set manually).
5. Optional: `document-fix` on verified items for Remediation Stories on a client share view.

### C. Client deliverables
Share links (`/share/[token]`) and room reports are how humans deliver results. Agents do not price work, convert curations to orders, or operate billing surfaces — payment and packaging are human-only. Public catalog: `https://aeoforged.com/pricing` (humans: home or `/pricing`; agents: `/for-agents`).