distribb

For a direct social publishing or comment-for-guide request, use [references/social-publishing.md](references/social-publishing.md) immediately. The SEO onboarding walkthrough below applies when the user is starting SEO setup; it is not a prerequisite for an authorized social post. ## FIRST TIME READING THIS SKILL? STOP. WALK THE USER THROUGH THIS BEFORE ANYTHING ELSE. The first time this skill loads in a conversation, do NOT jump straight to keyword research or writing. First walk the user through the points below, in this order, in your own words. This is the single most important habit: people who start with keyword research and publishing on day one get weak results and quit. People who follow the process get results. ### A. What Distribb is, in one breath Distribb is your SEO platform. You (the AI agent) do the thinking and the writing. Distribb provides the infrastructure: real keyword data, a backlink exchange network of real businesses, Google Search Console analysis, CMS publishing (WordPress, Webflow, Shopify, Ghost, Wix, Notion, GoHighLevel, Framer, or any API webhook), a content calendar, social repurposing, and done-for-you distribution on the Accelerator plan. You bring your own AI model. Distribb does everything around the writing. ### B. The proper SEO process (show this list to the user every first run) Tell the user this is the order that works, and that you will guide them through it: 1. **Create your account and go through onboarding** at https://distribb.io . Onboarding is where Distribb learns the business (website, language, tone, competitors, content pillars, publishing rules). Do not skip it. Tell the user: the quality of everything downstream depends on onboarding being complete and honest. See `references/onboarding-guide.md` for exactly what onboarding asks and why. 2. **Connect the two things that matter most: the website (CMS) and Google Search Console.** The CMS connection lets Distribb publish. The GSC connection lets you audit, avoid keywords they already rank for, and find real opportunities. Both are set up in onboarding (GSC is optional there and can also be added later in Settings). See `references/onboarding-guide.md` for the GSC connection details, including what to do if the user does not have Search Console set up yet. 3. **Make sure there is a blog to publish to.** Many sites have no blog or no blog index page. Without one, articles have nowhere to live. Confirm the site has a blog (or help them point Distribb at the right CMS collection) before writing anything. 4. **Audit the site BEFORE writing a single article.** This is step one of real SEO, not keyword research. The audit finds keyword cannibalization, content decay, pages stuck on page 2, missing topical clusters (topic cocoons), competitor gaps, and basic on-page problems. Run `/gsc-audit <domain>` or follow `references/audit-playbook.md`. The audit is available on every plan. 5. **Plan topical clusters, then do keyword research.** Group the work into topic clusters (a pillar page plus supporting articles that interlink) instead of random one-off posts. Then use keyword research to fill each cluster. See `references/audit-playbook.md` (topical authority section). 6. **Write and publish, always feeding the backlink exchange.** Every article should include 1-2 links to other businesses in the network so the user earns backlink credits. Distribb checks for this on submission and warns you if an article has none. 7. **Optimize what already ranks.** Use GSC-driven suggestions to rewrite pages stuck at the bottom of page 1 or on page 2. This is the fastest win because the page already has authority. Run `/optimize`. This whole skill exists to run that loop for the user. When in doubt, point them back to it. ### C. The Backlink Exchange (explain this clearly, it is the differentiator) Distribb runs a network of real businesses that exchange backlinks. When an article includes a link to another business in the network, Distribb detects it on submission and credits the user's project. The more links the user gives, the more they receive. These are real, high-DR (Domain Rating) backlinks from legitimate websites, not link farms. **Every current plan gets unlimited exchange access. Legacy Free Agentic accounts receive 1 backlink per month.** Backlinks are the hardest part of SEO to get right, and almost no other tool offers this. See `references/plans-and-backlinks.md`. ### D. Slash commands This skill ships ready-to-use slash commands so the user can drive the whole workflow with `/`: | Command | What it does | |---|---| | `/distribb` | Overview, account status, and the proper SEO process above | | `/distribb-setup` | Check the API key, confirm website + GSC are connected, and enable the other slash commands | | `/gsc-audit <domain>` | Full SEO audit from Search Console + on-page + competitor + cannibalization + topic clusters | | `/keyword-research <seed>` | Keyword ideas with volume and difficulty | | `/write-article <keyword>` | Research, write, add internal links + backlinks, and publish one article | | `/optimize` | Find and rewrite pages stuck on page 2+ using GSC data | | `/backlinks` | Check backlink credits, see targets, and explain how the exchange works | | `/content-calendar` | List, schedule, and manage planned/draft/published articles | | `/ai-visibility` | Find where the user should be recommended by ChatGPT/Perplexity/Gemini and which listicles to pitch | | `/news-writer <site-url-or-niche>` | Newsjack: find fresh news in the niche, write grounded news drafts, and queue them in Distribb | | `/statistics-page-writer <topic>` | Deep-research and publish a sourced statistics page journalists cite for months | | `/youtube-motion-video <topic>` | Make a faceless motion-collage explainer video ("In a Nutshell" docu style), optimize it for YouTube SEO, and publish it to the connected YouTube channel | | `/instagram-carousel <article-id-or-keyword>` | Turn one article/keyword into a viral, save-driven Instagram carousel (cover hook, one idea per slide, comment-for-link play), publish it, and close the loop with a companion article | | `/review-video <competitor>` | Compile REAL, verified reviews of a competitor into a faceless "<competitor> reviews" video, position the connected project's own business as the alternative, append the project's own testimonials, and publish to YouTube + a companion article | | `/gbp` | Google Business Profile manager: live review triage, draft + post public review replies, queue Google Business posts, post analytics | | `/link-outreach` | Work your backlink outreach replies: see which listicle authors replied (and their asking price), draft and send in-thread replies from Distribb's inbox (Accelerator) | | `/gov-backlinks` | Register the business in free government directories (SAM.gov, the SBA small business listing, state vendor portals) by driving the user's browser, for real .gov profile backlinks | | `/integrations` | See what is connected, send the user connect links, and use any connected integration (ad accounts, social inboxes, analytics, banks, outreach tools, databases, new integrations) | | `/paid-ads` | Audit, build and scale Meta, Google, TikTok and LinkedIn campaigns through the connected ad accounts; preview first, the user approves every spend | If these commands are not yet available when the user types them, run `/distribb-setup` (or copy this skill's `commands/*.md` into the project's `.claude/commands/` folder) to register them. See the **Slash Commands** section below. ### E. Getting an account If the user has no Distribb account yet, send them to **https://distribb.io** to sign up and go through onboarding. Their Distribb API key appears in Settings afterward. Plans at a glance (full detail in `references/plans-and-backlinks.md`): - **Agentic Mode** ($49/mo, 3-day free trial): Distribb-provided keyword data, full backlink exchange. - **Pro** ($97/mo): Distribb writes and publishes articles for you (the `POST /articles/generate` path), per-project credits. - **Accelerator**: everything plus done-for-you distribution that places the business on the platforms AI engines cite most. See section below and `references/plans-and-backlinks.md`. The free Agentic plan ($0/mo) is deprecated and no longer offered to new users. Current plans are Agentic Mode at $49/month and Pro at $97/month. **Legacy Free Agentic accounts, keyword research returns HTTP 402 until keys are saved:** On a legacy Free Agentic account, `POST /keywords/search` returns `HTTP 402 Payment Required` with `error: "byo_keys_required"` until the user saves a DataForSEO or Ahrefs API key at https://distribb.io/settings#seo-keys. The 402 body includes an `instructions_for_agent` string. Surface it verbatim to the user, do not retry. See the **Keyword Research, BYO Keys** section below for the full contract. --- ## Setup ```bash export DISTRIBB_API_KEY=your_api_key_here ``` No installation required. All commands use `curl` and `jq`. --- | Property | Value | |----------|-------| | **name** | distribb | | **description** | SEO platform: keyword research, article writing, backlink exchange network, CMS publishing, social media repurposing, content calendar | | **allowed-tools** | Bash(curl:*), Bash(jq:*), Bash(cat:*), WebFetch, WebSearch, Read, Write | --- ## API Base URL All endpoints use: `https://distribb.io/api/v1` All requests require the header: `Authorization: Bearer $DISTRIBB_API_KEY` --- ## Validate Your API Key Before running any workflow, verify your API key works: ```bash curl -s -H "Authorization: Bearer $DISTRIBB_API_KEY" \ https://distribb.io/api/v1/projects | jq . ``` If you get `{"error": "Missing or invalid API key..."}` or `{"error": "Account is not active."}`, the key is wrong or the account is inactive. Ask the user to check their API key in Settings at https://distribb.io/settings. --- ## What You Get | Capability | How It Works | Endpoint | |------------|-------------|----------| | **Generate Article** | Submit source content, Distribb AI expands into full SEO article (Pro plan only) | `POST /articles/generate` | | **Keyword Research** | Search volume, difficulty scores, keyword ideas. Current plans use Distribb data; legacy Free Agentic accounts use the user's own DataForSEO or Ahrefs key (returns HTTP 402 if not set) | `POST /keywords/search` (alias: `POST /keywords/research`) | | **Backlink Exchange** | Get real backlinks from other businesses in the network | `GET /backlink-targets` | | **Backlink Ledger** | Full link-level detail behind the aggregate status: earned + scheduled links (source domain, DR, business, target URL, status, date) plus a velocity/gap summary | `GET /backlinks` | | **CMS Publishing** | Publish to WordPress, Webflow, Shopify, Ghost, custom API | `POST /articles/:id/publish` | | **Content Calendar** | Schedule articles, track status, manage your pipeline | `GET /articles`, `POST /articles`, `PUT /articles/:id`, `DELETE /articles/:id` | | **Article Brief** | Everything one planned article needs: claim window, per-article instructions, committed exchange links, planned internal links, image targets | `GET /articles/:id/brief` | | **Feature Image** | Attach a hero image URL to an article (cannot generate one; supply the URL) | `POST /articles`, `PUT /articles/:id` with `feature_image` | | **Image Hosting** | Host an image you made or copy a public image URL, get a public URL | `POST /images` | | **Article Plan** | Switch between the article plans the account includes (8 premium, 30, 5 backlinks focused; 60 and 90 on Accelerator) | `POST /projects/:id/article-plan` | | **Page Screenshots** | Screenshot a listicle item's own website (async) | `POST /screenshots` | | **Project Settings** | Read & edit the FULL settings surface (~30 fields): instructions, sitemap/blog URLs, content pillars, tone, writing profile, positioning, images/brand, competitors, toggles, publish time/timezone | `GET /projects/:id`, `PUT /projects/:id` | | **Create + Onboard Project** | Create a new project (gated to paid slots; returns a buy-a-slot link if over) and optionally start keyword research + first articles. Ask the user before running research. Connect WordPress via API too | `POST /projects`, `POST /projects/:id/onboarding`, `POST /projects/:id/wordpress` | | **Internal Linking** | Get your published article URLs to cross-link in new content | `GET /internal-links` | | **Business Context** | Get brand voice, competitors, custom instructions | `GET /business-context` | | **Integrations** | See connected CMS platforms | `GET /integrations` | | **Google Search Console** | Pull the user's real GSC performance, top queries, top pages, clicks, impressions, CTR, position (if they've connected GSC). Aliased as `GET /rankings` and `GET /analytics` (search performance, NOT web-session analytics) | `GET /search-console` | | **Google Business Profile** | Live Google reviews (reviewer, rating, text, reply status), post/delete the business's PUBLIC review replies, queue Google Business posts, post-level analytics (if they've connected Google Business) | `GET /gbp/status`, `GET /gbp/reviews`, `POST\|DELETE /gbp/reviews/reply`, `POST /gbp/posts`, `GET /gbp/analytics` | | **Link Outreach** | Listicle authors who replied to the user's managed backlink outreach (their message + any asking price), and sending an in-thread reply from Distribb's warmed inbox on the user's behalf (Accelerator only) | `GET /link-outreach/prospects`, `POST /link-outreach/prospects/:id/reply` | | **AI Visibility (AEO)** | Distribb's already-tracked AI-search visibility: visibility score, share-of-voice, per-engine citation status (ChatGPT, Perplexity, Gemini, AI Overviews, AI Mode), cited pages, on-demand scans. Track your **own buyer-query prompts** (up to 25/project, scanned first) and scan AI Overview / AI Mode / ChatGPT / Gemini from the client's **own city** via `primary_location` | `GET /ai-visibility`, `POST /ai-visibility/scan`, `POST\|DELETE /ai-visibility/prompts` | | **Content Optimizations** | Find pages worth rewriting (mostly from GSC), review the AI's before/after diff, then approve and publish the rewrite to the CMS. Filter by opportunity with `?type=` (cannibalisation, declining_page, striking_distance, ctr_underperform, ...) | `GET /suggestions`, `POST /suggestions/run`, `POST /suggestions/:id/approve\|publish\|regenerate\|reject` | | **Social Media Repurposing** | Auto-generates social posts (X, LinkedIn, Reddit, etc.) when an article is published | Automatic (no endpoint needed) | | **Social Media Posting** | Write a post and send it to the user's connected accounts, now or scheduled | `GET /social/accounts`, `POST /social/publish` | | **Microworkers Campaign Management** | Create/register campaigns, list submissions, and rate worker slots for Reddit, Quora, YouTube, or generic proof tasks | `GET/POST /microworkers/campaigns`, `GET /microworkers/campaigns/:id/slots`, `POST /microworkers/slots/:slot_id/rate` | | **Every Integration** | The catalog of everything the user can connect (CMS, social accounts, ad accounts, Search Console, analytics tools, banks, databases, GitHub, new integrations): connected or not, which accounts, the tools each unlocks, and the connect link to send the user. Connecting stays with the user | `GET /integrations/catalog`, `GET /integrations/connect` | | **Integration Tools** | Run any connected integration's tools with the same gates as Distribb's own agent: ad campaigns, social DMs, comments and inbox, analytics, bank data, outreach, database reads, new integrations. Reads and previews in read mode; approved changes in action mode with `confirm` | `GET /agent-tools`, `POST /agent-tools/call`, `GET /agent-tools/jobs/:id` | | **Playbooks** | Distribb's playbooks for SEO, social media, outreach, paid ads and integrations (also in `references/`) | `GET /playbooks`, `GET /playbooks/:topic` | --- ## Start Here: Onboarding and the Two Connections Before any keyword research or writing, the user must have completed onboarding at https://distribb.io and connected two things. Everything downstream depends on this. **What onboarding collects** (so you know what Distribb already knows, and what to fill if it is thin): the website URL, then an AI pass that auto-populates business details. It captures language, tone (Informative / Conversational / Persuasive), writing profile (Experienced practitioner / Simple educational / Balanced SEO), product positioning, sitemap + blog root URL, content pillar URLs, internal-link count, keyword region, publishing time + timezone, blog publishing preference (publish live / save as draft in Distribb / send as draft to the CMS), image hosting + style, YouTube-videos toggle, brand intelligence, duplicate-content protection, custom AI instructions, 3-7 competitors, and the Google Search Console connection. Full field-by-field detail and how to read or change each via the API is in `references/onboarding-guide.md`. **The two connections that matter most:** 1. **Website / CMS** (WordPress, Webflow, Shopify, Ghost, Wix, Notion, GoHighLevel, Framer, or API webhook). This is how Distribb publishes. Check it with `GET /integrations`. 2. **Google Search Console.** This powers the audit, keyword-gap detection, and optimization suggestions. Check it with `GET /search-console` (returns `connected: true/false`). If the user has GSC access but has not connected it to Distribb, send them to https://distribb.io/integrations . **If the user does not have Search Console set up at all yet**, point them to Google's guide first: https://support.google.com/webmasters/answer/10267942?hl=en , then have them connect it in Distribb. Also confirm the site actually has a **blog** to publish to. A site with no blog index has nowhere for articles to live, and this is a common reason new users see no results. --- ## The SEO Audit (Run This First) Real SEO starts with an audit, not with publishing. Before writing anything for an existing site, run a full audit so the strategy is grounded in data. The audit is available on **every plan** (it only needs the website and, ideally, GSC). A Distribb audit covers: - **Keyword cannibalization** (multiple pages competing for the same query) - **Content decay** (pages losing traffic vs the previous period) - **Quick wins / striking distance** (queries at positions 11-20 and pages stuck on page 2+) - **CTR optimization** (pages that rank but get fewer clicks than expected) - **Dead pages** (pages that dropped to zero traffic) - **Brand vs non-brand health** - **Topical authority clusters (topic cocoons)** (which pillars and supporting clusters to build)