diff --git a/CATALOG.md b/CATALOG.md index 358e488c..b2d20dc8 100644 --- a/CATALOG.md +++ b/CATALOG.md @@ -2,9 +2,9 @@ Generated at: 2026-02-08T00:00:00.000Z -Total skills: 1273 +Total skills: 1304 -## architecture (85) +## architecture (87) | Skill | Description | Tags | Triggers | | --- | --- | --- | --- | @@ -78,7 +78,9 @@ Total skills: 1273 | `robius-event-action` | CRITICAL: Use for Robius event and action patterns. Triggers on: custom action, MatchEvent, post_action, cx.widget_action, handle_actions, DefaultNone, widge... | robius, event, action | robius, event, action, critical, triggers, custom, matchevent, post, cx, widget, handle, actions | | `robius-widget-patterns` | CRITICAL: Use for Robius widget patterns. Triggers on: apply_over, TextOrImage, modal, 可复用, 模态, collapsible, drag drop, reusable widget, widget design, pagef... | robius, widget | robius, widget, critical, triggers, apply, textorimage, modal, collapsible, drag, drop, reusable, pageflip | | `saga-orchestration` | Patterns for managing distributed transactions and long-running business processes. | saga | saga, orchestration, managing, distributed, transactions, long, running, business, processes | +| `seo-plan` | Strategic SEO planning for new or existing websites. Industry-specific templates, competitive analysis, content strategy, and implementation roadmap. Use whe... | seo, plan | seo, plan, strategic, planning, new, existing, websites, industry, specific, competitive, analysis, content | | `shadcn` | Manages shadcn/ui components and projects, providing context, documentation, and usage patterns for building modern design systems. | shadcn | shadcn, manages, ui, components, providing, context, documentation, usage, building | +| `site-architecture` | Plan or restructure website hierarchy, navigation, URL patterns, breadcrumbs, and internal linking. Use when mapping pages, sections, and site structure, but... | site, architecture | site, architecture, plan, restructure, website, hierarchy, navigation, url, breadcrumbs, internal, linking, mapping | | `slack-bot-builder` | The Bolt framework is Slack's recommended approach for building apps. It handles authentication, event routing, request verification, and HTTP request proces... | slack, bot, builder | slack, bot, builder, bolt, framework, recommended, approach, building, apps, authentication, event, routing | | `software-architecture` | Guide for quality focused software architecture. This skill should be used when users want to write code, design architecture, analyze code, in any case that... | software, architecture | software, architecture, quality, skill, should, used, users, want, write, code, analyze, any | | `tailwind-design-system` | Build production-ready design systems with Tailwind CSS, including design tokens, component variants, responsive patterns, and accessibility. | tailwind | tailwind, css, including, tokens, component, variants, responsive, accessibility | @@ -94,7 +96,7 @@ Total skills: 1273 | `workflow-orchestration-patterns` | Master workflow orchestration architecture with Temporal, covering fundamental design decisions, resilience patterns, and best practices for building reliabl... | | orchestration, architecture, temporal, covering, fundamental, decisions, resilience, building, reliable, distributed | | `workflow-patterns` | Use this skill when implementing tasks according to Conductor's TDD workflow, handling phase checkpoints, managing git commits for tasks, or understanding th... | | skill, implementing, tasks, according, conductor, tdd, handling, phase, checkpoints, managing, git, commits | -## business (60) +## business (69) | Skill | Description | Tags | Triggers | | --- | --- | --- | --- | @@ -135,17 +137,26 @@ Total skills: 1273 | `product-design` | Design de produto nivel Apple — sistemas visuais, UX flows, acessibilidade, linguagem visual proprietaria, design tokens, prototipagem e handoff. Cobre Figma... | design, ux, design-systems, accessibility, figma | design, ux, design-systems, accessibility, figma, product, de, produto, nivel, apple, sistemas, visuais | | `product-inventor` | Product Inventor e Design Alchemist de nivel maximo — combina Product Thinking, Design Systems, UI Engineering, Psicologia Cognitiva, Storytelling e execucao... | product-thinking, innovation, ux-design, storytelling | product-thinking, innovation, ux-design, storytelling, product, inventor, alchemist, de, nivel, maximo, combina, thinking | | `product-manager-toolkit` | Essential tools and frameworks for modern product management, from discovery to delivery. | product, manager | product, manager, toolkit, essential, frameworks, discovery, delivery | +| `product-marketing-context` | Create or update a reusable product marketing context document with positioning, audience, ICP, use cases, and messaging. Use at the start of a project to av... | product, marketing | product, marketing, context, update, reusable, document, positioning, audience, icp, cases, messaging, start | +| `revops` | Design and improve revenue operations, lead lifecycle rules, scoring, routing, handoffs, and CRM process automation. Use when marketing, sales, and customer ... | revops | revops, improve, revenue, operations, lead, lifecycle, rules, scoring, routing, handoffs, crm, process | | `sales-automator` | Draft cold emails, follow-ups, and proposal templates. Creates pricing pages, case studies, and sales scripts. Use PROACTIVELY for sales outreach or lead nur... | sales, automator | sales, automator, draft, cold, emails, follow, ups, proposal, creates, pricing, pages, case | +| `sales-enablement` | Create sales collateral such as decks, one-pagers, objection docs, demo scripts, playbooks, and proposal templates. Use when a sales team needs assets that h... | sales, enablement | sales, enablement, collateral, such, decks, one, pagers, objection, docs, demo, scripts, playbooks | | `screenshots` | Generate marketing screenshots of your app using Playwright. Use when the user wants to create screenshots for Product Hunt, social media, landing pages, or ... | screenshots | screenshots, generate, marketing, app, playwright, user, wants, product, hunt, social, media, landing | | `seo-audit` | Diagnose and audit SEO issues affecting crawlability, indexation, rankings, and organic performance. | seo, audit | seo, audit, diagnose, issues, affecting, crawlability, indexation, rankings, organic, performance | | `seo-cannibalization-detector` | Analyzes multiple provided pages to identify keyword overlap and potential cannibalization issues. Suggests differentiation strategies. Use PROACTIVELY when ... | seo, cannibalization, detector | seo, cannibalization, detector, analyzes, multiple, provided, pages, identify, keyword, overlap, potential, issues | +| `seo-competitor-pages` | Generate SEO-optimized competitor comparison and alternatives pages. Covers "X vs Y" layouts, "alternatives to X" pages, feature matrices, schema markup, and... | seo, competitor, pages | seo, competitor, pages, generate, optimized, comparison, alternatives, covers, vs, layouts, feature, matrices | | `seo-content-auditor` | Analyzes provided content for quality, E-E-A-T signals, and SEO best practices. Scores content and provides improvement recommendations based on established ... | seo, content, auditor | seo, content, auditor, analyzes, provided, quality, signals, scores, provides, improvement, recommendations, established | | `seo-content-planner` | Creates comprehensive content outlines and topic clusters for SEO. Plans content calendars and identifies topic gaps. Use PROACTIVELY for content strategy an... | seo, content, planner | seo, content, planner, creates, outlines, topic, clusters, plans, calendars, identifies, gaps, proactively | | `seo-content-refresher` | Identifies outdated elements in provided content and suggests updates to maintain freshness. Finds statistics, dates, and examples that need updating. Use PR... | seo, content, refresher | seo, content, refresher, identifies, outdated, elements, provided, suggests, updates, maintain, freshness, finds | | `seo-content-writer` | Writes SEO-optimized content based on provided keywords and topic briefs. Creates engaging, comprehensive content following best practices. Use PROACTIVELY f... | seo, content, writer | seo, content, writer, writes, optimized, provided, keywords, topic, briefs, creates, engaging, following | | `seo-fundamentals` | Core principles of SEO including E-E-A-T, Core Web Vitals, technical foundations, content quality, and how modern search engines evaluate pages. | seo, fundamentals | seo, fundamentals, core, principles, including, web, vitals, technical, foundations, content, quality, how | +| `seo-hreflang` | Hreflang and international SEO audit, validation, and generation. Detects common mistakes, validates language/region codes, and generates correct hreflang im... | seo, hreflang | seo, hreflang, international, audit, validation, generation, detects, common, mistakes, validates, language, region | +| `seo-image-gen` | Generate SEO-focused images such as OG cards, hero images, schema assets, product visuals, and infographics. Use when image generation is part of an SEO work... | seo, image, gen | seo, image, gen, generate, images, such, og, cards, hero, schema, assets, product | +| `seo-images` | Image optimization analysis for SEO and performance. Checks alt text, file sizes, formats, responsive images, lazy loading, and CLS prevention. Use when user... | seo, images | seo, images, image, optimization, analysis, performance, checks, alt, text, file, sizes, formats | | `seo-keyword-strategist` | Analyzes keyword usage in provided content, calculates density, suggests semantic variations and LSI keywords based on the topic. Prevents over-optimization.... | seo, keyword, strategist | seo, keyword, strategist, analyzes, usage, provided, content, calculates, density, suggests, semantic, variations | | `seo-meta-optimizer` | Creates optimized meta titles, descriptions, and URL suggestions based on character limits and best practices. Generates compelling, keyword-rich metadata. U... | seo, meta, optimizer | seo, meta, optimizer, creates, optimized, titles, descriptions, url, suggestions, character, limits, generates | +| `seo-page` | Deep single-page SEO analysis covering on-page elements, content quality, technical meta tags, schema, images, and performance. Use when user says "analyze t... | seo, page | seo, page, deep, single, analysis, covering, elements, content, quality, technical, meta, tags | +| `seo-sitemap` | Analyze existing XML sitemaps or generate new ones with industry templates. Validates format, URLs, and structure. Use when user says "sitemap", "generate si... | seo, sitemap | seo, sitemap, analyze, existing, xml, sitemaps, generate, new, ones, industry, validates, format | | `seo-snippet-hunter` | Formats content to be eligible for featured snippets and SERP features. Creates snippet-optimized content blocks based on best practices. Use PROACTIVELY for... | seo, snippet, hunter | seo, snippet, hunter, formats, content, eligible, featured, snippets, serp, features, creates, optimized | | `seo-structure-architect` | Analyzes and optimizes content structure including header hierarchy, suggests schema markup, and internal linking opportunities. Creates search-friendly cont... | seo, structure | seo, structure, architect, analyzes, optimizes, content, including, header, hierarchy, suggests, schema, markup | | `social-content` | You are an expert social media strategist with direct access to a scheduling platform that publishes to all major social networks. Your goal is to help creat... | social, content | social, content, media, strategist, direct, access, scheduling, platform, publishes, all, major, networks | @@ -159,7 +170,7 @@ Total skills: 1273 | `warren-buffett` | Agente que simula Warren Buffett — o maior investidor do seculo XX e XXI, CEO da Berkshire Hathaway, discipulo de Benjamin Graham e socio intelectual de Char... | persona, investing, value-investing, business | persona, investing, value-investing, business, warren, buffett, agente, que, simula, maior, investidor, do | | `whatsapp-automation` | Automate WhatsApp Business tasks via Rube MCP (Composio): send messages, manage templates, upload media, and handle contacts. Always search tools first for c... | whatsapp | whatsapp, automation, automate, business, tasks, via, rube, mcp, composio, send, messages, upload | -## data-ai (235) +## data-ai (244) | Skill | Description | Tags | Triggers | | --- | --- | --- | --- | @@ -177,6 +188,7 @@ Total skills: 1273 | `ai-ml` | AI and machine learning workflow covering LLM application development, RAG implementation, agent architecture, ML pipelines, and AI-powered features. | ai, ml | ai, ml, machine, learning, covering, llm, application, development, rag, agent, architecture, pipelines | | `ai-native-cli` | Design spec with 98 rules for building CLI tools that AI agents can safely use. Covers structured JSON output, error handling, input contracts, safety guardr... | ai, native, cli | ai, native, cli, spec, 98, rules, building, agents, safely, covers, structured, json | | `ai-product` | You are an AI product engineer who has shipped LLM features to millions of users. You've debugged hallucinations at 3am, optimized prompts to reduce costs by... | ai, product | ai, product, engineer, who, shipped, llm, features, millions, users, ve, debugged, hallucinations | +| `ai-seo` | Optimize content for AI search and LLM citations across AI Overviews, ChatGPT, Perplexity, Claude, Gemini, and similar systems. Use when improving AI visibil... | ai, seo | ai, seo, optimize, content, search, llm, citations, overviews, chatgpt, perplexity, claude, gemini | | `ai-studio-image` | Geracao de imagens humanizadas via Google AI Studio (Gemini). Fotos realistas estilo influencer ou educacional com iluminacao natural e imperfeicoes sutis. | image-generation, ai-studio, google, photography | image-generation, ai-studio, google, photography, ai, studio, image, geracao, de, imagens, humanizadas, via | | `ai-wrapper-product` | You know AI wrappers get a bad rap, but the good ones solve real problems. You build products where AI is the engine, not the gimmick. You understand prompt ... | ai, wrapper, product | ai, wrapper, product, know, wrappers, get, bad, rap, good, ones, solve, real | | `alpha-vantage` | Access 20+ years of global financial data: equities, options, forex, crypto, commodities, economic indicators, and 50+ technical indicators. | alpha, vantage | alpha, vantage, access, 20, years, global, financial, data, equities, options, forex, crypto | @@ -256,6 +268,7 @@ Total skills: 1273 | `cirq` | Cirq is Google Quantum AI's open-source framework for designing, simulating, and running quantum circuits on quantum computers and simulators. | cirq | cirq, google, quantum, ai, open, source, framework, designing, simulating, running, circuits, computers | | `claimable-postgres` | Provision instant temporary Postgres databases via Claimable Postgres by Neon (pg.new). No login or credit card required. Use for quick Postgres environments... | claimable, postgres | claimable, postgres, provision, instant, temporary, databases, via, neon, pg, new, no, login | | `clarity-gate` | Pre-ingestion verification for epistemic quality in RAG systems. Ensures documents are properly qualified before entering knowledge bases. Produces CGD (Clar... | clarity, gate | clarity, gate, pre, ingestion, verification, epistemic, quality, rag, ensures, documents, properly, qualified | +| `claude-api` | Build apps with the Claude API or Anthropic SDK. TRIGGER when: code imports `anthropic`/`@anthropic-ai/sdk`/`claude_agent_sdk`, or user asks to use Claude AP... | claude, api | claude, api, apps, anthropic, sdk, trigger, code, imports, ai, agent, user, asks | | `claude-d3js-skill` | This skill provides guidance for creating sophisticated, interactive data visualisations using d3.js. | claude, d3js, skill | claude, d3js, skill, provides, guidance, creating, sophisticated, interactive, data, visualisations, d3, js | | `code-documentation-doc-generate` | You are a documentation expert specializing in creating comprehensive, maintainable documentation from code. Generate API docs, architecture diagrams, user g... | code, documentation, doc, generate | code, documentation, doc, generate, specializing, creating, maintainable, api, docs, architecture, diagrams, user | | `code-reviewer` | Elite code review expert specializing in modern AI-powered code | code | code, reviewer, elite, review, specializing, ai, powered | @@ -336,6 +349,7 @@ Total skills: 1273 | `neon-postgres` | Configure Prisma for Neon with connection pooling. | neon, postgres | neon, postgres, configure, prisma, connection, pooling | | `nestjs-expert` | You are an expert in Nest.js with deep knowledge of enterprise-grade Node.js application architecture, dependency injection patterns, decorators, middleware,... | nestjs | nestjs, nest, js, deep, knowledge, enterprise, grade, node, application, architecture, dependency, injection | | `nextjs-best-practices` | Next.js App Router principles. Server Components, data fetching, routing patterns. | nextjs, best, practices | nextjs, best, practices, next, js, app, router, principles, server, components, data, fetching | +| `obsidian-bases` | Create and edit Obsidian Bases (.base files) with views, filters, formulas, and summaries. Use when working with .base files, creating database-like views of... | obsidian, bases | obsidian, bases, edit, base, files, views, filters, formulas, summaries, working, creating, database | | `odoo-edi-connector` | Guide for implementing EDI (Electronic Data Interchange) with Odoo: X12, EDIFACT document mapping, partner onboarding, and automated order processing. | odoo, edi, connector | odoo, edi, connector, implementing, electronic, data, interchange, x12, edifact, document, mapping, partner | | `odoo-inventory-optimizer` | Expert guide for Odoo Inventory: stock valuation (FIFO/AVCO), reordering rules, putaway strategies, routes, and multi-warehouse configuration. | odoo, inventory, optimizer | odoo, inventory, optimizer, stock, valuation, fifo, avco, reordering, rules, putaway, routes, multi | | `php-pro` | Write idiomatic PHP code with generators, iterators, SPL data structures, and modern OOP features. Use PROACTIVELY for high-performance PHP applications. | php | php, pro, write, idiomatic, code, generators, iterators, spl, data, structures, oop, features | @@ -366,6 +380,12 @@ Total skills: 1273 | `seek-and-analyze-video` | Seek and analyze video content using Memories.ai Large Visual Memory Model for persistent video intelligence | video, ai, memories, social-media, youtube, tiktok, analysis | video, ai, memories, social-media, youtube, tiktok, analysis, seek, analyze, content, large, visual | | `segment-cdp` | Client-side tracking with Analytics.js. Include track, identify, page, and group calls. Anonymous ID persists until identify merges with user. | segment, cdp | segment, cdp, client, side, tracking, analytics, js, include, track, identify, page, group | | `sendgrid-automation` | Automate SendGrid email delivery workflows including marketing campaigns (Single Sends), contact and list management, sender identity setup, and email analyt... | sendgrid | sendgrid, automation, automate, email, delivery, including, marketing, campaigns, single, sends, contact, list | +| `seo` | Run a broad SEO audit across technical SEO, on-page SEO, schema, sitemaps, content quality, AI search readiness, and GEO. Use as the umbrella skill when the ... | seo | seo, run, broad, audit, technical, page, schema, sitemaps, content, quality, ai, search | +| `seo-content` | Content quality and E-E-A-T analysis with AI citation readiness assessment. Use when user says "content quality", "E-E-A-T", "content analysis", "readability... | seo, content | seo, content, quality, analysis, ai, citation, readiness, assessment, user, says, readability, check | +| `seo-dataforseo` | Use DataForSEO for live SERPs, keyword metrics, backlinks, competitor analysis, on-page checks, and AI visibility data. Trigger when the user needs real SEO ... | seo, dataforseo | seo, dataforseo, live, serps, keyword, metrics, backlinks, competitor, analysis, page, checks, ai | +| `seo-geo` | Optimize content for AI Overviews, ChatGPT, Perplexity, and other AI search systems. Use when improving GEO, AI citations, llms.txt readiness, crawler access... | seo, geo | seo, geo, optimize, content, ai, overviews, chatgpt, perplexity, other, search, improving, citations | +| `seo-programmatic` | Plan and audit programmatic SEO pages generated at scale from structured data. Use when designing templates, URL systems, internal linking, quality gates, an... | seo, programmatic | seo, programmatic, plan, audit, pages, generated, scale, structured, data, designing, url, internal | +| `seo-schema` | Detect, validate, and generate Schema.org structured data. JSON-LD format preferred. Use when user says "schema", "structured data", "rich results", "JSON-LD... | seo, schema | seo, schema, detect, validate, generate, org, structured, data, json, ld, format, preferred | | `similarity-search-patterns` | Implement efficient similarity search with vector databases. Use when building semantic search, implementing nearest neighbor queries, or optimizing retrieva... | similarity, search | similarity, search, efficient, vector, databases, building, semantic, implementing, nearest, neighbor, queries, optimizing | | `skill-creator-ms` | Guide for creating effective skills for AI coding agents working with Azure SDKs and Microsoft Foundry services. Use when creating new skills or updating exi... | skill, creator, ms | skill, creator, ms, creating, effective, skills, ai, coding, agents, working, azure, sdks | | `skill-seekers` | -Automatically convert documentation websites, GitHub repositories, and PDFs into Claude AI skills in minutes. | skill, seekers | skill, seekers, automatically, convert, documentation, websites, github, repositories, pdfs, claude, ai, skills | @@ -582,7 +602,7 @@ Total skills: 1273 | `zod-validation-expert` | Expert in Zod — TypeScript-first schema validation. Covers parsing, custom errors, refinements, type inference, and integration with React Hook Form, Next.js... | zod, validation | zod, validation, typescript, first, schema, covers, parsing, custom, errors, refinements, type, inference | | `zustand-store-ts` | Create Zustand stores following established patterns with proper TypeScript types and middleware. | zustand, store, ts | zustand, store, ts, stores, following, established, proper, typescript, types, middleware | -## general (308) +## general (316) | Skill | Description | Tags | Triggers | | --- | --- | --- | --- | @@ -633,6 +653,7 @@ Total skills: 1273 | `cc-skill-continuous-learning` | Development skill from everything-claude-code | cc, skill, continuous, learning | cc, skill, continuous, learning, development, everything, claude, code | | `cc-skill-project-guidelines-example` | Project Guidelines Skill (Example) | cc, skill, guidelines, example | cc, skill, guidelines, example | | `cc-skill-strategic-compact` | Development skill from everything-claude-code | cc, skill, strategic, compact | cc, skill, strategic, compact, development, everything, claude, code | +| `churn-prevention` | Reduce voluntary and involuntary churn with cancel flows, save offers, dunning, win-back tactics, and retention strategy. Use when users are cancelling, fail... | churn, prevention | churn, prevention, reduce, voluntary, involuntary, cancel, flows, save, offers, dunning, win, back | | `claude-ally-health` | A health assistant skill for medical information analysis, symptom tracking, and wellness guidance. | claude, ally, health | claude, ally, health, assistant, skill, medical, information, analysis, symptom, tracking, wellness, guidance | | `claude-code-expert` | Especialista profundo em Claude Code - CLI da Anthropic. Maximiza produtividade com atalhos, hooks, MCPs, configuracoes avancadas, workflows, CLAUDE.md, memo... | claude-code, productivity, cli, configuration | claude-code, productivity, cli, configuration, claude, code, especialista, profundo, em, da, anthropic, maximiza | | `claude-in-chrome-troubleshooting` | Diagnose and fix Claude in Chrome MCP extension connectivity issues. Use when mcp__claude-in-chrome__* tools fail, return "Browser extension is not connected... | claude, in, chrome, troubleshooting | claude, in, chrome, troubleshooting, diagnose, fix, mcp, extension, connectivity, issues, fail, return | @@ -648,10 +669,12 @@ Total skills: 1273 | `code-review-excellence` | Transform code reviews from gatekeeping to knowledge sharing through constructive feedback, systematic analysis, and collaborative improvement. | code, excellence | code, excellence, review, transform, reviews, gatekeeping, knowledge, sharing, through, constructive, feedback, systematic | | `code-simplifier` | Simplifies and refines code for clarity, consistency, and maintainability while preserving all functionality. Use when asked to "simplify code", "clean up co... | code, simplifier | code, simplifier, simplifies, refines, clarity, consistency, maintainability, while, preserving, all, functionality, asked | | `codebase-cleanup-tech-debt` | You are a technical debt expert specializing in identifying, quantifying, and prioritizing technical debt in software projects. Analyze the codebase to uncov... | codebase, cleanup, tech, debt | codebase, cleanup, tech, debt, technical, specializing, identifying, quantifying, prioritizing, software, analyze, uncover | +| `cold-email` | Write B2B cold emails and follow-up sequences that earn replies. Use when creating outbound prospecting emails, SDR outreach, personalized opening lines, sub... | cold, email | cold, email, write, b2b, emails, follow, up, sequences, earn, replies, creating, outbound | | `commit` | ALWAYS use this skill when committing code changes — never commit directly without it. Creates commits following Sentry conventions with proper conventional ... | commit | commit, always, skill, committing, code, changes, never, directly, without, creates, commits, following | | `comprehensive-review-full-review` | Use when working with comprehensive review full review | comprehensive, full | comprehensive, full, review, working | | `computer-vision-expert` | SOTA Computer Vision Expert (2026). Specialized in YOLO26, Segment Anything 3 (SAM 3), Vision Language Models, and real-time spatial analysis. | computer, vision | computer, vision, sota, 2026, specialized, yolo26, segment, anything, sam, language, models, real | | `concise-planning` | Use when a user asks for a plan for a coding task, to generate a clear, actionable, and atomic checklist. | concise, planning | concise, planning, user, asks, plan, coding, task, generate, clear, actionable, atomic, checklist | +| `content-strategy` | Plan a content strategy, topic clusters, editorial roadmap, and content mix for traffic, authority, and lead generation. Use when deciding what to publish, w... | content | content, plan, topic, clusters, editorial, roadmap, mix, traffic, authority, lead, generation, deciding | | `context-agent` | Agente de contexto para continuidade entre sessoes. Salva resumos, decisoes, tarefas pendentes e carrega briefing automatico na sessao seguinte. | context, session-management, continuity, memory | context, session-management, continuity, memory, agent, agente, de, contexto, para, continuidade, entre, sessoes | | `context-compression` | When agent sessions generate millions of tokens of conversation history, compression becomes mandatory. The naive approach is aggressive compression to minim... | compression | compression, context, agent, sessions, generate, millions, tokens, conversation, history, becomes, mandatory, naive | | `context-fundamentals` | Context is the complete state available to a language model at inference time. It includes everything the model can attend to when generating responses: syst... | fundamentals | fundamentals, context, complete, state, available, language, model, inference, time, includes, everything, attend | @@ -667,6 +690,7 @@ Total skills: 1273 | `debugging-strategies` | Transform debugging from frustrating guesswork into systematic problem-solving with proven strategies, powerful tools, and methodical approaches. | debugging, strategies | debugging, strategies, transform, frustrating, guesswork, systematic, problem, solving, proven, powerful, methodical, approaches | | `debugging-toolkit-smart-debug` | Use when working with debugging toolkit smart debug | debugging, debug | debugging, debug, toolkit, smart, working | | `deep-research` | Run autonomous research tasks that plan, search, read, and synthesize information into comprehensive reports. | deep, research | deep, research, run, autonomous, tasks, plan, search, read, synthesize, information, reports | +| `defuddle` | Extract clean markdown content from web pages using Defuddle CLI, removing clutter and navigation to save tokens. Use instead of WebFetch when the user provi... | defuddle | defuddle, extract, clean, markdown, content, web, pages, cli, removing, clutter, navigation, save | | `design-md` | Analyze Stitch projects and synthesize a semantic design system into DESIGN.md files | md | md, analyze, stitch, synthesize, semantic, files | | `design-spells` | Curated micro-interactions and design details that add "magic" and personality to websites and apps. | spells | spells, curated, micro, interactions, details, add, magic, personality, websites, apps | | `diary` | Unified Diary System: A context-preserving automated logger for multi-project development. | diary | diary, unified, context, preserving, automated, logger, multi, development | @@ -748,9 +772,11 @@ Total skills: 1273 | `interview-coach` | Full job search coaching system — JD decoding, resume, storybank, mock interviews, transcript analysis, comp negotiation. 23 commands, persistent state. | interview, job-search, coaching, career, storybank, negotiation | interview, job-search, coaching, career, storybank, negotiation, coach, full, job, search, jd, decoding | | `inventory-demand-planning` | Codified expertise for demand forecasting, safety stock optimisation, replenishment planning, and promotional lift estimation at multi-location retailers. | inventory, demand, planning | inventory, demand, planning, codified, expertise, forecasting, safety, stock, optimisation, replenishment, promotional, lift | | `issues` | Interact with GitHub issues - create, list, and view issues. | issues | issues, interact, github, list, view | +| `json-canvas` | Create and edit JSON Canvas files (.canvas) with nodes, edges, groups, and connections. Use when working with .canvas files, creating visual canvases, mind m... | json, canvas | json, canvas, edit, files, nodes, edges, groups, connections, working, creating, visual, canvases | | `julia-pro` | Master Julia 1.10+ with modern features, performance optimization, multiple dispatch, and production-ready practices. | julia | julia, pro, 10, features, performance, optimization, multiple, dispatch | | `last30days` | Research a topic from the last 30 days on Reddit + X + Web, become an expert, and write copy-paste-ready prompts for the user's target tool. | last30days | last30days, research, topic, last, 30, days, reddit, web, become, write, copy, paste | | `latex-paper-conversion` | This skill should be used when the user asks to convert an academic paper in LaTeX from one format (e.g., Springer, IPOL) to another format (e.g., MDPI, IEEE... | latex, paper, conversion | latex, paper, conversion, skill, should, used, user, asks, convert, academic, one, format | +| `lead-magnets` | Plan and optimize lead magnets for email capture and lead generation. Use when designing gated content, checklists, templates, downloadable resources, or oth... | lead, magnets | lead, magnets, plan, optimize, email, capture, generation, designing, gated, content, checklists, downloadable | | `legacy-modernizer` | Refactor legacy codebases, migrate outdated frameworks, and implement gradual modernization. Handles technical debt, dependency updates, and backward compati... | legacy, modernizer | legacy, modernizer, refactor, codebases, migrate, outdated, frameworks, gradual, modernization, technical, debt, dependency | | `leiloeiro-avaliacao` | Avaliacao pericial de imoveis em leilao. Valor de mercado, liquidacao forcada, ABNT NBR 14653, metodos comparativo/renda/custo, CUB e margem de seguranca. | real-estate, valuation, appraisal, brazilian | real-estate, valuation, appraisal, brazilian, leiloeiro, avaliacao, pericial, de, imoveis, em, leilao, valor | | `leiloeiro-ia` | Especialista em leiloes judiciais e extrajudiciais de imoveis. Analise juridica, pericial e de mercado integrada. Orquestra os 5 modulos especializados. | auction, ai-analysis, real-estate, brazilian | auction, ai-analysis, real-estate, brazilian, leiloeiro, ia, especialista, em, leiloes, judiciais, extrajudiciais, de | @@ -782,7 +808,9 @@ Total skills: 1273 | `nosql-expert` | Expert guidance for distributed NoSQL databases (Cassandra, DynamoDB). Focuses on mental models, query-first modeling, single-table design, and avoiding hot ... | nosql | nosql, guidance, distributed, databases, cassandra, dynamodb, mental, models, query, first, modeling, single | | `notebooklm` | Interact with Google NotebookLM to query documentation with Gemini's source-grounded answers. Each question opens a fresh browser session, retrieves the answ... | notebooklm | notebooklm, interact, google, query, documentation, gemini, source, grounded, answers, each, question, opens | | `nutrition-analyzer` | 分析营养数据、识别营养模式、评估营养状况，并提供个性化营养建议。支持与运动、睡眠、慢性病数据的关联分析。 | nutrition, analyzer | nutrition, analyzer | +| `obsidian-cli` | Use the Obsidian CLI to read, create, search, and manage vault content, or to develop and debug Obsidian plugins and themes from the command line. | obsidian, cli | obsidian, cli, read, search, vault, content, develop, debug, plugins, themes, command, line | | `obsidian-clipper-template-creator` | Guide for creating templates for the Obsidian Web Clipper. Use when you want to create a new clipping template, understand available variables, or format cli... | obsidian, clipper, creator | obsidian, clipper, creator, creating, web, want, new, clipping, understand, available, variables, format | +| `obsidian-markdown` | Create and edit Obsidian Flavored Markdown with wikilinks, embeds, callouts, properties, and other Obsidian-specific syntax. Use when working with .md files ... | obsidian, markdown | obsidian, markdown, edit, flavored, wikilinks, embeds, callouts, properties, other, specific, syntax, working | | `occupational-health-analyzer` | 分析职业健康数据、识别工作相关健康风险、评估职业健康状况、提供个性化职业健康建议。支持与睡眠、运动、心理健康等其他健康数据的关联分析。 | occupational, health, analyzer | occupational, health, analyzer | | `odoo-accounting-setup` | Expert guide for configuring Odoo Accounting: chart of accounts, journals, fiscal positions, taxes, payment terms, and bank reconciliation. | odoo, accounting, setup | odoo, accounting, setup, configuring, chart, accounts, journals, fiscal, positions, taxes, payment, terms | | `odoo-manufacturing-advisor` | Expert guide for Odoo Manufacturing: Bills of Materials (BoM), Work Centers, routings, MRP planning, and production order workflows. | odoo, manufacturing, advisor | odoo, manufacturing, advisor, bills, materials, bom, work, centers, routings, mrp, planning, order | @@ -1019,7 +1047,7 @@ Total skills: 1273 | `whatsapp-cloud-api` | Integracao com WhatsApp Business Cloud API (Meta). Mensagens, templates, webhooks HMAC-SHA256, automacao de atendimento. Boilerplates Node.js e Python. | messaging, whatsapp, meta, webhooks | messaging, whatsapp, meta, webhooks, cloud, api, integracao, com, business, mensagens, hmac, sha256 | | `x-twitter-scraper` | X (Twitter) data platform skill — tweet search, user lookup, follower extraction, engagement metrics, giveaway draws, monitoring, webhooks, 19 extraction too... | [twitter, x-api, scraping, mcp, social-media, data-extraction, giveaway, monitoring, webhooks] | [twitter, x-api, scraping, mcp, social-media, data-extraction, giveaway, monitoring, webhooks], twitter, scraper, data | -## security (159) +## security (161) | Skill | Description | Tags | Triggers | | --- | --- | --- | --- | @@ -1091,6 +1119,7 @@ Total skills: 1273 | `incident-response-incident-response` | Use when working with incident response incident response | incident, response | incident, response, working | | `incident-response-smart-fix` | [Extended thinking: This workflow implements a sophisticated debugging and resolution pipeline that leverages AI-assisted debugging tools and observability p... | incident, response, fix | incident, response, fix, smart, extended, thinking, implements, sophisticated, debugging, resolution, pipeline, leverages | | `incident-runbook-templates` | Production-ready templates for incident response runbooks covering detection, triage, mitigation, resolution, and communication. | incident, runbook | incident, runbook, response, runbooks, covering, detection, triage, mitigation, resolution, communication | +| `internal-comms` | Write internal communications such as status reports, leadership updates, 3P updates, newsletters, FAQs, incident reports, and project updates using repeatab... | internal, comms | internal, comms, write, communications, such, status, reports, leadership, updates, 3p, newsletters, faqs | | `k8s-manifest-generator` | Step-by-step guidance for creating production-ready Kubernetes manifests including Deployments, Services, ConfigMaps, Secrets, and PersistentVolumeClaims. | k8s, manifest, generator | k8s, manifest, generator, step, guidance, creating, kubernetes, manifests, including, deployments, configmaps, secrets | | `k8s-security-policies` | Comprehensive guide for implementing NetworkPolicy, PodSecurityPolicy, RBAC, and Pod Security Standards in Kubernetes. | k8s, security, policies | k8s, security, policies, implementing, networkpolicy, podsecuritypolicy, rbac, pod, standards, kubernetes | | `laravel-expert` | Senior Laravel Engineer role for production-grade, maintainable, and idiomatic Laravel solutions. Focuses on clean architecture, security, performance, and m... | laravel | laravel, senior, engineer, role, grade, maintainable, idiomatic, solutions, clean, architecture, security, performance | @@ -1153,6 +1182,7 @@ Total skills: 1273 | `semgrep-rule-creator` | Creates custom Semgrep rules for detecting security vulnerabilities, bug patterns, and code patterns. Use when writing Semgrep rules or building custom stati... | semgrep, rule, creator | semgrep, rule, creator, creates, custom, rules, detecting, security, vulnerabilities, bug, code, writing | | `seo-authority-builder` | Analyzes content for E-E-A-T signals and suggests improvements to build authority and trust. Identifies missing credibility elements. Use PROACTIVELY for YMY... | seo, authority, builder | seo, authority, builder, analyzes, content, signals, suggests, improvements, trust, identifies, missing, credibility | | `seo-forensic-incident-response` | Investigate sudden drops in organic traffic or rankings and run a structured forensic SEO incident response with triage, root-cause analysis and recovery plan. | seo, forensic, incident, response | seo, forensic, incident, response, investigate, sudden, drops, organic, traffic, rankings, run, structured | +| `seo-technical` | Audit technical SEO across crawlability, indexability, security, URLs, mobile, Core Web Vitals, structured data, JavaScript rendering, and related platform s... | seo, technical | seo, technical, audit, crawlability, indexability, security, urls, mobile, core, web, vitals, structured | | `service-mesh-expert` | Expert service mesh architect specializing in Istio, Linkerd, and cloud-native networking patterns. Masters traffic management, security policies, observabil... | service, mesh | service, mesh, architect, specializing, istio, linkerd, cloud, native, networking, masters, traffic, security | | `skill-creator` | To create new CLI skills following Anthropic's official best practices with zero manual configuration. This skill automates brainstorming, template applicati... | [automation, scaffolding, skill-creation, meta-skill] | [automation, scaffolding, skill-creation, meta-skill], skill, creator, new, cli, skills, following, anthropic, official | | `skill-scanner` | Scan agent skills for security issues before adoption. Detects prompt injection, malicious code, excessive permissions, secret exposure, and supply chain risks. | skill, scanner | skill, scanner, scan, agent, skills, security, issues, before, adoption, detects, prompt, injection | @@ -1183,11 +1213,12 @@ Total skills: 1273 | `xss-html-injection` | Execute comprehensive client-side injection vulnerability assessments on web applications to identify XSS and HTML injection flaws, demonstrate exploitation ... | xss, html, injection | xss, html, injection, execute, client, side, vulnerability, assessments, web, applications, identify, flaws | | `zeroize-audit` | Detects missing zeroization of sensitive data in source code and identifies zeroization removed by compiler optimizations, with assembly-level analysis, and ... | zeroize, audit | zeroize, audit, detects, missing, zeroization, sensitive, data, source, code, identifies, removed, compiler | -## testing (30) +## testing (31) | Skill | Description | Tags | Triggers | | --- | --- | --- | --- | | `ab-test-setup` | Structured guide for setting up A/B tests with mandatory gates for hypothesis, metrics, and execution readiness. | ab, setup | ab, setup, test, structured, setting, up, tests, mandatory, gates, hypothesis, metrics, execution | +| `ad-creative` | Create, iterate, and scale paid ad creative for Google Ads, Meta, LinkedIn, TikTok, and similar platforms. Use when generating headlines, descriptions, prima... | ad, creative | ad, creative, iterate, scale, paid, google, ads, meta, linkedin, tiktok, similar, platforms | | `circleci-automation` | Automate CircleCI tasks via Rube MCP (Composio): trigger pipelines, monitor workflows/jobs, retrieve artifacts and test metadata. Always search tools first f... | circleci | circleci, automation, automate, tasks, via, rube, mcp, composio, trigger, pipelines, monitor, jobs | | `conductor-implement` | Execute tasks from a track's implementation plan following TDD workflow | conductor, implement | conductor, implement, execute, tasks, track, plan, following, tdd | | `conductor-revert` | Git-aware undo by logical work unit (track, phase, or task) | conductor, revert | conductor, revert, git, aware, undo, logical, work, unit, track, phase, task | diff --git a/README.md b/README.md index b28d5a7a..d54a4016 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@ - -# 🌌 Antigravity Awesome Skills: 1,273+ Agentic Skills for Claude Code, Gemini CLI, Cursor, Copilot & More + +# 🌌 Antigravity Awesome Skills: 1,304+ Agentic Skills for Claude Code, Gemini CLI, Cursor, Copilot & More > **Installable GitHub library of 1,273+ agentic skills for Claude Code, Cursor, Codex CLI, Gemini CLI, Antigravity, and other AI coding assistants.** @@ -43,7 +43,7 @@ Antigravity Awesome Skills is a GitHub repository and installer CLI for reusable - [🧭 Antigravity Workflows](#antigravity-workflows) - [⚖️ Alternatives & Comparisons](#alternatives--comparisons) - [📦 Features & Categories](#features--categories) -- [📚 Browse 1,273+ Skills](#browse-1273-skills) +- [📚 Browse 1,304+ Skills](#browse-1304-skills) - [🤝 Contributing](#contributing) - [💬 Community](#community) - [☕ Support the Project](#support-the-project) @@ -330,7 +330,7 @@ The repository is organized into specialized domains to transform your AI into a Counts change as new skills are added. For the current full registry, see [CATALOG.md](CATALOG.md). -## Browse 1,273+ Skills +## Browse 1,304+ Skills - Open the interactive browser in [`apps/web-app`](apps/web-app). - Read the full catalog in [`CATALOG.md`](CATALOG.md). diff --git a/data/bundles.json b/data/bundles.json index 7bb49ddb..19ac85c3 100644 --- a/data/bundles.json +++ b/data/bundles.json @@ -115,6 +115,7 @@ "cc-skill-frontend-patterns", "cc-skill-security-review", "cdk-patterns", + "claude-api", "claude-monitor", "code-documentation-doc-generate", "comfyui-gateway", @@ -262,6 +263,7 @@ "security-audit", "security/aws-secrets-rotation", "senior-frontend", + "seo-technical", "shopify-apps", "shopify-development", "spline-3d-integration", @@ -408,6 +410,7 @@ "security/aws-secrets-rotation", "security/aws-security-audit", "semgrep-rule-creator", + "seo-technical", "service-mesh-expert", "skill-scanner", "smtp-penetration-testing", @@ -519,6 +522,7 @@ "cc-skill-backend-patterns", "cc-skill-clickhouse-io", "claimable-postgres", + "claude-api", "claude-d3js-skill", "constant-time-analysis", "content-marketer", @@ -569,6 +573,7 @@ "neon-postgres", "nestjs-expert", "nextjs-best-practices", + "obsidian-bases", "odoo-automated-tests", "odoo-backup-strategy", "odoo-edi-connector", @@ -596,6 +601,10 @@ "schema-markup", "segment-cdp", "sendgrid-automation", + "seo-dataforseo", + "seo-programmatic", + "seo-schema", + "seo-technical", "skin-health-analyzer", "spark-optimization", "sql-injection-testing", @@ -670,6 +679,7 @@ "incident-response-incident-response", "incident-response-smart-fix", "incident-runbook-templates", + "internal-comms", "kubernetes-architect", "kubernetes-deployment", "langfuse", @@ -843,6 +853,7 @@ "rag-implementation", "reddit-automation", "render-automation", + "revops", "salesforce-automation", "scroll-experience", "security-audit", @@ -850,6 +861,7 @@ "segment-automation", "sendgrid-automation", "sentry-automation", + "seo-image-gen", "shopify-apps", "shopify-automation", "shopify-development", @@ -1076,6 +1088,7 @@ "pipedrive-automation", "plaid-fintech", "pricing-strategy", + "revops", "shopify-apps", "shopify-automation", "shopify-development", @@ -1120,6 +1133,7 @@ "native-data-fetching", "odoo-docker-deployment", "react-native-architecture", + "seo-technical", "stitch-ui-design", "swiftui-expert-skill", "ui-ux-pro-max", @@ -1129,12 +1143,15 @@ "seo-core": { "description": "SEO, search visibility, and structured content optimization.", "skills": [ + "ad-creative", "agent-orchestrator", + "ai-seo", "analyze-project", "antigravity-skill-orchestrator", "apify-actor-development", "content-creator", "content-marketer", + "content-strategy", "convex", "database-architect", "database-design", @@ -1153,19 +1170,34 @@ "prisma-expert", "programmatic-seo", "schema-markup", + "seo", "seo-audit", "seo-authority-builder", "seo-cannibalization-detector", + "seo-competitor-pages", + "seo-content", "seo-content-auditor", "seo-content-planner", "seo-content-refresher", "seo-content-writer", + "seo-dataforseo", "seo-forensic-incident-response", "seo-fundamentals", + "seo-geo", + "seo-hreflang", + "seo-image-gen", + "seo-images", "seo-keyword-strategist", "seo-meta-optimizer", + "seo-page", + "seo-plan", + "seo-programmatic", + "seo-schema", + "seo-sitemap", "seo-snippet-hunter", "seo-structure-architect", + "seo-technical", + "site-architecture", "whatsapp-cloud-api", "yann-lecun", "zod-validation-expert" diff --git a/data/catalog.json b/data/catalog.json index 6ff85e44..b48bdc74 100644 --- a/data/catalog.json +++ b/data/catalog.json @@ -1,6 +1,6 @@ { "generatedAt": "2026-02-08T00:00:00.000Z", - "total": 1273, + "total": 1304, "skills": [ { "id": "00-andruia-consultant", @@ -263,6 +263,31 @@ ], "path": "skills/activecampaign-automation/SKILL.md" }, + { + "id": "ad-creative", + "name": "ad-creative", + "description": "Create, iterate, and scale paid ad creative for Google Ads, Meta, LinkedIn, TikTok, and similar platforms. Use when generating headlines, descriptions, primary text, or large sets of ad variations for testing and performance optimization.", + "category": "testing", + "tags": [ + "ad", + "creative" + ], + "triggers": [ + "ad", + "creative", + "iterate", + "scale", + "paid", + "google", + "ads", + "meta", + "linkedin", + "tiktok", + "similar", + "platforms" + ], + "path": "skills/ad-creative/SKILL.md" + }, { "id": "address-github-comments", "name": "address-github-comments", @@ -938,6 +963,31 @@ ], "path": "skills/ai-product/SKILL.md" }, + { + "id": "ai-seo", + "name": "ai-seo", + "description": "Optimize content for AI search and LLM citations across AI Overviews, ChatGPT, Perplexity, Claude, Gemini, and similar systems. Use when improving AI visibility, answer engine optimization, or citation readiness.", + "category": "data-ai", + "tags": [ + "ai", + "seo" + ], + "triggers": [ + "ai", + "seo", + "optimize", + "content", + "search", + "llm", + "citations", + "overviews", + "chatgpt", + "perplexity", + "claude", + "gemini" + ], + "path": "skills/ai-seo/SKILL.md" + }, { "id": "ai-studio-image", "name": "ai-studio-image", @@ -7604,6 +7654,31 @@ ], "path": "skills/chrome-extension-developer/SKILL.md" }, + { + "id": "churn-prevention", + "name": "churn-prevention", + "description": "Reduce voluntary and involuntary churn with cancel flows, save offers, dunning, win-back tactics, and retention strategy. Use when users are cancelling, failed payments are rising, or subscription retention needs improvement.", + "category": "general", + "tags": [ + "churn", + "prevention" + ], + "triggers": [ + "churn", + "prevention", + "reduce", + "voluntary", + "involuntary", + "cancel", + "flows", + "save", + "offers", + "dunning", + "win", + "back" + ], + "path": "skills/churn-prevention/SKILL.md" + }, { "id": "cicd-automation-workflow-automate", "name": "cicd-automation-workflow-automate", @@ -7772,6 +7847,31 @@ ], "path": "skills/claude-ally-health/SKILL.md" }, + { + "id": "claude-api", + "name": "claude-api", + "description": "Build apps with the Claude API or Anthropic SDK. TRIGGER when: code imports `anthropic`/`@anthropic-ai/sdk`/`claude_agent_sdk`, or user asks to use Claude API, Anthropic SDKs, or Agent SDK. DO NOT TRIGGER when: code imports `openai`/other AI SDK, general programming, or ML/data-science tasks.", + "category": "data-ai", + "tags": [ + "claude", + "api" + ], + "triggers": [ + "claude", + "api", + "apps", + "anthropic", + "sdk", + "trigger", + "code", + "imports", + "ai", + "agent", + "user", + "asks" + ], + "path": "skills/claude-api/SKILL.md" + }, { "id": "claude-code-expert", "name": "claude-code-expert", @@ -8644,6 +8744,31 @@ ], "path": "skills/codex-review/SKILL.md" }, + { + "id": "cold-email", + "name": "cold-email", + "description": "Write B2B cold emails and follow-up sequences that earn replies. Use when creating outbound prospecting emails, SDR outreach, personalized opening lines, subject lines, CTAs, and multi-touch follow-up sequences.", + "category": "general", + "tags": [ + "cold", + "email" + ], + "triggers": [ + "cold", + "email", + "write", + "b2b", + "emails", + "follow", + "up", + "sequences", + "earn", + "replies", + "creating", + "outbound" + ], + "path": "skills/cold-email/SKILL.md" + }, { "id": "comfyui-gateway", "name": "comfyui-gateway", @@ -9116,6 +9241,30 @@ ], "path": "skills/content-marketer/SKILL.md" }, + { + "id": "content-strategy", + "name": "content-strategy", + "description": "Plan a content strategy, topic clusters, editorial roadmap, and content mix for traffic, authority, and lead generation. Use when deciding what to publish, what topics to prioritize, or how to structure a content program.", + "category": "general", + "tags": [ + "content" + ], + "triggers": [ + "content", + "plan", + "topic", + "clusters", + "editorial", + "roadmap", + "mix", + "traffic", + "authority", + "lead", + "generation", + "deciding" + ], + "path": "skills/content-strategy/SKILL.md" + }, { "id": "context-agent", "name": "context-agent", @@ -10642,6 +10791,30 @@ ], "path": "skills/defi-protocol-templates/SKILL.md" }, + { + "id": "defuddle", + "name": "defuddle", + "description": "Extract clean markdown content from web pages using Defuddle CLI, removing clutter and navigation to save tokens. Use instead of WebFetch when the user provides a URL to read or analyze, for online documentation, articles, blog posts, or any standard web page.", + "category": "general", + "tags": [ + "defuddle" + ], + "triggers": [ + "defuddle", + "extract", + "clean", + "markdown", + "content", + "web", + "pages", + "cli", + "removing", + "clutter", + "navigation", + "save" + ], + "path": "skills/defuddle/SKILL.md" + }, { "id": "dependency-management-deps-audit", "name": "dependency-management-deps-audit", @@ -16569,6 +16742,31 @@ ], "path": "skills/intercom-automation/SKILL.md" }, + { + "id": "internal-comms", + "name": "internal-comms", + "description": "Write internal communications such as status reports, leadership updates, 3P updates, newsletters, FAQs, incident reports, and project updates using repeatable internal formats.", + "category": "security", + "tags": [ + "internal", + "comms" + ], + "triggers": [ + "internal", + "comms", + "write", + "communications", + "such", + "status", + "reports", + "leadership", + "updates", + "3p", + "newsletters", + "faqs" + ], + "path": "skills/internal-comms/SKILL.md" + }, { "id": "internal-comms-anthropic", "name": "internal-comms-anthropic", @@ -16888,6 +17086,31 @@ ], "path": "skills/jira-automation/SKILL.md" }, + { + "id": "json-canvas", + "name": "json-canvas", + "description": "Create and edit JSON Canvas files (.canvas) with nodes, edges, groups, and connections. Use when working with .canvas files, creating visual canvases, mind maps, flowcharts, or when the user mentions Canvas files in Obsidian.", + "category": "general", + "tags": [ + "json", + "canvas" + ], + "triggers": [ + "json", + "canvas", + "edit", + "files", + "nodes", + "edges", + "groups", + "connections", + "working", + "creating", + "visual", + "canvases" + ], + "path": "skills/json-canvas/SKILL.md" + }, { "id": "julia-pro", "name": "julia-pro", @@ -17404,6 +17627,31 @@ ], "path": "skills/launch-strategy/SKILL.md" }, + { + "id": "lead-magnets", + "name": "lead-magnets", + "description": "Plan and optimize lead magnets for email capture and lead generation. Use when designing gated content, checklists, templates, downloadable resources, or other offers that convert visitors into subscribers.", + "category": "general", + "tags": [ + "lead", + "magnets" + ], + "triggers": [ + "lead", + "magnets", + "plan", + "optimize", + "email", + "capture", + "generation", + "designing", + "gated", + "content", + "checklists", + "downloadable" + ], + "path": "skills/lead-magnets/SKILL.md" + }, { "id": "legacy-modernizer", "name": "legacy-modernizer", @@ -20650,6 +20898,56 @@ ], "path": "skills/observability-monitoring-slo-implement/SKILL.md" }, + { + "id": "obsidian-bases", + "name": "obsidian-bases", + "description": "Create and edit Obsidian Bases (.base files) with views, filters, formulas, and summaries. Use when working with .base files, creating database-like views of notes, or when the user mentions Bases, table views, card views, filters, or formulas in Obsidian.", + "category": "data-ai", + "tags": [ + "obsidian", + "bases" + ], + "triggers": [ + "obsidian", + "bases", + "edit", + "base", + "files", + "views", + "filters", + "formulas", + "summaries", + "working", + "creating", + "database" + ], + "path": "skills/obsidian-bases/SKILL.md" + }, + { + "id": "obsidian-cli", + "name": "obsidian-cli", + "description": "Use the Obsidian CLI to read, create, search, and manage vault content, or to develop and debug Obsidian plugins and themes from the command line.", + "category": "general", + "tags": [ + "obsidian", + "cli" + ], + "triggers": [ + "obsidian", + "cli", + "read", + "search", + "vault", + "content", + "develop", + "debug", + "plugins", + "themes", + "command", + "line" + ], + "path": "skills/obsidian-cli/SKILL.md" + }, { "id": "obsidian-clipper-template-creator", "name": "obsidian-clipper-template-creator", @@ -20676,6 +20974,31 @@ ], "path": "skills/obsidian-clipper-template-creator/SKILL.md" }, + { + "id": "obsidian-markdown", + "name": "obsidian-markdown", + "description": "Create and edit Obsidian Flavored Markdown with wikilinks, embeds, callouts, properties, and other Obsidian-specific syntax. Use when working with .md files in Obsidian, or when the user mentions wikilinks, callouts, frontmatter, tags, embeds, or Obsidian notes.", + "category": "general", + "tags": [ + "obsidian", + "markdown" + ], + "triggers": [ + "obsidian", + "markdown", + "edit", + "flavored", + "wikilinks", + "embeds", + "callouts", + "properties", + "other", + "specific", + "syntax", + "working" + ], + "path": "skills/obsidian-markdown/SKILL.md" + }, { "id": "occupational-health-analyzer", "name": "occupational-health-analyzer", @@ -22752,6 +23075,31 @@ ], "path": "skills/product-manager-toolkit/SKILL.md" }, + { + "id": "product-marketing-context", + "name": "product-marketing-context", + "description": "Create or update a reusable product marketing context document with positioning, audience, ICP, use cases, and messaging. Use at the start of a project to avoid repeating core marketing context across tasks.", + "category": "business", + "tags": [ + "product", + "marketing" + ], + "triggers": [ + "product", + "marketing", + "context", + "update", + "reusable", + "document", + "positioning", + "audience", + "icp", + "cases", + "messaging", + "start" + ], + "path": "skills/product-marketing-context/SKILL.md" + }, { "id": "production-code-audit", "name": "production-code-audit", @@ -24112,6 +24460,30 @@ ], "path": "skills/reverse-engineer/SKILL.md" }, + { + "id": "revops", + "name": "revops", + "description": "Design and improve revenue operations, lead lifecycle rules, scoring, routing, handoffs, and CRM process automation. Use when marketing, sales, and customer success workflows need clearer operational structure.", + "category": "business", + "tags": [ + "revops" + ], + "triggers": [ + "revops", + "improve", + "revenue", + "operations", + "lead", + "lifecycle", + "rules", + "scoring", + "routing", + "handoffs", + "crm", + "process" + ], + "path": "skills/revops/SKILL.md" + }, { "id": "risk-manager", "name": "risk-manager", @@ -24431,6 +24803,31 @@ ], "path": "skills/sales-automator/SKILL.md" }, + { + "id": "sales-enablement", + "name": "sales-enablement", + "description": "Create sales collateral such as decks, one-pagers, objection docs, demo scripts, playbooks, and proposal templates. Use when a sales team needs assets that help reps move deals forward and close.", + "category": "business", + "tags": [ + "sales", + "enablement" + ], + "triggers": [ + "sales", + "enablement", + "collateral", + "such", + "decks", + "one", + "pagers", + "objection", + "docs", + "demo", + "scripts", + "playbooks" + ], + "path": "skills/sales-enablement/SKILL.md" + }, { "id": "salesforce-automation", "name": "salesforce-automation", @@ -25392,6 +25789,30 @@ ], "path": "skills/sentry-automation/SKILL.md" }, + { + "id": "seo", + "name": "seo", + "description": "Run a broad SEO audit across technical SEO, on-page SEO, schema, sitemaps, content quality, AI search readiness, and GEO. Use as the umbrella skill when the user asks for a full SEO analysis or strategy.", + "category": "data-ai", + "tags": [ + "seo" + ], + "triggers": [ + "seo", + "run", + "broad", + "audit", + "technical", + "page", + "schema", + "sitemaps", + "content", + "quality", + "ai", + "search" + ], + "path": "skills/seo/SKILL.md" + }, { "id": "seo-audit", "name": "seo-audit", @@ -25467,6 +25888,57 @@ ], "path": "skills/seo-cannibalization-detector/SKILL.md" }, + { + "id": "seo-competitor-pages", + "name": "seo-competitor-pages", + "description": "Generate SEO-optimized competitor comparison and alternatives pages. Covers \"X vs Y\" layouts, \"alternatives to X\" pages, feature matrices, schema markup, and conversion optimization. Use when user says \"comparison page\", \"vs page\", \"alternatives page\", \"competitor comparison\", or \"X vs Y\".", + "category": "business", + "tags": [ + "seo", + "competitor", + "pages" + ], + "triggers": [ + "seo", + "competitor", + "pages", + "generate", + "optimized", + "comparison", + "alternatives", + "covers", + "vs", + "layouts", + "feature", + "matrices" + ], + "path": "skills/seo-competitor-pages/SKILL.md" + }, + { + "id": "seo-content", + "name": "seo-content", + "description": "Content quality and E-E-A-T analysis with AI citation readiness assessment. Use when user says \"content quality\", \"E-E-A-T\", \"content analysis\", \"readability check\", \"thin content\", or \"content audit\".", + "category": "data-ai", + "tags": [ + "seo", + "content" + ], + "triggers": [ + "seo", + "content", + "quality", + "analysis", + "ai", + "citation", + "readiness", + "assessment", + "user", + "says", + "readability", + "check" + ], + "path": "skills/seo-content/SKILL.md" + }, { "id": "seo-content-auditor", "name": "seo-content-auditor", @@ -25571,6 +26043,31 @@ ], "path": "skills/seo-content-writer/SKILL.md" }, + { + "id": "seo-dataforseo", + "name": "seo-dataforseo", + "description": "Use DataForSEO for live SERPs, keyword metrics, backlinks, competitor analysis, on-page checks, and AI visibility data. Trigger when the user needs real SEO data rather than static guidance.", + "category": "data-ai", + "tags": [ + "seo", + "dataforseo" + ], + "triggers": [ + "seo", + "dataforseo", + "live", + "serps", + "keyword", + "metrics", + "backlinks", + "competitor", + "analysis", + "page", + "checks", + "ai" + ], + "path": "skills/seo-dataforseo/SKILL.md" + }, { "id": "seo-forensic-incident-response", "name": "seo-forensic-incident-response", @@ -25623,6 +26120,107 @@ ], "path": "skills/seo-fundamentals/SKILL.md" }, + { + "id": "seo-geo", + "name": "seo-geo", + "description": "Optimize content for AI Overviews, ChatGPT, Perplexity, and other AI search systems. Use when improving GEO, AI citations, llms.txt readiness, crawler accessibility, and passage-level citability.", + "category": "data-ai", + "tags": [ + "seo", + "geo" + ], + "triggers": [ + "seo", + "geo", + "optimize", + "content", + "ai", + "overviews", + "chatgpt", + "perplexity", + "other", + "search", + "improving", + "citations" + ], + "path": "skills/seo-geo/SKILL.md" + }, + { + "id": "seo-hreflang", + "name": "seo-hreflang", + "description": "Hreflang and international SEO audit, validation, and generation. Detects common mistakes, validates language/region codes, and generates correct hreflang implementations. Use when user says \"hreflang\", \"i18n SEO\", \"international SEO\", \"multi-language\", \"multi-region\", or \"language tags\".", + "category": "business", + "tags": [ + "seo", + "hreflang" + ], + "triggers": [ + "seo", + "hreflang", + "international", + "audit", + "validation", + "generation", + "detects", + "common", + "mistakes", + "validates", + "language", + "region" + ], + "path": "skills/seo-hreflang/SKILL.md" + }, + { + "id": "seo-image-gen", + "name": "seo-image-gen", + "description": "Generate SEO-focused images such as OG cards, hero images, schema assets, product visuals, and infographics. Use when image generation is part of an SEO workflow or content publishing task.", + "category": "business", + "tags": [ + "seo", + "image", + "gen" + ], + "triggers": [ + "seo", + "image", + "gen", + "generate", + "images", + "such", + "og", + "cards", + "hero", + "schema", + "assets", + "product" + ], + "path": "skills/seo-image-gen/SKILL.md" + }, + { + "id": "seo-images", + "name": "seo-images", + "description": "Image optimization analysis for SEO and performance. Checks alt text, file sizes, formats, responsive images, lazy loading, and CLS prevention. Use when user says \"image optimization\", \"alt text\", \"image SEO\", \"image size\", or \"image audit\".", + "category": "business", + "tags": [ + "seo", + "images" + ], + "triggers": [ + "seo", + "images", + "image", + "optimization", + "analysis", + "performance", + "checks", + "alt", + "text", + "file", + "sizes", + "formats" + ], + "path": "skills/seo-images/SKILL.md" + }, { "id": "seo-keyword-strategist", "name": "seo-keyword-strategist", @@ -25675,6 +26273,131 @@ ], "path": "skills/seo-meta-optimizer/SKILL.md" }, + { + "id": "seo-page", + "name": "seo-page", + "description": "Deep single-page SEO analysis covering on-page elements, content quality, technical meta tags, schema, images, and performance. Use when user says \"analyze this page\", \"check page SEO\", or provides a single URL for review.", + "category": "business", + "tags": [ + "seo", + "page" + ], + "triggers": [ + "seo", + "page", + "deep", + "single", + "analysis", + "covering", + "elements", + "content", + "quality", + "technical", + "meta", + "tags" + ], + "path": "skills/seo-page/SKILL.md" + }, + { + "id": "seo-plan", + "name": "seo-plan", + "description": "Strategic SEO planning for new or existing websites. Industry-specific templates, competitive analysis, content strategy, and implementation roadmap. Use when user says \"SEO plan\", \"SEO strategy\", \"content strategy\", \"site architecture\", or \"SEO roadmap\".", + "category": "architecture", + "tags": [ + "seo", + "plan" + ], + "triggers": [ + "seo", + "plan", + "strategic", + "planning", + "new", + "existing", + "websites", + "industry", + "specific", + "competitive", + "analysis", + "content" + ], + "path": "skills/seo-plan/SKILL.md" + }, + { + "id": "seo-programmatic", + "name": "seo-programmatic", + "description": "Plan and audit programmatic SEO pages generated at scale from structured data. Use when designing templates, URL systems, internal linking, quality gates, and index-bloat safeguards for pages at scale.", + "category": "data-ai", + "tags": [ + "seo", + "programmatic" + ], + "triggers": [ + "seo", + "programmatic", + "plan", + "audit", + "pages", + "generated", + "scale", + "structured", + "data", + "designing", + "url", + "internal" + ], + "path": "skills/seo-programmatic/SKILL.md" + }, + { + "id": "seo-schema", + "name": "seo-schema", + "description": "Detect, validate, and generate Schema.org structured data. JSON-LD format preferred. Use when user says \"schema\", \"structured data\", \"rich results\", \"JSON-LD\", or \"markup\".", + "category": "data-ai", + "tags": [ + "seo", + "schema" + ], + "triggers": [ + "seo", + "schema", + "detect", + "validate", + "generate", + "org", + "structured", + "data", + "json", + "ld", + "format", + "preferred" + ], + "path": "skills/seo-schema/SKILL.md" + }, + { + "id": "seo-sitemap", + "name": "seo-sitemap", + "description": "Analyze existing XML sitemaps or generate new ones with industry templates. Validates format, URLs, and structure. Use when user says \"sitemap\", \"generate sitemap\", \"sitemap issues\", or \"XML sitemap\".", + "category": "business", + "tags": [ + "seo", + "sitemap" + ], + "triggers": [ + "seo", + "sitemap", + "analyze", + "existing", + "xml", + "sitemaps", + "generate", + "new", + "ones", + "industry", + "validates", + "format" + ], + "path": "skills/seo-sitemap/SKILL.md" + }, { "id": "seo-snippet-hunter", "name": "seo-snippet-hunter", @@ -25726,6 +26449,31 @@ ], "path": "skills/seo-structure-architect/SKILL.md" }, + { + "id": "seo-technical", + "name": "seo-technical", + "description": "Audit technical SEO across crawlability, indexability, security, URLs, mobile, Core Web Vitals, structured data, JavaScript rendering, and related platform signals like robots.txt and AI crawler access.", + "category": "security", + "tags": [ + "seo", + "technical" + ], + "triggers": [ + "seo", + "technical", + "audit", + "crawlability", + "indexability", + "security", + "urls", + "mobile", + "core", + "web", + "vitals", + "structured" + ], + "path": "skills/seo-technical/SKILL.md" + }, { "id": "server-management", "name": "server-management", @@ -26039,6 +26787,31 @@ ], "path": "skills/similarity-search-patterns/SKILL.md" }, + { + "id": "site-architecture", + "name": "site-architecture", + "description": "Plan or restructure website hierarchy, navigation, URL patterns, breadcrumbs, and internal linking. Use when mapping pages, sections, and site structure, but not for XML sitemap auditing or schema markup.", + "category": "architecture", + "tags": [ + "site", + "architecture" + ], + "triggers": [ + "site", + "architecture", + "plan", + "restructure", + "website", + "hierarchy", + "navigation", + "url", + "breadcrumbs", + "internal", + "linking", + "mapping" + ], + "path": "skills/site-architecture/SKILL.md" + }, { "id": "skill-check", "name": "skill-check", diff --git a/docs/maintainers/skills-import-2026-03-21.md b/docs/maintainers/skills-import-2026-03-21.md new file mode 100644 index 00000000..cc120005 --- /dev/null +++ b/docs/maintainers/skills-import-2026-03-21.md @@ -0,0 +1,81 @@ +# Skills Import - 2026-03-21 + +This note records the skill import and normalization work completed on 2026-03-21. + +## Summary + +- Imported new skill directories from external repositories. +- Normalized frontmatter for imported skills where needed. +- Repaired imported dangling links that did not map cleanly into this repository. +- Regenerated derived artifacts after import. + +## Imported Skills by Source + +### `anthropics/skills` + +- `claude-api` +- `internal-comms` + +Note: +- `docx`, `pdf`, `pptx`, and `xlsx` were not re-imported as separate directories because this repository already exposes those aliases as symlinks to `*-official` skill directories. + +### `coreyhaines31/marketingskills` + +- `ad-creative` +- `ai-seo` +- `churn-prevention` +- `cold-email` +- `content-strategy` +- `lead-magnets` +- `product-marketing-context` +- `revops` +- `sales-enablement` +- `site-architecture` + +### `AgriciDaniel/claude-seo` + +- `seo` +- `seo-competitor-pages` +- `seo-content` +- `seo-dataforseo` +- `seo-geo` +- `seo-hreflang` +- `seo-image-gen` +- `seo-images` +- `seo-page` +- `seo-plan` +- `seo-programmatic` +- `seo-schema` +- `seo-sitemap` +- `seo-technical` + +### `kepano/obsidian-skills` + +- `defuddle` +- `json-canvas` +- `obsidian-bases` +- `obsidian-cli` +- `obsidian-markdown` + +## Not Imported + +These repositories were analyzed earlier in the comparison work, but no new primary skills were imported from them in this batch: + +- `obra/superpowers` +- `muratcankoylan/agent-skills-for-context-engineering` +- `PleasePrompto/notebooklm-skill` + +## Validation + +Commands run during the import: + +```bash +npm run validate +npm run index +npm run catalog +``` + +Result: + +- Validation passed after normalization. +- Generated index count after import: `1304` skills. diff --git a/skills/ad-creative/SKILL.md b/skills/ad-creative/SKILL.md new file mode 100644 index 00000000..ab9521bb --- /dev/null +++ b/skills/ad-creative/SKILL.md @@ -0,0 +1,371 @@ +--- +name: ad-creative +description: "Create, iterate, and scale paid ad creative for Google Ads, Meta, LinkedIn, TikTok, and similar platforms. Use when generating headlines, descriptions, primary text, or large sets of ad variations for testing and performance optimization." +risk: unknown +source: "https://github.com/coreyhaines31/marketingskills" +date_added: "2026-03-21" +metadata: + version: 1.1.0 +--- + +# Ad Creative + +You are an expert performance creative strategist. Your goal is to generate high-performing ad creative at scale — headlines, descriptions, and primary text that drive clicks and conversions — and iterate based on real performance data. + +## When to Use + +- Use when generating or iterating paid ad copy at scale. +- Use for headlines, descriptions, primary text, and structured ad variation sets. +- Use when performance data should inform the next round of creative. + +## Before Starting + +**Check for product marketing context first:** +If `.agents/product-marketing-context.md` exists (or `.claude/product-marketing-context.md` in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task. + +Gather this context (ask if not provided): + +### 1. Platform & Format +- What platform? (Google Ads, Meta, LinkedIn, TikTok, Twitter/X) +- What ad format? (Search RSAs, display, social feed, stories, video) +- Are there existing ads to iterate on, or starting from scratch? + +### 2. Product & Offer +- What are you promoting? (Product, feature, free trial, demo, lead magnet) +- What's the core value proposition? +- What makes this different from competitors? + +### 3. Audience & Intent +- Who is the target audience? +- What stage of awareness? (Problem-aware, solution-aware, product-aware) +- What pain points or desires drive them? + +### 4. Performance Data (if iterating) +- What creative is currently running? +- Which headlines/descriptions are performing best? (CTR, conversion rate, ROAS) +- Which are underperforming? +- What angles or themes have been tested? + +### 5. Constraints +- Brand voice guidelines or words to avoid? +- Compliance requirements? (Industry regulations, platform policies) +- Any mandatory elements? (Brand name, trademark symbols, disclaimers) + +--- + +## How This Skill Works + +This skill supports two modes: + +### Mode 1: Generate from Scratch +When starting fresh, you generate a full set of ad creative based on product context, audience insights, and platform best practices. + +### Mode 2: Iterate from Performance Data +When the user provides performance data (CSV, paste, or API output), you analyze what's working, identify patterns in top performers, and generate new variations that build on winning themes while exploring new angles. + +The core loop: + +``` +Pull performance data → Identify winning patterns → Generate new variations → Validate specs → Deliver +``` + +--- + +## Platform Specs + +Platforms reject or truncate creative that exceeds these limits, so verify every piece of copy fits before delivering. + +### Google Ads (Responsive Search Ads) + +| Element | Limit | Quantity | +|---------|-------|----------| +| Headline | 30 characters | Up to 15 | +| Description | 90 characters | Up to 4 | +| Display URL path | 15 characters each | 2 paths | + +**RSA rules:** +- Headlines must make sense independently and in any combination +- Pin headlines to positions only when necessary (reduces optimization) +- Include at least one keyword-focused headline +- Include at least one benefit-focused headline +- Include at least one CTA headline + +### Meta Ads (Facebook/Instagram) + +| Element | Limit | Notes | +|---------|-------|-------| +| Primary text | 125 chars visible (up to 2,200) | Front-load the hook | +| Headline | 40 characters recommended | Below the image | +| Description | 30 characters recommended | Below headline | +| URL display link | 40 characters | Optional | + +### LinkedIn Ads + +| Element | Limit | Notes | +|---------|-------|-------| +| Intro text | 150 chars recommended (600 max) | Above the image | +| Headline | 70 chars recommended (200 max) | Below the image | +| Description | 100 chars recommended (300 max) | Appears in some placements | + +### TikTok Ads + +| Element | Limit | Notes | +|---------|-------|-------| +| Ad text | 80 chars recommended (100 max) | Above the video | +| Display name | 40 characters | Brand name | + +### Twitter/X Ads + +| Element | Limit | Notes | +|---------|-------|-------| +| Tweet text | 280 characters | The ad copy | +| Headline | 70 characters | Card headline | +| Description | 200 characters | Card description | + +For detailed specs and format variations, see [references/platform-specs.md](references/platform-specs.md). + +--- + +## Generating Ad Visuals + +For image and video ad creative, use generative AI tools and code-based video rendering. See [references/generative-tools.md](references/generative-tools.md) for the complete guide covering: + +- **Image generation** — Nano Banana Pro (Gemini), Flux, Ideogram for static ad images +- **Video generation** — Veo, Kling, Runway, Sora, Seedance, Higgsfield for video ads +- **Voice & audio** — ElevenLabs, OpenAI TTS, Cartesia for voiceovers, cloning, multilingual +- **Code-based video** — Remotion for templated, data-driven video at scale +- **Platform image specs** — Correct dimensions for every ad placement +- **Cost comparison** — Pricing for 100+ ad variations across tools + +**Recommended workflow for scaled production:** +1. Generate hero creative with AI tools (exploratory, high-quality) +2. Build Remotion templates based on winning patterns +3. Batch produce variations with Remotion using data feeds +4. Iterate — AI for new angles, Remotion for scale + +--- + +## Generating Ad Copy + +### Step 1: Define Your Angles + +Before writing individual headlines, establish 3-5 distinct **angles** — different reasons someone would click. Each angle should tap into a different motivation. + +**Common angle categories:** + +| Category | Example Angle | +|----------|---------------| +| Pain point | "Stop wasting time on X" | +| Outcome | "Achieve Y in Z days" | +| Social proof | "Join 10,000+ teams who..." | +| Curiosity | "The X secret top companies use" | +| Comparison | "Unlike X, we do Y" | +| Urgency | "Limited time: get X free" | +| Identity | "Built for [specific role/type]" | +| Contrarian | "Why [common practice] doesn't work" | + +### Step 2: Generate Variations per Angle + +For each angle, generate multiple variations. Vary: +- **Word choice** — synonyms, active vs. passive +- **Specificity** — numbers vs. general claims +- **Tone** — direct vs. question vs. command +- **Structure** — short punch vs. full benefit statement + +### Step 3: Validate Against Specs + +Before delivering, check every piece of creative against the platform's character limits. Flag anything that's over and provide a trimmed alternative. + +### Step 4: Organize for Upload + +Present creative in a structured format that maps to the ad platform's upload requirements. + +--- + +## Iterating from Performance Data + +When the user provides performance data, follow this process: + +### Step 1: Analyze Winners + +Look at the top-performing creative (by CTR, conversion rate, or ROAS — ask which metric matters most) and identify: + +- **Winning themes** — What topics or pain points appear in top performers? +- **Winning structures** — Questions? Statements? Commands? Numbers? +- **Winning word patterns** — Specific words or phrases that recur? +- **Character utilization** — Are top performers shorter or longer? + +### Step 2: Analyze Losers + +Look at the worst performers and identify: + +- **Themes that fall flat** — What angles aren't resonating? +- **Common patterns in low performers** — Too generic? Too long? Wrong tone? + +### Step 3: Generate New Variations + +Create new creative that: +- **Doubles down** on winning themes with fresh phrasing +- **Extends** winning angles into new variations +- **Tests** 1-2 new angles not yet explored +- **Avoids** patterns found in underperformers + +### Step 4: Document the Iteration + +Track what was learned and what's being tested: + +``` +## Iteration Log +- Round: [number] +- Date: [date] +- Top performers: [list with metrics] +- Winning patterns: [summary] +- New variations: [count] headlines, [count] descriptions +- New angles being tested: [list] +- Angles retired: [list] +``` + +--- + +## Writing Quality Standards + +### Headlines That Click + +**Strong headlines:** +- Specific ("Cut reporting time 75%") over vague ("Save time") +- Benefits ("Ship code faster") over features ("CI/CD pipeline") +- Active voice ("Automate your reports") over passive ("Reports are automated") +- Include numbers when possible ("3x faster," "in 5 minutes," "10,000+ teams") + +**Avoid:** +- Jargon the audience won't recognize +- Claims without specificity ("Best," "Leading," "Top") +- All caps or excessive punctuation +- Clickbait that the landing page can't deliver on + +### Descriptions That Convert + +Descriptions should complement headlines, not repeat them. Use descriptions to: +- Add proof points (numbers, testimonials, awards) +- Handle objections ("No credit card required," "Free forever for small teams") +- Reinforce CTAs ("Start your free trial today") +- Add urgency when genuine ("Limited to first 500 signups") + +--- + +## Output Formats + +### Standard Output + +Organize by angle, with character counts: + +``` +## Angle: [Pain Point — Manual Reporting] + +### Headlines (30 char max) +1. "Stop Building Reports by Hand" (29) +2. "Automate Your Weekly Reports" (28) +3. "Reports Done in 5 Min, Not 5 Hr" (31) <- OVER LIMIT, trimmed below + -> "Reports in 5 Min, Not 5 Hrs" (27) + +### Descriptions (90 char max) +1. "Marketing teams save 10+ hours/week with automated reporting. Start free." (73) +2. "Connect your data sources once. Get automated reports forever. No code required." (80) +``` + +### Bulk CSV Output + +When generating at scale (10+ variations), offer CSV format for direct upload: + +```csv +headline_1,headline_2,headline_3,description_1,description_2,platform +"Stop Manual Reporting","Automate in 5 Minutes","Join 10K+ Teams","Save 10+ hrs/week on reports. Start free.","Connect data sources once. Reports forever.","google_ads" +``` + +### Iteration Report + +When iterating, include a summary: + +``` +## Performance Summary +- Analyzed: [X] headlines, [Y] descriptions +- Top performer: "[headline]" — [metric]: [value] +- Worst performer: "[headline]" — [metric]: [value] +- Pattern: [observation] + +## New Creative +[organized variations] + +## Recommendations +- [What to pause, what to scale, what to test next] +``` + +--- + +## Batch Generation Workflow + +For large-scale creative production (Anthropic's growth team generates 100+ variations per cycle): + +### 1. Break into sub-tasks +- **Headline generation** — Focused on click-through +- **Description generation** — Focused on conversion +- **Primary text generation** — Focused on engagement (Meta/LinkedIn) + +### 2. Generate in waves +- Wave 1: Core angles (3-5 angles, 5 variations each) +- Wave 2: Extended variations on top 2 angles +- Wave 3: Wild card angles (contrarian, emotional, specific) + +### 3. Quality filter +- Remove anything over character limit +- Remove duplicates or near-duplicates +- Flag anything that might violate platform policies +- Ensure headline/description combinations make sense together + +--- + +## Common Mistakes + +- **Writing headlines that only work together** — RSA headlines get combined randomly +- **Ignoring character limits** — Platforms truncate without warning +- **All variations sound the same** — Vary angles, not just word choice +- **No CTA headlines** — RSAs need action-oriented headlines to drive clicks; include at least 2-3 +- **Generic descriptions** — "Learn more about our solution" wastes the slot +- **Iterating without data** — Gut feelings are less reliable than metrics +- **Testing too many things at once** — Change one variable per test cycle +- **Retiring creative too early** — Allow 1,000+ impressions before judging + +--- + +## Tool Integrations + +For pulling performance data and managing campaigns, use the relevant ads platform tools available in this environment. + +| Platform | Pull Performance Data | Manage Campaigns | Guide | +|----------|:---------------------:|:----------------:|-------| +| **Google Ads** | `google-ads campaigns list`, `google-ads reports get` | `google-ads campaigns create` | Use available Google Ads integrations | +| **Meta Ads** | `meta-ads insights get` | `meta-ads campaigns list` | Use available Meta Ads integrations | +| **LinkedIn Ads** | `linkedin-ads analytics get` | `linkedin-ads campaigns list` | Use available LinkedIn Ads integrations | +| **TikTok Ads** | `tiktok-ads reports get` | `tiktok-ads campaigns list` | Use available TikTok Ads integrations | + +### Workflow: Pull Data, Analyze, Generate + +```bash +# 1. Pull recent ad performance +node tools/clis/google-ads.js reports get --type ad_performance --date-range last_30_days + +# 2. Analyze output (identify top/bottom performers) +# 3. Feed winning patterns into this skill +# 4. Generate new variations +# 5. Upload to platform +``` + +--- + +## Related Skills + +- **paid-ads**: For campaign strategy, targeting, budgets, and optimization +- **copywriting**: For landing page copy (where ad traffic lands) +- **ab-test-setup**: For structuring creative tests with statistical rigor +- **marketing-psychology**: For psychological principles behind high-performing creative +- **copy-editing**: For polishing ad copy before launch diff --git a/skills/ad-creative/evals/evals.json b/skills/ad-creative/evals/evals.json new file mode 100644 index 00000000..84c2ae36 --- /dev/null +++ b/skills/ad-creative/evals/evals.json @@ -0,0 +1,90 @@ +{ + "skill_name": "ad-creative", + "evals": [ + { + "id": 1, + "prompt": "Generate ad creative for our Meta (Facebook/Instagram) campaign. We sell an AI writing assistant for content marketers. Main value prop: write blog posts 5x faster. Target audience: content marketing managers at B2B SaaS companies. Budget: $5k/month.", + "expected_output": "Should check for product-marketing-context.md first. Should generate creative following the angle-based approach: identify 3-5 angles (speed, quality, ROI, pain of blank page, competitive edge). For each angle, should generate primary text (≤125 chars), headline (≤40 chars), and description (≤30 chars) respecting Meta character limits. Should provide multiple variations per angle. Should suggest image/visual direction for each. Should organize output with angle name, hook, body, CTA for each variation. Should recommend which angles to test first.", + "assertions": [ + "Checks for product-marketing-context.md", + "Uses angle-based generation approach", + "Identifies multiple angles (3-5)", + "Respects Meta character limits (125/40/30)", + "Generates multiple variations per angle", + "Suggests image or visual direction", + "Includes hook, body, and CTA for each", + "Recommends which angles to test first" + ], + "files": [] + }, + { + "id": 2, + "prompt": "I need Google Ads copy for our CRM product. We're targeting the keyword 'best CRM for small business'. Need responsive search ads.", + "expected_output": "Should generate Google RSA creative respecting character limits: headlines (≤30 chars each, need 10-15 variations) and descriptions (≤90 chars each, need 4+ variations). Should note that pinning should be used sparingly as it reduces optimization. Should include the target keyword in headlines. Should provide multiple angle-based variations. Should suggest ad extensions (sitelinks, callouts, structured snippets). Should follow Google Ads best practices for RSA.", + "assertions": [ + "Respects Google RSA character limits (30 char headlines, 90 char descriptions)", + "Generates 10-15 headline variations", + "Generates 4+ description variations", + "Includes target keyword in headlines", + "Notes pinning should be used sparingly per skill guidance", + "Suggests ad extensions", + "Uses angle-based variation approach" + ], + "files": [] + }, + { + "id": 3, + "prompt": "Here's our ad performance data: Ad A (pain point angle) - CTR 2.1%, CPC $3.20, Conv rate 4.5%. Ad B (social proof angle) - CTR 1.4%, CPC $4.10, Conv rate 6.2%. Ad C (feature angle) - CTR 0.8%, CPC $5.50, Conv rate 2.1%. Help me iterate on these.", + "expected_output": "Should activate the iteration-from-performance mode (not generate-from-scratch). Should analyze the data: Ad A has best CTR, Ad B has best conversion rate (highest efficiency despite lower CTR), Ad C is underperforming on all metrics. Should recommend doubling down on the pain point angle (high CTR) and social proof angle (high conversion), while pausing or reworking the feature angle. Should generate new variations that combine winning elements (pain point hook + social proof). Should suggest specific iterations on Ad A and Ad B.", + "assertions": [ + "Activates iteration mode based on performance data", + "Analyzes CTR, CPC, and conversion rate for each ad", + "Identifies winning angles from the data", + "Recommends pausing or reworking underperforming creative", + "Generates new variations combining winning elements", + "Provides specific iterations on top performers" + ], + "files": [] + }, + { + "id": 4, + "prompt": "we need linkedin ads for our enterprise security product. audience is CISOs and IT directors.", + "expected_output": "Should trigger on casual phrasing. Should generate LinkedIn ad creative respecting character limits: introductory text (≤150 chars), headline (≤70 chars), description (≤100 chars). Should adapt tone and messaging for enterprise security audience (CISOs, IT directors) — more formal, compliance-focused, risk-reduction language. Should provide multiple angles relevant to security buyers (risk reduction, compliance, incident response time, cost of breaches). Should suggest ad format recommendations for LinkedIn (sponsored content, message ads, etc.).", + "assertions": [ + "Triggers on casual phrasing", + "Respects LinkedIn character limits (150/70/100)", + "Adapts tone for enterprise security audience", + "Uses risk-reduction and compliance language", + "Provides multiple angles relevant to security buyers", + "Suggests LinkedIn ad format recommendations" + ], + "files": [] + }, + { + "id": 5, + "prompt": "I need to generate a big batch of ad variations for a multi-platform campaign launching next week. We're a meal delivery service targeting busy professionals. Need ads for Google, Meta, and TikTok.", + "expected_output": "Should activate the batch generation workflow. Should generate creative for all three platforms respecting each platform's character limits: Google RSA (30/90), Meta (125/40/30), TikTok (80 chars recommended, 100 max). Should identify 3-5 angles that work across platforms (convenience, health, time savings, variety, cost vs eating out). Should generate variations per angle per platform. Should note platform-specific creative considerations (TikTok needs video concepts, not just text). Should organize output clearly by platform.", + "assertions": [ + "Activates batch generation workflow", + "Generates for all three platforms", + "Respects each platform's character limits", + "Identifies angles that work across platforms", + "Notes TikTok needs video concepts", + "Organizes output by platform", + "Generates multiple variations per angle per platform" + ], + "files": [] + }, + { + "id": 6, + "prompt": "Help me plan our overall paid advertising strategy. We have a $20k monthly budget and want to figure out which platforms to use and how to allocate spend.", + "expected_output": "Should recognize this is a paid advertising strategy task, not ad creative generation. Should defer to or cross-reference the paid-ads skill, which handles campaign strategy, platform selection, and budget allocation. May briefly mention creative considerations but should make clear that paid-ads is the right skill for strategy.", + "assertions": [ + "Recognizes this as paid ads strategy, not creative generation", + "References or defers to paid-ads skill", + "Does not attempt full campaign strategy using creative generation patterns" + ], + "files": [] + } + ] +} diff --git a/skills/ad-creative/references/generative-tools.md b/skills/ad-creative/references/generative-tools.md new file mode 100644 index 00000000..e22ebcee --- /dev/null +++ b/skills/ad-creative/references/generative-tools.md @@ -0,0 +1,637 @@ +# Generative AI Tools for Ad Creative + +Reference for using AI image generators, video generators, and code-based video tools to produce ad visuals at scale. + +--- + +## When to Use Generative Tools + +| Need | Tool Category | Best Fit | +|------|---------------|----------| +| Static ad images (banners, social) | Image generation | Nano Banana Pro, Flux, Ideogram | +| Ad images with text overlays | Image generation (text-capable) | Ideogram, Nano Banana Pro | +| Short video ads (6-30 sec) | Video generation | Veo, Kling, Runway, Sora, Seedance | +| Video ads with voiceover | Video gen + voice | Veo/Sora (native), or Runway + ElevenLabs | +| Voiceover tracks for ads | Voice generation | ElevenLabs, OpenAI TTS, Cartesia | +| Multi-language ad versions | Voice generation | ElevenLabs, PlayHT | +| Brand voice cloning | Voice generation | ElevenLabs, Resemble AI | +| Product mockups and variations | Image generation + references | Flux (multi-image reference) | +| Templated video ads at scale | Code-based video | Remotion | +| Personalized video (name, data) | Code-based video | Remotion | +| Brand-consistent variations | Image gen + style refs | Flux, Ideogram, Nano Banana Pro | + +--- + +## Image Generation + +### Nano Banana Pro (Gemini) + +Google DeepMind's image generation model, available through the Gemini API. + +**Best for:** High-quality ad images, product visuals, text rendering +**API:** Gemini API (Google AI Studio, Vertex AI) +**Pricing:** ~$0.04/image (Gemini 2.5 Flash Image), ~$0.24/4K image (Nano Banana Pro) + +**Strengths:** +- Strong text rendering in images (logos, headlines) +- Native image editing (modify existing images with prompts) +- Available through the same Gemini API used for text generation +- Supports both generation and editing in one model + +**Ad creative use cases:** +- Generate social media ad images from text descriptions +- Create product mockup variations +- Edit existing ad images (swap backgrounds, change colors) +- Generate images with headline text baked in + +**API example:** +```bash +# Using the Gemini API for image generation +curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash-image:generateContent" \ + -H "Content-Type: application/json" \ + -H "x-goog-api-key: $GEMINI_API_KEY" \ + -d '{ + "contents": [{"parts": [{"text": "Create a clean, modern social media ad image for a project management tool. Show a laptop with a kanban board interface. Bright, professional, 16:9 ratio."}]}], + "generationConfig": {"responseModalities": ["TEXT", "IMAGE"]} + }' +``` + +**Docs:** [Gemini Image Generation](https://ai.google.dev/gemini-api/docs/image-generation) + +--- + +### Flux (Black Forest Labs) + +Open-weight image generation models with API access through Replicate and BFL's native API. + +**Best for:** Photorealistic images, brand-consistent variations, multi-reference generation +**API:** Replicate, BFL API, fal.ai +**Pricing:** ~$0.01-0.06/image depending on model and resolution + +**Model variants:** +| Model | Speed | Quality | Cost | Best For | +|-------|-------|---------|------|----------| +| Flux 2 Pro | ~6 sec | Highest | $0.015/MP | Final production assets | +| Flux 2 Flex | ~22 sec | High + editing | $0.06/MP | Iterative editing | +| Flux 2 Dev | ~2.5 sec | Good | $0.012/MP | Rapid prototyping | +| Flux 2 Klein | Fastest | Good | Lowest | High-volume batch generation | + +**Strengths:** +- Multi-image reference (up to 8 images) for consistent identity across ads +- Product consistency — same product in different contexts +- Style transfer from reference images +- Open-weight Dev model for self-hosting + +**Ad creative use cases:** +- Generate 50+ ad variations with consistent product/person identity +- Create product-in-context images (your SaaS on different devices) +- Style-match to existing brand assets using reference images +- Rapid A/B test image variations + +**Docs:** [Replicate Flux](https://replicate.com/black-forest-labs/flux-2-pro), [BFL API](https://docs.bfl.ml/) + +--- + +### Ideogram + +Specialized in typography and text rendering within images. + +**Best for:** Ad banners with text, branded graphics, social ad images with headlines +**API:** Ideogram API, Runware +**Pricing:** ~$0.06/image (API), ~$0.009/image (subscription) + +**Strengths:** +- Best-in-class text rendering (~90% accuracy vs ~30% for most tools) +- Style reference system (upload up to 3 reference images) +- 4.3 billion style presets for consistent brand aesthetics +- Strong at logos and branded typography + +**Ad creative use cases:** +- Generate ad banners with headline text directly in the image +- Create social media graphics with branded text overlays +- Produce multiple design variations with consistent typography +- Generate promotional materials without needing a designer for each iteration + +**Docs:** [Ideogram API](https://developer.ideogram.ai/), [Ideogram](https://ideogram.ai/) + +--- + +### Other Image Tools + +| Tool | Best For | API Status | Notes | +|------|----------|------------|-------| +| **DALL-E 3** (OpenAI) | General image generation | Official API | Integrated with ChatGPT, good text rendering | +| **Midjourney** | Artistic, high-aesthetic images | No official public API | Discord-based; unofficial APIs exist but risk bans | +| **Stable Diffusion** | Self-hosted, customizable | Open source | Best for teams with GPU infrastructure | + +--- + +## Video Generation + +### Google Veo + +Google DeepMind's video generation model, available through the Gemini API and Vertex AI. + +**Best for:** High-quality video ads with native audio, vertical video for social +**API:** Gemini API, Vertex AI +**Pricing:** ~$0.15/sec (Veo 3.1 Fast), ~$0.40/sec (Veo 3.1 Standard) + +**Capabilities:** +- Up to 60 seconds at 1080p +- Native audio generation (dialogue, sound effects, ambient) +- Vertical 9:16 output for Stories/Reels/Shorts +- Upscale to 4K +- Text-to-video and image-to-video + +**Ad creative use cases:** +- Generate short video ads (15-30 sec) from text descriptions +- Create vertical video ads for TikTok, Reels, Shorts +- Produce product demos with voiceover +- Generate multiple video variations from the same prompt with different styles + +**Docs:** [Veo on Vertex AI](https://cloud.google.com/vertex-ai/generative-ai/docs/video/overview) + +--- + +### Kling (Kuaishou) + +Video generation with simultaneous audio-visual generation and camera controls. + +**Best for:** Cinematic video ads, longer-form content, audio-synced video +**API:** Kling API, PiAPI, fal.ai +**Pricing:** ~$0.09/sec (via fal.ai third-party) + +**Capabilities:** +- Up to 3 minutes at 1080p/30-48fps +- Simultaneous audio-visual generation (Kling 2.6) +- Text-to-video and image-to-video +- Motion and camera controls + +**Ad creative use cases:** +- Longer product explainer videos +- Cinematic brand videos with synchronized audio +- Animate product images into video ads + +**Docs:** [Kling AI Developer](https://klingai.com/global/dev/model/video) + +--- + +### Runway + +Video generation and editing platform with strong controllability. + +**Best for:** Controlled video generation, style-consistent content, editing existing footage +**API:** Runway Developer Portal + +**Capabilities:** +- Gen-4: Character/scene consistency across shots +- Motion brush and camera controls +- Image-to-video with reference images +- Video-to-video style transfer + +**Ad creative use cases:** +- Generate video ads with consistent characters/products across scenes +- Style-transfer existing footage to match brand aesthetics +- Extend or remix existing video content + +**Docs:** [Runway API](https://docs.dev.runwayml.com/) + +--- + +### Sora 2 (OpenAI) + +OpenAI's video generation model with synchronized audio. + +**Best for:** High-fidelity video with dialogue and sound +**API:** OpenAI API +**Pricing:** Free tier available; Pro from $0.10-0.50/sec depending on resolution + +**Capabilities:** +- Up to 60 seconds with synchronized audio +- Dialogue, sound effects, and ambient audio +- sora-2 (fast) and sora-2-pro (quality) variants +- Text-to-video and image-to-video + +**Ad creative use cases:** +- Video testimonials and talking-head style ads +- Product demo videos with narration +- Narrative brand videos + +**Docs:** [OpenAI Video Generation](https://platform.openai.com/docs/guides/video-generation) + +--- + +### Seedance 2.0 (ByteDance) + +ByteDance's video generation model with simultaneous audio-visual generation and multimodal inputs. + +**Best for:** Fast, affordable video ads with native audio, multimodal reference inputs +**API:** BytePlus (official), Replicate, WaveSpeedAI, fal.ai (third-party); OpenAI-compatible API format +**Pricing:** ~$0.10-0.80/min depending on resolution (estimated 10-100x cheaper than Sora 2 per clip) + +**Capabilities:** +- Up to 20 seconds at up to 2K resolution +- Simultaneous audio-visual generation (Dual-Branch Diffusion Transformer) +- Text-to-video and image-to-video +- Up to 12 reference files for multimodal input +- OpenAI-compatible API structure + +**Ad creative use cases:** +- High-volume short video ad production at low cost +- Video ads with synchronized voiceover and sound effects in one pass +- Multi-reference generation (feed product images, brand assets, style references) +- Rapid iteration on video ad concepts + +**Docs:** [Seedance](https://seed.bytedance.com/en/seedance2_0) + +--- + +### Higgsfield + +Full-stack video creation platform with cinematic camera controls. + +**Best for:** Social video ads, cinematic style, mobile-first content +**Platform:** [higgsfield.ai](https://higgsfield.ai/) + +**Capabilities:** +- 50+ professional camera movements (zooms, pans, FPV drone shots) +- Image-to-video animation +- Built-in editing, transitions, and keyframing +- All-in-one workflow: image gen, animation, editing + +**Ad creative use cases:** +- Social media video ads with cinematic feel +- Animate product images into dynamic video +- Create multiple video variations with different camera styles +- Quick-turn video content for social campaigns + +--- + +### Video Tool Comparison + +| Tool | Max Length | Audio | Resolution | API | Best For | +|------|-----------|-------|------------|-----|----------| +| **Veo 3.1** | 60 sec | Native | 1080p/4K | Gemini | Vertical social video | +| **Kling 2.6** | 3 min | Native | 1080p | Third-party | Longer cinematic | +| **Runway Gen-4** | 10 sec | No | 1080p | Official | Controlled, consistent | +| **Sora 2** | 60 sec | Native | 1080p | Official | Dialogue-heavy | +| **Seedance 2.0** | 20 sec | Native | 2K | Official + third-party | Affordable high-volume | +| **Higgsfield** | Varies | Yes | 1080p | Web-based | Social, mobile-first | + +--- + +## Voice & Audio Generation + +For layering realistic voiceovers onto video ads, adding narration to product demos, or generating audio for Remotion-rendered videos. These tools turn ad scripts into natural-sounding voice tracks. + +### When to Use Voice Tools + +Many video generators (Veo, Kling, Sora, Seedance) now include native audio. Use standalone voice tools when you need: + +- **Voiceover on silent video** — Runway Gen-4 and Remotion produce silent output +- **Brand voice consistency** — Clone a specific voice for all ads +- **Multi-language versions** — Same ad script in 20+ languages +- **Script iteration** — Re-record voiceover without reshooting video +- **Precise control** — Exact timing, emotion, and pacing + +--- + +### ElevenLabs + +The market leader in realistic voice generation and voice cloning. + +**Best for:** Most natural-sounding voiceovers, brand voice cloning, multilingual +**API:** REST API with streaming support +**Pricing:** ~$0.12-0.30 per 1,000 characters depending on plan; starts at $5/month + +**Capabilities:** +- 29+ languages with natural accent and intonation +- Voice cloning from short audio clips (instant) or longer recordings (professional) +- Emotion and style control +- Streaming for real-time generation +- Voice library with hundreds of pre-built voices + +**Ad creative use cases:** +- Generate voiceover tracks for video ads +- Clone your brand spokesperson's voice for all ad variations +- Produce the same ad in 10+ languages from one script +- A/B test different voice styles (authoritative vs. friendly vs. urgent) + +**API example:** +```bash +curl -X POST "https://api.elevenlabs.io/v1/text-to-speech/{voice_id}" \ + -H "xi-api-key: $ELEVENLABS_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "text": "Stop wasting hours on manual reporting. Try DataFlow free for 14 days.", + "model_id": "eleven_multilingual_v2", + "voice_settings": {"stability": 0.5, "similarity_boost": 0.75} + }' --output voiceover.mp3 +``` + +**Docs:** [ElevenLabs API](https://elevenlabs.io/docs/api-reference/text-to-speech) + +--- + +### OpenAI TTS + +Simple, affordable text-to-speech built into the OpenAI API. + +**Best for:** Quick voiceovers, cost-effective at scale, simple integration +**API:** OpenAI API (same SDK as GPT/DALL-E) +**Pricing:** $15/million chars (standard), $30/million chars (HD); ~$0.015/min with gpt-4o-mini-tts + +**Capabilities:** +- 13 built-in voices (no custom cloning) +- Multiple languages +- Real-time streaming +- HD quality option +- Simple API — same SDK you already use for GPT + +**Ad creative use cases:** +- Fast, cheap voiceover for draft/test ad versions +- High-volume narration at low cost +- Prototype ad audio before investing in premium voice + +**Docs:** [OpenAI TTS](https://platform.openai.com/docs/guides/text-to-speech) + +--- + +### Cartesia Sonic + +Ultra-low latency voice generation built for real-time applications. + +**Best for:** Real-time voice, lowest latency, emotional expressiveness +**API:** REST + WebSocket streaming +**Pricing:** Starts at $5/month; pay-as-you-go from $0.03/min + +**Capabilities:** +- 40ms time-to-first-audio (fastest in class) +- 15+ languages +- Nonverbal expressiveness: laughter, breathing, emotional inflections +- Sonic Turbo for even lower latency +- Streaming API for real-time generation + +**Ad creative use cases:** +- Real-time ad preview during creative iteration +- Interactive demo videos with dynamic narration +- Ads requiring natural laughter, sighs, or emotional reactions + +**Docs:** [Cartesia Sonic](https://docs.cartesia.ai/build-with-cartesia/tts-models/latest) + +--- + +### Voicebox (Open Source) + +Free, local-first voice synthesis studio powered by Qwen3-TTS. The open-source alternative to ElevenLabs. + +**Best for:** Free voice cloning, local/private generation, zero-cost batch production +**API:** Local REST API at `http://localhost:8000` +**Pricing:** Free (MIT license). Runs entirely on your machine. +**Stack:** Tauri (Rust) + React + FastAPI (Python) + +**Capabilities:** +- Voice cloning from short audio samples via Qwen3-TTS +- Multi-language support (English, Chinese, more planned) +- Multi-track timeline editor for composing conversations +- 4-5x faster inference on Apple Silicon via MLX Metal acceleration +- Local REST API for programmatic generation +- No cloud dependency — all processing on-device + +**Ad creative use cases:** +- Free voice cloning for brand spokesperson across all ad variations +- Batch generate voiceovers without per-character costs +- Private/local generation when ad content is sensitive or pre-launch +- Prototype voice variations before committing to a paid service + +**API example:** +```bash +curl -X POST http://localhost:8000/generate \ + -H "Content-Type: application/json" \ + -d '{"text": "Stop wasting hours on manual reporting.", "profile_id": "abc123", "language": "en"}' +``` + +**Install:** Desktop apps for macOS and Windows at [voicebox.sh](https://voicebox.sh), or build from source: +```bash +git clone https://github.com/jamiepine/voicebox.git +cd voicebox && make setup && make dev +``` + +**Docs:** [GitHub](https://github.com/jamiepine/voicebox) + +--- + +### Other Voice Tools + +| Tool | Best For | Differentiator | API | +|------|----------|---------------|-----| +| **PlayHT** | Large voice library, low latency | 900+ voices, <300ms latency, ultra-realistic | [play.ht](https://play.ht/) | +| **Resemble AI** | Enterprise voice cloning | On-premise deployment, real-time speech-to-speech | [resemble.ai](https://www.resemble.ai/) | +| **WellSaid Labs** | Ethical, commercial-safe voices | Voices from compensated actors, safe for commercial use | [wellsaid.io](https://www.wellsaid.io/) | +| **Fish Audio** | Budget-friendly, emotion control | ~50-70% cheaper than ElevenLabs, emotion tags | [fish.audio](https://fish.audio/) | +| **Murf AI** | Non-technical teams | Browser-based studio, 200+ voices | [murf.ai](https://murf.ai/) | +| **Google Cloud TTS** | Google ecosystem, scale | 220+ voices, 40+ languages, enterprise SLAs | [Google TTS](https://cloud.google.com/text-to-speech) | +| **Amazon Polly** | AWS ecosystem, cost | Neural voices, SSML control, cheap at volume | [Amazon Polly](https://aws.amazon.com/polly/) | + +--- + +### Voice Tool Comparison + +| Tool | Quality | Cloning | Languages | Latency | Price/1K chars | +|------|---------|---------|-----------|---------|----------------| +| **ElevenLabs** | Best | Yes (instant + pro) | 29+ | ~200ms | $0.12-0.30 | +| **OpenAI TTS** | Good | No | 13+ | ~300ms | $0.015-0.030 | +| **Cartesia Sonic** | Very good | No | 15+ | ~40ms | ~$0.03/min | +| **PlayHT** | Very good | Yes | 140+ | <300ms | ~$0.10-0.20 | +| **Fish Audio** | Good | Yes | 13+ | ~200ms | ~$0.05-0.10 | +| **WellSaid** | Very good | No (actor voices) | English | ~300ms | Custom pricing | +| **Voicebox** | Good | Yes (local) | 2+ | Local | Free (open source) | + +### Choosing a Voice Tool + +``` +Need voiceover for ads? +├── Need to clone a specific brand voice? +│ ├── Best quality → ElevenLabs +│ ├── Enterprise/on-premise → Resemble AI +│ └── Budget-friendly → Fish Audio, PlayHT +├── Need multilingual (same ad, many languages)? +│ ├── Most languages → PlayHT (140+) +│ └── Best quality → ElevenLabs (29+) +├── Need free / open source / local? +│ └── Voicebox (MIT, runs on your machine) +├── Need cheap, fast, good-enough? +│ └── OpenAI TTS ($0.015/min) +├── Need commercially-safe licensing? +│ └── WellSaid Labs (actor-compensated voices) +└── Need real-time/interactive? + └── Cartesia Sonic (40ms TTFA) +``` + +### Workflow: Voice + Video + +``` +1. Write ad script (use ad-creative skill for copy) +2. Generate voiceover with ElevenLabs/OpenAI TTS +3. Generate or render video: + a. Silent video from Runway/Remotion → layer voice track + b. Or use Veo/Sora/Seedance with native audio (skip separate VO) +4. Combine with ffmpeg if layering separately: + ffmpeg -i video.mp4 -i voiceover.mp3 -c:v copy -c:a aac output.mp4 +5. Generate variations (different scripts, voices, or languages) +``` + +--- + +## Code-Based Video: Remotion + +For templated, data-driven video ads at scale, Remotion is the best option. Unlike AI video generators that produce unique video from prompts, Remotion uses React code to render deterministic, brand-perfect video from templates and data. + +**Best for:** Templated ad variations, personalized video, brand-consistent production +**Stack:** React + TypeScript +**Pricing:** Free for individuals/small teams; commercial license required for 4+ employees +**Docs:** [remotion.dev](https://www.remotion.dev/) + +### Why Remotion for Ads + +| AI Video Generators | Remotion | +|---------------------|----------| +| Unique output each time | Deterministic, pixel-perfect | +| Prompt-based, less control | Full code control over every frame | +| Hard to match brand exactly | Exact brand colors, fonts, spacing | +| One-at-a-time generation | Batch render hundreds from data | +| No dynamic data insertion | Personalize with names, prices, stats | + +### Ad Creative Use Cases + +**1. Dynamic product ads** +Feed a JSON array of products and render a unique video ad for each: +```tsx +// Simplified Remotion component for product ads +export const ProductAd: React.FC<{ + productName: string; + price: string; + imageUrl: string; + tagline: string; +}> = ({productName, price, imageUrl, tagline}) => { + return ( + + +

{productName}

+

{tagline}

+
{price}
+
Shop Now
+ + ); +}; +``` + +**2. A/B test video variations** +Render the same template with different headlines, CTAs, or color schemes: +```tsx +const variations = [ + {headline: "Save 50% Today", cta: "Get the Deal", theme: "urgent"}, + {headline: "Join 10K+ Teams", cta: "Start Free", theme: "social-proof"}, + {headline: "Built for Speed", cta: "Try It Now", theme: "benefit"}, +]; +// Render all variations programmatically +``` + +**3. Personalized outreach videos** +Generate videos addressing prospects by name for cold outreach or sales. + +**4. Social ad batch production** +Render the same content across different aspect ratios: +- 1:1 for feed +- 9:16 for Stories/Reels +- 16:9 for YouTube + +### Remotion Workflow for Ad Creative + +``` +1. Design template in React (or use AI to generate the component) +2. Define data schema (products, headlines, CTAs, images) +3. Feed data array into template +4. Batch render all variations +5. Upload to ad platform +``` + +### Getting Started + +```bash +# Create a new Remotion project +npx create-video@latest + +# Render a single video +npx remotion render src/index.ts MyComposition out/video.mp4 + +# Batch render from data +npx remotion render src/index.ts MyComposition --props='{"data": [...]}' +``` + +--- + +## Choosing the Right Tool + +### Decision Tree + +``` +Need video ads? +├── Templated, data-driven (same structure, different data) +│ └── Use Remotion +├── Unique creative from prompts (exploratory) +│ ├── Need dialogue/voiceover? → Sora 2, Veo 3.1, Kling 2.6, Seedance 2.0 +│ ├── Need consistency across scenes? → Runway Gen-4 +│ ├── Need vertical social video? → Veo 3.1 (native 9:16) +│ ├── Need high volume at low cost? → Seedance 2.0 +│ └── Need cinematic camera work? → Higgsfield, Kling +└── Both → Use AI gen for hero creative, Remotion for variations + +Need image ads? +├── Need text/headlines in image? → Ideogram +├── Need product consistency across variations? → Flux (multi-ref) +├── Need quick iterations on existing images? → Nano Banana Pro +├── Need highest visual quality? → Flux Pro, Midjourney +└── Need high volume at low cost? → Flux Klein, Nano Banana +``` + +### Cost Comparison for 100 Ad Variations + +| Approach | Tool | Approximate Cost | +|----------|------|-----------------| +| 100 static images | Nano Banana Pro | ~$4-24 | +| 100 static images | Flux Dev | ~$1-2 | +| 100 static images | Ideogram API | ~$6 | +| 100 × 15-sec videos | Veo 3.1 Fast | ~$225 | +| 100 × 15-sec videos | Remotion (templated) | ~$0 (self-hosted render) | +| 10 hero videos + 90 templated | Veo + Remotion | ~$22 + render time | + +### Recommended Workflow for Scaled Ad Production + +1. **Generate hero creative** with AI (Nano Banana, Flux, Veo) — high-quality, exploratory +2. **Build templates** in Remotion based on winning creative patterns +3. **Batch produce variations** with Remotion using data (products, headlines, CTAs) +4. **Iterate** — use AI tools for new angles, Remotion for scale + +This hybrid approach gives you the creative exploration of AI generators and the consistency and scale of code-based rendering. + +--- + +## Platform-Specific Image Specs + +When generating images for ads, request the correct dimensions: + +| Platform | Placement | Aspect Ratio | Recommended Size | +|----------|-----------|-------------|-----------------| +| Meta Feed | Single image | 1:1 | 1080x1080 | +| Meta Stories/Reels | Vertical | 9:16 | 1080x1920 | +| Meta Carousel | Square | 1:1 | 1080x1080 | +| Google Display | Landscape | 1.91:1 | 1200x628 | +| Google Display | Square | 1:1 | 1200x1200 | +| LinkedIn Feed | Landscape | 1.91:1 | 1200x627 | +| LinkedIn Feed | Square | 1:1 | 1200x1200 | +| TikTok Feed | Vertical | 9:16 | 1080x1920 | +| Twitter/X Feed | Landscape | 16:9 | 1200x675 | +| Twitter/X Card | Landscape | 1.91:1 | 800x418 | + +Include these dimensions in your generation prompts to avoid needing to crop or resize. diff --git a/skills/ad-creative/references/platform-specs.md b/skills/ad-creative/references/platform-specs.md new file mode 100644 index 00000000..c9a3c4a5 --- /dev/null +++ b/skills/ad-creative/references/platform-specs.md @@ -0,0 +1,213 @@ +# Platform Specs Reference + +Complete character limits, format requirements, and best practices for each ad platform. + +--- + +## Google Ads + +### Responsive Search Ads (RSAs) + +| Element | Character Limit | Required | Notes | +|---------|----------------|----------|-------| +| Headline | 30 chars | 3 minimum, 15 max | Any 3 may be shown together | +| Description | 90 chars | 2 minimum, 4 max | Any 2 may be shown together | +| Display path 1 | 15 chars | Optional | Appears after domain in URL | +| Display path 2 | 15 chars | Optional | Appears after path 1 | +| Final URL | No limit | Required | Landing page URL | + +**Combination rules:** +- Google selects up to 3 headlines and 2 descriptions to show +- Headlines appear separated by " | " or stacked +- Any headline can appear in any position unless pinned +- Pinning reduces Google's ability to optimize — use sparingly + +**Pinning strategy:** +- Pin your brand name to position 1 if brand guidelines require it +- Pin your strongest CTA to position 2 or 3 +- Leave most headlines unpinned for machine learning + +**Headline mix recommendation (15 headlines):** +- 3-4 keyword-focused (match search intent) +- 3-4 benefit-focused (what they get) +- 2-3 social proof (numbers, awards, customers) +- 2-3 CTA-focused (action to take) +- 1-2 differentiators (why you over competitors) +- 1 brand name headline + +**Description mix recommendation (4 descriptions):** +- 1 benefit + proof point +- 1 feature + outcome +- 1 social proof + CTA +- 1 urgency/offer + CTA (if applicable) + +### Performance Max + +| Element | Character Limit | Notes | +|---------|----------------|-------| +| Headline | 30 chars (5 required) | Short headlines for various placements | +| Long headline | 90 chars (5 required) | Used in display, video, discover | +| Description | 90 chars (1 required, 5 max) | Accompany various ad formats | +| Business name | 25 chars | Required | + +### Display Ads + +| Element | Character Limit | +|---------|----------------| +| Headline | 30 chars | +| Long headline | 90 chars | +| Description | 90 chars | +| Business name | 25 chars | + +--- + +## Meta Ads (Facebook & Instagram) + +### Single Image / Video / Carousel + +| Element | Recommended | Maximum | Notes | +|---------|-------------|---------|-------| +| Primary text | 125 chars | 2,200 chars | Text above image; truncated after ~125 | +| Headline | 40 chars | 255 chars | Below image; truncated after ~40 | +| Description | 30 chars | 255 chars | Below headline; may not show | +| URL display link | 40 chars | N/A | Optional custom display URL | + +**Placement-specific notes:** +- **Feed**: All elements show; primary text most visible +- **Stories/Reels**: Primary text overlaid; keep under 72 chars +- **Right column**: Only headline visible; skip description +- **Audience Network**: Varies by publisher + +**Best practices:** +- Front-load the hook in primary text (first 125 chars) +- Use line breaks for readability in longer primary text +- Emojis: test, but don't overuse — 1-2 per ad max +- Questions in primary text increase engagement +- Headline should be a clear CTA or value statement + +### Lead Ads (Instant Form) + +| Element | Limit | +|---------|-------| +| Greeting headline | 60 chars | +| Greeting description | 360 chars | +| Privacy policy text | 200 chars | + +--- + +## LinkedIn Ads + +### Single Image Ad + +| Element | Recommended | Maximum | Notes | +|---------|-------------|---------|-------| +| Intro text | 150 chars | 600 chars | Above the image; truncated after ~150 | +| Headline | 70 chars | 200 chars | Below the image | +| Description | 100 chars | 300 chars | Only shows on Audience Network | + +### Carousel Ad + +| Element | Limit | +|---------|-------| +| Intro text | 255 chars | +| Card headline | 45 chars | +| Card count | 2-10 cards | + +### Message Ad (InMail) + +| Element | Limit | +|---------|-------| +| Subject line | 60 chars | +| Message body | 1,500 chars | +| CTA button | 20 chars | + +### Text Ad + +| Element | Limit | +|---------|-------| +| Headline | 25 chars | +| Description | 75 chars | + +**LinkedIn-specific guidelines:** +- Professional tone, but not boring +- Use job-specific language the audience recognizes +- Statistics and data points perform well +- Avoid consumer-style hype ("Amazing!" "Incredible!") +- First-person testimonials from peers resonate + +--- + +## TikTok Ads + +### In-Feed Ads + +| Element | Recommended | Maximum | Notes | +|---------|-------------|---------|-------| +| Ad text | 80 chars | 100 chars | Above the video | +| Display name | N/A | 40 chars | Brand name | +| CTA button | Platform options | Predefined | Select from TikTok's options | + +### Spark Ads (Boosted Organic) + +| Element | Notes | +|---------|-------| +| Caption | Uses original post caption | +| CTA button | Added by advertiser | +| Display name | Original creator's handle | + +**TikTok-specific guidelines:** +- Native content outperforms polished ads +- First 2 seconds determine if they watch +- Use trending sounds and formats +- Text overlay is essential (most watch with sound off) +- Vertical video only (9:16) + +--- + +## Twitter/X Ads + +### Promoted Tweets + +| Element | Limit | Notes | +|---------|-------|-------| +| Tweet text | 280 chars | Full tweet with image/video | +| Card headline | 70 chars | Website card | +| Card description | 200 chars | Website card | + +### Website Cards + +| Element | Limit | +|---------|-------| +| Headline | 70 chars | +| Description | 200 chars | + +**Twitter/X-specific guidelines:** +- Conversational, casual tone +- Short sentences work best +- One clear message per tweet +- Hashtags: 1-2 max (0 is often better for ads) +- Threads can work for consideration-stage content + +--- + +## Character Counting Tips + +- **Spaces count** as characters on all platforms +- **Emojis** count as 1-2 characters depending on platform +- **Special characters** (|, &, etc.) count as 1 character +- **URLs** in body text count against limits +- **Dynamic keyword insertion** (`{KeyWord:default}`) can exceed limits — set safe defaults +- Always verify in the platform's ad preview before launching + +--- + +## Multi-Platform Creative Adaptation + +When creating for multiple platforms simultaneously, start with the most restrictive format: + +1. **Google Search headlines** (30 chars) — forces the tightest messaging +2. **Expand to Meta headlines** (40 chars) — add a word or two +3. **Expand to LinkedIn intro text** (150 chars) — add context and proof +4. **Expand to Meta primary text** (125+ chars) — full hook and value prop + +This cascading approach ensures your core message works everywhere, then gets enriched for platforms that allow more space. diff --git a/skills/ai-seo/SKILL.md b/skills/ai-seo/SKILL.md new file mode 100644 index 00000000..168bbfe8 --- /dev/null +++ b/skills/ai-seo/SKILL.md @@ -0,0 +1,407 @@ +--- +name: ai-seo +description: "Optimize content for AI search and LLM citations across AI Overviews, ChatGPT, Perplexity, Claude, Gemini, and similar systems. Use when improving AI visibility, answer engine optimization, or citation readiness." +risk: unknown +source: "https://github.com/coreyhaines31/marketingskills" +date_added: "2026-03-21" +metadata: + version: 1.1.0 +--- + +# AI SEO + +You are an expert in AI search optimization — the practice of making content discoverable, extractable, and citable by AI systems including Google AI Overviews, ChatGPT, Perplexity, Claude, Gemini, and Copilot. Your goal is to help users get their content cited as a source in AI-generated answers. + +## When to Use + +- Use when optimizing content to be cited by LLMs and AI search systems. +- Use when the user asks about AI SEO, AEO, GEO, LLM visibility, or AI citations. +- Use when traditional SEO alone is not the full question and AI-specific discoverability matters. + +## Before Starting + +**Check for product marketing context first:** +If `.agents/product-marketing-context.md` exists (or `.claude/product-marketing-context.md` in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task. + +Gather this context (ask if not provided): + +### 1. Current AI Visibility +- Do you know if your brand appears in AI-generated answers today? +- Have you checked ChatGPT, Perplexity, or Google AI Overviews for your key queries? +- What queries matter most to your business? + +### 2. Content & Domain +- What type of content do you produce? (Blog, docs, comparisons, product pages) +- What's your domain authority / traditional SEO strength? +- Do you have existing structured data (schema markup)? + +### 3. Goals +- Get cited as a source in AI answers? +- Appear in Google AI Overviews for specific queries? +- Compete with specific brands already getting cited? +- Optimize existing content or create new AI-optimized content? + +### 4. Competitive Landscape +- Who are your top competitors in AI search results? +- Are they being cited where you're not? + +--- + +## How AI Search Works + +### The AI Search Landscape + +| Platform | How It Works | Source Selection | +|----------|-------------|----------------| +| **Google AI Overviews** | Summarizes top-ranking pages | Strong correlation with traditional rankings | +| **ChatGPT (with search)** | Searches web, cites sources | Draws from wider range, not just top-ranked | +| **Perplexity** | Always cites sources with links | Favors authoritative, recent, well-structured content | +| **Gemini** | Google's AI assistant | Pulls from Google index + Knowledge Graph | +| **Copilot** | Bing-powered AI search | Bing index + authoritative sources | +| **Claude** | Brave Search (when enabled) | Training data + Brave search results | + +For a deep dive on how each platform selects sources and what to optimize per platform, see [references/platform-ranking-factors.md](references/platform-ranking-factors.md). + +### Key Difference from Traditional SEO + +Traditional SEO gets you ranked. AI SEO gets you **cited**. + +In traditional search, you need to rank on page 1. In AI search, a well-structured page can get cited even if it ranks on page 2 or 3 — AI systems select sources based on content quality, structure, and relevance, not just rank position. + +**Critical stats:** +- AI Overviews appear in ~45% of Google searches +- AI Overviews reduce clicks to websites by up to 58% +- Brands are 6.5x more likely to be cited via third-party sources than their own domains +- Optimized content gets cited 3x more often than non-optimized +- Statistics and citations boost visibility by 40%+ across queries + +--- + +## AI Visibility Audit + +Before optimizing, assess your current AI search presence. + +### Step 1: Check AI Answers for Your Key Queries + +Test 10-20 of your most important queries across platforms: + +| Query | Google AI Overview | ChatGPT | Perplexity | You Cited? | Competitors Cited? | +|-------|:-----------------:|:-------:|:----------:|:----------:|:-----------------:| +| [query 1] | Yes/No | Yes/No | Yes/No | Yes/No | [who] | +| [query 2] | Yes/No | Yes/No | Yes/No | Yes/No | [who] | + +**Query types to test:** +- "What is [your product category]?" +- "Best [product category] for [use case]" +- "[Your brand] vs [competitor]" +- "How to [problem your product solves]" +- "[Your product category] pricing" + +### Step 2: Analyze Citation Patterns + +When your competitors get cited and you don't, examine: +- **Content structure** — Is their content more extractable? +- **Authority signals** — Do they have more citations, stats, expert quotes? +- **Freshness** — Is their content more recently updated? +- **Schema markup** — Do they have structured data you're missing? +- **Third-party presence** — Are they cited via Wikipedia, Reddit, review sites? + +### Step 3: Content Extractability Check + +For each priority page, verify: + +| Check | Pass/Fail | +|-------|-----------| +| Clear definition in first paragraph? | | +| Self-contained answer blocks (work without surrounding context)? | | +| Statistics with sources cited? | | +| Comparison tables for "[X] vs [Y]" queries? | | +| FAQ section with natural-language questions? | | +| Schema markup (FAQ, HowTo, Article, Product)? | | +| Expert attribution (author name, credentials)? | | +| Recently updated (within 6 months)? | | +| Heading structure matches query patterns? | | +| AI bots allowed in robots.txt? | | + +### Step 4: AI Bot Access Check + +Verify your robots.txt allows AI crawlers. Each AI platform has its own bot, and blocking it means that platform can't cite you: + +- **GPTBot** and **ChatGPT-User** — OpenAI (ChatGPT) +- **PerplexityBot** — Perplexity +- **ClaudeBot** and **anthropic-ai** — Anthropic (Claude) +- **Google-Extended** — Google Gemini and AI Overviews +- **Bingbot** — Microsoft Copilot (via Bing) + +Check your robots.txt for `Disallow` rules targeting any of these. If you find them blocked, you have a business decision to make: blocking prevents AI training on your content but also prevents citation. One middle ground is blocking training-only crawlers (like **CCBot** from Common Crawl) while allowing the search bots listed above. + +See [references/platform-ranking-factors.md](references/platform-ranking-factors.md) for the full robots.txt configuration. + +--- + +## Optimization Strategy + +### The Three Pillars + +``` +1. Structure (make it extractable) +2. Authority (make it citable) +3. Presence (be where AI looks) +``` + +### Pillar 1: Structure — Make Content Extractable + +AI systems extract passages, not pages. Every key claim should work as a standalone statement. + +**Content block patterns:** +- **Definition blocks** for "What is X?" queries +- **Step-by-step blocks** for "How to X" queries +- **Comparison tables** for "X vs Y" queries +- **Pros/cons blocks** for evaluation queries +- **FAQ blocks** for common questions +- **Statistic blocks** with cited sources + +For detailed templates for each block type, see [references/content-patterns.md](references/content-patterns.md). + +**Structural rules:** +- Lead every section with a direct answer (don't bury it) +- Keep key answer passages to 40-60 words (optimal for snippet extraction) +- Use H2/H3 headings that match how people phrase queries +- Tables beat prose for comparison content +- Numbered lists beat paragraphs for process content +- Each paragraph should convey one clear idea + +### Pillar 2: Authority — Make Content Citable + +AI systems prefer sources they can trust. Build citation-worthiness. + +**The Princeton GEO research** (KDD 2024, studied across Perplexity.ai) ranked 9 optimization methods: + +| Method | Visibility Boost | How to Apply | +|--------|:---------------:|--------------| +| **Cite sources** | +40% | Add authoritative references with links | +| **Add statistics** | +37% | Include specific numbers with sources | +| **Add quotations** | +30% | Expert quotes with name and title | +| **Authoritative tone** | +25% | Write with demonstrated expertise | +| **Improve clarity** | +20% | Simplify complex concepts | +| **Technical terms** | +18% | Use domain-specific terminology | +| **Unique vocabulary** | +15% | Increase word diversity | +| **Fluency optimization** | +15-30% | Improve readability and flow | +| ~~Keyword stuffing~~ | **-10%** | **Actively hurts AI visibility** | + +**Best combination:** Fluency + Statistics = maximum boost. Low-ranking sites benefit even more — up to 115% visibility increase with citations. + +**Statistics and data** (+37-40% citation boost) +- Include specific numbers with sources +- Cite original research, not summaries of research +- Add dates to all statistics +- Original data beats aggregated data + +**Expert attribution** (+25-30% citation boost) +- Named authors with credentials +- Expert quotes with titles and organizations +- "According to [Source]" framing for claims +- Author bios with relevant expertise + +**Freshness signals** +- "Last updated: [date]" prominently displayed +- Regular content refreshes (quarterly minimum for competitive topics) +- Current year references and recent statistics +- Remove or update outdated information + +**E-E-A-T alignment** +- First-hand experience demonstrated +- Specific, detailed information (not generic) +- Transparent sourcing and methodology +- Clear author expertise for the topic + +### Pillar 3: Presence — Be Where AI Looks + +AI systems don't just cite your website — they cite where you appear. + +**Third-party sources matter more than your own site:** +- Wikipedia mentions (7.8% of all ChatGPT citations) +- Reddit discussions (1.8% of ChatGPT citations) +- Industry publications and guest posts +- Review sites (G2, Capterra, TrustRadius for B2B SaaS) +- YouTube (frequently cited by Google AI Overviews) +- Quora answers + +**Actions:** +- Ensure your Wikipedia page is accurate and current +- Participate authentically in Reddit communities +- Get featured in industry roundups and comparison articles +- Maintain updated profiles on relevant review platforms +- Create YouTube content for key how-to queries +- Answer relevant Quora questions with depth + +### Schema Markup for AI + +Structured data helps AI systems understand your content. Key schemas: + +| Content Type | Schema | Why It Helps | +|-------------|--------|-------------| +| Articles/Blog posts | `Article`, `BlogPosting` | Author, date, topic identification | +| How-to content | `HowTo` | Step extraction for process queries | +| FAQs | `FAQPage` | Direct Q&A extraction | +| Products | `Product` | Pricing, features, reviews | +| Comparisons | `ItemList` | Structured comparison data | +| Reviews | `Review`, `AggregateRating` | Trust signals | +| Organization | `Organization` | Entity recognition | + +Content with proper schema shows 30-40% higher AI visibility. For implementation, use the **schema-markup** skill. + +--- + +## Content Types That Get Cited Most + +Not all content is equally citable. Prioritize these formats: + +| Content Type | Citation Share | Why AI Cites It | +|-------------|:------------:|----------------| +| **Comparison articles** | ~33% | Structured, balanced, high-intent | +| **Definitive guides** | ~15% | Comprehensive, authoritative | +| **Original research/data** | ~12% | Unique, citable statistics | +| **Best-of/listicles** | ~10% | Clear structure, entity-rich | +| **Product pages** | ~10% | Specific details AI can extract | +| **How-to guides** | ~8% | Step-by-step structure | +| **Opinion/analysis** | ~10% | Expert perspective, quotable | + +**Underperformers for AI citation:** +- Generic blog posts without structure +- Thin product pages with marketing fluff +- Gated content (AI can't access it) +- Content without dates or author attribution +- PDF-only content (harder for AI to parse) + +--- + +## Monitoring AI Visibility + +### What to Track + +| Metric | What It Measures | How to Check | +|--------|-----------------|-------------| +| AI Overview presence | Do AI Overviews appear for your queries? | Manual check or Semrush/Ahrefs | +| Brand citation rate | How often you're cited in AI answers | AI visibility tools (see below) | +| Share of AI voice | Your citations vs. competitors | Peec AI, Otterly, ZipTie | +| Citation sentiment | How AI describes your brand | Manual review + monitoring tools | +| Source attribution | Which of your pages get cited | Track referral traffic from AI sources | + +### AI Visibility Monitoring Tools + +| Tool | Coverage | Best For | +|------|----------|----------| +| **Otterly AI** | ChatGPT, Perplexity, Google AI Overviews | Share of AI voice tracking | +| **Peec AI** | ChatGPT, Gemini, Perplexity, Claude, Copilot+ | Multi-platform monitoring at scale | +| **ZipTie** | Google AI Overviews, ChatGPT, Perplexity | Brand mention + sentiment tracking | +| **LLMrefs** | ChatGPT, Perplexity, AI Overviews, Gemini | SEO keyword → AI visibility mapping | + +### DIY Monitoring (No Tools) + +Monthly manual check: +1. Pick your top 20 queries +2. Run each through ChatGPT, Perplexity, and Google +3. Record: Are you cited? Who is? What page? +4. Log in a spreadsheet, track month-over-month + +--- + +## AI SEO for Different Content Types + +### SaaS Product Pages + +**Goal:** Get cited in "What is [category]?" and "Best [category]" queries. + +**Optimize:** +- Clear product description in first paragraph (what it does, who it's for) +- Feature comparison tables (you vs. category, not just competitors) +- Specific metrics ("processes 10,000 transactions/sec" not "blazing fast") +- Customer count or social proof with numbers +- Pricing transparency (AI cites pages with visible pricing) +- FAQ section addressing common buyer questions + +### Blog Content + +**Goal:** Get cited as an authoritative source on topics in your space. + +**Optimize:** +- One clear target query per post (match heading to query) +- Definition in first paragraph for "What is" queries +- Original data, research, or expert quotes +- "Last updated" date visible +- Author bio with relevant credentials +- Internal links to related product/feature pages + +### Comparison/Alternative Pages + +**Goal:** Get cited in "[X] vs [Y]" and "Best [X] alternatives" queries. + +**Optimize:** +- Structured comparison tables (not just prose) +- Fair and balanced (AI penalizes obviously biased comparisons) +- Specific criteria with ratings or scores +- Updated pricing and feature data +- Cite the competitor-alternatives skill for building these pages + +### Documentation / Help Content + +**Goal:** Get cited in "How to [X] with [your product]" queries. + +**Optimize:** +- Step-by-step format with numbered lists +- Code examples where relevant +- HowTo schema markup +- Screenshots with descriptive alt text +- Clear prerequisites and expected outcomes + +--- + +## Common Mistakes + +- **Ignoring AI search entirely** — ~45% of Google searches now show AI Overviews, and ChatGPT/Perplexity are growing fast +- **Treating AI SEO as separate from SEO** — Good traditional SEO is the foundation; AI SEO adds structure and authority on top +- **Writing for AI, not humans** — If content reads like it was written to game an algorithm, it won't get cited or convert +- **No freshness signals** — Undated content loses to dated content because AI systems weight recency heavily. Show when content was last updated +- **Gating all content** — AI can't access gated content. Keep your most authoritative content open +- **Ignoring third-party presence** — You may get more AI citations from a Wikipedia mention than from your own blog +- **No structured data** — Schema markup gives AI systems structured context about your content +- **Keyword stuffing** — Unlike traditional SEO where it's just ineffective, keyword stuffing actively reduces AI visibility by 10% (Princeton GEO study) +- **Blocking AI bots** — If GPTBot, PerplexityBot, or ClaudeBot are blocked in robots.txt, those platforms can't cite you +- **Generic content without data** — "We're the best" won't get cited. "Our customers see 3x improvement in [metric]" will +- **Forgetting to monitor** — You can't improve what you don't measure. Check AI visibility monthly at minimum + +--- + +## Tool Integrations + +For implementation, use the SEO and monitoring tools available in the current environment. + +| Tool | Use For | +|------|---------| +| `semrush` | AI Overview tracking, keyword research, content gap analysis | +| `ahrefs` | Backlink analysis, content explorer, AI Overview data | +| `gsc` | Search Console performance data, query tracking | +| `ga4` | Referral traffic from AI sources | + +--- + +## Task-Specific Questions + +1. What are your top 10-20 most important queries? +2. Have you checked if AI answers exist for those queries today? +3. Do you have structured data (schema markup) on your site? +4. What content types do you publish? (Blog, docs, comparisons, etc.) +5. Are competitors being cited by AI where you're not? +6. Do you have a Wikipedia page or presence on review sites? + +--- + +## Related Skills + +- **seo-audit**: For traditional technical and on-page SEO audits +- **schema-markup**: For implementing structured data that helps AI understand your content +- **content-strategy**: For planning what content to create +- **competitor-alternatives**: For building comparison pages that get cited +- **programmatic-seo**: For building SEO pages at scale +- **copywriting**: For writing content that's both human-readable and AI-extractable diff --git a/skills/ai-seo/evals/evals.json b/skills/ai-seo/evals/evals.json new file mode 100644 index 00000000..327ade34 --- /dev/null +++ b/skills/ai-seo/evals/evals.json @@ -0,0 +1,90 @@ +{ + "skill_name": "ai-seo", + "evals": [ + { + "id": 1, + "prompt": "How do I make sure our SaaS product shows up in AI search results? We're a project management tool and we keep getting left out of ChatGPT and Perplexity recommendations when people ask about project management software.", + "expected_output": "Should check for product-marketing-context.md first. Should apply the three pillars framework: Structure (make content extractable), Authority (make content citable), Presence (be where AI looks). Should run through the AI Visibility Audit checklist across platforms (Google AI Overviews, ChatGPT, Perplexity, etc.). Should check content extractability (clear definitions, structured comparisons, statistics). Should reference Princeton GEO research findings (citations improve visibility +40%, statistics +37%). Should check AI bot access in robots.txt. Should provide a prioritized action plan.", + "assertions": [ + "Checks for product-marketing-context.md", + "Applies three pillars framework (Structure, Authority, Presence)", + "Runs AI Visibility Audit across platforms", + "Checks content extractability", + "References Princeton GEO research findings", + "Checks AI bot access in robots.txt", + "Provides prioritized action plan" + ], + "files": [] + }, + { + "id": 2, + "prompt": "Should we block AI crawlers like GPTBot and PerplexityBot in our robots.txt? We're worried about content theft.", + "expected_output": "Should address the AI bot access question directly. Should explain the tradeoff: blocking AI bots prevents training on your content but also prevents AI platforms from citing and recommending you. Should reference the specific bots and their purposes (GPTBot, Google-Extended, PerplexityBot, ClaudeBot, etc.). Should provide the recommended robots.txt configuration. Should explain that blocking may hurt AI visibility more than it protects content. Should provide a nuanced recommendation based on business goals.", + "assertions": [ + "Addresses the blocking tradeoff directly", + "Explains impact on AI visibility vs content protection", + "Lists specific AI bot user agents", + "Provides recommended robots.txt configuration", + "Gives nuanced recommendation based on business goals", + "Explains what each bot does" + ], + "files": [] + }, + { + "id": 3, + "prompt": "What kind of content gets cited most by AI systems? We want to create content specifically optimized for AI search.", + "expected_output": "Should reference the content types that get cited most, including comparisons (~33% of AI citations), definitive guides (~15%), and other high-citation content types. Should explain why these formats work (they provide the structured, extractable, authoritative information AI systems need). Should provide specific recommendations for creating AI-optimized content: clear definitions, structured data, original statistics, comparison tables, expert quotes. Should reference the Princeton GEO research on what increases citation probability.", + "assertions": [ + "References specific content types with citation rates", + "Mentions comparisons as highest-cited format", + "Explains why these formats work for AI", + "Provides specific content creation recommendations", + "References Princeton GEO research", + "Mentions structured data, statistics, and clear definitions" + ], + "files": [] + }, + { + "id": 4, + "prompt": "we noticed our competitors are showing up in google AI overviews but we're not. what do we need to change?", + "expected_output": "Should trigger on casual phrasing. Should focus specifically on Google AI Overviews visibility. Should explain how AI Overviews selects sources (authoritative, well-structured, directly answers queries). Should run through the Structure pillar checklist: content extractability, heading hierarchy, answer-first format, structured data. Should check Authority signals: domain authority, citations, E-E-A-T. Should recommend specific content structure changes. Should suggest monitoring approach.", + "assertions": [ + "Triggers on casual phrasing", + "Focuses on Google AI Overviews specifically", + "Explains how AI Overviews selects sources", + "Checks Structure pillar (extractability, headings, answer-first)", + "Checks Authority signals", + "Recommends specific content structure changes", + "Suggests monitoring approach" + ], + "files": [] + }, + { + "id": 5, + "prompt": "Can you audit our website for AI search readiness? We want to know how visible we are across ChatGPT, Perplexity, Google AI Overviews, and other AI platforms.", + "expected_output": "Should run the full AI Visibility Audit. Should check each platform in the landscape (Google AI Overviews, ChatGPT, Perplexity, Claude, Gemini, Copilot). Should evaluate all three pillars: Structure (content extractability, JSON-LD, clear definitions), Authority (citations, backlinks, E-E-A-T signals), Presence (AI bot access, platform-specific factors). Should provide findings organized by pillar. Should provide a prioritized action plan with specific fixes.", + "assertions": [ + "Runs full AI Visibility Audit", + "Checks multiple AI platforms", + "Evaluates all three pillars (Structure, Authority, Presence)", + "Checks content extractability", + "Checks AI bot access", + "Provides findings organized by pillar", + "Provides prioritized action plan" + ], + "files": [] + }, + { + "id": 6, + "prompt": "Our organic search traffic has dropped 30% this quarter. Can you do a full SEO audit to figure out what's going on?", + "expected_output": "Should recognize this is a traditional SEO audit request, not specifically an AI SEO task. Should defer to or cross-reference the seo-audit skill, which handles comprehensive traditional SEO audits including crawlability, technical foundations, on-page optimization, and content quality. May mention AI search as one factor to investigate but should make clear that seo-audit is the primary skill for this task.", + "assertions": [ + "Recognizes this as a traditional SEO audit request", + "References or defers to seo-audit skill", + "Does not attempt a full traditional SEO audit using AI SEO patterns", + "May mention AI search as one factor to consider" + ], + "files": [] + } + ] +} diff --git a/skills/ai-seo/references/content-patterns.md b/skills/ai-seo/references/content-patterns.md new file mode 100644 index 00000000..e1926c80 --- /dev/null +++ b/skills/ai-seo/references/content-patterns.md @@ -0,0 +1,285 @@ +# AEO and GEO Content Patterns + +Reusable content block patterns optimized for answer engines and AI citation. + +--- + +## Contents +- Answer Engine Optimization (AEO) Patterns (Definition Block, Step-by-Step Block, Comparison Table Block, Pros and Cons Block, FAQ Block, Listicle Block) +- Generative Engine Optimization (GEO) Patterns (Statistic Citation Block, Expert Quote Block, Authoritative Claim Block, Self-Contained Answer Block, Evidence Sandwich Block) +- Domain-Specific GEO Tactics (Technology Content, Health/Medical Content, Financial Content, Legal Content, Business/Marketing Content) +- Voice Search Optimization (Question Formats for Voice, Voice-Optimized Answer Structure) + +## Answer Engine Optimization (AEO) Patterns + +These patterns help content appear in featured snippets, AI Overviews, voice search results, and answer boxes. + +### Definition Block + +Use for "What is [X]?" queries. + +```markdown +## What is [Term]? + +[Term] is [concise 1-sentence definition]. [Expanded 1-2 sentence explanation with key characteristics]. [Brief context on why it matters or how it's used]. +``` + +**Example:** +```markdown +## What is Answer Engine Optimization? + +Answer Engine Optimization (AEO) is the practice of structuring content so AI-powered systems can easily extract and present it as direct answers to user queries. Unlike traditional SEO that focuses on ranking in search results, AEO optimizes for featured snippets, AI Overviews, and voice assistant responses. This approach has become essential as over 60% of Google searches now end without a click. +``` + +### Step-by-Step Block + +Use for "How to [X]" queries. Optimal for list snippets. + +```markdown +## How to [Action/Goal] + +[1-sentence overview of the process] + +1. **[Step Name]**: [Clear action description in 1-2 sentences] +2. **[Step Name]**: [Clear action description in 1-2 sentences] +3. **[Step Name]**: [Clear action description in 1-2 sentences] +4. **[Step Name]**: [Clear action description in 1-2 sentences] +5. **[Step Name]**: [Clear action description in 1-2 sentences] + +[Optional: Brief note on expected outcome or time estimate] +``` + +**Example:** +```markdown +## How to Optimize Content for Featured Snippets + +Earning featured snippets requires strategic formatting and direct answers to search queries. + +1. **Identify snippet opportunities**: Use tools like Semrush or Ahrefs to find keywords where competitors have snippets you could capture. +2. **Match the snippet format**: Analyze whether the current snippet is a paragraph, list, or table, and format your content accordingly. +3. **Answer the question directly**: Provide a clear, concise answer (40-60 words for paragraph snippets) immediately after the question heading. +4. **Add supporting context**: Expand on your answer with examples, data, and expert insights in the following paragraphs. +5. **Use proper heading structure**: Place your target question as an H2 or H3, with the answer immediately following. + +Most featured snippets appear within 2-4 weeks of publishing well-optimized content. +``` + +### Comparison Table Block + +Use for "[X] vs [Y]" queries. Optimal for table snippets. + +```markdown +## [Option A] vs [Option B]: [Brief Descriptor] + +| Feature | [Option A] | [Option B] | +|---------|------------|------------| +| [Criteria 1] | [Value/Description] | [Value/Description] | +| [Criteria 2] | [Value/Description] | [Value/Description] | +| [Criteria 3] | [Value/Description] | [Value/Description] | +| [Criteria 4] | [Value/Description] | [Value/Description] | +| Best For | [Use case] | [Use case] | + +**Bottom line**: [1-2 sentence recommendation based on different needs] +``` + +### Pros and Cons Block + +Use for evaluation queries: "Is [X] worth it?", "Should I [X]?" + +```markdown +## Advantages and Disadvantages of [Topic] + +[1-sentence overview of the evaluation context] + +### Pros + +- **[Benefit category]**: [Specific explanation] +- **[Benefit category]**: [Specific explanation] +- **[Benefit category]**: [Specific explanation] + +### Cons + +- **[Drawback category]**: [Specific explanation] +- **[Drawback category]**: [Specific explanation] +- **[Drawback category]**: [Specific explanation] + +**Verdict**: [1-2 sentence balanced conclusion with recommendation] +``` + +### FAQ Block + +Use for topic pages with multiple common questions. Essential for FAQ schema. + +```markdown +## Frequently Asked Questions + +### [Question phrased exactly as users search]? + +[Direct answer in first sentence]. [Supporting context in 2-3 additional sentences]. + +### [Question phrased exactly as users search]? + +[Direct answer in first sentence]. [Supporting context in 2-3 additional sentences]. + +### [Question phrased exactly as users search]? + +[Direct answer in first sentence]. [Supporting context in 2-3 additional sentences]. +``` + +**Tips for FAQ questions:** +- Use natural question phrasing ("How do I..." not "How does one...") +- Include question words: what, how, why, when, where, who, which +- Match "People Also Ask" queries from search results +- Keep answers between 50-100 words + +### Listicle Block + +Use for "Best [X]", "Top [X]", "[Number] ways to [X]" queries. + +```markdown +## [Number] Best [Items] for [Goal/Purpose] + +[1-2 sentence intro establishing context and selection criteria] + +### 1. [Item Name] + +[Why it's included in 2-3 sentences with specific benefits] + +### 2. [Item Name] + +[Why it's included in 2-3 sentences with specific benefits] + +### 3. [Item Name] + +[Why it's included in 2-3 sentences with specific benefits] +``` + +--- + +## Generative Engine Optimization (GEO) Patterns + +These patterns optimize content for citation by AI assistants like ChatGPT, Claude, Perplexity, and Gemini. + +### Statistic Citation Block + +Statistics increase AI citation rates by 15-30%. Always include sources. + +```markdown +[Claim statement]. According to [Source/Organization], [specific statistic with number and timeframe]. [Context for why this matters]. +``` + +**Example:** +```markdown +Mobile optimization is no longer optional for SEO success. According to Google's 2024 Core Web Vitals report, 70% of web traffic now comes from mobile devices, and pages failing mobile usability standards see 24% higher bounce rates. This makes mobile-first indexing a critical ranking factor. +``` + +### Expert Quote Block + +Named expert attribution adds credibility and increases citation likelihood. + +```markdown +"[Direct quote from expert]," says [Expert Name], [Title/Role] at [Organization]. [1 sentence of context or interpretation]. +``` + +**Example:** +```markdown +"The shift from keyword-driven search to intent-driven discovery represents the most significant change in SEO since mobile-first indexing," says Rand Fishkin, Co-founder of SparkToro. This perspective highlights why content strategies must evolve beyond traditional keyword optimization. +``` + +### Authoritative Claim Block + +Structure claims for easy AI extraction with clear attribution. + +```markdown +[Topic] [verb: is/has/requires/involves] [clear, specific claim]. [Source] [confirms/reports/found] that [supporting evidence]. This [explains/means/suggests] [implication or action]. +``` + +**Example:** +```markdown +E-E-A-T is the cornerstone of Google's content quality evaluation. Google's Search Quality Rater Guidelines confirm that trust is the most critical factor, stating that "untrustworthy pages have low E-E-A-T no matter how experienced, expert, or authoritative they may seem." This means content creators must prioritize transparency and accuracy above all other optimization tactics. +``` + +### Self-Contained Answer Block + +Create quotable, standalone statements that AI can extract directly. + +```markdown +**[Topic/Question]**: [Complete, self-contained answer that makes sense without additional context. Include specific details, numbers, or examples in 2-3 sentences.] +``` + +**Example:** +```markdown +**Ideal blog post length for SEO**: The optimal length for SEO blog posts is 1,500-2,500 words for competitive topics. This range allows comprehensive topic coverage while maintaining reader engagement. HubSpot research shows long-form content earns 77% more backlinks than short articles, directly impacting search rankings. +``` + +### Evidence Sandwich Block + +Structure claims with evidence for maximum credibility. + +```markdown +[Opening claim statement]. + +Evidence supporting this includes: +- [Data point 1 with source] +- [Data point 2 with source] +- [Data point 3 with source] + +[Concluding statement connecting evidence to actionable insight]. +``` + +--- + +## Domain-Specific GEO Tactics + +Different content domains benefit from different authority signals. + +### Technology Content +- Emphasize technical precision and correct terminology +- Include version numbers and dates for software/tools +- Reference official documentation +- Add code examples where relevant + +### Health/Medical Content +- Cite peer-reviewed studies with publication details +- Include expert credentials (MD, RN, etc.) +- Note study limitations and context +- Add "last reviewed" dates + +### Financial Content +- Reference regulatory bodies (SEC, FTC, etc.) +- Include specific numbers with timeframes +- Note that information is educational, not advice +- Cite recognized financial institutions + +### Legal Content +- Cite specific laws, statutes, and regulations +- Reference jurisdiction clearly +- Include professional disclaimers +- Note when professional consultation is advised + +### Business/Marketing Content +- Include case studies with measurable results +- Reference industry research and reports +- Add percentage changes and timeframes +- Quote recognized thought leaders + +--- + +## Voice Search Optimization + +Voice queries are conversational and question-based. Optimize for these patterns: + +### Question Formats for Voice +- "What is..." +- "How do I..." +- "Where can I find..." +- "Why does..." +- "When should I..." +- "Who is..." + +### Voice-Optimized Answer Structure +- Lead with direct answer (under 30 words ideal) +- Use natural, conversational language +- Avoid jargon unless targeting expert audience +- Include local context where relevant +- Structure for single spoken response diff --git a/skills/ai-seo/references/platform-ranking-factors.md b/skills/ai-seo/references/platform-ranking-factors.md new file mode 100644 index 00000000..4353d090 --- /dev/null +++ b/skills/ai-seo/references/platform-ranking-factors.md @@ -0,0 +1,152 @@ +# How Each AI Platform Picks Sources + +Each AI search platform has its own search index, ranking logic, and content preferences. This guide covers what matters for getting cited on each one. + +Sources cited throughout: Princeton GEO study (KDD 2024), SE Ranking domain authority study, ZipTie content-answer fit analysis. + +--- + +## The Fundamentals + +Every AI platform shares three baseline requirements: + +1. **Your content must be in their index** — Each platform uses a different search backend (Google, Bing, Brave, or their own). If you're not indexed, you can't be cited. +2. **Your content must be crawlable** — AI bots need access via robots.txt. Block the bot, lose the citation. +3. **Your content must be extractable** — AI systems pull passages, not pages. Clear structure and self-contained paragraphs win. + +Beyond these basics, each platform weights different signals. Here's what matters and where. + +--- + +## Google AI Overviews + +Google AI Overviews pull from Google's own index and lean heavily on E-E-A-T signals (Experience, Expertise, Authoritativeness, Trustworthiness). They appear in roughly 45% of Google searches. + +**What makes Google AI Overviews different:** They already have your traditional SEO signals — backlinks, page authority, topical relevance. The additional AI layer adds a preference for content with cited sources and structured data. Research shows that including authoritative citations in your content correlates with a 132% visibility boost, and writing with an authoritative (not salesy) tone adds another 89%. + +**Importantly, AI Overviews don't just recycle the traditional Top 10.** Only about 15% of AI Overview sources overlap with conventional organic results. Pages that wouldn't crack page 1 in traditional search can still get cited if they have strong structured data and clear, extractable answers. + +**What to focus on:** +- Schema markup is the single biggest lever — Article, FAQPage, HowTo, and Product schemas give AI Overviews structured context to work with (30-40% visibility boost) +- Build topical authority through content clusters with strong internal linking +- Include named, sourced citations in your content (not just claims) +- Author bios with real credentials matter — E-E-A-T is weighted heavily +- 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 + +--- + +## ChatGPT + +ChatGPT's web search draws from a Bing-based index. It combines this with its training knowledge to generate answers, then cites the web sources it relied on. + +**What makes ChatGPT different:** Domain authority matters more here than on other AI platforms. An SE Ranking analysis of 129,000 domains found that authority and credibility signals account for roughly 40% of what determines citation, with content quality at about 35% and platform trust at 25%. Sites with very high referring domain counts (350K+) average 8.4 citations per response, while sites with slightly lower trust scores (91-96 vs 97-100) drop from 8.4 to 6 citations. + +**Freshness is a major differentiator.** Content updated within the last 30 days gets cited about 3.2x more often than older content. ChatGPT clearly favors recent information. + +**The most important signal is content-answer fit** — a ZipTie analysis of 400,000 pages found that how well your content's style and structure matches ChatGPT's own response format accounts for about 55% of citation likelihood. This is far more important than domain authority (12%) or on-page structure (14%) alone. Write the way ChatGPT would answer the question, and you're more likely to be the source it cites. + +**Where ChatGPT looks beyond your site:** Wikipedia accounts for 7.8% of all ChatGPT citations, Reddit for 1.8%, and Forbes for 1.1%. Brand official sites are cited frequently but third-party mentions carry significant weight. + +**What to focus on:** +- Invest in backlinks and domain authority — it's the strongest baseline signal +- Update competitive content at least monthly +- Structure your content the way ChatGPT structures its answers (conversational, direct, well-organized) +- Include verifiable statistics with named sources +- Clean heading hierarchy (H1 > H2 > H3) with descriptive headings + +--- + +## Perplexity + +Perplexity always cites its sources with clickable links, making it the most transparent AI search platform. It combines its own index with Google's and runs results through multiple reranking passes — initial relevance retrieval, then traditional ranking factor scoring, then ML-based quality evaluation that can discard entire result sets if they don't meet quality thresholds. + +**What makes Perplexity different:** It's the most "research-oriented" AI search engine, and its citation behavior reflects that. Perplexity maintains curated lists of authoritative domains (Amazon, GitHub, major academic sites) that get inherent ranking boosts. It uses a time-decay algorithm that evaluates new content quickly, giving fresh publishers a real shot at citation. + +**Perplexity has unique content preferences:** +- **FAQ Schema (JSON-LD)** — Pages with FAQ structured data get cited noticeably more often +- **PDF documents** — Publicly accessible PDFs (whitepapers, research reports) are prioritized. If you have authoritative PDF content gated behind a form, consider making a version public. +- **Publishing velocity** — How frequently you publish matters more than keyword targeting +- **Self-contained paragraphs** — Perplexity prefers atomic, semantically complete paragraphs it can extract cleanly + +**What to focus on:** +- Allow PerplexityBot in robots.txt +- Implement FAQPage schema on any page with Q&A content +- Host PDF resources publicly (whitepapers, guides, reports) +- Add Article schema with publication and modification timestamps +- Write in clear, self-contained paragraphs that work as standalone answers +- Build deep topical authority in your specific niche + +--- + +## Microsoft Copilot + +Copilot is embedded across Microsoft's ecosystem — Edge, Windows, Microsoft 365, and Bing Search. It relies entirely on Bing's index, so if Bing hasn't indexed your content, Copilot can't cite it. + +**What makes Copilot different:** The Microsoft ecosystem connection creates unique optimization opportunities. Mentions and content on LinkedIn and GitHub provide ranking boosts that other platforms don't offer. Copilot also puts more weight on page speed — sub-2-second load times are a clear threshold. + +**What to focus on:** +- Submit your site to Bing Webmaster Tools (many sites only submit to Google Search Console) +- Use IndexNow protocol for faster indexing of new and updated content +- Optimize page speed to under 2 seconds +- Write clear entity definitions — when your content defines a term or concept, make the definition explicit and extractable +- Build presence on LinkedIn (publish articles, maintain company page) and GitHub if relevant +- Ensure Bingbot has full crawl access + +--- + +## Claude + +Claude uses Brave Search as its search backend when web search is enabled — not Google, not Bing. This is a completely different index, which means your Brave Search visibility directly determines whether Claude can find and cite you. + +**What makes Claude different:** Claude is extremely selective about what it cites. While it processes enormous amounts of content, its citation rate is very low — it's looking for the most factually accurate, well-sourced content on a given topic. Data-rich content with specific numbers and clear attribution performs significantly better than general-purpose content. + +**What to focus on:** +- Verify your content appears in Brave Search results (search for your brand and key terms at search.brave.com) +- Allow ClaudeBot and anthropic-ai user agents in robots.txt +- Maximize factual density — specific numbers, named sources, dated statistics +- Use clear, extractable structure with descriptive headings +- Cite authoritative sources within your content +- Aim to be the most factually accurate source on your topic — Claude rewards precision + +--- + +## Allowing AI Bots in robots.txt + +If your robots.txt blocks an AI bot, that platform can't cite your content. Here are the user agents to allow: + +``` +User-agent: GPTBot # OpenAI — powers ChatGPT search +User-agent: ChatGPT-User # ChatGPT browsing mode +User-agent: PerplexityBot # Perplexity AI search +User-agent: ClaudeBot # Anthropic Claude +User-agent: anthropic-ai # Anthropic Claude (alternate) +User-agent: Google-Extended # Google Gemini and AI Overviews +User-agent: Bingbot # Microsoft Copilot (via Bing) +Allow: / +``` + +**Training vs. search:** Some AI bots are used for both model training and search citation. If you want to be cited but don't want your content used for training, your options are limited — GPTBot handles both for OpenAI. However, you can safely block **CCBot** (Common Crawl) without affecting any AI search citations, since it's only used for training dataset collection. + +--- + +## Where to Start + +If you're optimizing for AI search for the first time, focus your effort where your audience actually is: + +**Start with Google AI Overviews** — They reach the most users (45%+ of Google searches) and you likely already have Google SEO foundations in place. Add schema markup, include cited sources in your content, and strengthen E-E-A-T signals. + +**Then address ChatGPT** — It's the most-used standalone AI search tool for tech and business audiences. Focus on freshness (update content monthly), domain authority, and matching your content structure to how ChatGPT formats its responses. + +**Then expand to Perplexity** — Especially valuable if your audience includes researchers, early adopters, or tech professionals. Add FAQ schema, publish PDF resources, and write in clear, self-contained paragraphs. + +**Copilot and Claude are lower priority** unless your audience skews enterprise/Microsoft (Copilot) or developer/analyst (Claude). But the fundamentals — structured content, cited sources, schema markup — help across all platforms. + +**Actions that help everywhere:** +1. Allow all AI bots in robots.txt +2. Implement schema markup (FAQPage, Article, Organization at minimum) +3. Include statistics with named sources in your content +4. Update content regularly — monthly for competitive topics +5. Use clear heading structure (H1 > H2 > H3) +6. Keep page load time under 2 seconds +7. Add author bios with credentials diff --git a/skills/churn-prevention/SKILL.md b/skills/churn-prevention/SKILL.md new file mode 100644 index 00000000..d34ea340 --- /dev/null +++ b/skills/churn-prevention/SKILL.md @@ -0,0 +1,433 @@ +--- +name: churn-prevention +description: "Reduce voluntary and involuntary churn with cancel flows, save offers, dunning, win-back tactics, and retention strategy. Use when users are cancelling, failed payments are rising, or subscription retention needs improvement." +risk: unknown +source: "https://github.com/coreyhaines31/marketingskills" +date_added: "2026-03-21" +metadata: + version: 1.1.0 +--- + +# Churn Prevention + +You are an expert in SaaS retention and churn prevention. Your goal is to help reduce both voluntary churn (customers choosing to cancel) and involuntary churn (failed payments) through well-designed cancel flows, dynamic save offers, proactive retention, and dunning strategies. + +## When to Use + +- Use when churn is rising or cancellation behavior needs intervention. +- Use when designing cancel flows, save offers, dunning, or retention programs. +- Use when the user wants to reduce either voluntary or involuntary churn. + +## Before Starting + +**Check for product marketing context first:** +If `.agents/product-marketing-context.md` exists (or `.claude/product-marketing-context.md` in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task. + +Gather this context (ask if not provided): + +### 1. Current Churn Situation +- What's your monthly churn rate? (Voluntary vs. involuntary if known) +- How many active subscribers? +- What's the average MRR per customer? +- Do you have a cancel flow today, or does cancel happen instantly? + +### 2. Billing & Platform +- What billing provider? (Stripe, Chargebee, Paddle, Recurly, Braintree) +- Monthly, annual, or both billing intervals? +- Do you support plan pausing or downgrades? +- Any existing retention tooling? (Churnkey, ProsperStack, Raaft) + +### 3. Product & Usage Data +- Do you track feature usage per user? +- Can you identify engagement drop-offs? +- Do you have cancellation reason data from past churns? +- What's your activation metric? (What do retained users do that churned users don't?) + +### 4. Constraints +- B2B or B2C? (Affects flow design) +- Self-serve cancellation required? (Some regulations mandate easy cancel) +- Brand tone for offboarding? (Empathetic, direct, playful) + +--- + +## How This Skill Works + +Churn has two types requiring different strategies: + +| Type | Cause | Solution | +|------|-------|----------| +| **Voluntary** | Customer chooses to cancel | Cancel flows, save offers, exit surveys | +| **Involuntary** | Payment fails | Dunning emails, smart retries, card updaters | + +Voluntary churn is typically 50-70% of total churn. Involuntary churn is 30-50% but is often easier to fix. + +This skill supports three modes: + +1. **Build a cancel flow** — Design from scratch with survey, save offers, and confirmation +2. **Optimize an existing flow** — Analyze cancel data and improve save rates +3. **Set up dunning** — Failed payment recovery with retries and email sequences + +--- + +## Cancel Flow Design + +### The Cancel Flow Structure + +Every cancel flow follows this sequence: + +``` +Trigger → Survey → Dynamic Offer → Confirmation → Post-Cancel +``` + +**Step 1: Trigger** +Customer clicks "Cancel subscription" in account settings. + +**Step 2: Exit Survey** +Ask why they're cancelling. This determines which save offer to show. + +**Step 3: Dynamic Save Offer** +Present a targeted offer based on their reason (discount, pause, downgrade, etc.) + +**Step 4: Confirmation** +If they still want to cancel, confirm clearly with end-of-billing-period messaging. + +**Step 5: Post-Cancel** +Set expectations, offer easy reactivation path, trigger win-back sequence. + +### Exit Survey Design + +The exit survey is the foundation. Good reason categories: + +| Reason | What It Tells You | +|--------|-------------------| +| Too expensive | Price sensitivity, may respond to discount or downgrade | +| Not using it enough | Low engagement, may respond to pause or onboarding help | +| Missing a feature | Product gap, show roadmap or workaround | +| Switching to competitor | Competitive pressure, understand what they offer | +| Technical issues / bugs | Product quality, escalate to support | +| Temporary / seasonal need | Usage pattern, offer pause | +| Business closed / changed | Unavoidable, learn and let go gracefully | +| Other | Catch-all, include free text field | + +**Survey best practices:** +- 1 question, single-select with optional free text +- 5-8 reason options max (avoid decision fatigue) +- Put most common reasons first (review data quarterly) +- Don't make it feel like a guilt trip +- "Help us improve" framing works better than "Why are you leaving?" + +### Dynamic Save Offers + +The key insight: **match the offer to the reason.** A discount won't save someone who isn't using the product. A feature roadmap won't save someone who can't afford it. + +**Offer-to-reason mapping:** + +| Cancel Reason | Primary Offer | Fallback Offer | +|---------------|---------------|----------------| +| Too expensive | Discount (20-30% for 2-3 months) | Downgrade to lower plan | +| Not using it enough | Pause (1-3 months) | Free onboarding session | +| Missing feature | Roadmap preview + timeline | Workaround guide | +| Switching to competitor | Competitive comparison + discount | Feedback session | +| Technical issues | Escalate to support immediately | Credit + priority fix | +| Temporary / seasonal | Pause subscription | Downgrade temporarily | +| Business closed | Skip offer (respect the situation) | — | + +### Save Offer Types + +**Discount** +- 20-30% off for 2-3 months is the sweet spot +- Avoid 50%+ discounts (trains customers to cancel for deals) +- Time-limit the offer ("This offer expires when you leave this page") +- Show the dollar amount saved, not just the percentage + +**Pause subscription** +- 1-3 month pause maximum (longer pauses rarely reactivate) +- 60-80% of pausers eventually return to active +- Auto-reactivation with advance notice email +- Keep their data and settings intact + +**Plan downgrade** +- Offer a lower tier instead of full cancellation +- Show what they keep vs. what they lose +- Position as "right-size your plan" not "downgrade" +- Easy path back up when ready + +**Feature unlock / extension** +- Unlock a premium feature they haven't tried +- Extend trial of a higher tier +- Works best for "not getting enough value" reasons + +**Personal outreach** +- For high-value accounts (top 10-20% by MRR) +- Route to customer success for a call +- Personal email from founder for smaller companies + +### Cancel Flow UI Patterns + +``` +┌─────────────────────────────────────┐ +│ We're sorry to see you go │ +│ │ +│ What's the main reason you're │ +│ cancelling? │ +│ │ +│ ○ Too expensive │ +│ ○ Not using it enough │ +│ ○ Missing a feature I need │ +│ ○ Switching to another tool │ +│ ○ Technical issues │ +│ ○ Temporary / don't need right now │ +│ ○ Other: [____________] │ +│ │ +│ [Continue] │ +│ [Never mind, keep my subscription] │ +└─────────────────────────────────────┘ + ↓ (selects "Too expensive") +┌─────────────────────────────────────┐ +│ What if we could help? │ +│ │ +│ We'd love to keep you. Here's a │ +│ special offer: │ +│ │ +│ ┌───────────────────────────────┐ │ +│ │ 25% off for the next 3 months│ │ +│ │ Save $XX/month │ │ +│ │ │ │ +│ │ [Accept Offer] │ │ +│ └───────────────────────────────┘ │ +│ │ +│ Or switch to [Basic Plan] at │ +│ $X/month → │ +│ │ +│ [No thanks, continue cancelling] │ +└─────────────────────────────────────┘ +``` + +**UI principles:** +- Keep the "continue cancelling" option visible (no dark patterns) +- One primary offer + one fallback, not a wall of options +- Show specific dollar savings, not abstract percentages +- Use the customer's name and account data when possible +- Mobile-friendly (many cancellations happen on mobile) + +For detailed cancel flow patterns by industry and billing provider, see [references/cancel-flow-patterns.md](references/cancel-flow-patterns.md). + +--- + +## Churn Prediction & Proactive Retention + +The best save happens before the customer ever clicks "Cancel." + +### Risk Signals + +Track these leading indicators of churn: + +| Signal | Risk Level | Timeframe | +|--------|-----------|-----------| +| Login frequency drops 50%+ | High | 2-4 weeks before cancel | +| Key feature usage stops | High | 1-3 weeks before cancel | +| Support tickets spike then stop | High | 1-2 weeks before cancel | +| Email open rates decline | Medium | 2-6 weeks before cancel | +| Billing page visits increase | High | Days before cancel | +| Team seats removed | High | 1-2 weeks before cancel | +| Data export initiated | Critical | Days before cancel | +| NPS score drops below 6 | Medium | 1-3 months before cancel | + +### Health Score Model + +Build a simple health score (0-100) from weighted signals: + +``` +Health Score = ( + Login frequency score × 0.30 + + Feature usage score × 0.25 + + Support sentiment × 0.15 + + Billing health × 0.15 + + Engagement score × 0.15 +) +``` + +| Score | Status | Action | +|-------|--------|--------| +| 80-100 | Healthy | Upsell opportunities | +| 60-79 | Needs attention | Proactive check-in | +| 40-59 | At risk | Intervention campaign | +| 0-39 | Critical | Personal outreach | + +### Proactive Interventions + +**Before they think about cancelling:** + +| Trigger | Intervention | +|---------|-------------| +| Usage drop >50% for 2 weeks | "We noticed you haven't used [feature]. Need help?" email | +| Approaching plan limit | Upgrade nudge (not a wall — paywall-upgrade-cro handles this) | +| No login for 14 days | Re-engagement email with recent product updates | +| NPS detractor (0-6) | Personal follow-up within 24 hours | +| Support ticket unresolved >48h | Escalation + proactive status update | +| Annual renewal in 30 days | Value recap email + renewal confirmation | + +--- + +## Involuntary Churn: Payment Recovery + +Failed payments cause 30-50% of all churn but are the most recoverable. + +### The Dunning Stack + +``` +Pre-dunning → Smart retry → Dunning emails → Grace period → Hard cancel +``` + +### Pre-Dunning (Prevent Failures) + +- **Card expiry alerts**: Email 30, 15, and 7 days before card expires +- **Backup payment method**: Prompt for a second payment method at signup +- **Card updater services**: Visa/Mastercard auto-update programs (reduces hard declines 30-50%) +- **Pre-billing notification**: Email 3-5 days before charge for annual plans + +### Smart Retry Logic + +Not all failures are the same. Retry strategy by decline type: + +| Decline Type | Examples | Retry Strategy | +|-------------|----------|----------------| +| Soft decline (temporary) | Insufficient funds, processor timeout | Retry 3-5 times over 7-10 days | +| Hard decline (permanent) | Card stolen, account closed | Don't retry — ask for new card | +| Authentication required | 3D Secure, SCA | Send customer to update payment | + +**Retry timing best practices:** +- Retry 1: 24 hours after failure +- Retry 2: 3 days after failure +- Retry 3: 5 days after failure +- Retry 4: 7 days after failure (with dunning email escalation) +- After 4 retries: Hard cancel with reactivation path + +**Smart retry tip:** Retry on the day of the month the payment originally succeeded (if Day 1 worked before, retry on Day 1). Stripe Smart Retries handles this automatically. + +### Dunning Email Sequence + +| Email | Timing | Tone | Content | +|-------|--------|------|---------| +| 1 | Day 0 (failure) | Friendly alert | "Your payment didn't go through. Update your card." | +| 2 | Day 3 | Helpful reminder | "Quick reminder — update your payment to keep access." | +| 3 | Day 7 | Urgency | "Your account will be paused in 3 days. Update now." | +| 4 | Day 10 | Final warning | "Last chance to keep your account active." | + +**Dunning email best practices:** +- Direct link to payment update page (no login required if possible) +- Show what they'll lose (their data, their team's access) +- Don't blame ("your payment failed" not "you failed to pay") +- Include support contact for help +- Plain text performs better than designed emails for dunning + +### Recovery Benchmarks + +| Metric | Poor | Average | Good | +|--------|------|---------|------| +| Soft decline recovery | <40% | 50-60% | 70%+ | +| Hard decline recovery | <10% | 20-30% | 40%+ | +| Overall payment recovery | <30% | 40-50% | 60%+ | +| Pre-dunning prevention | None | 10-15% | 20-30% | + +For the complete dunning playbook with provider-specific setup, see [references/dunning-playbook.md](references/dunning-playbook.md). + +--- + +## Metrics & Measurement + +### Key Churn Metrics + +| Metric | Formula | Target | +|--------|---------|--------| +| Monthly churn rate | Churned customers / Start-of-month customers | <5% B2C, <2% B2B | +| Revenue churn (net) | (Lost MRR - Expansion MRR) / Start MRR | Negative (net expansion) | +| Cancel flow save rate | Saved / Total cancel sessions | 25-35% | +| Offer acceptance rate | Accepted offers / Shown offers | 15-25% | +| Pause reactivation rate | Reactivated / Total paused | 60-80% | +| Dunning recovery rate | Recovered / Total failed payments | 50-60% | +| Time to cancel | Days from first churn signal to cancel | Track trend | + +### Cohort Analysis + +Segment churn by: +- **Acquisition channel** — Which channels bring stickier customers? +- **Plan type** — Which plans churn most? +- **Tenure** — When do most cancellations happen? (30, 60, 90 days?) +- **Cancel reason** — Which reasons are growing? +- **Save offer type** — Which offers work best for which segments? + +### Cancel Flow A/B Tests + +Test one variable at a time: + +| Test | Hypothesis | Metric | +|------|-----------|--------| +| Discount % (20% vs 30%) | Higher discount saves more | Save rate, LTV impact | +| Pause duration (1 vs 3 months) | Longer pause increases return rate | Reactivation rate | +| Survey placement (before vs after offer) | Survey-first personalizes offers | Save rate | +| Offer presentation (modal vs full page) | Full page gets more attention | Save rate | +| Copy tone (empathetic vs direct) | Empathetic reduces friction | Save rate | + +**How to run cancel flow experiments:** Use the **ab-test-setup** skill to design statistically rigorous tests. PostHog is a good fit for cancel flow experiments — its feature flags can split users into different flows server-side, and its funnel analytics track each step of the cancel flow (survey → offer → accept/decline → confirm). + +--- + +## Common Mistakes + +- **No cancel flow at all** — Instant cancel leaves money on the table. Even a simple survey + one offer saves 10-15% +- **Making cancellation hard to find** — Hidden cancel buttons breed resentment and bad reviews. Many jurisdictions require easy cancellation (FTC Click-to-Cancel rule) +- **Same offer for every reason** — A blanket discount doesn't address "missing feature" or "not using it" +- **Discounts too deep** — 50%+ discounts train customers to cancel-and-return for deals +- **Ignoring involuntary churn** — Often 30-50% of total churn and the easiest to fix +- **No dunning emails** — Letting payment failures silently cancel accounts +- **Guilt-trip copy** — "Are you sure you want to abandon us?" damages brand trust +- **Not tracking save offer LTV** — A "saved" customer who churns 30 days later wasn't really saved +- **Pausing too long** — Pauses beyond 3 months rarely reactivate. Set limits. +- **No post-cancel path** — Make reactivation easy and trigger win-back emails, because some churned users will want to come back + +--- + +## Tool Integrations + +For implementation, use the billing, analytics, and experimentation tools available in the current environment. + +### Retention Platforms + +| Tool | Best For | Key Feature | +|------|----------|-------------| +| **Churnkey** | Full cancel flow + dunning | AI-powered adaptive offers, 34% avg save rate | +| **ProsperStack** | Cancel flows with analytics | Advanced rules engine, Stripe/Chargebee integration | +| **Raaft** | Simple cancel flow builder | Easy setup, good for early-stage | +| **Chargebee Retention** | Chargebee customers | Native integration, was Brightback | + +### Billing Providers (Dunning) + +| Provider | Smart Retries | Dunning Emails | Card Updater | +|----------|:------------:|:--------------:|:------------:| +| **Stripe** | Built-in (Smart Retries) | Built-in | Automatic | +| **Chargebee** | Built-in | Built-in | Via gateway | +| **Paddle** | Built-in | Built-in | Managed | +| **Recurly** | Built-in | Built-in | Built-in | +| **Braintree** | Manual config | Manual | Via gateway | + +### Related CLI Tools + +| Tool | Use For | +|------|---------| +| `stripe` | Subscription management, dunning config, payment retries | +| `customer-io` | Dunning email sequences, retention campaigns | +| `posthog` | Cancel flow A/B tests via feature flags, funnel analytics | +| `mixpanel` / `ga4` | Usage tracking, churn signal analysis | +| `segment` | Event routing for health scoring | + +--- + +## Related Skills + +- **email-sequence**: For win-back email sequences after cancellation +- **paywall-upgrade-cro**: For in-app upgrade moments and trial expiration +- **pricing-strategy**: For plan structure and annual discount strategy +- **onboarding-cro**: For activation to prevent early churn +- **analytics-tracking**: For setting up churn signal events +- **ab-test-setup**: For testing cancel flow variations with statistical rigor diff --git a/skills/churn-prevention/evals/evals.json b/skills/churn-prevention/evals/evals.json new file mode 100644 index 00000000..061b1a36 --- /dev/null +++ b/skills/churn-prevention/evals/evals.json @@ -0,0 +1,93 @@ +{ + "skill_name": "churn-prevention", + "evals": [ + { + "id": 1, + "prompt": "Our SaaS product has a 7% monthly churn rate and we need to bring it down. We're a $49/month project management tool with about 2,000 paying customers. Can you help us design a churn prevention strategy?", + "expected_output": "Should check for product-marketing-context.md first. Should address both voluntary and involuntary churn. Should design a cancel flow following the framework: trigger → exit survey → dynamic save offer → confirmation → post-cancel nurture. Should include the 7 exit survey categories and recommend dynamic save offers mapped to each cancellation reason. Should address dunning for involuntary churn (pre-dunning, smart retry, email sequence, grace period). Should recommend a health score model. Should provide prioritized implementation plan.", + "assertions": [ + "Checks for product-marketing-context.md", + "Addresses both voluntary and involuntary churn", + "Designs cancel flow with proper stages", + "Includes exit survey with multiple categories", + "Maps save offers to cancellation reasons", + "Addresses dunning stack for payment recovery", + "Recommends health score model", + "Provides prioritized implementation plan" + ], + "files": [] + }, + { + "id": 2, + "prompt": "We keep losing customers because their credit cards expire. About 15% of our churn is from failed payments. How do we fix this?", + "expected_output": "Should identify this as involuntary churn / payment recovery. Should apply the dunning stack framework: pre-dunning (card expiration reminders before failure), smart retry (retry logic based on failure reason), dunning email sequence (escalating urgency), grace period, and eventual cancellation. Should provide specific timing for each stage. Should recommend payment recovery tools and strategies (card updater services, backup payment methods). Should include recovery rate benchmarks.", + "assertions": [ + "Identifies as involuntary churn / payment recovery", + "Applies dunning stack framework", + "Includes pre-dunning card expiration reminders", + "Includes smart retry logic", + "Provides dunning email sequence with escalating urgency", + "Recommends grace period before cancellation", + "Mentions card updater services or backup payment methods", + "Includes recovery benchmarks" + ], + "files": [] + }, + { + "id": 3, + "prompt": "what should we show users when they click the cancel button? right now they just go straight to cancellation with no attempt to save them", + "expected_output": "Should trigger on casual phrasing. Should design the cancel flow: cancel button → exit survey → dynamic save offer → confirmation → post-cancel. Should detail the exit survey categories (too expensive, missing feature, switched to competitor, not using enough, technical issues, bad support, other). Should provide dynamic save offers matched to each reason (e.g., too expensive → discount offer, missing feature → roadmap update, not using enough → onboarding help). Should include copy recommendations for each screen. Should warn against dark patterns (making it impossible to cancel).", + "assertions": [ + "Triggers on casual phrasing", + "Designs multi-step cancel flow", + "Includes exit survey with 7 categories", + "Provides dynamic save offers mapped to reasons", + "Includes copy recommendations", + "Warns against dark patterns", + "Includes confirmation and post-cancel steps" + ], + "files": [] + }, + { + "id": 4, + "prompt": "How do we identify which customers are at risk of churning before they actually cancel? We want to be proactive.", + "expected_output": "Should apply the health score model framework. Should define health score components: product usage signals (login frequency, feature adoption, key action completion), engagement signals (support tickets, NPS responses, email engagement), and account signals (contract type, company growth, stakeholder changes). Should recommend scoring methodology (0-100 scale). Should define risk tiers and recommended interventions for each tier. Should suggest data sources and implementation approach.", + "assertions": [ + "Applies health score model framework", + "Defines usage-based health signals", + "Defines engagement-based health signals", + "Defines account-based health signals", + "Recommends scoring methodology", + "Defines risk tiers with interventions", + "Suggests data sources and implementation" + ], + "files": [] + }, + { + "id": 5, + "prompt": "Our exit survey shows that 40% of cancellations say 'too expensive' as the reason. What save offers should we try?", + "expected_output": "Should reference the dynamic save offers mapped to the 'too expensive' reason. Should suggest multiple offer types: temporary discount, downgrade to cheaper plan, annual billing discount, pause instead of cancel, extended trial of current plan. Should recommend testing different offers to find what works best. Should also dig deeper — 'too expensive' often masks other issues (not seeing value, not using enough features). Should suggest follow-up questions in the exit survey to get more specific.", + "assertions": [ + "References save offers for 'too expensive' reason", + "Suggests multiple offer types (discount, downgrade, pause)", + "Recommends testing different offers", + "Notes that 'too expensive' often masks other issues", + "Suggests deeper follow-up questions", + "Provides specific save offer copy or structure" + ], + "files": [] + }, + { + "id": 6, + "prompt": "We want to set up a win-back email sequence for customers who already cancelled. Can you help write those emails?", + "expected_output": "Should recognize this overlaps with email sequence work. Should defer to or cross-reference the email-sequence skill for writing the actual email sequence. May provide churn-specific context (timing post-cancel, re-engagement hooks, win-back offer strategy) but should make clear that email-sequence is the right skill for designing and writing the full email sequence.", + "assertions": [ + "Recognizes overlap with email sequence work", + "References or defers to email-sequence skill", + "May provide churn-specific context for the sequence", + "Does not attempt to write a full email sequence" + ], + "files": [] + } + ] +} diff --git a/skills/churn-prevention/references/cancel-flow-patterns.md b/skills/churn-prevention/references/cancel-flow-patterns.md new file mode 100644 index 00000000..a47ab991 --- /dev/null +++ b/skills/churn-prevention/references/cancel-flow-patterns.md @@ -0,0 +1,316 @@ +# Cancel Flow Patterns + +Detailed cancel flow patterns by business type, billing provider, and industry. + +--- + +## Cancel Flow by Business Type + +### B2C / Self-Serve SaaS + +High volume, low touch. The flow must work without human intervention. + +**Flow structure:** +``` +Cancel button → Exit survey (1 question) → Dynamic offer → Confirm → Post-cancel +``` + +**Characteristics:** +- Fully automated, no human in the loop +- Quick — 2-3 screens maximum +- One offer + one fallback, not a menu of options +- Mobile-optimized (significant cancellations on mobile) +- Clear "continue cancelling" at every step + +**Typical save rate:** 20-30% + +**Example flow for a $29/mo productivity app:** +1. "What's the main reason?" → 6 options +2. Selected "Too expensive" → "Get 25% off for 3 months (save $21.75)" +3. Declined → "Or switch to our Starter plan at $12/mo" +4. Declined → "We're sorry to see you go. Your access continues until [date]." + +--- + +### B2B / Team Plans + +Lower volume, higher stakes. Personal outreach is worth the cost. + +**Flow structure:** +``` +Cancel button → Exit survey → Offer (or route to CS) → Confirm → Post-cancel +``` + +**Characteristics:** +- Route accounts above MRR threshold to customer success +- Show team impact ("Your 8 team members will lose access") +- Offer admin-to-admin call for enterprise accounts +- Longer consideration — allow "schedule a call" as a save option +- Require admin/owner role to cancel (not any team member) + +**Typical save rate:** 30-45% (higher because of personal touch) + +**MRR-based routing:** + +| Account MRR | Cancel Flow | +|-------------|-------------| +| <$100/mo | Automated flow with offers | +| $100-$500/mo | Automated + flag for CS follow-up | +| $500-$2,000/mo | Route to CS before cancel completes | +| $2,000+/mo | Block self-serve cancel, require CS call | + +--- + +### Freemium / Free-to-Paid + +Users cancelling paid to return to free tier. Different psychology — they're not leaving, they're downgrading. + +**Flow structure:** +``` +Cancel button → "Switch to Free?" prompt → Exit survey (if still cancelling) → Offer → Confirm +``` + +**Characteristics:** +- Lead with the free tier as the first option (not a save offer) +- Show what they keep on free vs. what they lose +- The "save" is keeping them on free, not losing them entirely +- Track free-tier users for future re-upgrade campaigns + +--- + +## Cancel Flow by Billing Interval + +### Monthly Subscribers + +- More price-sensitive, shorter commitment +- Discount offers work well (20-30% for 2-3 months) +- Pause is effective (1-2 months) +- Suggest annual plan at a discount as an alternative + +**Offer priority:** +1. Discount (if reason = price) +2. Pause (if reason = not using / temporary) +3. Annual plan switch (if engaged but price-sensitive) + +### Annual Subscribers + +- Higher commitment, often cancelling for stronger reasons +- Prorate refund expectations matter +- Longer save window (they've already paid) +- Personal outreach more justified (higher LTV at stake) + +**Offer priority:** +1. Pause remainder of term (if temporary) +2. Plan adjustment + credit for next renewal +3. Personal outreach from CS +4. Partial refund + downgrade (better than full refund + cancel) + +**Refund handling:** +- Offer prorated refund if significant time remaining +- "Pause until renewal" if less than 3 months left +- Be generous — bad refund experiences create vocal detractors + +--- + +## Save Offer Patterns + +### The Discount Ladder + +Don't lead with your biggest discount. Escalate: + +``` +Cancel click → 15% off → Still cancelling → 25% off → Still cancelling → Let them go +``` + +**Rules:** +- Maximum 2 discount offers per cancel session +- Never exceed 30% (higher trains cancel-for-discount behavior) +- Time-limit discounts (2-3 months, then full price resumes) +- Track discount accepters — if they cancel again at full price, don't re-offer + +### The Pause Playbook + +Pause is often better than a discount because it doesn't devalue your product. + +**Implementation:** + +| Setting | Recommendation | +|---------|---------------| +| Pause duration options | 1 month, 2 months, 3 months | +| Default selection | 1 month (shortest) | +| Maximum pause | 3 months (longer pauses rarely return) | +| During pause | Keep data, remove access | +| Reactivation | Auto-reactivate with 7-day advance email | +| Repeat pauses | Allow 1 pause per 12-month period | + +**Pause reactivation sequence:** +- Day -7: "Your pause ends in 7 days. We've been busy — here's what's new." +- Day -1: "Welcome back tomorrow! Here's what's waiting for you." +- Day 0: "You're back! Here's a quick tour of what's new." + +### The Downgrade Path + +For multi-plan products, downgrade is the strongest save: + +``` +┌─────────────────────────────────────────┐ +│ Before you go, what about right-sizing │ +│ your plan? │ +│ │ +│ Current: Pro ($49/mo) │ +│ │ +│ ┌─────────────────────────────────┐ │ +│ │ Switch to Starter ($19/mo) │ │ +│ │ │ │ +│ │ ✓ Keep: Projects, integrations │ │ +│ │ ✗ Lose: Advanced analytics, │ │ +│ │ team features │ │ +│ │ │ │ +│ │ [Switch to Starter] │ │ +│ └─────────────────────────────────┘ │ +│ │ +│ [No thanks, continue cancelling] │ +└─────────────────────────────────────────┘ +``` + +**Downgrade best practices:** +- Show exactly what they keep and what they lose +- Use checkmarks and X marks for scanability +- Preserve their data even on the lower plan +- If they downgrade, don't show upgrade prompts for at least 30 days + +### The Competitor Switch Handler + +When the cancel reason is "switching to competitor": + +1. **Ask which competitor** (optional, don't force it) +2. **Show a comparison** if you have one (see competitor-alternatives skill) +3. **Offer a migration credit** ("We'll match their price for 3 months") +4. **Request a feedback call** ("15 minutes to understand what we're missing") + +This data is gold for product and marketing teams. + +--- + +## Post-Cancel Experience + +What happens after cancel matters for: +- Win-back potential +- Word of mouth +- Review sentiment + +### Confirmation Page + +``` +Your subscription has been cancelled. + +What happens next: +• Your access continues until [billing period end date] +• Your data will be preserved for 90 days +• You can reactivate anytime from your account settings + +[Reactivate My Account] + +We'd love to have you back. We'll keep improving based on feedback +from customers like you. +``` + +### Post-Cancel Sequence + +| Timing | Action | +|--------|--------| +| Immediately | Confirmation email with access end date | +| Day 1 | (Nothing — don't be desperate) | +| Day 7 | NPS/satisfaction survey about overall experience | +| Day 30 | "What's new" email with recent improvements | +| Day 60 | Address their specific cancel reason if resolved | +| Day 90 | Final win-back with special offer | + +**For detailed win-back email sequences**: See the email-sequence skill. + +--- + +## Segmentation Rules + +The most effective cancel flows use segmentation to show different offers to different customers. + +### Segmentation Dimensions + +| Dimension | Why It Matters | +|-----------|---------------| +| Plan / MRR | Higher-value customers get personal outreach | +| Tenure | Long-term customers get more generous offers | +| Usage level | High-usage customers get different messaging than dormant ones | +| Billing interval | Monthly vs. annual need different approaches | +| Previous saves | Don't re-offer the same discount to a repeat canceller | +| Cancel reason | Drives which offer to show (core mapping) | + +### Segment-Specific Flows + +**New customer (< 30 days):** +- They haven't activated. The save is onboarding, not discounts. +- Offer: Free onboarding call, setup help, extended trial +- Ask: "What were you hoping to accomplish?" (learn what's missing) + +**Engaged customer cancelling on price:** +- They love the product but can't justify the cost. +- Offer: Discount, annual plan switch, downgrade +- High save potential + +**Dormant customer (no login 30+ days):** +- They forgot about you. A discount won't bring them back. +- Offer: Pause subscription, "what changed?" conversation +- Low save potential — focus on learning why + +**Power user switching to competitor:** +- They're actively choosing something else. +- Offer: Competitive match, feedback call, roadmap preview +- Medium save potential — depends on reason + +--- + +## Implementation Checklist + +### Phase 1: Foundation (Week 1) +- [ ] Add cancel flow (survey + 1 offer + confirmation) +- [ ] Set up exit survey with 5-7 reason categories +- [ ] Map one offer per reason (simple 1:1 mapping) +- [ ] Track cancel reasons and save rate in analytics +- [ ] Enable pre-dunning card expiry emails + +### Phase 2: Optimization (Weeks 2-4) +- [ ] Add fallback offers (primary + secondary per reason) +- [ ] Implement pause subscription option +- [ ] Set up dunning email sequence (4 emails over 10 days) +- [ ] Enable smart retries (Stripe Smart Retries or equivalent) +- [ ] Add MRR-based routing for high-value accounts + +### Phase 3: Advanced (Month 2+) +- [ ] Build health score from usage signals +- [ ] Set up proactive intervention triggers +- [ ] A/B test discount amounts and offer types +- [ ] Segment flows by plan, tenure, and usage +- [ ] Post-cancel win-back sequence (coordinate with email-sequence skill) +- [ ] Cohort analysis: churn by channel, plan, tenure + +--- + +## Compliance Notes + +### FTC Click-to-Cancel Rule (US) +- Cancellation must be as easy as signup +- Cannot require a phone call to cancel if signup was online +- Cannot add excessive steps to discourage cancellation +- Save offers are allowed but "continue cancelling" must be clear + +### GDPR / Data Retention (EU) +- Inform users about data retention period post-cancel +- Offer data export before account deletion +- Honor deletion requests within 30 days +- Don't use post-cancel data for marketing without consent + +### General Best Practices +- Always show a clear path to complete cancellation +- Never hide the cancel button (dark pattern) +- Process cancellation even if save flow has errors +- Confirm cancellation with email receipt diff --git a/skills/churn-prevention/references/dunning-playbook.md b/skills/churn-prevention/references/dunning-playbook.md new file mode 100644 index 00000000..294e3b36 --- /dev/null +++ b/skills/churn-prevention/references/dunning-playbook.md @@ -0,0 +1,408 @@ +# Dunning Playbook + +Complete guide to recovering failed payments and reducing involuntary churn. + +--- + +## Why Dunning Matters + +- Failed payments cause 30-50% of all subscription churn +- Most failed payments are recoverable with the right strategy +- Subscription businesses lose an estimated $129 billion annually to involuntary churn +- Effective dunning recovers 50-60% of failed payments + +--- + +## The Dunning Timeline + +``` +Day -30 to -7: Pre-dunning (prevent failures) +Day 0: Payment fails → Smart retry #1 + Email #1 +Day 1-3: Smart retry #2 + Email #2 +Day 3-5: Smart retry #3 +Day 5-7: Smart retry #4 + Email #3 +Day 7-10: Final retry + Email #4 (final warning) +Day 10-14: Grace period ends → Account paused/cancelled +Day 14+: Win-back sequence begins +``` + +--- + +## Pre-Dunning: Prevent Failures Before They Happen + +### Card Expiry Management + +| Timing | Action | +|--------|--------| +| 30 days before expiry | Email: "Your card ending in 4242 expires next month" | +| 15 days before expiry | Email: "Update your payment method to avoid interruption" | +| 7 days before expiry | Email: "Your card expires in 7 days — update now" | +| 3 days before expiry | In-app banner: "Payment method expiring soon" | + +**Email template — Card expiring:** +``` +Subject: Your card ending in 4242 expires soon + +Hi [Name], + +The card on file for your [Product] subscription expires on [date]. + +Update your payment method now to avoid any interruption: + +[Update Payment Method →] + +This takes less than 30 seconds. + +— [Product] Team +``` + +### Card Updater Services + +Major card networks offer automatic card update programs: + +| Service | Network | What It Does | +|---------|---------|--------------| +| Visa Account Updater (VAU) | Visa | Auto-updates stored card numbers and expiry dates | +| Mastercard Automatic Billing Updater (ABU) | Mastercard | Same for Mastercard | +| Amex Cardrefresher | American Express | Same for Amex | + +**Impact:** Reduces hard declines from expired/replaced cards by 30-50%. + +**How to enable:** +- **Stripe**: Automatic — enabled by default +- **Chargebee**: Enabled through gateway settings +- **Recurly**: Built-in, enabled by default +- **Braintree**: Contact processor to enable + +### Backup Payment Methods + +Prompt for a second payment method: +- During signup: "Add a backup payment method" (low conversion) +- After first successful payment: "Protect your account with a backup card" (better timing) +- After a failed payment is recovered: "Add a backup to prevent future interruptions" (best timing — they felt the pain) + +### Pre-Billing Notifications + +For annual plans or high-value subscriptions: +- Email 7 days before renewal with amount and date +- Include link to update payment method +- Show what's included in the renewal +- Required by some regulations for auto-renewals + +--- + +## Smart Retry Strategy + +### Decline Type Classification + +| Code | Type | Meaning | Retry? | +|------|------|---------|--------| +| `insufficient_funds` | Soft | Temporarily low balance | Yes — retry in 2-3 days | +| `card_declined` (generic) | Soft | Various temporary reasons | Yes — retry 3-4 times | +| `processing_error` | Soft | Gateway/network issue | Yes — retry within 24h | +| `expired_card` | Hard | Card is expired | No — request new card | +| `stolen_card` | Hard | Card reported stolen | No — request new card | +| `do_not_honor` | Soft/Hard | Bank refused (ambiguous) | Try once more, then ask for new card | +| `authentication_required` | Auth | SCA/3DS needed | Send customer to authenticate | + +### Retry Schedule by Provider + +**Stripe (Smart Retries — recommended):** +- Enable "Smart Retries" in Stripe Dashboard → Billing → Settings +- Stripe's ML model picks optimal retry timing based on billions of transactions +- Typically 4-8 retry attempts over 3-4 weeks +- Recovers ~15% more than fixed-schedule retries + +**Manual retry schedule (if no smart retries):** + +| Retry | Timing | Best Day/Time | +|-------|--------|--------------| +| 1 | Day 1 (24h after failure) | Morning, same day of week as original | +| 2 | Day 3 | Try a different time of day | +| 3 | Day 5 | After typical payday (1st, 15th) | +| 4 | Day 7 | Morning of the next business day | +| 5 (final) | Day 10 | Last attempt before grace period ends | + +**Retry timing insights:** +- Retry on the same day of month the original payment succeeded +- Retry after common paydays (1st and 15th of the month) +- Avoid retrying on weekends (lower approval rates) +- Morning retries (8-10am local time) perform slightly better + +--- + +## Dunning Email Sequence + +### Email 1: Payment Failed (Day 0) + +**Tone:** Friendly, matter-of-fact. No alarm. + +``` +Subject: Action needed — your payment didn't go through + +Hi [Name], + +We tried to charge your [card type] ending in [last 4] for your +[Product] subscription ($[amount]), but it didn't go through. + +This happens sometimes — usually a quick card update fixes it. + +[Update Payment Method →] + +Your access isn't affected yet. We'll retry automatically, but +updating your card is the fastest fix. + +Need help? Just reply to this email. + +— [Product] Team +``` + +### Email 2: Reminder (Day 3) + +**Tone:** Helpful, slightly more urgent. + +``` +Subject: Quick reminder — update your payment for [Product] + +Hi [Name], + +Just a heads-up — we still haven't been able to process your +$[amount] payment for [Product]. + +[Update Payment Method →] + +Takes less than 30 seconds. Your [data/projects/team access] +is safe, but we'll need a valid payment method to keep your +account active. + +Questions? Reply here and we'll help. + +— [Product] Team +``` + +### Email 3: Urgency (Day 7) + +**Tone:** Direct, clear consequences. + +``` +Subject: Your [Product] account will be paused in 3 days + +Hi [Name], + +We've tried to process your payment several times, but your +[card type] ending in [last 4] keeps getting declined. + +If we don't receive payment by [date], your account will be +paused and you'll lose access to: + +• [Key feature/data they use] +• [Their projects/workspace] +• [Team access for X members] + +[Update Payment Method Now →] + +Your data won't be deleted — you can reactivate anytime by +updating your payment method. + +— [Product] Team +``` + +### Email 4: Final Warning (Day 10) + +**Tone:** Final, clear, no guilt. + +``` +Subject: Last chance to keep your [Product] account active + +Hi [Name], + +This is our last reminder. Your payment of $[amount] is past +due, and your account will be paused tomorrow ([date]). + +[Update Payment Method →] + +After pausing: +• Your data is saved for [90 days] +• You can reactivate anytime +• Just update your card to restore access + +If you intended to cancel, no action needed — your account +will be paused automatically. + +— [Product] Team +``` + +--- + +## Grace Period Management + +### What Happens During Grace Period + +| Setting | Recommendation | +|---------|---------------| +| Duration | 7-14 days after final retry | +| Access | Degraded (read-only) or full access | +| Visibility | In-app banner: "Payment past due — update to continue" | +| Retry | Continue background retries during grace | +| Communication | Dunning emails continue | + +### Access Degradation Options + +**Option A: Full access during grace (recommended for B2B)** +- Lower friction, customer feels respected +- Higher recovery rate (they still see value) +- Risk: some customers exploit the grace period + +**Option B: Read-only access (recommended for B2C)** +- Can view but not create/edit +- Creates urgency without data loss fear +- Clear message: "Update payment to resume full access" + +**Option C: Immediate lockout (not recommended)** +- Aggressive, damages relationship +- Lower recovery rate +- Only appropriate for very low-cost plans + +### Post-Grace Period + +| Timing | Action | +|--------|--------| +| Grace period ends | Pause account (not delete) | +| Day 1 post-pause | "Your account has been paused" email | +| Day 7 post-pause | "Your data is still here" reminder | +| Day 30 post-pause | Win-back attempt with new offer | +| Day 60 post-pause | Final win-back | +| Day 90 post-pause | Data deletion warning (if applicable) | + +--- + +## Provider-Specific Setup + +### Stripe + +**Enable Smart Retries:** +1. Dashboard → Settings → Billing → Subscriptions and emails +2. Enable "Smart Retries" under retry rules +3. Set failed payment emails in Dashboard → Settings → Emails + +**Custom retry rules (if not using Smart Retries):** +``` +Retry 1: 3 days after failure +Retry 2: 5 days after failure +Retry 3: 7 days after failure +Final: Mark subscription as unpaid after last retry +``` + +**Webhook events to handle:** +- `invoice.payment_failed` — trigger dunning +- `invoice.paid` — cancel dunning, restore access +- `customer.subscription.updated` — status changes +- `customer.subscription.deleted` — final cancellation + +### Chargebee + +**Built-in dunning:** +1. Settings → Configure Chargebee → Retry Settings +2. Configure retry attempts and intervals +3. Settings → Configure Chargebee → Email Notifications → Dunning + +**Dunning options:** +- Automatic retries with configurable schedule +- Built-in dunning emails (customizable templates) +- Grace period configuration per plan + +### Paddle + +**Managed dunning:** +- Paddle handles retries and dunning automatically +- Limited customization (Paddle manages the relationship) +- Webhook: `subscription.payment_failed`, `subscription.cancelled` +- Best for hands-off approach + +### Recurly + +**Revenue Recovery:** +1. Configuration → Dunning Management +2. Set retry schedule per plan +3. Configure grace period and final action (pause vs cancel) + +**Advanced features:** +- Machine-learning retry optimization +- Per-plan dunning schedules +- Built-in Account Updater + +--- + +## In-App Dunning + +Don't rely on email alone. Show payment failures in the app: + +### Banner Pattern +``` +┌──────────────────────────────────────────────────────┐ +│ ⚠ Your payment of $29 failed. Update your card to │ +│ avoid losing access. [Update Payment →] [Dismiss] │ +└──────────────────────────────────────────────────────┘ +``` + +**Rules:** +- Show on every page load during dunning period +- Allow dismiss (but show again next session) +- Direct link to payment update (fewest clicks possible) +- Don't block the product — let them continue using it + +### Modal Pattern (for final warning) +``` +┌─────────────────────────────────────┐ +│ │ +│ Your account will be paused │ +│ on [date] │ +│ │ +│ Update your payment method to │ +│ keep access to your [X] projects │ +│ and [Y] team members. │ +│ │ +│ [Update Payment Method] │ +│ [Remind Me Later] │ +│ │ +└─────────────────────────────────────┘ +``` + +--- + +## Measuring Dunning Performance + +### Key Metrics + +| Metric | How to Calculate | Target | +|--------|-----------------|--------| +| Recovery rate | Recovered payments / Total failed | 50-60% | +| Recovery rate by decline type | Recovered / Failed per type | Soft: 70%+, Hard: 40%+ | +| Time to recovery | Days from failure to successful payment | <5 days | +| Pre-dunning prevention rate | Prevented failures / Expected failures | 20-30% | +| Dunning email open rate | Opens / Sent per email | 60%+ | +| Dunning email click rate | Clicks / Opens per email | 30%+ | +| Revenue recovered (monthly) | Sum of recovered payment amounts | Track trend | +| Revenue lost to involuntary churn | Sum of failed + unrecovered amounts | Track trend | + +### Benchmarking + +**By company stage:** + +| Stage | Typical Involuntary Churn | Target After Optimization | +|-------|--------------------------|--------------------------| +| Early (< $1M ARR) | 3-5% of MRR/month | 1-2% | +| Growth ($1-10M ARR) | 2-4% of MRR/month | 0.5-1.5% | +| Scale ($10M+ ARR) | 1-3% of MRR/month | 0.3-0.8% | + +### ROI Calculation + +``` +Monthly failed payment MRR: $10,000 +Current recovery rate: 30% ($3,000 recovered) +Target recovery rate: 60% ($6,000 recovered) +Monthly improvement: $3,000/month +Annual improvement: $36,000/year +Cost of dunning optimization: ~$200-500/month (tooling) +ROI: 6-15x +``` diff --git a/skills/claude-api/LICENSE.txt b/skills/claude-api/LICENSE.txt new file mode 100644 index 00000000..7a4a3ea2 --- /dev/null +++ b/skills/claude-api/LICENSE.txt @@ -0,0 +1,202 @@ + + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright [yyyy] [name of copyright owner] + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. \ No newline at end of file diff --git a/skills/claude-api/SKILL.md b/skills/claude-api/SKILL.md new file mode 100644 index 00000000..af4247a3 --- /dev/null +++ b/skills/claude-api/SKILL.md @@ -0,0 +1,252 @@ +--- +name: claude-api +description: "Build apps with the Claude API or Anthropic SDK. TRIGGER when: code imports `anthropic`/`@anthropic-ai/sdk`/`claude_agent_sdk`, or user asks to use Claude API, Anthropic SDKs, or Agent SDK. DO NOT TRIGGER when: code imports `openai`/other AI SDK, general programming, or ML/data-science tasks." +risk: unknown +source: "https://github.com/anthropics/skills" +date_added: "2026-03-21" +license: Complete terms in LICENSE.txt +--- + +# Building LLM-Powered Applications with Claude + +This skill helps you build LLM-powered applications with Claude. Choose the right surface based on your needs, detect the project language, then read the relevant language-specific documentation. + +## When to Use + +- Use when building with the Claude API, Anthropic SDKs, or the Agent SDK. +- Use when code imports `anthropic`, `@anthropic-ai/sdk`, or related Claude SDK packages. +- Do not use for general coding work unrelated to Claude integrations. + +## Defaults + +Unless the user requests otherwise: + +For the Claude model version, please use Claude Opus 4.6, which you can access via the exact model string `claude-opus-4-6`. Please default to using adaptive thinking (`thinking: {type: "adaptive"}`) for anything remotely complicated. And finally, please default to streaming for any request that may involve long input, long output, or high `max_tokens` — it prevents hitting request timeouts. Use the SDK's `.get_final_message()` / `.finalMessage()` helper to get the complete response if you don't need to handle individual stream events + +--- + +## Language Detection + +Before reading code examples, determine which language the user is working in: + +1. **Look at project files** to infer the language: + + - `*.py`, `requirements.txt`, `pyproject.toml`, `setup.py`, `Pipfile` → **Python** — read from `python/` + - `*.ts`, `*.tsx`, `package.json`, `tsconfig.json` → **TypeScript** — read from `typescript/` + - `*.js`, `*.jsx` (no `.ts` files present) → **TypeScript** — JS uses the same SDK, read from `typescript/` + - `*.java`, `pom.xml`, `build.gradle` → **Java** — read from `java/` + - `*.kt`, `*.kts`, `build.gradle.kts` → **Java** — Kotlin uses the Java SDK, read from `java/` + - `*.scala`, `build.sbt` → **Java** — Scala uses the Java SDK, read from `java/` + - `*.go`, `go.mod` → **Go** — read from `go/` + - `*.rb`, `Gemfile` → **Ruby** — read from `ruby/` + - `*.cs`, `*.csproj` → **C#** — read from `csharp/` + - `*.php`, `composer.json` → **PHP** — read from `php/` + +2. **If multiple languages detected** (e.g., both Python and TypeScript files): + + - Check which language the user's current file or question relates to + - If still ambiguous, ask: "I detected both Python and TypeScript files. Which language are you using for the Claude API integration?" + +3. **If language can't be inferred** (empty project, no source files, or unsupported language): + + - Use AskUserQuestion with options: Python, TypeScript, Java, Go, Ruby, cURL/raw HTTP, C#, PHP + - If AskUserQuestion is unavailable, default to Python examples and note: "Showing Python examples. Let me know if you need a different language." + +4. **If unsupported language detected** (Rust, Swift, C++, Elixir, etc.): + + - Suggest cURL/raw HTTP examples from `curl/` and note that community SDKs may exist + - Offer to show Python or TypeScript examples as reference implementations + +5. **If user needs cURL/raw HTTP examples**, read from `curl/`. + +### Language-Specific Feature Support + +| Language | Tool Runner | Agent SDK | Notes | +| ---------- | ----------- | --------- | ------------------------------------- | +| Python | Yes (beta) | Yes | Full support — `@beta_tool` decorator | +| TypeScript | Yes (beta) | Yes | Full support — `betaZodTool` + Zod | +| Java | Yes (beta) | No | Beta tool use with annotated classes | +| Go | Yes (beta) | No | `BetaToolRunner` in `toolrunner` pkg | +| Ruby | Yes (beta) | No | `BaseTool` + `tool_runner` in beta | +| cURL | N/A | N/A | Raw HTTP, no SDK features | +| C# | No | No | Official SDK | +| PHP | No | No | Official SDK | + +--- + +## Which Surface Should I Use? + +> **Start simple.** Default to the simplest tier that meets your needs. Single API calls and workflows handle most use cases — only reach for agents when the task genuinely requires open-ended, model-driven exploration. + +| Use Case | Tier | Recommended Surface | Why | +| ----------------------------------------------- | --------------- | ------------------------- | --------------------------------------- | +| Classification, summarization, extraction, Q&A | Single LLM call | **Claude API** | One request, one response | +| Batch processing or embeddings | Single LLM call | **Claude API** | Specialized endpoints | +| Multi-step pipelines with code-controlled logic | Workflow | **Claude API + tool use** | You orchestrate the loop | +| Custom agent with your own tools | Agent | **Claude API + tool use** | Maximum flexibility | +| AI agent with file/web/terminal access | Agent | **Agent SDK** | Built-in tools, safety, and MCP support | +| Agentic coding assistant | Agent | **Agent SDK** | Designed for this use case | +| Want built-in permissions and guardrails | Agent | **Agent SDK** | Safety features included | + +> **Note:** The Agent SDK is for when you want built-in file/web/terminal tools, permissions, and MCP out of the box. If you want to build an agent with your own tools, Claude API is the right choice — use the tool runner for automatic loop handling, or the manual loop for fine-grained control (approval gates, custom logging, conditional execution). + +### Decision Tree + +``` +What does your application need? + +1. Single LLM call (classification, summarization, extraction, Q&A) + └── Claude API — one request, one response + +2. Does Claude need to read/write files, browse the web, or run shell commands + as part of its work? (Not: does your app read a file and hand it to Claude — + does Claude itself need to discover and access files/web/shell?) + └── Yes → Agent SDK — built-in tools, don't reimplement them + Examples: "scan a codebase for bugs", "summarize every file in a directory", + "find bugs using subagents", "research a topic via web search" + +3. Workflow (multi-step, code-orchestrated, with your own tools) + └── Claude API with tool use — you control the loop + +4. Open-ended agent (model decides its own trajectory, your own tools) + └── Claude API agentic loop (maximum flexibility) +``` + +### Should I Build an Agent? + +Before choosing the agent tier, check all four criteria: + +- **Complexity** — Is the task multi-step and hard to fully specify in advance? (e.g., "turn this design doc into a PR" vs. "extract the title from this PDF") +- **Value** — Does the outcome justify higher cost and latency? +- **Viability** — Is Claude capable at this task type? +- **Cost of error** — Can errors be caught and recovered from? (tests, review, rollback) + +If the answer is "no" to any of these, stay at a simpler tier (single call or workflow). + +--- + +## Architecture + +Everything goes through `POST /v1/messages`. Tools and output constraints are features of this single endpoint — not separate APIs. + +**User-defined tools** — You define tools (via decorators, Zod schemas, or raw JSON), and the SDK's tool runner handles calling the API, executing your functions, and looping until Claude is done. For full control, you can write the loop manually. + +**Server-side tools** — Anthropic-hosted tools that run on Anthropic's infrastructure. Code execution is fully server-side (declare it in `tools`, Claude runs code automatically). Computer use can be server-hosted or self-hosted. + +**Structured outputs** — Constrains the Messages API response format (`output_config.format`) and/or tool parameter validation (`strict: true`). The recommended approach is `client.messages.parse()` which validates responses against your schema automatically. Note: the old `output_format` parameter is deprecated; use `output_config: {format: {...}}` on `messages.create()`. + +**Supporting endpoints** — Batches (`POST /v1/messages/batches`), Files (`POST /v1/files`), and Token Counting feed into or support Messages API requests. + +--- + +## Current Models (cached: 2026-02-17) + +| Model | Model ID | Context | Input $/1M | Output $/1M | +| ----------------- | ------------------- | -------------- | ---------- | ----------- | +| Claude Opus 4.6 | `claude-opus-4-6` | 200K (1M beta) | $5.00 | $25.00 | +| Claude Sonnet 4.6 | `claude-sonnet-4-6` | 200K (1M beta) | $3.00 | $15.00 | +| Claude Haiku 4.5 | `claude-haiku-4-5` | 200K | $1.00 | $5.00 | + +**ALWAYS use `claude-opus-4-6` unless the user explicitly names a different model.** This is non-negotiable. Do not use `claude-sonnet-4-6`, `claude-sonnet-4-5`, or any other model unless the user literally says "use sonnet" or "use haiku". Never downgrade for cost — that's the user's decision, not yours. + +**CRITICAL: Use only the exact model ID strings from the table above — they are complete as-is. Do not append date suffixes.** For example, use `claude-sonnet-4-5`, never `claude-sonnet-4-5-20250514` or any other date-suffixed variant you might recall from training data. If the user requests an older model not in the table (e.g., "opus 4.5", "sonnet 3.7"), read `shared/models.md` for the exact ID — do not construct one yourself. + +A note: if any of the model strings above look unfamiliar to you, that's to be expected — that just means they were released after your training data cutoff. Rest assured they are real models; we wouldn't mess with you like that. + +--- + +## Thinking & Effort (Quick Reference) + +**Opus 4.6 — Adaptive thinking (recommended):** Use `thinking: {type: "adaptive"}`. Claude dynamically decides when and how much to think. No `budget_tokens` needed — `budget_tokens` is deprecated on Opus 4.6 and Sonnet 4.6 and must not be used. Adaptive thinking also automatically enables interleaved thinking (no beta header needed). **When the user asks for "extended thinking", a "thinking budget", or `budget_tokens`: always use Opus 4.6 with `thinking: {type: "adaptive"}`. The concept of a fixed token budget for thinking is deprecated — adaptive thinking replaces it. Do NOT use `budget_tokens` and do NOT switch to an older model.** + +**Effort parameter (GA, no beta header):** Controls thinking depth and overall token spend via `output_config: {effort: "low"|"medium"|"high"|"max"}` (inside `output_config`, not top-level). Default is `high` (equivalent to omitting it). `max` is Opus 4.6 only. Works on Opus 4.5, Opus 4.6, and Sonnet 4.6. Will error on Sonnet 4.5 / Haiku 4.5. Combine with adaptive thinking for the best cost-quality tradeoffs. Use `low` for subagents or simple tasks; `max` for the deepest reasoning. + +**Sonnet 4.6:** Supports adaptive thinking (`thinking: {type: "adaptive"}`). `budget_tokens` is deprecated on Sonnet 4.6 — use adaptive thinking instead. + +**Older models (only if explicitly requested):** If the user specifically asks for Sonnet 4.5 or another older model, use `thinking: {type: "enabled", budget_tokens: N}`. `budget_tokens` must be less than `max_tokens` (minimum 1024). Never choose an older model just because the user mentions `budget_tokens` — use Opus 4.6 with adaptive thinking instead. + +--- + +## Compaction (Quick Reference) + +**Beta, Opus 4.6 only.** For long-running conversations that may exceed the 200K context window, enable server-side compaction. The API automatically summarizes earlier context when it approaches the trigger threshold (default: 150K tokens). Requires beta header `compact-2026-01-12`. + +**Critical:** Append `response.content` (not just the text) back to your messages on every turn. Compaction blocks in the response must be preserved — the API uses them to replace the compacted history on the next request. Extracting only the text string and appending that will silently lose the compaction state. + +See `{lang}/claude-api/README.md` (Compaction section) for code examples. Full docs via WebFetch in `shared/live-sources.md`. + +--- + +## Reading Guide + +After detecting the language, read the relevant files based on what the user needs: + +### Quick Task Reference + +**Single text classification/summarization/extraction/Q&A:** +→ Read only `{lang}/claude-api/README.md` + +**Chat UI or real-time response display:** +→ Read `{lang}/claude-api/README.md` + `{lang}/claude-api/streaming.md` + +**Long-running conversations (may exceed context window):** +→ Read `{lang}/claude-api/README.md` — see Compaction section + +**Function calling / tool use / agents:** +→ Read `{lang}/claude-api/README.md` + `shared/tool-use-concepts.md` + `{lang}/claude-api/tool-use.md` + +**Batch processing (non-latency-sensitive):** +→ Read `{lang}/claude-api/README.md` + `{lang}/claude-api/batches.md` + +**File uploads across multiple requests:** +→ Read `{lang}/claude-api/README.md` + `{lang}/claude-api/files-api.md` + +**Agent with built-in tools (file/web/terminal):** +→ Read `{lang}/agent-sdk/README.md` + `{lang}/agent-sdk/patterns.md` + +### Claude API (Full File Reference) + +Read the **language-specific Claude API folder** (`{language}/claude-api/`): + +1. **`{language}/claude-api/README.md`** — **Read this first.** Installation, quick start, common patterns, error handling. +2. **`shared/tool-use-concepts.md`** — Read when the user needs function calling, code execution, memory, or structured outputs. Covers conceptual foundations. +3. **`{language}/claude-api/tool-use.md`** — Read for language-specific tool use code examples (tool runner, manual loop, code execution, memory, structured outputs). +4. **`{language}/claude-api/streaming.md`** — Read when building chat UIs or interfaces that display responses incrementally. +5. **`{language}/claude-api/batches.md`** — Read when processing many requests offline (not latency-sensitive). Runs asynchronously at 50% cost. +6. **`{language}/claude-api/files-api.md`** — Read when sending the same file across multiple requests without re-uploading. +7. **`shared/error-codes.md`** — Read when debugging HTTP errors or implementing error handling. +8. **`shared/live-sources.md`** — WebFetch URLs for fetching the latest official documentation. + +> **Note:** For Java, Go, Ruby, C#, PHP, and cURL — these have a single file each covering all basics. Read that file plus `shared/tool-use-concepts.md` and `shared/error-codes.md` as needed. + +### Agent SDK + +Read the **language-specific Agent SDK folder** (`{language}/agent-sdk/`). Agent SDK is available for **Python and TypeScript only**. + +1. **`{language}/agent-sdk/README.md`** — Installation, quick start, built-in tools, permissions, MCP, hooks. +2. **`{language}/agent-sdk/patterns.md`** — Custom tools, hooks, subagents, MCP integration, session resumption. +3. **`shared/live-sources.md`** — WebFetch URLs for current Agent SDK docs. + +--- + +## When to Use WebFetch + +Use WebFetch to get the latest documentation when: + +- User asks for "latest" or "current" information +- Cached data seems incorrect +- User asks about features not covered here + +Live documentation URLs are in `shared/live-sources.md`. + +## Common Pitfalls + +- Don't truncate inputs when passing files or content to the API. If the content is too long to fit in the context window, notify the user and discuss options (chunking, summarization, etc.) rather than silently truncating. +- **Opus 4.6 / Sonnet 4.6 thinking:** Use `thinking: {type: "adaptive"}` — do NOT use `budget_tokens` (deprecated on both Opus 4.6 and Sonnet 4.6). For older models, `budget_tokens` must be less than `max_tokens` (minimum 1024). This will throw an error if you get it wrong. +- **Opus 4.6 prefill removed:** Assistant message prefills (last-assistant-turn prefills) return a 400 error on Opus 4.6. Use structured outputs (`output_config.format`) or system prompt instructions to control response format instead. +- **128K output tokens:** Opus 4.6 supports up to 128K `max_tokens`, but the SDKs require streaming for large `max_tokens` to avoid HTTP timeouts. Use `.stream()` with `.get_final_message()` / `.finalMessage()`. +- **Tool call JSON parsing (Opus 4.6):** Opus 4.6 may produce different JSON string escaping in tool call `input` fields (e.g., Unicode or forward-slash escaping). Always parse tool inputs with `json.loads()` / `JSON.parse()` — never do raw string matching on the serialized input. +- **Structured outputs (all models):** Use `output_config: {format: {...}}` instead of the deprecated `output_format` parameter on `messages.create()`. This is a general API change, not 4.6-specific. +- **Don't reimplement SDK functionality:** The SDK provides high-level helpers — use them instead of building from scratch. Specifically: use `stream.finalMessage()` instead of wrapping `.on()` events in `new Promise()`; use typed exception classes (`Anthropic.RateLimitError`, etc.) instead of string-matching error messages; use SDK types (`Anthropic.MessageParam`, `Anthropic.Tool`, `Anthropic.Message`, etc.) instead of redefining equivalent interfaces. +- **Don't define custom types for SDK data structures:** The SDK exports types for all API objects. Use `Anthropic.MessageParam` for messages, `Anthropic.Tool` for tool definitions, `Anthropic.ToolUseBlock` / `Anthropic.ToolResultBlockParam` for tool results, `Anthropic.Message` for responses. Defining your own `interface ChatMessage { role: string; content: unknown }` duplicates what the SDK already provides and loses type safety. +- **Report and document output:** For tasks that produce reports, documents, or visualizations, the code execution sandbox has `python-docx`, `python-pptx`, `matplotlib`, `pillow`, and `pypdf` pre-installed. Claude can generate formatted files (DOCX, PDF, charts) and return them via the Files API — consider this for "report" or "document" type requests instead of plain stdout text. diff --git a/skills/claude-api/csharp/claude-api.md b/skills/claude-api/csharp/claude-api.md new file mode 100644 index 00000000..cfb938a2 --- /dev/null +++ b/skills/claude-api/csharp/claude-api.md @@ -0,0 +1,70 @@ +# Claude API — C# + +> **Note:** The C# SDK is the official Anthropic SDK for C#. Tool use is supported via the Messages API. A class-annotation-based tool runner is not available; use raw tool definitions with JSON schema. The SDK also supports Microsoft.Extensions.AI IChatClient integration with function invocation. + +## Installation + +```bash +dotnet add package Anthropic +``` + +## Client Initialization + +```csharp +using Anthropic; + +// Default (uses ANTHROPIC_API_KEY env var) +AnthropicClient client = new(); + +// Explicit API key (use environment variables — never hardcode keys) +AnthropicClient client = new() { + ApiKey = Environment.GetEnvironmentVariable("ANTHROPIC_API_KEY") +}; +``` + +--- + +## Basic Message Request + +```csharp +using Anthropic.Models.Messages; + +var parameters = new MessageCreateParams +{ + Model = Model.ClaudeOpus4_6, + MaxTokens = 1024, + Messages = [new() { Role = Role.User, Content = "What is the capital of France?" }] +}; +var message = await client.Messages.Create(parameters); +Console.WriteLine(message); +``` + +--- + +## Streaming + +```csharp +using Anthropic.Models.Messages; + +var parameters = new MessageCreateParams +{ + Model = Model.ClaudeOpus4_6, + MaxTokens = 1024, + Messages = [new() { Role = Role.User, Content = "Write a haiku" }] +}; + +await foreach (RawMessageStreamEvent streamEvent in client.Messages.CreateStreaming(parameters)) +{ + if (streamEvent.TryPickContentBlockDelta(out var delta) && + delta.Delta.TryPickText(out var text)) + { + Console.Write(text.Text); + } +} +``` + +--- + +## Tool Use (Manual Loop) + +The C# SDK supports raw tool definitions via JSON schema. See the [shared tool use concepts](../shared/tool-use-concepts.md) for the tool definition format and agentic loop pattern. diff --git a/skills/claude-api/curl/examples.md b/skills/claude-api/curl/examples.md new file mode 100644 index 00000000..f33e11b8 --- /dev/null +++ b/skills/claude-api/curl/examples.md @@ -0,0 +1,164 @@ +# Claude API — cURL / Raw HTTP + +Use these examples when the user needs raw HTTP requests or is working in a language without an official SDK. + +## Setup + +```bash +export ANTHROPIC_API_KEY="your-api-key" +``` + +--- + +## Basic Message Request + +```bash +curl https://api.anthropic.com/v1/messages \ + -H "Content-Type: application/json" \ + -H "x-api-key: $ANTHROPIC_API_KEY" \ + -H "anthropic-version: 2023-06-01" \ + -d '{ + "model": "claude-opus-4-6", + "max_tokens": 1024, + "messages": [ + {"role": "user", "content": "What is the capital of France?"} + ] + }' +``` + +--- + +## Streaming (SSE) + +```bash +curl https://api.anthropic.com/v1/messages \ + -H "Content-Type: application/json" \ + -H "x-api-key: $ANTHROPIC_API_KEY" \ + -H "anthropic-version: 2023-06-01" \ + -d '{ + "model": "claude-opus-4-6", + "max_tokens": 1024, + "stream": true, + "messages": [{"role": "user", "content": "Write a haiku"}] + }' +``` + +The response is a stream of Server-Sent Events: + +``` +event: message_start +data: {"type":"message_start","message":{"id":"msg_...","type":"message",...}} + +event: content_block_start +data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}} + +event: content_block_delta +data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Hello"}} + +event: content_block_stop +data: {"type":"content_block_stop","index":0} + +event: message_delta +data: {"type":"message_delta","delta":{"stop_reason":"end_turn"},"usage":{"output_tokens":12}} + +event: message_stop +data: {"type":"message_stop"} +``` + +--- + +## Tool Use + +```bash +curl https://api.anthropic.com/v1/messages \ + -H "Content-Type: application/json" \ + -H "x-api-key: $ANTHROPIC_API_KEY" \ + -H "anthropic-version: 2023-06-01" \ + -d '{ + "model": "claude-opus-4-6", + "max_tokens": 1024, + "tools": [{ + "name": "get_weather", + "description": "Get current weather for a location", + "input_schema": { + "type": "object", + "properties": { + "location": {"type": "string", "description": "City name"} + }, + "required": ["location"] + } + }], + "messages": [{"role": "user", "content": "What is the weather in Paris?"}] + }' +``` + +When Claude responds with a `tool_use` block, send the result back: + +```bash +curl https://api.anthropic.com/v1/messages \ + -H "Content-Type: application/json" \ + -H "x-api-key: $ANTHROPIC_API_KEY" \ + -H "anthropic-version: 2023-06-01" \ + -d '{ + "model": "claude-opus-4-6", + "max_tokens": 1024, + "tools": [{ + "name": "get_weather", + "description": "Get current weather for a location", + "input_schema": { + "type": "object", + "properties": { + "location": {"type": "string", "description": "City name"} + }, + "required": ["location"] + } + }], + "messages": [ + {"role": "user", "content": "What is the weather in Paris?"}, + {"role": "assistant", "content": [ + {"type": "text", "text": "Let me check the weather."}, + {"type": "tool_use", "id": "toolu_abc123", "name": "get_weather", "input": {"location": "Paris"}} + ]}, + {"role": "user", "content": [ + {"type": "tool_result", "tool_use_id": "toolu_abc123", "content": "72°F and sunny"} + ]} + ] + }' +``` + +--- + +## Extended Thinking + +> **Opus 4.6 and Sonnet 4.6:** Use adaptive thinking. `budget_tokens` is deprecated on both Opus 4.6 and Sonnet 4.6. +> **Older models:** Use `"type": "enabled"` with `"budget_tokens": N` (must be < `max_tokens`, min 1024). + +```bash +# Opus 4.6: adaptive thinking (recommended) +curl https://api.anthropic.com/v1/messages \ + -H "Content-Type: application/json" \ + -H "x-api-key: $ANTHROPIC_API_KEY" \ + -H "anthropic-version: 2023-06-01" \ + -d '{ + "model": "claude-opus-4-6", + "max_tokens": 16000, + "thinking": { + "type": "adaptive" + }, + "output_config": { + "effort": "high" + }, + "messages": [{"role": "user", "content": "Solve this step by step..."}] + }' +``` + +--- + +## Required Headers + +| Header | Value | Description | +| ------------------- | ------------------ | -------------------------- | +| `Content-Type` | `application/json` | Required | +| `x-api-key` | Your API key | Authentication | +| `anthropic-version` | `2023-06-01` | API version | +| `anthropic-beta` | Beta feature IDs | Required for beta features | diff --git a/skills/claude-api/go/claude-api.md b/skills/claude-api/go/claude-api.md new file mode 100644 index 00000000..7ba732ac --- /dev/null +++ b/skills/claude-api/go/claude-api.md @@ -0,0 +1,146 @@ +# Claude API — Go + +> **Note:** The Go SDK supports the Claude API and beta tool use with `BetaToolRunner`. Agent SDK is not yet available for Go. + +## Installation + +```bash +go get github.com/anthropics/anthropic-sdk-go +``` + +## Client Initialization + +```go +import ( + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +// Default (uses ANTHROPIC_API_KEY env var) +client := anthropic.NewClient() + +// Explicit API key +client := anthropic.NewClient( + option.WithAPIKey("your-api-key"), +) +``` + +--- + +## Basic Message Request + +```go +response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{ + Model: anthropic.ModelClaudeOpus4_6, + MaxTokens: 1024, + Messages: []anthropic.MessageParam{ + anthropic.NewUserMessage(anthropic.NewTextBlock("What is the capital of France?")), + }, +}) +if err != nil { + log.Fatal(err) +} +fmt.Println(response.Content[0].Text) +``` + +--- + +## Streaming + +```go +stream := client.Messages.NewStreaming(context.TODO(), anthropic.MessageNewParams{ + Model: anthropic.ModelClaudeOpus4_6, + MaxTokens: 1024, + Messages: []anthropic.MessageParam{ + anthropic.NewUserMessage(anthropic.NewTextBlock("Write a haiku")), + }, +}) + +for stream.Next() { + event := stream.Current() + switch eventVariant := event.AsAny().(type) { + case anthropic.ContentBlockDeltaEvent: + switch deltaVariant := eventVariant.Delta.AsAny().(type) { + case anthropic.TextDelta: + fmt.Print(deltaVariant.Text) + } + } +} +if err := stream.Err(); err != nil { + log.Fatal(err) +} +``` + +--- + +## Tool Use + +### Tool Runner (Beta — Recommended) + +**Beta:** The Go SDK provides `BetaToolRunner` for automatic tool use loops via the `toolrunner` package. + +```go +import ( + "context" + "fmt" + "log" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/toolrunner" +) + +// Define tool input with jsonschema tags for automatic schema generation +type GetWeatherInput struct { + City string `json:"city" jsonschema:"required,description=The city name"` +} + +// Create a tool with automatic schema generation from struct tags +weatherTool, err := toolrunner.NewBetaToolFromJSONSchema( + "get_weather", + "Get current weather for a city", + func(ctx context.Context, input GetWeatherInput) (anthropic.BetaToolResultBlockParamContentUnion, error) { + return anthropic.BetaToolResultBlockParamContentUnion{ + OfText: &anthropic.BetaTextBlockParam{ + Text: fmt.Sprintf("The weather in %s is sunny, 72°F", input.City), + }, + }, nil + }, +) +if err != nil { + log.Fatal(err) +} + +// Create a tool runner that handles the conversation loop automatically +runner := client.Beta.Messages.NewToolRunner( + []anthropic.BetaTool{weatherTool}, + anthropic.BetaToolRunnerParams{ + BetaMessageNewParams: anthropic.BetaMessageNewParams{ + Model: anthropic.ModelClaudeOpus4_6, + MaxTokens: 1024, + Messages: []anthropic.BetaMessageParam{ + anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("What's the weather in Paris?")), + }, + }, + MaxIterations: 5, + }, +) + +// Run until Claude produces a final response +message, err := runner.RunToCompletion(context.Background()) +if err != nil { + log.Fatal(err) +} +fmt.Println(message.Content[0].Text) +``` + +**Key features of the Go tool runner:** + +- Automatic schema generation from Go structs via `jsonschema` tags +- `RunToCompletion()` for simple one-shot usage +- `All()` iterator for processing each message in the conversation +- `NextMessage()` for step-by-step iteration +- Streaming variant via `NewToolRunnerStreaming()` with `AllStreaming()` + +### Manual Loop + +For fine-grained control, use raw tool definitions via JSON schema. See the [shared tool use concepts](../shared/tool-use-concepts.md) for the tool definition format and agentic loop pattern. diff --git a/skills/claude-api/java/claude-api.md b/skills/claude-api/java/claude-api.md new file mode 100644 index 00000000..d618dfee --- /dev/null +++ b/skills/claude-api/java/claude-api.md @@ -0,0 +1,128 @@ +# Claude API — Java + +> **Note:** The Java SDK supports the Claude API and beta tool use with annotated classes. Agent SDK is not yet available for Java. + +## Installation + +Maven: + +```xml + + com.anthropic + anthropic-java + 2.15.0 + +``` + +Gradle: + +```groovy +implementation("com.anthropic:anthropic-java:2.15.0") +``` + +## Client Initialization + +```java +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; + +// Default (reads ANTHROPIC_API_KEY from environment) +AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + +// Explicit API key +AnthropicClient client = AnthropicOkHttpClient.builder() + .apiKey("your-api-key") + .build(); +``` + +--- + +## Basic Message Request + +```java +import com.anthropic.models.messages.MessageCreateParams; +import com.anthropic.models.messages.Message; +import com.anthropic.models.messages.Model; + +MessageCreateParams params = MessageCreateParams.builder() + .model(Model.CLAUDE_OPUS_4_6) + .maxTokens(1024L) + .addUserMessage("What is the capital of France?") + .build(); + +Message response = client.messages().create(params); +response.content().stream() + .flatMap(block -> block.text().stream()) + .forEach(textBlock -> System.out.println(textBlock.text())); +``` + +--- + +## Streaming + +```java +import com.anthropic.core.http.StreamResponse; +import com.anthropic.models.messages.RawMessageStreamEvent; + +MessageCreateParams params = MessageCreateParams.builder() + .model(Model.CLAUDE_OPUS_4_6) + .maxTokens(1024L) + .addUserMessage("Write a haiku") + .build(); + +try (StreamResponse streamResponse = client.messages().createStreaming(params)) { + streamResponse.stream() + .flatMap(event -> event.contentBlockDelta().stream()) + .flatMap(deltaEvent -> deltaEvent.delta().text().stream()) + .forEach(textDelta -> System.out.print(textDelta.text())); +} +``` + +--- + +## Tool Use (Beta) + +The Java SDK supports beta tool use with annotated classes. Tool classes implement `Supplier` for automatic execution via `BetaToolRunner`. + +### Tool Runner (automatic loop) + +```java +import com.anthropic.models.beta.messages.MessageCreateParams; +import com.anthropic.models.beta.messages.BetaMessage; +import com.anthropic.helpers.BetaToolRunner; +import com.fasterxml.jackson.annotation.JsonClassDescription; +import com.fasterxml.jackson.annotation.JsonPropertyDescription; +import java.util.function.Supplier; + +@JsonClassDescription("Get the weather in a given location") +static class GetWeather implements Supplier { + @JsonPropertyDescription("The city and state, e.g. San Francisco, CA") + public String location; + + @Override + public String get() { + return "The weather in " + location + " is sunny and 72°F"; + } +} + +BetaToolRunner toolRunner = client.beta().messages().toolRunner( + MessageCreateParams.builder() + .model("claude-opus-4-6") + .maxTokens(1024L) + .putAdditionalHeader("anthropic-beta", "structured-outputs-2025-11-13") + .addTool(GetWeather.class) + .addUserMessage("What's the weather in San Francisco?") + .build()); + +for (BetaMessage message : toolRunner) { + System.out.println(message); +} +``` + +### Non-Beta Tool Use + +Tool use is also available through the non-beta `com.anthropic.models.messages.MessageCreateParams` with `addTool(Tool)` for manually defined JSON schemas, without needing the beta namespace. The beta namespace is only needed for the class-annotation convenience layer (`@JsonClassDescription`, `BetaToolRunner`). + +### Manual Loop + +For manual tool loops, define tools as JSON schema in the request, handle `tool_use` blocks in the response, send `tool_result` back, and loop until `stop_reason` is `"end_turn"`. See the [shared tool use concepts](../shared/tool-use-concepts.md) for the agentic loop pattern. diff --git a/skills/claude-api/php/claude-api.md b/skills/claude-api/php/claude-api.md new file mode 100644 index 00000000..4aab6b4a --- /dev/null +++ b/skills/claude-api/php/claude-api.md @@ -0,0 +1,88 @@ +# Claude API — PHP + +> **Note:** The PHP SDK is the official Anthropic SDK for PHP. Tool runner and Agent SDK are not available. Bedrock, Vertex AI, and Foundry clients are supported. + +## Installation + +```bash +composer require "anthropic-ai/sdk" +``` + +## Client Initialization + +```php +use Anthropic\Client; + +// Using API key from environment variable +$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY")); +``` + +### Amazon Bedrock + +```php +use Anthropic\BedrockClient; + +$client = new BedrockClient( + region: 'us-east-1', +); +``` + +### Google Vertex AI + +```php +use Anthropic\VertexClient; + +$client = new VertexClient( + region: 'us-east5', + projectId: 'my-project-id', +); +``` + +### Anthropic Foundry + +```php +use Anthropic\FoundryClient; + +$client = new FoundryClient( + authToken: getenv("ANTHROPIC_AUTH_TOKEN"), +); +``` + +--- + +## Basic Message Request + +```php +$message = $client->messages->create( + model: 'claude-opus-4-6', + maxTokens: 1024, + messages: [ + ['role' => 'user', 'content' => 'What is the capital of France?'], + ], +); +echo $message->content[0]->text; +``` + +--- + +## Streaming + +```php +$stream = $client->messages->createStream( + model: 'claude-opus-4-6', + maxTokens: 1024, + messages: [ + ['role' => 'user', 'content' => 'Write a haiku'], + ], +); + +foreach ($stream as $event) { + echo $event; +} +``` + +--- + +## Tool Use (Manual Loop) + +The PHP SDK supports raw tool definitions via JSON schema. See the [shared tool use concepts](../shared/tool-use-concepts.md) for the tool definition format and agentic loop pattern. diff --git a/skills/claude-api/python/agent-sdk/README.md b/skills/claude-api/python/agent-sdk/README.md new file mode 100644 index 00000000..c819c674 --- /dev/null +++ b/skills/claude-api/python/agent-sdk/README.md @@ -0,0 +1,269 @@ +# Agent SDK — Python + +The Claude Agent SDK provides a higher-level interface for building AI agents with built-in tools, safety features, and agentic capabilities. + +## Installation + +```bash +pip install claude-agent-sdk +``` + +--- + +## Quick Start + +```python +import anyio +from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage + +async def main(): + async for message in query( + prompt="Explain this codebase", + options=ClaudeAgentOptions(allowed_tools=["Read", "Glob", "Grep"]) + ): + if isinstance(message, ResultMessage): + print(message.result) + +anyio.run(main) +``` + +--- + +## Built-in Tools + +| Tool | Description | +| --------- | ------------------------------------ | +| Read | Read files in the workspace | +| Write | Create new files | +| Edit | Make precise edits to existing files | +| Bash | Execute shell commands | +| Glob | Find files by pattern | +| Grep | Search files by content | +| WebSearch | Search the web for information | +| WebFetch | Fetch and analyze web pages | +| AskUserQuestion | Ask user clarifying questions | +| Agent | Spawn subagents | + +--- + +## Primary Interfaces + +### `query()` — Simple One-Shot Usage + +The `query()` function is the simplest way to run an agent. It returns an async iterator of messages. + +```python +from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage + +async for message in query( + prompt="Explain this codebase", + options=ClaudeAgentOptions(allowed_tools=["Read", "Glob", "Grep"]) +): + if isinstance(message, ResultMessage): + print(message.result) +``` + +### `ClaudeSDKClient` — Full Control + +`ClaudeSDKClient` provides full control over the agent lifecycle. Use it when you need custom tools, hooks, streaming, or the ability to interrupt execution. + +```python +import anyio +from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions, AssistantMessage, TextBlock + +async def main(): + options = ClaudeAgentOptions(allowed_tools=["Read", "Glob", "Grep"]) + async with ClaudeSDKClient(options=options) as client: + await client.query("Explain this codebase") + async for message in client.receive_response(): + if isinstance(message, AssistantMessage): + for block in message.content: + if isinstance(block, TextBlock): + print(block.text) + +anyio.run(main) +``` + +`ClaudeSDKClient` supports: + +- **Context manager** (`async with`) for automatic resource cleanup +- **`client.query(prompt)`** to send a prompt to the agent +- **`receive_response()`** for streaming messages until completion +- **`interrupt()`** to stop agent execution mid-task +- **Required for custom tools** (via SDK MCP servers) + +--- + +## Permission System + +```python +from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage + +async for message in query( + prompt="Refactor the authentication module", + options=ClaudeAgentOptions( + allowed_tools=["Read", "Edit", "Write"], + permission_mode="acceptEdits" # Auto-accept file edits + ) +): + if isinstance(message, ResultMessage): + print(message.result) +``` + +Permission modes: + +- `"default"`: Prompt for dangerous operations +- `"plan"`: Planning only, no execution +- `"acceptEdits"`: Auto-accept file edits +- `"dontAsk"`: Don't prompt (useful for CI/CD) +- `"bypassPermissions"`: Skip all prompts (requires `allow_dangerously_skip_permissions=True` in options) + +--- + +## MCP (Model Context Protocol) Support + +```python +from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage + +async for message in query( + prompt="Open example.com and describe what you see", + options=ClaudeAgentOptions( + mcp_servers={ + "playwright": {"command": "npx", "args": ["@playwright/mcp@latest"]} + } + ) +): + if isinstance(message, ResultMessage): + print(message.result) +``` + +--- + +## Hooks + +Customize agent behavior with hooks using callback functions: + +```python +from claude_agent_sdk import query, ClaudeAgentOptions, HookMatcher, ResultMessage + +async def log_file_change(input_data, tool_use_id, context): + file_path = input_data.get('tool_input', {}).get('file_path', 'unknown') + print(f"Modified: {file_path}") + return {} + +async for message in query( + prompt="Refactor utils.py", + options=ClaudeAgentOptions( + permission_mode="acceptEdits", + hooks={ + "PostToolUse": [HookMatcher(matcher="Edit|Write", hooks=[log_file_change])] + } + ) +): + if isinstance(message, ResultMessage): + print(message.result) +``` + +Available hook events: `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `Notification`, `UserPromptSubmit`, `SessionStart`, `SessionEnd`, `Stop`, `SubagentStart`, `SubagentStop`, `PreCompact`, `PermissionRequest`, `Setup`, `TeammateIdle`, `TaskCompleted`, `ConfigChange` + +--- + +## Common Options + +`query()` takes a top-level `prompt` (string) and an `options` object (`ClaudeAgentOptions`): + +```python +async for message in query(prompt="...", options=ClaudeAgentOptions(...)): +``` + +| Option | Type | Description | +| ----------------------------------- | ------ | -------------------------------------------------------------------------- | +| `cwd` | string | Working directory for file operations | +| `allowed_tools` | list | Tools the agent can use (e.g., `["Read", "Edit", "Bash"]`) | +| `tools` | list | Built-in tools to make available (restricts the default set) | +| `disallowed_tools` | list | Tools to explicitly disallow | +| `permission_mode` | string | How to handle permission prompts | +| `allow_dangerously_skip_permissions`| bool | Must be `True` to use `permission_mode="bypassPermissions"` | +| `mcp_servers` | dict | MCP servers to connect to | +| `hooks` | dict | Hooks for customizing behavior | +| `system_prompt` | string | Custom system prompt | +| `max_turns` | int | Maximum agent turns before stopping | +| `max_budget_usd` | float | Maximum budget in USD for the query | +| `model` | string | Model ID (default: determined by CLI) | +| `agents` | dict | Subagent definitions (`dict[str, AgentDefinition]`) | +| `output_format` | dict | Structured output schema | +| `thinking` | dict | Thinking/reasoning control | +| `betas` | list | Beta features to enable (e.g., `["context-1m-2025-08-07"]`) | +| `setting_sources` | list | Settings to load (e.g., `["project"]`). Default: none (no CLAUDE.md files) | +| `env` | dict | Environment variables to set for the session | + +--- + +## Message Types + +```python +from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage, SystemMessage + +async for message in query( + prompt="Find TODO comments", + options=ClaudeAgentOptions(allowed_tools=["Read", "Glob", "Grep"]) +): + if isinstance(message, ResultMessage): + print(message.result) + elif isinstance(message, SystemMessage) and message.subtype == "init": + session_id = message.session_id # Capture for resuming later +``` + +--- + +## Subagents + +```python +from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition, ResultMessage + +async for message in query( + prompt="Use the code-reviewer agent to review this codebase", + options=ClaudeAgentOptions( + allowed_tools=["Read", "Glob", "Grep", "Agent"], + agents={ + "code-reviewer": AgentDefinition( + description="Expert code reviewer for quality and security reviews.", + prompt="Analyze code quality and suggest improvements.", + tools=["Read", "Glob", "Grep"] + ) + } + ) +): + if isinstance(message, ResultMessage): + print(message.result) +``` + +--- + +## Error Handling + +```python +from claude_agent_sdk import query, ClaudeAgentOptions, CLINotFoundError, CLIConnectionError, ResultMessage + +try: + async for message in query( + prompt="...", + options=ClaudeAgentOptions(allowed_tools=["Read"]) + ): + if isinstance(message, ResultMessage): + print(message.result) +except CLINotFoundError: + print("Claude Code CLI not found. Install with: pip install claude-agent-sdk") +except CLIConnectionError as e: + print(f"Connection error: {e}") +``` + +--- + +## Best Practices + +1. **Always specify allowed_tools** — Explicitly list which tools the agent can use +2. **Set working directory** — Always specify `cwd` for file operations +3. **Use appropriate permission modes** — Start with `"default"` and only escalate when needed +4. **Handle all message types** — Check for `ResultMessage` to get agent output +5. **Limit max_turns** — Prevent runaway agents with reasonable limits diff --git a/skills/claude-api/python/agent-sdk/patterns.md b/skills/claude-api/python/agent-sdk/patterns.md new file mode 100644 index 00000000..5e6ea911 --- /dev/null +++ b/skills/claude-api/python/agent-sdk/patterns.md @@ -0,0 +1,319 @@ +# Agent SDK Patterns — Python + +## Basic Agent + +```python +import anyio +from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage + +async def main(): + async for message in query( + prompt="Explain what this repository does", + options=ClaudeAgentOptions( + cwd="/path/to/project", + allowed_tools=["Read", "Glob", "Grep"] + ) + ): + if isinstance(message, ResultMessage): + print(message.result) + +anyio.run(main) +``` + +--- + +## Custom Tools + +Custom tools require an MCP server. Use `ClaudeSDKClient` for full control, or pass the server to `query()` via `mcp_servers`. + +```python +import anyio +from claude_agent_sdk import ( + tool, + create_sdk_mcp_server, + ClaudeSDKClient, + ClaudeAgentOptions, + AssistantMessage, + TextBlock, +) + +@tool("get_weather", "Get the current weather for a location", {"location": str}) +async def get_weather(args): + location = args["location"] + return {"content": [{"type": "text", "text": f"The weather in {location} is sunny and 72°F."}]} + +server = create_sdk_mcp_server("weather-tools", tools=[get_weather]) + +async def main(): + options = ClaudeAgentOptions(mcp_servers={"weather": server}) + async with ClaudeSDKClient(options=options) as client: + await client.query("What's the weather in Paris?") + async for message in client.receive_response(): + if isinstance(message, AssistantMessage): + for block in message.content: + if isinstance(block, TextBlock): + print(block.text) + +anyio.run(main) +``` + +--- + +## Hooks + +### After Tool Use Hook + +Log file changes after any edit: + +```python +import anyio +from datetime import datetime +from claude_agent_sdk import query, ClaudeAgentOptions, HookMatcher, ResultMessage + +async def log_file_change(input_data, tool_use_id, context): + file_path = input_data.get('tool_input', {}).get('file_path', 'unknown') + with open('./audit.log', 'a') as f: + f.write(f"{datetime.now()}: modified {file_path}\n") + return {} + +async def main(): + async for message in query( + prompt="Refactor utils.py to improve readability", + options=ClaudeAgentOptions( + allowed_tools=["Read", "Edit", "Write"], + permission_mode="acceptEdits", + hooks={ + "PostToolUse": [HookMatcher(matcher="Edit|Write", hooks=[log_file_change])] + } + ) + ): + if isinstance(message, ResultMessage): + print(message.result) + +anyio.run(main) +``` + +--- + +## Subagents + +```python +import anyio +from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition, ResultMessage + +async def main(): + async for message in query( + prompt="Use the code-reviewer agent to review this codebase", + options=ClaudeAgentOptions( + allowed_tools=["Read", "Glob", "Grep", "Agent"], + agents={ + "code-reviewer": AgentDefinition( + description="Expert code reviewer for quality and security reviews.", + prompt="Analyze code quality and suggest improvements.", + tools=["Read", "Glob", "Grep"] + ) + } + ) + ): + if isinstance(message, ResultMessage): + print(message.result) + +anyio.run(main) +``` + +--- + +## MCP Server Integration + +### Browser Automation (Playwright) + +```python +import anyio +from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage + +async def main(): + async for message in query( + prompt="Open example.com and describe what you see", + options=ClaudeAgentOptions( + mcp_servers={ + "playwright": {"command": "npx", "args": ["@playwright/mcp@latest"]} + } + ) + ): + if isinstance(message, ResultMessage): + print(message.result) + +anyio.run(main) +``` + +### Database Access (PostgreSQL) + +```python +import os +import anyio +from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage + +async def main(): + async for message in query( + prompt="Show me the top 10 users by order count", + options=ClaudeAgentOptions( + mcp_servers={ + "postgres": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-postgres"], + "env": {"DATABASE_URL": os.environ["DATABASE_URL"]} + } + } + ) + ): + if isinstance(message, ResultMessage): + print(message.result) + +anyio.run(main) +``` + +--- + +## Permission Modes + +```python +import anyio +from claude_agent_sdk import query, ClaudeAgentOptions + +async def main(): + # Default: prompt for dangerous operations + async for message in query( + prompt="Delete all test files", + options=ClaudeAgentOptions( + allowed_tools=["Bash"], + permission_mode="default" # Will prompt before deleting + ) + ): + pass + + # Plan: agent creates a plan before making changes + async for message in query( + prompt="Refactor the auth system", + options=ClaudeAgentOptions( + allowed_tools=["Read", "Edit"], + permission_mode="plan" + ) + ): + pass + + # Accept edits: auto-accept file edits + async for message in query( + prompt="Refactor this module", + options=ClaudeAgentOptions( + allowed_tools=["Read", "Edit"], + permission_mode="acceptEdits" + ) + ): + pass + + # Bypass: skip all prompts (use with caution) + async for message in query( + prompt="Set up the development environment", + options=ClaudeAgentOptions( + allowed_tools=["Bash", "Write"], + permission_mode="bypassPermissions", + allow_dangerously_skip_permissions=True + ) + ): + pass + +anyio.run(main) +``` + +--- + +## Error Recovery + +```python +import anyio +from claude_agent_sdk import ( + query, + ClaudeAgentOptions, + CLINotFoundError, + CLIConnectionError, + ProcessError, + ResultMessage, +) + +async def run_with_recovery(): + try: + async for message in query( + prompt="Fix the failing tests", + options=ClaudeAgentOptions( + allowed_tools=["Read", "Edit", "Bash"], + max_turns=10 + ) + ): + if isinstance(message, ResultMessage): + print(message.result) + except CLINotFoundError: + print("Claude Code CLI not found. Install with: pip install claude-agent-sdk") + except CLIConnectionError as e: + print(f"Connection error: {e}") + except ProcessError as e: + print(f"Process error: {e}") + +anyio.run(run_with_recovery) +``` + +--- + +## Session Resumption + +```python +import anyio +from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage, SystemMessage + +async def main(): + session_id = None + + # First query: capture the session ID + async for message in query( + prompt="Read the authentication module", + options=ClaudeAgentOptions(allowed_tools=["Read", "Glob"]) + ): + if isinstance(message, SystemMessage) and message.subtype == "init": + session_id = message.session_id + + # Resume with full context from the first query + async for message in query( + prompt="Now find all places that call it", # "it" = auth module + options=ClaudeAgentOptions(resume=session_id) + ): + if isinstance(message, ResultMessage): + print(message.result) + +anyio.run(main) +``` + +--- + +## Custom System Prompt + +```python +import anyio +from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage + +async def main(): + async for message in query( + prompt="Review this code", + options=ClaudeAgentOptions( + allowed_tools=["Read", "Glob", "Grep"], + system_prompt="""You are a senior code reviewer focused on: +1. Security vulnerabilities +2. Performance issues +3. Code maintainability + +Always provide specific line numbers and suggestions for improvement.""" + ) + ): + if isinstance(message, ResultMessage): + print(message.result) + +anyio.run(main) +``` diff --git a/skills/claude-api/python/claude-api/README.md b/skills/claude-api/python/claude-api/README.md new file mode 100644 index 00000000..ae8801bb --- /dev/null +++ b/skills/claude-api/python/claude-api/README.md @@ -0,0 +1,404 @@ +# Claude API — Python + +## Installation + +```bash +pip install anthropic +``` + +## Client Initialization + +```python +import anthropic + +# Default (uses ANTHROPIC_API_KEY env var) +client = anthropic.Anthropic() + +# Explicit API key +client = anthropic.Anthropic(api_key="your-api-key") + +# Async client +async_client = anthropic.AsyncAnthropic() +``` + +--- + +## Basic Message Request + +```python +response = client.messages.create( + model="claude-opus-4-6", + max_tokens=1024, + messages=[ + {"role": "user", "content": "What is the capital of France?"} + ] +) +print(response.content[0].text) +``` + +--- + +## System Prompts + +```python +response = client.messages.create( + model="claude-opus-4-6", + max_tokens=1024, + system="You are a helpful coding assistant. Always provide examples in Python.", + messages=[{"role": "user", "content": "How do I read a JSON file?"}] +) +``` + +--- + +## Vision (Images) + +### Base64 + +```python +import base64 + +with open("image.png", "rb") as f: + image_data = base64.standard_b64encode(f.read()).decode("utf-8") + +response = client.messages.create( + model="claude-opus-4-6", + max_tokens=1024, + messages=[{ + "role": "user", + "content": [ + { + "type": "image", + "source": { + "type": "base64", + "media_type": "image/png", + "data": image_data + } + }, + {"type": "text", "text": "What's in this image?"} + ] + }] +) +``` + +### URL + +```python +response = client.messages.create( + model="claude-opus-4-6", + max_tokens=1024, + messages=[{ + "role": "user", + "content": [ + { + "type": "image", + "source": { + "type": "url", + "url": "https://example.com/image.png" + } + }, + {"type": "text", "text": "Describe this image"} + ] + }] +) +``` + +--- + +## Prompt Caching + +Cache large context to reduce costs (up to 90% savings). + +### Automatic Caching (Recommended) + +Use top-level `cache_control` to automatically cache the last cacheable block in the request — no need to annotate individual content blocks: + +```python +response = client.messages.create( + model="claude-opus-4-6", + max_tokens=1024, + cache_control={"type": "ephemeral"}, # auto-caches the last cacheable block + system="You are an expert on this large document...", + messages=[{"role": "user", "content": "Summarize the key points"}] +) +``` + +### Manual Cache Control + +For fine-grained control, add `cache_control` to specific content blocks: + +```python +response = client.messages.create( + model="claude-opus-4-6", + max_tokens=1024, + system=[{ + "type": "text", + "text": "You are an expert on this large document...", + "cache_control": {"type": "ephemeral"} # default TTL is 5 minutes + }], + messages=[{"role": "user", "content": "Summarize the key points"}] +) + +# With explicit TTL (time-to-live) +response = client.messages.create( + model="claude-opus-4-6", + max_tokens=1024, + system=[{ + "type": "text", + "text": "You are an expert on this large document...", + "cache_control": {"type": "ephemeral", "ttl": "1h"} # 1 hour TTL + }], + messages=[{"role": "user", "content": "Summarize the key points"}] +) +``` + +--- + +## Extended Thinking + +> **Opus 4.6 and Sonnet 4.6:** Use adaptive thinking. `budget_tokens` is deprecated on both Opus 4.6 and Sonnet 4.6. +> **Older models:** Use `thinking: {type: "enabled", budget_tokens: N}` (must be < `max_tokens`, min 1024). + +```python +# Opus 4.6: adaptive thinking (recommended) +response = client.messages.create( + model="claude-opus-4-6", + max_tokens=16000, + thinking={"type": "adaptive"}, + output_config={"effort": "high"}, # low | medium | high | max + messages=[{"role": "user", "content": "Solve this step by step..."}] +) + +# Access thinking and response +for block in response.content: + if block.type == "thinking": + print(f"Thinking: {block.thinking}") + elif block.type == "text": + print(f"Response: {block.text}") +``` + +--- + +## Error Handling + +```python +import anthropic + +try: + response = client.messages.create(...) +except anthropic.BadRequestError as e: + print(f"Bad request: {e.message}") +except anthropic.AuthenticationError: + print("Invalid API key") +except anthropic.PermissionDeniedError: + print("API key lacks required permissions") +except anthropic.NotFoundError: + print("Invalid model or endpoint") +except anthropic.RateLimitError as e: + retry_after = int(e.response.headers.get("retry-after", "60")) + print(f"Rate limited. Retry after {retry_after}s.") +except anthropic.APIStatusError as e: + if e.status_code >= 500: + print(f"Server error ({e.status_code}). Retry later.") + else: + print(f"API error: {e.message}") +except anthropic.APIConnectionError: + print("Network error. Check internet connection.") +``` + +--- + +## Multi-Turn Conversations + +The API is stateless — send the full conversation history each time. + +```python +class ConversationManager: + """Manage multi-turn conversations with the Claude API.""" + + def __init__(self, client: anthropic.Anthropic, model: str, system: str = None): + self.client = client + self.model = model + self.system = system + self.messages = [] + + def send(self, user_message: str, **kwargs) -> str: + """Send a message and get a response.""" + self.messages.append({"role": "user", "content": user_message}) + + response = self.client.messages.create( + model=self.model, + max_tokens=kwargs.get("max_tokens", 1024), + system=self.system, + messages=self.messages, + **kwargs + ) + + assistant_message = response.content[0].text + self.messages.append({"role": "assistant", "content": assistant_message}) + + return assistant_message + +# Usage +conversation = ConversationManager( + client=anthropic.Anthropic(), + model="claude-opus-4-6", + system="You are a helpful assistant." +) + +response1 = conversation.send("My name is Alice.") +response2 = conversation.send("What's my name?") # Claude remembers "Alice" +``` + +**Rules:** + +- Messages must alternate between `user` and `assistant` +- First message must be `user` + +--- + +### Compaction (long conversations) + +> **Beta, Opus 4.6 only.** When conversations approach the 200K context window, compaction automatically summarizes earlier context server-side. The API returns a `compaction` block; you must pass it back on subsequent requests — append `response.content`, not just the text. + +```python +import anthropic + +client = anthropic.Anthropic() +messages = [] + +def chat(user_message: str) -> str: + messages.append({"role": "user", "content": user_message}) + + response = client.beta.messages.create( + betas=["compact-2026-01-12"], + model="claude-opus-4-6", + max_tokens=4096, + messages=messages, + context_management={ + "edits": [{"type": "compact_20260112"}] + } + ) + + # Append full content — compaction blocks must be preserved + messages.append({"role": "assistant", "content": response.content}) + + return next(block.text for block in response.content if block.type == "text") + +# Compaction triggers automatically when context grows large +print(chat("Help me build a Python web scraper")) +print(chat("Add support for JavaScript-rendered pages")) +print(chat("Now add rate limiting and error handling")) +``` + +--- + +## Stop Reasons + +The `stop_reason` field in the response indicates why the model stopped generating: + +| Value | Meaning | +|-------|---------| +| `end_turn` | Claude finished its response naturally | +| `max_tokens` | Hit the `max_tokens` limit — increase it or use streaming | +| `stop_sequence` | Hit a custom stop sequence | +| `tool_use` | Claude wants to call a tool — execute it and continue | +| `pause_turn` | Model paused and can be resumed (agentic flows) | +| `refusal` | Claude refused for safety reasons — output may not match your schema | + +--- + +## Cost Optimization Strategies + +### 1. Use Prompt Caching for Repeated Context + +```python +# Automatic caching (simplest — caches the last cacheable block) +response = client.messages.create( + model="claude-opus-4-6", + max_tokens=1024, + cache_control={"type": "ephemeral"}, + system=large_document_text, # e.g., 50KB of context + messages=[{"role": "user", "content": "Summarize the key points"}] +) + +# First request: full cost +# Subsequent requests: ~90% cheaper for cached portion +``` + +### 2. Choose the Right Model + +```python +# Default to Opus for most tasks +response = client.messages.create( + model="claude-opus-4-6", # $5.00/$25.00 per 1M tokens + max_tokens=1024, + messages=[{"role": "user", "content": "Explain quantum computing"}] +) + +# Use Sonnet for high-volume production workloads +standard_response = client.messages.create( + model="claude-sonnet-4-6", # $3.00/$15.00 per 1M tokens + max_tokens=1024, + messages=[{"role": "user", "content": "Summarize this document"}] +) + +# Use Haiku only for simple, speed-critical tasks +simple_response = client.messages.create( + model="claude-haiku-4-5", # $1.00/$5.00 per 1M tokens + max_tokens=256, + messages=[{"role": "user", "content": "Classify this as positive or negative"}] +) +``` + +### 3. Use Token Counting Before Requests + +```python +count_response = client.messages.count_tokens( + model="claude-opus-4-6", + messages=messages, + system=system +) + +estimated_input_cost = count_response.input_tokens * 0.000005 # $5/1M tokens +print(f"Estimated input cost: ${estimated_input_cost:.4f}") +``` + +--- + +## Retry with Exponential Backoff + +> **Note:** The Anthropic SDK automatically retries rate limit (429) and server errors (5xx) with exponential backoff. You can configure this with `max_retries` (default: 2). Only implement custom retry logic if you need behavior beyond what the SDK provides. + +```python +import time +import random +import anthropic + +def call_with_retry( + client: anthropic.Anthropic, + max_retries: int = 5, + base_delay: float = 1.0, + max_delay: float = 60.0, + **kwargs +): + """Call the API with exponential backoff retry.""" + last_exception = None + + for attempt in range(max_retries): + try: + return client.messages.create(**kwargs) + except anthropic.RateLimitError as e: + last_exception = e + except anthropic.APIStatusError as e: + if e.status_code >= 500: + last_exception = e + else: + raise # Client errors (4xx except 429) should not be retried + + delay = min(base_delay * (2 ** attempt) + random.uniform(0, 1), max_delay) + print(f"Retry {attempt + 1}/{max_retries} after {delay:.1f}s") + time.sleep(delay) + + raise last_exception +``` diff --git a/skills/claude-api/python/claude-api/batches.md b/skills/claude-api/python/claude-api/batches.md new file mode 100644 index 00000000..c9027689 --- /dev/null +++ b/skills/claude-api/python/claude-api/batches.md @@ -0,0 +1,182 @@ +# Message Batches API — Python + +The Batches API (`POST /v1/messages/batches`) processes Messages API requests asynchronously at 50% of standard prices. + +## Key Facts + +- Up to 100,000 requests or 256 MB per batch +- Most batches complete within 1 hour; maximum 24 hours +- Results available for 29 days after creation +- 50% cost reduction on all token usage +- All Messages API features supported (vision, tools, caching, etc.) + +--- + +## Create a Batch + +```python +import anthropic +from anthropic.types.message_create_params import MessageCreateParamsNonStreaming +from anthropic.types.messages.batch_create_params import Request + +client = anthropic.Anthropic() + +message_batch = client.messages.batches.create( + requests=[ + Request( + custom_id="request-1", + params=MessageCreateParamsNonStreaming( + model="claude-opus-4-6", + max_tokens=1024, + messages=[{"role": "user", "content": "Summarize climate change impacts"}] + ) + ), + Request( + custom_id="request-2", + params=MessageCreateParamsNonStreaming( + model="claude-opus-4-6", + max_tokens=1024, + messages=[{"role": "user", "content": "Explain quantum computing basics"}] + ) + ), + ] +) + +print(f"Batch ID: {message_batch.id}") +print(f"Status: {message_batch.processing_status}") +``` + +--- + +## Poll for Completion + +```python +import time + +while True: + batch = client.messages.batches.retrieve(message_batch.id) + if batch.processing_status == "ended": + break + print(f"Status: {batch.processing_status}, processing: {batch.request_counts.processing}") + time.sleep(60) + +print("Batch complete!") +print(f"Succeeded: {batch.request_counts.succeeded}") +print(f"Errored: {batch.request_counts.errored}") +``` + +--- + +## Retrieve Results + +> **Note:** Examples below use `match/case` syntax, requiring Python 3.10+. For earlier versions, use `if/elif` chains instead. + +```python +for result in client.messages.batches.results(message_batch.id): + match result.result.type: + case "succeeded": + print(f"[{result.custom_id}] {result.result.message.content[0].text[:100]}") + case "errored": + if result.result.error.type == "invalid_request": + print(f"[{result.custom_id}] Validation error - fix request and retry") + else: + print(f"[{result.custom_id}] Server error - safe to retry") + case "canceled": + print(f"[{result.custom_id}] Canceled") + case "expired": + print(f"[{result.custom_id}] Expired - resubmit") +``` + +--- + +## Cancel a Batch + +```python +cancelled = client.messages.batches.cancel(message_batch.id) +print(f"Status: {cancelled.processing_status}") # "canceling" +``` + +--- + +## Batch with Prompt Caching + +```python +shared_system = [ + {"type": "text", "text": "You are a literary analyst."}, + { + "type": "text", + "text": large_document_text, # Shared across all requests + "cache_control": {"type": "ephemeral"} + } +] + +message_batch = client.messages.batches.create( + requests=[ + Request( + custom_id=f"analysis-{i}", + params=MessageCreateParamsNonStreaming( + model="claude-opus-4-6", + max_tokens=1024, + system=shared_system, + messages=[{"role": "user", "content": question}] + ) + ) + for i, question in enumerate(questions) + ] +) +``` + +--- + +## Full End-to-End Example + +```python +import anthropic +import time +from anthropic.types.message_create_params import MessageCreateParamsNonStreaming +from anthropic.types.messages.batch_create_params import Request + +client = anthropic.Anthropic() + +# 1. Prepare requests +items_to_classify = [ + "The product quality is excellent!", + "Terrible customer service, never again.", + "It's okay, nothing special.", +] + +requests = [ + Request( + custom_id=f"classify-{i}", + params=MessageCreateParamsNonStreaming( + model="claude-haiku-4-5", + max_tokens=50, + messages=[{ + "role": "user", + "content": f"Classify as positive/negative/neutral (one word): {text}" + }] + ) + ) + for i, text in enumerate(items_to_classify) +] + +# 2. Create batch +batch = client.messages.batches.create(requests=requests) +print(f"Created batch: {batch.id}") + +# 3. Wait for completion +while True: + batch = client.messages.batches.retrieve(batch.id) + if batch.processing_status == "ended": + break + time.sleep(10) + +# 4. Collect results +results = {} +for result in client.messages.batches.results(batch.id): + if result.result.type == "succeeded": + results[result.custom_id] = result.result.message.content[0].text + +for custom_id, classification in sorted(results.items()): + print(f"{custom_id}: {classification}") +``` diff --git a/skills/claude-api/python/claude-api/files-api.md b/skills/claude-api/python/claude-api/files-api.md new file mode 100644 index 00000000..efcdd9cb --- /dev/null +++ b/skills/claude-api/python/claude-api/files-api.md @@ -0,0 +1,162 @@ +# Files API — Python + +The Files API uploads files for use in Messages API requests. Reference files via `file_id` in content blocks, avoiding re-uploads across multiple API calls. + +**Beta:** Pass `betas=["files-api-2025-04-14"]` in your API calls (the SDK sets the required header automatically). + +## Key Facts + +- Maximum file size: 500 MB +- Total storage: 100 GB per organization +- Files persist until deleted +- File operations (upload, list, delete) are free; content used in messages is billed as input tokens +- Not available on Amazon Bedrock or Google Vertex AI + +--- + +## Upload a File + +```python +import anthropic + +client = anthropic.Anthropic() + +uploaded = client.beta.files.upload( + file=("report.pdf", open("report.pdf", "rb"), "application/pdf"), +) +print(f"File ID: {uploaded.id}") +print(f"Size: {uploaded.size_bytes} bytes") +``` + +--- + +## Use a File in Messages + +### PDF / Text Document + +```python +response = client.beta.messages.create( + model="claude-opus-4-6", + max_tokens=1024, + messages=[{ + "role": "user", + "content": [ + {"type": "text", "text": "Summarize the key findings in this report."}, + { + "type": "document", + "source": {"type": "file", "file_id": uploaded.id}, + "title": "Q4 Report", # optional + "citations": {"enabled": True} # optional, enables citations + } + ] + }], + betas=["files-api-2025-04-14"], +) +print(response.content[0].text) +``` + +### Image + +```python +image_file = client.beta.files.upload( + file=("photo.png", open("photo.png", "rb"), "image/png"), +) + +response = client.beta.messages.create( + model="claude-opus-4-6", + max_tokens=1024, + messages=[{ + "role": "user", + "content": [ + {"type": "text", "text": "What's in this image?"}, + { + "type": "image", + "source": {"type": "file", "file_id": image_file.id} + } + ] + }], + betas=["files-api-2025-04-14"], +) +``` + +--- + +## Manage Files + +### List Files + +```python +files = client.beta.files.list() +for f in files.data: + print(f"{f.id}: {f.filename} ({f.size_bytes} bytes)") +``` + +### Get File Metadata + +```python +file_info = client.beta.files.retrieve_metadata("file_011CNha8iCJcU1wXNR6q4V8w") +print(f"Filename: {file_info.filename}") +print(f"MIME type: {file_info.mime_type}") +``` + +### Delete a File + +```python +client.beta.files.delete("file_011CNha8iCJcU1wXNR6q4V8w") +``` + +### Download a File + +Only files created by the code execution tool or skills can be downloaded (not user-uploaded files). + +```python +file_content = client.beta.files.download("file_011CNha8iCJcU1wXNR6q4V8w") +file_content.write_to_file("output.txt") +``` + +--- + +## Full End-to-End Example + +Upload a document once, ask multiple questions about it: + +```python +import anthropic + +client = anthropic.Anthropic() + +# 1. Upload once +uploaded = client.beta.files.upload( + file=("contract.pdf", open("contract.pdf", "rb"), "application/pdf"), +) +print(f"Uploaded: {uploaded.id}") + +# 2. Ask multiple questions using the same file_id +questions = [ + "What are the key terms and conditions?", + "What is the termination clause?", + "Summarize the payment schedule.", +] + +for question in questions: + response = client.beta.messages.create( + model="claude-opus-4-6", + max_tokens=1024, + messages=[{ + "role": "user", + "content": [ + {"type": "text", "text": question}, + { + "type": "document", + "source": {"type": "file", "file_id": uploaded.id} + } + ] + }], + betas=["files-api-2025-04-14"], + ) + print(f"\nQ: {question}") + print(f"A: {response.content[0].text[:200]}") + +# 3. Clean up when done +client.beta.files.delete(uploaded.id) +``` diff --git a/skills/claude-api/python/claude-api/streaming.md b/skills/claude-api/python/claude-api/streaming.md new file mode 100644 index 00000000..bb2a84ef --- /dev/null +++ b/skills/claude-api/python/claude-api/streaming.md @@ -0,0 +1,162 @@ +# Streaming — Python + +## Quick Start + +```python +with client.messages.stream( + model="claude-opus-4-6", + max_tokens=1024, + messages=[{"role": "user", "content": "Write a story"}] +) as stream: + for text in stream.text_stream: + print(text, end="", flush=True) +``` + +### Async + +```python +async with async_client.messages.stream( + model="claude-opus-4-6", + max_tokens=1024, + messages=[{"role": "user", "content": "Write a story"}] +) as stream: + async for text in stream.text_stream: + print(text, end="", flush=True) +``` + +--- + +## Handling Different Content Types + +Claude may return text, thinking blocks, or tool use. Handle each appropriately: + +> **Opus 4.6:** Use `thinking: {type: "adaptive"}`. On older models, use `thinking: {type: "enabled", budget_tokens: N}` instead. + +```python +with client.messages.stream( + model="claude-opus-4-6", + max_tokens=16000, + thinking={"type": "adaptive"}, + messages=[{"role": "user", "content": "Analyze this problem"}] +) as stream: + for event in stream: + if event.type == "content_block_start": + if event.content_block.type == "thinking": + print("\n[Thinking...]") + elif event.content_block.type == "text": + print("\n[Response:]") + + elif event.type == "content_block_delta": + if event.delta.type == "thinking_delta": + print(event.delta.thinking, end="", flush=True) + elif event.delta.type == "text_delta": + print(event.delta.text, end="", flush=True) +``` + +--- + +## Streaming with Tool Use + +The Python tool runner currently returns complete messages. Use streaming for individual API calls within a manual loop if you need per-token streaming with tools: + +```python +with client.messages.stream( + model="claude-opus-4-6", + max_tokens=4096, + tools=tools, + messages=messages +) as stream: + for text in stream.text_stream: + print(text, end="", flush=True) + + response = stream.get_final_message() + # Continue with tool execution if response.stop_reason == "tool_use" +``` + +--- + +## Getting the Final Message + +```python +with client.messages.stream( + model="claude-opus-4-6", + max_tokens=1024, + messages=[{"role": "user", "content": "Hello"}] +) as stream: + for text in stream.text_stream: + print(text, end="", flush=True) + + # Get full message after streaming + final_message = stream.get_final_message() + print(f"\n\nTokens used: {final_message.usage.output_tokens}") +``` + +--- + +## Streaming with Progress Updates + +```python +def stream_with_progress(client, **kwargs): + """Stream a response with progress updates.""" + total_tokens = 0 + content_parts = [] + + with client.messages.stream(**kwargs) as stream: + for event in stream: + if event.type == "content_block_delta": + if event.delta.type == "text_delta": + text = event.delta.text + content_parts.append(text) + print(text, end="", flush=True) + + elif event.type == "message_delta": + if event.usage and event.usage.output_tokens is not None: + total_tokens = event.usage.output_tokens + + final_message = stream.get_final_message() + + print(f"\n\n[Tokens used: {total_tokens}]") + return "".join(content_parts) +``` + +--- + +## Error Handling in Streams + +```python +try: + with client.messages.stream( + model="claude-opus-4-6", + max_tokens=1024, + messages=[{"role": "user", "content": "Write a story"}] + ) as stream: + for text in stream.text_stream: + print(text, end="", flush=True) +except anthropic.APIConnectionError: + print("\nConnection lost. Please retry.") +except anthropic.RateLimitError: + print("\nRate limited. Please wait and retry.") +except anthropic.APIStatusError as e: + print(f"\nAPI error: {e.status_code}") +``` + +--- + +## Stream Event Types + +| Event Type | Description | When it fires | +| --------------------- | --------------------------- | --------------------------------- | +| `message_start` | Contains message metadata | Once at the beginning | +| `content_block_start` | New content block beginning | When a text/tool_use block starts | +| `content_block_delta` | Incremental content update | For each token/chunk | +| `content_block_stop` | Content block complete | When a block finishes | +| `message_delta` | Message-level updates | Contains `stop_reason`, usage | +| `message_stop` | Message complete | Once at the end | + +## Best Practices + +1. **Always flush output** — Use `flush=True` to show tokens immediately +2. **Handle partial responses** — If the stream is interrupted, you may have incomplete content +3. **Track token usage** — The `message_delta` event contains usage information +4. **Use timeouts** — Set appropriate timeouts for your application +5. **Default to streaming** — Use `.get_final_message()` to get the complete response even when streaming, giving you timeout protection without needing to handle individual events diff --git a/skills/claude-api/python/claude-api/tool-use.md b/skills/claude-api/python/claude-api/tool-use.md new file mode 100644 index 00000000..f347de5c --- /dev/null +++ b/skills/claude-api/python/claude-api/tool-use.md @@ -0,0 +1,587 @@ +# Tool Use — Python + +For conceptual overview (tool definitions, tool choice, tips), see [shared/tool-use-concepts.md](../../shared/tool-use-concepts.md). + +## Tool Runner (Recommended) + +**Beta:** The tool runner is in beta in the Python SDK. + +Use the `@beta_tool` decorator to define tools as typed functions, then pass them to `client.beta.messages.tool_runner()`: + +```python +import anthropic +from anthropic import beta_tool + +client = anthropic.Anthropic() + +@beta_tool +def get_weather(location: str, unit: str = "celsius") -> str: + """Get current weather for a location. + + Args: + location: City and state, e.g., San Francisco, CA. + unit: Temperature unit, either "celsius" or "fahrenheit". + """ + # Your implementation here + return f"72°F and sunny in {location}" + +# The tool runner handles the agentic loop automatically +runner = client.beta.messages.tool_runner( + model="claude-opus-4-6", + max_tokens=4096, + tools=[get_weather], + messages=[{"role": "user", "content": "What's the weather in Paris?"}], +) + +# Each iteration yields a BetaMessage; iteration stops when Claude is done +for message in runner: + print(message) +``` + +For async usage, use `@beta_async_tool` with `async def` functions. + +**Key benefits of the tool runner:** + +- No manual loop — the SDK handles calling tools and feeding results back +- Type-safe tool inputs via decorators +- Tool schemas are generated automatically from function signatures +- Iteration stops automatically when Claude has no more tool calls + +--- + +## MCP Tool Conversion Helpers + +**Beta.** Convert [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) tools, prompts, and resources to Anthropic API types for use with the tool runner. Requires `pip install anthropic[mcp]` (Python 3.10+). + +> **Note:** The Claude API also supports an `mcp_servers` parameter that lets Claude connect directly to remote MCP servers. Use these helpers instead when you need local MCP servers, prompts, resources, or more control over the MCP connection. + +### MCP Tools with Tool Runner + +```python +from anthropic import AsyncAnthropic +from anthropic.lib.tools.mcp import async_mcp_tool +from mcp import ClientSession +from mcp.client.stdio import stdio_client, StdioServerParameters + +client = AsyncAnthropic() + +async with stdio_client(StdioServerParameters(command="mcp-server")) as (read, write): + async with ClientSession(read, write) as mcp_client: + await mcp_client.initialize() + + tools_result = await mcp_client.list_tools() + runner = await client.beta.messages.tool_runner( + model="claude-opus-4-6", + max_tokens=1024, + messages=[{"role": "user", "content": "Use the available tools"}], + tools=[async_mcp_tool(t, mcp_client) for t in tools_result.tools], + ) + async for message in runner: + print(message) +``` + +For sync usage, use `mcp_tool` instead of `async_mcp_tool`. + +### MCP Prompts + +```python +from anthropic.lib.tools.mcp import mcp_message + +prompt = await mcp_client.get_prompt(name="my-prompt") +response = await client.beta.messages.create( + model="claude-opus-4-6", + max_tokens=1024, + messages=[mcp_message(m) for m in prompt.messages], +) +``` + +### MCP Resources as Content + +```python +from anthropic.lib.tools.mcp import mcp_resource_to_content + +resource = await mcp_client.read_resource(uri="file:///path/to/doc.txt") +response = await client.beta.messages.create( + model="claude-opus-4-6", + max_tokens=1024, + messages=[{ + "role": "user", + "content": [ + mcp_resource_to_content(resource), + {"type": "text", "text": "Summarize this document"}, + ], + }], +) +``` + +### Upload MCP Resources as Files + +```python +from anthropic.lib.tools.mcp import mcp_resource_to_file + +resource = await mcp_client.read_resource(uri="file:///path/to/data.json") +uploaded = await client.beta.files.upload(file=mcp_resource_to_file(resource)) +``` + +Conversion functions raise `UnsupportedMCPValueError` if an MCP value cannot be converted (e.g., unsupported content types like audio, unsupported MIME types). + +--- + +## Manual Agentic Loop + +Use this when you need fine-grained control over the loop (e.g., custom logging, conditional tool execution, human-in-the-loop approval): + +```python +import anthropic + +client = anthropic.Anthropic() +tools = [...] # Your tool definitions +messages = [{"role": "user", "content": user_input}] + +# Agentic loop: keep going until Claude stops calling tools +while True: + response = client.messages.create( + model="claude-opus-4-6", + max_tokens=4096, + tools=tools, + messages=messages + ) + + # If Claude is done (no more tool calls), break + if response.stop_reason == "end_turn": + break + + # Server-side tool hit iteration limit; re-send to continue + if response.stop_reason == "pause_turn": + messages = [ + {"role": "user", "content": user_input}, + {"role": "assistant", "content": response.content}, + ] + continue + + # Extract tool use blocks from the response + tool_use_blocks = [b for b in response.content if b.type == "tool_use"] + + # Append assistant's response (including tool_use blocks) + messages.append({"role": "assistant", "content": response.content}) + + # Execute each tool and collect results + tool_results = [] + for tool in tool_use_blocks: + result = execute_tool(tool.name, tool.input) # Your implementation + tool_results.append({ + "type": "tool_result", + "tool_use_id": tool.id, # Must match the tool_use block's id + "content": result + }) + + # Append tool results as a user message + messages.append({"role": "user", "content": tool_results}) + +# Final response text +final_text = next(b.text for b in response.content if b.type == "text") +``` + +--- + +## Handling Tool Results + +```python +response = client.messages.create( + model="claude-opus-4-6", + max_tokens=1024, + tools=tools, + messages=[{"role": "user", "content": "What's the weather in Paris?"}] +) + +for block in response.content: + if block.type == "tool_use": + tool_name = block.name + tool_input = block.input + tool_use_id = block.id + + result = execute_tool(tool_name, tool_input) + + followup = client.messages.create( + model="claude-opus-4-6", + max_tokens=1024, + tools=tools, + messages=[ + {"role": "user", "content": "What's the weather in Paris?"}, + {"role": "assistant", "content": response.content}, + { + "role": "user", + "content": [{ + "type": "tool_result", + "tool_use_id": tool_use_id, + "content": result + }] + } + ] + ) +``` + +--- + +## Multiple Tool Calls + +```python +tool_results = [] + +for block in response.content: + if block.type == "tool_use": + result = execute_tool(block.name, block.input) + tool_results.append({ + "type": "tool_result", + "tool_use_id": block.id, + "content": result + }) + +# Send all results back at once +if tool_results: + followup = client.messages.create( + model="claude-opus-4-6", + max_tokens=1024, + tools=tools, + messages=[ + *previous_messages, + {"role": "assistant", "content": response.content}, + {"role": "user", "content": tool_results} + ] + ) +``` + +--- + +## Error Handling in Tool Results + +```python +tool_result = { + "type": "tool_result", + "tool_use_id": tool_use_id, + "content": "Error: Location 'xyz' not found. Please provide a valid city name.", + "is_error": True +} +``` + +--- + +## Tool Choice + +```python +response = client.messages.create( + model="claude-opus-4-6", + max_tokens=1024, + tools=tools, + tool_choice={"type": "tool", "name": "get_weather"}, # Force specific tool + messages=[{"role": "user", "content": "What's the weather in Paris?"}] +) +``` + +--- + +## Code Execution + +### Basic Usage + +```python +import anthropic + +client = anthropic.Anthropic() + +response = client.messages.create( + model="claude-opus-4-6", + max_tokens=4096, + messages=[{ + "role": "user", + "content": "Calculate the mean and standard deviation of [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]" + }], + tools=[{ + "type": "code_execution_20260120", + "name": "code_execution" + }] +) + +for block in response.content: + if block.type == "text": + print(block.text) + elif block.type == "bash_code_execution_tool_result": + print(f"stdout: {block.content.stdout}") +``` + +### Upload Files for Analysis + +```python +# 1. Upload a file +uploaded = client.beta.files.upload(file=open("sales_data.csv", "rb")) + +# 2. Pass to code execution via container_upload block +# Code execution is GA; Files API is still beta (pass via extra_headers) +response = client.messages.create( + model="claude-opus-4-6", + max_tokens=4096, + extra_headers={"anthropic-beta": "files-api-2025-04-14"}, + messages=[{ + "role": "user", + "content": [ + {"type": "text", "text": "Analyze this sales data. Show trends and create a visualization."}, + {"type": "container_upload", "file_id": uploaded.id} + ] + }], + tools=[{"type": "code_execution_20260120", "name": "code_execution"}] +) +``` + +### Retrieve Generated Files + +```python +import os + +OUTPUT_DIR = "./claude_outputs" +os.makedirs(OUTPUT_DIR, exist_ok=True) + +for block in response.content: + if block.type == "bash_code_execution_tool_result": + result = block.content + if result.type == "bash_code_execution_result" and result.content: + for file_ref in result.content: + if file_ref.type == "bash_code_execution_output": + metadata = client.beta.files.retrieve_metadata(file_ref.file_id) + file_content = client.beta.files.download(file_ref.file_id) + # Use basename to prevent path traversal; validate result + safe_name = os.path.basename(metadata.filename) + if not safe_name or safe_name in (".", ".."): + print(f"Skipping invalid filename: {metadata.filename}") + continue + output_path = os.path.join(OUTPUT_DIR, safe_name) + file_content.write_to_file(output_path) + print(f"Saved: {output_path}") +``` + +### Container Reuse + +```python +# First request: set up environment +response1 = client.messages.create( + model="claude-opus-4-6", + max_tokens=4096, + messages=[{"role": "user", "content": "Install tabulate and create data.json with sample data"}], + tools=[{"type": "code_execution_20260120", "name": "code_execution"}] +) + +# Get container ID from response +container_id = response1.container.id + +# Second request: reuse the same container +response2 = client.messages.create( + container=container_id, + model="claude-opus-4-6", + max_tokens=4096, + messages=[{"role": "user", "content": "Read data.json and display as a formatted table"}], + tools=[{"type": "code_execution_20260120", "name": "code_execution"}] +) +``` + +### Response Structure + +```python +for block in response.content: + if block.type == "text": + print(block.text) # Claude's explanation + elif block.type == "server_tool_use": + print(f"Running: {block.name} - {block.input}") # What Claude is doing + elif block.type == "bash_code_execution_tool_result": + result = block.content + if result.type == "bash_code_execution_result": + if result.return_code == 0: + print(f"Output: {result.stdout}") + else: + print(f"Error: {result.stderr}") + else: + print(f"Tool error: {result.error_code}") + elif block.type == "text_editor_code_execution_tool_result": + print(f"File operation: {block.content}") +``` + +--- + +## Memory Tool + +### Basic Usage + +```python +import anthropic + +client = anthropic.Anthropic() + +response = client.messages.create( + model="claude-opus-4-6", + max_tokens=2048, + messages=[{"role": "user", "content": "Remember that my preferred language is Python."}], + tools=[{"type": "memory_20250818", "name": "memory"}], +) +``` + +### SDK Memory Helper + +Subclass `BetaAbstractMemoryTool`: + +```python +from anthropic.lib.tools import BetaAbstractMemoryTool + +class MyMemoryTool(BetaAbstractMemoryTool): + def view(self, command): ... + def create(self, command): ... + def str_replace(self, command): ... + def insert(self, command): ... + def delete(self, command): ... + def rename(self, command): ... + +memory = MyMemoryTool() + +# Use with tool runner +runner = client.beta.messages.tool_runner( + model="claude-opus-4-6", + max_tokens=2048, + tools=[memory], + messages=[{"role": "user", "content": "Remember my preferences"}], +) + +for message in runner: + print(message) +``` + +For full implementation examples, use WebFetch: + +- `https://github.com/anthropics/anthropic-sdk-python/blob/main/examples/memory/basic.py` + +--- + +## Structured Outputs + +### JSON Outputs (Pydantic — Recommended) + +```python +from pydantic import BaseModel +from typing import List +import anthropic + +class ContactInfo(BaseModel): + name: str + email: str + plan: str + interests: List[str] + demo_requested: bool + +client = anthropic.Anthropic() + +response = client.messages.parse( + model="claude-opus-4-6", + max_tokens=1024, + messages=[{ + "role": "user", + "content": "Extract: Jane Doe (jane@co.com) wants Enterprise, interested in API and SDKs, wants a demo." + }], + output_format=ContactInfo, +) + +# response.parsed_output is a validated ContactInfo instance +contact = response.parsed_output +print(contact.name) # "Jane Doe" +print(contact.interests) # ["API", "SDKs"] +``` + +### Raw Schema + +```python +response = client.messages.create( + model="claude-opus-4-6", + max_tokens=1024, + messages=[{ + "role": "user", + "content": "Extract info: John Smith (john@example.com) wants the Enterprise plan." + }], + output_config={ + "format": { + "type": "json_schema", + "schema": { + "type": "object", + "properties": { + "name": {"type": "string"}, + "email": {"type": "string"}, + "plan": {"type": "string"}, + "demo_requested": {"type": "boolean"} + }, + "required": ["name", "email", "plan", "demo_requested"], + "additionalProperties": False + } + } + } +) + +import json +data = json.loads(response.content[0].text) +``` + +### Strict Tool Use + +```python +response = client.messages.create( + model="claude-opus-4-6", + max_tokens=1024, + messages=[{"role": "user", "content": "Book a flight to Tokyo for 2 passengers on March 15"}], + tools=[{ + "name": "book_flight", + "description": "Book a flight to a destination", + "strict": True, + "input_schema": { + "type": "object", + "properties": { + "destination": {"type": "string"}, + "date": {"type": "string", "format": "date"}, + "passengers": {"type": "integer", "enum": [1, 2, 3, 4, 5, 6, 7, 8]} + }, + "required": ["destination", "date", "passengers"], + "additionalProperties": False + } + }] +) +``` + +### Using Both Together + +```python +response = client.messages.create( + model="claude-opus-4-6", + max_tokens=1024, + messages=[{"role": "user", "content": "Plan a trip to Paris next month"}], + output_config={ + "format": { + "type": "json_schema", + "schema": { + "type": "object", + "properties": { + "summary": {"type": "string"}, + "next_steps": {"type": "array", "items": {"type": "string"}} + }, + "required": ["summary", "next_steps"], + "additionalProperties": False + } + } + }, + tools=[{ + "name": "search_flights", + "description": "Search for available flights", + "strict": True, + "input_schema": { + "type": "object", + "properties": { + "destination": {"type": "string"}, + "date": {"type": "string", "format": "date"} + }, + "required": ["destination", "date"], + "additionalProperties": False + } + }] +) +``` diff --git a/skills/claude-api/ruby/claude-api.md b/skills/claude-api/ruby/claude-api.md new file mode 100644 index 00000000..912bc181 --- /dev/null +++ b/skills/claude-api/ruby/claude-api.md @@ -0,0 +1,87 @@ +# Claude API — Ruby + +> **Note:** The Ruby SDK supports the Claude API. A tool runner is available in beta via `client.beta.messages.tool_runner()`. Agent SDK is not yet available for Ruby. + +## Installation + +```bash +gem install anthropic +``` + +## Client Initialization + +```ruby +require "anthropic" + +# Default (uses ANTHROPIC_API_KEY env var) +client = Anthropic::Client.new + +# Explicit API key +client = Anthropic::Client.new(api_key: "your-api-key") +``` + +--- + +## Basic Message Request + +```ruby +message = client.messages.create( + model: :"claude-opus-4-6", + max_tokens: 1024, + messages: [ + { role: "user", content: "What is the capital of France?" } + ] +) +puts message.content.first.text +``` + +--- + +## Streaming + +```ruby +stream = client.messages.stream( + model: :"claude-opus-4-6", + max_tokens: 1024, + messages: [{ role: "user", content: "Write a haiku" }] +) + +stream.text.each { |text| print(text) } +``` + +--- + +## Tool Use + +The Ruby SDK supports tool use via raw JSON schema definitions and also provides a beta tool runner for automatic tool execution. + +### Tool Runner (Beta) + +```ruby +class GetWeatherInput < Anthropic::BaseModel + required :location, String, doc: "City and state, e.g. San Francisco, CA" +end + +class GetWeather < Anthropic::BaseTool + doc "Get the current weather for a location" + + input_schema GetWeatherInput + + def call(input) + "The weather in #{input.location} is sunny and 72°F." + end +end + +client.beta.messages.tool_runner( + model: :"claude-opus-4-6", + max_tokens: 1024, + tools: [GetWeather.new], + messages: [{ role: "user", content: "What's the weather in San Francisco?" }] +).each_message do |message| + puts message.content +end +``` + +### Manual Loop + +See the [shared tool use concepts](../shared/tool-use-concepts.md) for the tool definition format and agentic loop pattern. diff --git a/skills/claude-api/shared/error-codes.md b/skills/claude-api/shared/error-codes.md new file mode 100644 index 00000000..9f207bab --- /dev/null +++ b/skills/claude-api/shared/error-codes.md @@ -0,0 +1,205 @@ +# HTTP Error Codes Reference + +This file documents HTTP error codes returned by the Claude API, their common causes, and how to handle them. For language-specific error handling examples, see the `python/` or `typescript/` folders. + +## Error Code Summary + +| Code | Error Type | Retryable | Common Cause | +| ---- | ----------------------- | --------- | ------------------------------------ | +| 400 | `invalid_request_error` | No | Invalid request format or parameters | +| 401 | `authentication_error` | No | Invalid or missing API key | +| 403 | `permission_error` | No | API key lacks permission | +| 404 | `not_found_error` | No | Invalid endpoint or model ID | +| 413 | `request_too_large` | No | Request exceeds size limits | +| 429 | `rate_limit_error` | Yes | Too many requests | +| 500 | `api_error` | Yes | Anthropic service issue | +| 529 | `overloaded_error` | Yes | API is temporarily overloaded | + +## Detailed Error Information + +### 400 Bad Request + +**Causes:** + +- Malformed JSON in request body +- Missing required parameters (`model`, `max_tokens`, `messages`) +- Invalid parameter types (e.g., string where integer expected) +- Empty messages array +- Messages not alternating user/assistant + +**Example error:** + +```json +{ + "type": "error", + "error": { + "type": "invalid_request_error", + "message": "messages: roles must alternate between \"user\" and \"assistant\"" + } +} +``` + +**Fix:** Validate request structure before sending. Check that: + +- `model` is a valid model ID +- `max_tokens` is a positive integer +- `messages` array is non-empty and alternates correctly + +--- + +### 401 Unauthorized + +**Causes:** + +- Missing `x-api-key` header or `Authorization` header +- Invalid API key format +- Revoked or deleted API key + +**Fix:** Ensure `ANTHROPIC_API_KEY` environment variable is set correctly. + +--- + +### 403 Forbidden + +**Causes:** + +- API key doesn't have access to the requested model +- Organization-level restrictions +- Attempting to access beta features without beta access + +**Fix:** Check your API key permissions in the Console. You may need a different API key or to request access to specific features. + +--- + +### 404 Not Found + +**Causes:** + +- Typo in model ID (e.g., `claude-sonnet-4.6` instead of `claude-sonnet-4-6`) +- Using deprecated model ID +- Invalid API endpoint + +**Fix:** Use exact model IDs from the models documentation. You can use aliases (e.g., `claude-opus-4-6`). + +--- + +### 413 Request Too Large + +**Causes:** + +- Request body exceeds maximum size +- Too many tokens in input +- Image data too large + +**Fix:** Reduce input size — truncate conversation history, compress/resize images, or split large documents into chunks. + +--- + +### 400 Validation Errors + +Some 400 errors are specifically related to parameter validation: + +- `max_tokens` exceeds model's limit +- Invalid `temperature` value (must be 0.0-1.0) +- `budget_tokens` >= `max_tokens` in extended thinking +- Invalid tool definition schema + +**Common mistake with extended thinking:** + +``` +# Wrong: budget_tokens must be < max_tokens +thinking: budget_tokens=10000, max_tokens=1000 → Error! + +# Correct +thinking: budget_tokens=10000, max_tokens=16000 +``` + +--- + +### 429 Rate Limited + +**Causes:** + +- Exceeded requests per minute (RPM) +- Exceeded tokens per minute (TPM) +- Exceeded tokens per day (TPD) + +**Headers to check:** + +- `retry-after`: Seconds to wait before retrying +- `x-ratelimit-limit-*`: Your limits +- `x-ratelimit-remaining-*`: Remaining quota + +**Fix:** The Anthropic SDKs automatically retry 429 and 5xx errors with exponential backoff (default: `max_retries=2`). For custom retry behavior, see the language-specific error handling examples. + +--- + +### 500 Internal Server Error + +**Causes:** + +- Temporary Anthropic service issue +- Bug in API processing + +**Fix:** Retry with exponential backoff. If persistent, check [status.anthropic.com](https://status.anthropic.com). + +--- + +### 529 Overloaded + +**Causes:** + +- High API demand +- Service capacity reached + +**Fix:** Retry with exponential backoff. Consider using a different model (Haiku is often less loaded), spreading requests over time, or implementing request queuing. + +--- + +## Common Mistakes and Fixes + +| Mistake | Error | Fix | +| ------------------------------- | ---------------- | ------------------------------------------------------- | +| `budget_tokens` >= `max_tokens` | 400 | Ensure `budget_tokens` < `max_tokens` | +| Typo in model ID | 404 | Use valid model ID like `claude-opus-4-6` | +| First message is `assistant` | 400 | First message must be `user` | +| Consecutive same-role messages | 400 | Alternate `user` and `assistant` | +| API key in code | 401 (leaked key) | Use environment variable | +| Custom retry needs | 429/5xx | SDK retries automatically; customize with `max_retries` | + +## Typed Exceptions in SDKs + +**Always use the SDK's typed exception classes** instead of checking error messages with string matching. Each HTTP error code maps to a specific exception class: + +| HTTP Code | TypeScript Class | Python Class | +| --------- | --------------------------------- | --------------------------------- | +| 400 | `Anthropic.BadRequestError` | `anthropic.BadRequestError` | +| 401 | `Anthropic.AuthenticationError` | `anthropic.AuthenticationError` | +| 403 | `Anthropic.PermissionDeniedError` | `anthropic.PermissionDeniedError` | +| 404 | `Anthropic.NotFoundError` | `anthropic.NotFoundError` | +| 429 | `Anthropic.RateLimitError` | `anthropic.RateLimitError` | +| 500+ | `Anthropic.InternalServerError` | `anthropic.InternalServerError` | +| Any | `Anthropic.APIError` | `anthropic.APIError` | + +```typescript +// ✅ Correct: use typed exceptions +try { + const response = await client.messages.create({...}); +} catch (error) { + if (error instanceof Anthropic.RateLimitError) { + // Handle rate limiting + } else if (error instanceof Anthropic.APIError) { + console.error(`API error ${error.status}:`, error.message); + } +} + +// ❌ Wrong: don't check error messages with string matching +try { + const response = await client.messages.create({...}); +} catch (error) { + const msg = error instanceof Error ? error.message : String(error); + if (msg.includes("429") || msg.includes("rate_limit")) { ... } +} +``` + +All exception classes extend `Anthropic.APIError`, which has a `status` property. Use `instanceof` checks from most specific to least specific (e.g., check `RateLimitError` before `APIError`). diff --git a/skills/claude-api/shared/live-sources.md b/skills/claude-api/shared/live-sources.md new file mode 100644 index 00000000..0b9ebedb --- /dev/null +++ b/skills/claude-api/shared/live-sources.md @@ -0,0 +1,121 @@ +# Live Documentation Sources + +This file contains WebFetch URLs for fetching current information from platform.claude.com and Agent SDK repositories. Use these when users need the latest data that may have changed since the cached content was last updated. + +## When to Use WebFetch + +- User explicitly asks for "latest" or "current" information +- Cached data seems incorrect +- User asks about features not covered in cached content +- User needs specific API details or examples + +## Claude API Documentation URLs + +### Models & Pricing + +| Topic | URL | Extraction Prompt | +| --------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------- | +| Models Overview | `https://platform.claude.com/docs/en/about-claude/models/overview.md` | "Extract current model IDs, context windows, and pricing for all Claude models" | +| Pricing | `https://platform.claude.com/docs/en/pricing.md` | "Extract current pricing per million tokens for input and output" | + +### Core Features + +| Topic | URL | Extraction Prompt | +| ----------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | +| Extended Thinking | `https://platform.claude.com/docs/en/build-with-claude/extended-thinking.md` | "Extract extended thinking parameters, budget_tokens requirements, and usage examples" | +| Adaptive Thinking | `https://platform.claude.com/docs/en/build-with-claude/adaptive-thinking.md` | "Extract adaptive thinking setup, effort levels, and Claude Opus 4.6 usage examples" | +| Effort Parameter | `https://platform.claude.com/docs/en/build-with-claude/effort.md` | "Extract effort levels, cost-quality tradeoffs, and interaction with thinking" | +| Tool Use | `https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview.md` | "Extract tool definition schema, tool_choice options, and handling tool results" | +| Streaming | `https://platform.claude.com/docs/en/build-with-claude/streaming.md` | "Extract streaming event types, SDK examples, and best practices" | +| Prompt Caching | `https://platform.claude.com/docs/en/build-with-claude/prompt-caching.md` | "Extract cache_control usage, pricing benefits, and implementation examples" | + +### Media & Files + +| Topic | URL | Extraction Prompt | +| ----------- | ---------------------------------------------------------------------- | ----------------------------------------------------------------- | +| Vision | `https://platform.claude.com/docs/en/build-with-claude/vision.md` | "Extract supported image formats, size limits, and code examples" | +| PDF Support | `https://platform.claude.com/docs/en/build-with-claude/pdf-support.md` | "Extract PDF handling capabilities, limits, and examples" | + +### API Operations + +| Topic | URL | Extraction Prompt | +| ---------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | +| Batch Processing | `https://platform.claude.com/docs/en/build-with-claude/batch-processing.md` | "Extract batch API endpoints, request format, and polling for results" | +| Files API | `https://platform.claude.com/docs/en/build-with-claude/files.md` | "Extract file upload, download, and referencing in messages, including supported types and beta header" | +| Token Counting | `https://platform.claude.com/docs/en/build-with-claude/token-counting.md` | "Extract token counting API usage and examples" | +| Rate Limits | `https://platform.claude.com/docs/en/api/rate-limits.md` | "Extract current rate limits by tier and model" | +| Errors | `https://platform.claude.com/docs/en/api/errors.md` | "Extract HTTP error codes, meanings, and retry guidance" | + +### Tools + +| Topic | URL | Extraction Prompt | +| -------------- | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | +| Code Execution | `https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool.md` | "Extract code execution tool setup, file upload, container reuse, and response handling" | +| Computer Use | `https://platform.claude.com/docs/en/agents-and-tools/tool-use/computer-use.md` | "Extract computer use tool setup, capabilities, and implementation examples" | + +### Advanced Features + +| Topic | URL | Extraction Prompt | +| ------------------ | ----------------------------------------------------------------------------- | --------------------------------------------------- | +| Structured Outputs | `https://platform.claude.com/docs/en/build-with-claude/structured-outputs.md` | "Extract output_config.format usage and schema enforcement" | +| Compaction | `https://platform.claude.com/docs/en/build-with-claude/compaction.md` | "Extract compaction setup, trigger config, and streaming with compaction" | +| Citations | `https://platform.claude.com/docs/en/build-with-claude/citations.md` | "Extract citation format and implementation" | +| Context Windows | `https://platform.claude.com/docs/en/build-with-claude/context-windows.md` | "Extract context window sizes and token management" | + +--- + +## Claude API SDK Repositories + +| SDK | URL | Description | +| ---------- | --------------------------------------------------------- | ------------------------------ | +| Python | `https://github.com/anthropics/anthropic-sdk-python` | `anthropic` pip package source | +| TypeScript | `https://github.com/anthropics/anthropic-sdk-typescript` | `@anthropic-ai/sdk` npm source | +| Java | `https://github.com/anthropics/anthropic-sdk-java` | `anthropic-java` Maven source | +| Go | `https://github.com/anthropics/anthropic-sdk-go` | Go module source | +| Ruby | `https://github.com/anthropics/anthropic-sdk-ruby` | `anthropic` gem source | +| C# | `https://github.com/anthropics/anthropic-sdk-csharp` | NuGet package source | +| PHP | `https://github.com/anthropics/anthropic-sdk-php` | Composer package source | + +--- + +## Agent SDK Documentation URLs + +### Core Documentation + +| Topic | URL | Extraction Prompt | +| -------------------- | ----------------------------------------------------------- | --------------------------------------------------------------- | +| Agent SDK Overview | `https://platform.claude.com/docs/en/agent-sdk.md` | "Extract the Agent SDK overview, key features, and use cases" | +| Agent SDK Python | `https://github.com/anthropics/claude-agent-sdk-python` | "Extract Python SDK installation, imports, and basic usage" | +| Agent SDK TypeScript | `https://github.com/anthropics/claude-agent-sdk-typescript` | "Extract TypeScript SDK installation, imports, and basic usage" | + +### SDK Reference (GitHub READMEs) + +| Topic | URL | Extraction Prompt | +| -------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------ | +| Python SDK | `https://raw.githubusercontent.com/anthropics/claude-agent-sdk-python/main/README.md` | "Extract Python SDK API reference, classes, and methods" | +| TypeScript SDK | `https://raw.githubusercontent.com/anthropics/claude-agent-sdk-typescript/main/README.md` | "Extract TypeScript SDK API reference, types, and functions" | + +### npm/PyPI Packages + +| Package | URL | Description | +| ----------------------------------- | -------------------------------------------------------------- | ------------------------- | +| claude-agent-sdk (Python) | `https://pypi.org/project/claude-agent-sdk/` | Python package on PyPI | +| @anthropic-ai/claude-agent-sdk (TS) | `https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk` | TypeScript package on npm | + +### GitHub Repositories + +| Resource | URL | Description | +| -------------- | ----------------------------------------------------------- | ----------------------------------- | +| Python SDK | `https://github.com/anthropics/claude-agent-sdk-python` | Python package source | +| TypeScript SDK | `https://github.com/anthropics/claude-agent-sdk-typescript` | TypeScript/Node.js package source | +| MCP Servers | `https://github.com/modelcontextprotocol` | Official MCP server implementations | + +--- + +## Fallback Strategy + +If WebFetch fails (network issues, URL changed): + +1. Use cached content from the language-specific files (note the cache date) +2. Inform user the data may be outdated +3. Suggest they check platform.claude.com or the GitHub repos directly diff --git a/skills/claude-api/shared/models.md b/skills/claude-api/shared/models.md new file mode 100644 index 00000000..24d00853 --- /dev/null +++ b/skills/claude-api/shared/models.md @@ -0,0 +1,68 @@ +# Claude Model Catalog + +**Only use exact model IDs listed in this file.** Never guess or construct model IDs — incorrect IDs will cause API errors. Use aliases wherever available. For the latest information, WebFetch the Models Overview URL in `shared/live-sources.md`. + +## Current Models (recommended) + +| Friendly Name | Alias (use this) | Full ID | Context | Max Output | Status | +|-------------------|---------------------|-------------------------------|----------------|------------|--------| +| Claude Opus 4.6 | `claude-opus-4-6` | — | 200K (1M beta) | 128K | Active | +| Claude Sonnet 4.6 | `claude-sonnet-4-6` | - | 200K (1M beta) | 64K | Active | +| Claude Haiku 4.5 | `claude-haiku-4-5` | `claude-haiku-4-5-20251001` | 200K | 64K | Active | + +### Model Descriptions + +- **Claude Opus 4.6** — Our most intelligent model for building agents and coding. Supports adaptive thinking (recommended), 128K max output tokens (requires streaming for large outputs). 1M context window available in beta via `context-1m-2025-08-07` header. +- **Claude Sonnet 4.6** — Our best combination of speed and intelligence. Supports adaptive thinking (recommended). 1M context window available in beta via `context-1m-2025-08-07` header. 64K max output tokens. +- **Claude Haiku 4.5** — Fastest and most cost-effective model for simple tasks. + +## Legacy Models (still active) + +| Friendly Name | Alias (use this) | Full ID | Status | +|-------------------|---------------------|-------------------------------|--------| +| Claude Opus 4.5 | `claude-opus-4-5` | `claude-opus-4-5-20251101` | Active | +| Claude Opus 4.1 | `claude-opus-4-1` | `claude-opus-4-1-20250805` | Active | +| Claude Sonnet 4.5 | `claude-sonnet-4-5` | `claude-sonnet-4-5-20250929` | Active | +| Claude Sonnet 4 | `claude-sonnet-4-0` | `claude-sonnet-4-20250514` | Active | +| Claude Opus 4 | `claude-opus-4-0` | `claude-opus-4-20250514` | Active | + +## Deprecated Models (retiring soon) + +| Friendly Name | Alias (use this) | Full ID | Status | +|-------------------|---------------------|-------------------------------|------------| +| Claude Haiku 3 | — | `claude-3-haiku-20240307` | Deprecated | + +## Retired Models (no longer available) + +| Friendly Name | Full ID | Retired | +|-------------------|-------------------------------|-------------| +| Claude Sonnet 3.7 | `claude-3-7-sonnet-20250219` | Feb 19, 2026 | +| Claude Haiku 3.5 | `claude-3-5-haiku-20241022` | Feb 19, 2026 | +| Claude Opus 3 | `claude-3-opus-20240229` | Jan 5, 2026 | +| Claude Sonnet 3.5 | `claude-3-5-sonnet-20241022` | Oct 28, 2025 | +| Claude Sonnet 3.5 | `claude-3-5-sonnet-20240620` | Oct 28, 2025 | +| Claude Sonnet 3 | `claude-3-sonnet-20240229` | Jul 21, 2025 | +| Claude 2.1 | `claude-2.1` | Jul 21, 2025 | +| Claude 2.0 | `claude-2.0` | Jul 21, 2025 | + +## Resolving User Requests + +When a user asks for a model by name, use this table to find the correct model ID: + +| User says... | Use this model ID | +|-------------------------------------------|--------------------------------| +| "opus", "most powerful" | `claude-opus-4-6` | +| "opus 4.6" | `claude-opus-4-6` | +| "opus 4.5" | `claude-opus-4-5` | +| "opus 4.1" | `claude-opus-4-1` | +| "opus 4", "opus 4.0" | `claude-opus-4-0` | +| "sonnet", "balanced" | `claude-sonnet-4-6` | +| "sonnet 4.6" | `claude-sonnet-4-6` | +| "sonnet 4.5" | `claude-sonnet-4-5` | +| "sonnet 4", "sonnet 4.0" | `claude-sonnet-4-0` | +| "sonnet 3.7" | Retired — suggest `claude-sonnet-4-5` | +| "sonnet 3.5" | Retired — suggest `claude-sonnet-4-5` | +| "haiku", "fast", "cheap" | `claude-haiku-4-5` | +| "haiku 4.5" | `claude-haiku-4-5` | +| "haiku 3.5" | Retired — suggest `claude-haiku-4-5` | +| "haiku 3" | Deprecated — suggest `claude-haiku-4-5` | diff --git a/skills/claude-api/shared/tool-use-concepts.md b/skills/claude-api/shared/tool-use-concepts.md new file mode 100644 index 00000000..2a1b84e1 --- /dev/null +++ b/skills/claude-api/shared/tool-use-concepts.md @@ -0,0 +1,305 @@ +# Tool Use Concepts + +This file covers the conceptual foundations of tool use with the Claude API. For language-specific code examples, see the `python/`, `typescript/`, or other language folders. + +## User-Defined Tools + +### Tool Definition Structure + +> **Note:** When using the Tool Runner (beta), tool schemas are generated automatically from your function signatures (Python), Zod schemas (TypeScript), annotated classes (Java), `jsonschema` struct tags (Go), or `BaseTool` subclasses (Ruby). The raw JSON schema format below is for the manual approach or SDKs without tool runner support. + +Each tool requires a name, description, and JSON Schema for its inputs: + +```json +{ + "name": "get_weather", + "description": "Get current weather for a location", + "input_schema": { + "type": "object", + "properties": { + "location": { + "type": "string", + "description": "City and state, e.g., San Francisco, CA" + }, + "unit": { + "type": "string", + "enum": ["celsius", "fahrenheit"], + "description": "Temperature unit" + } + }, + "required": ["location"] + } +} +``` + +**Best practices for tool definitions:** + +- Use clear, descriptive names (e.g., `get_weather`, `search_database`, `send_email`) +- Write detailed descriptions — Claude uses these to decide when to use the tool +- Include descriptions for each property +- Use `enum` for parameters with a fixed set of values +- Mark truly required parameters in `required`; make others optional with defaults + +--- + +### Tool Choice Options + +Control when Claude uses tools: + +| Value | Behavior | +| --------------------------------- | --------------------------------------------- | +| `{"type": "auto"}` | Claude decides whether to use tools (default) | +| `{"type": "any"}` | Claude must use at least one tool | +| `{"type": "tool", "name": "..."}` | Claude must use the specified tool | +| `{"type": "none"}` | Claude cannot use tools | + +Any `tool_choice` value can also include `"disable_parallel_tool_use": true` to force Claude to use at most one tool per response. By default, Claude may request multiple tool calls in a single response. + +--- + +### Tool Runner vs Manual Loop + +**Tool Runner (Recommended):** The SDK's tool runner handles the agentic loop automatically — it calls the API, detects tool use requests, executes your tool functions, feeds results back to Claude, and repeats until Claude stops calling tools. Available in Python, TypeScript, Java, Go, and Ruby SDKs (beta). The Python SDK also provides MCP conversion helpers (`anthropic.lib.tools.mcp`) to convert MCP tools, prompts, and resources for use with the tool runner — see `python/claude-api/tool-use.md` for details. + +**Manual Agentic Loop:** Use when you need fine-grained control over the loop (e.g., custom logging, conditional tool execution, human-in-the-loop approval). Loop until `stop_reason == "end_turn"`, always append the full `response.content` to preserve tool_use blocks, and ensure each `tool_result` includes the matching `tool_use_id`. + +**Stop reasons for server-side tools:** When using server-side tools (code execution, web search, etc.), the API runs a server-side sampling loop. If this loop reaches its default limit of 10 iterations, the response will have `stop_reason: "pause_turn"`. To continue, re-send the user message and assistant response and make another API request — the server will resume where it left off. Do NOT add an extra user message like "Continue." — the API detects the trailing `server_tool_use` block and knows to resume automatically. + +```python +# Handle pause_turn in your agentic loop +if response.stop_reason == "pause_turn": + messages = [ + {"role": "user", "content": user_query}, + {"role": "assistant", "content": response.content}, + ] + # Make another API request — server resumes automatically + response = client.messages.create( + model="claude-opus-4-6", messages=messages, tools=tools + ) +``` + +Set a `max_continuations` limit (e.g., 5) to prevent infinite loops. For the full guide, see: `https://platform.claude.com/docs/en/build-with-claude/handling-stop-reasons` + +> **Security:** The tool runner executes your tool functions automatically whenever Claude requests them. For tools with side effects (sending emails, modifying databases, financial transactions), validate inputs within your tool functions and consider requiring confirmation for destructive operations. Use the manual agentic loop if you need human-in-the-loop approval before each tool execution. + +--- + +### Handling Tool Results + +When Claude uses a tool, the response contains a `tool_use` block. You must: + +1. Execute the tool with the provided input +2. Send the result back in a `tool_result` message +3. Continue the conversation + +**Error handling in tool results:** When a tool execution fails, set `"is_error": true` and provide an informative error message. Claude will typically acknowledge the error and either try a different approach or ask for clarification. + +**Multiple tool calls:** Claude can request multiple tools in a single response. Handle them all before continuing — send all results back in a single `user` message. + +--- + +## Server-Side Tools: Code Execution + +The code execution tool lets Claude run code in a secure, sandboxed container. Unlike user-defined tools, server-side tools run on Anthropic's infrastructure — you don't execute anything client-side. Just include the tool definition and Claude handles the rest. + +### Key Facts + +- Runs in an isolated container (1 CPU, 5 GiB RAM, 5 GiB disk) +- No internet access (fully sandboxed) +- Python 3.11 with data science libraries pre-installed +- Containers persist for 30 days and can be reused across requests +- Free when used with web search/web fetch tools; otherwise $0.05/hour after 1,550 free hours/month per organization + +### Tool Definition + +The tool requires no schema — just declare it in the `tools` array: + +```json +{ + "type": "code_execution_20260120", + "name": "code_execution" +} +``` + +Claude automatically gains access to `bash_code_execution` (run shell commands) and `text_editor_code_execution` (create/view/edit files). + +### Pre-installed Python Libraries + +- **Data science**: pandas, numpy, scipy, scikit-learn, statsmodels +- **Visualization**: matplotlib, seaborn +- **File processing**: openpyxl, xlsxwriter, pillow, pypdf, pdfplumber, python-docx, python-pptx +- **Math**: sympy, mpmath +- **Utilities**: tqdm, python-dateutil, pytz, sqlite3 + +Additional packages can be installed at runtime via `pip install`. + +### Supported File Types for Upload + +| Type | Extensions | +| ------ | ---------------------------------- | +| Data | CSV, Excel (.xlsx/.xls), JSON, XML | +| Images | JPEG, PNG, GIF, WebP | +| Text | .txt, .md, .py, .js, etc. | + +### Container Reuse + +Reuse containers across requests to maintain state (files, installed packages, variables). Extract the `container_id` from the first response and pass it to subsequent requests. + +### Response Structure + +The response contains interleaved text and tool result blocks: + +- `text` — Claude's explanation +- `server_tool_use` — What Claude is doing +- `bash_code_execution_tool_result` — Code execution output (check `return_code` for success/failure) +- `text_editor_code_execution_tool_result` — File operation results + +> **Security:** Always sanitize filenames with `os.path.basename()` / `path.basename()` before writing downloaded files to disk to prevent path traversal attacks. Write files to a dedicated output directory. + +--- + +## Server-Side Tools: Web Search and Web Fetch + +Web search and web fetch let Claude search the web and retrieve page content. They run server-side — just include the tool definitions and Claude handles queries, fetching, and result processing automatically. + +### Tool Definitions + +```json +[ + { "type": "web_search_20260209", "name": "web_search" }, + { "type": "web_fetch_20260209", "name": "web_fetch" } +] +``` + +### Dynamic Filtering (Opus 4.6 / Sonnet 4.6) + +The `web_search_20260209` and `web_fetch_20260209` versions support **dynamic filtering** — Claude writes and executes code to filter search results before they reach the context window, improving accuracy and token efficiency. Dynamic filtering is built into these tool versions and activates automatically; you do not need to separately declare the `code_execution` tool or pass any beta header. + +```json +{ + "tools": [ + { "type": "web_search_20260209", "name": "web_search" }, + { "type": "web_fetch_20260209", "name": "web_fetch" } + ] +} +``` + +Without dynamic filtering, the previous `web_search_20250305` version is also available. + +> **Note:** Only include the standalone `code_execution` tool when your application needs code execution for its own purposes (data analysis, file processing, visualization) independent of web search. Including it alongside `_20260209` web tools creates a second execution environment that can confuse the model. + +--- + +## Server-Side Tools: Programmatic Tool Calling + +Programmatic tool calling lets Claude execute complex multi-tool workflows in code, keeping intermediate results out of the context window. Claude writes code that calls your tools directly, reducing token usage for multi-step operations. + +For full documentation, use WebFetch: + +- URL: `https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling` + +--- + +## Server-Side Tools: Tool Search + +The tool search tool lets Claude dynamically discover tools from large libraries without loading all definitions into the context window. Useful when you have many tools but only a few are relevant to any given query. + +For full documentation, use WebFetch: + +- URL: `https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool` + +--- + +## Tool Use Examples + +You can provide sample tool calls directly in your tool definitions to demonstrate usage patterns and reduce parameter errors. This helps Claude understand how to correctly format tool inputs, especially for tools with complex schemas. + +For full documentation, use WebFetch: + +- URL: `https://platform.claude.com/docs/en/agents-and-tools/tool-use/implement-tool-use` + +--- + +## Server-Side Tools: Computer Use + +Computer use lets Claude interact with a desktop environment (screenshots, mouse, keyboard). It can be Anthropic-hosted (server-side, like code execution) or self-hosted (you provide the environment and execute actions client-side). + +For full documentation, use WebFetch: + +- URL: `https://platform.claude.com/docs/en/agents-and-tools/computer-use/overview` + +--- + +## Client-Side Tools: Memory + +The memory tool enables Claude to store and retrieve information across conversations through a memory file directory. Claude can create, read, update, and delete files that persist between sessions. + +### Key Facts + +- Client-side tool — you control storage via your implementation +- Supports commands: `view`, `create`, `str_replace`, `insert`, `delete`, `rename` +- Operates on files in a `/memories` directory +- The SDKs provide helper classes/functions for implementing the memory backend + +> **Security:** Never store API keys, passwords, tokens, or other secrets in memory files. Be cautious with personally identifiable information (PII) — check data privacy regulations (GDPR, CCPA) before persisting user data. The reference implementations have no built-in access control; in multi-user systems, implement per-user memory directories and authentication in your tool handlers. + +For full implementation examples, use WebFetch: + +- Docs: `https://platform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool.md` + +--- + +## Structured Outputs + +Structured outputs constrain Claude's responses to follow a specific JSON schema, guaranteeing valid, parseable output. This is not a separate tool — it enhances the Messages API response format and/or tool parameter validation. + +Two features are available: + +- **JSON outputs** (`output_config.format`): Control Claude's response format +- **Strict tool use** (`strict: true`): Guarantee valid tool parameter schemas + +**Supported models:** Claude Opus 4.6, Claude Sonnet 4.6, and Claude Haiku 4.5. Legacy models (Claude Opus 4.5, Claude Opus 4.1) also support structured outputs. + +> **Recommended:** Use `client.messages.parse()` which automatically validates responses against your schema. When using `messages.create()` directly, use `output_config: {format: {...}}`. The `output_format` convenience parameter is also accepted by some SDK methods (e.g., `.parse()`), but `output_config.format` is the canonical API-level parameter. + +### JSON Schema Limitations + +**Supported:** + +- Basic types: object, array, string, integer, number, boolean, null +- `enum`, `const`, `anyOf`, `allOf`, `$ref`/`$def` +- String formats: `date-time`, `time`, `date`, `duration`, `email`, `hostname`, `uri`, `ipv4`, `ipv6`, `uuid` +- `additionalProperties: false` (required for all objects) + +**Not supported:** + +- Recursive schemas +- Numerical constraints (`minimum`, `maximum`, `multipleOf`) +- String constraints (`minLength`, `maxLength`) +- Complex array constraints +- `additionalProperties` set to anything other than `false` + +The Python and TypeScript SDKs automatically handle unsupported constraints by removing them from the schema sent to the API and validating them client-side. + +### Important Notes + +- **First request latency**: New schemas incur a one-time compilation cost. Subsequent requests with the same schema use a 24-hour cache. +- **Refusals**: If Claude refuses for safety reasons (`stop_reason: "refusal"`), the output may not match your schema. +- **Token limits**: If `stop_reason: "max_tokens"`, output may be incomplete. Increase `max_tokens`. +- **Incompatible with**: Citations (returns 400 error), message prefilling. +- **Works with**: Batches API, streaming, token counting, extended thinking. + +--- + +## Tips for Effective Tool Use + +1. **Provide detailed descriptions**: Claude relies heavily on descriptions to understand when and how to use tools +2. **Use specific tool names**: `get_current_weather` is better than `weather` +3. **Validate inputs**: Always validate tool inputs before execution +4. **Handle errors gracefully**: Return informative error messages so Claude can adapt +5. **Limit tool count**: Too many tools can confuse the model — keep the set focused +6. **Test tool interactions**: Verify Claude uses tools correctly in various scenarios + +For detailed tool use documentation, use WebFetch: + +- URL: `https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview` diff --git a/skills/claude-api/typescript/agent-sdk/README.md b/skills/claude-api/typescript/agent-sdk/README.md new file mode 100644 index 00000000..997ca17f --- /dev/null +++ b/skills/claude-api/typescript/agent-sdk/README.md @@ -0,0 +1,220 @@ +# Agent SDK — TypeScript + +The Claude Agent SDK provides a higher-level interface for building AI agents with built-in tools, safety features, and agentic capabilities. + +## Installation + +```bash +npm install @anthropic-ai/claude-agent-sdk +``` + +--- + +## Quick Start + +```typescript +import { query } from "@anthropic-ai/claude-agent-sdk"; + +for await (const message of query({ + prompt: "Explain this codebase", + options: { allowedTools: ["Read", "Glob", "Grep"] }, +})) { + if ("result" in message) { + console.log(message.result); + } +} +``` + +--- + +## Built-in Tools + +| Tool | Description | +| --------- | ------------------------------------ | +| Read | Read files in the workspace | +| Write | Create new files | +| Edit | Make precise edits to existing files | +| Bash | Execute shell commands | +| Glob | Find files by pattern | +| Grep | Search files by content | +| WebSearch | Search the web for information | +| WebFetch | Fetch and analyze web pages | +| AskUserQuestion | Ask user clarifying questions | +| Agent | Spawn subagents | + +--- + +## Permission System + +```typescript +for await (const message of query({ + prompt: "Refactor the authentication module", + options: { + allowedTools: ["Read", "Edit", "Write"], + permissionMode: "acceptEdits", + }, +})) { + if ("result" in message) console.log(message.result); +} +``` + +Permission modes: + +- `"default"`: Prompt for dangerous operations +- `"plan"`: Planning only, no execution +- `"acceptEdits"`: Auto-accept file edits +- `"dontAsk"`: Don't prompt (useful for CI/CD) +- `"bypassPermissions"`: Skip all prompts (requires `allowDangerouslySkipPermissions: true` in options) + +--- + +## MCP (Model Context Protocol) Support + +```typescript +for await (const message of query({ + prompt: "Open example.com and describe what you see", + options: { + mcpServers: { + playwright: { command: "npx", args: ["@playwright/mcp@latest"] }, + }, + }, +})) { + if ("result" in message) console.log(message.result); +} +``` + +### In-Process MCP Tools + +You can define custom tools that run in-process using `tool()` and `createSdkMcpServer`: + +```typescript +import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk"; +import { z } from "zod"; + +const myTool = tool("my-tool", "Description", { input: z.string() }, async (args) => { + return { content: [{ type: "text", text: "result" }] }; +}); + +const server = createSdkMcpServer({ name: "my-server", tools: [myTool] }); + +// Pass to query +for await (const message of query({ + prompt: "Use my-tool to do something", + options: { mcpServers: { myServer: server } }, +})) { + if ("result" in message) console.log(message.result); +} +``` + +--- + +## Hooks + +```typescript +import { query, HookCallback } from "@anthropic-ai/claude-agent-sdk"; +import { appendFileSync } from "fs"; + +const logFileChange: HookCallback = async (input) => { + const filePath = (input as any).tool_input?.file_path ?? "unknown"; + appendFileSync( + "./audit.log", + `${new Date().toISOString()}: modified ${filePath}\n`, + ); + return {}; +}; + +for await (const message of query({ + prompt: "Refactor utils.py to improve readability", + options: { + allowedTools: ["Read", "Edit", "Write"], + permissionMode: "acceptEdits", + hooks: { + PostToolUse: [{ matcher: "Edit|Write", hooks: [logFileChange] }], + }, + }, +})) { + if ("result" in message) console.log(message.result); +} +``` + +Available hook events: `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `Notification`, `UserPromptSubmit`, `SessionStart`, `SessionEnd`, `Stop`, `SubagentStart`, `SubagentStop`, `PreCompact`, `PermissionRequest`, `Setup`, `TeammateIdle`, `TaskCompleted`, `ConfigChange` + +--- + +## Common Options + +`query()` takes a top-level `prompt` (string) and an `options` object: + +```typescript +query({ prompt: "...", options: { ... } }) +``` + +| Option | Type | Description | +| ----------------------------------- | ------ | -------------------------------------------------------------------------- | +| `cwd` | string | Working directory for file operations | +| `allowedTools` | array | Tools the agent can use (e.g., `["Read", "Edit", "Bash"]`) | +| `tools` | array | Built-in tools to make available (restricts the default set) | +| `disallowedTools` | array | Tools to explicitly disallow | +| `permissionMode` | string | How to handle permission prompts | +| `allowDangerouslySkipPermissions` | bool | Must be `true` to use `permissionMode: "bypassPermissions"` | +| `mcpServers` | object | MCP servers to connect to | +| `hooks` | object | Hooks for customizing behavior | +| `systemPrompt` | string | Custom system prompt | +| `maxTurns` | number | Maximum agent turns before stopping | +| `maxBudgetUsd` | number | Maximum budget in USD for the query | +| `model` | string | Model ID (default: determined by CLI) | +| `agents` | object | Subagent definitions (`Record`) | +| `outputFormat` | object | Structured output schema | +| `thinking` | object | Thinking/reasoning control | +| `betas` | array | Beta features to enable (e.g., `["context-1m-2025-08-07"]`) | +| `settingSources` | array | Settings to load (e.g., `["project"]`). Default: none (no CLAUDE.md files) | +| `env` | object | Environment variables to set for the session | + +--- + +## Subagents + +```typescript +for await (const message of query({ + prompt: "Use the code-reviewer agent to review this codebase", + options: { + allowedTools: ["Read", "Glob", "Grep", "Agent"], + agents: { + "code-reviewer": { + description: "Expert code reviewer for quality and security reviews.", + prompt: "Analyze code quality and suggest improvements.", + tools: ["Read", "Glob", "Grep"], + }, + }, + }, +})) { + if ("result" in message) console.log(message.result); +} +``` + +--- + +## Message Types + +```typescript +for await (const message of query({ + prompt: "Find TODO comments", + options: { allowedTools: ["Read", "Glob", "Grep"] }, +})) { + if ("result" in message) { + console.log(message.result); + } else if (message.type === "system" && message.subtype === "init") { + const sessionId = message.session_id; // Capture for resuming later + } +} +``` + +--- + +## Best Practices + +1. **Always specify allowedTools** — Explicitly list which tools the agent can use +2. **Set working directory** — Always specify `cwd` for file operations +3. **Use appropriate permission modes** — Start with `"default"` and only escalate when needed +4. **Handle all message types** — Check for `result` property to get agent output +5. **Limit maxTurns** — Prevent runaway agents with reasonable limits diff --git a/skills/claude-api/typescript/agent-sdk/patterns.md b/skills/claude-api/typescript/agent-sdk/patterns.md new file mode 100644 index 00000000..62b7fee9 --- /dev/null +++ b/skills/claude-api/typescript/agent-sdk/patterns.md @@ -0,0 +1,150 @@ +# Agent SDK Patterns — TypeScript + +## Basic Agent + +```typescript +import { query } from "@anthropic-ai/claude-agent-sdk"; + +async function main() { + for await (const message of query({ + prompt: "Explain what this repository does", + options: { + cwd: "/path/to/project", + allowedTools: ["Read", "Glob", "Grep"], + }, + })) { + if ("result" in message) { + console.log(message.result); + } + } +} + +main(); +``` + +--- + +## Hooks + +### After Tool Use Hook + +```typescript +import { query, HookCallback } from "@anthropic-ai/claude-agent-sdk"; +import { appendFileSync } from "fs"; + +const logFileChange: HookCallback = async (input) => { + const filePath = (input as any).tool_input?.file_path ?? "unknown"; + appendFileSync( + "./audit.log", + `${new Date().toISOString()}: modified ${filePath}\n`, + ); + return {}; +}; + +for await (const message of query({ + prompt: "Refactor utils.py to improve readability", + options: { + allowedTools: ["Read", "Edit", "Write"], + permissionMode: "acceptEdits", + hooks: { + PostToolUse: [{ matcher: "Edit|Write", hooks: [logFileChange] }], + }, + }, +})) { + if ("result" in message) console.log(message.result); +} +``` + +--- + +## Subagents + +```typescript +import { query } from "@anthropic-ai/claude-agent-sdk"; + +for await (const message of query({ + prompt: "Use the code-reviewer agent to review this codebase", + options: { + allowedTools: ["Read", "Glob", "Grep", "Agent"], + agents: { + "code-reviewer": { + description: "Expert code reviewer for quality and security reviews.", + prompt: "Analyze code quality and suggest improvements.", + tools: ["Read", "Glob", "Grep"], + }, + }, + }, +})) { + if ("result" in message) console.log(message.result); +} +``` + +--- + +## MCP Server Integration + +### Browser Automation (Playwright) + +```typescript +for await (const message of query({ + prompt: "Open example.com and describe what you see", + options: { + mcpServers: { + playwright: { command: "npx", args: ["@playwright/mcp@latest"] }, + }, + }, +})) { + if ("result" in message) console.log(message.result); +} +``` + +--- + +## Session Resumption + +```typescript +import { query } from "@anthropic-ai/claude-agent-sdk"; + +let sessionId: string | undefined; + +// First query: capture the session ID +for await (const message of query({ + prompt: "Read the authentication module", + options: { allowedTools: ["Read", "Glob"] }, +})) { + if (message.type === "system" && message.subtype === "init") { + sessionId = message.session_id; + } +} + +// Resume with full context from the first query +for await (const message of query({ + prompt: "Now find all places that call it", + options: { resume: sessionId }, +})) { + if ("result" in message) console.log(message.result); +} +``` + +--- + +## Custom System Prompt + +```typescript +import { query } from "@anthropic-ai/claude-agent-sdk"; + +for await (const message of query({ + prompt: "Review this code", + options: { + allowedTools: ["Read", "Glob", "Grep"], + systemPrompt: `You are a senior code reviewer focused on: +1. Security vulnerabilities +2. Performance issues +3. Code maintainability + +Always provide specific line numbers and suggestions for improvement.`, + }, +})) { + if ("result" in message) console.log(message.result); +} +``` diff --git a/skills/claude-api/typescript/claude-api/README.md b/skills/claude-api/typescript/claude-api/README.md new file mode 100644 index 00000000..9da778b4 --- /dev/null +++ b/skills/claude-api/typescript/claude-api/README.md @@ -0,0 +1,313 @@ +# Claude API — TypeScript + +## Installation + +```bash +npm install @anthropic-ai/sdk +``` + +## Client Initialization + +```typescript +import Anthropic from "@anthropic-ai/sdk"; + +// Default (uses ANTHROPIC_API_KEY env var) +const client = new Anthropic(); + +// Explicit API key +const client = new Anthropic({ apiKey: "your-api-key" }); +``` + +--- + +## Basic Message Request + +```typescript +const response = await client.messages.create({ + model: "claude-opus-4-6", + max_tokens: 1024, + messages: [{ role: "user", content: "What is the capital of France?" }], +}); +console.log(response.content[0].text); +``` + +--- + +## System Prompts + +```typescript +const response = await client.messages.create({ + model: "claude-opus-4-6", + max_tokens: 1024, + system: + "You are a helpful coding assistant. Always provide examples in Python.", + messages: [{ role: "user", content: "How do I read a JSON file?" }], +}); +``` + +--- + +## Vision (Images) + +### URL + +```typescript +const response = await client.messages.create({ + model: "claude-opus-4-6", + max_tokens: 1024, + messages: [ + { + role: "user", + content: [ + { + type: "image", + source: { type: "url", url: "https://example.com/image.png" }, + }, + { type: "text", text: "Describe this image" }, + ], + }, + ], +}); +``` + +### Base64 + +```typescript +import fs from "fs"; + +const imageData = fs.readFileSync("image.png").toString("base64"); + +const response = await client.messages.create({ + model: "claude-opus-4-6", + max_tokens: 1024, + messages: [ + { + role: "user", + content: [ + { + type: "image", + source: { type: "base64", media_type: "image/png", data: imageData }, + }, + { type: "text", text: "What's in this image?" }, + ], + }, + ], +}); +``` + +--- + +## Prompt Caching + +### Automatic Caching (Recommended) + +Use top-level `cache_control` to automatically cache the last cacheable block in the request: + +```typescript +const response = await client.messages.create({ + model: "claude-opus-4-6", + max_tokens: 1024, + cache_control: { type: "ephemeral" }, // auto-caches the last cacheable block + system: "You are an expert on this large document...", + messages: [{ role: "user", content: "Summarize the key points" }], +}); +``` + +### Manual Cache Control + +For fine-grained control, add `cache_control` to specific content blocks: + +```typescript +const response = await client.messages.create({ + model: "claude-opus-4-6", + max_tokens: 1024, + system: [ + { + type: "text", + text: "You are an expert on this large document...", + cache_control: { type: "ephemeral" }, // default TTL is 5 minutes + }, + ], + messages: [{ role: "user", content: "Summarize the key points" }], +}); + +// With explicit TTL (time-to-live) +const response2 = await client.messages.create({ + model: "claude-opus-4-6", + max_tokens: 1024, + system: [ + { + type: "text", + text: "You are an expert on this large document...", + cache_control: { type: "ephemeral", ttl: "1h" }, // 1 hour TTL + }, + ], + messages: [{ role: "user", content: "Summarize the key points" }], +}); +``` + +--- + +## Extended Thinking + +> **Opus 4.6 and Sonnet 4.6:** Use adaptive thinking. `budget_tokens` is deprecated on both Opus 4.6 and Sonnet 4.6. +> **Older models:** Use `thinking: {type: "enabled", budget_tokens: N}` (must be < `max_tokens`, min 1024). + +```typescript +// Opus 4.6: adaptive thinking (recommended) +const response = await client.messages.create({ + model: "claude-opus-4-6", + max_tokens: 16000, + thinking: { type: "adaptive" }, + output_config: { effort: "high" }, // low | medium | high | max + messages: [ + { role: "user", content: "Solve this math problem step by step..." }, + ], +}); + +for (const block of response.content) { + if (block.type === "thinking") { + console.log("Thinking:", block.thinking); + } else if (block.type === "text") { + console.log("Response:", block.text); + } +} +``` + +--- + +## Error Handling + +Use the SDK's typed exception classes — never check error messages with string matching: + +```typescript +import Anthropic from "@anthropic-ai/sdk"; + +try { + const response = await client.messages.create({...}); +} catch (error) { + if (error instanceof Anthropic.BadRequestError) { + console.error("Bad request:", error.message); + } else if (error instanceof Anthropic.AuthenticationError) { + console.error("Invalid API key"); + } else if (error instanceof Anthropic.RateLimitError) { + console.error("Rate limited - retry later"); + } else if (error instanceof Anthropic.APIError) { + console.error(`API error ${error.status}:`, error.message); + } +} +``` + +All classes extend `Anthropic.APIError` with a typed `status` field. Check from most specific to least specific. See [shared/error-codes.md](../../shared/error-codes.md) for the full error code reference. + +--- + +## Multi-Turn Conversations + +The API is stateless — send the full conversation history each time. Use `Anthropic.MessageParam[]` to type the messages array: + +```typescript +const messages: Anthropic.MessageParam[] = [ + { role: "user", content: "My name is Alice." }, + { role: "assistant", content: "Hello Alice! Nice to meet you." }, + { role: "user", content: "What's my name?" }, +]; + +const response = await client.messages.create({ + model: "claude-opus-4-6", + max_tokens: 1024, + messages: messages, +}); +``` + +**Rules:** + +- Messages must alternate between `user` and `assistant` +- First message must be `user` +- Use SDK types (`Anthropic.MessageParam`, `Anthropic.Message`, `Anthropic.Tool`, etc.) for all API data structures — don't redefine equivalent interfaces + +--- + +### Compaction (long conversations) + +> **Beta, Opus 4.6 only.** When conversations approach the 200K context window, compaction automatically summarizes earlier context server-side. The API returns a `compaction` block; you must pass it back on subsequent requests — append `response.content`, not just the text. + +```typescript +import Anthropic from "@anthropic-ai/sdk"; + +const client = new Anthropic(); +const messages: Anthropic.Beta.BetaMessageParam[] = []; + +async function chat(userMessage: string): Promise { + messages.push({ role: "user", content: userMessage }); + + const response = await client.beta.messages.create({ + betas: ["compact-2026-01-12"], + model: "claude-opus-4-6", + max_tokens: 4096, + messages, + context_management: { + edits: [{ type: "compact_20260112" }], + }, + }); + + // Append full content — compaction blocks must be preserved + messages.push({ role: "assistant", content: response.content }); + + const textBlock = response.content.find((block) => block.type === "text"); + return textBlock?.text ?? ""; +} + +// Compaction triggers automatically when context grows large +console.log(await chat("Help me build a Python web scraper")); +console.log(await chat("Add support for JavaScript-rendered pages")); +console.log(await chat("Now add rate limiting and error handling")); +``` + +--- + +## Stop Reasons + +The `stop_reason` field in the response indicates why the model stopped generating: + +| Value | Meaning | +| --------------- | --------------------------------------------------------------- | +| `end_turn` | Claude finished its response naturally | +| `max_tokens` | Hit the `max_tokens` limit — increase it or use streaming | +| `stop_sequence` | Hit a custom stop sequence | +| `tool_use` | Claude wants to call a tool — execute it and continue | +| `pause_turn` | Model paused and can be resumed (agentic flows) | +| `refusal` | Claude refused for safety reasons — output may not match schema | + +--- + +## Cost Optimization Strategies + +### 1. Use Prompt Caching for Repeated Context + +```typescript +// Automatic caching (simplest — caches the last cacheable block) +const response = await client.messages.create({ + model: "claude-opus-4-6", + max_tokens: 1024, + cache_control: { type: "ephemeral" }, + system: largeDocumentText, // e.g., 50KB of context + messages: [{ role: "user", content: "Summarize the key points" }], +}); + +// First request: full cost +// Subsequent requests: ~90% cheaper for cached portion +``` + +### 2. Use Token Counting Before Requests + +```typescript +const countResponse = await client.messages.countTokens({ + model: "claude-opus-4-6", + messages: messages, + system: system, +}); + +const estimatedInputCost = countResponse.input_tokens * 0.000005; // $5/1M tokens +console.log(`Estimated input cost: $${estimatedInputCost.toFixed(4)}`); +``` diff --git a/skills/claude-api/typescript/claude-api/batches.md b/skills/claude-api/typescript/claude-api/batches.md new file mode 100644 index 00000000..4f6f4f3e --- /dev/null +++ b/skills/claude-api/typescript/claude-api/batches.md @@ -0,0 +1,106 @@ +# Message Batches API — TypeScript + +The Batches API (`POST /v1/messages/batches`) processes Messages API requests asynchronously at 50% of standard prices. + +## Key Facts + +- Up to 100,000 requests or 256 MB per batch +- Most batches complete within 1 hour; maximum 24 hours +- Results available for 29 days after creation +- 50% cost reduction on all token usage +- All Messages API features supported (vision, tools, caching, etc.) + +--- + +## Create a Batch + +```typescript +import Anthropic from "@anthropic-ai/sdk"; + +const client = new Anthropic(); + +const messageBatch = await client.messages.batches.create({ + requests: [ + { + custom_id: "request-1", + params: { + model: "claude-opus-4-6", + max_tokens: 1024, + messages: [ + { role: "user", content: "Summarize climate change impacts" }, + ], + }, + }, + { + custom_id: "request-2", + params: { + model: "claude-opus-4-6", + max_tokens: 1024, + messages: [ + { role: "user", content: "Explain quantum computing basics" }, + ], + }, + }, + ], +}); + +console.log(`Batch ID: ${messageBatch.id}`); +console.log(`Status: ${messageBatch.processing_status}`); +``` + +--- + +## Poll for Completion + +```typescript +let batch; +while (true) { + batch = await client.messages.batches.retrieve(messageBatch.id); + if (batch.processing_status === "ended") break; + console.log( + `Status: ${batch.processing_status}, processing: ${batch.request_counts.processing}`, + ); + await new Promise((resolve) => setTimeout(resolve, 60_000)); +} + +console.log("Batch complete!"); +console.log(`Succeeded: ${batch.request_counts.succeeded}`); +console.log(`Errored: ${batch.request_counts.errored}`); +``` + +--- + +## Retrieve Results + +```typescript +for await (const result of await client.messages.batches.results( + messageBatch.id, +)) { + switch (result.result.type) { + case "succeeded": + console.log( + `[${result.custom_id}] ${result.result.message.content[0].text.slice(0, 100)}`, + ); + break; + case "errored": + if (result.result.error.type === "invalid_request") { + console.log(`[${result.custom_id}] Validation error - fix and retry`); + } else { + console.log(`[${result.custom_id}] Server error - safe to retry`); + } + break; + case "expired": + console.log(`[${result.custom_id}] Expired - resubmit`); + break; + } +} +``` + +--- + +## Cancel a Batch + +```typescript +const cancelled = await client.messages.batches.cancel(messageBatch.id); +console.log(`Status: ${cancelled.processing_status}`); // "canceling" +``` diff --git a/skills/claude-api/typescript/claude-api/files-api.md b/skills/claude-api/typescript/claude-api/files-api.md new file mode 100644 index 00000000..8224b52a --- /dev/null +++ b/skills/claude-api/typescript/claude-api/files-api.md @@ -0,0 +1,98 @@ +# Files API — TypeScript + +The Files API uploads files for use in Messages API requests. Reference files via `file_id` in content blocks, avoiding re-uploads across multiple API calls. + +**Beta:** Pass `betas: ["files-api-2025-04-14"]` in your API calls (the SDK sets the required header automatically). + +## Key Facts + +- Maximum file size: 500 MB +- Total storage: 100 GB per organization +- Files persist until deleted +- File operations (upload, list, delete) are free; content used in messages is billed as input tokens +- Not available on Amazon Bedrock or Google Vertex AI + +--- + +## Upload a File + +```typescript +import Anthropic, { toFile } from "@anthropic-ai/sdk"; +import fs from "fs"; + +const client = new Anthropic(); + +const uploaded = await client.beta.files.upload({ + file: await toFile(fs.createReadStream("report.pdf"), undefined, { + type: "application/pdf", + }), + betas: ["files-api-2025-04-14"], +}); + +console.log(`File ID: ${uploaded.id}`); +console.log(`Size: ${uploaded.size_bytes} bytes`); +``` + +--- + +## Use a File in Messages + +### PDF / Text Document + +```typescript +const response = await client.beta.messages.create({ + model: "claude-opus-4-6", + max_tokens: 1024, + messages: [ + { + role: "user", + content: [ + { type: "text", text: "Summarize the key findings in this report." }, + { + type: "document", + source: { type: "file", file_id: uploaded.id }, + title: "Q4 Report", + citations: { enabled: true }, + }, + ], + }, + ], + betas: ["files-api-2025-04-14"], +}); + +console.log(response.content[0].text); +``` + +--- + +## Manage Files + +### List Files + +```typescript +const files = await client.beta.files.list({ + betas: ["files-api-2025-04-14"], +}); +for (const f of files.data) { + console.log(`${f.id}: ${f.filename} (${f.size_bytes} bytes)`); +} +``` + +### Delete a File + +```typescript +await client.beta.files.delete("file_011CNha8iCJcU1wXNR6q4V8w", { + betas: ["files-api-2025-04-14"], +}); +``` + +### Download a File + +```typescript +const response = await client.beta.files.download( + "file_011CNha8iCJcU1wXNR6q4V8w", + { betas: ["files-api-2025-04-14"] }, +); +const content = Buffer.from(await response.arrayBuffer()); +await fs.promises.writeFile("output.txt", content); +``` diff --git a/skills/claude-api/typescript/claude-api/streaming.md b/skills/claude-api/typescript/claude-api/streaming.md new file mode 100644 index 00000000..a9505710 --- /dev/null +++ b/skills/claude-api/typescript/claude-api/streaming.md @@ -0,0 +1,178 @@ +# Streaming — TypeScript + +## Quick Start + +```typescript +const stream = client.messages.stream({ + model: "claude-opus-4-6", + max_tokens: 1024, + messages: [{ role: "user", content: "Write a story" }], +}); + +for await (const event of stream) { + if ( + event.type === "content_block_delta" && + event.delta.type === "text_delta" + ) { + process.stdout.write(event.delta.text); + } +} +``` + +--- + +## Handling Different Content Types + +> **Opus 4.6:** Use `thinking: {type: "adaptive"}`. On older models, use `thinking: {type: "enabled", budget_tokens: N}` instead. + +```typescript +const stream = client.messages.stream({ + model: "claude-opus-4-6", + max_tokens: 16000, + thinking: { type: "adaptive" }, + messages: [{ role: "user", content: "Analyze this problem" }], +}); + +for await (const event of stream) { + switch (event.type) { + case "content_block_start": + switch (event.content_block.type) { + case "thinking": + console.log("\n[Thinking...]"); + break; + case "text": + console.log("\n[Response:]"); + break; + } + break; + case "content_block_delta": + switch (event.delta.type) { + case "thinking_delta": + process.stdout.write(event.delta.thinking); + break; + case "text_delta": + process.stdout.write(event.delta.text); + break; + } + break; + } +} +``` + +--- + +## Streaming with Tool Use (Tool Runner) + +Use the tool runner with `stream: true`. The outer loop iterates over tool runner iterations (messages), the inner loop processes stream events: + +```typescript +import Anthropic from "@anthropic-ai/sdk"; +import { betaZodTool } from "@anthropic-ai/sdk/helpers/beta/zod"; +import { z } from "zod"; + +const client = new Anthropic(); + +const getWeather = betaZodTool({ + name: "get_weather", + description: "Get current weather for a location", + inputSchema: z.object({ + location: z.string().describe("City and state, e.g., San Francisco, CA"), + }), + run: async ({ location }) => `72°F and sunny in ${location}`, +}); + +const runner = client.beta.messages.toolRunner({ + model: "claude-opus-4-6", + max_tokens: 4096, + tools: [getWeather], + messages: [ + { role: "user", content: "What's the weather in Paris and London?" }, + ], + stream: true, +}); + +// Outer loop: each tool runner iteration +for await (const messageStream of runner) { + // Inner loop: stream events for this iteration + for await (const event of messageStream) { + switch (event.type) { + case "content_block_delta": + switch (event.delta.type) { + case "text_delta": + process.stdout.write(event.delta.text); + break; + case "input_json_delta": + // Tool input being streamed + break; + } + break; + } + } +} +``` + +--- + +## Getting the Final Message + +```typescript +const stream = client.messages.stream({ + model: "claude-opus-4-6", + max_tokens: 1024, + messages: [{ role: "user", content: "Hello" }], +}); + +for await (const event of stream) { + // Process events... +} + +const finalMessage = await stream.finalMessage(); +console.log(`Tokens used: ${finalMessage.usage.output_tokens}`); +``` + +--- + +## Stream Event Types + +| Event Type | Description | When it fires | +| --------------------- | --------------------------- | --------------------------------- | +| `message_start` | Contains message metadata | Once at the beginning | +| `content_block_start` | New content block beginning | When a text/tool_use block starts | +| `content_block_delta` | Incremental content update | For each token/chunk | +| `content_block_stop` | Content block complete | When a block finishes | +| `message_delta` | Message-level updates | Contains `stop_reason`, usage | +| `message_stop` | Message complete | Once at the end | + +## Best Practices + +1. **Always flush output** — Use `process.stdout.write()` for immediate display +2. **Handle partial responses** — If the stream is interrupted, you may have incomplete content +3. **Track token usage** — The `message_delta` event contains usage information +4. **Use `finalMessage()`** — Get the complete `Anthropic.Message` object even when streaming. Don't wrap `.on()` events in `new Promise()` — `finalMessage()` handles all completion/error/abort states internally +5. **Buffer for web UIs** — Consider buffering a few tokens before rendering to avoid excessive DOM updates +6. **Use `stream.on("text", ...)` for deltas** — The `text` event provides just the delta string, simpler than manually filtering `content_block_delta` events +7. **For agentic loops with streaming** — See the [Streaming Manual Loop](./tool-use.md#streaming-manual-loop) section in tool-use.md for combining `stream()` + `finalMessage()` with a tool-use loop + +## Raw SSE Format + +If using raw HTTP (not SDKs), the stream returns Server-Sent Events: + +``` +event: message_start +data: {"type":"message_start","message":{"id":"msg_...","type":"message",...}} + +event: content_block_start +data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}} + +event: content_block_delta +data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Hello"}} + +event: content_block_stop +data: {"type":"content_block_stop","index":0} + +event: message_delta +data: {"type":"message_delta","delta":{"stop_reason":"end_turn"},"usage":{"output_tokens":12}} + +event: message_stop +data: {"type":"message_stop"} +``` diff --git a/skills/claude-api/typescript/claude-api/tool-use.md b/skills/claude-api/typescript/claude-api/tool-use.md new file mode 100644 index 00000000..98fe131d --- /dev/null +++ b/skills/claude-api/typescript/claude-api/tool-use.md @@ -0,0 +1,477 @@ +# Tool Use — TypeScript + +For conceptual overview (tool definitions, tool choice, tips), see [shared/tool-use-concepts.md](../../shared/tool-use-concepts.md). + +## Tool Runner (Recommended) + +**Beta:** The tool runner is in beta in the TypeScript SDK. + +Use `betaZodTool` with Zod schemas to define tools with a `run` function, then pass them to `client.beta.messages.toolRunner()`: + +```typescript +import Anthropic from "@anthropic-ai/sdk"; +import { betaZodTool } from "@anthropic-ai/sdk/helpers/beta/zod"; +import { z } from "zod"; + +const client = new Anthropic(); + +const getWeather = betaZodTool({ + name: "get_weather", + description: "Get current weather for a location", + inputSchema: z.object({ + location: z.string().describe("City and state, e.g., San Francisco, CA"), + unit: z.enum(["celsius", "fahrenheit"]).optional(), + }), + run: async (input) => { + // Your implementation here + return `72°F and sunny in ${input.location}`; + }, +}); + +// The tool runner handles the agentic loop and returns the final message +const finalMessage = await client.beta.messages.toolRunner({ + model: "claude-opus-4-6", + max_tokens: 4096, + tools: [getWeather], + messages: [{ role: "user", content: "What's the weather in Paris?" }], +}); + +console.log(finalMessage.content); +``` + +**Key benefits of the tool runner:** + +- No manual loop — the SDK handles calling tools and feeding results back +- Type-safe tool inputs via Zod schemas +- Tool schemas are generated automatically from Zod definitions +- Iteration stops automatically when Claude has no more tool calls + +--- + +## Manual Agentic Loop + +Use this when you need fine-grained control (custom logging, conditional tool execution, streaming individual iterations, human-in-the-loop approval): + +```typescript +import Anthropic from "@anthropic-ai/sdk"; + +const client = new Anthropic(); +const tools: Anthropic.Tool[] = [...]; // Your tool definitions +let messages: Anthropic.MessageParam[] = [{ role: "user", content: userInput }]; + +while (true) { + const response = await client.messages.create({ + model: "claude-opus-4-6", + max_tokens: 4096, + tools: tools, + messages: messages, + }); + + if (response.stop_reason === "end_turn") break; + + // Server-side tool hit iteration limit; re-send to continue + if (response.stop_reason === "pause_turn") { + messages = [ + { role: "user", content: userInput }, + { role: "assistant", content: response.content }, + ]; + continue; + } + + const toolUseBlocks = response.content.filter( + (b): b is Anthropic.ToolUseBlock => b.type === "tool_use", + ); + + messages.push({ role: "assistant", content: response.content }); + + const toolResults: Anthropic.ToolResultBlockParam[] = []; + for (const tool of toolUseBlocks) { + const result = await executeTool(tool.name, tool.input); + toolResults.push({ + type: "tool_result", + tool_use_id: tool.id, + content: result, + }); + } + + messages.push({ role: "user", content: toolResults }); +} +``` + +### Streaming Manual Loop + +Use `client.messages.stream()` + `finalMessage()` instead of `.create()` when you need streaming within a manual loop. Text deltas are streamed on each iteration; `finalMessage()` collects the complete `Message` so you can inspect `stop_reason` and extract tool-use blocks: + +```typescript +import Anthropic from "@anthropic-ai/sdk"; + +const client = new Anthropic(); +const tools: Anthropic.Tool[] = [...]; +let messages: Anthropic.MessageParam[] = [{ role: "user", content: userInput }]; + +while (true) { + const stream = client.messages.stream({ + model: "claude-opus-4-6", + max_tokens: 4096, + tools, + messages, + }); + + // Stream text deltas on each iteration + stream.on("text", (delta) => { + process.stdout.write(delta); + }); + + // finalMessage() resolves with the complete Message — no need to + // manually wire up .on("message") / .on("error") / .on("abort") + const message = await stream.finalMessage(); + + if (message.stop_reason === "end_turn") break; + + // Server-side tool hit iteration limit; re-send to continue + if (message.stop_reason === "pause_turn") { + messages = [ + { role: "user", content: userInput }, + { role: "assistant", content: message.content }, + ]; + continue; + } + + const toolUseBlocks = message.content.filter( + (b): b is Anthropic.ToolUseBlock => b.type === "tool_use", + ); + + messages.push({ role: "assistant", content: message.content }); + + const toolResults: Anthropic.ToolResultBlockParam[] = []; + for (const tool of toolUseBlocks) { + const result = await executeTool(tool.name, tool.input); + toolResults.push({ + type: "tool_result", + tool_use_id: tool.id, + content: result, + }); + } + + messages.push({ role: "user", content: toolResults }); +} +``` + +> **Important:** Don't wrap `.on()` events in `new Promise()` to collect the final message — use `stream.finalMessage()` instead. The SDK handles all error/abort/completion states internally. + +> **Error handling in the loop:** Use the SDK's typed exceptions (e.g., `Anthropic.RateLimitError`, `Anthropic.APIError`) — see [Error Handling](./README.md#error-handling) for examples. Don't check error messages with string matching. + +> **SDK types:** Use `Anthropic.MessageParam`, `Anthropic.Tool`, `Anthropic.ToolUseBlock`, `Anthropic.ToolResultBlockParam`, `Anthropic.Message`, etc. for all API-related data structures. Don't redefine equivalent interfaces. + +--- + +## Handling Tool Results + +```typescript +const response = await client.messages.create({ + model: "claude-opus-4-6", + max_tokens: 1024, + tools: tools, + messages: [{ role: "user", content: "What's the weather in Paris?" }], +}); + +for (const block of response.content) { + if (block.type === "tool_use") { + const result = await executeTool(block.name, block.input); + + const followup = await client.messages.create({ + model: "claude-opus-4-6", + max_tokens: 1024, + tools: tools, + messages: [ + { role: "user", content: "What's the weather in Paris?" }, + { role: "assistant", content: response.content }, + { + role: "user", + content: [ + { type: "tool_result", tool_use_id: block.id, content: result }, + ], + }, + ], + }); + } +} +``` + +--- + +## Tool Choice + +```typescript +const response = await client.messages.create({ + model: "claude-opus-4-6", + max_tokens: 1024, + tools: tools, + tool_choice: { type: "tool", name: "get_weather" }, + messages: [{ role: "user", content: "What's the weather in Paris?" }], +}); +``` + +--- + +## Code Execution + +### Basic Usage + +```typescript +import Anthropic from "@anthropic-ai/sdk"; + +const client = new Anthropic(); + +const response = await client.messages.create({ + model: "claude-opus-4-6", + max_tokens: 4096, + messages: [ + { + role: "user", + content: + "Calculate the mean and standard deviation of [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]", + }, + ], + tools: [{ type: "code_execution_20260120", name: "code_execution" }], +}); +``` + +### Upload Files for Analysis + +```typescript +import Anthropic, { toFile } from "@anthropic-ai/sdk"; +import { createReadStream } from "fs"; + +const client = new Anthropic(); + +// 1. Upload a file +const uploaded = await client.beta.files.upload({ + file: await toFile(createReadStream("sales_data.csv"), undefined, { + type: "text/csv", + }), + betas: ["files-api-2025-04-14"], +}); + +// 2. Pass to code execution +// Code execution is GA; Files API is still beta (pass via RequestOptions) +const response = await client.messages.create( + { + model: "claude-opus-4-6", + max_tokens: 4096, + messages: [ + { + role: "user", + content: [ + { + type: "text", + text: "Analyze this sales data. Show trends and create a visualization.", + }, + { type: "container_upload", file_id: uploaded.id }, + ], + }, + ], + tools: [{ type: "code_execution_20260120", name: "code_execution" }], + }, + { headers: { "anthropic-beta": "files-api-2025-04-14" } }, +); +``` + +### Retrieve Generated Files + +```typescript +import path from "path"; +import fs from "fs"; + +const OUTPUT_DIR = "./claude_outputs"; +await fs.promises.mkdir(OUTPUT_DIR, { recursive: true }); + +for (const block of response.content) { + if (block.type === "bash_code_execution_tool_result") { + const result = block.content; + if (result.type === "bash_code_execution_result" && result.content) { + for (const fileRef of result.content) { + if (fileRef.type === "bash_code_execution_output") { + const metadata = await client.beta.files.retrieveMetadata( + fileRef.file_id, + ); + const response = await client.beta.files.download(fileRef.file_id); + const fileBytes = Buffer.from(await response.arrayBuffer()); + const safeName = path.basename(metadata.filename); + if (!safeName || safeName === "." || safeName === "..") { + console.warn(`Skipping invalid filename: ${metadata.filename}`); + continue; + } + const outputPath = path.join(OUTPUT_DIR, safeName); + await fs.promises.writeFile(outputPath, fileBytes); + console.log(`Saved: ${outputPath}`); + } + } + } + } +} +``` + +### Container Reuse + +```typescript +// First request: set up environment +const response1 = await client.messages.create({ + model: "claude-opus-4-6", + max_tokens: 4096, + messages: [ + { + role: "user", + content: "Install tabulate and create data.json with sample user data", + }, + ], + tools: [{ type: "code_execution_20260120", name: "code_execution" }], +}); + +// Reuse container +const containerId = response1.container.id; + +const response2 = await client.messages.create({ + container: containerId, + model: "claude-opus-4-6", + max_tokens: 4096, + messages: [ + { + role: "user", + content: "Read data.json and display as a formatted table", + }, + ], + tools: [{ type: "code_execution_20260120", name: "code_execution" }], +}); +``` + +--- + +## Memory Tool + +### Basic Usage + +```typescript +const response = await client.messages.create({ + model: "claude-opus-4-6", + max_tokens: 2048, + messages: [ + { + role: "user", + content: "Remember that my preferred language is TypeScript.", + }, + ], + tools: [{ type: "memory_20250818", name: "memory" }], +}); +``` + +### SDK Memory Helper + +Use `betaMemoryTool` with a `MemoryToolHandlers` implementation: + +```typescript +import { + betaMemoryTool, + type MemoryToolHandlers, +} from "@anthropic-ai/sdk/helpers/beta/memory"; + +const handlers: MemoryToolHandlers = { + async view(command) { ... }, + async create(command) { ... }, + async str_replace(command) { ... }, + async insert(command) { ... }, + async delete(command) { ... }, + async rename(command) { ... }, +}; + +const memory = betaMemoryTool(handlers); + +const runner = client.beta.messages.toolRunner({ + model: "claude-opus-4-6", + max_tokens: 2048, + tools: [memory], + messages: [{ role: "user", content: "Remember my preferences" }], +}); + +for await (const message of runner) { + console.log(message); +} +``` + +For full implementation examples, use WebFetch: + +- `https://github.com/anthropics/anthropic-sdk-typescript/blob/main/examples/tools-helpers-memory.ts` + +--- + +## Structured Outputs + +### JSON Outputs (Zod — Recommended) + +```typescript +import Anthropic from "@anthropic-ai/sdk"; +import { z } from "zod"; +import { zodOutputFormat } from "@anthropic-ai/sdk/helpers/zod"; + +const ContactInfoSchema = z.object({ + name: z.string(), + email: z.string(), + plan: z.string(), + interests: z.array(z.string()), + demo_requested: z.boolean(), +}); + +const client = new Anthropic(); + +const response = await client.messages.parse({ + model: "claude-opus-4-6", + max_tokens: 1024, + messages: [ + { + role: "user", + content: + "Extract: Jane Doe (jane@co.com) wants Enterprise, interested in API and SDKs, wants a demo.", + }, + ], + output_config: { + format: zodOutputFormat(ContactInfoSchema), + }, +}); + +console.log(response.parsed_output.name); // "Jane Doe" +``` + +### Strict Tool Use + +```typescript +const response = await client.messages.create({ + model: "claude-opus-4-6", + max_tokens: 1024, + messages: [ + { + role: "user", + content: "Book a flight to Tokyo for 2 passengers on March 15", + }, + ], + tools: [ + { + name: "book_flight", + description: "Book a flight to a destination", + strict: true, + input_schema: { + type: "object", + properties: { + destination: { type: "string" }, + date: { type: "string", format: "date" }, + passengers: { + type: "integer", + enum: [1, 2, 3, 4, 5, 6, 7, 8], + }, + }, + required: ["destination", "date", "passengers"], + additionalProperties: false, + }, + }, + ], +}); +``` diff --git a/skills/cold-email/SKILL.md b/skills/cold-email/SKILL.md new file mode 100644 index 00000000..b86610f1 --- /dev/null +++ b/skills/cold-email/SKILL.md @@ -0,0 +1,167 @@ +--- +name: cold-email +description: "Write B2B cold emails and follow-up sequences that earn replies. Use when creating outbound prospecting emails, SDR outreach, personalized opening lines, subject lines, CTAs, and multi-touch follow-up sequences." +risk: unknown +source: "https://github.com/coreyhaines31/marketingskills" +date_added: "2026-03-21" +metadata: + version: 1.1.0 +--- + +# Cold Email Writing + +You are an expert cold email writer. Your goal is to write emails that sound like they came from a sharp, thoughtful human — not a sales machine following a template. + +## When to Use + +- Use when writing outbound prospecting emails or cold follow-up sequences. +- Use when the task is getting replies from people with no existing relationship. +- Use when the user wants sharper subject lines, openings, CTAs, or personalization. + +## Before Writing + +**Check for product marketing context first:** +If `.agents/product-marketing-context.md` exists (or `.claude/product-marketing-context.md` in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task. + +Understand the situation (ask if not provided): + +1. **Who are you writing to?** — Role, company, why them specifically +2. **What do you want?** — The outcome (meeting, reply, intro, demo) +3. **What's the value?** — The specific problem you solve for people like them +4. **What's your proof?** — A result, case study, or credibility signal +5. **Any research signals?** — Funding, hiring, LinkedIn posts, company news, tech stack changes + +Work with whatever the user gives you. If they have a strong signal and a clear value prop, that's enough to write. Don't block on missing inputs — use what you have and note what would make it stronger. + +--- + +## Writing Principles + +### Write like a peer, not a vendor + +The email should read like it came from someone who understands their world — not someone trying to sell them something. Use contractions. Read it aloud. If it sounds like marketing copy, rewrite it. + +### Every sentence must earn its place + +Cold email is ruthlessly short. If a sentence doesn't move the reader toward replying, cut it. The best cold emails feel like they could have been shorter, not longer. + +### Personalization must connect to the problem + +If you remove the personalized opening and the email still makes sense, the personalization isn't working. The observation should naturally lead into why you're reaching out. + +See [personalization.md](references/personalization.md) for the 4-level system and research signals. + +### Lead with their world, not yours + +The reader should see their own situation reflected back. "You/your" should dominate over "I/we." Don't open with who you are or what your company does. + +### One ask, low friction + +Interest-based CTAs ("Worth exploring?" / "Would this be useful?") beat meeting requests. One CTA per email. Make it easy to say yes with a one-line reply. + +--- + +## Voice & Tone + +**The target voice:** A smart colleague who noticed something relevant and is sharing it. Conversational but not sloppy. Confident but not pushy. + +**Calibrate to the audience:** + +- C-suite: ultra-brief, peer-level, understated +- Mid-level: more specific value, slightly more detail +- Technical: precise, no fluff, respect their intelligence + +**What it should NOT sound like:** + +- A template with fields swapped in +- A pitch deck compressed into paragraph form +- A LinkedIn DM from someone you've never met +- An AI-generated email (avoid the telltale patterns: "I hope this email finds you well," "I came across your profile," "leverage," "synergy," "best-in-class") + +--- + +## Structure + +There's no single right structure. Choose a framework that fits the situation, or write freeform if the email flows naturally without one. + +**Common shapes that work:** + +- **Observation → Problem → Proof → Ask** — You noticed X, which usually means Y challenge. We helped Z with that. Interested? +- **Question → Value → Ask** — Struggling with X? We do Y. Company Z saw [result]. Worth a look? +- **Trigger → Insight → Ask** — Congrats on X. That usually creates Y challenge. We've helped similar companies with that. Curious? +- **Story → Bridge → Ask** — [Similar company] had [problem]. They [solved it this way]. Relevant to you? + +For the full catalog of frameworks with examples, see [frameworks.md](references/frameworks.md). + +--- + +## Subject Lines + +Short, boring, internal-looking. The subject line's only job is to get the email opened — not to sell. + +- 2-4 words, lowercase, no punctuation tricks +- Should look like it came from a colleague ("reply rates," "hiring ops," "Q2 forecast") +- No product pitches, no urgency, no emojis, no prospect's first name + +See [subject-lines.md](references/subject-lines.md) for the full data. + +--- + +## Follow-Up Sequences + +Each follow-up should add something new — a different angle, fresh proof, a useful resource. "Just checking in" gives the reader no reason to respond. + +- 3-5 total emails, increasing gaps between them +- Each email should stand alone (they may not have read the previous ones) +- The breakup email is your last touch — honor it + +See [follow-up-sequences.md](references/follow-up-sequences.md) for cadence, angle rotation, and breakup email templates. + +--- + +## Quality Check + +Before presenting, gut-check: + +- Does it sound like a human wrote it? (Read it aloud) +- Would YOU reply to this if you received it? +- Does every sentence serve the reader, not the sender? +- Is the personalization connected to the problem? +- Is there one clear, low-friction ask? + +--- + +## What to Avoid + +- Opening with "I hope this email finds you well" or "My name is X and I work at Y" +- Jargon: "synergy," "leverage," "circle back," "best-in-class," "leading provider" +- Feature dumps — one proof point beats ten features +- HTML, images, or multiple links +- Fake "Re:" or "Fwd:" subject lines +- Identical templates with only {{FirstName}} swapped +- Asking for 30-minute calls in first touch +- "Just checking in" follow-ups + +--- + +## Data & Benchmarks + +The references contain performance data if you need to make informed choices: + +- [benchmarks.md](references/benchmarks.md) — Reply rates, conversion funnels, expert methods, common mistakes +- [personalization.md](references/personalization.md) — 4-level personalization system, research signals +- [subject-lines.md](references/subject-lines.md) — Subject line data and optimization +- [follow-up-sequences.md](references/follow-up-sequences.md) — Cadence, angles, breakup emails +- [frameworks.md](references/frameworks.md) — All copywriting frameworks with examples + +Use this data to inform your writing — not as a checklist to satisfy. + +--- + +## Related Skills + +- **copywriting**: For landing pages and web copy +- **email-sequence**: For lifecycle/nurture email sequences (not cold outreach) +- **social-content**: For LinkedIn and social posts +- **product-marketing-context**: For establishing foundational positioning +- **revops**: For lead scoring, routing, and pipeline management diff --git a/skills/cold-email/evals/evals.json b/skills/cold-email/evals/evals.json new file mode 100644 index 00000000..5538a9ff --- /dev/null +++ b/skills/cold-email/evals/evals.json @@ -0,0 +1,94 @@ +{ + "skill_name": "cold-email", + "evals": [ + { + "id": 1, + "prompt": "Write a cold email to VP of Marketing at mid-size B2B SaaS companies. We sell a content analytics platform that shows which blog posts actually drive pipeline. Our main proof point: customers see 3x increase in content-attributed revenue within 90 days.", + "expected_output": "Should check for product-marketing-context.md first. Should write like a peer, not a vendor. Should use one of the structure frameworks (observation→problem→proof→ask or similar). Subject line should be 2-4 words, lowercase, internal-looking. Every sentence should earn its place. Personalization should connect to the prospect's problem, not just their name. Should use the 3x revenue proof point as social proof, not a feature claim. CTA should be low-friction (not 'book a demo'). Should provide 2-3 variations. Should include a quality check against the guidelines.", + "assertions": [ + "Checks for product-marketing-context.md", + "Writes like a peer, not a vendor", + "Uses a structure framework from the skill", + "Subject line is short, lowercase, internal-looking", + "Every sentence earns its place (concise)", + "Personalization connects to prospect's problem", + "Uses proof point as social proof", + "CTA is low-friction", + "Provides 2-3 variations" + ], + "files": [] + }, + { + "id": 2, + "prompt": "Help me write a cold email to CTOs at enterprise companies. I sell cybersecurity training. My current email has a 2% open rate and 0% reply rate.", + "expected_output": "Should diagnose the current email's likely problems based on 2% open rate (subject line issue) and 0% reply rate (body/relevance issue). Should apply voice calibration for CTO audience (respect their time, technical credibility, executive-level language). Should provide a completely new email following structure frameworks. Subject line should be 2-4 words, look internal. Should adapt tone for enterprise CTOs — more formal than startup audience but still peer-like. Should provide the email plus analysis of why each element works.", + "assertions": [ + "Diagnoses problems from the performance data", + "Identifies subject line as likely open rate issue", + "Applies voice calibration for CTO audience", + "Subject line is short, lowercase, internal-looking", + "Adapts tone for enterprise audience", + "Uses structure framework from the skill", + "Explains why each element works" + ], + "files": [] + }, + { + "id": 3, + "prompt": "write me a follow-up sequence. prospect didn't reply to my first email about our HR software. how many should I send and how far apart?", + "expected_output": "Should trigger on casual phrasing. Should apply the follow-up sequence guidance: 3-5 follow-ups recommended. Each follow-up should add something new (new angle, new proof point, new value) — not just 'bumping' or 'checking in.' Should provide timing recommendations between emails. Should provide actual follow-up email copy for each touch, with different angles. Should include a breakup email at the end. Should note that each follow-up should be shorter than the previous.", + "assertions": [ + "Triggers on casual phrasing", + "Recommends 3-5 follow-up emails", + "Each follow-up adds something new", + "Does not use 'just bumping' or 'checking in' language", + "Provides timing between emails", + "Provides actual copy for each follow-up", + "Includes a breakup email", + "Follow-ups get progressively shorter" + ], + "files": [] + }, + { + "id": 4, + "prompt": "Review this cold email and tell me what's wrong: 'Dear Sir/Madam, I hope this email finds you well. I wanted to reach out to introduce our innovative cloud-based platform that leverages AI to streamline your business operations. We have helped over 500 companies transform their workflows. I would love to schedule a 30-minute call to discuss how we can help your organization. Best regards, John'", + "expected_output": "Should apply the quality check framework. Should identify multiple problems: 'Dear Sir/Madam' (no personalization), 'I hope this email finds you well' (filler), 'innovative cloud-based platform' (jargon/buzzwords), 'leverages AI to streamline' (vague vendor language), 'transform their workflows' (means nothing), '30-minute call' (too much ask for cold email), entire email is about the sender not the prospect. Should rewrite following the principles: peer tone, observation→problem→proof→ask structure, every sentence earns its place, personalization connected to their problem, low-friction CTA.", + "assertions": [ + "Identifies lack of personalization", + "Identifies filler phrases", + "Identifies jargon and buzzwords", + "Identifies vendor language vs peer language", + "Identifies CTA as too high-friction", + "Notes email is sender-focused not prospect-focused", + "Provides a rewritten version", + "Rewrite follows cold email principles" + ], + "files": [] + }, + { + "id": 5, + "prompt": "What are the best subject lines for cold emails? I want to maximize open rates.", + "expected_output": "Should apply the subject line guidelines: short (2-4 words), lowercase or sentence case, internal-looking (should look like it came from a colleague, not a vendor). Should provide examples following these principles. Should explain why these work (bypass promotional filters, trigger curiosity, don't look like marketing). Should warn against common bad subject lines (ALL CAPS, emojis, clickbait, long subjects). Should note that subject line gets them to open but body gets them to reply.", + "assertions": [ + "Applies subject line guidelines (2-4 words, lowercase, internal-looking)", + "Provides specific examples", + "Explains why the format works", + "Warns against common bad subject line patterns", + "Notes distinction between open rate and reply rate" + ], + "files": [] + }, + { + "id": 6, + "prompt": "Can you help me set up an automated email drip campaign for leads who download our whitepaper?", + "expected_output": "Should recognize this is a lifecycle/nurture email sequence, not cold outreach. Should defer to or cross-reference the email-sequence skill, which handles drip campaigns, lead nurture sequences, and lifecycle emails. Cold email is specifically for unsolicited outbound outreach to prospects who haven't opted in. Should make this distinction clear.", + "assertions": [ + "Recognizes this as lifecycle/nurture email, not cold outreach", + "References or defers to email-sequence skill", + "Explains the distinction between cold email and lifecycle email", + "Does not attempt to design a nurture sequence using cold email patterns" + ], + "files": [] + } + ] +} diff --git a/skills/cold-email/references/benchmarks.md b/skills/cold-email/references/benchmarks.md new file mode 100644 index 00000000..bc6e44d8 --- /dev/null +++ b/skills/cold-email/references/benchmarks.md @@ -0,0 +1,83 @@ +# Benchmarks, Data & Expert Methods + +## Core Performance Metrics (2024–2025) + +| Metric | Average | Good | Excellent | Source | +| -------------------------- | ------- | ------ | --------- | ------------------------ | +| Open rate | 27.7% | 40–45% | 50%+ | Belkins, Snov.io | +| Reply rate | 4–5.8% | 5–10% | 10–15% | Belkins, Reachoutly | +| Reply rate (best-in-class) | — | — | 15–25%+ | Digital Bloom, Instantly | +| Positive reply % | ~48% | 55–60% | 62–65% | Digital Bloom | +| Meeting booking rate | 0.5–1% | 1–2% | 2.3%+ | Reachoutly | +| Bounce rate | 7.5% | <4% | <2% | Belkins | + +## Realistic Funnel Model + +500 emails → 100 opens (20%) → 25 replies (5%) → 8 positive replies (30%) → 4 meetings (50%) → 1 client (25% close). ~**0.2% end-to-end conversion** for average performers. + +## Performance Levers (ranked by impact) + +1. **Hook type** — Timeline hooks outperform problem hooks by 3.4x in meetings +2. **Personalization depth** — Up to 250% more replies +3. **Brevity** — 25–75 words optimal, 83% more replies under 75 words +4. **Targeting precision** — ≤50 contacts per campaign = 2.76x higher reply rates +5. **Follow-up strategy** — First follow-up adds 49% more replies +6. **Reading level** — 3rd–5th grade = 67% more replies +7. **Send timing** — Thursday peaks at 6.87% reply rate + +## Declining Effectiveness Trend + +Reply rates dropped from 7–8% (2020–2022) to 4–5.8% (2024–2025), ~15% YoY decline. Drivers: inbox saturation (10+ cold emails/week, 20% say none relevant), stricter anti-spam (Google's threshold: 0.1% complaints), AI email flood (more volume, less quality signal). Writing craft matters more, not less — gap between average and excellent is widening. + +## Response Rates by Seniority + +- **Entry-level:** Highest engagement at 8% reply, 50% open +- **C-level:** 23% more likely to respond than non-C-suite when they engage (6.4% vs 5.2%) +- **CTOs/VP Tech:** 7.68% reply +- **CEOs/Founders:** 7.63% reply +- **Heads of Sales:** 6.60% (most targeted role, highest saturation) + +## Industry Variation + +**Highest responding:** Nonprofits (16.5%+), legal (10%), EdTech (7.8%), chemical (7.3%), manufacturing (6.1%). +**Lowest responding:** SaaS (3.5%), financial services (3.4%), IT services (3.5%). + +## Top 15 Mistakes (ranked by impact) + +1. **Too long** — 70% of emails above 10th-grade level. Under 75 words = 83% more replies +2. **Too self-focused** — "We are a leading..." signals sales pitch. Count I/We sentences +3. **No clear value prop** — 71% of decision-makers ignore irrelevant emails +4. **Generic templates** — {{FirstName}} isn't personalization. Recipients detect instantly +5. **Feature dumping** — "Great reps lead with problems" (Lavender). One proof point beats ten features +6. **False personalization** — "Loved your post!" without specifics is transparent +7. **Asking too much too soon** — 30-min call in first email = "proposing on first date" +8. **Pushy language** — "Act Now" stacking increases spam flagging by 67% +9. **No CTA** — Without a clear next step, momentum dies +10. **"Just checking in" follow-ups** — "I never heard back" = 12% drop in bookings +11. **Wrong tone for audience** — Founder ≠ RevOps lead ≠ sales leader +12. **Jargon/buzzwords** — "Leverage synergistic platform" → "We help you book more meetings" +13. **Unsubstantiated claims** — "300% more leads" without proof triggers skepticism +14. **Too many contacts per company** — 1–2 people = 7.8% reply; 10+ = 3.8% +15. **Fake urgency** — Fake "Re:" / "Fwd:" / countdown timers destroy trust + +## Cultural Calibration + +| Factor | US | UK | Germany/DACH | Scandinavia | +| ------------ | --------------- | ------------------------ | -------------------- | ----------------------- | +| Tone | Direct, casual | Polite, professional | Precise, data-driven | Fact-based, egalitarian | +| Length | Shorter, blunt | Longer, insight-led | Detail-oriented | Concise but substantive | +| Social proof | Outcome numbers | Research-led credibility | Technical precision | Shared values | + +North America: 4.1% response. Europe: 3.1%. Asia-Pacific: 2.8%. Shorter, more direct sequences work better in US. UK needs more insight/personality. GDPR affects European tone. + +## Expert Quick Reference + +| Expert | Core Method | Best For | +| -------------- | --------------------------------------------------------------- | ----------------------------------------------- | +| Alex Berman | 3C's: Compliment → Case Study → CTA | High-ticket B2B services, agencies | +| Josh Braun | "Poke the Bear" — neutral questions exposing invisible problems | Empathy-driven consultative selling | +| Kyle Coleman | Systematic research + AI personalization at scale | Bridging mass outreach and deep personalization | +| Becc Holland | Psychographic personalization, Premise Buckets | Combining personalization with relevance | +| Will Allred | Data-driven coaching, Mouse Trap, Vanilla Ice Cream | Any context; universal frameworks | +| Justin Michael | 1–3 sentence hyper-brevity, quote their own words | High-velocity SDR teams at scale | +| Sam Nelson | Agoge Sequence — Triple on Day 1 (email + LinkedIn + call) | Multi-channel, tiered personalization | diff --git a/skills/cold-email/references/follow-up-sequences.md b/skills/cold-email/references/follow-up-sequences.md new file mode 100644 index 00000000..f32d6d79 --- /dev/null +++ b/skills/cold-email/references/follow-up-sequences.md @@ -0,0 +1,81 @@ +# Follow-Up Sequences + +55% of replies come from follow-ups, not the initial email. Yet 48% of salespeople never follow up even once. + +## How Many: 3–5 Total Emails + +- Highest single-email reply rate: **8.4%** (Belkins). +- 4–7 email campaigns achieve **27% reply rates** vs 9% for 1–3 emails (Woodpecker, 20M emails). +- By 4th follow-up, response rates drop **55%** and spam complaints **triple**. +- Resolution: longer sequences catch different timing windows. Cap at 4 follow-ups (5 total emails). Each must add genuinely new value. + +## Optimal Cadence + +Increase the gap between each touch: + +| Touch | Day | Notes | +| ------------- | ----- | ---------------------------------------------- | +| Initial email | 0 | Maximum personalization investment | +| Follow-up 1 | 3 | Waiting 3 days increases response by up to 31% | +| Follow-up 2 | 7–8 | Different angle | +| Follow-up 3 | 14 | New value piece | +| Follow-up 4 | 21–28 | Breakup email | + +**Best days:** Tuesday–Thursday (Thursday peaks at 6.87% reply rate). +**Best times:** 9–11 AM or 1–3 PM in prospect's local time. +**Avoid:** Monday mornings (inbox overload), Friday afternoons (checked out). + +## Angle Rotation + +Each follow-up must stand alone while building toward the goal. Never just "bump this up." + +| Email | Angle | Purpose | +| ----------- | ---------------------------------------------------------- | -------------------------- | +| Initial | Personalized hook + core value prop + soft CTA | Introduce problem/solution | +| Follow-up 1 | Different angle, new value piece (stat, insight, resource) | Show additional benefit | +| Follow-up 2 | Social proof / case study from similar company | Build credibility | +| Follow-up 3 | New insight, industry trend, or relevant resource | Demonstrate expertise | +| Follow-up 4 | Breakup — acknowledge silence, leave door open | Trigger loss aversion | + +Add only **one new value proposition per email** (SalesBread). This naturally forces different angles. + +## The Breakup Email + +Leverages loss aversion — removing pressure while creating scarcity through withdrawal. Close.com reports **10–15% response rates** from breakup emails with cold prospects. + +**Structure:** + +1. Acknowledge you've reached out multiple times +2. Validate their potential lack of interest +3. State this is your final email for now +4. Leave the door open + +**Example:** + +> I haven't heard back, so I'll assume now isn't the right time. Before I close the loop: [1-sentence insight or resource]. If that changes things, feel free to reply. Otherwise, no hard feelings — good luck with [their goal]. + +**1-2-3 Format** (reduces friction to near zero): + +> Since I haven't heard back, I'll keep it simple. Reply with a number: +> +> 1 — Interested, let's talk +> 2 — Not now, check back in 3 months +> 3 — Not interested, please stop + +**Critical rule:** If you send a breakup email, honor it. Do not contact the prospect again. + +## Phrases That Kill Response Rates + +- "I never heard back" → **12% drop** in meeting booking rate (Gong) +- "Just checking in" → Zero value, signals laziness +- "Bumping this to the top of your inbox" → Presumptuous +- "Did you see my last email?" → Guilt-tripping +- "Following up on my previous message" → Generic, adds nothing + +## CTA Adjustment by Seniority + +**Executives/founders:** Ultra-low-effort, curiosity-driven. "Curious?" or "Worth 2 min?" + +**Mid-level managers:** More specific value. "Want me to walk through how [Company] saved 15 hours/week?" + +Higher in the org chart = less friction you can ask for. diff --git a/skills/cold-email/references/frameworks.md b/skills/cold-email/references/frameworks.md new file mode 100644 index 00000000..871e0f33 --- /dev/null +++ b/skills/cold-email/references/frameworks.md @@ -0,0 +1,90 @@ +# Cold Email Copywriting Frameworks + +Frameworks beat templates — they teach thinking patterns, not copy-paste shortcuts. + +## PAS — Problem, Agitate, Solution (default) + +**Structure:** Identify pain → Amplify consequences → Present solution + soft CTA. +**Best for:** Problem-aware but not solution-aware prospects. The workhorse framework. + +> Most VP Sales at companies your size spend 5+ hours/week on manual CRM reporting. That's 250+ hours/year not spent coaching reps — and often means inaccurate forecasts reaching leadership. We built a tool that auto-generates CRM reports in real time. Teams like Datadog reduced reporting time by 80%. Would it make sense to see how? + +## BAB — Before, After, Bridge + +**Structure:** Current painful situation → Ideal future → Your product as the bridge. +**Best for:** Transformation-driven offers with clear before/after. Emotional decision-makers. + +> Right now, your team is likely spending hours manually sourcing leads — feast or famine each quarter. Imagine qualified leads arriving daily on autopilot, reps spending 100% of their time selling. That's what our platform does. Companies like HubSpot saw a 40% pipeline increase within 90 days. Can I show you how? + +## QVC — Question, Value, CTA + +**Structure:** Targeted pain question → Brief value → Direct next step. +**Best for:** C-suite prospects who prefer brevity. Qualify interest immediately. + +> Are your SDRs spending more time researching than selling? We help sales teams automate prospect research so reps focus on conversations. Clients see 3x more meetings per rep per week. Worth a 10-minute demo? + +## AIDA — Attention, Interest, Desire, Action + +**Structure:** Hook/stat → Address specific challenge → Social proof/outcome → Clear CTA. +**Best for:** Data-driven prospects, high-ticket pitches with strong stats. + +> Companies in pharma lose 30% of leads due to manual outreach. Given {{Company}}'s growth this quarter, pipeline velocity is likely top of mind. Customers like Pfizer use our platform to automate lead qualification — cutting time-to-contact by 60%. Worth a 15-minute call? + +## PPP — Praise, Picture, Push + +**Structure:** Genuine compliment → How things could be better → Gentle push to action. +**Best for:** Senior prospects who respond to relationship-building. Requires genuine trigger. + +> Your keynote on scaling SDR teams was spot-on — especially on ramp time as the hidden cost. What if you could cut that in half? Our in-inbox coach helps new reps write effective emails from day one with real-time scoring. Open to a quick chat about how this could support your growth? + +## Star-Story-Solution + +**Structure:** Introduce character (customer) → Tell challenge narrative → Reveal results. +**Best for:** Strong customer success stories. Humanizes the pitch. + +> Last year, Sarah — VP Sales at a Series B startup — had 5 SDRs competing against a rival with 20. Her team was getting crushed on volume. They adopted our AI prospecting tool and sent hyper-personalized emails at 3x pace without losing quality. Within 90 days, they booked more meetings than their competitor's entire team. Happy to share how this could work for {{Company}}. + +## SCQ — Situation, Complication, Question + +**Structure:** Current reality → Complicating challenge → Question that speaks to need → Optional answer. +**Best for:** Consultative selling. Mirrors how professionals present to leadership. + +> Your team doubled this year. That usually means onboarding is eating into selling time. How are you handling ramp for new hires? + +## ACCA — Awareness, Comprehension, Conviction, Action + +**Structure:** Contrarian hook → Explain benefit simply → Provide proof → Strong CTA. +**Best for:** Analytical buyers who need evidence (engineers, CFOs, ops leaders). + +> Most sales teams measure rep activity. The top 5% measure rep efficiency instead. When Acme switched, they booked 40% more meetings with fewer emails. Worth seeing how? + +## 3C's (Alex Berman) + +**Structure:** Compliment → Case Study → CTA. +**Best for:** Agency/services cold outreach. Case study does the heavy lifting. + +> Big fan of [Company]. We just built an app for [Competitor] that does XYZ. I have a few more ideas. Interested? + +## Mouse Trap (Lavender/Will Allred) + +**Structure:** Observation + Binary value-prop question. 1–2 sentences total. +**Best for:** Maximum brevity. Impulsive reply based on curiosity. + +> Looks like you're hiring reps. Would it be helpful to get a more granular look at how they're ramping on email? + +## Justin Michael Method + +**Structure:** Trigger/Pain → Solution hint → Binary CTA. 1–3 sentences, no intro. +**Best for:** High-velocity SDR teams. Mobile-optimized. Deliberately polarizing. + +Spend max 1 minute on personalization. Use industry/persona-level signals. For top-tier prospects, quote their own words from interviews — they almost always respond. + +## Vanilla Ice Cream (Lavender) + +**Structure:** Observation → Problem/Insight → Credibility → Solution → Call-to-Conversation. +**Best for:** Universal "base" framework that works everywhere. Five parts. + +## PASTOR (Ray Edwards) + +**Structure:** Problem → Amplify → Story → Testimony → Offer → Response. +**Best for:** Longer-form or multi-email sequences. Consulting, education, complex B2B services. Each element can be developed across separate touches. diff --git a/skills/cold-email/references/personalization.md b/skills/cold-email/references/personalization.md new file mode 100644 index 00000000..c3f98d35 --- /dev/null +++ b/skills/cold-email/references/personalization.md @@ -0,0 +1,79 @@ +# Personalization at Scale + +Personalization drives **50–250% more replies** (Lavender). The key insight: **if your personalization has nothing to do with the problem you solve, it's just an attention hack** (Clay). + +## Four Levels of Personalization + +### Level 1 — Basic (merge tags) + +First name, company name, job title. Table stakes, no longer differentiating. ~5% lift. + +### Level 2 — Industry/segment + +Industry-specific pain points, trends, regulatory challenges. Scalable via micro-segmentation. + +> Most {{industry}} teams struggle with {{lead gen problem}}, which often leads to wasted effort. + +### Level 3 — Role-level + +Challenges specific to their role and seniority. + +> As Head of Sales, keeping pipeline steady is probably your biggest headache. Your RevOps team is small, so you're likely wearing multiple hats during scaling. + +### Level 4 — Individual (gold standard) + +Specific, timely observations about that person connected to the problem you solve. + +> Noticed you're hiring 3 SDRs — sounds like you're scaling outbound fast. Most teams hit follow-up fatigue during onboarding. + +## Research Signal Stack + +| Signal | Where to find it | How to use it | +| ----------------- | ---------------------------------- | ---------------------------------------------------------------------------- | +| Recent funding | Crunchbase, LinkedIn, press | "Congrats on Series B — scaling teams fast usually creates X challenge" | +| Job postings | LinkedIn Jobs, careers page | "Noticed you're hiring 3 SDRs — sounds like you're scaling outbound" | +| Tech stack | BuiltWith, Wappalyzer, HG Insights | "I see you're using HubSpot — most teams at your stage hit a ceiling with X" | +| LinkedIn activity | Posts, comments, job changes | "Really enjoyed your post about X" | +| Company news | Google News, press releases | "Congrats on acquiring X — integrating teams usually creates Y challenge" | +| Podcast/talks | Google, YouTube, podcasts | "Caught your talk at SaaStr on X — really insightful" | +| Website changes | Manual review | "Your new pricing page caught my eye — curious how it's converting" | + +## The 3-Minute Personalization System + +From "30 Minutes to President's Club": + +**Step 1:** Build a research stack of top 10 buying signals — 5 company triggers, 5 person triggers. Stack-rank by relevance. + +**Step 2:** Build a 3x3 template: (1) personalization attached to a problem, (2) problem you solve, (3) one-sentence solution + low-friction CTA. + +**Step 3:** Create 5 "trigger templates" — pre-written personalization paragraphs for each trigger, with a smooth segue into the problem. + +The personalization must logically connect to the problem. This creates 5 reusable triggers with the rest of the email constant. A top SDR writes a personalized email in **under 3 minutes**. + +## The Four -Graphic Principles (Becc Holland) + +- **Demographic** — Age, profession, background +- **Technographic** — Tech stack, tools used +- **Firmographic** — Company size, funding, industry, growth stage +- **Psychographic** — Values, passions, beliefs (highest-impact dimension) + +Tapping into what prospects are passionate about drives significantly higher response rates. + +## Observation-Based Openers (highest performing) + +**Trigger-event:** "Congrats on the recent funding round — scaling the team from here is exciting, and I imagine [challenge] is top of mind." + +**Observation:** "Your recent post about [topic] resonated — especially the part about [detail]. Got me thinking about how that applies to [challenge]." + +**Industry insight:** "Most [role titles] I talk to spend [X hours/week] on [problem] — curious if that matches your experience at [Company]." + +## What Feels Fake (avoid) + +- AI-generated emails with similar phrasing ("I hope this email finds you well") +- Generic attention hacks disconnected from problem ("Cool that you went to UCLA!" → pitch) +- Over-personalizing to creepiness +- "I saw your LinkedIn profile and wanted to reach out" — signals mass automation + +## The "So What?" Test + +After writing any opening line, read from prospect's perspective: "So what? Why would I care?" If the answer is nothing, rewrite. diff --git a/skills/cold-email/references/subject-lines.md b/skills/cold-email/references/subject-lines.md new file mode 100644 index 00000000..3a2cc592 --- /dev/null +++ b/skills/cold-email/references/subject-lines.md @@ -0,0 +1,53 @@ +# Subject Line Optimization + +The subject line determines whether the email gets read. The data is counterintuitive: **short, boring, internal-looking subject lines win decisively.** + +## Length: 2–4 words + +- 2-word subject lines get **60% more opens** than 5-word (Lavender). +- Going from 2 to 4 words reduces replies by **17.5%**. +- 2–4 words yield **46% open rates** vs 34% for 10 words (Belkins, 5.5M emails). +- Mobile truncates at 30–35 characters — brevity is practical necessity. + +## Internal Camouflage Principle + +Subject lines that look like they came from a colleague, not a vendor, double open rates (Gong). Buyers mentally categorize before opening — if it looks like sales, it's filtered. + +**High-performing examples:** "reply rates" · "trial delays" · "hiring ops" · "employee turnover" · "Q2 forecast" · "new patients" · "personalization issue" · "second page" + +## Capitalization: lowercase wins + +All-lowercase has highest open rates (Gong, 85M+ emails). Lowercase looks more personal/internal. For cold outreach specifically, lowercase beats title case. + +## Personalization: context over name + +Personalized subject lines boost opens **26–50%**, but type matters: + +- **First name in subject line → 12% fewer replies.** Signals automation. +- **Contextual personalization works:** pain points, competitors, trigger events, industry challenges. +- Use {{painPoint}}, {{competitor}}, {{commonGround}} — not {{firstName}}. + +## Questions: only when highly specific + +Data conflicts: Belkins says questions perform well (46% open rate). Lavender says questions lower opens by **56%**. Resolution: **specific pain questions work** ("Need help with {{challenge}}?"), **generic questions fail** ("Quick question?" / "Have 15 minutes?"). Default to statements. + +## What to Avoid + +| Anti-pattern | Impact | +| ---------------------------------------------- | --------------------------- | +| Salesy language ("increase," "boost," "ROI") | -17.9% opens | +| Urgency words ("ASAP," "urgent") | Below 36% opens | +| Excessive punctuation ("!!!" or "??") | -36% opens | +| Numbers and percentages | -46% opens | +| Emojis | Hurt B2B professionalism | +| Pitching product in subject | -57% replies | +| Empty/no subject line | +30% opens but -12% replies | +| Spam triggers ("free," "guarantee," "act now") | Deliverability risk | + +## C-Suite Subject Lines + +Executives receive 300–400 emails daily, decide in seconds. They respond **23% more often** than non-C-suite when emails pass their filter (6.4% reply rate). + +What works: ultra-concise, human, understated. "{{companyInitiative}}" · "thank you" · "an update" · "a question" · reference to a specific project or trigger event. + +Anything "salesy" is immediately rejected. diff --git a/skills/content-strategy/SKILL.md b/skills/content-strategy/SKILL.md new file mode 100644 index 00000000..5c3cc305 --- /dev/null +++ b/skills/content-strategy/SKILL.md @@ -0,0 +1,374 @@ +--- +name: content-strategy +description: "Plan a content strategy, topic clusters, editorial roadmap, and content mix for traffic, authority, and lead generation. Use when deciding what to publish, what topics to prioritize, or how to structure a content program." +risk: unknown +source: "https://github.com/coreyhaines31/marketingskills" +date_added: "2026-03-21" +metadata: + version: 1.1.0 +--- + +# Content Strategy + +You are a content strategist. Your goal is to help plan content that drives traffic, builds authority, and generates leads by being either searchable, shareable, or both. + +## When to Use + +- Use when deciding what content to create, in what order, and for which audience. +- Use when building topic clusters, content pillars, or an editorial roadmap. +- Use when the user needs strategy and prioritization, not just copywriting. + +## Before Planning + +**Check for product marketing context first:** +If `.agents/product-marketing-context.md` exists (or `.claude/product-marketing-context.md` in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task. + +Gather this context (ask if not provided): + +### 1. Business Context +- What does the company do? +- Who is the ideal customer? +- What's the primary goal for content? (traffic, leads, brand awareness, thought leadership) +- What problems does your product solve? + +### 2. Customer Research +- What questions do customers ask before buying? +- What objections come up in sales calls? +- What topics appear repeatedly in support tickets? +- What language do customers use to describe their problems? + +### 3. Current State +- Do you have existing content? What's working? +- What resources do you have? (writers, budget, time) +- What content formats can you produce? (written, video, audio) + +### 4. Competitive Landscape +- Who are your main competitors? +- What content gaps exist in your market? + +--- + +## Searchable vs Shareable + +Every piece of content must be searchable, shareable, or both. Prioritize in that order—search traffic is the foundation. + +**Searchable content** captures existing demand. Optimized for people actively looking for answers. + +**Shareable content** creates demand. Spreads ideas and gets people talking. + +### When Writing Searchable Content + +- Target a specific keyword or question +- Match search intent exactly—answer what the searcher wants +- Use clear titles that match search queries +- Structure with headings that mirror search patterns +- Place keywords in title, headings, first paragraph, URL +- Provide comprehensive coverage (don't leave questions unanswered) +- Include data, examples, and links to authoritative sources +- Optimize for AI/LLM discovery: clear positioning, structured content, brand consistency across the web + +### When Writing Shareable Content + +- Lead with a novel insight, original data, or counterintuitive take +- Challenge conventional wisdom with well-reasoned arguments +- Tell stories that make people feel something +- Create content people want to share to look smart or help others +- Connect to current trends or emerging problems +- Share vulnerable, honest experiences others can learn from + +--- + +## Content Types + +### Searchable Content Types + +**Use-Case Content** +Formula: [persona] + [use-case]. Targets long-tail keywords. +- "Project management for designers" +- "Task tracking for developers" +- "Client collaboration for freelancers" + +**Hub and Spoke** +Hub = comprehensive overview. Spokes = related subtopics. +``` +/topic (hub) +├── /topic/subtopic-1 (spoke) +├── /topic/subtopic-2 (spoke) +└── /topic/subtopic-3 (spoke) +``` +Create hub first, then build spokes. Interlink strategically. + +**Note:** Most content works fine under `/blog`. Only use dedicated hub/spoke URL structures for major topics with layered depth (e.g., Atlassian's `/agile` guide). For typical blog posts, `/blog/post-title` is sufficient. + +**Template Libraries** +High-intent keywords + product adoption. +- Target searches like "marketing plan template" +- Provide immediate standalone value +- Show how product enhances the template + +### Shareable Content Types + +**Thought Leadership** +- Articulate concepts everyone feels but hasn't named +- Challenge conventional wisdom with evidence +- Share vulnerable, honest experiences + +**Data-Driven Content** +- Product data analysis (anonymized insights) +- Public data analysis (uncover patterns) +- Original research (run experiments, share results) + +**Expert Roundups** +15-30 experts answering one specific question. Built-in distribution. + +**Case Studies** +Structure: Challenge → Solution → Results → Key learnings + +**Meta Content** +Behind-the-scenes transparency. "How We Got Our First $5k MRR," "Why We Chose Debt Over VC." + +For programmatic content at scale, see **programmatic-seo** skill. + +--- + +## Content Pillars and Topic Clusters + +Content pillars are the 3-5 core topics your brand will own. Each pillar spawns a cluster of related content. + +Most of the time, all content can live under `/blog` with good internal linking between related posts. Dedicated pillar pages with custom URL structures (like `/guides/topic`) are only needed when you're building comprehensive resources with multiple layers of depth. + +### How to Identify Pillars + +1. **Product-led**: What problems does your product solve? +2. **Audience-led**: What does your ICP need to learn? +3. **Search-led**: What topics have volume in your space? +4. **Competitor-led**: What are competitors ranking for? + +### Pillar Structure + +``` +Pillar Topic (Hub) +├── Subtopic Cluster 1 +│ ├── Article A +│ ├── Article B +│ └── Article C +├── Subtopic Cluster 2 +│ ├── Article D +│ ├── Article E +│ └── Article F +└── Subtopic Cluster 3 + ├── Article G + ├── Article H + └── Article I +``` + +### Pillar Criteria + +Good pillars should: +- Align with your product/service +- Match what your audience cares about +- Have search volume and/or social interest +- Be broad enough for many subtopics + +--- + +## Keyword Research by Buyer Stage + +Map topics to the buyer's journey using proven keyword modifiers: + +### Awareness Stage +Modifiers: "what is," "how to," "guide to," "introduction to" + +Example: If customers ask about project management basics: +- "What is Agile Project Management" +- "Guide to Sprint Planning" +- "How to Run a Standup Meeting" + +### Consideration Stage +Modifiers: "best," "top," "vs," "alternatives," "comparison" + +Example: If customers evaluate multiple tools: +- "Best Project Management Tools for Remote Teams" +- "Asana vs Trello vs Monday" +- "Basecamp Alternatives" + +### Decision Stage +Modifiers: "pricing," "reviews," "demo," "trial," "buy" + +Example: If pricing comes up in sales calls: +- "Project Management Tool Pricing Comparison" +- "How to Choose the Right Plan" +- "[Product] Reviews" + +### Implementation Stage +Modifiers: "templates," "examples," "tutorial," "how to use," "setup" + +Example: If support tickets show implementation struggles: +- "Project Template Library" +- "Step-by-Step Setup Tutorial" +- "How to Use [Feature]" + +--- + +## Content Ideation Sources + +### 1. Keyword Data + +If user provides keyword exports (Ahrefs, SEMrush, GSC), analyze for: +- Topic clusters (group related keywords) +- Buyer stage (awareness/consideration/decision/implementation) +- Search intent (informational, commercial, transactional) +- Quick wins (low competition + decent volume + high relevance) +- Content gaps (keywords competitors rank for that you don't) + +Output as prioritized table: +| Keyword | Volume | Difficulty | Buyer Stage | Content Type | Priority | + +### 2. Call Transcripts + +If user provides sales or customer call transcripts, extract: +- Questions asked → FAQ content or blog posts +- Pain points → problems in their own words +- Objections → content to address proactively +- Language patterns → exact phrases to use (voice of customer) +- Competitor mentions → what they compared you to + +Output content ideas with supporting quotes. + +### 3. Survey Responses + +If user provides survey data, mine for: +- Open-ended responses (topics and language) +- Common themes (30%+ mention = high priority) +- Resource requests (what they wish existed) +- Content preferences (formats they want) + +### 4. Forum Research + +Use web search to find content ideas: + +**Reddit:** `site:reddit.com [topic]` +- Top posts in relevant subreddits +- Questions and frustrations in comments +- Upvoted answers (validates what resonates) + +**Quora:** `site:quora.com [topic]` +- Most-followed questions +- Highly upvoted answers + +**Other:** Indie Hackers, Hacker News, Product Hunt, industry Slack/Discord + +Extract: FAQs, misconceptions, debates, problems being solved, terminology used. + +### 5. Competitor Analysis + +Use web search to analyze competitor content: + +**Find their content:** `site:competitor.com/blog` + +**Analyze:** +- Top-performing posts (comments, shares) +- Topics covered repeatedly +- Gaps they haven't covered +- Case studies (customer problems, use cases, results) +- Content structure (pillars, categories, formats) + +**Identify opportunities:** +- Topics you can cover better +- Angles they're missing +- Outdated content to improve on + +### 6. Sales and Support Input + +Extract from customer-facing teams: +- Common objections +- Repeated questions +- Support ticket patterns +- Success stories +- Feature requests and underlying problems + +--- + +## Prioritizing Content Ideas + +Score each idea on four factors: + +### 1. Customer Impact (40%) +- How frequently did this topic come up in research? +- What percentage of customers face this challenge? +- How emotionally charged was this pain point? +- What's the potential LTV of customers with this need? + +### 2. Content-Market Fit (30%) +- Does this align with problems your product solves? +- Can you offer unique insights from customer research? +- Do you have customer stories to support this? +- Will this naturally lead to product interest? + +### 3. Search Potential (20%) +- What's the monthly search volume? +- How competitive is this topic? +- Are there related long-tail opportunities? +- Is search interest growing or declining? + +### 4. Resource Requirements (10%) +- Do you have expertise to create authoritative content? +- What additional research is needed? +- What assets (graphics, data, examples) will you need? + +### Scoring Template + +| Idea | Customer Impact (40%) | Content-Market Fit (30%) | Search Potential (20%) | Resources (10%) | Total | +|------|----------------------|-------------------------|----------------------|-----------------|-------| +| Topic A | 8 | 9 | 7 | 6 | 8.0 | +| Topic B | 6 | 7 | 9 | 8 | 7.1 | + +--- + +## Output Format + +When creating a content strategy, provide: + +### 1. Content Pillars +- 3-5 pillars with rationale +- Subtopic clusters for each pillar +- How pillars connect to product + +### 2. Priority Topics +For each recommended piece: +- Topic/title +- Searchable, shareable, or both +- Content type (use-case, hub/spoke, thought leadership, etc.) +- Target keyword and buyer stage +- Why this topic (customer research backing) + +### 3. Topic Cluster Map +Visual or structured representation of how content interconnects. + +--- + +## Task-Specific Questions + +1. What patterns emerge from your last 10 customer conversations? +2. What questions keep coming up in sales calls? +3. Where are competitors' content efforts falling short? +4. What unique insights from customer research aren't being shared elsewhere? +5. Which existing content drives the most conversions, and why? + +--- + +## References + +- **[Headless CMS Guide](references/headless-cms.md)**: CMS selection, content modeling for marketing, editorial workflows, platform comparison (Sanity, Contentful, Strapi) + +--- + +## Related Skills + +- **copywriting**: For writing individual content pieces +- **seo-audit**: For technical SEO and on-page optimization +- **ai-seo**: For optimizing content for AI search engines and getting cited by LLMs +- **programmatic-seo**: For scaled content generation +- **site-architecture**: For page hierarchy, navigation design, and URL structure +- **email-sequence**: For email-based content +- **social-content**: For social media content diff --git a/skills/content-strategy/evals/evals.json b/skills/content-strategy/evals/evals.json new file mode 100644 index 00000000..f107352a --- /dev/null +++ b/skills/content-strategy/evals/evals.json @@ -0,0 +1,90 @@ +{ + "skill_name": "content-strategy", + "evals": [ + { + "id": 1, + "prompt": "Help me build a content strategy for our B2B SaaS product. We sell expense management software to finance teams at companies with 50-500 employees. We currently have no blog and want to start from scratch.", + "expected_output": "Should check for product-marketing-context.md first. Should establish content pillars (3-5 core topic areas). Should map content types by buyer stage (awareness → consideration → decision → implementation). Should identify keyword research opportunities by buyer stage. Should recommend a mix of searchable (SEO-driven) and shareable (thought leadership, data) content. Should use the prioritization scoring framework (customer impact 40%, content-market fit 30%, search potential 20%, resources 10%). Should provide an initial content calendar or publishing cadence. Should recommend content types appropriate for starting from scratch.", + "assertions": [ + "Checks for product-marketing-context.md", + "Establishes 3-5 content pillars", + "Maps content by buyer stage (awareness through implementation)", + "Includes keyword research by buyer stage", + "Recommends mix of searchable and shareable content", + "Uses prioritization scoring framework", + "Provides publishing cadence or calendar", + "Recommends appropriate starting content types" + ], + "files": [] + }, + { + "id": 2, + "prompt": "We have 200+ blog posts but traffic has been flat for a year. Our content feels random — no clear strategy. How do we fix this?", + "expected_output": "Should diagnose the 'random content' problem. Should recommend a content audit process to evaluate existing posts. Should introduce content pillars and topical clustering to organize the existing library. Should identify hub-and-spoke opportunities from existing content. Should recommend which posts to update, consolidate, or retire. Should use the prioritization framework to plan next steps. Should address topical authority building through clusters.", + "assertions": [ + "Diagnoses the 'random content' problem", + "Recommends content audit for existing posts", + "Introduces content pillars and topical clustering", + "Identifies hub-and-spoke opportunities", + "Recommends update, consolidate, or retire decisions", + "Uses prioritization framework", + "Addresses topical authority building" + ], + "files": [] + }, + { + "id": 3, + "prompt": "what kind of content should we be creating? we're a developer tool (API testing platform) and our audience is backend developers and QA engineers", + "expected_output": "Should trigger on casual phrasing. Should recommend content types appropriate for a developer audience: technical tutorials, documentation-style guides, use-case content, template/example libraries, data-driven benchmarks. Should note that developer audiences prefer depth, accuracy, and practical value over marketing fluff. Should suggest content pillars aligned with developer interests. Should use the ideation sources framework (keyword data, community forums like Stack Overflow/Reddit, competitor gaps).", + "assertions": [ + "Triggers on casual phrasing", + "Recommends content types for developer audience", + "Emphasizes technical depth and practical value", + "Notes developers prefer substance over marketing", + "Suggests content pillars for developer tool", + "Uses ideation sources framework", + "Mentions developer community channels" + ], + "files": [] + }, + { + "id": 4, + "prompt": "How should we prioritize which content to create first? We have a list of 50 blog post ideas but limited resources — one content marketer writing 2 posts per week.", + "expected_output": "Should apply the prioritization scoring framework: customer impact (40%), content-market fit (30%), search potential (20%), resources required (10%). Should help score or rank the content ideas using this framework. Should recommend focusing on high-impact, lower-effort content first. Should consider the buyer stage distribution (don't write only top-of-funnel). Should provide a practical workflow for the single content marketer to use going forward.", + "assertions": [ + "Applies prioritization scoring framework with weights", + "Explains each scoring dimension", + "Recommends focusing on high-impact, lower-effort first", + "Considers buyer stage distribution", + "Provides practical workflow for limited resources" + ], + "files": [] + }, + { + "id": 5, + "prompt": "We want to build topical authority in 'employee engagement.' What does a content cluster look like for this topic?", + "expected_output": "Should apply the hub-and-spoke content cluster model. Should design a pillar page for 'employee engagement' (comprehensive, 3000+ word guide). Should identify 8-15 supporting spoke articles targeting long-tail keywords related to employee engagement. Should map the internal linking structure between hub and spokes. Should address keyword research for the cluster. Should recommend content types for each piece (guide, how-to, template, data-driven, etc.).", + "assertions": [ + "Applies hub-and-spoke content cluster model", + "Designs a pillar page for the core topic", + "Identifies 8-15 supporting spoke articles", + "Maps internal linking between hub and spokes", + "Addresses keyword research for the cluster", + "Recommends content types for each piece" + ], + "files": [] + }, + { + "id": 6, + "prompt": "Can you write a blog post about remote work best practices for our HR software blog?", + "expected_output": "Should recognize this is a copywriting/content creation task, not a content strategy task. Should defer to or cross-reference the copywriting skill for writing individual pieces of content. May provide strategic context (where this fits in the content strategy, keyword targeting, audience) but should make clear that copywriting is the right skill for writing the actual content.", + "assertions": [ + "Recognizes this as content creation, not strategy", + "References or defers to copywriting skill", + "Does not attempt to write the full blog post", + "May provide strategic context for the piece" + ], + "files": [] + } + ] +} diff --git a/skills/content-strategy/references/headless-cms.md b/skills/content-strategy/references/headless-cms.md new file mode 100644 index 00000000..61ef10ed --- /dev/null +++ b/skills/content-strategy/references/headless-cms.md @@ -0,0 +1,194 @@ +# Headless CMS Guide + +Reference for choosing, modeling, and implementing a headless CMS for marketing content. + +## When to Use This Reference + +Use this when selecting a CMS for a new project, designing content models for marketing sites, setting up editorial workflows, or connecting CMS content to programmatic pages. + +--- + +## Headless vs Traditional CMS + +A headless CMS separates content management from presentation. Content is stored in a structured backend and delivered via API to any frontend. + +### When Headless Makes Sense + +- Multiple frontends consume the same content (web, mobile, email) +- Developers want full control over the frontend stack +- Content needs to be reused across channels +- You're building with a modern framework (Next.js, Remix, Astro) +- Marketing needs structured, reusable content blocks + +### When Traditional Works Better + +- Small team with no dedicated developers +- Simple blog or brochure site +- WYSIWYG editing is a hard requirement +- Budget is tight and WordPress/Webflow does the job + +### Decision Checklist + +| Factor | Headless | Traditional | +|--------|----------|-------------| +| Multi-channel delivery | Yes | Limited | +| Developer control | Full | Constrained | +| Non-technical editing | Requires setup | Built-in | +| Time to launch | Longer | Faster | +| Content reuse | Native | Manual | +| Hosting flexibility | Any frontend | Platform-dependent | + +--- + +## Content Modeling for Marketing + +### Core Principles + +1. **Think in types, not pages.** A "Landing Page" is a content type with fields — not an HTML file. This lets you reuse components across pages. +2. **Separate content from presentation.** Store the headline text, not the styled headline. Presentation belongs in the frontend. +3. **Design for reuse.** If testimonials appear on 5 pages, create a Testimonial type and reference it — don't duplicate. +4. **Keep models flat.** Deeply nested structures are hard to query and maintain. Prefer references over nesting. + +### Common Marketing Content Types + +| Type | Key Fields | Notes | +|------|-----------|-------| +| **Landing Page** | title, slug, hero, sections[], seo | Modular sections for flexibility | +| **Blog Post** | title, slug, body, author, category, tags, publishedAt, seo | Rich text or Portable Text body | +| **Case Study** | title, customer, challenge, solution, results, metrics[], logo | Link to related products/features | +| **Testimonial** | quote, author, role, company, avatar, rating | Reference from landing pages | +| **FAQ** | question, answer, category | Group by category for programmatic pages | +| **Author** | name, bio, avatar, social links | Reference from blog posts | +| **CTA Block** | heading, body, buttonText, buttonUrl, variant | Reusable across pages | + +### SEO Fields Checklist + +Every page-level content type needs: + +- `metaTitle` — 50-60 characters +- `metaDescription` — 150-160 characters +- `ogImage` — 1200x630px social preview +- `slug` — URL path segment +- `canonicalUrl` — optional override +- `noIndex` — boolean for excluding from search +- `structuredData` — optional JSON-LD override + +--- + +## Editorial Workflows + +### Draft → Review → Publish Cycle + +1. **Draft** — Author creates or edits content +2. **Review** — Editor reviews for accuracy, brand voice, SEO +3. **Approve** — Stakeholder signs off +4. **Schedule** — Set publish date/time +5. **Publish** — Content goes live via API + +### Preview APIs + +All major headless CMS platforms support draft previews: + +- **Sanity**: Real-time preview with `useLiveQuery` or Presentation tool +- **Contentful**: Preview API (`preview.contentful.com`) with separate access token +- **Strapi**: Draft & Publish system with `status=draft` query parameter (v5; replaces v4's `publicationState`) + +Set up a preview route in your frontend (e.g., `/api/preview`) that authenticates and renders draft content. + +### Roles and Permissions + +| Role | Can Create | Can Edit | Can Publish | Can Delete | +|------|:----------:|:--------:|:-----------:|:----------:| +| Author | Yes | Own | No | Own drafts | +| Editor | Yes | All | Yes | Drafts | +| Admin | Yes | All | Yes | All | + +Exact permission models vary by platform. Sanity uses role-based access. Contentful has space-level roles. Strapi has granular RBAC. + +--- + +## Platform Comparison + +| Feature | Sanity | Contentful | Strapi | +|---------|--------|------------|--------| +| Hosting | Cloud (managed) | Cloud (managed) | Self-hosted or Cloud | +| Query Language | GROQ | REST / GraphQL | REST / GraphQL | +| Free Tier | Generous | Limited | Open source (free) | +| Real-time Collab | Yes (built-in) | Limited | No | +| Best For | Developer flexibility | Enterprise multi-locale | Budget / self-hosted | +| Content Modeling | Schema-as-code | Web UI | Web UI or code | +| Media Handling | Built-in DAM | Built-in | Plugin-based | + +### Sanity + +**Strengths**: GROQ query language is powerful and flexible. Schema defined in code (version-controlled). Real-time collaborative editing. Portable Text for rich content. Generous free tier. + +**Considerations**: Steeper learning curve for non-developers. Studio customization requires React knowledge. Vendor lock-in on GROQ queries. + +**Marketing fit**: Best when developers and marketers collaborate closely. Strong for content-heavy sites with complex models. + +### Contentful + +**Strengths**: Mature enterprise platform. Excellent multi-locale support. Strong ecosystem of integrations. Composable content with Studio. Well-documented APIs. + +**Considerations**: Pricing scales with content types and locales. Two separate APIs (Delivery and Management). Rate limits can be tight on lower plans. + +**Marketing fit**: Best for enterprises with multi-market content needs. Good when you need established vendor reliability. + +### Strapi + +**Strengths**: Open source, self-hosted option. Full control over data. No per-seat pricing. Customizable admin panel. Plugin ecosystem. REST by default, GraphQL via plugin. + +**Considerations**: Self-hosting means you handle infrastructure. Smaller ecosystem than Sanity/Contentful. V5 migration can be significant from V4. + +**Marketing fit**: Best for teams with DevOps capability who want full control and no vendor lock-in. Good for budget-conscious projects. + +### Others Worth Knowing + +- **Hygraph** — GraphQL-native, strong for federation and multi-source content +- **Keystatic** — Git-based, good for developer-content hybrid workflows +- **Payload** — TypeScript-first, self-hosted, code-configured like Sanity +- **Builder.io** — Visual editor with headless backend, good for non-technical marketers +- **Prismic** — Slice-based content modeling, strong Next.js integration + +--- + +## Integration with Marketing Skills + +### Programmatic SEO + +Use CMS as the data source for programmatic pages. Store structured data (FAQs, comparisons, city pages) as content types and generate pages from queries. See **programmatic-seo** skill. + +### Copywriting + +CMS content models enforce consistent structure. Define fields that match your copy frameworks (headline, subheadline, social proof, CTA). See **copywriting** skill. + +### Site Architecture + +URL structure, navigation hierarchy, and internal linking all depend on how content is organized in the CMS. Plan your content model and site architecture together. See **site-architecture** skill. + +### Email Sequences + +Pull CMS content into email templates for consistent messaging across web and email. Case studies, testimonials, and blog posts can feed email nurture sequences. See **email-sequence** skill. + +--- + +## Implementation Checklist + +- [ ] Define content types based on page types and reusable blocks +- [ ] Add SEO fields to every page-level content type +- [ ] Set up preview/draft mode in your frontend +- [ ] Configure roles and permissions for your team +- [ ] Create sample content for each type before building frontend +- [ ] Set up webhook notifications for content changes (rebuild triggers) +- [ ] Document content guidelines for editors (field descriptions, character limits) +- [ ] Test content delivery performance (CDN, caching, ISR) +- [ ] Plan migration strategy if moving from existing CMS + +--- + +## Relevant Integration Guides + +- [Sanity](../../../tools/integrations/sanity.md) — GROQ queries, mutations, CLI +- [Contentful](../../../tools/integrations/contentful.md) — Delivery/Management APIs, publishing +- [Strapi](../../../tools/integrations/strapi.md) — REST CRUD, filters, document API diff --git a/skills/defuddle/SKILL.md b/skills/defuddle/SKILL.md new file mode 100644 index 00000000..63c40eba --- /dev/null +++ b/skills/defuddle/SKILL.md @@ -0,0 +1,50 @@ +--- +name: defuddle +description: Extract clean markdown content from web pages using Defuddle CLI, removing clutter and navigation to save tokens. Use instead of WebFetch when the user provides a URL to read or analyze, for online documentation, articles, blog posts, or any standard web page. +risk: unknown +source: "https://github.com/kepano/obsidian-skills" +date_added: "2026-03-21" +--- + +# Defuddle + +Use Defuddle CLI to extract clean readable content from web pages. Prefer over WebFetch for standard web pages — it removes navigation, ads, and clutter, reducing token usage. + +## When to Use + +- Use when the user provides a normal webpage URL to read, summarize, or analyze. +- Prefer it over noisy page-fetch approaches when token efficiency matters. +- Use for docs, articles, blog posts, and similar public web content. + +If not installed: `npm install -g defuddle` + +## Usage + +Always use `--md` for markdown output: + +```bash +defuddle parse --md +``` + +Save to file: + +```bash +defuddle parse --md -o content.md +``` + +Extract specific metadata: + +```bash +defuddle parse -p title +defuddle parse -p description +defuddle parse -p domain +``` + +## Output formats + +| Flag | Format | +|------|--------| +| `--md` | Markdown (default choice) | +| `--json` | JSON with both HTML and markdown | +| (none) | HTML | +| `-p ` | Specific metadata property | diff --git a/skills/internal-comms/LICENSE.txt b/skills/internal-comms/LICENSE.txt new file mode 100644 index 00000000..7a4a3ea2 --- /dev/null +++ b/skills/internal-comms/LICENSE.txt @@ -0,0 +1,202 @@ + + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright [yyyy] [name of copyright owner] + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. \ No newline at end of file diff --git a/skills/internal-comms/SKILL.md b/skills/internal-comms/SKILL.md new file mode 100644 index 00000000..8b3ead99 --- /dev/null +++ b/skills/internal-comms/SKILL.md @@ -0,0 +1,35 @@ +--- +name: internal-comms +description: "Write internal communications such as status reports, leadership updates, 3P updates, newsletters, FAQs, incident reports, and project updates using repeatable internal formats." +risk: unknown +source: "https://github.com/anthropics/skills" +date_added: "2026-03-21" +license: Complete terms in LICENSE.txt +--- + +## When to use this skill +To write internal communications, use this skill for: +- 3P updates (Progress, Plans, Problems) +- Company newsletters +- FAQ responses +- Status reports +- Leadership updates +- Project updates +- Incident reports + +## How to use this skill + +To write any internal communication: + +1. **Identify the communication type** from the request +2. **Load the appropriate guideline file** from the `examples/` directory: + - `examples/3p-updates.md` - For Progress/Plans/Problems team updates + - `examples/company-newsletter.md` - For company-wide newsletters + - `examples/faq-answers.md` - For answering frequently asked questions + - `examples/general-comms.md` - For anything else that doesn't explicitly match one of the above +3. **Follow the specific instructions** in that file for formatting, tone, and content gathering + +If the communication type doesn't match any existing guideline, ask for clarification or more context about the desired format. + +## Keywords +3P updates, company newsletter, company comms, weekly update, faqs, common questions, updates, internal comms diff --git a/skills/internal-comms/examples/3p-updates.md b/skills/internal-comms/examples/3p-updates.md new file mode 100644 index 00000000..5329bfbf --- /dev/null +++ b/skills/internal-comms/examples/3p-updates.md @@ -0,0 +1,47 @@ +## Instructions +You are being asked to write a 3P update. 3P updates stand for "Progress, Plans, Problems." The main audience is for executives, leadership, other teammates, etc. They're meant to be very succinct and to-the-point: think something you can read in 30-60sec or less. They're also for people with some, but not a lot of context on what the team does. + +3Ps can cover a team of any size, ranging all the way up to the entire company. The bigger the team, the less granular the tasks should be. For example, "mobile team" might have "shipped feature" or "fixed bugs," whereas the company might have really meaty 3Ps, like "hired 20 new people" or "closed 10 new deals." + +They represent the work of the team across a time period, almost always one week. They include three sections: +1) Progress: what the team has accomplished over the next time period. Focus mainly on things shipped, milestones achieved, tasks created, etc. +2) Plans: what the team plans to do over the next time period. Focus on what things are top-of-mind, really high priority, etc. for the team. +3) Problems: anything that is slowing the team down. This could be things like too few people, bugs or blockers that are preventing the team from moving forward, some deal that fell through, etc. + +Before writing them, make sure that you know the team name. If it's not specified, you can ask explicitly what the team name you're writing for is. + + +## Tools Available +Whenever possible, try to pull from available sources to get the information you need: +- Slack: posts from team members with their updates - ideally look for posts in large channels with lots of reactions +- Google Drive: docs written from critical team members with lots of views +- Email: emails with lots of responses of lots of content that seems relevant +- Calendar: non-recurring meetings that have a lot of importance, like product reviews, etc. + + +Try to gather as much context as you can, focusing on the things that covered the time period you're writing for: +- Progress: anything between a week ago and today +- Plans: anything from today to the next week +- Problems: anything between a week ago and today + + +If you don't have access, you can ask the user for things they want to cover. They might also include these things to you directly, in which case you're mostly just formatting for this particular format. + +## Workflow + +1. **Clarify scope**: Confirm the team name and time period (usually past week for Progress/Problems, next +week for Plans) +2. **Gather information**: Use available tools or ask the user directly +3. **Draft the update**: Follow the strict formatting guidelines +4. **Review**: Ensure it's concise (30-60 seconds to read) and data-driven + +## Formatting + +The format is always the same, very strict formatting. Never use any formatting other than this. Pick an emoji that is fun and captures the vibe of the team and update. + +[pick an emoji] [Team Name] (Dates Covered, usually a week) +Progress: [1-3 sentences of content] +Plans: [1-3 sentences of content] +Problems: [1-3 sentences of content] + +Each section should be no more than 1-3 sentences: clear, to the point. It should be data-driven, and generally include metrics where possible. The tone should be very matter-of-fact, not super prose-heavy. \ No newline at end of file diff --git a/skills/internal-comms/examples/company-newsletter.md b/skills/internal-comms/examples/company-newsletter.md new file mode 100644 index 00000000..4997a072 --- /dev/null +++ b/skills/internal-comms/examples/company-newsletter.md @@ -0,0 +1,65 @@ +## Instructions +You are being asked to write a company-wide newsletter update. You are meant to summarize the past week/month of a company in the form of a newsletter that the entire company will read. It should be maybe ~20-25 bullet points long. It will be sent via Slack and email, so make it consumable for that. + +Ideally it includes the following attributes: +- Lots of links: pulling documents from Google Drive that are very relevant, linking to prominent Slack messages in announce channels and from executives, perhgaps referencing emails that went company-wide, highlighting significant things that have happened in the company. +- Short and to-the-point: each bullet should probably be no longer than ~1-2 sentences +- Use the "we" tense, as you are part of the company. Many of the bullets should say "we did this" or "we did that" + +## Tools to use +If you have access to the following tools, please try to use them. If not, you can also let the user know directly that their responses would be better if they gave them access. + +- Slack: look for messages in channels with lots of people, with lots of reactions or lots of responses within the thread +- Email: look for things from executives that discuss company-wide announcements +- Calendar: if there were meetings with large attendee lists, particularly things like All-Hands meetings, big company announcements, etc. If there were documents attached to those meetings, those are great links to include. +- Documents: if there were new docs published in the last week or two that got a lot of attention, you can link them. These should be things like company-wide vision docs, plans for the upcoming quarter or half, things authored by critical executives, etc. +- External press: if you see references to articles or press we've received over the past week, that could be really cool too. + +If you don't have access to any of these things, you can ask the user for things they want to cover. In this case, you'll mostly just be polishing up and fitting to this format more directly. + +## Sections +The company is pretty big: 1000+ people. There are a variety of different teams and initiatives going on across the company. To make sure the update works well, try breaking it into sections of similar things. You might break into clusters like {product development, go to market, finance} or {recruiting, execution, vision}, or {external news, internal news} etc. Try to make sure the different areas of the company are highlighted well. + +## Prioritization +Focus on: +- Company-wide impact (not team-specific details) +- Announcements from leadership +- Major milestones and achievements +- Information that affects most employees +- External recognition or press + +Avoid: +- Overly granular team updates (save those for 3Ps) +- Information only relevant to small groups +- Duplicate information already communicated + +## Example Formats + +:megaphone: Company Announcements +- Announcement 1 +- Announcement 2 +- Announcement 3 + +:dart: Progress on Priorities +- Area 1 + - Sub-area 1 + - Sub-area 2 + - Sub-area 3 +- Area 2 + - Sub-area 1 + - Sub-area 2 + - Sub-area 3 +- Area 3 + - Sub-area 1 + - Sub-area 2 + - Sub-area 3 + +:pillar: Leadership Updates +- Post 1 +- Post 2 +- Post 3 + +:thread: Social Updates +- Update 1 +- Update 2 +- Update 3 diff --git a/skills/internal-comms/examples/faq-answers.md b/skills/internal-comms/examples/faq-answers.md new file mode 100644 index 00000000..395262a8 --- /dev/null +++ b/skills/internal-comms/examples/faq-answers.md @@ -0,0 +1,30 @@ +## Instructions +You are an assistant for answering questions that are being asked across the company. Every week, there are lots of questions that get asked across the company, and your goal is to try to summarize what those questions are. We want our company to be well-informed and on the same page, so your job is to produce a set of frequently asked questions that our employees are asking and attempt to answer them. Your singular job is to do two things: + +- Find questions that are big sources of confusion for lots of employees at the company, generally about things that affect a large portion of the employee base +- Attempt to give a nice summarized answer to that question in order to minimize confusion. + +Some examples of areas that may be interesting to folks: recent corporate events (fundraising, new executives, etc.), upcoming launches, hiring progress, changes to vision or focus, etc. + + +## Tools Available +You should use the company's available tools, where communication and work happens. For most companies, it looks something like this: +- Slack: questions being asked across the company - it could be questions in response to posts with lots of responses, questions being asked with lots of reactions or thumbs up to show support, or anything else to show that a large number of employees want to ask the same things +- Email: emails with FAQs written directly in them can be a good source as well +- Documents: docs in places like Google Drive, linked on calendar events, etc. can also be a good source of FAQs, either directly added or inferred based on the contents of the doc + +## Formatting +The formatting should be pretty basic: + +- *Question*: [insert question - 1 sentence] +- *Answer*: [insert answer - 1-2 sentence] + +## Guidance +Make sure you're being holistic in your questions. Don't focus too much on just the user in question or the team they are a part of, but try to capture the entire company. Try to be as holistic as you can in reading all the tools available, producing responses that are relevant to all at the company. + +## Answer Guidelines +- Base answers on official company communications when possible +- If information is uncertain, indicate that clearly +- Link to authoritative sources (docs, announcements, emails) +- Keep tone professional but approachable +- Flag if a question requires executive input or official response \ No newline at end of file diff --git a/skills/internal-comms/examples/general-comms.md b/skills/internal-comms/examples/general-comms.md new file mode 100644 index 00000000..0ea97701 --- /dev/null +++ b/skills/internal-comms/examples/general-comms.md @@ -0,0 +1,16 @@ + ## Instructions + You are being asked to write internal company communication that doesn't fit into the standard formats (3P + updates, newsletters, or FAQs). + + Before proceeding: + 1. Ask the user about their target audience + 2. Understand the communication's purpose + 3. Clarify the desired tone (formal, casual, urgent, informational) + 4. Confirm any specific formatting requirements + + Use these general principles: + - Be clear and concise + - Use active voice + - Put the most important information first + - Include relevant links and references + - Match the company's communication style \ No newline at end of file diff --git a/skills/json-canvas/SKILL.md b/skills/json-canvas/SKILL.md new file mode 100644 index 00000000..1c32b833 --- /dev/null +++ b/skills/json-canvas/SKILL.md @@ -0,0 +1,253 @@ +--- +name: json-canvas +description: Create and edit JSON Canvas files (.canvas) with nodes, edges, groups, and connections. Use when working with .canvas files, creating visual canvases, mind maps, flowcharts, or when the user mentions Canvas files in Obsidian. +risk: unknown +source: "https://github.com/kepano/obsidian-skills" +date_added: "2026-03-21" +--- + +# JSON Canvas Skill + +## When to Use + +- Use when creating or editing `.canvas` files for Obsidian. +- Use for mind maps, flowcharts, visual note structures, or connected canvases. +- Use when the user explicitly mentions JSON Canvas or Obsidian Canvas files. + +## File Structure + +A canvas file (`.canvas`) contains two top-level arrays following the [JSON Canvas Spec 1.0](https://jsoncanvas.org/spec/1.0/): + +```json +{ + "nodes": [], + "edges": [] +} +``` + +- `nodes` (optional): Array of node objects +- `edges` (optional): Array of edge objects connecting nodes + +## Common Workflows + +### 1. Create a New Canvas + +1. Create a `.canvas` file with the base structure `{"nodes": [], "edges": []}` +2. Generate unique 16-character hex IDs for each node (e.g., `"6f0ad84f44ce9c17"`) +3. Add nodes with required fields: `id`, `type`, `x`, `y`, `width`, `height` +4. Add edges referencing valid node IDs via `fromNode` and `toNode` +5. **Validate**: Parse the JSON to confirm it is valid. Verify all `fromNode`/`toNode` values exist in the nodes array + +### 2. Add a Node to an Existing Canvas + +1. Read and parse the existing `.canvas` file +2. Generate a unique ID that does not collide with existing node or edge IDs +3. Choose position (`x`, `y`) that avoids overlapping existing nodes (leave 50-100px spacing) +4. Append the new node object to the `nodes` array +5. Optionally add edges connecting the new node to existing nodes +6. **Validate**: Confirm all IDs are unique and all edge references resolve to existing nodes + +### 3. Connect Two Nodes + +1. Identify the source and target node IDs +2. Generate a unique edge ID +3. Set `fromNode` and `toNode` to the source and target IDs +4. Optionally set `fromSide`/`toSide` (top, right, bottom, left) for anchor points +5. Optionally set `label` for descriptive text on the edge +6. Append the edge to the `edges` array +7. **Validate**: Confirm both `fromNode` and `toNode` reference existing node IDs + +### 4. Edit an Existing Canvas + +1. Read and parse the `.canvas` file as JSON +2. Locate the target node or edge by `id` +3. Modify the desired attributes (text, position, color, etc.) +4. Write the updated JSON back to the file +5. **Validate**: Re-check all ID uniqueness and edge reference integrity after editing + +## Nodes + +Nodes are objects placed on the canvas. Array order determines z-index: first node = bottom layer, last node = top layer. + +### Generic Node Attributes + +| Attribute | Required | Type | Description | +|-----------|----------|------|-------------| +| `id` | Yes | string | Unique 16-char hex identifier | +| `type` | Yes | string | `text`, `file`, `link`, or `group` | +| `x` | Yes | integer | X position in pixels | +| `y` | Yes | integer | Y position in pixels | +| `width` | Yes | integer | Width in pixels | +| `height` | Yes | integer | Height in pixels | +| `color` | No | canvasColor | Preset `"1"`-`"6"` or hex (e.g., `"#FF0000"`) | + +### Text Nodes + +| Attribute | Required | Type | Description | +|-----------|----------|------|-------------| +| `text` | Yes | string | Plain text with Markdown syntax | + +```json +{ + "id": "6f0ad84f44ce9c17", + "type": "text", + "x": 0, + "y": 0, + "width": 400, + "height": 200, + "text": "# Hello World\n\nThis is **Markdown** content." +} +``` + +**Newline pitfall**: Use `\n` for line breaks in JSON strings. Do **not** use the literal `\\n` -- Obsidian renders that as the characters `\` and `n`. + +### File Nodes + +| Attribute | Required | Type | Description | +|-----------|----------|------|-------------| +| `file` | Yes | string | Path to file within the system | +| `subpath` | No | string | Link to heading or block (starts with `#`) | + +```json +{ + "id": "a1b2c3d4e5f67890", + "type": "file", + "x": 500, + "y": 0, + "width": 400, + "height": 300, + "file": "Attachments/diagram.png" +} +``` + +### Link Nodes + +| Attribute | Required | Type | Description | +|-----------|----------|------|-------------| +| `url` | Yes | string | External URL | + +```json +{ + "id": "c3d4e5f678901234", + "type": "link", + "x": 1000, + "y": 0, + "width": 400, + "height": 200, + "url": "https://obsidian.md" +} +``` + +### Group Nodes + +Groups are visual containers for organizing other nodes. Position child nodes inside the group's bounds. + +| Attribute | Required | Type | Description | +|-----------|----------|------|-------------| +| `label` | No | string | Text label for the group | +| `background` | No | string | Path to background image | +| `backgroundStyle` | No | string | `cover`, `ratio`, or `repeat` | + +```json +{ + "id": "d4e5f6789012345a", + "type": "group", + "x": -50, + "y": -50, + "width": 1000, + "height": 600, + "label": "Project Overview", + "color": "4" +} +``` + +## Edges + +Edges connect nodes via `fromNode` and `toNode` IDs. + +| Attribute | Required | Type | Default | Description | +|-----------|----------|------|---------|-------------| +| `id` | Yes | string | - | Unique identifier | +| `fromNode` | Yes | string | - | Source node ID | +| `fromSide` | No | string | - | `top`, `right`, `bottom`, or `left` | +| `fromEnd` | No | string | `none` | `none` or `arrow` | +| `toNode` | Yes | string | - | Target node ID | +| `toSide` | No | string | - | `top`, `right`, `bottom`, or `left` | +| `toEnd` | No | string | `arrow` | `none` or `arrow` | +| `color` | No | canvasColor | - | Line color | +| `label` | No | string | - | Text label | + +```json +{ + "id": "0123456789abcdef", + "fromNode": "6f0ad84f44ce9c17", + "fromSide": "right", + "toNode": "a1b2c3d4e5f67890", + "toSide": "left", + "toEnd": "arrow", + "label": "leads to" +} +``` + +## Colors + +The `canvasColor` type accepts either a hex string or a preset number: + +| Preset | Color | +|--------|-------| +| `"1"` | Red | +| `"2"` | Orange | +| `"3"` | Yellow | +| `"4"` | Green | +| `"5"` | Cyan | +| `"6"` | Purple | + +Preset color values are intentionally undefined -- applications use their own brand colors. + +## ID Generation + +Generate 16-character lowercase hexadecimal strings (64-bit random value): + +``` +"6f0ad84f44ce9c17" +"a3b2c1d0e9f8a7b6" +``` + +## Layout Guidelines + +- Coordinates can be negative (canvas extends infinitely) +- `x` increases right, `y` increases down; position is the top-left corner +- Space nodes 50-100px apart; leave 20-50px padding inside groups +- Align to grid (multiples of 10 or 20) for cleaner layouts + +| Node Type | Suggested Width | Suggested Height | +|-----------|-----------------|------------------| +| Small text | 200-300 | 80-150 | +| Medium text | 300-450 | 150-300 | +| Large text | 400-600 | 300-500 | +| File preview | 300-500 | 200-400 | +| Link preview | 250-400 | 100-200 | + +## Validation Checklist + +After creating or editing a canvas file, verify: + +1. All `id` values are unique across both nodes and edges +2. Every `fromNode` and `toNode` references an existing node ID +3. Required fields are present for each node type (`text` for text nodes, `file` for file nodes, `url` for link nodes) +4. `type` is one of: `text`, `file`, `link`, `group` +5. `fromSide`/`toSide` values are one of: `top`, `right`, `bottom`, `left` +6. `fromEnd`/`toEnd` values are one of: `none`, `arrow` +7. Color presets are `"1"` through `"6"` or valid hex (e.g., `"#FF0000"`) +8. JSON is valid and parseable + +If validation fails, check for duplicate IDs, dangling edge references, or malformed JSON strings (especially unescaped newlines in text content). + +## Complete Examples + +See [references/EXAMPLES.md](references/EXAMPLES.md) for full canvas examples including mind maps, project boards, research canvases, and flowcharts. + +## References + +- [JSON Canvas Spec 1.0](https://jsoncanvas.org/spec/1.0/) +- [JSON Canvas GitHub](https://github.com/obsidianmd/jsoncanvas) diff --git a/skills/json-canvas/references/EXAMPLES.md b/skills/json-canvas/references/EXAMPLES.md new file mode 100644 index 00000000..c94f9964 --- /dev/null +++ b/skills/json-canvas/references/EXAMPLES.md @@ -0,0 +1,329 @@ +# JSON Canvas Complete Examples + +## Simple Canvas with Text and Connections + +```json +{ + "nodes": [ + { + "id": "8a9b0c1d2e3f4a5b", + "type": "text", + "x": 0, + "y": 0, + "width": 300, + "height": 150, + "text": "# Main Idea\n\nThis is the central concept." + }, + { + "id": "1a2b3c4d5e6f7a8b", + "type": "text", + "x": 400, + "y": -100, + "width": 250, + "height": 100, + "text": "## Supporting Point A\n\nDetails here." + }, + { + "id": "2b3c4d5e6f7a8b9c", + "type": "text", + "x": 400, + "y": 100, + "width": 250, + "height": 100, + "text": "## Supporting Point B\n\nMore details." + } + ], + "edges": [ + { + "id": "3c4d5e6f7a8b9c0d", + "fromNode": "8a9b0c1d2e3f4a5b", + "fromSide": "right", + "toNode": "1a2b3c4d5e6f7a8b", + "toSide": "left" + }, + { + "id": "4d5e6f7a8b9c0d1e", + "fromNode": "8a9b0c1d2e3f4a5b", + "fromSide": "right", + "toNode": "2b3c4d5e6f7a8b9c", + "toSide": "left" + } + ] +} +``` + +## Project Board with Groups + +```json +{ + "nodes": [ + { + "id": "5e6f7a8b9c0d1e2f", + "type": "group", + "x": 0, + "y": 0, + "width": 300, + "height": 500, + "label": "To Do", + "color": "1" + }, + { + "id": "6f7a8b9c0d1e2f3a", + "type": "group", + "x": 350, + "y": 0, + "width": 300, + "height": 500, + "label": "In Progress", + "color": "3" + }, + { + "id": "7a8b9c0d1e2f3a4b", + "type": "group", + "x": 700, + "y": 0, + "width": 300, + "height": 500, + "label": "Done", + "color": "4" + }, + { + "id": "8b9c0d1e2f3a4b5c", + "type": "text", + "x": 20, + "y": 50, + "width": 260, + "height": 80, + "text": "## Task 1\n\nImplement feature X" + }, + { + "id": "9c0d1e2f3a4b5c6d", + "type": "text", + "x": 370, + "y": 50, + "width": 260, + "height": 80, + "text": "## Task 2\n\nReview PR #123", + "color": "2" + }, + { + "id": "0d1e2f3a4b5c6d7e", + "type": "text", + "x": 720, + "y": 50, + "width": 260, + "height": 80, + "text": "## Task 3\n\n~~Setup CI/CD~~" + } + ], + "edges": [] +} +``` + +## Research Canvas with Files and Links + +```json +{ + "nodes": [ + { + "id": "1e2f3a4b5c6d7e8f", + "type": "text", + "x": 300, + "y": 200, + "width": 400, + "height": 200, + "text": "# Research Topic\n\n## Key Questions\n\n- How does X affect Y?\n- What are the implications?", + "color": "5" + }, + { + "id": "2f3a4b5c6d7e8f9a", + "type": "file", + "x": 0, + "y": 0, + "width": 250, + "height": 150, + "file": "Literature/Paper A.pdf" + }, + { + "id": "3a4b5c6d7e8f9a0b", + "type": "file", + "x": 0, + "y": 200, + "width": 250, + "height": 150, + "file": "Notes/Meeting Notes.md", + "subpath": "#Key Insights" + }, + { + "id": "4b5c6d7e8f9a0b1c", + "type": "link", + "x": 0, + "y": 400, + "width": 250, + "height": 100, + "url": "https://example.com/research" + }, + { + "id": "5c6d7e8f9a0b1c2d", + "type": "file", + "x": 750, + "y": 150, + "width": 300, + "height": 250, + "file": "Attachments/diagram.png" + } + ], + "edges": [ + { + "id": "6d7e8f9a0b1c2d3e", + "fromNode": "2f3a4b5c6d7e8f9a", + "fromSide": "right", + "toNode": "1e2f3a4b5c6d7e8f", + "toSide": "left", + "label": "supports" + }, + { + "id": "7e8f9a0b1c2d3e4f", + "fromNode": "3a4b5c6d7e8f9a0b", + "fromSide": "right", + "toNode": "1e2f3a4b5c6d7e8f", + "toSide": "left", + "label": "informs" + }, + { + "id": "8f9a0b1c2d3e4f5a", + "fromNode": "4b5c6d7e8f9a0b1c", + "fromSide": "right", + "toNode": "1e2f3a4b5c6d7e8f", + "toSide": "left", + "toEnd": "arrow", + "color": "6" + }, + { + "id": "9a0b1c2d3e4f5a6b", + "fromNode": "1e2f3a4b5c6d7e8f", + "fromSide": "right", + "toNode": "5c6d7e8f9a0b1c2d", + "toSide": "left", + "label": "visualized by" + } + ] +} +``` + +## Flowchart + +```json +{ + "nodes": [ + { + "id": "a0b1c2d3e4f5a6b7", + "type": "text", + "x": 200, + "y": 0, + "width": 150, + "height": 60, + "text": "**Start**", + "color": "4" + }, + { + "id": "b1c2d3e4f5a6b7c8", + "type": "text", + "x": 200, + "y": 100, + "width": 150, + "height": 60, + "text": "Step 1:\nGather data" + }, + { + "id": "c2d3e4f5a6b7c8d9", + "type": "text", + "x": 200, + "y": 200, + "width": 150, + "height": 80, + "text": "**Decision**\n\nIs data valid?", + "color": "3" + }, + { + "id": "d3e4f5a6b7c8d9e0", + "type": "text", + "x": 400, + "y": 200, + "width": 150, + "height": 60, + "text": "Process data" + }, + { + "id": "e4f5a6b7c8d9e0f1", + "type": "text", + "x": 0, + "y": 200, + "width": 150, + "height": 60, + "text": "Request new data", + "color": "1" + }, + { + "id": "f5a6b7c8d9e0f1a2", + "type": "text", + "x": 400, + "y": 320, + "width": 150, + "height": 60, + "text": "**End**", + "color": "4" + } + ], + "edges": [ + { + "id": "a6b7c8d9e0f1a2b3", + "fromNode": "a0b1c2d3e4f5a6b7", + "fromSide": "bottom", + "toNode": "b1c2d3e4f5a6b7c8", + "toSide": "top" + }, + { + "id": "b7c8d9e0f1a2b3c4", + "fromNode": "b1c2d3e4f5a6b7c8", + "fromSide": "bottom", + "toNode": "c2d3e4f5a6b7c8d9", + "toSide": "top" + }, + { + "id": "c8d9e0f1a2b3c4d5", + "fromNode": "c2d3e4f5a6b7c8d9", + "fromSide": "right", + "toNode": "d3e4f5a6b7c8d9e0", + "toSide": "left", + "label": "Yes", + "color": "4" + }, + { + "id": "d9e0f1a2b3c4d5e6", + "fromNode": "c2d3e4f5a6b7c8d9", + "fromSide": "left", + "toNode": "e4f5a6b7c8d9e0f1", + "toSide": "right", + "label": "No", + "color": "1" + }, + { + "id": "e0f1a2b3c4d5e6f7", + "fromNode": "e4f5a6b7c8d9e0f1", + "fromSide": "top", + "fromEnd": "none", + "toNode": "b1c2d3e4f5a6b7c8", + "toSide": "left", + "toEnd": "arrow" + }, + { + "id": "f1a2b3c4d5e6f7a8", + "fromNode": "d3e4f5a6b7c8d9e0", + "fromSide": "bottom", + "toNode": "f5a6b7c8d9e0f1a2", + "toSide": "top" + } + ] +} +``` diff --git a/skills/lead-magnets/SKILL.md b/skills/lead-magnets/SKILL.md new file mode 100644 index 00000000..e73b0fd3 --- /dev/null +++ b/skills/lead-magnets/SKILL.md @@ -0,0 +1,319 @@ +--- +name: lead-magnets +description: "Plan and optimize lead magnets for email capture and lead generation. Use when designing gated content, checklists, templates, downloadable resources, or other offers that convert visitors into subscribers." +risk: unknown +source: "https://github.com/coreyhaines31/marketingskills" +date_added: "2026-03-21" +metadata: + version: 1.0.0 +--- + +# Lead Magnets + +You are an expert in lead magnet strategy. Your goal is to help plan lead magnets that capture emails, generate qualified leads, and naturally lead to product adoption. + +## When to Use + +- Use when planning downloadable offers or gated resources for email capture. +- Use when the user wants a lead magnet strategy tied to conversion and product interest. +- Use when deciding what to give away, not just writing the asset itself. + +## Before Planning + +**Check for product marketing context first:** +If `.agents/product-marketing-context.md` exists (or `.claude/product-marketing-context.md` in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task. + +Gather this context (ask if not provided): + +### 1. Business Context +- What does the company do? +- Who is the ideal customer? +- What problems does your product solve? + +### 2. Current Lead Generation +- How do you currently capture leads? +- What lead magnets or offers do you have? +- What's your current conversion rate on email capture? + +### 3. Content Assets +- What existing content could be repurposed? (blog posts, guides, data) +- What expertise can you package? +- What templates or tools do you use internally? + +### 4. Goals +- Primary goal: email list growth, lead quality, product education? +- Target audience stage: awareness, consideration, or decision? +- Timeline and resource constraints? + +--- + +## Lead Magnet Principles + +### 1. Solve a Specific Problem +- Address one clear pain point, not a broad topic +- "How to write cold emails that get replies" > "Marketing guide" + +### 2. Match the Buyer Stage +- Awareness leads need education +- Consideration leads need comparison and evaluation +- Decision leads need implementation help + +### 3. High Perceived Value, Low Time Investment +- Should look like it's worth paying for +- Consumable in under 30 minutes (ideally under 10) +- Immediate, actionable takeaway + +### 4. Natural Path to Product +- Solves a problem your product also solves +- Creates awareness of a gap your product fills +- Demonstrates your expertise in the space + +### 5. Easy to Consume +- One clear format (don't mix ebook + video + spreadsheet) +- Works on mobile +- No special software required + +--- + +## Lead Magnet Types + +| Type | Best For | Effort | Time to Create | +|------|----------|--------|----------------| +| Checklist | Quick wins, process steps | Low | 1-2 hours | +| Cheat sheet | Reference material, shortcuts | Low | 2-4 hours | +| Template (doc/spreadsheet/Notion) | Repeatable processes, workflows | Low-Med | 2-8 hours | +| Swipe file | Inspiration, examples | Medium | 4-8 hours | +| Ebook/guide | Deep education, authority | High | 1-3 weeks | +| Mini-course (email) | Education + nurture | Medium | 1-2 weeks | +| Mini-course (video) | Education + personality | High | 2-4 weeks | +| Quiz/assessment | Segmentation, engagement | Medium | 1-2 weeks | +| Webinar | Authority, live engagement | Medium | 1 week prep | +| Resource library | Ongoing value, return visits | High | Ongoing | +| Free trial/community access | Product experience | Varies | Varies | + +**For detailed creation guidance per format**: See [references/format-guide.md](references/format-guide.md) + +--- + +## Matching Lead Magnets to Buyer Stage + +### Awareness Stage +Goal: Educate on the problem. Attract people who don't know you yet. + +| Format | Example | +|--------|---------| +| Checklist | "10-Point Website Audit Checklist" | +| Cheat sheet | "SEO Cheat Sheet for Beginners" | +| Ebook/guide | "The Complete Guide to Email Marketing" | +| Quiz | "What Type of Marketer Are You?" | + +### Consideration Stage +Goal: Help evaluate solutions. Build trust and demonstrate expertise. + +| Format | Example | +|--------|---------| +| Comparison template | "CRM Comparison Spreadsheet" | +| Assessment | "Marketing Maturity Assessment" | +| Case study collection | "5 Companies That 3x'd Their Pipeline" | +| Webinar | "How to Choose the Right Analytics Tool" | + +### Decision Stage +Goal: Help implement. Remove friction to purchase. + +| Format | Example | +|--------|---------| +| Template | "Ready-to-Use Sales Email Templates" | +| Free trial | "14-Day Free Trial" | +| Implementation guide | "Migration Checklist: Switch in 30 Minutes" | +| ROI calculator | "Calculate Your Savings" (→ see **free-tool-strategy**) | + +--- + +## Gating Strategy + +### Gating Options + +| Approach | When to Use | Trade-off | +|----------|-------------|-----------| +| **Full gate** | High-value content, bottom-funnel | Max capture, lower reach | +| **Partial gate** | Preview + full version | Balance of reach and capture | +| **Ungated + optional** | Top-funnel education | Max reach, lower capture | +| **Content upgrade** | Blog post + bonus | Contextual, high-intent | + +### What to Ask For + +- **Email only** — highest conversion, lowest friction +- **Email + name** — enables personalization, slight friction increase +- **Email + company/role** — better lead qualification, more friction +- **Multi-field** — only for high-value offers (webinars, demos) + +Rule of thumb: Ask for the minimum needed. Every extra field reduces conversion by 5-10%. + +### How to Frame the Exchange + +- Make the value obvious: "Get the full 25-page guide free" +- Show a preview: table of contents, first page, sample results +- Add social proof: "Downloaded by 5,000+ marketers" +- Reduce risk: "No spam. Unsubscribe anytime." + +**For form optimization**: See **form-cro** skill +**For popup implementation**: See **popup-cro** skill + +--- + +## Landing Page & Delivery + +### Landing Page Structure + +1. **Headline** — Clear benefit: what they'll get and why it matters +2. **Preview/mockup** — Visual of the lead magnet (cover, screenshot, sample page) +3. **What's inside** — 3-5 bullet points of key takeaways +4. **Social proof** — Download count, testimonials, logos +5. **Form** — Minimal fields, clear CTA button +6. **FAQ** — Address hesitations (Is it really free? What format?) + +**For landing page optimization**: See **page-cro** skill + +### Delivery Methods + +| Method | Pros | Cons | +|--------|------|------| +| **Instant download** | Immediate gratification | No email verification | +| **Email delivery** | Verifies email, starts relationship | Slight delay | +| **Thank you page + email** | Best of both—instant access + email copy | Slightly more complex | +| **Drip delivery** | Builds habit, multiple touchpoints | Only for courses/series | + +### Thank You Page Optimization + +Don't waste the thank you page. After they've converted: +- Confirm delivery ("Check your inbox") +- Offer a next step (book a demo, start trial, join community) +- Share on social (pre-written tweet/post) +- Recommend related content + +--- + +## Promotion & Distribution + +### Blog CTAs & Content Upgrades + +- Add relevant CTAs within blog posts (inline, end-of-post) +- Create post-specific content upgrades (bonus checklist for a how-to post) +- Content upgrades convert 2-5x better than generic sidebar CTAs + +### Exit-Intent & Popups + +- Trigger on exit intent or scroll depth +- Match the popup offer to the page content +- **See popup-cro** for implementation + +### Social Media + +- Share snippets and teasers from the lead magnet +- Create carousel posts from key points +- Use the lead magnet as the CTA in your bio/profile +- **See social-content** for social strategy + +### Paid Promotion + +- Facebook/Instagram lead ads for top-funnel lead magnets +- Google Ads for high-intent lead magnets (templates, tools) +- LinkedIn for B2B lead magnets +- Retarget blog visitors with lead magnet ads +- **See paid-ads** for campaign strategy + +### Partner Co-Promotion + +- Cross-promote with complementary brands +- Guest webinars with partner audiences +- Include in partner newsletters +- Bundle in resource collections + +--- + +## Measuring Success + +### Key Metrics + +| Metric | What It Tells You | Benchmark | +|--------|-------------------|-----------| +| **Landing page conversion rate** | Offer attractiveness | 20-40% (warm traffic), 5-15% (cold) | +| **Cost per lead** | Acquisition efficiency | Varies by channel and industry | +| **Lead-to-customer rate** | Lead quality | 1-5% (B2B), varies widely | +| **Email engagement** | Content relevance | 30-50% open, 2-5% click | +| **Time to conversion** | Nurture effectiveness | Track by lead magnet source | + +**For detailed benchmarks by format and industry**: See [references/benchmarks.md](references/benchmarks.md) + +### A/B Testing Ideas + +- **Headline**: Benefit-focused vs. curiosity-driven +- **Format**: Checklist vs. guide on same topic +- **Gate level**: Full gate vs. partial preview +- **Form fields**: Email-only vs. email + name +- **CTA copy**: "Download Free Guide" vs. "Get Your Copy" +- **Delivery**: Instant download vs. email delivery + +### Lead Quality Signals + +Good lead magnet attracted quality leads if: +- Higher-than-average email engagement +- Leads progress to trial/demo at expected rates +- Low unsubscribe rate after delivery +- Leads match ICP demographics + +--- + +## Output Format + +When creating a lead magnet strategy, provide: + +### 1. Lead Magnet Recommendation +- Format and topic +- Target buyer stage +- Why this format for this audience +- Estimated creation effort + +### 2. Content Outline +- Key sections/components +- Length and scope +- What makes it unique or valuable + +### 3. Gating & Capture Plan +- What to gate and how +- Form fields +- Landing page structure + +### 4. Distribution Plan +- Promotion channels +- Content upgrade opportunities +- Paid amplification (if applicable) + +### 5. Measurement Plan +- KPIs and targets +- What to A/B test first + +--- + +## Task-Specific Questions + +1. What existing content or expertise could you turn into a lead magnet? +2. Where does your audience spend time online? +3. What's the most common question prospects ask before buying? +4. Do you have an email nurture sequence set up for new leads? +5. What's your budget for design and promotion? + +--- + +## Related Skills + +- **free-tool-strategy**: For interactive tools as lead magnets (calculators, graders, quizzes) +- **copywriting**: For writing the lead magnet content itself +- **email-sequence**: For nurture sequences after lead capture +- **page-cro**: For optimizing lead magnet landing pages +- **popup-cro**: For popup-based lead capture +- **form-cro**: For optimizing capture forms +- **content-strategy**: For content planning and topic selection +- **analytics-tracking**: For measuring lead magnet performance +- **paid-ads**: For paid promotion of lead magnets +- **social-content**: For social media promotion diff --git a/skills/lead-magnets/references/benchmarks.md b/skills/lead-magnets/references/benchmarks.md new file mode 100644 index 00000000..e54e9485 --- /dev/null +++ b/skills/lead-magnets/references/benchmarks.md @@ -0,0 +1,129 @@ +# Lead Magnet Benchmarks + +Reference data for planning and evaluating lead magnet performance. + +--- + +## Conversion Rate Benchmarks + +### By Format Type + +| Format | Landing Page Conversion | Notes | +|--------|------------------------|-------| +| Checklist | 30-50% | High because low commitment | +| Cheat sheet | 25-40% | Quick reference appeal | +| Template | 25-45% | Immediate utility drives conversion | +| Ebook/guide | 20-35% | Higher commitment, lower rate | +| Quiz | 30-50% | Engagement drives completion | +| Webinar | 20-40% (registration) | 30-50% attendance rate of registrants | +| Mini-course | 15-30% | Higher commitment, higher quality leads | +| Free trial | 5-15% | High intent but high friction | + +### By Traffic Source + +| Source | Expected Conversion | Why | +|--------|-------------------|-----| +| Blog content upgrade | 3-8% of post readers | Contextually relevant | +| Dedicated landing page (organic) | 20-40% | High intent | +| Dedicated landing page (paid) | 10-25% | Cold traffic | +| Exit-intent popup | 2-5% of visitors | Interruption-based | +| Sidebar/banner CTA | 0.5-2% | Low engagement | +| Social media link | 10-20% | Warm but browsing | + +### By Industry (Landing Page) + +| Industry | Average Conversion | +|----------|-------------------| +| SaaS/Tech | 15-25% | +| Marketing/Agency | 20-35% | +| Finance | 10-20% | +| E-commerce | 10-20% | +| Education | 20-35% | +| Health/Wellness | 15-25% | + +--- + +## Lead Quality Indicators + +### Signals of High-Quality Leads +- Open first 3 emails at 40%+ rate +- Click through to content or product pages +- Return to site within 30 days +- Match ICP demographics (role, company size, industry) +- Progress to trial, demo, or purchase within 90 days + +### Signals of Low-Quality Leads +- Unsubscribe within first 3 emails +- Never open beyond delivery email +- Use disposable email addresses +- Don't match target customer profile +- Downloaded for the content, no product interest + +### Quality vs. Quantity by Format + +| Format | Lead Volume | Lead Quality | Net Value | +|--------|-------------|-------------|-----------| +| Generic ebook | High | Low-Medium | Medium | +| Specific template | Medium | High | High | +| Industry report | Medium | Medium-High | High | +| Quiz/assessment | High | Medium (segmentable) | High | +| Webinar | Low-Medium | High | High | +| Checklist | High | Low-Medium | Medium | +| Free trial | Low | Very High | Very High | + +--- + +## Cost Benchmarks + +### Cost Per Lead by Channel + +| Channel | Typical CPL | Notes | +|---------|-------------|-------| +| Organic search | $0-5 | Lowest, but slow to build | +| Blog content upgrade | $0-2 | Nearly free if you have traffic | +| Facebook/Instagram Ads | $3-15 | B2C lower, B2B higher | +| Google Ads | $10-50 | High intent, higher cost | +| LinkedIn Ads | $25-75 | B2B, expensive but qualified | +| Partner co-promotion | $0-5 | Depends on relationship | + +### Creation Cost by Format + +| Format | DIY Cost | With Designer/Freelancer | +|--------|----------|-------------------------| +| Checklist | Free | $100-300 | +| Cheat sheet | Free | $200-500 | +| Template | Free | $100-500 | +| Ebook (10-25 pages) | Free | $500-2,000 | +| Quiz | $0-100/mo (tool) | $500-2,000 | +| Webinar | Free (Zoom) | $500-1,500 (production) | +| Mini-course (email) | Free | $500-1,500 (copywriting) | +| Video course | $0-200 (gear) | $2,000-5,000 | + +--- + +## Timeline Expectations + +### Time to Create + +| Format | Solo Creator | With Team | +|--------|-------------|-----------| +| Checklist | 1-2 hours | Same day | +| Cheat sheet | 2-4 hours | Same day | +| Template | 2-8 hours | 1-2 days | +| Swipe file | 4-8 hours | 1-2 days | +| Ebook | 1-3 weeks | 1-2 weeks | +| Quiz | 1-2 weeks | 1 week | +| Webinar prep | 1 week | 3-5 days | +| Mini-course | 1-2 weeks | 1 week | + +### Time to See Results + +| Phase | Timeline | +|-------|----------| +| First leads | Immediately with existing traffic or paid | +| Organic traffic growth | 2-6 months (SEO) | +| Meaningful lead volume | 1-3 months | +| Measurable impact on pipeline | 3-6 months | +| Full ROI assessment | 6-12 months | + +**Note**: These benchmarks are general guidelines. Your actual results depend on audience, niche, traffic volume, and offer quality. Start measuring from day one and build your own benchmarks. diff --git a/skills/lead-magnets/references/format-guide.md b/skills/lead-magnets/references/format-guide.md new file mode 100644 index 00000000..b4f7f790 --- /dev/null +++ b/skills/lead-magnets/references/format-guide.md @@ -0,0 +1,196 @@ +# Lead Magnet Format Guide + +Detailed creation guidance for each lead magnet format. + +## Contents +- Ebooks & Guides +- Checklists +- Cheat Sheets +- Templates & Spreadsheets +- Swipe Files +- Mini-Courses +- Quizzes & Assessments +- Webinars & Workshops + +--- + +## Ebooks & Guides + +**Best for**: Building authority, deep education, awareness-stage leads + +**Structure**: +1. Title page with professional design +2. Table of contents +3. Introduction — frame the problem, set expectations +4. 3-7 chapters — one key concept per chapter +5. Summary — recap key takeaways +6. CTA — next step toward your product + +**Guidelines**: +- Ideal length: 10-25 pages (shorter is fine if valuable) +- Include visuals: charts, diagrams, screenshots +- Use callout boxes for key stats or quotes +- End each chapter with a quick takeaway +- Don't pad — density beats length + +**Tools**: Canva, Google Docs → PDF, Notion export, Designrr, Beacon.by + +--- + +## Checklists + +**Best for**: Process-oriented tasks, quick wins, implementation help + +**Structure**: +- Title: "[Number]-Point [Topic] Checklist" +- Numbered or checkbox items +- Group into logical sections if 10+ items +- Brief explanation per item (1-2 sentences) + +**Guidelines**: +- Keep to 1-2 pages +- Use actionable language ("Verify X", "Set up Y", "Remove Z") +- Order by workflow sequence or priority +- Make it printable — clean layout, generous spacing +- Include a "done" checkbox for each item + +**What works**: Step-by-step processes, audit criteria, launch checklists, setup guides + +--- + +## Cheat Sheets + +**Best for**: Reference material, shortcuts, quick-lookup information + +**Structure**: +- One page (two pages max) +- Organized by category or workflow +- Dense but scannable +- Visual hierarchy with headers and grouping + +**Guidelines**: +- Optimize for quick reference, not reading +- Use tables, grids, or columns +- Include formulas, shortcuts, or code snippets +- Design for printing or saving as desktop reference +- Bold the most important items + +**What works**: Keyboard shortcuts, formula references, terminology glossaries, decision matrices + +--- + +## Templates & Spreadsheets + +**Best for**: Repeatable processes, planning, tracking + +### Spreadsheet Templates (Google Sheets / Excel) +- Include a "How to Use" tab with instructions +- Pre-fill with example data +- Use data validation for dropdown fields +- Add conditional formatting for visual cues +- Lock formula cells, leave input cells editable +- Include a "Make a Copy" link (Google Sheets) + +### Notion Templates +- Provide a duplicate link +- Include a getting-started guide +- Pre-populate with example content +- Use Notion's database features (views, filters, relations) +- Keep it simple — don't over-engineer + +### Document Templates +- Provide in multiple formats (Google Doc, Word, PDF) +- Include placeholder text with [BRACKETS] for customization +- Add inline instructions in a different color +- Make it immediately usable with minimal editing + +**Key principle**: Templates should be usable within 5 minutes of downloading. + +--- + +## Swipe Files + +**Best for**: Inspiration, examples, learning from others + +**Structure**: +- Curated collection of 15-50 examples +- Organized by category, type, or use case +- Each example includes: + - The example itself (screenshot, text, link) + - Why it works (2-3 bullet annotations) + - How to adapt it (1-2 sentences) + +**Guidelines**: +- Quality over quantity — curate ruthlessly +- Add your analysis, don't just collect +- Organize for browsing (categories, tags) +- Update periodically with fresh examples +- Credit original sources + +**What works**: Email subject lines, landing pages, ad copy, CTAs, onboarding flows, pricing pages + +--- + +## Mini-Courses + +### Email-Based Mini-Courses +- 3-5 emails delivered over 5-7 days +- One lesson per email, one concept per lesson +- Each email: teach → example → exercise +- Progressive difficulty (build on previous lessons) +- Final email: summary + CTA for product or next step + +### Video-Based Mini-Courses +- 3-5 videos, 5-15 minutes each +- Host on unlisted YouTube, Loom, or course platform +- Deliver links via email drip +- Include worksheets or exercises per lesson +- More personal — builds stronger connection + +**Cadence**: Every 1-2 days. Don't stretch too thin or compress too tight. + +**Key principle**: Each lesson should deliver standalone value. If someone only watches lesson 2, they should still learn something useful. + +--- + +## Quizzes & Assessments + +**Best for**: Engagement, segmentation, personalized results + +**Question Design**: +- 5-10 questions (sweet spot: 7) +- Multiple choice only — no open-ended +- Questions should feel insightful, not obvious +- Progress indicator ("Question 3 of 7") + +**Result Segmentation**: +- 3-5 result categories +- Each result: name, description, personalized recommendations +- Tailor follow-up emails by result type +- Share-worthy result format ("I got: Growth Stage Marketer!") + +**Implementation**: Gate results behind email capture. The quiz itself is ungated — the personalized results require an email. + +**For building interactive quizzes**: See **free-tool-strategy** skill for technical implementation guidance. + +--- + +## Webinars & Workshops + +### Live Webinars +- 30-45 minutes teaching + 15 minutes Q&A +- Structure: Hook → Teach (3 key points) → Demo/example → CTA +- Promote 1-2 weeks in advance +- Send 3 reminder emails (confirmation, day before, 1 hour before) +- Record for replay (extends value) + +### Evergreen Webinars +- Pre-recorded, available on demand +- Same structure as live but tighter editing +- Always-on lead generation +- Gate with email registration +- Automated follow-up sequence + +**Follow-up**: Send replay link + summary + CTA within 24 hours. Continue with nurture sequence. + +**Key principle**: Teach something genuinely useful. A webinar that's just a sales pitch will damage trust. diff --git a/skills/obsidian-bases/SKILL.md b/skills/obsidian-bases/SKILL.md new file mode 100644 index 00000000..c429b3c2 --- /dev/null +++ b/skills/obsidian-bases/SKILL.md @@ -0,0 +1,506 @@ +--- +name: obsidian-bases +description: Create and edit Obsidian Bases (.base files) with views, filters, formulas, and summaries. Use when working with .base files, creating database-like views of notes, or when the user mentions Bases, table views, card views, filters, or formulas in Obsidian. +risk: unknown +source: "https://github.com/kepano/obsidian-skills" +date_added: "2026-03-21" +--- + +# Obsidian Bases Skill + +## When to Use + +- Use when creating or editing `.base` files in Obsidian. +- Use for database-like note views with filters, formulas, summaries, or cards/tables. +- Use when the user asks about Obsidian Bases specifically. + +## Workflow + +1. **Create the file**: Create a `.base` file in the vault with valid YAML content +2. **Define scope**: Add `filters` to select which notes appear (by tag, folder, property, or date) +3. **Add formulas** (optional): Define computed properties in the `formulas` section +4. **Configure views**: Add one or more views (`table`, `cards`, `list`, or `map`) with `order` specifying which properties to display +5. **Validate**: Verify the file is valid YAML with no syntax errors. Check that all referenced properties and formulas exist. Common issues: unquoted strings containing special YAML characters, mismatched quotes in formula expressions, referencing `formula.X` without defining `X` in `formulas` +6. **Test in Obsidian**: Open the `.base` file in Obsidian to confirm the view renders correctly. If it shows a YAML error, check quoting rules below + +## Schema + +Base files use the `.base` extension and contain valid YAML. + +```yaml +# Global filters apply to ALL views in the base +filters: + # Can be a single filter string + # OR a recursive filter object with and/or/not + and: [] + or: [] + not: [] + +# Define formula properties that can be used across all views +formulas: + formula_name: 'expression' + +# Configure display names and settings for properties +properties: + property_name: + displayName: "Display Name" + formula.formula_name: + displayName: "Formula Display Name" + file.ext: + displayName: "Extension" + +# Define custom summary formulas +summaries: + custom_summary_name: 'values.mean().round(3)' + +# Define one or more views +views: + - type: table | cards | list | map + name: "View Name" + limit: 10 # Optional: limit results + groupBy: # Optional: group results + property: property_name + direction: ASC | DESC + filters: # View-specific filters + and: [] + order: # Properties to display in order + - file.name + - property_name + - formula.formula_name + summaries: # Map properties to summary formulas + property_name: Average +``` + +## Filter Syntax + +Filters narrow down results. They can be applied globally or per-view. + +### Filter Structure + +```yaml +# Single filter +filters: 'status == "done"' + +# AND - all conditions must be true +filters: + and: + - 'status == "done"' + - 'priority > 3' + +# OR - any condition can be true +filters: + or: + - 'file.hasTag("book")' + - 'file.hasTag("article")' + +# NOT - exclude matching items +filters: + not: + - 'file.hasTag("archived")' + +# Nested filters +filters: + or: + - file.hasTag("tag") + - and: + - file.hasTag("book") + - file.hasLink("Textbook") + - not: + - file.hasTag("book") + - file.inFolder("Required Reading") +``` + +### Filter Operators + +| Operator | Description | +|----------|-------------| +| `==` | equals | +| `!=` | not equal | +| `>` | greater than | +| `<` | less than | +| `>=` | greater than or equal | +| `<=` | less than or equal | +| `&&` | logical and | +| `\|\|` | logical or | +| ! | logical not | + +## Properties + +### Three Types of Properties + +1. **Note properties** - From frontmatter: `note.author` or just `author` +2. **File properties** - File metadata: `file.name`, `file.mtime`, etc. +3. **Formula properties** - Computed values: `formula.my_formula` + +### File Properties Reference + +| Property | Type | Description | +|----------|------|-------------| +| `file.name` | String | File name | +| `file.basename` | String | File name without extension | +| `file.path` | String | Full path to file | +| `file.folder` | String | Parent folder path | +| `file.ext` | String | File extension | +| `file.size` | Number | File size in bytes | +| `file.ctime` | Date | Created time | +| `file.mtime` | Date | Modified time | +| `file.tags` | List | All tags in file | +| `file.links` | List | Internal links in file | +| `file.backlinks` | List | Files linking to this file | +| `file.embeds` | List | Embeds in the note | +| `file.properties` | Object | All frontmatter properties | + +### The `this` Keyword + +- In main content area: refers to the base file itself +- When embedded: refers to the embedding file +- In sidebar: refers to the active file in main content + +## Formula Syntax + +Formulas compute values from properties. Defined in the `formulas` section. + +```yaml +formulas: + # Simple arithmetic + total: "price * quantity" + + # Conditional logic + status_icon: 'if(done, "✅", "⏳")' + + # String formatting + formatted_price: 'if(price, price.toFixed(2) + " dollars")' + + # Date formatting + created: 'file.ctime.format("YYYY-MM-DD")' + + # Calculate days since created (use .days for Duration) + days_old: '(now() - file.ctime).days' + + # Calculate days until due date + days_until_due: 'if(due_date, (date(due_date) - today()).days, "")' +``` + +## Key Functions + +Most commonly used functions. For the complete reference of all types (Date, String, Number, List, File, Link, Object, RegExp), see [FUNCTIONS_REFERENCE.md](references/FUNCTIONS_REFERENCE.md). + +| Function | Signature | Description | +|----------|-----------|-------------| +| `date()` | `date(string): date` | Parse string to date (`YYYY-MM-DD HH:mm:ss`) | +| `now()` | `now(): date` | Current date and time | +| `today()` | `today(): date` | Current date (time = 00:00:00) | +| `if()` | `if(condition, trueResult, falseResult?)` | Conditional | +| `duration()` | `duration(string): duration` | Parse duration string | +| `file()` | `file(path): file` | Get file object | +| `link()` | `link(path, display?): Link` | Create a link | + +### Duration Type + +When subtracting two dates, the result is a **Duration** type (not a number). + +**Duration Fields:** `duration.days`, `duration.hours`, `duration.minutes`, `duration.seconds`, `duration.milliseconds` + +**IMPORTANT:** Duration does NOT support `.round()`, `.floor()`, `.ceil()` directly. Access a numeric field first (like `.days`), then apply number functions. + +```yaml +# CORRECT: Calculate days between dates +"(date(due_date) - today()).days" # Returns number of days +"(now() - file.ctime).days" # Days since created +"(date(due_date) - today()).days.round(0)" # Rounded days + +# WRONG - will cause error: +# "((date(due) - today()) / 86400000).round(0)" # Duration doesn't support division then round +``` + +### Date Arithmetic + +```yaml +# Duration units: y/year/years, M/month/months, d/day/days, +# w/week/weeks, h/hour/hours, m/minute/minutes, s/second/seconds +"now() + \"1 day\"" # Tomorrow +"today() + \"7d\"" # A week from today +"now() - file.ctime" # Returns Duration +"(now() - file.ctime).days" # Get days as number +``` + +## View Types + +### Table View + +```yaml +views: + - type: table + name: "My Table" + order: + - file.name + - status + - due_date + summaries: + price: Sum + count: Average +``` + +### Cards View + +```yaml +views: + - type: cards + name: "Gallery" + order: + - file.name + - cover_image + - description +``` + +### List View + +```yaml +views: + - type: list + name: "Simple List" + order: + - file.name + - status +``` + +### Map View + +Requires latitude/longitude properties and the Maps community plugin. + +```yaml +views: + - type: map + name: "Locations" + # Map-specific settings for lat/lng properties +``` + +## Default Summary Formulas + +| Name | Input Type | Description | +|------|------------|-------------| +| `Average` | Number | Mathematical mean | +| `Min` | Number | Smallest number | +| `Max` | Number | Largest number | +| `Sum` | Number | Sum of all numbers | +| `Range` | Number | Max - Min | +| `Median` | Number | Mathematical median | +| `Stddev` | Number | Standard deviation | +| `Earliest` | Date | Earliest date | +| `Latest` | Date | Latest date | +| `Range` | Date | Latest - Earliest | +| `Checked` | Boolean | Count of true values | +| `Unchecked` | Boolean | Count of false values | +| `Empty` | Any | Count of empty values | +| `Filled` | Any | Count of non-empty values | +| `Unique` | Any | Count of unique values | + +## Complete Examples + +### Task Tracker Base + +```yaml +filters: + and: + - file.hasTag("task") + - 'file.ext == "md"' + +formulas: + days_until_due: 'if(due, (date(due) - today()).days, "")' + is_overdue: 'if(due, date(due) < today() && status != "done", false)' + priority_label: 'if(priority == 1, "🔴 High", if(priority == 2, "🟡 Medium", "🟢 Low"))' + +properties: + status: + displayName: Status + formula.days_until_due: + displayName: "Days Until Due" + formula.priority_label: + displayName: Priority + +views: + - type: table + name: "Active Tasks" + filters: + and: + - 'status != "done"' + order: + - file.name + - status + - formula.priority_label + - due + - formula.days_until_due + groupBy: + property: status + direction: ASC + summaries: + formula.days_until_due: Average + + - type: table + name: "Completed" + filters: + and: + - 'status == "done"' + order: + - file.name + - completed_date +``` + +### Reading List Base + +```yaml +filters: + or: + - file.hasTag("book") + - file.hasTag("article") + +formulas: + reading_time: 'if(pages, (pages * 2).toString() + " min", "")' + status_icon: 'if(status == "reading", "📖", if(status == "done", "✅", "📚"))' + year_read: 'if(finished_date, date(finished_date).year, "")' + +properties: + author: + displayName: Author + formula.status_icon: + displayName: "" + formula.reading_time: + displayName: "Est. Time" + +views: + - type: cards + name: "Library" + order: + - cover + - file.name + - author + - formula.status_icon + filters: + not: + - 'status == "dropped"' + + - type: table + name: "Reading List" + filters: + and: + - 'status == "to-read"' + order: + - file.name + - author + - pages + - formula.reading_time +``` + +### Daily Notes Index + +```yaml +filters: + and: + - file.inFolder("Daily Notes") + - '/^\d{4}-\d{2}-\d{2}$/.matches(file.basename)' + +formulas: + word_estimate: '(file.size / 5).round(0)' + day_of_week: 'date(file.basename).format("dddd")' + +properties: + formula.day_of_week: + displayName: "Day" + formula.word_estimate: + displayName: "~Words" + +views: + - type: table + name: "Recent Notes" + limit: 30 + order: + - file.name + - formula.day_of_week + - formula.word_estimate + - file.mtime +``` + +## Embedding Bases + +Embed in Markdown files: + +```markdown +![[MyBase.base]] + + +![[MyBase.base#View Name]] +``` + +## YAML Quoting Rules + +- Use single quotes for formulas containing double quotes: `'if(done, "Yes", "No")'` +- Use double quotes for simple strings: `"My View Name"` +- Escape nested quotes properly in complex expressions + +## Troubleshooting + +### YAML Syntax Errors + +**Unquoted special characters**: Strings containing `:`, `{`, `}`, `[`, `]`, `,`, `&`, `*`, `#`, `?`, `|`, `-`, `<`, `>`, `=`, `!`, `%`, `@`, `` ` `` must be quoted. + +```yaml +# WRONG - colon in unquoted string +displayName: Status: Active + +# CORRECT +displayName: "Status: Active" +``` + +**Mismatched quotes in formulas**: When a formula contains double quotes, wrap the entire formula in single quotes. + +```yaml +# WRONG - double quotes inside double quotes +formulas: + label: "if(done, "Yes", "No")" + +# CORRECT - single quotes wrapping double quotes +formulas: + label: 'if(done, "Yes", "No")' +``` + +### Common Formula Errors + +**Duration math without field access**: Subtracting dates returns a Duration, not a number. Always access `.days`, `.hours`, etc. + +```yaml +# WRONG - Duration is not a number +"(now() - file.ctime).round(0)" + +# CORRECT - access .days first, then round +"(now() - file.ctime).days.round(0)" +``` + +**Missing null checks**: Properties may not exist on all notes. Use `if()` to guard. + +```yaml +# WRONG - crashes if due_date is empty +"(date(due_date) - today()).days" + +# CORRECT - guard with if() +'if(due_date, (date(due_date) - today()).days, "")' +``` + +**Referencing undefined formulas**: Ensure every `formula.X` in `order` or `properties` has a matching entry in `formulas`. + +```yaml +# This will fail silently if 'total' is not defined in formulas +order: + - formula.total + +# Fix: define it +formulas: + total: "price * quantity" +``` + +## References + +- [Bases Syntax](https://help.obsidian.md/bases/syntax) +- [Functions](https://help.obsidian.md/bases/functions) +- [Views](https://help.obsidian.md/bases/views) +- [Formulas](https://help.obsidian.md/formulas) +- [Complete Functions Reference](references/FUNCTIONS_REFERENCE.md) diff --git a/skills/obsidian-bases/references/FUNCTIONS_REFERENCE.md b/skills/obsidian-bases/references/FUNCTIONS_REFERENCE.md new file mode 100644 index 00000000..047888de --- /dev/null +++ b/skills/obsidian-bases/references/FUNCTIONS_REFERENCE.md @@ -0,0 +1,173 @@ +# Functions Reference + +## Global Functions + +| Function | Signature | Description | +|----------|-----------|-------------| +| `date()` | `date(string): date` | Parse string to date. Format: `YYYY-MM-DD HH:mm:ss` | +| `duration()` | `duration(string): duration` | Parse duration string | +| `now()` | `now(): date` | Current date and time | +| `today()` | `today(): date` | Current date (time = 00:00:00) | +| `if()` | `if(condition, trueResult, falseResult?)` | Conditional | +| `min()` | `min(n1, n2, ...): number` | Smallest number | +| `max()` | `max(n1, n2, ...): number` | Largest number | +| `number()` | `number(any): number` | Convert to number | +| `link()` | `link(path, display?): Link` | Create a link | +| `list()` | `list(element): List` | Wrap in list if not already | +| `file()` | `file(path): file` | Get file object | +| `image()` | `image(path): image` | Create image for rendering | +| `icon()` | `icon(name): icon` | Lucide icon by name | +| `html()` | `html(string): html` | Render as HTML | +| `escapeHTML()` | `escapeHTML(string): string` | Escape HTML characters | + +## Any Type Functions + +| Function | Signature | Description | +|----------|-----------|-------------| +| `isTruthy()` | `any.isTruthy(): boolean` | Coerce to boolean | +| `isType()` | `any.isType(type): boolean` | Check type | +| `toString()` | `any.toString(): string` | Convert to string | + +## Date Functions & Fields + +**Fields:** `date.year`, `date.month`, `date.day`, `date.hour`, `date.minute`, `date.second`, `date.millisecond` + +| Function | Signature | Description | +|----------|-----------|-------------| +| `date()` | `date.date(): date` | Remove time portion | +| `format()` | `date.format(string): string` | Format with Moment.js pattern | +| `time()` | `date.time(): string` | Get time as string | +| `relative()` | `date.relative(): string` | Human-readable relative time | +| `isEmpty()` | `date.isEmpty(): boolean` | Always false for dates | + +## Duration Type + +When subtracting two dates, the result is a **Duration** type (not a number). Duration has its own properties and methods. + +**Duration Fields:** +| Field | Type | Description | +|-------|------|-------------| +| `duration.days` | Number | Total days in duration | +| `duration.hours` | Number | Total hours in duration | +| `duration.minutes` | Number | Total minutes in duration | +| `duration.seconds` | Number | Total seconds in duration | +| `duration.milliseconds` | Number | Total milliseconds in duration | + +**IMPORTANT:** Duration does NOT support `.round()`, `.floor()`, `.ceil()` directly. You must access a numeric field first (like `.days`), then apply number functions. + +```yaml +# CORRECT: Calculate days between dates +"(date(due_date) - today()).days" # Returns number of days +"(now() - file.ctime).days" # Days since created + +# CORRECT: Round the numeric result if needed +"(date(due_date) - today()).days.round(0)" # Rounded days +"(now() - file.ctime).hours.round(0)" # Rounded hours + +# WRONG - will cause error: +# "((date(due) - today()) / 86400000).round(0)" # Duration doesn't support division then round +``` + +## Date Arithmetic + +```yaml +# Duration units: y/year/years, M/month/months, d/day/days, +# w/week/weeks, h/hour/hours, m/minute/minutes, s/second/seconds + +# Add/subtract durations +"date + \"1M\"" # Add 1 month +"date - \"2h\"" # Subtract 2 hours +"now() + \"1 day\"" # Tomorrow +"today() + \"7d\"" # A week from today + +# Subtract dates returns Duration type +"now() - file.ctime" # Returns Duration +"(now() - file.ctime).days" # Get days as number +"(now() - file.ctime).hours" # Get hours as number + +# Complex duration arithmetic +"now() + (duration('1d') * 2)" +``` + +## String Functions + +**Field:** `string.length` + +| Function | Signature | Description | +|----------|-----------|-------------| +| `contains()` | `string.contains(value): boolean` | Check substring | +| `containsAll()` | `string.containsAll(...values): boolean` | All substrings present | +| `containsAny()` | `string.containsAny(...values): boolean` | Any substring present | +| `startsWith()` | `string.startsWith(query): boolean` | Starts with query | +| `endsWith()` | `string.endsWith(query): boolean` | Ends with query | +| `isEmpty()` | `string.isEmpty(): boolean` | Empty or not present | +| `lower()` | `string.lower(): string` | To lowercase | +| `title()` | `string.title(): string` | To Title Case | +| `trim()` | `string.trim(): string` | Remove whitespace | +| `replace()` | `string.replace(pattern, replacement): string` | Replace pattern | +| `repeat()` | `string.repeat(count): string` | Repeat string | +| `reverse()` | `string.reverse(): string` | Reverse string | +| `slice()` | `string.slice(start, end?): string` | Substring | +| `split()` | `string.split(separator, n?): list` | Split to list | + +## Number Functions + +| Function | Signature | Description | +|----------|-----------|-------------| +| `abs()` | `number.abs(): number` | Absolute value | +| `ceil()` | `number.ceil(): number` | Round up | +| `floor()` | `number.floor(): number` | Round down | +| `round()` | `number.round(digits?): number` | Round to digits | +| `toFixed()` | `number.toFixed(precision): string` | Fixed-point notation | +| `isEmpty()` | `number.isEmpty(): boolean` | Not present | + +## List Functions + +**Field:** `list.length` + +| Function | Signature | Description | +|----------|-----------|-------------| +| `contains()` | `list.contains(value): boolean` | Element exists | +| `containsAll()` | `list.containsAll(...values): boolean` | All elements exist | +| `containsAny()` | `list.containsAny(...values): boolean` | Any element exists | +| `filter()` | `list.filter(expression): list` | Filter by condition (uses `value`, `index`) | +| `map()` | `list.map(expression): list` | Transform elements (uses `value`, `index`) | +| `reduce()` | `list.reduce(expression, initial): any` | Reduce to single value (uses `value`, `index`, `acc`) | +| `flat()` | `list.flat(): list` | Flatten nested lists | +| `join()` | `list.join(separator): string` | Join to string | +| `reverse()` | `list.reverse(): list` | Reverse order | +| `slice()` | `list.slice(start, end?): list` | Sublist | +| `sort()` | `list.sort(): list` | Sort ascending | +| `unique()` | `list.unique(): list` | Remove duplicates | +| `isEmpty()` | `list.isEmpty(): boolean` | No elements | + +## File Functions + +| Function | Signature | Description | +|----------|-----------|-------------| +| `asLink()` | `file.asLink(display?): Link` | Convert to link | +| `hasLink()` | `file.hasLink(otherFile): boolean` | Has link to file | +| `hasTag()` | `file.hasTag(...tags): boolean` | Has any of the tags | +| `hasProperty()` | `file.hasProperty(name): boolean` | Has property | +| `inFolder()` | `file.inFolder(folder): boolean` | In folder or subfolder | + +## Link Functions + +| Function | Signature | Description | +|----------|-----------|-------------| +| `asFile()` | `link.asFile(): file` | Get file object | +| `linksTo()` | `link.linksTo(file): boolean` | Links to file | + +## Object Functions + +| Function | Signature | Description | +|----------|-----------|-------------| +| `isEmpty()` | `object.isEmpty(): boolean` | No properties | +| `keys()` | `object.keys(): list` | List of keys | +| `values()` | `object.values(): list` | List of values | + +## Regular Expression Functions + +| Function | Signature | Description | +|----------|-----------|-------------| +| `matches()` | `regexp.matches(string): boolean` | Test if matches | diff --git a/skills/obsidian-cli/SKILL.md b/skills/obsidian-cli/SKILL.md new file mode 100644 index 00000000..3811f601 --- /dev/null +++ b/skills/obsidian-cli/SKILL.md @@ -0,0 +1,115 @@ +--- +name: obsidian-cli +description: "Use the Obsidian CLI to read, create, search, and manage vault content, or to develop and debug Obsidian plugins and themes from the command line." +risk: unknown +source: "https://github.com/kepano/obsidian-skills" +date_added: "2026-03-21" +--- + +# Obsidian CLI + +Use the `obsidian` CLI to interact with a running Obsidian instance. Requires Obsidian to be open. + +## When to Use + +- Use when managing vault content through the Obsidian CLI. +- Use when developing or debugging Obsidian plugins and themes from the command line. +- Use when the user wants shell-driven interaction with a running Obsidian app. + +## Command reference + +Run `obsidian help` to see all available commands. This is always up to date. Full docs: https://help.obsidian.md/cli + +## Syntax + +**Parameters** take a value with `=`. Quote values with spaces: + +```bash +obsidian create name="My Note" content="Hello world" +``` + +**Flags** are boolean switches with no value: + +```bash +obsidian create name="My Note" silent overwrite +``` + +For multiline content use `\n` for newline and `\t` for tab. + +## File targeting + +Many commands accept `file` or `path` to target a file. Without either, the active file is used. + +- `file=` — resolves like a wikilink (name only, no path or extension needed) +- `path=` — exact path from vault root, e.g. `folder/note.md` + +## Vault targeting + +Commands target the most recently focused vault by default. Use `vault=` as the first parameter to target a specific vault: + +```bash +obsidian vault="My Vault" search query="test" +``` + +## Common patterns + +```bash +obsidian read file="My Note" +obsidian create name="New Note" content="# Hello" template="Template" silent +obsidian append file="My Note" content="New line" +obsidian search query="search term" limit=10 +obsidian daily:read +obsidian daily:append content="- [ ] New task" +obsidian property:set name="status" value="done" file="My Note" +obsidian tasks daily todo +obsidian tags sort=count counts +obsidian backlinks file="My Note" +``` + +Use `--copy` on any command to copy output to clipboard. Use `silent` to prevent files from opening. Use `total` on list commands to get a count. + +## Plugin development + +### Develop/test cycle + +After making code changes to a plugin or theme, follow this workflow: + +1. **Reload** the plugin to pick up changes: + ```bash + obsidian plugin:reload id=my-plugin + ``` +2. **Check for errors** — if errors appear, fix and repeat from step 1: + ```bash + obsidian dev:errors + ``` +3. **Verify visually** with a screenshot or DOM inspection: + ```bash + obsidian dev:screenshot path=screenshot.png + obsidian dev:dom selector=".workspace-leaf" text + ``` +4. **Check console output** for warnings or unexpected logs: + ```bash + obsidian dev:console level=error + ``` + +### Additional developer commands + +Run JavaScript in the app context: + +```bash +obsidian eval code="app.vault.getFiles().length" +``` + +Inspect CSS values: + +```bash +obsidian dev:css selector=".workspace-leaf" prop=background-color +``` + +Toggle mobile emulation: + +```bash +obsidian dev:mobile on +``` + +Run `obsidian help` to see additional developer commands including CDP and debugger controls. diff --git a/skills/obsidian-markdown/SKILL.md b/skills/obsidian-markdown/SKILL.md new file mode 100644 index 00000000..3230e2cd --- /dev/null +++ b/skills/obsidian-markdown/SKILL.md @@ -0,0 +1,205 @@ +--- +name: obsidian-markdown +description: Create and edit Obsidian Flavored Markdown with wikilinks, embeds, callouts, properties, and other Obsidian-specific syntax. Use when working with .md files in Obsidian, or when the user mentions wikilinks, callouts, frontmatter, tags, embeds, or Obsidian notes. +risk: unknown +source: "https://github.com/kepano/obsidian-skills" +date_added: "2026-03-21" +--- + +# Obsidian Flavored Markdown Skill + +Create and edit valid Obsidian Flavored Markdown. Obsidian extends CommonMark and GFM with wikilinks, embeds, callouts, properties, comments, and other syntax. This skill covers only Obsidian-specific extensions -- standard Markdown (headings, bold, italic, lists, quotes, code blocks, tables) is assumed knowledge. + +## When to Use + +- Use when writing or editing Markdown notes intended for Obsidian. +- Use when the task involves wikilinks, embeds, callouts, frontmatter properties, or Obsidian-specific syntax. +- Use when the user wants notes that render correctly inside an Obsidian vault. + +## Workflow: Creating an Obsidian Note + +1. **Add frontmatter** with properties (title, tags, aliases) at the top of the file. See [PROPERTIES.md](references/PROPERTIES.md) for all property types. +2. **Write content** using standard Markdown for structure, plus Obsidian-specific syntax below. +3. **Link related notes** using wikilinks (`[[Note]]`) for internal vault connections, or standard Markdown links for external URLs. +4. **Embed content** from other notes, images, or PDFs using the `![[embed]]` syntax. See [EMBEDS.md](references/EMBEDS.md) for all embed types. +5. **Add callouts** for highlighted information using `> [!type]` syntax. See [CALLOUTS.md](references/CALLOUTS.md) for all callout types. +6. **Verify** the note renders correctly in Obsidian's reading view. + +> When choosing between wikilinks and Markdown links: use `[[wikilinks]]` for notes within the vault (Obsidian tracks renames automatically) and plain Markdown links for external URLs only. + +## Internal Links (Wikilinks) + +```markdown +[[Note Name]] Link to note +[[Note Name|Display Text]] Custom display text +[[Note Name#Heading]] Link to heading +[[Note Name#^block-id]] Link to block +[[#Heading in same note]] Same-note heading link +``` + +Define a block ID by appending `^block-id` to any paragraph: + +```markdown +This paragraph can be linked to. ^my-block-id +``` + +For lists and quotes, place the block ID on a separate line after the block: + +```markdown +> A quote block + +^quote-id +``` + +## Embeds + +Prefix any wikilink with `!` to embed its content inline: + +```markdown +![[Note Name]] Embed full note +![[Note Name#Heading]] Embed section +![[image.png]] Embed image +![[image.png|300]] Embed image with width +![[document.pdf#page=3]] Embed PDF page +``` + +See [EMBEDS.md](references/EMBEDS.md) for audio, video, search embeds, and external images. + +## Callouts + +```markdown +> [!note] +> Basic callout. + +> [!warning] Custom Title +> Callout with a custom title. + +> [!faq]- Collapsed by default +> Foldable callout (- collapsed, + expanded). +``` + +Common types: `note`, `tip`, `warning`, `info`, `example`, `quote`, `bug`, `danger`, `success`, `failure`, `question`, `abstract`, `todo`. + +See [CALLOUTS.md](references/CALLOUTS.md) for the full list with aliases, nesting, and custom CSS callouts. + +## Properties (Frontmatter) + +```yaml +--- +title: My Note +date: 2024-01-15 +tags: + - project + - active +aliases: + - Alternative Name +cssclasses: + - custom-class +--- +``` + +Default properties: `tags` (searchable labels), `aliases` (alternative note names for link suggestions), `cssclasses` (CSS classes for styling). + +See [PROPERTIES.md](references/PROPERTIES.md) for all property types, tag syntax rules, and advanced usage. + +## Tags + +```markdown +#tag Inline tag +#nested/tag Nested tag with hierarchy +``` + +Tags can contain letters, numbers (not first character), underscores, hyphens, and forward slashes. Tags can also be defined in frontmatter under the `tags` property. + +## Comments + +```markdown +This is visible %%but this is hidden%% text. + +%% +This entire block is hidden in reading view. +%% +``` + +## Obsidian-Specific Formatting + +```markdown +==Highlighted text== Highlight syntax +``` + +## Math (LaTeX) + +```markdown +Inline: $e^{i\pi} + 1 = 0$ + +Block: +$$ +\frac{a}{b} = c +$$ +``` + +## Diagrams (Mermaid) + +````markdown +```mermaid +graph TD + A[Start] --> B{Decision} + B -->|Yes| C[Do this] + B -->|No| D[Do that] +``` +```` + +To link Mermaid nodes to Obsidian notes, add `class NodeName internal-link;`. + +## Footnotes + +```markdown +Text with a footnote[^1]. + +[^1]: Footnote content. + +Inline footnote.^[This is inline.] +``` + +## Complete Example + +````markdown +--- +title: Project Alpha +date: 2024-01-15 +tags: + - project + - active +status: in-progress +--- + +# Project Alpha + +This project aims to [[improve workflow]] using modern techniques. + +> [!important] Key Deadline +> The first milestone is due on ==January 30th==. + +## Tasks + +- [x] Initial planning +- [ ] Development phase + - [ ] Backend implementation + - [ ] Frontend design + +## Notes + +The algorithm uses $O(n \log n)$ sorting. See [[Algorithm Notes#Sorting]] for details. + +![[Architecture Diagram.png|600]] + +Reviewed in [[Meeting Notes 2024-01-10#Decisions]]. +```` + +## References + +- [Obsidian Flavored Markdown](https://help.obsidian.md/obsidian-flavored-markdown) +- [Internal links](https://help.obsidian.md/links) +- [Embed files](https://help.obsidian.md/embeds) +- [Callouts](https://help.obsidian.md/callouts) +- [Properties](https://help.obsidian.md/properties) diff --git a/skills/obsidian-markdown/references/CALLOUTS.md b/skills/obsidian-markdown/references/CALLOUTS.md new file mode 100644 index 00000000..c086824c --- /dev/null +++ b/skills/obsidian-markdown/references/CALLOUTS.md @@ -0,0 +1,58 @@ +# Callouts Reference + +## Basic Callout + +```markdown +> [!note] +> This is a note callout. + +> [!info] Custom Title +> This callout has a custom title. + +> [!tip] Title Only +``` + +## Foldable Callouts + +```markdown +> [!faq]- Collapsed by default +> This content is hidden until expanded. + +> [!faq]+ Expanded by default +> This content is visible but can be collapsed. +``` + +## Nested Callouts + +```markdown +> [!question] Outer callout +> > [!note] Inner callout +> > Nested content +``` + +## Supported Callout Types + +| Type | Aliases | Color / Icon | +|------|---------|-------------| +| `note` | - | Blue, pencil | +| `abstract` | `summary`, `tldr` | Teal, clipboard | +| `info` | - | Blue, info | +| `todo` | - | Blue, checkbox | +| `tip` | `hint`, `important` | Cyan, flame | +| `success` | `check`, `done` | Green, checkmark | +| `question` | `help`, `faq` | Yellow, question mark | +| `warning` | `caution`, `attention` | Orange, warning | +| `failure` | `fail`, `missing` | Red, X | +| `danger` | `error` | Red, zap | +| `bug` | - | Red, bug | +| `example` | - | Purple, list | +| `quote` | `cite` | Gray, quote | + +## Custom Callouts (CSS) + +```css +.callout[data-callout="custom-type"] { + --callout-color: 255, 0, 0; + --callout-icon: lucide-alert-circle; +} +``` diff --git a/skills/obsidian-markdown/references/EMBEDS.md b/skills/obsidian-markdown/references/EMBEDS.md new file mode 100644 index 00000000..14a8989c --- /dev/null +++ b/skills/obsidian-markdown/references/EMBEDS.md @@ -0,0 +1,63 @@ +# Embeds Reference + +## Embed Notes + +```markdown +![[Note Name]] +![[Note Name#Heading]] +![[Note Name#^block-id]] +``` + +## Embed Images + +```markdown +![[image.png]] +![[image.png|640x480]] Width x Height +![[image.png|300]] Width only (maintains aspect ratio) +``` + +## External Images + +```markdown +![Alt text](https://example.com/image.png) +![Alt text|300](https://example.com/image.png) +``` + +## Embed Audio + +```markdown +![[audio.mp3]] +![[audio.ogg]] +``` + +## Embed PDF + +```markdown +![[document.pdf]] +![[document.pdf#page=3]] +![[document.pdf#height=400]] +``` + +## Embed Lists + +```markdown +![[Note#^list-id]] +``` + +Where the list has a block ID: + +```markdown +- Item 1 +- Item 2 +- Item 3 + +^list-id +``` + +## Embed Search Results + +````markdown +```query +tag:#project status:done +``` +```` diff --git a/skills/obsidian-markdown/references/PROPERTIES.md b/skills/obsidian-markdown/references/PROPERTIES.md new file mode 100644 index 00000000..e46a63ab --- /dev/null +++ b/skills/obsidian-markdown/references/PROPERTIES.md @@ -0,0 +1,61 @@ +# Properties (Frontmatter) Reference + +Properties use YAML frontmatter at the start of a note: + +```yaml +--- +title: My Note Title +date: 2024-01-15 +tags: + - project + - important +aliases: + - My Note + - Alternative Name +cssclasses: + - custom-class +status: in-progress +rating: 4.5 +completed: false +due: 2024-02-01T14:30:00 +--- +``` + +## Property Types + +| Type | Example | +|------|---------| +| Text | `title: My Title` | +| Number | `rating: 4.5` | +| Checkbox | `completed: true` | +| Date | `date: 2024-01-15` | +| Date & Time | `due: 2024-01-15T14:30:00` | +| List | `tags: [one, two]` or YAML list | +| Links | `related: "[[Other Note]]"` | + +## Default Properties + +- `tags` - Note tags (searchable, shown in graph view) +- `aliases` - Alternative names for the note (used in link suggestions) +- `cssclasses` - CSS classes applied to the note in reading/editing view + +## Tags + +```markdown +#tag +#nested/tag +#tag-with-dashes +#tag_with_underscores +``` + +Tags can contain: letters (any language), numbers (not first character), underscores `_`, hyphens `-`, forward slashes `/` (for nesting). + +In frontmatter: + +```yaml +--- +tags: + - tag1 + - nested/tag2 +--- +``` diff --git a/skills/product-marketing-context/SKILL.md b/skills/product-marketing-context/SKILL.md new file mode 100644 index 00000000..f890b055 --- /dev/null +++ b/skills/product-marketing-context/SKILL.md @@ -0,0 +1,250 @@ +--- +name: product-marketing-context +description: "Create or update a reusable product marketing context document with positioning, audience, ICP, use cases, and messaging. Use at the start of a project to avoid repeating core marketing context across tasks." +risk: unknown +source: "https://github.com/coreyhaines31/marketingskills" +date_added: "2026-03-21" +metadata: + version: 1.1.0 +--- + +# Product Marketing Context + +You help users create and maintain a product marketing context document. This captures foundational positioning and messaging information that other marketing skills reference, so users don't repeat themselves. + +## When to Use + +- Use when creating a reusable product, audience, and positioning context file. +- Use at the start of a marketing project before more specialized marketing skills. +- Use when the user wants to avoid re-explaining ICP, messaging, and product basics. + +The document is stored at `.agents/product-marketing-context.md`. + +## Workflow + +### Step 1: Check for Existing Context + +First, check if `.agents/product-marketing-context.md` already exists. Also check `.claude/product-marketing-context.md` for older setups — if found there but not in `.agents/`, offer to move it. + +**If it exists:** +- Read it and summarize what's captured +- Ask which sections they want to update +- Only gather info for those sections + +**If it doesn't exist, offer two options:** + +1. **Auto-draft from codebase** (recommended): You'll study the repo—README, landing pages, marketing copy, package.json, etc.—and draft a V1 of the context document. The user then reviews, corrects, and fills gaps. This is faster than starting from scratch. + +2. **Start from scratch**: Walk through each section conversationally, gathering info one section at a time. + +Most users prefer option 1. After presenting the draft, ask: "What needs correcting? What's missing?" + +### Step 2: Gather Information + +**If auto-drafting:** +1. Read the codebase: README, landing pages, marketing copy, about pages, meta descriptions, package.json, any existing docs +2. Draft all sections based on what you find +3. Present the draft and ask what needs correcting or is missing +4. Iterate until the user is satisfied + +**If starting from scratch:** +Walk through each section below conversationally, one at a time. Don't dump all questions at once. + +For each section: +1. Briefly explain what you're capturing +2. Ask relevant questions +3. Confirm accuracy +4. Move to the next + +Push for verbatim customer language — exact phrases are more valuable than polished descriptions because they reflect how customers actually think and speak, which makes copy more resonant. + +--- + +## Sections to Capture + +### 1. Product Overview +- One-line description +- What it does (2-3 sentences) +- Product category (what "shelf" you sit on—how customers search for you) +- Product type (SaaS, marketplace, e-commerce, service, etc.) +- Business model and pricing + +### 2. Target Audience +- Target company type (industry, size, stage) +- Target decision-makers (roles, departments) +- Primary use case (the main problem you solve) +- Jobs to be done (2-3 things customers "hire" you for) +- Specific use cases or scenarios + +### 3. Personas (B2B only) +If multiple stakeholders are involved in buying, capture for each: +- User, Champion, Decision Maker, Financial Buyer, Technical Influencer +- What each cares about, their challenge, and the value you promise them + +### 4. Problems & Pain Points +- Core challenge customers face before finding you +- Why current solutions fall short +- What it costs them (time, money, opportunities) +- Emotional tension (stress, fear, doubt) + +### 5. Competitive Landscape +- **Direct competitors**: Same solution, same problem (e.g., Calendly vs SavvyCal) +- **Secondary competitors**: Different solution, same problem (e.g., Calendly vs Superhuman scheduling) +- **Indirect competitors**: Conflicting approach (e.g., Calendly vs personal assistant) +- How each falls short for customers + +### 6. Differentiation +- Key differentiators (capabilities alternatives lack) +- How you solve it differently +- Why that's better (benefits) +- Why customers choose you over alternatives + +### 7. Objections & Anti-Personas +- Top 3 objections heard in sales and how to address them +- Who is NOT a good fit (anti-persona) + +### 8. Switching Dynamics +The JTBD Four Forces: +- **Push**: What frustrations drive them away from current solution +- **Pull**: What attracts them to you +- **Habit**: What keeps them stuck with current approach +- **Anxiety**: What worries them about switching + +### 9. Customer Language +- How customers describe the problem (verbatim) +- How they describe your solution (verbatim) +- Words/phrases to use +- Words/phrases to avoid +- Glossary of product-specific terms + +### 10. Brand Voice +- Tone (professional, casual, playful, etc.) +- Communication style (direct, conversational, technical) +- Brand personality (3-5 adjectives) + +### 11. Proof Points +- Key metrics or results to cite +- Notable customers/logos +- Testimonial snippets +- Main value themes and supporting evidence + +### 12. Goals +- Primary business goal +- Key conversion action (what you want people to do) +- Current metrics (if known) + +--- + +## Step 3: Create the Document + +After gathering information, create `.agents/product-marketing-context.md` with this structure: + +```markdown +# Product Marketing Context + +*Last updated: [date]* + +## Product Overview +**One-liner:** +**What it does:** +**Product category:** +**Product type:** +**Business model:** + +## Target Audience +**Target companies:** +**Decision-makers:** +**Primary use case:** +**Jobs to be done:** +- +**Use cases:** +- + +## Personas +| Persona | Cares about | Challenge | Value we promise | +|---------|-------------|-----------|------------------| +| | | | | + +## Problems & Pain Points +**Core problem:** +**Why alternatives fall short:** +- +**What it costs them:** +**Emotional tension:** + +## Competitive Landscape +**Direct:** [Competitor] — falls short because... +**Secondary:** [Approach] — falls short because... +**Indirect:** [Alternative] — falls short because... + +## Differentiation +**Key differentiators:** +- +**How we do it differently:** +**Why that's better:** +**Why customers choose us:** + +## Objections +| Objection | Response | +|-----------|----------| +| | | + +**Anti-persona:** + +## Switching Dynamics +**Push:** +**Pull:** +**Habit:** +**Anxiety:** + +## Customer Language +**How they describe the problem:** +- "[verbatim]" +**How they describe us:** +- "[verbatim]" +**Words to use:** +**Words to avoid:** +**Glossary:** +| Term | Meaning | +|------|---------| +| | | + +## Brand Voice +**Tone:** +**Style:** +**Personality:** + +## Proof Points +**Metrics:** +**Customers:** +**Testimonials:** +> "[quote]" — [who] +**Value themes:** +| Theme | Proof | +|-------|-------| +| | | + +## Goals +**Business goal:** +**Conversion action:** +**Current metrics:** +``` + +--- + +## Step 4: Confirm and Save + +- Show the completed document +- Ask if anything needs adjustment +- Save to `.agents/product-marketing-context.md` +- Tell them: "Other marketing skills will now use this context automatically. Run `/product-marketing-context` anytime to update it." + +--- + +## Tips + +- **Be specific**: Ask "What's the #1 frustration that brings them to you?" not "What problem do they solve?" +- **Capture exact words**: Customer language beats polished descriptions +- **Ask for examples**: "Can you give me an example?" unlocks better answers +- **Validate as you go**: Summarize each section and confirm before moving on +- **Skip what doesn't apply**: Not every product needs all sections (e.g., Personas for B2C) diff --git a/skills/product-marketing-context/evals/evals.json b/skills/product-marketing-context/evals/evals.json new file mode 100644 index 00000000..cc5ce653 --- /dev/null +++ b/skills/product-marketing-context/evals/evals.json @@ -0,0 +1,85 @@ +{ + "skill_name": "product-marketing-context", + "evals": [ + { + "id": 1, + "prompt": "I want to set up my product marketing context. We're a B2B SaaS company that sells a customer feedback platform to product teams.", + "expected_output": "Should check if .agents/product-marketing-context.md already exists. If not, should offer two options: (1) Auto-draft from codebase (recommended) or (2) Start from scratch. If user chooses start from scratch, should walk through sections conversationally one at a time. Should cover all applicable sections: Product Overview, Target Audience, Personas, Problems You Solve, Competitive Landscape, Differentiation, Objections, Switching Dynamics, Customer Language, Brand Voice, Proof Points, and Goals. Should create the file at .agents/product-marketing-context.md when complete.", + "assertions": [ + "Checks for existing product-marketing-context.md", + "Offers two options: auto-draft or start from scratch", + "Covers applicable sections", + "Walks through sections conversationally one at a time", + "Creates file at .agents/product-marketing-context.md" + ], + "files": [] + }, + { + "id": 2, + "prompt": "Update our product marketing context. We just added a new enterprise tier and our target audience has expanded to include VP of Engineering, not just Product Managers.", + "expected_output": "Should check for existing .agents/product-marketing-context.md and read it. Should identify which sections need updating based on the changes: Target Audience (add VP of Engineering), Personas (add new persona), Product Overview (new enterprise tier, including pricing updates within that section), Objections (enterprise-specific), and Competitive Landscape (enterprise competitors). Should update only the relevant sections, preserving existing content that hasn't changed.", + "assertions": [ + "Reads existing product-marketing-context.md", + "Identifies sections that need updating", + "Updates Target Audience with VP of Engineering", + "Adds new persona for the expanded audience", + "Updates Product Overview for enterprise tier", + "Preserves unchanged sections" + ], + "files": [] + }, + { + "id": 3, + "prompt": "create a product context doc for my app. it's a mobile app that helps people find hiking trails. we're just getting started.", + "expected_output": "Should trigger on casual phrasing. Should check for existing context doc. Should offer auto-draft or start-from-scratch options. Should adapt questions for an early-stage B2C mobile app (outdoor/fitness niche). Should note that some sections may be sparse for an early-stage product and that's okay — they can be filled in as the business matures. Should skip non-applicable sections (e.g., Personas section is B2B-focused) rather than forcing all 12. Should accept lighter answers for sections like Proof Points or Competitive Landscape if the company is new.", + "assertions": [ + "Triggers on casual phrasing", + "Checks for existing context doc", + "Offers auto-draft or start-from-scratch options", + "Adapts questions for early-stage B2C mobile app", + "Notes some sections may be sparse early on", + "Skips non-applicable sections rather than forcing all 12", + "Creates file at .agents/product-marketing-context.md" + ], + "files": [] + }, + { + "id": 4, + "prompt": "Can you auto-draft our product marketing context from our existing codebase and marketing materials?", + "expected_output": "Should activate the auto-draft workflow mode. Should scan the codebase for existing marketing context: README, landing page copy, pricing page, about page, meta descriptions, any existing documentation. Should draft the product-marketing-context.md from what it finds, filling in sections where information is available and flagging sections that need manual input. Should present the draft for review before saving.", + "assertions": [ + "Activates auto-draft workflow mode", + "Scans codebase for existing marketing materials", + "Drafts context from found information", + "Flags sections needing manual input", + "Presents draft for review before saving" + ], + "files": [] + }, + { + "id": 5, + "prompt": "Do we have a product marketing context set up? I want to make sure the other marketing skills have context about our product.", + "expected_output": "Should check for .agents/product-marketing-context.md (and the older .claude/product-marketing-context.md location). Should report whether it exists and summarize its contents if found. If it doesn't exist, should offer to create one and explain why it's valuable (other skills like copywriting, page-cro, seo-audit check for it first). Should explain how other skills use this context document.", + "assertions": [ + "Checks both file locations", + "Reports whether context doc exists", + "Summarizes contents if found", + "Offers to create if missing", + "Explains how other skills use it" + ], + "files": [] + }, + { + "id": 6, + "prompt": "Write homepage copy for our SaaS product.", + "expected_output": "Should recognize this is a copywriting task, not a product marketing context task. Should check for product-marketing-context.md (as other skills do), and if it doesn't exist, may suggest creating one first. But should defer to the copywriting skill for actually writing the homepage copy.", + "assertions": [ + "Recognizes this as a copywriting task", + "May check for or suggest creating product-marketing-context.md", + "References or defers to copywriting skill for the actual copy", + "Does not attempt to write homepage copy using context creation patterns" + ], + "files": [] + } + ] +} diff --git a/skills/revops/SKILL.md b/skills/revops/SKILL.md new file mode 100644 index 00000000..e78c0560 --- /dev/null +++ b/skills/revops/SKILL.md @@ -0,0 +1,352 @@ +--- +name: revops +description: "Design and improve revenue operations, lead lifecycle rules, scoring, routing, handoffs, and CRM process automation. Use when marketing, sales, and customer success workflows need clearer operational structure." +risk: unknown +source: "https://github.com/coreyhaines31/marketingskills" +date_added: "2026-03-21" +metadata: + version: 1.1.0 +--- + +# RevOps + +You are an expert in revenue operations. Your goal is to help design and optimize the systems that connect marketing, sales, and customer success into a unified revenue engine. + +## When to Use + +- Use when the user needs lead scoring, routing, handoffs, or lifecycle definitions. +- Use when CRM process design and revenue-team coordination are the core problem. +- Use when marketing, sales, and customer success systems need operational alignment. + +## Before Starting + +**Check for product marketing context first:** +If `.agents/product-marketing-context.md` exists (or `.claude/product-marketing-context.md` in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task. + +Gather this context (ask if not provided): + +1. **GTM motion** — Product-led (PLG), sales-led, or hybrid? +2. **ACV range** — What's the average contract value? +3. **Sales cycle length** — Days from first touch to closed-won? +4. **Current stack** — CRM, marketing automation, scheduling, enrichment tools? +5. **Current state** — How are leads managed today? What's working and what's not? +6. **Goals** — Increase conversion? Reduce speed-to-lead? Fix handoff leaks? Build from scratch? + +Work with whatever the user gives you. If they have a clear problem area, start there. Don't block on missing inputs — use what you have and note what would strengthen the solution. + +--- + +## Core Principles + +### Single Source of Truth +One system of record for every lead and account. If data lives in multiple places, it will conflict. Pick a CRM as the canonical source and sync everything to it. + +### Define Before Automate +Get stage definitions, scoring criteria, and routing rules right on paper before building workflows. Automating a broken process just creates broken results faster. + +### Measure Every Handoff +Every handoff between teams is a potential leak. Marketing-to-sales, SDR-to-AE, AE-to-CS — each needs an SLA, a tracking mechanism, and someone accountable for follow-through. + +### Revenue Team Alignment +Marketing, sales, and customer success must agree on definitions. If marketing calls something an MQL but sales won't work it, the definition is wrong. Alignment meetings aren't optional. + +--- + +## Lead Lifecycle Framework + +### Stage Definitions + +| Stage | Entry Criteria | Exit Criteria | Owner | +|-------|---------------|---------------|-------| +| **Subscriber** | Opts in to content (blog, newsletter) | Provides company info or shows engagement | Marketing | +| **Lead** | Identified contact with basic info | Meets minimum fit criteria | Marketing | +| **MQL** | Passes fit + engagement threshold | Sales accepts or rejects within SLA | Marketing | +| **SQL** | Sales accepts and qualifies via conversation | Opportunity created or recycled | Sales (SDR/AE) | +| **Opportunity** | Budget, authority, need, timeline confirmed | Closed-won or closed-lost | Sales (AE) | +| **Customer** | Closed-won deal | Expands, renews, or churns | CS / Account Mgmt | +| **Evangelist** | High NPS, referral activity, case study | Ongoing program participation | CS / Marketing | + +### MQL Definition + +An MQL requires both **fit** and **engagement**: + +- **Fit score** — Does this person match your ICP? (company size, industry, role, tech stack) +- **Engagement score** — Have they shown buying intent? (pricing page, demo request, multiple visits) + +Neither alone is sufficient. A perfect-fit company that never engages isn't an MQL. A student downloading every ebook isn't an MQL. + +### MQL-to-SQL Handoff SLA + +Define response times and document them: +- MQL alert sent to assigned rep +- Rep contacts within **4 hours** (business hours) +- Rep qualifies or rejects within **48 hours** +- Rejected MQLs go to recycling nurture with reason code + +**For complete lifecycle stage templates and SLA examples**: See [references/lifecycle-definitions.md](references/lifecycle-definitions.md) + +--- + +## Lead Scoring + +### Scoring Dimensions + +**Explicit scoring (fit)** — Who they are: +- Company size, industry, revenue +- Job title, seniority, department +- Tech stack, geography + +**Implicit scoring (engagement)** — What they do: +- Page visits (especially pricing, demo, case studies) +- Content downloads, webinar attendance +- Email engagement (opens, clicks) +- Product usage (for PLG) + +**Negative scoring** — Disqualifying signals: +- Competitor email domains +- Student/personal email +- Unsubscribes, spam complaints +- Job title mismatches (intern, student) + +### Building a Scoring Model + +1. Define your ICP attributes and weight them +2. Identify high-intent behavioral signals from closed-won data +3. Set point values for each attribute and behavior +4. Set MQL threshold (typically 50-80 points on a 100-point scale) +5. Test against historical data — does the model correctly identify past wins? +6. Launch, measure, and recalibrate quarterly + +### Common Scoring Mistakes + +- Weighting content downloads too heavily (research ≠ buying intent) +- Not including negative scoring (lets bad leads through) +- Setting and forgetting (buyer behavior changes; recalibrate quarterly) +- Scoring all page visits equally (pricing page ≠ blog post) + +**For detailed scoring templates and example models**: See [references/scoring-models.md](references/scoring-models.md) + +--- + +## Lead Routing + +### Routing Methods + +| Method | How It Works | Best For | +|--------|-------------|----------| +| **Round-robin** | Distribute evenly across reps | Equal territories, similar deal sizes | +| **Territory-based** | Assign by geography, vertical, or segment | Regional teams, industry specialists | +| **Account-based** | Named accounts go to named reps | ABM motions, strategic accounts | +| **Skill-based** | Route by deal complexity, product line, or language | Diverse product lines, global teams | + +### Routing Rules Essentials + +- Route to the **most specific match** first, then fall back to general +- Include a **fallback owner** — unassigned leads go cold fast and waste pipeline +- Round-robin should account for **rep capacity and availability** (PTO, quota attainment) +- Log every routing decision for audit and optimization + +### Speed-to-Lead + +Response time is the single biggest factor in lead conversion: +- Contact within **5 minutes** = 21x more likely to qualify (Lead Connect) +- After **30 minutes**, conversion drops by 10x +- After **24 hours**, the lead is effectively cold + +Build routing rules that prioritize speed. Alert reps immediately. Escalate if SLA is missed. + +**For routing decision trees and platform-specific setup**: See [references/routing-rules.md](references/routing-rules.md) + +--- + +## Pipeline Stage Management + +### Pipeline Stages + +| Stage | Required Fields | Exit Criteria | +|-------|----------------|---------------| +| **Qualified** | Contact info, company, source, fit score | Discovery call scheduled | +| **Discovery** | Pain points, current solution, timeline | Needs confirmed, demo scheduled | +| **Demo/Evaluation** | Technical requirements, decision makers | Positive evaluation, proposal requested | +| **Proposal** | Pricing, terms, stakeholder map | Proposal delivered and reviewed | +| **Negotiation** | Redlines, approval chain, close date | Terms agreed, contract sent | +| **Closed Won** | Signed contract, payment terms | Handoff to CS complete | +| **Closed Lost** | Loss reason, competitor (if any) | Post-mortem logged | + +### Stage Hygiene + +- **Required fields per stage** — Don't let reps advance a deal without filling in required data +- **Stale deal alerts** — Flag deals that sit in a stage beyond the average time (e.g., 2x average days) +- **Stage skip detection** — Alert when deals jump stages (Qualified → Proposal skipping Discovery) +- **Close date discipline** — Push dates must include a reason; no silent pushes + +### Pipeline Metrics + +| Metric | What It Tells You | +|--------|-------------------| +| Stage conversion rates | Where deals die | +| Average time in stage | Where deals stall | +| Pipeline velocity | Revenue per day through the funnel | +| Coverage ratio | Pipeline value vs. quota (target 3-4x) | +| Win rate by source | Which channels produce real revenue | + +--- + +## CRM Automation Workflows + +### Essential Automations + +- **Lifecycle stage updates** — Auto-advance stages when criteria are met +- **Task creation on handoff** — Create follow-up task when MQL assigned to rep +- **SLA alerts** — Notify manager if rep misses response time SLA +- **Deal stage triggers** — Auto-send proposals, update forecasts, notify CS on close + +### Marketing-to-Sales Automations + +- **MQL alert** — Instant notification to assigned rep with lead context +- **Meeting booked** — Notify AE when prospect books via scheduling tool +- **Lead activity digest** — Daily summary of high-intent actions by active leads +- **Re-engagement trigger** — Alert sales when a dormant lead returns to site + +### Calendar Scheduling Integration + +- **Round-robin scheduling** — Distribute meetings evenly across team +- **Routing by criteria** — Send enterprise leads to senior AEs, SMB to junior reps +- **Pre-meeting enrichment** — Auto-populate CRM record before the call +- **No-show workflows** — Auto-follow-up if prospect misses meeting + +**For platform-specific workflow recipes**: See [references/automation-playbooks.md](references/automation-playbooks.md) + +--- + +## Deal Desk Processes + +### When You Need a Deal Desk + +- ACV above **$25K** (or your threshold for non-standard deals) +- Non-standard payment terms (net-90, quarterly billing) +- Multi-year contracts with custom pricing +- Volume discounts beyond published tiers +- Custom legal terms or SLAs + +### Approval Workflow Tiers + +| Deal Size | Approval Required | +|-----------|-------------------| +| Standard pricing | Auto-approved | +| 10-20% discount | Sales manager | +| 20-40% discount | VP Sales | +| 40%+ discount or custom terms | Deal desk review | +| Multi-year / enterprise | Finance + Legal | + +### Non-Standard Terms Handling + +Document every exception. Track which non-standard terms get requested most — if everyone asks for the same exception, it should become standard. Review quarterly. + +--- + +## Data Hygiene & Enrichment + +### Dedup Strategy + +- **Matching rules** — Email domain + company name + phone as primary match keys +- **Merge priority** — CRM record wins over marketing automation; most recent activity wins for fields +- **Scheduled dedup** — Run weekly automated dedup with manual review for edge cases + +### Required Fields Enforcement + +- Enforce required fields at each lifecycle stage +- Block stage advancement if fields are empty +- Use progressive profiling — don't require everything upfront + +### Enrichment Tools + +| Tool | Strength | +|------|----------| +| Clearbit | Real-time enrichment, good for tech companies | +| Apollo | Contact data + sequences, strong for prospecting | +| ZoomInfo | Enterprise-grade, largest B2B database | + +### Quarterly Audit Checklist + +- Review and merge duplicates +- Validate email deliverability on stale contacts +- Archive contacts with no activity in 12+ months +- Audit lifecycle stage distribution (look for bottlenecks) +- Verify enrichment data accuracy on a sample set + +--- + +## RevOps Metrics Dashboard + +### Key Metrics + +| Metric | Formula / Definition | Benchmark | +|--------|---------------------|-----------| +| Lead-to-MQL rate | MQLs / Total leads | 5-15% | +| MQL-to-SQL rate | SQLs / MQLs | 30-50% | +| SQL-to-Opportunity | Opportunities / SQLs | 50-70% | +| Pipeline velocity | (# deals x avg deal size x win rate) / avg sales cycle | Varies by ACV | +| CAC | Total sales + marketing spend / new customers | LTV:CAC > 3:1 | +| LTV:CAC ratio | Customer lifetime value / CAC | 3:1 to 5:1 healthy | +| Speed-to-lead | Time from form fill to first rep contact | < 5 minutes ideal | +| Win rate | Closed-won / total opportunities | 20-30% (varies) | + +### Dashboard Structure + +Build three views: +1. **Marketing view** — Lead volume, MQL rate, source attribution, cost per MQL +2. **Sales view** — Pipeline value, stage conversion, velocity, forecast accuracy +3. **Executive view** — CAC, LTV:CAC, revenue vs. target, pipeline coverage + +--- + +## Output Format + +When delivering RevOps recommendations, provide: + +1. **Lifecycle stage document** — Stage definitions with entry/exit criteria, owners, and SLAs +2. **Scoring specification** — Fit and engagement attributes with point values and MQL threshold +3. **Routing rules document** — Decision tree with assignment logic and fallbacks +4. **Pipeline configuration** — Stage definitions, required fields, and automation triggers +5. **Metrics dashboard spec** — Key metrics, data sources, and target benchmarks + +Format each as a standalone document the user can implement directly. Include platform-specific guidance when the CRM is known. + +--- + +## Task-Specific Questions + +1. What CRM platform are you using (or planning to use)? +2. How many leads per month do you generate? +3. What's your current MQL definition? +4. Where do leads get stuck in your funnel? +5. Do you have SLAs between marketing and sales today? + +--- + +## Tool Integrations + +For implementation, use the CRM, scheduling, enrichment, and automation tools available in the current environment. Key RevOps tools: + +| Tool | What It Does | Guide | +|------|-------------|-------| +| **HubSpot** | CRM, marketing automation, lead scoring, workflows | Use available HubSpot integrations | +| **Salesforce** | Enterprise CRM, pipeline management, reporting | Use available Salesforce integrations | +| **Calendly** | Meeting scheduling, round-robin routing | Use available scheduling integrations | +| **SavvyCal** | Scheduling with priority-based availability | Use available scheduling integrations | +| **Clearbit** | Real-time lead enrichment and scoring | Use available enrichment integrations | +| **Apollo** | Contact data, enrichment, and outbound sequences | Use available outbound data integrations | +| **ActiveCampaign** | Marketing automation for SMBs, lead scoring | Use available marketing automation integrations | +| **Zapier** | Cross-tool automation and workflow glue | Use available workflow automation integrations | + +--- + +## Related Skills + +- **cold-email**: For outbound prospecting emails +- **email-sequence**: For lifecycle and nurture email flows +- **pricing-strategy**: For pricing decisions and packaging +- **analytics-tracking**: For tracking pipeline metrics and attribution +- **launch-strategy**: For go-to-market launch planning +- **sales-enablement**: For sales collateral, decks, and objection handling diff --git a/skills/revops/evals/evals.json b/skills/revops/evals/evals.json new file mode 100644 index 00000000..3612fbe3 --- /dev/null +++ b/skills/revops/evals/evals.json @@ -0,0 +1,91 @@ +{ + "skill_name": "revops", + "evals": [ + { + "id": 1, + "prompt": "Help me set up our lead lifecycle stages. We're a B2B SaaS company selling to mid-market. We use HubSpot as our CRM and have marketing and sales teams that aren't aligned on lead definitions.", + "expected_output": "Should check for product-marketing-context.md first. Should apply the lead lifecycle framework: Subscriber → Lead → MQL → SQL → Opportunity → Customer → Evangelist. Should define clear criteria for each stage transition (what makes a Lead become an MQL, etc.). Should address the alignment issue between marketing and sales — define shared definitions and SLAs. Should recommend CRM implementation steps for HubSpot. Should include lead scoring setup. Should provide a handoff process between marketing and sales.", + "assertions": [ + "Checks for product-marketing-context.md", + "Applies lead lifecycle framework with all stages", + "Defines criteria for each stage transition", + "Addresses marketing-sales alignment", + "Provides CRM implementation guidance for HubSpot", + "Includes lead scoring setup", + "Provides handoff process between teams" + ], + "files": [] + }, + { + "id": 2, + "prompt": "Set up lead scoring for us. We want to prioritize which leads sales should call first. We sell enterprise software ($50k+ ACV).", + "expected_output": "Should apply the lead scoring framework with three dimensions: explicit scoring (firmographics — company size, industry, title match), implicit scoring (behavioral — page visits, content downloads, email engagement), and negative scoring (unsubscribes, competitor emails, student emails). Should provide specific scoring criteria appropriate for enterprise ($50k+ ACV): weight firmographic signals heavily, include budget and authority signals. Should define score thresholds for MQL and SQL. Should recommend lead routing based on scores.", + "assertions": [ + "Applies lead scoring with explicit, implicit, and negative dimensions", + "Provides specific scoring criteria for enterprise", + "Weights firmographic signals appropriately", + "Includes behavioral scoring signals", + "Includes negative scoring signals", + "Defines MQL and SQL score thresholds", + "Recommends lead routing based on scores" + ], + "files": [] + }, + { + "id": 3, + "prompt": "our pipeline is a mess. deals sit in stages forever and we don't know what's actually going to close. how do we fix this?", + "expected_output": "Should trigger on casual phrasing. Should apply the pipeline stage management guidance. Should recommend: define clear pipeline stages with entry/exit criteria, set maximum time in each stage, implement stage velocity tracking, add required fields per stage to force data entry. Should address deal hygiene: regular pipeline reviews, stale deal flagging, win/loss analysis. Should recommend CRM automation to enforce stage rules. Should provide a practical cleanup plan for the current mess.", + "assertions": [ + "Triggers on casual phrasing", + "Applies pipeline stage management", + "Defines stages with entry/exit criteria", + "Recommends maximum time per stage", + "Addresses deal hygiene and pipeline reviews", + "Recommends CRM automation for enforcement", + "Provides practical cleanup plan" + ], + "files": [] + }, + { + "id": 4, + "prompt": "What RevOps metrics should we be tracking? We want to build a dashboard for our leadership team.", + "expected_output": "Should apply the RevOps metrics dashboard framework. Should recommend metrics across the funnel: lead volume by source, MQL-to-SQL conversion rate, SQL-to-Opportunity rate, win rate, average deal size, sales cycle length, pipeline velocity, pipeline coverage ratio, CAC, LTV, LTV:CAC ratio. Should organize metrics by audience (marketing team, sales team, leadership). Should recommend dashboard structure and cadence for reviews.", + "assertions": [ + "Applies RevOps metrics dashboard", + "Covers full-funnel metrics", + "Includes conversion rates between stages", + "Includes pipeline velocity and coverage", + "Includes CAC, LTV, LTV:CAC", + "Organizes by audience", + "Recommends dashboard structure and review cadence" + ], + "files": [] + }, + { + "id": 5, + "prompt": "Our CRM data is a disaster. Duplicate records, missing fields, inconsistent naming. How do we clean it up and keep it clean?", + "expected_output": "Should apply the data hygiene guidance. Should recommend: duplicate detection and merging strategy, required field enforcement, standardized naming conventions (picklists over free text), data validation rules, regular audit cadence. Should address both cleanup (one-time fix) and prevention (ongoing processes). Should recommend CRM automation for data hygiene. Should provide a prioritized cleanup plan (start with highest-impact data quality issues).", + "assertions": [ + "Applies data hygiene guidance", + "Recommends duplicate detection and merging", + "Recommends required field enforcement", + "Addresses standardized naming conventions", + "Covers both cleanup and prevention", + "Recommends CRM automation for hygiene", + "Provides prioritized cleanup plan" + ], + "files": [] + }, + { + "id": 6, + "prompt": "Can you help me write cold outreach emails to prospects in our pipeline?", + "expected_output": "Should recognize this is a cold email / outbound writing task, not RevOps. Should defer to or cross-reference the cold-email skill for writing outbound prospecting emails. RevOps covers the systems, processes, and data infrastructure — not the actual email content.", + "assertions": [ + "Recognizes this as cold email writing, not RevOps", + "References or defers to cold-email skill", + "Explains RevOps covers systems and processes, not email content" + ], + "files": [] + } + ] +} diff --git a/skills/revops/references/automation-playbooks.md b/skills/revops/references/automation-playbooks.md new file mode 100644 index 00000000..e2888743 --- /dev/null +++ b/skills/revops/references/automation-playbooks.md @@ -0,0 +1,290 @@ +# Automation Playbooks + +Platform-specific workflow recipes for HubSpot, Salesforce, scheduling tools, and cross-tool automation. + +## HubSpot Workflow Recipes + +### 1. MQL Alert and Assignment + +**Name:** MQL Notification and Task Creation +**Trigger:** Contact property "Lifecycle Stage" is changed to "Marketing Qualified Lead" +**Actions:** +1. Rotate contact owner among sales team (round-robin) +2. Send internal email notification to contact owner with lead context +3. Create task: "Follow up with [Contact Name]" — due in 4 hours +4. Send Slack notification to #sales-alerts channel +5. Enroll in "MQL Follow-Up" sequence (if using HubSpot Sequences) +**Outcome:** Every MQL gets assigned instantly with a clear SLA +**Notes:** Set enrollment criteria to exclude leads already owned by a rep + +--- + +### 2. MQL SLA Escalation + +**Name:** MQL SLA Breach Alert +**Trigger:** Contact property "Lifecycle Stage" equals "MQL" AND "Days since last contacted" is greater than 0.5 (12 hours) +**Actions:** +1. Send internal email to contact owner: "SLA warning: [Contact Name] has not been contacted" +2. If still no activity after 24 hours → send alert to sales manager +3. If still no activity after 48 hours → reassign contact owner via rotation +4. Create task for new owner: "Urgent: Contact [Contact Name] — reassigned due to SLA breach" +**Outcome:** No MQL goes unworked for more than 48 hours +**Notes:** Exclude contacts where last activity type is "Call" or "Meeting" (already engaged) + +--- + +### 3. Lead Scoring Update and MQL Promotion + +**Name:** Auto-MQL on Score Threshold +**Trigger:** Contact property "HubSpot Score" is greater than or equal to 65 +**Actions:** +1. Set lifecycle stage to "Marketing Qualified Lead" +2. Set "MQL Date" to current date +3. Suppress from marketing nurture workflows +4. Trigger MQL Alert workflow (recipe #1) +**Outcome:** Leads automatically promote to MQL when they hit the scoring threshold +**Notes:** Add suppression list for existing customers and competitors + +--- + +### 4. Meeting Booked Notification + +**Name:** Meeting Booked Alert to AE +**Trigger:** Meeting activity is logged for contact (via Calendly/HubSpot meetings) +**Actions:** +1. Send internal email to contact owner with meeting details +2. Update contact property "Last Meeting Booked" to current date +3. If lifecycle stage is "Lead" → update to "MQL" +4. Create task: "Prepare for meeting with [Contact Name]" — due 1 hour before meeting +5. Send Slack notification to #meetings channel +**Outcome:** AEs are prepared for every meeting with full context +**Notes:** Include recent page views and content downloads in notification email + +--- + +### 5. Closed-Won Handoff to CS + +**Name:** Customer Onboarding Trigger +**Trigger:** Deal stage is changed to "Closed Won" +**Actions:** +1. Update associated contact lifecycle stage to "Customer" +2. Set "Customer Since" date to current date +3. Assign contact owner to CS team member (based on segment/territory) +4. Create task for CS: "Schedule kickoff call with [Company Name]" — due in 2 business days +5. Enroll contact in "Customer Onboarding" email sequence +6. Send internal notification to CS manager +7. Remove from all sales sequences +**Outcome:** Seamless handoff from sales to customer success +**Notes:** Include deal notes, contract value, and key stakeholders in CS notification + +--- + +### 6. Stale Deal Alert + +**Name:** Pipeline Hygiene — Stale Deal Detection +**Trigger:** Deal property "Days in current stage" is greater than [2x average for that stage] +**Actions:** +1. Send internal email to deal owner: "Deal stale alert: [Deal Name] has been in [Stage] for [X] days" +2. Create task: "Update or close [Deal Name]" — due in 3 business days +3. If no update after 7 days → alert sales manager +4. Add to "Stale Deals" dashboard list +**Outcome:** Pipeline stays clean and forecast stays accurate +**Notes:** Customize thresholds per stage (Discovery: 14 days, Proposal: 10 days, Negotiation: 21 days) + +--- + +### 7. Recycled Lead Nurture Re-Entry + +**Name:** MQL Recycling to Nurture +**Trigger:** Contact property "Sales Rejection Reason" is known (any value) +**Actions:** +1. Update lifecycle stage to "Recycled" +2. Reset engagement score to baseline (keep fit score) +3. Enroll in "Recycled Lead Nurture" sequence (lower frequency) +4. Set "Recycle Date" to current date +5. Set re-enrollment trigger: if HubSpot Score exceeds threshold again, re-trigger MQL workflow +**Outcome:** Rejected leads get a second chance without clogging the pipeline +**Notes:** Track recycled-to-MQL conversion rate as a separate metric + +--- + +### 8. Lead Activity Digest + +**Name:** Daily Lead Activity Summary +**Trigger:** Scheduled — daily at 8:00 AM local time +**Actions:** +1. Filter contacts: lifecycle stage is "SQL" or "Opportunity" AND had website activity in last 24 hours +2. Send digest email to each contact owner with their leads' activity +3. Include: pages visited, content downloaded, emails opened/clicked +**Outcome:** Sales reps start each day knowing which leads are active +**Notes:** Only include leads with meaningful activity (exclude single homepage visits) + +--- + +## Salesforce Flow Equivalents + +### 1. MQL Alert and Assignment (Salesforce Flow) + +**Type:** Record-Triggered Flow +**Object:** Lead +**Trigger:** Lead field "Status" is changed to "MQL" +**Flow steps:** +1. Get Records: Query "Rep Assignment" custom object for next available rep +2. Update Records: Set Lead Owner to assigned rep +3. Create Records: Create Task — "Contact MQL: {Lead.Name}" with due date = NOW + 4 hours +4. Action: Send email alert to new lead owner +5. Update Records: Update "Rep Assignment" last-assigned timestamp +**Notes:** Use a custom "Rep Assignment" object to manage round-robin state + +### 2. SLA Escalation (Salesforce Flow) + +**Type:** Scheduled-Triggered Flow +**Schedule:** Every 4 hours during business hours +**Flow steps:** +1. Get Records: Leads where Status = "MQL" AND LastActivityDate < TODAY - 1 +2. Decision: Is lead older than 48 hours with no activity? + - YES → Reassign to next rep, create urgent task, alert manager + - NO → Send reminder email to current owner +**Notes:** Pair with Process Builder for real-time alerts on initial assignment + +### 3. Pipeline Stage Automation (Salesforce Flow) + +**Type:** Record-Triggered Flow +**Object:** Opportunity +**Trigger:** Stage field is updated +**Flow steps:** +1. Decision: Which stage was it changed to? +2. For each stage: + - **Discovery:** Create task "Complete discovery questionnaire" + - **Demo:** Create task "Prepare demo environment" + - **Proposal:** Create task "Send proposal" + alert deal desk if ACV > $25K + - **Closed Won:** Trigger CS handoff (create Case, assign CS owner, send welcome email) + - **Closed Lost:** Create task "Log loss reason" + add to win/loss analysis report + +### 4. Stale Deal Detection (Salesforce Flow) + +**Type:** Scheduled-Triggered Flow +**Schedule:** Daily at 7:00 AM +**Flow steps:** +1. Get Records: Open Opportunities where Days_In_Stage > Stage_SLA_Threshold +2. Loop through results: + - Create Task: "Update stale deal: {Opportunity.Name}" + - Send email to Opportunity Owner + - If Days_In_Stage > 2x threshold → send email to Owner's Manager +3. Update custom field "Stale Flag" = true for dashboard visibility + +--- + +## Calendly / SavvyCal Integration Patterns + +### Round-Robin Meeting Scheduling + +**Calendly setup:** +1. Create a team event type with all eligible reps +2. Distribution: "Optimize for equal distribution" +3. Availability: Each rep manages their own calendar +4. Buffer: 15 min before and after meetings +5. Minimum notice: 4 hours (avoid last-minute bookings) + +**CRM integration:** +1. Calendly webhook fires on booking +2. Match invitee email to CRM contact +3. If contact exists → assign meeting to contact owner (override round-robin if owned) +4. If new contact → create lead, assign via routing rules, log meeting +5. Set lifecycle stage to MQL (meeting = high intent) + +### SavvyCal Setup + +**Advantages over Calendly:** +- Priority-based scheduling (prefer certain time slots) +- Overlay calendars (show team availability in one view) +- Personalized booking links per rep + +**Integration pattern:** +1. Create team scheduling link with priority rules +2. Webhook on booking → Zapier/Make → CRM +3. Match or create contact, assign owner, create task +4. Send confirmation with meeting prep materials + +### Meeting Routing by Criteria + +``` +Booking form submitted +├─ Company size > 500? (form field) +│ ├─ YES → Route to enterprise AE calendar +│ └─ NO ↓ +├─ Existing customer? (CRM lookup) +│ ├─ YES → Route to account owner's calendar +│ └─ NO ↓ +└─ Round-robin across SDR team +``` + +### No-Show Workflow + +**Trigger:** Meeting time passes + no meeting notes logged within 30 minutes +**Actions:** +1. Wait 30 minutes after scheduled meeting time +2. Check: Was a call or meeting logged? + - YES → No action + - NO → Send "Sorry we missed you" email to prospect +3. Create task: "Reschedule with [Contact Name]" — due next business day +4. If second no-show → flag contact and alert manager + +--- + +## Zapier Cross-Tool Patterns + +### 1. New Lead → CRM + Slack + Task + +**Trigger:** New form submission (Typeform, HubSpot, Webflow) +**Actions:** +1. Create/update contact in CRM +2. Enrich with Clearbit (if available) +3. Post to Slack #new-leads with enriched data +4. Create task in project management tool (Asana, Linear) + +### 2. Meeting Booked → CRM + Prep Email + +**Trigger:** New Calendly/SavvyCal booking +**Actions:** +1. Find or create CRM contact +2. Update lifecycle stage to MQL +3. Send prep email to assigned rep (include CRM link, LinkedIn profile, recent activity) +4. Create pre-meeting task + +### 3. Deal Closed → Onboarding Stack + +**Trigger:** CRM deal stage changed to "Closed Won" +**Actions:** +1. Create customer record in CS tool (Vitally, Gainsight, ChurnZero) +2. Add to onboarding project template +3. Send welcome email via email tool +4. Create Slack channel: #customer-[company-name] +5. Notify CS team in Slack + +### 4. Lead Scoring → Cross-Tool Sync + +**Trigger:** CRM lead score crosses MQL threshold +**Actions:** +1. Update marketing automation platform status +2. Add to retargeting audience (Facebook, Google Ads) +3. Trigger SDR outreach sequence +4. Log event in analytics (Mixpanel, Amplitude) + +### 5. SLA Breach → Multi-Channel Alert + +**Trigger:** CRM task overdue (MQL follow-up task) +**Actions:** +1. Send Slack DM to rep +2. Send email to rep +3. If 2+ hours overdue → Slack DM to manager +4. If 4+ hours overdue → reassign in CRM (via webhook back to CRM) + +### 6. Weekly Pipeline Digest + +**Trigger:** Schedule — every Monday at 8:00 AM +**Actions:** +1. Query CRM for pipeline summary (total value, new deals, stale deals, expected closes) +2. Format as summary +3. Post to Slack #sales-team +4. Send email digest to sales leadership diff --git a/skills/revops/references/lifecycle-definitions.md b/skills/revops/references/lifecycle-definitions.md new file mode 100644 index 00000000..811f9683 --- /dev/null +++ b/skills/revops/references/lifecycle-definitions.md @@ -0,0 +1,278 @@ +# Lifecycle Stage Definitions + +Complete templates for lead lifecycle stages, MQL criteria by business type, SLAs, and rejection/recycling workflows. + +## Stage Templates + +### Subscriber + +**Entry criteria:** +- Opted in to blog, newsletter, or content updates +- No company information required + +**Exit criteria:** +- Provides company information via form or enrichment +- Visits 3+ pages in a session +- Downloads gated content + +**Owner:** Marketing (automated) + +**Actions on entry:** +- Add to newsletter nurture +- Begin tracking engagement score + +--- + +### Lead + +**Entry criteria:** +- Identified contact with name + email + company +- May come from form fill, enrichment, or import + +**Exit criteria:** +- Reaches MQL threshold (fit + engagement) +- Manually qualified by marketing/SDR + +**Owner:** Marketing + +**Actions on entry:** +- Enrich contact data (company size, industry, role) +- Begin scoring +- Add to relevant nurture sequence + +--- + +### MQL (Marketing Qualified Lead) + +**Entry criteria:** +- Meets fit score threshold AND engagement score threshold +- OR triggers high-intent action (demo request, pricing page + form fill) + +**Exit criteria:** +- Sales accepts (becomes SQL) +- Sales rejects (recycled to nurture with reason code) +- No response within SLA (escalated to manager) + +**Owner:** Marketing → Sales (handoff) + +**Actions on entry:** +- Instant alert to assigned sales rep +- Create follow-up task with 4-hour SLA +- Pause marketing nurture sequences +- Log all recent activity for sales context + +--- + +### SQL (Sales Qualified Lead) + +**Entry criteria:** +- Sales rep has had qualifying conversation +- Confirmed: budget, authority, need, or timeline (at least 2 of 4) + +**Exit criteria:** +- Opportunity created with projected value +- Disqualified (recycled with reason code) + +**Owner:** Sales (SDR or AE) + +**Actions on entry:** +- Update lifecycle stage in CRM +- Notify AE if SDR-qualified +- Begin sales sequence if not already in conversation + +--- + +### Opportunity + +**Entry criteria:** +- Formal opportunity created in CRM +- Deal value, close date, and stage assigned + +**Exit criteria:** +- Closed-won or closed-lost + +**Owner:** Sales (AE) + +**Actions on entry:** +- Add to pipeline reporting +- Create deal tasks (proposal, demo, etc.) +- Notify CS if deal is likely to close + +--- + +### Customer + +**Entry criteria:** +- Closed-won deal +- Contract signed and payment terms set + +**Exit criteria:** +- Churns, expands, or renews + +**Owner:** Customer Success / Account Management + +**Actions on entry:** +- Trigger onboarding sequence +- Assign CS manager +- Schedule kickoff call +- Remove from all sales sequences + +--- + +### Evangelist + +**Entry criteria:** +- NPS score 9-10, or active referral behavior +- Agreed to case study, testimonial, or referral program + +**Exit criteria:** +- Ongoing program participation + +**Owner:** Customer Success + Marketing + +**Actions on entry:** +- Add to advocacy program +- Request case study or testimonial +- Invite to referral program +- Feature in marketing campaigns (with permission) + +--- + +## MQL Criteria Templates by Business Type + +### PLG (Product-Led Growth) + +**Fit score (40% weight):** + +| Attribute | Points | +|-----------|--------| +| Company size 10-500 | +15 | +| Company size 500-5000 | +20 | +| Target industry | +10 | +| Decision-maker role | +15 | +| Uses complementary tool | +10 | + +**Engagement score (60% weight) — weight product usage heavily:** + +| Signal | Points | +|--------|--------| +| Created free account | +15 | +| Completed onboarding | +20 | +| Used core feature 3+ times | +25 | +| Invited team member | +20 | +| Hit usage limit | +15 | +| Visited pricing page | +10 | + +**MQL threshold:** 65 points + +--- + +### Sales-Led (Enterprise) + +**Fit score (60% weight) — weight fit heavily:** + +| Attribute | Points | +|-----------|--------| +| Company size 500+ | +20 | +| Target industry | +15 | +| VP+ title | +20 | +| Budget authority confirmed | +15 | +| Uses competitor product | +10 | + +**Engagement score (40% weight):** + +| Signal | Points | +|--------|--------| +| Requested demo | +25 | +| Attended webinar | +10 | +| Downloaded whitepaper | +10 | +| Visited pricing page 2+ times | +15 | +| Engaged with sales email | +10 | + +**MQL threshold:** 70 points + +--- + +### Mid-Market (Balanced) + +**Fit score (50% weight):** + +| Attribute | Points | +|-----------|--------| +| Company size 50-1000 | +15 | +| Target industry | +10 | +| Manager+ title | +15 | +| Target geography | +10 | + +**Engagement score (50% weight):** + +| Signal | Points | +|--------|--------| +| Demo request | +25 | +| Free trial signup | +20 | +| Pricing page visit | +10 | +| Content download (2+) | +10 | +| Email click (3+) | +10 | +| Webinar attendance | +10 | + +**MQL threshold:** 60 points + +--- + +## SLA Templates + +### MQL-to-SQL SLA + +| Metric | Target | Escalation | +|--------|--------|------------| +| First contact attempt | Within 4 business hours | Alert to sales manager at 4 hours | +| Qualification decision | Within 48 hours | Auto-escalate at 48 hours | +| Meeting scheduled (if qualified) | Within 5 business days | Weekly pipeline review flag | + +### SQL-to-Opportunity SLA + +| Metric | Target | Escalation | +|--------|--------|------------| +| Discovery call completed | Within 3 business days of SQL | Alert to AE manager | +| Opportunity created | Within 5 business days of SQL | Pipeline review flag | + +### Opportunity-to-Close SLA + +| Metric | Target | Escalation | +|--------|--------|------------| +| Proposal delivered | Within 5 business days of demo | AE manager alert | +| Deal stale in stage | 2x average days for that stage | Pipeline review flag | +| Close date pushed 2+ times | Immediate | Forecast review required | + +--- + +## Lead Rejection and Recycling + +### Rejection Reason Codes + +| Code | Reason | Recycle Action | +|------|--------|----------------| +| **FIT-01** | Company too small | Nurture; re-score if company grows | +| **FIT-02** | Wrong industry | Archive; do not recycle | +| **FIT-03** | Wrong role / no authority | Nurture; monitor for org changes | +| **ENG-01** | No response after 3 attempts | Recycle to nurture in 90 days | +| **ENG-02** | Interested but bad timing | Recycle to nurture; re-engage in 60 days | +| **QUAL-01** | No budget | Recycle to nurture in 90 days | +| **QUAL-02** | Using competitor, locked in | Recycle; trigger before contract renewal | +| **QUAL-03** | Not a real project | Archive; do not recycle | + +### Recycling Workflow + +1. Sales rejects MQL with reason code +2. CRM updates lifecycle stage to "Recycled" +3. Lead enters recycling nurture sequence (different from original nurture) +4. Engagement score resets to baseline (keep fit score) +5. If lead re-engages and crosses MQL threshold, re-route to sales with "Recycled MQL" flag +6. Track recycled MQL conversion rate separately + +### Recycling Nurture Sequence + +- **Frequency:** Bi-weekly or monthly (lower frequency than initial nurture) +- **Content:** Industry insights, case studies, product updates +- **Duration:** 6 months, then archive if no engagement +- **Re-MQL trigger:** High-intent action (demo request, pricing page revisit) diff --git a/skills/revops/references/routing-rules.md b/skills/revops/references/routing-rules.md new file mode 100644 index 00000000..75bbf2d2 --- /dev/null +++ b/skills/revops/references/routing-rules.md @@ -0,0 +1,203 @@ +# Lead Routing Rules + +Decision trees, platform-specific configurations, territory routing, ABM routing, and speed-to-lead benchmarks. + +## Routing Decision Tree + +Use this template to map your routing logic: + +``` +New Lead Arrives +│ +├─ Is this a named/target account? +│ ├─ YES → Route to assigned account owner +│ └─ NO ↓ +│ +├─ Is ACV likely > $50K? (based on company size + industry) +│ ├─ YES → Route to enterprise AE team +│ └─ NO ↓ +│ +├─ Is this a PLG signup with team usage? +│ ├─ YES → Route to PLG sales specialist +│ └─ NO ↓ +│ +├─ Does lead match a territory? +│ ├─ YES → Route to territory owner +│ └─ NO ↓ +│ +└─ Default: Round-robin across available reps + └─ If no rep available: Assign to team queue with 1-hour SLA +``` + +Customize this tree for your business. The key principle: **route to the most specific match first, fall back to general.** + +--- + +## Round-Robin Configuration + +### Basic Round-Robin Rules + +1. Distribute leads evenly across eligible reps +2. Skip reps who are on PTO, at capacity, or have a full pipeline +3. Weight by quota attainment (reps below quota get slight priority) +4. Reset distribution count weekly or monthly +5. Log every assignment for auditing + +### HubSpot Round-Robin Setup + +**Using HubSpot's rotation tool:** +- Navigate to Automation → Workflows +- Trigger: Contact property "Lifecycle Stage" equals "MQL" +- Action: Rotate contact owner among selected users +- Options: Even distribution, skip unavailable owners +- Add delay + task creation after assignment + +**Custom rotation with workflows:** +1. Create a custom property "Rotation Counter" (number) +2. Workflow trigger: New MQL created +3. Branch by rotation counter value (0, 1, 2... for each rep) +4. Set contact owner to corresponding rep +5. Increment counter (reset at max) +6. Create follow-up task with SLA deadline + +### Salesforce Round-Robin Setup + +**Using Lead Assignment Rules:** +1. Setup → Feature Settings → Marketing → Lead Assignment Rules +2. Create rule entries in priority order (most specific first) +3. For round-robin: Use assignment rule + custom logic + +**Using Flow for advanced routing:** +1. Create a Record-Triggered Flow on Lead creation +2. Get Records: Query a custom "Rep Queue" object for next available rep +3. Decision element: Check rep availability, capacity, territory +4. Update Records: Assign lead owner +5. Create Task: Follow-up task with SLA +6. Update "Rep Queue" to track last assignment + +--- + +## Territory Routing + +### By Geography + +| Territory | Regions | Assigned Team | +|-----------|---------|---------------| +| West | CA, WA, OR, NV, AZ, UT, CO, HI | Team West | +| Central | TX, IL, MN, MO, OH, MI, WI, IN | Team Central | +| East | NY, MA, PA, NJ, CT, VA, FL, GA | Team East | +| International | All non-US | International team | + +### By Company Size + +| Segment | Company Size | Team | +|---------|-------------|------| +| SMB | 1-50 employees | Inside sales | +| Mid-market | 51-500 employees | Mid-market AEs | +| Enterprise | 501-5000 employees | Enterprise AEs | +| Strategic | 5000+ employees | Strategic account team | + +### By Industry + +| Vertical | Industries | Specialist | +|----------|-----------|------------| +| Tech | SaaS, IT services, hardware | Tech vertical rep | +| Financial | Banking, insurance, fintech | Financial vertical rep | +| Healthcare | Hospitals, pharma, healthtech | Healthcare vertical rep | +| General | All others | General pool (round-robin) | + +### Hybrid Territory Model + +Combine multiple dimensions for precision: + +``` +Lead arrives +├─ Company size > 1000? +│ ├─ YES → Enterprise team +│ │ └─ Sub-route by geography +│ └─ NO ↓ +├─ Industry = Healthcare or Financial? +│ ├─ YES → Vertical specialist +│ └─ NO ↓ +└─ Round-robin across general pool + └─ Weighted by geography preference +``` + +--- + +## Named Account / ABM Routing + +### Setup + +1. **Define target account list** (typically 50-500 accounts) +2. **Assign account owners** in CRM (1 rep per account) +3. **Match logic:** Any lead from a target account domain routes to account owner +4. **Matching rules:** + - Email domain match (primary) + - Company name fuzzy match (secondary, requires manual review) + - IP-to-company resolution (tertiary, for anonymous visitors) + +### ABM Routing Rules + +| Tier | Account Type | Routing | Response SLA | +|------|-------------|---------|--------------| +| Tier 1 | Top 20 strategic accounts | Named owner, instant alert | 1 hour | +| Tier 2 | Top 100 target accounts | Named owner, standard alert | 4 hours | +| Tier 3 | Target industry / size match | Territory or round-robin | Same business day | + +### Multi-Contact Handling + +When multiple contacts from the same account engage: +- Route all contacts to the **same account owner** +- Notify the owner of new contacts entering +- Track account-level engagement score (sum of all contacts) +- Trigger "buying committee" alert when 3+ contacts from one account engage + +--- + +## Speed-to-Lead Data + +### Response Time Impact on Conversion + +| Response Time | Relative Qualification Rate | Notes | +|---------------|---------------------------|-------| +| Under 5 minutes | **21x** more likely to qualify | Gold standard | +| 5-10 minutes | 10x more likely | Still strong | +| 10-30 minutes | 4x more likely | Acceptable for most | +| 30 min - 1 hour | 2x more likely | Below best practice | +| 1-24 hours | Baseline | Industry average | +| 24+ hours | 60% lower than baseline | Lead is effectively cold | + +Source: Lead Connect, InsideSales.com + +### Implementing Speed-to-Lead + +1. **Instant notification** — Push notification + email to rep on MQL creation +2. **Auto-task with timer** — Create task with 5-minute SLA countdown +3. **Escalation chain:** + - 5 min: Original rep alerted + - 15 min: Backup rep alerted + - 30 min: Manager alerted + - 1 hour: Lead reassigned to next available rep +4. **Measure and report** — Track actual response times weekly; recognize fast responders + +### Speed-to-Lead Automation + +**Trigger:** New MQL created +**Actions:** +1. Assign to rep via routing rules (instant) +2. Send push notification + email to rep +3. Create task: "Contact [Lead Name] — 5 min SLA" +4. Start SLA timer +5. If no activity logged in 15 min → alert backup rep +6. If no activity in 30 min → alert manager +7. If no activity in 60 min → reassign via round-robin + +### Measuring Speed-to-Lead + +Track these metrics weekly: +- **Average time to first contact** (from MQL creation to first call/email) +- **Median time to first contact** (less skewed by outliers) +- **% of leads contacted within SLA** (target: 90%+) +- **Contact rate by time of day** (identify coverage gaps) +- **Conversion rate by response time** (prove the ROI of speed) diff --git a/skills/revops/references/scoring-models.md b/skills/revops/references/scoring-models.md new file mode 100644 index 00000000..743d1de5 --- /dev/null +++ b/skills/revops/references/scoring-models.md @@ -0,0 +1,247 @@ +# Lead Scoring Models + +Detailed scoring templates, example models by business type, and calibration guidance. + +## Explicit Scoring Template (Fit) + +### Company Attributes + +| Attribute | Criteria | Points | +|-----------|----------|--------| +| **Company size** | 1-10 employees | +5 | +| | 11-50 employees | +10 | +| | 51-200 employees | +15 | +| | 201-1000 employees | +20 | +| | 1000+ employees | +15 (unless enterprise-focused, then +25) | +| **Industry** | Primary target industry | +20 | +| | Secondary target industry | +10 | +| | Non-target industry | 0 | +| **Revenue** | Under $1M | +5 | +| | $1M-$10M | +10 | +| | $10M-$100M | +15 | +| | $100M+ | +20 | +| **Geography** | Primary market | +10 | +| | Secondary market | +5 | +| | Non-target market | 0 | + +### Contact Attributes + +| Attribute | Criteria | Points | +|-----------|----------|--------| +| **Job title** | C-suite (CEO, CTO, CMO) | +25 | +| | VP level | +20 | +| | Director level | +15 | +| | Manager level | +10 | +| | Individual contributor | +5 | +| **Department** | Primary buying department | +15 | +| | Adjacent department | +5 | +| | Unrelated department | 0 | +| **Seniority** | Decision maker | +20 | +| | Influencer | +10 | +| | End user | +5 | + +### Technology Attributes + +| Attribute | Criteria | Points | +|-----------|----------|--------| +| **Tech stack** | Uses complementary tool | +15 | +| | Uses competitor | +10 (they understand the category) | +| | Uses tool you replace | +20 | +| **Tech maturity** | Modern stack (cloud, SaaS-forward) | +10 | +| | Legacy stack | +5 | + +--- + +## Implicit Scoring Template (Engagement) + +### High-Intent Signals + +| Signal | Points | Decay | +|--------|--------|-------| +| **Demo request** | +30 | None | +| **Pricing page visit** | +20 | -5 per week | +| **Free trial signup** | +25 | None | +| **Contact sales form** | +30 | None | +| **Case study page (2+)** | +15 | -5 per 2 weeks | +| **Comparison page visit** | +15 | -5 per week | +| **ROI calculator used** | +20 | -5 per 2 weeks | + +### Medium-Intent Signals + +| Signal | Points | Decay | +|--------|--------|-------| +| **Webinar registration** | +10 | -5 per month | +| **Webinar attendance** | +15 | -5 per month | +| **Whitepaper download** | +10 | -5 per month | +| **Blog visit (3+ in a week)** | +10 | -5 per 2 weeks | +| **Email click** | +5 per click | -2 per month | +| **Email open (3+)** | +5 | -2 per month | +| **Social media engagement** | +5 | -2 per month | + +### Low-Intent Signals + +| Signal | Points | Decay | +|--------|--------|-------| +| **Single blog visit** | +2 | -2 per month | +| **Newsletter open** | +2 | -1 per month | +| **Single email open** | +1 | -1 per month | +| **Visited homepage only** | +1 | -1 per week | + +### Product Usage Signals (PLG) + +| Signal | Points | Decay | +|--------|--------|-------| +| **Created account** | +15 | None | +| **Completed onboarding** | +20 | None | +| **Used core feature (3+ times)** | +25 | -5 per month inactive | +| **Invited team member** | +25 | None | +| **Hit usage limit** | +20 | -10 per month | +| **Exported data** | +10 | -5 per month | +| **Connected integration** | +15 | None | +| **Daily active for 5+ days** | +20 | -10 per 2 weeks inactive | + +--- + +## Negative Scoring Signals + +| Signal | Points | Notes | +|--------|--------|-------| +| **Competitor email domain** | -50 | Auto-flag for review | +| **Student email (.edu)** | -30 | May still be valid in some cases | +| **Personal email (gmail, yahoo)** | -10 | Less relevant for B2B; adjust for SMB | +| **Unsubscribe from emails** | -20 | Reduce engagement score | +| **Bounce (hard)** | -50 | Remove from scoring | +| **Spam complaint** | -100 | Remove from all sequences | +| **Job title: Student/Intern** | -25 | Low buying authority | +| **Job title: Consultant** | -10 | May be evaluating for client | +| **No website visit in 90 days** | -15 | Score decay | +| **Invalid phone number** | -10 | Data quality signal | +| **Careers page visitor only** | -30 | Likely a job seeker | + +--- + +## Example Scoring Models + +### Model 1: PLG SaaS (ACV $500-$5K) + +**Weight: 30% fit / 70% engagement (heavily favor product usage)** + +**Fit criteria:** +- Company size 10-500: +15 +- Target industry: +10 +- Manager+ role: +10 +- Uses complementary tool: +10 + +**Engagement criteria:** +- Created free account: +15 +- Completed onboarding: +20 +- Used core feature 3+ times: +25 +- Invited team member: +25 +- Hit usage limit: +20 +- Pricing page visit: +15 + +**Negative:** +- Personal email: -10 +- No login in 14 days: -15 +- Competitor domain: -50 + +**MQL threshold: 60 points** +**Recalibration: Monthly** (fast feedback loop with high volume) + +--- + +### Model 2: Enterprise Sales-Led (ACV $50K+) + +**Weight: 60% fit / 40% engagement (fit is critical at this ACV)** + +**Fit criteria:** +- Company size 500+: +20 +- Revenue $50M+: +15 +- Target industry: +15 +- VP+ title: +20 +- Decision maker confirmed: +15 +- Uses competitor: +10 + +**Engagement criteria:** +- Demo request: +30 +- Multiple stakeholders engaged: +20 +- Attended executive webinar: +15 +- Downloaded ROI guide: +10 +- Visited pricing page 2+: +15 + +**Negative:** +- Company too small (<100): -30 +- Individual contributor only: -15 +- Competitor domain: -50 + +**MQL threshold: 75 points** +**Recalibration: Quarterly** (longer sales cycles, smaller sample size) + +--- + +### Model 3: Mid-Market Hybrid (ACV $5K-$25K) + +**Weight: 50% fit / 50% engagement (balanced approach)** + +**Fit criteria:** +- Company size 50-1000: +15 +- Target industry: +10 +- Manager-VP title: +15 +- Target geography: +10 +- Uses complementary tool: +10 + +**Engagement criteria:** +- Demo request or trial signup: +25 +- Pricing page visit: +15 +- Case study download: +10 +- Webinar attendance: +10 +- Email engagement (3+ clicks): +10 +- Blog visits (5+ pages): +10 + +**Negative:** +- Personal email: -10 +- No engagement in 30 days: -10 +- Competitor domain: -50 +- Student/intern title: -25 + +**MQL threshold: 65 points** +**Recalibration: Quarterly** + +--- + +## Threshold Calibration + +### Setting the Initial Threshold + +1. **Pull closed-won data** from the last 6-12 months +2. **Retroactively score** each deal using your new model +3. **Find the natural breakpoint** — what score separated wins from losses? +4. **Set threshold** just below where 80% of closed-won deals would have scored +5. **Validate** against closed-lost — if many closed-lost score above threshold, tighten criteria + +### Calibration Cadence + +| Business Type | Recalibration Frequency | Why | +|---------------|------------------------|-----| +| PLG / High volume | Monthly | Fast feedback loop, lots of data | +| Mid-market | Quarterly | Moderate cycle length | +| Enterprise | Quarterly to semi-annually | Long cycles, small sample size | + +### Calibration Steps + +1. **Pull MQL-to-closed data** for the calibration period +2. **Compare scored MQLs vs. actual outcomes:** + - High score + closed-won = correctly scored + - High score + closed-lost = possible false positive (tighten) + - Low score + closed-won = possible false negative (loosen) +3. **Adjust weights** based on which attributes actually correlated with wins +4. **Adjust threshold** if MQL volume is too high (raise) or too low (lower) +5. **Document changes** and communicate to sales team + +### Warning Signs Your Model Needs Recalibration + +- MQL-to-SQL acceptance rate drops below 30% +- Sales consistently rejects MQLs as "not ready" +- High-scoring leads don't convert; low-scoring leads do +- MQL volume spikes without corresponding revenue +- New product/market changes since last calibration diff --git a/skills/sales-enablement/SKILL.md b/skills/sales-enablement/SKILL.md new file mode 100644 index 00000000..1fc36aae --- /dev/null +++ b/skills/sales-enablement/SKILL.md @@ -0,0 +1,358 @@ +--- +name: sales-enablement +description: "Create sales collateral such as decks, one-pagers, objection docs, demo scripts, playbooks, and proposal templates. Use when a sales team needs assets that help reps move deals forward and close." +risk: unknown +source: "https://github.com/coreyhaines31/marketingskills" +date_added: "2026-03-21" +metadata: + version: 1.1.0 +--- + +# Sales Enablement + +You are an expert in B2B sales enablement. Your goal is to create sales collateral that reps actually use — decks, one-pagers, objection docs, demo scripts, and playbooks that help close deals. + +## When to Use + +- Use when building decks, one-pagers, objection handling docs, or demo scripts. +- Use when a sales team needs collateral tailored to stage, persona, or use case. +- Use when the asset should help reps close deals rather than drive top-of-funnel traffic. + +## Before Starting + +**Check for product marketing context first:** +If `.agents/product-marketing-context.md` exists (or `.claude/product-marketing-context.md` in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task. + +Gather this context (ask if not provided): + +1. **Value Proposition & Differentiators** + - What do you sell and who is it for? + - What makes you different from the next best alternative? + - What outcomes can you prove? + +2. **Sales Motion** + - How do you sell? (self-serve, inside sales, field sales, hybrid) + - Average deal size and sales cycle length + - Key personas involved in the buying decision + +3. **Collateral Needs** + - What specific assets do you need? + - What stage of the funnel are they for? + - Who will use them? (AE, SDR, champion, prospect) + +4. **Current State** + - What materials exist today? + - What's working and what's not? + - What do reps ask for most? + +--- + +## Core Principles + +### Sales Uses What Sales Trusts +Involve reps in creation. Use their language, not marketing's. If reps rewrite your deck before sending it, you wrote the wrong deck. Test drafts with your top performers first. + +### Situation-Specific, Not Generic +Tailor to persona, deal stage, and use case. A deck for a CTO should look different from one for a VP of Sales. A one-pager for post-meeting follow-up serves a different purpose than one for a trade show. + +### Scannable Over Comprehensive +Reps need information in 3 seconds, not 30. Use bold headers, short bullets, and visual hierarchy. If a rep can't find the answer mid-call, the doc has failed. + +### Tie Back to Business Outcomes +Every claim connects to revenue, efficiency, or risk reduction. Features mean nothing without the "so what." Replace "AI-powered analytics" with "cut reporting time by 80%." + +--- + +## Sales Deck / Pitch Deck + +### 10-12 Slide Framework + +1. **Current World Problem** — The pain your buyer lives with today +2. **Cost of the Problem** — What inaction costs (time, money, risk) +3. **The Shift Happening** — Market or technology change creating urgency +4. **Your Approach** — How you solve it differently +5. **Product Walkthrough** — 3-4 key workflows, not a feature tour +6. **Proof Points** — Metrics, logos, analyst recognition +7. **Case Study** — One customer story told well +8. **Implementation / Timeline** — How they get from here to live +9. **ROI / Value** — Expected return and payback period +10. **Pricing Overview** — Transparent, tiered if applicable +11. **Next Steps / CTA** — Clear action with timeline + +### Deck Principles + +- **Story arc, not feature tour.** Every deck tells a story: the world has a problem, there's a better way, here's proof, here's how to get there. +- **One idea per slide.** If you need two points, use two slides. +- **Design for presenting, not reading.** Slides support the conversation — they don't replace it. Minimal text, strong visuals. + +### Customization by Buyer Type + +| Buyer | Emphasize | De-emphasize | +|-------|-----------|--------------| +| Technical buyer | Architecture, security, integrations, API | ROI calculations, business metrics | +| Economic buyer | ROI, payback period, total cost, risk | Technical details, implementation specifics | +| Champion | Internal selling points, quick wins, peer proof | Deep technical or financial detail | + +**For full slide-by-slide guidance**: See [references/deck-frameworks.md](references/deck-frameworks.md) + +--- + +## One-Pagers / Leave-Behinds + +### When to Use + +- **Post-meeting recap** — Reinforce what you discussed, keep momentum +- **Champion internal selling** — Arm your champion to sell for you +- **Trade show handout** — Quick intro that drives follow-up + +### Structure + +1. **Problem statement** — The pain in one sentence +2. **Your solution** — What you do and how +3. **3 differentiators** — Why you vs. alternatives +4. **Proof point** — One strong metric or customer quote +5. **CTA** — Clear next step with contact info + +### Design Principles + +- One page, literally. Front only, or front and back maximum. +- Scannable in 30 seconds. Bold headers, short bullets, whitespace. +- Include your logo, website, and a specific contact (not info@). +- Match your brand but keep it clean — this is a sales tool, not a brand piece. + +**For templates by use case**: See [references/one-pager-templates.md](references/one-pager-templates.md) + +--- + +## Objection Handling Docs + +### Objection Categories + +| Category | Examples | +|----------|----------| +| Price | "Too expensive," "No budget this quarter," "Competitor is cheaper" | +| Timing | "Not the right time," "Maybe next quarter," "Too busy to implement" | +| Competition | "We already use X," "What makes you different?" | +| Authority | "I need to check with my boss," "The committee decides" | +| Status quo | "What we have works fine," "Not broken, don't fix it" | +| Technical | "Does it integrate with X?," "Security concerns," "Can it scale?" | + +### Response Framework + +For each objection, document: + +1. **Objection statement** — Exactly how reps hear it +2. **Why they say it** — The real concern behind the words +3. **Response approach** — How to acknowledge and redirect +4. **Proof point** — Specific evidence that addresses the concern +5. **Follow-up question** — Keep the conversation moving forward + +### Two Formats + +- **Quick-reference table** for live calls — objection, one-line response, proof point. Fits on one screen. +- **Detailed doc** for prep and training — full context, talk tracks, role-play scenarios. + +**For the full objection library**: See [references/objection-library.md](references/objection-library.md) + +--- + +## ROI Calculators & Value Props + +### Calculator Design + +**Inputs** (current state metrics the prospect provides): +- Time spent on manual processes +- Current tool costs +- Error rates or inefficiency metrics +- Team size + +**Calculations** (your formula for value): +- Time saved per week/month/year +- Cost reduction (tools, headcount, errors) +- Revenue impact (faster deals, higher conversion) + +**Outputs** (what the prospect sees): +- Annual ROI percentage +- Payback period in months +- Total 3-year value + +### Value Prop by Persona + +| Persona | Cares About | Lead With | +|---------|-------------|-----------| +| CTO / VP Eng | Architecture, scale, security, team velocity | Technical superiority, integration depth | +| VP Sales | Pipeline, quota attainment, rep productivity | Revenue impact, time savings per rep | +| CFO | Total cost, payback period, risk | ROI, cost reduction, financial predictability | +| End user | Ease of use, daily workflow, learning curve | Time saved, frustration eliminated | + +### Implementation Options + +- **Spreadsheet** — Fastest to build, easy to customize per deal. Works for inside sales. +- **Web tool** — More polished, captures leads, scales better. Worth building if deal volume is high. +- **Slide-based** — ROI story embedded in the deck. Good for executive presentations. + +--- + +## Demo Scripts & Talk Tracks + +### Script Structure + +1. **Opening** (2 min) — Context setting, agenda, confirm goals for the call +2. **Discovery recap** (3 min) — Summarize what you learned, confirm priorities +3. **Solution walkthrough** (15-20 min) — 3-4 key workflows mapped to their pain +4. **Interaction points** — Questions to ask during the demo, not just at the end +5. **Close** (5 min) — Summarize value, propose next steps with timeline + +### Talk Track Types + +| Type | Duration | Focus | +|------|----------|-------| +| Discovery call | 30 min | Qualify, understand pain, map buying process | +| First demo | 30-45 min | Show 3-4 workflows tied to their pain | +| Technical deep-dive | 45-60 min | Architecture, security, integrations, API | +| Executive overview | 20-30 min | Business outcomes, ROI, strategic alignment | + +### Key Principles + +- **Demo after discovery, not before.** If you don't know their pain, you're guessing which features matter. +- **Customize to their use case.** Use their terminology, their data (if possible), their workflow. +- **Leave time for questions.** A demo where the prospect doesn't talk is a demo that doesn't close. + +**For full script templates**: See [references/demo-scripts.md](references/demo-scripts.md) + +--- + +## Case Study Briefs (Sales Format) + +### How Sales Case Studies Differ + +Marketing case studies tell a story. Sales case studies arm reps with fast-access proof. Keep them short, outcome-focused, and tagged for retrieval. + +### Structure + +1. **Customer profile** — Industry, company size, buyer role +2. **Challenge** — What they were struggling with (2-3 sentences) +3. **Solution** — What they implemented (1-2 sentences) +4. **Results** — 3 specific metrics (before/after) +5. **Pull quote** — One sentence from the customer +6. **Tags** — Industry, use case, company size, persona + +### Organization + +Organize case studies so reps can find the right one instantly: +- **By industry** — "Show me a case study for healthcare" +- **By use case** — "Show me someone who used us for X" +- **By company size** — "Show me an enterprise example" + +--- + +## Proposal Templates + +### Structure + +1. **Executive summary** — Their challenge, your solution, expected outcome (1 page max) +2. **Proposed solution** — What you'll deliver, mapped to their requirements +3. **Implementation plan** — Timeline, milestones, responsibilities +4. **Investment** — Pricing, payment terms, what's included +5. **Next steps** — How to move forward, decision timeline + +### Customization Guidance + +- Mirror their language from discovery calls +- Reference specific pain points they mentioned +- Include only relevant case studies (same industry or use case) +- Name the stakeholders you've spoken with + +### Common Mistakes + +- **Too long** — If it's over 10 pages, it won't get read. Aim for 5-7. +- **Too generic** — Templated proposals signal low effort. Customize the exec summary at minimum. +- **Burying the price** — Don't make them hunt for it. Be transparent and confident. + +--- + +## Sales Playbooks + +### What Goes in a Playbook + +- **Buyer profile** — Who you're selling to, their goals and pains +- **Qualification criteria** — BANT, MEDDIC, or your framework +- **Discovery questions** — Organized by topic, not a script +- **Objection handling** — Top 10 objections with responses +- **Competitive positioning** — How you win against each competitor +- **Demo flow** — Recommended sequence for each persona +- **Email templates** — Follow-up, proposal, check-in, breakup + +### When to Build + +- **New product launch** — Reps need a single source of truth +- **New market segment** — Different buyers need different approaches +- **New hire ramp** — Playbooks cut ramp time significantly + +### Keeping It Living + +Playbooks die when they're not updated. Review quarterly, get input from top reps, and remove anything outdated. Assign an owner — if nobody owns it, it rots. + +--- + +## Buyer Persona Cards + +### Card Structure + +| Field | Description | +|-------|-------------| +| Role / title | Common titles and reporting structure | +| Goals | What success looks like for them | +| Pains | What frustrates them daily | +| Top objections | The 3-5 objections you'll hear from this role | +| Evaluation criteria | How they judge solutions | +| Buying process | Their role in the decision, who they influence | +| Messaging angle | The one sentence that resonates most | + +### Persona Types + +- **Economic buyer** — Signs the check. Cares about ROI and risk. +- **Technical buyer** — Evaluates the product. Cares about capabilities and integration. +- **End user** — Uses it daily. Cares about ease and workflow fit. +- **Champion** — Advocates internally. Needs ammunition to sell for you. +- **Blocker** — Opposes the purchase. Understand their concern to neutralize it. + +--- + +## Output Format + +Deliver the right format for each asset type: + +| Asset | Deliverable | +|-------|-------------| +| Sales deck | Slide-by-slide outline with headline, body copy, and speaker notes | +| One-pager | Full copy with layout guidance (visual hierarchy, sections) | +| Objection doc | Table format: objection, response, proof point, follow-up | +| Demo script | Scene-by-scene with timing, talk track, and interaction points | +| ROI calculator | Input fields, formulas, output display with sample data | +| Playbook | Structured document with table of contents and sections | +| Persona card | One-page card format per persona | +| Proposal | Section-by-section copy with customization notes | + +--- + +## Task-Specific Questions + +If context is missing, ask: + +1. What collateral do you need? (deck, one-pager, objection doc, etc.) +2. Who will use it? (AE, SDR, champion, prospect) +3. What sales stage is it for? (prospecting, discovery, demo, negotiation, close) +4. Who is the target persona? (title, seniority, department) +5. What are the top 3 objections you hear most? + +--- + +## Related Skills + +- **competitor-alternatives**: For public-facing comparison and alternative pages +- **copywriting**: For marketing website copy +- **cold-email**: For outbound prospecting emails +- **revops**: For lead lifecycle, scoring, routing, and pipeline management +- **pricing-strategy**: For pricing decisions and packaging +- **product-marketing-context**: For foundational positioning and messaging diff --git a/skills/sales-enablement/evals/evals.json b/skills/sales-enablement/evals/evals.json new file mode 100644 index 00000000..1617f62e --- /dev/null +++ b/skills/sales-enablement/evals/evals.json @@ -0,0 +1,91 @@ +{ + "skill_name": "sales-enablement", + "evals": [ + { + "id": 1, + "prompt": "Help me create a sales deck for our B2B SaaS product. We sell an employee engagement platform to HR directors at companies with 500-5000 employees. Our main differentiator is real-time pulse surveys with AI-powered insights.", + "expected_output": "Should check for product-marketing-context.md first. Should apply the 10-12 slide sales deck framework: Title, Problem/Stakes, Current Solutions Failing, Vision, Product/Solution, How It Works, Proof (case studies/metrics), Pricing, Why Now, and Next Steps. Should tailor the deck to the HR director audience and employee engagement space. Should incorporate the differentiator (real-time pulse surveys + AI insights). Should provide slide-by-slide content recommendations with speaker notes. Should recommend visual direction.", + "assertions": [ + "Checks for product-marketing-context.md", + "Applies 10-12 slide framework", + "Includes Problem, Solution, Proof, Pricing, Next Steps slides", + "Tailors to HR director audience", + "Incorporates stated differentiator", + "Provides slide-by-slide content", + "Includes speaker notes or talking points" + ], + "files": [] + }, + { + "id": 2, + "prompt": "Our sales team keeps getting the same objections. The top ones are: 'we already use SurveyMonkey,' 'we don't have budget right now,' and 'our team is too small to need this.' Help me create an objection handling doc.", + "expected_output": "Should apply the objection handling framework with the response structure for each objection. Should categorize the objections (competitor/status quo, budget, need/timing). For each objection, should provide: acknowledge, reframe, evidence/proof, bridge to value, and follow-up question. Should provide 2-3 response variations per objection for different contexts. Should organize as a document sales reps can reference quickly during calls.", + "assertions": [ + "Applies objection handling framework", + "Categorizes the three objections", + "Provides structured response for each (acknowledge, reframe, evidence, bridge)", + "Provides 2-3 response variations per objection", + "Organizes for quick reference during calls", + "Categorizes objections using the skill's framework (competitor, budget, need/timing)" + ], + "files": [] + }, + { + "id": 3, + "prompt": "i need a one-pager we can leave behind after sales meetings. something that summarizes our product and key benefits.", + "expected_output": "Should trigger on casual phrasing. Should apply the one-pager/leave-behind framework. Should include: headline with core value proposition, key benefits (3-5), social proof (customer logos, key metric), how it works (simplified), pricing summary or 'starting at' range, and clear next step CTA. Should recommend design principles for a one-pager: scannable, visual hierarchy, not text-heavy. Should note this should fit on one page (front, or front and back).", + "assertions": [ + "Triggers on casual phrasing", + "Applies one-pager/leave-behind framework", + "Includes headline, benefits, social proof, how it works, CTA", + "Keeps to one page format", + "Recommends scannable design", + "Provides specific content for each section" + ], + "files": [] + }, + { + "id": 4, + "prompt": "Create a demo script for our analytics dashboard product. Typical demo is 30 minutes with a VP of Marketing.", + "expected_output": "Should apply the demo script/talk track framework with the 5-part structure. Should include: opening (rapport, agenda setting, discovery questions), problem validation (confirm their pain), solution walkthrough (show product addressing their pain), proof points (metrics, case studies during demo), and close (next steps, timeline). Should time-box each section for 30 minutes. Should include key questions to ask during discovery. Should note when to customize based on prospect's answers.", + "assertions": [ + "Applies 5-part demo script structure", + "Includes opening with discovery questions", + "Includes problem validation", + "Includes solution walkthrough", + "Includes proof points", + "Includes close with next steps", + "Time-boxes for 30 minutes", + "Notes customization based on prospect responses" + ], + "files": [] + }, + { + "id": 5, + "prompt": "Help me build an ROI calculator we can use during sales calls. We need to show prospects how much money they'll save by switching to our product.", + "expected_output": "Should apply the ROI calculator framework. Should define inputs (what data to collect from the prospect: team size, current costs, time spent on manual processes), calculation methodology (how to compute savings), and output format (visual showing ROI timeline, payback period, annual savings). Should recommend keeping calculations transparent and conservative. Should suggest validating assumptions during the sales call. Should provide the calculator structure and formula logic.", + "assertions": [ + "Applies ROI calculator framework", + "Defines required inputs", + "Provides calculation methodology", + "Recommends conservative assumptions", + "Includes ROI timeline and payback period", + "Suggests validating assumptions during calls", + "Provides calculator structure" + ], + "files": [] + }, + { + "id": 6, + "prompt": "We need a public comparison page showing how we stack up against Zendesk and Intercom.", + "expected_output": "Should recognize this is a public-facing competitor comparison page, not internal sales collateral. Should defer to or cross-reference the competitor-alternatives skill, which handles public comparison and alternatives pages. Sales-enablement covers internal materials (battle cards, objection handling) while competitor-alternatives handles SEO-focused public comparison content.", + "assertions": [ + "Recognizes this as a public comparison page", + "References or defers to competitor-alternatives skill", + "Explains the distinction between internal and public collateral", + "Does not attempt public SEO comparison page using sales enablement patterns" + ], + "files": [] + } + ] +} diff --git a/skills/sales-enablement/references/deck-frameworks.md b/skills/sales-enablement/references/deck-frameworks.md new file mode 100644 index 00000000..218c0fe1 --- /dev/null +++ b/skills/sales-enablement/references/deck-frameworks.md @@ -0,0 +1,263 @@ +# Sales Deck Frameworks + +Detailed slide-by-slide guidance for building sales decks that tell a story and close deals. + +## The Storytelling Arc + +Every great deck follows a narrative structure: **Situation → Complication → Resolution.** + +- **Situation** (Slides 1-3): The world your buyer lives in. Establish shared understanding. +- **Complication** (Slides 2-3): Why the status quo is no longer sustainable. Create urgency. +- **Resolution** (Slides 4-11): Your approach, proof, and path forward. + +The goal is not to present features. The goal is to make the buyer feel understood, then show them a better way. + +--- + +## Slide-by-Slide Template + +### Slide 1: Current World Problem + +**What to include:** +- The challenge your buyer faces daily +- A stat or data point that quantifies the problem +- Visual: simple graphic or striking number + +**What to avoid:** +- Starting with your company or product +- Generic industry trends that don't connect to pain +- More than one core problem + +**Copy prompt:** "What is the one problem that, if you could describe it perfectly, would make your buyer say 'that's exactly my situation'?" + +--- + +### Slide 2: Cost of the Problem + +**What to include:** +- Financial impact (revenue lost, costs incurred) +- Time impact (hours wasted, delays) +- Risk impact (what happens if they do nothing) +- Specific numbers wherever possible + +**What to avoid:** +- Vague claims without data +- Fear-mongering without substance +- Too many metrics (pick 2-3 that hit hardest) + +**Copy prompt:** "If your buyer does nothing for the next 12 months, what does it cost them?" + +--- + +### Slide 3: The Shift Happening + +**What to include:** +- Market trend or technology change creating a new opportunity +- Why "the old way" no longer works +- Why now is the right time to act + +**What to avoid:** +- Hype-driven trends without substance +- Making it about your product yet +- Overly technical explanations + +**Copy prompt:** "What has changed in the market that makes the old approach unsustainable?" + +--- + +### Slide 4: Your Approach + +**What to include:** +- Your philosophy or unique point of view +- How your approach differs from conventional solutions +- The "aha" insight that led to your product + +**What to avoid:** +- Feature lists (too early) +- Jargon or acronyms +- Claiming to be "the only" or "the first" unless provably true + +**Copy prompt:** "What do you believe about solving this problem that most people get wrong?" + +--- + +### Slide 5: Product Walkthrough + +**What to include:** +- 3-4 key workflows that map to the pain from Slide 1 +- Screenshots or product visuals +- Brief description of what each workflow accomplishes + +**What to avoid:** +- Showing every feature +- Dense UI screenshots without callouts +- Talking about technology instead of outcomes + +**Copy prompt:** "Walk through 3 things the buyer would do in your product in their first week." + +--- + +### Slide 6: Proof Points + +**What to include:** +- Customer logos (aim for recognizable names in their industry) +- Key metrics: "X% improvement," "Y hours saved," "Z% increase" +- Analyst recognition, awards, or certifications if relevant + +**What to avoid:** +- Unsubstantiated claims +- Too many logos without context +- Vanity metrics that don't relate to the buyer's pain + +**Copy prompt:** "What are 3 numbers that prove your product works?" + +--- + +### Slide 7: Case Study + +**What to include:** +- One customer story told well: challenge, solution, results +- Specific metrics (before and after) +- Customer quote if available +- Choose a customer similar to the prospect + +**What to avoid:** +- Multiple case studies crammed into one slide +- Generic outcomes without specifics +- Customers from irrelevant industries + +**Copy prompt:** "Tell the story of one customer who went from struggling to succeeding with your product." + +--- + +### Slide 8: Implementation / Timeline + +**What to include:** +- Clear phases with timeline (e.g., Week 1: Setup, Week 2-3: Integration, Week 4: Live) +- What's required from their side vs. yours +- Support resources available + +**What to avoid:** +- Overcomplicating the process +- Hiding time requirements +- Skipping the "what do I need to do?" question + +**Copy prompt:** "How does a customer get from signing to live? What does each week look like?" + +--- + +### Slide 9: ROI / Value + +**What to include:** +- Expected return based on their inputs or industry benchmarks +- Payback period +- Total value over 1-3 years +- Comparison to cost of inaction + +**What to avoid:** +- Unrealistic projections +- ROI without showing your math +- Generic numbers not tied to their situation + +**Copy prompt:** "If they buy today, what does the next 12 months look like in dollars and hours?" + +--- + +### Slide 10: Pricing Overview + +**What to include:** +- Pricing tiers or structure +- What's included at each level +- Recommended plan for their situation + +**What to avoid:** +- Burying the price or being cagey +- Too many options (3 tiers max) +- Surprising them with hidden costs + +**Copy prompt:** "What does it cost, what do they get, and which plan is right for them?" + +--- + +### Slide 11: Next Steps / CTA + +**What to include:** +- Specific next action with timeline ("Start a pilot next week") +- What happens after they say yes +- Your contact information + +**What to avoid:** +- Vague CTAs ("Let's stay in touch") +- Multiple competing next steps +- Ending without energy + +**Copy prompt:** "What is the one thing you want them to do after this meeting?" + +--- + +## Persona Customization Guide + +### Technical Buyer Deck + +**Add:** +- Architecture diagram slide after Product Walkthrough +- Security and compliance details +- Integration ecosystem and API capabilities +- Technical implementation requirements + +**Remove or minimize:** +- ROI calculations (they care about capability, not cost) +- High-level market trends (they want specifics) + +**Adjust tone:** Precise, no fluff, respect their expertise. Avoid marketing superlatives. + +### Economic Buyer Deck + +**Add:** +- Detailed ROI slide with calculations shown +- Total cost of ownership comparison +- Risk mitigation and compliance +- Executive summary slide up front + +**Remove or minimize:** +- Technical details and architecture +- Feature-level walkthroughs +- Implementation specifics (they'll delegate) + +**Adjust tone:** Business-focused, outcome-driven. Speak in dollars and percentages. + +### Champion Deck + +**Add:** +- "Internal selling" slide — key points for them to present to their team +- Quick-win slide — what success looks like in 30 days +- Peer proof — companies like theirs who succeeded +- Objection pre-handling — common pushback they'll face internally + +**Remove or minimize:** +- Deep technical or financial detail +- Anything that requires context they can't relay + +**Adjust tone:** Empowering, equipping. Make them look smart to their boss. + +--- + +## Anti-Patterns + +### The Feature Dump +Every slide is a feature with a screenshot. No story, no "so what," no connection to the buyer's world. Reps click through it; prospects tune out. + +### The Wall of Text +Slides with 200+ words. Nobody reads them during a presentation. If the slide requires reading, it belongs in a leave-behind. + +### The Missing Story Arc +Slides exist in isolation — no narrative flow from problem to solution to proof. The deck feels like a brochure, not a conversation. + +### The Generic Screenshot +Product screenshots without callouts, annotations, or context. The prospect can't tell what they're looking at or why it matters. + +### The Premature Demo +Jumping to product features before establishing the problem. The buyer has no frame of reference for why your features matter. + +### The Kitchen Sink +Trying to address every persona, every use case, every feature in one deck. The result is a 40-slide monster that nobody wants to sit through. diff --git a/skills/sales-enablement/references/demo-scripts.md b/skills/sales-enablement/references/demo-scripts.md new file mode 100644 index 00000000..e9dd0691 --- /dev/null +++ b/skills/sales-enablement/references/demo-scripts.md @@ -0,0 +1,355 @@ +# Demo Script Templates + +Scene-by-scene templates for different call types, with timing, talk tracks, and interaction guidance. + +## Discovery Call Script + +**Duration:** 30 minutes +**Goal:** Qualify the opportunity, understand pain, map the buying process. + +### Scene 1: Opening (3 min) + +**Talk track:** +> "Thanks for taking the time, [Name]. I've done some research on [Company] but I'd love to hear from you directly. My goal for today is to understand what you're working on and see if there's a fit — and if there's not, I'll tell you that too. Sound good?" + +**What to establish:** +- Set the agenda and time expectation +- Position yourself as a peer, not a pitch person +- Get permission to ask questions + +--- + +### Scene 2: Situation Questions (7 min) + +**Questions to ask:** +- "Can you walk me through how your team handles [relevant process] today?" +- "What tools are you currently using for this?" +- "How many people are involved in this workflow?" +- "How long has this been in place?" + +**What you're listening for:** +- Current process and tools +- Team size and structure +- How established (and how entrenched) the current approach is + +--- + +### Scene 3: Pain Identification (10 min) + +**Questions to ask:** +- "What's the biggest challenge with that process today?" +- "When that breaks down, what happens?" +- "How much time does your team spend on [specific task] per week?" +- "What have you tried to fix this?" +- "If you could wave a magic wand, what would change?" + +**What you're listening for:** +- Specific, quantifiable pain points +- Emotional frustration (not just logical problems) +- Failed attempts to solve this (shows urgency) +- The "magic wand" answer reveals their ideal state + +**Interaction tip:** Take notes visibly. Repeat back what you hear: "So if I understand correctly, the biggest issue is [X], which costs you about [Y] per month. Is that right?" + +--- + +### Scene 4: Impact & Priority (5 min) + +**Questions to ask:** +- "Where does solving this sit on your priority list this quarter?" +- "What happens if you don't solve this in the next 6 months?" +- "Who else is affected by this problem?" +- "Is there budget allocated for solving this?" + +**What you're listening for:** +- Priority level (nice-to-have vs. must-solve) +- Urgency and consequences of inaction +- Organizational breadth of the problem +- Budget signals + +--- + +### Scene 5: Buying Process (3 min) + +**Questions to ask:** +- "If you decided this was the right solution, what does the evaluation process look like?" +- "Who else would be involved in the decision?" +- "Have you evaluated solutions for this before?" +- "What's your timeline for making a decision?" + +**What you're listening for:** +- Decision-making process and stakeholders +- Past evaluation experience (and why they didn't buy) +- Timeline for decision + +--- + +### Scene 6: Close (2 min) + +**Talk track:** +> "Based on what you've shared, I think there's a strong fit — specifically around [pain point 1] and [pain point 2]. What I'd suggest as a next step is a 30-minute demo where I can show you exactly how we'd address those. I'll customize it to your workflow. Does [specific date/time] work?" + +**What to do:** +- Summarize the 2-3 key pain points +- Propose a specific next step with a date +- Send a calendar invite before you hang up + +--- + +## First Demo Script + +**Duration:** 30-45 minutes +**Goal:** Show how your product solves their specific pain. Advance to evaluation/pilot. + +### Scene 1: Opening & Recap (5 min) + +**Talk track:** +> "Last time we spoke, you mentioned [pain point 1], [pain point 2], and [goal]. I've put together a demo focused on those three areas. If I've missed anything, flag it and we'll adjust. Sound good?" + +**What to do:** +- Recap discovery findings to show you listened +- Confirm priorities haven't changed +- Set expectation for what they'll see + +--- + +### Scene 2: Workflow 1 — Primary Pain Point (10 min) + +**Structure:** +1. Restate the pain: "You mentioned [specific problem]..." +2. Show the solution: Walk through the workflow step by step +3. Highlight the outcome: "This means [specific benefit]..." + +**Interaction point (at the 5-min mark):** +> "How does this compare to how you're handling it today?" + +**What to avoid:** +- Showing every feature of this section +- Getting lost in settings or configuration +- Talking for more than 3 minutes without asking a question + +--- + +### Scene 3: Workflow 2 — Secondary Pain Point (8 min) + +**Structure:** +Same as Workflow 1 — restate pain, show solution, highlight outcome. + +**Interaction point:** +> "Is this the kind of visibility your team has been asking for?" + +--- + +### Scene 4: Workflow 3 — Differentiator (7 min) + +**Structure:** +Show something they can't do today and can't get from competitors. + +**Talk track:** +> "This is where we're really different from [competitor/status quo]. [Explain the unique capability]. For example, [Customer] uses this to [specific outcome]." + +**Interaction point:** +> "How would your team use this?" + +--- + +### Scene 5: Proof Point (3 min) + +**Talk track:** +> "Let me share a quick example. [Customer similar to them] was in a similar situation — [brief challenge]. After implementing, they saw [specific metrics]. Their [role] said [quote]." + +**What to do:** +- Choose a case study that matches their industry, size, or use case +- Keep it brief — this is reinforcement, not a presentation + +--- + +### Scene 6: Close (5 min) + +**Talk track:** +> "Based on what we've covered, here's what I'd recommend as next steps: [specific next step]. This typically takes [timeline]. Who else on your team should be involved? I can set up a [follow-up meeting type] for [date]." + +**What to do:** +- Propose a specific next step (not "let me know") +- Identify additional stakeholders to involve +- Set a follow-up date before ending the call +- Send recap email within 2 hours + +--- + +## Technical Deep-Dive Script + +**Duration:** 45-60 minutes +**Goal:** Satisfy technical evaluation criteria. Address architecture, security, and integration concerns. + +### Scene 1: Opening (3 min) + +**Talk track:** +> "I know your goal today is to understand the technical details — architecture, security, integrations, and how this fits your stack. I'll walk through each area and leave plenty of time for questions. What's your top priority for this session?" + +**Attendees:** Typically includes their technical evaluator (engineer, architect, IT lead) plus your SE or solutions engineer. + +--- + +### Scene 2: Architecture Overview (10 min) + +**Cover:** +- High-level architecture diagram +- Infrastructure and hosting (cloud provider, regions) +- Data flow and storage +- Scalability approach +- Uptime SLA and reliability track record + +**Interaction point:** +> "How does this compare to your current infrastructure requirements?" + +--- + +### Scene 3: Security & Compliance (10 min) + +**Cover:** +- Certifications (SOC 2, ISO 27001, HIPAA, etc.) +- Data encryption (at rest, in transit) +- Access controls and authentication (SSO, RBAC) +- Audit logging +- Data residency and privacy (GDPR, CCPA) +- Penetration testing cadence + +**Interaction point:** +> "What are your must-have security requirements? I want to make sure we address them specifically." + +--- + +### Scene 4: Integrations & API (15 min) + +**Cover:** +- Native integrations relevant to their stack +- API capabilities (REST, GraphQL, webhooks) +- Authentication methods +- Rate limits and data sync frequency +- Live demo of relevant integration + +**Interaction point:** +> "Walk me through your current stack — I want to map out exactly how we'd fit in." + +--- + +### Scene 5: Implementation & Migration (5 min) + +**Cover:** +- Implementation timeline and phases +- Data migration process +- Configuration requirements +- Training and onboarding +- Ongoing support model + +**Interaction point:** +> "What does your team's capacity look like for implementation? That helps me scope the right timeline." + +--- + +### Scene 6: Q&A and Close (10 min) + +**Talk track:** +> "What questions do I need to answer for you to feel confident about the technical fit?" + +**What to do:** +- Answer directly — if you don't know, say so and follow up +- Document all questions for follow-up +- Propose next step (security review, proof of concept, pilot) +- Send technical documentation summary within 24 hours + +--- + +## Executive Overview Script + +**Duration:** 20-30 minutes +**Goal:** Get executive buy-in on the business case. Advance to budget approval or decision. + +### Scene 1: Opening (2 min) + +**Talk track:** +> "Thanks for your time, [Name]. [Champion] has been evaluating [your product] and the results look strong. I'll keep this focused on the business impact and what a partnership looks like. I know your time is valuable so I'll aim to leave 10 minutes for questions." + +**What to do:** +- Be concise — executives punish rambling +- Reference the champion and work done so far +- Set a clear agenda + +--- + +### Scene 2: The Problem & Cost (5 min) + +**Talk track:** +> "Based on what [Champion] shared, your team is spending [X hours/$ amount] on [problem]. That's [annual cost]. It's also creating [secondary impact: risk, delays, churn]. This isn't unique to you — it's an industry-wide challenge, and the companies solving it are seeing [outcome]." + +**What to do:** +- Use their numbers, not generic benchmarks +- Connect to metrics they care about (revenue, cost, risk) +- Keep it to 2-3 key points + +--- + +### Scene 3: The Solution & Differentiation (5 min) + +**Talk track:** +> "Here's what we do differently. [One-sentence explanation]. For your team specifically, this means [specific benefit 1] and [specific benefit 2]. [Champion]'s team has already seen [early result or reaction from evaluation]." + +**What to do:** +- High-level, not feature-level +- Tie to their strategic priorities +- Reference the champion's evaluation + +--- + +### Scene 4: ROI & Business Case (5 min) + +**Talk track:** +> "Here's the business case. Based on your team's numbers: [walk through ROI calculation]. Expected payback period is [X months]. Over 3 years, the total value is [$ amount]. [Customer similar to them] saw [specific result] within [timeframe]." + +**What to do:** +- Show the math, not just the conclusion +- Use conservative estimates (executives discount inflated numbers) +- One strong case study, not three weak ones + +--- + +### Scene 5: Q&A and Decision (5-10 min) + +**Talk track:** +> "What questions do you have? And — assuming the business case holds up, what does the decision process look like from here?" + +**What to do:** +- Listen more than talk +- Answer concisely +- Get a clear next step and timeline +- Thank the champion in front of the executive + +--- + +## Interaction Point Guidance + +### When to Ask Questions During Demos + +- **After showing each workflow** — "How does this compare to your current process?" +- **When you see a reaction** — "I noticed you reacted to that — what are you thinking?" +- **Before moving to the next section** — "Any questions on this before we move on?" +- **When showing a differentiator** — "How would your team use this?" +- **At the midpoint** — "Are we covering the right things, or should we adjust?" + +### Questions NOT to Ask During Demos + +- "Does that make sense?" (patronizing) +- "Are you still with me?" (implies they're lost) +- "Isn't that cool?" (salesy) +- Rhetorical questions that don't invite real dialogue + +### How to Handle "Can You Show Me X?" + +When a prospect asks to see something during the demo: + +1. **If it's quick** — show it now, then return to your flow +2. **If it's a tangent** — "Great question. Let me note that and show you after the main flow so we stay on track." +3. **If it's not possible** — "We don't do that today. Here's how customers handle it: [alternative]." + +Never say "I'll get back to you" without writing it down and following up within 24 hours. diff --git a/skills/sales-enablement/references/objection-library.md b/skills/sales-enablement/references/objection-library.md new file mode 100644 index 00000000..22bcbc69 --- /dev/null +++ b/skills/sales-enablement/references/objection-library.md @@ -0,0 +1,270 @@ +# Objection Library + +Common B2B SaaS objections with response frameworks. Organized by category for quick reference. + +## Quick-Reference Table + +For live calls. Find the objection, scan the response, reference the proof. + +| Objection | Response (1-line) | Proof Point | +|-----------|--------------------|-------------| +| "Too expensive" | "Compared to what? Let's look at what the problem costs you today." | ROI case study showing payback in X months | +| "No budget" | "When budget opens up, what would need to be true for this to be a priority?" | Customer who started with a pilot to prove value | +| "Competitor is cheaper" | "They are — here's what you give up at that price point." | Feature comparison + customer who switched | +| "Not the right time" | "What changes next quarter that makes it better timing?" | Cost-of-delay calculation | +| "Maybe next quarter" | "Happy to reconnect. What would a pilot look like before then?" | Customer who started small and expanded | +| "We use X already" | "How's that working for [specific pain area]?" | Customer who switched from X | +| "What makes you different?" | "For teams like yours, the biggest difference is [specific differentiator]." | Side-by-side comparison for their use case | +| "Need to check with my boss" | "Absolutely. What would help you make the case? I can send materials." | Champion one-pager, ROI calculator | +| "The committee decides" | "Who's on the committee and what does each person care about?" | Multi-persona case study | +| "What we have works fine" | "It does work — the question is whether it's costing you more than it should." | Benchmark data showing efficiency gaps | +| "Not broken, don't fix it" | "Agreed — this isn't about fixing, it's about the opportunity cost of the current approach." | Customer who didn't know what they were missing | +| "Does it integrate with X?" | "Yes / Let me check and get you specifics by end of day." | Integration documentation, customer using same stack | +| "Security concerns" | "Completely fair. Here's our security overview — happy to loop in our team." | SOC 2 report, security whitepaper | +| "Can it scale?" | "We serve companies from [small] to [large]. Here's an example at your scale." | Case study at similar scale | +| "We tried something like this before" | "What went wrong? Understanding that helps me show how we're different." | Customer with same failed experience who succeeded with you | + +--- + +## Detailed Objection Responses + +### Price Objections + +#### "It's too expensive" + +**Why they say it:** May be genuine budget constraint, sticker shock, or negotiation tactic. Often means they don't yet see enough value to justify the cost. + +**Response approach:** +1. Don't defend the price immediately. Ask "Compared to what?" +2. Reframe from cost to investment — what does the problem cost them today? +3. Walk through the ROI calculation together +4. If budget is real, explore smaller starting points + +**Talk track:** +> "I hear that. Let me ask — what's the cost of the problem we discussed? You mentioned your team spends [X hours] on [task] every week. At your team's loaded cost, that's roughly [$ amount] per year. Our solution runs [$ price] — so the question is whether eliminating that problem is worth the investment." + +**Proof point:** ROI calculator or case study showing payback period. + +**Follow-up question:** "If the ROI was clear, is this something you'd prioritize this quarter?" + +--- + +#### "We don't have budget for this" + +**Why they say it:** Budget may genuinely be allocated. Or they haven't identified budget because priority isn't established. + +**Response approach:** +1. Validate — budget constraints are real +2. Understand timing — when does budget cycle reset? +3. Explore alternatives — pilot, smaller scope, different budget line +4. Help them build the business case to create budget + +**Talk track:** +> "Totally understand. Two questions: When does your next budget cycle open? And — if we could show clear ROI with a limited pilot, is that something you could fund from a different line item? Sometimes teams fund this from the efficiency savings it creates." + +**Proof point:** Customer who started with a small pilot and expanded after proving ROI. + +**Follow-up question:** "Would it help if I put together an ROI brief you could share with your finance team?" + +--- + +#### "Competitor X is cheaper" + +**Why they say it:** They're comparing prices, possibly without comparing capabilities. May be using competitor price as leverage. + +**Response approach:** +1. Acknowledge the price difference — don't pretend it doesn't exist +2. Shift to total cost of ownership and value delivered +3. Highlight what they lose at the lower price point +4. Share proof from customers who evaluated both + +**Talk track:** +> "You're right, [Competitor] is less expensive. Here's what I've seen from teams who evaluated both: [Competitor] works well for [their strength]. Where it falls short is [specific gap]. Customers like [name] actually switched to us after starting with [Competitor] because [specific reason]. The question is whether [specific capability] is worth the difference for your team." + +**Proof point:** Customer who switched from the competitor, with specific reasons. + +**Follow-up question:** "What's most important to your team — the lowest price or the best fit for [their specific need]?" + +--- + +### Timing Objections + +#### "Not the right time" + +**Why they say it:** Competing priorities, organizational change, genuine capacity constraint, or lack of urgency. + +**Response approach:** +1. Understand what's competing for their attention +2. Quantify the cost of waiting +3. Explore low-commitment next steps that keep momentum +4. Set a concrete follow-up date + +**Talk track:** +> "I get it — timing matters. Can I ask what's taking priority right now? The reason I bring up timing is that every month of [problem], based on our earlier conversation, costs your team roughly [$ amount]. A 3-month delay is [$ amount]. What if we mapped out a start date that works with your calendar so you're not losing that value?" + +**Proof point:** Cost-of-delay calculation based on their specific numbers. + +**Follow-up question:** "What would need to change for this to move up in priority?" + +--- + +#### "Maybe next quarter" + +**Why they say it:** Genuine scheduling, or a polite way of saying "not interested enough right now." + +**Response approach:** +1. Accept the timeline gracefully +2. Propose a small action now that maintains momentum +3. Get a specific date for follow-up +4. Send value in the meantime (content, benchmarks, insights) + +**Talk track:** +> "Next quarter works. To make sure we hit the ground running, would it make sense to do [small next step] now? That way when Q[X] starts, you're not starting from scratch. I'll also send over [relevant content] in the meantime. Can we lock in [specific date] to reconnect?" + +**Proof point:** Customer who started the evaluation process early and was live by their target date. + +**Follow-up question:** "Is there anything I can send between now and then that would be helpful?" + +--- + +### Competition Objections + +#### "We already use X" + +**Why they say it:** They have an existing solution and switching has real costs. May be satisfied, or may have frustrations they haven't voiced. + +**Response approach:** +1. Don't trash the competitor — ask how it's working +2. Probe for specific pain points with their current solution +3. Position as complementary if possible, replacement if not +4. Offer a side-by-side comparison or trial + +**Talk track:** +> "How's that working for you? Specifically, when it comes to [area where you're stronger] — is that meeting your needs? The reason I ask is that most teams who come to us from [Competitor] tell us [specific pain point] was the tipping point. Not saying that's you, but worth exploring." + +**Proof point:** Customer who switched from that specific competitor. + +**Follow-up question:** "If you could change one thing about your current setup, what would it be?" + +--- + +#### "What makes you different?" + +**Why they say it:** They're evaluating options and want a clear differentiator. Sometimes a genuine question, sometimes a test. + +**Response approach:** +1. Don't list features — give the one thing that matters most for their situation +2. Tie the differentiator to their specific pain +3. Back it up with proof +4. Offer to show, not just tell + +**Talk track:** +> "For teams like yours — [their industry/size/use case] — the biggest difference is [specific differentiator]. That matters because [connection to their pain]. For example, [Customer] was evaluating us alongside [Competitor] and chose us because [specific reason]. Want me to walk you through how that works?" + +**Proof point:** Case study of a customer who chose you over alternatives. + +**Follow-up question:** "What's the most important criteria for your decision?" + +--- + +### Authority Objections + +#### "I need to check with my boss" + +**Why they say it:** They may not be the decision maker, or they need internal buy-in to proceed. Could also be a stall tactic. + +**Response approach:** +1. Support them, don't pressure them +2. Arm them with materials to sell internally +3. Offer to join a meeting with their boss +4. Understand what their boss cares about + +**Talk track:** +> "Absolutely — what would help you make the case? I can put together a one-pager that covers the ROI and addresses the concerns your boss is likely to have. Also happy to jump on a quick call with them if that would be helpful. What does your boss typically prioritize — cost savings, risk reduction, or efficiency?" + +**Proof point:** Champion enablement one-pager, ROI calculator. + +**Follow-up question:** "What questions do you think your boss will ask?" + +--- + +#### "A committee decides this" + +**Why they say it:** Enterprise buying involves multiple stakeholders. Genuine process, not a brush-off. + +**Response approach:** +1. Map the buying committee — who's involved and what each person cares about +2. Provide persona-specific materials +3. Offer to present to the committee +4. Help your champion navigate the internal process + +**Talk track:** +> "That makes sense. Can you walk me through who's on the committee and what each person cares about? I can tailor materials for each stakeholder so you're not doing all the heavy lifting. I've also got a deck designed for executive presentations if that would be useful." + +**Proof point:** Multi-stakeholder case study showing how different personas were addressed. + +**Follow-up question:** "Who on the committee is most likely to push back, and what would their concern be?" + +--- + +### Status Quo Objections + +#### "What we have works fine" + +**Why they say it:** Inertia is real. The current solution may be adequate, and change has real costs. + +**Response approach:** +1. Agree — don't argue with their experience +2. Shift from "broken vs. fixed" to "good vs. great" +3. Introduce the concept of opportunity cost +4. Show what peers are achieving + +**Talk track:** +> "It probably does work — and I wouldn't suggest changing something that's truly meeting your needs. The question I'd ask is: is 'works fine' the bar? Teams using [your product] are seeing [specific outcome]. If you're leaving [X% improvement] on the table, is that worth exploring?" + +**Proof point:** Benchmark data showing what's possible vs. status quo. + +**Follow-up question:** "If there were one area where your current approach could be better, what would it be?" + +--- + +### Technical Objections + +#### "Does it integrate with X?" + +**Why they say it:** Integration is a real requirement. They need to know your product fits their stack. + +**Response approach:** +1. Answer directly — yes, no, or "let me check" +2. If yes, provide specifics (native, API, Zapier, etc.) +3. If no, explain alternatives or workarounds +4. Never bluff — they'll find out during evaluation + +**Talk track (if yes):** +> "Yes, we integrate with [X] natively. It takes about [time] to set up. [Customer] runs the same stack and here's how they have it configured." + +**Talk track (if no):** +> "We don't have a native integration with [X] today. Here's what customers typically do: [alternative]. We also have an open API that [description]. Would it help to get our technical team on a call to explore options?" + +**Proof point:** Customer using the same tech stack, integration documentation. + +**Follow-up question:** "What other tools are in your stack that we'd need to work with?" + +--- + +#### "We have security concerns" + +**Why they say it:** Legitimate concern, especially in regulated industries or enterprise. Non-negotiable for many buyers. + +**Response approach:** +1. Take it seriously — never dismiss security concerns +2. Provide documentation proactively (SOC 2, security whitepaper) +3. Offer to loop in your security team +4. Ask about their specific requirements + +**Talk track:** +> "That's exactly the right question to ask. Here's our security overview — we're [SOC 2 Type II / ISO 27001 / etc.] certified, and I can share our full security documentation. We also have a security team that's happy to do a review call with your infosec team. What are your specific requirements?" + +**Proof point:** Security certifications, compliance documentation, customers in regulated industries. + +**Follow-up question:** "Do you have a security questionnaire you'd like us to fill out?" diff --git a/skills/sales-enablement/references/one-pager-templates.md b/skills/sales-enablement/references/one-pager-templates.md new file mode 100644 index 00000000..4902cdc9 --- /dev/null +++ b/skills/sales-enablement/references/one-pager-templates.md @@ -0,0 +1,208 @@ +# One-Pager Templates + +Templates for different one-pager use cases, with layout guidance and copy prompts. + +## Product Overview One-Pager + +The default one-pager. Introduces your product to someone who knows nothing about you. + +### Structure + +``` +[Logo] [Tagline] + +HEADLINE: One sentence describing what you do and who it's for. + +THE PROBLEM +2-3 sentences describing the pain your buyer faces. + +THE SOLUTION +2-3 sentences describing how your product solves it. + +WHY [YOUR PRODUCT] +• Differentiator 1 — One sentence explaining the benefit +• Differentiator 2 — One sentence explaining the benefit +• Differentiator 3 — One sentence explaining the benefit + +PROOF +"Customer quote with specific result." — Name, Title, Company +[Optional: 2-3 metric callouts: "X% improvement", "Y hours saved"] + +[CTA Button/Link] [Contact: name@company.com] +``` + +### Copy Prompts + +- Headline: "What do you do, in one sentence, that makes someone say 'tell me more'?" +- Problem: "What is your buyer struggling with before they find you?" +- Differentiators: "If you could only tell them 3 things, what would make them choose you?" + +--- + +## Use-Case Specific One-Pager + +Tailored to a specific workflow, vertical, or problem. More targeted than the product overview. + +### Structure + +``` +[Logo] [Use Case: e.g., "For Sales Teams"] + +HEADLINE: How [your product] helps [persona] [achieve outcome]. + +THE CHALLENGE +When [persona] needs to [task], they face [specific pain]. +This leads to [consequence]: [time wasted / money lost / risk]. + +HOW IT WORKS +1. [Step 1] — What happens and why it matters +2. [Step 2] — What happens and why it matters +3. [Step 3] — What happens and why it matters + +RESULTS +• [Metric 1]: Before → After +• [Metric 2]: Before → After +• [Metric 3]: Before → After + +CUSTOMER SPOTLIGHT +"Quote about this specific use case." — Name, Title, Company + +[CTA: "See it in action" or "Start a pilot"] [Contact info] +``` + +### When to Use + +- Different buyer personas need different one-pagers +- Industry-specific versions (healthcare, fintech, e-commerce) +- Use-case versions (reporting, onboarding, security) + +--- + +## Post-Meeting Leave-Behind + +Designed to reinforce a conversation that already happened. Summarizes what you discussed and proposes next steps. + +### Structure + +``` +[Logo] [Date of Meeting] + +MEETING RECAP: [Company Name] + +WHAT WE DISCUSSED +• [Pain point 1 they mentioned] +• [Pain point 2 they mentioned] +• [Goal they're trying to achieve] + +HOW [YOUR PRODUCT] HELPS +• [Solution to pain 1] — [Specific capability or workflow] +• [Solution to pain 2] — [Specific capability or workflow] +• [How you help them reach their goal] + +RELEVANT PROOF +"Quote from a similar customer." — Name, Title, Company +[1-2 metrics from a similar customer] + +PROPOSED NEXT STEPS +1. [Next step with date] +2. [Follow-up action] +3. [Decision timeline] + +[Your name] | [Your title] | [Email] | [Phone] +``` + +### Tips + +- Send within 24 hours of the meeting +- Reference specific things they said (shows you listened) +- Keep proposed next steps concrete and time-bound +- This is the asset your champion forwards to their boss + +--- + +## Champion Enablement One-Pager + +Designed specifically for your internal champion to share with their team and leadership. Written to make them look smart. + +### Structure + +``` +[Logo] + +WHY WE'RE EVALUATING [YOUR PRODUCT] + +THE SITUATION +[2-3 sentences about the internal challenge, written as if the champion +is explaining it to their team. Use "we" and "our" language.] + +WHAT [YOUR PRODUCT] DOES +[1-2 sentences. Plain language, no jargon.] + +WHY THIS SOLUTION +• [Reason 1] — How it solves our specific problem +• [Reason 2] — How it compares to what we do today +• [Reason 3] — How it compares to alternatives we evaluated + +EXPECTED IMPACT +• [Metric]: Current state → Expected state +• [Metric]: Current state → Expected state +• [Time to value]: Live within [X weeks] + +WHO ELSE USES IT +[2-3 recognizable company names in their industry] +"Relevant customer quote." — Name, Title, Company + +NEXT STEPS +• [What we're doing next] +• [What we need from the team] +• [Decision timeline] + +Questions? Talk to [Champion name] or [Your name at email]. +``` + +### Why This Works + +- Written in the champion's voice, not yours +- Answers the questions their boss will ask +- Includes peer proof from companies they respect +- Clear ask and timeline to drive internal momentum + +--- + +## Layout Guidance + +### Visual Hierarchy + +1. **Headline** — Largest text, top of page, immediately communicates value +2. **Section headers** — Bold, clear, act as scannable anchors +3. **Body text** — Short sentences, bullet points preferred over paragraphs +4. **Proof elements** — Metrics and quotes should visually stand out (larger font, color, or callout box) +5. **CTA** — Prominent placement, bottom of page or bottom-right + +### Whitespace + +- Margins: at least 0.75" on all sides +- Space between sections: enough to visually separate (don't cram) +- If it feels crowded, cut content. Never shrink font below 9pt. + +### Font Sizing + +| Element | Suggested Size | +|---------|---------------| +| Headline | 18-24pt | +| Section headers | 12-14pt bold | +| Body text | 10-11pt | +| Fine print / footer | 8-9pt | + +### Color + +- Use brand colors for headers and accents +- Keep body text dark (black or near-black) on white +- Limit accent colors to 1-2 for visual consistency +- Use color to draw attention to metrics and CTAs + +### File Format + +- **PDF** for email attachments and leave-behinds +- **Google Slides / PowerPoint** for editable versions reps can customize +- Always include both — reps will customize, prospects want clean PDFs diff --git a/skills/seo-competitor-pages/SKILL.md b/skills/seo-competitor-pages/SKILL.md new file mode 100644 index 00000000..d5e15553 --- /dev/null +++ b/skills/seo-competitor-pages/SKILL.md @@ -0,0 +1,229 @@ +--- +name: seo-competitor-pages +description: > + Generate SEO-optimized competitor comparison and alternatives pages. Covers + "X vs Y" layouts, "alternatives to X" pages, feature matrices, schema markup, + and conversion optimization. Use when user says "comparison page", "vs page", + "alternatives page", "competitor comparison", or "X vs Y". +risk: unknown +source: "https://github.com/AgriciDaniel/claude-seo" +date_added: "2026-03-21" +user-invokable: true +argument-hint: "[url or generate] [competitor]" +allowed-tools: + - Read + - Grep + - Glob + - Bash + - WebFetch +--- + +# Competitor Comparison & Alternatives Pages + +Create high-converting comparison and alternatives pages that target +competitive intent keywords with accurate, structured content. + +## When to Use + +- Use when creating `X vs Y` comparison pages or alternatives pages. +- Use when targeting competitor-intent keywords with SEO landing pages. +- Use when the user needs structured comparison content, feature matrices, or conversion-oriented competitor pages. + +## Page Types + +### 1. "X vs Y" Comparison Pages +- Direct head-to-head comparison between two products/services +- Balanced feature-by-feature analysis +- Clear verdict or recommendation with justification +- Target keyword: `[Product A] vs [Product B]` + +### 2. "Alternatives to X" Pages +- List of alternatives to a specific product/service +- Each alternative with brief summary, pros/cons, best-for use case +- Target keyword: `[Product] alternatives`, `best alternatives to [Product]` + +### 3. "Best [Category] Tools" Roundup Pages +- Curated list of top tools/services in a category +- Ranking criteria clearly stated +- Target keyword: `best [category] tools [year]`, `top [category] software` + +### 4. Comparison Table Pages +- Feature matrix with multiple products in columns +- Sortable/filterable if interactive +- Target keyword: `[category] comparison`, `[category] comparison chart` + +## Comparison Table Generation + +### Feature Matrix Layout +``` +| Feature | Your Product | Competitor A | Competitor B | +|------------------|:------------:|:------------:|:------------:| +| Feature 1 | ✅ | ✅ | ❌ | +| Feature 2 | ✅ | ⚠️ Partial | ✅ | +| Feature 3 | ✅ | ❌ | ❌ | +| Pricing (from) | $X/mo | $Y/mo | $Z/mo | +| Free Tier | ✅ | ❌ | ✅ | +``` + +### Data Accuracy Requirements +- All feature claims must be verifiable from public sources +- Pricing must be current (include "as of [date]" note) +- Update frequency: review quarterly or when competitors ship major changes +- Link to source for each competitor data point where possible + +## Schema Markup Recommendations + +### Product Schema with AggregateRating +```json +{ + "@context": "https://schema.org", + "@type": "Product", + "name": "[Product Name]", + "description": "[Product Description]", + "brand": { + "@type": "Brand", + "name": "[Brand Name]" + }, + "aggregateRating": { + "@type": "AggregateRating", + "ratingValue": "[Rating]", + "reviewCount": "[Count]", + "bestRating": "5", + "worstRating": "1" + } +} +``` + +### SoftwareApplication (for software comparisons) +```json +{ + "@context": "https://schema.org", + "@type": "SoftwareApplication", + "name": "[Software Name]", + "applicationCategory": "[Category]", + "operatingSystem": "[OS]", + "offers": { + "@type": "Offer", + "price": "[Price]", + "priceCurrency": "USD" + } +} +``` + +### ItemList (for roundup pages) +```json +{ + "@context": "https://schema.org", + "@type": "ItemList", + "name": "Best [Category] Tools [Year]", + "itemListOrder": "https://schema.org/ItemListOrderDescending", + "numberOfItems": "[Count]", + "itemListElement": [ + { + "@type": "ListItem", + "position": 1, + "name": "[Product Name]", + "url": "[Product URL]" + } + ] +} +``` + +## Keyword Targeting + +### Comparison Intent Patterns +| Pattern | Example | Search Volume Signal | +|---------|---------|---------------------| +| `[A] vs [B]` | "Slack vs Teams" | High | +| `[A] alternative` | "Figma alternatives" | High | +| `[A] alternatives [year]` | "Notion alternatives 2026" | High | +| `best [category] tools` | "best project management tools" | High | +| `[A] vs [B] for [use case]` | "AWS vs Azure for startups" | Medium | +| `[A] review [year]` | "Monday.com review 2026" | Medium | +| `[A] vs [B] pricing` | "HubSpot vs Salesforce pricing" | Medium | +| `is [A] better than [B]` | "is Notion better than Confluence" | Medium | + +### Title Tag Formulas +- X vs Y: `[A] vs [B]: [Key Differentiator] ([Year])` +- Alternatives: `[N] Best [A] Alternatives in [Year] (Free & Paid)` +- Roundup: `[N] Best [Category] Tools in [Year], Compared & Ranked` + +### H1 Patterns +- Match title tag intent +- Include primary keyword naturally +- Keep under 70 characters + +## Conversion-Optimized Layouts + +### CTA Placement +- **Above fold**: Brief comparison summary with primary CTA +- **After comparison table**: "Try [Your Product] free" CTA +- **Bottom of page**: Final recommendation with CTA +- Avoid aggressive CTAs in competitor description sections (reduces trust) + +### Social Proof Sections +- Customer testimonials relevant to comparison criteria +- G2/Capterra/TrustPilot ratings (with source links) +- Case studies showing migration from competitor +- "Switched from [Competitor]" stories + +### Pricing Highlights +- Clear pricing comparison table +- Highlight value advantages (not just lowest price) +- Include hidden costs (setup fees, per-user pricing, overage charges) +- Link to full pricing page + +### Trust Signals +- "Last updated [date]" timestamp +- Author with relevant expertise +- Methodology disclosure (how comparisons were conducted) +- Disclosure of own product affiliation + +## Fairness Guidelines + +- **Accuracy**: All competitor information must be verifiable from public sources +- **No defamation**: Never make false or misleading claims about competitors +- **Cite sources**: Link to competitor websites, review sites, or documentation +- **Timely updates**: Review and update when competitors release major changes +- **Disclose affiliation**: Clearly state which product is yours +- **Balanced presentation**: Acknowledge competitor strengths honestly +- **Pricing accuracy**: Include "as of [date]" disclaimers on all pricing data +- **Feature verification**: Test competitor features where possible, cite documentation otherwise + +## Internal Linking + +- Link to your own product/service pages from comparison sections +- Cross-link between related comparison pages (e.g., "A vs B" links to "A vs C") +- Link to feature-specific pages when discussing individual features +- Breadcrumb: Home > Comparisons > [This Page] +- Related comparisons section at bottom of page +- Link to case studies and testimonials mentioned in the comparison + +## Output + +### Comparison Page Template +- `COMPARISON-PAGE.md`: Ready-to-implement page structure with sections +- Feature matrix table +- Content outline with word count targets (minimum 1,500 words) + +### Schema Markup +- `comparison-schema.json`: Product/SoftwareApplication/ItemList JSON-LD + +### Keyword Strategy +- Primary and secondary keywords +- Related long-tail opportunities +- Content gaps vs existing competitor pages + +### Recommendations +- Content improvements for existing comparison pages +- New comparison page opportunities +- Schema markup additions +- Conversion optimization suggestions + +## Error Handling + +| Scenario | Action | +|----------|--------| +| Competitor URL unreachable | Report which competitor URLs failed. Proceed with available data and note gaps in the comparison. | +| Insufficient competitor data (pricing, features unavailable) | Flag missing data points clearly. Use "Not publicly available" in comparison tables rather than guessing. | +| No product/service overlap found | Report that the products serve different markets. Suggest alternative competitors that share feature overlap, or pivot to a category roundup format. | diff --git a/skills/seo-content/SKILL.md b/skills/seo-content/SKILL.md new file mode 100644 index 00000000..5a8db84b --- /dev/null +++ b/skills/seo-content/SKILL.md @@ -0,0 +1,186 @@ +--- +name: seo-content +description: > + Content quality and E-E-A-T analysis with AI citation readiness assessment. + Use when user says "content quality", "E-E-A-T", "content analysis", + "readability check", "thin content", or "content audit". +risk: unknown +source: "https://github.com/AgriciDaniel/claude-seo" +date_added: "2026-03-21" +user-invokable: true +argument-hint: "[url]" +allowed-tools: + - Read + - Grep + - Glob + - Bash + - WebFetch +--- + +# Content Quality & E-E-A-T Analysis + +## When to Use + +- Use when auditing content quality, readability, thin content risk, or E-E-A-T signals. +- Use when the user wants a content-focused SEO review rather than a full technical audit. +- Use when checking whether content is structured and trustworthy enough for search and AI citation. + +## E-E-A-T Framework (updated Sept 2025 QRG) + +Read `seo/references/eeat-framework.md` for full criteria. + +### Experience (first-hand signals) +- Original research, case studies, before/after results +- Personal anecdotes, process documentation +- Unique data, proprietary insights +- Photos/videos from direct experience + +### Expertise +- Author credentials, certifications, bio +- Professional background relevant to topic +- Technical depth appropriate for audience +- Accurate, well-sourced claims + +### Authoritativeness +- External citations, backlinks from authoritative sources +- Brand mentions, industry recognition +- Published in recognized outlets +- Cited by other experts + +### Trustworthiness +- Contact information, physical address +- Privacy policy, terms of service +- Customer testimonials, reviews +- Date stamps, transparent corrections +- Secure site (HTTPS) + +## Content Metrics + +### Word Count Analysis +Compare against page type minimums: +| Page Type | Minimum | +|-----------|---------| +| Homepage | 500 | +| Service page | 800 | +| Blog post | 1,500 | +| Product page | 300+ (400+ for complex products) | +| Location page | 500-600 | + +> **Important:** These are **topical coverage floors**, not targets. Google has confirmed word count is NOT a direct ranking factor. The goal is comprehensive topical coverage; a 500-word page that thoroughly answers the query will outrank a 2,000-word page that doesn't. Use these as guidelines for adequate coverage depth, not rigid requirements. + +### Readability +- Flesch Reading Ease: target 60-70 for general audience + +> **Note:** Flesch Reading Ease is a useful proxy for content accessibility but is NOT a direct Google ranking factor. John Mueller has confirmed Google does not use basic readability scores for ranking. Yoast deprioritized Flesch scores in v19.3. Use readability analysis as a content quality indicator, not as an SEO metric to optimize directly. +- Grade level: match target audience +- Sentence length: average 15-20 words +- Paragraph length: 2-4 sentences + +### Keyword Optimization +- Primary keyword in title, H1, first 100 words +- Natural density (1-3%) +- Semantic variations present +- No keyword stuffing + +### Content Structure +- Logical heading hierarchy (H1 -> H2 -> H3) +- Scannable sections with descriptive headings +- Bullet/numbered lists where appropriate +- Table of contents for long-form content + +### Multimedia +- Relevant images with proper alt text +- Videos where appropriate +- Infographics for complex data +- Charts/graphs for statistics + +### Internal Linking +- 3-5 relevant internal links per 1000 words +- Descriptive anchor text +- Links to related content +- No orphan pages + +### External Linking +- Cite authoritative sources +- Open in new tab for user experience +- Reasonable count (not excessive) + +## AI Content Assessment (Sept 2025 QRG addition) + +Google's raters now formally assess whether content appears AI-generated. + +### Acceptable AI Content +- Demonstrates genuine E-E-A-T +- Provides unique value +- Has human oversight and editing +- Contains original insights + +### Low-Quality AI Content Markers +- Generic phrasing, lack of specificity +- No original insight +- Repetitive structure across pages +- No author attribution +- Factual inaccuracies + +> **Helpful Content System (March 2024):** The Helpful Content System was merged into Google's core ranking algorithm during the March 2024 core update. It no longer operates as a standalone classifier. Helpfulness signals are now weighted within every core update. The same principles apply (people-first content, demonstrating E-E-A-T, satisfying user intent), but enforcement is continuous rather than through separate HCU updates. + +## AI Citation Readiness (GEO signals) + +Optimize for AI search engines (ChatGPT, Perplexity, Google AI Overviews): + +- Clear, quotable statements with statistics/facts +- Structured data (especially for data points) +- Strong heading hierarchy (H1->H2->H3 flow) +- Answer-first formatting for key questions +- Tables and lists for comparative data +- Clear attribution and source citations + +### AI Search Visibility & GEO (2025-2026) + +**Google AI Mode** launched publicly in May 2025 as a separate tab in Google Search, available in 180+ countries. Unlike AI Overviews (which appear above organic results), AI Mode provides a fully conversational search experience with **zero organic blue links**, making AI citation the only visibility mechanism. + +**Key optimization strategies for AI citation:** +- **Structured answers:** Clear question-answer formats, definition patterns, and step-by-step instructions that AI systems can extract and cite +- **First-party data:** Original research, statistics, case studies, and unique datasets are highly cited by AI systems +- **Schema markup:** Article, FAQ (for non-Google AI platforms), and structured content schemas help AI systems parse and attribute content +- **Topical authority:** AI systems preferentially cite sources that demonstrate deep expertise. Build content clusters, not isolated pages +- **Entity clarity:** Ensure brand, authors, and key concepts are clearly defined with structured data (Organization, Person schema) +- **Multi-platform tracking:** Monitor visibility across Google AI Overviews, AI Mode, ChatGPT, Perplexity, and Bing Copilot, not just traditional rankings. Treat AI citation as a standalone KPI alongside organic rankings and traffic. + +**Generative Engine Optimization (GEO):** +GEO is the emerging discipline of optimizing content specifically for AI-generated answers. Key GEO signals include: quotability (clear, concise extractable facts), attribution (source citations within your content), structure (well-organized heading hierarchy), and freshness (regularly updated data). Cross-reference the `seo-geo` skill for detailed GEO workflows. + +## Content Freshness + +- Publication date visible +- Last updated date if content has been revised +- Flag content older than 12 months without update for fast-changing topics + +## Output + +### Content Quality Score: XX/100 + +### E-E-A-T Breakdown +| Factor | Score | Key Signals | +|--------|-------|-------------| +| Experience | XX/25 | ... | +| Expertise | XX/25 | ... | +| Authoritativeness | XX/25 | ... | +| Trustworthiness | XX/25 | ... | + +### AI Citation Readiness: XX/100 + +### Issues Found +### Recommendations + +## DataForSEO Integration (Optional) + +If DataForSEO MCP tools are available, use `kw_data_google_ads_search_volume` for real keyword volume data, `dataforseo_labs_bulk_keyword_difficulty` for difficulty scores, `dataforseo_labs_search_intent` for intent classification, and `content_analysis_summary` for content quality analysis. + +## Error Handling + +| Scenario | Action | +|----------|--------| +| URL unreachable (DNS failure, connection refused) | Report the error clearly. Do not guess page content. Suggest the user verify the URL and try again. | +| Content behind paywall (402/403, login wall) | Report that the content is not publicly accessible. Analyze only the visible portion (meta tags, headers) and note the limitation. | +| Thin content (fewer than 100 words retrievable) | Report the findings as-is rather than guessing. Flag the page as potentially JavaScript-rendered or gated, and suggest the user provide the full text directly. | diff --git a/skills/seo-dataforseo/SKILL.md b/skills/seo-dataforseo/SKILL.md new file mode 100644 index 00000000..7832d9c6 --- /dev/null +++ b/skills/seo-dataforseo/SKILL.md @@ -0,0 +1,395 @@ +--- +name: seo-dataforseo +description: "Use DataForSEO for live SERPs, keyword metrics, backlinks, competitor analysis, on-page checks, and AI visibility data. Trigger when the user needs real SEO data rather than static guidance." +risk: unknown +source: "https://github.com/AgriciDaniel/claude-seo" +date_added: "2026-03-21" +user-invokable: true +argument-hint: "[command] [query]" +allowed-tools: + - Read + - Grep + - Glob + - Bash + - WebFetch + - Write +--- + +# DataForSEO: Live SEO Data (Extension) + +Live search data via the DataForSEO MCP server. Provides real-time SERP results, +keyword metrics, backlink profiles, on-page analysis, content analysis, business +listings, AI visibility checking, and LLM mention tracking across +9 API modules with 79 MCP tools. + +## When to Use + +- Use when the user needs live SEO data instead of static best-practice guidance. +- Use for SERP lookups, keyword volumes, backlink checks, competitor data, or AI visibility tracking. +- Use only when the DataForSEO extension is available in the environment. + +## Prerequisites + +This skill requires the DataForSEO extension to be installed: +```bash +./extensions/dataforseo/install.sh +``` + +**Check availability:** Before using any DataForSEO tool, verify the MCP server +is connected by checking if `serp_organic_live_advanced` or any DataForSEO tool +is available. If tools are not available, inform the user the extension is not +installed and provide install instructions. + +## API Credit Awareness + +DataForSEO charges per API call. Be efficient: +- Prefer bulk endpoints over multiple single calls +- Use default parameters (US, English) unless user specifies otherwise +- Cache results mentally within a session; don't re-fetch the same data +- Warn user before running expensive operations (full backlink crawls, large keyword lists) + +## Quick Reference + +| Command | What it does | +|---------|-------------| +| `/seo dataforseo serp ` | Google organic SERP results | +| `/seo dataforseo serp-youtube ` | YouTube search results | +| `/seo dataforseo youtube ` | YouTube video deep analysis | +| `/seo dataforseo keywords ` | Keyword ideas and suggestions | +| `/seo dataforseo volume ` | Search volume for keywords | +| `/seo dataforseo difficulty ` | Keyword difficulty scores | +| `/seo dataforseo intent ` | Search intent classification | +| `/seo dataforseo trends ` | Google Trends data | +| `/seo dataforseo backlinks ` | Full backlink profile | +| `/seo dataforseo competitors ` | Competitor domain analysis | +| `/seo dataforseo ranked ` | Ranked keywords for domain | +| `/seo dataforseo intersection ` | Keyword/backlink overlap | +| `/seo dataforseo traffic ` | Bulk traffic estimation | +| `/seo dataforseo subdomains ` | Subdomains with ranking data | +| `/seo dataforseo top-searches ` | Top queries mentioning domain | +| `/seo dataforseo onpage ` | On-page analysis (Lighthouse + parsing) | +| `/seo dataforseo tech ` | Technology stack detection | +| `/seo dataforseo whois ` | WHOIS registration data | +| `/seo dataforseo content ` | Content analysis and trends | +| `/seo dataforseo listings ` | Business listings search | +| `/seo dataforseo ai-scrape ` | ChatGPT web scraper for GEO | +| `/seo dataforseo ai-mentions ` | LLM mention tracking for GEO | + +--- + +## SERP Analysis + +### `/seo dataforseo serp ` + +Fetch live Google organic search results. + +**MCP tools:** `serp_organic_live_advanced` + +**Default parameters:** location_code=2840 (US), language_code=en, device=desktop, depth=100 + +**Also supports:** The `serp_organic_live_advanced` tool supports Google, Bing, and Yahoo via the `se` parameter. Specify "bing" or "yahoo" to switch search engines. + +**Output:** Rank, URL, title, description, domain, featured snippets, AI overview references, People Also Ask. + +### `/seo dataforseo serp-youtube ` + +Fetch YouTube search results. Valuable for GEO. YouTube mentions correlate most strongly with AI citations. + +**MCP tools:** `serp_youtube_organic_live_advanced` + +**Output:** Video title, channel, views, upload date, description, URL. + +### `/seo dataforseo youtube ` + +Deep analysis of a specific YouTube video: info, comments, and subtitles. YouTube mentions have the strongest correlation (0.737) with AI visibility, making this critical for GEO analysis. + +**MCP tools:** `serp_youtube_video_info_live_advanced`, `serp_youtube_video_comments_live_advanced`, `serp_youtube_video_subtitles_live_advanced` + +**Parameters:** video_id (the YouTube video ID, e.g., "dQw4w9WgXcQ") + +**Output:** Video metadata (title, channel, views, likes, description), top comments with engagement, subtitle/transcript text. + +--- + +## Keyword Research + +### `/seo dataforseo keywords ` + +Generate keyword ideas, suggestions, and related terms from a seed keyword. + +**MCP tools:** `dataforseo_labs_google_keyword_ideas`, `dataforseo_labs_google_keyword_suggestions`, `dataforseo_labs_google_related_keywords` + +**Default parameters:** location_code=2840 (US), language_code=en, limit=50 + +**Output:** Keyword, search volume, CPC, competition level, keyword difficulty, trend. + +### `/seo dataforseo volume ` + +Get search volume and metrics for a list of keywords. + +**MCP tools:** `kw_data_google_ads_search_volume` + +**Parameters:** keywords (array, comma-separated), location_code, language_code + +**Output:** Keyword, monthly search volume, CPC, competition, monthly trend data. + +### `/seo dataforseo difficulty ` + +Calculate keyword difficulty scores for ranking competitiveness. + +**MCP tools:** `dataforseo_labs_bulk_keyword_difficulty` + +**Parameters:** keywords (array), location_code, language_code + +**Output:** Keyword, difficulty score (0-100), interpretation (Easy/Medium/Hard/Very Hard). + +### `/seo dataforseo intent ` + +Classify keywords by user search intent. + +**MCP tools:** `dataforseo_labs_search_intent` + +**Parameters:** keywords (array), location_code, language_code + +**Output:** Keyword, intent type (informational, navigational, commercial, transactional), confidence score. + +### `/seo dataforseo trends ` + +Analyze keyword trends over time using Google Trends data. + +**MCP tools:** `kw_data_google_trends_explore` + +**Parameters:** keywords (array), location_code, date_from, date_to, language_code + +**Output:** Keyword, time series data, trend direction, seasonality signals. + +--- + +## Domain & Competitor Analysis + +### `/seo dataforseo backlinks ` + +Comprehensive backlink profile analysis. + +**MCP tools:** `backlinks_summary`, `backlinks_backlinks`, `backlinks_anchors`, `backlinks_referring_domains`, `backlinks_bulk_spam_score`, `backlinks_timeseries_summary` + +**Default parameters:** limit=100 per sub-call + +**Output:** Total backlinks, referring domains, domain rank, spam score, top anchors, new/lost backlinks over time, dofollow ratio, top referring domains. + +### `/seo dataforseo competitors ` + +Identify competing domains and estimate traffic. + +**MCP tools:** `dataforseo_labs_google_competitors_domain`, `dataforseo_labs_google_domain_rank_overview`, `dataforseo_labs_bulk_traffic_estimation` + +**Output:** Competitor domains, keyword overlap %, estimated traffic, domain rank, common keywords. + +### `/seo dataforseo ranked ` + +List keywords a domain ranks for with positions and page data. + +**MCP tools:** `dataforseo_labs_google_ranked_keywords`, `dataforseo_labs_google_relevant_pages` + +**Default parameters:** limit=100, location_code=2840 + +**Output:** Keyword, position, URL, search volume, traffic share, SERP features. + +### `/seo dataforseo intersection [...]` + +Find shared keywords and backlink sources across 2-20 domains. + +**MCP tools:** `dataforseo_labs_google_domain_intersection`, `backlinks_domain_intersection` + +**Parameters:** domains (2-20 array) + +**Output:** Shared keywords with positions per domain, shared backlink sources, unique keywords per domain. + +### `/seo dataforseo traffic ` + +Estimate organic search traffic for one or more domains. + +**MCP tools:** `dataforseo_labs_bulk_traffic_estimation` + +**Parameters:** domains (array) + +**Output:** Domain, estimated organic traffic, estimated traffic cost, top keywords. + +### `/seo dataforseo subdomains ` + +Enumerate subdomains with their ranking data and traffic estimates. + +**MCP tools:** `dataforseo_labs_google_subdomains` + +**Parameters:** target (domain), location_code, language_code + +**Output:** Subdomain, ranked keywords count, estimated traffic, organic cost. + +### `/seo dataforseo top-searches ` + +Find the most popular search queries that mention a specific domain in results. + +**MCP tools:** `dataforseo_labs_google_top_searches` + +**Parameters:** target (domain), location_code, language_code + +**Output:** Query, search volume, domain position, SERP features, traffic share. + +--- + +## Technical / On-Page + +### `/seo dataforseo onpage ` + +Run on-page analysis including Lighthouse audit and content parsing. + +**MCP tools:** `on_page_instant_pages`, `on_page_content_parsing`, `on_page_lighthouse` + +**Usage:** +- `on_page_instant_pages`:Quick page analysis (status codes, meta tags, content size, page timing, broken links, on-page checks) +- `on_page_content_parsing`:Extract and parse page content (plain text, word count, structure) +- `on_page_lighthouse`:Full Lighthouse audit (performance score, accessibility, best practices, SEO, Core Web Vitals) + +**Output:** Pages crawled, status codes, meta tags, titles, content size, load times, Lighthouse scores, broken links, resource analysis. + +### `/seo dataforseo tech ` + +Detect technologies used on a domain. + +**MCP tools:** `domain_analytics_technologies_domain_technologies` + +**Output:** Technology name, version, category (CMS, analytics, CDN, framework, etc.). + +### `/seo dataforseo whois ` + +Retrieve WHOIS registration data. + +**MCP tools:** `domain_analytics_whois_overview` + +**Output:** Registrar, creation date, expiration date, nameservers, registrant info (if public). + +--- + +## Content & Business Data + +### `/seo dataforseo content ` + +Analyze content quality, search for content by topic, and track phrase trends. + +**MCP tools:** `content_analysis_search`, `content_analysis_summary`, `content_analysis_phrase_trends` + +**Parameters:** keyword (for search/trends) or URL (for summary) + +**Output:** Content matches with quality scores, sentiment analysis, readability metrics, phrase trend data over time. + +### `/seo dataforseo listings ` + +Search business listings for local SEO competitive analysis. + +**MCP tools:** `business_data_business_listings_search` + +**Parameters:** keyword, location (optional) + +**Output:** Business name, description, category, address, phone, domain, rating, review count, claimed status. + +--- + +## AI Visibility / GEO + +### `/seo dataforseo ai-scrape ` + +Scrape what ChatGPT web search returns for a query. Real GEO visibility check: see which sources ChatGPT cites for your target keywords. + +**MCP tools:** `ai_optimization_chat_gpt_scraper` + +**Parameters:** query, location_code (optional), language_code (optional). Use `ai_optimization_chat_gpt_scraper_locations` to look up available locations. + +**Output:** ChatGPT response content, cited sources/URLs, referenced domains. + +### `/seo dataforseo ai-mentions ` + +Track how LLMs mention brands, domains, and topics. Critical for GEO. Measures actual AI visibility across multiple LLM platforms. + +**MCP tools:** `ai_opt_llm_ment_search`, `ai_opt_llm_ment_top_domains`, `ai_opt_llm_ment_top_pages`, `ai_opt_llm_ment_agg_metrics` + +**Parameters:** keyword, location_code (optional), language_code (optional). Use `ai_opt_llm_ment_loc_and_lang` for available locations/languages and `ai_optimization_llm_models` for supported LLM models. + +**Workflow:** +1. Search LLM mentions with `ai_opt_llm_ment_search` (find mentions of a brand/keyword across LLM responses) +2. Get top cited domains with `ai_opt_llm_ment_top_domains` (which domains are most cited for this topic) +3. Get top cited pages with `ai_opt_llm_ment_top_pages` (which specific pages are most cited) +4. Get aggregate metrics with `ai_opt_llm_ment_agg_metrics` (overall mention volume, trends) + +**Output:** LLM mention count, top cited domains with frequency, top cited pages, mention trends over time, cross-platform visibility scores. + +**Advanced:** Use `ai_opt_llm_ment_cross_agg_metrics` for cross-model comparison (how mentions differ across ChatGPT, Claude, Perplexity, etc.). + +--- + +## Available Utility Tools + +These DataForSEO tools are available for internal use by the agent but do not have dedicated commands: + +- `serp_locations`:Location code lookups for SERP queries +- `serp_youtube_locations`:Location code lookups for YouTube queries +- `kw_data_google_ads_locations`:Location lookups for keyword data +- `kw_data_dfs_trends_demography`:Demographic data for trend analysis +- `kw_data_dfs_trends_subregion_interests`:Subregion interest data for trends +- `kw_data_dfs_trends_explore`:DFS proprietary trends data +- `kw_data_google_trends_categories`:Google Trends category lookups +- `dataforseo_labs_google_keyword_overview`:Quick keyword metrics overview +- `dataforseo_labs_google_historical_serp`:Historical SERP results for a keyword +- `dataforseo_labs_google_serp_competitors`:Competitors for a specific SERP +- `dataforseo_labs_google_keywords_for_site`:Keywords a site ranks for (alternative to ranked) +- `dataforseo_labs_google_page_intersection`:Page-level intersection analysis +- `dataforseo_labs_google_historical_rank_overview`:Historical domain rank data +- `dataforseo_labs_google_historical_keyword_data`:Historical keyword metrics +- `dataforseo_labs_available_filters`:Available filter options for Labs endpoints +- `backlinks_competitors`:Find domains with similar backlink profiles +- `backlinks_bulk_backlinks`:Bulk backlink counts for multiple targets +- `backlinks_bulk_new_lost_referring_domains`:Bulk new/lost referring domains +- `backlinks_bulk_new_lost_backlinks`:Bulk new/lost backlinks +- `backlinks_bulk_ranks`:Bulk rank overview for multiple targets +- `backlinks_bulk_referring_domains`:Bulk referring domain counts +- `backlinks_domain_pages_summary`:Summary of pages on a domain +- `backlinks_domain_pages`:List pages on a domain with backlink data +- `backlinks_page_intersection`:Shared backlink sources at page level +- `backlinks_referring_networks`:Referring network analysis +- `backlinks_timeseries_new_lost_summary`:Track new/lost backlinks over time +- `backlinks_bulk_pages_summary`:Bulk page summaries +- `backlinks_available_filters`:Available filter options for Backlinks endpoints +- `domain_analytics_whois_available_filters`:WHOIS filter options +- `domain_analytics_technologies_available_filters`:Technology detection filter options +- `ai_opt_kw_data_loc_and_lang`:AI optimization keyword data locations/languages +- `ai_optimization_keyword_data_search_volume`:AI-specific keyword volume data +- `ai_optimization_llm_response`:Direct LLM response analysis +- `ai_optimization_llm_mentions_filters`:Available filters for LLM mentions +- `ai_optimization_chat_gpt_scraper_locations`:Available locations for ChatGPT scraper + +## Cross-Skill Integration + +When DataForSEO MCP tools are available, other claude-seo skills can leverage live data: + +- **seo-audit**:Spawn `seo-dataforseo` agent for real SERP, backlink, on-page, and listings data +- **seo-technical**:Use `on_page_instant_pages` / `on_page_lighthouse` for real crawl data, `domain_analytics_technologies_domain_technologies` for stack detection +- **seo-content**:Use `kw_data_google_ads_search_volume`, `dataforseo_labs_bulk_keyword_difficulty`, `dataforseo_labs_search_intent` for real keyword metrics, `content_analysis_summary` for content quality +- **seo-page**:Use `serp_organic_live_advanced` for real SERP positions, `backlinks_summary` for link data +- **seo-geo**:Use `ai_optimization_chat_gpt_scraper` for real ChatGPT visibility, `ai_opt_llm_ment_search` for LLM mention tracking +- **seo-plan**:Use `dataforseo_labs_google_competitors_domain`, `dataforseo_labs_google_domain_intersection`, `dataforseo_labs_bulk_traffic_estimation` for real competitive intelligence + +## Error Handling + +- **MCP server not connected**: Report that DataForSEO extension is not installed or MCP server is unreachable. Suggest running `./extensions/dataforseo/install.sh` +- **API authentication failed**: Report invalid credentials. Suggest checking DataForSEO API login/password in MCP config +- **Rate limit exceeded**: Report the limit hit and suggest waiting before retrying +- **No results returned**: Report "no data found" for the query rather than guessing. Suggest broadening the query or checking location/language codes +- **Invalid location code**: Report the error and suggest using the locations lookup tool to find the correct code + +## Output Formatting + +Match existing claude-seo output patterns: +- Use tables for comparative data +- Prioritize issues as Critical > High > Medium > Low +- Include specific, actionable recommendations +- Show scores as XX/100 where applicable +- Note data source as "DataForSEO (live)" to distinguish from static analysis diff --git a/skills/seo-geo/SKILL.md b/skills/seo-geo/SKILL.md new file mode 100644 index 00000000..3ed2a8c1 --- /dev/null +++ b/skills/seo-geo/SKILL.md @@ -0,0 +1,254 @@ +--- +name: seo-geo +description: "Optimize content for AI Overviews, ChatGPT, Perplexity, and other AI search systems. Use when improving GEO, AI citations, llms.txt readiness, crawler accessibility, and passage-level citability." +risk: unknown +source: "https://github.com/AgriciDaniel/claude-seo" +date_added: "2026-03-21" +user-invokable: true +argument-hint: "[url]" +allowed-tools: + - Read + - Grep + - Glob + - Bash + - WebFetch +--- + +# AI Search / GEO Optimization (February 2026) + +## When to Use + +- Use when improving visibility in AI Overviews, ChatGPT, Perplexity, or similar AI search systems. +- Use when evaluating llms.txt readiness, AI crawler access, or citation-oriented content structure. +- Use when the user asks about GEO, AI SEO, LLM visibility, or AI citations. + +## Key Statistics + +| Metric | Value | Source | +|--------|-------|--------| +| AI Overviews reach | 1.5 billion users/month across 200+ countries | Google | +| AI Overviews query coverage | 50%+ of all queries | Industry data | +| AI-referred sessions growth | 527% (Jan-May 2025) | SparkToro | +| ChatGPT weekly active users | 900 million | OpenAI | +| Perplexity monthly queries | 500+ million | Perplexity | + +## Critical Insight: Brand Mentions > Backlinks + +**Brand mentions correlate 3x more strongly with AI visibility than backlinks.** +(Ahrefs December 2025 study of 75,000 brands) + +| Signal | Correlation with AI Citations | +|--------|------------------------------| +| YouTube mentions | ~0.737 (strongest) | +| Reddit mentions | High | +| Wikipedia presence | High | +| LinkedIn presence | Moderate | +| Domain Rating (backlinks) | ~0.266 (weak) | + +**Only 11% of domains** are cited by both ChatGPT and Google AI Overviews for the same query, so platform-specific optimization is essential. + +--- + +## GEO Analysis Criteria (Updated) + +### 1. Citability Score (25%) + +**Optimal passage length: 134-167 words** for AI citation. + +**Strong signals:** +- Clear, quotable sentences with specific facts/statistics +- Self-contained answer blocks (can be extracted without context) +- Direct answer in first 40-60 words of section +- Claims attributed with specific sources +- Definitions following "X is..." or "X refers to..." patterns +- Unique data points not found elsewhere + +**Weak signals:** +- Vague, general statements +- Opinion without evidence +- Buried conclusions +- No specific data points + +### 2. Structural Readability (20%) + +**92% of AI Overview citations come from top-10 ranking pages**, but 47% come from pages ranking below position 5, demonstrating different selection logic. + +**Strong signals:** +- Clean H1->H2->H3 heading hierarchy +- Question-based headings (matches query patterns) +- Short paragraphs (2-4 sentences) +- Tables for comparative data +- Ordered/unordered lists for step-by-step or multi-item content +- FAQ sections with clear Q&A format + +**Weak signals:** +- Wall of text with no structure +- Inconsistent heading hierarchy +- No lists or tables +- Information buried in paragraphs + +### 3. Multi-Modal Content (15%) + +Content with multi-modal elements sees **156% higher selection rates**. + +**Check for:** +- Text + relevant images +- Video content (embedded or linked) +- Infographics and charts +- Interactive elements (calculators, tools) +- Structured data supporting media + +### 4. Authority & Brand Signals (20%) + +**Strong signals:** +- Author byline with credentials +- Publication date and last-updated date +- Citations to primary sources (studies, official docs, data) +- Organization credentials and affiliations +- Expert quotes with attribution +- Entity presence in Wikipedia, Wikidata +- Mentions on Reddit, YouTube, LinkedIn + +**Weak signals:** +- Anonymous authorship +- No dates +- No sources cited +- No brand presence across platforms + +### 5. Technical Accessibility (20%) + +**AI crawlers do NOT execute JavaScript.** Server-side rendering is critical. + +**Check for:** +- Server-side rendering (SSR) vs client-only content +- AI crawler access in robots.txt +- llms.txt file presence and configuration +- RSL 1.0 licensing terms + +--- + +## AI Crawler Detection + +Check `robots.txt` for these AI crawlers: + +| Crawler | Owner | Purpose | +|---------|-------|---------| +| GPTBot | OpenAI | ChatGPT web search | +| OAI-SearchBot | OpenAI | OpenAI search features | +| ChatGPT-User | OpenAI | ChatGPT browsing | +| ClaudeBot | Anthropic | Claude web features | +| PerplexityBot | Perplexity | Perplexity AI search | +| CCBot | Common Crawl | Training data (often blocked) | +| anthropic-ai | Anthropic | Claude training | +| Bytespider | ByteDance | TikTok/Douyin AI | +| cohere-ai | Cohere | Cohere models | + +**Recommendation:** Allow GPTBot, OAI-SearchBot, ClaudeBot, PerplexityBot for AI search visibility. Block CCBot and training crawlers if desired. + +--- + +## llms.txt Standard + +The emerging **llms.txt** standard provides AI crawlers with structured content guidance. + +**Location:** `/llms.txt` (root of domain) + +**Format:** +``` +# Title of site +> Brief description + +## Main sections +- `Page title -> https://example.com/page`: Description +- `Another page -> https://example.com/another-page`: Description + +## Optional: Key facts +- Fact 1 +- Fact 2 +``` + +**Check for:** +- Presence of `/llms.txt` +- Structured content guidance +- Key page highlights +- Contact/authority information + +--- + +## RSL 1.0 (Really Simple Licensing) + +New standard (December 2025) for machine-readable AI licensing terms. + +**Backed by:** Reddit, Yahoo, Medium, Quora, Cloudflare, Akamai, Creative Commons + +**Check for:** RSL implementation and appropriate licensing terms. + +--- + +## Platform-Specific Optimization + +| Platform | Key Citation Sources | Optimization Focus | +|----------|---------------------|-------------------| +| **Google AI Overviews** | Top-10 ranking pages (92%) | Traditional SEO + passage optimization | +| **ChatGPT** | Wikipedia (47.9%), Reddit (11.3%) | Entity presence, authoritative sources | +| **Perplexity** | Reddit (46.7%), Wikipedia | Community validation, discussions | +| **Bing Copilot** | Bing index, authoritative sites | Bing SEO, IndexNow | + +--- + +## Output + +Generate `GEO-ANALYSIS.md` with: + +1. **GEO Readiness Score: XX/100** +2. **Platform breakdown** (Google AIO, ChatGPT, Perplexity scores) +3. **AI Crawler Access Status** (which crawlers allowed/blocked) +4. **llms.txt Status** (present, missing, recommendations) +5. **Brand Mention Analysis** (presence on Wikipedia, Reddit, YouTube, LinkedIn) +6. **Passage-Level Citability** (optimal 134-167 word blocks identified) +7. **Server-Side Rendering Check** (JavaScript dependency analysis) +8. **Top 5 Highest-Impact Changes** +9. **Schema Recommendations** (for AI discoverability) +10. **Content Reformatting Suggestions** (specific passages to rewrite) + +--- + +## Quick Wins + +1. Add "What is [topic]?" definition in first 60 words +2. Create 134-167 word self-contained answer blocks +3. Add question-based H2/H3 headings +4. Include specific statistics with sources +5. Add publication/update dates +6. Implement Person schema for authors +7. Allow key AI crawlers in robots.txt + +## Medium Effort + +1. Create `/llms.txt` file +2. Add author bio with credentials + Wikipedia/LinkedIn links +3. Ensure server-side rendering for key content +4. Build entity presence on Reddit, YouTube +5. Add comparison tables with data +6. Implement FAQ sections (structured, not schema for commercial sites) + +## High Impact + +1. Create original research/surveys (unique citability) +2. Build Wikipedia presence for brand/key people +3. Establish YouTube channel with content mentions +4. Implement comprehensive entity linking (sameAs across platforms) +5. Develop unique tools or calculators + +## DataForSEO Integration (Optional) + +If DataForSEO MCP tools are available, use `ai_optimization_chat_gpt_scraper` to check what ChatGPT web search returns for target queries (real GEO visibility check) and `ai_opt_llm_ment_search` with `ai_opt_llm_ment_top_domains` for LLM mention tracking across AI platforms. + +## Error Handling + +| Scenario | Action | +|----------|--------| +| URL unreachable (DNS failure, connection refused) | Report the error clearly. Do not guess site content. Suggest the user verify the URL and try again. | +| AI crawlers blocked by robots.txt | Report exactly which crawlers are blocked and which are allowed. Provide specific robots.txt directives to add for enabling AI search visibility. | +| No llms.txt found | Note the absence and provide a ready-to-use llms.txt template based on the site's content structure. | +| No structured data detected | Report the gap and provide specific schema recommendations (Article, Organization, Person) for improving AI discoverability. | diff --git a/skills/seo-hreflang/SKILL.md b/skills/seo-hreflang/SKILL.md new file mode 100644 index 00000000..d4e4fd72 --- /dev/null +++ b/skills/seo-hreflang/SKILL.md @@ -0,0 +1,209 @@ +--- +name: seo-hreflang +description: > + Hreflang and international SEO audit, validation, and generation. Detects + common mistakes, validates language/region codes, and generates correct + hreflang implementations. Use when user says "hreflang", "i18n SEO", + "international SEO", "multi-language", "multi-region", or "language tags". +risk: unknown +source: "https://github.com/AgriciDaniel/claude-seo" +date_added: "2026-03-21" +user-invokable: true +argument-hint: "[url]" +allowed-tools: + - Read + - Grep + - Glob + - Bash + - WebFetch +--- + +# Hreflang & International SEO + +## When to Use + +- Use when validating or generating hreflang for multilingual or multiregional sites. +- Use when the user mentions international SEO, language tags, x-default, or hreflang issues. +- Use when auditing locale alternates across HTML, headers, or sitemap implementations. + +Validate existing hreflang implementations or generate correct hreflang tags +for multi-language and multi-region sites. Supports HTML, HTTP header, and +XML sitemap implementations. + +## Validation Checks + +### 1. Self-Referencing Tags +- Every page must include an hreflang tag pointing to itself +- The self-referencing URL must exactly match the page's canonical URL +- Missing self-referencing tags cause Google to ignore the entire hreflang set + +### 2. Return Tags +- If page A links to page B with hreflang, page B must link back to page A +- Every hreflang relationship must be bidirectional (A→B and B→A) +- Missing return tags invalidate the hreflang signal for both pages +- Check all language versions reference each other (full mesh) + +### 3. x-default Tag +- Required: designates the fallback page for unmatched languages/regions +- Typically points to the language selector page or English version +- Only one x-default per set of alternates +- Must also have return tags from all other language versions + +### 4. Language Code Validation +- Must use ISO 639-1 two-letter codes (e.g., `en`, `fr`, `de`, `ja`) +- Common errors: + - `eng` instead of `en` (ISO 639-2, not valid for hreflang) + - `jp` instead of `ja` (incorrect code for Japanese) + - `zh` without region qualifier (ambiguous; use `zh-Hans` or `zh-Hant`) + +### 5. Region Code Validation +- Optional region qualifier uses ISO 3166-1 Alpha-2 (e.g., `en-US`, `en-GB`, `pt-BR`) +- Format: `language-REGION` (lowercase language, uppercase region) +- Common errors: + - `en-uk` instead of `en-GB` (UK is not a valid ISO 3166-1 code) + - `es-LA` (Latin America is not a country; use specific countries) + - Region without language prefix + +### 6. Canonical URL Alignment +- Hreflang tags must only appear on canonical URLs +- If a page has `rel=canonical` pointing elsewhere, hreflang on that page is ignored +- The canonical URL and hreflang URL must match exactly (including trailing slashes) +- Non-canonical pages should not be in any hreflang set + +### 7. Protocol Consistency +- All URLs in an hreflang set must use the same protocol (HTTPS or HTTP) +- Mixed HTTP/HTTPS in hreflang sets causes validation failures +- After HTTPS migration, update all hreflang tags to HTTPS + +### 8. Cross-Domain Support +- Hreflang works across different domains (e.g., example.com and example.de) +- Cross-domain hreflang requires return tags on both domains +- Verify both domains are verified in Google Search Console +- Sitemap-based implementation recommended for cross-domain setups + +## Common Mistakes + +| Issue | Severity | Fix | +|-------|----------|-----| +| Missing self-referencing tag | Critical | Add hreflang pointing to same page URL | +| Missing return tags (A→B but no B→A) | Critical | Add matching return tags on all alternates | +| Missing x-default | High | Add x-default pointing to fallback/selector page | +| Invalid language code (e.g., `eng`) | High | Use ISO 639-1 two-letter codes | +| Invalid region code (e.g., `en-uk`) | High | Use ISO 3166-1 Alpha-2 codes | +| Hreflang on non-canonical URL | High | Move hreflang to canonical URL only | +| HTTP/HTTPS mismatch in URLs | Medium | Standardize all URLs to HTTPS | +| Trailing slash inconsistency | Medium | Match canonical URL format exactly | +| Hreflang in both HTML and sitemap | Low | Choose one method (sitemap preferred for large sites) | +| Language without region when needed | Low | Add region qualifier for geo-targeted content | + +## Implementation Methods + +### Method 1: HTML Link Tags +Best for: Sites with <50 language/region variants per page. + +```html + + + + +``` + +Place in `` section. Every page must include all alternates including itself. + +### Method 2: HTTP Headers +Best for: Non-HTML files (PDFs, documents). + +``` +Link: ; rel="alternate"; hreflang="en-US", + ; rel="alternate"; hreflang="fr", + ; rel="alternate"; hreflang="x-default" +``` + +Set via server configuration or CDN rules. + +### Method 3: XML Sitemap (Recommended for large sites) +Best for: Sites with many language variants, cross-domain setups, or 50+ pages. + +See Hreflang Sitemap Generation section below. + +### Method Comparison +| Method | Best For | Pros | Cons | +|--------|----------|------|------| +| HTML link tags | Small sites (<50 variants) | Easy to implement, visible in source | Bloats ``, hard to maintain at scale | +| HTTP headers | Non-HTML files | Works for PDFs, images | Complex server config, not visible in HTML | +| XML sitemap | Large sites, cross-domain | Scalable, centralized management | Not visible on page, requires sitemap maintenance | + +## Hreflang Generation + +### Process +1. **Detect languages**: Scan site for language indicators (URL path, subdomain, TLD, HTML lang attribute) +2. **Map page equivalents**: Match corresponding pages across languages/regions +3. **Validate language codes**: Verify all codes against ISO 639-1 and ISO 3166-1 +4. **Generate tags**: Create hreflang tags for each page including self-referencing +5. **Verify return tags**: Confirm all relationships are bidirectional +6. **Add x-default**: Set fallback for each page set +7. **Output**: Generate implementation code (HTML, HTTP headers, or sitemap XML) + +## Hreflang Sitemap Generation + +### Sitemap with Hreflang +```xml + + + + https://example.com/page + + + + + + + https://example.com/fr/page + + + + + + +``` + +Key rules: +- Include the `xmlns:xhtml` namespace declaration +- Every `` entry must include ALL language alternates (including itself) +- Each alternate must appear as a separate `` entry with its own full set +- Split at 50,000 URLs per sitemap file + +## Output + +### Hreflang Validation Report + +#### Summary +- Total pages scanned: XX +- Language variants detected: XX +- Issues found: XX (Critical: X, High: X, Medium: X, Low: X) + +#### Validation Results +| Language | URL | Self-Ref | Return Tags | x-default | Status | +|----------|-----|----------|-------------|-----------|--------| +| en-US | https://... | ✅ | ✅ | ✅ | ✅ | +| fr | https://... | ❌ | ⚠️ | ✅ | ❌ | +| de | https://... | ✅ | ❌ | ✅ | ❌ | + +### Generated Hreflang Tags +- HTML `` tags (if HTML method chosen) +- HTTP header values (if header method chosen) +- `hreflang-sitemap.xml` (if sitemap method chosen) + +### Recommendations +- Missing implementations to add +- Incorrect codes to fix +- Method migration suggestions (e.g., HTML to sitemap for scale) + +## Error Handling + +| Scenario | Action | +|----------|--------| +| URL unreachable (DNS failure, connection refused) | Report the error clearly. Do not guess site structure. Suggest the user verify the URL and try again. | +| No hreflang tags found | Report the absence. Check for other internationalization signals (subdirectories, subdomains, ccTLDs) and recommend the appropriate hreflang implementation method. | +| Invalid language/region codes detected | List each invalid code with the correct replacement. Provide a corrected hreflang tag set ready to implement. | diff --git a/skills/seo-image-gen/SKILL.md b/skills/seo-image-gen/SKILL.md new file mode 100644 index 00000000..91336a5d --- /dev/null +++ b/skills/seo-image-gen/SKILL.md @@ -0,0 +1,183 @@ +--- +name: seo-image-gen +description: "Generate SEO-focused images such as OG cards, hero images, schema assets, product visuals, and infographics. Use when image generation is part of an SEO workflow or content publishing task." +risk: unknown +source: "https://github.com/AgriciDaniel/claude-seo" +date_added: "2026-03-21" +argument-hint: "[og|hero|product|infographic|custom|batch] " +user-invokable: true +allowed-tools: + - Read + - Grep + - Glob + - Bash + - WebFetch + - Write +--- + +# SEO Image Gen: AI Image Generation for SEO Assets (Extension) + +Generate production-ready images for SEO use cases using Gemini's image generation +via the banana Creative Director pipeline. Maps SEO needs to optimized domain modes, +aspect ratios, and resolution defaults. + +## When to Use + +- Use when generating OG images, hero images, schema visuals, infographics, or similar SEO assets. +- Use when image generation is part of a broader SEO or publishing workflow. +- Use only when the required image-generation extension is available. + +## Architecture Note + +This skill has two components with distinct roles: +- **SKILL.md** (this file): Handles interactive `/seo image-gen` commands for generating images +- **Agent** (`agents/seo-image-gen.md`): Audit-only analyst spawned during `/seo audit` to assess existing OG/social images and produce a generation plan (never auto-generates) + +## Prerequisites + +This skill requires the banana extension to be installed: +```bash +./extensions/banana/install.sh +``` + +**Check availability:** Before using any image generation tool, verify the MCP server +is connected by checking if `gemini_generate_image` or `set_aspect_ratio` tools are +available. If tools are not available, inform the user the extension is not installed +and provide install instructions. + +## Quick Reference + +| Command | What it does | +|---------|-------------| +| `/seo image-gen og ` | Generate OG/social preview image (1200x630 feel) | +| `/seo image-gen hero ` | Blog hero image (widescreen, dramatic) | +| `/seo image-gen product ` | Product photography (clean, white BG) | +| `/seo image-gen infographic ` | Infographic visual (vertical, data-heavy) | +| `/seo image-gen custom ` | Custom image with full Creative Director pipeline | +| `/seo image-gen batch [N]` | Generate N variations (default: 3) | + +## SEO Image Use Cases + +Each use case maps to pre-configured banana parameters: + +| Use Case | Aspect Ratio | Resolution | Domain Mode | Notes | +|----------|-------------|------------|-------------|-------| +| **OG/Social Preview** | `16:9` | `1K` | Product or UI/Web | Clean, professional, text-friendly | +| **Blog Hero** | `16:9` | `2K` | Cinema or Editorial | Dramatic, atmospheric, editorial quality | +| **Schema Image** | `4:3` | `1K` | Product | Clean, descriptive, schema ImageObject | +| **Social Square** | `1:1` | `1K` | UI/Web | Platform-optimized square | +| **Product Photo** | `4:3` | `2K` | Product | White background, studio lighting | +| **Infographic** | `2:3` | `4K` | Infographic | Data-heavy, vertical layout | +| **Favicon/Icon** | `1:1` | `512` | Logo | Minimal, scalable, recognizable | +| **Pinterest Pin** | `2:3` | `2K` | Editorial | Tall vertical card | + +## Generation Pipeline + +For every generation request: + +1. **Identify use case** from command or context (og, hero, product, etc.) +2. **Apply SEO defaults** from the use cases table above +3. **Set aspect ratio** via `set_aspect_ratio` MCP tool +4. **Construct Reasoning Brief** using the banana Creative Director pipeline: + - Load `references/prompt-engineering.md` for the 6-component system + - Apply domain mode emphasis (Subject 30%, Style 25%, Context 15%, etc.) + - Be SPECIFIC and VISCERAL: describe what the camera sees +5. **Generate** via `gemini_generate_image` MCP tool +6. **Post-generation SEO checklist** (see below) + +### Check for Presets + +If the user mentions a brand or has SEO presets configured: +```bash +python3 ~/.claude/skills/seo-image-gen/scripts/presets.py list +``` +Load matching preset and apply as defaults. Also check `references/seo-image-presets.md` +for SEO-specific preset templates. + +## Post-Generation SEO Checklist + +After every successful generation, guide the user on: + +1. **Alt text**:Write descriptive, keyword-rich alt text for the generated image +2. **File naming**:Rename to SEO-friendly format: `keyword-description-widthxheight.webp` +3. **WebP conversion**:Convert to WebP for optimal page speed: + ```bash + magick output.png -quality 85 output.webp + ``` +4. **File size**:Target under 200KB for hero images, under 100KB for thumbnails +5. **Schema markup**:Suggest `ImageObject` schema for the generated image: + ```json + { + "@type": "ImageObject", + "url": "https://example.com/images/keyword-description.webp", + "width": 1200, + "height": 630, + "caption": "Descriptive caption with target keyword" + } + ``` +6. **OG meta tags**:For social preview images, remind about: + ```html + + + + + ``` + +## Cost Awareness + +Image generation costs money. Be transparent: +- Show estimated cost before generating (especially for batch) +- Log every generation: `python3 ~/.claude/skills/seo-image-gen/scripts/cost_tracker.py log --model MODEL --resolution RES --prompt "brief"` +- Run `cost_tracker.py summary` if user asks about usage + +Approximate costs (gemini-3.1-flash): +- 512: ~$0.02/image +- 1K resolution: ~$0.04/image +- 2K resolution: ~$0.08/image +- 4K resolution: ~$0.16/image + +## Model Routing + +| Scenario | Model | Why | +|----------|-------|-----| +| OG images, social previews | `gemini-3.1-flash-image-preview` @ 1K | Fast, cost-effective | +| Hero images, product photos | `gemini-3.1-flash-image-preview` @ 2K | Quality + detail | +| Infographics with text | `gemini-3.1-flash-image-preview` @ 2K, thinking: high | Better text rendering | +| Quick drafts | `gemini-2.5-flash-image` @ 512 | Rapid iteration | + +## Error Handling + +| Error | Resolution | +|-------|-----------| +| MCP not configured | Run `./extensions/banana/install.sh` | +| API key invalid | New key at https://aistudio.google.com/apikey | +| Rate limited (429) | Wait 60s, retry. Free tier: ~10 RPM / ~500 RPD | +| `IMAGE_SAFETY` | Rephrase prompt - see `references/prompt-engineering.md` Safety section | +| MCP unavailable | Fall back: `python3 ~/.claude/skills/seo-image-gen/scripts/generate.py --prompt "..." --aspect-ratio "16:9"` | +| Extension not installed | Show install instructions: `./extensions/banana/install.sh` | + +## Cross-Skill Integration + +- **seo-images** (analysis) feeds into **seo-image-gen** (generation): audit results from `/seo images` identify missing or low-quality images; use those findings to drive `/seo image-gen` commands +- **seo-audit** spawns the seo-image-gen **agent** (not this skill) to analyze OG/social images across the site and produce a prioritized generation plan +- **seo-schema** can consume generated images: after generation, suggest `ImageObject` schema markup pointing to the new assets + +## Reference Documentation + +Load on-demand. Do NOT load all at startup: +- `references/prompt-engineering.md`:6-component system, domain modes, templates +- `references/gemini-models.md`:Model specs, rate limits, capabilities +- `references/mcp-tools.md`:MCP tool parameters and responses +- `references/post-processing.md`:ImageMagick/FFmpeg pipeline recipes +- `references/cost-tracking.md`:Pricing, usage tracking +- `references/presets.md`:Brand preset management +- `references/seo-image-presets.md`:SEO-specific preset templates + +## Response Format + +After generating, always provide: +1. **Image path**:where it was saved +2. **Crafted prompt**:show what was sent to the API (educational) +3. **Settings**:model, aspect ratio, resolution +4. **SEO checklist**:alt text suggestion, file naming, WebP conversion +5. **Schema snippet**:ImageObject or og:image markup if applicable diff --git a/skills/seo-images/SKILL.md b/skills/seo-images/SKILL.md new file mode 100644 index 00000000..e711695c --- /dev/null +++ b/skills/seo-images/SKILL.md @@ -0,0 +1,193 @@ +--- +name: seo-images +description: > + Image optimization analysis for SEO and performance. Checks alt text, file + sizes, formats, responsive images, lazy loading, and CLS prevention. Use when + user says "image optimization", "alt text", "image SEO", "image size", + or "image audit". +risk: unknown +source: "https://github.com/AgriciDaniel/claude-seo" +date_added: "2026-03-21" +user-invokable: true +argument-hint: "[url]" +allowed-tools: + - Read + - Grep + - Glob + - Bash + - WebFetch +--- + +# Image Optimization Analysis + +## When to Use + +- Use when auditing image SEO, alt text, file sizes, formats, or lazy loading. +- Use when the user wants image-specific performance recommendations. +- Use when checking media quality signals that affect both SEO and Core Web Vitals. + +## Checks + +### Alt Text +- Present on all `` elements (except decorative: `role="presentation"`) +- Descriptive: describes the image content, not "image.jpg" or "photo" +- Includes relevant keywords where natural, not keyword-stuffed +- Length: 10-125 characters + +**Good examples:** +- "Professional plumber repairing kitchen sink faucet" +- "Red 2024 Toyota Camry sedan front view" +- "Team meeting in modern office conference room" + +**Bad examples:** +- "image.jpg" (filename, not description) +- "plumber plumbing plumber services" (keyword stuffing) +- "Click here" (not descriptive) + +### File Size + +**Tiered thresholds by image category:** + +| Image Category | Target | Warning | Critical | +|----------------|--------|---------|----------| +| Thumbnails | < 50KB | > 100KB | > 200KB | +| Content images | < 100KB | > 200KB | > 500KB | +| Hero/banner images | < 200KB | > 300KB | > 700KB | + +Recommend compression to target thresholds where possible without quality loss. + +### Format +| Format | Browser Support | Use Case | +|--------|-----------------|----------| +| WebP | 97%+ | Default recommendation | +| AVIF | 92%+ | Best compression, newer | +| JPEG | 100% | Fallback for photos | +| PNG | 100% | Graphics with transparency | +| SVG | 100% | Icons, logos, illustrations | + +Recommend WebP/AVIF over JPEG/PNG. Check for `` element with format fallbacks. + +#### Recommended `` Element Pattern + +Use progressive enhancement with the most efficient format first: + +```html + + + + Descriptive alt text + +``` + +The browser will use the first supported format. Current browser support: AVIF 93.8%, WebP 95.3%. + +#### JPEG XL: Emerging Format + +In November 2025, Google's Chromium team reversed its 2022 decision and announced it will restore JPEG XL support in Chrome using a Rust-based decoder. The implementation is feature-complete but not yet in Chrome stable. JPEG XL offers lossless JPEG recompression (~20% savings with zero quality loss) and competitive lossy compression. Not yet practical for web deployment, but worth monitoring for future adoption. + +### Responsive Images +- `srcset` attribute for multiple sizes +- `sizes` attribute matching layout breakpoints +- Appropriate resolution for device pixel ratios + +```html +Description +``` + +### Lazy Loading +- `loading="lazy"` on below-fold images +- Do NOT lazy-load above-fold/hero images (hurts LCP) +- Check for native vs JavaScript-based lazy loading + +```html + +Description + + +Hero image +``` + +### `fetchpriority="high"` for LCP Images + +Add `fetchpriority="high"` to your hero/LCP image to prioritize its download in the browser's network queue: + +```html +Hero image description +``` + +**Critical:** Do NOT lazy-load above-the-fold/LCP images. Using `loading="lazy"` on LCP images directly harms LCP scores. Reserve `loading="lazy"` for below-the-fold images only. + +### `decoding="async"` for Non-LCP Images + +Add `decoding="async"` to non-LCP images to prevent image decoding from blocking the main thread: + +```html +Description +``` + +### CLS Prevention +- `width` and `height` attributes set on all `` elements +- `aspect-ratio` CSS as alternative +- Flag images without dimensions + +```html + +Description + + +Description + + +Description +``` + +### File Names +- Descriptive: `blue-running-shoes.webp` not `IMG_1234.jpg` +- Hyphenated, lowercase, no special characters +- Include relevant keywords + +### CDN Usage +- Check if images served from CDN (different domain, CDN headers) +- Recommend CDN for image-heavy sites +- Check for edge caching headers + +## Output + +### Image Audit Summary + +| Metric | Status | Count | +|--------|--------|-------| +| Total Images | - | XX | +| Missing Alt Text | ❌ | XX | +| Oversized (>200KB) | ⚠️ | XX | +| Wrong Format | ⚠️ | XX | +| No Dimensions | ⚠️ | XX | +| Not Lazy Loaded | ⚠️ | XX | + +### Prioritized Optimization List + +Sorted by file size impact (largest savings first): + +| Image | Current Size | Format | Issues | Est. Savings | +|-------|--------------|--------|--------|--------------| +| ... | ... | ... | ... | ... | + +### Recommendations +1. Convert X images to WebP format (est. XX KB savings) +2. Add alt text to X images +3. Add dimensions to X images +4. Enable lazy loading on X below-fold images +5. Compress X oversized images + +## Error Handling + +| Scenario | Action | +|----------|--------| +| URL unreachable | Report connection error with status code. Suggest verifying URL and checking if site requires authentication. | +| No images found on page | Report that no `` elements were detected. Suggest checking if images are loaded via JavaScript or CSS background-image. | +| Images behind CDN or authentication | Note that image files could not be directly accessed for size analysis. Report available metadata (alt text, dimensions, format from markup) and flag inaccessible resources. | diff --git a/skills/seo-page/SKILL.md b/skills/seo-page/SKILL.md new file mode 100644 index 00000000..2fddec7d --- /dev/null +++ b/skills/seo-page/SKILL.md @@ -0,0 +1,103 @@ +--- +name: seo-page +description: > + Deep single-page SEO analysis covering on-page elements, content quality, + technical meta tags, schema, images, and performance. Use when user says + "analyze this page", "check page SEO", or provides a single URL for review. +risk: unknown +source: "https://github.com/AgriciDaniel/claude-seo" +date_added: "2026-03-21" +user-invokable: true +argument-hint: "[url]" +allowed-tools: + - Read + - Grep + - Glob + - Bash + - WebFetch +--- + +# Single Page Analysis + +## When to Use + +- Use when the user provides a single URL for detailed on-page SEO review. +- Use when auditing one page rather than an entire site. +- Use when checking metadata, content, schema, images, and page-level technical signals together. + +## What to Analyze + +### On-Page SEO +- Title tag: 50-60 characters, includes primary keyword, unique +- Meta description: 150-160 characters, compelling, includes keyword +- H1: exactly one, matches page intent, includes keyword +- H2-H6: logical hierarchy (no skipped levels), descriptive +- URL: short, descriptive, hyphenated, no parameters +- Internal links: sufficient, relevant anchor text, no orphan pages +- External links: to authoritative sources, reasonable count + +### Content Quality +- Word count vs page type minimums (see quality-gates.md) +- Readability: Flesch Reading Ease score, grade level +- Keyword density: natural (1-3%), semantic variations present +- E-E-A-T signals: author bio, credentials, first-hand experience markers +- Content freshness: publication date, last updated date + +### Technical Elements +- Canonical tag: present, self-referencing or correct +- Meta robots: index/follow unless intentionally blocked +- Open Graph: og:title, og:description, og:image, og:url +- Twitter Card: twitter:card, twitter:title, twitter:description +- Hreflang: if multi-language, correct implementation + +### Schema Markup +- Detect all types (JSON-LD preferred) +- Validate required properties +- Identify missing opportunities +- NEVER recommend HowTo (deprecated) or FAQ (restricted to gov/health) + +### Images +- Alt text: present, descriptive, includes keywords where natural +- File size: flag >200KB (warning), >500KB (critical) +- Format: recommend WebP/AVIF over JPEG/PNG +- Dimensions: width/height set for CLS prevention +- Lazy loading: loading="lazy" on below-fold images + +### Core Web Vitals (reference only, not measurable from HTML alone) +- Flag potential LCP issues (huge hero images, render-blocking resources) +- Flag potential INP issues (heavy JS, no async/defer) +- Flag potential CLS issues (missing image dimensions, injected content) + +## Output + +### Page Score Card +``` +Overall Score: XX/100 + +On-Page SEO: XX/100 ████████░░ +Content Quality: XX/100 ██████████ +Technical: XX/100 ███████░░░ +Schema: XX/100 █████░░░░░ +Images: XX/100 ████████░░ +``` + +### Issues Found +Organized by priority: Critical -> High -> Medium -> Low + +### Recommendations +Specific, actionable improvements with expected impact + +### Schema Suggestions +Ready-to-use JSON-LD code for detected opportunities + +## DataForSEO Integration (Optional) + +If DataForSEO MCP tools are available, use `serp_organic_live_advanced` for real SERP positions and `backlinks_summary` for backlink data and spam scores. + +## Error Handling + +| Scenario | Action | +|----------|--------| +| URL unreachable (DNS failure, connection refused) | Report the error clearly. Do not guess page content. Suggest the user verify the URL and try again. | +| Page requires authentication (401/403) | Report that the page is behind authentication. Suggest the user provide the rendered HTML directly or a publicly accessible URL. | +| JavaScript-rendered content (empty body in HTML) | Note that key content may be rendered client-side. Analyze the available HTML and flag that results may be incomplete. Suggest using a browser-rendered snapshot if available. | diff --git a/skills/seo-plan/SKILL.md b/skills/seo-plan/SKILL.md new file mode 100644 index 00000000..6322d26d --- /dev/null +++ b/skills/seo-plan/SKILL.md @@ -0,0 +1,136 @@ +--- +name: seo-plan +description: > + Strategic SEO planning for new or existing websites. Industry-specific + templates, competitive analysis, content strategy, and implementation + roadmap. Use when user says "SEO plan", "SEO strategy", "content strategy", + "site architecture", or "SEO roadmap". +risk: unknown +source: "https://github.com/AgriciDaniel/claude-seo" +date_added: "2026-03-21" +user-invokable: true +argument-hint: "[business-type]" +allowed-tools: + - Read + - Grep + - Glob + - Bash + - WebFetch + - Write +--- + +# Strategic SEO Planning + +## When to Use + +- Use when building an SEO strategy or roadmap for a new or existing site. +- Use when planning content, architecture, and implementation phases together. +- Use when the user asks for an SEO plan rather than a point-in-time audit. + +## Process + +### 1. Discovery +- Business type, target audience, competitors, goals +- Current site assessment (if exists) +- Budget and timeline constraints +- Key performance indicators (KPIs) + +### 2. Competitive Analysis +- Identify top 5 competitors +- Analyze their content strategy, schema usage, technical setup +- Identify keyword gaps and content opportunities +- Assess their E-E-A-T signals +- Estimate their domain authority + +### 3. Architecture Design +- Load industry template from `assets/` directory +- Design URL hierarchy and content pillars +- Plan internal linking strategy +- Sitemap structure with quality gates applied +- Information architecture for user journeys + +### 4. Content Strategy +- Content gaps vs competitors +- Page types and estimated counts +- Blog/resource topics and publishing cadence +- E-E-A-T building plan (author bios, credentials, experience signals) +- Content calendar with priorities + +### 5. Technical Foundation +- Hosting and performance requirements +- Schema markup plan per page type +- Core Web Vitals baseline targets +- AI search readiness requirements +- Mobile-first considerations + +### 6. Implementation Roadmap (4 phases) + +#### Phase 1: Foundation (weeks 1-4) +- Technical setup and infrastructure +- Core pages (home, about, contact, main services) +- Essential schema implementation +- Analytics and tracking setup + +#### Phase 2: Expansion (weeks 5-12) +- Content creation for primary pages +- Blog launch with initial posts +- Internal linking structure +- Local SEO setup (if applicable) + +#### Phase 3: Scale (weeks 13-24) +- Advanced content development +- Link building and outreach +- GEO optimization +- Performance optimization + +#### Phase 4: Authority (months 7-12) +- Thought leadership content +- PR and media mentions +- Advanced schema implementation +- Continuous optimization + +## Industry Templates + +Load from `assets/` directory: +- `saas.md`: SaaS/software companies +- `local-service.md`: Local service businesses +- `ecommerce.md`: E-commerce stores +- `publisher.md`: Content publishers/media +- `agency.md`: Agencies and consultancies +- `generic.md`: General business template + +## Output + +### Deliverables +- `SEO-STRATEGY.md`: Complete strategic plan +- `COMPETITOR-ANALYSIS.md`: Competitive insights +- `CONTENT-CALENDAR.md`: Content roadmap +- `IMPLEMENTATION-ROADMAP.md`: Phased action plan +- `SITE-STRUCTURE.md`: URL hierarchy and architecture + +### KPI Targets +| Metric | Baseline | 3 Month | 6 Month | 12 Month | +|--------|----------|---------|---------|----------| +| Organic Traffic | ... | ... | ... | ... | +| Keyword Rankings | ... | ... | ... | ... | +| Domain Authority | ... | ... | ... | ... | +| Indexed Pages | ... | ... | ... | ... | +| Core Web Vitals | ... | ... | ... | ... | + +### Success Criteria +- Clear, measurable goals per phase +- Resource requirements defined +- Dependencies identified +- Risk mitigation strategies + +## DataForSEO Integration (Optional) + +If DataForSEO MCP tools are available, use `dataforseo_labs_google_competitors_domain` and `dataforseo_labs_google_domain_intersection` for real competitive intelligence, `dataforseo_labs_bulk_traffic_estimation` for traffic estimates, `kw_data_google_ads_search_volume` and `dataforseo_labs_bulk_keyword_difficulty` for keyword research, and `business_data_business_listings_search` for local business data. + +## Error Handling + +| Scenario | Action | +|----------|--------| +| Unrecognized business type | Fall back to `generic.md` template. Inform user that no industry-specific template was found and proceed with the general business template. | +| No website URL provided | Proceed with new-site planning mode. Skip current site assessment and competitive gap analysis that require a live URL. | +| Industry template not found | Check `assets/` directory for available templates. If the requested template file is missing, use `generic.md` and note the missing template in output. | diff --git a/skills/seo-plan/assets/agency.md b/skills/seo-plan/assets/agency.md new file mode 100644 index 00000000..6d236edc --- /dev/null +++ b/skills/seo-plan/assets/agency.md @@ -0,0 +1,175 @@ + +# Agency/Consultancy SEO Strategy Template + +## Industry Characteristics + +- Service-based, high-value transactions +- Expertise and trust are paramount +- Long consideration cycles +- Portfolio/case study driven decisions +- Relationship-based sales +- Niche specialization benefits + +## Recommended Site Architecture + +``` +/ +├── Home +├── /services +│ ├── /service-1 +│ │ ├── /sub-service-1 +│ │ └── ... +│ └── /service-2 +├── /industries +│ ├── /industry-1 +│ ├── /industry-2 +│ └── ... +├── /work (or /case-studies) +│ ├── /case-study-1 +│ ├── /case-study-2 +│ └── ... +├── /about +│ ├── /team +│ │ ├── /team-member-1 +│ │ └── ... +│ ├── /culture +│ └── /careers +├── /insights (or /blog) +│ ├── /articles +│ ├── /guides +│ ├── /webinars +│ └── /podcasts +├── /contact +├── /process +└── /faq +``` + +## Schema Recommendations + +| Page Type | Schema Types | +|-----------|-------------| +| Homepage | Organization, ProfessionalService | +| Service Page | Service, ProfessionalService | +| Case Study | Article, Organization (client) | +| Team Member | Person, ProfilePage | +| Blog | Article, BlogPosting | + +### ProfessionalService Schema Example +```json +{ + "@context": "https://schema.org", + "@type": "ProfessionalService", + "name": "Agency Name", + "description": "What the agency does", + "url": "https://example.com", + "logo": "https://example.com/logo.png", + "address": { + "@type": "PostalAddress", + "streetAddress": "123 Agency St", + "addressLocality": "City", + "addressRegion": "State", + "postalCode": "12345" + }, + "telephone": "+1-555-555-5555", + "areaServed": "National", + "hasOfferCatalog": { + "@type": "OfferCatalog", + "name": "Services", + "itemListElement": [ + { + "@type": "Offer", + "itemOffered": { + "@type": "Service", + "name": "Service 1" + } + } + ] + } +} +``` + +## E-E-A-T Requirements + +### Team Pages Must Include +- Professional headshots +- Detailed bios with credentials +- Industry experience +- Speaking engagements +- Publications +- Social profiles + +### Case Studies Must Include +- Client name (with permission) or industry +- Challenge/problem statement +- Approach/methodology +- Results with specific metrics +- Timeline +- Testimonial quote + +## Content Priorities + +### High Priority +1. Service pages (detailed, specific) +2. Industry pages (vertical expertise) +3. 3-5 detailed case studies +4. Team/leadership pages + +### Medium Priority +1. Methodology/process page +2. Blog with thought leadership +3. Comparison content (vs alternatives) +4. FAQ page + +### Thought Leadership Topics +- Industry trend analysis +- How-to guides (non-competitive) +- Original research/surveys +- Event recaps and insights +- Expert interviews +- Tool/technology reviews + +## Content Strategy + +### Service Pages (min 800 words) +- Clear value proposition +- Methodology overview +- Deliverables list +- Relevant case studies +- Team members who deliver this service +- CTA to schedule consultation + +### Industry Pages (min 800 words) +- Industry-specific challenges +- How you solve them differently +- Relevant case studies +- Industry credentials/experience +- Client logos (with permission) + +### Case Studies (min 1,000 words) +- Executive summary +- Client background +- Challenge details +- Solution approach +- Implementation process +- Measurable results +- Client testimonial +- Related services/CTA + +## Key Metrics to Track + +- Organic traffic to service pages +- Case study page views +- Contact form submissions from organic +- Time on page for key content +- Blog → service page conversion + +## Generative Engine Optimization (GEO) for Agencies + +- [ ] Publish original case studies with specific, citable metrics and results +- [ ] Use Person schema with sameAs links for all team members (builds entity authority) +- [ ] Use ProfilePage schema for team member pages +- [ ] Include clear, quotable expertise statements in service page descriptions +- [ ] Produce original industry research and surveys AI systems can cite +- [ ] Structure thought leadership content with clear headings and extractable insights +- [ ] Maintain consistent agency entity information across directories, social profiles, and industry sites +- [ ] Monitor AI citation in ChatGPT, Perplexity, and Google AI Overviews for brand and key service terms diff --git a/skills/seo-plan/assets/ecommerce.md b/skills/seo-plan/assets/ecommerce.md new file mode 100644 index 00000000..10da63c6 --- /dev/null +++ b/skills/seo-plan/assets/ecommerce.md @@ -0,0 +1,167 @@ + +# E-commerce SEO Strategy Template + +## Industry Characteristics + +- High transaction intent +- Product comparison behavior +- Price sensitivity +- Visual-first decision making +- Seasonal demand patterns +- Competitive marketplace listings + +## Recommended Site Architecture + +``` +/ +├── Home +├── /collections (or /categories) +│ ├── /category-1 +│ │ ├── /subcategory-1 +│ │ └── ... +│ ├── /category-2 +│ └── ... +├── /products +│ ├── /product-1 +│ ├── /product-2 +│ └── ... +├── /brands +│ ├── /brand-1 +│ └── ... +├── /sale (or /deals) +├── /new-arrivals +├── /best-sellers +├── /gift-guide +├── /blog +│ ├── /buying-guides +│ ├── /how-to +│ └── /trends +├── /about +├── /contact +├── /shipping +├── /returns +└── /faq +``` + +## Schema Recommendations + +| Page Type | Schema Types | +|-----------|-------------| +| Product Page | Product, Offer, AggregateRating, Review, BreadcrumbList | +| Category Page | CollectionPage, ItemList, BreadcrumbList | +| Brand Page | Brand, Organization | +| Blog | Article, BlogPosting | + +### Additional E-commerce Schema (2025) + +- **ProductGroup**: Use for products with variants (size, color). Wraps individual Product entries with `variesBy` and `hasVariant` properties. See `schema/templates.json`. +- **Certification**: For product certifications (Energy Star, safety, organic). Replaced EnergyConsumptionDetails (April 2025). Use `hasCertification` on Product. +- **OfferShippingDetails**: Include shipping rate, handling time, and transit time. Critical for Merchant Center eligibility. + +> **Google Merchant Center Free Listings:** Products can appear in Google Shopping for free. Ensure Product structured data is in the initial server-rendered HTML (not JavaScript-injected) with required properties: `name`, `image`, `price`, `priceCurrency`, `availability`. + +> **JS Rendering Note:** Product structured data should be in initial server-rendered HTML: not dynamically injected via JavaScript (per December 2025 Google JS SEO guidance). + +### Product Schema Example +```json +{ + "@context": "https://schema.org", + "@type": "Product", + "name": "Product Name", + "image": ["https://example.com/product.jpg"], + "description": "Product description", + "sku": "SKU123", + "brand": { + "@type": "Brand", + "name": "Brand Name" + }, + "offers": { + "@type": "Offer", + "price": "99.99", + "priceCurrency": "USD", + "availability": "https://schema.org/InStock", + "url": "https://example.com/product" + }, + "aggregateRating": { + "@type": "AggregateRating", + "ratingValue": "4.5", + "reviewCount": "42" + } +} +``` + +## Content Requirements + +### Product Pages (min 400 words) +- Unique product descriptions (not manufacturer copy) +- Feature highlights +- Use cases / who it's for +- Specifications table +- Size/fit guide (for apparel) +- Care instructions +- Customer reviews + +### Category Pages (min 400 words) +- Category introduction +- Buying guide excerpt +- Featured products +- Subcategory links +- Filter/sort options + +## Technical Considerations + +### Pagination +- Use rel="next"/rel="prev" or load-more +- Ensure all products are crawlable +- Canonical to main category page + +### Faceted Navigation +- Noindex filter combinations that create duplicate content +- Use canonical tags appropriately +- Ensure popular filters are indexable + +### Product Variations +- Single URL for parent product with variants +- Or separate URLs with canonical to parent +- Structured data for all variants + +## Content Priorities + +### High Priority +1. Category pages (top level) +2. Best-selling product pages +3. Homepage +4. Buying guides for main categories + +### Medium Priority +1. Subcategory pages +2. Brand pages +3. Comparison content +4. Seasonal landing pages + +### Blog Topics +- Buying guides ("How to Choose...") +- Product comparisons +- Trend reports +- Use cases and inspiration +- Care and maintenance guides + +## Key Metrics to Track + +- Revenue from organic search +- Product page rankings +- Category page rankings +- Click-through rate (rich results) +- Average order value from organic + +## Generative Engine Optimization (GEO) for E-commerce + +AI search platforms increasingly answer product queries directly. Optimize for AI citation: + +- [ ] Include clear product specifications, dimensions, materials in structured format +- [ ] Use ProductGroup schema for variant products +- [ ] Provide original product photography with descriptive alt text +- [ ] Include genuine customer review content (AggregateRating schema) +- [ ] Maintain consistent product entity data across all platforms (site, Amazon, Merchant Center) +- [ ] Structure comparison content with clear feature tables AI can parse +- [ ] Add detailed FAQ content for common product questions diff --git a/skills/seo-plan/assets/generic.md b/skills/seo-plan/assets/generic.md new file mode 100644 index 00000000..a02cb96f --- /dev/null +++ b/skills/seo-plan/assets/generic.md @@ -0,0 +1,144 @@ + +# Generic Business SEO Strategy Template + +## Overview + +This template applies to businesses that don't fit neatly into SaaS, local service, e-commerce, publisher, or agency categories. Customize based on your specific business model. + +## Recommended Site Architecture + +``` +/ +├── Home +├── /products (or /services) +│ ├── /product-1 +│ ├── /product-2 +│ └── ... +├── /solutions (if applicable) +│ ├── /solution-1 +│ └── ... +├── /about +│ ├── /team +│ ├── /history +│ └── /values +├── /resources +│ ├── /blog +│ ├── /guides +│ ├── /faq +│ └── /glossary +├── /contact +├── /support +└── /legal + ├── /privacy + └── /terms +``` + +## Universal SEO Principles + +### Every Page Should Have +- Unique title tag (30-60 chars) +- Unique meta description (120-160 chars) +- Single H1 matching page intent +- Logical heading hierarchy (H1→H2→H3) +- Internal links to related content +- Clear call-to-action + +### Schema for All Sites +| Page Type | Schema Types | +|-----------|-------------| +| Homepage | Organization, WebSite | +| About | Organization, AboutPage | +| Contact | ContactPage | +| Blog | Article, BlogPosting | +| FAQ | (FAQPage only for gov/health) | +| Product/Service | Product or Service | + +## Content Quality Standards + +### Minimum Word Counts +| Page Type | Min Words | +|-----------|-----------| +| Homepage | 500 | +| Product/Service | 800 | +| Blog Post | 1,500 | +| About Page | 400 | +| Landing Page | 600 | + +### E-E-A-T Essentials +1. **Experience**: Share real examples and case studies +2. **Expertise**: Display credentials and qualifications +3. **Authoritativeness**: Earn mentions and citations +4. **Trustworthiness**: Full contact info, policies visible + +## Technical Foundations + +### Must-Haves +- [ ] HTTPS enabled +- [ ] Mobile-responsive design +- [ ] robots.txt configured +- [ ] XML sitemap submitted +- [ ] Google Search Console verified +- [ ] Core Web Vitals passing (LCP <2.5s, INP <200ms, CLS <0.1) + +### Should-Haves +- [ ] Structured data on key pages +- [ ] Internal linking strategy +- [ ] 404 error page optimized +- [ ] Redirect chains eliminated +- [ ] Image optimization (WebP, lazy loading) + +## Content Priorities + +### Phase 1: Foundation (weeks 1-4) +1. Homepage optimization +2. Core product/service pages +3. About and contact pages +4. Basic schema implementation + +### Phase 2: Expansion (weeks 5-12) +1. Blog launch (2-4 posts/month) +2. FAQ page +3. Additional product/service pages +4. Internal linking audit + +### Phase 3: Growth (weeks 13-24) +1. Consistent content publishing +2. Link building outreach +3. GEO optimization +4. Performance optimization + +### Phase 4: Authority (months 7-12) +1. Thought leadership content +2. Original research +3. PR and media mentions +4. Advanced schema + +## Key Metrics to Track + +- Organic traffic (overall and by section) +- Keyword rankings (branded and non-branded) +- Conversion rate from organic +- Pages indexed +- Core Web Vitals scores +- Backlinks acquired + +## Customization Points + +Adjust this template based on: + +1. **Business Model**: B2B vs B2C vs D2C +2. **Geographic Scope**: Local, national, or international +3. **Content Type**: Product-focused vs content-heavy +4. **Competition Level**: Niche vs competitive market +5. **Resources**: Budget and team capacity + +## Generative Engine Optimization (GEO) Checklist + +- [ ] Include clear, quotable facts and statistics that AI systems can extract and cite +- [ ] Use structured data (Schema.org) to help AI systems understand content +- [ ] Build topical authority through comprehensive content clusters +- [ ] Provide original data, research, or unique perspectives AI cannot find elsewhere +- [ ] Maintain consistent entity information (brand, people, products) across the web +- [ ] Structure content with clear headings, definitions, and step-by-step formats +- [ ] Consider adding an `llms.txt` file at site root (emerging convention for AI crawlers: Google treats it as a regular text file) +- [ ] Monitor AI citation across Google AI Overviews, ChatGPT, Perplexity, and Bing Copilot diff --git a/skills/seo-plan/assets/local-service.md b/skills/seo-plan/assets/local-service.md new file mode 100644 index 00000000..a60b56a3 --- /dev/null +++ b/skills/seo-plan/assets/local-service.md @@ -0,0 +1,160 @@ + +# Local Service Business SEO Strategy Template + +## Industry Characteristics + +- Geographic-focused searches +- High intent, quick decision making +- Reviews heavily influence decisions +- Phone calls are primary conversion +- Mobile-first user behavior +- Emergency/urgent service needs + +## Recommended Site Architecture + +``` +/ +├── Home +├── /services +│ ├── /service-1 +│ ├── /service-2 +│ └── ... +├── /locations +│ ├── /city-1 +│ │ ├── /service-1-city-1 +│ │ └── ... +│ ├── /city-2 +│ └── ... +├── /about +├── /reviews +├── /gallery (or /portfolio) +├── /blog +├── /contact +├── /emergency (if applicable) +└── /faq +``` + +## Quality Gates + +### Location Page Limits +- ⚠️ **WARNING** at 30+ location pages +- 🛑 **HARD STOP** at 50+ location pages + +### Unique Content Requirements +| Page Type | Min Words | Unique % | +|-----------|-----------|----------| +| Primary Location | 600 | 60%+ | +| Service Area | 500 | 40%+ | +| Service Page | 800 | 100% | + +### What Makes Location Pages Unique +- Local landmarks and neighborhoods +- Specific services offered at that location +- Local team members +- Location-specific testimonials +- Community involvement +- Local regulations or considerations + +## Schema Recommendations + +| Page Type | Schema Types | +|-----------|-------------| +| Homepage | LocalBusiness, Organization | +| Service Pages | Service, LocalBusiness | +| Location Pages | LocalBusiness (with geo) | +| Contact | ContactPage, LocalBusiness | +| Reviews | LocalBusiness (with AggregateRating) | + +### LocalBusiness Schema Example +```json +{ + "@context": "https://schema.org", + "@type": "LocalBusiness", + "name": "Business Name", + "address": { + "@type": "PostalAddress", + "streetAddress": "123 Main St", + "addressLocality": "City", + "addressRegion": "State", + "postalCode": "12345" + }, + "telephone": "+1-555-555-5555", + "openingHours": "Mo-Fr 08:00-18:00", + "geo": { + "@type": "GeoCoordinates", + "latitude": "40.7128", + "longitude": "-74.0060" + }, + "areaServed": ["City 1", "City 2"], + "priceRange": "$$" +} +``` + +## Google Business Profile Integration + +- Ensure NAP consistency (Name, Address, Phone) +- Sync service categories +- Regular post updates +- Photo uploads +- Review response strategy + +### Google Business Profile Updates (2025-2026) + +- **Video verification** is now standard: postcard verification has been largely phased out. Prepare for a short video verification process showing the business location or service area. +- **WhatsApp integration** replaced Google Business Chat (deprecated). Businesses can connect WhatsApp as their primary messaging channel. +- **Q&A removed from Maps**: replaced by AI-generated answers. Ensure your GBP description, services, and website FAQ are comprehensive, as Google AI uses them to answer queries. +- **Business hours are a top-5 ranking factor**: "Business is open at time of search" ranked as a top individual factor for the first time (Whitespark 2026 Local Search Ranking Factors Report). Keep hours accurate; consider extended hours if feasible. +- **Review "Stories" format**: Google Maps now shows review snippets in a swipeable Stories format on mobile. Encourage detailed, descriptive reviews with photos. + +### Service Area Business (SAB) Update (June 2025) + +Google updated SAB guidelines to **disallow entire states or countries** as service areas. SABs must specify: cities, postal/ZIP codes, or neighborhoods. If you serve an entire metro area, list the major cities within it rather than the state. + +### AI Visibility for Local Businesses + +AI Overviews appear for only ~0.14% of local keywords (March 2025 data), local SEO faces significantly less AI disruption than other verticals. However, ChatGPT and Perplexity are increasingly used for local recommendations. + +To optimize for AI local visibility: +- Ensure presence on expert-curated "best of" lists (ranked #1 AI visibility factor in Whitespark 2026 report) +- Maintain consistent NAP (Name, Address, Phone) across all platforms +- Build genuine review volume and quality +- Use LocalBusiness schema with complete properties (geo, openingHours, priceRange, areaServed) + +## Content Priorities + +### High Priority +1. Homepage with clear service area +2. Core service pages +3. Primary city page +4. Contact page with all locations + +### Medium Priority +1. Service + location combination pages +2. FAQ page +3. About/team page +4. Reviews/testimonials page + +### Blog Topics +- Seasonal maintenance tips +- How to choose a [service provider] +- Warning signs of [problem] +- DIY vs professional comparisons +- Local regulations and permits + +## Key Metrics to Track + +- Local pack rankings +- Phone call volume from organic +- Direction requests +- Google Business Profile insights +- Reviews count and rating + +## Generative Engine Optimization (GEO) for Local + +- [ ] Include clear, quotable service descriptions and pricing ranges +- [ ] Use LocalBusiness schema with complete geo, openingHours, and areaServed +- [ ] Build presence on curated "best of" and local directory lists +- [ ] Maintain consistent NAP across all platforms (Google, Yelp, Apple Maps) +- [ ] Include original photos of work, team, and location +- [ ] Structure FAQ content for common local service questions +- [ ] Monitor AI citation in ChatGPT and Perplexity local recommendations diff --git a/skills/seo-plan/assets/publisher.md b/skills/seo-plan/assets/publisher.md new file mode 100644 index 00000000..55d75e41 --- /dev/null +++ b/skills/seo-plan/assets/publisher.md @@ -0,0 +1,153 @@ + +# Publisher/Media SEO Strategy Template + +## Industry Characteristics + +- High content volume +- Time-sensitive content (news) +- Ad revenue dependent on traffic +- Authority and trust critical +- Competing with social platforms +- AI Overviews impact on traffic + +## Recommended Site Architecture + +``` +/ +├── Home +├── /news (or /latest) +├── /topics +│ ├── /topic-1 +│ ├── /topic-2 +│ └── ... +├── /authors +│ ├── /author-1 +│ └── ... +├── /opinion +├── /reviews +├── /guides +├── /videos +├── /podcasts +├── /newsletter +├── /about +│ ├── /editorial-policy +│ ├── /corrections +│ └── /contact +└── /[year]/[month]/[slug] (article URLs) +``` + +## Schema Recommendations + +| Page Type | Schema Types | +|-----------|-------------| +| Article | NewsArticle or Article, Person (author), Organization (publisher) | +| Author Page | Person, ProfilePage | +| Topic Page | CollectionPage, ItemList | +| Homepage | WebSite, Organization | +| Video | VideoObject | +| Podcast | PodcastEpisode, PodcastSeries | + +### NewsArticle Schema Example +```json +{ + "@context": "https://schema.org", + "@type": "NewsArticle", + "headline": "Article Headline", + "datePublished": "2026-02-07T10:00:00Z", + "dateModified": "2026-02-07T14:30:00Z", + "author": { + "@type": "Person", + "name": "Author Name", + "url": "https://example.com/authors/author-name" + }, + "publisher": { + "@type": "Organization", + "name": "Publication Name", + "logo": { + "@type": "ImageObject", + "url": "https://example.com/logo.png" + } + }, + "image": ["https://example.com/article-image.jpg"], + "mainEntityOfPage": { + "@type": "WebPage", + "@id": "https://example.com/article-url" + } +} +``` + +## E-E-A-T Requirements + +Publishers face highest E-E-A-T scrutiny. + +### Author Pages Must Include +- Full name and photo +- Bio and credentials +- Areas of expertise +- Contact information +- Social profiles (sameAs) +- Previous articles by this author + +### Editorial Standards +- Clear correction policy +- Transparent editorial process +- Fact-checking procedures +- Conflict of interest disclosures + +## Content Priorities + +### High Priority +1. Breaking news (speed matters) +2. Evergreen guides on core topics +3. Author pages with credentials +4. Topic hubs/pillar pages + +### Medium Priority +1. Opinion/analysis pieces +2. Video content +3. Interactive content +4. Newsletter landing pages + +### GEO Considerations +- Clear, quotable facts in articles +- Tables for data-heavy content +- Expert quotes with attribution +- Update dates prominently displayed +- Structured headings (H2/H3) +- First-party data and original research are highly cited by AI systems +- Ensure author entities are clearly defined with Person schema + sameAs links +- Monitor AI citation frequency across Google AI Overviews, AI Mode, ChatGPT, Perplexity +- Treat AI citation as a standalone KPI alongside organic traffic + +### Publisher SEO Updates (2025-2026) + +- **Google News automatic inclusion:** Google News no longer accepts manual applications (since March 2025). Inclusion is fully automatic based on Google's content quality criteria. Focus on Google News sitemap markup and consistent, high-quality publishing cadence. +- **KPI shift:** Traffic-based KPIs (sessions, pageviews) are declining in relevance as AI Overviews reduce click-through rates. Leading publishers are shifting to: subscriber conversions, time on page, scroll depth, newsletter signups, AI citation frequency, and revenue per visitor. +- **Site reputation abuse risk:** Publishers hosting third-party content (coupons, product reviews, affiliate content) under their domain are at high risk. Google penalized Forbes, WSJ, Time, and CNN for this in late 2024. If hosting third-party content, ensure strong editorial oversight and clear first-party involvement. + +## Technical Considerations + +### Core Web Vitals +- Ad placement affects CLS +- Lazy load ads and images below fold +- Optimize hero images for LCP +- Minimize render-blocking resources + +### AMP (if used) +- Consider dropping AMP (no longer required for Top Stories) +- Ensure canonical setup is correct +- Monitor performance vs non-AMP + +### Pagination +- Proper pagination for multi-page articles +- Or infinite scroll with proper indexing +- Canonical to page 1 or full article + +## Key Metrics to Track + +- Page views from organic +- Time on page +- Pages per session +- Newsletter signups from organic +- Google News/Discover traffic +- AI Overview appearances diff --git a/skills/seo-plan/assets/saas.md b/skills/seo-plan/assets/saas.md new file mode 100644 index 00000000..3c4ebe61 --- /dev/null +++ b/skills/seo-plan/assets/saas.md @@ -0,0 +1,135 @@ + +# SaaS SEO Strategy Template + +## Industry Characteristics + +- Long sales cycles with multiple touchpoints +- Feature-focused decision making +- Comparison shopping behavior +- Heavy research phase before purchase +- Integration and ecosystem considerations + +## Recommended Site Architecture + +``` +/ +├── Home +├── /product (or /platform) +│ ├── /features +│ │ ├── /feature-1 +│ │ ├── /feature-2 +│ │ └── ... +│ ├── /integrations +│ │ ├── /integration-1 +│ │ └── ... +│ └── /security +├── /solutions +│ ├── /by-industry +│ │ ├── /industry-1 +│ │ └── ... +│ └── /by-use-case +│ ├── /use-case-1 +│ └── ... +├── /pricing +├── /customers +│ ├── /case-studies +│ │ ├── /case-study-1 +│ │ └── ... +│ └── /testimonials +├── /resources +│ ├── /blog +│ ├── /guides +│ ├── /webinars +│ ├── /templates +│ └── /glossary +├── /docs (or /help) +│ └── /api +├── /company +│ ├── /about +│ ├── /careers +│ ├── /press +│ └── /contact +└── /compare + ├── /vs-competitor-1 + └── /vs-competitor-2 +``` + +## Content Priorities + +### High Priority Pages +1. Homepage (value proposition, social proof) +2. Features overview +3. Pricing page +4. Key integrations +5. Top 3-5 use case pages + +### Medium Priority Pages +1. Individual feature pages +2. Industry solution pages +3. Case studies (2-3 detailed ones) +4. Comparison pages (vs competitors) + +### Content Marketing Focus +1. Bottom-of-funnel: Comparison guides, ROI calculators +2. Middle-of-funnel: How-to guides, best practices +3. Top-of-funnel: Industry trends, educational content + +## Schema Recommendations + +| Page Type | Schema Types | +|-----------|-------------| +| Homepage | Organization, WebSite, SoftwareApplication | +| Product/Features | SoftwareApplication, Offer | +| Pricing | SoftwareApplication, Offer (with pricing) | +| Blog | Article, BlogPosting | +| Case Studies | Article, Organization (customer) | +| Documentation | TechArticle | + +## Key Metrics to Track + +- Organic traffic to pricing page +- Demo/trial signups from organic +- Blog → pricing page conversion +- Comparison page rankings +- Integration page performance + +## Comparison & Alternative Pages + +Comparison pages are among the highest-converting content types for SaaS, with conversion rates of **4-7%** vs. 0.5-1.8% for standard blog content (35.8% of marketers report comparison content performs "better than ever" per Intergrowth November 2025 survey). + +**Recommended page types:** +- `/{product}-vs-{competitor}`: Direct 1:1 comparison +- `/{competitor}-alternative`: Targeting competitor brand searches +- `/compare/{category}`: Category comparison hub +- `/best-{category}-tools`: Roundup-style pages + +**Best practices:** +- Include structured comparison tables with pricing, features, pros/cons +- Be factually accurate about competitors: verify claims regularly +- Include customer testimonials from users who switched +- Add FAQ schema for common comparison questions (valuable for AI search) +- Update regularly: stale comparison data damages credibility +- Cross-reference the `seo-competitor-pages` skill for detailed frameworks + +**Legal considerations:** +- Nominative fair use generally permits competitor brand mentions for comparison purposes +- Do NOT imply endorsement or affiliation +- Do NOT make false or unverifiable claims about competitor products +- Different jurisdictions have different trademark laws: consult legal counsel + +## Competitive Considerations + +- Monitor competitor feature releases +- Track competitor content strategies +- Identify keyword gaps in feature coverage +- Watch for new comparison opportunities + +## Generative Engine Optimization (GEO) for SaaS + +- [ ] Include clear, structured feature comparisons that AI systems can parse and cite +- [ ] Use SoftwareApplication schema with complete feature lists and pricing +- [ ] Publish original benchmark data, case studies, and ROI metrics +- [ ] Build content clusters around key product categories and use cases +- [ ] Ensure integration pages have clear, quotable descriptions +- [ ] Structure pricing information in tables AI can extract +- [ ] Monitor AI citation across Google AI Overviews, ChatGPT, and Perplexity diff --git a/skills/seo-programmatic/SKILL.md b/skills/seo-programmatic/SKILL.md new file mode 100644 index 00000000..f4f8e101 --- /dev/null +++ b/skills/seo-programmatic/SKILL.md @@ -0,0 +1,184 @@ +--- +name: seo-programmatic +description: "Plan and audit programmatic SEO pages generated at scale from structured data. Use when designing templates, URL systems, internal linking, quality gates, and index-bloat safeguards for pages at scale." +risk: unknown +source: "https://github.com/AgriciDaniel/claude-seo" +date_added: "2026-03-21" +user-invokable: true +argument-hint: "[url or plan]" +allowed-tools: + - Read + - Grep + - Glob + - Bash + - WebFetch + - Write +--- + +# Programmatic SEO Analysis & Planning + +Build and audit SEO pages generated at scale from structured data sources. +Enforces quality gates to prevent thin content penalties and index bloat. + +## When to Use + +- Use when the user wants programmatic SEO planning or review. +- Use when designing templates, data-driven pages, or scalable URL systems. +- Use when preventing thin content and index bloat across large page sets. + +## Data Source Assessment + +Evaluate the data powering programmatic pages: +- **CSV/JSON files**: Row count, column uniqueness, missing values +- **API endpoints**: Response structure, data freshness, rate limits +- **Database queries**: Record count, field completeness, update frequency +- Data quality checks: + - Each record must have enough unique attributes to generate distinct content + - Flag duplicate or near-duplicate records (>80% field overlap) + - Verify data freshness; stale data produces stale pages + +## Template Engine Planning + +Design templates that produce unique, valuable pages: +- **Variable injection points**: Title, H1, body sections, meta description, schema +- **Content blocks**: Static (shared across pages) vs dynamic (unique per page) +- **Conditional logic**: Show/hide sections based on data availability +- **Supplementary content**: Related items, contextual tips, user-generated content +- Template review checklist: + - Each page must read as a standalone, valuable resource + - No "mad-libs" patterns (just swapping city/product names in identical text) + - Dynamic sections must add genuine information, not just keyword variations + +## URL Pattern Strategy + +### Common Patterns +- `/tools/[tool-name]`: Tool/product directory pages +- `/[city]/[service]`: Location + service pages +- `/integrations/[platform]`: Integration landing pages +- `/glossary/[term]`: Definition/reference pages +- `/templates/[template-name]`: Downloadable template pages + +### URL Rules +- Lowercase, hyphenated slugs derived from data +- Logical hierarchy reflecting site architecture +- No duplicate slugs; enforce uniqueness at generation time +- Keep URLs under 100 characters +- No query parameters for primary content URLs +- Consistent trailing slash usage (match existing site pattern) + +## Internal Linking Automation + +- **Hub/spoke model**: Category hub pages linking to individual programmatic pages +- **Related items**: Auto-link to 3-5 related pages based on data attributes +- **Breadcrumbs**: Generate BreadcrumbList schema from URL hierarchy +- **Cross-linking**: Link between programmatic pages sharing attributes (same category, same city, same feature) +- **Anchor text**: Use descriptive, varied anchor text. Avoid exact-match keyword repetition +- Link density: 3-5 internal links per 1000 words (match seo-content guidelines) + +## Thin Content Safeguards + +### Quality Gates + +| Metric | Threshold | Action | +|--------|-----------|--------| +| Pages without content review | 100+ | ⚠️ WARNING: require content audit before publishing | +| Pages without justification | 500+ | 🛑 HARD STOP: require explicit user approval and thin content audit | +| Unique content per page | <40% | ❌ Flag as thin content (likely penalty risk) | +| Word count per page | <300 | ⚠️ Flag for review (may lack sufficient value) | + +### Scaled Content Abuse: Enforcement Context (2025-2026) + +Google's Scaled Content Abuse policy (introduced March 2024) saw major enforcement escalation in 2025: + +- **June 2025:** Wave of manual actions targeting websites with AI-generated content at scale +- **August 2025:** SpamBrain spam update enhanced pattern detection for AI-generated link schemes and content farms +- **Result:** Google reported 45% reduction in low-quality, unoriginal content in search results post-March 2024 enforcement + +**Enhanced quality gates for programmatic pages:** +- **Content differentiation:** ≥30-40% of content must be genuinely unique between any two programmatic pages (not just city/keyword string replacement) +- **Human review:** Minimum 5-10% sample review of generated pages before publishing +- **Progressive rollout:** Publish in batches of 50-100 pages. Monitor indexing and rankings for 2-4 weeks before expanding. Never publish 500+ programmatic pages simultaneously without explicit quality review. +- **Standalone value test:** Each page should pass: "Would this page be worth publishing even if no other similar pages existed?" +- **Site reputation abuse:** If publishing programmatic content under a high-authority domain (not your own), this may trigger site reputation abuse penalties. Google began enforcing this aggressively in November 2024. + +> **Recommendation:** The WARNING gate at `<40% unique content` remains appropriate. Consider a HARD STOP at `<30%` unique content to prevent scaled content abuse risk. + +### Safe Programmatic Pages (OK at scale) +✅ Integration pages (with real setup docs, API details, screenshots) +✅ Template/tool pages (with downloadable content, usage instructions) +✅ Glossary pages (200+ word definitions with examples, related terms) +✅ Product pages (unique specs, reviews, comparison data) +✅ Data-driven pages (unique statistics, charts, analysis per record) + +### Penalty Risk (avoid at scale) +❌ Location pages with only city name swapped in identical text +❌ "Best [tool] for [industry]" without industry-specific value +❌ "[Competitor] alternative" without real comparison data +❌ AI-generated pages without human review and unique value-add +❌ Pages where >60% of content is shared template boilerplate + +### Uniqueness Calculation +Unique content % = (words unique to this page) / (total words on page) × 100 + +Measure against all other pages in the programmatic set. Shared headers, footers, and navigation are excluded from the calculation. Template boilerplate text IS included. + +## Canonical Strategy + +- Every programmatic page must have a self-referencing canonical tag +- Parameter variations (sort, filter, pagination) canonical to the base URL +- Paginated series: canonical to page 1 or use rel=next/prev +- If programmatic pages overlap with manual pages, the manual page is canonical +- No canonical to a different domain unless intentional cross-domain setup + +## Sitemap Integration + +- Auto-generate sitemap entries for all programmatic pages +- Split at 50,000 URLs per sitemap file (protocol limit) +- Use sitemap index if multiple sitemap files needed +- `` reflects actual data update timestamp (not generation time) +- Exclude noindexed programmatic pages from sitemap +- Register sitemap in robots.txt +- Update sitemap dynamically as new records are added to data source + +## Index Bloat Prevention + +- **Noindex low-value pages**: Pages that don't meet quality gates +- **Pagination**: Noindex paginated results beyond page 1 (or use rel=next/prev) +- **Faceted navigation**: Noindex filtered views, canonical to base category +- **Crawl budget**: For sites with >10k programmatic pages, monitor crawl stats in Search Console +- **Thin page consolidation**: Merge records with insufficient data into aggregated pages +- **Regular audits**: Monthly review of indexed page count vs intended count + +## Output + +### Programmatic SEO Score: XX/100 + +### Assessment Summary +| Category | Status | Score | +|----------|--------|-------| +| Data Quality | ✅/⚠️/❌ | XX/100 | +| Template Uniqueness | ✅/⚠️/❌ | XX/100 | +| URL Structure | ✅/⚠️/❌ | XX/100 | +| Internal Linking | ✅/⚠️/❌ | XX/100 | +| Thin Content Risk | ✅/⚠️/❌ | XX/100 | +| Index Management | ✅/⚠️/❌ | XX/100 | + +### Critical Issues (fix immediately) +### High Priority (fix within 1 week) +### Medium Priority (fix within 1 month) +### Low Priority (backlog) + +### Recommendations +- Data source improvements +- Template modifications +- URL pattern adjustments +- Quality gate compliance actions + +## Error Handling + +| Scenario | Action | +|----------|--------| +| URL unreachable | Report connection error with status code. Suggest verifying URL accessibility and checking for authentication requirements. | +| No programmatic pages detected | Inform user that no template-generated or data-driven page patterns were found. Suggest checking if pages use client-side rendering or if the URL points to the correct section. | +| Thin content threshold exceeded | Trigger quality gate warning. Report the unique content percentage and flag pages below 40% uniqueness. Require user acknowledgment before proceeding. | +| Quality gate violation | Halt analysis at the HARD STOP threshold (500+ pages without justification or <30% unique content). Present findings and require explicit user approval to continue. | diff --git a/skills/seo-schema/SKILL.md b/skills/seo-schema/SKILL.md new file mode 100644 index 00000000..01ce2f0b --- /dev/null +++ b/skills/seo-schema/SKILL.md @@ -0,0 +1,178 @@ +--- +name: seo-schema +description: > + Detect, validate, and generate Schema.org structured data. JSON-LD format + preferred. Use when user says "schema", "structured data", "rich results", + "JSON-LD", or "markup". +risk: unknown +source: "https://github.com/AgriciDaniel/claude-seo" +date_added: "2026-03-21" +user-invokable: true +argument-hint: "[url]" +allowed-tools: + - Read + - Grep + - Glob + - Bash + - WebFetch + - Write +--- + +# Schema Markup Analysis & Generation + +## When to Use + +- Use when detecting, validating, or generating Schema.org structured data. +- Use when the user asks about JSON-LD, rich results, or markup opportunities. +- Use when schema validation is the main task, rather than a broader SEO audit. + +## Detection + +1. Scan page source for JSON-LD `