@seoagent-official/seoagent 1.64.0 → 1.65.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/index.js +1 -1
- package/package.json +1 -1
- package/skills/references/keyword-research.md +17 -5
- package/skills/references/listicle-articles.md +138 -0
- package/skills/seoagent.md +26 -11
package/index.js
CHANGED
|
@@ -564,7 +564,7 @@ ${t}
|
|
|
564
564
|
`),!(s.subtype==="success"&&!s.is_error))return l.error(" Agent did not complete the citation audit (rate limit, auth, or network)."),null;i=String(s.result??"")}return i}catch(o){return process.stdout.write(`
|
|
565
565
|
`),l.error(` Agent error: ${o.message}`),null}}function Ud(e){if(!e||typeof e!="object")return;let t=e.type;if(t==="text"){let n=e.text;typeof n=="string"&&n&&process.stdout.write(Kt(n));return}if(t==="tool_use"){let n=String(e.name??"tool"),r=e.input,o=n==="WebSearch"?String(r?.query??""):n==="WebFetch"?String(r?.url??""):"";process.stdout.write(R.dim(` ${R.magenta("\u{1F50E}")} ${n}${o?` ${Md(o,70)}`:""}
|
|
566
566
|
`))}}function Md(e,t){return e.length<=t?e:e.slice(0,t-1)+"\u2026"}function Bd(e){return typeof e!="string"?[]:e.split(",").map(t=>t.trim()).filter(Boolean)}function Wd(e){try{if(!Nd(e))return null;let t=Ld(e).filter(o=>o.endsWith(".json")).sort();if(t.length===0)return null;let n=t[t.length-1],r=JSON.parse(jd(Gi(e,n),"utf-8"));return r&&typeof r=="object"&&Array.isArray(r.results)&&typeof r.generated_at=="string"?r:null}catch{return null}}import Ge from"picocolors";var Gd=30,Kd=/<(script|style|noscript|template|svg|nav|header|footer)\b[^>]*>[\s\S]*?<\/\1>/gi;function qd(e){let t=e,n=/<body\b[^>]*>([\s\S]*?)<\/body>/i.exec(t);n&&(t=n[1]),t=t.replace(Kd," ").replace(/<!--[\s\S]*?-->/g," ").replace(/<[^>]+>/g," ").replace(/ /gi," ").replace(/&[a-z]+;/gi," ").replace(/\s+/g," ").trim();let r=t===""?0:t.split(" ").filter(Boolean).length;return{wordCount:r,rendered:r<Gd?"empty":"yes"}}async function Hd(e,t){try{let n=await B(e,{headers:{"user-agent":"Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html) SEOAgent-CLI"},redirect:"follow"},{attempts:2,timeoutMs:1e4,fetchImpl:t});if(!n.ok)return{status:n.status,rendered:"error",wordCount:0};let r=await n.text(),{wordCount:o,rendered:i}=qd(r);return{status:n.status,rendered:i,wordCount:o}}catch{return{status:null,rendered:"error",wordCount:0}}}async function Ki(e,t={}){let n=Math.max(1,t.concurrency??5),r=new Map,o=[...e],i=0;async function s(){for(;;){let a=o.shift();if(a===void 0)return;r.set(a,await Hd(a,t.fetchImpl)),i+=1,t.onProgress?.(i,e.length)}}return await Promise.all(Array.from({length:Math.min(n,e.length)},()=>s())),r}var tr=300;async function ft(e={}){if(e.all){await Yd();return}let t=process.cwd();if(!L(t))return;ye(t);let n=Nn(t);Hi(t);let r=await qi(t,{enrichSitemap:!0,crawl:e.crawl});if(n.reason==="refreshed"?(l.success(n.from&&n.from!==n.to?`Refreshed the SEOAgent skill ${n.from} \u2192 ${n.to}.`:`Refreshed the SEOAgent skill (now ${n.to}).`),l.info("Your `.seoagent/` knowledge was left untouched.")):(l.error(`Could not refresh the skill (${n.reason}).`),process.exitCode=1),r.added>0?l.success(`Re-scanned the codebase: +${r.added} new page${r.added===1?"":"s"} merged into .seoagent/pages.md (${r.total} total).`):r.total>0&&l.info(`Page inventory already current (${r.total} pages).`),r.crawl){let{crawled:o,empty:i,errors:s}=r.crawl;l.success(`Crawled ${o} page${o===1?"":"s"} \u2192 filled Status / Rendered / Word count`+(i>0?`, ${i} render empty`:"")+(s>0?`, ${s} unreachable`:"")+".")}}async function qi(e,t={}){try{let n=_(e),r=n?.domain&&n.domain!=="unknown"?n.domain:null,{pages:o}=ce(e,r);t.enrichSitemap&&r&&await co(o,r);let i,s;if(t.crawl&&r){let c=o.map(d=>d.url).filter(d=>/^https?:\/\//.test(d)),u=c.slice(0,tr);if(c.length>tr&&l.info(`Crawling the first ${tr} of ${c.length} pages (cap).`),u.length>0){l.info(`Crawling ${u.length} page${u.length===1?"":"s"}\u2026`),s=await Ki(u);let d=0,p=0;for(let g of s.values())g.rendered==="empty"?d++:g.rendered==="error"&&p++;i={crawled:s.size,empty:d,errors:p}}}let a=jt(e,o,s);return{added:a.added,total:a.total,crawl:i}}catch{return{added:0,total:0}}}async function Yd(){let e=Mr();if(e.length===0){l.info("No SEOAgent projects are registered on this machine yet. They register themselves on `init` / `sync`.");return}l.message(`Refreshing ${e.length} project${e.length===1?"":"s"} to SEOAgent ${Ge.bold(E)}\u2026`);let t=0,n=0;for(let r of e){let o=Nn(r);Hi(r);let i=await qi(r),s=i.added>0?Ge.cyan(` +${i.added} page${i.added===1?"":"s"}`):"";if(o.reason==="refreshed"){t++;let a=o.from&&o.from!==o.to?Ge.dim(` (${o.from} \u2192 ${o.to})`):"";l.message(` ${Ge.green("\u2713")} ${r}${a}${s}`)}else n++,l.message(` ${Ge.yellow("!")} ${r} ${Ge.dim("\u2014 "+o.reason)}${s}`)}l.success(`Refreshed ${t}/${e.length} project${e.length===1?"":"s"} to ${E}.`),n>0&&l.info(`${n} could not be refreshed (see above).`)}function Hi(e){try{he(e)}catch{}}import{spinner as rr,confirm as zd,isCancel as Vd}from"@clack/prompts";import y from"picocolors";var zi={easy_win:"easy win",striking_distance:"striking distance",competitor_gap:"competitor gap",defend:"defend",low_priority:"low priority"};async function Jd(e){let t=process.cwd(),n=Sr(t);if(!n){l.error(`No .seoagent/project.md found. Run \`${f("init")}\` first.`),process.exitCode=1;return}let r=_(t),o=r?.domain&&r.domain!=="unknown"?r.domain:void 0,i=(e.apiBase||A.BASE).replace(/\/$/,""),a=!!process.stdout.isTTY&&!e.json?rr():null;a?.start(`Looking up ${y.bold(`"${e.keyword}"`)} ${y.dim("via DataForSEO (free peek)\u2026")}`);let c;try{c=await B(`${i}/api/cli/keywords/peek`,{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify({install_id:n,keyword:e.keyword,...o?{domain:o}:{}})})}catch(d){k(a,"error",`Network error: ${d.message}`,y.red("Network error.")),process.exitCode=1;return}let u=null;try{u=await c.json()}catch{u=null}if(e.json){process.stdout.write(JSON.stringify({status:u?.status??"error",http_status:c.status,body:u??null})+`
|
|
567
|
-
`);return}if(c.status===429||u?.skipped?.startsWith("rate-limited")){let d=u?.skipped==="rate-limited:ip"?"this network":"this install";k(a,"warn",`Daily peek quota reached for ${d}.`,y.yellow(`Daily peek quota reached for ${d}.`)),l.message(Yi()),process.exitCode=1;return}if(!c.ok||!u){k(a,"error",`Peek failed (${c.status})${u?.error?`: ${u.error}`:""}`,y.red(`Peek failed (${c.status}).`)),process.exitCode=1;return}if(u.skipped==="provider-quota"){k(a,"warn","Real keyword data is temporarily unavailable. Try again later.",y.yellow("Real keyword data is temporarily unavailable. Try again later.")),l.message(y.dim("No action needed on your side \u2014 the maintainer has been notified."));return}if(u.skipped==="no-creds"||u.skipped==="no-table"){k(a,"warn","Real keyword data isn\u2019t enabled on the server yet \u2014 try again later.",y.yellow("Real keyword data is not enabled on the server yet."));return}if(!u.opportunity){k(a,"warn",`No data returned for "${e.keyword}".`,y.yellow(`No data returned for "${e.keyword}".`));return}a?.stop(y.green("Got it.")),l.message(Xd(u.opportunity)),u.remaining&&l.message(`${y.dim("Peeks remaining today:")} ${y.bold(String(u.remaining.install))} ${y.dim("\u2014 "+Yi())}`)}function Xd(e){let n=u=>y.dim(u.padEnd(14)),r=e.volume!=null?y.bold(String(e.volume)):y.dim("n/a"),o=e.difficulty!=null?`${y.bold(String(e.difficulty))} ${y.dim(Qd(e.difficulty))}`:y.dim("n/a"),i=zi[e.opportunity]??e.opportunity,s=e.opportunity==="easy_win"?y.bold(y.green(i)):e.opportunity==="striking_distance"?y.bold(y.cyan(i)):e.opportunity==="competitor_gap"?y.bold(y.yellow(i)):y.dim(i),a=[{content:`${y.green("\u25CF")} ${y.bold(e.keyword)}`},{sep:!0},{content:`${n("Volume:")}${r} ${y.dim("/mo")}`},{content:`${n("Difficulty:")}${o}`},{content:`${n("Opportunity:")}${s}`}],c=`${y.bold(y.cyan("Keyword peek"))}`;return I(a,{width:55,title:c})}function Qd(e){return e<=20?"easy":e<=40?"moderate":e<=60?"hard":"very hard"}function Yi(e=j()){return e?`You're logged in \u2014 run \`${f("keywords")}\` for full enrichment (no quota)
|
|
567
|
+
`);return}if(c.status===429||u?.skipped?.startsWith("rate-limited")){let d=u?.skipped==="rate-limited:ip"?"this network":"this install";k(a,"warn",`Daily peek quota reached for ${d}.`,y.yellow(`Daily peek quota reached for ${d}.`)),l.message(Yi()),process.exitCode=1;return}if(!c.ok||!u){k(a,"error",`Peek failed (${c.status})${u?.error?`: ${u.error}`:""}`,y.red(`Peek failed (${c.status}).`)),process.exitCode=1;return}if(u.skipped==="provider-quota"){k(a,"warn","Real keyword data is temporarily unavailable. Try again later.",y.yellow("Real keyword data is temporarily unavailable. Try again later.")),l.message(y.dim("No action needed on your side \u2014 the maintainer has been notified."));return}if(u.skipped==="no-creds"||u.skipped==="no-table"){k(a,"warn","Real keyword data isn\u2019t enabled on the server yet \u2014 try again later.",y.yellow("Real keyword data is not enabled on the server yet."));return}if(!u.opportunity){k(a,"warn",`No data returned for "${e.keyword}".`,y.yellow(`No data returned for "${e.keyword}".`));return}a?.stop(y.green("Got it.")),l.message(Xd(u.opportunity)),u.remaining&&l.message(`${y.dim("Peeks remaining today:")} ${y.bold(String(u.remaining.install))} ${y.dim("\u2014 "+Yi())}`)}function Xd(e){let n=u=>y.dim(u.padEnd(14)),r=e.volume!=null?y.bold(String(e.volume)):y.dim("n/a"),o=e.difficulty!=null?`${y.bold(String(e.difficulty))} ${y.dim(Qd(e.difficulty))}`:y.dim("n/a"),i=zi[e.opportunity]??e.opportunity,s=e.opportunity==="easy_win"?y.bold(y.green(i)):e.opportunity==="striking_distance"?y.bold(y.cyan(i)):e.opportunity==="competitor_gap"?y.bold(y.yellow(i)):y.dim(i),a=[{content:`${y.green("\u25CF")} ${y.bold(e.keyword)}`},{sep:!0},{content:`${n("Volume:")}${r} ${y.dim("/mo")}`},{content:`${n("Difficulty:")}${o}`},{content:`${n("Opportunity:")}${s}`}],c=`${y.bold(y.cyan("Keyword peek"))}`;return I(a,{width:55,title:c})}function Qd(e){return e<=20?"easy":e<=40?"moderate":e<=60?"hard":"very hard"}function Yi(e=j()){return e?`You're logged in \u2014 run \`${f("keywords")}\` for full enrichment (no quota). Pro unlocks the full inventory beyond the ~25 cap plus \`${f("keywords --discover")}\` (new targets) + \`${f("keywords --competitors")}\` (competitor gaps): ${f("upgrade")}.`:`Log in for the full top-25 enrichment, no quota: ${f("login")}`}function nr(e){let t=e.filter(n=>n.opportunity!=="low_priority");if(t.length!==0){l.message("Top opportunities:");for(let n of t){let r=n.volume!=null?`vol ${n.volume}`:"vol n/a",o=n.difficulty!=null?`KD ${n.difficulty}`:"KD n/a",i=n.our_position!=null?`, you're #${n.our_position}`:", not ranking";l.message(` \u2022 [${zi[n.opportunity]??n.opportunity}] ${n.keyword} \u2014 ${r}, ${o}${i}`)}}}function Zd(e){if(e.length!==0){l.message("Top competitor gaps:");for(let t of e){let n=t.volume!=null?`vol ${t.volume}`:"vol n/a",r=t.difficulty!=null?`KD ${t.difficulty}`:"KD n/a",o=t.their_position!=null?`#${t.their_position}`:"top 10";l.message(` \u2022 ${t.keyword} \u2014 ${t.competitor_domain} ranks ${o}, ${n}, ${r}`)}}}async function ep(e){let t=e.all?"all":"suggested";if(t==="all"&&process.stdin.isTTY){let a=await zd({message:"Delete ALL keywords for this site from the cloud? This cannot be undone."});if(Vd(a)||!a){l.info("No changes.");return}}let n=e.apiBase||e.auth.api_base||A.BASE,r=process.stdout.isTTY?rr():null;r?.start(t==="all"?"Purging all keywords\u2026":"Purging suggested keywords\u2026");let o;try{o=await B(`${n}/api/cli/keywords/purge`,{method:"POST",headers:{"Content-Type":"application/json",Authorization:`Bearer ${e.auth.user_token}:${e.auth.website_token}`},body:JSON.stringify({scope:t})})}catch(a){k(r,"error",`Network error: ${a.message}`,y.red("Network error.")),process.exitCode=1;return}let i=null;try{i=await o.json()}catch{i=null}if(i?.skipped==="no-table"||i?.skipped==="no-columns"){k(r,"warn","Keyword storage isn\u2019t enabled on the server yet.",y.yellow("Nothing to purge yet."));return}if(!o.ok||i?.status!=="ok"){k(r,"error",`Purge failed (${o.status})${i?.error?`: ${i.error}`:""}`,y.red(`Purge failed (${o.status}).`)),process.exitCode=1;return}let s=i.purged??0;k(r,"success",`Purged ${s} ${t==="all"?"":"suggested "}keyword${s===1?"":"s"}.`,y.green(`Purged ${s} keyword${s===1?"":"s"}.`)),l.message(y.dim(t==="all"?"Cleared the cloud inventory. Re-run `seoagent keywords --seed` / strategy to rebuild it.":"Cleared discovery noise. Your clustered keywords were kept."))}async function me(e={}){if(e.peek&&e.peek.trim().length>0){await Jd({keyword:e.peek.trim(),apiBase:e.apiBase,json:e.json});return}let t=j();if(!t){l.error(`Not logged in. Run \`${f("login")}\` first.`),process.exitCode=1;return}if(e.purge){await ep({all:e.all,apiBase:e.apiBase,auth:t});return}let n=e.apiBase||t.api_base||A.BASE,r=`Bearer ${t.user_token}:${t.website_token}`,o=e.competitors?"competitors":e.discover?"discover":e.seed?"seed":"enrich",i=o==="competitors"?"/api/cli/keywords/competitors":o==="discover"?"/api/cli/keywords/discover":o==="seed"?"/api/cli/keywords/seed":"/api/cli/keywords/enrich",s=o==="competitors"?"Finding keywords your competitors rank for\u2026":o==="discover"?"Discovering new keywords to target\u2026":o==="seed"?"Seeding keywords from your Search Console data\u2026":"Enriching keywords with real volume + difficulty\u2026",c=!!process.stdout.isTTY?rr():null;c?.start(s);let u=o==="competitors"||o==="discover"||o==="seed",d;try{d=await B(`${n}${i}`,{method:"POST",headers:{"Content-Type":"application/json",Authorization:r},body:"{}"},u?{timeoutMs:6e4,attempts:1}:{})}catch(m){k(c,"error",`Network error: ${m.message}`,y.red("Network error.")),process.exitCode=1;return}let p=null;try{p=await d.json()}catch{p=null}if(d.status===402||p?.code==="upgrade_required"){k(c,"warn",o==="competitors"?"Competitor gap analysis is a paid feature.":"Keyword discovery is a paid feature.",y.yellow("Paid feature \u2014 upgrade to continue.")),l.message(o==="competitors"?`Upgrade to see which keywords competitors rank for that you don't: ${y.cyan(A.PRICING)}`:`Upgrade to find new keywords to target: ${y.cyan(A.PRICING)}`),process.exitCode=1;return}if(!d.ok||p?.status!=="ok"){k(c,"error",`Server rejected request (${d.status})${p?.error?`: ${p.error}`:""}`,y.red(`Server rejected request (${d.status}).`)),process.exitCode=1;return}if(p.skipped==="no-gsc-data"){k(c,"warn","No Search Console data to seed from yet. Connect Google Search Console (run `seoagent login` and link GSC) \u2014 or wait for impressions to accrue on a new site.",y.yellow("No Search Console data yet."));return}if(p.skipped==="no-keywords"||p.skipped==="no-seeds"){k(c,"warn","No keywords yet. Seed from Search Console with `seoagent keywords --seed`, or run the keyword strategy (Phase 2) first, then try again.",y.yellow("No keywords yet."));return}if(p.skipped==="no-competitors"){k(c,"warn","No competitors found yet. Add competitors or run strategy discovery first, then try again.",y.yellow("No competitors yet."));return}if(p.skipped==="no-creds"||p.skipped==="no-columns"||p.skipped==="no-table"){k(c,"warn","Real keyword data isn\u2019t enabled on the server yet \u2014 try again later.",y.yellow("Real keyword data is not enabled on the server yet."));return}if(p.skipped){k(c,"warn",`Skipped: ${p.skipped}`,y.yellow(`Skipped: ${p.skipped}`));return}if(o==="competitors"){let m=p.gaps??0;k(c,"success",`Found ${m} competitor gap${m===1?"":"s"} across ${p.competitors?.length??0} competitor${p.competitors?.length===1?"":"s"} (added as "suggested").`,y.green(`${m} competitor gap${m===1?"":"s"} found.`)),Zd(p.topGaps??[]),l.message(`Review them in ${y.cyan(".seoagent/keywords.md")} (a read-only projection \u2014 don't hand-edit it). Keep the on-topic ones for your clusters; clear off-topic noise with \`${f("keywords --purge")}\`.`);return}if(o==="discover"){let m=p.discovered??0;k(c,"success",`Discovered ${m} new keyword${m===1?"":"s"} to target (added as "suggested").`,y.green(`${m} new keyword${m===1?"":"s"} discovered.`)),nr(p.opportunities??[]),l.message(`Review them in ${y.cyan(".seoagent/keywords.md")} (a read-only projection \u2014 don't hand-edit it). Relevance-check before adopting; clear off-topic noise with \`${f("keywords --purge")}\`.`);return}if(o==="seed"){let m=p.seeded??0;k(c,"success",`Seeded ${m} keyword${m===1?"":"s"} from Search Console (real impressed queries, added as "suggested").`,y.green(`${m} keyword${m===1?"":"s"} seeded from Search Console.`)),nr(p.opportunities??[]),l.message(`These are queries your site already gets impressions for \u2014 striking-distance wins first. Review in ${y.cyan(".seoagent/keywords.md")} and build clusters from them.`);return}let g=p.enriched??0;k(c,"success",`Enriched ${g} keyword${g===1?"":"s"}.`,y.green(`Enriched ${g} keyword${g===1?"":"s"}.`)),nr(p.opportunities??[]),p.paid||l.message(`${y.dim("Free plan:")} enriched up to ${y.bold(String(p.cap??25))} keywords. ${y.dim("Upgrade for full enrichment + discovery + competitor gap:")} ${y.cyan(A.PRICING)}`)}import P from"picocolors";function mt(e={}){let t=process.cwd(),n=_(t),r=ae(t);if(e.json){process.stdout.write(JSON.stringify(r,null,2)+`
|
|
568
568
|
`);return}if(l.message(tp(r)),!n){l.warn(`No SEOAgent project here. Run \`${f("init")}\` first to persist the provider.`);return}z(t,{image_provider:r.provider}),l.info(`Saved to ${P.cyan(".seoagent/project.md")} ${P.dim(`(image_provider: ${r.provider})`)}`)}function tp(e){let n=i=>P.dim(i.padEnd(12)),r=[];if(e.provider==="none"){r.push({content:`${P.dim("\u25CB")} ${P.bold(P.yellow("No image provider detected"))}`}),r.push({sep:!0}),r.push({content:P.dim("Set ONE of these to enable image generation:")});let i=eo();for(let s of Object.keys(i))r.push({content:`${n(s+":")}${P.cyan(i[s].join(" or "))}`});r.push({sep:!0}),r.push({content:P.dim("Add to your shell, .env.local, or .env, then re-run:")}),r.push({content:` ${P.cyan(f("env-check"))}`})}else{r.push({content:`${P.green("\u2713")} ${P.dim("Image provider:")} ${P.bold(P.green(e.provider))}`}),r.push({sep:!0}),e.matched_key&&r.push({content:`${n("Key:")}${P.bold(e.matched_key)}`}),e.source&&r.push({content:`${n("Source:")}${P.cyan(e.source)}`});let i=e.available_providers.filter(s=>s!==e.provider);i.length>0&&r.push({content:`${n("Available:")}${P.dim(i.join(", "))}`})}let o=`${P.bold(P.cyan("SEOAgent"))} ${P.dim("\xB7")} ${P.dim("env-check")}`;return I(r,{width:64,title:o})}import{existsSync as ir,mkdirSync as Xi,writeFileSync as Qi}from"fs";import{dirname as en,isAbsolute as sp,join as Zt,resolve as ap}from"path";import{tmpdir as cp}from"os";import{spinner as lp}from"@clack/prompts";import N from"picocolors";import{Buffer as Vi}from"buffer";async function or(e){let t=await fetch(e);if(!t.ok)throw new Error(`Image download failed: ${t.status} ${t.statusText}`);let n=await t.arrayBuffer();return Vi.from(n)}async function np(e){let t=e.size??"1024x1024",n=await fetch("https://api.openai.com/v1/images/generations",{method:"POST",headers:{Authorization:`Bearer ${e.apiKey}`,"Content-Type":"application/json"},body:JSON.stringify({model:"gpt-image-1",prompt:e.prompt,size:t,n:1})});if(!n.ok){let i=await n.text().catch(()=>"");throw new Error(`OpenAI image API ${n.status}: ${i.slice(0,300)}`)}let o=(await n.json()).data?.[0];if(!o)throw new Error("OpenAI image API returned no data");if(o.b64_json)return{bytes:Vi.from(o.b64_json,"base64"),contentType:"image/png"};if(o.url)return{bytes:await or(o.url),contentType:"image/png"};throw new Error("OpenAI image API returned neither b64_json nor url")}async function rp(e){let t=process.env.FAL_MODEL||"fal-ai/flux/schnell",n=await fetch(`https://fal.run/${t}`,{method:"POST",headers:{Authorization:`Key ${e.apiKey}`,"Content-Type":"application/json"},body:JSON.stringify({prompt:e.prompt,image_size:"landscape_16_9",num_images:1})});if(!n.ok){let s=await n.text().catch(()=>"");throw new Error(`fal.ai API ${n.status}: ${s.slice(0,300)}`)}let o=(await n.json()).images?.[0];if(!o?.url)throw new Error("fal.ai API returned no image url");return{bytes:await or(o.url),contentType:o.content_type??"image/png"}}async function op(e,t,n=9e4){let r=Date.now(),o=1e3;for(;Date.now()-r<n;){let i=await fetch(`https://api.replicate.com/v1/predictions/${e}`,{headers:{Authorization:`Token ${t}`}});if(!i.ok)throw new Error(`Replicate poll failed: ${i.status}`);let s=await i.json();if(s.status==="succeeded"||s.status==="failed"||s.status==="canceled")return s;await new Promise(a=>setTimeout(a,o)),o=Math.min(o*1.5,5e3)}throw new Error("Replicate prediction timed out")}async function ip(e){let t=process.env.REPLICATE_MODEL||"black-forest-labs/flux-schnell",n=await fetch(`https://api.replicate.com/v1/models/${t}/predictions`,{method:"POST",headers:{Authorization:`Token ${e.apiKey}`,"Content-Type":"application/json",Prefer:"wait"},body:JSON.stringify({input:{prompt:e.prompt,aspect_ratio:"16:9"}})});if(!n.ok){let s=await n.text().catch(()=>"");throw new Error(`Replicate API ${n.status}: ${s.slice(0,300)}`)}let r=await n.json();if(r.status!=="succeeded"&&r.status!=="failed"&&(r=await op(r.id,e.apiKey)),r.status!=="succeeded")throw new Error(`Replicate prediction ${r.status}: ${r.error??""}`);let o=Array.isArray(r.output)?r.output[0]:r.output;if(!o)throw new Error("Replicate prediction returned no output");return{bytes:await or(o),contentType:"image/png",providerImageId:r.id}}async function Ji(e,t){switch(e){case"openai":return np(t);case"fal":return rp(t);case"replicate":return ip(t);default:throw new Error(`Unknown image provider: ${e}`)}}function up(e){return e==="openai"||e==="fal"||e==="replicate"}async function gt(e={}){let t=process.cwd();if(!e.prompt){l.warn(`Missing --prompt. Example: ${f('generate-image --prompt "..." --out content/images/hero.png')}`),process.exitCode=1;return}if(!e.out){l.warn("Missing --out. Example: --out .seoagent/content/images/hero.png"),process.exitCode=1;return}let n=_(t),r=null;if(e.provider){if(!up(e.provider)){l.warn(`Invalid --provider "${e.provider}". Use one of: openai, fal, replicate.`),process.exitCode=1;return}r=e.provider}else n?.image_provider&&n.image_provider!=="none"?r=n.image_provider:r=ae(t).provider;if(!r||r==="none"){l.warn(`No image generation provider available. Set OPENAI_API_KEY, FAL_KEY, or REPLICATE_API_TOKEN, then run \`${f("env-check")}\`.`),process.exitCode=1;return}let o=Zr(t,r);if(!o){l.warn(`Provider "${r}" selected but no API key found. Set the env var, then re-run.`),process.exitCode=1;return}let i=sp(e.out)?e.out:ap(t,e.out),a=!e.silent&&!!process.stdout.isTTY?lp():null;a?.start(`Generating image with ${N.bold(r)} ${N.dim(`(${o.envName})`)}\u2026`);try{let c=await Ji(r,{prompt:e.prompt,apiKey:o.key,size:e.size});ir(en(i))||Xi(en(i),{recursive:!0}),Qi(i,c.bytes),e.silent||k(a,"success",`Wrote ${i} (${c.bytes.length} bytes, ${c.contentType}).`,N.green(`Wrote ${i} ${N.dim(`(${c.bytes.length} bytes, ${c.contentType})`)}`))}catch(c){a?.stop(N.red("Image generation failed."));let u=pp(t,{provider:r,envName:o.envName,prompt:e.prompt,size:e.size,outPath:i,error:c});l.message(dp({provider:r,envName:o.envName,prompt:e.prompt,size:e.size,message:c.message})),u&&l.message(`${N.dim("Full error log:")} ${N.cyan(u)}`),process.exitCode=1}}function dp(e){let n=d=>N.dim(d.padEnd(10)),o=e.prompt.length>54?`${e.prompt.slice(0,53)}\u2026`:e.prompt,i=[{content:`${N.red("\u2717")} ${N.bold(N.red("Image generation failed"))}`},{sep:!0},{content:`${n("Provider:")}${N.bold(e.provider)}`},{content:`${n("Key:")}${e.envName}`},{content:`${n("Prompt:")}${N.dim(`"${o}"`)}`}];e.size&&i.push({content:`${n("Size:")}${e.size}`}),i.push({sep:!0});let s=e.message.replace(/\s+/g," ").trim(),a=64,c=s.length>a?`${s.slice(0,a-1)}\u2026`:s;i.push({content:N.red(c)});let u=`${N.bold(N.cyan("SEOAgent"))} ${N.dim("\xB7")} ${N.dim("generate-image")}`;return I(i,{width:70,title:u})}function pp(e,t){let r=`seoagent-generate-image-${new Date().toISOString().replace(/[:.]/g,"-")}.log`,o=Zt(e,w),i=Zt(o,".errors"),s=ir(o)?Zt(i,r):Zt(cp(),r),a=["# SEOAgent generate-image error",`# ${new Date().toISOString()}`,"","## Request",`provider: ${t.provider}`,`env_var: ${t.envName}`,`prompt: ${JSON.stringify(t.prompt)}`,`size: ${t.size??"(default)"}`,`out_path: ${t.outPath}`,`cwd: ${e}`,"","## Error",`message: ${t.error.message}`,"","## Stack",t.error.stack??"(no stack)",""];t.error.cause&&a.push("## Cause",String(t.error.cause),"");try{return ir(en(s))||Xi(en(s),{recursive:!0}),Qi(s,a.join(`
|
|
569
569
|
`)),s}catch{return null}}import G from"picocolors";async function ht(e={}){let t=j();if(!t){e.json?process.stdout.write(`${JSON.stringify({logged_in:!1})}
|
|
570
570
|
`):l.error(`Not logged in. Run \`${f("login")}\` first.`),process.exitCode=1;return}let n=(e.apiBase||t.api_base||A.BASE).replace(/\/$/,""),r=`Bearer ${t.user_token}:${t.website_token}`,o;try{o=await fetch(`${n}/api/cli/whoami`,{method:"GET",headers:{Authorization:r,Accept:"application/json"}})}catch(s){l.error(`Network error: ${s.message}`),process.exitCode=1;return}if(o.status===404){if(e.json){process.stdout.write(`${JSON.stringify({logged_in:!0,server_supports_whoami:!1,api_base:n})}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@seoagent-official/seoagent",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.65.0",
|
|
4
4
|
"description": "The persistent AI SEO agent for Claude Code. Audits, keyword strategy, briefs, articles, and the autopilot loop (cloud detects → CLI executes → ack closes) — other SEO tools write the prompt, SEOAgent runs it.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|
|
@@ -1,10 +1,20 @@
|
|
|
1
1
|
# Keyword Research Protocol
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
**Use the richest real data the account is entitled to — WebSearch estimates are the fallback, not the default.** Check the tier (you usually know it; else `seoagent whoami` → `plan`/`paid`):
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
| Tier | Data path |
|
|
6
|
+
|---|---|
|
|
7
|
+
| **Pro / paid** | **Full DataForSEO** — `seoagent keywords` (enrich, no quota) + `--discover` (new targets) + `--competitors` (gap keywords). Don't fall back to WebSearch estimates for a paid user. |
|
|
8
|
+
| **Free account (logged in)** | `seoagent keywords` — real volume/difficulty for the top ~25 (no quota). WebSearch for breadth beyond 25. Surface the Pro upsell. |
|
|
9
|
+
| **Anonymous (no login)** | `keywords --peek "<kw>"` — a *single*-keyword spot-check, ~10/day quota. WebSearch H/M/L for breadth. Recommend `seoagent login`. |
|
|
6
10
|
|
|
7
|
-
|
|
11
|
+
**Never loop `--peek` across many keywords** — it's the anonymous single-keyword tool and will hit its ~10/day quota. Logged in, `seoagent keywords` enriches the whole top set at once with no quota. Use `--peek` only when not logged in, or to validate one finalist.
|
|
12
|
+
|
|
13
|
+
**WebSearch H/M/L priorities are directional** — use them only when real numbers aren't available (anonymous breadth, beyond the free ~25, a `402` gate, or first-mover terms below). Never invent numeric scores.
|
|
14
|
+
|
|
15
|
+
> **First-mover terms DataForSEO can't size = opportunity.** Brand-new on-strategy categories (`claude code seo`, `cursor seo`, an emerging product term) often return **no volume / no data**. For a first-mover that means low competition you can own before the volume arrives — **don't discard an on-strategy term for lack of data**; mark it `first_mover`/high-opportunity (cite `context.md` + any GSC impressions or WebSearch signal) and prioritize. Treat no-data as low-value only when the term is *also* off-strategy.
|
|
16
|
+
|
|
17
|
+
**Cold start — seed from Search Console.** On a site with **no keyword inventory yet**, the best first move (once `seoagent login` + GSC are connected) is `seoagent keywords --seed`: it adds the site's **own impressed GSC queries** — real, inherently relevant, winnable terms (page-2 queries become "striking distance"). It's **additive** (adds new queries, keeps any existing keywords — never overwrites). Do this *before* `--discover`/`--competitors`, which need a topic signal and otherwise return noise.
|
|
8
18
|
|
|
9
19
|
**Cold start — seed from Search Console.** On a site with **no keyword inventory yet**, the best first move (once `seoagent login` + GSC are connected) is `seoagent keywords --seed`: it adds the site's **own impressed GSC queries** — real, inherently relevant, winnable terms (page-2 queries become "striking distance"). It's **additive** (adds new queries, keeps any existing keywords — never overwrites). Do this *before* `--discover`/`--competitors`, which need a topic signal and otherwise return noise.
|
|
10
20
|
|
|
@@ -14,8 +24,8 @@ A **free SEOAgent Cloud account** enriches the top ~25 keywords with **real volu
|
|
|
14
24
|
|
|
15
25
|
`--discover` and `--competitors` are **expansion** tools — they only work well once the site has a real topic signal. On a brand-new or thin site they degrade into generic high-volume noise (e.g. "1/8 as a decimal") because DataForSEO has nothing relevant to anchor to. Follow this order:
|
|
16
26
|
|
|
17
|
-
1. **
|
|
18
|
-
2. **
|
|
27
|
+
1. **Seed the inventory FIRST so discovery has a signal** — via `keywords --seed` (GSC) and/or a WebSearch pass (the steps below). This isn't "WebSearch instead of DataForSEO"; it's giving `--discover`/`--competitors` a real topic to anchor to so they don't return generic noise. Once there's an inventory, real DataForSEO leads.
|
|
28
|
+
2. **Name real competitors (improves `--competitors`).** Write competitors to `.seoagent/competitors.md` **with real domains in the headings** (e.g. `## Competitor 1: Surfer SEO — surferseo.com`) — that's what's parsed into the cloud's competitor table. `seoagent sync`. On Pro, `--competitors` will *also* auto-discover rivals (DataForSEO `competitors_domain`) and merge them, but naming the obvious ones up front gives it a cleaner anchor on a thin domain. (No DataForSEO/Pro? A WebSearch competitor pass into `competitors.md` is the free substitute.)
|
|
19
29
|
3. **Then** run `seoagent keywords` (enrich) → `--discover` → `--competitors`.
|
|
20
30
|
4. **Always relevance-check what they return.** Treat every `status='suggested'` keyword as a *candidate*, not a fact — drop anything off-topic for the business before adding it to the strategy, no matter how high the volume or low the difficulty. The server now filters obvious noise, but you are the final gate.
|
|
21
31
|
5. **For a single keyword's real numbers without the bulk commands, use `--peek`** — it's reliable and quota-limited; ideal for validating finalists.
|
|
@@ -150,6 +160,8 @@ Write each cluster to `.seoagent/strategy/clusters/{cluster-slug}.md` with the m
|
|
|
150
160
|
|
|
151
161
|
### Step 7: Tag Priority
|
|
152
162
|
|
|
163
|
+
**Use real DataForSEO volume + difficulty + opportunity labels when the account has them** (logged in → top ~25; Pro → the whole inventory). H/M/L bins below are the **fallback** for terms you only have WebSearch signal for (and for first-mover terms with no data — tag those high-opportunity, not low). Don't downgrade a real low-difficulty/striking-distance term to "M" on a hunch when the data says otherwise.
|
|
164
|
+
|
|
153
165
|
Use H/M/L bins:
|
|
154
166
|
- **High** — high search demand signals (autocomplete, multiple SERP results, "people also ask"), low competition (no Wikipedia, no government, no huge brands), strong business fit
|
|
155
167
|
- **Medium** — decent demand but competitive, OR low demand but easy to win
|
|
@@ -0,0 +1,138 @@
|
|
|
1
|
+
# Listicle Article Protocol
|
|
2
|
+
|
|
3
|
+
A listicle is a **format**, not a cluster role: a ranked or curated set of items ("Top 10 X", "Best N Y", "7 Ways to Z"). By cluster role a listicle is almost always a **SUB_PILLAR** or **LONG_TAIL** (a spoke that funnels authority UP). Write it in this format *on top of* its role — tag it `article_type: listicle` (and `page_type: listicle`) so the cloud pipeline applies listicle handling + `ItemList` schema.
|
|
4
|
+
|
|
5
|
+
The win: listicles dominate **commercial-investigation** SERPs ("best", "top", "alternatives") and are the format AI answer engines quote most for "what are the best X" — a clean item list is trivially extractable.
|
|
6
|
+
|
|
7
|
+
## When to Use
|
|
8
|
+
|
|
9
|
+
- The title matches a listicle pattern the backend recognizes: `Top N`, `Best N`, `N Best`, `N Top`, `N Ways`, `N Tips`, `N Reasons`. (Inference regex: `/(top \d+|best \d+|\d+ best|\d+ top|\d+ ways|\d+ tips|\d+ reasons)/i`.)
|
|
10
|
+
- Intent is commercial-investigation or "show me the options": *best ai seo tools*, *clearscope alternatives*, *top next.js seo plugins*.
|
|
11
|
+
- You have a genuine, defensible set of items. If you can't fill N with real, distinct entries, pick a smaller N or write a guide instead.
|
|
12
|
+
|
|
13
|
+
## URL & Slug Rules
|
|
14
|
+
|
|
15
|
+
- `/blog/{primary-keyword}` — flat, same as every other post.
|
|
16
|
+
- Slug = the keyword, not the number: `best-ai-seo-tools`, **not** `top-10-ai-seo-tools` (the count changes when you update the list; the keyword doesn't). Keep the number in the title, out of the slug.
|
|
17
|
+
|
|
18
|
+
## Word Count Target
|
|
19
|
+
|
|
20
|
+
Driven by item count, not a fixed total: **~120–250 words per item** + ~150-word intro + ~150-word conclusion. So a Top 7 ≈ 1,300–1,900 words; a Top 12 ≈ 1,900–3,200. Don't pad thin items to match the fat ones — uneven depth is fine if the item warrants it, but every item earns its slot.
|
|
21
|
+
|
|
22
|
+
## Title Patterns
|
|
23
|
+
|
|
24
|
+
The number is part of the promise — keep it. Add the year for freshness on "best/top" commercial terms.
|
|
25
|
+
|
|
26
|
+
1. **{N} Best {category} ({year})** — `10 Best AI SEO Tools (2026)`
|
|
27
|
+
2. **Top {N} {category} for {audience/use case}** — `Top 7 SEO Tools for Next.js Developers`
|
|
28
|
+
3. **{N} {category} {qualifier}** — `9 Free Keyword Research Tools`
|
|
29
|
+
4. **Best {category} for {use case}** (no number — a curated "best of") — `Best AI SEO Tools for Indie Hackers`
|
|
30
|
+
|
|
31
|
+
Match the number in the title to the actual item count. A title that says 10 with 8 items reads as sloppy and Google notices the mismatch.
|
|
32
|
+
|
|
33
|
+
## Section Structure
|
|
34
|
+
|
|
35
|
+
1. **Intro (≤150 words)** — what the list covers, who it's for, and *how you chose* (the selection criteria — one line builds trust + E-E-A-T). Don't bury the list behind a 600-word preamble; searchers came for the items.
|
|
36
|
+
2. **Quick-pick summary** — 2–5 bolded verdicts right after the intro: **Best overall:** X · **Best free:** Y · **Best for {use case}:** Z. This is the AI-extractable / featured-snippet payload — put it high.
|
|
37
|
+
3. **At-a-glance comparison table** (strongly recommended for tools/products) — columns like Tool · Best for · Price · Standout. One row per item. Tables are the single most-quoted element in AI Overviews for "best X".
|
|
38
|
+
4. **The items** — one H2 per item, **identical sub-structure for every item** (see below). Consistency *is* the quality bar for a listicle.
|
|
39
|
+
5. **How to choose** — a short H2 helping the reader self-select ("pick X if…, Y if…"). Reinforces the quick-pick.
|
|
40
|
+
6. **FAQ** — only if there are genuinely 3+ recurring sub-questions ("is there a free option?", "which works with WordPress?").
|
|
41
|
+
|
|
42
|
+
### Per-item structure (keep it identical across all items)
|
|
43
|
+
|
|
44
|
+
Each item is an H2 (`## 1. {Item name}` — numbered so the count is unmistakable), then the **same** beats in the **same order**:
|
|
45
|
+
|
|
46
|
+
- **One-line verdict** (bold) — the take. *"The most automated option if you live in your editor."*
|
|
47
|
+
- **What it is** — 1–2 sentences.
|
|
48
|
+
- **Standout / why it's on the list** — the differentiator.
|
|
49
|
+
- **Best for** — the audience this item suits.
|
|
50
|
+
- **Pricing** — real, current, or "free / from $X/mo" (don't invent numbers — leave it out if unknown).
|
|
51
|
+
- *(Optional)* **Pros / Cons** — 2–3 each, as tight bullets.
|
|
52
|
+
- A link — to the item's site, or to your own page if it's your product/an internal target.
|
|
53
|
+
|
|
54
|
+
## Honesty & positioning (when your own product is on the list)
|
|
55
|
+
|
|
56
|
+
Including yourself is fine and expected — but **earn the placement**. State real strengths and real limits; don't auto-rank yourself #1 over obviously stronger incumbents. A listicle that's transparently self-serving loses the trust (and the citations) that make the format work. If you're a first-mover in the category, say *why* you're listed (the honest differentiator), not just *that* you're #1. Follow `.seoagent/context.md` for current positioning and banned claims.
|
|
57
|
+
|
|
58
|
+
## Internal Linking — a listicle links UP and OUT
|
|
59
|
+
|
|
60
|
+
Read `.seoagent/strategy/clusters/{cluster-slug}.md`:
|
|
61
|
+
- **Link UP** to the parent (sub_pillar if this is a long_tail; the pillar if this is a sub_pillar) — at least once.
|
|
62
|
+
- **Link OUT to your own pages** when an item *is* your product or maps to one of your `/compare`, `/features`, or pillar pages — the listicle is a hub that distributes authority to commercial pages.
|
|
63
|
+
- Link sideways to a sibling listicle/spoke once if relevant.
|
|
64
|
+
|
|
65
|
+
## AI Search Optimization
|
|
66
|
+
|
|
67
|
+
Listicles are prime AI-Overview real estate. Optimize for extraction:
|
|
68
|
+
- **Quick-pick verdicts + comparison table high on the page** — these are what gets quoted.
|
|
69
|
+
- **Consistent per-item structure** so an LLM can parse each entry into the same fields.
|
|
70
|
+
- **The number in an H2 per item** (`## 3. …`) makes the list machine-countable.
|
|
71
|
+
- Keep verdicts declarative and standalone ("X is the best free option because…").
|
|
72
|
+
|
|
73
|
+
## Metadata Defaults
|
|
74
|
+
|
|
75
|
+
```yaml
|
|
76
|
+
title: "{N} Best {category} ({year})"
|
|
77
|
+
article_type: listicle # so the cloud pipeline applies listicle handling
|
|
78
|
+
page_type: listicle
|
|
79
|
+
meta_title: "{N} Best {category} ({year})" # ≤60 chars
|
|
80
|
+
meta_description: "Our pick of the {N} best {category} for {audience} in {year} — {best-overall} for X, {best-free} for Y, and more." # 150-160 chars
|
|
81
|
+
canonical: "https://{domain}/blog/{slug}"
|
|
82
|
+
og:
|
|
83
|
+
title: "{Title}"
|
|
84
|
+
description: "{The quick-pick verdicts in one line}"
|
|
85
|
+
image_alt: "{...}"
|
|
86
|
+
twitter:
|
|
87
|
+
card: summary_large_image
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
## JSON-LD Schema
|
|
91
|
+
|
|
92
|
+
A listicle's defining schema is **`ItemList`** (in addition to `Article`). For tool/product round-ups, type each item as `SoftwareApplication`/`Product`; add `Review`/`AggregateRating` only if you have real ratings.
|
|
93
|
+
|
|
94
|
+
```json
|
|
95
|
+
[
|
|
96
|
+
{
|
|
97
|
+
"@type": "Article",
|
|
98
|
+
"headline": "{Title}",
|
|
99
|
+
"author": { "@type": "Person", "name": "{Author}" },
|
|
100
|
+
"datePublished": "{ISO date}",
|
|
101
|
+
"dateModified": "{ISO date}",
|
|
102
|
+
"image": "https://{domain}/{hero}",
|
|
103
|
+
"publisher": { "...": "..." }
|
|
104
|
+
},
|
|
105
|
+
{
|
|
106
|
+
"@type": "ItemList",
|
|
107
|
+
"itemListOrder": "https://schema.org/ItemListOrderDescending",
|
|
108
|
+
"numberOfItems": "{N}",
|
|
109
|
+
"itemListElement": [
|
|
110
|
+
{ "@type": "ListItem", "position": 1, "name": "{Item 1}", "url": "{item-1-url}" },
|
|
111
|
+
{ "@type": "ListItem", "position": 2, "name": "{Item 2}", "url": "{item-2-url}" }
|
|
112
|
+
]
|
|
113
|
+
}
|
|
114
|
+
]
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
Use `itemListOrder` `…OrderAscending`/`…OrderDescending` for a true ranking; omit it (or use unordered) for an unranked "best of". See `references/schema-markup.md` for the full JSON-LD rules.
|
|
118
|
+
|
|
119
|
+
## Quality rules — a listicle is LIGHTER than a guide/pillar
|
|
120
|
+
|
|
121
|
+
The cloud's type-conditional quality bar does **not** require Principle Callouts, a Boundary section, Reusable Artifacts, or Citations on a listicle (those are for guide/pillar/how_to). Don't force pillar-style scaffolding onto a list — it bloats it. The listicle's quality bar is: **complete & current item set, consistent per-item structure, honest verdicts, a comparison table, and the quick-pick summary.**
|
|
122
|
+
|
|
123
|
+
## After Writing
|
|
124
|
+
|
|
125
|
+
1. Update the cluster file — set this article's `status: drafted` and note `format: listicle` in the article table.
|
|
126
|
+
2. **Link UP** — edit the parent (sub_pillar/pillar) to reference this listicle if it isn't already linked.
|
|
127
|
+
3. Append to `.seoagent/changelog.md`: `[date] Listicle drafted: {slug} ({N} items, {word_count} words)`.
|
|
128
|
+
4. Run `seoagent sync`.
|
|
129
|
+
|
|
130
|
+
## Common Pitfalls
|
|
131
|
+
|
|
132
|
+
- **Title/count mismatch.** Title says 10, body has 8. Fix one or the other.
|
|
133
|
+
- **Uneven items.** Item 1 gets 400 words, item 7 gets 40. Keep the per-item structure consistent.
|
|
134
|
+
- **Number in the slug.** `top-10-…` rots when the list changes; use the keyword.
|
|
135
|
+
- **Burying the list.** A 600-word intro before item 1. Lead with the quick-pick + table.
|
|
136
|
+
- **Dishonest self-ranking.** Putting your product #1 over clearly stronger tools — kills trust and citations.
|
|
137
|
+
- **Padding to pillar length.** A listicle is as long as its items justify; don't inflate to 3,000 words.
|
|
138
|
+
- **No comparison table / no quick-pick.** You're leaving the AI-Overview and featured-snippet wins on the table.
|
package/skills/seoagent.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: seoagent
|
|
3
|
-
description: "Persistent AI SEO agent. ALWAYS use when the user mentions: SEO, ranking, rank, keywords, meta tags, search traffic, organic traffic, content strategy, audit, Google, Bing, Search Console, GSC, schema markup, JSON-LD, sitemap, robots.txt, internal linking, AI search, AEO, GEO, OKF, Open Knowledge Format, AI knowledge bundle, llms.txt, alt text, page speed, Core Web Vitals, slug, URL structure, canonical, breadcrumbs, hub and spoke, pillar content, topic cluster, programmatic SEO, landing page SEO, blog SEO, why am I not ranking. Also use SILENTLY when the user asks to write, edit, or improve a blog post, landing page, marketing copy, or any file under content/, posts/, blog/, pages/ — these are SEO-adjacent and should persist to .seoagent/ even without an explicit invocation. Replaces separate seo-audit, content-strategy, programmatic-seo, ai-seo, site-architecture, and schema-markup skills with one unified, persistent workflow."
|
|
3
|
+
description: "Persistent AI SEO agent. ALWAYS use when the user mentions: SEO, ranking, rank, keywords, meta tags, search traffic, organic traffic, content strategy, audit, Google, Bing, Search Console, GSC, schema markup, JSON-LD, sitemap, robots.txt, internal linking, AI search, AEO, GEO, OKF, Open Knowledge Format, AI knowledge bundle, llms.txt, alt text, page speed, Core Web Vitals, slug, URL structure, canonical, breadcrumbs, hub and spoke, pillar content, topic cluster, programmatic SEO, landing page SEO, blog SEO, listicle, best-of / top-N roundup, why am I not ranking. Also use SILENTLY when the user asks to write, edit, or improve a blog post, landing page, marketing copy, or any file under content/, posts/, blog/, pages/ — these are SEO-adjacent and should persist to .seoagent/ even without an explicit invocation. Replaces separate seo-audit, content-strategy, programmatic-seo, ai-seo, site-architecture, and schema-markup skills with one unified, persistent workflow."
|
|
4
4
|
allowed-tools: Read, Write, Edit, Bash, WebFetch, WebSearch
|
|
5
5
|
---
|
|
6
6
|
|
|
@@ -42,6 +42,7 @@ This SKILL.md is the orchestration layer. Detailed protocols live in `references
|
|
|
42
42
|
| Writing a pillar article | `references/pillar-articles.md` |
|
|
43
43
|
| Writing a sub-pillar article | `references/sub-pillar-articles.md` |
|
|
44
44
|
| Writing a long-tail article | `references/long-tail-articles.md` |
|
|
45
|
+
| Writing a listicle ("Top N" / "Best X") | `references/listicle-articles.md` |
|
|
45
46
|
| Programmatic SEO at scale | `references/programmatic.md` |
|
|
46
47
|
| Adding schema markup / JSON-LD | `references/schema-markup.md` |
|
|
47
48
|
| Refreshing or rewriting an existing page | `references/rewrite-protocol.md` |
|
|
@@ -490,7 +491,7 @@ The single biggest quality lever for the strategy is **real Google Search Consol
|
|
|
490
491
|
- **On-strategy** — aligned with the current positioning → keep and prioritize (these are real, winnable, *and* on-message).
|
|
491
492
|
- **Legacy / off-strategy** — demand from an older brand, product, or audience the site has moved away from → mark as *harvest/defend* (worth keeping rankings, not worth building the new strategy around). Note them as such; don't let them steer the clusters.
|
|
492
493
|
4. **Add forward-looking clusters GSC can't show.** The new direction has little or no search history yet, so it won't appear in `--seed`. Generate those targets from the current positioning (`context.md`) + WebSearch — this is where the strategy points *forward*, not backward.
|
|
493
|
-
5. **No GSC data yet (brand-new site)?** `--seed` will say so —
|
|
494
|
+
5. **No GSC data yet (brand-new site)?** `--seed` will say so — use WebSearch to draft the clusters, then get real numbers the tier allows: **logged in → `seoagent keywords`** (enrich the drafted set), **Pro → also `keywords --discover`** for new targets; `--peek` only if not logged in. Revisit `--seed` once impressions accrue. **Stale GSC?** If the freshest seeded data looks weeks old, the cloud GSC sync may be behind — flag it; the seed is only as fresh as the synced data.
|
|
494
495
|
|
|
495
496
|
### Cluster Structure (Hub and Spoke)
|
|
496
497
|
|
|
@@ -508,13 +509,25 @@ The role enum is `PILLAR | SUB_PILLAR | LONG_TAIL` — these match the SEOAgent
|
|
|
508
509
|
|
|
509
510
|
> **Writing order — pillars to plant the hubs, then DEPTH before breadth.** Write each cluster's PILLAR first so every topic has its hub. But once the pillars exist, **complete one cluster before opening the next** — finish the spokes of your single highest-priority cluster rather than scattering one or two articles across all of them. A *complete* hub-and-spoke cluster is what signals topical authority and lifts the whole cluster's rankings; three half-built clusters dilute that signal and leave every topic shallow. Choose which cluster to finish by **ICP fit × easy-win density** (the cluster whose audience is your actual customer and whose keywords are lowest-difficulty), not by what's most fun to write. Only start the next cluster once the current one's spokes are essentially done. When you summarize "what's next", recommend the specific cluster to finish, not a scatter of articles.
|
|
510
511
|
|
|
511
|
-
###
|
|
512
|
+
### Keyword data: use real DataForSEO by tier — WebSearch is the FALLBACK
|
|
512
513
|
|
|
513
|
-
|
|
514
|
+
**Real DataForSEO numbers are the default whenever the account can get them — don't lead with WebSearch estimates.** Check the tier first (you usually know it from the session; if not, `seoagent whoami` returns `plan` + `paid`), then use the richest data the account is entitled to:
|
|
514
515
|
|
|
515
|
-
|
|
516
|
+
| Tier | Run | You get |
|
|
517
|
+
|---|---|---|
|
|
518
|
+
| **Pro / paid (`paid: true`)** | `seoagent keywords` (enrich, no quota) → `keywords --discover` (new targets) → `keywords --competitors` (competitor gaps) | **Full DataForSEO** — real volume/difficulty across the inventory, new-target discovery, competitor-gap keywords. **This is the path for a Pro user — do NOT fall back to WebSearch estimates for them.** |
|
|
519
|
+
| **Free account (logged in, `paid: false`)** | `seoagent keywords` | Real DataForSEO volume/difficulty for the top ~25 keywords (no quota). WebSearch only for breadth beyond 25. **Surface the Pro upsell** (below). |
|
|
520
|
+
| **Anonymous (not logged in)** | `keywords --peek "<kw>"` for a *single* spot-check (~10/day) + WebSearch H/M/L for breadth | A taste. **Recommend `seoagent login`** — a free account turns peek-spam into full top-25 enrichment, no quota. |
|
|
521
|
+
|
|
522
|
+
> **Never loop `--peek` across many keywords.** It's an anonymous *single-keyword* spot-check with a ~10/day quota — burning it on 15 lookups (then running dry) is the wrong tool and a real dogfooding mistake. The instant the user is logged in, `seoagent keywords` enriches the whole top set at once with **no quota**. Peek exists only for the not-logged-in "what's this one keyword worth?" moment.
|
|
523
|
+
|
|
524
|
+
**WebSearch H/M/L estimates are the FALLBACK, not the default.** Use them only for: anonymous breadth, keywords beyond a free account's ~25, a `402 upgrade_required` gate, or first-mover terms DataForSEO can't size (next). Never invent numeric scores — H/M/L only.
|
|
525
|
+
|
|
526
|
+
> **First-mover terms DataForSEO can't size — that's opportunity, not absence of it.** DataForSEO under-rates brand-new, on-strategy categories: `claude code seo`, `cursor seo`, an emerging product term may return **no volume / no data**. For a first-mover, no keyword-tool data on an **on-strategy** term means low competition you can own *before* the volume shows up. **Do NOT discard an on-strategy term just because DataForSEO has nothing** — mark it `first_mover` / high-opportunity (cite the strategy in `context.md` + any GSC impressions or WebSearch signal) and prioritize it. Only treat no-data as low-value when the term is *also* off-strategy.
|
|
527
|
+
|
|
528
|
+
> **Competitor research by tier.** **Pro:** run `seoagent keywords --competitors` — it auto-discovers competitors (DataForSEO `competitors_domain`) and returns keywords they rank top-10 for that you don't, no manual setup. Don't hand-research what the API will hand you. **Free / anonymous:** do a **WebSearch competitor pass** (find the 3–5 real rivals in the category, profile positioning + top content), write them into `.seoagent/competitors.md`, then surface that Pro turns this into automated competitor-gap keywords.
|
|
516
529
|
|
|
517
|
-
A **free SEOAgent Cloud account**
|
|
530
|
+
A **free SEOAgent Cloud account** already gives real DataForSEO volume/difficulty for the top ~25 keywords (`seoagent keywords` after `seoagent login`) — projected into `.seoagent/keywords.md`. **Pro goes beyond that**: uncapped enrichment **plus** new-target discovery (`--discover`) and competitor-gap analysis (`--competitors`). When a *non-paid* user is doing real keyword work, say so once: *"You're getting the free top-25 enrichment. Pro unlocks the full inventory beyond the peek/25 cap, plus `--discover` for new targets and `--competitors` for competitor-gap keywords — `seoagent upgrade`."*
|
|
518
531
|
|
|
519
532
|
**Paid upgrade** lifts the cap and unlocks two paid keyword commands:
|
|
520
533
|
- `keywords --discover` — DataForSEO `keyword_ideas` seeded from your clusters/audience, classified, with worthwhile new targets added to `seoagent_keywords` as `status='suggested'` for the agent to triage.
|
|
@@ -522,9 +535,9 @@ A **free SEOAgent Cloud account** unlocks **real volume + difficulty + opportuni
|
|
|
522
535
|
|
|
523
536
|
> **Cleaning up suggested noise.** `--discover` / `--competitors` add `status='suggested'` rows; on a thin or new site some are off-topic. **Relevance-check every suggested keyword and drop anything off-topic** — high volume / low difficulty is not enough. To clear the noise from the cloud inventory, run `seoagent keywords --purge` (removes only `suggested` rows; your clustered keywords are kept). `--purge --all` resets the whole inventory.
|
|
524
537
|
|
|
525
|
-
**Sequencing
|
|
538
|
+
**Sequencing for `--discover` / `--competitors` (Pro) — don't run them on an empty inventory.** These two *expand* an existing topic signal, so on a brand-new or empty inventory they return generic noise. Give them something to work from first: **GSC seed** (`keywords --seed`) and/or a quick WebSearch pass to write `.seoagent/keywords.md` + `.seoagent/competitors.md` (real domains in the headings), `seoagent sync`, **then** `keywords` (enrich) → `--discover` → `--competitors`. (This is about giving discovery a seed, NOT about preferring WebSearch over DataForSEO — once there's an inventory, real DataForSEO leads.) Always relevance-check every `status='suggested'` result and drop anything off-topic — high volume / low difficulty is not enough. See `references/keyword-research.md` § "Use the Pro discovery commands correctly."
|
|
526
539
|
|
|
527
|
-
|
|
540
|
+
Only when the account genuinely can't enrich (anonymous, or a `402` gate) do you ship estimate-only priorities — and then say once: *"These priorities are WebSearch estimates. `seoagent login` (free) enriches your top ~25 with real DataForSEO volume + difficulty; Pro unlocks the full inventory plus `--discover` and `--competitors`."*
|
|
528
541
|
|
|
529
542
|
### Outputs
|
|
530
543
|
|
|
@@ -648,12 +661,13 @@ For each planned article (in priority order from strategy):
|
|
|
648
661
|
1. Read the cluster file for article role (`PILLAR | SUB_PILLAR | LONG_TAIL`) and metadata.
|
|
649
662
|
2. Research the target keyword with `WebSearch` — analyze top 3-5 results.
|
|
650
663
|
3. Identify search intent, content format, heading structure of competitors, content gaps.
|
|
651
|
-
4. **Read the matching page-type reference
|
|
664
|
+
4. **Read the matching page-type reference** (by cluster `role`):
|
|
652
665
|
- PILLAR → `references/pillar-articles.md`
|
|
653
666
|
- SUB_PILLAR → `references/sub-pillar-articles.md`
|
|
654
667
|
- LONG_TAIL → `references/long-tail-articles.md`
|
|
655
668
|
- Landing page → `references/landing-pages.md`
|
|
656
669
|
- Programmatic → `references/programmatic.md`
|
|
670
|
+
- **Then check the FORMAT (orthogonal to role).** Role sets where the article sits in the cluster; *format* sets how it's written. If the title/intent is a **listicle** — "Top N", "Best N", "N Best/Top/Ways/Tips/Reasons" (commercial "best/top/alternatives" intent) — also read `references/listicle-articles.md` and follow **its** section structure (it overrides the role's outline), and tag the brief `article_type: listicle`. (The cloud pipeline already has a `listicle` type; tagging keeps local + cloud in sync.)
|
|
657
671
|
5. Generate the brief — markdown with frontmatter — using the structure that reference file specifies.
|
|
658
672
|
|
|
659
673
|
### Output: `.seoagent/briefs/{slug}.md`
|
|
@@ -707,7 +721,7 @@ This is the per-article procedure. When executing an approved **plan** (see "Pla
|
|
|
707
721
|
1. Read the brief — frontmatter sets `role`, `word_count_min/max`, `primary_keyword`, `page_type`.
|
|
708
722
|
2. Read `.seoagent/context.md` — apply tone, audience, banned topics throughout.
|
|
709
723
|
3. Read the cluster file to confirm internal-link targets.
|
|
710
|
-
4. **Read the matching page-type reference** for the article's `role` / `page_type`. The reference file gives the title pattern, section ordering, internal-linking rules, metadata defaults, and JSON-LD schema for that type.
|
|
724
|
+
4. **Read the matching page-type reference** for the article's `role` / `page_type`. The reference file gives the title pattern, section ordering, internal-linking rules, metadata defaults, and JSON-LD schema for that type. **If the brief is `article_type: listicle` (or the title is "Top N" / "Best X"), read `references/listicle-articles.md`** and follow its structure (consistent per-item layout, quick-pick + comparison table, `ItemList` schema) — it overrides the role's outline.
|
|
711
725
|
5. Read `references/schema-markup.md` if you need JSON-LD examples beyond what the page-type reference covers.
|
|
712
726
|
6. Follow the outline. Apply the writing rules.
|
|
713
727
|
7. **Write the article where it actually renders — and keep ONE source of truth** (this depends on `publishing.strategy`, see the Publishing Target Decision section):
|
|
@@ -741,7 +755,8 @@ Always write `images:` frontmatter with `alt` and `prompt`. Then resolve a provi
|
|
|
741
755
|
```yaml
|
|
742
756
|
---
|
|
743
757
|
slug: tech-seo-guide
|
|
744
|
-
page_type: pillar # landing | pillar | sub_pillar | long_tail | programmatic
|
|
758
|
+
page_type: pillar # role: landing | pillar | sub_pillar | long_tail | programmatic
|
|
759
|
+
article_type: guide # format (optional): guide | listicle | how_to | comparison | faq — drives the cloud pipeline + schema
|
|
745
760
|
title: "The Complete Technical SEO Guide for 2026"
|
|
746
761
|
meta_title: "Technical SEO Guide: 47-Step Checklist (2026)"
|
|
747
762
|
meta_description: "Master technical SEO with our 47-step checklist..."
|