Compare commits

...
25 Commits
Author SHA1 Message Date
Corey Haines 3bea48edea Merge pull request #371 from coreyhaines31/development
Release v2.4.2 — ai-seo: OKF coverage
2026-06-15 10:19:14 -07:00
Corey Haines 8d0b7adce2 Merge pull request #370 from coreyhaines31/feature/ai-seo-okf
feat(ai-seo): add Open Knowledge Format (OKF) coverage
2026-06-15 10:18:28 -07:00
Corey HainesandClaude Opus 4.7 f0c3fe8887 feat(ai-seo): add Open Knowledge Format (OKF) coverage
Adds a new reference doc and a brief SKILL.md subsection covering
Google's v0.1 Open Knowledge Format spec, introduced on the Google
Cloud blog on 2026-06-12 and shipped inside Knowledge Catalog.

What changed:
- New references/okf.md (104 lines) with the full breakdown
- Brief OKF subsection in SKILL.md under Machine-Readable Files for
  AI Agents, linking to the reference
- Description triggers extended: llms.txt, OKF, Open Knowledge Format,
  knowledge bundle, agent-readable site
- Brief OKF callout added to the Google AI Overviews section of
  references/platform-ranking-factors.md framing OKF as a "register
  early" protocol bet rather than a confirmed ranking signal
- ai-seo skill metadata version 2.0.1 -> 2.1.0
- Repo version 2.4.1 -> 2.4.2 (patch: no new skill, just content)

Honest framing carried through both files: Google built OKF primarily
for data-team catalog metadata sharing. The site-readable-by-agents
repurposing popularized by Suganthan Mohanadasan is a legitimate but
secondary use. Treat OKF adoption as protocol-layer registration like
early schema.org, not as a tactic that moves rankings today.

Verification: confirmed Google Cloud blog post is live (datePublished
2026-06-12), confirmed v0.1 spec at GoogleCloudPlatform/knowledge-
catalog/okf/SPEC.md, confirmed Knowledge Catalog product page, and
confirmed Suganthan's free OKF generator at suganthan.com/okf-
generator. WordPress plugin awaiting wp.org approval at time of
writing.

validate-skills.sh passes 44/44.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-06-15 10:15:46 -07:00
Corey Haines bee3f2f42c Merge pull request #369 from coreyhaines31/development
docs(readme): add AI Marketing Training CTA
2026-06-12 23:46:27 -07:00
Corey Haines abf10cface Merge pull request #368 from coreyhaines31/feature/readme-ai-marketing-training-cta
docs(readme): add AI Marketing Training CTA
2026-06-12 23:45:51 -07:00
Corey HainesandClaude Opus 4.7 ff3a37dbc8 docs(readme): add AI Marketing Training CTA
Adds a sentence in the intro paragraph pointing to the new offer at
conversionfactory.co/offers/ai-marketing-training. Placed between the
Swipe Files newsletter mention and the Magister autonomous-agent
mention to keep the "learn from content / learn through training /
hands-off autonomous" flow.

Uses the "dangerously good at AI" framing from the launch tweet.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-06-12 23:45:28 -07:00
Corey Haines 4b377f289b Merge pull request #364 from coreyhaines31/development
Release v2.4.1
2026-06-10 13:26:58 -07:00
Corey Haines 4fae86c626 Merge pull request #363 from coreyhaines31/chore/release-v2.4.1-rename-pr-to-public-relations
chore: release v2.4.1 — rename pr to public-relations
2026-06-10 13:26:19 -07:00
Corey HainesandClaude Opus 4.7 6d00fcf644 chore: release v2.4.1 — rename pr to public-relations
Renames the new pr skill to public-relations to avoid collision with
pull-request-named skills common in other Claude Code plugins (code
review, GitHub automation, etc.). The skill description already said
"not pull requests" but the directory name and "/pr" trigger were still
ambiguous to skill resolvers and users.

Rename happened within hours of the initial v2.4.0 publish, before
meaningful install adoption. No content changes - skill version stays
at 1.0.0.

Updates:
- git mv skills/pr/ skills/public-relations/
- name: public-relations in SKILL.md frontmatter
- social/SKILL.md cross-reference updated (958 chars, still under 1024)
- VERSIONS.md table row + 2.4.0 entry + new 2.4.1 entry
- README.md skills table row + alphabetical re-sort (public-relations
  now between prospecting and referrals)
- marketplace.json metadata.version + plugin.json version to 2.4.1

Caught while drafting v2.4.0 social-announcement content.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-06-10 13:25:46 -07:00
Corey Haines d0d00c12ff Merge pull request #361 from coreyhaines31/development
Hot-fix: social description length
2026-06-10 13:14:20 -07:00
Corey Haines 4c198ab496 Merge pull request #360 from coreyhaines31/fix/v2.4.0-social-description-length
fix(social): trim description under 1024 char limit
2026-06-10 13:13:54 -07:00
Corey HainesandClaude Opus 4.7 f45cbdb6c4 fix(social): trim description under 1024 char Agent Skills limit
The v2.4.0 description expansion to add listening trigger phrases pushed
the description to 1188 chars, exceeding the Agent Skills 1-1024 limit
documented in AGENTS.md. validate-skills.sh failed for social. Caught by
codex review.

Trimmed redundant phrases (monitor mentions/find brand mentions/track
competitors/who is complaining about/posts to engage with/engagement
triage/find people asking for collapsed to canonical forms) and
shortened the cross-references. Now 944 chars. Listening discoverability
preserved through 'social listening,' 'brand mentions,' 'competitor
monitoring,' 'top posts to comment on,' and 'find people asking for.'

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-06-10 13:13:26 -07:00
Corey Haines eadc5484ce Merge pull request #359 from coreyhaines31/development
Release v2.4.0 (corrected)
2026-06-10 13:08:48 -07:00
Corey Haines a064dd837f Merge remote-tracking branch 'origin/main' into development
# Conflicts:
#	.claude-plugin/marketplace.json
2026-06-10 13:08:07 -07:00
Corey Haines 91a9b42aa8 Merge pull request #358 from coreyhaines31/fix/v2.4.0-corrections
fix: v2.4.0 corrections
2026-06-10 13:06:36 -07:00
Corey HainesandClaude Opus 4.7 6f27a99f0a fix: v2.4.0 corrections
Four fixes folded into v2.4.0 after a codex review caught real issues.

- Bump plugin metadata to 2.4.0 (marketplace.json metadata.version and
  plugin.json version). Without this, the claude plugin update path
  would not surface the v2.4.0 release. Also catches the plugin
  description up to 44 skills with the new pr skill called out.
- Extend social SKILL.md description with listening / brand-monitoring /
  competitor-monitoring / engagement-triage trigger phrases so the new
  listening workflow is actually discoverable.
- Fix the newsworthiness rubric in pr/references/newsjacking.md. The
  weights sum to 8x with each dimension scored 1-10, so the max weighted
  total is 80, not 40. Threshold normalized to 50/80.
- Clarify the listening sources template copy command. Show paths for
  plugin/marketplace, .claude/, and in-repo installs instead of assuming
  the user is in the repo root.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-06-10 13:05:54 -07:00
coreyhaines31 74d5bcb462 chore: sync skills with marketplace.json, plugin.json, and README 2026-06-10 19:53:25 +00:00
Corey Haines 1e3bdacfa8 Merge pull request #357 from coreyhaines31/development
Release v2.4.0
2026-06-10 12:53:03 -07:00
Corey Haines dce9908745 Merge pull request #356 from coreyhaines31/chore/release-v2.4.0
chore: release v2.4.0
2026-06-10 12:52:12 -07:00
Corey HainesandClaude Opus 4.7 085bb4c01b chore: release v2.4.0
Adds the `pr` skill (public relations / earned media) and bumps `social`
to 2.1.0 for the listening reference + sources template.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-06-10 12:49:47 -07:00
Corey Haines 9a1001fac1 Merge pull request #355 from coreyhaines31/feature/pr-skill
feat(pr): add public relations skill for earned media
2026-06-10 12:46:31 -07:00
Corey Haines 29d42c399e Merge pull request #347 from coreyhaines31/feature/social-listening-reference
feat(social): add listening reference for engagement triage
2026-06-10 12:45:48 -07:00
Corey HainesandClaude Opus 4.7 c2f7f6482e chore(social): bump version to 2.1.0 for listening reference
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-06-10 12:45:06 -07:00
Corey HainesandClaude Opus 4.7 e3a294055c feat(pr): add public relations skill for earned media work
Adds a `pr` skill covering reactive (newsjacking), proactive (journalist
pitching), inbound (HARO/Qwoted/Featured), and owned (press page) PR
modes. References include: a newsjacking detect-score-angle-pitch loop
with curl-based news monitoring, a journalist pitching workflow with
six pitch templates by angle, a press-platforms triage guide, and a
curated tier list of media outlets / newsletters / podcasts.

Explicitly scoped to earned media — directs to `directory-submissions`
for Product Hunt / BetaList / SaaS directory work.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-06-10 12:27:43 -07:00
Corey HainesandClaude Opus 4.7 310d5997f4 feat(social): add listening reference for engagement triage
Adds a social listening workflow to the social skill — surfacing the top
posts to comment on each day rather than scrolling. Includes a scoring
rubric, comment quality tiers, curl recipes for Reddit/HN/Bluesky, and
a browser-driven path for LinkedIn/X via dev-browser. Ships a copyable
sources template for `.agents/listening-sources.md`.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-06-05 15:08:53 -07:00
15 changed files with 1656 additions and 10 deletions
+2 -2
View File
@@ -6,13 +6,13 @@
},
"metadata": {
"description": "Marketing skills for AI agents — conversion optimization, copywriting, SEO, paid ads, and growth",
"version": "2.3.0",
"version": "2.4.2",
"repository": "https://github.com/coreyhaines31/marketingskills"
},
"plugins": [
{
"name": "marketing-skills",
"description": "43 marketing skills for technical marketers and founders: CRO, copywriting, cold email, prospecting, SEO, AI SEO, paid ads, SMS, ad creative, video production, image generation, co-marketing, churn prevention, pricing, referrals, revenue operations, sales enablement, customer research, site architecture, comprehensive AARRR-structured marketing plans, and more",
"description": "44 marketing skills for technical marketers and founders: CRO, copywriting, cold email, prospecting, SEO, AI SEO, paid ads, SMS, ad creative, video production, image generation, co-marketing, churn prevention, pricing, referrals, revenue operations, sales enablement, customer research, site architecture, comprehensive AARRR-structured marketing plans, public relations and earned media, and more",
"source": "./"
}
]
+1 -1
View File
@@ -1,7 +1,7 @@
{
"name": "marketing-skills",
"description": "Marketing skills for AI agents — conversion optimization, copywriting, SEO, paid ads, ad creative, and growth",
"version": "2.3.0",
"version": "2.4.2",
"author": {
"name": "Corey Haines"
},
+2 -1
View File
@@ -2,7 +2,7 @@
A collection of AI agent skills focused on marketing tasks. Built for technical marketers and founders who want AI coding agents to help with conversion optimization, copywriting, SEO, analytics, and growth engineering. Works with Claude Code, OpenAI Codex, Cursor, Windsurf, and any agent that supports the [Agent Skills spec](https://agentskills.io).
Built by [Corey Haines](https://corey.co?ref=marketingskills). Need hands-on help? Check out [Conversion Factory](https://conversionfactory.co?ref=marketingskills) — Corey's agency for conversion optimization, landing pages, and growth strategy. Want to learn more about marketing? Subscribe to [Swipe Files](https://swipefiles.com?ref=marketingskills). Want an autonomous AI agent that uses these skills to be your CMO? Try [Magister](https://magistermarketing.com?ref=marketingskills).
Built by [Corey Haines](https://corey.co?ref=marketingskills). Need hands-on help? Check out [Conversion Factory](https://conversionfactory.co?ref=marketingskills) — Corey's agency for conversion optimization, landing pages, and growth strategy. Want to learn more about marketing? Subscribe to [Swipe Files](https://swipefiles.com?ref=marketingskills). Want to get dangerously good at using AI for marketing? Check out [AI Marketing Training](https://conversionfactory.co/offers/ai-marketing-training?ref=marketingskills). Want an autonomous AI agent that uses these skills to be your CMO? Try [Magister](https://magistermarketing.com?ref=marketingskills).
New to the terminal and coding agents? Check out the companion guide [Coding for Marketers](https://codingformarketers.com?ref=marketingskills).
@@ -89,6 +89,7 @@ See each skill's **Related Skills** section for the full dependency map.
| [product-marketing](skills/product-marketing/) | When the user wants to create or update their product marketing context document. Also use when the user mentions... |
| [programmatic-seo](skills/programmatic-seo/) | When the user wants to create SEO-driven pages at scale using templates and data. Also use when the user mentions... |
| [prospecting](skills/prospecting/) | When the user wants to find, qualify, and build a list of prospects to reach out to — across B2B SaaS, general B2B, or... |
| [public-relations](skills/public-relations/) | When the user wants help with public relations, earned media, press coverage, journalist outreach, or media strategy... |
| [referrals](skills/referrals/) | When the user wants to create, optimize, or analyze a referral program, affiliate program, or word-of-mouth strategy.... |
| [revops](skills/revops/) | When the user wants help with revenue operations, lead lifecycle management, or marketing-to-sales handoff processes.... |
| [sales-enablement](skills/sales-enablement/) | When the user wants to create sales collateral, pitch decks, one-pagers, objection handling docs, or demo scripts. Also... |
+17 -2
View File
@@ -6,7 +6,7 @@ Current versions of all skills. Agents can compare against local versions to che
|-------|---------|--------------|
| ab-testing | 2.0.0 | 2026-05-05 |
| ad-creative | 2.0.0 | 2026-05-05 |
| ai-seo | 2.0.1 | 2026-05-18 |
| ai-seo | 2.1.0 | 2026-06-15 |
| analytics | 2.0.0 | 2026-05-05 |
| aso | 2.0.0 | 2026-05-05 |
| churn-prevention | 2.0.0 | 2026-05-05 |
@@ -37,6 +37,7 @@ Current versions of all skills. Agents can compare against local versions to che
| product-marketing | 2.0.0 | 2026-05-05 |
| programmatic-seo | 2.0.0 | 2026-05-05 |
| prospecting | 1.0.0 | 2026-05-26 |
| public-relations | 1.0.0 | 2026-06-10 |
| referrals | 2.0.0 | 2026-05-05 |
| revops | 2.0.0 | 2026-05-05 |
| sales-enablement | 2.0.0 | 2026-05-05 |
@@ -45,11 +46,25 @@ Current versions of all skills. Agents can compare against local versions to che
| signup | 2.0.0 | 2026-05-05 |
| site-architecture | 2.0.0 | 2026-05-05 |
| sms | 1.0.0 | 2026-05-21 |
| social | 2.0.0 | 2026-05-05 |
| social | 2.1.0 | 2026-06-10 |
| video | 2.0.1 | 2026-05-18 |
## Recent Changes
### 2.4.2 (2026-06-15)
- **ai-seo** (2.0.1 → 2.1.0): added coverage of Google's Open Knowledge Format (OKF), a v0.1 markdown spec for agent-readable site bundles introduced on the Google Cloud blog on 2026-06-12 and shipped inside Knowledge Catalog. New `references/okf.md` reference covers what OKF is (directory of cross-linked markdown files with YAML frontmatter — `type` required, plus `title`/`description`/`resource`/`tags`/`timestamp` recommended), honest framing (Google built it for data-team catalog metadata; site-readable repurposing popularized by Suganthan Mohanadasan is a clever secondary use), what it does for AI search today (nothing immediate; protocol-layer registration like early schema.org adoption), where OKF fits in the agent-readable stack alongside `sitemap.xml` / `robots.txt` / `llms.txt` / `/pricing.md` / schema, three ways to ship a bundle (Suganthan's free web generator, his pending WordPress plugin, or by hand), hosting guidance (`yoursite.com/okf/index.md` plus an `llms.txt` line pointing to it), when to skip (closed platforms like Wix/Squarespace, very small sites, sites without other machine-readable files), and what to watch (v1.0 spec, AI engine adoption signals). `SKILL.md` adds a brief OKF subsection under "Machine-Readable Files for AI Agents" pointing to the reference. Frontmatter description extended with new triggers: `llms.txt`, `OKF`, `Open Knowledge Format`, `knowledge bundle`, `agent-readable site`. `references/platform-ranking-factors.md` Google AI Overviews section gets an OKF callout framing it as a "register early" protocol bet rather than a confirmed ranking signal.
### 2.4.1 (2026-06-10)
- Renamed `pr` skill to `public-relations` to avoid collision with pull-request skills in other Claude Code plugins (common naming for code-review / GitHub PR automation). The skill description already disambiguated from pull requests, but the directory name `pr` was still ambiguous to skill resolvers and to users typing `/pr`. The rename happened within hours of the initial v2.4.0 publish, before meaningful install adoption. No content changes; skill version stays at 1.0.0. All cross-references in `social/SKILL.md`, `VERSIONS.md`, and `README.md` updated accordingly.
### 2.4.0 (2026-06-10)
- Added `public-relations` skill (originally shipped as `pr`, renamed in v2.4.1) for public relations / earned media work — pitching journalists, newsjacking trending stories, responding to press requests (HARO/Connectively, Qwoted, Featured, Help A B2B Writer), and building the owned-media foundation (press page + media kit). Four PR modes (reactive / proactive / inbound / owned), explicit when-to-skip framing, and a banned-vocabulary list. References include: `newsjacking.md` (detect → score → angle → pitch loop with newsworthiness scoring rubric, 7 angle templates, Google News / HN / Reddit curl recipes, failure modes); `journalist-pitching.md` (media list construction, journalist fit scoring, 6 pitch templates by angle — data story / exclusive launch / op-ed / customer story / trend connector / newsjack response — subject-line craft, embargo etiquette, follow-up cadence); `press-platforms.md` (daily triage workflow, response template, ROI reality check); `media-outlets.md` (tiered list of tech press, SaaS, AI, devtools, business outlets, newsletters, podcasts, vertical press, regional press — explicitly scoped to journalist-driven outlets, with startup directories deferred to `directory-submissions`). Scope is enforced via cross-references: the `public-relations` skill handles earned media; `directory-submissions` handles Product Hunt / BetaList / SaaS directories; `launch` handles the broader launch moment.
- **social** (2.0.0 → 2.1.0): added `references/listening.md` for engagement triage — a daily loop for surfacing the top posts to comment on rather than scrolling feeds. Includes a 5-dimension scoring rubric (ICP fit, intent signal, reach potential, comment opportunity, recency), comment quality tiers, curl-based recipes for Reddit / HN Algolia / Bluesky (no auth required), and a browser-driven workflow for LinkedIn and X via `dev-browser` with persistent session. Added `references/listening-sources-template.md` — a copyable starter for `.agents/listening-sources.md` covering brand/category context, ICP definition, target accounts per platform, intent keywords, subreddits, saved-search URLs, and a do-not-engage list. SKILL.md Engagement Strategy section now links to the listening reference.
- Total skills: 44.
### 2.3.0 (2026-05-27)
- Added `marketing-plan` skill — comprehensive AARRR-structured marketing plan generator. Produces a 13-section Notion-paste-ready plan document (executive summary, strategic frame, current state, AARRR breakdown, 90-day roadmap, 12-month outlook with funding-stage capability unlocks, marketing operations stack mapping skills + MCPs to AARRR stages, tactical idea bank cross-referencing all 139 `marketing-ideas` to AARRR + client-specific status, measurement framework, RACI, open decisions). Customized for current budget, team, stage, and tooling stack. Three-phase workflow: INIT (research + intake), REVIEW (section-by-section walkthrough), FINALIZE (compile + verify + optional publish to shared repo). References include methodology, plan-template, aarrr-framework, current-state-rubric (self-contained 17-section scoring rubric), ops-stack-mapping, idea-cross-reference (139-idea AARRR mapping), funding-stage-unlocks, measurement-framework, client-types (variations by B2B SaaS / D2C / hardware-hybrid / marketplace / dev tool / clinical / commerce), example-quietude (anonymized canonical reference plan, based on a real fCMO engagement with names/identifying details changed), budget-planning (two scientific methods for setting the marketing budget — Revenue-Based 5–40% of ARR, and Goal-Based formula reverse-engineered from the revenue target; plus blended CAC calculation, the 10–20% experimental buffer rule, the 3-3-2-2-2 VC growth path, and the forecasting reality check), growth-patterns (the real shape of SaaS growth — $0–10K / $10K–100K / $100K–1M phases with binding constraints, linear vs step-function vs S-curve patterns, and Channel × Product × Market layering), and team-and-agency-model (the strategy-in-house / execution-outsourced principle, three core functions Growth/Product/Content, π-shaped marketer framework, title progression Manager → Lead → Director → VP → Chief, agency selection framework, and the three-stage scaling model Early/Growth/Scale). Budget, growth-pattern, and team frameworks drawn from *Founding Marketing* by Corey Haines.
+6 -2
View File
@@ -1,8 +1,8 @@
---
name: ai-seo
description: "When the user wants to optimize content for AI search engines, get cited by LLMs, or appear in AI-generated answers. Also use when the user mentions 'AI SEO,' 'AEO,' 'GEO,' 'LLMO,' 'answer engine optimization,' 'generative engine optimization,' 'LLM optimization,' 'AI Overviews,' 'optimize for ChatGPT,' 'optimize for Perplexity,' 'AI citations,' 'AI visibility,' 'zero-click search,' 'how do I show up in AI answers,' 'LLM mentions,' or 'optimize for Claude/Gemini.' Use this whenever someone wants their content to be cited or surfaced by AI assistants and AI search engines. For traditional technical and on-page SEO audits, see seo-audit. For structured data implementation, see schema."
description: "When the user wants to optimize content for AI search engines, get cited by LLMs, or appear in AI-generated answers. Also use when the user mentions 'AI SEO,' 'AEO,' 'GEO,' 'LLMO,' 'answer engine optimization,' 'generative engine optimization,' 'LLM optimization,' 'AI Overviews,' 'optimize for ChatGPT,' 'optimize for Perplexity,' 'AI citations,' 'AI visibility,' 'zero-click search,' 'how do I show up in AI answers,' 'LLM mentions,' 'optimize for Claude/Gemini,' 'llms.txt,' 'OKF,' 'Open Knowledge Format,' 'knowledge bundle,' or 'agent-readable site.' Use this whenever someone wants their content to be cited or surfaced by AI assistants and AI search engines. For traditional technical and on-page SEO audits, see seo-audit. For structured data implementation, see schema."
metadata:
version: 2.0.1
version: 2.1.0
---
# AI SEO
@@ -313,6 +313,10 @@ Add these machine-readable files to your site root:
If you don't have one yet, add an `llms.txt` that gives AI systems a quick overview of what your product does, who it's for, and links to key pages (including your pricing).
**`/okf/` — Open Knowledge Format bundle (Google-backed, v0.1)**
Google [introduced OKF](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing) in June 2026 — a markdown spec for representing site content as a directory of cross-linked files with YAML frontmatter, agent-readable without scraping. Built primarily for data-team catalog metadata; the site-readable-by-agents repurposing was popularized by Suganthan Mohanadasan. No confirmed AI-search ranking signal today — treat it as protocol-layer registration like early schema.org. **For the full breakdown, implementation paths (free generator, WordPress plugin, by-hand), hosting guidance, and when to skip, see [references/okf.md](references/okf.md).**
### Schema Markup for AI
Structured data helps AI systems understand your content. Key schemas:
+104
View File
@@ -0,0 +1,104 @@
# Open Knowledge Format (OKF)
Google's v0.1 markdown spec for representing site content as an agent-readable bundle. Introduced on the [Google Cloud blog](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing) on 2026-06-12 and shipped inside Knowledge Catalog.
## What it is
OKF is a directory of cross-linked markdown files. Each file has:
- A YAML frontmatter block (`type` required; `title`, `description`, `resource`, `tags`, `timestamp` recommended)
- A standard markdown body
- Standard markdown links to other files in the bundle (which the spec treats as concept relationships)
An optional `index.md` lists the files for progressive disclosure. The bundle can be distributed as a git repo (recommended), a tarball/zip, or a subdirectory of a larger repo.
The [full spec](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/HEAD/okf/SPEC.md) fits on one page. The repo lives under `GoogleCloudPlatform` (the "not an official Google product" disclaimer is Google's standard open-source boilerplate, not a denial — it appears on most of Google's open-source repos including their main AI samples repo).
### A minimal concept file
```markdown
---
type: Article
title: How to Connect the Ahrefs MCP Server to Manus
description: The official MCP servers, why they did not connect, and the fix.
resource: https://yoursite.com/blog/ahrefs-mcp-manus/
tags: [mcp, ahrefs]
---
# How to Connect the Ahrefs MCP Server to Manus
The body of the post, as clean markdown.
```
Add an `index.md` that lists all files so an agent can see the bundle's shape before opening each file, and that is the entire format.
## Honest framing
**Google built OKF for data teams sharing catalog metadata** — BigQuery tables, API endpoints, metrics, playbooks. Most of the spec's examples are data-team artifacts, not blog posts. Google's blog post framing: "improve data sharing" and "standardized documentation" for collaboration across teams.
Pointing OKF at a marketing site is a **clever repurposing** popularized by [Suganthan Mohanadasan](https://suganthan.com/blog/open-knowledge-format/). It's a legitimate use case for the format but not Google's primary one. Frame it accurately when explaining it to founders or marketing teams.
## What it does for AI search today
Nothing immediate. Nothing crawls the web for OKF bundles yet — the spec is weeks old, no AI engine has announced integration, and Knowledge Catalog ingests bundles only for paying enterprise customers' data teams.
Treat OKF as **protocol-layer registration** — the same shape of bet as early `schema.org` adoption was a decade ago. Schema took the better part of ten years to pay off; people who shipped it early are still glad they did.
A secondary benefit that pays off today regardless: **generating the bundle is itself an internal-linking audit**. Suganthan's tool draws every page as a node and every internal link as an edge, so islands and orphans become obvious at a glance.
## Where OKF fits in the agent-readable stack
| Layer | Purpose |
|---|---|
| `sitemap.xml` | Tells a crawler which URLs exist |
| `robots.txt` (with AI bot rules) | Permits or blocks AI crawlers |
| `llms.txt` | Points an agent at the handful of pages you most want read |
| `/pricing.md` | Structured pricing for agent-buyer comparisons |
| **`/okf/` bundle** | Hands over the content itself as cross-linked concepts |
| Schema markup | Per-page structured data (Article, FAQPage, Product, etc.) |
These stack rather than compete. `llms.txt` is a signpost, OKF is the library.
## How to ship one
Three options, ordered by how much effort they take:
### 1. Suganthan's free web tool (recommended for most sites)
[suganthan.com/okf-generator](https://suganthan.com/okf-generator/) — paste a URL or sitemap, crawls up to 100 pages, returns a downloadable bundle. Also draws the resulting page graph so you can spot disconnected pages before publishing.
### 2. WordPress plugin (pending wp.org approval)
Suganthan's plugin (free, GPL, awaiting wp.org approval at time of writing) installs in a minute, serves the bundle at `/okf/`, and rebuilds on every publish or edit so it stays in sync. Direct download link is in [his blog post](https://suganthan.com/blog/open-knowledge-format/). Requires WordPress 6.0+ and PHP 7.4+. Read-only — never edits posts or settings.
### 3. By hand
Only practical for a handful of pages. Each post becomes a markdown file with frontmatter that you cross-link manually. Miserable for a whole site.
## Hosting & discovery
Serve the bundle at `yoursite.com/okf/`, starting with `yoursite.com/okf/index.md`:
- **Static hosts / Cloudflare**: drag and drop
- **WordPress**: Suganthan's plugin handles the serving
- **Static sites with custom paths**: upload the directory to `/okf/`
- **Closed platforms (Wix, Squarespace, most page-builders)**: you usually can't serve files at custom paths — skip OKF entirely
After it's serving, add a line to `llms.txt` pointing to the bundle so agents that read `llms.txt` (today) can discover the bundle (later).
## When to skip
- Site is <10 pages — overhead exceeds payoff
- Site is on a closed platform that won't allow custom paths
- You're not maintaining `llms.txt`, schema markup, or other machine-readable files (OKF compounds with those; alone it does nothing)
- You can't budget the 30 minutes a quarter to refresh the bundle as content changes
## What to watch
OKF is v0.1, weeks old. Worth tracking, not worth obsessing over:
- Whether Google announces OKF support in AI Overviews / Knowledge Graph (currently no signal)
- Whether non-Google engines (ChatGPT, Perplexity, Claude) announce OKF reading
- Whether the spec moves to v1.0 (breaking changes are possible at <1.0)
- Whether Knowledge Catalog adds public ingestion endpoints
- Adoption signals — search GitHub for `okf/index.md` to see who's shipping bundles
@@ -34,6 +34,8 @@ Google AI Overviews pull from Google's own index and lean heavily on E-E-A-T sig
- Get into Google's Knowledge Graph where possible (an accurate Wikipedia entry helps)
- Target "how to" and "what is" query patterns — these trigger AI Overviews most often
**Watch for OKF.** In June 2026 Google introduced the [Open Knowledge Format](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing) — a markdown spec for agent-readable site bundles. There is no confirmed signal that AI Overviews factor it in today, but the spec is published, the GitHub repo lives under `GoogleCloudPlatform`, and it ships inside Knowledge Catalog. For protocol-layer "register early" plays, it has the same shape as early schema.org adoption did a decade ago. See **Machine-Readable Files for AI Agents** in the main `SKILL.md` for how to generate and serve a bundle.
---
## ChatGPT
+131
View File
@@ -0,0 +1,131 @@
---
name: public-relations
description: "When the user wants help with public relations, earned media, press coverage, journalist outreach, or media strategy (not pull requests). Also use when the user mentions 'PR,' 'public relations,' 'press,' 'press release,' 'press coverage,' 'media outreach,' 'pitch a journalist,' 'get featured,' 'media list,' 'media kit,' 'press kit,' 'newsjacking,' 'news hijack,' 'HARO,' 'Qwoted,' 'Featured,' 'Help A Reporter,' 'reporter request,' 'tech press,' 'TechCrunch,' 'earned media,' 'thought leadership placement,' 'op-ed,' 'guest article,' 'press contacts,' or 'how do I get press.' Use this for earned media work — finding journalists, pitching stories, newsjacking, and responding to press requests. For startup/SaaS/AI directory submissions, see directory-submissions. For product launches, see launch. For social-media engagement, see social. For cold-email outreach to prospects, see cold-email."
metadata:
version: 1.0.0
---
# Public Relations & Earned Media
You are an expert in earned media for software products. Your goal is to help the user get covered by journalists, podcasts, and newsletters — efficiently, with respect for the people on the other end of the pitch.
## Before Starting
**Check for product marketing context first:**
If `.agents/product-marketing.md` exists (or `.claude/product-marketing.md`, or the legacy `product-marketing-context.md` filename, in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
---
## Core Philosophy
PR is not a substitute for distribution. It's a multiplier for it.
- **Earned media doesn't drive direct conversions.** A TechCrunch hit will not give you 1,000 paying customers. It will give you backlinks, brand legitimacy, AI-citation surface area, and ammo for sales conversations.
- **Pitch journalists like you'd pitch a customer:** specific, useful, fast, and never about you.
- **The story is not your product. The story is the trend, the data, the conflict, or the human.** Your product is the evidence.
- **Speed beats polish on reactive PR.** A B+ pitch in the first hour of a story beats an A+ pitch on day three.
### When PR is worth it
- You have **a real story** — proprietary data, a strong opinion, a milestone, a customer with a sharp before/after, or a fresh angle on a trending topic
- You have **founder/exec time** — journalists want quotes from people with skin in the game, not from a PR rep
- You have **a destination** — a press page, blog post, or product launch that converts attention into something useful
### When to skip PR (for now)
- Pre-launch with no story beyond "we exist"
- No one on the team can sustain pitching for 4–6 weeks (PR is a momentum game)
- You don't have a clear ICP — journalists ask "who reads my piece because of this?" and if you can't answer, neither can they
---
## The PR Mix
Four modes. Most teams over-index on one. Run at least three.
| Mode | What it is | Effort | Speed to coverage |
|------|------------|--------|-------------------|
| **Reactive (newsjacking)** | Inject your POV into trending news | Low–medium | Hours to days |
| **Proactive (pitching)** | Build a media list, pitch original stories | High | 2–8 weeks |
| **Inbound (press requests)** | Respond to journalist queries on HARO/Qwoted/Featured | Low | Days to weeks |
| **Owned (press page + media kit)** | Make it easy for journalists to find you | One-time setup | N/A |
**For the reactive newsjacking workflow** — see [references/newsjacking.md](references/newsjacking.md)
**For proactive journalist pitching** — see [references/journalist-pitching.md](references/journalist-pitching.md)
**For inbound press-request platforms (HARO, Qwoted, etc.)** — see [references/press-platforms.md](references/press-platforms.md)
**For where to pitch (media outlets, podcasts, newsletters)** — see [references/media-outlets.md](references/media-outlets.md). For startup/SaaS/AI directories, use the separate `directory-submissions` skill — different intent, different list.
---
## Owned: Press Page + Media Kit
Set this up once. It's the cheapest PR investment with the highest ROI on every future story.
**Press page (`/press` or `/newsroom`) should include:**
- One-paragraph company description (copy/paste ready)
- Founder bios with headshots (high-res, downloadable)
- Logo pack (SVG + PNG, light + dark, with usage guidelines)
- Product screenshots (high-res)
- Recent coverage list (social proof for the next journalist)
- Founding date, employee count, funding (if disclosed)
- Press contact email (not a form — journalists hate forms)
- Recent press releases / announcements
**One sentence at the top:** "For interview requests or assets, email press@yourcompany.com — we respond within 24 hours."
Then *actually* respond within 24 hours.
---
## Quick Reference: Pitch Quality Bar
Before sending any pitch, the answer to all of these should be yes:
- [ ] Does this journalist cover this beat? (Check their last 5 articles.)
- [ ] Is there a clear news hook — something that just happened or is about to?
- [ ] Could this journalist write a complete story from this email alone? (Data, quotes, customer name, contact.)
- [ ] Is the subject line specific enough to predict the article's headline?
- [ ] Is the pitch under 150 words?
- [ ] Did you avoid the words "revolutionary," "game-changing," "disruptive," and "synergy"?
- [ ] Is the ask clear? (Interview? Embargo? Exclusive? Quote?)
If any answer is no, don't send.
---
## Measurement
What to track:
| Metric | Why |
|--------|-----|
| **Coverage count** (placements / month) | Activity baseline |
| **Domain rating of placements** | Backlink value |
| **Referral traffic from coverage** | Did anyone actually click? |
| **Brand search lift** | Did people search you after reading? |
| **AI citation rate** (ChatGPT, Perplexity quote your brand?) | The new measurement that matters |
| **Sales conversations citing the article** | The only one that matters for revenue |
What not to obsess over: AVE (advertising value equivalency) — it's a vanity metric PR firms invented.
---
## Common Workflows
### "Help me newsjack [trending story]"
Go to [newsjacking.md](references/newsjacking.md), run the scoring rubric, draft 2–3 angles, pick the best, draft the pitch.
### "Find journalists who cover [beat]"
Go to [journalist-pitching.md](references/journalist-pitching.md), use the discovery checklist + dev-browser to research recent articles, build a scored list.
### "What's worth pitching this week?"
Combine: recent product milestones + active news cycles + any data you've collected. Score each potential story by the quality bar above.
### "Respond to this HARO query"
Go to [press-platforms.md](references/press-platforms.md), use the response template, keep it under 200 words.
### "Build my press page"
Use the checklist above. Most companies do this in an afternoon and forget about it for a year — that's fine.
@@ -0,0 +1,368 @@
# Journalist Pitching — Proactive PR Workflow
Building a media list, scoring journalist fit, and crafting pitches that actually get opened. This is a 4–8 week practice, not a one-shot.
## Contents
- Building the media list
- Scoring journalist fit
- Pitch templates by angle
- Subject lines that get opened
- Voice and structure
- Embargoes, exclusives, and follow-up etiquette
- Pitch killers
- Tooling
---
## Building the Media List
The goal: a list of 20–40 journalists who actually cover your beat. Not 500 names from a database.
### Discovery checklist
For each candidate journalist:
- [ ] Read their **last 5 articles** — are they covering your beat right now?
- [ ] Note their **publication** — does it reach your ICP?
- [ ] Check their **bio** on the outlet site — what topics do they own?
- [ ] Check **X/LinkedIn** for what they're posting about this week
- [ ] Note their **email** (usually on outlet author page, Muck Rack, or company About page)
- [ ] Check **Muck Rack** if available — it shows recent topics and pitch preferences
### Where to find candidates
| Method | How |
|--------|-----|
| **Reverse lookup from coverage you want** | Find 5 articles about competitors / your category, note bylines |
| **Topic search on Muck Rack** | Free tier shows journalists by topic |
| **X / Twitter lists** | "[your niche] reporters" lists already exist |
| **LinkedIn search** | "Journalist" + "[your category]" — filter by recent activity |
| **Newsletter author pages** | Beehiiv, Substack, ConvertKit creators are pitchable |
| **Podcast host research** | Listen to 1 episode before pitching — non-negotiable |
### Don't waste time on
- **Mass media databases** (Cision, Meltwater) for early-stage — overkill and expensive
- **Journalists who haven't posted in 6+ months** — they may have left
- **"Editor-in-chief" generic addresses** — pitches there get ignored or routed to interns
- **Journalists who explicitly state "no PR pitches" in bio** — respect it
---
## Scoring Journalist Fit
Score each journalist 1–10 across four dimensions. Sum and rank. Focus on top 20.
| Dimension | What it measures | Weight |
|-----------|------------------|--------|
| **Beat match** | Do they cover your category specifically? | 3x |
| **Reach** | Outlet's audience size + their byline traction | 2x |
| **Engagement** | Do they respond to pitches publicly / on X? | 2x |
| **Recency** | Have they written about a related topic in last 30d? | 1x |
**Tiering:**
- **Tier 1 (8–10):** Personal pitch with original angle. Custom each time.
- **Tier 2 (5–7):** Standard pitch, lightly customized.
- **Tier 3 (below 5):** Skip or pitch only when story is exceptional.
---
## Pitch Templates by Angle
Six structures that work. Pick the one that matches your story.
### 1. Data story
```
Subject: [Specific stat] — [implication]
Hi [name],
I noticed you covered [recent article] — wanted to share data that might
be relevant.
We [analyzed N / surveyed N / tracked N] and found:
• [Stat 1 with surprise factor]
• [Stat 2]
• [Stat 3]
The most interesting pattern: [one-sentence insight].
Full data + methodology here: [link to one-pager, not your homepage]
Happy to share the raw dataset, jump on a call, or connect you with
[customer who's relevant].
[your name + 1-line credential]
```
### 2. Exclusive launch / milestone
```
Subject: Exclusive: [specific milestone] at [company]
Hi [name],
I have an exclusive on [milestone] that I think fits your [beat] coverage.
The story: [one sentence]
Why it matters: [one sentence — for their readers, not for you]
What's new: [the actual news, not the marketing line]
Embargo until [day, time, timezone] — would love to give you first
window. Press kit + assets: [link]
Free to talk [two specific time options].
[your name]
```
### 3. Op-ed / contributed piece
```
Subject: Op-ed pitch: [provocative thesis]
Hi [name],
I read your piece on [recent article] — sharp take on [specific point].
I'd like to pitch a 700-word op-ed: "[Thesis as a headline]"
Core argument:
• [Point 1]
• [Point 2]
• [Point 3 — the surprising one]
Why me: [1 sentence — credential or unique vantage]
Why now: [1 sentence — the news hook]
Can have a draft to you by [date]. Happy to adapt to your house style.
[your name]
```
### 4. Customer story
```
Subject: Customer story for [their beat] — [specific outcome]
Hi [name],
For your [beat] coverage, I have a [customer type] willing to talk on
the record about [specific outcome].
The hook: [customer] [did something specific] and [measurable result].
The interesting part: [the surprising or counterintuitive detail].
Customer details:
• Name: [name, title, company]
• Available: [windows]
• Willing to share: [data points / screenshots / metrics]
Happy to coordinate the intro.
[your name]
```
### 5. Trend piece / connector
```
Subject: Trend forming in [space] — three signals
Hi [name],
Three things in [space] this month that I think connect:
1. [Signal 1 with link]
2. [Signal 2 with link]
3. [Signal 3 — yours, briefly]
The pattern: [one sentence].
This might be early for a piece, but if you're tracking the space I
wanted to flag it. Happy to share data we've collected or connect you
with others seeing the same.
[your name]
```
### 6. Newsjack response
```
Subject: Re: [their article headline] — quick data point
Hi [name],
Saw your piece on [story] this morning — wanted to add a relevant
data point in case you do a follow-up.
[One-sentence stat or insight].
Source: [our data / our customers / our analysis]
Methodology: [one sentence]
Quotable: "[a sentence you'd be comfortable seeing in print]"
If useful for a follow-up, I'm around all day at this number: [phone].
[your name]
```
---
## Subject Lines That Get Opened
Journalists open pitches based on the subject line alone. Rules:
- **Under 50 characters** — mobile preview cuts off
- **Lead with the specific** — "73% of devs deploy to prod on Fridays" beats "New data on developer workflows"
- **Promise a story, not a product** — "Why [trend]" beats "[Company] launches [thing]"
- **Use prefixes that signal value** — "Exclusive:", "Data:", "Op-ed pitch:", "Re: [their article]"
**Test against this question:** would *you* open this in a 200-email inbox?
**Patterns that work:**
- "[Specific stat] — [implication]" — "73% of agents fail this test"
- "Exclusive: [milestone]" — "Exclusive: Anthropic launches AgentOS"
- "Re: [their headline]" — direct response to recent coverage
- "[Provocative thesis]" — "Why VC funding is bad for AI safety"
**Patterns that get deleted:**
- "Press release: [boring]"
- "[Company] announces [thing]"
- "Story idea for you!"
- "Following up on my previous email"
- Any subject line with "innovative," "disruptive," "revolutionary"
---
## Voice and Structure
### Length
**150 words max for the pitch.** If you can't say it in 150 words, you don't know what your story is yet.
### Structure
1. **One-line context** — why you're emailing them specifically (their recent article, their beat)
2. **The story** — what it is, in one sentence
3. **Why it matters to their readers** — not why it matters to you
4. **Proof** — data, customer, quote, link
5. **The ask** — interview, embargo, quote, link
### Voice
- Sound like a person, not a press release
- Reference their actual recent work — proves you read them
- Don't use emoji unless they do
- Don't open with "I hope this finds you well" — burn it
- Don't ask "did you get my email?" follow-ups (see [Follow-up](#embargoes-exclusives-and-follow-up-etiquette))
### Banned vocabulary
Revolutionary, disruptive, game-changing, paradigm shift, leverage, synergy, robust, seamless, holistic, world-class, best-in-class, next-generation, cutting-edge, AI-powered (unless that's the actual differentiation), at-the-end-of-the-day.
---
## Embargoes, Exclusives, and Follow-Up Etiquette
### Embargoes
An embargo is "you can write this story, but don't publish until [time]."
- **Only offer embargoes to journalists you've worked with** or have strong reputations for honoring them
- State the embargo time clearly: day, time, timezone
- If they break embargo, your relationship with them is over
### Exclusives
"Only you get this story" — powerful tool, use sparingly.
- **First-tier outlet only** — exclusives to tier 2/3 outlets waste the lever
- **Be honest about scope** — "exclusive to [outlet] in the US" is fine
- **Have a parallel plan** — what you publish/pitch the next day after the exclusive runs
### Follow-up cadence
- **Day 0** — initial pitch
- **Day 3** — one follow-up if you have new information ("Just talked to [customer] who can join us")
- **Day 7** — final check-in with a fresh hook ("This came out today, still relevant?")
- **After day 7** — let it go. Re-pitch when you have something genuinely new.
**Never:**
- "Bumping this up" / "Did you see my email?"
- Multi-day silent follow-ups with no new value
- Same pitch reformatted
---
## Pitch Killers
Things that instantly disqualify your pitch:
- Wrong name / wrong outlet (autoreplace fail)
- Pitching topics they explicitly don't cover
- Press release attached as PDF (just paste the key bits)
- Long signature with logos and disclaimers
- CC'ing 5 other journalists on the same email
- "Per my last email" energy
- Asking them to sign an NDA before talking
- Pitching a story you can't actually tell (no customer willing to talk, no data ready to share)
---
## Tooling
### Finding journalist contact info
```bash
# Most journalists' emails follow patterns:
# firstname@outlet.com
# firstname.lastname@outlet.com
# flastname@outlet.com
# Use Hunter.io, RocketReach, or just guess and bounce-check
```
### Researching their recent work (browser-driven)
Use `dev-browser` (persistent session, no rate limits) to:
- Open the journalist's outlet author page → scrape last 5 article headlines + dates
- Open their X/Twitter profile → note recent topics
- Open their LinkedIn → confirm current role
Output what you find as:
```
JOURNALIST PROFILE — [name]
Outlet: [name]
Beat: [topics from last 5 articles]
Recent angle: [pattern you noticed]
Recent X activity: [what they're posting]
Score: [X/40 from rubric]
Best pitch angle: [from template library]
Email: [confirmed]
```
### Maintaining the media list
Store in `.agents/media-list.md` (or `.csv` if you prefer). Update monthly — journalists move jobs constantly.
```markdown
## Tier 1 (top 20)
| Name | Outlet | Beat | Last contact | Last coverage | Email | Score |
|------|--------|------|--------------|---------------|-------|-------|
| ... | ... | ... | 2026-05-15 | none yet | ... | 9/10 |
```
### Pitch tracking
Track in a simple spreadsheet:
- Date sent
- Subject line
- Journalist
- Outlet
- Response (open / reply / pass / coverage)
- What they said
After 30 pitches, you'll see which subject patterns and which angles work for you specifically.
@@ -0,0 +1,207 @@
# Media Outlets — Where to Pitch
A curated, opinionated list of *where* to pitch for software/SaaS PR. This is the media-outlet slice of resources like submit.co — the journalist-driven half. For startup/SaaS/AI directories (Product Hunt, BetaList, Futurepedia, etc.), use the separate `directory-submissions` skill — different intent, different audience.
## How to use this list
- **Don't pitch a publication. Pitch a journalist at that publication.** See [journalist-pitching.md](journalist-pitching.md) for the discovery workflow.
- **Tier signals quality, not effort** — a small tier-3 outlet might be perfect for your niche
- **Submission/tip URLs are listed where they exist** — but a journalist's email beats a tip form every time
- **This list ages fast** — verify the outlet still exists and the journalist is still there before pitching
---
## Tech & Startup Press (Tier 1)
The big names. High bar to clear, high payoff when you do. Pitch the specific reporter, not the tip line.
| Outlet | Best for | Tip URL |
|--------|---------|---------|
| **TechCrunch** | Funding, product launches, startup news | techcrunch.com/got-a-tip/ |
| **The Verge** | Consumer tech, product reviews, policy | theverge.com/contact |
| **Wired** | Long-form tech, culture, business | wired.com/about/feedback |
| **Fast Company** | Innovation, design, business strategy | fastcompany.com/contact-us |
| **VentureBeat** | AI, enterprise tech, gaming | venturebeat.com/contribute |
| **Ars Technica** | Deep tech, science, policy | arstechnica.com/contact-us |
| **The Information** | Subscription-gated, scoops on tech industry | theinformation.com/about |
| **Bloomberg / Reuters** | Business, finance, big-picture stories | bloomberg.com/feedback |
| **WSJ Tech** | Enterprise, business angle | wsj.com/tips |
| **NYT Tech** | Mainstream tech, culture | nytimes.com/tips |
---
## SaaS & B2B (Tier 1–2)
Lower-profile than the consumer tech outlets but often higher ROI for B2B SaaS.
| Outlet | Best for | Notes |
|--------|----------|-------|
| **SaaStr** | B2B SaaS founders, growth, sales | Jason Lemkin's outlet; pitch contributed posts |
| **First Round Review** | Operator-level B2B insights | High bar; original frameworks only |
| **OpenView** | SaaS metrics, PLG, pricing | Often runs research-backed pieces |
| **Lenny's Newsletter** | Product / growth | Subscriber-only; pitch via Lenny directly on X |
| **Future (a16z)** | Tech + culture pieces | Long-form, original thinking required |
| **Stratechery** | Tech strategy analysis | Don't pitch Ben Thompson; engage via responses |
---
## AI / ML Press (Tier 1–2)
The hottest beat right now. Reporters here are inundated — your angle has to be sharp.
| Outlet | Best for | Notes |
|--------|----------|-------|
| **The Decoder** | AI news, fast-turn | Daily AI news cycle |
| **Import AI** (Jack Clark) | Weekly AI newsletter | Pitch research-backed angles |
| **The Batch** (Andrew Ng) | AI industry analysis | Submitted by deeplearning.ai team |
| **MIT Technology Review** | AI policy, capability, ethics | Higher bar, slower cycle |
| **Hugging Face blog** | Open-source AI tools | Contributed posts welcome |
| **Latent Space** | Practitioner-focused AI/ML | Podcast + newsletter |
---
## Developer & DevTools Press
Where to pitch if your audience is engineers.
| Outlet | Best for | Notes |
|--------|----------|-------|
| **The New Stack** | DevTools, infra, cloud-native | Active contributor program |
| **InfoQ** | Enterprise dev, software architecture | Long-form technical pieces |
| **DEV.to** | Self-published, community-driven | Build credibility before pitching |
| **Hacker Noon** | Tech blogging platform | Easy to publish but low signal |
| **Console** | DevTools newsletter | Curated weekly; submit projects |
| **DevTools FM** | Podcast | Pitch as guest |
---
## Business & Marketing Press
For pitching the business / marketing angle of your story.
| Outlet | Best for | Notes |
|--------|----------|-------|
| **Inc.** | Founder stories, business advice | Contributor program available |
| **Entrepreneur** | Small business, growth | Volume publisher; quality varies |
| **HBR.org** | Original research, frameworks | High bar; long lead time |
| **MarketingProfs** | B2B marketing | Contributor-friendly |
| **Marketing Brew (Morning Brew)** | Daily marketing newsletter | Reporter-driven, pitch directly |
| **Marketing Land / Search Engine Journal** | SEO, SEM, channels | Niche but high-intent audience |
| **Reforge** | Growth, product, retention | Original framework required |
---
## Newsletters (Reporter-Driven)
Newsletters are increasingly the most valuable PR placement — small audiences, but high-intent.
| Newsletter | Audience | How to pitch |
|-----------|---------|--------------|
| **Lenny's Newsletter** | Product/growth, ~600k readers | DM Lenny on X with sharp angle |
| **The Pragmatic Engineer** (Gergely Orosz) | Software eng leaders | Pitch via email; original engineering insights |
| **The Generalist** (Mario Gabriele) | Tech business analysis | Pitch via email; deep angles |
| **Stratechery** (Ben Thompson) | Tech strategy | Don't pitch; engage in replies |
| **Newcomer** (Eric Newcomer) | Tech business + scoops | Tips welcome via email |
| **Platformer** (Casey Newton) | Tech + policy | Pitch via Substack |
| **Big Technology** (Alex Kantrowitz) | Big Tech analysis | Pitch via Substack |
| **Not Boring** (Packy McCormick) | Tech + culture | Tough to crack; original takes only |
**For B2B SaaS:**
- **SaaStr Daily**
- **Demand Curve**
- **Growth Unhinged** (Kyle Poyar)
- **Trends.vc**
**For AI:**
- **Import AI** (Jack Clark)
- **The Batch** (Andrew Ng)
- **The Algorithm** (MIT Tech Review)
- **Interconnects** (Nathan Lambert)
- **AI Tidbits**
---
## Podcasts
A podcast appearance is often higher leverage than a press hit — longer engagement, evergreen replay, audience trust transfer.
### Top SaaS / startup podcasts
- **Lenny's Podcast** — product/growth
- **My First Million** — founder stories, business ideas
- **The Twenty Minute VC** — funding angle
- **SaaStr Podcast** — B2B SaaS
- **Acquired** — deep-dive company stories (don't pitch unless you're a unicorn)
- **The All-In Podcast** — broad tech/business (very hard to get on)
### Top AI podcasts
- **No Priors** (Sarah Guo, Elad Gil)
- **Latent Space**
- **Practical AI**
- **The TWIML AI Podcast**
- **The Cognitive Revolution**
### Top dev / engineering podcasts
- **The Changelog**
- **Software Engineering Daily**
- **DevTools FM**
### How to pitch a podcast
1. **Listen to 3 episodes** — non-negotiable
2. **Find the host's preferred channel** (X DM, email, guest form)
3. **Pitch a topic, not yourself** — "I'd love to come on and talk about [specific angle]" not "I'd love to be a guest"
4. **Bring evidence** — links to other appearances, your unique angle, what listeners will learn
5. **Make it easy** — bio, headshot, suggested questions in the pitch
---
## Industry / Vertical Press
Don't overlook trade press — smaller audience, much higher intent.
| Vertical | Outlets to investigate |
|----------|----------------------|
| **Marketing** | Adweek, Marketing Brew, AdAge, Search Engine Land |
| **Sales** | Sales Hacker, Modern Sales Pros |
| **HR / People Ops** | HR Brew, SHRM, HR Dive |
| **Finance / Fintech** | The Block, CoinDesk, Finextra |
| **Healthcare tech** | STAT, MobiHealthNews, Healthcare IT News |
| **Education tech** | EdSurge, EdScoop |
| **Real estate tech** | Inman, The Real Deal |
| **Legal tech** | Above the Law, Law360 |
| **Climate tech** | Heatmap, Canary Media, Latitude Media |
| **Devtools** | The New Stack, InfoQ, DevOps.com |
For your specific vertical: Google `"top publications" + "[your industry]"` and run the same scoring exercise from [journalist-pitching.md](journalist-pitching.md).
---
## Regional / Local
If your company has a regional angle (HQ location, customer concentration, government contract), local press is underrated.
- **Local business journals** — Bizjournals network covers 40+ US cities
- **Local NPR affiliates** — high-quality, business angle welcomed
- **Local TV business segments** — high reach, easy to get
- **State / regional tech news** — e.g., Built In (Chicago, Austin, etc.), TechBuzz (Utah)
---
## What's NOT On This List (And Why)
- **Product Hunt, BetaList, Indie Hackers** — these are directories, not press. Use the `directory-submissions` skill.
- **Press release wires** (PRNewswire, BusinessWire, GlobeNewswire) — overpriced for early-stage; journalists ignore them. Skip until you have IR / SEC requirements.
- **"As featured in" badge mills** — paid "media coverage" services. Worthless and damaging.
- **Random "guest post" SEO link networks** — Google penalizes these. Don't.
---
## Maintaining This List
This list will go stale. Recommended cadence:
- **Quarterly:** verify your tier-1 contacts are still at the outlet
- **Monthly:** add new outlets/newsletters relevant to your category
- **Per pitch:** confirm the journalist is still there before sending (check X / LinkedIn for "joined [new place]")
Store your live, working version in `.agents/media-list.md` (per [journalist-pitching.md](journalist-pitching.md)).
@@ -0,0 +1,218 @@
# Newsjacking — Reactive PR Workflow
Injecting your POV into a story that's already trending. Done well: free distribution off a wave of attention. Done badly: cringe at best, brand damage at worst.
## Contents
- When newsjacking works (and when it doesn't)
- The detect → score → angle → pitch loop
- Newsworthiness scoring rubric
- Story angle library
- Speed: the only thing that matters
- Sources & tooling
- Failure modes
---
## When Newsjacking Works
- **Tech/regulatory news in your category** — new law, new platform launch, competitor pivot, big acquisition
- **Industry data drops** — a major report drops, you have a sharper take or contradicting data
- **Public conversation** — a debate or controversy where your expertise is genuinely relevant
- **Seasonal/cyclical moments** — earnings season, year-end reviews, conference weeks
## When to Skip
- **Tragedies, accidents, deaths** — no exceptions. Don't.
- **Politically charged stories** unless your brand explicitly takes political stances
- **You have no genuine expertise** in the area
- **The window is already closed** — if a story is 48h+ old and you weren't first, you're late
- **The angle is "we have a product for this"** — that's marketing, not journalism
---
## The Loop
A repeatable workflow Claude can run on demand or daily.
1. **Detect** — surface trending stories in your category (see [Sources & Tooling](#sources--tooling))
2. **Score** — apply the [newsworthiness rubric](#newsworthiness-scoring-rubric); drop anything below threshold
3. **Angle** — generate 2–3 angles per story using the [angle library](#story-angle-library)
4. **Validate** — sanity-check: do you actually have the expertise/data to back this angle?
5. **Pitch** — draft a tight pitch to 3–5 journalists who cover this beat (see [journalist-pitching.md](journalist-pitching.md))
6. **Post** — also publish on your blog, LinkedIn, X — it builds the trail journalists check before quoting you
Output format Claude should produce:
```
NEWSJACK CANDIDATE — 2026-06-10
Story: "EU passes AI Act amendment requiring agent registration"
Source: TechCrunch, 3h ago
Score: 8/10 (high relevance, fresh, you have proprietary data)
Angles:
1. Data hot take: "Our analysis of 12,000 agent deployments shows 73% would fail this requirement"
2. Contrarian: "Why the registration rule will hurt safety, not improve it"
3. Customer story: "How [customer] is preparing — interview offer"
Recommended: #1 (you have unique data, strongest hook)
Pitch draft: [see journalist-pitching.md for template]
Target journalists: [list with rationale]
```
---
## Newsworthiness Scoring Rubric
Score each candidate 1–10 on five dimensions, multiply by the weight, then sum. Max possible: 80 (10 × the 8x weight total).
| Dimension | What it measures | Weight |
|-----------|------------------|--------|
| **Timeliness** | Story <24h old? Window still open? | 2x |
| **Relevance** | Genuinely in your expertise area? | 2x |
| **Angle uniqueness** | Can you say something no one else is saying? | 2x |
| **Authority** | Do you have data, customers, or experience to back it? | 1x |
| **Reach potential** | Will this story keep growing or has it peaked? | 1x |
**Threshold:** weighted total ≥ 50/80. Below that, skip.
**Auto-disqualify if:**
- The story is about something tragic
- Your angle is "I disagree" with nothing to back it
- You haven't actually formed an opinion — you just want to be quoted
---
## Story Angle Library
Use these templates to generate angles fast.
### 1. Data hot take
*"We analyzed [N] [things] after [event]. Here's what we found."*
Best when you have proprietary data. The journalist gets a stat, you get the citation.
### 2. Contrarian
*"Everyone says [popular take]. Here's why they're wrong."*
Best when you can defend the position with specifics. Weak when it's just contrarianism for attention.
### 3. "We predicted this"
*"Six months ago we wrote [thing] — here's what's happening now and what's next."*
Best when you actually did predict it. Lethal to your credibility if you didn't.
### 4. Customer impact
*"Here's a [customer type] who's directly affected. We can put you in touch."*
Best for B2B. Reporters love named customers willing to talk.
### 5. Insider explainer
*"This story is complicated. Here's what's actually happening."*
Best when most coverage is missing nuance. You're not arguing — you're educating.
### 6. Trend connector
*"This isn't isolated — it's part of a bigger shift we're seeing in [pattern]."*
Best when you have several data points or examples to connect.
### 7. Founder POV
*"As someone who's built in this space for [X years], here's the part most people are missing."*
Best for opinion pieces / op-eds. Weak as a soundbite pitch.
---
## Speed: The Only Thing That Matters
Newsjacking decays fast. Approximate windows:
| Story type | Effective window |
|-----------|------------------|
| Breaking tech news | 4–12 hours |
| Major regulation / policy | 24–48 hours |
| Industry report / data drop | 24–72 hours |
| Conference announcement | Same day |
| Acquisition / funding news | 12–24 hours |
**Implication:** if you can't draft and send within the window, don't bother. Set up the loop so detection → pitch takes <2 hours.
---
## Sources & Tooling
Reuses tooling from the `social` skill's listening workflow. Same install: `brew install jq`.
### Google News RSS (no auth)
```bash
# Replace QUERY with topic (use + for spaces, %22 for quotes)
curl -s "https://news.google.com/rss/search?q=QUERY&hl=en-US&gl=US&ceid=US:en" \
| xmllint --xpath "//item[position()<11]" - 2>/dev/null
```
### Hacker News (Algolia) for tech stories
```bash
SINCE=$(($(date +%s) - 86400))
curl -s "https://hn.algolia.com/api/v1/search_by_date?query=QUERY&tags=story&numericFilters=created_at_i>${SINCE}" \
| jq '.hits[] | {title, url, points, num_comments, created_at, hn_url: ("https://news.ycombinator.com/item?id="+.objectID)}'
```
### Reddit (for category-specific subs)
```bash
curl -s -A "newsjack/1.0" \
"https://www.reddit.com/r/SUBREDDIT/top.json?t=day&limit=15" \
| jq '.data.children[].data | {title, url, score, num_comments, created_utc}'
```
### Journalist research (browser-driven)
For finding *which* journalists are covering the story right now:
- **dev-browser** → Google News search for the story → click through to articles → note the bylines
- Then go to those journalists' X / LinkedIn / Muck Rack profile to confirm beat and recent coverage
See also [journalist-pitching.md](journalist-pitching.md) for the full discovery workflow.
### Source list
For repeatable monitoring, add a "Newsjacking topics" section to `.agents/listening-sources.md` (template in the `social` skill's references):
```markdown
## Newsjacking topics (Google News RSS)
- "AI agent regulation"
- "[your category] funding"
- "[your competitors] OR [adjacent competitors]"
## Industry data drops (RSS / manual)
- Pitchbook reports
- a16z state of [industry] reports
- [your category] benchmark reports
```
---
## Failure Modes
Things that have ended careers and brands.
- **Tragedy-jacking** — Oreo's 2013 Super Bowl tweet worked. Most attempts since have not. Wartime, disasters, deaths: don't.
- **The forced fit** — "Here's our take on [trending story] — it's actually about [our product]." Journalists see through this instantly.
- **The empty take** — pitching "we have an opinion" without specifics. Journalists need a quote-worthy line, not "we're closely watching this."
- **Speed without judgment** — being first with a bad take is worse than being late with a good one. The 30-minute "is this brand-appropriate?" gut check exists for a reason.
- **Pitching the same angle to 50 journalists** — they talk. Get caught once, lose the relationships.
- **No follow-through** — pitch goes out, journalist responds in 20 minutes, founder takes 6 hours to reply. Story moves on.
---
## Companion Practice: The Public Trail
Every newsjack pitch is stronger if the journalist can find evidence you've been thinking about this publicly. Before pitching:
1. Publish a short post (blog, LinkedIn, X thread) with your take
2. Reference it in the pitch ("more thinking here: [link]")
3. This signals you're not opportunistic — you're an actual voice in the space
If you don't have time to publish, you're probably not ready to pitch.
@@ -0,0 +1,188 @@
# Press Request Platforms — Inbound PR
Journalists posting "I need a source for X" — you respond, sometimes you get quoted, sometimes you don't. The cheapest PR play available, but only if you treat it seriously.
## Contents
- The major platforms
- Daily triage workflow
- Response template
- What makes a response get selected
- What kills a response
- ROI reality check
---
## The Major Platforms
| Platform | What it is | Cost | Quality |
|----------|-----------|------|---------|
| **[Connectively](https://www.connectively.us)** (formerly HARO) | Daily email digest of journalist queries | Free tier; paid for filters | Mixed — high volume, lots of noise |
| **[Qwoted](https://www.qwoted.com)** | Web app with journalist requests | Free; paid for outreach | Good — better-quality outlets |
| **[Featured](https://featured.com)** | Web app, expert profiles, journalist requests | Free tier; paid pro | Good for thought-leadership snippets |
| **[Help A B2B Writer](https://helpab2bwriter.com)** | Twice-weekly email of B2B queries | Free | High — B2B-focused, low spam |
| **[SourceBottle](https://www.sourcebottle.com)** | Australia-focused but global queries | Free | Variable |
| **[Terkel](https://terkel.io)** | Roundup-style ("we asked 50 experts…") | Free | Volume-heavy, low effort |
| **[JournoRequests](https://twitter.com/journorequests)** | X account aggregating tweets | Free | UK-skewed, real-time |
| **#JournoRequest** (X hashtag) | Live journalist requests | Free | Real-time, fast-moving |
**Recommended starter set:** Connectively + Qwoted + Help A B2B Writer + monitoring `#JournoRequest` on X.
---
## Daily Triage Workflow
These platforms generate volume. Treat it like email triage — fast pass, deep response on the rare matches.
### Step 1 — Filter (5 min)
For each digest / request feed:
- Drop everything where you don't have **direct experience or data**
- Drop everything from outlets your ICP doesn't read
- Drop everything with a deadline you can't meet
- Keep only requests where you can give a **complete, named, on-the-record answer**
Realistic conversion: 50 daily requests → 2–4 worth answering.
### Step 2 — Deep response (15 min per request)
For each keeper:
- Read the request 3 times — what's the *actual* angle?
- Look up the journalist if possible — recent coverage, beat
- Write a custom response (see [template](#response-template))
- Send within their stated deadline (early > late)
### Step 3 — Log
Track in a spreadsheet:
- Date
- Platform
- Journalist + outlet
- Topic
- Response sent (yes/no)
- Outcome (no response / passed / quoted / linked)
After 30 responses, you'll see which topics/platforms convert.
---
## Response Template
Keep responses under 200 words. Journalists are scanning 50+ replies for one quote.
```
Hi [name],
Quick response to your request about [topic].
[Specific credential — 1 sentence. "Built X for 5 years" / "Led marketing at Y" / "Have analyzed N companies in space"]
The most important thing about [topic]: [your actual point in 2 sentences].
[A specific example, story, or data point — this is what gets quoted.]
[If applicable: a contrarian or surprising angle that differentiates from typical answers.]
Happy to expand on any of this, share data, or be quoted directly.
Feel free to use this attribution:
[Your name], [your title], [your company]
Contact for follow-up: [email + phone]
```
**Note the structure:**
1. One-sentence intro
2. One-sentence credential
3. Two-sentence answer
4. Specific example (the quotable part)
5. Optional: differentiator
6. Clear offer
7. Pre-written attribution (saves them 30 seconds)
8. Contact info
---
## What Makes a Response Get Selected
After analyzing hundreds of quoted responses, the patterns:
### Quotable specificity
**Bad:** "Companies should focus on customer experience."
**Good:** "When we A/B tested 47 onboarding flows, the version with a 30-second video at step 3 increased activation by 41%."
The good version is a quote. The bad version is filler.
### Concrete credential
**Bad:** "As a marketing expert..."
**Good:** "I've run growth at three Series B SaaS companies, all in B2B sales tooling."
Specificity beats title-stacking.
### Story over advice
**Bad:** "It's important to track the right metrics."
**Good:** "We almost shut down because we were optimizing for MRR when our real problem was activation. Once we switched to tracking 7-day activation, everything else followed."
Stories make articles. Advice makes filler.
### Pre-formatted for their workflow
- Pre-written attribution
- Multiple quotable lines (let them pick)
- High-res headshot link (don't attach)
- One-line company description
### Time match
**Most quotes come from responses sent in the first 6 hours.** After 24 hours, your chances drop sharply. Treat deadlines as if they're 24h earlier than stated.
---
## What Kills a Response
- **Pitching your product** when they asked for expert commentary
- **Generic advice** that could come from any expert
- **Multiple "experts" from your company** responding to the same request (looks coordinated, often is)
- **Hiring a PR firm to spam responses** — journalists smell it
- **Demanding a link back** to your site — most can't promise links
- **Ignoring the deadline** by 1+ days
- **Long bio sections** before the actual answer
- **Asking to "see the article before publication"** — you don't get to do that
- **Asking what other experts said** so you can differentiate — they won't tell you
---
## ROI Reality Check
Most teams overinvest in these platforms because they're cheap. Be honest:
| Effort | Realistic outcome (90 days) |
|--------|----------------------------|
| 5 hr/week, custom responses | 3–10 quoted placements |
| 1 hr/week, template responses | 0–2 placements |
| Outsourced to PR firm | Lots of submissions, few quotes |
**A quote in a tier-1 outlet is worth:**
- A backlink (DR depends on outlet)
- A sales-collateral asset ("As featured in...")
- AI-citation surface area
- Brand legitimacy in the abstract
**A quote in a tier-3 outlet is worth:**
- A backlink, often nofollow
- Maybe an Instagram screenshot
**Decision rule:** if you can sustain 5 hr/week of quality responses for 90 days, this is worth it. If you can only do 1 hr/week, skip it and invest in [proactive pitching](journalist-pitching.md) instead.
---
## Setup Checklist
Before you start responding:
- [ ] Press page exists and is current (see main SKILL.md)
- [ ] One-line credential is written and rehearsed
- [ ] Headshot is high-res and at a public URL
- [ ] You have 3–5 specific stories / data points ready to deploy
- [ ] You've decided which 2–3 platforms to use (don't try all 7)
- [ ] You've blocked a daily 20-min window for triage
- [ ] You're logging responses in a tracker
Without these, you're spamming and wasting their time and yours.
+4 -2
View File
@@ -1,8 +1,8 @@
---
name: social
description: "When the user wants help creating, scheduling, or optimizing social media content for LinkedIn, Twitter/X, Instagram, TikTok, Facebook, or other platforms. Also use when the user mentions 'LinkedIn post,' 'Twitter thread,' 'social media,' 'content calendar,' 'social scheduling,' 'engagement,' 'viral content,' 'what should I post,' 'repurpose this content,' 'tweet ideas,' 'LinkedIn carousel,' 'social media strategy,' 'grow my following,' 'TikTok video,' 'Reels,' 'Shorts,' 'video script,' 'video hook,' 'short-form video,' or 'create a reel.' Use this for social media content creation, repurposing, scheduling, and short-form video scripting. For broader content strategy, see content-strategy. For paid video ads, see ad-creative."
description: "When the user wants help creating, scheduling, or optimizing social media content for LinkedIn, Twitter/X, Instagram, TikTok, Facebook, or other platforms, or wants to do social listening and engagement triage. Also use when the user mentions 'LinkedIn post,' 'Twitter thread,' 'social media,' 'content calendar,' 'social scheduling,' 'engagement,' 'viral content,' 'what should I post,' 'repurpose this content,' 'tweet ideas,' 'LinkedIn carousel,' 'social media strategy,' 'grow my following,' 'TikTok video,' 'Reels,' 'Shorts,' 'video script,' 'video hook,' 'short-form video,' 'create a reel,' 'social listening,' 'brand mentions,' 'competitor monitoring,' 'top posts to comment on,' or 'find people asking for.' Use this for social media content creation, repurposing, scheduling, short-form video scripting, and social listening. For broader content strategy, see content-strategy. For paid ads, see ad-creative. For earned media, see public-relations."
metadata:
version: 2.0.0
version: 2.1.0
---
# Social Content
@@ -211,6 +211,8 @@ Extract "content atoms" — self-contained moments from any long-form content th
3. Share/repost with added insight (5 min)
4. Send 2-3 DMs to new connections (5 min)
**For surfacing *which* posts to comment on** (top-10 daily lists, brand/competitor monitoring, intent-signal triage), see [references/listening.md](references/listening.md). Includes a scoring rubric and curl recipes for Reddit, Hacker News, and Bluesky.
### Quality Comments
- Add new insight, not just "Great post!"
@@ -0,0 +1,123 @@
# Listening Sources — Template
Copy this file to `.agents/listening-sources.md` in your project (or `.claude/listening-sources.md`) and fill in the brackets. Claude reads it when running the [listening workflow](listening.md).
Delete sections you don't use. Keep this short and current — stale sources are worse than no sources.
---
## What We're Listening For
**Brand / product:** [Your product name]
**Category:** [e.g., "AI writing assistant", "Postgres GUI"]
**Goal:** [e.g., "find people switching from Notion", "engage with B2B SaaS founders 50-200 employees"]
## ICP (for scoring)
Used by the [scoring rubric](listening.md#scoring-rubric) to judge ICP fit.
- **Role:** [e.g., "founder, head of marketing, marketing ops lead"]
- **Company stage:** [e.g., "seed to Series B SaaS, 10-200 employees"]
- **Industry:** [e.g., "B2B SaaS, infra, devtools"]
- **Signals they're a fit:** [e.g., "writes about GTM, runs paid ads, recently raised"]
---
## Target Accounts
Engage with **every** post from these accounts when relevant. Keep this list to 20-50 max.
### LinkedIn (browser-driven — use dev-browser to view feed)
- [Name] — `linkedin.com/in/handle`
- [Name] — `linkedin.com/in/handle`
### X / Twitter (browser-driven)
- [@handle]
- [@handle]
### Reddit
- u/[username]
- u/[username]
### Bluesky
- [handle.bsky.social]
### Blogs / Newsletters (RSS)
- [Name] — `https://example.com/feed/`
- [Name] — `https://example.substack.com/feed`
### YouTube channels (RSS)
- [Name] — channel ID `UCxxxxxxxx`
---
## Keywords (intent signals)
Search across all platforms. Claude runs these through Reddit, HN, Bluesky on the [daily loop](listening.md#the-daily-triage-loop).
### High-intent (someone shopping or switching)
- `"alternative to [competitor]"`
- `"looking for a [category] tool"`
- `"recommend a [category]"`
- `"switching from [competitor]"`
- `"frustrated with [competitor]"`
### Problem signals (someone in pain)
- `"[category] is so [bad/hard/expensive]"`
- `"why is [category] [problem]"`
- `"hate [pain point]"`
### Brand mentions
- `"[your brand]"`
- `"[your brand misspelling]"`
- `"[your domain]"`
### Competitor mentions (monitor for switching language)
- `"[competitor 1]"`
- `"[competitor 2]"`
---
## Subreddits
Pulled via Reddit JSON API on the daily loop.
- r/SaaS
- r/Entrepreneur
- r/[your niche, e.g., "marketing", "devtools"]
- r/[adjacent community]
---
## Saved Searches (manual / browser-driven)
URLs Claude opens via dev-browser to scan.
### LinkedIn Sales Navigator
- [Search name] — `https://linkedin.com/sales/search/people?...`
### LinkedIn (regular)
- Posts hashtag — `https://linkedin.com/feed/hashtag/yourtopic/`
### X advanced search
- [Search name] — `https://x.com/search?q=...&f=live`
---
## Do Not Engage
Save yourself the regret.
- Accounts known for bad-faith dunking: [@handle], [@handle]
- Blocked brands / competitors who'll screenshot: [list]
- Topics to avoid: [politics, [your founder's hot takes], etc.]
---
## Notes for Claude
- When asked for "today's top 10," output in the format defined in [listening.md](listening.md#the-daily-triage-loop)
- For LinkedIn and X, use dev-browser with the persistent session (user is logged in)
- For everything else, use the curl recipes in [listening.md](listening.md#sources--light-tooling-curl-recipes)
- Default lookback: 24h. User can override.
- Always ask before posting — output drafts, user approves and posts manually
+283
View File
@@ -0,0 +1,283 @@
# Social Listening & Engagement Triage
How to surface the right posts to engage with each day — instead of randomly scrolling. The goal is a short, scorable list ("here are your top 10 posts to comment on") rather than an open feed.
## Contents
- When to use this
- The daily triage loop
- Scoring rubric
- Comment quality tiers
- Sources & light tooling (curl recipes)
- Per-platform notes
- Common workflows
---
## When to Use This
Use listening when the goal is **commenting and relationships**, not posting. Typical asks:
- "Give me the top 10 posts I should comment on today"
- "Who's complaining about [competitor] right now?"
- "Find people asking for a tool like mine"
- "Surface posts from my 20 target accounts in the last 24h"
- "What's the conversation around [topic] this week?"
If the user wants to **create** content, use the rest of the social skill. Listening feeds creation (it surfaces angles, language, objections), but the output is different.
---
## The Daily Triage Loop
A repeatable 20-minute loop the user (or you, on their behalf) can run each morning.
1. **Pull** — fetch new posts from defined sources (target accounts, keywords, subreddits, hashtags). See [tooling](#sources--light-tooling-curl-recipes).
2. **Filter** — drop anything older than 24h, low signal, or off-topic.
3. **Score** — apply the [rubric](#scoring-rubric). Keep top 10.
4. **Draft** — for each, draft a comment matched to the post's tier.
5. **Post** — user reviews, edits, posts. Mark which actually went live.
6. **Log** — track what you commented on and what got replies. This is your engagement loop dataset.
Output format Claude should produce:
```
TOP 10 POSTS — 2026-06-05
1. [Score 9/10] @author — LinkedIn — 2h ago
"We just rolled out X and the team is loving it…"
Why: ICP fit (B2B SaaS, 50–200 employees), buying-intent signal
Suggested comment: [draft]
Link: https://…
```
---
## Scoring Rubric
Score each post 1–10 across five dimensions, then sum and rank.
| Dimension | What it measures | Weight |
|-----------|------------------|--------|
| **ICP fit** | Is the author your target customer / influencer? | 2x |
| **Intent signal** | Are they expressing a problem, asking, or shopping? | 2x |
| **Reach potential** | Is the post getting traction (likes/comments rising)? | 1x |
| **Comment opportunity** | Can you say something genuinely useful, not generic? | 2x |
| **Recency** | Posted in last 1–4h (early comments win, especially on LinkedIn) | 1x |
**Intent signal examples (high-value):**
- "Looking for a tool that does X"
- "Why is [category] so painful?"
- "We just switched from [competitor] because…"
- "Anyone use [competitor] — is it worth it?"
- A complaint about a known competitor
**Drop if any of these are true:**
- Author isn't ICP and isn't an influencer
- Post is >24h old and already has 50+ comments (your comment buries)
- Generic motivational/AI-slop post
- Self-promotion thread where comments don't get reach
- You can't add anything beyond "Great post!"
---
## Comment Quality Tiers
Match the comment to the post. Don't waste a tier-1 draft on a tier-3 opportunity.
**Tier 1 — Relationship builder (target accounts, ICP, high intent)**
- Add a specific insight or counter-example
- Reference your own experience with specifics (numbers, names, outcomes)
- Ask a thoughtful follow-up that invites a reply
- Length: 2–4 sentences, no link
**Tier 2 — Visibility play (high-reach post, adjacent topic)**
- Add one sharp insight in one sentence
- Pattern: "Agreed — and the part most miss is [X]"
- Length: 1–2 sentences
**Tier 3 — Light touch (relationship maintenance)**
- Specific reaction, not "Love this"
- Quote a specific line and react to it
- Length: 1 sentence
**Never:** "Great post!", emoji-only, "+1", LinkedIn-isms like "This is gold 🔥"
---
## Sources & Light Tooling (curl recipes)
These are public JSON endpoints — no auth needed. Run them from bash, pipe to `jq`, and Claude can parse the output to score and draft comments.
**Requires:** `jq` (most recipes) and `xmllint` (RSS only). Install once:
```bash
# macOS
brew install jq
# xmllint ships with macOS; on Linux: apt install libxml2-utils
```
### Reddit (free, scriptable)
**New posts in a subreddit:**
```bash
curl -s -A "listening/1.0" \
"https://www.reddit.com/r/SaaS/new.json?limit=25" \
| jq '.data.children[].data | {title, author, url: ("https://reddit.com"+.permalink), score, num_comments, created_utc, selftext: (.selftext | .[0:300])}'
```
**Search across Reddit by keyword (last day, sorted new):**
```bash
curl -s -A "listening/1.0" \
"https://www.reddit.com/search.json?q=KEYWORD&sort=new&t=day&limit=25" \
| jq '.data.children[].data | {subreddit, title, url: ("https://reddit.com"+.permalink), author, score, created_utc}'
```
Swap `KEYWORD` for things like `"alternative to notion"`, `"recommend a crm"`, your competitor names, or your own brand for mentions. Use quotes around multi-word phrases.
### Hacker News (Algolia search)
**Recent stories mentioning a keyword (last 24h):**
```bash
SINCE=$(($(date +%s) - 86400))
curl -s "https://hn.algolia.com/api/v1/search_by_date?query=KEYWORD&tags=story&numericFilters=created_at_i>${SINCE}" \
| jq '.hits[] | {title, url, author, points, num_comments, created_at, story_id: .objectID, hn_url: ("https://news.ycombinator.com/item?id="+.objectID)}'
```
**Recent comments mentioning a keyword:**
```bash
curl -s "https://hn.algolia.com/api/v1/search_by_date?query=KEYWORD&tags=comment&numericFilters=created_at_i>${SINCE}" \
| jq '.hits[] | {author, comment_text, story_title, hn_url: ("https://news.ycombinator.com/item?id="+.objectID)}'
```
### Bluesky (free, public API)
**Search posts by keyword:**
```bash
curl -s "https://public.api.bsky.app/xrpc/app.bsky.feed.searchPosts?q=KEYWORD&limit=25&sort=latest" \
| jq '.posts[] | {author: .author.handle, text: .record.text, likes: .likeCount, replies: .replyCount, url: ("https://bsky.app/profile/"+.author.handle+"/post/"+(.uri | split("/") | last))}'
```
### RSS for blogs, podcasts, YouTube channels
For target accounts that publish to RSS (most blogs, all YouTube channels):
```bash
# YouTube channel feed (replace CHANNEL_ID)
curl -s "https://www.youtube.com/feeds/videos.xml?channel_id=CHANNEL_ID"
# Generic blog feed
curl -s "https://example.com/feed/" | xmllint --xpath "//item[position()<6]" - 2>/dev/null
```
### LinkedIn & X — use the browser
LinkedIn and X don't expose useful public APIs, but you can drive a real browser session. **dev-browser** (MCP, already in the global setup) and **Playwright** both maintain persistent state — log in once, the session stays alive, Claude can navigate the authenticated feed.
**dev-browser workflow (preferred — already wired up):**
1. User logs into LinkedIn / X once in the dev-browser session
2. Claude navigates to a target URL (feed, profile, saved search, hashtag)
3. Claude reads the accessibility tree / page text, extracts posts
4. Claude scores using the [rubric](#scoring-rubric) and drafts comments
5. User reviews and posts manually (don't auto-post — high-stakes, bot detection risk)
**Useful URLs to feed dev-browser:**
| URL pattern | What it shows |
|-------------|---------------|
| `linkedin.com/in/HANDLE/recent-activity/all/` | A target account's recent posts |
| `linkedin.com/feed/hashtag/TOPIC/` | Hashtag feed |
| `linkedin.com/feed/` | Your main feed (algorithmic — less useful for triage) |
| `x.com/HANDLE` | A target account's profile |
| `x.com/search?q=QUERY&f=live` | Real-time search (use `f=live` for chronological) |
| `x.com/i/lists/LIST_ID` | A curated list — best for target accounts |
**Tips:**
- On X, build a private list of target accounts and use the list URL. Far cleaner than the algorithmic feed.
- LinkedIn's `/recent-activity/all/` URL is the cleanest way to see one person's posts without the algorithm.
- For both platforms, scroll programmatically (dev-browser supports it) to load more posts before extracting.
**Paid alternatives if you don't want to drive a browser:**
| Platform | Tools |
|----------|-------|
| LinkedIn | Sales Navigator (saved searches), Taplio (engagement) |
| X | TweetDeck/X Pro (saved columns), Typefully, Taplio, Tweet Hunter |
**Still closed (no good path):**
- Instagram & TikTok — closed APIs, browser automation is detectable and risky. Use native saved searches / hashtag follows.
---
## Per-Platform Notes
### LinkedIn
- **Browser-driven** (dev-browser with persistent session) — see [LinkedIn & X — use the browser](#linkedin--x--use-the-browser)
- **First-hour comments matter most** — algorithm weights early engagement heavily. Prioritize posts <2h old from target accounts.
- Comments with 5+ words get more reach than reactions
- Replying to other commenters can put you in front of their network
- Tag the author in your reply only if it adds context
### Twitter/X
- **Browser-driven** (dev-browser) — build a private list of target accounts and point dev-browser at the list URL
- Reply within first 30 min for max reach on big accounts
- Quote-tweet > reply when adding substantial value
- Threading your reply (multi-tweet) signals effort
- Don't pile on dunks — relationships > clout
### Reddit
- Read the subreddit rules before commenting (some ban self-promotion outright)
- Earn karma in the sub before linking to anything you own
- Long, specific answers win. AMAs and "help me decide" threads are gold
- Never lead with your product — answer the question first
### Hacker News
- Comment quality bar is high; low-effort gets downvoted fast
- Founders commenting on threads about their product is welcomed if you're transparent
- Search for past discussions of your category — they're often dormant gold mines
### Bluesky
- Smaller volume but high engagement-to-follower ratio
- Tech and indie-hacker communities are active
- Custom feeds (like Bluesky's "Following" + topic feeds) replace algorithmic search
---
## Common Workflows
### "Give me my top 10 posts to comment on today"
1. Pull from: target account RSS/saved searches + Reddit (relevant subs) + HN (last 24h)
2. Score with the [rubric](#scoring-rubric)
3. Output top 10 with suggested comments
### "Find people complaining about [competitor]"
1. Reddit search: `"competitor name" -site:competitor.com` sorted by new
2. HN comment search for competitor name
3. Bluesky search for competitor handle/name
4. Score by intent signal (high if switching language: "moving from", "alternatives to", "frustrated with")
### "Surface brand mentions from the last week"
1. Reddit search for brand name
2. HN search (stories + comments) for brand name
3. Bluesky search for brand name + handle
4. Output as: reply needed (yes/no), tone (positive/negative/neutral), suggested response
### "Find target-account posts I missed"
1. Maintain a list of target accounts with their RSS / Reddit usernames / Bluesky handles
2. Fetch each source's recent posts
3. Filter to last 24h, output sorted by score
---
## Setting Up the Source List
The user should maintain a list of sources somewhere persistent at `.agents/listening-sources.md` (or `.claude/listening-sources.md`). Claude reads it when running the daily loop.
**A ready-to-fill template lives at [listening-sources-template.md](listening-sources-template.md).** Copy it into the project and edit. The source path depends on how the skill was installed:
```bash
# Plugin / marketplace install (most common):
cp .agents/skills/social/references/listening-sources-template.md .agents/listening-sources.md
# .claude/ install:
cp .claude/skills/social/references/listening-sources-template.md .agents/listening-sources.md
# Working inside the marketingskills repo:
cp skills/social/references/listening-sources-template.md .agents/listening-sources.md
```
The template covers: brand/category, ICP (for scoring), target accounts per platform, intent keywords, subreddits, saved-search URLs, and a do-not-engage list.