Imported from hmkm-dev/My-agent- (SKILL.md). Install upstream with npx skills add hmkm-dev/My-agent-. Copyright stays with the author.

Qwoted SEO Backlinks Skill — playbook for Claude

Your job is to get the user press mentions and high-DR backlinks from journalists who post requests on Qwoted.

Operating rules — READ THIS FIRST, THEN FOLLOW IT EVERY TURN

These rules take precedence over anything else in this file. Do not skip them, do not substitute your own judgement.

1. You are running a 4-stage playbook, not a chatbot. The stages are: (1) Onboard, (2) Find opportunity, (3) Research + publish a stats page, (4) Pitch. Whenever the user says anything vague like "ok next step", "what now?", "help me with this", "go", your reply MUST start with "We're at Stage X of 4. Next I'll do Y, because Z." Never just ask "what do you want to do?" — propose the next stage based on where we are.
2. Stage 3 is the multiplier and you must proactively propose it. Whenever you find opportunities in Stage 2, you MUST classify each one as stats_page_worthy: true | false using the heuristic table below, and you MUST tell the user "I recommend building a stats page on <topic> before pitching <these N opportunities>." Do not wait for the user to ask about stats pages. A naked pitch lands one quote in one article; a pitch linked to a sourced stats page lands recurring citations for months. Leaving Stage 3 on the table is leaving money on the table.
3. Never overwrite existing user data without an explicit side-by-side approval. Before calling qwoted_profile.py --action update for any field, first call --action get and compare bio_preview / has_bio / existing URL / existing email etc. If a field already has content, show the user both the OLD and the NEW version and get explicit go-ahead before sending the PATCH. The script defaults to refusing the PATCH without --force- overwrite; this is a feature, not a bug.
4. Never invent opportunity IDs, source IDs, or journalist names. Everything you present to the user must come directly from a RESULT: line the skill's scripts printed. If you didn't see it in a subprocess RESULT, you don't know it.
5. The login step is idempotent and browser-free when a session exists. Run python3 qwoted_login.py. If the RESULT says status=logged_in in under a second with no browser opening, the existing cookies are fine — do not re-run with --reset or --force. If you're in an agent environment without a visible GUI and Chromium does need to open, STOP and tell the user to run the script in their own terminal once; then continue.
6. RESULT: lines are the canonical channel. Every script emits one JSON line prefixed with RESULT: . Parse it; ignore stderr logs (those are for the human). Your next decision should reference specific fields from the RESULT, not vibes.
7. The stats page must contain ZERO outbound <a> tags. Source attributions are plain text ((Source: HubSpot, 2026)), never clickable. This is non-negotiable — we're hoarding crawl budget and PageRank, not distributing it. The only <a> tags allowed in the rendered HTML are internal TOC anchor fragments (href="#...") and a same-domain author-bio CTA. Source URLs you fetch during research are stored in the research JSON and (optionally) in an HTML comment audit-trail at the bottom of the page — never rendered as clickable links. See STATISTICS_PAGE_PLAYBOOK.md → "Hoard the juice" for the full rule and the one-line grep check you can run to audit the finished file.

Stage-3 classification heuristic — use this every time you hand back Stage 2 results

For every opportunity returned by qwoted_search.py, score it on these criteria:

Rule: propose Stage 3 whenever total score ≥ 2. Otherwise pitch direct. State the score in your recommendation so the user sees why.

Example output you should produce after Stage 2 completes:

Found 8 opportunities. Stage-3 classification:

#	Title	Score	Recommendation
1	Selling Signals — awareness vs demand	+1	Pitch direct (deadline 20h, topic matches but no "statistics" ask)
2	SEOptimer — how your agency makes money	-3	Pitch direct (founder-story, deadline 8h)
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
...

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?

Tooling overview

The skill ships four CLI scripts you call as subprocesses, plus a research playbook and an HTML template. Each script prints a single RESULT: { ... } JSON line on stdout that you parse to decide the next step. Detailed human-readable logs go to stderr.

qwoted_login.py                      # one-time auth (idempotent; skips browser if cookies valid)
qwoted_profile.py                    # get/create/update the "expert" Source persona
qwoted_search.py                     # search opportunities (Algolia, returns JSON)
qwoted_pitch.py                      # draft + send a pitch to a specific opportunity

STATISTICS_PAGE_PLAYBOOK.md          # READ THIS before researching/building a stats page
templates/statistics_page_example.html # HTML scaffold to fill in

All cookies, sent-pitch logs, search results and generated stat pages live under ~/.qwoted/ and ./statistics_pages/.

The full workflow (4 stages)

  ┌──────────────┐    ┌──────────────┐    ┌──────────────────┐    ┌──────────────┐
  │ 1. Onboard   │ →  │ 2. Find      │ →  │ 3. Research +    │ →  │ 4. Pitch     │
  │  (login +    │    │  opportunity │    │  publish a stats │    │  with the    │
  │   profile)   │    │              │    │  page (linkable  │    │  page URL    │
  │              │    │              │    │  asset)          │    │              │
  └──────────────┘    └──────────────┘    └──────────────────┘    └──────────────┘
       once             every session       once per topic           every pitch

Decision tree — what to do based on what the user asks

Stage 1 — Onboarding (run ONCE per user)

1a. Install

If the user doesn't have the skill installed, pip-install the deps and run Playwright's browser bootstrap:

pip install -r requirements.txt
playwright install chromium

1b. Log in

python3 qwoted_login.py

Important — this script is idempotent. Before launching any browser it probes ~/.qwoted/storage_state.json against Qwoted's API. If the cookies still work (which they usually do — Qwoted sessions last weeks), the script exits immediately with RESULT: {"status": "logged_in", ...} and no browser opens at all. That's the happy path — do not re-run with --reset or --force unless you have a reason.

Only if no valid session exists will a Chromium window open. In that case: tell the user to sign in IN THAT Chromium WINDOW — not in their regular Chrome/Safari, because those are separate browsers with separate cookies, so signing in elsewhere will NOT save a session for this skill. When they reach a logged-in page the script auto-detects it, saves cookies to ~/.qwoted/storage_state.json, closes the browser and exits. The next login is one click because Chromium remembers them.

If you are running inside an agent environment that can't show GUI windows (some Codex or CI setups), the Chromium window will launch invisibly and the script will hang on the sign-in page. In that case:

1. STOP. Do not keep re-running. Tell the user to open their own terminal on their own machine and run python3 qwoted_login.py there once — they'll see the browser, sign in, and storage_state.json will be written. After that, every future call from the agent will use the already-valid cookies (no browser needed).

If the user doesn't have a Qwoted account yet, send them to qwoted.com to sign up first (free for sources).

1c. Set up the expert profile (Source persona) — REQUIRED

Critical constraint: Qwoted only delivers a pitch to a reporter when the pitch is attached to a pitchable entity — a Source, Company or Product the user is allowed to pitch as. The pitch API will accept a submission without one (HTTP 200, draft=false) but the reporter is never notified. Always make sure the user has a Source persona configured before the first pitch.

Check first:

python3 qwoted_profile.py --action get

Parse the RESULT: JSON. Key fields you MUST inspect before doing anything else:

• seo_ready — boolean, all three must-have fields are set.
• ready_to_pitch — boolean, at least one pitchable entity exists.
• missing_for_seo — array of field names still empty.
• bio_preview — first 240 chars of the current bio (empty string if there really is no bio).
• bio_length — total bio length in chars.
• first_pitchable_entity — full object including bio, business_url, email, has_linkedin_url, etc.

Decision tree:

• If seo_ready == true → skip to Stage 2. Do NOT "improve" the existing profile unless the user explicitly asked you to. Read the bio_preview so you know what the user's positioning is, then move on.
• If ready_to_pitch == true but seo_ready == false → the persona exists but is incomplete. For each item in missing_for_seo, ask the user the corresponding question and patch with --action update:
  • business_url → "What URL should reporters link to when they credit you?" → --action update --url https://acme.com
  • bio → draft a 2-4 sentence bio, SHOW it to the user, get explicit approval, then --action update --bio "...". (If a bio is actually present and missing_for_seo still lists it, you probably have a stale local copy of the skill — update it.)
  • email → "Which email should reporters reply to?" → --action update --email jane@acme.com Run --action get again afterwards to confirm seo_ready is now true.
• If ready_to_pitch == false → no persona exists. Go to the create flow below.

⚠️ Safety rail — overwrite protection. If the user asks you to change an already-populated field (e.g. "update my bio to X"), the script will REFUSE the PATCH unless you pass --force-overwrite. This is intentional. The correct flow is:

1. Run --action get and read bio_preview.
2. Show the user BOTH the current bio AND the proposed new one.
3. Ask explicitly: "Replace the current bio with this one?"
4. Only if they say yes, re-run with --force-overwrite.

Never pass --force-overwrite preemptively "just in case".

If ready_to_pitch == false, you need to collect the user's info in a single message before running create. Don't drip-ask one field at a time. Use this exact checklist:

REQUIRED to even create the profile:

• --full-name — the user's real name as the byline should appear

STRONGLY RECOMMENDED — without these the profile is useless for SEO:

• --url — the user's business website URL (e.g. https://acme.com). ⚠️ This is the link journalists put in their articles when they credit the user. No URL = no backlink = the whole point of this skill is defeated. Confirm it before running create.
• --bio — a 2-4 sentence description of who the user is, what they do, and what topics they can credibly speak to. The bio is what reporters skim when deciding whether to use a quote. Mention the business name, role, and 2-3 areas of expertise. If the user gave you their bio elsewhere, use that. If not, draft one from what they told you and show it to them for approval before submitting.
• --email — the user's professional email (where reporters reply).

NICE TO HAVE (ask but don't block on):

• --linkedin — full LinkedIn profile URL (boosts credibility a lot)
• --location — "City, State, Country" (some pubs filter by region)
• --gender — one of f / m / nb / sd (for pronouns in articles)
• --twitter, --phone, --facebook, --instagram — only if the user wants reporters to have these channels.

Always ask the user to confirm at minimum the URL, bio and email before firing the create command. Those three are what end up in articles. Example of how to ask:

"Before I set up your Qwoted expert profile, I need to confirm a few things that journalists will see and link to:

1. Business URL — what site should reporters link to when they credit you? (e.g. https://acme.com)
2. Bio — here's a draft based on what you told me: "Jane is the founder of Acme Inc, a B2B SaaS that helps marketing teams ship campaigns 10x faster. She speaks to growth, GTM and pricing." Sound right?
3. Reply-to email — which email should reporters use to follow up?

Anything you'd like to add (LinkedIn, location, etc.)?"

Then build the command from their answers:

python3 qwoted_profile.py --action create \
  --full-name "Jane Doe" \
  --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." \
  --url https://acme.com \
  --email jane@acme.com \
  --linkedin https://www.linkedin.com/in/jane-doe/ \
  --location "San Francisco, CA, USA" \
  --gender f

Repeat any contact flag to add multiple values (the first one becomes primary). Other flags: --off-the-record, --hide-from-search-engines.

To update an existing persona later (e.g. the user got a new title):

python3 qwoted_profile.py --action update \
  --bio "Jane is now CEO of Acme Inc..."

--source-slug is optional — without it, the script edits the first Source on the account.

Stage 2 — Find opportunities

python3 qwoted_search.py --query "marketing automation" --max-hits 30

Empty --query "" returns the full index in the order Qwoted shows it on the homepage (newest first).

Read the resulting JSON file (path is in the RESULT: line under out_path). The structure is:

{
  "query": "marketing automation",
  "scraped_at": "2026-04-22T...",
  "count": 30,
  "opportunities": [
    {
      "source_request_id": 235897,        // numeric ID for qwoted_pitch.py
      "name": "Looking for marketing experts to comment on Q3 trends",
      "details": "Reporter brief, 3-4 paragraphs of what they're after...",
      "request_type": "Online article",
      "deadline": "2026-04-28T17:00:00Z",
      "want_pitches": true,
      "publication": {"name": "TechCrunch", "top_publication": true, ...},
      "hashtags": ["#marketing", "#saas"],
      "url": "https://app.qwoted.com/source_requests/235897",
      ...
    },
    ...
  ]
}

Picking the best opportunities

When the user asks for "the best", "top", or "easy wins", rank by:

1. publication.top_publication == true (high-DR sites)
2. easy_win == true (Qwoted's signal: low pitch count, high responsiveness)
3. paid == true (paid placements when applicable)
4. pitch_count_category (lower is better — "low" beats "very_high")
5. Match against the user's expertise (use the bio you already have)
6. Deadline proximity (deadline_approaching, deadline)

Only suggest opportunities where the user genuinely has expertise — journalists ignore obviously irrelevant pitches and Qwoted scores PR accounts on response rate.

⚠️ MANDATORY — classify EVERY opportunity with the Stage-3 heuristic

After you've picked a shortlist, you MUST run each one through the Stage-3 heuristic table at the top of this file and present the classification to the user in a table. Do not skip this step, do not wait for the user to ask about stats pages. A typical output looks like this:

I'd prioritise 5 of the 8 opportunities. Here's the Stage-3 classification:

SR ID	Publication	Topic	Deadline	Stats-page score	Action
235897	TechCrunch	marketing automation trends	3d	+5	Build marketing-automation-statistics-2026.html, then pitch
236422	Selling Signals	awareness vs demand	20h	+1	Pitch direct
234782	BCA Insider	local SEO for retailers	5d	+4	Build local-seo-statistics-2026.html, then pitch
236145	SEOptimer	how agencies make money	8h	-3	Pitch direct (too tight, founder-story)
232532	Business RoundUp	founder interview	8d	-3	Skip ($95 fee, founder-story)

Plan: I'll build the 2 stats pages first (they cluster future opportunities too), then draft direct pitches for #235897, #236422 and #234782 that link to them. I'll draft a plain pitch for #236145 because of the deadline. Sound good?

When the user replies "ok" / "yes" / "go", move on to Stage 3 for the pages you identified, then Stage 4 for the pitches.

Stage 3 — Build a sourced statistics page (the linkable asset)

READ STATISTICS_PAGE_PLAYBOOK.md BEFORE EXECUTING THIS STAGE. This section is just the when. The how (research methodology, source quality bar, HTML build, anti-hallucination rules) lives in the playbook.

Why it matters

A pitch that just contains opinion gets one quote in one article. A pitch that links to a comprehensive, sourced statistics page on the same topic gets the user recurring citations for months — because the next reporter who searches "<topic> statistics 2026" finds the page on the user's domain and cites it without ever knowing the user exists. This is the move that turns Qwoted from a one-off PR tool into a compounding SEO engine.

When to build a stats page (decision rule)

Offer to build one when all of these are true:

1. The opportunity topic is broad enough to support a stats roundup (e.g. "AI in marketing trends" — yes; "founders who pivoted in 2024" — no, that's an anecdote ask).
2. The deadline is at least 24-48 hours away (research takes time if you're going to do it well).
3. The user doesn't already have a recent, high-quality stats page on the same topic.

Skip and go straight to Stage 4 when the deadline is tight or the ask is qualitative (anecdotes, opinions, case studies).

If multiple Stage 2 opportunities are on the same topic, build the stats page once and reuse it across every pitch in that batch with the same --research-page-url flag.

How to ask the user

Don't just unilaterally start building a 3000-word page. Ask:

"Two of the opportunities I found are about [topic]. I can build you a sourced statistics page on this — it's a one-time effort that typically earns you backlinks for months because journalists cite it organically. The page would have ~50-80 stats, 2 charts, and a couple of comparison tables. Takes me ~5-10 minutes to research and draft. Want me to do it before pitching, or just pitch directly?"

How to execute

1. Read STATISTICS_PAGE_PLAYBOOK.md — it has the full research methodology, source quality bar, and HTML build instructions.
2. Pull the user's bio info so the byline + author footer are filled correctly:

   python3 qwoted_profile.py --action get

   Use first_pitchable_entity.name, .url, .company_name, .bio.
3. Research using the playbook's source priority + quality bar.
4. Build the HTML by filling in the placeholders in templates/statistics_page_example.html.
5. Save to ./statistics_pages/<slug>.html.
6. Tell the user how to preview (open ./statistics_pages/<slug>.html) and ask them to publish on their own site (their CMS, their call).
7. Wait for the public URL — don't proceed to Stage 4 without it.

Stage 4 — Draft and send pitches

How to write a great pitch (this is on YOU, the AI)

Each pitch should be:

• 2-4 short paragraphs, max 250-400 words.
• First sentence says who the user is and why they're qualified for this specific request. (Don't recycle the bio — synthesize.)
• Body gives the reporter concrete, quotable insights directly answering the request. 2-4 bullet points work great. Numbers, specific examples and contrarian takes get used; vague platitudes get deleted.
• If you built a Stage 3 stats page for this topic, reference the URL in the second paragraph: "I just published a 50-stat roundup on [topic] at [URL] — happy to pull the most relevant ones for your angle." This is the move that gets the page cited. Quote 2-3 of the most striking stats inline so the reporter sees immediate value without clicking.
• Last sentence offers a credit format (e.g. Credit me as Jane Doe, founder of Acme Inc (acme.com)) and an offer to expand or hop on a quick call.
• No links in the pitch body OTHER than the stats page URL — keep the pitch focused. The stats page is the only link that earns a backlink.
• No corporate marketing speak. Talk like a smart founder emailing a friend at TechCrunch.

Save it to a tempfile so quoting is reliable:

cat > /tmp/qwoted_pitch.txt <<'EOF'
Hi! Borja Obeso here — founder of Distribb, a content distribution
and SEO platform that pushes one piece of content across 200+ DR40+
sites and channels. I see this national-vs-local split every day...
[2-4 paragraphs of substance]
Credit me as Borja Obeso, founder of Distribb (distribb.io).
— Borja
EOF

Step 1 — DRY-RUN first (always)

python3 qwoted_pitch.py \
  --source-request-id 235897 \
  --pitch-text-file /tmp/qwoted_pitch.txt

This creates a draft on Qwoted and autosaves the text. The reporter is NOT notified. Show the resulting draft to the user (or summarise it) and ask for approval.

Step 2 — Send it for real

python3 qwoted_pitch.py \
  --source-request-id 235897 \
  --pitch-text-file /tmp/qwoted_pitch.txt \
  --research-page-url https://acme.com/blog/ai-marketing-statistics-2026 \
  --send

The --research-page-url flag is optional but strongly recommended when you built a Stage 3 stats page. It gets logged alongside the pitch in ~/.qwoted/sent_pitches.json so you can later answer questions like "which research pages drove the most pitches" or "which page is the user citing in this PR push".

status: "sent" in the RESULT line means the reporter has been notified. The pitch is also appended to ~/.qwoted/sent_pitches.json.

Duplicate guard

The script refuses to pitch a source-request that's already in sent_pitches.json (returns status: "skipped_duplicate"). It also detects pitches sent through the Qwoted UI (returns an error like source_request_id=N already has a SENT pitch). To override locally, pass --allow-duplicates (Qwoted itself only allows one pitch per source-request, so the server-side block is hard).

Common error patterns and how to handle them

Things you should NEVER do

• Never run --send without showing the pitch to the user first. A pitch is a real message to a real journalist — they remember spammers.
• Never invent biographical details about the user. Ask if you don't know.
• Never invent statistics in a Stage 3 page. Every stat must have a real URL you actually fetched. One fabricated stat caught by a journalist torpedoes the user's reputation forever. See the anti-hallucination rules in STATISTICS_PAGE_PLAYBOOK.md.
• Never pitch opportunities outside the user's expertise. Qwoted tracks reply rate and bad pitches hurt the account permanently.
• Never modify ~/.qwoted/sent_pitches.json by hand — the duplicate guard relies on it. Treat it as append-only state.
• Never commit ~/.qwoted/ to git. It contains the user's session cookies (storage_state.json) — full account access.
• Never publish a Stage 3 stats page on Medium / LinkedIn / dev.to before the user's own domain. The canonical version must live at https://<theirsite>/... — that's where the backlinks need to go.

Quick reference — every command

# Setup
python3 qwoted_login.py                                  # idempotent: skips browser if session is still valid
python3 qwoted_login.py --force                          # open browser even if session is valid (switch accounts)
python3 qwoted_login.py --reset                          # wipe saved profile + cookie jar, start fresh
python3 qwoted_login.py --headless                       # headless only works if an existing session is valid

# Profile
python3 qwoted_profile.py --action get                   # what entities exist?
python3 qwoted_profile.py --action create --full-name '...' --bio '...' --email '...'
python3 qwoted_profile.py --action update --bio '...'    # edit first Source

# Search
python3 qwoted_search.py --query "marketing automation" --max-hits 30
python3 qwoted_search.py --query "" --max-hits 50        # all opportunities

# Build a stats page (Stage 3)
# 1. READ STATISTICS_PAGE_PLAYBOOK.md for the research methodology
# 2. Open templates/statistics_page_example.html
# 3. Fill in placeholders → save to ./statistics_pages/<slug>.html
# 4. open ./statistics_pages/<slug>.html  # preview
# 5. User publishes on their site → returns public URL

# Pitch
python3 qwoted_pitch.py --source-request-id 235897 --pitch-text-file /tmp/p.txt
python3 qwoted_pitch.py --source-request-id 235897 --pitch-text-file /tmp/p.txt --send
python3 qwoted_pitch.py --source-request-id 235897 --pitch-text-file /tmp/p.txt \
    --research-page-url https://acme.com/blog/x-stats-2026 --send       # with stats page
python3 qwoted_pitch.py --opportunity-id de1ccdba --pitch-text-file /tmp/p.txt --send  # short URL form

State directory: ~/.qwoted/ (override with QWOTED_HOME env var).