aaron-he-zhu/aaron-marketing-skills

A library of Claude Skills and slash commands that turns a chat agent into a marketing operator. Seven disciplines and a shared protocol layer, at a glance:

/aaron-marketing:auto routes any natural-language goal across all of it. Skills and commands are plain Markdown; small Bash/Python-stdlib runtimes provide hooks, validation, scoring, registry events, connectors, and CI checks (no pip, no build step). Every skill runs at Tier 1 with data you provide; connectors only automate retrieval or an explicitly approved mutation.

The authoritative typed topology is references/system-catalog.json; see the generated system architecture for the readable four-layer map, all 120 paths, registry owners, auditor sinks, and distribution profiles.

The pre-merge standalone repos are now signpost repos pointing here — seo-geo-claude-skills (final 20-skill line preserved at tag v9.9.12) and influencer-marketing-agent-skills (final IMPACT line at tag standalone-final). Sibling-repo policy: docs/repo-family.md.

---

Contents

• Why this library
• Install
• First run
• Architecture
  • The shared skill contract
  • The system: a four-layer marketing operating system
  • Quality system: eight frameworks, eight gates
  • The protocol layer
  • Memory & automation hooks
• Skill catalog
  • Narrative — TALE (16)
  • SEO/GEO — SITE (16)
  • Social — ECHO (16)
  • Email — SEND (16)
  • Paid Ads — ROAS (16)
  • Influencer — STAR (16)
  • Launch — RAMP (16)
  • Protocol layer (8)
• Commands
• Connectors & enhancement tiers
• Recommended workflows
• Repository layout
• Design philosophy
• Quality guards (CI)
• Contributing & project docs
• Disclaimer
• License

---

Why this library

---

Install

Use it with Claude Code, any Agent Skills-compatible host, or a plain git clone:

In Claude Code, marketplace add only registers the catalog — run /plugin install aaron-marketing@aaron (or pick it from /plugin) to actually enable the skills and commands. To pull a single skill on a generic host: npx skills add aaron-he-zhu/aaron-marketing-skills -s keyword-research. Browse the bundle on the skills.sh registry. Per-agent directories, frontmatter quirks, and what degrades outside the plugin: docs/agent-compatibility.md (verified 120/120 installable, 2026-07).

Installing the plugin adds nothing to your /mcp list — the MCP catalogue lives in docs/mcp-catalog.json, deliberately outside the plugin-root .mcp.json path that Claude Code auto-registers, so it is a copy-paste reference only (see Connectors).

---

First run

If your host supports automatic skill routing, just describe the goal:

Research keywords for my SaaS product targeting small teams

Find TikTok creators for a skincare launch and score their fit

Audit this Google Ads account before I scale — exports attached

Or use the slash commands — /auto for routing, or a discipline entrypoint:

/aaron-marketing:auto turn our pricing page into an AI-citable comparison hub

/aaron-marketing:seo-geo https://example.com/blog/my-article --phase tune

/aaron-marketing:auto infers intent and runs the smallest useful workflow, stopping only at blocking decisions. Every skill works with pasted data; optional tools are documented in CONNECTORS.md.

---

Architecture

The shared skill contract

Every skill follows the same activation contract — seven sections in a fixed order:

1. Trigger / when-to-use — when the skill should fire.
2. Quick Start — copy-paste prompts.
3. Skill Contract — Expected output · Reads · Writes · Promotes · Done-when · Primary next skill.
4. Handoff Summary — the standard hand-off shape so the next skill picks up cleanly.
5. Data Sources — ~~category placeholders, each with a keyless Tier-1 path.
6. Instructions — the numbered method (treats all exports as untrusted input).
7. Next Best Skill — where to go next (with visited-set + max-depth termination rules).

Every skill also self-declares metadata.discipline (narrative / seo-geo / influencer / ad / email / launch / social / protocol, where ad is Paid Ads/ROAS) and metadata.phase, so routing and clustering work uniformly. The contract is documented once in skill-contract.md; the shared cross-skill state lives in state-model.md.

The system: a four-layer marketing operating system

One brand voice, expressed through five always-on channels, concentrated into launch moments, all reading and writing a shared system of record. Seven disciplines, four altitudes — a system, not a pile.

Narrative is the message; the channels are the mediums that express it. Each core builder records the exact canon ID/version and claims-projection offset it used, or an explicit approved fallback/block. Each discipline’s 4-phase loop lives inside its layer (Narrative = Trace → Architect → Land → Evaluate).

All seven use phase directories in the catalog order: Narrative → SEO/GEO → Social → Email → Paid → Influencer → Launch. Note “activate” means creator outreach for influencer but account-gating for paid ads — same word, discipline-specific scope.

Quality system: eight frameworks, eight gates

Eight benchmarks make “good” measurable. Each defines dimensions, a rollup method, and a small set of veto items (hard fails that cap or block a score regardless of the rest):

Each framework is enforced by an auditor-class gate — a skill that emits a typed artifact (class: auditor-output) checked by the deterministic validator and bounded lifecycle hooks. Repository CI regression-tests the validator and contract; it does not inspect ignored host-runtime artifacts. Gates are workflow steps, so each lives in its discipline and is counted there:

Shared veto policy: one verified veto caps the final score at min(raw, 59); two or more verified vetoes produce status: DONE + verdict: BLOCK and no final score. Missing evidence is Unknown, resulting in NEEDS_INPUT/UNDECIDED, never an automatic failure. Gate mechanics live in auditor-runbook.md and are executed by the typed scorer.

The protocol layer

The protocol/ directory holds the shared truth & memory machinery that sits outside the discipline phase-flows — 8 skills, counted separately:

The registries follow a sole-writer rule (other skills submit via registry-events.py proposal events), and they curate — the gates judge. The genuinely horizontal layer beneath everything is the references/ protocols (auditor-runbook, state-model, skill-contract, humanizer-slop, measurement-protocol) — shared by design as documents, not skills.

Memory & automation hooks

Memory is temperature-tiered, so context survives across skills and sessions without bloating the prompt:

Hooks (hooks/hooks.json, runner hooks/claude-hook.sh) wire seven Claude Code events:

The Artifact Gate is framework-agnostic — the same hook validates TALE, CORE-EEAT, CITE, STAR, ROAS, SEND, RAMP, and ECHO artifacts with no per-framework code.

---

Skill catalog

Skill links open each SKILL.md. Expand the Details under each discipline for a one-line purpose per skill. Catalog order follows the four-layer strata — Narrative (L1 · Strategy) first, the five always-on channels next, Launch (L3 · Orchestration), then the Protocol layer.

Narrative — TALE (16) · 📖 Discipline guide

Four phase directories under narrative/ (4 skills each) follow the TALE loop (Trace → Architect → Land → Evaluate); the gate (⛩ narrative-quality-auditor) sits in Evaluate. It runs truth, system, and effectiveness profiles separately; a full review links three results and never averages them. Narrative is the L1 · Strategy layer: one brand voice the five always-on channels inherit. It absorbs positioning — positioning-mapper stays physically in launch/ but reads logically as the front of TALE Trace.

SEO/GEO — SITE (16) · 📖 Discipline guide

Four phase directories (4 skills each) plus the discipline’s two quality gates (marked ⛩).

Social — ECHO (16) · 📖 Discipline guide

Four phase directories under social/ (4 skills each) follow the ECHO loop; the gate (⛩ social-quality-auditor) sits in Host. Each run selects the asset gate or one program-maturity profile; those constructs are never combined. The discipline ships no posting, engagement, or DM automation of any kind.

Email — SEND (16) · 📖 Discipline guide

Four phase directories under email/ (4 skills each) follow the SEND loop; the gate (⛩ email-quality-auditor) sits in Deliver. Only the gate computes EQS from the declared promotional, retention, cold-outbound, or newsletter profile — every other skill works one lever and hands off.

Paid Ads — ROAS (16) · 📖 Discipline guide

Four phase directories under ad/ (4 skills each) follow the ROAS loop; the gate (⛩ ad-account-auditor) sits in Activate. Only the gate computes the profile-weighted RQS — every other skill works one lever and hands off.

Influencer — STAR (16) · 📖 Discipline guide

Four phase directories (4 skills each); the discipline’s gate (⛩ creator-content-auditor) sits in Activate.

Launch — RAMP (16) · 📖 Discipline guide

Four phase directories under launch/ (4 skills each) follow the RAMP loop; the gate (⛩ launch-readiness-auditor) sits in Mobilize. Each run selects one preflight, execution, or outcome profile; scores from different lifecycle reads are linked but never averaged.

Protocol layer (8)

The shared truth & memory machinery — see Architecture § The protocol layer for roles and sole-writer rules.

---

Commands

Eight commands: /aaron-marketing:auto routes any goal across all seven disciplines, and each discipline has exactly one explicit entrypoint. Source: commands/.

Daily work normally starts with /aaron-marketing:auto; the other seven are explicit discipline entrypoints, with --phase to narrow the stage.

---

Connectors & enhancement tiers

Skills name tools with ~~category placeholders (~~SEO tool, ~~web analytics, ~~ad platform, ~~email platform, …) instead of specific vendors, and every category has a keyless Tier-1 path. Full recipes — including the free/first-party endpoint for each category — are in CONNECTORS.md.

The connector layer is a product in itself

100+ documented integration paths across three engineered layers — and every one of them earns its place:

What makes them trustworthy rather than just numerous:

• Three safety classes, engineered gates (SECURITY.md): hosted fetchers run a local robots.txt pre-flight before every delegated fetch and refuse on Disallow; anything that mutates external state (email sends, index pushes) is dry-run by default behind an explicit --live flag, with idempotency keys where the vendor supports them and no auto-retry where it doesn’t.
• Verified, then re-verified: endpoints are checked against primary vendor docs with dates, keyless paths are live-tested, a CI guard enforces version/tracking sync, and a pre-release live smoke catches endpoint drift (it has already caught real API changes — twice).
• Facts, not verdicts: connectors report record presence, parsed tags, and raw series; the auditor gates do the judging, and skills label every number Measured / User-provided / Estimated.
• A written playbook (docs/connector-playbook.md) governs every addition — qualify, verify, implement, test, wire, document, track, regress, record — so quality holds as the catalog grows.

• Bundled zero-dependency helpers under scripts/connectors/ (Python stdlib only) pull public/own data locally — e.g. PageSpeed/CrUX, Open PageRank, page crawl, Wayback CDX, Wikidata SPARQL, Common Crawl, advertools recipes — plus resend.py, direct Resend ESP automation for the email skills (free-tier key: domain-auth status, seed-test sends, suppression sync, broadcast scheduling; mutating subcommands dry-run by default and require --live), and firecrawl.py + tavily.py, keyless hosted-fetcher automation for the research skills (Firecrawl: live web SERP + JS-rendered page markdown + site maps; Tavily: scored search + an AI answer engine’s cited-sources probe for GEO + URL extract — both free with no key at all, both with a local robots.txt pre-flight built in).
• Free/keyless sources documented per category: Google Search Console & GA4 (own data), PageSpeed/CrUX, Wikidata, Common Crawl, Open PageRank, Firecrawl keyless SERP/scrape, Tavily keyless AI-search, DNS-over-HTTPS email-auth records (doh.py), Wikipedia attention series (pageviews.py), GDELT news mentions (gdelt.py), YouTube creator metrics on a free key (youtube.py), IndexNow + Baidu index push (indexpush.py, dry-run gated), the ad-transparency libraries (Meta/Google/TikTok), and recipe rows for crt.sh, the W3C validator, oEmbed, and HN Algolia.
• Opt-in MCP servers (Ahrefs, Semrush, SE Ranking, SISTRIX, SimilarWeb, the self-hosted free OpenSEO suite, Cloudflare, Vercel, HubSpot, Amplitude, Notion, Webflow, Sanity, Contentful, Slack, Resend, the keyless Firecrawl and Tavily) are catalogued in docs/mcp-catalog.json as a copy-paste reference only — the catalog sits outside the auto-registered plugin-root .mcp.json path, so nothing is registered for you. Copy the entries you want into your own MCP config.

Paid-ads skills score from your own-account manual export (native ad-manager CSV, GA4, ecommerce). Keyed ad-platform APIs (Google Ads SDK, Meta Marketing API) are opt-in Tier-2/3 only and never a Tier-1 requirement. Email skills score the same way — from your own ESP export — and every deliverability signal is keyless (DNS lookups, a DMARC RUA report, and a seed-list inbox test), so a keyed ESP API is never a Tier-1 requirement either; when Resend is your ESP, the bundled resend.py automates the same loop on the free tier.

---

Recommended workflows

Most real goals span disciplines. /aaron-marketing:auto routes a natural-language goal to the smallest useful chain across all seven — a product launch, for instance, pulls Launch, Email, Social, and Paid at once:

/aaron-marketing:auto launch our v2 on Product Hunt in 3 weeks — 1,200 on the waitlist; we need the page, the emails, and a launch-day plan

Or drive one discipline’s loop end to end — each discipline’s 📖 Discipline guide (linked from the skill catalog) adds scenario-level plays:

Narrative (TALE loop)

1. Trace — narrative-baseline-mapper → category-narrative-mapper → audience-belief-mapper → positioning-truth-tracer
2. Architect — strategic-narrative-designer → message-system-architect → brand-language-codifier → story-bank-builder
3. Land — narrative-cascade-planner → pitch-narrative-builder → narrative-enablement-kit → proof-point-packager
4. Evaluate — narrative-quality-auditor (⛩ TALE gate) → message-test-designer → narrative-resonance-monitor → narrative-drift-monitor

SEO/GEO (SITE loop)

1. Survey — keyword-research → competitor-analysis → content-gap-analysis
2. Implement — content-writer → geo-content-optimizer → serp-markup-builder / page-play-builder
3. Tune — content-quality-auditor (⛩ publish gate) → on-page-seo-checker → technical-seo-checker → site-structure-optimizer
4. Evaluate — rank-tracker → performance-monitor → offsite-signal-analyzer; domain-authority-auditor (⛩) for the trust review

Social (ECHO loop)

1. Explore — channel-portfolio-planner → voice-dossier-builder → platform-norm-profiler → participation-warmup-planner
2. Craft — social-calendar-builder → social-creative-builder → short-video-scripter → advocacy-program-designer
3. Host — social-quality-auditor (⛩ ECHO gate) → engagement-inbox-manager → social-selling-planner → crisis-response-planner
4. Observe — social-pulse-monitor → share-of-voice-tracker → dark-social-attributor → social-measurement-loop

Email (SEND loop)

1. Setup — deliverability-qa → list-segment-builder
2. Engage — email-creative-builder
3. Nurture — email-sequence-designer → newsletter-monetization-planner
4. Deliver — send-experiment-designer → email-quality-auditor (⛩ EQS gate) before send

Paid Ads (ROAS loop)

1. Research — audience-segment-builder → campaign-architect
2. Orchestrate — ad-creative-builder → ad-test-designer (+ landing-optimizer for the page)
3. Activate — conversion-signal-qa → ad-account-auditor (⛩ RQS gate) before any budget goes live
4. Scale — paid-measurement-loop → attribution-reconciler → roi-calculator → report-generator

Influencer (STAR loop)

1. Scout — audience-mapper → trend-spotter → influencer-discovery → fit-scorer (STAR Suitability)
2. Target — competitor-tracker → campaign-planner → brief-generator → budget-optimizer
3. Activate — outreach-manager → creator-content-auditor (⛩ STAR gate) → contract-helper → content-amplifier
4. Report — landing-optimizer → performance-analyzer → roi-calculator → report-generator

Launch (RAMP loop)

1. Research — positioning-mapper → launch-tier-planner → launch-window-planner → early-access-designer
2. Assemble — message-house-builder → launch-asset-packager → pricing-packaging-planner → sales-enablement-kit
3. Mobilize — launch-readiness-auditor (⛩ RAMP gate) → launch-day-conductor → community-launch-runner → press-media-relations
4. Prove — launch-monitor → launch-feedback-synthesizer → launch-retro-analyzer → momentum-planner

For a full trust review, pair content-quality-auditor with domain-authority-auditor for a combined 120-item assessment. With memory-management active, handoffs and open loops persist in HOT/WARM/COLD memory automatically.

---

Repository layout

narrative/{trace,architect,land,evaluate}/                  # Narrative — TALE (16, incl. its gate)
seo-geo/{survey,implement,tune,evaluate}/                  # SEO/GEO (16, incl. its 2 gates)
influencer/{scout,target,activate,report}/                   # Influencer (16, incl. its gate)
ad/research|orchestrate|activate|scale/            # Paid Ads — ROAS (16, incl. its gate)
email/setup|engage|nurture|deliver/                  # Email — SEND (16, incl. its gate)
launch/research|assemble|mobilize|prove/             # Launch — RAMP (16, incl. its gate)
social/explore|craft|host|observe/                   # Social — ECHO (16, incl. its gate)
protocol/                                            # Protocol layer (8) — truth registries + memory
commands/        # 8 slash commands (auto, narrative, seo-geo, influencer, ad, email, launch, social)
references/      # shared contract, state model, the 8 benchmarks, auditor runbook, platform packs
evals/           # per-skill structural eval cases + structure-manifest.json
hooks/           # hooks.json + claude-hook.sh (the only runtime logic)
scripts/         # validate-skill.sh + connectors/ (stdlib) + CI guards
memory/          # HOT/WARM/COLD scaffolding + registry stores (entities/creators/claims/consent/launch/channels/narrative-registry)
docs/            # localized README (zh)
.claude-plugin/  # plugin.json + marketplace.json mirror

This source repository contains both runtime and maintenance assets. User distributions are allowlisted by references/distribution-files.json and built with python3 scripts/build-distribution.py --output --plugin; tests, evals, CI, generators, and contributor-only documentation are intentionally excluded. A standalone skill build uses --skill and contains only that skill directory.

---

Design philosophy

• Skills are content. The only code is the Bash validator, the Bash hook runner, and zero-dependency Python-stdlib connector/check helpers. No third-party / pip dependencies, ever — enforced by a dependency-creep guard.
• Keyless first. Every ~~category has a free/own-data recipe; MCP and paid tools are pure convenience.
• Surgical & MECE. Each skill owns one job with a crisp scope boundary; overlapping work ships as a mode of an existing skill rather than a new thin skill. Registries curate, gates judge, analyzers feed gates.
• No invented numbers. Skills label every figure Measured / User-provided / Estimated and ship an AI-slop / banned-phrase detector.
• Compliance is guidance, not law. FTC-disclosure and claim-integrity checks flag risk; they are not legal advice.

---

Quality guards (CI)

Every change runs against a set of fail-closed guards (all in scripts/ and tests/):

Live endpoint drift is sampled separately by the manual scripts/connectors/smoke-live.sh — one minimal real call per hosted connector listed in that script, with shape assertions (rate-limit answers count as SKIP); run it before a release, never in CI.

---

Contributing & project docs

• CONTRIBUTING.md — authoring rules, the contribution checklist, and the authoritative 10-surface tracking list.
• VERSIONS.md — per-skill versions + changelog (current bundle: 18.0.0).
• SECURITY.md · PRIVACY.md · CODE_OF_CONDUCT.md — security, privacy, and community policy.
• CLAUDE.md / AGENTS.md — agent-facing context for this repo.

---

Disclaimer

These skills assist brand-narrative, SEO/GEO, influencer-marketing, paid-ads, email-marketing, product-launch, and organic-social workflows but do not guarantee rankings, AI citations, traffic, engagement, conversions, ROAS, deliverability, or business outcomes. Influencer-, ad-, email-, and social-compliance checks (FTC disclosure, claim integrity, platform policy, consent/opt-in, material-connection disclosure) are guidance, not legal advice. Verify recommendations with qualified professionals before relying on them for major strategy, financial, or legal decisions.

License

Apache License 2.0 — see LICENSE.

Star History