Skip to content
Back to search

qwoted-seo-backlinks

Automate Qwoted (HARO-style PR platform) end-to-end and earn high-DR backlinks at scale: log in, set up the user's "expert" Source persona (bio + employer + contacts), search the Algolia-backed opportunity index, RESEARCH and BUILD a sourced statistics page on the user's topic (the linkable asset journalists love to cite), draft pitches as the user that link to that page, and submit them to journalists. Use this skill whenever the user asks for "PR opportunities", "Qwoted opportunities", "press mentions", "journalist requests", "HARO replies", "media pitches", "podcast guesting", "expert quotes", "stats page for SEO", "research page for journalists", or "backlinks from journalists".

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/bomx--qwoted-seo-backlinks-skill/badge.svg)](/listings/bomx--qwoted-seo-backlinks-skill)

HTML

<a href="/listings/bomx--qwoted-seo-backlinks-skill"><img src="/api/listings/bomx--qwoted-seo-backlinks-skill/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

npx skills add Bomx/qwoted-seo-backlinks-skill

Or clone manually:

git clone https://github.com/Bomx/qwoted-seo-backlinks-skill.git
cd qwoted-seo-backlinks-skill
pip install -r requirements.txt
playwright install chromium

That's it. Claude reads `SKILL.md` to learn the workflow.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 641 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. ---
  2. name: qwoted-seo-backlinks
  3. description: |
  4. Automate Qwoted (HARO-style PR platform) end-to-end and earn high-DR
  5. backlinks at scale: log in, set up the user's "expert" Source persona
  6. (bio + employer + contacts), search the Algolia-backed opportunity
  7. index, RESEARCH and BUILD a sourced statistics page on the user's
  8. topic (the linkable asset journalists love to cite), draft pitches
  9. as the user that link to that page, and submit them to journalists.
  10. Use this skill whenever the user asks for "PR opportunities",
  11. "Qwoted opportunities", "press mentions", "journalist requests",
  12. "HARO replies", "media pitches", "podcast guesting", "expert quotes",
  13. "stats page for SEO", "research page for journalists", or
  14. "backlinks from journalists".
  15. ---
  16. # Qwoted SEO Backlinks Skill — playbook for Claude
  17. Your job is to get the user **press mentions and high-DR backlinks** from
  18. journalists who post requests on [Qwoted](https://app.qwoted.com).
  19. ---
  20. ## Operating rules — READ THIS FIRST, THEN FOLLOW IT EVERY TURN
  21. These rules take precedence over anything else in this file. Do not
  22. skip them, do not substitute your own judgement.
  23. 1. **You are running a 4-stage playbook, not a chatbot.** The stages
  24. are: (1) Onboard, (2) Find opportunity, (3) Research + publish a
  25. stats page, (4) Pitch. Whenever the user says anything vague like
  26. "ok next step", "what now?", "help me with this", "go", your reply
  27. MUST start with "**We're at Stage X of 4. Next I'll do Y, because
  28. Z.**" Never just ask "what do you want to do?" — propose the next
  29. stage based on where we are.
  30. 2. **Stage 3 is the multiplier and you must proactively propose it.**
  31. Whenever you find opportunities in Stage 2, you MUST classify each
  32. one as `stats_page_worthy: true | false` using the heuristic table
  33. below, and you MUST tell the user "I recommend building a stats
  34. page on `<topic>` before pitching `<these N opportunities>`." Do
  35. not wait for the user to ask about stats pages. A naked pitch lands
  36. one quote in one article; a pitch linked to a sourced stats page
  37. lands recurring citations for months. Leaving Stage 3 on the table
  38. is leaving money on the table.
  39. 3. **Never overwrite existing user data without an explicit
  40. side-by-side approval.** Before calling `qwoted_profile.py --action
  41. update` for any field, first call `--action get` and compare
  42. `bio_preview` / `has_bio` / existing URL / existing email etc. If
  43. a field already has content, show the user both the OLD and the
  44. NEW version and get explicit go-ahead before sending the PATCH.
  45. The script defaults to refusing the PATCH without `--force-
  46. overwrite`; this is a feature, not a bug.
  47. 4. **Never invent opportunity IDs, source IDs, or journalist names.**
  48. Everything you present to the user must come directly from a
  49. `RESULT:` line the skill's scripts printed. If you didn't see it
  50. in a subprocess RESULT, you don't know it.
  51. 5. **The login step is idempotent and browser-free when a session
  52. exists.** Run `python3 qwoted_login.py`. If the RESULT says
  53. `status=logged_in` in under a second with no browser opening, the
  54. existing cookies are fine — do not re-run with `--reset` or
  55. `--force`. If you're in an agent environment without a visible GUI
  56. and Chromium does need to open, STOP and tell the user to run the
  57. script in their own terminal once; then continue.
  58. 6. **`RESULT:` lines are the canonical channel.** Every script emits
  59. one JSON line prefixed with `RESULT: `. Parse it; ignore stderr
  60. logs (those are for the human). Your next decision should reference
  61. specific fields from the RESULT, not vibes.
  62. 7. **The stats page must contain ZERO outbound `<a>` tags.** Source
  63. attributions are plain text (`(Source: HubSpot, 2026)`), never
  64. clickable. This is non-negotiable — we're hoarding crawl budget
  65. and PageRank, not distributing it. The only `<a>` tags allowed
  66. in the rendered HTML are internal TOC anchor fragments
  67. (`href="#..."`) and a same-domain author-bio CTA. Source URLs
  68. you fetch during research are stored in the research JSON and
  69. (optionally) in an HTML comment audit-trail at the bottom of the
  70. page — never rendered as clickable links. See
  71. `STATISTICS_PAGE_PLAYBOOK.md` → "Hoard the juice" for the full
  72. rule and the one-line `grep` check you can run to audit the
  73. finished file.
  74. ---
  75. ## Stage-3 classification heuristic — use this every time you hand back Stage 2 results
  76. For every opportunity returned by `qwoted_search.py`, score it on
  77. these criteria:
  78. | Signal | Weight |
  79. |---|---|
  80. | Topic is broad enough that public data exists (e.g. "AI in marketing", "local SEO", "remote work trends", "e-commerce conversion") | +2 |
  81. | User's business already touches this topic → page will earn recurring traffic, not just one-time citation | +2 |
  82. | Deadline is at least 24 hours away (stats-page build takes 30-60 min of research) | +1 |
  83. | Multiple opportunities in the same cluster (→ one page supports 3+ pitches) | +2 |
  84. | Request explicitly asks for "statistics", "data", "research", "trends" | +3 |
  85. | Topic is hyper-niche / only relevant to this one publication (e.g. "billiard retailer local SEO") | -1 (a stats page still works but the niche is smaller) |
  86. | Deadline is under 12 hours | -3 (skip Stage 3, pitch direct) |
  87. | Ask is pure founder-story / personal opinion ("how did you start your company") | -3 (no data needed) |
  88. | Paid placement / $X appearance fee | -2 (different ROI math) |
  89. **Rule:** propose Stage 3 whenever total score ≥ 2. Otherwise pitch direct.
  90. State the score in your recommendation so the user sees why.
  91. Example output you should produce after Stage 2 completes:
  92. > Found 8 opportunities. Stage-3 classification:
  93. >
  94. > | # | Title | Score | Recommendation |
  95. > |---|---|---|---|
  96. > | 1 | Selling Signals — awareness vs demand | +1 | Pitch direct (deadline 20h, topic matches but no "statistics" ask) |
  97. > | 2 | SEOptimer — how your agency makes money | -3 | Pitch direct (founder-story, deadline 8h) |
  98. > | 3 | BCA Insider — local SEO for retailers | +4 | **Build stats page** on `local-seo-statistics-2026` — feeds this pitch AND any future local-SEO pitch |
  99. > | ... |
  100. >
  101. > I'll start by building the local-SEO stats page (covers #3 + any future local-SEO opps), then while it renders I'll draft the direct pitches for #1 and #2. Sound good?
  102. ---
  103. ## Tooling overview
  104. The skill ships four CLI scripts you call as subprocesses, plus a
  105. research playbook and an HTML template. Each script prints a single
  106. `RESULT: { ... }` JSON line on stdout that you parse to decide the
  107. next step. Detailed human-readable logs go to stderr.
  108. ```
  109. qwoted_login.py # one-time auth (idempotent; skips browser if cookies valid)
  110. qwoted_profile.py # get/create/update the "expert" Source persona
  111. qwoted_search.py # search opportunities (Algolia, returns JSON)
  112. qwoted_pitch.py # draft + send a pitch to a specific opportunity
  113. STATISTICS_PAGE_PLAYBOOK.md # READ THIS before researching/building a stats page
  114. templates/statistics_page_example.html # HTML scaffold to fill in
  115. ```
  116. All cookies, sent-pitch logs, search results and generated stat pages
  117. live under `~/.qwoted/` and `./statistics_pages/`.
  118. ---
  119. ## The full workflow (4 stages)
  120. ```
  121. ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐ ┌──────────────┐
  122. │ 1. Onboard │ → │ 2. Find │ → │ 3. Research + │ → │ 4. Pitch │
  123. │ (login + │ │ opportunity │ │ publish a stats │ │ with the │
  124. │ profile) │ │ │ │ page (linkable │ │ page URL │
  125. │ │ │ │ │ asset) │ │ │
  126. └──────────────┘ └──────────────┘ └──────────────────┘ └──────────────┘
  127. once every session once per topic every pitch
  128. ```
  129. ---
  130. ## Decision tree — what to do based on what the user asks
  131. | User intent | Skill stage(s) |
  132. |---|---|
  133. | "Set me up on Qwoted" / first time | Stage 1: `qwoted_login.py` → `qwoted_profile.py --action get` → create/update ONLY missing fields |
  134. | "Update my Qwoted bio" / "change my expert profile" | Stage 1c: `qwoted_profile.py --action get` first, SHOW existing bio, ask for approval, then `--action update --bio '...' --force-overwrite` if user confirms |
  135. | "Find PR opportunities about X" | Stage 2: `qwoted_search.py --query "X" --max-hits 30` → classify each result with the Stage-3 heuristic → propose stats page(s) |
  136. | "Build me a stats page on X" / "make a research page about X" | Stage 3 only: read `STATISTICS_PAGE_PLAYBOOK.md` and execute |
  137. | "Pitch opportunity #N" / "draft a pitch for SR 235897" | Check Stage-3 score first; if ≥2 propose stats page; then Stage 4 dry-run → user approves → `--send` |
  138. | "Pitch the top 3 opportunities about X" | Stage 2 → cluster by topic → Stage 3 ONCE per cluster → Stage 4 looped with the same `--research-page-url` |
  139. | "Ok next step" / "what now?" / "go" | RESTATE the stage we're on and PROPOSE the next one. Do not ask the user. |
  140. ---
  141. ## Stage 1 — Onboarding (run ONCE per user)
  142. ### 1a. Install
  143. If the user doesn't have the skill installed, pip-install the deps and
  144. run Playwright's browser bootstrap:
  145. ```bash
  146. pip install -r requirements.txt
  147. playwright install chromium
  148. ```
  149. ### 1b. Log in
  150. ```bash
  151. python3 qwoted_login.py
  152. ```
  153. **Important — this script is idempotent.** Before launching any browser
  154. it probes `~/.qwoted/storage_state.json` against Qwoted's API. If the
  155. cookies still work (which they usually do — Qwoted sessions last weeks),
  156. the script exits immediately with `RESULT: {"status": "logged_in", ...}`
  157. and **no browser opens at all**. That's the happy path — do not re-run
  158. with `--reset` or `--force` unless you have a reason.
  159. Only if no valid session exists will a Chromium window open. In that
  160. case: **tell the user to sign in IN THAT Chromium WINDOW** — not in
  161. their regular Chrome/Safari, because those are separate browsers with
  162. separate cookies, so signing in elsewhere will NOT save a session for
  163. this skill. When they reach a logged-in page the script auto-detects
  164. it, saves cookies to `~/.qwoted/storage_state.json`, closes the browser
  165. and exits. The next login is one click because Chromium remembers them.
  166. **If you are running inside an agent environment that can't show GUI
  167. windows** (some Codex or CI setups), the Chromium window will launch
  168. invisibly and the script will hang on the sign-in page. In that case:
  169. 1. STOP. Do not keep re-running. Tell the user to open their own
  170. terminal on their own machine and run `python3 qwoted_login.py`
  171. there once — they'll see the browser, sign in, and `storage_state.json`
  172. will be written. After that, every future call from the agent will
  173. use the already-valid cookies (no browser needed).
  174. If the user doesn't have a Qwoted account yet, send them to
  175. [qwoted.com](https://qwoted.com) to sign up first (free for sources).
  176. ### 1c. Set up the expert profile (Source persona) — REQUIRED
  177. **Critical constraint**: Qwoted only delivers a pitch to a reporter
  178. when the pitch is attached to a *pitchable entity* — a Source, Company
  179. or Product the user is allowed to pitch as. The pitch API will accept
  180. a submission without one (HTTP 200, draft=false) but the reporter is
  181. **never notified**. Always make sure the user has a Source persona
  182. configured before the first pitch.
  183. Check first:
  184. ```bash
  185. python3 qwoted_profile.py --action get
  186. ```
  187. Parse the `RESULT:` JSON. Key fields you MUST inspect before doing
  188. anything else:
  189. * `seo_ready` — boolean, all three must-have fields are set.
  190. * `ready_to_pitch` — boolean, at least one pitchable entity exists.
  191. * `missing_for_seo` — array of field names still empty.
  192. * `bio_preview` — first 240 chars of the current bio (empty string if
  193. there really is no bio).
  194. * `bio_length` — total bio length in chars.
  195. * `first_pitchable_entity` — full object including `bio`,
  196. `business_url`, `email`, `has_linkedin_url`, etc.
  197. Decision tree:
  198. * If `seo_ready == true` → **skip to Stage 2. Do NOT "improve" the
  199. existing profile unless the user explicitly asked you to.** Read
  200. the bio_preview so you know what the user's positioning is, then
  201. move on.
  202. * If `ready_to_pitch == true` but `seo_ready == false` → the persona
  203. exists but is incomplete. For each item in `missing_for_seo`, ask
  204. the user the corresponding question and patch with `--action update`:
  205. * `business_url` → "What URL should reporters link to when they
  206. credit you?" → `--action update --url https://acme.com`
  207. * `bio` → draft a 2-4 sentence bio, SHOW it to the user, get explicit
  208. approval, then `--action update --bio "..."`. (If a bio is actually
  209. present and `missing_for_seo` still lists it, you probably have a
  210. stale local copy of the skill — update it.)
  211. * `email` → "Which email should reporters reply to?" →
  212. `--action update --email jane@acme.com`
  213. Run `--action get` again afterwards to confirm `seo_ready` is now
  214. true.
  215. * If `ready_to_pitch == false` → no persona exists. Go to the create
  216. flow below.
  217. **⚠️ Safety rail — overwrite protection.** If the user asks you to
  218. *change* an already-populated field (e.g. "update my bio to X"), the
  219. script will REFUSE the PATCH unless you pass `--force-overwrite`. This
  220. is intentional. The correct flow is:
  221. 1. Run `--action get` and read `bio_preview`.
  222. 2. Show the user BOTH the current bio AND the proposed new one.
  223. 3. Ask explicitly: "Replace the current bio with this one?"
  224. 4. Only if they say yes, re-run with `--force-overwrite`.
  225. Never pass `--force-overwrite` preemptively "just in case".
  226. If `ready_to_pitch == false`, you need to **collect the user's info
  227. in a single message before running create**. Don't drip-ask one field
  228. at a time. Use this exact checklist:
  229. > **REQUIRED to even create the profile:**
  230. > - `--full-name` — the user's real name as the byline should appear
  231. >
  232. > **STRONGLY RECOMMENDED — without these the profile is useless for SEO:**
  233. > - `--url` — the user's **business website URL** (e.g. `https://acme.com`).
  234. > ⚠️ This is the link journalists put in their articles when they
  235. > credit the user. **No URL = no backlink = the whole point of this
  236. > skill is defeated.** Confirm it before running create.
  237. > - `--bio` — a 2-4 sentence description of who the user is, what they
  238. > do, and what topics they can credibly speak to. The bio is what
  239. > reporters skim when deciding whether to use a quote. Mention the
  240. > business name, role, and 2-3 areas of expertise. If the user gave
  241. > you their bio elsewhere, use that. If not, draft one from what they
  242. > told you and **show it to them for approval before submitting**.
  243. > - `--email` — the user's professional email (where reporters reply).
  244. >
  245. > **NICE TO HAVE (ask but don't block on):**
  246. > - `--linkedin` — full LinkedIn profile URL (boosts credibility a lot)
  247. > - `--location` — `"City, State, Country"` (some pubs filter by region)
  248. > - `--gender` — one of `f` / `m` / `nb` / `sd` (for pronouns in articles)
  249. > - `--twitter`, `--phone`, `--facebook`, `--instagram` — only if the
  250. > user wants reporters to have these channels.
  251. **Always ask the user to confirm at minimum the URL, bio and email**
  252. before firing the create command. Those three are what end up in
  253. articles. Example of how to ask:
  254. > "Before I set up your Qwoted expert profile, I need to confirm a few
  255. > things that journalists will see and link to:
  256. >
  257. > 1. **Business URL** — what site should reporters link to when they
  258. > credit you? (e.g. `https://acme.com`)
  259. > 2. **Bio** — here's a draft based on what you told me: *"Jane is the
  260. > founder of Acme Inc, a B2B SaaS that helps marketing teams ship
  261. > campaigns 10x faster. She speaks to growth, GTM and pricing."*
  262. > Sound right?
  263. > 3. **Reply-to email** — which email should reporters use to follow up?
  264. >
  265. > Anything you'd like to add (LinkedIn, location, etc.)?"
  266. Then build the command from their answers:
  267. ```bash
  268. python3 qwoted_profile.py --action create \
  269. --full-name "Jane Doe" \
  270. --bio "Jane is the founder of Acme Inc, a B2B SaaS that helps marketing teams ship campaigns 10x faster. She advises on growth, GTM and pricing." \
  271. --url https://acme.com \
  272. --email jane@acme.com \
  273. --linkedin https://www.linkedin.com/in/jane-doe/ \
  274. --location "San Francisco, CA, USA" \
  275. --gender f
  276. ```
  277. Repeat any contact flag to add multiple values (the first one becomes
  278. primary). Other flags: `--off-the-record`, `--hide-from-search-engines`.
  279. To update an existing persona later (e.g. the user got a new title):
  280. ```bash
  281. python3 qwoted_profile.py --action update \
  282. --bio "Jane is now CEO of Acme Inc..."
  283. ```
  284. `--source-slug` is optional — without it, the script edits the first
  285. Source on the account.
  286. ---
  287. ## Stage 2 — Find opportunities
  288. ```bash
  289. python3 qwoted_search.py --query "marketing automation" --max-hits 30
  290. ```
  291. Empty `--query ""` returns the full index in the order Qwoted shows it
  292. on the homepage (newest first).
  293. Read the resulting JSON file (path is in the `RESULT:` line under
  294. `out_path`). The structure is:
  295. ```json
  296. {
  297. "query": "marketing automation",
  298. "scraped_at": "2026-04-22T...",
  299. "count": 30,
  300. "opportunities": [
  301. {
  302. "source_request_id": 235897, // numeric ID for qwoted_pitch.py
  303. "name": "Looking for marketing experts to comment on Q3 trends",
  304. "details": "Reporter brief, 3-4 paragraphs of what they're after...",
  305. "request_type": "Online article",
  306. "deadline": "2026-04-28T17:00:00Z",
  307. "want_pitches": true,
  308. "publication": {"name": "TechCrunch", "top_publication": true, ...},
  309. "hashtags": ["#marketing", "#saas"],
  310. "url": "https://app.qwoted.com/source_requests/235897",
  311. ...
  312. },
  313. ...
  314. ]
  315. }
  316. ```
  317. ### Picking the best opportunities
  318. When the user asks for "the best", "top", or "easy wins", rank by:
  319. 1. `publication.top_publication == true` (high-DR sites)
  320. 2. `easy_win == true` (Qwoted's signal: low pitch count, high responsiveness)
  321. 3. `paid == true` (paid placements when applicable)
  322. 4. `pitch_count_category` (lower is better — "low" beats "very_high")
  323. 5. Match against the user's expertise (use the bio you already have)
  324. 6. Deadline proximity (`deadline_approaching`, `deadline`)
  325. Only suggest opportunities where the user genuinely has expertise —
  326. journalists ignore obviously irrelevant pitches and Qwoted scores PR
  327. accounts on response rate.
  328. ### ⚠️ MANDATORY — classify EVERY opportunity with the Stage-3 heuristic
  329. After you've picked a shortlist, you MUST run each one through the
  330. Stage-3 heuristic table at the top of this file and present the
  331. classification to the user in a table. **Do not skip this step, do
  332. not wait for the user to ask about stats pages.** A typical output
  333. looks like this:
  334. > I'd prioritise 5 of the 8 opportunities. Here's the Stage-3 classification:
  335. >
  336. > | SR ID | Publication | Topic | Deadline | Stats-page score | Action |
  337. > |---|---|---|---|---|---|
  338. > | 235897 | TechCrunch | marketing automation trends | 3d | **+5** | **Build `marketing-automation-statistics-2026.html`**, then pitch |
  339. > | 236422 | Selling Signals | awareness vs demand | 20h | +1 | Pitch direct |
  340. > | 234782 | BCA Insider | local SEO for retailers | 5d | **+4** | **Build `local-seo-statistics-2026.html`**, then pitch |
  341. > | 236145 | SEOptimer | how agencies make money | 8h | -3 | Pitch direct (too tight, founder-story) |
  342. > | 232532 | Business RoundUp | founder interview | 8d | -3 | Skip ($95 fee, founder-story) |
  343. >
  344. > Plan: I'll build the 2 stats pages first (they cluster future
  345. > opportunities too), then draft direct pitches for #235897, #236422
  346. > and #234782 that link to them. I'll draft a plain pitch for #236145
  347. > because of the deadline. Sound good?
  348. When the user replies "ok" / "yes" / "go", move on to Stage 3 for
  349. the pages you identified, then Stage 4 for the pitches.
  350. ---
  351. ## Stage 3 — Build a sourced statistics page (the linkable asset)
  352. > **READ `STATISTICS_PAGE_PLAYBOOK.md` BEFORE EXECUTING THIS STAGE.**
  353. > This section is just the *when*. The *how* (research methodology,
  354. > source quality bar, HTML build, anti-hallucination rules) lives in
  355. > the playbook.
  356. ### Why it matters
  357. A pitch that just contains opinion gets one quote in one article. A
  358. pitch that links to a comprehensive, sourced statistics page on the
  359. same topic gets the user *recurring* citations for months — because
  360. the next reporter who searches `"<topic> statistics 2026"` finds the
  361. page on the user's domain and cites it without ever knowing the user
  362. exists. **This is the move that turns Qwoted from a one-off PR tool
  363. into a compounding SEO engine.**
  364. ### When to build a stats page (decision rule)
  365. Offer to build one when **all** of these are true:
  366. 1. The opportunity topic is broad enough to support a stats roundup
  367. (e.g. "AI in marketing trends" — yes; "founders who pivoted in
  368. 2024" — no, that's an anecdote ask).
  369. 2. The deadline is **at least 24-48 hours away** (research takes time
  370. if you're going to do it well).
  371. 3. The user doesn't already have a recent, high-quality stats page on
  372. the same topic.
  373. Skip and go straight to Stage 4 when the deadline is tight or the ask
  374. is qualitative (anecdotes, opinions, case studies).
  375. If multiple Stage 2 opportunities are on the same topic, **build the
  376. stats page once and reuse it across every pitch in that batch** with
  377. the same `--research-page-url` flag.
  378. ### How to ask the user
  379. Don't just unilaterally start building a 3000-word page. Ask:
  380. > *"Two of the opportunities I found are about [topic]. I can build
  381. > you a sourced statistics page on this — it's a one-time effort that
  382. > typically earns you backlinks for months because journalists cite
  383. > it organically. The page would have ~50-80 stats, 2 charts, and a
  384. > couple of comparison tables. Takes me ~5-10 minutes to research and
  385. > draft. Want me to do it before pitching, or just pitch directly?"*
  386. ### How to execute
  387. 1. **Read `STATISTICS_PAGE_PLAYBOOK.md`** — it has the full research
  388. methodology, source quality bar, and HTML build instructions.
  389. 2. **Pull the user's bio info** so the byline + author footer are
  390. filled correctly:
  391. ```bash
  392. python3 qwoted_profile.py --action get
  393. ```
  394. Use `first_pitchable_entity.name`, `.url`, `.company_name`, `.bio`.
  395. 3. **Research** using the playbook's source priority + quality bar.
  396. 4. **Build the HTML** by filling in the placeholders in
  397. `templates/statistics_page_example.html`.
  398. 5. **Save to** `./statistics_pages/<slug>.html`.
  399. 6. **Tell the user** how to preview (`open ./statistics_pages/<slug>.html`)
  400. and ask them to publish on their own site (their CMS, their call).
  401. 7. **Wait for the public URL** — don't proceed to Stage 4 without it.
  402. ---
  403. ## Stage 4 — Draft and send pitches
  404. ### How to write a great pitch (this is on YOU, the AI)
  405. Each pitch should be:
  406. * **2-4 short paragraphs**, max 250-400 words.
  407. * **First sentence** says who the user is and why they're qualified for
  408. *this specific* request. (Don't recycle the bio — synthesize.)
  409. * **Body** gives the reporter *concrete, quotable insights* directly
  410. answering the request. 2-4 bullet points work great. Numbers,
  411. specific examples and contrarian takes get used; vague platitudes
  412. get deleted.
  413. * **If you built a Stage 3 stats page** for this topic, reference
  414. the URL in the second paragraph: *"I just published a 50-stat
  415. roundup on [topic] at [URL] — happy to pull the most relevant
  416. ones for your angle."* This is the move that gets the page cited.
  417. Quote 2-3 of the most striking stats inline so the reporter sees
  418. immediate value without clicking.
  419. * **Last sentence** offers a credit format (e.g. `Credit me as Jane
  420. Doe, founder of Acme Inc (acme.com)`) and an offer to expand or
  421. hop on a quick call.
  422. * **No links in the pitch body OTHER than the stats page URL** — keep
  423. the pitch focused. The stats page is the only link that earns a
  424. backlink.
  425. * **No corporate marketing speak.** Talk like a smart founder
  426. emailing a friend at TechCrunch.
  427. Save it to a tempfile so quoting is reliable:
  428. ```bash
  429. cat > /tmp/qwoted_pitch.txt <<'EOF'
  430. Hi! Borja Obeso here — founder of Distribb, a content distribution
  431. and SEO platform that pushes one piece of content across 200+ DR40+
  432. sites and channels. I see this national-vs-local split every day...
  433. [2-4 paragraphs of substance]
  434. Credit me as Borja Obeso, founder of Distribb (distribb.io).
  435. — Borja
  436. EOF
  437. ```
  438. ### Step 1 — DRY-RUN first (always)
  439. ```bash
  440. python3 qwoted_pitch.py \
  441. --source-request-id 235897 \
  442. --pitch-text-file /tmp/qwoted_pitch.txt
  443. ```
  444. This creates a draft on Qwoted and autosaves the text. **The reporter
  445. is NOT notified.** Show the resulting draft to the user (or summarise
  446. it) and ask for approval.
  447. ### Step 2 — Send it for real
  448. ```bash
  449. python3 qwoted_pitch.py \
  450. --source-request-id 235897 \
  451. --pitch-text-file /tmp/qwoted_pitch.txt \
  452. --research-page-url https://acme.com/blog/ai-marketing-statistics-2026 \
  453. --send
  454. ```
  455. The `--research-page-url` flag is optional but **strongly recommended
  456. when you built a Stage 3 stats page**. It gets logged alongside the
  457. pitch in `~/.qwoted/sent_pitches.json` so you can later answer
  458. questions like "which research pages drove the most pitches" or
  459. "which page is the user citing in this PR push".
  460. `status: "sent"` in the RESULT line means the reporter has been
  461. notified. The pitch is also appended to `~/.qwoted/sent_pitches.json`.
  462. ### Duplicate guard
  463. The script refuses to pitch a source-request that's already in
  464. `sent_pitches.json` (returns `status: "skipped_duplicate"`). It also
  465. detects pitches sent through the Qwoted UI (returns an error like
  466. `source_request_id=N already has a SENT pitch`). To override locally,
  467. pass `--allow-duplicates` (Qwoted itself only allows one pitch per
  468. source-request, so the server-side block is hard).
  469. ---
  470. ## Common error patterns and how to handle them
  471. | `RESULT.error` contains... | Meaning | Action |
  472. |---|---|---|
  473. | `No Qwoted session found` / `session expired` | Cookies missing or expired | Run `python3 qwoted_login.py` |
  474. | `Cannot --send: no pitchable Source/Company/Product` | User skipped Stage 1c | Run `qwoted_profile.py --action create ...` |
  475. | `already has a SENT pitch` | This SR has been pitched already | Pick a different opportunity |
  476. | `is stuck in a non-draft, non-delivered state` | Previous submit attempt without entities | Pick a different opportunity (Qwoted won't let us re-edit) |
  477. | `validation errors: ['Bio is too short']` | Form-level issue | Adjust the field and re-run |
  478. ---
  479. ## Things you should NEVER do
  480. * **Never run `--send` without showing the pitch to the user first.** A
  481. pitch is a real message to a real journalist — they remember spammers.
  482. * **Never invent biographical details** about the user. Ask if you don't
  483. know.
  484. * **Never invent statistics in a Stage 3 page.** Every stat must have a
  485. real URL you actually fetched. One fabricated stat caught by a
  486. journalist torpedoes the user's reputation forever. See the
  487. anti-hallucination rules in `STATISTICS_PAGE_PLAYBOOK.md`.
  488. * **Never pitch opportunities outside the user's expertise.** Qwoted
  489. tracks reply rate and bad pitches hurt the account permanently.
  490. * **Never modify `~/.qwoted/sent_pitches.json`** by hand — the
  491. duplicate guard relies on it. Treat it as append-only state.
  492. * **Never commit `~/.qwoted/` to git.** It contains the user's session
  493. cookies (`storage_state.json`) — full account access.
  494. * **Never publish a Stage 3 stats page on Medium / LinkedIn / dev.to
  495. before the user's own domain.** The canonical version must live at
  496. `https://<theirsite>/...` — that's where the backlinks need to go.
  497. ---
  498. ## Quick reference — every command
  499. ```bash
  500. # Setup
  501. python3 qwoted_login.py # idempotent: skips browser if session is still valid
  502. python3 qwoted_login.py --force # open browser even if session is valid (switch accounts)
  503. python3 qwoted_login.py --reset # wipe saved profile + cookie jar, start fresh
  504. python3 qwoted_login.py --headless # headless only works if an existing session is valid
  505. # Profile
  506. python3 qwoted_profile.py --action get # what entities exist?
  507. python3 qwoted_profile.py --action create --full-name '...' --bio '...' --email '...'
  508. python3 qwoted_profile.py --action update --bio '...' # edit first Source
  509. # Search
  510. python3 qwoted_search.py --query "marketing automation" --max-hits 30
  511. python3 qwoted_search.py --query "" --max-hits 50 # all opportunities
  512. # Build a stats page (Stage 3)
  513. # 1. READ STATISTICS_PAGE_PLAYBOOK.md for the research methodology
  514. # 2. Open templates/statistics_page_example.html
  515. # 3. Fill in placeholders → save to ./statistics_pages/<slug>.html
  516. # 4. open ./statistics_pages/<slug>.html # preview
  517. # 5. User publishes on their site → returns public URL
  518. # Pitch
  519. python3 qwoted_pitch.py --source-request-id 235897 --pitch-text-file /tmp/p.txt
  520. python3 qwoted_pitch.py --source-request-id 235897 --pitch-text-file /tmp/p.txt --send
  521. python3 qwoted_pitch.py --source-request-id 235897 --pitch-text-file /tmp/p.txt \
  522. --research-page-url https://acme.com/blog/x-stats-2026 --send # with stats page
  523. python3 qwoted_pitch.py --opportunity-id de1ccdba --pitch-text-file /tmp/p.txt --send # short URL form
  524. ```
  525. State directory: `~/.qwoted/` (override with `QWOTED_HOME` env var).
README.md · README · 253 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Qwoted SEO Backlinks Skill
  2. <p align="center">
  3. <b>Built by the team at <a href="https://distribb.io">Distribb</a> — the SEO & backlinks autopilot for operators.</b><br/>
  4. <a href="https://distribb.io"><b>→ Automate your SEO and backlinks with us at distribb.io</b></a>
  5. </p>
  6. ---
  7. > **AI-powered PR automation for Qwoted, with linkable-asset
  8. > generation built in.** Let your Claude Code agent set up your
  9. > expert profile, find journalist requests, **research and build a
  10. > sourced statistics page on the topic** (the kind journalists love
  11. > to cite), and send pitches that link to it — earning press
  12. > mentions and recurring high-DR backlinks while you focus on the
  13. > work that matters.
  14. [Qwoted](https://qwoted.com) is the modern HARO replacement: every day,
  15. journalists at TechCrunch, Forbes, Inc., 1851 Franchise, Adweek and
  16. 6,000+ other publications post requests for expert sources on a topic
  17. they're writing about. Reply with a thoughtful pitch and you might land
  18. in the article — usually with a do-follow link back to your site (which
  19. is why this is one of the best white-hat SEO backlink channels in 2026).
  20. **The unique move in this skill is Stage 3:** instead of just sending
  21. a naked opinion pitch, Claude can research and generate a
  22. comprehensive HTML statistics page on the topic (40-80 sourced stats,
  23. Chart.js charts, schema.org markup, ready to publish on your CMS).
  24. You publish it, Claude pitches with the link. The journalist gets
  25. quotable numbers; you get one-shot mentions *plus* recurring
  26. citations for months as other reporters discover your page through
  27. search.
  28. This skill teaches Claude Code (or any AI agent that can shell out) how
  29. to drive Qwoted end-to-end on your behalf, so you can say things like:
  30. - *"Find me PR opportunities about marketing automation today."*
  31. - *"Build me a sourced stats page on AI in marketing, then pitch
  32. the top 3 opportunities about it."*
  33. - *"Update my Qwoted bio to reflect my new role."*
  34. …and have it actually happen.
  35. ---
  36. ## Install as a Claude Code skill
  37. ```bash
  38. npx skills add Bomx/qwoted-seo-backlinks-skill
  39. ```
  40. Or clone manually:
  41. ```bash
  42. git clone https://github.com/Bomx/qwoted-seo-backlinks-skill.git
  43. cd qwoted-seo-backlinks-skill
  44. pip install -r requirements.txt
  45. playwright install chromium
  46. ```
  47. That's it. Claude reads `SKILL.md` to learn the workflow.
  48. ## Setup (3 minutes, one time)
  49. ### 1. Sign up for Qwoted
  50. Free account at [qwoted.com](https://qwoted.com). Pick the "I am a
  51. source / brand" option (not "I am media"). You'll get an email to
  52. verify.
  53. ### 2. Tell Claude to set you up
  54. Once the skill is installed, just say:
  55. > *"Set me up on Qwoted. My name is Jane Doe, I'm the founder of Acme
  56. > Inc, our website is acme.com and my LinkedIn is /in/jane-doe. We do
  57. > marketing automation for B2B SaaS."*
  58. Claude will:
  59. 1. Run `qwoted_login.py` — a Chromium window opens; you sign in to
  60. Qwoted (this includes MFA, captchas, anything Qwoted asks for).
  61. 2. Save your session cookies to `~/.qwoted/storage_state.json`.
  62. 3. Run `qwoted_profile.py --action create ...` to fill out your
  63. "expert" Source persona (the thing Qwoted attaches to every pitch
  64. so reporters know who's pitching them).
  65. 4. Confirm everything is wired up correctly.
  66. ### 3. Done — start pitching
  67. > *"Find Qwoted opportunities about SaaS pricing this week, then pitch
  68. > the top 3."*
  69. Claude will search the index, draft a custom pitch per opportunity
  70. based on your bio, **show each pitch to you for approval**, and then
  71. submit only the ones you say yes to. Sent pitches are logged to
  72. `~/.qwoted/sent_pitches.json` so the same opportunity never gets
  73. pitched twice.
  74. ---
  75. ## What the skill ships
  76. | File | What it does |
  77. |---|---|
  78. | `qwoted_login.py` | One-time browser login. Saves cookies to `~/.qwoted/`. Re-runs only if cookies expire (typically every 30 days). |
  79. | `qwoted_profile.py` | Get / create / update your Qwoted "Source" persona — the bio, employer, location and contact links every pitch is attached to. |
  80. | `qwoted_search.py` | Searches the same Algolia index Qwoted's website uses. Returns clean JSON with deadline, publication, request type, hashtags, etc. |
  81. | `qwoted_pitch.py` | Drafts and (optionally) submits pitches via Qwoted's internal API. Defaults to dry-run; you must pass `--send` to actually fire. Optional `--research-page-url` flag logs the linked stats-page URL for traceability. |
  82. | `STATISTICS_PAGE_PLAYBOOK.md` | The research methodology Claude follows when building a Stage-3 stats page: source quality bar, anti-hallucination rules, structure, length targets, anti-patterns. |
  83. | `templates/statistics_page_example.html` | Self-contained HTML scaffold (modern responsive CSS, Chart.js charts, Article + FAQPage schema markup, print-friendly). Claude fills in the placeholders. |
  84. | `SKILL.md` | The Claude Code playbook itself — frontmatter + 4-stage workflow. |
  85. All four scripts are pure Python (`requests` + `playwright`) and have
  86. an opinionated `RESULT: { ... }` JSON output line so AI agents can
  87. chain them together reliably.
  88. ---
  89. ## The 4-stage workflow
  90. ```
  91. ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐ ┌──────────────┐
  92. │ 1. Onboard │ → │ 2. Find │ → │ 3. Research + │ → │ 4. Pitch │
  93. │ (login + │ │ opportunity │ │ publish a stats │ │ with the │
  94. │ profile) │ │ │ │ page (linkable │ │ page URL │
  95. │ │ │ │ │ asset) │ │ │
  96. └──────────────┘ └──────────────┘ └──────────────────┘ └──────────────┘
  97. once every session once per topic every pitch
  98. ```
  99. Stage 3 is the multiplier. A naked pitch lands one quote in one
  100. article. A pitch that links to a thoroughly-sourced stats page lands
  101. *recurring* citations for months because the next reporter who
  102. searches `"<topic> statistics 2026"` finds the page on your domain
  103. and cites it on their own.
  104. ## State directory
  105. Everything lives under `~/.qwoted/` and `./statistics_pages/`:
  106. ```
  107. ~/.qwoted/
  108. ├── storage_state.json # session cookies (full account access — do NOT share)
  109. ├── chromium-profile/ # persistent Chromium profile so re-logins are 1-click
  110. ├── profile_state.json # snapshot of your Sources/Products/Companies
  111. ├── sent_pitches.json # append-only log w/ research_page_url tracking
  112. └── opportunities/ # JSON dumps from each search
  113. └── marketing_20260422_153058.json
  114. ./statistics_pages/ # generated stats pages (Stage 3 output)
  115. └── ai-in-marketing-statistics-2026.html
  116. ```
  117. Override the `~/.qwoted/` location with `QWOTED_HOME=/some/path`.
  118. Reset by deleting the folder.
  119. ---
  120. ## Running the scripts directly (no AI)
  121. You can use this skill as a regular CLI too:
  122. ```bash
  123. # Set up
  124. python3 qwoted_login.py
  125. python3 qwoted_profile.py --action get
  126. # Find opportunities about SaaS pricing
  127. python3 qwoted_search.py --query "saas pricing" --max-hits 20
  128. # Dry-run a pitch (no email sent)
  129. python3 qwoted_pitch.py \
  130. --source-request-id 235897 \
  131. --pitch-text-file ./my_pitch.txt
  132. # Actually send it
  133. python3 qwoted_pitch.py \
  134. --source-request-id 235897 \
  135. --pitch-text-file ./my_pitch.txt \
  136. --send
  137. ```
  138. Run any script with `--help` for the full flag list.
  139. ---
  140. ## Why a separate "expert" Source persona is required
  141. Qwoted's pitch API will happily accept a submission *without* a
  142. pitchable entity attached (HTTP 200, draft=false), but **the reporter
  143. is never notified**. The pitch is functionally dead. We learned this
  144. the hard way; the skill now refuses to fire `--send` if no Source /
  145. Product is attached, and the setup wizard makes sure you have one
  146. before you can pitch.
  147. ---
  148. ## Privacy + security
  149. - **No telemetry.** Every script makes one of: a Qwoted API call, an
  150. Algolia search, or a local file write. There is no third-party
  151. reporting, analytics or "phone home". Read the source, all 5 files
  152. are < 700 lines each.
  153. - **Cookies stay local.** `~/.qwoted/storage_state.json` never leaves
  154. your machine. It IS effectively your Qwoted password — `.gitignore`
  155. blocks it from being committed accidentally.
  156. - **MIT license.** Fork it, ship a paid SaaS on top of it, whatever.
  157. ---
  158. ## Troubleshooting
  159. | Symptom | Fix |
  160. |---|---|
  161. | `No Qwoted session found` | `python3 qwoted_login.py` |
  162. | Login window opens but never closes | You're stuck on Qwoted's login page. Sign in fully. |
  163. | `Cannot --send: no pitchable Source/Company/Product` | Run `qwoted_profile.py --action create ...` first. |
  164. | `already has a SENT pitch` | Qwoted only allows one pitch per source-request. Pick a different one. |
  165. | Playwright says `Executable doesn't exist` | Run `playwright install chromium` once. |
  166. ---
  167. ## Want your entire SEO engine on autopilot?
  168. This skill is one piece of a bigger system. **[Distribb](https://distribb.io)**
  169. handles the rest:
  170. - Keyword research with real buyer-intent signals
  171. - Original-data research pages (exactly like Stage 3 of this skill, but
  172. automated across your whole content calendar)
  173. - Publishing to WordPress / Webflow / Shopify
  174. - A high-DR backlink-exchange network with 200+ DR40+ sites
  175. - Internal linking + social-media repurposing
  176. **[→ Automate your SEO and backlinks at distribb.io](https://distribb.io)**
  177. Built by [Borja Obeso](https://www.linkedin.com/in/borja-obeso/), founder of
  178. [Distribb](https://distribb.io). Related: the
  179. [Distribb Claude skill](https://github.com/Bomx/distribb-skill) for keyword
  180. research, backlink exchange and CMS publishing.
  181. ---
  182. ## Related searches this repo answers
  183. `qwoted automation`, `qwoted api`, `qwoted skill claude`, `claude code
  184. seo skill`, `auto pr backlinks`, `journalist pitch automation`, `haro
  185. alternative automation`, `pr outreach ai agent`, `expert source pr
  186. tool`, `automated press mentions`, `ai-generated statistics page`,
  187. `linkable asset for seo`, `journalist citation backlinks`,
  188. `programmatic seo pr`, `claude code stats page generator`,
  189. `haro pitch automation 2026`.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.