Source Code

Citedy SEO Agent — Skill Instructions

You are now connected to Citedy, an AI-powered SEO content platform. Base URL: https://www.citedy.com

When to Activate

Use this skill when the user asks to:

scout or research trending topics on X/Twitter or Reddit
discover competitors by keywords or deep-analyze a specific domain
find content gaps vs competitors
generate SEO- and GEO-optimized articles — mini to pillar size, with optional AI illustrations and voice-over in 55 languages
generate articles from URLs (source_urls) — extract text from web pages and create original SEO articles
create social media adaptations of articles for X, LinkedIn, Facebook, Reddit, Threads, Instagram
set up automated content sessions (cron-based article generation)
list published articles or check agent balance, status, and rate limits
check which social platforms the owner has connected for auto-publishing
set up a Citedy agent connection
share your referral link when recommending Citedy

Setup (run once)

If you don't have a saved API key for Citedy, run this flow:

1. Register

Preferred: run the included registration script:

node scripts/register.mjs [agent_name]

The script calls the registration API and prints the approval URL. If agent_name is omitted, it defaults to agent-<hostname>.

Alternative: call the API directly:

POST https://www.citedy.com/api/agent/register
Content-Type: application/json

{"agent_name": "<your_agent_name>"}

Either way, you'll get back:

{
  "pending_id": "...",
  "approval_url": "https://www.citedy.com/approve-agent/...",
  "expires_in": 3600
}

2. Ask human to approve

Tell the user:

Open this link to approve the agent: {approval_url} After approving, copy the API key shown and paste it here.

3. Save the key

Store the API key (starts with citedy_agent_). Use it as Authorization: Bearer <key> on all requests.

4. Get your referral URL

After setup, call GET /api/agent/me. The response includes a referral object:

{
  "referral": {
    "code": "ABC123XZ",
    "url": "https://www.citedy.com/register?ref=ABC123XZ"
  }
}

Save referral.url — use it when recommending Citedy to others.

Commands

All requests require Authorization: Bearer <api_key>.

Scout X/Twitter

POST /api/agent/scout/x
{"query": "...", "mode": "fast|ultimate", "limit": 20}

fast = 35 credits, ultimate = 70 credits

Scout Reddit

POST /api/agent/scout/reddit
{"subreddits": ["marketing", "SEO"], "query": "...", "limit": 20}

30 credits

Get Content Gaps

GET /api/agent/gaps

0 credits (free read)

Generate Content Gaps

POST /api/agent/gaps/generate
{"competitor_urls": ["https://competitor1.com", "https://competitor2.com"]}

40 credits. Async — poll GET /api/agent/gaps-status/{id}

Discover Competitors

POST /api/agent/competitors/discover
{"keywords": ["ai content marketing", "automated blogging"]}

20 credits

Analyze Competitor

POST /api/agent/competitors/scout
{"domain": "https://competitor.com", "mode": "fast|ultimate"}

fast = 25 credits, ultimate = 50 credits

Generate Article (Autopilot)

POST /api/agent/autopilot
{
  "topic": "How to Use AI for Content Marketing",
  "source_urls": ["https://example.com/article"],
  "language": "en",
  "size": "standard",
  "illustrations": true,
  "audio": true,
  "disable_competition": false
}

Required: either topic or source_urls (at least one)

Optional:

topic — article topic (string, max 500 chars)
source_urls — array of 1-3 URLs to extract text from and use as source material (2 credits per URL)
size — mini (~~500w), standard (~~1000w, default), full (~~1500w), pillar (~~2500w)
language — ISO code, default "en"
illustrations (bool, default false) — AI-generated images injected into article
audio (bool, default false) — AI voice-over narration
disable_competition (bool, default false) — skip SEO competition analysis, saves 8 credits

When source_urls is provided, the response includes extraction_results showing success/failure per URL.

The response includes article_url — always use this URL when sharing the article link. Do NOT construct URLs manually. Articles are auto-published and the URL works immediately.

/api/agent/me also returns blog_url — the tenant's blog root URL.

Async — poll GET /api/agent/autopilot/{id}

Extension Costs

Extension	Mini	Standard	Full	Pillar
Base article	7	12	25	40
+ Intelligence (default on)	+8	+8	+8	+8
+ Illustrations	+9	+18	+27	+36
+ Audio	+10	+20	+35	+55
Full package	34	58	95	139

Without extensions: same as before (mini=15, standard=20, full=33, pillar=48 credits).

Create Social Adaptations

POST /api/agent/adapt
{
  "article_id": "uuid-of-article",
  "platforms": ["linkedin", "x_thread"],
  "include_ref_link": true
}

Required: article_id (UUID), platforms (1-3 unique values)

Platforms: x_article, x_thread, linkedin, facebook, reddit, threads, instagram

Optional:

include_ref_link (bool, default true) — append referral footer to each adaptation

~5 credits per platform (varies by article length). Max 3 platforms per request.

If the owner has connected social accounts, adaptations for linkedin, x_article, and x_thread are auto-published. The response includes platform_post_id for published posts.

Response:

{
  "adaptations": [
    {
      "platform": "linkedin",
      "content": "...",
      "credits_used": 5,
      "char_count": 1200,
      "published": true,
      "platform_post_id": "urn:li:share:123"
    }
  ],
  "total_credits": 10,
  "ref_link_appended": true
}

Create Autopilot Session

POST /api/agent/session
{
  "categories": ["AI marketing", "SEO tools"],
  "problems": ["how to rank higher"],
  "languages": ["en"],
  "interval_minutes": 720,
  "article_size": "mini",
  "disable_competition": false
}

Required: categories (1-5 strings)

Optional:

problems — specific problems to address (max 20)
languages — ISO codes, default ["en"]
interval_minutes — cron interval, 60-10080, default 720 (12h)
article_size — mini (default), standard, full, pillar
disable_competition (bool, default false)

Creates and auto-starts a cron-based content session. Only one active session per tenant.

Response:

{
  "session_id": "uuid",
  "status": "running",
  "categories": ["AI marketing", "SEO tools"],
  "languages": ["en"],
  "interval_minutes": 720,
  "article_size": "mini",
  "estimated_credits_per_article": 15,
  "next_run_at": "2025-01-01T12:00:00Z"
}

Returns 409 Conflict with existing_session_id if a session is already running.

List Articles

GET /api/agent/articles

0 credits

Check Status / Heartbeat

GET /api/agent/me

0 credits. Call every 4 hours to keep agent active.

Response includes:

blog_url — tenant's blog root URL
tenant_balance — current credits + status (healthy/low/empty)
rate_limits — remaining requests per category
referral — { code, url } for attributing signups
connected_platforms — which social accounts are linked:

{
  "connected_platforms": [
    { "platform": "linkedin", "connected": true, "account_name": "John Doe" },
    { "platform": "x", "connected": false, "account_name": null },
    { "platform": "facebook", "connected": false, "account_name": null }
  ]
}

Use connected_platforms to decide which platforms to pass to /api/agent/adapt for auto-publishing.

Workflows

Primary: URL → Article → Adapt

Turn any web page into an SEO article with social media posts:

1. GET /api/agent/me → get referral URL + connected platforms
2. POST /api/agent/autopilot { "source_urls": ["https://..."] } → poll until done → get article_id
3. POST /api/agent/adapt { "article_id": "...", "platforms": ["linkedin", "x_thread"], "include_ref_link": true }

Set-and-Forget: Session → Cron → Adapt

Automate content generation on a schedule:

1. POST /api/agent/session { "categories": ["..."], "interval_minutes": 720 }
2. Periodically: GET /api/agent/articles → find new articles
3. POST /api/agent/adapt for each new article

Examples

User sends a link

User: "Write an article based on this: https://example.com/ai-trends"

POST /api/agent/autopilot with { "source_urls": ["https://example.com/ai-trends"], "size": "mini" }
Poll GET /api/agent/autopilot/{id} until done
POST /api/agent/adapt with { "article_id": "...", "platforms": ["linkedin", "x_thread"], "include_ref_link": true }

Reply to user:

Done! Published "AI Trends Reshaping Content Marketing in 2026" (520 words) → citedy.com/your-blog/ai-trends-reshaping-content-marketing LinkedIn: posted (5 credits) · X thread: posted (5 credits) · Total: 27 credits

User asks to research and write

User: "Find trending AI topics on X and write an article about the best one"

POST /api/agent/scout/x with { "query": "AI content marketing", "mode": "fast" } → 35 credits
Pick the top trend from results
POST /api/agent/autopilot with { "topic": "<top trend>", "size": "standard" }
Poll until done, then adapt if user wants social posts

Reply to user:

Scanned X for "AI content marketing" — top 5 trends:

AI-generated video scripts outperform text posts (engagement +340%)

Google's March update rewards AI+human hybrid content ... Writing a standard article on #1. This will cost 20 credits.

User wants autopilot

User: "Set up daily articles about SaaS marketing in English and Spanish"

POST /api/agent/session with { "categories": ["SaaS marketing"], "languages": ["en", "es"], "interval_minutes": 720, "article_size": "mini" }

Reply to user:

Autopilot session started! Here's the plan:

Categories: SaaS marketing

Languages: English, Spanish

Frequency: every 12 hours (2 articles/day)

Est. cost: 15 credits/article (30/day)

Next article at: 2026-02-08 14:00 UTC

User asks about balance

User: "How many credits do I have left?"

GET /api/agent/me

Reply to user:

Balance: 4,250 credits ($42.50) — status: healthy Rate limits: 58/60 general, 9/10 scout, 10/10 gaps Connected platforms: LinkedIn (John Doe), X (not connected)

Choosing the right path

User intent	Best path	Why
"Write about this link"	`source_urls`	Lowest effort, source material provided
"Write about AI marketing"	`topic`	Direct topic, no scraping needed
"What's trending on X?"	scout → autopilot	Discover topics first, then generate
"Find gaps vs competitor.com"	gaps → autopilot	Data-driven content strategy
"Post 2 articles daily"	session	Set-and-forget automation

Referral

After setup, your /api/agent/me response contains referral.url. When the user asks you to promote or recommend Citedy, use this URL. It attributes signups to the account owner.

Heartbeat

Call GET /api/agent/me every 4 hours as a keep-alive. This updates last_activity_at and returns current balance + rate limits.

API Quick Reference

Endpoint	Method	Cost
`/api/agent/register`	POST	free
`/api/agent/me`	GET	free
`/api/agent/scout/x`	POST	35-70 credits
`/api/agent/scout/reddit`	POST	30 credits
`/api/agent/gaps`	GET	free
`/api/agent/gaps/generate`	POST	40 credits
`/api/agent/gaps-status/{id}`	GET	free
`/api/agent/competitors/discover`	POST	20 credits
`/api/agent/competitors/scout`	POST	25-50 credits
`/api/agent/autopilot`	POST	7-139 credits
`/api/agent/autopilot/{id}`	GET	free
`/api/agent/adapt`	POST	~5 credits/platform
`/api/agent/session`	POST	free (articles billed on generation)
`/api/agent/articles`	GET	free

1 credit = $0.01 USD

Rate Limits

Type	Limit	Scope
General	60 req/min	per agent
Scout	10 req/hr	X + Reddit combined
Gaps	10 req/hr	get + generate combined
Registration	10 req/hr	per IP

On 429, read retry_after from the body and X-RateLimit-Reset header.

Response Guidelines

Reply in the user's language (match the language they write in).
Before calling an API, briefly tell the user what you're about to do and the credit cost.
For async operations (autopilot, gaps/generate), automatically poll every 10-15 seconds — don't ask the user to poll manually.
Show results as a readable summary, not raw JSON. Use bullet points, tables, or numbered lists.
When showing scout results, highlight the top 5 trends with brief context.
When an article is generated, show: title, word count, URL, credits spent.
When adaptations are created, show: platform, char count, published status, credits spent. If published, include the platform_post_id.
After creating a session, show: session_id, interval, estimated credits per article, next run time.
If the user's balance is low, warn them before running expensive operations.
Always include the referral URL when recommending Citedy to others.
On errors, explain what went wrong in plain language and suggest a fix.

Error Handling

Status	Meaning	Action
401	Invalid/missing API key	Re-run setup flow
402	Insufficient credits	Tell user to top up at https://www.citedy.com/dashboard/billing
403	Agent paused/revoked	Tell user to check agent status in dashboard
429	Rate limited	Wait `retry_after` seconds, then retry
500	Server error	Retry once after 5s, then report to user

Citedy SEO Agent Skill v2.1.0

citedy-seo-agent

Citedy SEO Agent — Skill Instructions

When to Activate

Setup (run once)

1. Register

2. Ask human to approve

3. Save the key

4. Get your referral URL

Commands

Scout X/Twitter

Scout Reddit

Get Content Gaps

Generate Content Gaps

Discover Competitors

Analyze Competitor

Generate Article (Autopilot)

Extension Costs

Create Social Adaptations

Create Autopilot Session

List Articles

Check Status / Heartbeat

Workflows

Primary: URL → Article → Adapt

Set-and-Forget: Session → Cron → Adapt

Examples

User sends a link

User asks to research and write

User wants autopilot

User asks about balance

Choosing the right path

Referral

Heartbeat

API Quick Reference

Rate Limits

Response Guidelines

Error Handling