adspirer-skills 0.1.0

package/README.md

@@ -0,0 +1,69 @@
+# adspirer-skills
+
+**Install [Adspirer Skills](https://adspirer.com/skills) — 92 expert advertising workflows for AI agents — with one command.**
+
+Ready-to-run skills for **Google Ads, Meta (Facebook/Instagram) Ads, TikTok Ads, LinkedIn Ads, and Amazon Ads**: media planning, creative production, campaign launch, and always-on ad ops. Each is a bounded workflow in the open [Agent Skills](https://agentskills.io) (`SKILL.md`) format — so it drops into **Claude Code, Claude, ChatGPT, Cursor, Codex, Gemini CLI**, and any Agent-Skills-compatible AI.
+
+```bash
+npx adspirer-skills list                                     # browse all 92 skills
+npx adspirer-skills add the-daily-pacing-check                   # install (Claude Code by default)
+npx adspirer-skills add meta-full-funnel-launcher --agent cursor
+npx adspirer-skills search "meta campaign"
+```
+
+No account needed to install or run. Browse everything at **[adspirer.com/skills](https://adspirer.com/skills)**.
+
+## Agents
+
+`claude-code` (default) · `claude` · `cursor` · `codex` · `windsurf` · `gemini` · `openclaw` · `antigravity` · `hermes` · `other`
+
+```bash
+npx adspirer-skills add <skill> --agent <name>
+```
+
+The CLI writes each skill into your agent's native location (Claude Code → `.claude/skills/`, Cursor → `.cursor/rules/`, Codex → `AGENTS.md`, and so on).
+
+## Why these are safe to run
+
+Every Adspirer Skill carries the same contract: **fixed checks against live account data, honest stop conditions, and approval gates on anything that spends.** Skill content is reference material — authority comes only from you, and nothing spends a dollar without your explicit approval. The ads leg connects through [Adspirer](https://adspirer.com/skills) only when a step touches a live ad account.
+
+## Popular skills
+
+- **[A/B Test Runner](https://adspirer.com/skills/a-b-test-runner)** — Set up a clean A/B test (one variable, proper split, a decision rule and duration for significance), read it honestly, and call the winner only when the data supports it.
+- **[Ad Copy Writing Room](https://adspirer.com/skills/ad-copy-writing-room)** — A copy-writing prompt that produces platform-correct ad copy variations (headlines, primary text, CTAs) grounded in a real offer and audience, with angle rationale.
+- **[Ad-Library Deep Dive](https://adspirer.com/skills/ad-library-deep-dive)** — Systematically mine a brand's Meta Ad Library: creative angles, hooks, formats, longevity (long-running = winning) — extract patterns to inform your own creative.
+- **[Agency New-Client Onboarding](https://adspirer.com/skills/agency-new-client-onboarding)** — Onboard a new client end to end: audit their accounts, set up tracking, build the initial plan, launch the first campaigns, and establish the reporting cadence.
+- **[Amazon Sponsored Products Launcher](https://adspirer.com/skills/amazon-sponsored-products-launcher)** — Launch an Amazon Sponsored Products campaign: product eligibility, keyword/ASIN targeting, bids, negatives, built and checked.
+- **[Anomaly Triage](https://adspirer.com/skills/anomaly-triage)** — When a metric moves sharply, triage it: is it real, a tracking artifact, a platform delay, or a genuine change? Trace it to a driver before anyone panics.
+- **[App Campaign (UAC) Launcher](https://adspirer.com/skills/app-campaign-uac-launcher)** — Launch a Google App campaign (UAC): conversion events/SDK check, asset variety, bidding by install vs in-app action, built paused and verified.
+- **[App Growth Stack](https://adspirer.com/skills/app-growth-stack)** — Stand up an app-growth stack: UAC + Meta app campaigns, install + in-app event tracking, cohort/LTV read, and a scaling plan — end to end, gated.
+- **[Audience Architect](https://adspirer.com/skills/audience-architect)** — Design a layered audience strategy (cold/warm/hot, exclusions, lookalikes/custom) for a campaign, per platform, with overlap and audience-size sanity checks.
+- **[Avatar Spokesperson Ads](https://adspirer.com/skills/avatar-spokesperson-ads)** — Generate avatar-spokesperson video ads via HeyGen — script, avatar, voiceover — at scale for testing message variations.
+- **[B2B Media Plan (LinkedIn-first)](https://adspirer.com/skills/b2b-media-plan-linkedin-first)** — Build a B2B media plan centered on LinkedIn: firmographic targeting, ABM lists, lead-gen vs traffic objectives, realistic B2B CPLs, and budget staging.
+- **[B2B Pipeline Engine](https://adspirer.com/skills/b2b-pipeline-engine)** — Build a B2B pipeline engine: LinkedIn + Search lead gen → CRM sync (HubSpot if connected) → follow-up → attribute pipeline back to campaigns.
+
+## Browse by job
+
+**Media Planning** — [Audience Architect](https://adspirer.com/skills/audience-architect) · [B2B Media Plan (LinkedIn-first)](https://adspirer.com/skills/b2b-media-plan-linkedin-first) · [Campaign Budget Splitter](https://adspirer.com/skills/campaign-budget-splitter) · [E-commerce Media Plan](https://adspirer.com/skills/e-commerce-media-plan) · [Flighting & Pacing Planner](https://adspirer.com/skills/flighting-pacing-planner) · [Keyword Universe Builder](https://adspirer.com/skills/keyword-universe-builder) · [Launch-Readiness Audit](https://adspirer.com/skills/launch-readiness-audit) · [Market-Entry Media Plan](https://adspirer.com/skills/market-entry-media-plan) · [The Channel-Mix Advisor](https://adspirer.com/skills/the-channel-mix-advisor) · [The Media Plan Builder](https://adspirer.com/skills/the-media-plan-builder)
+
+**Creative Production** — [Ad Copy Writing Room](https://adspirer.com/skills/ad-copy-writing-room) · [Avatar Spokesperson Ads](https://adspirer.com/skills/avatar-spokesperson-ads) · [Brand-Character Ads](https://adspirer.com/skills/brand-character-ads) · [Creative Brief Generator](https://adspirer.com/skills/creative-brief-generator) · [Creative Compliance Pre-Check](https://adspirer.com/skills/creative-compliance-pre-check) · [Creative Resize Matrix](https://adspirer.com/skills/creative-resize-matrix) · [Design-System Ad Kit](https://adspirer.com/skills/design-system-ad-kit) · [Landing Page Builder](https://adspirer.com/skills/landing-page-builder) · [Pro Retouch Pipeline](https://adspirer.com/skills/pro-retouch-pipeline) · [Static Ad Factory](https://adspirer.com/skills/static-ad-factory) · [Text-in-Image Ad Maker](https://adspirer.com/skills/text-in-image-ad-maker) · [The Creative Testing Matrix](https://adspirer.com/skills/the-creative-testing-matrix) · [UGC-Style Video Ads](https://adspirer.com/skills/ugc-style-video-ads) · [Video Ad Concepter](https://adspirer.com/skills/video-ad-concepter) · [Voiceover & Dubbing Pack](https://adspirer.com/skills/voiceover-dubbing-pack)
+
+**Campaign Launch** — [Amazon Sponsored Products Launcher](https://adspirer.com/skills/amazon-sponsored-products-launcher) · [App Campaign (UAC) Launcher](https://adspirer.com/skills/app-campaign-uac-launcher) · [Cross-Platform Product Launch](https://adspirer.com/skills/cross-platform-product-launch) · [Google Search Campaign Launcher](https://adspirer.com/skills/google-search-campaign-launcher) · [Google Shopping Launcher](https://adspirer.com/skills/google-shopping-launcher) · [LinkedIn ABM Matrix Launcher](https://adspirer.com/skills/linkedin-abm-matrix-launcher) · [LinkedIn Lead-Gen Launcher](https://adspirer.com/skills/linkedin-lead-gen-launcher) · [Meta Catalog / DPA Launcher](https://adspirer.com/skills/meta-catalog-dpa-launcher) · [Meta Click-to-WhatsApp Launcher](https://adspirer.com/skills/meta-click-to-whatsapp-launcher) · [Meta Full-Funnel Launcher](https://adspirer.com/skills/meta-full-funnel-launcher) · [Performance Max Launcher](https://adspirer.com/skills/performance-max-launcher) · [The Retargeting Stack](https://adspirer.com/skills/the-retargeting-stack) · [TikTok Launch Kit](https://adspirer.com/skills/tiktok-launch-kit) · [YouTube Campaign Launcher](https://adspirer.com/skills/youtube-campaign-launcher)
+
+**Ad Ops & Optimization** — [A/B Test Runner](https://adspirer.com/skills/a-b-test-runner) · [Broken-Link & LP Checker](https://adspirer.com/skills/broken-link-lp-checker) · [Conversion-Tracking Auditor](https://adspirer.com/skills/conversion-tracking-auditor) · [Creative Fatigue Monitor](https://adspirer.com/skills/creative-fatigue-monitor) · [Disapproval Resolver](https://adspirer.com/skills/disapproval-resolver) · [Meta Ads scale runner](https://adspirer.com/skills/meta-ads-scale-runner) · [Negative Keyword Miner](https://adspirer.com/skills/negative-keyword-miner) · [Placement Cleaner](https://adspirer.com/skills/placement-cleaner) · [Quality-Score Rescue](https://adspirer.com/skills/quality-score-rescue) · [Seasonal Ramp Playbook](https://adspirer.com/skills/seasonal-ramp-playbook) · [The Account Takeover Audit](https://adspirer.com/skills/the-account-takeover-audit) · [The Bid-Strategy Doctor](https://adspirer.com/skills/the-bid-strategy-doctor) · [The Budget Reallocator](https://adspirer.com/skills/the-budget-reallocator) · [The Daily Pacing Check](https://adspirer.com/skills/the-daily-pacing-check) · [The Frequency Doctor](https://adspirer.com/skills/the-frequency-doctor) · [The Overspend Guardian](https://adspirer.com/skills/the-overspend-guardian) · [Weekly Account Hygiene Sweep](https://adspirer.com/skills/weekly-account-hygiene-sweep)
+
+**Analytics & Reporting** — [Anomaly Triage](https://adspirer.com/skills/anomaly-triage) · [Client-Ready Monthly Report](https://adspirer.com/skills/client-ready-monthly-report) · [Cohort & LTV Reader](https://adspirer.com/skills/cohort-ltv-reader) · [Cross-Platform ROAS Rollup](https://adspirer.com/skills/cross-platform-roas-rollup) · [GA4 Truth-Check](https://adspirer.com/skills/ga4-truth-check) · [Slack Reporting Bot](https://adspirer.com/skills/slack-reporting-bot) · [The Attribution Detective](https://adspirer.com/skills/the-attribution-detective) · [The Board Slide](https://adspirer.com/skills/the-board-slide) · [The Creative Leaderboard](https://adspirer.com/skills/the-creative-leaderboard) · [The Monday-Morning Report](https://adspirer.com/skills/the-monday-morning-report) · [The Spend Reconciler](https://adspirer.com/skills/the-spend-reconciler) · [Warehouse-Grade Ads Reporting](https://adspirer.com/skills/warehouse-grade-ads-reporting)
+
+**Research & Intelligence** — [Ad-Library Deep Dive](https://adspirer.com/skills/ad-library-deep-dive) · [Competitor Ad Recon](https://adspirer.com/skills/competitor-ad-recon) · [Competitor Traffic X-Ray](https://adspirer.com/skills/competitor-traffic-x-ray) · [Market Sizing Snapshot](https://adspirer.com/skills/market-sizing-snapshot) · [Review-Mining for Ad Copy](https://adspirer.com/skills/review-mining-for-ad-copy) · [SERP & Share-of-Voice Tracker](https://adspirer.com/skills/serp-share-of-voice-tracker) · [The Audience Interview Miner](https://adspirer.com/skills/the-audience-interview-miner) · [The Offer Lab](https://adspirer.com/skills/the-offer-lab) · [Trend Scout](https://adspirer.com/skills/trend-scout)
+
+**Full-Stack Playbooks** — [Agency New-Client Onboarding](https://adspirer.com/skills/agency-new-client-onboarding) · [App Growth Stack](https://adspirer.com/skills/app-growth-stack) · [B2B Pipeline Engine](https://adspirer.com/skills/b2b-pipeline-engine) · [Creative Refresh Cycle](https://adspirer.com/skills/creative-refresh-cycle) · [E-commerce Growth Loop](https://adspirer.com/skills/e-commerce-growth-loop) · [Launch-Day War Room](https://adspirer.com/skills/launch-day-war-room) · [Lead-Gen Machine](https://adspirer.com/skills/lead-gen-machine) · [The Localization Expander](https://adspirer.com/skills/the-localization-expander) · [The Turnaround Playbook](https://adspirer.com/skills/the-turnaround-playbook) · [Zero-to-Launch: New Product](https://adspirer.com/skills/zero-to-launch-new-product)
+
+**Agency Ops** — [Media-Plan-to-Tracker Sync](https://adspirer.com/skills/media-plan-to-tracker-sync) · [New-Platform Expansion Brief](https://adspirer.com/skills/new-platform-expansion-brief) · [The Client Status Update](https://adspirer.com/skills/the-client-status-update) · [The Proposal Builder](https://adspirer.com/skills/the-proposal-builder) · [The QBR Pack](https://adspirer.com/skills/the-qbr-pack)
+
+## Learn more
+
+- **All 92 skills:** [adspirer.com/skills](https://adspirer.com/skills)
+- **Docs & setup for your AI client:** [adspirer.com/docs](https://adspirer.com/docs/introduction)
+- **Machine-readable catalog:** [catalog.json](https://adspirer.com/skills/catalog.json) · [llms.txt](https://adspirer.com/skills/llms.txt)
+
+Made by [Adspirer](https://adspirer.com) — the AI advertising agent for Google, Meta, TikTok, LinkedIn & Amazon.

package/bin/adspirer-skills.mjs

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+// adspirer-skills — install Adspirer Skills into any AI agent.
+//   npx adspirer-skills add <slug> [--agent <name>] [--dir <path>]
+//   npx adspirer-skills list
+//   npx adspirer-skills search <query>
+// Fetches skills from adspirer.com/skills (the DB-backed registry). No install needed to run.
+import { mkdir, writeFile, readFile } from 'node:fs/promises';
+import { join, resolve, sep } from 'node:path';
+
+const BASE = process.env.ADSPIRER_SKILLS_URL || 'https://adspirer.com/skills';
+
+// Per-agent install layout. `dir` is relative to cwd; `file` is what we write the skill into.
+// The value is ALWAYS the same SKILL.md markdown — each agent just reads it from its own location.
+const AGENTS = {
+  'claude-code': { dir: '.claude/skills/{slug}', file: 'SKILL.md', note: 'Claude Code reads .claude/skills/*/SKILL.md.' },
+  claude: { dir: 'adspirer-skills/{slug}', file: 'SKILL.md', note: 'Upload this folder as a skill in Claude / claude.ai.' },
+  cursor: { dir: '.cursor/rules', file: '{slug}.md', note: 'Cursor loads .cursor/rules/*.md.' },
+  codex: { dir: '.', file: 'AGENTS.md', note: 'Appended to AGENTS.md (Codex reads it).', append: true },
+  windsurf: { dir: '.windsurf/rules', file: '{slug}.md', note: 'Windsurf loads .windsurf/rules/*.md.' },
+  gemini: { dir: '.gemini', file: 'GEMINI.md', note: 'Gemini CLI reads GEMINI.md.', append: true },
+  openclaw: { dir: 'adspirer-skills/{slug}', file: 'SKILL.md', note: 'Point OpenClaw at this SKILL.md.' },
+  antigravity: { dir: 'adspirer-skills/{slug}', file: 'SKILL.md', note: 'Point Antigravity at this SKILL.md.' },
+  hermes: { dir: 'adspirer-skills/{slug}', file: 'SKILL.md', note: 'Point Hermes at this SKILL.md.' },
+  other: { dir: 'adspirer-skills/{slug}', file: 'SKILL.md', note: 'Universal folder — tell your agent to read SKILL.md.' },
+};
+
+const SLUG_RE = /^[a-z0-9-]{1,80}$/;
+const c = { dim: (s) => `\x1b[2m${s}\x1b[0m`, b: (s) => `\x1b[1m${s}\x1b[0m`, g: (s) => `\x1b[32m${s}\x1b[0m`, r: (s) => `\x1b[31m${s}\x1b[0m`, cy: (s) => `\x1b[36m${s}\x1b[0m` };
+
+function parseArgs(argv) {
+  const out = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--agent' || a === '-a') out.agent = argv[++i];
+    else if (a === '--dir' || a === '-d') out.dir = argv[++i];
+    else if (a === '--help' || a === '-h') out.help = true;
+    else out._.push(a);
+  }
+  return out;
+}
+
+async function getJson(path) {
+  const r = await fetch(`${BASE}${path}`, { headers: { accept: 'application/json' } });
+  if (!r.ok) throw new Error(`registry ${r.status} for ${path}`);
+  return r.json();
+}
+async function getText(path) {
+  const r = await fetch(`${BASE}${path}`);
+  if (!r.ok) throw new Error(`not found: ${path} (${r.status})`);
+  return r.text();
+}
+
+function usage() {
+  console.log(`
+${c.b('adspirer-skills')} — install Adspirer Skills into your AI agent
+
+${c.b('Usage')}
+  npx adspirer-skills add <slug> [--agent <name>] [--dir <path>]
+  npx adspirer-skills list
+  npx adspirer-skills search <query>
+
+${c.b('Agents')}  ${Object.keys(AGENTS).join(', ')}
+  (default: claude-code)
+
+${c.b('Examples')}
+  npx adspirer-skills add the-daily-pacing-check
+  npx adspirer-skills add meta-full-funnel-launcher --agent cursor
+  npx adspirer-skills list
+
+Browse everything at ${c.cy(BASE)}
+`);
+}
+
+async function cmdList() {
+  const cat = await getJson('/catalog.json');
+  console.log(`\n${c.b(`${cat.skills.length} Adspirer Skills`)}  ${c.dim(BASE)}\n`);
+  for (const s of cat.skills) {
+    console.log(`  ${c.cy(s.id.padEnd(34))} ${c.dim(s.category)}  ${s.title}`);
+  }
+  console.log(`\nInstall one:  ${c.b('npx adspirer-skills add <id>')}\n`);
+}
+
+async function cmdSearch(query) {
+  const cat = await getJson('/catalog.json');
+  const q = query.toLowerCase();
+  const hits = cat.skills.filter((s) => (s.title + ' ' + s.summary + ' ' + s.id + ' ' + s.category).toLowerCase().includes(q));
+  console.log(`\n${c.b(`${hits.length} match(es) for "${query}"`)}\n`);
+  for (const s of hits) console.log(`  ${c.cy(s.id.padEnd(34))} ${s.title}\n     ${c.dim(s.summary)}`);
+  console.log('');
+}
+
+async function cmdAdd(slug, args) {
+  if (!slug || !SLUG_RE.test(slug)) {
+    console.error(c.r(`Invalid skill id "${slug || ''}". Run:  npx adspirer-skills list`));
+    process.exit(1);
+  }
+  const agentKey = (args.agent || 'claude-code').toLowerCase();
+  const agent = AGENTS[agentKey];
+  if (!agent) {
+    console.error(c.r(`Unknown agent "${agentKey}". One of: ${Object.keys(AGENTS).join(', ')}`));
+    process.exit(1);
+  }
+
+  process.stdout.write(c.dim(`Fetching ${slug} …`));
+  let md;
+  try {
+    md = await getText(`/${slug}.md`);
+  } catch (e) {
+    console.error(`\r${c.r(`✗ ${e.message}`)}          `);
+    console.error(c.dim(`  Run  npx adspirer-skills list  to see available skills.`));
+    process.exit(1);
+  }
+
+  const dir = args.dir || agent.dir.replaceAll('{slug}', slug);
+  const file = agent.file.replaceAll('{slug}', slug);
+  // Contain everything we write to the current working directory — reject any
+  // --dir that escapes it via `..` (or an absolute path pointing elsewhere).
+  const cwd = resolve(process.cwd());
+  const targetDir = resolve(cwd, dir);
+  if (targetDir !== cwd && !targetDir.startsWith(cwd + sep)) {
+    console.error(c.r(`--dir "${dir}" escapes the current directory. Pick a path inside the project.`));
+    process.exit(1);
+  }
+  const target = join(targetDir, file);
+  await mkdir(targetDir, { recursive: true });
+
+  if (agent.append) {
+    // Idempotent append: if this skill's delimited block is already present,
+    // leave the file alone rather than stacking a duplicate copy.
+    const marker = `<!-- Adspirer Skill: ${slug} `;
+    let existing = '';
+    try { existing = await readFile(target, 'utf8'); } catch { /* new file */ }
+    if (existing.includes(marker)) {
+      console.log(`\r${c.g('✓')} ${c.b(slug)} already present in ${dir}/${file} — left unchanged.          `);
+      return;
+    }
+    const header = `\n\n<!-- Adspirer Skill: ${slug} (adspirer.com/skills/${slug}) -->\n`;
+    const { appendFile } = await import('node:fs/promises');
+    await appendFile(target, header + md);
+  } else {
+    await writeFile(target, md);
+  }
+
+  console.log(`\r${c.g('✓')} Installed ${c.b(slug)} for ${c.b(agentKey)}          `);
+  console.log(`  ${c.dim('→')} ${dir}/${file}`);
+  console.log(`  ${c.dim(agent.note)}`);
+  console.log(`\n  Then tell your agent:  ${c.cy(`"run the ${slug.replaceAll('-', ' ')} skill"`)}\n`);
+  // Best-effort install telemetry (never blocks; ignores failure).
+  fetch(`${BASE}/api/events`, {
+    method: 'POST', headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ event_type: 'install_copy', surface: 'cli', skill_id: slug }),
+  }).catch(() => {});
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const [cmd, ...rest] = args._;
+  if (args.help || !cmd) return usage();
+  try {
+    if (cmd === 'add') return await cmdAdd(rest[0], args);
+    if (cmd === 'list') return await cmdList();
+    if (cmd === 'search') return await cmdSearch(rest.join(' '));
+    usage();
+  } catch (e) {
+    console.error(c.r(`✗ ${e.message}`));
+    process.exit(1);
+  }
+}
+main();

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "adspirer-skills",
+  "version": "0.1.0",
+  "description": "Install Adspirer Skills — expert Google, Meta, TikTok & LinkedIn ad-ops workflows — into any AI agent (Claude Code, ChatGPT, Cursor, Codex, Gemini, and more). Open Agent-Skills (SKILL.md) format.",
+  "bin": {
+    "adspirer-skills": "bin/adspirer-skills.mjs"
+  },
+  "type": "module",
+  "engines": { "node": ">=18" },
+  "files": ["bin", "README.md"],
+  "keywords": [
+    "adspirer", "agent skills", "skill", "SKILL.md", "ai agent", "ai advertising",
+    "advertising automation", "ad ops", "media planning", "campaign automation",
+    "google ads", "meta ads", "facebook ads", "tiktok ads", "linkedin ads", "amazon ads",
+    "claude", "claude code", "chatgpt", "cursor", "codex", "gemini", "mcp", "ppc", "marketing"
+  ],
+  "homepage": "https://adspirer.com/skills",
+  "repository": { "type": "git", "url": "https://github.com/Adspirer/skills-registry.git" },
+  "bugs": { "url": "https://adspirer.com/skills" },
+  "author": "Adspirer (https://adspirer.com)",
+  "license": "MIT"
+}