Compare commits
14 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 mohitagw15856
|
44f69a541f | ||
 Mohit Aggarwal
|
20eda05cc6 | ||
|
Mohit Aggarwal
|
6bb25a8c13 | ||
|
Mohit Aggarwal
|
5f12fcff50 | ||
|
Mohit Aggarwal
|
84abb1583d | ||
|
Mohit Aggarwal
|
2c92636980 | ||
|
mohitagw15856
|
dc579c7512 | ||
|
Mohit Aggarwal
|
d213ccde1c | ||
|
mohitagw15856
|
ae6ea4d53e | ||
|
mohitagw15856
|
94e53d38a8 | ||
|
mohitagw15856
|
01c10eb625 | ||
|
mohitagw15856
|
49137bd1b6 | ||
|
mohitagw15856
|
929fa3ad7f | ||
|
mohitagw15856
|
e366a77cf0 |
@@ -1,8 +1,8 @@
|
||||
{
|
||||
"$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
|
||||
"name": "pm-claude-skills",
|
||||
"version": "11.0.0",
|
||||
"description": "PM stands for Professional, not just Product Management. 135 Claude Skills + 4 agent templates across 23 bundles covering 16 professions — engineering, customer success, legal, finance, HR, sales, design, Figma, marketing, and more. Built by a PM, used by everyone. Building blocks for the Anthropic agent template architecture.",
|
||||
"version": "14.0.0",
|
||||
"description": "PM stands for Professional, not just Product Management. 167 Claude Skills + 4 agent templates across 26 bundles covering 18 professions — engineering, customer success, legal, finance, HR, sales, design, Figma, marketing, social media, writers, and more. Built by a PM, used by everyone. Building blocks for the Anthropic agent template architecture.",
|
||||
"owner": {
|
||||
"name": "Mohit Aggarwal",
|
||||
"email": "mohit15856@gmail.com"
|
||||
@@ -18,8 +18,8 @@
|
||||
},
|
||||
{
|
||||
"name": "pm-discovery",
|
||||
"description": "Discovery & research skills: Discovery Interview Guide, Job Story Mapper, User Interview Synthesis, Assumption Mapper. Structure user research from screener to synthesis.",
|
||||
"version": "3.0.0",
|
||||
"description": "Discovery & research skills: Discovery Interview Guide, Job Story Mapper, User Interview Synthesis, Assumption Mapper, Customer Journey Map. Structure user research from screener to synthesis — including end-to-end journey mapping with touchpoints, emotions, and prioritised opportunities.",
|
||||
"version": "3.1.0",
|
||||
"category": "productivity",
|
||||
"source": "./plugins/pm-discovery",
|
||||
"homepage": "https://github.com/mohitagw15856/pm-claude-skills"
|
||||
@@ -34,8 +34,8 @@
|
||||
},
|
||||
{
|
||||
"name": "pm-delivery",
|
||||
"description": "Sprint & delivery skills: Sprint Planning, Technical Spec, A/B Test Planner, Go-to-Market Planner, Launch Checklist, Sprint Brief, Retro Analysis, PPTX Slide Auditor.",
|
||||
"version": "3.1.0",
|
||||
"description": "Sprint & delivery skills: Sprint Planning, Technical Spec, A/B Test Planner, Go-to-Market Planner, Launch Checklist, Sprint Brief, Retro Analysis, PPTX Slide Auditor, User Story Writer. Write production-ready user stories with Given/When/Then acceptance criteria, edge cases, and definition of done.",
|
||||
"version": "3.2.0",
|
||||
"category": "productivity",
|
||||
"source": "./plugins/pm-delivery",
|
||||
"homepage": "https://github.com/mohitagw15856/pm-claude-skills"
|
||||
@@ -58,8 +58,8 @@
|
||||
},
|
||||
{
|
||||
"name": "pm-advanced",
|
||||
"description": "Advanced PM skills: AI Product Canvas, Multi-Source Signal Synthesiser, Experiment Designer, Design Handoff Brief, Stakeholder Update. For senior PMs working on complex products.",
|
||||
"version": "3.0.0",
|
||||
"description": "Advanced PM skills: AI Product Canvas, Multi-Source Signal Synthesiser, Experiment Designer, Design Handoff Brief, AI Ethics Review. For senior PMs working on complex products — including a structured ethical review framework for AI/ML features covering fairness, transparency, privacy, safety, and accountability.",
|
||||
"version": "3.1.0",
|
||||
"category": "productivity",
|
||||
"source": "./plugins/pm-advanced",
|
||||
"homepage": "https://github.com/mohitagw15856/pm-claude-skills"
|
||||
@@ -74,48 +74,48 @@
|
||||
},
|
||||
{
|
||||
"name": "pm-gtm",
|
||||
"description": "Marketing & GTM skills: Go-To-Market Planner, Content Calendar, Competitor Teardown, Email Campaign, SEO Content Brief, Media Pitch. Build positioning statements, messaging pillars, feature lists, use cases, launch campaigns, SEO briefs, and journalist pitches.",
|
||||
"version": "1.1.0",
|
||||
"description": "Marketing & GTM skills: Go-To-Market Planner, Content Calendar, Competitor Teardown, Email Campaign, SEO Content Brief, Media Pitch, Social Media Strategy, Product Positioning Doc. Build positioning docs, messaging frameworks, content pillars, social strategies with KPIs, launch campaigns, and journalist pitches.",
|
||||
"version": "1.2.0",
|
||||
"category": "productivity",
|
||||
"source": "./plugins/pm-gtm",
|
||||
"homepage": "https://github.com/mohitagw15856/pm-claude-skills"
|
||||
},
|
||||
{
|
||||
"name": "pm-engineering",
|
||||
"description": "Engineering & tech skills: Code Review Checklist, Incident Postmortem, API Docs Writer, Architecture Decision Record, Debugging Log Analyser, PR Description Writer, System Design Interview, Changelog Generator, Test Strategy Doc, Runbook Writer, CI/CD Playbook, SLO & Error Budget, Developer Onboarding Doc, On-Call Runbook, Security Threat Model, Performance Budget, Database Schema Design, Database Migration Plan, Technical Debt Register, RFC Writer, Capacity Planning, Load Testing Plan, Disaster Recovery Plan, Feature Flag Guide, Dependency Audit, Service Catalog Entry, Monitoring Setup Guide, Local Dev Setup, API Versioning Strategy, Infra-as-Code Review, Engineering Weekly Report, Tech Radar, Sprint Velocity Analysis, Microservices Decomposition, Engineering Hiring Rubric. 35 structured skills for engineering teams, SREs, and technical PMs.",
|
||||
"version": "4.0.0",
|
||||
"description": "Engineering & tech skills: Code Review Checklist, Incident Postmortem, API Docs Writer, Architecture Decision Record, Debugging Log Analyser, PR Description Writer, System Design Interview, Changelog Generator, Test Strategy Doc, Runbook Writer, CI/CD Playbook, SLO & Error Budget, Developer Onboarding Doc, On-Call Runbook, Security Threat Model, Performance Budget, Database Schema Design, Database Migration Plan, Technical Debt Register, RFC Writer, Capacity Planning, Load Testing Plan, Disaster Recovery Plan, Feature Flag Guide, Dependency Audit, Service Catalog Entry, Monitoring Setup Guide, Local Dev Setup, API Versioning Strategy, Infra-as-Code Review, Engineering Weekly Report, Tech Radar, Sprint Velocity Analysis, Microservices Decomposition, Engineering Hiring Rubric, Context Mode, Claude Superpowers. 37 structured skills for engineering teams, SREs, technical PMs, and Claude Code power users.",
|
||||
"version": "4.1.0",
|
||||
"category": "productivity",
|
||||
"source": "./plugins/pm-engineering",
|
||||
"homepage": "https://github.com/mohitagw15856/pm-claude-skills"
|
||||
},
|
||||
{
|
||||
"name": "pm-cs",
|
||||
"description": "Customer Success skills: Customer Health Scorecard, QBR Deck, Escalation Brief, Churn Analysis. Score account health with a weighted RAG framework, build structured QBR decks with value narratives, write crisp escalation briefs for at-risk accounts, and analyse churn by category and segment with prioritised interventions.",
|
||||
"version": "1.0.0",
|
||||
"description": "Customer Success skills: Customer Health Scorecard, QBR Deck, Escalation Brief, Churn Analysis, Renewal Playbook, Customer Success Plan. Score health, build QBRs, write escalation briefs, plan renewals with commercial strategy and objection responses, and build joint success plans with milestones and mutual commitments.",
|
||||
"version": "1.1.0",
|
||||
"category": "productivity",
|
||||
"source": "./plugins/pm-cs",
|
||||
"homepage": "https://github.com/mohitagw15856/pm-claude-skills"
|
||||
},
|
||||
{
|
||||
"name": "pm-data",
|
||||
"description": "Data & analytics skills: Metrics Framework, SQL Query Explainer, Dashboard Brief, Chart Data Extractor. Build North Star metric trees, explain SQL, spec dashboards, and digitise chart images.",
|
||||
"version": "1.1.0",
|
||||
"description": "Data & analytics skills: Metrics Framework, SQL Query Explainer, Dashboard Brief, Chart Data Extractor, Cohort Analysis, Data Pipeline Spec. Build metric trees, explain SQL, spec dashboards, run cohort retention analysis with LTV modelling, and design ETL/ELT pipeline specifications with SLAs and data quality rules.",
|
||||
"version": "1.2.0",
|
||||
"category": "productivity",
|
||||
"source": "./plugins/pm-data",
|
||||
"homepage": "https://github.com/mohitagw15856/pm-claude-skills"
|
||||
},
|
||||
{
|
||||
"name": "pm-people",
|
||||
"description": "Leadership & people skills: Performance Review, Hiring Rubric, Team Offsite Planner. Write structured reviews, build interview scorecards, and plan offsites from goals to minute-by-minute agenda.",
|
||||
"version": "1.0.0",
|
||||
"description": "Leadership & people skills: Performance Review, Hiring Rubric, Team Offsite Planner, 360-Degree Feedback Template, Team Health Check. Write reviews, build scorecards, run Spotify-model team health assessments, and design 360 feedback surveys with structured narrative reports.",
|
||||
"version": "1.1.0",
|
||||
"category": "productivity",
|
||||
"source": "./plugins/pm-people",
|
||||
"homepage": "https://github.com/mohitagw15856/pm-claude-skills"
|
||||
},
|
||||
{
|
||||
"name": "pm-design",
|
||||
"description": "Design & UX skills: UX Research Plan, Design Critique, Accessibility Audit. Create research plans with discussion guides, critique designs using JTBD and Gestalt principles, audit for WCAG 2.2 compliance.",
|
||||
"version": "1.0.0",
|
||||
"description": "Design & UX skills: UX Research Plan, Design Critique, Accessibility Audit, Design System Audit. Create research plans, critique designs using JTBD and Gestalt principles, audit for WCAG 2.2 compliance, and audit design systems for component coverage, token consistency, and adoption health.",
|
||||
"version": "1.1.0",
|
||||
"category": "productivity",
|
||||
"source": "./plugins/pm-design",
|
||||
"homepage": "https://github.com/mohitagw15856/pm-claude-skills"
|
||||
@@ -154,16 +154,16 @@
|
||||
},
|
||||
{
|
||||
"name": "pm-sales",
|
||||
"description": "Sales skills: Sales Battlecard, Discovery Call Prep, Proposal Writer, Account Plan, Sales Forecasting Model. Build competitive battlecards, prepare discovery calls, write winning proposals, create account plans, and build pipeline-based revenue forecasts with scenario analysis.",
|
||||
"version": "1.1.0",
|
||||
"description": "Sales skills: Sales Battlecard, Discovery Call Prep, Proposal Writer, Account Plan, Sales Forecasting Model, Partnership Proposal. Build battlecards, prepare calls, write proposals, create account plans, build forecasts, and structure B2B partnership proposals with mutual value, commercial terms, and joint GTM plans.",
|
||||
"version": "1.2.0",
|
||||
"category": "productivity",
|
||||
"source": "./plugins/pm-sales",
|
||||
"homepage": "https://github.com/mohitagw15856/pm-claude-skills"
|
||||
},
|
||||
{
|
||||
"name": "pm-operations",
|
||||
"description": "Operations skills: Process Documentation, SOP Writer, Vendor Evaluation, Project Status Report, Workshop Facilitation Guide. Document workflows, write audit-ready SOPs, evaluate vendors, produce RAG status reports, and design facilitated workshops with activity instructions and facilitator moves.",
|
||||
"version": "1.1.0",
|
||||
"description": "Operations skills: Process Documentation, SOP Writer, Vendor Evaluation, Project Status Report, Workshop Facilitation Guide, Risk Register, RACI Matrix, Email Triage, Morning Intelligence. Document workflows, write SOPs, build risk registers, define RACI matrices, triage your inbox to only what needs action, and auto-generate a personalised morning news brief.",
|
||||
"version": "1.3.0",
|
||||
"category": "productivity",
|
||||
"source": "./plugins/pm-operations",
|
||||
"homepage": "https://github.com/mohitagw15856/pm-claude-skills"
|
||||
@@ -178,8 +178,8 @@
|
||||
},
|
||||
{
|
||||
"name": "pm-cross",
|
||||
"description": "Cross-profession skills: Press Release, Grant Proposal, Executive Summary, Teaching Lesson Plan. Write journalist-ready press releases, structure grant applications, produce decision-ready executive summaries, and design complete lesson plans for any subject, audience, or setting.",
|
||||
"version": "1.1.0",
|
||||
"description": "Cross-profession skills: Press Release, Grant Proposal, Executive Summary, Teaching Lesson Plan, Sycophancy Challenger, Last 30 Days Research, NotebookLM Connector. Get genuine push-back on your ideas (not validation), gather multi-platform research from the last 30 days, and automate NotebookLM from Claude.",
|
||||
"version": "1.2.0",
|
||||
"category": "productivity",
|
||||
"source": "./plugins/pm-cross",
|
||||
"homepage": "https://github.com/mohitagw15856/pm-claude-skills"
|
||||
@@ -191,6 +191,22 @@
|
||||
"category": "productivity",
|
||||
"source": "./plugins/pm-figma",
|
||||
"homepage": "https://github.com/mohitagw15856/pm-claude-skills"
|
||||
},
|
||||
{
|
||||
"name": "pm-social",
|
||||
"description": "Social Media skills: Social Media Audit, Influencer Brief, Community Management Playbook, Social Ad Campaign, Viral Content Framework. Score your social presence, brief influencer partnerships, manage communities at scale, plan paid social campaigns with full ad copy, and build a repeatable system for shareable content.",
|
||||
"version": "1.0.0",
|
||||
"category": "productivity",
|
||||
"source": "./plugins/pm-social",
|
||||
"homepage": "https://github.com/mohitagw15856/pm-claude-skills"
|
||||
},
|
||||
{
|
||||
"name": "pm-writers",
|
||||
"description": "Writers & Content Creators skills: Instagram Post Downloader, AEO Optimizer, Thumbnail Creator, Substack Notes Scraper, Notes Humanizer. Download Instagram carousels as PDFs, restructure articles for AI citation, generate thumbnail candidates via Gemini, export Substack Notes analytics to Excel, and strip AI writing patterns from any text.",
|
||||
"version": "1.0.0",
|
||||
"category": "productivity",
|
||||
"source": "./plugins/pm-writers",
|
||||
"homepage": "https://github.com/mohitagw15856/pm-claude-skills"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
@@ -1,18 +1,18 @@
|
||||
# 🧠 PM Claude Skills — 135 Skills for Every Profession
|
||||
# 🧠 PM Claude Skills — 167 Skills for Every Profession
|
||||
|
||||
[](https://github.com/mohitagw15856/pm-claude-skills/stargazers)
|
||||
[](https://github.com/mohitagw15856/pm-claude-skills)
|
||||
[](https://github.com/mohitagw15856/pm-claude-skills/releases)
|
||||
[](https://github.com/mohitagw15856/pm-claude-skills)
|
||||
[](https://github.com/mohitagw15856/pm-claude-skills/releases)
|
||||
[](https://github.com/mohitagw15856/pm-claude-skills#-quick-install-2-minutes)
|
||||
[](LICENSE)
|
||||
[](https://github.com/sponsors/mohitagw15856)
|
||||
|
||||
> **PM stands for Professional, not just Product Management.**
|
||||
> 135 Claude Skills + 4 agent templates across 16 professions. Built by a PM, used by everyone.
|
||||
> 167 Claude Skills + 4 agent templates across 26 bundles covering 18 professions. Built by a PM, used by everyone.
|
||||
|
||||
A community-built library of Claude Skills for professionals across every field — product management, engineering, customer success, marketing, design, legal, finance, HR, sales, operations, research, and more. Each skill is a structured SKILL.md file that teaches Claude how to produce professional-grade outputs for your specific workflows.
|
||||
A community-built library of Claude Skills for professionals across every field — product management, engineering, customer success, marketing, social media, writers, design, legal, finance, HR, sales, operations, research, and more. Each skill is a structured SKILL.md file that teaches Claude how to produce professional-grade outputs for your specific workflows.
|
||||
|
||||
**🆕 Latest release (v11.0.0):** The full 500-star milestone is now complete — 21 remaining engineering skills shipped. pm-engineering is now the largest bundle in the library with 35 skills. 135 skills across 16 professions.
|
||||
**🆕 Latest release (v14.0.0):** 12 new community-inspired skills across 4 bundles — a brand new Writers & Content Creators profession (Instagram downloader, AEO optimizer, thumbnail creator, Substack scraper, notes humanizer), plus decision-making, productivity, and Claude Code power tools.
|
||||
---
|
||||
|
||||
## 🚀 Quick Install (2 minutes)
|
||||
@@ -49,6 +49,10 @@ claude plugin install pm-cross@pm-claude-skills # Cross-profession
|
||||
|
||||
claude plugin install pm-figma@pm-claude-skills # Figma
|
||||
|
||||
claude plugin install pm-social@pm-claude-skills # Social Media 🆕
|
||||
|
||||
claude plugin install pm-writers@pm-claude-skills # Writers & Content Creators 🆕
|
||||
|
||||
|
||||
Or clone and symlink for auto-updates:
|
||||
|
||||
@@ -74,7 +78,7 @@ ln -s ~/pm-claude-skills/skills/* ~/.claude/skills/
|
||||
|
||||
On May 5, 2026, Anthropic [released their first agent templates](https://www.anthropic.com/news/finance-agents) — pre-packaged Claude agents that combine **skills, connectors, and subagents** into ready-to-run workflows for financial services.
|
||||
|
||||
This library is the largest open-source collection of professional skills available — covering 15 professions beyond financial services. **The 106 skills here are the building blocks for agent templates outside of finance.**
|
||||
This library is the largest open-source collection of professional skills available — covering 17 professions beyond financial services. **The 167 skills here are the building blocks for agent templates outside of finance.**
|
||||
|
||||
### What is an agent template?
|
||||
|
||||
@@ -151,6 +155,93 @@ More templates will follow. If you want to contribute one, see the [template con
|
||||
|
||||
---
|
||||
|
||||
## 🆕 What's New in v14.0.0 — Writers & Content Creators + 7 Community Skills
|
||||
|
||||
**12 new community-inspired skills across 4 bundles:**
|
||||
|
||||
### New profession: ✍️ Writers & Content Creators (`pm-writers`)
|
||||
|
||||
| Skill | What It Does |
|
||||
|---|---|
|
||||
| **Instagram Post Downloader** 🆕 | Downloads Instagram images and carousels as high-res files; stitches carousel slides into a single PDF |
|
||||
| **AEO Optimizer** 🆕 | Restructures articles for AI citation — rewrites H2s as questions, adds 50–80 word answer capsules, audits paragraph length and trust signals |
|
||||
| **Thumbnail Creator** 🆕 | Generates brand-aligned thumbnail candidates via Gemini API from article copy; Claude evaluates results via computer vision |
|
||||
| **Substack Notes Scraper** 🆕 | Scrapes Substack Notes engagement data (likes, comments, restacks) and exports a formatted .xlsx with filters and conditional formatting |
|
||||
| **Notes Humanizer** 🆕 | Strips AI writing patterns (em dashes, filler phrases, uniform rhythm) and injects genuine human signals — opinion, varied rhythm, specific detail |
|
||||
|
||||
### Extended: `pm-cross` (+3 skills)
|
||||
|
||||
| Skill | What It Does |
|
||||
|---|---|
|
||||
| **Sycophancy Challenger** 🆕 | Flips Claude's default — argues the strongest case *against* your idea first, holds its position under pushback, and only backs down with new evidence |
|
||||
| **Last 30 Days Research** 🆕 | Searches Reddit, X, and the web for the last 30 days on any topic and returns a structured report: consensus, disagreements, pain points, and signal confidence |
|
||||
| **NotebookLM Connector** 🆕 | Automates NotebookLM from Claude Code via Chrome extension — create notebooks, add sources, generate mindmaps and audio overviews |
|
||||
|
||||
### Extended: `pm-operations` (+2 skills)
|
||||
|
||||
| Skill | What It Does |
|
||||
|---|---|
|
||||
| **Email Triage** 🆕 | Reads Gmail for a configurable window, filters out receipts/notifications, and surfaces only what needs a reply or decision — with priority, urgency, and a reply starter |
|
||||
| **Morning Intelligence** 🆕 | 15-question interview that writes a personalised master prompt for your morning news brief, ready to drop into a Cowork Scheduled Task or Claude Code Routine |
|
||||
|
||||
### Extended: `pm-engineering` (+2 skills — for Claude Code users)
|
||||
|
||||
| Skill | What It Does |
|
||||
|---|---|
|
||||
| **Context Mode** 🆕 | Solves Claude Code context bloat and memory loss — filters raw command output and maintains a session log so Claude resumes exactly where it left off after a reset |
|
||||
| **Claude Superpowers** 🆕 | Forces Claude Code to plan before coding, work in isolation, write tests first, and review its own work twice — from 60% first pass to 80%+ |
|
||||
|
||||
The library now includes **167 skills** across **18 professions** + 4 working agent templates.
|
||||
|
||||
---
|
||||
|
||||
## 🆕 What's New in v13.0.0 — Social Media Profession
|
||||
|
||||
**5 new skills — a complete Social Media profession bundle:**
|
||||
|
||||
| Skill | Bundle | What It Does |
|
||||
|---|---|---|
|
||||
| **Social Media Audit** 🆕 | pm-social | Scored audit across all platforms — profile completeness, content performance, competitive benchmarking, and a prioritised action plan |
|
||||
| **Influencer Brief** 🆕 | pm-social | Complete creator partnership brief with deliverables, creative guidelines, approval workflow, commercial terms, and campaign measurement |
|
||||
| **Community Management Playbook** 🆕 | pm-social | Response frameworks, moderation rules, escalation tiers, DM templates, tone-of-voice guidance, and community health metrics |
|
||||
| **Social Ad Campaign** 🆕 | pm-social | Full-funnel paid social campaign plan with audience targeting, ad set architecture, copy for every format (video, static, carousel, lead gen), budget allocation, and A/B testing plan |
|
||||
| **Viral Content Framework** 🆕 | pm-social | Psychology of sharing, 6 proven hook formulas, 5 content structures, platform-specific playbooks for LinkedIn/TikTok/Instagram/X/YouTube, and a repeatable content testing system |
|
||||
|
||||
The library now includes **167 skills** across **18 professions** + 4 working agent templates.
|
||||
|
||||
Install the new bundle:
|
||||
|
||||
claude plugin install pm-social@pm-claude-skills
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 🆕 What's New in v12.0.0 — 150 Skills Milestone
|
||||
|
||||
**15 new skills across 10 bundles:**
|
||||
|
||||
| Skill | Bundle | What It Does |
|
||||
|---|---|---|
|
||||
| **Cohort Analysis** 🆕 | pm-data | Retention curves, LTV projection, behavioural segmentation, and churn leading indicators — with SQL reference queries |
|
||||
| **Data Pipeline Spec** 🆕 | pm-data | ETL/ELT pipeline design with sources, transforms, SLAs, DQ rules, error handling, and security/compliance notes |
|
||||
| **Renewal Playbook** 🆕 | pm-cs | Renewal brief with health snapshot, stakeholder map, value story, commercial scenarios, objection responses, and a 16-week timeline |
|
||||
| **Customer Success Plan** 🆕 | pm-cs | Joint success plan with business goals, success metrics, milestone roadmap, mutual commitments, and escalation path |
|
||||
| **360-Degree Feedback Template** 🆕 | pm-people | Either a complete survey instrument with GWT acceptance criteria, or a structured narrative feedback report with themes and development actions |
|
||||
| **Team Health Check** 🆕 | pm-people | Spotify-model health assessment across 7 dimensions — delivery, safety, morale, speed, purpose, and collaboration — with facilitation guide |
|
||||
| **Risk Register** 🆕 | pm-operations | L×I risk scoring, RAG heat map, top-risk executive summary, and per-risk mitigation and contingency plans |
|
||||
| **RACI Matrix** 🆕 | pm-operations | Complete RACI with role definitions, decision map, anti-pattern guide, and a communication template for all involved teams |
|
||||
| **Social Media Strategy** 🆕 | pm-gtm | Audience profile, platform rationale, content pillars, posting cadence, tone of voice, KPIs, and a 4-week starter calendar |
|
||||
| **Product Positioning Doc** 🆕 | pm-gtm | April Dunford-style positioning doc with category, target customer, competitive alternatives, differentiation, proof points, messaging hierarchy, and persona messaging |
|
||||
| **Customer Journey Map** 🆕 | pm-discovery | Stage-by-stage journey from awareness to advocacy with touchpoints, emotions, pain points, an emotion curve, and prioritised opportunities |
|
||||
| **User Story Writer** 🆕 | pm-delivery | Production-ready user stories with Given/When/Then ACs, edge cases, out-of-scope, definition of done, and epic decomposition |
|
||||
| **AI Ethics Review** 🆕 | pm-advanced | Structured ethical review covering fairness, bias, transparency, privacy, safety, accountability, and societal impact — with risk tier and pre-deployment checklist |
|
||||
| **Partnership Proposal** 🆕 | pm-sales | B2B partnership proposal with mutual value, commercial model, joint GTM plan, governance, and risks |
|
||||
| **Design System Audit** 🆕 | pm-design | Component coverage audit, token consistency, documentation quality, WCAG 2.2 accessibility, adoption barriers, and a remediation roadmap |
|
||||
|
||||
The library now includes **150 skills** across **16 professions** + 4 working agent templates.
|
||||
|
||||
---
|
||||
|
||||
## 🆕 What's New in v10.0.0
|
||||
|
||||
**Two star milestones unlocked — 8 new skills shipped:**
|
||||
@@ -232,88 +323,92 @@ This repo was built alongside a published article series. Read the full story:
|
||||
|
||||
---
|
||||
|
||||
## 🗂️ All 135 Skills
|
||||
## 🗂️ All 167 Skills
|
||||
|
||||
### 🛠️ Product Management (Skills 1–34)
|
||||
### 🛠️ Product Management (Skills 1–37)
|
||||
**Bundles:** `pm-essentials` · `pm-discovery` · `pm-planning` · `pm-delivery` · `pm-analytics` · `pm-strategy` · `pm-advanced` · `pm-rituals`
|
||||
|
||||
> The original toolkit covering the full PM lifecycle — discovery, prioritisation, delivery, strategy, stakeholder comms, and weekly rituals. Now includes Word tracked changes and PowerPoint slide auditing.
|
||||
|
||||
| # | Skill | What It Does |
|
||||
|---|---|---|
|
||||
| 1–6 | **pm-essentials** | PRD Template, Meeting Notes, Stakeholder Update, User Research Synthesis, Competitive Analysis, **Word Doc Tracked Changes** 🆕 |
|
||||
| 7–10 | **pm-discovery** | Discovery Interview Guide, Job Story Mapper, User Interview Synthesis, Assumption Mapper |
|
||||
| 11–16 | **pm-planning** | OKR Builder, Feature Prioritisation (RICE/MoSCoW/Kano/ICE), Roadmap Presentation, Pricing Strategy |
|
||||
| 17–24 | **pm-delivery** | Sprint Planning, Technical Spec, A/B Test Planner, Go-to-Market Planner, Launch Checklist, Sprint Brief, Retro, **PPTX Slide Auditor** 🆕 |
|
||||
| 25–27 | **pm-analytics** | Data Analysis Standard, Retention Analysis, Product Health Analysis |
|
||||
| 28–33 | **pm-strategy** | Competitor Signal Tracker, Competitive Intelligence Monitor, Stakeholder Influence Mapper, Strategic Narrative, Executive Update, Ambiguity Resolver |
|
||||
| 34 | **pm-advanced** | AI Product Canvas, Multi-Source Signal Synthesiser, Experiment Designer, Design Handoff Brief |
|
||||
| 1–6 | **pm-essentials** | PRD Template, Meeting Notes, Stakeholder Update, User Research Synthesis, Competitive Analysis, **Word Doc Tracked Changes** |
|
||||
| 7–11 | **pm-discovery** | Discovery Interview Guide, Job Story Mapper, User Interview Synthesis, Assumption Mapper, **Customer Journey Map** 🆕 |
|
||||
| 12–17 | **pm-planning** | OKR Builder, Feature Prioritisation (RICE/MoSCoW/Kano/ICE), Roadmap Presentation, Pricing Strategy, RICE Impact Matrix, Roadmap Narrative |
|
||||
| 18–26 | **pm-delivery** | Sprint Planning, Technical Spec, A/B Test Planner, Go-to-Market Planner, Launch Checklist, Sprint Brief, Retro, PPTX Slide Auditor, **User Story Writer** 🆕 |
|
||||
| 27–29 | **pm-analytics** | Data Analysis Standard, Retention Analysis, Product Health Analysis |
|
||||
| 30–35 | **pm-strategy** | Competitor Signal Tracker, Competitive Intelligence Monitor, Stakeholder Influence Mapper, Strategic Narrative, Executive Update, Ambiguity Resolver |
|
||||
| 36–37 | **pm-advanced** | AI Product Canvas, Multi-Source Signal Synthesiser, Experiment Designer, Design Handoff Brief, **AI Ethics Review** 🆕 |
|
||||
|
||||
> See [Part 7 article](https://medium.com/product-powerhouse/33-claude-skills-for-pms-are-now-in-the-claude-code-marketplace-heres-how-to-install-them-7968ab6bb1e1) for full PM skills detail.
|
||||
|
||||
---
|
||||
|
||||
### 📣 Marketing & GTM (Skills 35–40)
|
||||
### 📣 Marketing & GTM (Skills 38–45)
|
||||
**Bundle:** `pm-gtm`
|
||||
|
||||
| # | Skill | Folder | What It Does |
|
||||
|---|---|---|---|
|
||||
| 35 | **Go-To-Market** | `skills/go-to-market/` | Positioning statements, messaging pillars, feature/benefit mapping, role-specific use cases |
|
||||
| 36 | **Content Calendar** | `skills/content-calendar/` | Multi-channel content calendars with opening hooks, formats, and repurposing map |
|
||||
| 37 | **Competitor Teardown** | `skills/competitor-teardown/` | Full competitive analysis: positioning map, feature comparison, messaging gaps, SWOT, recommendations |
|
||||
| 38 | **Email Campaign** | `skills/email-campaign/` | Sequenced email campaigns with subject lines, preview text, body copy, and CTAs |
|
||||
| 39 | **SEO Content Brief** 🆕 | `skills/seo-content-brief/` | Complete SEO briefs with search intent, competitor gap analysis, content outline, and on-page requirements |
|
||||
| 40 | **Media Pitch** 🆕 | `skills/media-pitch/` | Story-first journalist pitches with angle development framework and pitch writing rules |
|
||||
| 38 | **Go-To-Market** | `skills/go-to-market/` | Positioning statements, messaging pillars, feature/benefit mapping, role-specific use cases |
|
||||
| 39 | **Content Calendar** | `skills/content-calendar/` | Multi-channel content calendars with opening hooks, formats, and repurposing map |
|
||||
| 40 | **Competitor Teardown** | `skills/competitor-teardown/` | Full competitive analysis: positioning map, feature comparison, messaging gaps, SWOT, recommendations |
|
||||
| 41 | **Email Campaign** | `skills/email-campaign/` | Sequenced email campaigns with subject lines, preview text, body copy, and CTAs |
|
||||
| 42 | **SEO Content Brief** | `skills/seo-content-brief/` | Complete SEO briefs with search intent, competitor gap analysis, content outline, and on-page requirements |
|
||||
| 43 | **Media Pitch** | `skills/media-pitch/` | Story-first journalist pitches with angle development framework and pitch writing rules |
|
||||
| 44 | **Social Media Strategy** 🆕 | `skills/social-media-strategy/` | Audience profile, platform rationale, content pillars, posting cadence, KPIs, and a 4-week starter calendar |
|
||||
| 45 | **Product Positioning Doc** 🆕 | `skills/product-positioning-doc/` | April Dunford-style positioning with category, differentiation, proof points, messaging hierarchy, and persona messaging |
|
||||
|
||||
---
|
||||
|
||||
### 👩💻 Engineering & Tech (Skills 41–75)
|
||||
### 👩💻 Engineering & Tech (Skills 46–80, 166–167)
|
||||
**Bundle:** `pm-engineering`
|
||||
|
||||
| # | Skill | Folder | What It Does |
|
||||
|---|---|---|---|
|
||||
| 41 | **Code Review Checklist** | `skills/code-review-checklist/` | Tailored PR review checklists by language, type, and risk level |
|
||||
| 42 | **Incident Postmortem** | `skills/incident-postmortem/` | Blameless postmortems with timeline, RCA, impact, and action items |
|
||||
| 43 | **API Docs Writer** | `skills/api-docs-writer/` | Developer-facing API docs: endpoints, parameters, response schemas, code examples |
|
||||
| 44 | **Architecture Decision Record** | `skills/architecture-decision-record/` | ADRs with context, options considered, decision, consequences, and risks |
|
||||
| 45 | **Debugging Log Analyser** | `skills/debugging-log-analyser/` | Parse stack traces and error logs into a structured root cause diagnosis with a specific fix |
|
||||
| 46 | **PR Description Writer** | `skills/pr-description-writer/` | Write reviewer-friendly PR descriptions from a diff, commit list, or change summary |
|
||||
| 47 | **System Design Interview** | `skills/system-design-interview/` | Structure complete system design answers with capacity estimates, component deep-dives, and trade-offs |
|
||||
| 48 | **Changelog Generator** | `skills/changelog-generator/` | Convert git commits into a polished, user-facing changelog following Keep a Changelog format |
|
||||
| 49 | **Test Strategy Doc** | `skills/test-strategy-doc/` | Write a complete test strategy with risk assessment, test types, coverage targets, and P0/P1 test cases |
|
||||
| 50 | **Runbook Writer** | `skills/runbook-writer/` | Write operational runbooks for deployments, incidents, and maintenance with exact commands and rollback steps |
|
||||
| 51 | **CI/CD Playbook** | `skills/cicd-playbook/` | Complete pipeline playbook covering every stage, rollback procedures, secrets management, and on-call responsibilities |
|
||||
| 52 | **SLO & Error Budget** | `skills/slo-error-budget/` | SLI definitions, SLO targets, error budget calculation, burn rate alerts, and error budget policy |
|
||||
| 53 | **Developer Onboarding Doc** | `skills/developer-onboarding-doc/` | Everything a new engineer needs in their first week — architecture, local setup, testing, deployment, and key contacts |
|
||||
| 54 | **On-Call Runbook** | `skills/oncall-runbook/` | Per-alert response procedures, escalation matrix, diagnostic cheat sheet, and handoff template |
|
||||
| 55 | **Security Threat Model** 🆕 | `skills/security-threat-model/` | STRIDE-based threat model with asset register, trust boundaries, per-component threat enumeration, risk scores, and mitigations |
|
||||
| 56 | **Performance Budget** 🆕 | `skills/performance-budget/` | Performance budgets for Core Web Vitals and backend latency SLOs with CI enforcement and breach response policy |
|
||||
| 57 | **Database Schema Design** 🆕 | `skills/database-schema-design/` | Database schema documentation with ER diagram, DDL definitions, index strategy, and access pattern analysis |
|
||||
| 58 | **Database Migration Plan** 🆕 | `skills/database-migration-plan/` | Safe zero-downtime migration plan using expand-contract pattern with per-step rollback and data validation queries |
|
||||
| 59 | **Technical Debt Register** 🆕 | `skills/technical-debt-register/` | Debt inventory with business impact scoring, effort estimates, priority matrix, and quarterly resolution roadmap |
|
||||
| 60 | **RFC Writer** 🆕 | `skills/rfc-writer/` | Engineering Request for Comments covering problem, proposed solution, alternatives-with-rejection-reasons, and rollout plan |
|
||||
| 61 | **Capacity Planning** 🆕 | `skills/capacity-planning/` | Traffic forecasts, resource requirements per tier, scaling strategy, cost projections, and infrastructure action roadmap |
|
||||
| 62 | **Load Testing Plan** 🆕 | `skills/load-testing-plan/` | Load test plan with scenario definitions (baseline/stress/spike/soak), k6/Locust skeleton, thresholds, and CI gates |
|
||||
| 63 | **Disaster Recovery Plan** 🆕 | `skills/disaster-recovery-plan/` | DR plan with RPO/RTO targets, per-scenario runbooks, backup procedures, game day testing, and communication templates |
|
||||
| 64 | **Feature Flag Guide** 🆕 | `skills/feature-flag-guide/` | Feature flag lifecycle playbook — taxonomy, rollout strategy, monitoring requirements, cleanup policy, and governance |
|
||||
| 65 | **Dependency Audit** 🆕 | `skills/dependency-audit/` | Dependency audit for CVE vulnerabilities, license compliance, outdated packages, and 30-day remediation plan |
|
||||
| 66 | **Service Catalog Entry** 🆕 | `skills/service-catalog-entry/` | Microservice catalog entry with ownership, SLAs, API contract, data classification, and operational runbook links |
|
||||
| 67 | **Monitoring Setup Guide** 🆕 | `skills/monitoring-setup-guide/` | Four golden signals applied to a service, alert rules spec, structured log schema, tracing setup, and dashboard layout |
|
||||
| 68 | **Local Dev Setup** 🆕 | `skills/local-dev-setup/` | Local development setup guide — prerequisites, env vars, dependencies, test commands, and 5 common failure fixes |
|
||||
| 69 | **API Versioning Strategy** 🆕 | `skills/api-versioning-strategy/` | API versioning scheme, lifecycle policy, breaking change classification table, deprecation process, and migration guide template |
|
||||
| 70 | **Infra-as-Code Review** 🆕 | `skills/infra-as-code-review/` | IaC review for Terraform/CloudFormation/Pulumi — security, naming, state, cost, and drift risk with severity-classified findings |
|
||||
| 71 | **Engineering Weekly Report** 🆕 | `skills/engineering-weekly-report/` | Weekly engineering status in a consistent format — shipped/in-progress/blocked, metrics, decisions, risks, and next week |
|
||||
| 72 | **Tech Radar** 🆕 | `skills/tech-radar/` | ThoughtWorks-format technology radar with Adopt/Trial/Assess/Hold quadrants, per-blip rationale, and maintenance process |
|
||||
| 73 | **Sprint Velocity Analysis** 🆕 | `skills/sprint-velocity-analysis/` | Velocity trend analysis, completion rate patterns, blocker frequency, improvement recommendations, and capacity forecast |
|
||||
| 74 | **Microservices Decomposition** 🆕 | `skills/microservices-decomposition/` | Domain-driven service boundary design with bounded context map, communication patterns, data ownership, and strangler fig migration plan |
|
||||
| 75 | **Engineering Hiring Rubric** 🆕 | `skills/engineering-hiring-rubric/` | Technical interview rubric with level expectations, coding scorecard, system design guide, behavioural question bank, and debrief template |
|
||||
| 46 | **Code Review Checklist** | `skills/code-review-checklist/` | Tailored PR review checklists by language, type, and risk level |
|
||||
| 47 | **Incident Postmortem** | `skills/incident-postmortem/` | Blameless postmortems with timeline, RCA, impact, and action items |
|
||||
| 48 | **API Docs Writer** | `skills/api-docs-writer/` | Developer-facing API docs: endpoints, parameters, response schemas, code examples |
|
||||
| 49 | **Architecture Decision Record** | `skills/architecture-decision-record/` | ADRs with context, options considered, decision, consequences, and risks |
|
||||
| 50 | **Debugging Log Analyser** | `skills/debugging-log-analyser/` | Parse stack traces and error logs into a structured root cause diagnosis with a specific fix |
|
||||
| 51 | **PR Description Writer** | `skills/pr-description-writer/` | Write reviewer-friendly PR descriptions from a diff, commit list, or change summary |
|
||||
| 52 | **System Design Interview** | `skills/system-design-interview/` | Structure complete system design answers with capacity estimates, component deep-dives, and trade-offs |
|
||||
| 53 | **Changelog Generator** | `skills/changelog-generator/` | Convert git commits into a polished, user-facing changelog following Keep a Changelog format |
|
||||
| 54 | **Test Strategy Doc** | `skills/test-strategy-doc/` | Write a complete test strategy with risk assessment, test types, coverage targets, and P0/P1 test cases |
|
||||
| 55 | **Runbook Writer** | `skills/runbook-writer/` | Write operational runbooks for deployments, incidents, and maintenance with exact commands and rollback steps |
|
||||
| 56 | **CI/CD Playbook** | `skills/cicd-playbook/` | Complete pipeline playbook covering every stage, rollback procedures, secrets management, and on-call responsibilities |
|
||||
| 57 | **SLO & Error Budget** | `skills/slo-error-budget/` | SLI definitions, SLO targets, error budget calculation, burn rate alerts, and error budget policy |
|
||||
| 58 | **Developer Onboarding Doc** | `skills/developer-onboarding-doc/` | Everything a new engineer needs in their first week — architecture, local setup, testing, deployment, and key contacts |
|
||||
| 59 | **On-Call Runbook** | `skills/oncall-runbook/` | Per-alert response procedures, escalation matrix, diagnostic cheat sheet, and handoff template |
|
||||
| 60 | **Security Threat Model** 🆕 | `skills/security-threat-model/` | STRIDE-based threat model with asset register, trust boundaries, per-component threat enumeration, risk scores, and mitigations |
|
||||
| 61 | **Performance Budget** 🆕 | `skills/performance-budget/` | Performance budgets for Core Web Vitals and backend latency SLOs with CI enforcement and breach response policy |
|
||||
| 62 | **Database Schema Design** 🆕 | `skills/database-schema-design/` | Database schema documentation with ER diagram, DDL definitions, index strategy, and access pattern analysis |
|
||||
| 63 | **Database Migration Plan** 🆕 | `skills/database-migration-plan/` | Safe zero-downtime migration plan using expand-contract pattern with per-step rollback and data validation queries |
|
||||
| 64 | **Technical Debt Register** 🆕 | `skills/technical-debt-register/` | Debt inventory with business impact scoring, effort estimates, priority matrix, and quarterly resolution roadmap |
|
||||
| 65 | **RFC Writer** 🆕 | `skills/rfc-writer/` | Engineering Request for Comments covering problem, proposed solution, alternatives-with-rejection-reasons, and rollout plan |
|
||||
| 66 | **Capacity Planning** 🆕 | `skills/capacity-planning/` | Traffic forecasts, resource requirements per tier, scaling strategy, cost projections, and infrastructure action roadmap |
|
||||
| 67 | **Load Testing Plan** 🆕 | `skills/load-testing-plan/` | Load test plan with scenario definitions (baseline/stress/spike/soak), k6/Locust skeleton, thresholds, and CI gates |
|
||||
| 68 | **Disaster Recovery Plan** 🆕 | `skills/disaster-recovery-plan/` | DR plan with RPO/RTO targets, per-scenario runbooks, backup procedures, game day testing, and communication templates |
|
||||
| 69 | **Feature Flag Guide** 🆕 | `skills/feature-flag-guide/` | Feature flag lifecycle playbook — taxonomy, rollout strategy, monitoring requirements, cleanup policy, and governance |
|
||||
| 70 | **Dependency Audit** 🆕 | `skills/dependency-audit/` | Dependency audit for CVE vulnerabilities, license compliance, outdated packages, and 30-day remediation plan |
|
||||
| 71 | **Service Catalog Entry** 🆕 | `skills/service-catalog-entry/` | Microservice catalog entry with ownership, SLAs, API contract, data classification, and operational runbook links |
|
||||
| 72 | **Monitoring Setup Guide** 🆕 | `skills/monitoring-setup-guide/` | Four golden signals applied to a service, alert rules spec, structured log schema, tracing setup, and dashboard layout |
|
||||
| 73 | **Local Dev Setup** 🆕 | `skills/local-dev-setup/` | Local development setup guide — prerequisites, env vars, dependencies, test commands, and 5 common failure fixes |
|
||||
| 74 | **API Versioning Strategy** 🆕 | `skills/api-versioning-strategy/` | API versioning scheme, lifecycle policy, breaking change classification table, deprecation process, and migration guide template |
|
||||
| 75 | **Infra-as-Code Review** 🆕 | `skills/infra-as-code-review/` | IaC review for Terraform/CloudFormation/Pulumi — security, naming, state, cost, and drift risk with severity-classified findings |
|
||||
| 76 | **Engineering Weekly Report** 🆕 | `skills/engineering-weekly-report/` | Weekly engineering status in a consistent format — shipped/in-progress/blocked, metrics, decisions, risks, and next week |
|
||||
| 77 | **Tech Radar** 🆕 | `skills/tech-radar/` | ThoughtWorks-format technology radar with Adopt/Trial/Assess/Hold quadrants, per-blip rationale, and maintenance process |
|
||||
| 78 | **Sprint Velocity Analysis** 🆕 | `skills/sprint-velocity-analysis/` | Velocity trend analysis, completion rate patterns, blocker frequency, improvement recommendations, and capacity forecast |
|
||||
| 79 | **Microservices Decomposition** 🆕 | `skills/microservices-decomposition/` | Domain-driven service boundary design with bounded context map, communication patterns, data ownership, and strangler fig migration plan |
|
||||
| 80 | **Engineering Hiring Rubric** 🆕 | `skills/engineering-hiring-rubric/` | Technical interview rubric with level expectations, coding scorecard, system design guide, behavioural question bank, and debrief template |
|
||||
| 166 | **Context Mode** 🆕 | `skills/context-mode/` | Filters command output noise and maintains a session log so Claude resumes exactly where it left off after a context reset |
|
||||
| 167 | **Claude Superpowers** 🆕 | `skills/claude-superpowers/` | Forces Claude Code to plan first, work in isolation, write tests before code, and double-review its own output — consistently better first passes |
|
||||
|
||||
---
|
||||
|
||||
### 🤝 Customer Success (Skills 76–79)
|
||||
### 🤝 Customer Success (Skills 76–81)
|
||||
**Bundle:** `pm-cs`
|
||||
|
||||
> 250 ⭐ milestone unlocked. Install:
|
||||
> Install:
|
||||
|
||||
claude plugin install pm-cs@pm-claude-skills
|
||||
|
||||
@@ -324,179 +419,232 @@ claude plugin install pm-cs@pm-claude-skills
|
||||
| 77 | **QBR Deck** | `skills/qbr-deck/` | Slide-by-slide quarterly business review with talking points, value narrative, and mutual commitments |
|
||||
| 78 | **Escalation Brief** | `skills/cs-escalation-brief/` | Structured brief for at-risk accounts — root cause, business impact, resolution plan, and decision required |
|
||||
| 79 | **Churn Analysis** | `skills/churn-analysis/` | Churn breakdown by category and segment, early warning signals, and prioritised interventions |
|
||||
| 80 | **Renewal Playbook** 🆕 | `skills/renewal-playbook/` | Renewal brief with health snapshot, value story, commercial scenarios, objection responses, and 16-week execution timeline |
|
||||
| 81 | **Customer Success Plan** 🆕 | `skills/customer-success-plan/` | Joint success plan with business goals, success metrics, milestone roadmap, mutual commitments, and escalation path |
|
||||
|
||||
---
|
||||
|
||||
### 📊 Data & Analytics (Skills 80–83)
|
||||
### 📊 Data & Analytics (Skills 82–87)
|
||||
**Bundle:** `pm-data`
|
||||
|
||||
| # | Skill | Folder | What It Does |
|
||||
|---|---|---|---|
|
||||
| 80 | **Metrics Framework** | `skills/metrics-framework/` | North Star + metric tree, dashboard tiers, counter-metrics |
|
||||
| 81 | **SQL Query Explainer** | `skills/sql-query-explainer/` | Explain, optimise, write, and document SQL in plain English |
|
||||
| 82 | **Dashboard Brief** | `skills/dashboard-brief/` | Complete dashboard spec: KPIs, charts, filters, layout, data requirements |
|
||||
| 83 | **Chart Data Extractor** | `skills/chart-data-extractor/` | Extract pixel-level data from chart images into structured data tables |
|
||||
| 82 | **Metrics Framework** | `skills/metrics-framework/` | North Star + metric tree, dashboard tiers, counter-metrics |
|
||||
| 83 | **SQL Query Explainer** | `skills/sql-query-explainer/` | Explain, optimise, write, and document SQL in plain English |
|
||||
| 84 | **Dashboard Brief** | `skills/dashboard-brief/` | Complete dashboard spec: KPIs, charts, filters, layout, data requirements |
|
||||
| 85 | **Chart Data Extractor** | `skills/chart-data-extractor/` | Extract pixel-level data from chart images into structured data tables |
|
||||
| 86 | **Cohort Analysis** 🆕 | `skills/cohort-analysis/` | Retention curves, LTV projection, behavioural segmentation, churn leading indicators, and SQL reference queries |
|
||||
| 87 | **Data Pipeline Spec** 🆕 | `skills/data-pipeline-spec/` | ETL/ELT pipeline design with sources, transforms, SLAs, DQ rules, error handling, and compliance notes |
|
||||
|
||||
---
|
||||
|
||||
### 🧑💼 Leadership & People (Skills 84–86)
|
||||
### 🧑💼 Leadership & People (Skills 88–92)
|
||||
**Bundle:** `pm-people`
|
||||
|
||||
| # | Skill | Folder | What It Does |
|
||||
|---|---|---|---|
|
||||
| 84 | **Performance Review** | `skills/performance-review/` | Structured reviews from bullet-point notes — self, manager, peer, and upward |
|
||||
| 85 | **Hiring Rubric** | `skills/hiring-rubric/` | Interview scorecards with competencies, behavioural questions, and panel guide |
|
||||
| 86 | **Team Offsite Planner** | `skills/team-offsite-planner/` | Full offsite agenda, session facilitation notes, and logistics checklist |
|
||||
| 88 | **Performance Review** | `skills/performance-review/` | Structured reviews from bullet-point notes — self, manager, peer, and upward |
|
||||
| 89 | **Hiring Rubric** | `skills/hiring-rubric/` | Interview scorecards with competencies, behavioural questions, and panel guide |
|
||||
| 90 | **Team Offsite Planner** | `skills/team-offsite-planner/` | Full offsite agenda, session facilitation notes, and logistics checklist |
|
||||
| 91 | **360-Degree Feedback Template** 🆕 | `skills/360-feedback-template/` | Survey instrument with GWT-anchored questions, or a structured narrative report with strengths and development themes |
|
||||
| 92 | **Team Health Check** 🆕 | `skills/team-health-check/` | Spotify-model assessment across 7 dimensions — delivery, safety, morale, speed, purpose, and collaboration |
|
||||
|
||||
---
|
||||
|
||||
### 🎨 Design & UX (Skills 87–89)
|
||||
### 🎨 Design & UX (Skills 93–96)
|
||||
**Bundle:** `pm-design`
|
||||
|
||||
| # | Skill | Folder | What It Does |
|
||||
|---|---|---|---|
|
||||
| 87 | **UX Research Plan** | `skills/ux-research-plan/` | Research plans with screener, discussion guide, and synthesis framework |
|
||||
| 88 | **Design Critique** | `skills/design-critique/` | Structured feedback using JTBD, Gestalt principles, and Nielsen's heuristics |
|
||||
| 89 | **Accessibility Audit** | `skills/accessibility-audit/` | WCAG 2.2 audit with prioritised remediation and quick wins |
|
||||
| 93 | **UX Research Plan** | `skills/ux-research-plan/` | Research plans with screener, discussion guide, and synthesis framework |
|
||||
| 94 | **Design Critique** | `skills/design-critique/` | Structured feedback using JTBD, Gestalt principles, and Nielsen's heuristics |
|
||||
| 95 | **Accessibility Audit** | `skills/accessibility-audit/` | WCAG 2.2 audit with prioritised remediation and quick wins |
|
||||
| 96 | **Design System Audit** 🆕 | `skills/design-system-audit/` | Audit component coverage, token consistency, documentation quality, WCAG compliance, adoption barriers, and remediation roadmap |
|
||||
|
||||
---
|
||||
|
||||
### 🏢 Business & Strategy (Skills 90–92)
|
||||
### 🏢 Business & Strategy (Skills 97–99)
|
||||
**Bundle:** `pm-business`
|
||||
|
||||
| # | Skill | Folder | What It Does |
|
||||
|---|---|---|---|
|
||||
| 90 | **Investor Update** | `skills/investor-update/` | Monthly/quarterly investor updates: metrics, highlights, challenges, and asks |
|
||||
| 91 | **Board Deck Narrative** | `skills/board-deck-narrative/` | Slide-by-slide board presentation structure with narrative beats and talking points |
|
||||
| 92 | **Job Application** | `skills/job-application/` | Tailored CV summary, ATS keyword optimisation, and cover letter for any JD |
|
||||
| 97 | **Investor Update** | `skills/investor-update/` | Monthly/quarterly investor updates: metrics, highlights, challenges, and asks |
|
||||
| 98 | **Board Deck Narrative** | `skills/board-deck-narrative/` | Slide-by-slide board presentation structure with narrative beats and talking points |
|
||||
| 99 | **Job Application** | `skills/job-application/` | Tailored CV summary, ATS keyword optimisation, and cover letter for any JD |
|
||||
|
||||
---
|
||||
|
||||
### ⚖️ Legal (Skills 93–96)
|
||||
### ⚖️ Legal (Skills 100–103)
|
||||
**Bundle:** `pm-legal`
|
||||
|
||||
> ⚠️ All legal skills include a disclaimer. Not a substitute for qualified legal advice.
|
||||
|
||||
| # | Skill | Folder | What It Does |
|
||||
|---|---|---|---|
|
||||
| 93 | **Contract Review** | `skills/contract-review/` | Structured review with key terms, flagged clauses, risk rating, and plain English summary |
|
||||
| 94 | **NDA Analyser** | `skills/nda-analyser/` | Clause-by-clause NDA analysis with risk flags and negotiation checklist |
|
||||
| 95 | **Legal Brief** | `skills/legal-brief/` | Legal memos and argument outlines in IRAC format (Issue, Rule, Application, Conclusion) |
|
||||
| 96 | **Compliance Checklist** | `skills/compliance-checklist/` | GDPR, SOC 2, ISO 27001, FCA, HIPAA compliance checklists with prioritised gap analysis |
|
||||
| 100 | **Contract Review** | `skills/contract-review/` | Structured review with key terms, flagged clauses, risk rating, and plain English summary |
|
||||
| 101 | **NDA Analyser** | `skills/nda-analyser/` | Clause-by-clause NDA analysis with risk flags and negotiation checklist |
|
||||
| 102 | **Legal Brief** | `skills/legal-brief/` | Legal memos and argument outlines in IRAC format (Issue, Rule, Application, Conclusion) |
|
||||
| 103 | **Compliance Checklist** | `skills/compliance-checklist/` | GDPR, SOC 2, ISO 27001, FCA, HIPAA compliance checklists with prioritised gap analysis |
|
||||
|
||||
---
|
||||
|
||||
### 💰 Finance (Skills 97–101)
|
||||
### 💰 Finance (Skills 104–108)
|
||||
**Bundle:** `pm-finance`
|
||||
|
||||
| # | Skill | Folder | What It Does |
|
||||
|---|---|---|---|
|
||||
| 97 | **Financial Model Narrative** | `skills/financial-model-narrative/` | Turns P&L and model outputs into board-ready written narratives |
|
||||
| 98 | **Budget Variance Analysis** | `skills/budget-variance-analysis/` | Variance table with root cause commentary and management summary |
|
||||
| 99 | **Investor Pitch Deck** | `skills/investor-pitch-deck/` | Slide-by-slide pitch deck structure with what each slide must prove |
|
||||
| 100 | **Financial Due Diligence** | `skills/financial-due-diligence/` | DD document request list, analytical questions, and red flags checklist |
|
||||
| 101 | **Tax Planning Checklist** | `skills/tax-planning-checklist/` | Year-end tax planning framework across income, pension, CGT, business reliefs, and ISAs |
|
||||
| 104 | **Financial Model Narrative** | `skills/financial-model-narrative/` | Turns P&L and model outputs into board-ready written narratives |
|
||||
| 105 | **Budget Variance Analysis** | `skills/budget-variance-analysis/` | Variance table with root cause commentary and management summary |
|
||||
| 106 | **Investor Pitch Deck** | `skills/investor-pitch-deck/` | Slide-by-slide pitch deck structure with what each slide must prove |
|
||||
| 107 | **Financial Due Diligence** | `skills/financial-due-diligence/` | DD document request list, analytical questions, and red flags checklist |
|
||||
| 108 | **Tax Planning Checklist** | `skills/tax-planning-checklist/` | Year-end tax planning framework across income, pension, CGT, business reliefs, and ISAs |
|
||||
|
||||
---
|
||||
|
||||
### 👥 HR (Skills 102–106)
|
||||
### 👥 HR (Skills 109–113)
|
||||
**Bundle:** `pm-hr`
|
||||
|
||||
| # | Skill | Folder | What It Does |
|
||||
|---|---|---|---|
|
||||
| 102 | **Job Description Writer** | `skills/job-description-writer/` | Inclusive, structured JDs with built-in language review and salary range nudge |
|
||||
| 103 | **Onboarding Plan** | `skills/onboarding-plan/` | 30/60/90-day plans with week-by-week structure, milestones, and manager checklist |
|
||||
| 104 | **Employee Engagement Survey** | `skills/employee-engagement-survey/` | Survey design + results analysis mode with eNPS and action planning template |
|
||||
| 105 | **Redundancy Consultation** | `skills/redundancy-consultation/` | Process timeline, at-risk letter, consultation script, and confirmation letter — UK law |
|
||||
| 106 | **Change Management Plan** | `skills/change-management-plan/` | Full change plan covering stakeholder analysis, communication strategy, training, and adoption metrics |
|
||||
| 109 | **Job Description Writer** | `skills/job-description-writer/` | Inclusive, structured JDs with built-in language review and salary range nudge |
|
||||
| 110 | **Onboarding Plan** | `skills/onboarding-plan/` | 30/60/90-day plans with week-by-week structure, milestones, and manager checklist |
|
||||
| 111 | **Employee Engagement Survey** | `skills/employee-engagement-survey/` | Survey design + results analysis mode with eNPS and action planning template |
|
||||
| 112 | **Redundancy Consultation** | `skills/redundancy-consultation/` | Process timeline, at-risk letter, consultation script, and confirmation letter — UK law |
|
||||
| 113 | **Change Management Plan** | `skills/change-management-plan/` | Full change plan covering stakeholder analysis, communication strategy, training, and adoption metrics |
|
||||
|
||||
---
|
||||
|
||||
### 🤝 Sales (Skills 107–111)
|
||||
### 🤝 Sales (Skills 114–119)
|
||||
**Bundle:** `pm-sales`
|
||||
|
||||
| # | Skill | Folder | What It Does |
|
||||
|---|---|---|---|
|
||||
| 107 | **Sales Battlecard** | `skills/sales-battlecard/` | One-page competitive battlecard with objection responses and landmine questions |
|
||||
| 108 | **Discovery Call Prep** | `skills/discovery-call-prep/` | Call brief with research summary, hypothesis, structured questions, and success criteria |
|
||||
| 109 | **Proposal Writer** | `skills/proposal-writer/` | Commercial proposals structured around the prospect's problem, not the product |
|
||||
| 110 | **Account Plan** | `skills/account-plan/` | Strategic account plan with relationship map, whitespace analysis, risks, and 90-day actions |
|
||||
| 111 | **Sales Forecasting Model** | `skills/sales-forecasting-model/` | Pipeline-based forecast with stage model, scenario analysis, assumption log, and activity sanity check |
|
||||
| 114 | **Sales Battlecard** | `skills/sales-battlecard/` | One-page competitive battlecard with objection responses and landmine questions |
|
||||
| 115 | **Discovery Call Prep** | `skills/discovery-call-prep/` | Call brief with research summary, hypothesis, structured questions, and success criteria |
|
||||
| 116 | **Proposal Writer** | `skills/proposal-writer/` | Commercial proposals structured around the prospect's problem, not the product |
|
||||
| 117 | **Account Plan** | `skills/account-plan/` | Strategic account plan with relationship map, whitespace analysis, risks, and 90-day actions |
|
||||
| 118 | **Sales Forecasting Model** | `skills/sales-forecasting-model/` | Pipeline-based forecast with stage model, scenario analysis, assumption log, and activity sanity check |
|
||||
| 119 | **Partnership Proposal** 🆕 | `skills/partnership-proposal/` | B2B partnership proposal with mutual value, commercial model, joint GTM plan, governance, and risk register |
|
||||
|
||||
---
|
||||
|
||||
### ⚙️ Operations (Skills 112–116)
|
||||
### ⚙️ Operations (Skills 120–126, 164–165)
|
||||
**Bundle:** `pm-operations`
|
||||
|
||||
| # | Skill | Folder | What It Does |
|
||||
|---|---|---|---|
|
||||
| 112 | **Process Documentation** | `skills/process-documentation/` | Clear process docs with steps, roles, edge cases — followable by a new starter |
|
||||
| 113 | **SOP Writer** | `skills/sop-writer/` | Formal, audit-ready SOPs with version control, quality checks, and non-conformance process |
|
||||
| 114 | **Vendor Evaluation** | `skills/vendor-evaluation/` | Weighted vendor scorecard, RFP questions, reference check template, and recommendation |
|
||||
| 115 | **Project Status Report** | `skills/project-status-report/` | RAG status reports with milestone progress, issues, risks, and decisions required |
|
||||
| 116 | **Workshop Facilitation Guide** | `skills/workshop-facilitation-guide/` | Complete facilitation guides with activity instructions, decision protocols, and facilitator moves |
|
||||
| 120 | **Process Documentation** | `skills/process-documentation/` | Clear process docs with steps, roles, edge cases — followable by a new starter |
|
||||
| 121 | **SOP Writer** | `skills/sop-writer/` | Formal, audit-ready SOPs with version control, quality checks, and non-conformance process |
|
||||
| 122 | **Vendor Evaluation** | `skills/vendor-evaluation/` | Weighted vendor scorecard, RFP questions, reference check template, and recommendation |
|
||||
| 123 | **Project Status Report** | `skills/project-status-report/` | RAG status reports with milestone progress, issues, risks, and decisions required |
|
||||
| 124 | **Workshop Facilitation Guide** | `skills/workshop-facilitation-guide/` | Complete facilitation guides with activity instructions, decision protocols, and facilitator moves |
|
||||
| 125 | **Risk Register** 🆕 | `skills/risk-register/` | L×I risk scoring, RAG heat map, top-risk executive summary, and per-risk mitigation and contingency plans |
|
||||
| 126 | **RACI Matrix** 🆕 | `skills/raci-matrix/` | RACI with role definitions, decision map, anti-pattern guide, and a communication template for all teams |
|
||||
| 164 | **Email Triage** 🆕 | `skills/email-triage/` | Reads Gmail for a configurable window and surfaces only what needs action — priority-ranked with urgency ratings and reply starters |
|
||||
| 165 | **Morning Intelligence** 🆕 | `skills/morning-intelligence/` | 15-question interview that writes a personalised master prompt for your daily news brief, ready for Cowork Scheduled Tasks or Claude Code Routines |
|
||||
|
||||
---
|
||||
|
||||
### 🏥 Research & Healthcare (Skills 117–120)
|
||||
### 🏥 Research & Healthcare (Skills 127–130)
|
||||
**Bundle:** `pm-research`
|
||||
|
||||
> ⚠️ Healthcare skills are for documentation and educational purposes only. All clinical content must be reviewed by a qualified professional.
|
||||
|
||||
| # | Skill | Folder | What It Does |
|
||||
|---|---|---|---|
|
||||
| 117 | **Clinical Case Summary** | `skills/clinical-case-summary/` | SBAR handovers, SOAP notes, and case reports for educational and documentation use |
|
||||
| 118 | **Research Protocol** | `skills/research-protocol/` | Complete study protocols with objectives, methodology, ethics, and analysis plan |
|
||||
| 119 | **Patient Communication** | `skills/patient-communication/` | Plain English patient letters, leaflets, and results communications at Grade 6 reading level |
|
||||
| 120 | **Literature Review** | `skills/literature-review/` | Thematically organised literature reviews with synthesis, critical analysis, and gap identification |
|
||||
| 127 | **Clinical Case Summary** | `skills/clinical-case-summary/` | SBAR handovers, SOAP notes, and case reports for educational and documentation use |
|
||||
| 128 | **Research Protocol** | `skills/research-protocol/` | Complete study protocols with objectives, methodology, ethics, and analysis plan |
|
||||
| 129 | **Patient Communication** | `skills/patient-communication/` | Plain English patient letters, leaflets, and results communications at Grade 6 reading level |
|
||||
| 130 | **Literature Review** | `skills/literature-review/` | Thematically organised literature reviews with synthesis, critical analysis, and gap identification |
|
||||
|
||||
---
|
||||
|
||||
### 🌐 Cross-Profession (Skills 121–124)
|
||||
### 🌐 Cross-Profession (Skills 131–134, 161–163)
|
||||
**Bundle:** `pm-cross`
|
||||
|
||||
| # | Skill | Folder | What It Does |
|
||||
|---|---|---|---|
|
||||
| 121 | **Press Release** | `skills/press-release/` | Journalist-ready press releases with headline rules, boilerplate, and journalist test |
|
||||
| 122 | **Grant Proposal** | `skills/grant-proposal/` | Complete grant applications aligned to funder priorities with budget narrative |
|
||||
| 123 | **Executive Summary** | `skills/executive-summary/` | Decision-ready executive summaries with bottom line upfront, adapted for any audience |
|
||||
| 124 | **Teaching Lesson Plan** | `skills/teaching-lesson-plan/` | Complete lesson plans for any subject, audience, or setting — with objectives, activities, and formative assessment |
|
||||
| 131 | **Press Release** | `skills/press-release/` | Journalist-ready press releases with headline rules, boilerplate, and journalist test |
|
||||
| 132 | **Grant Proposal** | `skills/grant-proposal/` | Complete grant applications aligned to funder priorities with budget narrative |
|
||||
| 133 | **Executive Summary** | `skills/executive-summary/` | Decision-ready executive summaries with bottom line upfront, adapted for any audience |
|
||||
| 134 | **Teaching Lesson Plan** | `skills/teaching-lesson-plan/` | Complete lesson plans for any subject, audience, or setting — with objectives, activities, and formative assessment |
|
||||
| 161 | **Sycophancy Challenger** 🆕 | `skills/sycophancy-challenger/` | Argues the strongest case *against* your idea first — a genuine thinking partner that holds its position under pressure |
|
||||
| 162 | **Last 30 Days Research** 🆕 | `skills/last-30-days-research/` | Searches Reddit, X, and the web for the last 30 days on any topic and returns consensus, disagreements, pain points, and signal confidence |
|
||||
| 163 | **NotebookLM Connector** 🆕 | `skills/notebooklm-connector/` | Automates NotebookLM via Chrome extension — create notebooks, add sources, generate mindmaps and audio overviews from Claude Code |
|
||||
|
||||
---
|
||||
|
||||
### 🖼️ Figma (Skills 125–134)
|
||||
### 🖼️ Figma (Skills 135–144)
|
||||
**Bundle:** `pm-figma`
|
||||
|
||||
| # | Skill | Folder | What It Does |
|
||||
|---|---|---|---|
|
||||
| 125 | **Figma Component Audit** | `skills/figma-component-audit/` | Audit component library for naming issues, coverage gaps, and variant completeness |
|
||||
| 126 | **Figma Design Brief** | `skills/figma-design-brief/` | Convert PRDs and feature requests into structured Figma design briefs |
|
||||
| 127 | **Figma Annotation Guide** | `skills/figma-annotation-guide/` | Generate complete developer handoff annotations covering all states and edge cases |
|
||||
| 128 | **Figma Design Review** | `skills/figma-design-review/` | PM design review against requirements with explicit approval status |
|
||||
| 129 | **Figma User Flow Planner** | `skills/figma-user-flow-planner/` | Map all screens, states, and decision points before opening Figma |
|
||||
| 130 | **Figma Variant Matrix** | `skills/figma-variant-matrix/` | Define all component variants, properties, and states before building |
|
||||
| 131 | **Figma Spacing System** | `skills/figma-spacing-system/` | Design a complete spacing scale, grid, and token system |
|
||||
| 132 | **Figma Prototype Plan** | `skills/figma-prototype-plan/` | Plan prototype scope, interactions, and test task scripts for user testing |
|
||||
| 133 | **Figma Design QA** | `skills/figma-design-qa/` | Pre-handoff QA checklist covering file hygiene, states, accessibility, and handoff readiness |
|
||||
| 134 | **Figma Design Critique (PM)** | `skills/figma-design-critique-pm/` | PM-perspective design critique focused on product outcomes, not aesthetics |
|
||||
| 135 | **Figma Component Audit** | `skills/figma-component-audit/` | Audit component library for naming issues, coverage gaps, and variant completeness |
|
||||
| 136 | **Figma Design Brief** | `skills/figma-design-brief/` | Convert PRDs and feature requests into structured Figma design briefs |
|
||||
| 137 | **Figma Annotation Guide** | `skills/figma-annotation-guide/` | Generate complete developer handoff annotations covering all states and edge cases |
|
||||
| 138 | **Figma Design Review** | `skills/figma-design-review/` | PM design review against requirements with explicit approval status |
|
||||
| 139 | **Figma User Flow Planner** | `skills/figma-user-flow-planner/` | Map all screens, states, and decision points before opening Figma |
|
||||
| 140 | **Figma Variant Matrix** | `skills/figma-variant-matrix/` | Define all component variants, properties, and states before building |
|
||||
| 141 | **Figma Spacing System** | `skills/figma-spacing-system/` | Design a complete spacing scale, grid, and token system |
|
||||
| 142 | **Figma Prototype Plan** | `skills/figma-prototype-plan/` | Plan prototype scope, interactions, and test task scripts for user testing |
|
||||
| 143 | **Figma Design QA** | `skills/figma-design-qa/` | Pre-handoff QA checklist covering file hygiene, states, accessibility, and handoff readiness |
|
||||
| 144 | **Figma Design Critique (PM)** | `skills/figma-design-critique-pm/` | PM-perspective design critique focused on product outcomes, not aesthetics |
|
||||
|
||||
claude plugin install pm-figma@pm-claude-skills
|
||||
|
||||
|
||||
---
|
||||
|
||||
### 📅 PM Rituals (Skill 135)
|
||||
### 📅 PM Rituals (Skills 145–150)
|
||||
**Bundle:** `pm-rituals`
|
||||
|
||||
| # | Skill | Folder | What It Does |
|
||||
|---|---|---|---|
|
||||
| 135 | **PM Weekly Review** | `skills/pm-weekly-review/` | Weekly PM review and planning ritual — metrics, shipping progress, blockers, and next week's priorities |
|
||||
| 145 | **PM Weekly Review** | `skills/pm-weekly-review/` | Weekly PM review and planning ritual — metrics, shipping progress, blockers, and next week's priorities |
|
||||
|
||||
---
|
||||
|
||||
### 📱 Social Media (Skills 151–155)
|
||||
**Bundle:** `pm-social`
|
||||
|
||||
> Install:
|
||||
|
||||
```
|
||||
claude plugin install pm-social@pm-claude-skills
|
||||
```
|
||||
|
||||
| # | Skill | Folder | What It Does |
|
||||
|---|---|---|---|
|
||||
| 151 | **Social Media Audit** 🆕 | `skills/social-media-audit/` | Scored audit across all platforms — profile completeness, content performance, competitive benchmarking, and a prioritised action plan with 30-day quick wins |
|
||||
| 152 | **Influencer Brief** 🆕 | `skills/influencer-brief/` | Complete creator partnership brief with deliverables spec, creative guidelines, key messages, approval workflow, commercial terms, and campaign measurement |
|
||||
| 153 | **Community Management Playbook** 🆕 | `skills/community-management-playbook/` | Response frameworks, moderation rules, escalation tiers, DM templates, tone-of-voice guidance, platform-specific notes, and community health metrics |
|
||||
| 154 | **Social Ad Campaign** 🆕 | `skills/social-ad-campaign/` | Full-funnel paid social plan with audience targeting, ad set architecture, copy for every format (video, static, carousel, lead gen), budget allocation, bidding strategy, and A/B testing plan |
|
||||
| 155 | **Viral Content Framework** 🆕 | `skills/viral-content-framework/` | Psychology of sharing, 6 proven hook formulas, 5 content structures, platform-specific playbooks for LinkedIn/TikTok/Instagram/X/YouTube, and a repeatable content testing system |
|
||||
|
||||
---
|
||||
|
||||
### ✍️ Writers & Content Creators (Skills 156–160)
|
||||
**Bundle:** `pm-writers`
|
||||
|
||||
> Install:
|
||||
|
||||
```
|
||||
claude plugin install pm-writers@pm-claude-skills
|
||||
```
|
||||
|
||||
| # | Skill | Folder | What It Does |
|
||||
|---|---|---|---|
|
||||
| 156 | **Instagram Post Downloader** 🆕 | `skills/instagram-post-downloader/` | Downloads Instagram images and full carousels as high-res files; stitches carousel slides into a single PDF. Requires `*.cdninstagram.com` on domain allowlist |
|
||||
| 157 | **AEO Optimizer** 🆕 | `skills/aeo-optimizer/` | Restructures any article for AI citation — rewrites H2s as questions, adds 50–80 word answer capsules under each, audits paragraph length, and flags trust signals |
|
||||
| 158 | **Thumbnail Creator** 🆕 | `skills/thumbnail-creator/` | Generates brand-aligned thumbnail candidates via Gemini API; Claude evaluates results via computer vision and returns ranked candidates with rationale |
|
||||
| 159 | **Substack Notes Scraper** 🆕 | `skills/substack-notes-scraper/` | Scrapes Substack Notes and exports likes, comments, and restacks to a formatted .xlsx with frozen headers, filters, and top-performer highlighting |
|
||||
| 160 | **Notes Humanizer** 🆕 | `skills/notes-humanizer/` | Strips AI writing patterns (em dashes, filler phrases, uniform rhythm) across 3 phases: audit, strip, inject — returns side-by-side comparison and clean final text |
|
||||
|
||||
---
|
||||
|
||||
## ❤️ Sponsor This Work
|
||||
|
||||
Building and maintaining 135 skills across 23 bundles takes real time — testing skills against new model releases, building new ones from community requests, writing the article series, and keeping documentation current.
|
||||
Building and maintaining 167 skills across 26 bundles takes real time — testing skills against new model releases, building new ones from community requests, writing the article series, and keeping documentation current.
|
||||
|
||||
If these skills save you time at work, consider sponsoring:
|
||||
|
||||
@@ -587,7 +735,7 @@ claude plugin install pm-gtm@pm-claude-skills
|
||||
|
||||
claude plugin install pm-engineering@pm-claude-skills # Engineering (35 skills)
|
||||
|
||||
claude plugin install pm-cs@pm-claude-skills # Customer Success (4 skills) 🆕
|
||||
claude plugin install pm-cs@pm-claude-skills # Customer Success
|
||||
|
||||
claude plugin install pm-data@pm-claude-skills
|
||||
|
||||
@@ -613,6 +761,10 @@ claude plugin install pm-cross@pm-claude-skills
|
||||
|
||||
claude plugin install pm-figma@pm-claude-skills
|
||||
|
||||
claude plugin install pm-social@pm-claude-skills # Social Media 🆕
|
||||
|
||||
claude plugin install pm-writers@pm-claude-skills # Writers & Content Creators 🆕
|
||||
|
||||
---
|
||||
|
||||
## 🤖 Companion Repository — ChatGPT Custom GPTs
|
||||
@@ -627,7 +779,7 @@ Read the full breakdown: [Part 12 — I Built the Same Skills Library for ChatGP
|
||||
|
||||
## 🛠️ Custom Skills for Your Team
|
||||
|
||||
The 114 skills in this library are built for general professional workflows. But the most powerful version of Claude Skills is one built specifically for *your* team — your templates, your terminology, your processes, your quality standards.
|
||||
The 155 skills in this library are built for general professional workflows. But the most powerful version of Claude Skills is one built specifically for *your* team — your templates, your terminology, your processes, your quality standards.
|
||||
|
||||
**What custom skills look like in practice:**
|
||||
|
||||
|
||||
@@ -0,0 +1,207 @@
|
||||
---
|
||||
name: ai-ethics-review
|
||||
description: "Conduct an ethical review of an AI or ML feature, model, or product. Use when asked to run an AI ethics review, assess AI risks, audit a model for bias, or produce an AI impact assessment. Produces a structured ethics review covering fairness, transparency, privacy, safety, accountability, and societal impact with prioritised mitigations."
|
||||
---
|
||||
|
||||
# AI Ethics Review Skill
|
||||
|
||||
This skill produces a structured ethical review of an AI or machine learning feature, model, or product. Output covers fairness, transparency, privacy, safety, accountability, and societal impact — with risk scoring, prioritised mitigations, and a checklist suitable for governance review or responsible AI documentation.
|
||||
|
||||
> ⚠️ This skill provides a structured framework for identifying and documenting ethical risks. It is not a substitute for legal advice, regulated algorithmic impact assessments, or specialist ethics review required in specific jurisdictions (e.g. EU AI Act, UK AI regulation).
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask the user for these if not provided:
|
||||
- **Feature or model name** and what it does
|
||||
- **Who it affects** — which users or people does the AI interact with, make decisions about, or collect data from?
|
||||
- **What decisions or outputs it produces** — recommendations, predictions, classifications, generation, automation?
|
||||
- **Consequentiality** — how significant are the AI's decisions? (low-stakes suggestions vs decisions that affect employment, credit, health, safety, etc.)
|
||||
- **Data used** — what training data, user data, or third-party data is used?
|
||||
- **Human oversight** — is there a human in the loop, and at what stage?
|
||||
- **Deployment context** — who will use this and how? (internal tool / consumer-facing / automated pipeline)
|
||||
|
||||
## Output Structure
|
||||
|
||||
---
|
||||
|
||||
# AI Ethics Review: [Feature / Model Name]
|
||||
|
||||
**Product / system:** [Name and brief description]
|
||||
**Review type:** [Pre-deployment review / Post-deployment audit / Change review]
|
||||
**Risk tier:** [High / Medium / Low — based on consequentiality, scale, and affected population]
|
||||
**Reviewer:** [Name / Team]
|
||||
**Date:** [Date]
|
||||
**Status:** [Draft / Approved / Requires escalation]
|
||||
|
||||
---
|
||||
|
||||
## 1. Feature Summary
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| **What it does** | [1–2 sentences — plain English description of the AI feature and its purpose] |
|
||||
| **Who uses it** | [End users / internal teams / automated system] |
|
||||
| **Who is affected by its outputs** | [May be different from who uses it — e.g. an AI hiring tool is used by HR but affects candidates] |
|
||||
| **Output type** | [Recommendation / Classification / Prediction / Generation / Automation / Scoring] |
|
||||
| **Scale** | [How many people affected per day/month?] |
|
||||
| **Consequentiality** | [High: affects access to services, employment, credit, health, safety / Medium: influences decisions / Low: suggestions with easy override] |
|
||||
| **Human oversight level** | [Full automation / Human review before action / Human can override after action / Advisory only] |
|
||||
|
||||
---
|
||||
|
||||
## 2. Risk Tier Assessment
|
||||
|
||||
| Factor | Score (1–3) | Rationale |
|
||||
|---|---|---|
|
||||
| **Consequentiality** (impact on individuals) | [1=low, 3=high] | [e.g. 3 — model output influences hiring decisions] |
|
||||
| **Scale** (number of people affected) | [1=few, 3=many] | [e.g. 2 — internal tool used for ~500 candidates/year] |
|
||||
| **Reversibility** (can harm be undone?) | [1=reversible, 3=irreversible] | [e.g. 2 — unfair rejection can be appealed but may not be caught] |
|
||||
| **Vulnerability of affected group** | [1=general population, 3=protected or vulnerable group] | [e.g. 2 — includes protected characteristics in the decision context] |
|
||||
| **Transparency** (do affected people know?) | [1=informed, 3=opaque] | [e.g. 3 — candidates are not told AI is used in screening] |
|
||||
|
||||
**Composite risk tier:** [High (12–15) / Medium (7–11) / Low (3–6)]
|
||||
|
||||
**Risk tier implications:**
|
||||
- **High:** Mandatory senior ethics review, DPA/DPIA required, human-in-loop for all consequential decisions, ongoing monitoring required
|
||||
- **Medium:** Ethics review recommended, document mitigations, quarterly monitoring
|
||||
- **Low:** Standard review, document assumptions, annual review
|
||||
|
||||
---
|
||||
|
||||
## 3. Fairness & Bias
|
||||
|
||||
*Does the AI treat people equitably across groups?*
|
||||
|
||||
**Protected characteristics relevant to this feature:**
|
||||
[List applicable protected characteristics — age, gender, race/ethnicity, disability, religion, national origin, etc.]
|
||||
|
||||
| Risk | Analysis | Mitigation |
|
||||
|---|---|---|
|
||||
| **Training data bias** | [Does the training data reflect historical discrimination? e.g. hiring data that reflects past biases in who was hired] | [Audit training data for demographic representation / use debiasing techniques / document data lineage] |
|
||||
| **Proxy discrimination** | [Could the model use a proxy for a protected characteristic? e.g. using postcode as a proxy for race] | [Identify proxy features / test for disparate impact using adversarial debiasing] |
|
||||
| **Differential performance** | [Does the model perform differently across demographic groups? — e.g. lower accuracy for underrepresented groups] | [Disaggregate performance metrics by group / set minimum performance thresholds per group] |
|
||||
| **Feedback loops** | [Does the model's output reinforce existing disparities? e.g. recommending content that keeps disadvantaged groups in lower-engagement patterns] | [Monitor outcome distributions over time / implement feedback loop detection] |
|
||||
|
||||
**Fairness evaluation method:** [What method will be used to measure fairness — statistical parity / equalised odds / individual fairness? Who is responsible for running it and how often?]
|
||||
|
||||
---
|
||||
|
||||
## 4. Transparency & Explainability
|
||||
|
||||
*Can affected people understand how the AI makes decisions?*
|
||||
|
||||
| Dimension | Current state | Required state | Gap |
|
||||
|---|---|---|---|
|
||||
| **User disclosure** | [Are users told they're interacting with AI?] | [Yes — required for trust and regulation] | [e.g. No disclosure on current UI] |
|
||||
| **Decision explanation** | [Can the system explain why it reached a conclusion?] | [For high-stakes decisions: yes] | [e.g. Black-box model — no feature attribution available] |
|
||||
| **Right to know** | [Can affected people ask how a decision was made?] | [Yes — required under GDPR Art. 22 for automated decisions] | [e.g. No process exists] |
|
||||
| **Confidence calibration** | [Does the model express appropriate uncertainty?] | [Yes — overconfident models cause over-reliance] | [e.g. Model outputs binary label without confidence score] |
|
||||
|
||||
**Explainability approach:** [LIME / SHAP / rule-based surrogate / LLM-generated rationale / none — and why]
|
||||
|
||||
---
|
||||
|
||||
## 5. Privacy & Data
|
||||
|
||||
*Is personal data used responsibly and lawfully?*
|
||||
|
||||
| Risk | Analysis | Mitigation |
|
||||
|---|---|---|
|
||||
| **Data minimisation** | [Does the model use more personal data than necessary?] | [Audit input features — remove any that don't improve performance and involve unnecessary data collection] |
|
||||
| **Data retention** | [How long is personal data retained for training and inference?] | [Define retention policy aligned to GDPR / CCPA / sector requirements] |
|
||||
| **Re-identification risk** | [Could model outputs or training data be used to identify individuals?] | [Differential privacy / k-anonymity / output rate limiting] |
|
||||
| **Third-party data** | [Is data from third parties used? Is it licensed for this use?] | [Audit data licensing / get legal sign-off on each third-party source] |
|
||||
| **Cross-border data transfer** | [Is personal data transferred across jurisdictions?] | [Legal review — Standard Contractual Clauses or equivalent] |
|
||||
|
||||
**DPIA required?** [Yes / No / Uncertain — for High tier or whenever processing is likely to result in high risk to individuals under GDPR Art. 35]
|
||||
|
||||
---
|
||||
|
||||
## 6. Safety & Reliability
|
||||
|
||||
*What happens when the AI gets it wrong?*
|
||||
|
||||
| Failure mode | Likelihood | Impact | Mitigation |
|
||||
|---|---|---|---|
|
||||
| **False positives** | [H/M/L] | [e.g. Flagging a legitimate transaction as fraud — customer locked out] | [Set threshold conservatively; human review for edge cases] |
|
||||
| **False negatives** | [H/M/L] | [e.g. Missing a real fraud case — financial loss] | [Monitor false negative rate; set minimum recall threshold] |
|
||||
| **Out-of-distribution inputs** | [H/M/L] | [Model behaves unpredictably on inputs outside training distribution] | [Input validation; confidence thresholding — route uncertain inputs to human review] |
|
||||
| **Model degradation** | [M] | [Performance degrades as data distributions shift post-deployment] | [Scheduled performance monitoring; drift detection alerts] |
|
||||
| **Adversarial inputs** | [L/M] | [Deliberate manipulation of inputs to game the model] | [Adversarial testing; rate limiting; anomaly detection on inputs] |
|
||||
| **Single point of failure** | [L/M] | [Model outage causes downstream system failure] | [Graceful degradation — define fallback behaviour when model is unavailable] |
|
||||
|
||||
**Fallback behaviour:** [What happens if the AI is unavailable or returns low-confidence output? — e.g. route to human review / use rule-based fallback / block the action]
|
||||
|
||||
---
|
||||
|
||||
## 7. Accountability & Governance
|
||||
|
||||
*Who is responsible when things go wrong?*
|
||||
|
||||
| Question | Answer |
|
||||
|---|---|
|
||||
| **Who owns this AI feature?** | [Team or individual with end-to-end accountability] |
|
||||
| **Who approved deployment?** | [Name and role — must be documented] |
|
||||
| **Who is responsible for ongoing monitoring?** | [Team and cadence] |
|
||||
| **Who can shut it down?** | [Who has kill-switch authority and under what conditions?] |
|
||||
| **How are incidents reported?** | [Internal escalation path + external disclosure process if required] |
|
||||
| **Is this subject to regulation?** | [EU AI Act / UK AI regulation / sector-specific rules — FINRA, FDA, FCA, etc.] |
|
||||
|
||||
**Incident response plan:** [Link to or describe what happens if the model causes harm — detection, escalation, remediation, disclosure]
|
||||
|
||||
---
|
||||
|
||||
## 8. Societal Impact
|
||||
|
||||
*Beyond individual users — what are the broader effects?*
|
||||
|
||||
| Impact area | Risk | Mitigation |
|
||||
|---|---|---|
|
||||
| **Labour displacement** | [Does this AI automate tasks that currently employ people?] | [Transition plan / human-AI collaboration framing / skills retraining commitment] |
|
||||
| **Environmental impact** | [What is the carbon cost of training and inference?] | [Measure and offset; prefer efficient architectures; use renewable-energy infrastructure where possible] |
|
||||
| **Power concentration** | [Does this AI give the deploying organisation disproportionate power over individuals?] | [Ensure right to opt out; avoid lock-in; consider open alternatives] |
|
||||
| **Information ecosystem** | [Could this AI contribute to misinformation, filter bubbles, or manipulation?] | [Provenance labelling / content policies / algorithmic diversity requirements] |
|
||||
|
||||
---
|
||||
|
||||
## 9. Mitigation Priorities
|
||||
|
||||
| # | Risk | Severity | Action | Owner | Deadline |
|
||||
|---|---|---|---|---|---|
|
||||
| 1 | [Highest risk — e.g. No disclosure to affected candidates] | Critical | [Add AI disclosure to UI and candidate-facing documentation] | [PM + Legal] | [Before launch] |
|
||||
| 2 | [e.g. No fairness evaluation across demographic groups] | High | [Commission third-party fairness audit using [method]] | [ML team + external auditor] | [Within 30 days of launch] |
|
||||
| 3 | [e.g. No model monitoring in place] | High | [Deploy performance and drift monitoring dashboard] | [ML Ops] | [Launch day] |
|
||||
| 4 | [e.g. DPIA not completed] | High | [Complete DPIA with DPO before deployment] | [Legal / DPO] | [Before launch] |
|
||||
|
||||
---
|
||||
|
||||
## 10. Pre-Deployment Checklist
|
||||
|
||||
- [ ] Ethics review completed and approved by required reviewers
|
||||
- [ ] DPIA completed (if required)
|
||||
- [ ] Fairness evaluation completed and results documented
|
||||
- [ ] AI disclosure is in place wherever required
|
||||
- [ ] Human oversight mechanism is defined and tested
|
||||
- [ ] Kill-switch and escalation path is documented and tested
|
||||
- [ ] Model monitoring is deployed and alerting is configured
|
||||
- [ ] Data lineage and training data audit documented
|
||||
- [ ] Legal sign-off obtained on data licensing and cross-border transfers
|
||||
- [ ] Incident response plan in place
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] "Who is affected" includes people the AI makes decisions *about*, not just who uses the product
|
||||
- [ ] Fairness analysis names specific protected characteristics, not just "diverse groups"
|
||||
- [ ] Safety section covers both false positive and false negative failure modes
|
||||
- [ ] Accountability section names real people, not teams or roles
|
||||
- [ ] Mitigations are specific and time-bound — not "monitor and review"
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- "Run an AI ethics review for [feature]"
|
||||
- "Conduct an ethical impact assessment for our new ML model"
|
||||
- "Review the AI risks for our hiring / credit / recommendation system"
|
||||
- "Build a responsible AI checklist for our product"
|
||||
- "What are the ethical risks of using AI for [use case]?"
|
||||
@@ -0,0 +1,150 @@
|
||||
---
|
||||
name: last-30-days-research
|
||||
description: Multi-platform research skill that gathers recent (last 30 days) opinions, sentiment, and signal on any topic from Reddit, X/Twitter, and the web. Cuts through SEO-stuffed results to surface what real people are actually saying.
|
||||
---
|
||||
|
||||
# Last 30 Days Research
|
||||
|
||||
## The Problem
|
||||
|
||||
Googling gives SEO-stuffed "best of" lists written six months ago by someone who has never used the thing. Real honest takes live on Reddit threads, X replies, and niche communities — but chasing them across platforms eats your afternoon. This skill does the chase for you.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
| Input | Required | Notes |
|
||||
|-------|----------|-------|
|
||||
| Topic | Yes | Tool, trend, feature, product, event, company — anything with a name |
|
||||
| Date scope | No | Defaults to last 30 days. Can override to last 7 days or last 90 days |
|
||||
| Angle | No | e.g. "focus on developer sentiment" or "looking for pricing complaints specifically" |
|
||||
|
||||
## Output Structure
|
||||
|
||||
The output is a structured research report with the following sections, delivered in this exact order:
|
||||
|
||||
```
|
||||
## Last 30 Days Research: [Topic]
|
||||
Research window: [Date 30 days ago] → [Today's date]
|
||||
|
||||
---
|
||||
|
||||
## What People Agree On
|
||||
[Consensus points that appear across multiple platforms — most reliable signal]
|
||||
|
||||
## Where People Disagree
|
||||
[Active debates, contrasting views — include which side has more weight]
|
||||
|
||||
## Pain Points That Keep Coming Up
|
||||
[Recurring complaints and frustrations — strongest signal of real problems]
|
||||
|
||||
## Positive Signals
|
||||
[What people genuinely praise — not PR, but unprompted appreciation]
|
||||
|
||||
## Most Interesting Takes
|
||||
[Contrarian, unexpected, or surprisingly insightful comments worth noting]
|
||||
|
||||
## Sources
|
||||
[Links to the most useful threads/posts found — 5–10 links with brief labels]
|
||||
|
||||
## Signal Confidence
|
||||
[High / Medium / Low — with a one-line rationale based on data volume and consistency]
|
||||
```
|
||||
|
||||
Each section should contain substantive content, not placeholders. If a section has no findings (e.g. no positive signals found), state that explicitly rather than leaving it empty or fabricating content.
|
||||
|
||||
## Instructions for Claude
|
||||
|
||||
### Step 1 — Calculate the date window
|
||||
|
||||
Determine today's date and subtract 30 days to get the research start date. Format: YYYY-MM-DD. Use these dates explicitly in every search query.
|
||||
|
||||
### Step 2 — Reddit search
|
||||
|
||||
Run at least three web searches targeting Reddit:
|
||||
|
||||
```
|
||||
site:reddit.com "[topic]" after:[30-days-ago-date]
|
||||
site:reddit.com "[topic]" 2025
|
||||
reddit.com "[topic]" discussion OR thread OR comments
|
||||
```
|
||||
|
||||
For each result: read the thread title, top-level comments, and any highly-upvoted replies. Record the key claims and the URL.
|
||||
|
||||
If the topic has common synonyms or abbreviations, run additional searches with those (e.g. "Claude Code" and "claude.code" and "Anthropic coding tool").
|
||||
|
||||
### Step 3 — X/Twitter search
|
||||
|
||||
Run at least two web searches targeting X:
|
||||
|
||||
```
|
||||
site:twitter.com OR site:x.com "[topic]" after:[30-days-ago-date]
|
||||
"[topic]" site:x.com -is:retweet
|
||||
```
|
||||
|
||||
Note: X search via web has limitations. If results are sparse, supplement with searches for specific accounts known to discuss the topic area (e.g. tech journalists, domain experts).
|
||||
|
||||
### Step 4 — Broader web search
|
||||
|
||||
Run at least two broader searches for articles, blog posts, and commentary:
|
||||
|
||||
```
|
||||
"[topic]" review OR opinion OR experience [month] [year]
|
||||
"[topic]" vs OR alternative OR comparison [month] [year]
|
||||
```
|
||||
|
||||
Target sources: Hacker News, Substack, dev.to, personal blogs, product communities. Avoid press releases and vendor-authored content.
|
||||
|
||||
### Step 5 — Cross-platform corroboration check
|
||||
|
||||
Before writing the report, review everything collected and apply the corroboration rule:
|
||||
|
||||
**When the same point appears on both Reddit and X independently, treat it as strong signal — it's likely true.**
|
||||
|
||||
A point mentioned only once on one platform is a data point, not a finding. Weight your sections accordingly.
|
||||
|
||||
### Step 6 — Write the report
|
||||
|
||||
Populate each section of the output structure. Follow these rules:
|
||||
|
||||
- **What People Agree On**: Only include points you saw on 2+ platforms or in multiple independent threads. These are your most reliable findings.
|
||||
- **Where People Disagree**: Name the sides. "Some say X, others say Y — and the X camp seems louder based on upvote counts / engagement."
|
||||
- **Pain Points**: Be specific. "Performance issues" is weak. "Cold start times over 4 seconds on the free tier" is useful.
|
||||
- **Positive Signals**: Must be unprompted praise, not from product marketing or sponsored content.
|
||||
- **Most Interesting Takes**: At least 2, maximum 5. Quote or closely paraphrase where possible.
|
||||
- **Sources**: Include the actual URLs. Label each one briefly (e.g. "Reddit thread: 'Has anyone switched from X to Y?'").
|
||||
- **Signal Confidence**: Rate High/Medium/Low based on:
|
||||
- High = 10+ sources, consistent signal across platforms
|
||||
- Medium = 5–10 sources, some inconsistency
|
||||
- Low = fewer than 5 sources, or highly fragmented signal
|
||||
|
||||
### Step 7 — Sanity check before delivering
|
||||
|
||||
Before outputting the report, verify:
|
||||
|
||||
- [ ] Every claim in the report traces to an actual source found during research (not prior knowledge)
|
||||
- [ ] The date window was actually applied to searches, not ignored
|
||||
- [ ] No fabricated or hallucinated URLs in the Sources section
|
||||
- [ ] Signal Confidence rating reflects the actual data volume, not optimism
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] At minimum 3 Reddit searches were run with the date filter applied
|
||||
- [ ] At minimum 2 X/Twitter searches were run
|
||||
- [ ] At minimum 2 broader web searches were run
|
||||
- [ ] Cross-platform corroboration principle was applied (same point on multiple platforms = stronger signal)
|
||||
- [ ] Pain Points section contains specific, concrete details — not vague generalisations
|
||||
- [ ] Sources section contains real URLs (not hallucinated), verified during research
|
||||
- [ ] Signal Confidence is rated and justified
|
||||
- [ ] If a section has no findings, it says so explicitly rather than being omitted or padded
|
||||
- [ ] No vendor-authored content or press releases treated as independent signal
|
||||
- [ ] Synonyms and alternative names for the topic were searched
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- "What are people saying about Cursor AI from the last 30 days?"
|
||||
- "Research Vercel's recent sentiment"
|
||||
- "Last 30 days on the Arc browser shutdown"
|
||||
- "What's the current vibe on Supabase?"
|
||||
- "What are developers saying about Claude Code lately?"
|
||||
- "Research [topic] from the last 30 days"
|
||||
- "Give me a signal report on [product]"
|
||||
- "What's the Reddit and Twitter take on [trend]?"
|
||||
@@ -0,0 +1,175 @@
|
||||
---
|
||||
name: notebooklm-connector
|
||||
description: Automates NotebookLM from Claude Code — creates notebooks, adds sources, and triggers outputs (mindmaps, audio overviews, slide decks) without manual clicking via the Claude Chrome extension.
|
||||
---
|
||||
|
||||
# NotebookLM Connector
|
||||
|
||||
## The Problem
|
||||
|
||||
NotebookLM is one of the best AI research tools — but it doesn't connect to your other tools. Every notebook requires manual setup inside the NotebookLM UI: open browser, name the notebook, paste URLs one by one, click generate. For researchers, builders, or anyone who works with a high volume of sources, this friction compounds fast.
|
||||
|
||||
This skill automates NotebookLM from Claude Code using browser automation via the Claude Chrome extension.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
| Requirement | Details |
|
||||
|-------------|---------|
|
||||
| Claude Chrome extension | Must be installed and active in your Chrome browser |
|
||||
| NotebookLM account | Active account at notebooklm.google.com |
|
||||
| Chrome browser | Open and signed into NotebookLM |
|
||||
|
||||
If the Chrome extension is not installed, this skill cannot function. There is no fallback — you will need to perform actions manually.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
| Input | Required | Notes |
|
||||
|-------|----------|-------|
|
||||
| Action(s) to perform | Yes | What you want done — see Supported Actions below |
|
||||
| Notebook name | Conditional | Required for create; optional for add/generate if a notebook is already open |
|
||||
| Sources | Conditional | Required for add sources action — URLs, file paths, or pasted text |
|
||||
| Output type | Conditional | Required for generate action — mindmap, audio overview, or briefing doc |
|
||||
|
||||
## Supported Actions
|
||||
|
||||
| Action | What It Does |
|
||||
|--------|-------------|
|
||||
| Create notebook | Opens NotebookLM, creates a new notebook with the specified title |
|
||||
| Add sources | Adds one or more URLs, files, or text blocks as sources to a notebook |
|
||||
| Generate mindmap | Triggers mindmap generation from the notebook's sources |
|
||||
| Generate audio overview | Requests an audio overview (note: takes several minutes to render) |
|
||||
| Generate briefing doc | Requests a briefing document or slide deck from sources |
|
||||
| List notebooks | Lists your existing notebooks and their source counts |
|
||||
| Open notebook | Navigates to a specific existing notebook by name |
|
||||
|
||||
Actions can be chained in a single request: "Create a notebook called 'AI Trends Q2', add these 3 URLs as sources, then generate a mindmap."
|
||||
|
||||
## Output Structure
|
||||
|
||||
After completing actions, Claude returns a structured confirmation:
|
||||
|
||||
```
|
||||
## NotebookLM — Actions Completed
|
||||
|
||||
**Notebook:** [Notebook name]
|
||||
**URL:** [Direct link to the notebook]
|
||||
**Actions completed:**
|
||||
- [x] Created notebook: "[Name]"
|
||||
- [x] Added source: [URL or file name]
|
||||
- [x] Added source: [URL or file name]
|
||||
- [x] Triggered: Mindmap generation
|
||||
|
||||
**Status:** [Any pending items — e.g. "Audio overview is generating, check back in 5–10 minutes"]
|
||||
|
||||
**Notes:** [Any issues encountered or deviations from the requested actions]
|
||||
```
|
||||
|
||||
If an action fails, the failed step is marked with `[ ]` and a reason is provided. See Error Handling below.
|
||||
|
||||
## Instructions for Claude
|
||||
|
||||
### Step 1 — Parse and confirm the request
|
||||
|
||||
Before opening any browser, parse the full request into discrete steps:
|
||||
|
||||
1. What notebook is being targeted (new or existing)?
|
||||
2. What sources need to be added (list each URL or file)?
|
||||
3. What outputs need to be generated?
|
||||
|
||||
If anything is ambiguous — e.g. "add my research sources" without specifying what they are — ask for clarification before proceeding. Do not guess at source URLs.
|
||||
|
||||
### Step 2 — Check the Chrome extension is available
|
||||
|
||||
Confirm browser automation is available via the Claude Chrome extension. If it is not active, stop and report:
|
||||
|
||||
> "This skill requires the Claude Chrome extension to be installed and active. Please install it at [extension URL] and try again."
|
||||
|
||||
### Step 3 — Navigate to NotebookLM
|
||||
|
||||
Open or navigate to `https://notebooklm.google.com`. Confirm the user is logged in. If a login screen appears, stop and ask the user to log in manually, then retry.
|
||||
|
||||
### Step 4 — Execute actions in order
|
||||
|
||||
Execute each action in the sequence requested. After each action, confirm it completed before moving to the next. Do not batch actions speculatively.
|
||||
|
||||
**Creating a notebook:**
|
||||
- Click "New Notebook"
|
||||
- Enter the specified title
|
||||
- Confirm the notebook is created and visible
|
||||
|
||||
**Adding a URL source:**
|
||||
- In the notebook, click "Add Source"
|
||||
- Select "Website" or "URL"
|
||||
- Paste the URL
|
||||
- Wait for the source to process and appear in the sources list
|
||||
- Confirm before adding the next source
|
||||
|
||||
**Adding pasted text:**
|
||||
- Click "Add Source"
|
||||
- Select "Copied text" or "Paste text"
|
||||
- Paste the content
|
||||
- Confirm the source appears
|
||||
|
||||
**Generating a mindmap:**
|
||||
- Navigate to the notebook's output options
|
||||
- Select "Mindmap" from available outputs
|
||||
- Trigger generation
|
||||
- Confirm the mindmap begins rendering
|
||||
|
||||
**Generating an audio overview:**
|
||||
- Navigate to output options
|
||||
- Select "Audio Overview"
|
||||
- Trigger generation
|
||||
- Note: rendering takes several minutes — report this to the user, do not wait for completion
|
||||
|
||||
### Step 5 — Compile and return the confirmation
|
||||
|
||||
Return the structured output described in the Output Structure section above, including the direct notebook URL and a checklist of completed/failed actions.
|
||||
|
||||
## Error Handling
|
||||
|
||||
If any step fails, do the following:
|
||||
|
||||
1. Stop at the failed step (do not attempt to continue)
|
||||
2. Report the exact step that failed and what was observed
|
||||
3. Suggest a manual workaround for that step
|
||||
4. Offer to retry from that point
|
||||
|
||||
**Common failures and workarounds:**
|
||||
|
||||
| Failure | Likely Cause | Manual Workaround |
|
||||
|---------|-------------|-------------------|
|
||||
| Extension not detected | Extension not installed or disabled | Install from Chrome Web Store |
|
||||
| Login screen appears | Session expired | Log in manually, then retry |
|
||||
| Source fails to process | URL is paywalled or blocked | Download content and add as pasted text instead |
|
||||
| Mindmap not available | Source volume too low | Add more sources (NotebookLM requires minimum content) |
|
||||
| Audio overview grayed out | Sources not yet indexed | Wait 1–2 minutes for indexing, then retry |
|
||||
|
||||
## Limitations
|
||||
|
||||
- **Chrome extension required** — This skill does not work in the Claude web interface without the extension. It cannot function in API-only or terminal-only Claude setups.
|
||||
- **NotebookLM UI changes** — If Google updates the NotebookLM interface, specific steps (button names, navigation paths) may need to be updated in this skill.
|
||||
- **Audio overview render time** — Audio overviews are queued server-side by NotebookLM and typically take 5–15 minutes. Claude can trigger the request but cannot wait for completion.
|
||||
- **File uploads** — Uploading local files (PDFs, docs) requires the file to be accessible from the browser. File paths must be absolute.
|
||||
- **Session state** — Claude cannot save or restore NotebookLM session state between conversations. Each session starts fresh.
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] User's full request was parsed into discrete steps before any browser action was taken
|
||||
- [ ] Ambiguous source references were clarified before proceeding
|
||||
- [ ] Each action was confirmed complete before the next one started
|
||||
- [ ] Direct notebook URL is included in the output
|
||||
- [ ] If audio overview was triggered, user was informed of the render delay
|
||||
- [ ] Any failed steps are explicitly reported with the specific failure reason
|
||||
- [ ] Manual workaround was offered for any step that failed
|
||||
- [ ] Output checklist accurately reflects what was completed vs. what failed
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- "Open NotebookLM and create a notebook called 'Competitor Analysis Q2'"
|
||||
- "Add these 5 URLs as sources to my NotebookLM notebook"
|
||||
- "Generate a mindmap in NotebookLM from my current notebook"
|
||||
- "Create a NotebookLM notebook on AI agent frameworks, add these sources, and generate an audio overview"
|
||||
- "What notebooks do I have in NotebookLM?"
|
||||
- "Add this article to NotebookLM: [URL]"
|
||||
- "Generate a briefing doc from my NotebookLM sources on [topic]"
|
||||
@@ -0,0 +1,156 @@
|
||||
---
|
||||
name: sycophancy-challenger
|
||||
description: Flips Claude's default from "find reasons you're right" to "find reasons you're wrong." A genuine thinking partner, not a mirror with grammar. Use before high-stakes decisions, plans, assumptions, or pitches you haven't stress-tested.
|
||||
---
|
||||
|
||||
# Sycophancy Challenger
|
||||
|
||||
Claude defaults to validating. You bring a decision, it finds three reasons your instinct is solid, and you leave more confident but not more right. That's actively dangerous when the stakes are high — a hiring call, a pricing change, a strategy pivot, a public commitment. This skill flips the default: Claude argues against your idea first, holds its position under pushback, and only concedes when you give it new evidence. Not when you express displeasure.
|
||||
|
||||
> Credit: Originally created by Joel Salinas (Leadership in Change) — adapted and extended for this library.
|
||||
|
||||
---
|
||||
|
||||
## Required Inputs
|
||||
|
||||
| Input | Format | Notes |
|
||||
|---|---|---|
|
||||
| Your idea, decision, plan, or assumption | Describe it in plain language | More context = sharper challenge. Include reasoning if you have it. |
|
||||
|
||||
No other setup required. Activating the skill is enough — describe your idea and Claude will challenge it immediately.
|
||||
|
||||
---
|
||||
|
||||
## Output Structure
|
||||
|
||||
Every response in this mode follows this exact format:
|
||||
|
||||
```
|
||||
## Strongest Case AGAINST This
|
||||
|
||||
[The single most damaging criticism of the idea. Not a list of concerns — the
|
||||
one argument that, if true, would kill this. Stated directly, without softening.]
|
||||
|
||||
|
||||
## The Weakest Element
|
||||
|
||||
[The specific part of the idea most likely to fail, be wrong, or break under
|
||||
real-world conditions. Named precisely. Not "execution risk" — the actual thing.]
|
||||
|
||||
|
||||
## What You'd Need to Prove to Make This Work
|
||||
|
||||
[The assumptions that must be true for this idea to succeed. Written as testable
|
||||
claims, not as encouragement. If an assumption can't be tested, that's noted.]
|
||||
|
||||
|
||||
## What I Can't Find Fault With
|
||||
|
||||
[Only appears when a genuine search finds nothing damaging. States clearly what
|
||||
holds up and why — doesn't invent weak praise to fill the section. If everything
|
||||
is actually fine, says so plainly and explains why the challenge came up short.]
|
||||
```
|
||||
|
||||
No additional sections. No summary. No "overall, this is a solid idea." The format ends when the four sections are complete.
|
||||
|
||||
---
|
||||
|
||||
## Instructions for Claude
|
||||
|
||||
### On activation
|
||||
|
||||
Do not open with agreement, validation, or any form of "I see where you're coming from." Begin the challenge immediately. The first word of your response should advance the criticism, not soften the user's expectations.
|
||||
|
||||
### Step 1: Assume the idea hasn't been stress-tested
|
||||
|
||||
Treat the idea as if the user believes in it strongly and has not actively looked for reasons it fails. Your job is to be the adversary they didn't have in the room.
|
||||
|
||||
### Step 2: Find the strongest case against it
|
||||
|
||||
Not a balanced view. Not pros and cons. The strongest case against. Ask:
|
||||
- What's the most likely way this fails?
|
||||
- What's the assumption that, if wrong, makes everything else irrelevant?
|
||||
- Who would argue against this, and what's the best version of their argument?
|
||||
- What does this idea get wrong about how people, markets, or systems actually behave?
|
||||
|
||||
State the strongest case directly. Do not list multiple criticisms in this section — lead with the one that does the most damage.
|
||||
|
||||
### Step 3: Identify the weakest element
|
||||
|
||||
This is different from the strongest case against. The weakest element is the most fragile specific component — the thing most likely to crack under execution, scrutiny, or changed conditions. Name it precisely. Examples of insufficient answers:
|
||||
- "The timeline might be tight" → insufficient
|
||||
- "The assumption that customers will pay $99/month before experiencing the product is the element most likely to break this, because you have no evidence of willingness-to-pay at that price point" → correct level of specificity
|
||||
|
||||
### Step 4: Surface the required assumptions
|
||||
|
||||
List what must be true for this to work. Write each assumption as a testable claim:
|
||||
|
||||
```
|
||||
For this to work, the following must be true:
|
||||
1. [Assumption stated as a claim that can be verified or falsified]
|
||||
2. [Assumption stated as a claim]
|
||||
3. [Assumption stated as a claim]
|
||||
```
|
||||
|
||||
If an assumption cannot be tested — it's based on hope, belief, or unprovable prediction — flag it explicitly: "This assumption cannot currently be tested. That's a risk."
|
||||
|
||||
### Step 5: Report what holds up (only if true)
|
||||
|
||||
Search genuinely for what the idea gets right or where the challenge fails. If you find it, state it clearly. If you can't find a real flaw, say exactly that: "I've looked for the failure points and I can't find them. Here's what actually holds up: [specific things]." Do not invent praise. Do not invent flaws either.
|
||||
|
||||
### Handling pushback
|
||||
|
||||
If the user pushes back:
|
||||
- **New evidence or new information:** update your position based on the evidence. State what changed and why.
|
||||
- **Emotional pushback, repetition, or displeasure:** do not move. Restate the criticism calmly. Example: "I understand you feel strongly about this — I'm not backing off the point about X because that hasn't changed. If there's something I'm missing, tell me what it is."
|
||||
- **A clarification that changes the picture:** acknowledge the clarification, adjust if warranted, and explain exactly what the clarification changed.
|
||||
|
||||
Do not soften a position because the user seems upset. Do not move back to validation mode mid-conversation.
|
||||
|
||||
### When the skill ends
|
||||
|
||||
The session is complete when the user has either:
|
||||
1. Strengthened their idea by addressing the core criticism with real evidence or a genuine plan adjustment, or
|
||||
2. Identified a real flaw they're going to fix.
|
||||
|
||||
Not when they've expressed satisfaction. Not when a certain number of exchanges have happened. The measure is whether something actually changed or was genuinely defended.
|
||||
|
||||
### Prohibitions
|
||||
|
||||
These prohibitions do more work than the rules above. Follow them absolutely:
|
||||
|
||||
- **Never open with agreement or validation.** Not "That's an interesting approach," not "I can see why you'd think that." Start with the challenge.
|
||||
- **Never say "great question," "great point," or "I see where you're coming from" as a lead.** These are validation openers, not neutral transitions.
|
||||
- **Never soften a criticism with "however, there are also positives."** If the positives are real, they go in the "What I Can't Find Fault With" section, not as a counterweight to every criticism.
|
||||
- **Never back down because the user expressed displeasure.** Only move if given new evidence.
|
||||
- **Never invent a flaw that isn't real.** If the idea is actually solid, say so. Inventing fake criticisms is as useless as fake validation.
|
||||
- **Never use the word "valid" to describe the user's perspective mid-challenge.** It's a validation signal disguised as a neutral word.
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Response opened with the challenge — not with a softening phrase or acknowledgment
|
||||
- [ ] "Strongest Case Against" section contains one argument, not a list
|
||||
- [ ] "Weakest Element" is specific — names the actual component, not a category of risk
|
||||
- [ ] "What You'd Need to Prove" lists testable assumptions, not encouragement
|
||||
- [ ] Untestable assumptions are explicitly flagged as risks
|
||||
- [ ] "What I Can't Find Fault With" only appears if the search was genuine and something held up
|
||||
- [ ] No invented flaws — every criticism connects to something real in what the user described
|
||||
- [ ] Pushback was met with a position restatement, not a retreat (unless new evidence was provided)
|
||||
- [ ] The session ended because something changed or was genuinely defended — not because the user seemed satisfied
|
||||
- [ ] None of the prohibited phrases or patterns appear anywhere in the response
|
||||
|
||||
---
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- "Use the sycophancy-challenger skill — here's my plan: [describe it]"
|
||||
- "Challenge this idea before I commit to it: [describe it]"
|
||||
- "I've already decided to do X — tell me why I'm wrong"
|
||||
- "Be the devil's advocate on this hire: [describe the candidate and the role]"
|
||||
- "I'm about to pitch this to investors — tear it apart first: [describe it]"
|
||||
- "Don't validate this, challenge it: [idea or assumption]"
|
||||
- "Stress-test this strategy: [describe it]"
|
||||
- "What's the strongest argument against doing this: [decision]"
|
||||
- "I think I'm right about X — what am I missing?"
|
||||
@@ -0,0 +1,192 @@
|
||||
---
|
||||
name: customer-success-plan
|
||||
description: "Build a joint customer success plan for a specific account. Use when asked to create a success plan, joint success plan, mutual action plan, or customer onboarding plan. Produces a structured success plan with business goals, milestones, success metrics, ownership, and a 90-180 day roadmap."
|
||||
---
|
||||
|
||||
# Customer Success Plan Skill
|
||||
|
||||
This skill produces a joint customer success plan — a living document shared between the CSM and the customer that aligns on outcomes, milestones, and mutual commitments. Output is ready to co-author with the customer in a kickoff call or QBR.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask the user for these if not provided:
|
||||
- **Account name** and industry
|
||||
- **Product / plan purchased**
|
||||
- **Key stakeholders** — customer champion and economic buyer
|
||||
- **Customer's stated business goals** — why did they buy? What problem are they solving?
|
||||
- **Contract term and renewal date**
|
||||
- **Current onboarding stage** (new customer / expanding / post-QBR / pre-renewal)
|
||||
- **Seats / licenses / usage purchased**
|
||||
- **Any known risks** — adoption gaps, champion uncertainty, competing priorities
|
||||
|
||||
## Output Structure
|
||||
|
||||
---
|
||||
|
||||
# Customer Success Plan: [Account Name]
|
||||
|
||||
**Product:** [Product name / plan tier]
|
||||
**Contract term:** [Start date → Renewal date]
|
||||
**CSM:** [Name]
|
||||
**Customer champion:** [Name, Title]
|
||||
**Customer executive sponsor:** [Name, Title — if known]
|
||||
**Last updated:** [Date]
|
||||
**Status:** [Active / Under review / Completed]
|
||||
|
||||
---
|
||||
|
||||
## 1. Partnership Objectives
|
||||
|
||||
> *What does success look like for [Account Name] at contract end?*
|
||||
|
||||
[Write 2–3 sentences describing the customer's core objective in plain English — what they are trying to achieve in their business, not what features they are using.]
|
||||
|
||||
**Primary business goal:** [e.g. Reduce time-to-hire by 30% across engineering teams]
|
||||
**Secondary goal:** [e.g. Consolidate three legacy tools into one platform, saving £X/year]
|
||||
**Success statement (customer's words):** "[Direct quote from champion about what success looks like — ask for this in kickoff]"
|
||||
|
||||
---
|
||||
|
||||
## 2. Success Metrics
|
||||
|
||||
Define how both parties will measure success. Agreed in the kickoff call and tracked in QBRs.
|
||||
|
||||
| Metric | Baseline (today) | Target | By when | Data source |
|
||||
|---|---|---|---|---|
|
||||
| [e.g. Seat utilisation] | [X%] | [≥ 80%] | [Month 3] | [Product analytics] |
|
||||
| [e.g. Time to hire] | [X days] | [< Y days] | [Month 6] | [Customer's ATS] |
|
||||
| [e.g. Reports produced/month] | [X] | [≥ Y] | [Month 3] | [Product analytics] |
|
||||
| [e.g. NPS] | [X] | [≥ 8] | [Month 6] | [Quarterly survey] |
|
||||
|
||||
**Leading indicators** (early signs the plan is on track):
|
||||
- [e.g. 5+ users log in within the first 2 weeks]
|
||||
- [e.g. First workflow automated within 30 days]
|
||||
- [e.g. Champion presents the tool to their team by end of Month 1]
|
||||
|
||||
---
|
||||
|
||||
## 3. Milestone Roadmap
|
||||
|
||||
Break the success journey into phases with clear milestones and owners:
|
||||
|
||||
### Phase 1: Onboard (Month 1)
|
||||
|
||||
| Milestone | Owner | Due date | Status |
|
||||
|---|---|---|---|
|
||||
| Admin setup complete (SSO, permissions, data integration) | [IT contact] | [Date] | [ ] |
|
||||
| All purchased seats activated and users invited | [Champion] | [Date] | [ ] |
|
||||
| Core workflow [X] configured and tested | [CSM + Champion] | [Date] | [ ] |
|
||||
| First training session delivered (all teams) | [CSM] | [Date] | [ ] |
|
||||
| Kickoff call completed and success plan co-signed | [CSM + Champion] | [Date] | [ ] |
|
||||
|
||||
### Phase 2: Adopt (Months 2–3)
|
||||
|
||||
| Milestone | Owner | Due date | Status |
|
||||
|---|---|---|---|
|
||||
| [Core feature] in active daily use by ≥ X users | [Champion] | [Date] | [ ] |
|
||||
| First business outcome achieved and documented | [Champion + CSM] | [Date] | [ ] |
|
||||
| 30-day check-in completed | [CSM] | [Date] | [ ] |
|
||||
| [Power user workflow] enabled for advanced users | [CSM] | [Date] | [ ] |
|
||||
|
||||
### Phase 3: Value (Months 4–6)
|
||||
|
||||
| Milestone | Owner | Due date | Status |
|
||||
|---|---|---|---|
|
||||
| QBR 1 delivered — ROI evidence presented | [CSM + AE] | [Date] | [ ] |
|
||||
| Success metric [X] hit target | [Champion] | [Date] | [ ] |
|
||||
| Expansion use case identified and introduced | [AE] | [Date] | [ ] |
|
||||
| Reference call or case study agreed | [Champion] | [Date] | [ ] |
|
||||
|
||||
### Phase 4: Renew & Expand (Months 7–12)
|
||||
|
||||
| Milestone | Owner | Due date | Status |
|
||||
|---|---|---|---|
|
||||
| QBR 2 delivered — renewal conversation started | [CSM + AE] | [Date] | [ ] |
|
||||
| Renewal proposal sent | [AE] | [Date] | [ ] |
|
||||
| Expansion or flat renewal signed | [AE] | [Date] | [ ] |
|
||||
|
||||
---
|
||||
|
||||
## 4. Mutual Commitments
|
||||
|
||||
Success plans work when both parties commit. Document what each side will do:
|
||||
|
||||
**[Vendor] commits to:**
|
||||
- Dedicated CSM available [X days/week / by email within 24 hours]
|
||||
- Monthly [call / check-in / async update] with champion
|
||||
- QBR every [90 days] with executive summary and ROI report
|
||||
- Priority support for [Account] — response SLA of [X hours] for P1 issues
|
||||
- Roadmap preview for relevant upcoming features
|
||||
- [Any other specific commitment made in sales cycle]
|
||||
|
||||
**[Account Name] commits to:**
|
||||
- Champion available for [30-min monthly] check-in
|
||||
- Users complete onboarding training by [date]
|
||||
- Feedback on product experience shared monthly (async or sync)
|
||||
- Executive sponsor participates in QBR 1 and renewal discussion
|
||||
- Provide outcome data to CSM quarterly for ROI tracking
|
||||
|
||||
---
|
||||
|
||||
## 5. Stakeholder Engagement Plan
|
||||
|
||||
| Stakeholder | Role | Engagement frequency | Format | Owner |
|
||||
|---|---|---|---|---|
|
||||
| [Champion] | Day-to-day owner | Weekly (async) + Monthly (call) | Slack / Email + Zoom | CSM |
|
||||
| [Economic buyer] | Budget holder | Quarterly | QBR (in-person or video) | CSM + AE |
|
||||
| [IT contact] | Integration owner | As needed | Email | CSM |
|
||||
| [End users] | Active users | Training only | Group session | CSM |
|
||||
|
||||
---
|
||||
|
||||
## 6. Risk & Mitigation
|
||||
|
||||
| Risk | Likelihood | Impact | Mitigation plan |
|
||||
|---|---|---|---|
|
||||
| Low adoption in first 30 days | [M] | [H] | CSM hosts live onboarding; champion sends internal comms day 1 |
|
||||
| Champion changes role | [L] | [H] | Multi-thread: introduce CSM to 2 additional stakeholders by Month 2 |
|
||||
| Budget pressure at renewal | [M] | [H] | Build ROI case monthly; document value continuously |
|
||||
| Competing priorities delay rollout | [H] | [M] | Agree minimum viable adoption path with champion; don't require perfection to declare value |
|
||||
|
||||
---
|
||||
|
||||
## 7. Communication Plan
|
||||
|
||||
| Communication | Audience | Frequency | Format | Owner |
|
||||
|---|---|---|---|---|
|
||||
| Health update | Champion | Monthly | Email summary (3 bullets: what's good, what needs attention, one ask) | CSM |
|
||||
| QBR | Champion + Exec | Quarterly | 45-min video call with slide deck | CSM + AE |
|
||||
| Product updates | Champion | As released | Release notes email | CSM |
|
||||
| Support status | Champion | When open tickets exist | Email / Slack | Support + CSM |
|
||||
|
||||
---
|
||||
|
||||
## 8. Escalation Path
|
||||
|
||||
If the success plan falls off track:
|
||||
|
||||
| Trigger | Action | Owner | Timeline |
|
||||
|---|---|---|---|
|
||||
| Health drops to Amber | Internal review + champion call within 5 days | CSM | Immediate |
|
||||
| Health drops to Red | CS leadership + AE looped in; escalation brief drafted | CS Manager | Within 24 hours |
|
||||
| Champion is unresponsive for >10 days | AE attempts exec sponsor contact | AE | After CSM attempt fails |
|
||||
| Adoption <40% at Month 3 | Emergency enablement session + revised milestone plan | CSM | Within 1 week of flag |
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Success metrics are the customer's metrics — not just product usage metrics
|
||||
- [ ] Milestones have specific owners and due dates — not "TBD"
|
||||
- [ ] Mutual commitments section is genuinely mutual — not just what the vendor will do
|
||||
- [ ] Risk register includes champion departure and low adoption
|
||||
- [ ] Plan is written to be shared with the customer — no internal-only commentary in this document
|
||||
- [ ] Executive sponsor is identified and has an engagement role
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- "Build a success plan for [Account Name] who just signed"
|
||||
- "Create a joint success plan for our new enterprise customer"
|
||||
- "Write a 6-month customer success roadmap for [Company]"
|
||||
- "I need a mutual action plan for our QBR with [Account]"
|
||||
- "Generate a customer success plan for an at-risk account"
|
||||
@@ -0,0 +1,190 @@
|
||||
---
|
||||
name: renewal-playbook
|
||||
description: "Build a structured renewal playbook for a customer account. Use when asked to plan a renewal, structure a renewal negotiation, prepare for an expansion conversation, or build a renewal strategy for at-risk or healthy accounts. Produces a renewal brief with health assessment, negotiation strategy, objection responses, expansion levers, and a timeline."
|
||||
---
|
||||
|
||||
# Renewal Playbook Skill
|
||||
|
||||
This skill produces a complete renewal playbook for a specific customer account, covering health assessment, commercial strategy, negotiation preparation, expansion opportunity mapping, and a step-by-step timeline. Output is ready for the CSM or account team to execute 90–180 days before renewal.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask the user for these if not provided:
|
||||
- **Account name**
|
||||
- **Renewal date**
|
||||
- **Current ARR** and proposed renewal ARR (if different)
|
||||
- **Account health** — RAG status and main reasons (or describe the account situation)
|
||||
- **Key stakeholders** — economic buyer, champion, and any detractors
|
||||
- **Renewal risk factors** — budget pressure, low adoption, competitive threat, champion departure, etc.
|
||||
- **Expansion opportunity** — any upsell or cross-sell potential?
|
||||
- **Contract terms** — current plan, duration, and any terms up for renegotiation
|
||||
|
||||
## Output Structure
|
||||
|
||||
---
|
||||
|
||||
# Renewal Playbook: [Account Name]
|
||||
|
||||
**Renewal date:** [Date]
|
||||
**Current ARR:** [£/$/€ X]
|
||||
**Target renewal ARR:** [£/$/€ X — flat / +X% expansion / contraction risk]
|
||||
**Health status:** [Green / Amber / Red]
|
||||
**CSM:** [Name]
|
||||
**Account executive:** [Name]
|
||||
**Days to renewal:** [X days]
|
||||
|
||||
---
|
||||
|
||||
## 1. Account Health Snapshot
|
||||
|
||||
| Dimension | Score (1–5) | Evidence |
|
||||
|---|---|---|
|
||||
| **Product adoption** | [X/5] | [e.g. 3 of 5 purchased seats active; core feature used weekly] |
|
||||
| **Business outcomes** | [X/5] | [e.g. Customer reports X% improvement in [metric]; no formal ROI review done] |
|
||||
| **Relationship depth** | [X/5] | [e.g. Strong champion in [name/role]; limited exec sponsorship] |
|
||||
| **Support & satisfaction** | [X/5] | [e.g. 2 open P2 tickets; last NPS 7; no escalations in 6 months] |
|
||||
| **Commercial engagement** | [X/5] | [e.g. Invoice paid on time; no discount pressure raised yet] |
|
||||
| **Overall health** | [X/5 — weighted] | [Green / Amber / Red] |
|
||||
|
||||
**Renewal thesis:** [One sentence: why this account will renew — or what must change for it to renew.]
|
||||
|
||||
---
|
||||
|
||||
## 2. Stakeholder Map
|
||||
|
||||
| Stakeholder | Role | Influence | Sentiment | Our relationship |
|
||||
|---|---|---|---|---|
|
||||
| [Name] | Economic buyer | High | [Positive / Neutral / Negative] | [Warm / Cold / Unknown] |
|
||||
| [Name] | Champion | High | [Positive] | [Warm] |
|
||||
| [Name] | End user | Low | [Neutral] | [Limited] |
|
||||
| [Name] | IT / procurement | Medium | [Neutral] | [Transactional] |
|
||||
|
||||
**Champion risk:** [Is our champion secure in their role? Any signals of departure or reorganisation?]
|
||||
|
||||
**Multi-thread plan:** [Who else do we need relationships with before renewal? How do we get there?]
|
||||
|
||||
---
|
||||
|
||||
## 3. Risk Register
|
||||
|
||||
| Risk | Likelihood (H/M/L) | Impact (H/M/L) | Mitigation |
|
||||
|---|---|---|---|
|
||||
| [Budget pressure / cost-cutting] | [H] | [H] | [Build ROI case 90 days out; identify budget holder's priorities] |
|
||||
| [Low adoption in [department]] | [M] | [H] | [Run targeted enablement session; tie to champion's OKRs] |
|
||||
| [Competitor evaluation] | [M] | [M] | [Request competitive intelligence; schedule exec-level call] |
|
||||
| [Champion departure] | [L] | [H] | [Map two additional stakeholders; executive intro call] |
|
||||
|
||||
---
|
||||
|
||||
## 4. Value Story
|
||||
|
||||
Build the ROI narrative for the renewal conversation:
|
||||
|
||||
**Headline result:** [e.g. "[Account] saved X hours/week or reduced [metric] by X% using [product]"]
|
||||
|
||||
**Evidence sources:**
|
||||
- [ ] Product usage data (logins, features used, seat utilisation)
|
||||
- [ ] Business metric improvement (pull from QBR deck or success plan)
|
||||
- [ ] Support resolution time improvement
|
||||
- [ ] Customer-provided testimonial or case study quotes
|
||||
|
||||
**Value gaps to close before renewal:** [Are there outcomes the customer expected but hasn't seen yet? What's the plan to close these?]
|
||||
|
||||
---
|
||||
|
||||
## 5. Expansion Opportunity
|
||||
|
||||
Map upside beyond flat renewal:
|
||||
|
||||
| Opportunity | Type | Estimated value | Likelihood | Timing |
|
||||
|---|---|---|---|---|
|
||||
| [Seat expansion — [dept] wants to add 10 users] | Upsell | [+£X ARR] | [High] | [Renewal or +3M] |
|
||||
| [Cross-sell — [Product B] use case identified] | Cross-sell | [+£X ARR] | [Medium] | [+6M] |
|
||||
| [Multi-year commitment] | Discount for term | [+£X TCV / -X% discount] | [Low] | [At renewal] |
|
||||
|
||||
**Expansion play:** [Which opportunity to lead with, and the sequence for raising it in the renewal conversation]
|
||||
|
||||
---
|
||||
|
||||
## 6. Commercial Strategy
|
||||
|
||||
**Renewal scenario planning:**
|
||||
|
||||
| Scenario | Probability | ARR outcome | Response strategy |
|
||||
|---|---|---|---|
|
||||
| **Flat renewal** | [X%] | [£X — same as current] | [Accept; plant seeds for +6M expansion] |
|
||||
| **Expansion** | [X%] | [£X] | [Lead with ROI evidence; pitch seat or feature expansion] |
|
||||
| **Contraction risk** | [X%] | [£X — downgrade to lower tier] | [Propose phased commitment; demonstrate path to full adoption] |
|
||||
| **Churn risk** | [X%] | [£0] | [Escalate to leadership; executive sponsor engagement] |
|
||||
|
||||
**Discount guardrails:**
|
||||
- Floor discount: [X% — do not go below without VP approval]
|
||||
- Triggers for discount: [Multi-year / volume / reference customer commitment]
|
||||
- What to ask for in return: [Reference case study / G2 review / executive intro / case study participation]
|
||||
|
||||
**Pricing flexibility:**
|
||||
- [e.g. Can offer monthly billing in exchange for 24-month commit]
|
||||
- [e.g. Can offer X seats free in exchange for expansion commitment]
|
||||
|
||||
---
|
||||
|
||||
## 7. Objection Responses
|
||||
|
||||
Prepare for the most likely objections:
|
||||
|
||||
**"The price is too high"**
|
||||
> Anchor on value delivered: "[Customer] achieved [X outcome] — at [£X ARR], that's [£Y per outcome / hour saved / user]. What would it cost to deliver that outcome without us?"
|
||||
> If budget is genuinely constrained, explore: phased payment, reduction in scope rather than full churn, multi-year pricing.
|
||||
|
||||
**"We're not seeing enough adoption"**
|
||||
> Acknowledge, then commit: "You're right — [X seats] are actively using [core feature] out of [Y]. We want to fix this. Here's our 60-day plan: [exec sponsor on enablement call / training session / in-product nudge campaign]."
|
||||
|
||||
**"We're evaluating [Competitor]"**
|
||||
> Don't panic. Ask: "What's driving the evaluation — is it specific features, pricing, or something else?" Then map gaps honestly. Offer a feature roadmap preview if relevant. Get clarity on their criteria and timeline before responding defensively.
|
||||
|
||||
**"We need to reduce spend this quarter"**
|
||||
> Separate the commercial conversation from the value conversation. Offer to protect the relationship with a reduced scope today with a committed expansion trigger at a business milestone. Avoid discounting without a reason.
|
||||
|
||||
---
|
||||
|
||||
## 8. Renewal Timeline
|
||||
|
||||
| Week | Action | Owner | Notes |
|
||||
|---|---|---|---|
|
||||
| **W–16** (4 months out) | Internal renewal review — health, expansion opportunity, risk | CSM | Flag to leadership if Red |
|
||||
| **W–12** | QBR / executive business review — ROI evidence delivered | CSM + AE | Book 45–60 min with economic buyer |
|
||||
| **W–10** | Champion 1:1 — pulse check on satisfaction and upcoming priorities | CSM | Uncover internal dynamics before commercial discussion |
|
||||
| **W–8** | Expansion conversation — plant seeds, share roadmap | AE | Do not lead with pricing |
|
||||
| **W–6** | Send renewal proposal — pricing, terms, options | AE | Include multi-year option |
|
||||
| **W–4** | Negotiation — address objections, finalise commercial terms | AE + CSM | Escalate to VP if >X% discount required |
|
||||
| **W–2** | Legal / procurement — contract redlines, signature process | AE + Legal | |
|
||||
| **W–0** | Signed. Handoff to post-renewal success plan | CSM | Thank the champion; begin next cycle |
|
||||
|
||||
---
|
||||
|
||||
## 9. Success Criteria
|
||||
|
||||
- [ ] Renewal signed before deadline
|
||||
- [ ] ARR outcome within target range
|
||||
- [ ] Champion relationship maintained or improved
|
||||
- [ ] At least one expansion conversation started
|
||||
- [ ] ROI evidence documented and accepted by customer
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Stakeholder map includes the economic buyer — not just the champion
|
||||
- [ ] Risk register has a mitigation for every H/H risk
|
||||
- [ ] Value story uses product data and business outcomes, not just feature lists
|
||||
- [ ] Commercial strategy includes a floor discount and a reason-to-discount framework
|
||||
- [ ] Timeline starts at least 90 days before renewal date
|
||||
- [ ] Objection responses are specific to this account, not generic
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- "Build a renewal playbook for [Account Name] renewing in [Month]"
|
||||
- "Help me plan the renewal strategy for an at-risk customer"
|
||||
- "Prepare a renewal brief for my QBR with [Company]"
|
||||
- "What's my renewal strategy for a Red account coming up in 60 days?"
|
||||
- "Create a renewal and expansion plan for [Account]"
|
||||
@@ -0,0 +1,187 @@
|
||||
---
|
||||
name: cohort-analysis
|
||||
description: "Structure a cohort analysis for retention, LTV, or behavioural patterns. Use when asked to run a cohort analysis, analyse retention by cohort, segment users by behaviour over time, or calculate lifetime value by acquisition period. Produces a complete cohort analysis framework with methodology, cohort definitions, retention curves, and prioritised interventions."
|
||||
---
|
||||
|
||||
# Cohort Analysis Skill
|
||||
|
||||
This skill produces a structured cohort analysis covering retention curves, LTV estimation, behavioural segmentation, and actionable interventions. Output is ready to present to product leadership or share with growth and data teams.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask the user for these if not provided:
|
||||
- **Analysis goal** (retention improvement / LTV modelling / behavioural segmentation / churn prediction)
|
||||
- **Product or feature being analysed**
|
||||
- **Cohort definition** — what groups users? (acquisition month, signup channel, plan tier, feature adoption)
|
||||
- **Observation window** — how many periods to track? (e.g. 12 months, 8 weeks)
|
||||
- **Key metric** — what are you measuring per cohort? (retention rate, revenue, engagement score, feature usage)
|
||||
- **Available data** — what tables/metrics are available? (paste schema or describe)
|
||||
- **Baseline** — any existing retention benchmarks or goals?
|
||||
|
||||
## Output Structure
|
||||
|
||||
---
|
||||
|
||||
# Cohort Analysis: [Product / Feature]
|
||||
|
||||
**Analysis type:** [Retention / LTV / Behavioural / Churn]
|
||||
**Cohort definition:** [Acquisition month / Signup channel / Plan tier / Feature adoption date]
|
||||
**Observation window:** [X months / weeks]
|
||||
**Primary metric:** [Metric name]
|
||||
**Date prepared:** [Date]
|
||||
|
||||
---
|
||||
|
||||
## 1. Cohort Definitions
|
||||
|
||||
| Cohort | Period | Size | Description |
|
||||
|---|---|---|---|
|
||||
| [Cohort 1] | [Jan 2025] | [N users] | [e.g. Users who signed up in Jan 2025 via organic] |
|
||||
| [Cohort 2] | [Feb 2025] | [N users] | [...] |
|
||||
|
||||
**Cohort logic:**
|
||||
- Cohort entry event: [First sign-up / First purchase / Feature activation]
|
||||
- Cohort exit criteria: [Churned / Downgraded / No activity for 30 days]
|
||||
- Exclusions: [Trial users / Internal test accounts / Users with < X days of data]
|
||||
|
||||
---
|
||||
|
||||
## 2. Retention Curve
|
||||
|
||||
**How to read:** Each cell shows what % of the cohort performed the key metric in period N.
|
||||
|
||||
| Cohort | Period 0 | Period 1 | Period 2 | Period 3 | Period 6 | Period 12 |
|
||||
|---|---|---|---|---|---|---|
|
||||
| Jan 2025 | 100% | [X%] | [X%] | [X%] | [X%] | [X%] |
|
||||
| Feb 2025 | 100% | [X%] | [X%] | [X%] | [X%] | [X%] |
|
||||
| [Trend] | — | [↑/↓ vs prior] | [...] | [...] | [...] | [...] |
|
||||
|
||||
**Retention plateau:** [At what period does retention flatten? What % does it flatten at?]
|
||||
|
||||
**Key observations:**
|
||||
- [e.g. Period 1 → Period 2 drop is the largest — average X% churn in first 30 days]
|
||||
- [e.g. Cohorts acquired via [channel] retain X% better at Period 6]
|
||||
- [e.g. Retention has improved from X% → Y% at Period 3 comparing oldest to newest cohort]
|
||||
|
||||
---
|
||||
|
||||
## 3. LTV Projection (if applicable)
|
||||
|
||||
**ARPU per period:** [£/$/€ X per active user per month]
|
||||
**Retention curve used:** [Which cohort or blended average]
|
||||
|
||||
| Period | Retained % | Revenue per user | Cumulative LTV |
|
||||
|---|---|---|---|
|
||||
| Month 1 | [X%] | [£X] | [£X] |
|
||||
| Month 3 | [X%] | [£X] | [£X] |
|
||||
| Month 6 | [X%] | [£X] | [£X] |
|
||||
| Month 12 | [X%] | [£X] | [£X] |
|
||||
|
||||
**Blended LTV:** [£X at 12 months — based on blended retention across cohorts]
|
||||
|
||||
**LTV by segment:**
|
||||
| Segment | LTV (12M) | vs Baseline |
|
||||
|---|---|---|
|
||||
| [Organic] | [£X] | [+X%] |
|
||||
| [Paid] | [£X] | [-X%] |
|
||||
| [Enterprise] | [£X] | [+X%] |
|
||||
|
||||
---
|
||||
|
||||
## 4. Behavioural Segmentation
|
||||
|
||||
Group cohorts by behaviour patterns, not just acquisition date:
|
||||
|
||||
| Segment | Definition | Size | Retention (P6) | LTV (12M) |
|
||||
|---|---|---|---|---|
|
||||
| **Power users** | [Used core feature ≥ 3x/week in first 30 days] | [X%] | [X%] | [£X] |
|
||||
| **Casual users** | [Used 1–2x/week in first 30 days] | [X%] | [X%] | [£X] |
|
||||
| **Dormant** | [Logged in but did not use core feature] | [X%] | [X%] | [£X] |
|
||||
| **Never activated** | [Signed up but never completed onboarding] | [X%] | [X%] | [£X] |
|
||||
|
||||
**Activation threshold insight:** [What action — taken within the first X days — most strongly predicts retention? This is the "aha moment" to optimise for.]
|
||||
|
||||
---
|
||||
|
||||
## 5. Leading Indicators of Churn
|
||||
|
||||
List the signals that appear **before** users churn, so teams can intervene:
|
||||
|
||||
| Signal | How early does it appear? | Churn correlation | Intervention |
|
||||
|---|---|---|---|
|
||||
| [No login for 7 days] | [7 days before churn] | [Strong] | [Re-engagement email sequence] |
|
||||
| [Support ticket with escalation] | [14 days before churn] | [Moderate] | [CSM outreach within 48 hours] |
|
||||
| [Feature usage dropped >50% WoW] | [10 days before churn] | [Strong] | [In-app nudge with use-case tutorial] |
|
||||
|
||||
---
|
||||
|
||||
## 6. Cohort Comparison: What's Changed Over Time
|
||||
|
||||
Compare oldest and newest cohorts to assess whether product improvements are showing up in retention:
|
||||
|
||||
| Metric | [Oldest cohort — e.g. Jan 2024] | [Newest cohort — e.g. Jan 2025] | Change |
|
||||
|---|---|---|---|
|
||||
| Period 1 retention | [X%] | [X%] | [↑/↓ X pp] |
|
||||
| Period 3 retention | [X%] | [X%] | [↑/↓ X pp] |
|
||||
| Activation rate | [X%] | [X%] | [↑/↓ X pp] |
|
||||
| Avg. sessions in first 30 days | [X] | [X] | [↑/↓] |
|
||||
|
||||
**Verdict:** [Are more recent cohorts performing better or worse? What shipped in that period that might explain the change?]
|
||||
|
||||
---
|
||||
|
||||
## 7. Recommendations
|
||||
|
||||
Prioritise by impact on retention curve:
|
||||
|
||||
| # | Recommendation | Target segment | Expected impact | Effort | Priority |
|
||||
|---|---|---|---|---|---|
|
||||
| 1 | [e.g. Redesign onboarding to hit activation milestone in day 1, not day 7] | [Never-activated segment] | [+X pp P1 retention] | [Medium] | P1 |
|
||||
| 2 | [e.g. Launch re-engagement sequence at day 7 inactivity trigger] | [Dormant segment] | [+X pp P2 retention] | [Low] | P1 |
|
||||
| 3 | [e.g. Introduce power-user features earlier to accelerate habit formation] | [Casual users] | [+X pp P6 LTV] | [High] | P2 |
|
||||
|
||||
---
|
||||
|
||||
## 8. SQL Reference (if applicable)
|
||||
|
||||
Provide the core cohort query so data teams can replicate or extend the analysis:
|
||||
|
||||
```sql
|
||||
-- Retention cohort query
|
||||
SELECT
|
||||
DATE_TRUNC('month', u.created_at) AS cohort_month,
|
||||
DATE_TRUNC('month', e.event_date) AS activity_month,
|
||||
DATEDIFF('month', u.created_at, e.event_date) AS period,
|
||||
COUNT(DISTINCT e.user_id) AS retained_users,
|
||||
COUNT(DISTINCT c.user_id) AS cohort_size,
|
||||
ROUND(COUNT(DISTINCT e.user_id) * 100.0 / COUNT(DISTINCT c.user_id), 1) AS retention_rate
|
||||
FROM users u
|
||||
JOIN events e ON u.user_id = e.user_id
|
||||
JOIN (
|
||||
SELECT user_id, DATE_TRUNC('month', created_at) AS cohort_month
|
||||
FROM users
|
||||
WHERE created_at >= '[start_date]'
|
||||
) c ON u.user_id = c.user_id AND DATE_TRUNC('month', u.created_at) = c.cohort_month
|
||||
WHERE e.event_type = '[key_retention_event]'
|
||||
GROUP BY 1, 2, 3
|
||||
ORDER BY 1, 3;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Cohort definition is unambiguous — the same user cannot appear in two cohorts
|
||||
- [ ] Retention curve shows a clear plateau, or the analysis notes that the window is too short to see one
|
||||
- [ ] LTV projection uses observed retention, not assumed
|
||||
- [ ] Behavioural segments are mutually exclusive and exhaustive
|
||||
- [ ] Recommendations are tied to specific cohort or segment findings — not generic growth advice
|
||||
- [ ] Leading indicators are observable in production data, not just in theory
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- "Run a cohort analysis for our SaaS product"
|
||||
- "Analyse retention by acquisition month for the last 12 cohorts"
|
||||
- "What's the LTV of users who came via paid vs organic?"
|
||||
- "Build a cohort retention model showing period 0 through period 12"
|
||||
- "Segment users by behaviour and show me which group retains best"
|
||||
@@ -0,0 +1,221 @@
|
||||
---
|
||||
name: data-pipeline-spec
|
||||
description: "Design an ETL/ELT data pipeline specification. Use when asked to design a data pipeline, spec an ETL or ELT process, document a data ingestion workflow, or plan a data integration. Produces a complete pipeline spec with sources, transforms, destinations, SLAs, error handling, and data quality rules."
|
||||
---
|
||||
|
||||
# Data Pipeline Spec Skill
|
||||
|
||||
This skill produces a complete data pipeline specification covering sources, transformations, destinations, scheduling, SLAs, error handling, data quality checks, and monitoring requirements. Output is ready for engineering handoff or architecture review.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask the user for these if not provided:
|
||||
- **Pipeline purpose** — what business question or workflow does this pipeline serve?
|
||||
- **Source systems** — where does data come from? (databases, APIs, files, event streams)
|
||||
- **Destination** — where does data land? (data warehouse, data lake, downstream DB, reporting tool)
|
||||
- **Transformation type** — ETL (transform before loading) or ELT (load raw, transform in warehouse)?
|
||||
- **Frequency / SLA** — how often must data be fresh? (real-time / hourly / daily / weekly)
|
||||
- **Volume estimate** — approximate rows/events per run
|
||||
- **Data quality requirements** — completeness, deduplication, freshness, schema enforcement
|
||||
- **Team or stack** — any specific tools in use? (Airflow, dbt, Fivetran, Spark, Kafka, etc.)
|
||||
|
||||
## Output Structure
|
||||
|
||||
---
|
||||
|
||||
# Data Pipeline Spec: [Pipeline Name]
|
||||
|
||||
**Purpose:** [One sentence — what decision or workflow does this pipeline enable?]
|
||||
**Type:** [ETL / ELT / Streaming / Batch]
|
||||
**Owner:** [Team or individual]
|
||||
**Version:** [1.0]
|
||||
**Date:** [Date]
|
||||
**Status:** [Draft / Under Review / Approved]
|
||||
|
||||
---
|
||||
|
||||
## 1. Overview
|
||||
|
||||
[2–3 sentences describing the pipeline end-to-end: what data moves, from where to where, at what cadence, and why.]
|
||||
|
||||
**Architecture diagram (text):**
|
||||
|
||||
```
|
||||
[Source A] ──┐
|
||||
[Source B] ──┤──► [Ingestion Layer] ──► [Transform Layer] ──► [Destination] ──► [Consumers]
|
||||
[Source C] ──┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. Sources
|
||||
|
||||
| Source | System | Connection type | Data format | Update pattern | Volume |
|
||||
|---|---|---|---|---|---|
|
||||
| [Source 1] | [PostgreSQL / Salesforce / S3 / Kafka] | [JDBC / REST API / SDK / Webhook] | [JSON / CSV / Parquet / CDC] | [Append / Full refresh / Incremental] | [X rows/day] |
|
||||
| [Source 2] | [...] | [...] | [...] | [...] | [...] |
|
||||
|
||||
**Incremental key (if applicable):** [The column used to identify new or changed records — e.g. `updated_at`, `event_id`]
|
||||
|
||||
**Authentication:** [API key / OAuth / IAM role / connection string — note where credentials are stored]
|
||||
|
||||
---
|
||||
|
||||
## 3. Ingestion Layer
|
||||
|
||||
**Tool:** [Fivetran / Airbyte / Kafka Connect / custom script / dbt source]
|
||||
|
||||
**Ingestion method:**
|
||||
- [ ] Full extract (full table refresh each run)
|
||||
- [ ] Incremental extract (only new/changed rows since last run)
|
||||
- [ ] CDC (change data capture from database transaction log)
|
||||
- [ ] Event streaming (continuous ingestion from Kafka/Kinesis)
|
||||
|
||||
**Raw landing zone:** [Where raw data lands before transformation — e.g. `raw.salesforce_opportunities` in Snowflake, S3 bucket `s3://data-raw/crm/`]
|
||||
|
||||
**Schema handling:** [Strict schema enforcement / Schema evolution allowed / Union schema]
|
||||
|
||||
---
|
||||
|
||||
## 4. Transformation Logic
|
||||
|
||||
List each transformation in execution order. For ELT pipelines, this is the dbt model or SQL layer.
|
||||
|
||||
| Step | Name | Description | Input | Output | Tool |
|
||||
|---|---|---|---|---|---|
|
||||
| 1 | [Deduplicate events] | [Remove duplicate event rows based on event_id] | `raw.events` | `staging.events_deduped` | [dbt / SQL / Spark] |
|
||||
| 2 | [Join user profile] | [Enrich events with user attributes from CRM] | `staging.events_deduped`, `raw.users` | `staging.events_enriched` | [...] |
|
||||
| 3 | [Aggregate to daily] | [Roll up to user×day grain] | `staging.events_enriched` | `mart.user_daily_activity` | [...] |
|
||||
|
||||
**Business logic rules:**
|
||||
- [e.g. Revenue is recognised on `payment_confirmed_at`, not `payment_initiated_at`]
|
||||
- [e.g. Users in the `internal@company.com` domain are excluded from all metrics]
|
||||
- [e.g. Currency conversion uses the ECB rate from the first business day of each month]
|
||||
|
||||
**Slowly Changing Dimensions (SCD) — if applicable:**
|
||||
- [e.g. `users.plan_tier` is SCD Type 2 — keep history of plan changes with `valid_from` / `valid_to`]
|
||||
|
||||
---
|
||||
|
||||
## 5. Destination
|
||||
|
||||
| Destination | System | Schema / Table | Write mode | Consumers |
|
||||
|---|---|---|---|---|
|
||||
| [Primary] | [Snowflake / BigQuery / Redshift / PostgreSQL] | [`analytics.mart_user_activity`] | [Append / Upsert / Full replace] | [Looker / Metabase / downstream pipeline] |
|
||||
| [Secondary] | [...] | [...] | [...] | [...] |
|
||||
|
||||
**Partitioning / Clustering:** [e.g. Partitioned by `event_date`, clustered by `user_id` — reduces query cost for time-range scans]
|
||||
|
||||
**Retention policy:** [e.g. Raw data retained for 90 days; mart tables retained indefinitely]
|
||||
|
||||
---
|
||||
|
||||
## 6. Scheduling & SLAs
|
||||
|
||||
| SLA | Target | Breach action |
|
||||
|---|---|---|
|
||||
| **Data freshness** | [Data must be ≤ X hours old by HH:MM UTC] | [Page on-call / alert Slack channel] |
|
||||
| **Pipeline completion** | [Must complete within X minutes of trigger] | [Alert and auto-retry] |
|
||||
| **Availability** | [Pipeline must run successfully X% of days per month] | [Incident review] |
|
||||
|
||||
**Schedule:** [Cron expression and human description — e.g. `0 6 * * *` — daily at 06:00 UTC]
|
||||
|
||||
**Trigger type:**
|
||||
- [ ] Time-based (cron)
|
||||
- [ ] Event-based (triggered by upstream pipeline success / file arrival / Kafka lag)
|
||||
- [ ] Manual (ad hoc runs only)
|
||||
|
||||
**Backfill strategy:** [How to reprocess historical data if the pipeline fails or logic changes — e.g. parameterised date range, full drop-and-reload]
|
||||
|
||||
---
|
||||
|
||||
## 7. Data Quality Rules
|
||||
|
||||
| Check | Table | Rule | Failure action |
|
||||
|---|---|---|---|
|
||||
| Completeness | `staging.events` | `event_id IS NOT NULL` — 100% of rows | Block load / Alert |
|
||||
| Uniqueness | `mart.user_daily_activity` | `(user_id, date)` must be unique | Block load |
|
||||
| Freshness | `mart.user_daily_activity` | `max(event_date) >= CURRENT_DATE - 1` | Alert |
|
||||
| Volume | `staging.events` | Row count within ±20% of 7-day average | Alert |
|
||||
| Referential integrity | `staging.events` | All `user_id` values exist in `users` table | Alert |
|
||||
|
||||
**DQ tool:** [dbt tests / Great Expectations / Monte Carlo / custom SQL assertions]
|
||||
|
||||
---
|
||||
|
||||
## 8. Error Handling & Recovery
|
||||
|
||||
**Retry policy:** [e.g. 3 retries with exponential back-off: 5 min, 20 min, 60 min]
|
||||
|
||||
**Failure modes and responses:**
|
||||
|
||||
| Failure | Detection | Response | Owner |
|
||||
|---|---|---|---|
|
||||
| Source unavailable | HTTP 5xx / connection timeout | Retry 3×, then alert and skip run | Data engineering |
|
||||
| Schema change in source | Column missing or type mismatch | Block load, alert schema owner | Data owner + engineering |
|
||||
| DQ check fails | dbt test failure / assertion error | Block load for P1 checks; alert for P2 | Data engineering |
|
||||
| Partial load | Row count < expected threshold | Alert; do not publish to consumers until resolved | Data engineering |
|
||||
|
||||
**Dead-letter queue:** [Where failed records are routed for manual inspection — e.g. `raw.dlq_events`]
|
||||
|
||||
---
|
||||
|
||||
## 9. Monitoring & Observability
|
||||
|
||||
**Metrics to track:**
|
||||
- Pipeline run duration (p50, p95)
|
||||
- Rows processed per run
|
||||
- DQ check pass rate
|
||||
- Source freshness lag
|
||||
- Error rate per source
|
||||
|
||||
**Alerting:**
|
||||
- [Slack channel: #data-alerts]
|
||||
- [PagerDuty: data-on-call escalation for P1 SLA breaches]
|
||||
- [Dashboard: [link to monitoring dashboard]]
|
||||
|
||||
**Logging:** [What gets logged and where — e.g. Airflow task logs to CloudWatch, structured JSON to data lake]
|
||||
|
||||
---
|
||||
|
||||
## 10. Dependencies & Sequencing
|
||||
|
||||
**Upstream dependencies:** [Which pipelines or data sources must succeed before this pipeline runs?]
|
||||
|
||||
**Downstream dependents:** [Which dashboards, pipelines, or models depend on this pipeline's output?]
|
||||
|
||||
```
|
||||
[upstream pipeline A] ──► THIS PIPELINE ──► [downstream dashboard B]
|
||||
└──► [downstream pipeline C]
|
||||
```
|
||||
|
||||
**Coordination mechanism:** [Airflow DAG dependency / dbt ref() / event trigger / manual gate]
|
||||
|
||||
---
|
||||
|
||||
## 11. Security & Compliance
|
||||
|
||||
- **PII fields:** [List columns containing PII — e.g. `email`, `ip_address`, `name`]
|
||||
- **Masking / Pseudonymisation:** [e.g. email hashed with SHA-256 before landing in mart layer]
|
||||
- **Access control:** [Who can query the destination tables? — e.g. Role-based access in Snowflake]
|
||||
- **Data residency:** [Which regions is data permitted to transit and rest in?]
|
||||
- **Audit trail:** [Is pipeline execution auditable for compliance purposes? Where are logs retained?]
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Every source has an incremental key or full-refresh justification
|
||||
- [ ] Business logic rules are documented, not just the SQL
|
||||
- [ ] SLAs are agreed with consumers, not set unilaterally by engineering
|
||||
- [ ] DQ checks cover completeness, uniqueness, freshness, and volume
|
||||
- [ ] Failure modes include a documented recovery owner
|
||||
- [ ] PII fields are identified and a treatment plan is specified
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- "Design a data pipeline for our Salesforce to Snowflake sync"
|
||||
- "Write a pipeline spec for ingesting Stripe events into our data warehouse"
|
||||
- "Build an ETL spec for our user activity data"
|
||||
- "Document our dbt pipeline from raw events to the analytics mart"
|
||||
- "Spec out the pipeline that feeds the executive dashboard"
|
||||
@@ -0,0 +1,218 @@
|
||||
---
|
||||
name: user-story-writer
|
||||
description: "Write well-structured user stories with acceptance criteria and edge cases. Use when asked to write user stories, create tickets from a feature brief, convert a PRD into stories, or write acceptance criteria. Produces ready-to-estimate stories in the standard format with clear acceptance criteria, edge cases, and definition of done."
|
||||
---
|
||||
|
||||
# User Story Writer Skill
|
||||
|
||||
This skill produces production-ready user stories from a feature brief, PRD section, or verbal description. Each story follows the standard format with a clear who/what/why, behavioural acceptance criteria in Given/When/Then format, edge cases, and definition of done. Output is ready to paste into Jira, Linear, or your planning tool.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask the user for these if not provided:
|
||||
- **Feature or change** to break into stories — paste the brief, PRD section, or describe the feature
|
||||
- **User types / personas** involved (e.g. admin, end user, guest, API consumer)
|
||||
- **Scope** — are we writing one story or decomposing an epic into a full set of stories?
|
||||
- **Acceptance criteria format preference** — Given/When/Then, bullet checklist, or both?
|
||||
- **Technical constraints or notes** — anything the engineering team has flagged that should shape the stories
|
||||
|
||||
## Output Structure
|
||||
|
||||
For each story:
|
||||
|
||||
---
|
||||
|
||||
## Story: [Short title — verb + noun, e.g. "Filter search results by date range"]
|
||||
|
||||
**Epic:** [Parent epic name — e.g. "Advanced Search"]
|
||||
**Story ID:** [Jira/Linear ID — leave blank if not yet created]
|
||||
**Priority:** [P1 / P2 / P3]
|
||||
**Story points:** [Leave blank — for engineering to estimate]
|
||||
|
||||
---
|
||||
|
||||
### User Story
|
||||
|
||||
> **As a** [specific user type — not "user"],
|
||||
> **I want to** [concrete action they want to take],
|
||||
> **So that** [the outcome they achieve — business value, not feature description].
|
||||
|
||||
**Example:**
|
||||
> As an **account manager**,
|
||||
> I want to **filter my client list by last contact date**,
|
||||
> so that I **can quickly identify clients I haven't spoken to in over 30 days and prioritise outreach**.
|
||||
|
||||
---
|
||||
|
||||
### Context
|
||||
|
||||
[1–3 sentences of context that aren't in the user story itself: when does this story matter, what triggers the need, how does it fit into a larger flow. This helps engineers understand why before they ask.]
|
||||
|
||||
---
|
||||
|
||||
### Acceptance Criteria
|
||||
|
||||
**Format: Given / When / Then**
|
||||
|
||||
Each criterion tests one specific behaviour. Write one GWT per observable outcome — not one GWT for the whole feature.
|
||||
|
||||
**AC1: [Short name for this criterion]**
|
||||
```
|
||||
Given [starting state or context]
|
||||
When [user action]
|
||||
Then [observable system behaviour]
|
||||
```
|
||||
|
||||
**AC2: [Short name]**
|
||||
```
|
||||
Given [...]
|
||||
When [...]
|
||||
Then [...]
|
||||
```
|
||||
|
||||
**AC3: [Short name]**
|
||||
```
|
||||
Given [...]
|
||||
When [...]
|
||||
Then [...]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Edge Cases
|
||||
|
||||
[List scenarios that are non-obvious but must be handled. These become additional ACs or notes to engineering.]
|
||||
|
||||
- [ ] **[Edge case 1]:** [e.g. User applies a date filter that returns 0 results — show empty state with clear messaging and a "clear filters" action]
|
||||
- [ ] **[Edge case 2]:** [e.g. User has >10,000 clients — filter must not degrade load time >200ms]
|
||||
- [ ] **[Edge case 3]:** [e.g. Date filter persists across page refresh — or explicitly should not if that's the decision]
|
||||
- [ ] **[Permission edge case]:** [e.g. Read-only users can see the filter but cannot save filter presets]
|
||||
|
||||
---
|
||||
|
||||
### Out of Scope
|
||||
|
||||
[Explicitly state what this story does NOT cover — prevents scope creep and clarifies where the next story begins.]
|
||||
|
||||
- Saving and sharing filter presets (separate story — see [Story X])
|
||||
- Bulk actions on filtered results
|
||||
- Exporting filtered client list to CSV
|
||||
|
||||
---
|
||||
|
||||
### Definition of Done
|
||||
|
||||
- [ ] Acceptance criteria all pass
|
||||
- [ ] Edge cases handled (or explicitly deferred with a new ticket raised)
|
||||
- [ ] Unit tests written for each AC
|
||||
- [ ] Works on mobile viewport (if applicable)
|
||||
- [ ] Accessibility: keyboard navigable and screen-reader compatible
|
||||
- [ ] Error states are handled and copy approved
|
||||
- [ ] Product and design have reviewed in staging
|
||||
- [ ] No console errors in production build
|
||||
|
||||
---
|
||||
|
||||
## Epic Decomposition Template
|
||||
|
||||
If the user provides an epic or feature brief, decompose it into a full set of stories before writing them:
|
||||
|
||||
**Epic:** [Name]
|
||||
**Goal:** [What outcome does completing this epic achieve?]
|
||||
**Stories:**
|
||||
|
||||
| # | Story | Notes | Dependencies |
|
||||
|---|---|---|---|
|
||||
| 1 | [Core happy path story — the simplest version of the feature that delivers value] | | |
|
||||
| 2 | [Validation / error handling story] | | Depends on #1 |
|
||||
| 3 | [Edge case or power user story] | | Depends on #1 |
|
||||
| 4 | [Admin or configuration story] | | |
|
||||
| 5 | [Performance or scale story — if applicable] | | Depends on #1 |
|
||||
|
||||
**Suggested sprint order:** [Which stories are P1 for MVP? Which can follow in a later sprint?]
|
||||
|
||||
---
|
||||
|
||||
## Common Story Anti-Patterns — and Fixes
|
||||
|
||||
Use these to review stories before handing to engineering:
|
||||
|
||||
| Anti-pattern | Example | Fix |
|
||||
|---|---|---|
|
||||
| **Solution in the story** | "As a user I want a dropdown filter" | Remove the UI decision — "As a user I want to filter by date range" |
|
||||
| **Vague "so that"** | "so that it's easier to use" | Make it specific — "so that I can prioritise outreach without opening each record manually" |
|
||||
| **Too big** | Story covers 5 distinct user flows | Split into separate stories per flow |
|
||||
| **No acceptance criteria** | Story has description only | Add at least 3 GWT criteria before engineering starts |
|
||||
| **ACs that test the solution, not the behaviour** | "Given the dropdown is open, When I select an option" | Test the outcome — "Given I have applied a date filter, When I view my results, Then only clients last contacted in that date range appear" |
|
||||
| **Missing empty state** | No AC for what happens with 0 results | Add it — empty states are part of the feature |
|
||||
| **Missing error state** | No AC for network failure or invalid input | Add error handling ACs explicitly |
|
||||
|
||||
---
|
||||
|
||||
## Example: Full Story Set for a Feature
|
||||
|
||||
**Feature brief:** "Allow users to export their invoice history as a PDF or CSV"
|
||||
|
||||
---
|
||||
|
||||
### Story 1: Export invoice list as CSV
|
||||
|
||||
> As a **finance admin**,
|
||||
> I want to **export my invoice history as a CSV file**,
|
||||
> so that I can **import it into our accounting software without manual data entry**.
|
||||
|
||||
**AC1: Successful export**
|
||||
```
|
||||
Given I am on the Invoices page with at least one invoice
|
||||
When I click "Export" and select "CSV"
|
||||
Then a CSV file is downloaded containing all visible invoices with columns: Invoice ID, Date, Amount, Status, Customer Name
|
||||
```
|
||||
|
||||
**AC2: Empty state**
|
||||
```
|
||||
Given I am on the Invoices page with no invoices
|
||||
When I click "Export"
|
||||
Then the export button is disabled and a tooltip reads "No invoices to export"
|
||||
```
|
||||
|
||||
**AC3: Filtered export**
|
||||
```
|
||||
Given I have applied a date filter showing invoices from Jan 2026 only
|
||||
When I click "Export" and select "CSV"
|
||||
Then the export contains only invoices from Jan 2026 — not all invoices
|
||||
```
|
||||
|
||||
**Edge cases:**
|
||||
- [ ] Export with >10,000 invoices — must complete in <30s or show a progress indicator
|
||||
- [ ] Export triggered on mobile — downloads to device's default download location
|
||||
|
||||
**Out of scope:** PDF export (Story 2), scheduled exports (future epic)
|
||||
|
||||
---
|
||||
|
||||
### Story 2: Export invoice list as PDF
|
||||
|
||||
> As a **finance admin**,
|
||||
> I want to **export my invoice history as a formatted PDF**,
|
||||
> so that I can **share a professional summary with our accountant**.
|
||||
|
||||
[... ACs follow same pattern ...]
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Every story has a specific user type — not "a user" or "the system"
|
||||
- [ ] The "so that" explains business value — not just feature description
|
||||
- [ ] Each AC tests one observable outcome — not a bundle of behaviours
|
||||
- [ ] Empty states, error states, and edge cases are explicitly handled
|
||||
- [ ] Out of scope is documented — not assumed
|
||||
- [ ] Stories are independent — they can be shipped individually without depending on unreleased work (except where explicitly noted)
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- "Write user stories for [feature] from this brief"
|
||||
- "Break this PRD section into user stories with acceptance criteria"
|
||||
- "Convert these feature requirements into Jira tickets"
|
||||
- "Write the user stories and ACs for [feature name]"
|
||||
- "Decompose this epic into individual stories ready for sprint planning"
|
||||
@@ -0,0 +1,215 @@
|
||||
---
|
||||
name: design-system-audit
|
||||
description: "Audit a design system for consistency, coverage, and quality. Use when asked to audit a design system, review a component library, assess design token coverage, or evaluate the health of a shared design system. Produces a structured audit with a health score, component coverage gaps, token inconsistencies, accessibility issues, and a prioritised remediation roadmap."
|
||||
---
|
||||
|
||||
# Design System Audit Skill
|
||||
|
||||
This skill produces a structured audit of a design system — covering component coverage, token consistency, documentation quality, accessibility compliance, contribution processes, and adoption health. Output is ready for a design system team, design leadership, or an engineering team evaluating their shared component library.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask the user for these if not provided:
|
||||
- **Design system name** and what product(s) it serves
|
||||
- **Audit scope** — component library / design tokens / documentation / contribution process / all of the above
|
||||
- **Current tooling** — Figma / Storybook / Zeroheight / custom / combination?
|
||||
- **Team using it** — how many designers and engineers, how many products?
|
||||
- **Known pain points** — what do teams complain about most?
|
||||
- **Governance model** — centralised team / federated contributors / no dedicated team?
|
||||
- **Goal of the audit** — improve adoption / prepare for a rebrand / onboard new teams / justify investment?
|
||||
|
||||
## Output Structure
|
||||
|
||||
---
|
||||
|
||||
# Design System Audit: [System Name]
|
||||
|
||||
**Products served:** [List of products / apps]
|
||||
**Audit scope:** [Full / Components only / Tokens only / Documentation]
|
||||
**Auditor:** [Name / Team]
|
||||
**Date:** [Date]
|
||||
**Stakeholders:** [Design lead, Eng lead, CPO, etc.]
|
||||
|
||||
---
|
||||
|
||||
## Overall Health Score
|
||||
|
||||
| Dimension | Score (1–5) | Status |
|
||||
|---|---|---|
|
||||
| Component coverage | [X/5] | 🟢/🟡/🔴 |
|
||||
| Token consistency | [X/5] | 🟢/🟡/🔴 |
|
||||
| Documentation quality | [X/5] | 🟢/🟡/🔴 |
|
||||
| Accessibility compliance | [X/5] | 🟢/🟡/🔴 |
|
||||
| Adoption rate | [X/5] | 🟢/🟡/🔴 |
|
||||
| Contribution process | [X/5] | 🟢/🟡/🔴 |
|
||||
| **Overall** | **[X/5]** | 🟢/🟡/🔴 |
|
||||
|
||||
**Summary:** [2–3 sentences. What is the overall state of the design system? What are the top 2 issues and what is the biggest strength?]
|
||||
|
||||
---
|
||||
|
||||
## 1. Component Coverage Audit
|
||||
|
||||
**How to assess:** Compare components in the design system against the actual UI patterns in the product. Every pattern that exists in production but not in the system is a coverage gap.
|
||||
|
||||
### Component Inventory
|
||||
|
||||
| Category | Components present | Coverage | Gap |
|
||||
|---|---|---|---|
|
||||
| **Navigation** | [Navbar, Sidebar, Breadcrumb, Tabs] | [80%] | [Missing: Mega menu, mobile drawer] |
|
||||
| **Forms & Inputs** | [Text input, Dropdown, Checkbox, Radio, Toggle, Date picker] | [90%] | [Missing: Multi-select, Rich text editor] |
|
||||
| **Feedback & Alerts** | [Toast, Banner, Modal, Tooltip] | [60%] | [Missing: Inline validation, Progress indicator, Skeleton loader] |
|
||||
| **Data Display** | [Table, Card, Badge, Avatar] | [50%] | [Missing: Data grid, Stat card, Timeline, Gantt] |
|
||||
| **Layout** | [Grid, Container, Divider, Spacer] | [70%] | [Missing: Responsive breakpoint utilities] |
|
||||
| **Buttons & Actions** | [Button, Icon button, FAB, Link] | [100%] | [None] |
|
||||
|
||||
**Coverage score:** [X% of production UI patterns are covered by the design system]
|
||||
|
||||
**Most impactful gaps:**
|
||||
1. [Most used pattern not in the system — causing most duplication]
|
||||
2. [...]
|
||||
3. [...]
|
||||
|
||||
---
|
||||
|
||||
## 2. Component Quality Audit
|
||||
|
||||
For each component, assess against these quality criteria:
|
||||
|
||||
| Component | States complete | Responsive | Accessibility | Dark mode | Props documented | Code matches Figma |
|
||||
|---|---|---|---|---|---|---|
|
||||
| Button | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
|
||||
| Modal | ⚠️ Loading state missing | ✅ | ✅ | ❌ | ⚠️ Partial | ✅ |
|
||||
| Table | ❌ Sorting state missing | ❌ No mobile layout | ⚠️ No aria-sort | ❌ | ❌ | ⚠️ Drift |
|
||||
| [Component] | [...] | [...] | [...] | [...] | [...] | [...] |
|
||||
|
||||
**Legend:** ✅ Complete — ⚠️ Partial / inconsistent — ❌ Missing
|
||||
|
||||
**Components with critical quality issues (fix before anything else):**
|
||||
- [Component name]: [Specific issue and why it's blocking]
|
||||
- [...]
|
||||
|
||||
---
|
||||
|
||||
## 3. Design Token Audit
|
||||
|
||||
**Token coverage:**
|
||||
|
||||
| Token type | Defined | Used consistently | Issues |
|
||||
|---|---|---|---|
|
||||
| **Colour** | [X tokens defined] | [⚠️ — 12 hardcoded hex values found in Figma] | [Inconsistent use of primary-500 vs primary-600 for CTAs across products] |
|
||||
| **Typography** | [X tokens defined] | [✅] | [None — all type styles use token scale] |
|
||||
| **Spacing** | [X tokens defined] | [⚠️ — custom spacing used in X components] | [Engineers using arbitrary px values instead of spacing tokens in X components] |
|
||||
| **Border radius** | [X tokens defined] | [❌ — not defined; each component has hardcoded values] | [Button, card, modal all use different radius values with no token] |
|
||||
| **Shadow / elevation** | [X tokens defined] | [⚠️] | [3 different drop-shadow values in use; no elevation scale] |
|
||||
| **Animation / motion** | [X tokens defined] | [❌ — not defined] | [Transition durations inconsistent across components] |
|
||||
|
||||
**Semantic token layer:** [Does the system have semantic tokens (e.g. `color.action.primary` on top of `color.blue.500`) or only primitive tokens?]
|
||||
|
||||
**Token drift:** [Are code tokens and Figma tokens in sync? Use a tool like Token Studio, Style Dictionary, or manual comparison.]
|
||||
|
||||
---
|
||||
|
||||
## 4. Documentation Quality Audit
|
||||
|
||||
**Assessment per component / pattern:**
|
||||
|
||||
| Document type | Quality | Issues |
|
||||
|---|---|---|
|
||||
| **Usage guidelines** | [⚠️ — X% of components have guidelines] | [Button and Form components documented; Navigation and Data Display mostly undocumented] |
|
||||
| **Do / Don't examples** | [❌ — mostly absent] | [Engineers frequently misuse components because intent is unclear] |
|
||||
| **Accessibility notes** | [⚠️ — present for some components] | [No consistent format; accessibility notes missing for interactive components] |
|
||||
| **Code examples** | [✅ — all Storybook components have code examples] | [...] |
|
||||
| **Changelog** | [❌ — no component-level changelog exists] | [Breaking changes are not communicated; causes unexpected UI regressions] |
|
||||
| **Migration guides** | [❌ — absent] | [Teams don't know how to upgrade to new component versions] |
|
||||
|
||||
**Documentation score:** [X% of components have complete, usable documentation]
|
||||
|
||||
**Most common designer / engineer complaint about docs:** [e.g. "I can't find whether to use Modal or Drawer for this use case — no guidance exists"]
|
||||
|
||||
---
|
||||
|
||||
## 5. Accessibility Audit
|
||||
|
||||
**WCAG 2.2 compliance status:**
|
||||
|
||||
| Criterion | Level | Status | Components affected |
|
||||
|---|---|---|---|
|
||||
| Colour contrast (text) | AA | [✅ / ⚠️ / ❌] | [e.g. ❌ — Disabled state text fails 4.5:1 ratio in 3 components] |
|
||||
| Colour contrast (UI components) | AA | [✅ / ⚠️ / ❌] | [...] |
|
||||
| Keyboard navigation | AA | [✅ / ⚠️ / ❌] | [⚠️ — Modal focus trap not implemented; Dropdown not keyboard accessible] |
|
||||
| Focus visible | AA | [✅ / ⚠️ / ❌] | [...] |
|
||||
| Screen reader support (ARIA) | AA | [✅ / ⚠️ / ❌] | [❌ — Table component lacks aria-sort; Icon buttons have no aria-label] |
|
||||
| Touch target size | AA | [✅ / ⚠️ / ❌] | [⚠️ — Mobile tap targets below 44×44px in X components] |
|
||||
| Motion / animation | AA | [✅ / ⚠️ / ❌] | [...] |
|
||||
|
||||
**Critical accessibility blockers (must fix before next release):**
|
||||
1. [Most critical issue — e.g. Keyboard users cannot close Modal — focus trap missing]
|
||||
2. [...]
|
||||
|
||||
---
|
||||
|
||||
## 6. Adoption Audit
|
||||
|
||||
**Adoption by team / product:**
|
||||
|
||||
| Product / Team | Components used from system | Custom components built outside system | Adoption score |
|
||||
|---|---|---|---|
|
||||
| [Product A] | [X% of UI uses system components] | [Y custom components] | [High / Medium / Low] |
|
||||
| [Product B] | [...] | [...] | [...] |
|
||||
|
||||
**Why teams are not adopting:**
|
||||
|
||||
| Barrier | Severity | Evidence |
|
||||
|---|---|---|
|
||||
| [Component doesn't exist] | High | [Top reason in team survey] |
|
||||
| [Component exists but doesn't meet use case] | Medium | [Modal component lacks X state needed by Product B] |
|
||||
| [Documentation too sparse to know how to use it] | Medium | [...] |
|
||||
| [No one enforces system use — easier to build custom] | High | [...] |
|
||||
| [System is out of date with product's current visual language] | Medium | [...] |
|
||||
|
||||
---
|
||||
|
||||
## 7. Contribution Process Audit
|
||||
|
||||
| Dimension | Current state | Assessment |
|
||||
|---|---|---|
|
||||
| **How to contribute** | [Documented / Not documented] | [✅ / ❌] |
|
||||
| **Contribution criteria** | [Clear entry bar for what goes in the system] | [⚠️ — unclear who decides what becomes a system component vs stays local] |
|
||||
| **Review process** | [Who reviews contributions and how long it takes] | [❌ — no formal review; contributions sit unreviewed for weeks] |
|
||||
| **Release cadence** | [How often system releases happen] | [⚠️ — sporadic; no set cadence] |
|
||||
| **Breaking change policy** | [How breaking changes are handled and communicated] | [❌ — no policy; breaking changes are a surprise] |
|
||||
| **Versioning** | [Semantic versioning in place?] | [✅ — all packages use semver] |
|
||||
|
||||
---
|
||||
|
||||
## 8. Prioritised Remediation Roadmap
|
||||
|
||||
| Priority | Initiative | Impact | Effort | Timeline |
|
||||
|---|---|---|---|---|
|
||||
| P1 | Fix [X] critical accessibility issues (keyboard nav, ARIA) | Critical — legal + user impact | Medium | Sprint 1–2 |
|
||||
| P1 | Define and implement border radius and shadow token scale | High — ends inconsistency | Low | Sprint 1 |
|
||||
| P1 | Document top 10 most-used components (usage + do/don't) | High — unblocks adoption | Medium | Sprint 2–4 |
|
||||
| P2 | Build Skeleton loader + Inline validation components (top 2 gaps) | High — eliminates custom duplication | High | Quarter 2 |
|
||||
| P2 | Establish contribution process with SLA for reviews | Medium — enables growth | Low | Sprint 3 |
|
||||
| P3 | Dark mode token support | Medium — product parity | High | Quarter 3 |
|
||||
| P3 | Design-code token sync tooling (Token Studio / Style Dictionary) | Medium — reduces drift | Medium | Quarter 2–3 |
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Coverage gaps are identified by comparing the design system to actual production UI, not assumed
|
||||
- [ ] Accessibility issues cite specific WCAG criterion and affected components
|
||||
- [ ] Adoption barriers are backed by evidence (interviews, survey, usage data) — not assumed
|
||||
- [ ] Remediation roadmap has effort estimates and is sequenced by impact
|
||||
- [ ] Both Figma and code (Storybook/implementation) are assessed — not just Figma
|
||||
- [ ] Stakeholders from design, engineering, and product have reviewed the audit
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- "Audit our design system for consistency and coverage"
|
||||
- "Review our component library and identify gaps"
|
||||
- "Assess the health of our shared design system"
|
||||
- "Run a design system audit before we do a rebrand"
|
||||
- "What's wrong with our design system and what should we fix first?"
|
||||
@@ -0,0 +1,215 @@
|
||||
---
|
||||
name: customer-journey-map
|
||||
description: "Build a customer journey map for a product, service, or experience. Use when asked to map a customer journey, create a user journey, document touchpoints and pain points, or design an experience map. Produces a complete journey map with stages, touchpoints, emotions, pain points, and prioritised opportunities."
|
||||
---
|
||||
|
||||
# Customer Journey Map Skill
|
||||
|
||||
This skill produces a complete customer journey map covering every stage from awareness through advocacy. Each stage includes touchpoints, customer actions, emotions, pain points, and specific improvement opportunities. Output is ready for use in product discovery, UX design, or cross-functional alignment workshops.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask the user for these if not provided:
|
||||
- **Product or service** being mapped
|
||||
- **Customer persona** — which customer segment is this map for? (be specific — one persona per map)
|
||||
- **Journey scope** — full end-to-end (awareness → advocacy), or a specific phase (e.g. onboarding only)?
|
||||
- **Current state or future state?** — mapping how it works today, or designing how it should work?
|
||||
- **Data sources** — any research, user interviews, support tickets, NPS comments, analytics available?
|
||||
- **Goal of the map** — what decision will this inform? (redesign, prioritisation, stakeholder alignment, new feature)
|
||||
|
||||
## Output Structure
|
||||
|
||||
---
|
||||
|
||||
# Customer Journey Map: [Product / Service]
|
||||
|
||||
**Persona:** [Name — e.g. "Sarah, the overwhelmed HR manager"]
|
||||
**Journey scope:** [Full end-to-end / Onboarding / Purchase / Renewal]
|
||||
**Current or future state:** [Current state / Desired future state]
|
||||
**Prepared by:** [Name / Team]
|
||||
**Date:** [Date]
|
||||
**Based on:** [Research sources — interviews, analytics, support data, assumed/hypothetical]
|
||||
|
||||
---
|
||||
|
||||
## Persona Summary
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| **Name** | [Sarah] |
|
||||
| **Role** | [HR Manager at a 200-person professional services firm] |
|
||||
| **Goal** | [Reduce time spent on manual employee data management] |
|
||||
| **Frustrations** | [Too many tools that don't talk to each other; always chasing approvals] |
|
||||
| **Tech comfort** | [Moderate — comfortable with SaaS tools but not a power user] |
|
||||
| **Decision power** | [Recommends tools; budget approved by CHRO] |
|
||||
|
||||
---
|
||||
|
||||
## Journey Overview
|
||||
|
||||
```
|
||||
AWARENESS → CONSIDERATION → DECISION → ONBOARDING → ADOPTION → ADVOCACY
|
||||
[Stage 1] [Stage 2] [Stage 3] [Stage 4] [Stage 5] [Stage 6]
|
||||
```
|
||||
|
||||
**Overall experience rating (current state):** [😤 Frustrating / 😐 Neutral / 😊 Positive]
|
||||
|
||||
---
|
||||
|
||||
## Stage 1: Awareness
|
||||
|
||||
*How does the customer first discover the product exists?*
|
||||
|
||||
**Customer goal at this stage:** [e.g. Realise they have a problem worth solving — or find a solution to a specific pain]
|
||||
|
||||
| Element | Detail |
|
||||
|---|---|
|
||||
| **Trigger** | [What event makes them start looking? — e.g. Manual process breaks down / peer recommendation / saw ad] |
|
||||
| **Where they are** | [Google search / LinkedIn / conference / colleague conversation / email newsletter] |
|
||||
| **What they do** | [e.g. Searches "automate employee onboarding" / asks peers in HR community / clicks LinkedIn ad] |
|
||||
| **Emotion** | [😤 Frustrated — overwhelmed by manual processes and hoping for a better way] |
|
||||
| **Pain points** | [Overwhelming number of options / hard to know which tools are credible / can't tell what's B2B vs B2C from homepage] |
|
||||
| **Opportunities** | [SEO content targeting the trigger keyword / LinkedIn thought leadership / peer community presence] |
|
||||
|
||||
---
|
||||
|
||||
## Stage 2: Consideration
|
||||
|
||||
*The customer is actively evaluating options. What do they do to decide?*
|
||||
|
||||
| Element | Detail |
|
||||
|---|---|
|
||||
| **Customer goal** | [Narrow down from many options to a shortlist of 2–3] |
|
||||
| **What they do** | [Reads G2/Capterra reviews / watches demo video / downloads comparison guide / asks peers who use something similar] |
|
||||
| **Touchpoints** | [Website / review sites / social proof / demo request flow / sales email] |
|
||||
| **Emotion** | [😕 Anxious — worried about making the wrong choice; past tool purchases haven't delivered] |
|
||||
| **Pain points** | [Pricing not visible on website / demo requires a call before seeing the product / unclear if it works with their existing stack] |
|
||||
| **Opportunities** | [Self-serve demo or interactive product tour / transparent pricing page / ROI calculator / case studies from similar company size] |
|
||||
|
||||
---
|
||||
|
||||
## Stage 3: Decision
|
||||
|
||||
*The customer is ready to buy — or not. What makes them commit?*
|
||||
|
||||
| Element | Detail |
|
||||
|---|---|
|
||||
| **Customer goal** | [Get sign-off from CHRO and justify the decision with a business case] |
|
||||
| **What they do** | [Books sales call / requests security questionnaire / builds internal business case / negotiates contract] |
|
||||
| **Touchpoints** | [AE / sales call / security review / contract / procurement process] |
|
||||
| **Emotion** | [😬 Cautious — doesn't want to be wrong; presenting to leadership adds pressure] |
|
||||
| **Pain points** | [Sales process is slow / security questionnaire takes weeks / contract terms are non-standard and require legal] |
|
||||
| **Opportunities** | [Security FAQ self-serve / standard contract with predictable terms / champion toolkit (slides, business case template) to help them sell internally] |
|
||||
|
||||
---
|
||||
|
||||
## Stage 4: Onboarding
|
||||
|
||||
*The customer has bought. Now they need to get value fast.*
|
||||
|
||||
| Element | Detail |
|
||||
|---|---|
|
||||
| **Customer goal** | [Get the product working and show their CHRO it was a good decision] |
|
||||
| **What they do** | [Receives welcome email / attends kickoff call / configures integrations / invites team] |
|
||||
| **Touchpoints** | [Onboarding email sequence / in-product onboarding checklist / CSM / help centre / integrations marketplace] |
|
||||
| **Emotion** | [😬 Anxious but hopeful — excited about potential but stressed about the setup work] |
|
||||
| **Pain points** | [Setup is more complex than expected / IT required for SSO but IT is slow to respond / generic onboarding doesn't match their use case] |
|
||||
| **Opportunities** | [Role-specific onboarding paths / IT connector with pre-filled request template / quick win email at day 3 (show them one thing that already works)] |
|
||||
|
||||
**Key moment of truth:** [What single moment in this stage determines whether they'll become an active user or ghost? — e.g. "First time the product saves them 30 minutes on a task they used to do manually"]
|
||||
|
||||
---
|
||||
|
||||
## Stage 5: Adoption
|
||||
|
||||
*The customer is using the product. Are they getting consistent value?*
|
||||
|
||||
| Element | Detail |
|
||||
|---|---|
|
||||
| **Customer goal** | [Make the product a regular part of their workflow; demonstrate ROI to leadership] |
|
||||
| **What they do** | [Uses core features daily / discovers new features / hits a limitation / contacts support / attends webinar] |
|
||||
| **Touchpoints** | [Product UI / in-app notifications / email / support / community / customer success manager] |
|
||||
| **Emotion** | [Variable — some days 😊 when the product works well; some days 😤 when hitting a gap or bug] |
|
||||
| **Pain points** | [Feature they expected isn't there / reporting doesn't show the metric leadership wants / power features are too complex / feels like they're underutilising what they're paying for] |
|
||||
| **Opportunities** | [Proactive CSM check-in at day 30 / in-product feature discovery / usage dashboard for the customer to see their own ROI / community for peer learning] |
|
||||
|
||||
**Adoption health indicators:**
|
||||
- [DAU/MAU ratio — what does healthy look like?]
|
||||
- [Feature X used by Y% of seats within Z weeks]
|
||||
- [First NPS survey at 60 days — target score]
|
||||
|
||||
---
|
||||
|
||||
## Stage 6: Advocacy
|
||||
|
||||
*The customer loves the product. How do you turn them into a referral engine?*
|
||||
|
||||
| Element | Detail |
|
||||
|---|---|
|
||||
| **Customer goal** | [Solve problems faster; feel like an expert; feel valued as a customer] |
|
||||
| **What they do** | [Refers a peer / writes a G2 review / participates in case study / speaks at event / becomes a power user / joins community] |
|
||||
| **Touchpoints** | [CSM / community / review request email / referral programme / case study outreach / conference sponsorship] |
|
||||
| **Emotion** | [😊 Proud — the tool is part of their professional identity; they feel smart for choosing it] |
|
||||
| **Pain points** | [Referral programme is clunky / no structured way to connect with peers / case study process is slow and effortful for them] |
|
||||
| **Opportunities** | [One-click G2 review request at high-satisfaction moment / peer community / referral programme with meaningful reward / case study process that does most of the work for them] |
|
||||
|
||||
---
|
||||
|
||||
## Emotion Curve
|
||||
|
||||
Plot the customer's emotional experience across the journey:
|
||||
|
||||
```
|
||||
High 😊 │ * * *
|
||||
│ *
|
||||
Neutral 😐│ * *
|
||||
│ *
|
||||
Low 😤 │ * *
|
||||
└────────────────────────────────────────────────────
|
||||
Aware Consider Decide Onboard Adopt Advocate
|
||||
```
|
||||
|
||||
**Lowest point:** [Which stage has the worst experience — and why?]
|
||||
**Highest point:** [When is the customer most delighted — what drove it?]
|
||||
**Biggest drop:** [Where does sentiment fall most sharply — this is usually the biggest opportunity]
|
||||
|
||||
---
|
||||
|
||||
## Prioritised Opportunities
|
||||
|
||||
| Opportunity | Stage | Impact on customer | Effort to fix | Priority |
|
||||
|---|---|---|---|---|
|
||||
| [Self-serve product tour before sales call] | Consideration | [High — removes top buying barrier] | [Medium] | P1 |
|
||||
| [Quick win email at day 3] | Onboarding | [High — builds early habit] | [Low] | P1 |
|
||||
| [IT SSO setup template] | Onboarding | [Medium — removes specific blocker] | [Low] | P2 |
|
||||
| [30-day proactive CSM check-in] | Adoption | [Medium — catches churn signals early] | [Medium] | P2 |
|
||||
| [Peer referral programme] | Advocacy | [High for growth — reduces CAC] | [High] | P3 |
|
||||
|
||||
---
|
||||
|
||||
## What We Don't Know (Research Gaps)
|
||||
|
||||
| Gap | How to close it | Priority |
|
||||
|---|---|---|
|
||||
| [What actually triggers the decision to start looking?] | [5 JTBD interviews with recent buyers] | [High] |
|
||||
| [What causes customers to stall in onboarding?] | [Drop-off analysis in onboarding funnel + 3 interviews with churned customers] | [High] |
|
||||
| [What % of customers have reached the advocacy stage?] | [Product analytics — identify power users; NPS by cohort] | [Medium] |
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Map covers one specific persona — not "all customers"
|
||||
- [ ] Each stage includes the customer's emotional state — not just actions
|
||||
- [ ] Pain points are the customer's pain — not the company's pain
|
||||
- [ ] Opportunities are specific enough to become backlog items or design prompts
|
||||
- [ ] Emotion curve shows the real experience — not an aspirationally positive version
|
||||
- [ ] Research gaps are documented — the map reflects what is known, not assumed
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- "Map the customer journey for [product]"
|
||||
- "Build a user journey from awareness to advocacy"
|
||||
- "Create a journey map for our onboarding experience"
|
||||
- "Map out the touchpoints and pain points for [customer type]"
|
||||
- "Design an experience map for [process or product]"
|
||||
@@ -13,10 +13,12 @@ Ask the user for these if not provided:
|
||||
- **API or endpoint details** (raw spec, Postman export, or verbal description)
|
||||
- **Auth method** (API key / Bearer token / OAuth 2.0 / None)
|
||||
- **Base URL**
|
||||
- **API version** (e.g. v1, v2.3, or "unversioned" — affects deprecation notes and versioning headers)
|
||||
- **Rate limits** (requests per second/minute per token or IP, if known — or "unknown")
|
||||
- **Audience** (internal developers / external partners / public)
|
||||
- **Output format** (Markdown / OpenAPI YAML / Plain prose)
|
||||
- **Output format** (Markdown for developer portals and READMEs / Plain prose for Confluence or Notion — note: OpenAPI YAML is not produced by this skill)
|
||||
|
||||
## Output Structure
|
||||
## Output Format
|
||||
|
||||
For each endpoint, produce the following:
|
||||
|
||||
@@ -133,13 +135,13 @@ data = response.json()
|
||||
- [ ] Every parameter is documented (type, required/optional, description)
|
||||
- [ ] Response fields are fully documented with types
|
||||
- [ ] All relevant error codes are listed with resolution guidance
|
||||
- [ ] Code examples are copy-paste runnable (no pseudocode)
|
||||
- [ ] Error codes cover at minimum: 400 (bad request), 401/403 (auth), 404 (not found), 429 (rate limited), 500 (server error) — or explicitly note which don't apply to this endpoint
|
||||
- [ ] Code examples use the actual base URL and a realistic placeholder token — no examples reference undefined variables or "YOUR_ENDPOINT" outside the snippet
|
||||
- [ ] Auth method is clearly stated at the top
|
||||
- [ ] Enum values are listed where applicable
|
||||
- [ ] Pagination documented if the endpoint is a list endpoint
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
## Usage Examples
|
||||
- "Document this API endpoint: [paste spec or description]"
|
||||
- "Turn this Postman collection into developer docs"
|
||||
- "Write API reference docs for [endpoint]"
|
||||
|
||||
@@ -10,6 +10,7 @@ This skill produces a complete Architecture Decision Record (ADR) following the
|
||||
## Required Inputs
|
||||
|
||||
Ask the user for these if not provided:
|
||||
- **ADR number** (sequential number in your ADR registry — e.g. 012; or "next available" if unknown)
|
||||
- **Decision title** (brief, e.g. "Use PostgreSQL as primary datastore")
|
||||
- **Context** (what situation led to this decision needing to be made?)
|
||||
- **Options considered** (at least 2; if only 1 is given, prompt for alternatives that were considered or ruled out)
|
||||
@@ -17,8 +18,9 @@ Ask the user for these if not provided:
|
||||
- **Reason for choice**
|
||||
- **Status** (Proposed / Accepted / Deprecated / Superseded)
|
||||
- **Author and date**
|
||||
- **Team context** (optional — team size, relevant experience, org constraints; helps calibrate formality and depth of the Context section)
|
||||
|
||||
## Output Structure
|
||||
## Output Format
|
||||
|
||||
---
|
||||
|
||||
@@ -89,13 +91,13 @@ For each option, produce:
|
||||
|
||||
## Implementation Notes
|
||||
|
||||
[Optional but valuable: any specific patterns, gotchas, or guidance for the team implementing based on this decision. Link to relevant tickets, RFCs, or design docs if applicable.]
|
||||
[Include if the decision has non-obvious implementation gotchas, or if there are related tickets/RFCs implementers will need. Skip only if the decision is purely tooling selection with no implementation ambiguity.]
|
||||
|
||||
---
|
||||
|
||||
## Review Date
|
||||
|
||||
[Optional: "This decision should be reviewed if [condition] — e.g. team grows beyond 20 engineers, or traffic exceeds 10M requests/day."]
|
||||
[Include unless the decision is permanent or self-evidently final. State a specific trigger condition — e.g. "Review if team grows beyond 20 engineers or traffic exceeds 10M requests/day" — not just "should be reviewed periodically".]
|
||||
|
||||
---
|
||||
|
||||
@@ -107,10 +109,10 @@ For each option, produce:
|
||||
- [ ] Consequences include *negative* consequences — no decision is consequence-free
|
||||
- [ ] Decision is stated in plain language in the Decision section
|
||||
- [ ] Risks section identifies what would invalidate this decision
|
||||
- [ ] Written for someone with no prior context on this decision
|
||||
|
||||
## Example Trigger Phrases
|
||||
- [ ] Context section states the problem explicitly in its first 1–2 sentences (does not assume the reader knows what problem the team was solving)
|
||||
- [ ] Each rejected option's "Why ruled out" explanation names a specific constraint or trade-off (not a circular statement like "didn't meet our requirements")
|
||||
|
||||
## Usage Examples
|
||||
- "Write an ADR for using [technology]"
|
||||
- "Document our decision to [architectural choice]"
|
||||
- "Create an architecture decision record for [topic]"
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: changelog-generator
|
||||
description: "Convert a git log, commit list, or release notes into a polished, user-facing changelog. Use when writing release notes, generating a CHANGELOG.md entry, or documenting what changed in a version. Produces a structured changelog section with version header, categorised changes, and migration notes. Optimised for Opus 4.7 and newer models."
|
||||
description: "Convert a git log, commit list, or release notes into a polished, user-facing changelog. Use when writing release notes, generating a CHANGELOG.md entry, or documenting what changed in a version. Produces a structured changelog section with version header, categorised changes, and migration notes."
|
||||
---
|
||||
|
||||
# Changelog Generator Skill
|
||||
@@ -15,8 +15,10 @@ Ask for these if not provided:
|
||||
- **Release date** (or "today")
|
||||
- **Audience** (developers using an API / end users of a product / internal team — affects language)
|
||||
- **Any breaking changes** (flag these explicitly if known)
|
||||
- **Previous version behaviour** (optional — paste the previous changelog entry or describe what is changing; needed for accurate "Changed" entries)
|
||||
- **Scope** (whole product / specific package or module — e.g. "payments SDK only", "iOS app", "all services")
|
||||
|
||||
## Output Structure
|
||||
## Output Format
|
||||
|
||||
Follow [Keep a Changelog](https://keepachangelog.com) format:
|
||||
|
||||
@@ -52,6 +54,10 @@ Follow [Keep a Changelog](https://keepachangelog.com) format:
|
||||
|
||||
---
|
||||
|
||||
---
|
||||
|
||||
> **Skill guidance — do not include the following section in the delivered changelog:**
|
||||
|
||||
## Formatting Rules Applied
|
||||
|
||||
**Language:** Write for the reader, not the committer. "Add dark mode support" not "implement ThemeProvider with dark palette variant".
|
||||
@@ -72,9 +78,10 @@ Follow [Keep a Changelog](https://keepachangelog.com) format:
|
||||
- [ ] Related commits are grouped into single entries (not listed individually)
|
||||
- [ ] Version and date header is correct
|
||||
- [ ] Empty sections are omitted
|
||||
- [ ] Tone is imperative mood throughout
|
||||
- [ ] No entries start with past-tense verbs (no "Added", "Fixed", "Removed" — use "Add", "Fix", "Remove")
|
||||
- [ ] Every breaking change entry includes a specific migration action (not just "update your code")
|
||||
|
||||
## Example Trigger Phrases
|
||||
## Usage Examples
|
||||
- "Write a changelog for version [X]" + [paste commits]
|
||||
- "Generate release notes from these commits"
|
||||
- "Turn this git log into a CHANGELOG entry"
|
||||
|
||||
@@ -0,0 +1,282 @@
|
||||
---
|
||||
name: claude-superpowers
|
||||
description: "Force Claude Code to work like a senior developer: plan before coding, work in isolation, write tests first, and review its own output twice before presenting it. Use when asked to enable superpowers mode, activate the superpowers framework, or turn on superpowers for this session. Installs a 4-stage framework — Plan, Isolate, Test First, Double Review — that prevents Claude from sprinting into broken code."
|
||||
---
|
||||
|
||||
# Claude Superpowers Skill
|
||||
|
||||
Stop Claude from shipping the first thing it writes. Superpowers mode locks Claude into four stages — Plan, Isolate, Test First, Double Review — so that what it presents at the end is actually right.
|
||||
|
||||
The default problem: Claude sprints out of the gate, writes the whole thing in one shot, and it looks great — until someone runs it. It doesn't plan. It doesn't test. It doesn't verify. The result: code that breaks on edge cases, debugging rounds that burn tokens, and rework that costs more than doing it right the first time.
|
||||
|
||||
> **Credit:** Inspired by a skill from Nate Herk's YouTube channel — adapted and extended for this library.
|
||||
|
||||
---
|
||||
|
||||
## Required Inputs
|
||||
|
||||
No inputs required. Superpowers activates on command, then applies to whatever coding task follows.
|
||||
|
||||
---
|
||||
|
||||
## The Four Stages
|
||||
|
||||
### Stage 1 — Plan
|
||||
|
||||
Before writing a single line of code, Claude must produce a written plan and wait for user confirmation.
|
||||
|
||||
**Plan format:**
|
||||
|
||||
```
|
||||
PLAN
|
||||
════
|
||||
|
||||
TASK
|
||||
[One-sentence restatement of what was asked. If anything is ambiguous, flag it here before proceeding.]
|
||||
|
||||
APPROACH
|
||||
[2–4 sentences describing the implementation approach and key decisions. If there are multiple valid approaches, briefly explain why this one was chosen.]
|
||||
|
||||
FILES TO CREATE OR MODIFY
|
||||
- [path/to/file.ts] — [what changes: create / modify / delete — one line reason]
|
||||
- [path/to/file.ts] — [what changes]
|
||||
|
||||
EDGE CASES I WILL HANDLE
|
||||
- [Edge case 1]
|
||||
- [Edge case 2]
|
||||
- [Edge case 3]
|
||||
|
||||
EDGE CASES I AM NOT HANDLING (out of scope)
|
||||
- [Out of scope case — reason]
|
||||
|
||||
ASSUMPTIONS
|
||||
- [Any assumption made where the requirements were unclear]
|
||||
|
||||
Confirm this plan before I start coding.
|
||||
```
|
||||
|
||||
Claude must not proceed until the user says yes (or provides corrections). If the user corrects the plan, revise and re-confirm before starting.
|
||||
|
||||
---
|
||||
|
||||
### Stage 2 — Isolate
|
||||
|
||||
Claude works in isolation until the output is complete and reviewed. Nothing touches the main project until explicitly approved.
|
||||
|
||||
**Isolation rules:**
|
||||
- If git is available: create a feature branch before making any changes. Branch name format: `superpowers/[task-slug]`
|
||||
- If no git: note that changes are being made to a working copy and flag all modified files at the end for user review before they're considered "shipped"
|
||||
- Do not modify files outside the scope defined in the plan unless the user explicitly expands scope during the session
|
||||
- If new scope is discovered mid-task (e.g. a dependency needs to change), surface it: "This requires also modifying [X] — should I include that in scope?"
|
||||
|
||||
**On starting Stage 2, announce:**
|
||||
```
|
||||
ISOLATE
|
||||
Working in isolation on branch: superpowers/[task-slug]
|
||||
No changes will be considered final until Stage 4 review is complete.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Stage 3 — Test First
|
||||
|
||||
Before writing the implementation, write the tests (or at minimum, define the expected behaviour as executable assertions).
|
||||
|
||||
**Test-first approach:**
|
||||
1. Write tests that define the expected behaviour for the task
|
||||
2. Write tests that cover each edge case identified in the plan
|
||||
3. Run the tests — they should fail (implementation doesn't exist yet)
|
||||
4. Confirm the tests are failing for the right reason before writing implementation
|
||||
5. Write the implementation
|
||||
6. Run the tests — they should now pass
|
||||
7. If tests fail: fix the implementation, not the tests
|
||||
|
||||
**If the project has no test setup:** flag it and offer two options:
|
||||
- Option A: Set up a minimal test harness before proceeding (recommended)
|
||||
- Option B: Define the expected behaviour as a checklist of manual verification steps (faster but weaker)
|
||||
|
||||
**Test summary to show before writing implementation:**
|
||||
|
||||
```
|
||||
TESTS WRITTEN
|
||||
─────────────
|
||||
File: [test file path]
|
||||
Tests:
|
||||
✗ [test description — covers: happy path]
|
||||
✗ [test description — covers: edge case 1]
|
||||
✗ [test description — covers: edge case 2]
|
||||
✗ [test description — covers: error state]
|
||||
|
||||
All tests failing as expected. Starting implementation.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Stage 4 — Double Review
|
||||
|
||||
After completing the code and running tests, Claude reviews its own work twice before presenting it. Neither review is a formality.
|
||||
|
||||
**Review 1 — "Does this match what was asked for?"**
|
||||
|
||||
Check the completed code against the original request and confirmed plan:
|
||||
- Does it do everything that was asked?
|
||||
- Does it handle all edge cases from the plan?
|
||||
- Are there any mismatches between what was planned and what was built?
|
||||
- Are there any assumptions baked in that weren't confirmed?
|
||||
|
||||
**Review 2 — "Is this good code?"**
|
||||
|
||||
Check for technical quality independent of the requirements:
|
||||
- Obvious bugs or logic errors
|
||||
- Missing error handling (especially at boundaries: API calls, file I/O, user input)
|
||||
- Security issues (injection vulnerabilities, exposed secrets, missing auth checks)
|
||||
- Readability: would another developer understand this in 6 months?
|
||||
- Performance: any obvious inefficiencies on the critical path?
|
||||
- Dead code or unused imports introduced
|
||||
|
||||
**Double Review output format:**
|
||||
|
||||
```
|
||||
REVIEW 1 — CORRECTNESS
|
||||
───────────────────────
|
||||
✅ Handles [requirement 1]
|
||||
✅ Handles [requirement 2]
|
||||
✅ Edge case [X] covered
|
||||
⚠️ [Issue found — what it is and what was changed to fix it]
|
||||
|
||||
REVIEW 2 — CODE QUALITY
|
||||
────────────────────────
|
||||
✅ Error handling present at all API boundaries
|
||||
✅ No obvious security issues
|
||||
⚠️ [Issue found — what it was and how it was fixed]
|
||||
✅ Readable — no unexplained complexity
|
||||
|
||||
VERDICT: [Ready to present / Fixed N issues before presenting]
|
||||
```
|
||||
|
||||
If issues are found in either review, fix them and note what was fixed. Present the corrected version, not the original draft.
|
||||
|
||||
---
|
||||
|
||||
## Activation Response
|
||||
|
||||
When the user triggers Superpowers mode, respond with:
|
||||
|
||||
```
|
||||
Superpowers mode active.
|
||||
|
||||
I'll work in 4 stages for every coding task this session:
|
||||
1. PLAN — Write a plan and wait for your confirmation before coding
|
||||
2. ISOLATE — Work on a branch; nothing ships until you approve
|
||||
3. TEST — Write tests before the implementation
|
||||
4. REVIEW — Review my own work twice before presenting it
|
||||
|
||||
What are we building?
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Output Structure
|
||||
|
||||
### Full task flow (all four stages)
|
||||
|
||||
```
|
||||
PLAN
|
||||
════
|
||||
[Plan format as above]
|
||||
Confirm this plan before I start coding.
|
||||
|
||||
---
|
||||
[User confirms]
|
||||
---
|
||||
|
||||
ISOLATE
|
||||
Working in isolation on branch: superpowers/[task-slug]
|
||||
|
||||
TESTS WRITTEN
|
||||
─────────────
|
||||
[Test summary — all failing]
|
||||
Starting implementation.
|
||||
|
||||
---
|
||||
[Implementation runs]
|
||||
---
|
||||
|
||||
REVIEW 1 — CORRECTNESS
|
||||
───────────────────────
|
||||
[Checklist]
|
||||
|
||||
REVIEW 2 — CODE QUALITY
|
||||
────────────────────────
|
||||
[Checklist]
|
||||
|
||||
VERDICT: Ready to present.
|
||||
|
||||
---
|
||||
|
||||
COMPLETE
|
||||
════════
|
||||
[Summary of what was built, files created/modified, how to run/test it]
|
||||
Branch: superpowers/[task-slug] — merge when ready.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## CLAUDE.md Installation Text
|
||||
|
||||
After activating Superpowers for the session, provide the user with the exact text to add to their `CLAUDE.md` to make it permanent:
|
||||
|
||||
````
|
||||
```
|
||||
## Superpowers Framework
|
||||
|
||||
This framework is always active for coding tasks in this project.
|
||||
|
||||
### Stage 1 — Plan
|
||||
Before writing any code: produce a written plan including task restatement, approach, files to create/modify, edge cases to handle, and assumptions. Wait for explicit user confirmation before proceeding.
|
||||
|
||||
### Stage 2 — Isolate
|
||||
Work on a feature branch (superpowers/[task-slug]) or clearly flagged working copy. Nothing is considered shipped until the user approves after Stage 4.
|
||||
|
||||
### Stage 3 — Test First
|
||||
Write tests before writing the implementation. Tests should fail before implementation, pass after. If no test setup exists, offer to create one or produce a manual verification checklist.
|
||||
|
||||
### Stage 4 — Double Review
|
||||
After completing code, run two reviews before presenting:
|
||||
- Review 1: Does this match what was asked for? Check against original request and plan.
|
||||
- Review 2: Is this good code? Check for bugs, missing error handling, security issues, readability.
|
||||
Fix any issues found. Present the corrected version. Show the review checklist.
|
||||
```
|
||||
````
|
||||
|
||||
Tell the user: "Add this to your CLAUDE.md and Superpowers will be active permanently for this project."
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Stage 1 plan was shown and user explicitly confirmed before any code was written
|
||||
- [ ] Plan includes: task restatement, approach, files to modify, edge cases in scope, edge cases out of scope, assumptions
|
||||
- [ ] Ambiguities in the original request were flagged in the plan (not silently assumed)
|
||||
- [ ] Stage 2 isolation: a feature branch was created (or flagged as working copy if no git)
|
||||
- [ ] Stage 3 tests were written before implementation — not after
|
||||
- [ ] Tests were run and confirmed to be failing before implementation started
|
||||
- [ ] Stage 4 Review 1 checked against the original request — not just against the plan
|
||||
- [ ] Stage 4 Review 2 checked for bugs, error handling, security, readability — all four
|
||||
- [ ] Issues found in either review were fixed before presenting — not flagged as "things to fix later"
|
||||
- [ ] Final output shows what was built, which files were changed, and how to run/test it
|
||||
- [ ] CLAUDE.md installation text was offered after activation
|
||||
|
||||
---
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- "Enable superpowers mode"
|
||||
- "Activate superpowers"
|
||||
- "Turn on superpowers for this session"
|
||||
- "Use the superpowers framework"
|
||||
- "Make sure you plan before coding"
|
||||
- "I want you to review your work before showing me"
|
||||
- "Write tests first this time"
|
||||
- "Slow down and plan it out before you start building"
|
||||
- "Work on a branch and show me a plan before touching anything"
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: code-review-checklist
|
||||
description: "Generate a tailored code review checklist for any pull request based on the language, type of change, and risk level. Use when asked to review code, check a PR, review a pull request, or generate a code review checklist. Produces a focused checklist with language-specific checks, risk-level-appropriate depth, and a clear approve/request-changes recommendation. Optimised for Opus 4.7 and newer models."
|
||||
description: "Generate a tailored code review checklist for any pull request based on the language, type of change, and risk level. Use when asked to review code, check a PR, review a pull request, or generate a code review checklist. Produces a focused checklist with language-specific checks, risk-level-appropriate depth, and a clear approve/request-changes recommendation."
|
||||
---
|
||||
|
||||
# Code Review Checklist Skill
|
||||
@@ -14,15 +14,19 @@ Ask the user for these if not provided:
|
||||
- **Type of change** (feature / bug fix / refactor / dependency upgrade / security patch / performance)
|
||||
- **Risk level** (low / medium / high / critical)
|
||||
- **PR description** (paste the description or link to the PR)
|
||||
- **Code or diff** (optional — paste key changed files or a `git diff`; significantly improves checklist specificity)
|
||||
- **Author context** (new starter / experienced / external contributor)
|
||||
|
||||
## Output Structure
|
||||
## Output Format
|
||||
|
||||
### 1. Review Summary
|
||||
**PR:** [Title or reference]
|
||||
---
|
||||
|
||||
# Code Review: [PR Title or Reference]
|
||||
|
||||
### 1. PR Overview
|
||||
**Scope assessment:** [Small / Medium / Large / Too large — should be split]
|
||||
**Recommended review depth:** [Skim / Standard / Deep dive]
|
||||
**Estimated review time:** [Minutes]
|
||||
**Estimated review time:** [e.g. 20–30 min — use 5 min per 50 lines of diff as a rough guide]
|
||||
|
||||
### 2. Correctness Checks
|
||||
|
||||
@@ -94,14 +98,17 @@ Language-specific correctness checks — choose based on the language stated:
|
||||
### 7. Common Pitfalls for This Change Type
|
||||
Based on the change type and language, flag 2-3 things reviewers typically miss for this combination.
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
- [ ] Checklist is tailored to the stated language (not generic)
|
||||
- [ ] Change-type-specific section is included
|
||||
- [ ] Risk-appropriate depth matches stated risk level
|
||||
- [ ] Decision framework is explicit
|
||||
- [ ] Decision framework includes at least one named blocking condition and one named non-blocking comment condition
|
||||
- [ ] Common pitfalls are specific to the stated language + change-type combo (not generic advice like "watch out for bugs")
|
||||
|
||||
## Example Trigger Phrases
|
||||
## Usage Examples
|
||||
- "Generate a code review checklist for [PR description]"
|
||||
- "What should I check in this pull request?"
|
||||
- "Give me a code review checklist for a [language] [change type]"
|
||||
- "Review checklist for a high-risk PR in [language]"
|
||||
- "Review checklist for a high-risk PR in [language]"
|
||||
|
||||
@@ -0,0 +1,248 @@
|
||||
---
|
||||
name: context-mode
|
||||
description: "Activate output filtering, session logging, and auto-resume to keep Claude Code sessions running for hours without context bloat or memory loss. Use when asked to enable context mode, turn on long session mode, or activate session persistence. Installs a session log at project root, filters verbose command output before it enters context, and auto-resumes after Claude resets."
|
||||
---
|
||||
|
||||
# Context Mode Skill
|
||||
|
||||
Fix the two session killers that end most Claude Code sessions in under 30 minutes: context bloat from raw command output, and memory loss after a reset.
|
||||
|
||||
Context Mode runs three systems simultaneously to keep sessions alive:
|
||||
|
||||
- **Output Filtering** — strips verbose command output before it enters context
|
||||
- **Session Log** — writes a running log of everything that happened
|
||||
- **Auto-Resume** — reads the log on reset and picks up exactly where you left off
|
||||
|
||||
> **Credit:** Inspired by a skill from Nate Herk's YouTube channel — adapted and extended for this library.
|
||||
|
||||
---
|
||||
|
||||
## Required Inputs
|
||||
|
||||
No inputs required. Context Mode activates on command.
|
||||
|
||||
Optional: user can specify a custom log file path if they don't want `session.log` in the project root.
|
||||
|
||||
---
|
||||
|
||||
## How Context Mode Works
|
||||
|
||||
### Part 1 — Output Filtering
|
||||
|
||||
The problem: every time Claude Code runs a command, the full raw output enters the context window. A single `npm install` can dump hundreds of lines. A test suite run? Thousands. Within 30 minutes, the context is full of noise and Claude resets.
|
||||
|
||||
The fix: before any command output enters context, filter it to the useful summary only.
|
||||
|
||||
**What gets kept:**
|
||||
- Last 10 lines of stdout
|
||||
- Every line containing `error`, `warn`, `fail`, `exception`, `traceback`, or `fatal` (case-insensitive)
|
||||
- The exit code
|
||||
- A one-line summary of what the command did and whether it succeeded
|
||||
|
||||
**What gets discarded:**
|
||||
- Middle section of long stdout (replaced with `[... N lines of output truncated ...]`)
|
||||
- Progress bars, download indicators, verbose install logs
|
||||
- Repeated identical lines (deduplicated)
|
||||
|
||||
**Filtering summary format:**
|
||||
|
||||
```
|
||||
COMMAND: [command run]
|
||||
STATUS: [exit code — success / failed]
|
||||
SUMMARY: [one sentence: what happened]
|
||||
ERRORS: [any error/warn lines — or "none"]
|
||||
TAIL: [last 10 lines of stdout]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Part 2 — Session Log
|
||||
|
||||
Claude maintains a running log file at `[project root]/session.log`. This file is written after every significant action and is the source of truth for resuming after a reset.
|
||||
|
||||
**Session log format:**
|
||||
|
||||
```
|
||||
SESSION LOG
|
||||
===========
|
||||
Started: [timestamp]
|
||||
Branch: [current git branch]
|
||||
Directory: [working directory]
|
||||
|
||||
FILES EDITED
|
||||
────────────
|
||||
[timestamp] [file path] — [one-line description of what changed]
|
||||
|
||||
COMMANDS RUN
|
||||
────────────
|
||||
[timestamp] [command] — [outcome: success / failed — brief reason]
|
||||
|
||||
TASKS IN PROGRESS
|
||||
─────────────────
|
||||
[ ] [Task description — what's been done so far and what's left]
|
||||
[x] [Completed task]
|
||||
|
||||
LAST USER PROMPT
|
||||
────────────────
|
||||
[The most recent instruction from the user, verbatim]
|
||||
|
||||
LAST ACTION TAKEN
|
||||
─────────────────
|
||||
[What Claude did last, in one sentence]
|
||||
```
|
||||
|
||||
**Log update rules:**
|
||||
- Write to `session.log` after every file edit
|
||||
- Write to `session.log` after every command run
|
||||
- Update "Tasks in Progress" when a task is started, progressed, or completed
|
||||
- Always overwrite "Last User Prompt" and "Last Action Taken" with the current values — don't append, replace
|
||||
|
||||
---
|
||||
|
||||
### Part 3 — Resume on Reset
|
||||
|
||||
When a new Claude session starts, the first action is:
|
||||
|
||||
1. Check for `session.log` in the project root
|
||||
2. If found, read it and announce the resume:
|
||||
|
||||
```
|
||||
Resuming session.
|
||||
|
||||
Branch: [branch]
|
||||
Last working on: [last task in progress]
|
||||
Files edited: [list from session log]
|
||||
Tasks pending: [incomplete tasks]
|
||||
Last prompt: "[last user prompt]"
|
||||
|
||||
Continuing from where we left off.
|
||||
```
|
||||
|
||||
3. Continue with the next logical step — don't ask "what should I do?" — check the task list and carry on
|
||||
|
||||
If no `session.log` exists, start fresh and initialise the log.
|
||||
|
||||
---
|
||||
|
||||
## Activation Response
|
||||
|
||||
When the user triggers Context Mode, respond with:
|
||||
|
||||
```
|
||||
Context Mode active.
|
||||
|
||||
Session log initialised at: [absolute path to session.log]
|
||||
Output filtering: enabled
|
||||
Auto-resume: enabled
|
||||
|
||||
I'll maintain your session state across resets. Long sessions won't lose context.
|
||||
```
|
||||
|
||||
Then immediately initialise `session.log` with the current timestamp, branch, and directory.
|
||||
|
||||
---
|
||||
|
||||
## Output Structure
|
||||
|
||||
### On activation
|
||||
|
||||
```
|
||||
Context Mode active.
|
||||
Session log initialised at: [path]
|
||||
Output filtering: enabled
|
||||
Auto-resume: enabled
|
||||
I'll maintain your session state across resets. Long sessions won't lose context.
|
||||
```
|
||||
|
||||
### On command execution (filtered output format)
|
||||
|
||||
```
|
||||
COMMAND: npm test
|
||||
STATUS: exit 1 — failed
|
||||
SUMMARY: 47 tests passed, 3 failed in auth.test.ts
|
||||
ERRORS: Error: Expected 200, received 401 (line 84)
|
||||
Error: Token not found in response (line 112)
|
||||
TAIL:
|
||||
✓ login with valid credentials (23ms)
|
||||
✓ logout clears session (11ms)
|
||||
✗ refresh token after expiry
|
||||
...
|
||||
```
|
||||
|
||||
### On reset / new session (resume announcement)
|
||||
|
||||
```
|
||||
Resuming session.
|
||||
|
||||
Branch: feature/auth-refresh
|
||||
Last working on: Fixing token refresh logic in auth.service.ts
|
||||
Files edited: src/auth/auth.service.ts, src/auth/auth.test.ts
|
||||
Tasks pending: [ ] Fix failing test on line 112
|
||||
[ ] Run full test suite once fix is applied
|
||||
Last prompt: "The refresh token test is still failing — look at the 401 handling"
|
||||
|
||||
Continuing from where we left off.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## CLAUDE.md Installation Text
|
||||
|
||||
After activating Context Mode for the session, provide the user with the exact text to add to their `CLAUDE.md` to make it permanent across all sessions:
|
||||
|
||||
````
|
||||
```
|
||||
## Context Mode
|
||||
|
||||
Context Mode is always active in this project.
|
||||
|
||||
### Output Filtering
|
||||
Before any command output enters context, filter it to:
|
||||
- Last 10 lines of stdout
|
||||
- Any lines containing: error, warn, fail, exception, traceback, fatal (case-insensitive)
|
||||
- Exit code
|
||||
- One-line summary of what the command did
|
||||
|
||||
Use this format for filtered output:
|
||||
COMMAND: [command]
|
||||
STATUS: [exit code — success/failed]
|
||||
SUMMARY: [one sentence]
|
||||
ERRORS: [error lines or "none"]
|
||||
TAIL: [last 10 lines]
|
||||
|
||||
### Session Log
|
||||
Maintain a running session log at ./session.log. Write to it after every file edit and every command run. Track: files edited, commands run, tasks in progress, last user prompt, last action taken. Format defined in Context Mode skill.
|
||||
|
||||
### Auto-Resume
|
||||
At the start of every new session, check for ./session.log. If it exists, read it and announce the resume state. Continue from the last task in progress without asking for instructions.
|
||||
```
|
||||
````
|
||||
|
||||
Tell the user: "Add this to your CLAUDE.md and Context Mode will be active permanently for this project — even after you close and reopen the session."
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] `session.log` was initialised immediately on activation (not deferred)
|
||||
- [ ] Log path shown to user is the absolute path, not relative
|
||||
- [ ] Output filtering is applied on the very next command run — not just announced
|
||||
- [ ] Filtered output format includes: command, status, summary, errors, and tail — all five fields
|
||||
- [ ] Session log tracks all four categories: files edited, commands run, tasks in progress, last prompt
|
||||
- [ ] Resume announcement reads the actual log contents — not a generic template
|
||||
- [ ] On resume, Claude continues the work without prompting the user for instructions
|
||||
- [ ] CLAUDE.md installation text was offered after activation
|
||||
- [ ] Log update rule is clear: "Last User Prompt" and "Last Action Taken" replace previous values, not append
|
||||
|
||||
---
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- "Enable context mode"
|
||||
- "Turn on context mode for this session"
|
||||
- "Activate long session mode"
|
||||
- "I keep losing context — fix it"
|
||||
- "Set up session logging"
|
||||
- "Keep track of what you've done so you can resume after a reset"
|
||||
- "Enable output filtering to save context"
|
||||
- "Set up auto-resume so we don't lose our place"
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: debugging-log-analyser
|
||||
description: "Parse error logs, stack traces, and crash reports into a structured root cause diagnosis. Use when sharing a log, stack trace, error output, or crash dump. Produces a structured diagnosis with probable root cause, affected code path, suggested fix, and next debugging steps. Optimised for Opus 4.7 and newer models."
|
||||
description: "Parse error logs, stack traces, and crash reports into a structured root cause diagnosis. Use when sharing a log, stack trace, error output, or crash dump. Produces a structured diagnosis with probable root cause, affected code path, suggested fix, and next debugging steps."
|
||||
---
|
||||
|
||||
# Debugging Log Analyser Skill
|
||||
@@ -12,14 +12,19 @@ Parses raw error logs, stack traces, and crash reports into a structured diagnos
|
||||
Ask for these if not provided:
|
||||
- **The log / stack trace / error output** (paste directly or describe the error)
|
||||
- **Language and framework** (e.g. Node.js + Express, Python + Django, Java Spring, Go)
|
||||
- **Context** (what the user was doing when the error occurred)
|
||||
- **Context** (what changed before this started — e.g. recent deploy, config change, increased traffic, new input data; or "nothing changed" is also useful)
|
||||
- **Frequency** (one-off / intermittent / consistent / regression after a specific change)
|
||||
- **Environment** (local dev / staging / production)
|
||||
- **What they've already tried** (if anything)
|
||||
|
||||
## Output Structure
|
||||
## Output Format
|
||||
|
||||
---
|
||||
|
||||
# Debugging Report: [Service/App Name]
|
||||
|
||||
### 1. Error Classification
|
||||
**Error type:** [Runtime exception / Build error / Config error / Network error / Memory/resource error / Unknown]
|
||||
**Error type:** [Runtime exception / Build error / Config error / Network error / Memory error / Unknown]
|
||||
**Severity:** [Fatal / Critical / Warning / Informational]
|
||||
**Recurrence pattern:** [One-off / Intermittent / Consistent / On-startup / Under load]
|
||||
|
||||
@@ -64,14 +69,17 @@ One or two concrete things that would prevent this class of error recurring:
|
||||
- Add monitoring/alerting for [condition]
|
||||
- Test that covers [scenario]
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
- [ ] Root cause is specific (not "there might be a null pointer issue")
|
||||
- [ ] At least one concrete code-level fix is suggested
|
||||
- [ ] Next steps are actionable commands, not vague advice
|
||||
- [ ] Language-specific idioms are used correctly
|
||||
- [ ] Suggested fix references the actual language/framework in the input (not a generic fix that could apply to any language)
|
||||
- [ ] Confidence level includes a stated reason (not just "High" or "Low" with no explanation)
|
||||
- [ ] Prevention is proactive (not just "add error handling")
|
||||
|
||||
## Example Trigger Phrases
|
||||
## Usage Examples
|
||||
- "Why is this crashing?" + [paste log]
|
||||
- "Can you analyse this stack trace?"
|
||||
- "I'm getting this error, what does it mean?"
|
||||
|
||||
@@ -5,7 +5,7 @@ description: "Write a structured incident postmortem or post-incident review. Us
|
||||
|
||||
# Incident Postmortem Skill
|
||||
|
||||
This skill produces a complete, blameless incident postmortem document following industry-standard format. Output is ready to share with engineering teams, leadership, and affected stakeholders.
|
||||
This skill produces a complete, blameless incident postmortem document following industry-standard format. Output enforces blameless framing throughout — system gaps over individual failures — and drives toward specific, closeable action items rather than vague process commitments.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
@@ -20,8 +20,10 @@ Ask the user for these if not provided:
|
||||
- **How it was resolved**
|
||||
- **Initial thoughts on root cause**
|
||||
- **Action items already identified** (optional)
|
||||
- **Responders** (who was on-call or responded — names or roles; used for the timeline, not for blame)
|
||||
- **Customer or external communications sent** (optional — any status page updates, emails, or support messages with timestamps)
|
||||
|
||||
## Output Structure
|
||||
## Output Format
|
||||
|
||||
---
|
||||
|
||||
@@ -131,13 +133,14 @@ Rules for action items:
|
||||
|
||||
- [ ] Timeline has no blame-focused language
|
||||
- [ ] Root cause is specific (not "human error")
|
||||
- [ ] Root cause answers "why did this happen?" not just "what happened?" — it names a system or process gap, not a symptom
|
||||
- [ ] Contributing factors explain the systemic gaps
|
||||
- [ ] Every action item has an owner and due date
|
||||
- [ ] "What went well" section is genuine, not token
|
||||
- [ ] No action item contains vague language like "improve monitoring", "increase resilience", or "better testing" — each must name a specific change
|
||||
- [ ] Executive summary is readable by non-technical leadership
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
## Usage Examples
|
||||
- "Write a postmortem for the [incident name] outage"
|
||||
- "Help me write a P1 incident report"
|
||||
- "Generate an RCA document for [service] going down on [date]"
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: pr-description-writer
|
||||
description: "Write a clear, structured pull request description from a git diff, branch summary, or commit list. Use when asked to write a PR description, draft a pull request, or document code changes. Produces a description with summary, motivation, changes made, testing steps, and reviewer guidance. Optimised for Opus 4.7 and newer models."
|
||||
description: "Write a clear, structured pull request description from a git diff, branch summary, or commit list. Use when asked to write a PR description, draft a pull request, or document code changes. Produces a description with summary, motivation, changes made, testing steps, and reviewer guidance."
|
||||
---
|
||||
|
||||
# PR Description Writer Skill
|
||||
@@ -15,8 +15,10 @@ Ask for these if not provided:
|
||||
- **How to test it** (any specific steps a reviewer needs to verify it works)
|
||||
- **Risk level** (low / medium / high — affects how much reviewer guidance to include)
|
||||
- **PR type** (feature / bug fix / refactor / dependency upgrade / config change / hotfix)
|
||||
- **Target branch** (e.g. main / develop / release/2.4 — affects risk framing and reviewer guidance)
|
||||
- **Linked issue or ticket** (e.g. JIRA-1234, GitHub #567 — or "none")
|
||||
|
||||
## Output Structure
|
||||
## Output Format
|
||||
|
||||
### Title
|
||||
A clear, imperative-mood title under 72 characters:
|
||||
@@ -43,7 +45,7 @@ Bullet list of specific changes — one bullet per logical change, not per file:
|
||||
### Screenshots / Demo
|
||||
[If UI change: include before/after screenshots or a screen recording]
|
||||
[If API change: include example request/response]
|
||||
[If no visual change: this section can be omitted]
|
||||
[If no visual change and no API contract change: omit this section entirely — do not leave it as a placeholder]
|
||||
|
||||
### How to Test
|
||||
Step-by-step instructions a reviewer can follow:
|
||||
@@ -76,10 +78,11 @@ Flag anything that warrants extra attention:
|
||||
- [ ] Title is imperative mood and under 72 characters
|
||||
- [ ] Summary explains what AND why (not just what)
|
||||
- [ ] Changes list describes logical changes (not file-by-file changes)
|
||||
- [ ] Title starts with a valid type prefix (feat / fix / refactor / chore / deps / config / hotfix) and is under 72 characters
|
||||
- [ ] Testing steps are reproducible by someone unfamiliar with the code
|
||||
- [ ] Risk-appropriate reviewer guidance is included
|
||||
- [ ] For high-risk PRs, Reviewer Notes flags at least one specific area of concern or deliberate trade-off; for low-risk PRs, Reviewer Notes is either omitted or kept to one line
|
||||
|
||||
## Example Trigger Phrases
|
||||
## Usage Examples
|
||||
- "Write a PR description for these changes" + [paste diff or description]
|
||||
- "Draft a pull request for [feature]"
|
||||
- "I need a PR description — here's what I changed"
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: runbook-writer
|
||||
description: "Write an operational runbook for a service, incident type, or deployment procedure. Use when asked to write a runbook, create an ops guide, document an operational procedure, or prepare an incident response playbook. Produces a runbook with overview, prerequisites, step-by-step procedures, rollback steps, troubleshooting table, and escalation paths. Optimised for Opus 4.7 and newer models."
|
||||
description: "Write an operational runbook for a service, incident type, or deployment procedure. Use when asked to write a runbook, create an ops guide, document an operational procedure, or prepare an incident response playbook. Produces a runbook with overview, prerequisites, step-by-step procedures, rollback steps, troubleshooting table, and escalation paths."
|
||||
---
|
||||
|
||||
# Runbook Writer Skill
|
||||
@@ -15,14 +15,16 @@ Ask for these if not provided:
|
||||
- **System/service name and what it does** (brief description)
|
||||
- **Audience** (new on-call engineers / experienced SREs / DevOps team)
|
||||
- **Tech stack** (where relevant — e.g. Kubernetes, AWS RDS, Node.js)
|
||||
- **Monitoring tools** (e.g. Grafana, Datadog, CloudWatch, Splunk — used to name specific dashboards and alert links in the steps)
|
||||
- **Key environment details** (e.g. Kubernetes cluster name, AWS account/region, relevant namespaces or resource names — paste what's relevant for exact commands)
|
||||
|
||||
## Output Structure
|
||||
## Output Format
|
||||
|
||||
---
|
||||
**Runbook:** [Runbook Title]
|
||||
**Service:** [Service Name]
|
||||
**Type:** [Deployment / Incident Response / Maintenance / DR]
|
||||
**Last Updated:** [Date]
|
||||
**Last Updated:** [Insert today's date in YYYY-MM-DD format]
|
||||
**Owner:** [Team or person]
|
||||
**Severity:** [P1 / P2 / P3 — if incident-type]
|
||||
|
||||
@@ -133,10 +135,11 @@ After completing the runbook:
|
||||
- [ ] Expected output is specified for each step so engineer knows if it worked
|
||||
- [ ] Failure path is explicit for each step (not "if it fails, investigate")
|
||||
- [ ] Rollback procedure is complete and independently testable
|
||||
- [ ] Escalation paths name specific contacts, not just team names
|
||||
- [ ] Escalation table has no cells containing only "[Team name]" — every row must either have a real contact or be explicitly flagged as [FILL IN: on-call rotation link]
|
||||
- [ ] Rollback section contains at least one concrete command (not left as "[rollback command]" placeholder)
|
||||
- [ ] Runbook can be followed by someone who has never touched this system
|
||||
|
||||
## Example Trigger Phrases
|
||||
## Usage Examples
|
||||
- "Write a runbook for [service] deployment"
|
||||
- "Create an incident response runbook for [alert type]"
|
||||
- "I need a runbook for [procedure]"
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: system-design-interview
|
||||
description: "Structure a complete system design answer for interview questions or real architecture sessions. Use when asked to design a system, answer a system design interview question, or architect a solution at scale. Produces a structured answer covering requirements, capacity estimates, high-level design, component deep-dives, trade-offs, and follow-up considerations. Optimised for Opus 4.7 and newer models."
|
||||
description: "Structure a complete system design answer for interview questions or real architecture sessions. Use when asked to design a system, answer a system design interview question, or architect a solution at scale. Produces a structured answer covering requirements, capacity estimates, high-level design, component deep-dives, trade-offs, and follow-up considerations."
|
||||
---
|
||||
|
||||
# System Design Interview Skill
|
||||
@@ -14,8 +14,10 @@ Ask for these if not provided:
|
||||
- **Scope** (interview prep / real architecture decision / practice run)
|
||||
- **Scale target** (rough numbers: DAU, requests/sec, data volume — or "assume typical web scale")
|
||||
- **Constraints or priorities** (e.g. prioritise availability over consistency, minimise cost, low-latency reads)
|
||||
- **Time available** (interview context only: 30 / 45 / 60 minutes — skip for real architecture sessions)
|
||||
- **Emphasis** (optional — any area to go deeper on, e.g. "focus on the DB design" or "spend more time on scaling")
|
||||
|
||||
## Output Structure
|
||||
## Output Format
|
||||
|
||||
### 1. Clarifying Questions
|
||||
Before designing, list 4–6 questions that would change the design. Examples:
|
||||
@@ -62,12 +64,7 @@ Then proceed with stated assumptions if answering an interview question.
|
||||
|
||||
### 5. High-Level Architecture
|
||||
|
||||
```
|
||||
[Client] → [CDN/Edge] → [Load Balancer] → [API Servers] → [Cache] → [DB]
|
||||
→ [Message Queue] → [Workers]
|
||||
```
|
||||
|
||||
Describe each layer in 1–2 sentences explaining its role and technology choice.
|
||||
Draw an ASCII diagram specific to this system. Do not default to the client→CDN→LB→API→Cache→DB template unless it genuinely applies. Label each component with the specific technology chosen (e.g. "Kafka" not "Message Queue", "PostgreSQL" not "DB"). Describe each component in 1–2 sentences explaining its role and why that technology was chosen.
|
||||
|
||||
### 6. Component Deep-Dive
|
||||
|
||||
@@ -122,12 +119,13 @@ Things to tackle in production but out of scope for this design session:
|
||||
|
||||
## Quality Checks
|
||||
- [ ] Clarifying questions are design-changing (not generic filler)
|
||||
- [ ] Capacity estimates use real numbers (not just "it scales")
|
||||
- [ ] Capacity estimates show the arithmetic: DAU → requests/day → requests/sec → storage per record → total storage, so the numbers can be sanity-checked
|
||||
- [ ] Every row in the Trade-offs table has a non-empty Trade-off column (no rows where the trade-off is blank or says "none")
|
||||
- [ ] At least 2 component deep-dives with technology choices justified
|
||||
- [ ] Trade-offs section is honest (not just benefits of chosen approach)
|
||||
- [ ] Data flow is described end-to-end for the critical path
|
||||
|
||||
## Example Trigger Phrases
|
||||
## Usage Examples
|
||||
- "Help me answer a system design interview: [question]"
|
||||
- "Design [system] for a system design interview"
|
||||
- "How would I architect [system] at scale?"
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: test-strategy-doc
|
||||
description: "Write a test strategy document from a feature spec, PRD, or system description. Use when asked to create a test plan, write a test strategy, define QA approach, or plan testing for a feature or release. Produces a complete test strategy with scope, risk assessment, test types, coverage targets, and a prioritised test case outline. Optimised for Opus 4.7 and newer models."
|
||||
description: "Write a test strategy document from a feature spec, PRD, or system description. Use when asked to create a test plan, write a test strategy, define QA approach, or plan testing for a feature or release. Produces a complete test strategy with scope, risk assessment, test types, coverage targets, and a prioritised test case outline."
|
||||
---
|
||||
|
||||
# Test Strategy Document Skill
|
||||
@@ -11,12 +11,14 @@ Produces a complete test strategy from a feature spec, PRD, or system descriptio
|
||||
|
||||
Ask for these if not provided:
|
||||
- **Feature or system being tested** (paste a spec, PRD, or describe it in plain English)
|
||||
- **Tech stack** (language, framework, testing tools already in use if known)
|
||||
- **Tech stack** (language and framework — e.g. TypeScript + React, Python + FastAPI)
|
||||
- **Existing test coverage** (e.g. "we have unit tests but no E2E tests", "we use Jest + Playwright already", or "starting from scratch")
|
||||
- **Deployment cadence** (e.g. continuous deployment / weekly releases / quarterly — affects what must be automated vs. manual)
|
||||
- **Risk level** (low / medium / high / critical — affects depth and coverage requirements)
|
||||
- **Timeline** (when does this need to ship — affects prioritisation)
|
||||
- **Team context** (who is doing the testing — developers / dedicated QA / both)
|
||||
|
||||
## Output Structure
|
||||
## Output Format
|
||||
|
||||
### 1. Test Scope
|
||||
|
||||
@@ -66,7 +68,7 @@ Identify the highest-risk areas first — these drive depth and coverage:
|
||||
- **Tools:** [e.g. Playwright, Cypress, Selenium]
|
||||
- **Focus areas:** [The 3–5 most critical user flows]
|
||||
|
||||
**Performance Tests** *(include only if risk is medium+)*
|
||||
**Performance Tests** *(include if any row in the Risk Assessment table has performance as a risk factor, regardless of overall risk level)*
|
||||
- **What:** Load, stress, or latency testing
|
||||
- **Targets:** [Specific numbers — e.g. 200 req/sec at p95 < 200ms]
|
||||
- **Tools:** [e.g. k6, Locust, JMeter]
|
||||
@@ -115,11 +117,12 @@ Testing is complete when:
|
||||
|
||||
## Quality Checks
|
||||
- [ ] Risk table is populated and drives test priority (not filled in generically)
|
||||
- [ ] P0 test cases cover the highest-risk paths specifically
|
||||
- [ ] Every "P0 — exhaustive" row in the Risk Assessment table has at least one corresponding P0 test case
|
||||
- [ ] "Out of scope" section names at least one explicit exclusion (not left blank)
|
||||
- [ ] Each test type names a concrete tool (not "some testing framework")
|
||||
- [ ] Definition of Done is measurable (not "tests are done when QA is happy")
|
||||
|
||||
## Example Trigger Phrases
|
||||
## Usage Examples
|
||||
- "Write a test strategy for [feature]" + [paste spec or PRD]
|
||||
- "Create a test plan for [system]"
|
||||
- "How should we test [feature]?"
|
||||
|
||||
@@ -0,0 +1,221 @@
|
||||
---
|
||||
name: product-positioning-doc
|
||||
description: "Write a product positioning document and messaging framework. Use when asked to define product positioning, write a positioning statement, build a messaging framework, or create a messaging hierarchy. Produces a complete positioning doc with category definition, target customer, differentiation, proof points, messaging pillars, and persona-specific messaging."
|
||||
---
|
||||
|
||||
# Product Positioning Doc Skill
|
||||
|
||||
This skill produces a complete product positioning document following the April Dunford positioning methodology. Output covers category definition, target customer, unique attributes, proof points, and a messaging hierarchy — ready to align GTM, marketing, sales, and product teams.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask the user for these if not provided:
|
||||
- **Product name** and what it does
|
||||
- **Target customer** — who is it for? (role, company type, size)
|
||||
- **Problem it solves** — what pain or goal does it address?
|
||||
- **Key alternatives** — what do customers use today instead? (not just direct competitors — include status quo, spreadsheets, DIY)
|
||||
- **Differentiation** — what does this product do that alternatives cannot? (not features — capabilities that produce different outcomes)
|
||||
- **Proof points** — any customer data, case studies, metrics, or validation?
|
||||
- **Business goal** — is positioning for a new category, expansion into new segment, or repositioning away from a declining category?
|
||||
|
||||
## Output Structure
|
||||
|
||||
---
|
||||
|
||||
# Positioning Document: [Product Name]
|
||||
|
||||
**Version:** [1.0]
|
||||
**Owner:** [PMM / Founder / Marketing lead]
|
||||
**Date:** [Date]
|
||||
**Status:** [Draft / Reviewed / Approved]
|
||||
**Approved by:** [Names — this document must be signed off by product, marketing, and sales leadership before use]
|
||||
|
||||
---
|
||||
|
||||
## 1. Background & Context
|
||||
|
||||
[2–3 sentences describing why positioning is being done now. Is this a new product, a pivot, a segment expansion, or a rebrand? What triggered this work?]
|
||||
|
||||
**Positioning objective:** [e.g. Move from being perceived as a reporting tool to being the category leader in revenue intelligence for mid-market SaaS]
|
||||
|
||||
---
|
||||
|
||||
## 2. Market Category
|
||||
|
||||
**What category does this product compete in?**
|
||||
|
||||
This is the frame of reference your customer uses to understand what the product is. Choose the wrong category and everything downstream — competitors, value, messaging — is wrong.
|
||||
|
||||
**Category:** [e.g. Customer data platform / Revenue intelligence / No-code automation / Modern data stack]
|
||||
|
||||
**Why this category, not [alternative category]?**
|
||||
[1–2 sentences on why this framing serves the customer's understanding better than adjacent categories]
|
||||
|
||||
**Category maturity:**
|
||||
- [ ] New category (we are creating it — high education burden, high upside if it works)
|
||||
- [ ] Growing category (fast-growing segment — compete on differentiation)
|
||||
- [ ] Mature category (well-understood — must disrupt with clear superiority or narrower niche)
|
||||
|
||||
---
|
||||
|
||||
## 3. Target Customer
|
||||
|
||||
**Be precise. Vague targeting produces vague positioning.**
|
||||
|
||||
| Dimension | Description |
|
||||
|---|---|
|
||||
| **Primary buyer / decision-maker** | [e.g. VP of Revenue Operations at B2B SaaS companies with 100–500 employees] |
|
||||
| **Primary user** | [e.g. Revenue operations analysts and sales ops managers] |
|
||||
| **Company profile** | [Industry, size, growth stage, technology stack] |
|
||||
| **Business context** | [What is happening in their world that makes them a buyer right now?] |
|
||||
| **Trigger event** | [What just happened that makes them start looking for a solution? — e.g. Sales team grew past 20 reps, forecast accuracy became a board question] |
|
||||
|
||||
**Who this is NOT for:**
|
||||
[Be explicit about who to exclude — this sharpens the positioning for those who are a fit]
|
||||
|
||||
---
|
||||
|
||||
## 4. Competitive Alternatives
|
||||
|
||||
What do buyers use today when they don't have your product? List all real alternatives — not just direct competitors.
|
||||
|
||||
| Alternative | Who uses it | Why buyers choose it | What they sacrifice |
|
||||
|---|---|---|---|
|
||||
| **[Direct competitor — e.g. Gong]** | [Enterprise sales teams] | [Market leader, strong brand, sales coaching features] | [Price, complexity, implementation time] |
|
||||
| **[Adjacent tool — e.g. Salesforce reports]** | [CRM-native users] | [Already have it, no additional cost] | [No AI analysis, manual reporting, siloed data] |
|
||||
| **[Status quo — e.g. spreadsheets + manual tracking]** | [SMB, early-stage] | [Free, flexible, no change management] | [Time-consuming, error-prone, not scalable] |
|
||||
| **[Build in-house]** | [Tech companies with data teams] | [Custom to their exact needs] | [Engineering cost, maintenance burden, 12+ month timeline] |
|
||||
|
||||
**Key insight:** [What does this competitive landscape tell you about what your positioning must emphasise? e.g. "Every alternative either costs too much or requires too much manual work — positioning must nail 'fast time to value' and 'right-sized for mid-market'"]
|
||||
|
||||
---
|
||||
|
||||
## 5. Unique Differentiated Attributes
|
||||
|
||||
These are the features or capabilities your product has that alternatives genuinely cannot match — or cannot match at the same level. Do not list features that competitors also have.
|
||||
|
||||
| Attribute | What it is | What it enables (outcome) | Why competitors can't match it |
|
||||
|---|---|---|---|
|
||||
| [e.g. Real-time CRM sync] | [Bidirectional sync with any CRM in <5 min] | [Reps see clean data in the tools they already use — no toggle between systems] | [Legacy competitors require 3-month integration projects; Salesforce-native tools only work in SFDC] |
|
||||
| [e.g. Natural language querying] | [Ask questions in plain English, get data visualisations] | [Anyone on the revenue team can answer their own questions without SQL or waiting for an analyst] | [BI tools require analyst training; direct competitors have rigid dashboards] |
|
||||
| [...] | [...] | [...] | [...] |
|
||||
|
||||
**The core differentiation thesis:**
|
||||
[1–2 sentences that unite the above attributes into a single "why we win" statement — this is internal language, not customer-facing yet]
|
||||
|
||||
---
|
||||
|
||||
## 6. Value Proof Points
|
||||
|
||||
Back up the differentiation claims with evidence:
|
||||
|
||||
| Claim | Proof point | Source |
|
||||
|---|---|---|
|
||||
| [Fastest time to value] | [Average customer is live in 4 hours vs 3 months for legacy alternatives] | [Customer data — average across [X] accounts] |
|
||||
| [Better forecast accuracy] | [Customers achieve X% improvement in forecast accuracy within 90 days] | [Case study: [Company Name] — link] |
|
||||
| [Loved by operators, not just managers] | [NPS of X among end users; 4.8/5 on G2 for ease of use] | [G2 reviews, internal NPS survey] |
|
||||
|
||||
**Proof gaps:** [Are there claims you're making that you don't yet have evidence for? List them — they are either research projects or risks to the positioning]
|
||||
|
||||
---
|
||||
|
||||
## 7. Positioning Statement
|
||||
|
||||
The classic positioning template — internal only, never used verbatim in marketing:
|
||||
|
||||
> **For** [target customer]
|
||||
> **who** [trigger event or problem statement],
|
||||
> **[Product name]** is a **[category]**
|
||||
> **that** [primary differentiated value — the outcome, not the feature].
|
||||
> **Unlike** [primary alternative],
|
||||
> **[Product name]** [the key thing that makes you different and better].
|
||||
|
||||
**Draft positioning statement:**
|
||||
> For [VP Revenue Ops at B2B SaaS companies with 50–500 reps] who [struggle to forecast accurately as the sales team scales], [Product Name] is a [revenue intelligence platform] that [gives every rep and manager accurate, real-time pipeline visibility without any analyst overhead]. Unlike [Salesforce dashboards and manual reporting], [Product Name] [syncs automatically, surfaces risks before they become missed quarters, and needs no configuration by IT or data teams].
|
||||
|
||||
---
|
||||
|
||||
## 8. Messaging Hierarchy
|
||||
|
||||
Translate the positioning into customer-facing language at three levels:
|
||||
|
||||
### Tagline (5–8 words)
|
||||
|
||||
[The simplest possible statement of what you do and for whom. Used in ads, hero sections, email signatures.]
|
||||
|
||||
Options to test:
|
||||
1. [e.g. "Revenue intelligence for scaling sales teams"]
|
||||
2. [e.g. "Forecast with confidence. Close with clarity."]
|
||||
3. [e.g. "The revenue platform your whole team will actually use"]
|
||||
|
||||
### Value Proposition (1–2 sentences)
|
||||
|
||||
[Used in the hero section of the website, email subject lines, and sales decks. Must be instantly clear.]
|
||||
|
||||
> [e.g. "[Product Name] gives revenue teams real-time pipeline visibility and accurate forecasting — without spreadsheets, custom reports, or waiting for an analyst. Get live in 4 hours, not 4 months."]
|
||||
|
||||
### Full Description (3–5 sentences)
|
||||
|
||||
[Used in PR, partnership briefs, longer sales emails, and About Us pages.]
|
||||
|
||||
> [e.g. "[Product Name] is the revenue intelligence platform built for mid-market SaaS teams. Unlike legacy BI tools that require analyst configuration or CRM dashboards that only show what's already happened, [Product Name] automatically syncs your entire revenue stack, surfaces AI-driven risk signals, and lets any rep or manager ask questions in plain English. [X] customers use [Product Name] to call their quarters with confidence. Average time to live: 4 hours."]
|
||||
|
||||
---
|
||||
|
||||
## 9. Persona-Specific Messaging
|
||||
|
||||
The core positioning is the same, but different buyers care about different aspects:
|
||||
|
||||
| Persona | Their primary concern | Lead message | Proof point to use |
|
||||
|---|---|---|---|
|
||||
| **VP Revenue Operations** | Forecast accuracy, board credibility | "Call your quarter with confidence" | [X% improvement in forecast accuracy across N customers] |
|
||||
| **Head of Sales** | Rep productivity, pipeline visibility | "Your reps close more, not admin more" | [X hours/week saved per rep] |
|
||||
| **CEO / CFO** | Revenue predictability, cost | "Stop being surprised by quarters" | [ROI: £X saved vs X headcount required to replicate manually] |
|
||||
| **Sales Rep** | Ease of use, not adding to workload | "It works in the tools you already use" | [Ease of use NPS, G2 reviews] |
|
||||
|
||||
---
|
||||
|
||||
## 10. Messaging Do's and Don'ts
|
||||
|
||||
**Do say:**
|
||||
- [Specific, outcome-focused language — what the customer achieves]
|
||||
- [Comparative language grounded in evidence]
|
||||
- [Language your target buyer uses to describe their problem — not language you invented]
|
||||
|
||||
**Don't say:**
|
||||
- ["Best-in-class", "innovative", "cutting-edge", "game-changing" — unless followed by evidence]
|
||||
- [Feature lists without outcome context]
|
||||
- [Jargon your buyer doesn't use themselves]
|
||||
- [Claims your competitors could also make]
|
||||
|
||||
---
|
||||
|
||||
## 11. Distribution Plan
|
||||
|
||||
Positioning only works if it's implemented consistently:
|
||||
|
||||
| Team | What they need | Format | Owner | When |
|
||||
|---|---|---|---|---|
|
||||
| Marketing | Tagline, value prop, messaging hierarchy | This doc + messaging playbook | PMM | [Date] |
|
||||
| Sales | Competitive positioning, objection responses | One-pager + deck | Sales enablement | [Date] |
|
||||
| Product | Category definition, target customer | Shared doc + roadmap input | PMM + PM | [Date] |
|
||||
| Leadership | Full positioning narrative | This doc | PMM | [Date] |
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Positioning statement has exactly one A — the product is accountable to exactly one primary differentiated claim
|
||||
- [ ] Competitive alternatives include the status quo — not just named competitors
|
||||
- [ ] Differentiated attributes describe outcomes, not features
|
||||
- [ ] Every proof point cites a source — not "customers say…"
|
||||
- [ ] Persona messaging uses the buyer's language, not the company's
|
||||
- [ ] At least two people from product, marketing, and sales have reviewed and approved
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- "Write a positioning document for [product]"
|
||||
- "Build a messaging framework for our B2B SaaS tool"
|
||||
- "Define our product positioning — who is this for and why should they care?"
|
||||
- "Create a positioning statement and messaging hierarchy for [launch]"
|
||||
- "Help me articulate our differentiation vs [Competitor]"
|
||||
@@ -0,0 +1,237 @@
|
||||
---
|
||||
name: social-media-strategy
|
||||
description: "Build a social media strategy for a brand, product, or creator. Use when asked to create a social media strategy, define a social content strategy, plan content pillars, set social KPIs, or build a posting framework. Produces a complete strategy with audience definition, platform selection, content pillars, posting cadence, KPIs, and a 4-week starter calendar."
|
||||
---
|
||||
|
||||
# Social Media Strategy Skill
|
||||
|
||||
This skill produces a complete social media strategy covering audience definition, platform rationale, content pillars, posting cadence, tone of voice guidelines, measurement framework, and a 4-week starter content calendar. Output is ready for a marketing team, founder, or agency to execute immediately.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask the user for these if not provided:
|
||||
- **Brand / product / creator name**
|
||||
- **What you're promoting** — product, service, personal brand, community, or event
|
||||
- **Target audience** — who are you trying to reach? (job title, age, interests, platforms they use)
|
||||
- **Business goal** — what does social need to achieve? (brand awareness / lead generation / community building / sales / recruitment)
|
||||
- **Current social presence** — which platforms are you on? What's working, what isn't?
|
||||
- **Competitors or aspirational accounts** — who does social well in your space?
|
||||
- **Resources** — how many people and how much time per week can you dedicate to social?
|
||||
|
||||
## Output Structure
|
||||
|
||||
---
|
||||
|
||||
# Social Media Strategy: [Brand / Product / Creator]
|
||||
|
||||
**Goal:** [Primary business goal]
|
||||
**Audience:** [1-sentence description of primary audience]
|
||||
**Timeframe:** [e.g. Q3 2026 — 3-month strategy]
|
||||
**Owner:** [Marketing lead / founder / social team]
|
||||
**Date:** [Date]
|
||||
|
||||
---
|
||||
|
||||
## 1. Audience Profile
|
||||
|
||||
**Primary audience:**
|
||||
|
||||
| Dimension | Detail |
|
||||
|---|---|
|
||||
| **Who they are** | [Job title, age range, life stage, geography] |
|
||||
| **What they care about** | [Professional or personal priorities, pain points] |
|
||||
| **Where they spend time online** | [Platforms, communities, influencers they follow] |
|
||||
| **What they consume** | [Content formats they engage with — video, threads, newsletters, podcasts] |
|
||||
| **What would make them follow you** | [The specific value proposition of your social presence] |
|
||||
|
||||
**Secondary audience:** [Any secondary segment — e.g. job seekers if you're a brand, investors if you're a startup]
|
||||
|
||||
---
|
||||
|
||||
## 2. Platform Strategy
|
||||
|
||||
Not every platform is right for every brand. Justify each platform choice:
|
||||
|
||||
| Platform | Audience fit | Content format | Priority | Why (or why not) |
|
||||
|---|---|---|---|---|
|
||||
| **LinkedIn** | [B2B / professional] | [Text posts, carousels, articles] | [Primary / Secondary / Skip] | [e.g. Primary platform for B2B SaaS — where buyers and influencers are] |
|
||||
| **X / Twitter** | [Tech, media, founders] | [Short text, threads, replies] | [...] | [...] |
|
||||
| **Instagram** | [Consumer, visual brands, creators] | [Reels, Stories, carousels] | [...] | [...] |
|
||||
| **TikTok** | [B2C, Gen Z, consumer] | [Short-form video] | [...] | [...] |
|
||||
| **YouTube** | [All audiences — discovery + long-form] | [Long-form video, Shorts] | [...] | [...] |
|
||||
| **Threads** | [Text-first, creator, early adopter] | [Short text, conversations] | [...] | [...] |
|
||||
|
||||
**Lead platform:** [One platform to invest most heavily in — where your audience is most active and where you have the best chance to stand out]
|
||||
|
||||
**Supporting platforms:** [1–2 secondary platforms where you'll repurpose or adapt content]
|
||||
|
||||
---
|
||||
|
||||
## 3. Content Pillars
|
||||
|
||||
Define 3–5 content themes that anchor your social presence. Each pillar must serve the audience, not just the brand.
|
||||
|
||||
### Pillar 1: [Name — e.g. "Behind the build"]
|
||||
|
||||
**What it is:** [1-sentence description]
|
||||
**Why the audience cares:** [What value does this deliver to them?]
|
||||
**Content examples:**
|
||||
- [e.g. Engineering decisions we made and why]
|
||||
- [e.g. Week-in-the-life of the founding team]
|
||||
- [e.g. What we shipped this week and what we learned]
|
||||
|
||||
**Format mix:** [Carousel / video / thread / short-form text]
|
||||
**Posting cadence:** [X times per week]
|
||||
|
||||
---
|
||||
|
||||
### Pillar 2: [Name — e.g. "Practical education"]
|
||||
|
||||
**What it is:** [...]
|
||||
**Why the audience cares:** [...]
|
||||
**Content examples:**
|
||||
- [...]
|
||||
- [...]
|
||||
|
||||
**Format mix:** [...]
|
||||
**Posting cadence:** [...]
|
||||
|
||||
---
|
||||
|
||||
### Pillar 3: [Name — e.g. "Social proof and community"]
|
||||
|
||||
**What it is:** [Customer stories, testimonials, user-generated content, community spotlights]
|
||||
**Why the audience cares:** [Validation from peers carries more weight than brand claims]
|
||||
**Content examples:**
|
||||
- [Customer outcome stories — 1 metric + 1 quote format]
|
||||
- [Repost community member wins]
|
||||
- [Case study carousels]
|
||||
|
||||
**Format mix:** [...]
|
||||
**Posting cadence:** [...]
|
||||
|
||||
---
|
||||
|
||||
### Pillar 4: [Name — e.g. "Point of view"]
|
||||
|
||||
**What it is:** [Opinions on industry trends, hot takes, commentary on news in your space]
|
||||
**Why the audience cares:** [People follow accounts that say something, not just share information]
|
||||
**Content examples:**
|
||||
- [Contrarian takes on common advice]
|
||||
- [Reaction to industry news — what it means for your audience]
|
||||
- [Founder's personal perspective on a topic]
|
||||
|
||||
**Format mix:** [...]
|
||||
**Posting cadence:** [...]
|
||||
|
||||
---
|
||||
|
||||
## 4. Tone of Voice
|
||||
|
||||
Define how your brand sounds on social — before you write a single post:
|
||||
|
||||
| Dimension | [Your brand] sounds like... | [Your brand] does NOT sound like... |
|
||||
|---|---|---|
|
||||
| **Formality** | [e.g. Conversational, plain English] | [Corporate speak, jargon] |
|
||||
| **Energy** | [e.g. Curious, enthusiastic] | [Aggressive, hypey] |
|
||||
| **Personality** | [e.g. Smart friend who happens to be an expert] | [Faceless institution] |
|
||||
| **Humour** | [e.g. Dry wit, occasional] | [Try-hard memes, sarcasm] |
|
||||
| **Self-promotion** | [e.g. Earns the right to mention the product] | [Every post is an ad] |
|
||||
|
||||
**Reference accounts that nail the tone you're aiming for:** [Name 2–3 accounts — and why]
|
||||
|
||||
---
|
||||
|
||||
## 5. Posting Cadence & Workflow
|
||||
|
||||
| Platform | Posts per week | Best days | Best times | Format split |
|
||||
|---|---|---|---|---|
|
||||
| [LinkedIn] | [3–5] | [Tue–Thu] | [07:30–09:00 or 12:00–13:00] | [60% educational, 30% POV, 10% product] |
|
||||
| [X / Twitter] | [5–7] | [Any] | [Morning and lunchtime] | [50% replies/engagement, 30% original, 20% reposts] |
|
||||
| [Instagram] | [3–4] | [Mon, Wed, Fri] | [18:00–20:00] | [50% Reels, 30% carousels, 20% Stories] |
|
||||
|
||||
**Content production workflow:**
|
||||
|
||||
| Day | Activity | Owner | Time required |
|
||||
|---|---|---|---|
|
||||
| Monday | Plan the week's content — review pillars, select topics | [Social manager] | 30 min |
|
||||
| Tuesday | Write long-form posts for LinkedIn and threads | [Writer / founder] | 60 min |
|
||||
| Wednesday | Design carousels or graphics | [Designer / Canva] | 45 min |
|
||||
| Thursday | Schedule the week's content in [Buffer / Hootsuite / Later] | [Social manager] | 20 min |
|
||||
| Daily | Engage with comments, reply to mentions, interact with community | [Social manager] | 15 min |
|
||||
|
||||
---
|
||||
|
||||
## 6. Growth Tactics
|
||||
|
||||
Beyond posting, how will you grow your following and reach?
|
||||
|
||||
| Tactic | Description | Platform | Frequency |
|
||||
|---|---|---|---|
|
||||
| **Engage before you post** | Spend 15 min commenting on posts from target accounts before posting your own | All | Daily |
|
||||
| **Collaboration posts** | Co-create content with a complementary brand or creator | LinkedIn / IG | Monthly |
|
||||
| **Community participation** | Answer questions in relevant groups, subreddits, or Discord servers | LinkedIn / Reddit / Discord | Weekly |
|
||||
| **Tag relevant accounts** | When mentioning companies, tools, or people — tag them (earns reshares) | All | As relevant |
|
||||
| **Cross-promote** | Mention your social in newsletters, emails, events, and podcast appearances | All | Ongoing |
|
||||
| **Use trending formats early** | When a new format (e.g. LinkedIn carousels, IG Reels) emerges, adopt early | Platform-specific | When relevant |
|
||||
|
||||
---
|
||||
|
||||
## 7. Measurement Framework
|
||||
|
||||
**Primary KPIs (tied to business goal):**
|
||||
|
||||
| KPI | Platform | Current baseline | Target (90 days) | Why it matters |
|
||||
|---|---|---|---|---|
|
||||
| [Follower growth rate] | [LinkedIn] | [X%/month] | [≥ Y%/month] | [Audience reach] |
|
||||
| [Engagement rate] | [LinkedIn] | [X%] | [≥ Y%] | [Content resonance] |
|
||||
| [Link clicks / traffic from social] | [All] | [X visits/month] | [≥ Y visits/month] | [Direct business impact] |
|
||||
| [Inbound leads attributed to social] | [LinkedIn] | [X/month] | [≥ Y/month] | [Revenue impact] |
|
||||
|
||||
**Secondary metrics (health indicators):**
|
||||
- Reach per post
|
||||
- Saves and shares (not just likes)
|
||||
- Comment sentiment and quality
|
||||
- DMs initiated from content
|
||||
|
||||
**Reporting cadence:** [Weekly check on engagement / Monthly review of follower and traffic / Quarterly strategy review]
|
||||
|
||||
---
|
||||
|
||||
## 8. 4-Week Starter Content Calendar
|
||||
|
||||
A concrete first month of content — ready to adapt and post:
|
||||
|
||||
| Week | Day | Platform | Pillar | Format | Topic idea |
|
||||
|---|---|---|---|---|---|
|
||||
| 1 | Mon | LinkedIn | Education | Carousel | [e.g. "5 things we wished we knew before building [X]"] |
|
||||
| 1 | Wed | LinkedIn | Behind the build | Text post | [e.g. "We almost gave up in month 3. Here's what changed."] |
|
||||
| 1 | Fri | Instagram | Social proof | Reel | [e.g. Customer story — problem → solution → result] |
|
||||
| 2 | Tue | LinkedIn | POV | Thread | [e.g. "Hot take: [common advice in your space] is wrong. Here's why."] |
|
||||
| 2 | Thu | X/Twitter | Education | Thread | [e.g. "The [X] framework we use every week — and how you can steal it"] |
|
||||
| 2 | Sat | Instagram | Behind the build | Story | [e.g. "Week 2 update — what we shipped and one thing that didn't go to plan"] |
|
||||
| 3 | Mon | LinkedIn | Education | Carousel | [e.g. "How to [achieve outcome] in [timeframe] — step by step"] |
|
||||
| 3 | Wed | LinkedIn | Community | Text post | [e.g. Reshare a customer win with commentary] |
|
||||
| 3 | Fri | Instagram | POV | Reel | [e.g. "[Industry myth] — why we disagree and what we do instead"] |
|
||||
| 4 | Tue | LinkedIn | Behind the build | Video | [e.g. Founder talking to camera — "One thing I learned building [X] this month"] |
|
||||
| 4 | Thu | X/Twitter | POV | Thread | [e.g. "[Trend in your space] — here's what's actually happening"] |
|
||||
| 4 | Sat | All | Milestone | Text + image | [e.g. "[X followers / X users / X months] — thank you + what's next"] |
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Every content pillar delivers value to the audience — not just the brand
|
||||
- [ ] Platform selection is justified by where the target audience actually spends time
|
||||
- [ ] Tone of voice examples are specific enough to use as a writing guide
|
||||
- [ ] KPIs are tied to the business goal, not just vanity metrics (likes, followers in isolation)
|
||||
- [ ] Posting cadence is realistic for the available resources — sustainable beats ambitious
|
||||
- [ ] The 4-week calendar has specific topic ideas, not just "write an educational post"
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- "Build a social media strategy for [brand/product]"
|
||||
- "Create a LinkedIn content strategy for our B2B SaaS"
|
||||
- "Help me define content pillars and posting cadence for our startup"
|
||||
- "Design a 90-day social media plan for [company]"
|
||||
- "What should our social media strategy be for a product launch?"
|
||||
@@ -0,0 +1,186 @@
|
||||
---
|
||||
name: email-triage
|
||||
description: Reads your Gmail inbox for a configurable window (default: last 8 hours) and surfaces only what needs action — replies, decisions, or follow-up. Filters out receipts, notifications, newsletters, and anything that doesn't need you.
|
||||
---
|
||||
|
||||
# Email Triage
|
||||
|
||||
## The Problem
|
||||
|
||||
Most of us spend real time triaging email that could be sorted automatically. Scrolling through a mixed inbox of newsletters, order confirmations, Jira notifications, and actual human asks is a tax on focus. The 40 emails since lunch contain maybe 4 that actually need you — this skill finds those 4.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
| Requirement | Details |
|
||||
|-------------|---------|
|
||||
| Gmail connector | Must be active in Claude settings (Settings → Connectors → Gmail) |
|
||||
| Gmail account | The account you want triaged |
|
||||
|
||||
If the Gmail connector is not connected, Claude will prompt you to connect it before proceeding.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
| Input | Required | Default | Notes |
|
||||
|-------|----------|---------|-------|
|
||||
| Time window | No | Last 8 hours | Accepts: "last 8 hours", "last 24h", "today", "since Monday", "last 3 days" |
|
||||
| Always-include senders | No | None | Specific names or email addresses that always surface, regardless of content |
|
||||
| Always-ignore senders | No | None | Domains or addresses to always suppress (e.g. noreply@*, jira@company.com) |
|
||||
| Focus area | No | None | Optional context: "focus on anything from clients" or "flag anything about the launch" |
|
||||
|
||||
## What Gets Filtered Out
|
||||
|
||||
Claude suppresses the following categories. They are counted in the summary but not shown:
|
||||
|
||||
- Order confirmations and shipping notifications
|
||||
- Marketing and promotional emails (including "one-time" offer emails)
|
||||
- Newsletter subscriptions and digest emails
|
||||
- Automated system notifications (monitoring alerts, CI/CD, build reports)
|
||||
- Calendar invites that have already been accepted or declined
|
||||
- Read receipts and delivery confirmations
|
||||
- Social media notifications (LinkedIn, Twitter/X, etc.)
|
||||
- Internal ticket updates unless the ticket is assigned to you and requires action
|
||||
- Bank and financial statements (surfaced count only, not content)
|
||||
|
||||
## What Gets Surfaced
|
||||
|
||||
Claude surfaces only emails that meet one or more of these criteria:
|
||||
|
||||
- A human is waiting for a reply
|
||||
- A decision is being requested
|
||||
- There is a deadline or time-sensitive ask, explicit or implied
|
||||
- The sender is someone who does not usually email you (potential priority signal)
|
||||
- The email is from a sender in your always-include list
|
||||
|
||||
## Output Format
|
||||
|
||||
```
|
||||
## Inbox Triage — [Time window] | [Date], [Time]
|
||||
**Total emails scanned:** X | **Actionable:** Y | **Filtered out:** Z
|
||||
|
||||
---
|
||||
|
||||
### 🔴 High Priority — Needs reply or decision today
|
||||
|
||||
**From:** [Name] <email@domain.com>
|
||||
**Subject:** [Subject line]
|
||||
**Received:** [Time, e.g. 2:14 PM]
|
||||
**What they need:** [One sentence — the actual ask, not a summary of the email]
|
||||
**Reply starter:** "[A draft opener they can continue — 1 sentence max]"
|
||||
|
||||
---
|
||||
|
||||
**From:** [Name] <email@domain.com>
|
||||
**Subject:** [Subject line]
|
||||
**Received:** [Time]
|
||||
**What they need:** [One sentence]
|
||||
**Reply starter:** "[Draft opener]"
|
||||
|
||||
---
|
||||
|
||||
### 🟡 Medium Priority — Reply within 24–48h
|
||||
|
||||
**From:** [Name] <email@domain.com>
|
||||
**Subject:** [Subject line]
|
||||
**Received:** [Time]
|
||||
**What they need:** [One sentence]
|
||||
**Reply starter:** "[Draft opener]" *(or "No reply needed — action only: [what to do]")*
|
||||
|
||||
---
|
||||
|
||||
### 🟢 FYI — Worth knowing, no action required
|
||||
|
||||
- **[Name]** re: [Subject] — [One-line summary of why it might be relevant]
|
||||
- **[Name]** re: [Subject] — [One-line summary]
|
||||
|
||||
---
|
||||
|
||||
### ⚪ Filtered Out — [Z emails]
|
||||
Receipts: X | Newsletters: X | Notifications: X | Other automated: X
|
||||
*(No action needed — not shown in detail)*
|
||||
```
|
||||
|
||||
## Instructions for Claude
|
||||
|
||||
### Step 1 — Connect and confirm the time window
|
||||
|
||||
Confirm the Gmail connector is active. Parse the requested time window and translate it to an exact datetime range (e.g. "last 8 hours" = [current time minus 8 hours] to now). State the window at the top of the output.
|
||||
|
||||
### Step 2 — Read the inbox
|
||||
|
||||
Fetch emails from the inbox for the specified time window. Include: sender name, sender email, subject, received time, and email body (or first 500 words if long). Do not fetch emails older than the window.
|
||||
|
||||
### Step 3 — Apply ignore rules
|
||||
|
||||
If the user specified always-ignore senders or domains, suppress those immediately. If no ignore list was given, apply standard suppression (see What Gets Filtered Out). Track counts for the filtered summary.
|
||||
|
||||
### Step 4 — Classify each remaining email
|
||||
|
||||
For each non-suppressed email, classify into one of four categories:
|
||||
|
||||
- **High Priority**: A human is waiting on a reply today, or there is an explicit deadline within 24 hours
|
||||
- **Medium Priority**: A reply is needed but not urgently, or there is an implicit ask without a hard deadline
|
||||
- **FYI**: No action needed, but the user would likely want to know about it
|
||||
- **Filtered Out**: Falls into a suppressed category — add to count, do not show
|
||||
|
||||
Apply the always-include list after classification: any email from a flagged sender surfaces regardless of category, with its actual classification.
|
||||
|
||||
### Step 5 — Write the "What they need" line
|
||||
|
||||
This is the highest-value part of the output. Write exactly one sentence that captures the actual ask — not a summary of the email, the ask.
|
||||
|
||||
Bad: "Sarah sent an email about the Q3 report."
|
||||
Good: "Sarah needs your sign-off on the Q3 report before she sends it to the board at 5 PM."
|
||||
|
||||
If there is no clear ask, it is probably FYI or filtered out.
|
||||
|
||||
### Step 6 — Write the reply starter
|
||||
|
||||
For High and Medium priority emails, write a one-sentence reply opener. The opener should:
|
||||
- Match the tone of the sender (formal vs. casual)
|
||||
- Acknowledge the ask directly
|
||||
- Be something the user can actually send with minimal editing
|
||||
|
||||
Example: "Thanks for flagging this — let me check with the team and get back to you by EOD."
|
||||
|
||||
If the email requires an action rather than a reply (e.g. "please approve this expense"), write: "No reply needed — action only: [describe the action]."
|
||||
|
||||
### Step 7 — Assemble and deliver the output
|
||||
|
||||
Use the output format exactly as specified. Do not add extra sections, editorialise, or explain your reasoning. The output should be scannable in under 60 seconds.
|
||||
|
||||
### Step 8 — Offer next steps
|
||||
|
||||
After the triage output, offer one of:
|
||||
- "Want me to draft replies to any of these?"
|
||||
- "Say 'reply to [name]' and I'll draft it."
|
||||
|
||||
Keep this to one line. Do not elaborate.
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Time window was applied correctly — no emails outside the window are included
|
||||
- [ ] Gmail connector was confirmed active before reading
|
||||
- [ ] Every High Priority email has a specific, concrete "What they need" sentence — not a vague summary
|
||||
- [ ] Reply starters match the tone of the original email (formal/informal)
|
||||
- [ ] Filtered-out count is accurate and broken down by category
|
||||
- [ ] FYI section contains only emails with no action required — nothing actionable is buried here
|
||||
- [ ] Always-include senders surfaced regardless of category
|
||||
- [ ] Always-ignore senders/domains are fully suppressed
|
||||
- [ ] Output is scannable — no unnecessary prose, no padding
|
||||
- [ ] Financial statements and sensitive content were counted but not shown in full
|
||||
|
||||
## Dispatch / Mobile Usage
|
||||
|
||||
This skill works from the Claude mobile app (Dispatch). On mobile, the output renders cleanly with the emoji priority markers serving as visual anchors for quick scanning. Recommended mobile trigger: "Check my emails" or "/email-triage".
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- `/email-triage`
|
||||
- "Check my emails"
|
||||
- "What emails need my attention?"
|
||||
- "Triage my inbox for the last 8 hours"
|
||||
- "What came in since this morning?"
|
||||
- "Any urgent emails I need to deal with?"
|
||||
- "Triage my inbox — ignore anything from Jira and the marketing domain"
|
||||
- "Check emails from the last 24 hours, flag anything from [client name]"
|
||||
- "What do I need to reply to today?"
|
||||
@@ -0,0 +1,198 @@
|
||||
---
|
||||
name: morning-intelligence
|
||||
description: "Run a 15-question interview to capture your role, topics, sources, exclusions, and format preferences — then write a master prompt you can drop into a scheduled task or Claude Code Routine to get a personalised news brief every morning. Use when asked to set up a morning intelligence brief, build a morning news prompt, or create a personalised news briefing."
|
||||
---
|
||||
|
||||
# Morning Intelligence Skill
|
||||
|
||||
Write the prompt that writes your briefing. A 15-question interview extracts your exact context — role, topics, sources, exclusions, format, recency — then produces a single master prompt you can paste into a scheduled task or Claude Code Routine and never touch again.
|
||||
|
||||
> **Pro tip:** Run this interview with Opus for the best output. Opus asks sharper follow-up questions and writes a tighter master prompt.
|
||||
|
||||
> **Credit:** Originally created by Ashwin Francis (Cash&Cache) — adapted and extended for this library.
|
||||
|
||||
---
|
||||
|
||||
## Required Inputs
|
||||
|
||||
No inputs required upfront. The skill runs the interview first.
|
||||
|
||||
If the user has already provided context (e.g. pasted a role description or topic list), absorb it and skip those questions in the interview — don't ask for information already given.
|
||||
|
||||
---
|
||||
|
||||
## How the Interview Works
|
||||
|
||||
Run questions **one at a time** (or in small groups of 2–3 where they're closely related). Don't dump all 15 at once. Wait for each answer before proceeding. Ask natural follow-ups where the answer is vague.
|
||||
|
||||
### Interview Questions
|
||||
|
||||
**Block 1 — Who you are and how you read**
|
||||
|
||||
1. What is your role, and what lens do you read news through? (e.g. "Head of Product at a B2B SaaS — I read for competitive moves, AI tooling, and enterprise buying signals.")
|
||||
2. What are the 3–5 topics you always want covered? Be specific — "AI" is too broad; "AI applied to enterprise software" is better.
|
||||
3. What are 2–3 topics you actively want filtered out — things that waste your time every morning?
|
||||
|
||||
**Block 2 — Sources and signals**
|
||||
|
||||
4. Which publications, newsletters, or outlets do you trust most? (Examples: The Information, TLDR, Benedict Evans, Stratechery, FT, specific subreddits)
|
||||
5. Are there any Twitter/X accounts, Substack writers, or niche sources that are must-reads for you specifically?
|
||||
6. Is there any geography that matters — are you focused on a specific country, region, or market?
|
||||
|
||||
**Block 3 — Story type and recency**
|
||||
|
||||
7. What mix of story types do you want? Rank or weight these: breaking news / in-depth analysis / opinion / data & research / product launches & announcements.
|
||||
8. How fresh does the content need to be? Only today's news? Last 24 hours? Last 48 hours? Or are you okay with "last few days" if a story is important enough?
|
||||
|
||||
**Block 4 — Format and time**
|
||||
|
||||
9. How do you want the brief formatted? Options: bullet list by topic / short narrative paragraphs / a digest with headlines + 1-line summaries / a table / mixed.
|
||||
10. What's your reading time budget in the morning? 5 minutes (tight digest) / 10 minutes (fuller brief) / 15 minutes (comprehensive).
|
||||
|
||||
**Block 5 — This week specifically**
|
||||
|
||||
11. Is there anything you're tracking this week in particular — a specific company, deal, product launch, regulatory development, or ongoing story?
|
||||
|
||||
**Block 6 — Follow-up clarification (questions 12–15)**
|
||||
|
||||
Based on the answers above, ask 4 targeted follow-up questions to sharpen ambiguities. Examples of what to probe:
|
||||
|
||||
- If a topic is still broad: "You said [topic] — do you want the technical angle, the business/market angle, or both?"
|
||||
- If sources are vague: "When you say [publication], do you want everything from them or only specific sections/writers?"
|
||||
- If format is unclear: "You want bullets — should each topic have its own section with 3–5 bullets, or one flat list of all stories?"
|
||||
- If recency conflicts with format: "You want only today's news but a comprehensive 15-minute brief — on slow news days, should I go deeper on one story or pull from the last 48 hours to fill it out?"
|
||||
- If exclusions are vague: "You said no [topic] — does that include adjacent topics like [related thing], or strictly [topic]?"
|
||||
|
||||
Use your judgement on which 4 are most worth asking given the actual answers.
|
||||
|
||||
---
|
||||
|
||||
## Output Structure
|
||||
|
||||
After the interview is complete, produce three things in order:
|
||||
|
||||
### 1. Summary of What You Told Me
|
||||
|
||||
A brief summary of the interview, clustered into thematic pillars. This lets the user verify the master prompt will be accurate before it's written.
|
||||
|
||||
```
|
||||
WHAT I HEARD
|
||||
────────────
|
||||
Role lens: [1 sentence]
|
||||
Core topics: [Pillar 1] · [Pillar 2] · [Pillar 3]
|
||||
Exclusions: [Topic A], [Topic B]
|
||||
Sources: [List]
|
||||
Story mix: [e.g. 60% analysis, 30% news, 10% data]
|
||||
Recency: [e.g. Last 24 hours, today only for breaking]
|
||||
Format: [e.g. Bullets by topic, ~10 min read]
|
||||
This week: [Specific tracking items]
|
||||
```
|
||||
|
||||
Confirm: "Does this look right? I'll write the master prompt based on this."
|
||||
|
||||
---
|
||||
|
||||
### 2. The Master Prompt
|
||||
|
||||
Formatted and ready to paste. Start with a markdown code block so the user can copy it cleanly.
|
||||
|
||||
````
|
||||
```
|
||||
MORNING INTELLIGENCE BRIEF — MASTER PROMPT
|
||||
==========================================
|
||||
|
||||
You are an intelligence analyst briefing [ROLE] at the start of their day.
|
||||
|
||||
TASK
|
||||
Generate a personalised morning news brief covering the following.
|
||||
|
||||
TOPICS TO COVER
|
||||
1. [Topic / Pillar 1] — focus on [angle]
|
||||
2. [Topic / Pillar 2] — focus on [angle]
|
||||
3. [Topic / Pillar 3] — focus on [angle]
|
||||
[add pillars as needed]
|
||||
|
||||
NEVER INCLUDE
|
||||
- [Excluded topic 1]
|
||||
- [Excluded topic 2]
|
||||
- [Excluded topic 3]
|
||||
|
||||
PREFERRED SOURCES (prioritise these)
|
||||
[Source 1], [Source 2], [Source 3], [Source 4]
|
||||
|
||||
STORY TYPE MIX
|
||||
[e.g. Prioritise analysis and data-driven pieces. Include breaking news only if significant. Skip opinion unless it's from [specific writer].]
|
||||
|
||||
RECENCY
|
||||
[e.g. Cover only the last 24 hours. For ongoing stories I'm tracking, include relevant developments from the last 48 hours.]
|
||||
|
||||
CURRENTLY TRACKING THIS WEEK
|
||||
[Specific story / company / topic the user flagged]
|
||||
|
||||
FORMAT
|
||||
[e.g. Organise by topic. Under each topic: 2–4 bullet points. Each bullet: headline + 1–2 sentence summary + source name. End with a "What to watch today" section: 2–3 sentences on what matters most today.]
|
||||
|
||||
LENGTH
|
||||
Target a [5/10/15]-minute read.
|
||||
|
||||
TONE
|
||||
Analyst voice. No fluff. Lead with the signal, not the noise. If something is uncertain or based on incomplete reporting, flag it as such.
|
||||
```
|
||||
````
|
||||
|
||||
---
|
||||
|
||||
### 3. Setup Guide
|
||||
|
||||
A short section below the master prompt:
|
||||
|
||||
```
|
||||
HOW TO USE THIS PROMPT
|
||||
──────────────────────
|
||||
|
||||
OPTION A — Cowork Scheduled Tasks (Claude Pro/Max)
|
||||
Requires: Desktop app open at scheduled time
|
||||
1. Open Claude desktop → Cowork → Scheduled Tasks
|
||||
2. Create a new task, set your time (e.g. 7:00 AM)
|
||||
3. Paste the master prompt as the task content
|
||||
4. Save. It will run every morning when your desktop app is open.
|
||||
|
||||
OPTION B — Claude Code Routines (runs in the cloud)
|
||||
Requires: Claude Code with Routines access
|
||||
Advantage: Runs without your laptop being on
|
||||
1. In your project root, create or open .claude/routines.json
|
||||
2. Add a new routine with a cron schedule (e.g. "0 7 * * *" for 7 AM daily)
|
||||
3. Set the prompt field to the master prompt above
|
||||
4. Commit and push — Claude Code will run it on schedule.
|
||||
|
||||
UPDATING YOUR BRIEF
|
||||
When your focus shifts, re-run this skill. The interview takes 5–10 minutes
|
||||
and produces a new master prompt to replace the old one.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Every interview question was asked — none skipped unless the user already provided the answer
|
||||
- [ ] The "What I Heard" summary was shown and confirmed before writing the master prompt
|
||||
- [ ] The master prompt uses specific topic angles, not vague category names (not "AI" — "AI applied to enterprise software")
|
||||
- [ ] Exclusions are explicitly stated in the master prompt with a NEVER INCLUDE section
|
||||
- [ ] Sources are listed in order of preference, not as a flat unordered list
|
||||
- [ ] Story type mix is written as a directive, not just a list
|
||||
- [ ] Recency instruction handles the edge case of slow news days
|
||||
- [ ] Format instruction is precise enough that a different AI could follow it correctly
|
||||
- [ ] The master prompt is inside a code block so it copies cleanly
|
||||
- [ ] Both setup options (Cowork and Claude Code Routines) are included
|
||||
|
||||
---
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- "Set up my morning intelligence brief"
|
||||
- "Build me a morning news prompt"
|
||||
- "Interview me for a morning briefing skill"
|
||||
- "I want to start every day with a personalised news digest"
|
||||
- "Help me set up a daily AI news brief"
|
||||
- "Create a scheduled morning news prompt for me"
|
||||
- "Build me a prompt for my daily briefing routine"
|
||||
@@ -0,0 +1,160 @@
|
||||
---
|
||||
name: raci-matrix
|
||||
description: "Define a RACI matrix for a cross-functional project or process. Use when asked to build a RACI, create a responsibility matrix, clarify ownership across teams, or document decision rights. Produces a complete RACI matrix with role definitions, decision mapping, and a process for resolving conflicts."
|
||||
---
|
||||
|
||||
# RACI Matrix Skill
|
||||
|
||||
This skill produces a complete RACI (Responsible, Accountable, Consulted, Informed) matrix for a project, product launch, or ongoing process. Output is ready to share with teams to clarify ownership, reduce decision bottlenecks, and eliminate duplication of effort.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask the user for these if not provided:
|
||||
- **Project or process name**
|
||||
- **Key activities or decisions** to map (or the user can describe the project and the skill will derive them)
|
||||
- **Teams or roles involved** (list team names and key individuals if helpful)
|
||||
- **Primary purpose** — clarifying launch ownership / onboarding a new team / reducing bottlenecks / governance documentation
|
||||
- **RACI variant** — standard RACI, or RASCI (adds Supportive), or DACI (Driver, Approver, Contributors, Informed)?
|
||||
|
||||
## Output Structure
|
||||
|
||||
---
|
||||
|
||||
# RACI Matrix: [Project / Process Name]
|
||||
|
||||
**Version:** [1.0]
|
||||
**Owner:** [Programme lead / PM]
|
||||
**Date:** [Date]
|
||||
**Teams involved:** [List teams]
|
||||
|
||||
---
|
||||
|
||||
## 1. Role Definitions
|
||||
|
||||
Before reading the matrix, agree on what each letter means for this project:
|
||||
|
||||
| Letter | Role | Definition | Rules |
|
||||
|---|---|---|---|
|
||||
| **R** | Responsible | Does the work. One or more people actually execute the task. | Multiple Rs are allowed — but if there are many, consider splitting the task |
|
||||
| **A** | Accountable | Owns the outcome. Signs off on decisions. Answers if something goes wrong. | **There must be exactly one A per row.** Never two. Never zero. |
|
||||
| **C** | Consulted | Provides expertise or input before work is done. Two-way communication. | Consulted parties must be engaged — not just available. Cap at 3 per row or it becomes noise |
|
||||
| **I** | Informed | Notified of progress or outcomes. One-way communication. | Informed only — they don't review or approve |
|
||||
|
||||
**Golden rules:**
|
||||
- Every row has exactly one **A**
|
||||
- The same person or team should not be **A** for more than [X] rows — spreads accountability too thin
|
||||
- **C** is expensive — consulting someone means they must respond. Use it intentionally
|
||||
- If someone is **R** they cannot also be **A** for the same task unless they are the decision-maker (common in small teams)
|
||||
|
||||
---
|
||||
|
||||
## 2. RACI Matrix
|
||||
|
||||
Columns = teams or roles. Rows = activities or decisions.
|
||||
|
||||
| Activity / Decision | [Role 1] | [Role 2] | [Role 3] | [Role 4] | [Role 5] | Notes |
|
||||
|---|---|---|---|---|---|---|
|
||||
| **[Phase 1: Discovery]** | | | | | | |
|
||||
| Define project scope and objectives | A/R | C | I | I | — | PM leads; engineering consulted on technical feasibility |
|
||||
| Conduct user research | R | A | C | I | — | UX researcher executes; PM accountable |
|
||||
| Approve discovery findings | C | A | I | R | — | |
|
||||
| **[Phase 2: Design]** | | | | | | |
|
||||
| Define solution approach | A | R | C | I | I | |
|
||||
| Design system / UI designs | C | A/R | I | I | — | |
|
||||
| Design review and sign-off | C | R | A | I | — | |
|
||||
| Accessibility review | I | R | A | C | — | |
|
||||
| **[Phase 3: Build]** | | | | | | |
|
||||
| Technical architecture decision | C | C | A/R | I | — | |
|
||||
| Sprint planning | A | C | R | I | I | |
|
||||
| Code review and merge | I | C | R | A | — | |
|
||||
| Security review | I | C | C | A/R | — | |
|
||||
| **[Phase 4: Launch]** | | | | | | |
|
||||
| Launch go / no-go decision | A | C | C | R | I | PM holds final authority |
|
||||
| Release to production | C | I | A/R | I | — | |
|
||||
| Customer communications | A/R | I | I | I | C | |
|
||||
| Post-launch monitoring | C | I | R | A | — | |
|
||||
| **[Ongoing / BAU]** | | | | | | |
|
||||
| Incident response | I | C | R | A | — | |
|
||||
| Feature prioritisation | A/R | C | C | I | I | |
|
||||
| Stakeholder reporting | A/R | I | I | I | C | |
|
||||
|
||||
---
|
||||
|
||||
## 3. Decision Map
|
||||
|
||||
For high-stakes decisions, document the decision type, who holds authority, and how disagreements are resolved:
|
||||
|
||||
| Decision | Authority (A) | Must consult (C) | Escalation path if disagreed |
|
||||
|---|---|---|---|
|
||||
| Scope change >20% effort | [Exec sponsor / Programme lead] | [PM, Engineering lead] | [Steering committee] |
|
||||
| Budget overrun >10% | [Finance / Exec] | [PM, Programme lead] | [CFO / Board] |
|
||||
| Architecture pattern change | [Engineering lead] | [Tech lead, Security] | [CTO] |
|
||||
| Go-live date change | [PM] | [Engineering, Comms, CS] | [Programme sponsor] |
|
||||
| Feature cut from scope | [PM] | [Product, UX, Engineering] | [CPO] |
|
||||
|
||||
---
|
||||
|
||||
## 4. Common RACI Anti-Patterns — and Fixes
|
||||
|
||||
Review the completed matrix against these failure modes:
|
||||
|
||||
| Anti-pattern | Symptom | Fix |
|
||||
|---|---|---|
|
||||
| **Multiple As** | Two teams both think they own an outcome | Agree one A; the other becomes C or I |
|
||||
| **No A** | Decisions stall; no one feels responsible | Assign the most senior stakeholder as A |
|
||||
| **Everyone is C** | Every decision goes to a committee | Audit each C — does this person actually provide input that changes outcomes? If not, move to I |
|
||||
| **R without A** | Work gets done but no one owns quality | Add an A; usually the manager of the R |
|
||||
| **A without R** | Accountability without execution — manager is disconnected | Add an R from the team; or combine A/R if appropriate |
|
||||
| **Too many Rs** | Diffusion of responsibility | Split the task into sub-tasks, each with one clear R |
|
||||
| **Key team missing from matrix** | They're affected but not in the RACI | Add them; assign at minimum I for relevant rows |
|
||||
|
||||
---
|
||||
|
||||
## 5. Communication Template
|
||||
|
||||
Once the RACI is agreed, use this template to communicate it to all involved teams:
|
||||
|
||||
---
|
||||
|
||||
**Subject:** [Project Name] — Roles and Responsibilities Agreed
|
||||
|
||||
We've finalised the RACI matrix for [Project Name]. Here's what it means for you:
|
||||
|
||||
**[Role 1 team]:** You are **Accountable** for [X, Y, Z activities]. This means you make the final call on those decisions and answer if outcomes are not met.
|
||||
|
||||
**[Role 2 team]:** You are **Responsible** for [A, B, C]. You execute the work. For [D], you are **Consulted** — we need your input before decisions are finalised.
|
||||
|
||||
**[Role 3 team]:** You are **Informed** on [E, F] — we'll send you updates at [weekly / milestone / launch]. No action required unless you see something that needs escalation.
|
||||
|
||||
Please review the full matrix here: [Link]. Raise any concerns by [Date] — after that, we'll treat it as agreed.
|
||||
|
||||
---
|
||||
|
||||
## 6. RACI Review Cadence
|
||||
|
||||
| Trigger | Action |
|
||||
|---|---|
|
||||
| New team member joins | Review rows relevant to their role — update R as needed |
|
||||
| Phase change (e.g. discovery → delivery) | Review full matrix — some Rs and As will shift |
|
||||
| Escalation or confusion about ownership | Use the matrix to diagnose — find the missing A |
|
||||
| 3 months into a long programme | Full RACI review — roles drift over time |
|
||||
| Team restructure or reorganisation | Full rebuild — ownership assumptions change |
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Every row has exactly one **A**
|
||||
- [ ] No individual or team is **A** for more than their realistic sphere of authority
|
||||
- [ ] **C** columns are sparse — consulting everyone dilutes the process
|
||||
- [ ] Matrix was reviewed and agreed by at least one representative from each role column
|
||||
- [ ] A communication plan exists to share the RACI with all involved parties
|
||||
- [ ] Decision map covers the top 5–10 highest-stakes decisions in the project
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- "Build a RACI matrix for our product launch"
|
||||
- "Create a responsibility matrix for our new cross-functional project"
|
||||
- "Who owns what on this initiative? Help me build a RACI"
|
||||
- "Map out decision rights for our engineering and product teams"
|
||||
- "Generate a RACI for a [migration / launch / process] involving [teams]"
|
||||
@@ -0,0 +1,211 @@
|
||||
---
|
||||
name: risk-register
|
||||
description: "Build and maintain a project or product risk register. Use when asked to create a risk register, identify project risks, build a risk matrix, or document risks and mitigations for a programme. Produces a complete risk register with likelihood/impact scoring, RAG status, ownership, and prioritised mitigations."
|
||||
---
|
||||
|
||||
# Risk Register Skill
|
||||
|
||||
This skill produces a complete risk register for a project, programme, or product. Output follows standard risk management practice with likelihood × impact scoring, RAG status, a risk heat map, and specific mitigation and contingency plans. Ready to share with a project board, steering committee, or programme office.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask the user for these if not provided:
|
||||
- **Project or product name**
|
||||
- **Project stage** (discovery / delivery / launch / live / programme-level)
|
||||
- **Key objectives** — what is the project trying to achieve?
|
||||
- **Known risks** — anything already on the team's radar (even informal concerns count)
|
||||
- **Key dependencies** — external vendors, teams, systems, or regulatory approvals
|
||||
- **Deadline or milestone sensitivity** — are there hard dates that cannot move?
|
||||
- **Audience** — who will read this? (internal team / executive steering / external board / regulator)
|
||||
|
||||
## Output Structure
|
||||
|
||||
---
|
||||
|
||||
# Risk Register: [Project / Product Name]
|
||||
|
||||
**Project stage:** [Discovery / Delivery / Launch / Live / Programme]
|
||||
**Version:** [1.0]
|
||||
**Owner:** [PM / Programme Manager / Risk Lead]
|
||||
**Last reviewed:** [Date]
|
||||
**Next review:** [Date — recommend weekly during delivery, monthly during discovery]
|
||||
**Status:** [Active / Archived]
|
||||
|
||||
---
|
||||
|
||||
## 1. Risk Scoring Framework
|
||||
|
||||
**Likelihood (L)**
|
||||
|
||||
| Score | Label | Definition |
|
||||
|---|---|---|
|
||||
| 5 | Almost certain | >80% probability of occurring |
|
||||
| 4 | Likely | 60–80% probability |
|
||||
| 3 | Possible | 40–60% probability |
|
||||
| 2 | Unlikely | 20–40% probability |
|
||||
| 1 | Rare | <20% probability |
|
||||
|
||||
**Impact (I)**
|
||||
|
||||
| Score | Label | Definition |
|
||||
|---|---|---|
|
||||
| 5 | Critical | Programme failure, regulatory breach, major financial loss, safety event |
|
||||
| 4 | High | Significant schedule delay (>4 weeks), scope reduction, reputational damage |
|
||||
| 3 | Medium | Moderate delay (1–4 weeks), cost overrun, reduced quality |
|
||||
| 2 | Low | Minor delay (<1 week), manageable cost increase |
|
||||
| 1 | Negligible | Minimal impact, easily absorbed |
|
||||
|
||||
**Risk Score = L × I**
|
||||
|
||||
| Score | RAG | Action |
|
||||
|---|---|---|
|
||||
| 20–25 | 🔴 Critical | Immediate escalation; active management required |
|
||||
| 12–19 | 🔴 High | Owner-assigned mitigation; weekly review |
|
||||
| 8–11 | 🟡 Medium | Mitigation planned; fortnightly review |
|
||||
| 4–7 | 🟡 Low | Monitor; monthly review |
|
||||
| 1–3 | 🟢 Negligible | Accept; review if context changes |
|
||||
|
||||
---
|
||||
|
||||
## 2. Risk Register
|
||||
|
||||
| ID | Risk | Category | L | I | Score | RAG | Owner | Status | Mitigation | Contingency | Review date |
|
||||
|---|---|---|---|---|---|---|---|---|---|---|---|
|
||||
| R01 | [Risk description — be specific: "Third-party API may not support required volume, causing X to fail"] | [Schedule / Technical / Resource / Commercial / Compliance / External] | [1–5] | [1–5] | [L×I] | 🔴/🟡/🟢 | [Name] | [Open / Mitigating / Closed] | [What are we doing to reduce likelihood or impact?] | [What do we do if it happens?] | [Date] |
|
||||
| R02 | [...] | [...] | [...] | [...] | [...] | [...] | [...] | [...] | [...] | [...] | [...] |
|
||||
|
||||
---
|
||||
|
||||
## 3. Risk Categories — Common Risks by Type
|
||||
|
||||
Use these to prompt risk identification. Add, remove, or customise for your project.
|
||||
|
||||
### Schedule & Delivery
|
||||
- Key milestone depends on a dependency that has not confirmed availability
|
||||
- Team capacity reduced by planned or unplanned absence during critical period
|
||||
- Technical complexity is underestimated — story points consistently overrun
|
||||
- External approval (regulator, legal, procurement) takes longer than planned
|
||||
|
||||
### Technical
|
||||
- Integration with a third-party system not yet prototyped or agreed
|
||||
- Existing technical debt makes the change harder or riskier than estimated
|
||||
- Security or compliance review required before launch has not been scoped
|
||||
- Performance under production load untested
|
||||
- Key technical knowledge held by one person (single point of failure)
|
||||
|
||||
### Resource & People
|
||||
- Key SME or engineer leaving or unavailable during critical phase
|
||||
- Budget not confirmed for Phase 2 of the project
|
||||
- Stakeholder sponsor changes role or leaves the organisation
|
||||
- Team not yet at full capacity (hiring lag, access issues, onboarding time)
|
||||
|
||||
### Commercial & Financial
|
||||
- Vendor or partner contract not yet signed
|
||||
- Cost estimate based on assumptions that have not been validated
|
||||
- Revenue or savings case depends on assumptions outside the team's control
|
||||
- Currency exposure or exchange rate risk for international projects
|
||||
|
||||
### Compliance & Regulatory
|
||||
- Data privacy impact assessment (DPIA) not yet complete
|
||||
- Regulatory approval required and timeline is uncertain
|
||||
- GDPR, HIPAA, SOC 2, or sector-specific compliance requirement not yet mapped
|
||||
- Legal review of terms of service or contracts pending
|
||||
|
||||
### Stakeholder & Adoption
|
||||
- Key user group has low awareness or motivation to adopt the change
|
||||
- Internal resistance from a team that will be affected by the change
|
||||
- Executive sponsor not consistently engaged — decisions are slow
|
||||
- Communications plan not yet agreed with change management team
|
||||
|
||||
### External
|
||||
- Market or competitive change could undermine the business case
|
||||
- Macroeconomic conditions affect budget or priority
|
||||
- Supplier or infrastructure provider risk (e.g. cloud provider, hardware)
|
||||
- Geopolitical or regulatory environment change
|
||||
|
||||
---
|
||||
|
||||
## 4. Risk Heat Map
|
||||
|
||||
Plot risks by likelihood (Y axis) and impact (X axis):
|
||||
|
||||
```
|
||||
│ Low Medium High Critical
|
||||
│ (1) (2-3) (4) (5)
|
||||
─────────┼────────────────────────────────────
|
||||
Almost │ 🟡 🟡 🔴 🔴
|
||||
certain │
|
||||
(5) │
|
||||
─────────┼────────────────────────────────────
|
||||
Likely │ 🟡 🟡 🔴 🔴
|
||||
(4) │
|
||||
─────────┼────────────────────────────────────
|
||||
Possible │ 🟢 🟡 🟡 🔴
|
||||
(3) │
|
||||
─────────┼────────────────────────────────────
|
||||
Unlikely │ 🟢 🟢 🟡 🟡
|
||||
(2) │
|
||||
─────────┼────────────────────────────────────
|
||||
Rare │ 🟢 🟢 🟢 🟡
|
||||
(1) │
|
||||
```
|
||||
|
||||
[Plot each risk ID on this grid — e.g. R01 lands at L4/I5 = 🔴 Critical]
|
||||
|
||||
---
|
||||
|
||||
## 5. Top Risks — Executive Summary
|
||||
|
||||
For steering committee or board-level reporting:
|
||||
|
||||
| Rank | Risk | Score | RAG | Owner | Mitigation status |
|
||||
|---|---|---|---|---|---|
|
||||
| 1 | [Most critical risk — plain English description] | [X] | 🔴 | [Owner] | [Active / Planned / Not started] |
|
||||
| 2 | [...] | [...] | 🔴 | [...] | [...] |
|
||||
| 3 | [...] | [...] | 🟡 | [...] | [...] |
|
||||
| 4 | [...] | [...] | 🟡 | [...] | [...] |
|
||||
| 5 | [...] | [...] | 🟡 | [...] | [...] |
|
||||
|
||||
**Decisions required from steering:**
|
||||
- [Any risk that requires budget, scope, or timeline decision to mitigate]
|
||||
|
||||
---
|
||||
|
||||
## 6. Risk Changes Since Last Review
|
||||
|
||||
| Risk ID | Change | Detail |
|
||||
|---|---|---|
|
||||
| [R03] | Score increased | [L moved from 2 → 4 — vendor confirmed delay in API availability] |
|
||||
| [R07] | Risk closed | [Legal sign-off received on 12 May] |
|
||||
| [NEW] | New risk identified | [R09 — budget freeze announcement affects Phase 2 funding] |
|
||||
|
||||
---
|
||||
|
||||
## 7. Risk Closure Criteria
|
||||
|
||||
A risk is closed when:
|
||||
- The risk event can no longer occur (e.g. milestone passed, contract signed), OR
|
||||
- The residual risk score drops to Negligible (1–3) AND the team formally accepts it, OR
|
||||
- The risk has materialised and transitioned to an **issue** (tracked separately)
|
||||
|
||||
**Issues log:** [Link to issues log — risks that have materialised and are now active problems being managed]
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Every risk has a specific owner — not "the team" or "TBD"
|
||||
- [ ] Mitigations describe what is actively being done — not "monitor and review"
|
||||
- [ ] Contingency plans exist for all Critical and High risks
|
||||
- [ ] Risk descriptions are specific — "vendor may be late" is not specific enough; name the vendor and the dependency
|
||||
- [ ] Register has been reviewed in the last [X] days
|
||||
- [ ] Closed risks are archived, not deleted — they provide audit trail
|
||||
- [ ] Risks are distinguished from issues — a risk is something that might happen; an issue is something that has happened
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- "Build a risk register for our product launch"
|
||||
- "Create a risk matrix for [project name]"
|
||||
- "What risks should I document for a data migration project?"
|
||||
- "Generate a risk register for our steering committee"
|
||||
- "Help me identify and score risks for our Q3 delivery plan"
|
||||
@@ -0,0 +1,256 @@
|
||||
---
|
||||
name: 360-feedback-template
|
||||
description: "Design a 360-degree feedback survey or write a structured 360 feedback report. Use when asked to build a 360 feedback process, write 360 feedback for a colleague, design a feedback survey, or produce a feedback report. Produces either a complete survey instrument with rating scales and open-ended questions, or a structured narrative feedback report with themes, strengths, and development areas."
|
||||
---
|
||||
|
||||
# 360-Degree Feedback Template Skill
|
||||
|
||||
This skill produces two outputs depending on what the user needs: (1) a complete 360 survey instrument for gathering feedback, or (2) a structured 360 feedback report written from gathered notes. Both outputs follow best practice: behaviourally anchored ratings, specific examples, and development-oriented framing.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask the user which output they need, then gather inputs:
|
||||
|
||||
**For a survey instrument:**
|
||||
- **Role being reviewed** (job title and level)
|
||||
- **Competencies to assess** (or use defaults below)
|
||||
- **Reviewer relationships** (peer / direct report / manager / cross-functional)
|
||||
- **Rating scale preference** (1–5 / 1–4 / frequency-based)
|
||||
- **Anonymity level** (fully anonymous / attributed / confidential aggregated)
|
||||
|
||||
**For a feedback report:**
|
||||
- **Person being reviewed** (role and level)
|
||||
- **Feedback notes or raw themes** from reviewers (paste what you have)
|
||||
- **Reviewer relationships** (how many peers, direct reports, managers responded)
|
||||
- **Any context** — performance cycle, specific behaviours to address, promotion consideration
|
||||
|
||||
---
|
||||
|
||||
## Output A: 360 Survey Instrument
|
||||
|
||||
---
|
||||
|
||||
# 360 Feedback Survey: [Role / Level]
|
||||
|
||||
**Purpose:** This survey helps [Name / "the reviewee"] understand how their behaviours and impact are perceived by the people they work with most closely. Responses [are / are not] anonymous. Results will be shared as [individual responses / aggregated themes].
|
||||
|
||||
**Instructions:** For each statement, rate how frequently you observe this behaviour. Add specific examples in the open-ended sections — these are the most valuable part of the survey.
|
||||
|
||||
**Rating scale:**
|
||||
- **5 — Consistently:** Almost always demonstrates this behaviour, even in difficult situations
|
||||
- **4 — Usually:** Demonstrates this behaviour more often than not
|
||||
- **3 — Sometimes:** Demonstrates this behaviour inconsistently
|
||||
- **2 — Rarely:** Seldom demonstrates this behaviour
|
||||
- **1 — Not observed:** Have not had the opportunity to observe this behaviour
|
||||
|
||||
---
|
||||
|
||||
### Section 1: Delivery & Execution
|
||||
|
||||
| Statement | Rating (1–5) |
|
||||
|---|---|
|
||||
| Delivers work on time and to the expected quality | |
|
||||
| Proactively flags risks and blockers before they become problems | |
|
||||
| Follows through on commitments without needing to be chased | |
|
||||
| Manages their workload effectively without compromising quality | |
|
||||
| Adapts quickly when priorities or requirements change | |
|
||||
|
||||
**Open question:** Describe a specific time when [Name] handled a delivery challenge particularly well or poorly.
|
||||
|
||||
---
|
||||
|
||||
### Section 2: Communication & Collaboration
|
||||
|
||||
| Statement | Rating (1–5) |
|
||||
|---|---|
|
||||
| Communicates clearly and concisely in both written and verbal formats | |
|
||||
| Listens actively and considers others' input before responding | |
|
||||
| Keeps the right people informed without over-communicating | |
|
||||
| Resolves disagreements constructively and without defensiveness | |
|
||||
| Makes it easy for others to collaborate with them | |
|
||||
|
||||
**Open question:** Give an example of how [Name] handled a difficult or high-stakes communication.
|
||||
|
||||
---
|
||||
|
||||
### Section 3: Leadership & Influence
|
||||
|
||||
| Statement | Rating (1–5) |
|
||||
|---|---|
|
||||
| Sets a clear direction that others can follow | |
|
||||
| Builds confidence and capability in people around them | |
|
||||
| Influences decisions without relying on authority | |
|
||||
| Gives clear, constructive feedback that helps others improve | |
|
||||
| Creates an environment where people feel safe to raise concerns | |
|
||||
|
||||
**Open question:** Describe a situation where [Name]'s leadership had a notable positive or negative impact on the team.
|
||||
|
||||
---
|
||||
|
||||
### Section 4: Strategic Thinking
|
||||
|
||||
| Statement | Rating (1–5) |
|
||||
|---|---|
|
||||
| Understands the broader business context, not just their immediate work | |
|
||||
| Makes connections between their work and organisational goals | |
|
||||
| Thinks ahead and anticipates second-order consequences | |
|
||||
| Brings original ideas or new approaches to problems | |
|
||||
| Balances short-term needs with longer-term thinking | |
|
||||
|
||||
**Open question:** Give an example of [Name] demonstrating (or missing) strategic thinking.
|
||||
|
||||
---
|
||||
|
||||
### Section 5: Culture & Values
|
||||
|
||||
| Statement | Rating (1–5) |
|
||||
|---|---|
|
||||
| Treats everyone with respect, regardless of level or background | |
|
||||
| Is someone people trust and can rely on | |
|
||||
| Gives credit to others and shares the spotlight | |
|
||||
| Takes responsibility for mistakes without placing blame | |
|
||||
| Contributes positively to team morale, especially under pressure | |
|
||||
|
||||
**Open question:** How does [Name] embody (or not embody) the team's values in practice?
|
||||
|
||||
---
|
||||
|
||||
### Section 6: Overall & Development
|
||||
|
||||
**Open questions (all reviewers):**
|
||||
|
||||
1. What is [Name]'s single most important strength? Give a specific example.
|
||||
|
||||
2. What is the one behaviour or habit that, if changed, would most increase [Name]'s effectiveness?
|
||||
|
||||
3. Is there anything else you want [Name] to know? (This response will be shared directly.)
|
||||
|
||||
---
|
||||
|
||||
## Output B: 360 Feedback Report
|
||||
|
||||
---
|
||||
|
||||
# 360 Feedback Report: [Name] — [Role]
|
||||
|
||||
**Review cycle:** [Quarter / Year / Promotion cycle]
|
||||
**Responses received:** [X total — X peers, X direct reports, X managers, X cross-functional]
|
||||
**Report prepared by:** [HR / People team / Manager / Coach]
|
||||
**Date:** [Date]
|
||||
|
||||
> This report synthesises feedback from [X] reviewers. Open-ended responses have been lightly edited for clarity; no individual response is attributed to protect reviewer confidentiality. Direct quotes marked in *italics* appear verbatim.
|
||||
|
||||
---
|
||||
|
||||
### Executive Summary
|
||||
|
||||
[3–4 sentences. State the overall picture: what is this person known for, what is working well, and what one or two areas are the consistent development themes. Balanced, honest, and grounded in the data — not a sanitised summary.]
|
||||
|
||||
**Overall rating:** [X.X / 5.0 — above average / at level / below expectations for level]
|
||||
|
||||
---
|
||||
|
||||
### Strengths: What to Build On
|
||||
|
||||
**Theme 1: [Strength — e.g. Reliability and follow-through]**
|
||||
|
||||
[2–3 sentences synthesising the feedback evidence for this strength. Reference how many reviewers noted it and in what contexts.]
|
||||
|
||||
*"[Direct quote from reviewer that best illustrates this theme]"*
|
||||
|
||||
---
|
||||
|
||||
**Theme 2: [Strength — e.g. Collaborative problem-solving]**
|
||||
|
||||
[2–3 sentences synthesising evidence.]
|
||||
|
||||
*"[Direct quote]"*
|
||||
|
||||
---
|
||||
|
||||
**Theme 3: [Strength — e.g. Clear communication under pressure]**
|
||||
|
||||
[2–3 sentences synthesising evidence.]
|
||||
|
||||
*"[Direct quote]"*
|
||||
|
||||
---
|
||||
|
||||
### Development Areas: What to Work On
|
||||
|
||||
**Theme 1: [Development area — e.g. Giving timely upward feedback]**
|
||||
|
||||
[2–3 sentences describing the behaviour pattern observed, what impact it has, and what different looks like. Non-blaming and specific.]
|
||||
|
||||
*"[Direct quote that captures the theme]"*
|
||||
|
||||
**Suggested actions:**
|
||||
- [Specific, observable behaviour change — e.g. In the next team meeting where you disagree with a decision, name your concern in the meeting rather than after it]
|
||||
- [Development resource or practice — e.g. Try the "I notice / I wonder / I suggest" framework for giving difficult feedback]
|
||||
|
||||
---
|
||||
|
||||
**Theme 2: [Development area — e.g. Strategic communication to leadership]**
|
||||
|
||||
[2–3 sentences.]
|
||||
|
||||
*"[Direct quote]"*
|
||||
|
||||
**Suggested actions:**
|
||||
- [...]
|
||||
- [...]
|
||||
|
||||
---
|
||||
|
||||
### Ratings Summary
|
||||
|
||||
| Competency | Average score | Range | Notable pattern |
|
||||
|---|---|---|---|
|
||||
| Delivery & Execution | [X.X] | [X–X] | [e.g. Consistently high; one outlier] |
|
||||
| Communication & Collaboration | [X.X] | [X–X] | [e.g. Peers score higher than direct reports] |
|
||||
| Leadership & Influence | [X.X] | [X–X] | [...] |
|
||||
| Strategic Thinking | [X.X] | [X–X] | [...] |
|
||||
| Culture & Values | [X.X] | [X–X] | [...] |
|
||||
| **Overall** | **[X.X]** | [X–X] | |
|
||||
|
||||
**Score variance:** [Is there high agreement or wide spread across reviewers? High variance suggests the behaviour is context-dependent — explore when and with whom.]
|
||||
|
||||
---
|
||||
|
||||
### Direct Message from Reviewers
|
||||
|
||||
[Include up to 3 unedited quotes from the "Is there anything else you want [Name] to know?" question. These are shared verbatim as agreed in the survey instructions.]
|
||||
|
||||
*"[Quote 1]"*
|
||||
|
||||
*"[Quote 2]"*
|
||||
|
||||
*"[Quote 3]"*
|
||||
|
||||
---
|
||||
|
||||
### Recommended Focus for the Next 90 Days
|
||||
|
||||
[1–2 specific, measurable development commitments. Written to be agreed in the feedback conversation — not prescriptive.]
|
||||
|
||||
1. **[Behaviour to change]:** [What does success look like at 90 days? How will we measure it?]
|
||||
2. **[Skill to build]:** [What specific resource, practice, or support will help? Who will observe progress?]
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Survey questions are behaviourally anchored — they describe observable actions, not attitudes
|
||||
- [ ] Open-ended questions ask for specific examples — not general impressions
|
||||
- [ ] Report strengths are backed by specific evidence, not generic praise
|
||||
- [ ] Development areas name the behaviour and its impact — not the person's character
|
||||
- [ ] Suggested actions are specific enough that the reviewee knows exactly what to do differently on Monday
|
||||
- [ ] Direct quotes are genuinely direct — not paraphrased into blandness
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- "Build a 360 feedback survey for a [role] at senior level"
|
||||
- "Write a 360 feedback report from these notes: [paste notes]"
|
||||
- "Design a 360 review template for engineering managers"
|
||||
- "Help me write constructive 360 feedback for my colleague [Name]"
|
||||
- "Create a peer feedback survey for our upcoming performance cycle"
|
||||
@@ -0,0 +1,262 @@
|
||||
---
|
||||
name: team-health-check
|
||||
description: "Run a structured team health assessment. Use when asked to run a team health check, assess team morale, facilitate a team retrospective on ways of working, or evaluate team dynamics. Produces a health assessment across key dimensions with RAG status, underlying signals, and prioritised improvement actions."
|
||||
---
|
||||
|
||||
# Team Health Check Skill
|
||||
|
||||
This skill produces a structured team health assessment inspired by Spotify's health check model and extended with engineering, product, and cross-functional team dimensions. Output can be used as a facilitation guide for a live session or as an async survey-and-report format.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask the user for these if not provided:
|
||||
- **Team name and function** (engineering squad, product team, sales pod, etc.)
|
||||
- **Team size and composition** (how many people, what roles)
|
||||
- **Format** — facilitated live session or async survey + report?
|
||||
- **Context** — why are you running this now? (new team / ongoing ritual / post-incident / low morale signal)
|
||||
- **Any known issues** — anything the facilitator knows going in that will colour the results?
|
||||
|
||||
## Output Structure
|
||||
|
||||
---
|
||||
|
||||
# Team Health Check: [Team Name]
|
||||
|
||||
**Date:** [Date]
|
||||
**Facilitated by:** [Name or role]
|
||||
**Team size:** [X people]
|
||||
**Format:** [Live session (60 min) / Async survey + report]
|
||||
**Cycle:** [One-off / Quarterly / Monthly]
|
||||
|
||||
---
|
||||
|
||||
## Part 1: Facilitation Guide (Live Session)
|
||||
|
||||
Use this guide to run the session in 60 minutes.
|
||||
|
||||
### Session structure
|
||||
|
||||
| Time | Activity | Owner |
|
||||
|---|---|---|
|
||||
| 0–5 min | Framing and ground rules | Facilitator |
|
||||
| 5–40 min | Card voting — 7 dimensions, 5 min each | Full team |
|
||||
| 40–50 min | Top 3 themes discussion | Full team |
|
||||
| 50–58 min | Actions and owners | Team lead |
|
||||
| 58–60 min | Close and next date | Facilitator |
|
||||
|
||||
### Ground rules (read at start)
|
||||
|
||||
- This is not a performance review — there are no wrong answers
|
||||
- We're assessing the team, not individuals — speak about "we" not "they"
|
||||
- What's said here stays here — results shared as aggregated themes, not attributed to individuals
|
||||
- The goal is one or two actionable improvements, not a long list
|
||||
|
||||
### Voting mechanic
|
||||
|
||||
For each dimension, each team member votes with one of three cards:
|
||||
- 🟢 **Green** — working well, we're proud of this
|
||||
- 🟡 **Amber** — some things work, but there are issues worth discussing
|
||||
- 🔴 **Red** — we have a real problem here that's slowing us down
|
||||
|
||||
After voting, the team discusses: what drove the votes? What would make this Green?
|
||||
|
||||
---
|
||||
|
||||
## Part 2: Health Dimensions
|
||||
|
||||
---
|
||||
|
||||
### Dimension 1: Delivering Value
|
||||
|
||||
*Are we shipping things that matter, at the pace we should?*
|
||||
|
||||
| Indicator | Probes for discussion |
|
||||
|---|---|
|
||||
| We ship work that creates real value for our users | How do we know our output is valuable? When did we last talk to a user? |
|
||||
| Our pace of delivery feels healthy and sustainable | Are we consistently shipping? Or do we have long dry spells? |
|
||||
| We have clarity on what "done" looks like | Do we have a shared definition of ready and done? |
|
||||
| We celebrate shipping, not just building | Do we acknowledge completed work, or does it just disappear into the backlog? |
|
||||
|
||||
**Current vote:** 🟢 / 🟡 / 🔴
|
||||
|
||||
**Key themes from discussion:**
|
||||
|
||||
**What would make this Green?**
|
||||
|
||||
---
|
||||
|
||||
### Dimension 2: Easy to Release
|
||||
|
||||
*Is releasing software (or our work) smooth and low-risk?*
|
||||
|
||||
| Indicator | Probes for discussion |
|
||||
|---|---|
|
||||
| We can release whenever we choose, without anxiety | What does a release feel like? Smooth or stressful? |
|
||||
| Our deployment process is automated and reliable | How much manual work does a release involve? |
|
||||
| We have confidence in our test coverage | Do we catch bugs before users do? |
|
||||
| Rollback is fast and rehearsed | Have we ever rolled back? How long did it take? |
|
||||
|
||||
**Current vote:** 🟢 / 🟡 / 🔴
|
||||
|
||||
**Key themes from discussion:**
|
||||
|
||||
**What would make this Green?**
|
||||
|
||||
---
|
||||
|
||||
### Dimension 3: Fun & Morale
|
||||
|
||||
*Do people enjoy working here and with each other?*
|
||||
|
||||
| Indicator | Probes for discussion |
|
||||
|---|---|
|
||||
| People generally enjoy coming to work | If you had to describe the team energy in one word, what would it be? |
|
||||
| We celebrate successes as a team | When did we last properly celebrate something? |
|
||||
| Interpersonal dynamics are healthy — no drama or cliques | Are there any relationships that are strained or avoided? |
|
||||
| We laugh and have non-work conversations | Do we know each other as people, not just colleagues? |
|
||||
|
||||
**Current vote:** 🟢 / 🟡 / 🔴
|
||||
|
||||
**Key themes from discussion:**
|
||||
|
||||
**What would make this Green?**
|
||||
|
||||
---
|
||||
|
||||
### Dimension 4: Psychological Safety
|
||||
|
||||
*Can people speak up, take risks, and make mistakes without fear?*
|
||||
|
||||
| Indicator | Probes for discussion |
|
||||
|---|---|
|
||||
| People raise concerns without worrying about the consequences | When did someone last raise a concern publicly? What happened? |
|
||||
| Mistakes are treated as learning opportunities, not blame events | Think of the last mistake on the team. How was it handled? |
|
||||
| People challenge each other's ideas in a constructive way | Do we have real debates, or do we agree in the room and disagree in the corridor? |
|
||||
| Everyone's voice feels equally heard regardless of seniority | Do the same people always speak first and longest? |
|
||||
|
||||
**Current vote:** 🟢 / 🟡 / 🔴
|
||||
|
||||
**Key themes from discussion:**
|
||||
|
||||
**What would make this Green?**
|
||||
|
||||
---
|
||||
|
||||
### Dimension 5: Speed & Feedback Loops
|
||||
|
||||
*Do we learn fast and adjust quickly?*
|
||||
|
||||
| Indicator | Probes for discussion |
|
||||
|---|---|
|
||||
| We get feedback on our work quickly (from users, data, tests) | How long after shipping do we know if something worked? |
|
||||
| Our planning and retrospective cycles help us improve | Do retros lead to real change, or do the same issues come back? |
|
||||
| We cut work that isn't working, even when it's hard | Can you name something we've stopped doing because it wasn't working? |
|
||||
| Our meetings and processes don't slow us down | Which meetings do people dread? Which do they find valuable? |
|
||||
|
||||
**Current vote:** 🟢 / 🟡 / 🔴
|
||||
|
||||
**Key themes from discussion:**
|
||||
|
||||
**What would make this Green?**
|
||||
|
||||
---
|
||||
|
||||
### Dimension 6: Mission & Purpose
|
||||
|
||||
*Do we understand why our work matters?*
|
||||
|
||||
| Indicator | Probes for discussion |
|
||||
|---|---|
|
||||
| Everyone on the team can articulate why their work matters | Could each person on this team explain to a stranger why their work is important? |
|
||||
| The team's goals are clear and shared | Can everyone name the team's top 3 priorities right now? |
|
||||
| Our work connects to the wider company direction | Do we understand how we fit into the bigger picture? |
|
||||
| We're proud of what this team builds | If you described your team's work to someone you respect, would you feel good about it? |
|
||||
|
||||
**Current vote:** 🟢 / 🟡 / 🔴
|
||||
|
||||
**Key themes from discussion:**
|
||||
|
||||
**What would make this Green?**
|
||||
|
||||
---
|
||||
|
||||
### Dimension 7: Collaboration & Support
|
||||
|
||||
*Do we work well together and support each other?*
|
||||
|
||||
| Indicator | Probes for discussion |
|
||||
|---|---|
|
||||
| People actively help each other when someone is stuck | Think of the last time someone was blocked — what happened? |
|
||||
| Knowledge is shared openly — no information silos | Is there any knowledge that only one person holds? What's the risk? |
|
||||
| Cross-team collaboration is smooth and low-friction | Which team is hardest to collaborate with and why? |
|
||||
| People feel supported when they're struggling | Is there psychological safety to say "I'm struggling with this"? |
|
||||
|
||||
**Current vote:** 🟢 / 🟡 / 🔴
|
||||
|
||||
**Key themes from discussion:**
|
||||
|
||||
**What would make this Green?**
|
||||
|
||||
---
|
||||
|
||||
## Part 3: Health Summary & Report
|
||||
|
||||
Use this template to document results after the session or survey.
|
||||
|
||||
---
|
||||
|
||||
### RAG Summary Dashboard
|
||||
|
||||
| Dimension | Score | Status | Trend vs last quarter |
|
||||
|---|---|---|---|
|
||||
| Delivering Value | [X/5] | 🟢 / 🟡 / 🔴 | [↑ / → / ↓] |
|
||||
| Easy to Release | [X/5] | 🟢 / 🟡 / 🔴 | [...] |
|
||||
| Fun & Morale | [X/5] | 🟢 / 🟡 / 🔴 | [...] |
|
||||
| Psychological Safety | [X/5] | 🟢 / 🟡 / 🔴 | [...] |
|
||||
| Speed & Feedback Loops | [X/5] | 🟢 / 🟡 / 🔴 | [...] |
|
||||
| Mission & Purpose | [X/5] | 🟢 / 🟡 / 🔴 | [...] |
|
||||
| Collaboration & Support | [X/5] | 🟢 / 🟡 / 🔴 | [...] |
|
||||
| **Overall** | **[X/5]** | 🟢 / 🟡 / 🔴 | [↑ / → / ↓] |
|
||||
|
||||
---
|
||||
|
||||
### Top Themes
|
||||
|
||||
**What's working well (keep doing):**
|
||||
1. [...]
|
||||
2. [...]
|
||||
|
||||
**What needs attention (most important to fix):**
|
||||
1. [Most pressing issue — specific, with evidence from the session]
|
||||
2. [Second issue]
|
||||
3. [Third issue — if applicable]
|
||||
|
||||
---
|
||||
|
||||
### Action Plan
|
||||
|
||||
| Action | Owner | Due date | Success indicator |
|
||||
|---|---|---|---|
|
||||
| [Specific action — e.g. Introduce pairing Fridays for knowledge sharing] | [Team lead / individual] | [Date] | [How will we know it worked?] |
|
||||
| [...] | [...] | [...] | [...] |
|
||||
|
||||
**Next health check:** [Date — recommended 6–8 weeks for teams with active improvement actions, 13 weeks for steady-state teams]
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Session ground rules established psychological safety before voting started
|
||||
- [ ] Each dimension had open discussion, not just a vote
|
||||
- [ ] Actions are specific enough to be verifiably done — no vague commitments like "improve communication"
|
||||
- [ ] Each action has a single owner — not "the team"
|
||||
- [ ] Results are shared with the team, not kept by management
|
||||
- [ ] Trend data is tracked across cycles to show improvement or regression
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- "Run a team health check for my engineering squad"
|
||||
- "Facilitate a team health assessment — we've had some morale issues"
|
||||
- "Build a team health check survey for my product team"
|
||||
- "Generate a Spotify-style health check for our cross-functional pod"
|
||||
- "Create a quarterly team health check template"
|
||||
@@ -0,0 +1,228 @@
|
||||
---
|
||||
name: partnership-proposal
|
||||
description: "Write a B2B partnership proposal or business case. Use when asked to write a partnership proposal, draft a partnership brief, structure a co-marketing proposal, or create a business case for a strategic partnership. Produces a structured proposal with value proposition, partnership model, commercial terms, and mutual commitments."
|
||||
---
|
||||
|
||||
# Partnership Proposal Skill
|
||||
|
||||
This skill produces a complete B2B partnership proposal covering the partnership rationale, mutual value, partnership model, commercial terms, governance, and a joint go-to-market plan. Output is ready to share with a prospective partner or use as the basis for a business case to internal stakeholders.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask the user for these if not provided:
|
||||
- **Your company** — name, what you do, and the audience you serve
|
||||
- **Prospective partner** — name, what they do, and their audience
|
||||
- **Partnership type** — technology integration / co-marketing / reseller / referral / strategic alliance / OEM
|
||||
- **Partnership goal** — what does each party get? (new customers / revenue / product capability / market reach)
|
||||
- **Proposed commercial model** — revenue share, referral fee, licensing, co-investment?
|
||||
- **Urgency or context** — is there a specific event, product launch, or competitive reason for this partnership?
|
||||
|
||||
## Output Structure
|
||||
|
||||
---
|
||||
|
||||
# Partnership Proposal: [Your Company] × [Partner Company]
|
||||
|
||||
**Prepared by:** [Name, Role at Your Company]
|
||||
**Date:** [Date]
|
||||
**Partnership type:** [Technology / Co-marketing / Reseller / Referral / Strategic Alliance]
|
||||
**Proposal status:** [Initial proposal / For negotiation / Final]
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
[3–5 sentences. Answer: what are we proposing, why now, and what does each party stand to gain? Write this so a busy executive can understand the proposal in 60 seconds without reading further.]
|
||||
|
||||
**Headline value for [Partner]:**
|
||||
> [One sentence — the most compelling thing this partnership does for them]
|
||||
|
||||
**Headline value for [Your Company]:**
|
||||
> [One sentence — the most compelling thing this partnership does for you]
|
||||
|
||||
---
|
||||
|
||||
## 1. The Opportunity
|
||||
|
||||
**Market context:** [Why does this partnership make sense now? What's happening in the market that creates a window for this to work?]
|
||||
|
||||
**Shared customer:** [Describe the customer both organisations serve — the overlap that makes this logical. Include size of the shared addressable market if you have it.]
|
||||
|
||||
**Problem neither of us solves alone:** [What can't either party do for the shared customer independently that the partnership would enable?]
|
||||
|
||||
---
|
||||
|
||||
## 2. What We're Proposing
|
||||
|
||||
**Partnership model:**
|
||||
|
||||
| Element | Description |
|
||||
|---|---|
|
||||
| **Type** | [Technology integration / Co-marketing / Reseller / Referral / OEM] |
|
||||
| **Scope** | [What specifically are we partnering on? — product features, joint campaigns, distribution, etc.] |
|
||||
| **Exclusivity** | [Exclusive in [region/segment] / Non-exclusive / Right of first refusal] |
|
||||
| **Duration** | [Initial term — e.g. 12 months, renewable] |
|
||||
| **Geographic scope** | [UK / EMEA / Global / Specific markets] |
|
||||
|
||||
**What this looks like in practice:**
|
||||
|
||||
[3–5 bullet points describing what the partnership actually means day-to-day. Make it concrete and operational — not abstract. e.g.:]
|
||||
- [Our product will natively integrate with [Partner's product] — the integration will be live in [timeframe]]
|
||||
- [We will co-market to each other's customer bases — joint webinar, co-authored content, shared newsletter placement]
|
||||
- [Each company will train a dedicated partnership contact who manages the relationship]
|
||||
- [[Partner] will list [Your product] in their marketplace / app directory / referral programme]
|
||||
|
||||
---
|
||||
|
||||
## 3. Value Proposition — What Each Party Gets
|
||||
|
||||
### For [Partner]
|
||||
|
||||
| Value | Evidence / Basis |
|
||||
|---|---|
|
||||
| **[New customer reach]** | [e.g. Access to [Your Company]'s [X,000] [role] customers — [X%] of whom have expressed interest in [Partner's category]] |
|
||||
| **[Product capability]** | [e.g. [Partner]'s product gains [capability] that [X%] of their customers have requested — based on [source]] |
|
||||
| **[Revenue opportunity]** | [e.g. Estimated [£/$/€ X] in referral revenue in Year 1 based on [X%] conversion from shared pipeline] |
|
||||
| **[Market differentiation]** | [e.g. The integration creates a meaningful competitive moat vs [Competitor] who lacks this capability] |
|
||||
|
||||
### For [Your Company]
|
||||
|
||||
| Value | Evidence / Basis |
|
||||
|---|---|
|
||||
| **[Distribution]** | [e.g. Access to [Partner]'s [X,000] customers in [segment] — a segment where we currently have [X] customers] |
|
||||
| **[Credibility]** | [e.g. Association with [Partner]'s brand accelerates enterprise sales cycles — [Partner] is trusted by [X] of the Fortune 500] |
|
||||
| **[Revenue]** | [e.g. Target [X] referral customers in Year 1 at average ACV of [£X] = [£X ARR]] |
|
||||
| **[Product]** | [e.g. [Partner]'s data / capability enhances [specific part of our product] — improving [user outcome]] |
|
||||
|
||||
---
|
||||
|
||||
## 4. Commercial Model
|
||||
|
||||
**Proposed commercial terms:**
|
||||
|
||||
| Term | Proposal | Notes |
|
||||
|---|---|---|
|
||||
| **Revenue share** | [e.g. [X%] of ARR from customers referred by [Partner]] | [Standard in this category: [X–Y%] range] |
|
||||
| **Referral fee** | [e.g. £[X] per qualified lead that converts] | [Or: flat fee per introduction vs % of closed deal] |
|
||||
| **Licensing / access** | [e.g. [Partner] provides API access at no cost in exchange for integration and co-marketing] | [...] |
|
||||
| **Co-marketing investment** | [e.g. Each party commits [£X] to joint marketing activities per quarter] | [...] |
|
||||
| **Minimum commitment** | [e.g. [X] qualified referrals per quarter / [£X] GMV per year] | [Optional — only if there's a meaningful minimum that makes sense] |
|
||||
|
||||
**Payment terms:** [Monthly / Quarterly in arrears / Annual true-up]
|
||||
|
||||
**What we're not proposing:** [Be explicit about what's off the table — e.g. equity / exclusivity in all markets / upfront payment]
|
||||
|
||||
---
|
||||
|
||||
## 5. Joint Go-to-Market Plan
|
||||
|
||||
**Phase 1: Foundation (Months 1–2)**
|
||||
|
||||
| Activity | Owner | Timeline |
|
||||
|---|---|---|
|
||||
| Technical integration scoped and resourced | [Engineering at both companies] | [Month 1] |
|
||||
| Partnership launch announcement drafted | [Marketing at both companies] | [Month 1] |
|
||||
| Joint customer case study identified | [CSM at both companies] | [Month 2] |
|
||||
| Partner enablement — each team trained on the other's product | [Partnership lead, both sides] | [Month 2] |
|
||||
|
||||
**Phase 2: Launch (Month 3)**
|
||||
|
||||
| Activity | Owner | Timeline |
|
||||
|---|---|---|
|
||||
| Integration live in both products / marketplace | [Engineering] | [Month 3] |
|
||||
| Joint press release / blog post / email announcement | [Marketing] | [Month 3] |
|
||||
| First joint webinar | [Both companies] | [Month 3] |
|
||||
| First joint pipeline reviewed | [Partnership leads] | [Month 3] |
|
||||
|
||||
**Phase 3: Scale (Months 4–12)**
|
||||
|
||||
| Activity | Owner | Cadence |
|
||||
|---|---|---|
|
||||
| Co-sell on named accounts | [AE at both companies] | [Monthly] |
|
||||
| Joint content (blog, webinar, case study) | [Marketing] | [Quarterly] |
|
||||
| Pipeline and revenue review | [Partnership leads] | [Monthly] |
|
||||
| Partnership QBR | [VP level, both companies] | [Quarterly] |
|
||||
|
||||
---
|
||||
|
||||
## 6. Success Metrics
|
||||
|
||||
How we'll know the partnership is working:
|
||||
|
||||
| Metric | Year 1 target | Measurement |
|
||||
|---|---|---|
|
||||
| Customers referred (each direction) | [X] | [CRM tracking — tagged as partner-sourced] |
|
||||
| Revenue from partnership | [£/$/€ X ARR] | [CRM + finance reporting] |
|
||||
| Integration adoption | [X% of mutual customers using integration] | [Product analytics] |
|
||||
| Customer satisfaction with integration | [NPS ≥ X] | [Post-integration survey] |
|
||||
| Joint pipeline generated | [£X] | [Quarterly pipeline review] |
|
||||
|
||||
**Review cadence:** Monthly partnership lead check-in + Quarterly business review at VP level
|
||||
|
||||
---
|
||||
|
||||
## 7. Governance & Operations
|
||||
|
||||
**Partnership contacts:**
|
||||
|
||||
| Role | [Your Company] | [Partner] |
|
||||
|---|---|---|
|
||||
| Partnership lead (day-to-day) | [Name, email] | [TBC] |
|
||||
| Executive sponsor | [Name, title] | [TBC] |
|
||||
| Technical lead | [Name] | [TBC] |
|
||||
| Marketing lead | [Name] | [TBC] |
|
||||
|
||||
**Decision-making:**
|
||||
- Day-to-day partnership operations: partnership leads
|
||||
- Commercial term changes: VP-level approval from both parties
|
||||
- Partnership termination: CEO/MD sign-off + [X days] written notice
|
||||
|
||||
**Legal framework:**
|
||||
- [ ] Partnership agreement / MOU to be drafted by [Company]'s legal team
|
||||
- [ ] Data processing agreement (if personal data is shared)
|
||||
- [ ] NDAs: [already in place / to be signed before detailed discussions]
|
||||
- [ ] IP ownership: [Clarify who owns jointly developed materials, integrations, content]
|
||||
|
||||
---
|
||||
|
||||
## 8. Risks & Mitigations
|
||||
|
||||
| Risk | Likelihood | Mitigation |
|
||||
|---|---|---|
|
||||
| Partnership champion leaves [Partner] | M | Ensure VP-level sponsorship; build multiple relationships |
|
||||
| Integration takes longer than planned | M | Scope technical work in Phase 1; set realistic launch commitment |
|
||||
| Low adoption of the integration | M | Include in onboarding for both products; co-market to existing customers not just new |
|
||||
| Partner signs with our competitor | L | Discuss exclusivity options; prioritise quick launch to create switching costs |
|
||||
| Commercial model becomes imbalanced | L | Quarterly review with clear exit terms if targets are consistently missed |
|
||||
|
||||
---
|
||||
|
||||
## 9. Proposed Next Steps
|
||||
|
||||
| # | Action | Owner | By when |
|
||||
|---|---|---|---|
|
||||
| 1 | [Partner] reviews this proposal and provides feedback | [[Partner name]] | [Date] |
|
||||
| 2 | Both parties sign NDA (if not already in place) | [Legal, both sides] | [Before next meeting] |
|
||||
| 3 | Technical discovery call — assess integration feasibility | [Engineering leads] | [Date] |
|
||||
| 4 | Commercial terms negotiation | [Partnership leads / VP] | [Date] |
|
||||
| 5 | MOU / partnership agreement drafted and signed | [Legal] | [Date] |
|
||||
| 6 | Integration and launch planning begins | [Both teams] | [Date] |
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Value proposition for the partner is written from their perspective — not yours
|
||||
- [ ] Commercial model includes specific numbers, not just structure
|
||||
- [ ] "What we're not proposing" section prevents misaligned expectations
|
||||
- [ ] Go-to-market plan has named owners and dates, not "TBD"
|
||||
- [ ] Success metrics are agreed bilaterally — not set unilaterally
|
||||
- [ ] Risks section includes the most uncomfortable risk (partner signs with a competitor)
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- "Write a partnership proposal for [Company] to partner with [Partner]"
|
||||
- "Draft a co-marketing partnership brief between us and [Partner]"
|
||||
- "Create a reseller partnership proposal for [Company]"
|
||||
- "Build the business case for a strategic partnership with [Partner]"
|
||||
- "Structure a technology integration partnership proposal"
|
||||
@@ -0,0 +1,309 @@
|
||||
---
|
||||
name: community-management-playbook
|
||||
description: "Build a community management playbook for a brand's social media channels. Use when asked to create guidelines for managing comments, DMs, and community interactions, define a moderation policy, or build response frameworks for social media community managers. Produces a complete playbook with response templates, escalation paths, moderation rules, and tone guidelines."
|
||||
---
|
||||
|
||||
# Community Management Playbook Skill
|
||||
|
||||
This skill produces a complete community management playbook covering response frameworks, tone guidelines, comment moderation rules, DM handling, crisis and escalation paths, response templates, and community health metrics. Output gives a community manager or social media team everything they need to manage public interactions consistently, professionally, and at speed.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask the user for these if not provided:
|
||||
- **Brand / product name**
|
||||
- **Active platforms** — which channels need community management (Instagram, LinkedIn, X/Twitter, Facebook, TikTok, YouTube, Discord, Reddit, etc.)
|
||||
- **Team structure** — who manages community? (solo, small team, agency, rotating)
|
||||
- **Brand tone of voice** — how the brand sounds (e.g. warm and friendly / professional / witty / technical)
|
||||
- **Primary community type** — customers, fans, professional network, creators, users of a product
|
||||
- **Common comment types** — what kinds of interactions do you get? (support questions, complaints, praise, spam, trolls)
|
||||
- **Response time SLA** — how fast must the team respond? (e.g. within 2 hours on weekdays)
|
||||
|
||||
## Output Structure
|
||||
|
||||
---
|
||||
|
||||
# Community Management Playbook: [Brand Name]
|
||||
|
||||
**Version:** 1.0
|
||||
**Platforms covered:** [List]
|
||||
**Team:** [Names or roles]
|
||||
**Last updated:** [Date]
|
||||
|
||||
---
|
||||
|
||||
## 1. Why Community Management Matters
|
||||
|
||||
[2–3 sentences on what's at stake: brand reputation, customer loyalty, algorithm signals, trust-building. Frame community management as a business function, not just social admin.]
|
||||
|
||||
**Our community management goals:**
|
||||
1. [Goal 1: e.g. Respond to every comment and DM within our SLA — no question goes unanswered]
|
||||
2. [Goal 2: e.g. Turn complaints into loyalty moments — every resolved issue is a trust win]
|
||||
3. [Goal 3: e.g. Amplify positive sentiment — surface customer stories and user wins]
|
||||
4. [Goal 4: e.g. Protect brand reputation — remove harmful content quickly and consistently]
|
||||
|
||||
---
|
||||
|
||||
## 2. Response Framework
|
||||
|
||||
Use this decision tree for every comment or message:
|
||||
|
||||
```
|
||||
Is it spam, phishing, or dangerous content?
|
||||
→ YES: Delete immediately. Report if platform requires. Log in moderation tracker.
|
||||
→ NO: Continue ↓
|
||||
|
||||
Is it a hate comment, harassment, or offensive content?
|
||||
→ YES: Hide or delete. Consider account block. Escalate if ongoing. See Section 6.
|
||||
→ NO: Continue ↓
|
||||
|
||||
Is it a customer complaint or support question?
|
||||
→ YES: Respond within SLA. Acknowledge, empathise, resolve or redirect. See Section 4.
|
||||
→ NO: Continue ↓
|
||||
|
||||
Is it positive — praise, testimonial, or user win?
|
||||
→ YES: Like + reply with warm acknowledgement. Flag for social proof content if suitable.
|
||||
→ NO: Continue ↓
|
||||
|
||||
Is it a question about the brand, product, or content?
|
||||
→ YES: Answer clearly and helpfully. Include a CTA if relevant.
|
||||
→ NO: Continue ↓
|
||||
|
||||
Is it a general conversation starter or neutral engagement?
|
||||
→ YES: Engage authentically — like, reply briefly, or ask a follow-up question.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Response Time SLAs
|
||||
|
||||
| Channel | Comment type | Target response time | Owner |
|
||||
|---|---|---|---|
|
||||
| [Instagram] | Customer complaint | [2 hours (business hours)] | [CM Lead] |
|
||||
| [Instagram] | General comment / question | [Same day] | [CM team] |
|
||||
| [Instagram] | DM | [4 hours (business hours)] | [CM Lead] |
|
||||
| [LinkedIn] | Professional comment / question | [4 hours (business hours)] | [CM / Marketing] |
|
||||
| [X / Twitter] | Public reply / mention | [2 hours (business hours)] | [CM Lead] |
|
||||
| [X / Twitter] | DM | [4 hours (business hours)] | [CM team] |
|
||||
| [Facebook] | Comment | [4 hours (business hours)] | [CM team] |
|
||||
| [TikTok] | Comment on promoted post | [8 hours] | [CM team] |
|
||||
| [YouTube] | Comment | [24 hours] | [CM team] |
|
||||
|
||||
**Out-of-hours coverage:**
|
||||
- [Define weekend / evening coverage — e.g. "On-call CM checks mentions at 9am, 1pm, and 6pm on weekends"]
|
||||
- Crisis escalation is always on — see Section 6 for out-of-hours escalation contacts
|
||||
|
||||
---
|
||||
|
||||
## 4. Response Templates
|
||||
|
||||
These are starting-point templates — always personalise with the person's name and specific context.
|
||||
|
||||
### Positive comments
|
||||
|
||||
**Praise / testimonial:**
|
||||
> "Thank you so much, [name]! 🙌 This genuinely made our day. So glad [product/service] is working for you. [Add specific personal note if possible]."
|
||||
|
||||
**User-generated content / sharing their experience:**
|
||||
> "Love seeing this, [name]! Thanks for sharing 🙌. [Relevant genuine comment on their specific post or experience]."
|
||||
|
||||
**Review or recommendation:**
|
||||
> "Thank you for taking the time to share this, [name] — really appreciate it. [Add genuine specific reaction]. If you ever want to [next step / share more / join community], we'd love to have you."
|
||||
|
||||
---
|
||||
|
||||
### Questions about the product or brand
|
||||
|
||||
**Feature question:**
|
||||
> "Great question, [name]! [Answer clearly in 1–3 sentences]. If you'd like more detail, [link to docs / help centre / DM us]. Happy to help with anything else!"
|
||||
|
||||
**Pricing / availability question:**
|
||||
> "[Answer] — [link if relevant]. Feel free to DM us if you need anything specific. 😊"
|
||||
|
||||
**"Is this available in [region/format]?" question:**
|
||||
> "[Answer with current availability]. If that's changed, you'll always see it first at [link / newsletter sign-up / our channels]. 🙌"
|
||||
|
||||
---
|
||||
|
||||
### Complaints
|
||||
|
||||
**Product issue — acknowledged, redirecting to support:**
|
||||
> "Hi [name], really sorry to hear this — that's definitely not the experience we want for you. 😔 Could you DM us with [order number / account email / details]? We'll get this sorted as quickly as possible."
|
||||
|
||||
**Shipping / fulfilment complaint:**
|
||||
> "Hi [name], thank you for letting us know and I'm so sorry for this. We want to make it right. Please DM us with your order reference and we'll investigate right away."
|
||||
|
||||
**General dissatisfaction:**
|
||||
> "Hi [name], I'm sorry to hear you're not happy — your feedback genuinely matters to us. Could you DM us or email [support email] so we can understand what happened and fix it? We really do want to get this right."
|
||||
|
||||
**Public complaint that needs urgent attention:**
|
||||
> "Hi [name], I can see why that would be frustrating and I want to make sure we sort this out properly. I'm going to DM you now — please look out for a message from us."
|
||||
|
||||
---
|
||||
|
||||
### Difficult interactions
|
||||
|
||||
**Polite but persistent critic:**
|
||||
> "Hi [name], thank you for the honest feedback — we do read and take this seriously. We can't always respond to every individual point publicly, but if you'd like to share more detail, [DM us / email us at X]. We're genuinely working on [relevant area] and appreciate you holding us accountable."
|
||||
|
||||
**Misinformation or incorrect claim about the brand:**
|
||||
> "Hi [name], just wanted to gently clarify — [correct the record factually in 1–2 sentences]. Happy to share more if useful! [Link to source / official page if relevant]."
|
||||
|
||||
**Competitor attack or negative comparison:**
|
||||
> [Do NOT engage publicly with competitive comparisons. Respond only if there's factual misinformation. Template: "Hi [name], happy to share what makes [brand] work for our customers — feel free to DM us if you'd like to know more."]
|
||||
|
||||
---
|
||||
|
||||
### DM templates
|
||||
|
||||
**First DM response — complaint:**
|
||||
> "Hi [name], thanks for reaching out. I'm [name] from the [brand] team. I've seen your [comment/message] and want to make sure we get this sorted for you properly. Could you share [details needed — order number, email, screenshots]? I'll personally make sure this is resolved."
|
||||
|
||||
**First DM response — support question:**
|
||||
> "Hi [name]! Thanks for getting in touch. Happy to help — [answer or next step]. If you need anything else, just reply here. 😊"
|
||||
|
||||
**Issue resolved — closing DM:**
|
||||
> "Glad we could sort that out, [name]! If you ever need anything else, we're here. Have a great [day/weekend]! 🙌"
|
||||
|
||||
---
|
||||
|
||||
## 5. Moderation Rules
|
||||
|
||||
**Content that must be deleted immediately:**
|
||||
- [ ] Spam (repeated posts, fake giveaways, phishing links)
|
||||
- [ ] Explicit or NSFW content
|
||||
- [ ] Personal attacks on other community members
|
||||
- [ ] Doxxing (sharing personal information about another person)
|
||||
- [ ] Content that violates platform terms of service
|
||||
- [ ] Illegal content or illegal product promotion
|
||||
|
||||
**Content that should be hidden (not deleted) — review within 4 hours:**
|
||||
- [ ] Unverified complaints that may require investigation before action
|
||||
- [ ] Offensive language that isn't targeting a specific person
|
||||
- [ ] Posts that may be legitimate but contain sensitive information
|
||||
|
||||
**Content that should be left (even if negative) — respond and monitor:**
|
||||
- [ ] Genuine product criticism or negative reviews
|
||||
- [ ] Complaints that are being actively resolved
|
||||
- [ ] Controversial opinions that are within the rules of civil debate
|
||||
- [ ] Negative comparisons to competitors (only respond if misinformation)
|
||||
|
||||
**Account-level actions:**
|
||||
|
||||
| Action | When to use |
|
||||
|---|---|
|
||||
| Comment hide | First instance of borderline content |
|
||||
| Comment delete | Clear rule violation |
|
||||
| User block | Repeated harassment / spam after warning |
|
||||
| Report to platform | Content that may breach platform T&Cs or laws |
|
||||
|
||||
**"Never delete to silence" rule:** Never delete a genuine complaint or criticism just because it's uncomfortable. Deleting legitimate negative feedback damages trust more than the original complaint.
|
||||
|
||||
---
|
||||
|
||||
## 6. Escalation & Crisis Protocol
|
||||
|
||||
### Escalation tiers
|
||||
|
||||
**Tier 1 — CM handles directly:**
|
||||
- Routine complaints, questions, thank-yous
|
||||
- Single negative comment, isolated incident
|
||||
- Standard off-topic or mildly unhappy comment
|
||||
|
||||
**Tier 2 — Escalate to [Marketing Lead / Brand Manager] within 2 hours:**
|
||||
- Customer with significant public platform (journalist, influencer, known figure)
|
||||
- Complaint gaining traction (10+ likes on a negative comment)
|
||||
- Legal or compliance mention ("I'm going to sue", "trading standards", "data breach")
|
||||
- Media interest — journalist asking questions publicly
|
||||
|
||||
**Tier 3 — Escalate to [CMO / Founder / CEO] immediately:**
|
||||
- Viral negative content (100+ shares / views growing rapidly)
|
||||
- Allegation of safety issue, injury, or product harm
|
||||
- Coordinated negative campaign or pile-on
|
||||
- Any media coverage of a complaint
|
||||
- Potential crisis — brand reputation at risk
|
||||
|
||||
### Crisis response protocol
|
||||
|
||||
1. **Stop scheduled posting** — pause all queued content immediately
|
||||
2. **Assess** — what is the scope? How fast is it spreading? What's the allegation?
|
||||
3. **Brief leadership** — share screenshot, link, and initial assessment within 30 minutes
|
||||
4. **Hold public response** — do not post publicly until leadership approves messaging
|
||||
5. **Draft response options** — prepare 2–3 response options (acknowledge / deny / defer)
|
||||
6. **Respond or don't respond?** — sometimes silence + private resolution beats a public statement
|
||||
7. **Monitor** — track mentions every 30 minutes during a crisis
|
||||
8. **Post-crisis review** — within 48 hours, document what happened and what to do differently
|
||||
|
||||
**Out-of-hours escalation contacts:**
|
||||
- CM Lead: [Name, mobile]
|
||||
- Marketing Lead: [Name, mobile]
|
||||
- [Senior escalation]: [Name, mobile]
|
||||
|
||||
---
|
||||
|
||||
## 7. Tone of Voice in Practice
|
||||
|
||||
| Situation | Tone | Example phrase | Avoid |
|
||||
|---|---|---|---|
|
||||
| Complimenting content | Warm, genuine, specific | "This genuinely made our day 🙌" | Generic "Thank you!" |
|
||||
| Answering a product question | Helpful, clear, not jargony | "Great question — here's exactly how it works…" | "Per our FAQs…" |
|
||||
| Resolving a complaint | Empathetic, responsible, action-oriented | "Really sorry to hear this — let's sort it out." | "This is not our fault" |
|
||||
| Engaging with light content | Playful, natural, on-brand | [Match the energy of the post — don't be stiff] | Corporate speak |
|
||||
| Handling criticism | Measured, honest, not defensive | "We hear you and we're working on it." | "As per our T&Cs…" |
|
||||
| Addressing a crisis | Calm, clear, factual, empathetic | "We're aware of this and are treating it as an urgent priority." | Defensive or dismissive |
|
||||
|
||||
**Emoji use:** [Define brand's emoji policy — e.g. "Use emojis sparingly — 1 per response max, only on positive interactions. Never on complaints or sensitive topics."]
|
||||
|
||||
---
|
||||
|
||||
## 8. Community Health Metrics
|
||||
|
||||
Track these weekly:
|
||||
|
||||
| Metric | What it measures | Target | Current |
|
||||
|---|---|---|---|
|
||||
| Average response time | Speed of community management | [≤ X hours] | [X hours] |
|
||||
| Response rate | % of comments/DMs replied to | [≥ X%] | [X%] |
|
||||
| Comment sentiment ratio | Positive : Neutral : Negative split | [≥ X% positive] | [X%] |
|
||||
| Escalation rate | % of interactions escalated | [≤ X%] | [X%] |
|
||||
| DM resolution time | Time to resolve a DM complaint | [≤ X hours] | [X hours] |
|
||||
| Content reports / removals | Volume of content moderated | [Track trend] | [X/week] |
|
||||
|
||||
**Weekly CM review (15 min):**
|
||||
- Review last week's metrics vs target
|
||||
- Flag any recurring complaint themes (product signals for the team)
|
||||
- Identify any standout positive interactions worth amplifying
|
||||
- Note any escalations and how they were handled
|
||||
|
||||
---
|
||||
|
||||
## 9. Platform-Specific Notes
|
||||
|
||||
| Platform | Key nuance | Best practice |
|
||||
|---|---|---|
|
||||
| **Instagram** | Comments move fast on Reels; DMs high volume | Prioritise Reel comments; use saved replies for FAQ DMs |
|
||||
| **LinkedIn** | Professional audience; public replies visible to networks | Keep responses professional; avoid humour on complaints |
|
||||
| **X / Twitter** | Real-time; pile-ons escalate fast | Monitor with keyword alerts; act on Tier 2 triggers quickly |
|
||||
| **TikTok** | Comment culture is more casual; meme responses ok | Match platform tone but keep brand voice; don't try too hard |
|
||||
| **YouTube** | Older comments resurface regularly | Monitor new comments on older videos; set up notifications |
|
||||
| **Facebook** | Groups + page comments; older audience | More formal tone; monitor group dynamics separately |
|
||||
| **Discord** | Real-time community; requires moderators | Designate community moderators; publish community rules prominently |
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Response templates cover all common scenarios (positive, neutral, complaint, crisis)
|
||||
- [ ] SLAs are realistic for available team resource
|
||||
- [ ] Moderation rules clearly distinguish between delete, hide, and leave
|
||||
- [ ] Escalation tiers are specific — each tier has a named contact and timeframe
|
||||
- [ ] Tone of voice guidance is concrete enough to write from (examples included)
|
||||
- [ ] Community health metrics have targets, not just labels
|
||||
- [ ] Platform-specific nuances are covered for every active channel
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- "Build a community management playbook for [brand]"
|
||||
- "Create social media response guidelines for our team"
|
||||
- "What should our moderation policy be for [platform]?"
|
||||
- "Write community management templates and escalation procedures"
|
||||
- "How should we handle negative comments on social media?"
|
||||
@@ -0,0 +1,242 @@
|
||||
---
|
||||
name: influencer-brief
|
||||
description: "Create a structured brief for an influencer or creator partnership campaign. Use when asked to brief an influencer, plan a creator collaboration, set up a paid partnership, or define deliverables for a sponsored content campaign. Produces a complete campaign brief with objectives, deliverables, creative guidelines, approval process, and performance metrics."
|
||||
---
|
||||
|
||||
# Influencer Brief Skill
|
||||
|
||||
This skill produces a professional influencer campaign brief that a creator can receive and act on immediately. It covers campaign objectives, audience alignment, content deliverables, creative guidelines, messaging dos and don'ts, approval workflow, payment terms, and performance expectations. Output is ready to send to a creator, talent manager, or agency.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask the user for these if not provided:
|
||||
- **Brand / product name** — what is being promoted
|
||||
- **Campaign goal** — what you want the partnership to achieve (awareness / sales / sign-ups / content creation / event promotion)
|
||||
- **Influencer type / tier** — nano (1K–10K), micro (10K–100K), macro (100K–1M), mega/celebrity (1M+)
|
||||
- **Platform(s)** — Instagram, TikTok, YouTube, LinkedIn, X/Twitter, podcast
|
||||
- **Deliverables** — what content you need (e.g. 2 Instagram Reels, 1 Story, 1 TikTok video)
|
||||
- **Campaign dates** — start date, content deadlines, go-live window
|
||||
- **Budget range** — fee range, gifting, affiliate / commission structure
|
||||
- **Key messages** — what must the creator communicate?
|
||||
|
||||
## Output Structure
|
||||
|
||||
---
|
||||
|
||||
# Influencer Partnership Brief
|
||||
|
||||
**Campaign name:** [e.g. "Spring Launch — [Brand] x [Creator]"]
|
||||
**Brand:** [Brand name]
|
||||
**Campaign period:** [Start date → End date]
|
||||
**Brief date:** [Date]
|
||||
**Brand contact:** [Name, email, response time SLA]
|
||||
|
||||
---
|
||||
|
||||
## 1. Campaign Overview
|
||||
|
||||
**Why we're working with creators:**
|
||||
[2–3 sentences on the campaign context — product launch, seasonal push, brand awareness drive, community building. Explain why influencer marketing is the right channel for this goal.]
|
||||
|
||||
**Campaign goal:** [Single primary goal — e.g. "Drive 500 sign-ups to [product] from [creator]'s audience within 30 days of go-live"]
|
||||
|
||||
**Target audience:**
|
||||
- Who they are: [Age, gender, interests, platforms, mindset]
|
||||
- Why [creator]'s audience is the right fit: [Specific alignment — e.g. "Tech-curious professionals aged 25–40 who already use productivity tools"]
|
||||
|
||||
**Campaign type:**
|
||||
- [ ] Paid partnership (sponsored post / video)
|
||||
- [ ] Gifted / product collaboration
|
||||
- [ ] Affiliate / commission
|
||||
- [ ] Brand ambassador (ongoing)
|
||||
- [ ] Event / launch attendance
|
||||
- [ ] Co-created content
|
||||
|
||||
---
|
||||
|
||||
## 2. Creator Selection Rationale
|
||||
|
||||
*(Complete this section if the creator has already been selected)*
|
||||
|
||||
| Criteria | [Creator handle] | Why they're a fit |
|
||||
|---|---|---|
|
||||
| Follower count | [X] | [Context] |
|
||||
| Engagement rate | [X%] | [Above/at/below category average] |
|
||||
| Audience alignment | [Description] | [Overlap with target audience] |
|
||||
| Content style | [Description] | [Fit with brand tone] |
|
||||
| Past brand partnerships | [Yes/No] | [Relevant category experience] |
|
||||
| Exclusivity requirements | [Yes/No] | [Competitor conflicts?] |
|
||||
|
||||
---
|
||||
|
||||
## 3. Content Deliverables
|
||||
|
||||
Be specific. Ambiguity leads to reshoots and renegotiations.
|
||||
|
||||
| Deliverable | Platform | Format | Duration / specs | Deadline | Usage rights |
|
||||
|---|---|---|---|---|---|
|
||||
| [e.g. Primary hero video] | TikTok | Video | 30–60 sec, vertical 9:16 | [Date] | [Organic only / paid amplification / forever] |
|
||||
| [e.g. Story set] | Instagram | Story x3 | 15 sec each, link sticker | [Date] | [Organic only] |
|
||||
| [e.g. Reel] | Instagram | Reel | 15–30 sec, vertical | [Date] | [Paid amplification allowed for 30 days] |
|
||||
| [e.g. Long-form review] | YouTube | Video | 8–12 min, [product] featured from min 2 | [Date] | [Organic only] |
|
||||
|
||||
**Posting window:** Content must go live between [Date] and [Date]. Do not post during [blackout periods if any].
|
||||
|
||||
**Exclusivity:** Creator agrees not to post competing content for [X days] before and [X days] after campaign go-live.
|
||||
|
||||
---
|
||||
|
||||
## 4. Key Messages
|
||||
|
||||
**What the creator MUST communicate:**
|
||||
|
||||
✅ Must include:
|
||||
- [Message 1: e.g. "[Product name] is now available at [price / in [region]]"]
|
||||
- [Message 2: e.g. The specific problem [product] solves — [describe in plain language]]
|
||||
- [Message 3: e.g. The unique differentiator — [what makes it different from alternatives]]
|
||||
- [CTA: e.g. "Use code [CREATOR] for [X]% off" / "Link in bio to try free for 14 days"]
|
||||
|
||||
❌ Must NOT include:
|
||||
- [Restriction 1: e.g. Do not compare directly to [competitor name]]
|
||||
- [Restriction 2: e.g. Do not make unsubstantiated health or results claims]
|
||||
- [Restriction 3: e.g. Do not share pricing beyond the introductory offer]
|
||||
- [Restriction 4: e.g. Do not use the word "cheap" — use "accessible" or "great value"]
|
||||
|
||||
**Brand disclosure requirement:**
|
||||
All posts must include a paid partnership disclosure per [ASA / FTC / CAP Code] guidelines:
|
||||
- Instagram / TikTok: Use native "Paid Partnership" tag + "#ad" in caption
|
||||
- YouTube: Verbal disclosure in the first 30 seconds + description disclosure
|
||||
- "This video is sponsored by [Brand]" is acceptable
|
||||
|
||||
---
|
||||
|
||||
## 5. Creative Guidelines
|
||||
|
||||
**Tone of voice:**
|
||||
- [Your brand] sounds like: [e.g. "A knowledgeable friend — warm, direct, never corporate"]
|
||||
- [Your brand] does NOT sound like: [e.g. "A sales pitch, hype-driven, or try-hard"]
|
||||
- Creator's authentic voice is encouraged — the brief is a guide, not a script
|
||||
|
||||
**Visual guidelines:**
|
||||
- Brand colours (if shown): [Primary hex / description — e.g. "Navy #1A2B5C and white"]
|
||||
- Logo usage: [Not required in organic posts / required in pinned Stories / as overlay if using branded assets]
|
||||
- Product shot requirements: [e.g. Product must be clearly visible for minimum 5 seconds / in hands / in-use context only]
|
||||
- Setting: [e.g. Natural lifestyle setting preferred / office environment / no white studio backgrounds]
|
||||
- Avoid: [e.g. Clutter, competing products in frame, low lighting, filters that distort product colour]
|
||||
|
||||
**Script / storyline suggestions (creator's own words — these are starting points, not a script):**
|
||||
|
||||
Option A — Problem/Solution hook:
|
||||
> "I've been [doing thing that product solves] for years and it was always [pain point]. Then I found [product] and [specific outcome]. Here's how it works…"
|
||||
|
||||
Option B — Curiosity/Discovery hook:
|
||||
> "I got sent something I actually ended up using every day. [Product name]. And here's what surprised me about it…"
|
||||
|
||||
Option C — Social proof / endorsement:
|
||||
> "I know everyone says [category] tools are overhyped but [product] is genuinely different. The reason is [specific differentiator]…"
|
||||
|
||||
*The creator should use their own style and language — these are for inspiration only.*
|
||||
|
||||
---
|
||||
|
||||
## 6. Approval & Revision Process
|
||||
|
||||
**Pre-posting approval is required.** No content goes live without brand sign-off.
|
||||
|
||||
| Stage | Action required | Timeline | Contact |
|
||||
|---|---|---|---|
|
||||
| Script / treatment (if applicable) | Send for review | [X] days before shoot | [Brand contact name] |
|
||||
| Draft content (video / post) | Send for review | [X] working days before go-live | [Brand contact name] |
|
||||
| Brand feedback | Brands provide feedback | Within [X] working days | — |
|
||||
| Revisions | Creator amends (max [X] rounds) | Within [X] days of feedback | — |
|
||||
| Final approval | Brand sign-off | [X] days before go-live | — |
|
||||
|
||||
**Maximum revision rounds:** [X] rounds included in the fee. Additional rounds billed at [rate] or [approach].
|
||||
|
||||
**Feedback format:** [Brand] will provide written feedback via [email / shared doc]. Verbal feedback calls available on request.
|
||||
|
||||
---
|
||||
|
||||
## 7. Commercial Terms
|
||||
|
||||
| Term | Detail |
|
||||
|---|---|
|
||||
| Fee | [£/$/€ X] flat fee OR [rate per deliverable] |
|
||||
| Payment schedule | [50% on brief acceptance, 50% within 30 days of go-live] |
|
||||
| Affiliate / commission | [X% of sales via tracking link / code — paid monthly] |
|
||||
| Usage rights | [Organic social only / brand may amplify as paid ads / brand may repurpose in owned channels for X months] |
|
||||
| Exclusivity period | [X days pre-launch + X days post-launch — no direct competitor content] |
|
||||
| Gifted product | [List of products being gifted, approximate value] |
|
||||
| Contract | [Separate partnership agreement to follow / this brief serves as the agreement] |
|
||||
|
||||
---
|
||||
|
||||
## 8. Tracking & Measurement
|
||||
|
||||
How we'll measure success:
|
||||
|
||||
| KPI | Target | How measured |
|
||||
|---|---|---|
|
||||
| [Views / impressions] | [≥ X] | Platform analytics shared post-campaign |
|
||||
| [Engagement rate] | [≥ X%] | Platform analytics |
|
||||
| [Link clicks / swipe-ups] | [≥ X] | UTM link / affiliate link tracking |
|
||||
| [Conversions / sign-ups / sales] | [≥ X] | Promo code redemptions / UTM attribution |
|
||||
| [Reach / new audience] | [≥ X] | Platform analytics |
|
||||
|
||||
**Creator deliverables post-campaign:**
|
||||
- Provide screenshot or export of post analytics within [X] days of go-live
|
||||
- Share link to live content once posted
|
||||
- Notify brand contact immediately if post is removed or edited after approval
|
||||
|
||||
**Promo code / tracking link:**
|
||||
- Creator-specific code: [CODE] ([X]% off for creator's audience)
|
||||
- Tracking URL: [UTM link or affiliate URL]
|
||||
- Link placement: [Bio / pinned Story / video description]
|
||||
|
||||
---
|
||||
|
||||
## 9. Important Dates
|
||||
|
||||
| Milestone | Date |
|
||||
|---|---|
|
||||
| Brief sent to creator | [Date] |
|
||||
| Creator acceptance deadline | [Date] |
|
||||
| Contract signed | [Date] |
|
||||
| Product shipped / access provided | [Date] |
|
||||
| Draft content submitted to brand | [Date] |
|
||||
| Brand feedback returned | [Date] |
|
||||
| Final approval | [Date] |
|
||||
| Content go-live window | [Date → Date] |
|
||||
| Analytics report due from creator | [Date] |
|
||||
| Final payment | [Date] |
|
||||
|
||||
---
|
||||
|
||||
## 10. Useful Assets & Links
|
||||
|
||||
- Brand asset folder: [Link to Dropbox / Google Drive / Notion]
|
||||
- Product page / landing page: [URL]
|
||||
- Brand guidelines (if shared): [Link]
|
||||
- Previous campaign examples: [Links to past collab posts for style reference]
|
||||
- Brand contact: [Name, email, phone / WhatsApp for urgent queries]
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Deliverables are fully specified (platform, format, dimensions, duration, deadline)
|
||||
- [ ] Key messages include a specific, trackable CTA
|
||||
- [ ] Creative guidelines allow creative freedom while protecting brand
|
||||
- [ ] Approval process has clear timelines and named contacts
|
||||
- [ ] Commercial terms are complete — fee, payment schedule, usage rights, exclusivity
|
||||
- [ ] Tracking method is in place before campaign goes live
|
||||
- [ ] Disclosure requirements are clearly stated (FTC / ASA compliance)
|
||||
- [ ] Important dates include a buffer for revisions
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- "Write an influencer brief for our product launch"
|
||||
- "Create a creator partnership brief for [campaign]"
|
||||
- "Draft a brief for a TikTok influencer collab"
|
||||
- "Build a paid partnership brief for [brand]"
|
||||
- "What should I include in an influencer campaign brief?"
|
||||
@@ -0,0 +1,328 @@
|
||||
---
|
||||
name: social-ad-campaign
|
||||
description: "Plan and write a paid social advertising campaign. Use when asked to build a paid social campaign, create Meta/LinkedIn/TikTok/X ad copy, define a social ad strategy, or plan an advertising funnel across social platforms. Produces a complete campaign plan with audience targeting, ad set structure, copy for each ad format, budget allocation, and measurement framework."
|
||||
---
|
||||
|
||||
# Social Ad Campaign Skill
|
||||
|
||||
This skill produces a complete paid social advertising campaign plan covering campaign objective, audience targeting, funnel structure, ad set architecture, ad copy and creative briefs for each format, budget allocation, bidding strategy, and a measurement framework. Output is ready for a media buyer, performance marketer, or social team to execute.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask the user for these if not provided:
|
||||
- **Brand / product name**
|
||||
- **Campaign objective** — what are you trying to achieve? (traffic / leads / conversions / brand awareness / app installs / video views / event promotion)
|
||||
- **Platform(s)** — Meta (Facebook/Instagram), LinkedIn, TikTok, X/Twitter, Pinterest, Snapchat
|
||||
- **Target audience** — who are you trying to reach? (demographics, interests, job titles, behaviours, lookalikes)
|
||||
- **Budget** — total campaign budget and timeframe (e.g. £5,000 over 4 weeks)
|
||||
- **Offer / landing page** — what is the ad driving to? (free trial, product page, lead form, event sign-up)
|
||||
- **Key message** — the single most important thing the ad must communicate
|
||||
|
||||
## Output Structure
|
||||
|
||||
---
|
||||
|
||||
# Paid Social Campaign Plan: [Brand] — [Campaign Name]
|
||||
|
||||
**Campaign objective:** [e.g. Lead generation — 200 qualified leads in 30 days]
|
||||
**Platform(s):** [e.g. Meta (Instagram + Facebook), LinkedIn]
|
||||
**Budget:** [£/$/€ X total over X weeks]
|
||||
**Campaign period:** [Start date → End date]
|
||||
**Owner:** [Media buyer / performance marketer / agency]
|
||||
**Date:** [Date]
|
||||
|
||||
---
|
||||
|
||||
## 1. Campaign Strategy Overview
|
||||
|
||||
**Why paid social for this objective:**
|
||||
[2–3 sentences justifying the platform and format choice for this specific goal and audience. E.g. "LinkedIn is the right channel for this B2B SaaS campaign — we can target by job title, company size, and seniority, ensuring budget reaches decision-makers, not browsers."]
|
||||
|
||||
**Funnel structure:**
|
||||
|
||||
| Stage | Objective | Audience | Budget allocation |
|
||||
|---|---|---|---|
|
||||
| **Top of funnel (TOFU)** | Awareness / reach | Cold audience — interest/behaviour targeting | [X%] |
|
||||
| **Middle of funnel (MOFU)** | Consideration / engagement | Warm audience — video viewers, page engagers, website visitors | [X%] |
|
||||
| **Bottom of funnel (BOFU)** | Conversion / lead | Hot audience — retargeting, custom audiences, lookalikes | [X%] |
|
||||
|
||||
---
|
||||
|
||||
## 2. Audience Targeting
|
||||
|
||||
### Audience 1: [Cold — Primary Target]
|
||||
|
||||
**Platform:** [Meta / LinkedIn / TikTok]
|
||||
**Audience size target:** [e.g. 500K–2M — broad enough to learn, narrow enough to be relevant]
|
||||
|
||||
| Targeting dimension | Settings |
|
||||
|---|---|
|
||||
| Location | [Country / region / city] |
|
||||
| Age | [e.g. 28–45] |
|
||||
| Gender | [All / specify if relevant] |
|
||||
| Interests / behaviours | [e.g. SaaS tools, productivity apps, small business owners] |
|
||||
| Job titles (LinkedIn) | [e.g. Head of Marketing, Marketing Director, CMO] |
|
||||
| Company size (LinkedIn) | [e.g. 50–500 employees] |
|
||||
| Industry (LinkedIn) | [e.g. Technology, Financial Services, Healthcare] |
|
||||
| Exclude | [e.g. Existing customers — upload suppression list] |
|
||||
|
||||
### Audience 2: [Warm — Engagement Retargeting]
|
||||
|
||||
**Platform:** [Meta]
|
||||
**Source:** People who engaged with content / visited website in last 30 days
|
||||
|
||||
| Signal | Action |
|
||||
|---|---|
|
||||
| Watched 50%+ of a video ad | Retarget with a case study or testimonial ad |
|
||||
| Visited product page but didn't convert | Retarget with a direct offer / free trial CTA |
|
||||
| Engaged with Instagram / Facebook page | Retarget with social proof ad |
|
||||
|
||||
### Audience 3: [Hot — Conversion Retargeting]
|
||||
|
||||
**Platform:** [Meta / LinkedIn]
|
||||
**Source:** Website visitors (last 7 days), abandoned cart, form started but not completed
|
||||
|
||||
**Retargeting message:** More direct. Address the specific action they took. Time-sensitive CTA.
|
||||
|
||||
### Audience 4: [Lookalike]
|
||||
|
||||
**Source:** [Existing customers / email list / best-converting website visitors]
|
||||
**Lookalike similarity:** [1%–3% (tight match) / 3%–10% (broader reach)]
|
||||
**Platform:** Meta
|
||||
|
||||
---
|
||||
|
||||
## 3. Campaign Structure
|
||||
|
||||
### Meta Campaign Architecture
|
||||
|
||||
```
|
||||
Campaign: [Campaign Name] — [Objective: Lead Generation / Traffic / Conversions]
|
||||
│
|
||||
├── Ad Set 1: TOFU — Cold Interests
|
||||
│ ├── Ad 1A: [Video ad — hook format]
|
||||
│ ├── Ad 1B: [Static image — benefit-led headline]
|
||||
│ └── Ad 1C: [Carousel — feature/use case showcase]
|
||||
│
|
||||
├── Ad Set 2: MOFU — Warm Retargeting (30-day engagers)
|
||||
│ ├── Ad 2A: [Social proof / testimonial]
|
||||
│ └── Ad 2B: [Case study / before & after]
|
||||
│
|
||||
└── Ad Set 3: BOFU — Hot Retargeting (7-day website visitors)
|
||||
├── Ad 3A: [Direct offer — free trial / discount / demo]
|
||||
└── Ad 3B: [Objection handling — FAQ / reassurance]
|
||||
```
|
||||
|
||||
### LinkedIn Campaign Architecture
|
||||
|
||||
```
|
||||
Campaign Group: [Campaign Name]
|
||||
│
|
||||
├── Campaign 1: [Job Title Targeting — Awareness]
|
||||
│ ├── Single Image Ad: [Thought leadership hook]
|
||||
│ └── Video Ad: [Problem/solution story]
|
||||
│
|
||||
├── Campaign 2: [Company Size + Industry — Consideration]
|
||||
│ ├── Single Image Ad: [Case study / proof point]
|
||||
│ └── Lead Gen Form: [Gated asset / webinar / demo]
|
||||
│
|
||||
└── Campaign 3: [Retargeting — Conversion]
|
||||
└── Sponsored Message / Lead Gen Form: [Direct CTA with personalisation]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Ad Copy
|
||||
|
||||
### Format 1: Video Ad (15–30 seconds) — TOFU
|
||||
|
||||
**Hook (first 3 seconds — must stop the scroll):**
|
||||
> "[Pattern interrupt question or statement — e.g. 'Are you still doing [painful thing] manually?']"
|
||||
|
||||
**Core message (seconds 4–20):**
|
||||
> "[Agitate the problem → introduce the solution → show the specific outcome]"
|
||||
|
||||
**CTA (final 5 seconds):**
|
||||
> "[Clear, single action — e.g. 'Try free for 14 days — link in bio' / 'Get your demo today']"
|
||||
|
||||
**Visual direction:**
|
||||
- [e.g. Founder talking to camera in natural setting — authentic, not polished ad]
|
||||
- [e.g. Screen recording showing the product in use — show the outcome, not the feature]
|
||||
- [e.g. Customer testimonial — real person, real result, first-person story]
|
||||
|
||||
**Caption copy:**
|
||||
> [Headline — max 40 chars]
|
||||
> [Body copy — 1–3 sentences max]
|
||||
> [CTA button label: e.g. "Learn More" / "Sign Up" / "Get Started"]
|
||||
|
||||
---
|
||||
|
||||
### Format 2: Static Image Ad — TOFU/MOFU
|
||||
|
||||
**Ad variant A — Benefit-led headline:**
|
||||
|
||||
| Element | Copy |
|
||||
|---|---|
|
||||
| **Headline** | "[Single-sentence benefit statement — e.g. 'Cut reporting time by 80% with [Product]']" |
|
||||
| **Body copy** | "[Problem → solution in 2 sentences. Proof point if available.]" |
|
||||
| **CTA** | "Start free trial" / "Book a demo" / "Get 20% off" |
|
||||
| **Image** | [Product UI / result visual / human context shot — no stock photos of people in suits] |
|
||||
|
||||
**Ad variant B — Social proof headline:**
|
||||
|
||||
| Element | Copy |
|
||||
|---|---|
|
||||
| **Headline** | "['[Result] in [timeframe]' — real customer result, or '500+ teams use [Product] to...']" |
|
||||
| **Body copy** | "[Expand on the proof. 1–2 sentences. Add a second proof point if available.]" |
|
||||
| **CTA** | "See how it works" / "Try it free" |
|
||||
| **Image** | [Customer photo + quote overlay / logo wall / before/after data visual] |
|
||||
|
||||
**Ad variant C — Curiosity/question headline:**
|
||||
|
||||
| Element | Copy |
|
||||
|---|---|
|
||||
| **Headline** | "['[Common misconception or challenging question]' — e.g. 'What if [painful process] took 10 minutes, not 2 hours?']" |
|
||||
| **Body copy** | "[Answer the question → introduce product → specific outcome]" |
|
||||
| **CTA** | "Find out how" |
|
||||
|
||||
---
|
||||
|
||||
### Format 3: Carousel Ad — Features / Use Cases
|
||||
|
||||
**Headline (shown above carousel):** "[Problem-first statement or benefit hook]"
|
||||
|
||||
| Card # | Headline | Description | Image |
|
||||
|---|---|---|---|
|
||||
| Card 1 (hook) | "[Compelling hook — why this matters]" | "[1-sentence setup]" | [Eye-catching visual / stat] |
|
||||
| Card 2 | "[Use case / feature 1]" | "[Specific outcome this delivers]" | [Product UI or illustration] |
|
||||
| Card 3 | "[Use case / feature 2]" | "[Specific outcome this delivers]" | [Product UI or illustration] |
|
||||
| Card 4 | "[Use case / feature 3]" | "[Specific outcome this delivers]" | [Product UI or illustration] |
|
||||
| Card 5 (CTA card) | "[Strong CTA headline]" | "[Reinforce the offer / urgency]" | [CTA-focused visual / button] |
|
||||
|
||||
---
|
||||
|
||||
### Format 4: Lead Gen Form Ad (LinkedIn / Meta)
|
||||
|
||||
**Intro text (shown before form):**
|
||||
> "[1–2 sentences on what they'll get and why it's worth 60 seconds of their time]"
|
||||
|
||||
**Form headline:** "[Value-led headline — e.g. 'Get your free [asset] / Book your 20-min demo']"
|
||||
|
||||
**Form fields (keep to minimum — each extra field reduces conversion):**
|
||||
- First name
|
||||
- Work email
|
||||
- [One qualifying question — e.g. "Company size" / "Current tool used" / "Biggest challenge"]
|
||||
|
||||
**Privacy notice:** [Standard GDPR / CCPA compliance text — "By submitting, you agree to our Privacy Policy and may be contacted by [Brand] about relevant products and services."]
|
||||
|
||||
**Thank you message:**
|
||||
> "[What happens next — e.g. 'Thanks! You'll receive [asset] in your inbox within 5 minutes. Our team will be in touch within 1 business day.']"
|
||||
|
||||
---
|
||||
|
||||
### Format 5: Retargeting Ad — BOFU
|
||||
|
||||
**For website visitors (7 days) — direct offer:**
|
||||
> Headline: "[Specific nudge — e.g. 'Still thinking about [Product]? Here's 20% off to make the decision easier.']"
|
||||
> Body: "[Reinforce the primary benefit. Add urgency if genuine — e.g. 'Offer ends [date]'.]"
|
||||
> CTA: "Claim offer" / "Start free trial" / "Book demo"
|
||||
|
||||
**For video viewers (50%+) — social proof bridge:**
|
||||
> Headline: "[Continue the story — e.g. 'See what [50/100/500] teams achieved with [Product]']"
|
||||
> Body: "[Customer result quote or specific outcome. Bridge from awareness to consideration.]"
|
||||
> CTA: "Read the case study" / "See how it works"
|
||||
|
||||
---
|
||||
|
||||
## 5. Budget Allocation
|
||||
|
||||
**Total budget:** [£/$/€ X over X weeks]
|
||||
|
||||
| Ad Set | Stage | Budget | % of total | Expected CPM | Expected CPC | Expected conversions |
|
||||
|---|---|---|---|---|---|---|
|
||||
| Ad Set 1 — Cold interests | TOFU | [£X/week] | [X%] | [£X] | [£X] | [X leads / clicks] |
|
||||
| Ad Set 2 — Warm retargeting | MOFU | [£X/week] | [X%] | [£X] | [£X] | [X] |
|
||||
| Ad Set 3 — Hot retargeting | BOFU | [£X/week] | [X%] | [£X] | [£X] | [X] |
|
||||
| **Total** | — | [£X/week] | 100% | — | — | [X total] |
|
||||
|
||||
**Bidding strategy:**
|
||||
- TOFU: [Lowest cost / Maximum reach — optimise for video views or link clicks]
|
||||
- MOFU: [Lowest cost — optimise for landing page views or lead form opens]
|
||||
- BOFU: [Cost cap / Target cost — optimise for conversions or lead form submits]
|
||||
|
||||
**Budget reallocation rule:** After [7] days, pause ad sets with CPL > [£X]. Reallocate budget to best-performing ad sets. Review weekly.
|
||||
|
||||
---
|
||||
|
||||
## 6. Measurement Framework
|
||||
|
||||
**Primary KPI (tied to campaign objective):**
|
||||
|
||||
| KPI | Target | Why |
|
||||
|---|---|---|
|
||||
| [Cost per lead (CPL)] | [≤ £/$/€ X] | [Primary success metric — every pound spent measured against leads generated] |
|
||||
| [Conversion rate (ad → lead form)] | [≥ X%] | [Quality of targeting and ad relevance] |
|
||||
| [Total leads] | [≥ X in X weeks] | [Volume target] |
|
||||
|
||||
**Secondary metrics (optimisation signals):**
|
||||
|
||||
| Metric | Target | Action if off-target |
|
||||
|---|---|---|
|
||||
| CTR (click-through rate) | [≥ X%] | [Test new headlines / hook variations] |
|
||||
| CPM (cost per 1K impressions) | [≤ £/$/€ X] | [Broaden audience / test new placements] |
|
||||
| Video completion rate (if video) | [≥ X%] | [Test shorter video / stronger hook] |
|
||||
| Lead form completion rate | [≥ X%] | [Reduce form fields / test form intro copy] |
|
||||
| Lead-to-opportunity rate (post-campaign) | [≥ X%] | [Review lead quality — tighten audience targeting] |
|
||||
|
||||
**Reporting cadence:**
|
||||
- Daily: Check spend, CTR, and CPL — pause clearly underperforming ads
|
||||
- Weekly: Full performance review + budget reallocation decision
|
||||
- Campaign end: Final report with learnings for next campaign
|
||||
|
||||
**Attribution model:** [Last-click / 7-day click + 1-day view / data-driven (if volume sufficient)]
|
||||
|
||||
**Tracking setup checklist:**
|
||||
- [ ] Pixel / conversion API installed and verified on landing page
|
||||
- [ ] Conversion event firing correctly (lead form submit / purchase / sign-up)
|
||||
- [ ] UTM parameters set on all ad destination URLs
|
||||
- [ ] Lead form CRM integration tested
|
||||
- [ ] Lookalike audiences seeded from customer list upload
|
||||
|
||||
---
|
||||
|
||||
## 7. A/B Testing Plan
|
||||
|
||||
Run structured tests — change one variable at a time:
|
||||
|
||||
| Test # | Variable | Control | Variant | Success metric | Min budget to run |
|
||||
|---|---|---|---|---|---|
|
||||
| 1 | Hook / headline | [Current headline] | [Challenger headline] | CTR | [£X / 500 impressions] |
|
||||
| 2 | Creative format | Static image | Video | CPL | [£X / 1,000 impressions] |
|
||||
| 3 | CTA | "Learn More" | "Start free trial" | Conversion rate | [£X / 200 clicks] |
|
||||
| 4 | Audience | Interest-based | Lookalike 1% | CPL | [Equal budget split] |
|
||||
|
||||
**Testing rules:**
|
||||
- Run each test for minimum [7] days or [1,000 impressions] — whichever comes first
|
||||
- Change one variable at a time — never two in the same test
|
||||
- Document results and apply winning variant to all future campaigns
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Campaign objective is single and measurable — not "awareness and leads"
|
||||
- [ ] Full-funnel structure: TOFU, MOFU, and BOFU ad sets are separate
|
||||
- [ ] Each ad has a specific hook, benefit, and CTA — not generic copy
|
||||
- [ ] Ad copy has been tested against the "1-second scroll stop" rule — does the hook compel a pause?
|
||||
- [ ] Budget allocation reflects funnel logic — BOFU gets proportionally more per lead
|
||||
- [ ] Tracking setup checklist completed before campaign goes live
|
||||
- [ ] A/B test plan is in place — one variable per test, minimum budget defined
|
||||
- [ ] Retargeting suppression is set — existing customers excluded from acquisition campaigns
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- "Plan a paid social campaign for [product launch]"
|
||||
- "Build Meta ad copy for our lead generation campaign"
|
||||
- "Create a LinkedIn ad campaign for [B2B SaaS product]"
|
||||
- "Write TikTok ad copy for [consumer brand]"
|
||||
- "Structure a paid social funnel for [offer]"
|
||||
@@ -0,0 +1,227 @@
|
||||
---
|
||||
name: social-media-audit
|
||||
description: "Audit an existing social media presence across all active platforms. Use when asked to review social media performance, analyse a brand's social presence, benchmark against competitors, or identify what's working and what isn't. Produces a scored audit with platform-by-platform analysis, content performance review, competitive benchmarking, and a prioritised action plan."
|
||||
---
|
||||
|
||||
# Social Media Audit Skill
|
||||
|
||||
This skill produces a comprehensive social media audit covering profile completeness, content performance, audience engagement, posting consistency, competitive position, and a prioritised improvement plan. Output is ready for a social media manager, marketing lead, or agency to act on immediately.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask the user for these if not provided:
|
||||
- **Brand / handle name** — which account(s) to audit
|
||||
- **Active platforms** — which social channels to include (LinkedIn, Instagram, X/Twitter, TikTok, YouTube, Facebook, etc.)
|
||||
- **Audit timeframe** — what period to review (e.g. last 90 days, last 6 months)
|
||||
- **Business goal** — what social media should be achieving (brand awareness / lead gen / community / sales)
|
||||
- **Competitor handles** — 2–3 competitors or benchmark accounts for comparison
|
||||
- **Available metrics** — follower count, average engagement rate, post frequency, reach, impressions (if the user has them)
|
||||
|
||||
## Output Structure
|
||||
|
||||
---
|
||||
|
||||
# Social Media Audit: [Brand Name]
|
||||
|
||||
**Audit period:** [e.g. Feb–Apr 2026]
|
||||
**Platforms audited:** [List]
|
||||
**Audited by:** [Name / role]
|
||||
**Date:** [Date]
|
||||
**Overall health score:** [X / 100]
|
||||
|
||||
---
|
||||
|
||||
## 1. Audit Summary — Health Score
|
||||
|
||||
Score each dimension out of 10. Weighted total = overall health score out of 100.
|
||||
|
||||
| Dimension | Weight | Score (/10) | Weighted Score | Assessment |
|
||||
|---|---|---|---|---|
|
||||
| Profile completeness & branding | 10% | [X] | [X] | [1-sentence note] |
|
||||
| Content quality & consistency | 25% | [X] | [X] | [1-sentence note] |
|
||||
| Audience engagement | 20% | [X] | [X] | [1-sentence note] |
|
||||
| Follower growth | 15% | [X] | [X] | [1-sentence note] |
|
||||
| Platform strategy fit | 15% | [X] | [X] | [1-sentence note] |
|
||||
| Competitive position | 15% | [X] | [X] | [1-sentence note] |
|
||||
| **Total** | 100% | — | **[X/100]** | [Overall verdict] |
|
||||
|
||||
**Overall verdict:** 🟢 Strong (80–100) / 🟡 Developing (60–79) / 🔴 Needs work (<60)
|
||||
|
||||
---
|
||||
|
||||
## 2. Platform-by-Platform Analysis
|
||||
|
||||
Repeat this section for each active platform:
|
||||
|
||||
### [Platform Name] — Score: [X/10]
|
||||
|
||||
**Profile health:**
|
||||
- Bio / description: [Clear and keyword-rich / generic / missing]
|
||||
- Profile photo / banner: [Professional / outdated / mismatched]
|
||||
- Link in bio / CTA: [Present and current / missing]
|
||||
- Pinned content: [Exists and strategic / outdated / none]
|
||||
- Contact info / location: [Complete / incomplete]
|
||||
|
||||
**Audience:**
|
||||
- Followers: [X]
|
||||
- Follower growth (audit period): [+X% / -X% / flat]
|
||||
- Follower quality: [Relevant audience / mixed / unclear]
|
||||
|
||||
**Content performance:**
|
||||
|
||||
| Metric | Your account | Benchmark / competitor | Gap |
|
||||
|---|---|---|---|
|
||||
| Posts per week | [X] | [X] | [+/- X] |
|
||||
| Average engagement rate | [X%] | [X%] | [+/- X%] |
|
||||
| Average reach per post | [X] | [X] | [+/- X] |
|
||||
| Top format by engagement | [e.g. carousel] | [e.g. video] | [Match / mismatch] |
|
||||
|
||||
**Content audit — what you posted:**
|
||||
|
||||
| Content type | % of posts | Avg engagement | Verdict |
|
||||
|---|---|---|---|
|
||||
| Educational / how-to | [X%] | [X%] | [Keep / scale / drop] |
|
||||
| Product / promotional | [X%] | [X%] | [Keep / scale / drop] |
|
||||
| Behind-the-scenes | [X%] | [X%] | [Keep / scale / drop] |
|
||||
| Social proof / testimonials | [X%] | [X%] | [Keep / scale / drop] |
|
||||
| Engagement bait / conversation starters | [X%] | [X%] | [Keep / scale / drop] |
|
||||
|
||||
**Top 3 performing posts:**
|
||||
1. [Post description + why it worked]
|
||||
2. [Post description + why it worked]
|
||||
3. [Post description + why it worked]
|
||||
|
||||
**Bottom 3 performing posts:**
|
||||
1. [Post description + why it underperformed]
|
||||
2. [Post description + why it underperformed]
|
||||
3. [Post description + why it underperformed]
|
||||
|
||||
**Posting patterns:**
|
||||
- Best performing days: [e.g. Tue, Thu]
|
||||
- Best performing times: [e.g. 08:00–10:00]
|
||||
- Actual posting pattern: [e.g. sporadic / daily / consistent]
|
||||
- Consistency score: [Consistent / irregular / sporadic]
|
||||
|
||||
**Platform verdict:** [2–3 sentences on what's working, what isn't, and the #1 change to make]
|
||||
|
||||
---
|
||||
|
||||
## 3. Competitive Benchmarking
|
||||
|
||||
Compare against 2–3 competitors or aspirational accounts:
|
||||
|
||||
| Metric | [Your brand] | [Competitor 1] | [Competitor 2] | [Competitor 3] |
|
||||
|---|---|---|---|---|
|
||||
| LinkedIn followers | | | | |
|
||||
| LinkedIn eng. rate | | | | |
|
||||
| Instagram followers | | | | |
|
||||
| Instagram eng. rate | | | | |
|
||||
| Post frequency (all platforms) | | | | |
|
||||
| Content formats used | | | | |
|
||||
| Top content theme | | | | |
|
||||
|
||||
**Competitive gaps:**
|
||||
- **Where you're ahead:** [Specific metrics or tactics where you outperform]
|
||||
- **Where you're behind:** [Specific gaps — follower count, engagement, content variety]
|
||||
- **Opportunities they're missing:** [Whitespace you could own]
|
||||
|
||||
**What competitors are doing well that you should steal (ethically):**
|
||||
1. [Tactic / format / approach]
|
||||
2. [Tactic / format / approach]
|
||||
3. [Tactic / format / approach]
|
||||
|
||||
---
|
||||
|
||||
## 4. Content Strategy Assessment
|
||||
|
||||
**Are you posting the right mix?**
|
||||
|
||||
| Principle | Met? | Evidence | Recommendation |
|
||||
|---|---|---|---|
|
||||
| 80/20 rule: audience value vs self-promotion | [Yes/No] | [X% promotional posts] | [...] |
|
||||
| Consistent content pillars | [Yes/No] | [Pillars identified or not] | [...] |
|
||||
| Format variety (not just text posts) | [Yes/No] | [Format breakdown] | [...] |
|
||||
| Regular engagement with audience | [Yes/No] | [Reply rate, comment engagement] | [...] |
|
||||
| SEO / discoverability in profiles and posts | [Yes/No] | [Keywords, hashtags used] | [...] |
|
||||
|
||||
**Content gaps identified:**
|
||||
- [Gap 1: e.g. No video content despite video outperforming text on Instagram]
|
||||
- [Gap 2: e.g. No customer stories or social proof]
|
||||
- [Gap 3: e.g. Hashtag strategy missing — no discoverability beyond existing followers]
|
||||
|
||||
---
|
||||
|
||||
## 5. Audience Insights
|
||||
|
||||
**Follower quality assessment:**
|
||||
- Do followers match the target audience? [Yes / Partially / No]
|
||||
- Signs of inorganic growth? [e.g. high follower count, very low engagement = possible bought followers]
|
||||
- Most engaged audience segments: [e.g. industry, role, geography if visible from analytics]
|
||||
|
||||
**Engagement quality:**
|
||||
- Comment sentiment: [Positive / Mixed / Negative / Sparse]
|
||||
- Are comments substantive or just emoji reactions? [Substantive / Surface-level]
|
||||
- Are you responding to comments? [Always / Sometimes / Rarely / Never]
|
||||
- DMs / direct inquiries from social: [High / Low / None tracked]
|
||||
|
||||
---
|
||||
|
||||
## 6. Prioritised Action Plan
|
||||
|
||||
Ranked by impact × effort:
|
||||
|
||||
### 🔴 Do immediately (this week)
|
||||
|
||||
| Action | Platform | Why | Expected impact |
|
||||
|---|---|---|---|
|
||||
| [e.g. Update LinkedIn bio with clear value prop and keywords] | LinkedIn | Profile discovery | Higher profile views |
|
||||
| [e.g. Pin best-performing post to top of profile] | Instagram | First impression | Higher follow rate |
|
||||
| [e.g. Add link in bio with UTM tracking] | All | Traffic attribution | Measurable ROI |
|
||||
|
||||
### 🟡 Do this month
|
||||
|
||||
| Action | Platform | Why | Expected impact |
|
||||
|---|---|---|---|
|
||||
| [e.g. Launch a weekly educational carousel series] | LinkedIn | Fills content gap, high engagement format | +X% engagement rate |
|
||||
| [e.g. Start responding to all comments within 24h] | All | Signals algorithm engagement | Improved reach |
|
||||
| [e.g. Test video format 2x per week] | Instagram / TikTok | Underutilised high-reach format | Follower growth |
|
||||
|
||||
### 🟢 Do this quarter
|
||||
|
||||
| Action | Platform | Why | Expected impact |
|
||||
|---|---|---|---|
|
||||
| [e.g. Define 3–5 content pillars and build a monthly calendar] | All | Strategic consistency | Compound growth |
|
||||
| [e.g. Run a hashtag audit — identify 15–20 relevant tags per platform] | Instagram / LinkedIn | Discoverability | Organic reach |
|
||||
| [e.g. Source 3 customer stories for social proof content] | All | Social proof pillar | Trust + conversion |
|
||||
|
||||
---
|
||||
|
||||
## 7. 30-Day Quick Win Plan
|
||||
|
||||
The fastest way to improve the score by 10+ points:
|
||||
|
||||
| Week | Priority action | Platform | Owner | Success metric |
|
||||
|---|---|---|---|---|
|
||||
| 1 | [e.g. Fix all profile gaps — bio, photo, CTA, pinned post] | All | [Name] | 100% profile completeness |
|
||||
| 2 | [e.g. Post 3x educational carousel / video this week] | LinkedIn / IG | [Name] | ≥X% engagement rate |
|
||||
| 3 | [e.g. Engage actively — comment on 10 accounts per day] | LinkedIn / IG | [Name] | +X new followers |
|
||||
| 4 | [e.g. Review analytics and double down on best format] | All | [Name] | Identify top performing format |
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Every platform scored against objective criteria, not guesswork
|
||||
- [ ] Competitive benchmarks use real data, not assumptions
|
||||
- [ ] Content audit covers actual post types posted, not idealised mix
|
||||
- [ ] Recommendations are specific and actionable — not "post more content"
|
||||
- [ ] Action plan is sequenced by impact × effort, not just effort
|
||||
- [ ] 30-day plan has named owners and measurable success metrics
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- "Audit our social media presence"
|
||||
- "Review our Instagram and LinkedIn performance"
|
||||
- "How are we doing on social compared to competitors?"
|
||||
- "What's working and what isn't on our social channels?"
|
||||
- "Give me a social media health check for [brand]"
|
||||
@@ -0,0 +1,397 @@
|
||||
---
|
||||
name: viral-content-framework
|
||||
description: "Build a framework for creating shareable, high-reach social media content. Use when asked to plan viral content, develop a shareable content strategy, create a hook writing system, or build a repeatable process for content that gets shared. Produces a platform-specific viral content framework with hook formulas, content structures, shareability triggers, and a content testing system."
|
||||
---
|
||||
|
||||
# Viral Content Framework Skill
|
||||
|
||||
This skill produces a platform-specific framework for creating content that earns shares, saves, comments, and organic reach beyond your existing following. It covers the psychology of sharing, hook formulas, content structures that consistently perform, platform-specific formats, and a repeatable system for producing high-reach content. Output gives a content creator, social media manager, or marketer a structured process they can apply immediately.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask the user for these if not provided:
|
||||
- **Brand / creator name**
|
||||
- **Primary platform(s)** — where are you trying to build reach? (LinkedIn, TikTok, Instagram, X/Twitter, YouTube)
|
||||
- **Content niche / topic area** — what is the content about?
|
||||
- **Target audience** — who are you trying to reach and what do they care about?
|
||||
- **Content goal** — what should high-reach content achieve? (followers / brand awareness / inbound leads / community / sales)
|
||||
- **Current performance baseline** — roughly how many impressions / shares / saves does a typical post get today?
|
||||
|
||||
## Output Structure
|
||||
|
||||
---
|
||||
|
||||
# Viral Content Framework: [Brand / Creator Name]
|
||||
|
||||
**Platform(s):** [List]
|
||||
**Niche:** [Content topic area]
|
||||
**Audience:** [Target audience description]
|
||||
**Goal:** [What high-reach content should achieve]
|
||||
**Date:** [Date]
|
||||
|
||||
---
|
||||
|
||||
## 1. The Psychology of Sharing
|
||||
|
||||
Before tactics, understand why people share. Content goes viral when it triggers one or more of these sharing motivations:
|
||||
|
||||
| Motivation | What it means | How to trigger it |
|
||||
|---|---|---|
|
||||
| **Identity** | "Sharing this says something good about me" | Make the audience look smart, informed, or principled by sharing |
|
||||
| **Utility** | "This is so useful I'd be doing my friends a disservice not to share it" | Teach something actionable that produces an immediate result |
|
||||
| **Emotion** | "This made me feel something — I want others to feel it too" | Surprise, delight, inspiration, righteous anger, nostalgia |
|
||||
| **Tribe** | "My people need to see this" | Create content that speaks specifically to a tight community |
|
||||
| **Status** | "Being first to share this makes me look ahead of the curve" | Break news, contrarian takes, insider information |
|
||||
| **Validation** | "This is exactly what I've been thinking but couldn't articulate" | Voice what the audience already believes — be their spokesperson |
|
||||
|
||||
**For [brand/creator], the primary sharing motivation is:** [Choose 1–2 that fit the niche and audience]
|
||||
|
||||
---
|
||||
|
||||
## 2. The Virality Formula
|
||||
|
||||
High-reach content = **Strong hook × Valuable substance × Easy shareability**
|
||||
|
||||
All three must be present. Strong hooks that lead to thin content get clicks but not shares. Brilliant content with a weak hook never gets seen. Content that's hard to share (too long, too branded, too complex) dies at the save stage.
|
||||
|
||||
### Diagnosing your current content:
|
||||
|
||||
| Element | Strong | Weak | Fix |
|
||||
|---|---|---|---|
|
||||
| Hook (first line / first frame) | Stops scrolling immediately | Generic opening | Use hook formulas in Section 3 |
|
||||
| Substance | Actionable, specific, surprising | Vague, obvious, or filler | Apply content structures in Section 4 |
|
||||
| Shareability | Short enough to screenshot, save, or re-share | Too long, too branded, too complex | Trim to the essential value |
|
||||
|
||||
---
|
||||
|
||||
## 3. Hook Formulas That Work
|
||||
|
||||
The hook is everything. You have 1–3 seconds on TikTok/Instagram, 1 sentence on LinkedIn/X. Use these proven formulas:
|
||||
|
||||
### Formula 1: The Contrarian Statement
|
||||
*"[Widely believed thing] is wrong / a myth / overrated."*
|
||||
> Examples:
|
||||
> - "Posting every day on LinkedIn is killing your reach."
|
||||
> - "Consistency isn't the reason great creators grow. This is."
|
||||
> - "The best social media strategy doesn't start with content."
|
||||
|
||||
**Why it works:** Challenges existing beliefs → triggers curiosity + mild outrage = comments + shares
|
||||
|
||||
---
|
||||
|
||||
### Formula 2: The Specific Number / Result
|
||||
*"I [achieved specific result] in [specific timeframe]. Here's how."*
|
||||
> Examples:
|
||||
> - "I went from 0 to 10,000 LinkedIn followers in 6 months. Here's the exact system."
|
||||
> - "Our last post got 2.3M views. These are the 4 decisions that made it happen."
|
||||
> - "I reduced our content production time by 70% using this workflow."
|
||||
|
||||
**Why it works:** Specific numbers are credible. Credibility earns attention. "How" frames create utility.
|
||||
|
||||
---
|
||||
|
||||
### Formula 3: The Uncomfortable Truth
|
||||
*"Nobody wants to hear this, but [uncomfortable truth about your niche]."*
|
||||
> Examples:
|
||||
> - "Nobody wants to hear this, but most social media 'strategies' are just posting without a plan."
|
||||
> - "Your content isn't underperforming because of the algorithm. It's because of the hook."
|
||||
> - "If your product needs a social media strategy to sell, you may have a product problem."
|
||||
|
||||
**Why it works:** "Nobody wants to hear this" primes people to read it. Uncomfortable truths polarise → comments
|
||||
|
||||
---
|
||||
|
||||
### Formula 4: The Listicle Tease
|
||||
*"[X] things I wish someone had told me about [topic]."*
|
||||
> Examples:
|
||||
> - "5 things every social media manager knows that nobody talks about publicly."
|
||||
> - "8 LinkedIn hacks that took me 3 years to discover."
|
||||
> - "The 3 types of hooks that consistently outperform everything else."
|
||||
|
||||
**Why it works:** Implied exclusivity + easy to save and return to
|
||||
|
||||
---
|
||||
|
||||
### Formula 5: The Story Hook
|
||||
*"[Specific moment / scene / event that sets up a tension]."*
|
||||
> Examples:
|
||||
> - "At 11pm on a Sunday, our post started going viral. By Monday morning it had 500k views. Here's what we did wrong."
|
||||
> - "Six months ago I had 200 followers. I changed one thing. Now I have 40,000."
|
||||
> - "A customer tweeted something about us last week. I nearly deleted it. I didn't. Here's what happened."
|
||||
|
||||
**Why it works:** Stories create forward momentum — people read to find out what happens
|
||||
|
||||
---
|
||||
|
||||
### Formula 6: The Pattern Interrupt Question
|
||||
*"[Question that the audience has never been asked about a familiar topic]."*
|
||||
> Examples:
|
||||
> - "What's the real reason some posts go viral on command and others die quietly?"
|
||||
> - "If you had to teach someone to create shareable content in 10 minutes, what would you actually say?"
|
||||
> - "What would happen if you stopped posting for 30 days?"
|
||||
|
||||
**Why it works:** Unusual question about a familiar topic creates a "never thought about that" response
|
||||
|
||||
---
|
||||
|
||||
## 4. Content Structures That Perform
|
||||
|
||||
### Structure 1: The "Thread / Listicle" (LinkedIn, X/Twitter)
|
||||
|
||||
Best for: Education, frameworks, how-to content
|
||||
|
||||
```
|
||||
Hook: [Formula 1–6 above]
|
||||
↓
|
||||
Promise: "Here's what I'm going to share and why it matters to you."
|
||||
↓
|
||||
Point 1: [Specific, actionable, with an example]
|
||||
Point 2: [Specific, actionable, with an example]
|
||||
Point 3: [Specific, actionable, with an example]
|
||||
[...up to 7–10 points — stop when you run out of substance, not ideas]
|
||||
↓
|
||||
Summary: "The one thing to remember from all of this is: [distill to a single insight]"
|
||||
↓
|
||||
CTA: [Follow for more / save this / what would you add?]
|
||||
```
|
||||
|
||||
**Shareability trigger:** Utility — save to come back to. Comment-baiting summary.
|
||||
|
||||
---
|
||||
|
||||
### Structure 2: The "Before → After → Bridge" (All platforms)
|
||||
|
||||
Best for: Product/service showcases, transformations, case studies
|
||||
|
||||
```
|
||||
Hook: [The after — start with the impressive result]
|
||||
↓
|
||||
Before: "Here's what the situation looked like before: [specific, relatable pain]"
|
||||
↓
|
||||
After: "Here's what it looks like now: [specific, impressive outcome with numbers]"
|
||||
↓
|
||||
Bridge: "Here's exactly what changed between those two states: [the process / insight / tool]"
|
||||
↓
|
||||
CTA: [Try it / learn more / what's your 'before'?]
|
||||
```
|
||||
|
||||
**Shareability trigger:** Identity + utility — audience wants to share a transformation they aspire to
|
||||
|
||||
---
|
||||
|
||||
### Structure 3: The "Contrarian Deep Dive" (LinkedIn, X/Twitter, YouTube)
|
||||
|
||||
Best for: Building authority, thought leadership, engagement
|
||||
|
||||
```
|
||||
Hook: [Contrarian statement — Formula 1]
|
||||
↓
|
||||
Acknowledge the conventional wisdom: "Most people believe [X] because [reason]."
|
||||
↓
|
||||
Provide evidence against it: "But here's the data / experience / example that challenges it."
|
||||
↓
|
||||
Make the case: "What actually works is [Y], and here's why."
|
||||
↓
|
||||
Nuance (important): "To be fair, [X] works when [specific conditions]. But for [audience], [Y] is better."
|
||||
↓
|
||||
CTA: "Disagree? Tell me why ↓"
|
||||
```
|
||||
|
||||
**Shareability trigger:** Status + validation + tribe (people share things that represent their worldview)
|
||||
|
||||
---
|
||||
|
||||
### Structure 4: The "Story Arc" (TikTok, Instagram Reels, YouTube Shorts)
|
||||
|
||||
Best for: Video content, personal brand building
|
||||
|
||||
```
|
||||
Frame 1 (0–3 sec): Hook — [The punchline, result, or conflict stated upfront]
|
||||
Frame 2 (3–15 sec): Setup — [Who you are + what happened / the situation]
|
||||
Frame 3 (15–40 sec): Complication — [What went wrong / what the challenge was]
|
||||
Frame 4 (40–55 sec): Resolution — [What you did / what happened]
|
||||
Frame 5 (final 5 sec): CTA — [Follow for more / share if this happened to you / comment your take]
|
||||
```
|
||||
|
||||
**Shareability trigger:** Emotion — people share stories that resonate with an experience they've had
|
||||
|
||||
---
|
||||
|
||||
### Structure 5: The "Carousel / Slide Deck" (Instagram, LinkedIn)
|
||||
|
||||
Best for: How-to content, frameworks, comparisons, statistics
|
||||
|
||||
```
|
||||
Slide 1 (Cover): [Hook — compelling headline. Must earn the swipe.]
|
||||
Slide 2: [Context — why this matters. Set up the value.]
|
||||
Slides 3–7: [One insight per slide. Max 30 words + clear visual/diagram per slide.]
|
||||
Slide 8 (Summary): [The key takeaway distilled to one sentence.]
|
||||
Slide 9 (CTA): [Save this / follow / share / link in bio]
|
||||
```
|
||||
|
||||
**Shareability trigger:** Save rate. Carousels are the most-saved format on Instagram. Algorithm rewards saves.
|
||||
|
||||
---
|
||||
|
||||
## 5. Platform-Specific Playbook
|
||||
|
||||
### LinkedIn
|
||||
|
||||
**What goes viral on LinkedIn:**
|
||||
- Career advice that feels personally earned, not theoretical
|
||||
- Data + unexpected insight ("We analysed 100 LinkedIn posts and found...")
|
||||
- Contrarian takes on work, careers, or the professional world
|
||||
- Vulnerable, human moments (layoffs, failures, what you learned)
|
||||
- Tactical how-to posts with numbered lists
|
||||
|
||||
**Format priority:** Long-form text posts → carousels → video (in order of average reach)
|
||||
|
||||
**Algorithm signals that boost reach:** Comments > saves > reactions. Ask a question in the CTA.
|
||||
|
||||
**Posting time:** Tuesday–Thursday, 07:30–09:00 or 12:00–13:00 in your audience's timezone
|
||||
|
||||
**What kills LinkedIn reach:** Outbound links in the post body (add links in first comment instead), posting too frequently (3–5x/week max), vanity metrics in the hook
|
||||
|
||||
---
|
||||
|
||||
### TikTok
|
||||
|
||||
**What goes viral on TikTok:**
|
||||
- First 1–2 seconds must hook visually AND verbally
|
||||
- Relatability over polish — authentic > produced
|
||||
- Trending sounds / formats used with original content
|
||||
- "I can't believe they said that" or "I need to show this to [my person]" reaction content
|
||||
- Educational content that delivers value in under 60 seconds
|
||||
|
||||
**Format priority:** Trending sound duets/stitches → original POV → talking-head education
|
||||
|
||||
**Algorithm signals that boost reach:** Watch-through rate (% who watch the full video) is the #1 signal. Replays, shares, and comments follow.
|
||||
|
||||
**Hook principle:** Start mid-sentence. Start in the action. Never open with "Hey guys, today I'm going to..."
|
||||
|
||||
---
|
||||
|
||||
### Instagram
|
||||
|
||||
**What goes viral on Instagram:**
|
||||
- Carousels with a save-worthy framework or checklist (saves are the top signal)
|
||||
- Reels with a hook in the first frame (text overlay + visual hook simultaneously)
|
||||
- Before/after transformations (personal, product, design)
|
||||
- Content that makes people think "I need to send this to [specific person]"
|
||||
- Aesthetic content that people want on their feed
|
||||
|
||||
**Format priority:** Reels → carousels → static images (in order of current algorithm weighting)
|
||||
|
||||
**Algorithm signals that boost reach:** Saves > shares > comments > likes. Design for saves.
|
||||
|
||||
**Caption strategy:** Hook in the first line (shows before "more" truncation). Value in the body. CTA at the end.
|
||||
|
||||
---
|
||||
|
||||
### X / Twitter
|
||||
|
||||
**What goes viral on X:**
|
||||
- Strong opinion stated concisely (≤280 characters, no thread needed)
|
||||
- Data or insight that surprises the tech/media/culture audience
|
||||
- "This is the [most/best/funniest] [X] I've ever seen" amplification
|
||||
- Dunks on widely-held beliefs (with evidence)
|
||||
- Breaking news commentary that's faster than media
|
||||
|
||||
**Format priority:** Short opinion takes → threads → quote tweets with commentary
|
||||
|
||||
**Algorithm signals that boost reach:** Replies > retweets > likes. Controversy (civil) drives replies.
|
||||
|
||||
**Thread principle:** First tweet must work as a standalone — many people won't click "see more"
|
||||
|
||||
---
|
||||
|
||||
### YouTube (Shorts + Long-form)
|
||||
|
||||
**What goes viral — Shorts:**
|
||||
- Same TikTok principles apply
|
||||
- "Wait for it" content — builds to a payoff
|
||||
- Tutorial that delivers a result in under 60 seconds
|
||||
|
||||
**What goes viral — Long-form:**
|
||||
- High-retention opening: state the payoff in the first 30 seconds
|
||||
- Chapter markers for navigation (increases watch time)
|
||||
- Strong thumbnail + title pairing — the algorithm tests these against click-through rate
|
||||
|
||||
---
|
||||
|
||||
## 6. The Content Testing System
|
||||
|
||||
Virality is repeatable if you treat content creation as an experiment.
|
||||
|
||||
### Step 1: Create content batches
|
||||
|
||||
Produce 5–10 pieces per content type. Use a consistent structure with one variable changed per batch (hook type, format, topic angle).
|
||||
|
||||
### Step 2: Post and measure — the 48-hour signal
|
||||
|
||||
| Platform | 48-hour signal to watch | What it tells you |
|
||||
|---|---|---|
|
||||
| LinkedIn | Comments + saves in first 2 hours | Relevance to professional audience |
|
||||
| TikTok | Watch-through rate in first 24 hours | Hook and content quality |
|
||||
| Instagram | Saves rate per impression | "Worth returning to" value |
|
||||
| X/Twitter | Replies in first 4 hours | Resonance with the community |
|
||||
|
||||
### Step 3: Identify your "content codes"
|
||||
|
||||
After 30 days, review your top 5 performing posts and answer:
|
||||
- What format were they?
|
||||
- What hook formula?
|
||||
- What topic angle?
|
||||
- What content structure?
|
||||
- What time were they posted?
|
||||
|
||||
Your "content code" = the combination of these variables that consistently outperforms. Double down.
|
||||
|
||||
### Step 4: Scale what works
|
||||
|
||||
| Phase | Action |
|
||||
|---|---|
|
||||
| Week 1–4 | Test 2–3 hook formulas + 2–3 content structures. Post consistently. |
|
||||
| Month 2 | Identify top-performing patterns. Create 2x more of those. |
|
||||
| Month 3+ | 70% proven formats / 30% new experiments. Never stop testing the 30%. |
|
||||
|
||||
---
|
||||
|
||||
## 7. Content Bank — 30 Starter Ideas for [Niche]
|
||||
|
||||
Apply the hook formulas and content structures from above to these topic angles:
|
||||
|
||||
| # | Content angle | Hook formula | Structure | Format |
|
||||
|---|---|---|---|---|
|
||||
| 1 | [Common mistake in your niche] | Contrarian statement | Thread | LinkedIn / X |
|
||||
| 2 | [Counterintuitive insight you learned] | Uncomfortable truth | Thread | LinkedIn |
|
||||
| 3 | [A result you achieved + the process] | Specific number/result | Before→After→Bridge | All |
|
||||
| 4 | [A framework you use regularly] | Listicle tease | Carousel | Instagram / LinkedIn |
|
||||
| 5 | [An industry trend + your take] | Contrarian deep dive | Thread | LinkedIn / X |
|
||||
| 6 | [A story of failure + lesson] | Story hook | Story arc | TikTok / Reels |
|
||||
| 7 | [A tool/resource your audience would save] | Utility listicle | Carousel / list | Instagram / LinkedIn |
|
||||
| 8 | [A "what I wish I knew" post] | Listicle tease | Thread | LinkedIn |
|
||||
| 9 | [A behind-the-scenes process] | Pattern interrupt question | Video | TikTok / Reels |
|
||||
| 10 | [A reaction to industry news] | Contrarian statement | Thread | X / LinkedIn |
|
||||
|
||||
*[Generate 20 more ideas specific to the brand's niche here, using the same table format]*
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Every hook uses a proven formula — no generic openers like "Today I want to talk about..."
|
||||
- [ ] Content structure chosen matches the platform and goal (save-bait on IG, thread on LinkedIn)
|
||||
- [ ] Each piece of content has one clear shareability trigger identified
|
||||
- [ ] Platform-specific rules are applied (e.g. no outbound links in LinkedIn post body)
|
||||
- [ ] Content bank has enough variety to test multiple angles before doubling down
|
||||
- [ ] Testing system is set up — 48-hour signal tracked for every post
|
||||
- [ ] CTA asks for a specific action, not a generic "like and share"
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- "Build a viral content framework for [brand / creator]"
|
||||
- "Help me create shareable content for [platform]"
|
||||
- "What makes content go viral on [LinkedIn / TikTok / Instagram]?"
|
||||
- "Give me hook formulas and content structures for [niche]"
|
||||
- "Build a repeatable system for creating high-reach content"
|
||||
@@ -0,0 +1,531 @@
|
||||
---
|
||||
name: aeo-optimizer
|
||||
description: "Optimize an article for Answer Engine Optimization (AEO) — restructuring content so AI engines like ChatGPT, Perplexity, and Claude can extract, quote, and cite it. Rewrites headings as questions, drops 50-80 word answer capsules, audits paragraph length, and flags trust signals. Use when asked to AEO-optimize, make content AI-readable, improve AI citation chances, or adapt an article for answer engines."
|
||||
---
|
||||
|
||||
# AEO Optimizer Skill
|
||||
|
||||
AEO — Answer Engine Optimization — is the discipline of structuring content so that AI engines (ChatGPT, Perplexity, Claude, Gemini) can extract clean, quotable answers and confidently cite your content as a source.
|
||||
|
||||
Most articles are written for humans who scroll, skim, and click. AI engines don't scroll — they scan for extractable answer units. They look for short, self-contained answer blocks sitting directly beneath a clear question heading. If they can't find those, they either skip the content or paraphrase it poorly. This skill fixes that.
|
||||
|
||||
---
|
||||
|
||||
## The AEO Problem
|
||||
|
||||
Here is what AI engines are scanning for, and what most articles fail to provide:
|
||||
|
||||
| What AI engines want | What most articles deliver |
|
||||
|---|---|
|
||||
| H2 = a direct question ("What is X?") | H2 = a vague topic label ("About X" or "Understanding X") |
|
||||
| 50-80 word answer capsule immediately under the heading | Long intro paragraphs before the actual answer |
|
||||
| No links inside the answer block | Inline links that break extractability |
|
||||
| ≤3 sentences per paragraph | Dense 6-8 sentence paragraphs |
|
||||
| Named frameworks, original data, first-person experience | Generic statements with no attribution or specificity |
|
||||
| Consistent question-answer-expand structure throughout | Inconsistent structure that varies section by section |
|
||||
|
||||
When an AI engine cannot cleanly extract a 50-80 word answer, it either skips the article or provides a vague paraphrase without a citation link. AEO optimization removes those barriers.
|
||||
|
||||
---
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Claude will ask for these if not provided:
|
||||
|
||||
| Input | Required | Notes |
|
||||
|---|---|---|
|
||||
| Article content | Yes | Paste the full draft text, or provide a URL Claude can fetch |
|
||||
| Target audience | No | Helps calibrate question phrasing — e.g. "beginner founders" vs "senior engineers" |
|
||||
| Primary keyword or topic | No | If provided, Claude ensures H2 questions cover it directly |
|
||||
| Existing URL (if published) | No | Used in the audit report to note the live page |
|
||||
| Preserve exact section order | No | Defaults to yes — Claude rewrites in place, doesn't restructure |
|
||||
|
||||
If providing a URL instead of pasted text, Claude will fetch the page content. Note: paywalled or JavaScript-rendered articles may require manual paste.
|
||||
|
||||
---
|
||||
|
||||
## Output Structure
|
||||
|
||||
Claude produces two deliverables in sequence:
|
||||
|
||||
### Deliverable 1 — AEO-Ready Article
|
||||
|
||||
The full rewritten article with:
|
||||
- All H2s rewritten as direct questions
|
||||
- 50-80 word answer capsule inserted directly beneath each H2
|
||||
- Paragraphs trimmed to ≤3 sentences where they exceeded that
|
||||
- Trust signals preserved and lightly emphasized
|
||||
- No links inside any answer capsule
|
||||
- Original voice and structure maintained — this is an optimization, not a rewrite
|
||||
|
||||
**Format:**
|
||||
|
||||
```markdown
|
||||
# [Original H1 title — unchanged unless it needs question format]
|
||||
|
||||
[Introduction — keep as-is or trim to ≤3 sentences. Add a "What this covers:" summary if intro is >150 words.]
|
||||
|
||||
## [H2 rewritten as a direct question?]
|
||||
|
||||
[Answer capsule — 50-80 words, no links, self-contained, answers the question completely on its own.]
|
||||
|
||||
[Rest of the section body — expanded explanation, examples, data, links allowed here]
|
||||
|
||||
## [Next H2 as a direct question?]
|
||||
|
||||
[Answer capsule — 50-80 words, no links]
|
||||
|
||||
[Section body]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Deliverable 2 — AEO Audit Report
|
||||
|
||||
Structured report showing all changes made and signals identified.
|
||||
|
||||
**Format:**
|
||||
|
||||
---
|
||||
|
||||
## AEO Audit Report
|
||||
|
||||
**Article:** [Title]
|
||||
**URL:** [If provided]
|
||||
**Audit date:** [Today's date]
|
||||
**AEO readiness score (before):** [X/10]
|
||||
**AEO readiness score (after):** [X/10]
|
||||
|
||||
---
|
||||
|
||||
### Heading Rewrites
|
||||
|
||||
| Original H2 | Rewritten H2 | Change type |
|
||||
|---|---|---|
|
||||
| Understanding Content Strategy | What is content strategy and why does it matter? | Topic label → direct question |
|
||||
| The Benefits of X | What are the main benefits of X? | Vague noun phrase → question |
|
||||
| How We Do It at [Company] | How does [Company] approach X? | First-person → question format |
|
||||
|
||||
---
|
||||
|
||||
### Answer Capsule Placements
|
||||
|
||||
For each section, confirm capsule word count is within 50-80 words:
|
||||
|
||||
| Section | Capsule word count | Links removed from capsule | Status |
|
||||
|---|---|---|---|
|
||||
| What is content strategy...? | 64 words | 2 links removed | OK |
|
||||
| How do you build a content calendar? | 71 words | 0 links (none were present) | OK |
|
||||
| What tools do content teams use? | 58 words | 1 link removed | OK |
|
||||
|
||||
---
|
||||
|
||||
### Paragraph Length Audit
|
||||
|
||||
| Section | Original max paragraph (sentences) | Action taken |
|
||||
|---|---|---|
|
||||
| Introduction | 6 sentences | Split into 2 paragraphs |
|
||||
| Section 2 body | 4 sentences | Trimmed to 3 |
|
||||
| Section 4 body | 2 sentences | No change needed |
|
||||
|
||||
**Paragraphs flagged as too long (before optimization):** [N]
|
||||
**Paragraphs within ≤3 sentences (after optimization):** [all]
|
||||
|
||||
---
|
||||
|
||||
### Trust Signal Inventory
|
||||
|
||||
Trust signals are the elements AI engines treat as credibility markers — original data, named frameworks, first-person experience, and specific attributions. These make AI engines more likely to cite rather than paraphrase.
|
||||
|
||||
| Signal type | Found in article | Example | AEO value |
|
||||
|---|---|---|---|
|
||||
| Original data / research | Yes | "Our analysis of 400 posts showed..." | High — cite-worthy claim |
|
||||
| Named framework | Yes | "The RICE scoring model" | High — search anchor |
|
||||
| First-person experience | Yes | "After running 3 content audits..." | Medium — authority signal |
|
||||
| Named expert / quote | No | — | Recommend adding |
|
||||
| Specific numbers / stats | Yes | "34% increase in organic traffic" | High — extractable fact |
|
||||
| Date-stamped content | No | — | Recommend adding publication date |
|
||||
| Case study reference | Yes | "At Acme Corp, we ran..." | High — concrete example |
|
||||
|
||||
**Trust signals present:** [N]
|
||||
**Recommended additions:** [list any gaps]
|
||||
|
||||
---
|
||||
|
||||
### AEO Scoring Rubric
|
||||
|
||||
| Criterion | Before | After |
|
||||
|---|---|---|
|
||||
| H2s as direct questions (% of total) | [X%] | [X%] |
|
||||
| Answer capsule present under each H2 | No | Yes |
|
||||
| Capsules within 50-80 words | N/A | [X/N sections] |
|
||||
| No links inside capsules | N/A | Yes |
|
||||
| Paragraphs ≤3 sentences | [X%] | [X%] |
|
||||
| Trust signals present | [N] | [N] |
|
||||
| **Total score** | **[X/10]** | **[X/10]** |
|
||||
|
||||
---
|
||||
|
||||
### Recommended Next Steps
|
||||
|
||||
1. [Any remaining gaps — e.g. "Section 4 capsule is 88 words — trim by 10"]
|
||||
2. [Structural suggestions — e.g. "Add a FAQ section at the end for high-volume PAA questions"]
|
||||
3. [Missing trust signals — e.g. "Add a publication date and last-updated date for freshness signals"]
|
||||
4. [Schema markup suggestion if applicable — FAQ schema, HowTo schema, etc.]
|
||||
|
||||
---
|
||||
|
||||
*End of AEO Audit Report*
|
||||
|
||||
---
|
||||
|
||||
## How Claude Should Execute This Skill
|
||||
|
||||
### Step 1 — Ingest the article
|
||||
|
||||
Accept the content as either:
|
||||
- **Pasted text:** Treat as-is. Do not attempt to fetch a URL if text is pasted.
|
||||
- **URL:** Fetch the page. Extract the main article body — ignore nav, sidebars, footers, and ad blocks. If the page is JavaScript-rendered and fetch returns only a shell, ask the user to paste the text instead.
|
||||
|
||||
Count the headings. Note the number of H2s, H3s, and H1s. This sets expectations for how many capsules will be written.
|
||||
|
||||
### Step 2 — Assess AEO readiness before touching anything
|
||||
|
||||
Before rewriting, score the article on the AEO rubric (see Deliverable 2 scoring table). This gives the user a before/after comparison and helps Claude identify where to focus effort.
|
||||
|
||||
Run through each criterion and note the count:
|
||||
- How many H2s are already in question format? (count ones that end with "?")
|
||||
- Does any section already have a 50-80 word self-contained answer block?
|
||||
- What is the average and maximum paragraph length in sentences?
|
||||
- How many trust signals are present? (scan for numbers, named frameworks, first-person phrases, quotes)
|
||||
|
||||
Record the before scores. Do not round up — be honest.
|
||||
|
||||
### Step 3 — Rewrite H2 headings as questions
|
||||
|
||||
For each H2 in the article, rewrite it as a direct question that a real person would ask an AI engine. Guidelines:
|
||||
|
||||
**The question must:**
|
||||
- Be specific enough that the answer could stand alone as a snippet
|
||||
- Use "What", "How", "Why", "When", "Which", or "Who" — not vague gerunds ("Understanding", "Exploring", "Unpacking")
|
||||
- Match the search intent of the original section, not just rephrase it generically
|
||||
- Be 8 words or fewer when possible (longer questions are harder for AI engines to match)
|
||||
|
||||
**Examples of heading transformations:**
|
||||
|
||||
| Before | After |
|
||||
|---|---|
|
||||
| Introduction to Agile | What is Agile methodology? |
|
||||
| Why We Built This | Why did [Company] build [product]? |
|
||||
| The Case for Async Work | Why do distributed teams choose async work? |
|
||||
| Benefits | What are the main benefits of X? |
|
||||
| Tools and Resources | Which tools do [audience] use for X? |
|
||||
| Getting Started | How do you get started with X? |
|
||||
| Common Mistakes | What mistakes do beginners make with X? |
|
||||
| Our Approach | How does [Company/author] approach X? |
|
||||
|
||||
Do not rewrite H3s unless the user requests it. H3s can stay as labels — AI engines primarily anchor on H2s.
|
||||
|
||||
Do not change the H1. The H1 is the article title and SEO title — it follows different rules.
|
||||
|
||||
### Step 4 — Write answer capsules
|
||||
|
||||
For each H2, write a 50-80 word answer capsule to be inserted immediately after the heading and before any existing body text.
|
||||
|
||||
**Capsule rules:**
|
||||
- Must be self-contained — someone reading only the heading + capsule should have a complete, useful answer
|
||||
- No links of any kind inside the capsule (links break AI extractability)
|
||||
- No hedging phrases ("It depends", "There are many factors") — commit to the answer
|
||||
- Use the same voice and terminology as the article — do not change the author's perspective
|
||||
- If the section has an existing strong first paragraph that is already 50-80 words and self-contained, use it as the capsule with minimal edits rather than writing a new one
|
||||
- Count words precisely — under 50 is too thin, over 80 and AI engines may not extract it cleanly
|
||||
|
||||
**Capsule structure options:**
|
||||
|
||||
Option A — Definition then application:
|
||||
```
|
||||
[Concise definition of the concept in 1-2 sentences.] [How it applies in practice, with one specific example or number.] [Why it matters for the reader's situation.]
|
||||
```
|
||||
|
||||
Option B — Direct answer then context:
|
||||
```
|
||||
[Direct answer to the heading question in 1 sentence.] [2-3 sentences of supporting context, specifics, or mechanism.] [Optional: one concrete example or stat.]
|
||||
```
|
||||
|
||||
Option C — How-to opener:
|
||||
```
|
||||
[State the outcome in 1 sentence.] [Steps 1, 2, 3 in compressed form.] [Note on when this applies or what to watch for.]
|
||||
```
|
||||
|
||||
Mark each capsule clearly with an HTML comment so the author knows it was added:
|
||||
```html
|
||||
<!-- AEO Answer Capsule — 64 words -->
|
||||
[capsule text]
|
||||
<!-- End AEO Capsule -->
|
||||
```
|
||||
|
||||
### Step 5 — Audit and trim paragraph length
|
||||
|
||||
Scan every paragraph in the body sections (not the capsules). If a paragraph exceeds 3 sentences:
|
||||
- Split it into two paragraphs at the most natural break
|
||||
- Do not summarise or remove content — just add a paragraph break
|
||||
- If a paragraph is a list in disguise (long run-on sentence with "and", "then", "also"), convert it to a bullet list instead
|
||||
|
||||
Note every change in the audit report's paragraph length table.
|
||||
|
||||
### Step 6 — Identify and flag trust signals
|
||||
|
||||
Scan the full article for trust signals. Do not add trust signals — only identify what exists and flag gaps. Trust signals are:
|
||||
|
||||
| Signal type | What to look for |
|
||||
|---|---|
|
||||
| Original data | "Our data shows", "We analysed X", "In our survey of N..." |
|
||||
| Named frameworks | Any named methodology, model, or system (RICE, Jobs-to-be-Done, etc.) |
|
||||
| First-person experience | "I found", "We ran", "When I built", "After testing..." |
|
||||
| Specific numbers | Percentages, counts, timeframes, dollar amounts |
|
||||
| Expert quotes | Direct quotes attributed to a named person |
|
||||
| Case studies | Named company or project with specific outcomes |
|
||||
| Publication freshness | A visible publish or update date |
|
||||
|
||||
Flag any category with zero signals as a gap. Include specific recommendations for what could be added (e.g. "Add a statistic to the intro — even a well-known industry stat cited correctly adds credibility").
|
||||
|
||||
### Step 7 — Assemble the output
|
||||
|
||||
Produce the two deliverables in this order:
|
||||
|
||||
1. First: the full AEO-ready article. Use the original markdown structure with the changes applied. Make sure capsules have the HTML comment markers.
|
||||
2. Second: the AEO Audit Report, using the exact table structure from the Output Structure section above.
|
||||
|
||||
Separate the two deliverables with a clear horizontal rule (`---`) and a heading (`## AEO Audit Report`).
|
||||
|
||||
### Step 8 — Optional: FAQ section recommendation
|
||||
|
||||
If the article does not already have a FAQ section, and the topic has obvious high-volume PAA (People Also Ask) questions, recommend adding one. Provide 3-5 suggested FAQ questions in question format with brief capsule answers. Note that FAQ sections with proper schema markup (`FAQPage` JSON-LD) get preferential treatment in both traditional SEO and AI engine extraction.
|
||||
|
||||
---
|
||||
|
||||
## AEO Reference: What Makes a Good Answer Capsule
|
||||
|
||||
This section is reference material — Claude should use it when evaluating capsule quality.
|
||||
|
||||
**Strong capsule (62 words):**
|
||||
> Content strategy is the planning and management of content to achieve specific business goals. It defines what to publish, for whom, through which channels, and how often. A strong content strategy starts with audience research, maps content to stages of the buyer journey, and includes a measurement framework. Without it, content teams produce output without direction — publishing more without knowing whether it drives outcomes.
|
||||
|
||||
Why it works:
|
||||
- Answers the question completely in isolation
|
||||
- No links
|
||||
- Specific enough to be citable (mentions audience research, buyer journey, measurement framework)
|
||||
- Under 80 words
|
||||
|
||||
**Weak capsule (48 words — too short, too vague):**
|
||||
> Content strategy is important for businesses. It helps you plan what content to create. Many companies use content strategy to grow their audience. There are different approaches depending on your goals. It's a broad topic that covers many areas of marketing.
|
||||
|
||||
Why it fails:
|
||||
- Does not complete the answer — "many areas" is not an answer
|
||||
- No specifics, no named concepts
|
||||
- Under 50 words
|
||||
- AI engine would not cite this — it says nothing citable
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
Before marking this task complete, verify each item:
|
||||
|
||||
- [ ] Every H2 in the article is now a direct question ending with "?"
|
||||
- [ ] Every question-format H2 has an answer capsule immediately below it (no intervening text)
|
||||
- [ ] Every capsule is between 50 and 80 words — count precisely, not approximately
|
||||
- [ ] No links appear inside any capsule block
|
||||
- [ ] Every capsule has the HTML comment markers noting word count
|
||||
- [ ] Paragraphs throughout the article body are ≤3 sentences (flag any exceptions in the report)
|
||||
- [ ] The H1 title is unchanged
|
||||
- [ ] H3s are unchanged (unless user requested otherwise)
|
||||
- [ ] Original voice, tone, and terminology are preserved — this is optimization, not ghostwriting
|
||||
- [ ] Trust signal inventory table is populated with actual examples from the text, not generic placeholders
|
||||
- [ ] Gaps in trust signals are noted with specific recommendations, not just "add more data"
|
||||
- [ ] Before and after AEO scores are both present in the audit report
|
||||
- [ ] Heading rewrites table is complete — one row per H2
|
||||
- [ ] Paragraph length audit table is complete — covers all sections
|
||||
- [ ] Any FAQ section recommendation is based on real PAA-style questions for the topic, not invented ones
|
||||
- [ ] Both deliverables (article + audit report) are present in the response
|
||||
- [ ] Total word count of the rewritten article is within ±10% of the original (optimization, not expansion)
|
||||
|
||||
---
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- "AEO optimize this article"
|
||||
- "Make this content AI-readable"
|
||||
- "Rewrite my headings as questions and add answer capsules"
|
||||
- "Optimize this for ChatGPT and Perplexity to cite"
|
||||
- "Run an AEO audit on this draft"
|
||||
- "Make this article get picked up by AI search"
|
||||
- "I want Perplexity to cite my content — can you fix this article?"
|
||||
- "Turn these headings into questions and add short answer blocks"
|
||||
- "Can you add answer capsules under each section?"
|
||||
- "Audit this for answer engine optimization"
|
||||
- "My content isn't showing up in AI answers — fix the structure"
|
||||
- "AEO this" [followed by article text or URL]
|
||||
- "Optimize for AI citation"
|
||||
- "Make each section self-contained for AI extraction"
|
||||
|
||||
---
|
||||
|
||||
## Appendix: AEO vs SEO — Key Differences
|
||||
|
||||
This is useful context Claude can share with users who are unfamiliar with AEO:
|
||||
|
||||
| Dimension | SEO (Search Engine Optimization) | AEO (Answer Engine Optimization) |
|
||||
|---|---|---|
|
||||
| Target | Google's ranking algorithm | AI engine extraction models |
|
||||
| Primary signal | Backlinks, authority, keyword density | Structured Q&A, answer capsule clarity |
|
||||
| Content format | Long-form, comprehensive coverage | Question-first, capsule-first, then expand |
|
||||
| Heading style | Keyword-rich labels ("Best Project Management Tools") | Direct questions ("What are the best project management tools?") |
|
||||
| Paragraph length | Not a ranking factor | Short (≤3 sentences) is strongly preferred |
|
||||
| Links in body | Important for authority passing | Links inside answer capsules break extractability |
|
||||
| Trust signals | Domain authority, backlink profile | Named data, frameworks, first-person experience |
|
||||
| Measurement | Organic ranking position, CTR | AI citation frequency, answer box appearances |
|
||||
|
||||
AEO does not replace SEO — it complements it. A well-structured article optimized for AEO will also perform better in traditional search because its structure is clearer and its headings are more specific to user intent.
|
||||
|
||||
---
|
||||
|
||||
## Appendix: Answer Capsule Templates by Content Type
|
||||
|
||||
Not all articles have the same kind of content. Use these capsule templates as starting points based on the section type.
|
||||
|
||||
### "What is X?" sections (definition)
|
||||
|
||||
```
|
||||
[X] is [concise category or type]. It [what it does or how it works] by [mechanism or method].
|
||||
[Why it exists or what problem it solves — 1 sentence.] [One concrete example or real-world application.]
|
||||
```
|
||||
|
||||
Target: 55-70 words. Avoid starting with "X is a type of X" — give immediate signal.
|
||||
|
||||
### "How do you do X?" sections (how-to)
|
||||
|
||||
```
|
||||
To [achieve outcome], [do step A], then [do step B], then [do step C].
|
||||
[The most common mistake or prerequisite — 1 sentence.] [The expected result or timeframe.]
|
||||
```
|
||||
|
||||
Target: 50-65 words. Use active verbs throughout. No links.
|
||||
|
||||
### "Why does X matter?" sections (rationale)
|
||||
|
||||
```
|
||||
[X] matters because [specific reason 1] and [specific reason 2].
|
||||
Without [X], [consequence — ideally quantified or concrete].
|
||||
[Who this is most important for, and under what conditions.]
|
||||
```
|
||||
|
||||
Target: 55-75 words. Specifics outperform generalities here — name numbers when they exist.
|
||||
|
||||
### "What are the benefits of X?" sections (list rationale)
|
||||
|
||||
```
|
||||
The main benefits of [X] are [benefit 1], [benefit 2], and [benefit 3].
|
||||
[Benefit 1] means [specific outcome]. [Benefit 2] enables [specific use case].
|
||||
Together these make [X] valuable for [audience] who need [outcome].
|
||||
```
|
||||
|
||||
Target: 60-80 words. Compress the list into prose — bullet lists inside capsules are less extractable.
|
||||
|
||||
### "Which X should I choose?" sections (comparison/decision)
|
||||
|
||||
```
|
||||
Choose [Option A] when [condition A]. Choose [Option B] when [condition B].
|
||||
The deciding factor is [key variable]. [One sentence on the most common mistake —
|
||||
picking based on the wrong criterion.]
|
||||
```
|
||||
|
||||
Target: 50-70 words. Decision capsules are among the highest-cited by AI engines — they answer the user's actual next question.
|
||||
|
||||
### "When should I X?" sections (timing/trigger)
|
||||
|
||||
```
|
||||
[X] when [specific trigger condition], typically [timeframe or frequency].
|
||||
Early signs that it's time include [signal 1] and [signal 2].
|
||||
Waiting too long often results in [consequence].
|
||||
```
|
||||
|
||||
Target: 45-65 words. Concise is especially important for timing capsules.
|
||||
|
||||
---
|
||||
|
||||
## Appendix: AEO Scoring Rubric — Detailed Criteria
|
||||
|
||||
Use this when producing the before/after score. Each criterion has a maximum contribution to the /10 score.
|
||||
|
||||
| Criterion | Max score | How to assess |
|
||||
|---|---|---|
|
||||
| H2s as direct questions | 2 pts | 2 = all H2s are questions; 1 = majority; 0 = few or none |
|
||||
| Answer capsules present | 2 pts | 2 = every H2 section has a capsule; 1 = some sections; 0 = none |
|
||||
| Capsules within 50-80 words | 1 pt | 1 = all capsules in range; 0 = any over 80 or under 50 |
|
||||
| No links inside capsules | 1 pt | 1 = zero links in any capsule; 0 = any links present |
|
||||
| Paragraphs ≤3 sentences | 2 pts | 2 = all paragraphs compliant; 1 = majority; 0 = widespread violations |
|
||||
| Trust signals present | 2 pts | 2 = 3+ trust signal types; 1 = 1-2 types; 0 = none |
|
||||
|
||||
**Score interpretation:**
|
||||
- 8-10: Strong AEO readiness — well-positioned for AI citation
|
||||
- 5-7: Partial — likely extracted occasionally but inconsistently
|
||||
- 0-4: Low readiness — AI engines will paraphrase at best, skip at worst
|
||||
|
||||
A typical unoptimized article scores 2-4. A well-structured but unoptimized thought leadership piece might score 4-6. After this skill runs, target 8+.
|
||||
|
||||
---
|
||||
|
||||
## Appendix: How Different AI Engines Extract Content
|
||||
|
||||
Understanding how each engine works helps explain the rules behind the skill.
|
||||
|
||||
### ChatGPT (GPT-4 and later) / Bing
|
||||
|
||||
Retrieval-augmented generation with Bing Search integration. When a user asks a question, Bing retrieves pages, then GPT extracts passages. It tends to extract the first plausible answer-shaped block it finds in the page — meaning the capsule directly under the H2 is almost always what gets quoted. It prefers prose over lists for citations (though it reads lists fine).
|
||||
|
||||
**Implication:** Get the capsule under the question-format H2 right. The rest of the section body is bonus context.
|
||||
|
||||
### Perplexity
|
||||
|
||||
Explicitly designed for sourced Q&A. It retrieves 5-10 pages per query and extracts from all of them simultaneously. It shows citations with numbered footnotes. It strongly prefers content that is:
|
||||
- Clearly attributed (author name or publication byline visible)
|
||||
- Recently published or updated (freshness signal)
|
||||
- Structured around the question being asked (heading match)
|
||||
|
||||
**Implication:** Trust signals (author, date) and heading-to-question matching are especially important for Perplexity. Capsules that include specific numbers or named frameworks are more likely to be footnoted.
|
||||
|
||||
### Claude (Anthropic)
|
||||
|
||||
Claude with web search capability (Claude.ai or API with tools) retrieves pages and synthesises across them. Claude prioritises self-contained, complete answers and tends to directly quote capsules that are within the 50-80 word range. Claude is less likely to quote incomplete paragraphs that trail off or rely on surrounding context.
|
||||
|
||||
**Implication:** The self-contained requirement is especially important for Claude citation. If the capsule requires reading the surrounding sentences to make sense, Claude will paraphrase instead of quote.
|
||||
|
||||
### Google Gemini (AI Overviews)
|
||||
|
||||
Integrated into Google Search. Generates AI Overviews for informational queries. Extracts from indexed pages, with preference for pages that already rank well (so SEO and AEO reinforce each other here). Tends to extract bulleted lists and numbered steps for how-to content; extracts definition capsules for "what is" queries.
|
||||
|
||||
**Implication:** For Gemini AI Overviews, structured how-to content with numbered steps in the capsule performs well. Definition capsules should include the category/type as the first word.
|
||||
|
||||
---
|
||||
|
||||
## Appendix: Content Types That Benefit Most from AEO
|
||||
|
||||
Not all content benefits equally. Use this to set expectations with the user about where AEO investment pays off most.
|
||||
|
||||
| Content type | AEO benefit | Reason |
|
||||
|---|---|---|
|
||||
| Glossary or definition articles | Very high | AI engines are constantly answering "what is X?" queries |
|
||||
| How-to guides and tutorials | Very high | Step-by-step content is a primary retrieval target |
|
||||
| Comparison articles ("X vs Y") | High | Decision queries are common AI engine inputs |
|
||||
| FAQ pages | High | Already in question format — just needs capsule discipline |
|
||||
| Research roundups with original data | High | Named statistics are citation anchors |
|
||||
| Thought leadership / opinion pieces | Medium | Opinion is less extractable; add definition and how-to sections |
|
||||
| News and timely content | Medium | AI engines prefer evergreen; but breaking news gets citation bursts |
|
||||
| Case studies | Medium | Specific outcomes are extractable; company-specific context less so |
|
||||
| Creative writing / narrative | Low | Not structured for extraction; AEO rules don't apply |
|
||||
| Product pages / landing pages | Low | Conversion-focused pages are rarely cited by AI engines |
|
||||
|
||||
---
|
||||
|
||||
*Originally created by Gencay (LearnAIwithMe) — adapted and extended for this library.*
|
||||
@@ -0,0 +1,665 @@
|
||||
---
|
||||
name: instagram-post-downloader
|
||||
description: "Download Instagram posts — single images or full carousels — directly from a URL. Fetches high-resolution files from Instagram's CDN, saves them into a named folder, and stitches carousel slides into a single PDF. Supports batch downloading of multiple URLs at once. Use when asked to download, save, or archive an Instagram post, reel thumbnail, or carousel."
|
||||
---
|
||||
|
||||
# Instagram Post Downloader Skill
|
||||
|
||||
Downloads Instagram posts at full resolution from Instagram's CDN — no screenshots, no compression. Handles single images, carousels (multi-slide posts), and Reel cover images. For carousels, produces individual slide files plus a single stitched PDF. Supports batch URLs in one run.
|
||||
|
||||
---
|
||||
|
||||
## PREREQUISITE — Domain Allowlist
|
||||
|
||||
Before this skill can fetch any media, you must add Instagram's CDN domain to Claude Code's allowlist:
|
||||
|
||||
**Settings → Capabilities → Domain allowlist → Add:**
|
||||
```
|
||||
*.cdninstagram.com
|
||||
```
|
||||
|
||||
Without this, all CDN fetch calls will be blocked. If you see a permission error when Claude attempts a fetch to `cdninstagram.com`, this is the fix.
|
||||
|
||||
---
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Claude will ask for these if not provided upfront:
|
||||
|
||||
| Input | Required | Notes |
|
||||
|---|---|---|
|
||||
| Instagram post URL(s) | Yes | One per line, or comma-separated. `https://www.instagram.com/p/XXXX/` or `https://www.instagram.com/reel/XXXX/` format |
|
||||
| Output directory | No | Defaults to `./instagram-downloads/` in the current working directory |
|
||||
| PDF stitch for carousels | No | Defaults to **yes** — produces `carousel.pdf` alongside individual slides |
|
||||
| File naming prefix | No | Optional prefix added before slide filenames, e.g. `brand_` → `brand_slide_01.jpg` |
|
||||
|
||||
**Batch input example:**
|
||||
```
|
||||
https://www.instagram.com/p/ABC123/
|
||||
https://www.instagram.com/p/DEF456/
|
||||
https://www.instagram.com/p/GHI789/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Output Structure
|
||||
|
||||
For each URL processed, Claude creates a folder named after the post caption (first 40 characters, sanitised — spaces become underscores, special characters stripped). If no caption is available, the folder is named after the post shortcode.
|
||||
|
||||
### Single image post
|
||||
|
||||
```
|
||||
instagram-downloads/
|
||||
└── this_is_the_caption_first_40_chars/
|
||||
├── image.jpg
|
||||
└── metadata.txt
|
||||
```
|
||||
|
||||
### Carousel post
|
||||
|
||||
```
|
||||
instagram-downloads/
|
||||
└── carousel_caption_first_40_chars/
|
||||
├── slide_01.jpg
|
||||
├── slide_02.jpg
|
||||
├── slide_03.jpg
|
||||
├── slide_04.jpg
|
||||
├── carousel.pdf ← all slides stitched in order
|
||||
└── metadata.txt
|
||||
```
|
||||
|
||||
### Batch run (3 URLs)
|
||||
|
||||
```
|
||||
instagram-downloads/
|
||||
├── first_post_caption_sanitised/
|
||||
│ ├── image.jpg
|
||||
│ └── metadata.txt
|
||||
├── second_post_carousel_caption/
|
||||
│ ├── slide_01.jpg
|
||||
│ ├── slide_02.jpg
|
||||
│ ├── carousel.pdf
|
||||
│ └── metadata.txt
|
||||
└── third_post_caption_here/
|
||||
├── image.jpg
|
||||
└── metadata.txt
|
||||
```
|
||||
|
||||
### metadata.txt format
|
||||
|
||||
```
|
||||
Post URL: https://www.instagram.com/p/XXXX/
|
||||
Shortcode: XXXX
|
||||
Type: carousel | single_image | reel
|
||||
Slide count: 4 (carousel only)
|
||||
Caption: [full caption text]
|
||||
Username: @username
|
||||
Fetched at: 2026-05-27T14:32:00Z
|
||||
CDN URLs:
|
||||
slide_01.jpg https://scontent.cdninstagram.com/v/...
|
||||
slide_02.jpg https://scontent.cdninstagram.com/v/...
|
||||
```
|
||||
|
||||
### Completion summary (printed to terminal)
|
||||
|
||||
```
|
||||
Instagram Post Downloader — Batch Complete
|
||||
==========================================
|
||||
URLs processed: 3
|
||||
Posts saved: 3
|
||||
Total files: 11 (9 images + 2 PDFs)
|
||||
Skipped: 0
|
||||
Output dir: /Users/you/project/instagram-downloads/
|
||||
|
||||
Results:
|
||||
✓ this_is_the_caption_first_40_chars/ 1 image
|
||||
✓ carousel_caption_first_40_chars/ 4 slides → carousel.pdf
|
||||
✓ third_post_caption_here/ 1 image
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## How Claude Should Execute This Skill
|
||||
|
||||
### Step 1 — Collect and validate inputs
|
||||
|
||||
1. Accept the URL(s) from the user. If the user pastes a comma-separated list, split on commas. If they paste one per line, split on newlines.
|
||||
2. Validate each URL matches `instagram.com/p/`, `instagram.com/reel/`, or `instagram.com/tv/`. Flag malformed URLs before proceeding.
|
||||
3. Confirm the output directory. If none provided, use `./instagram-downloads/` and tell the user.
|
||||
4. Ask about PDF stitching preference only if the user hasn't said either way. Default is yes.
|
||||
|
||||
### Step 2 — For each URL: fetch the post page
|
||||
|
||||
Fetch the Instagram post page HTML:
|
||||
|
||||
```
|
||||
GET https://www.instagram.com/p/{shortcode}/?__a=1&__d=dis
|
||||
```
|
||||
|
||||
Instagram frequently changes its API surface. Use this fallback chain in order:
|
||||
|
||||
**Attempt A — JSON endpoint:**
|
||||
```
|
||||
https://www.instagram.com/p/{shortcode}/?__a=1&__d=dis
|
||||
```
|
||||
Parse the JSON response. Look for `graphql.shortcode_media` or `data.shortcode_media`.
|
||||
|
||||
**Attempt B — Embed page (most reliable):**
|
||||
```
|
||||
https://www.instagram.com/p/{shortcode}/embed/captioned/
|
||||
```
|
||||
Fetch this page's HTML and extract `og:image` meta tags and any `window.__additionalDataLoaded` or `window.__StaticData` JSON blobs embedded in `<script>` tags.
|
||||
|
||||
**Attempt C — oEmbed endpoint:**
|
||||
```
|
||||
https://api.instagram.com/oembed/?url=https://www.instagram.com/p/{shortcode}/&omitscript=true
|
||||
```
|
||||
This returns `thumbnail_url` — useful for single images, but only gives the first frame for carousels.
|
||||
|
||||
**Headers to include on all requests:**
|
||||
```
|
||||
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36
|
||||
Accept-Language: en-US,en;q=0.9
|
||||
Accept: text/html,application/xhtml+xml,application/json
|
||||
```
|
||||
|
||||
### Step 3 — Extract CDN image URLs
|
||||
|
||||
From the fetched data, extract all high-resolution CDN URLs. Instagram CDN URLs follow these patterns:
|
||||
|
||||
```
|
||||
https://scontent.cdninstagram.com/v/...jpg?...
|
||||
https://scontent-lax3-1.cdninstagram.com/v/...jpg?...
|
||||
https://instagram.fXXX1-1.fbcdn.net/v/...jpg?...
|
||||
```
|
||||
|
||||
**For single image posts:**
|
||||
- Extract the single `display_url` or the largest `display_resources` entry (pick the one with the highest `config_width`).
|
||||
|
||||
**For carousel posts:**
|
||||
- Look for `edge_sidecar_to_children.edges[]` in the JSON. Each edge has its own `node.display_url` and `node.display_resources[]`.
|
||||
- Iterate all edges in order. This determines slide numbering.
|
||||
- Pick the highest-resolution variant from each slide's `display_resources` array.
|
||||
|
||||
**For Reels:**
|
||||
- The cover image is extractable the same way as a single image.
|
||||
- The video file itself requires a third-party tool (see Bonus section).
|
||||
|
||||
**If JSON extraction fails**, fall back to scraping `<meta property="og:image">` tags from the page HTML — this gives at least one image URL (the first slide or only image).
|
||||
|
||||
### Step 4 — Sanitise folder name
|
||||
|
||||
Build the folder name from the post caption:
|
||||
1. Take the first 40 characters of the caption.
|
||||
2. Strip all characters that are not alphanumeric, spaces, or hyphens.
|
||||
3. Replace spaces and hyphens with underscores.
|
||||
4. Lowercase the result.
|
||||
5. Strip leading/trailing underscores.
|
||||
6. If the result is empty (e.g. caption was all emoji), use the post shortcode instead.
|
||||
|
||||
```python
|
||||
import re
|
||||
|
||||
def sanitise_folder_name(caption: str, shortcode: str) -> str:
|
||||
truncated = caption[:40]
|
||||
cleaned = re.sub(r'[^a-zA-Z0-9 \-]', '', truncated)
|
||||
underscored = re.sub(r'[\s\-]+', '_', cleaned).strip('_').lower()
|
||||
return underscored if underscored else shortcode
|
||||
```
|
||||
|
||||
### Step 5 — Create output folder structure
|
||||
|
||||
```python
|
||||
import os
|
||||
|
||||
base_dir = "./instagram-downloads"
|
||||
folder_name = sanitise_folder_name(caption, shortcode)
|
||||
post_dir = os.path.join(base_dir, folder_name)
|
||||
os.makedirs(post_dir, exist_ok=True)
|
||||
```
|
||||
|
||||
If a folder with that name already exists (e.g. running the same URL twice), append the shortcode to avoid collision: `folder_name_SHORTCODE`.
|
||||
|
||||
### Step 6 — Download each image file
|
||||
|
||||
For each CDN URL, download the file with a streaming GET request:
|
||||
|
||||
```python
|
||||
import requests
|
||||
|
||||
def download_file(url: str, dest_path: str) -> bool:
|
||||
headers = {
|
||||
"User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
|
||||
"Referer": "https://www.instagram.com/",
|
||||
}
|
||||
response = requests.get(url, headers=headers, stream=True, timeout=30)
|
||||
response.raise_for_status()
|
||||
with open(dest_path, "wb") as f:
|
||||
for chunk in response.iter_content(chunk_size=8192):
|
||||
f.write(chunk)
|
||||
return True
|
||||
```
|
||||
|
||||
Name files:
|
||||
- Single image: `image.jpg`
|
||||
- Carousel slides: `slide_01.jpg`, `slide_02.jpg`, ... (zero-padded to 2 digits, or 3 digits if >99 slides)
|
||||
|
||||
Detect file format from the `Content-Type` header or URL extension. Instagram serves JPEG for photos and may serve WebP in some cases — preserve the actual extension.
|
||||
|
||||
### Step 7 — Stitch carousel PDF (if applicable)
|
||||
|
||||
After all slides are downloaded, stitch them into a single PDF using Pillow:
|
||||
|
||||
```python
|
||||
from PIL import Image
|
||||
|
||||
def stitch_to_pdf(image_paths: list[str], output_path: str) -> None:
|
||||
"""
|
||||
Combine a list of image files into a single multi-page PDF.
|
||||
Each image becomes one page. Page size matches the image dimensions.
|
||||
"""
|
||||
images = []
|
||||
for path in sorted(image_paths): # sort ensures slide_01, slide_02, ... order
|
||||
img = Image.open(path).convert("RGB")
|
||||
images.append(img)
|
||||
|
||||
if not images:
|
||||
return
|
||||
|
||||
first = images[0]
|
||||
rest = images[1:]
|
||||
first.save(
|
||||
output_path,
|
||||
format="PDF",
|
||||
save_all=True,
|
||||
append_images=rest,
|
||||
resolution=150.0,
|
||||
)
|
||||
```
|
||||
|
||||
Save as `carousel.pdf` in the post folder. If Pillow is not installed, run `pip install Pillow` first — or instruct the user to do so.
|
||||
|
||||
**Dependency check at start of skill:**
|
||||
```python
|
||||
try:
|
||||
from PIL import Image
|
||||
except ImportError:
|
||||
print("Pillow not installed. Run: pip install Pillow")
|
||||
print("PDF stitching will be skipped. Individual slides will still be downloaded.")
|
||||
skip_pdf = True
|
||||
```
|
||||
|
||||
### Step 8 — Write metadata.txt
|
||||
|
||||
Write a `metadata.txt` file into the post folder with all extracted metadata:
|
||||
|
||||
```python
|
||||
from datetime import datetime, timezone
|
||||
|
||||
def write_metadata(post_dir, post_url, shortcode, post_type, caption, username, cdn_urls):
|
||||
lines = [
|
||||
f"Post URL: {post_url}",
|
||||
f"Shortcode: {shortcode}",
|
||||
f"Type: {post_type}",
|
||||
]
|
||||
if post_type == "carousel":
|
||||
lines.append(f"Slide count: {len(cdn_urls)}")
|
||||
lines += [
|
||||
f"Caption: {caption}",
|
||||
f"Username: @{username}",
|
||||
f"Fetched at: {datetime.now(timezone.utc).isoformat()}",
|
||||
"CDN URLs:",
|
||||
]
|
||||
for filename, url in cdn_urls.items():
|
||||
lines.append(f" {filename:<16} {url}")
|
||||
|
||||
with open(os.path.join(post_dir, "metadata.txt"), "w", encoding="utf-8") as f:
|
||||
f.write("\n".join(lines) + "\n")
|
||||
```
|
||||
|
||||
### Step 9 — Print completion summary
|
||||
|
||||
After processing all URLs, print the summary table to the terminal (format shown in Output Structure section above). Include:
|
||||
- Total URLs attempted
|
||||
- Posts successfully saved
|
||||
- Total files written (images + PDFs separately)
|
||||
- Any URLs that were skipped and the reason
|
||||
|
||||
### Step 10 — Handle errors gracefully
|
||||
|
||||
| Error scenario | Action |
|
||||
|---|---|
|
||||
| URL is not an Instagram URL | Skip with message: "Skipped — not an Instagram URL: [url]" |
|
||||
| Post is private or requires login | Skip with message: "Skipped — post is private or login required: [url]" |
|
||||
| CDN fetch returns 403/404 | Try alternate CDN URL if available; if none, skip slide and note in metadata |
|
||||
| Pillow not installed | Skip PDF stitching, save slides only, note in summary |
|
||||
| Network timeout | Retry once after 5 seconds; if still failing, skip and log |
|
||||
| Folder name collision | Append shortcode suffix to folder name |
|
||||
| Rate limiting (429) | Wait 10 seconds and retry; log if retry also fails |
|
||||
|
||||
---
|
||||
|
||||
## Bonus — Downloading Instagram Reels (Video)
|
||||
|
||||
This skill covers images and carousel PDFs. For Reels video files, Claude Code cannot download video directly without a third-party tool, because Instagram's video CDN uses signed URLs and additional auth tokens.
|
||||
|
||||
**Recommended approach for Reels:**
|
||||
|
||||
Use `yt-dlp`, a maintained open-source tool:
|
||||
|
||||
```bash
|
||||
# Install
|
||||
pip install yt-dlp
|
||||
|
||||
# Download a Reel
|
||||
yt-dlp "https://www.instagram.com/reel/XXXX/" -o "%(title)s.%(ext)s"
|
||||
|
||||
# Download to a specific folder
|
||||
yt-dlp "https://www.instagram.com/reel/XXXX/" \
|
||||
-o "./instagram-downloads/%(uploader)s_%(id)s.%(ext)s"
|
||||
|
||||
# Download best quality
|
||||
yt-dlp -f "bestvideo+bestaudio" "https://www.instagram.com/reel/XXXX/"
|
||||
```
|
||||
|
||||
Claude can run this command via Bash if the user asks. `yt-dlp` handles the auth token extraction automatically for public Reels.
|
||||
|
||||
---
|
||||
|
||||
## Full Script Template
|
||||
|
||||
Claude should offer to write this as a standalone script (`instagram_downloader.py`) that the user can run independently:
|
||||
|
||||
```python
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
Instagram Post Downloader
|
||||
Fetches high-res images from public Instagram posts and carousels.
|
||||
Requires: pip install requests Pillow
|
||||
"""
|
||||
|
||||
import os
|
||||
import re
|
||||
import sys
|
||||
import json
|
||||
import time
|
||||
import requests
|
||||
from datetime import datetime, timezone
|
||||
from pathlib import Path
|
||||
|
||||
try:
|
||||
from PIL import Image
|
||||
PILLOW_AVAILABLE = True
|
||||
except ImportError:
|
||||
PILLOW_AVAILABLE = False
|
||||
print("Warning: Pillow not installed. PDF stitching disabled. Run: pip install Pillow")
|
||||
|
||||
|
||||
HEADERS = {
|
||||
"User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 "
|
||||
"(KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
|
||||
"Accept-Language": "en-US,en;q=0.9",
|
||||
"Referer": "https://www.instagram.com/",
|
||||
}
|
||||
|
||||
|
||||
def extract_shortcode(url: str) -> str:
|
||||
match = re.search(r"instagram\.com/(?:p|reel|tv)/([A-Za-z0-9_-]+)", url)
|
||||
if not match:
|
||||
raise ValueError(f"Cannot extract shortcode from URL: {url}")
|
||||
return match.group(1)
|
||||
|
||||
|
||||
def fetch_post_data(shortcode: str) -> dict:
|
||||
"""Try multiple endpoints to get post JSON data."""
|
||||
# Attempt A: JSON endpoint
|
||||
try:
|
||||
url = f"https://www.instagram.com/p/{shortcode}/?__a=1&__d=dis"
|
||||
r = requests.get(url, headers=HEADERS, timeout=15)
|
||||
if r.status_code == 200:
|
||||
data = r.json()
|
||||
media = (data.get("graphql", {}).get("shortcode_media") or
|
||||
data.get("data", {}).get("shortcode_media"))
|
||||
if media:
|
||||
return media
|
||||
except Exception:
|
||||
pass
|
||||
|
||||
# Attempt B: Embed page
|
||||
try:
|
||||
url = f"https://www.instagram.com/p/{shortcode}/embed/captioned/"
|
||||
r = requests.get(url, headers=HEADERS, timeout=15)
|
||||
html = r.text
|
||||
# Look for JSON blob in script tags
|
||||
matches = re.findall(r'window\.__additionalDataLoaded\([^,]+,(\{.+?\})\);', html)
|
||||
for blob in matches:
|
||||
try:
|
||||
data = json.loads(blob)
|
||||
media = (data.get("graphql", {}).get("shortcode_media") or
|
||||
data.get("data", {}).get("shortcode_media"))
|
||||
if media:
|
||||
return media
|
||||
except json.JSONDecodeError:
|
||||
continue
|
||||
except Exception:
|
||||
pass
|
||||
|
||||
return {}
|
||||
|
||||
|
||||
def get_cdn_urls(media: dict) -> list[tuple[str, str]]:
|
||||
"""Return list of (filename, cdn_url) tuples."""
|
||||
results = []
|
||||
media_type = media.get("__typename", "")
|
||||
|
||||
if media_type == "GraphSidecar":
|
||||
edges = media.get("edge_sidecar_to_children", {}).get("edges", [])
|
||||
for i, edge in enumerate(edges, start=1):
|
||||
node = edge.get("node", {})
|
||||
resources = node.get("display_resources", [])
|
||||
url = (max(resources, key=lambda r: r.get("config_width", 0)).get("src")
|
||||
if resources else node.get("display_url", ""))
|
||||
if url:
|
||||
ext = "jpg" if "jpg" in url.lower() else "webp"
|
||||
filename = f"slide_{i:02d}.{ext}"
|
||||
results.append((filename, url))
|
||||
else:
|
||||
resources = media.get("display_resources", [])
|
||||
url = (max(resources, key=lambda r: r.get("config_width", 0)).get("src")
|
||||
if resources else media.get("display_url", ""))
|
||||
if url:
|
||||
ext = "jpg" if "jpg" in url.lower() else "webp"
|
||||
results.append((f"image.{ext}", url))
|
||||
|
||||
return results
|
||||
|
||||
|
||||
def sanitise_folder_name(caption: str, shortcode: str) -> str:
|
||||
truncated = caption[:40] if caption else ""
|
||||
cleaned = re.sub(r"[^a-zA-Z0-9 \-]", "", truncated)
|
||||
underscored = re.sub(r"[\s\-]+", "_", cleaned).strip("_").lower()
|
||||
return underscored if underscored else shortcode
|
||||
|
||||
|
||||
def download_file(url: str, dest_path: str) -> bool:
|
||||
r = requests.get(url, headers=HEADERS, stream=True, timeout=30)
|
||||
r.raise_for_status()
|
||||
with open(dest_path, "wb") as f:
|
||||
for chunk in r.iter_content(chunk_size=8192):
|
||||
f.write(chunk)
|
||||
return True
|
||||
|
||||
|
||||
def stitch_pdf(image_paths: list[str], output_path: str) -> None:
|
||||
if not PILLOW_AVAILABLE:
|
||||
return
|
||||
images = [Image.open(p).convert("RGB") for p in sorted(image_paths)]
|
||||
if images:
|
||||
images[0].save(output_path, format="PDF", save_all=True,
|
||||
append_images=images[1:], resolution=150.0)
|
||||
|
||||
|
||||
def process_url(post_url: str, base_dir: str, stitch_pdf_flag: bool) -> dict:
|
||||
result = {"url": post_url, "status": "ok", "files": [], "error": None}
|
||||
try:
|
||||
shortcode = extract_shortcode(post_url)
|
||||
media = fetch_post_data(shortcode)
|
||||
|
||||
caption = ""
|
||||
username = ""
|
||||
if media:
|
||||
caption_edges = media.get("edge_media_to_caption", {}).get("edges", [])
|
||||
caption = caption_edges[0]["node"]["text"] if caption_edges else ""
|
||||
owner = media.get("owner", {})
|
||||
username = owner.get("username", "")
|
||||
|
||||
folder_name = sanitise_folder_name(caption, shortcode)
|
||||
post_dir = os.path.join(base_dir, folder_name)
|
||||
if os.path.exists(post_dir):
|
||||
post_dir = f"{post_dir}_{shortcode}"
|
||||
os.makedirs(post_dir, exist_ok=True)
|
||||
|
||||
cdn_urls = get_cdn_urls(media) if media else []
|
||||
if not cdn_urls:
|
||||
# Fallback: oEmbed
|
||||
oembed_url = f"https://api.instagram.com/oembed/?url={post_url}&omitscript=true"
|
||||
r = requests.get(oembed_url, headers=HEADERS, timeout=10)
|
||||
if r.status_code == 200:
|
||||
thumb = r.json().get("thumbnail_url", "")
|
||||
if thumb:
|
||||
cdn_urls = [("image.jpg", thumb)]
|
||||
username = r.json().get("author_name", "")
|
||||
|
||||
downloaded_paths = []
|
||||
cdn_map = {}
|
||||
for filename, url in cdn_urls:
|
||||
dest = os.path.join(post_dir, filename)
|
||||
download_file(url, dest)
|
||||
downloaded_paths.append(dest)
|
||||
cdn_map[filename] = url
|
||||
result["files"].append(filename)
|
||||
|
||||
if stitch_pdf_flag and len(downloaded_paths) > 1 and PILLOW_AVAILABLE:
|
||||
pdf_path = os.path.join(post_dir, "carousel.pdf")
|
||||
stitch_pdf(downloaded_paths, pdf_path)
|
||||
result["files"].append("carousel.pdf")
|
||||
|
||||
post_type = "carousel" if len(cdn_urls) > 1 else "single_image"
|
||||
write_metadata(post_dir, post_url, shortcode, post_type, caption, username, cdn_map)
|
||||
result["files"].append("metadata.txt")
|
||||
|
||||
except Exception as e:
|
||||
result["status"] = "error"
|
||||
result["error"] = str(e)
|
||||
|
||||
return result
|
||||
|
||||
|
||||
def write_metadata(post_dir, post_url, shortcode, post_type, caption, username, cdn_map):
|
||||
lines = [
|
||||
f"Post URL: {post_url}",
|
||||
f"Shortcode: {shortcode}",
|
||||
f"Type: {post_type}",
|
||||
]
|
||||
if post_type == "carousel":
|
||||
lines.append(f"Slide count: {len([k for k in cdn_map if 'slide' in k])}")
|
||||
lines += [
|
||||
f"Caption: {caption}",
|
||||
f"Username: @{username}",
|
||||
f"Fetched at: {datetime.now(timezone.utc).isoformat()}",
|
||||
"CDN URLs:",
|
||||
]
|
||||
for fn, url in cdn_map.items():
|
||||
lines.append(f" {fn:<18} {url}")
|
||||
with open(os.path.join(post_dir, "metadata.txt"), "w", encoding="utf-8") as f:
|
||||
f.write("\n".join(lines) + "\n")
|
||||
|
||||
|
||||
def main(urls: list[str], base_dir: str = "./instagram-downloads", stitch: bool = True):
|
||||
os.makedirs(base_dir, exist_ok=True)
|
||||
results = []
|
||||
for url in urls:
|
||||
url = url.strip()
|
||||
if not url:
|
||||
continue
|
||||
print(f"Processing: {url}")
|
||||
r = process_url(url, base_dir, stitch)
|
||||
results.append(r)
|
||||
time.sleep(1) # polite delay between requests
|
||||
|
||||
# Summary
|
||||
ok = [r for r in results if r["status"] == "ok"]
|
||||
err = [r for r in results if r["status"] == "error"]
|
||||
total_files = sum(len(r["files"]) for r in ok)
|
||||
print("\nInstagram Post Downloader — Batch Complete")
|
||||
print("==========================================")
|
||||
print(f"URLs processed: {len(results)}")
|
||||
print(f"Posts saved: {len(ok)}")
|
||||
print(f"Total files: {total_files}")
|
||||
print(f"Errors: {len(err)}")
|
||||
print(f"Output dir: {os.path.abspath(base_dir)}\n")
|
||||
for r in results:
|
||||
if r["status"] == "ok":
|
||||
print(f" OK {r['url']}")
|
||||
else:
|
||||
print(f" ERR {r['url']} — {r['error']}")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
if len(sys.argv) < 2:
|
||||
print("Usage: python instagram_downloader.py <url1> [url2] ...")
|
||||
sys.exit(1)
|
||||
main(sys.argv[1:])
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
Before marking the task complete, verify each item:
|
||||
|
||||
- [ ] Domain allowlist confirmed — `*.cdninstagram.com` is added before any fetch attempts
|
||||
- [ ] All provided URLs validated as Instagram URLs before processing begins
|
||||
- [ ] CDN URLs are the highest-resolution variants available (largest `config_width` selected)
|
||||
- [ ] Folder name is sanitised — no special characters, no spaces, max 40 chars from caption
|
||||
- [ ] Folder collision handled — shortcode appended if folder already exists
|
||||
- [ ] Carousel slides numbered sequentially with zero-padding (`slide_01`, `slide_02`, ...)
|
||||
- [ ] PDF includes all slides in correct order (not alphabetical — by slide index)
|
||||
- [ ] metadata.txt written to every post folder, including full CDN URLs
|
||||
- [ ] Pillow dependency checked at startup — graceful fallback if not available
|
||||
- [ ] Batch completion summary printed with file counts and any errors
|
||||
- [ ] Private post errors caught and reported — not silently skipped
|
||||
- [ ] Rate limiting handled — at least 1 second delay between requests
|
||||
- [ ] No credential or cookie storage — skill operates on public posts only
|
||||
|
||||
---
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- "Download this Instagram post for me: https://www.instagram.com/p/ABC123/"
|
||||
- "Save that carousel to my downloads folder"
|
||||
- "Can you grab all the slides from this Instagram post and make a PDF?"
|
||||
- "Download these 5 Instagram posts" [followed by list of URLs]
|
||||
- "Archive this IG post before it gets deleted"
|
||||
- "I need the full-res images from this carousel"
|
||||
- "Download the images from this Instagram URL and stitch them into a PDF"
|
||||
- "Batch download these Instagram posts" [followed by URLs]
|
||||
- "Save the slides from this Instagram carousel as individual JPEGs"
|
||||
- "Get me the high-res version of this Instagram image"
|
||||
|
||||
---
|
||||
|
||||
## Notes on Instagram's Anti-Scraping Measures
|
||||
|
||||
Instagram actively changes its page structure and API endpoints. If all three fetch attempts fail:
|
||||
|
||||
1. The embed page method (`/embed/captioned/`) is historically the most stable — start there.
|
||||
2. CDN URLs expire. Download immediately after fetching — do not store URLs and download later.
|
||||
3. Instagram may return a login wall for some posts even if they're technically public. If this happens, the skill cannot proceed without authentication (which is out of scope).
|
||||
4. If Instagram returns a 429, wait 10–30 seconds before retrying. Reduce batch size for large lists.
|
||||
|
||||
This skill is designed for public posts only. It does not support login, sessions, or private content.
|
||||
|
||||
---
|
||||
|
||||
*Originally inspired by a skill from Frank and Diana Dovgopol (Write, Prompt, Scale) — adapted and extended for this library.*
|
||||
@@ -0,0 +1,166 @@
|
||||
---
|
||||
name: notes-humanizer
|
||||
description: Strips AI writing patterns from text and rewrites it to sound genuinely human — not by softening it, but by removing statistical defaults and injecting the specific signals that human writers produce.
|
||||
---
|
||||
|
||||
# Notes Humanizer
|
||||
|
||||
"Humanize this" prompts don't work because they don't know what to remove. AI text has specific, identifiable defaults — em dashes used as parenthetical substitutes, rule-of-three lists where all items have identical rhythm, sentences that hover between 15 and 20 words. Fix those defaults, add the signals human writers actually produce, and the text stops reading as synthetic. This skill does that systematically, in two phases, and shows you exactly what changed and why.
|
||||
|
||||
> Credit: Originally created by Orel (TheIndiepreneur) — adapted and extended for this library.
|
||||
|
||||
---
|
||||
|
||||
## Required Inputs
|
||||
|
||||
| Input | Format | Notes |
|
||||
|---|---|---|
|
||||
| Text to humanize | Paste directly into the chat | Any length. Works on paragraphs, full articles, social posts, emails. |
|
||||
|
||||
No other inputs required. Claude will not ask clarifying questions before starting — it works with what's given.
|
||||
|
||||
---
|
||||
|
||||
## Output Structure
|
||||
|
||||
### Section 1: What Was Found
|
||||
|
||||
A plain-language audit of the AI patterns detected in the original text, before any rewriting:
|
||||
|
||||
```
|
||||
PATTERNS DETECTED
|
||||
─────────────────
|
||||
Em dashes used as parenthetical substitutes: 3
|
||||
Filler openers ("Let's dive in", "It's worth noting", etc.): 2
|
||||
Rule-of-three lists with identical rhythm: 1
|
||||
Sentence length variance: low (avg 17 words, range 14–21)
|
||||
Hedging qualifiers: 4
|
||||
Passive constructions where active is cleaner: 2
|
||||
```
|
||||
|
||||
### Section 2: Side-by-Side Comparison
|
||||
|
||||
| Original | Rewritten |
|
||||
|---|---|
|
||||
| [original paragraph] | [rewritten paragraph] |
|
||||
|
||||
(One row per paragraph or logical block. Short texts get the full comparison in one table. Long texts get the table collapsed to changed sections only, with unchanged sections noted.)
|
||||
|
||||
### Section 3: Change Log
|
||||
|
||||
Every specific change made, with the reason:
|
||||
|
||||
```
|
||||
CHANGES MADE
|
||||
────────────────────────────────────────────────
|
||||
1. Removed em dash in "success — and it shows"
|
||||
→ Rewritten as "success (and it shows)"
|
||||
Why: em dash here is a parenthetical substitute, not a genuine pause
|
||||
|
||||
2. Deleted "It's worth noting that"
|
||||
Why: pure filler — the sentence is stronger without it
|
||||
|
||||
3. Broke rule-of-three list "X, Y, and Z"
|
||||
→ "X and Y. Z is different — [expanded thought]"
|
||||
Why: all three items had identical rhythm; broke the pattern
|
||||
|
||||
4. Added short sentence: "That's the problem."
|
||||
Why: needed a sub-8-word sentence to vary rhythm
|
||||
|
||||
5. Added sentence starting with "But"
|
||||
Why: human writers do this; AI avoids it as a statistical default
|
||||
|
||||
6. Added specific example: [detail added]
|
||||
Why: the original made an abstract claim with no grounding detail
|
||||
|
||||
7. Added aside: "(I've watched this fail three times in a row)"
|
||||
Why: breaks fourth wall slightly; signals genuine perspective
|
||||
```
|
||||
|
||||
### Section 4: Clean Output
|
||||
|
||||
The full rewritten text, ready to copy and paste — no annotations, no formatting artifacts.
|
||||
|
||||
```
|
||||
[Full rewritten text here]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Instructions for Claude
|
||||
|
||||
### Phase 1: Audit
|
||||
|
||||
Read the full text before making any changes. Identify and count every instance of these patterns:
|
||||
|
||||
**Patterns to remove or rewrite:**
|
||||
|
||||
| Pattern | Action |
|
||||
|---|---|
|
||||
| Em dash used as parenthetical substitute (`word — word` where a comma or parenthesis would work) | Replace with parentheses or rewrite the clause |
|
||||
| "Let's dive in" | Delete or replace with a direct first sentence |
|
||||
| "In conclusion" | Delete or rewrite as a genuine closing thought |
|
||||
| "It's worth noting that" | Delete — the sentence stands without it |
|
||||
| "At its core" | Delete or rewrite |
|
||||
| "Game-changer" | Replace with what the thing actually changes |
|
||||
| "Delve" | Replace with look, dig, explore — or rewrite the sentence |
|
||||
| "Navigate" used metaphorically for non-navigation tasks | Replace with a direct verb |
|
||||
| Rule-of-three lists where all three items have identical grammatical structure and similar word count | Break the third item out as its own sentence or expand it |
|
||||
| Sentences where every sentence in a paragraph falls in the 14–22 word range | Deliberately add one very short sentence and one longer one |
|
||||
| "Needless to say" | Delete |
|
||||
| "It's important to note that" | Delete |
|
||||
| Passive constructions where the active form is more direct | Flip to active |
|
||||
|
||||
Do not remove every em dash — only the ones used as parenthetical substitutes. Do not remove all hedging — only empty hedging that adds no information.
|
||||
|
||||
### Phase 2: Inject
|
||||
|
||||
After stripping patterns, add the following signals. Each one should emerge from the actual content — don't add generic filler:
|
||||
|
||||
1. **One genuine opinion or take.** The author appears to actually believe something specific. State it without hedging. ("This approach works, and I think most people underestimate how rarely the alternative does.")
|
||||
|
||||
2. **One specific detail, example, or number.** Ground the most abstract claim in the text with something concrete. If the text says "this happens frequently," add a real or illustrative number. If it says "many companies do this," name the type of company.
|
||||
|
||||
3. **One aside or parenthetical thought that breaks the fourth wall slightly.** This is the signal most synthetic text lacks — the writer momentarily steps out of the formal argument to say something human. ("(I've seen this specific mistake made by people who absolutely should have known better.)")
|
||||
|
||||
4. **At least one sentence under 8 words.** Make it land on a point, not a transition.
|
||||
|
||||
5. **One sentence that starts with "And" or "But."** Place it where the rhythm earns it, not randomly.
|
||||
|
||||
### Phase 3: Report
|
||||
|
||||
Present the output in the four-section structure defined above. The change log must list every individual change — not categories of change, but specific instances. If you changed three em dashes, list all three separately.
|
||||
|
||||
### Handling edge cases
|
||||
|
||||
- **If the text is already mostly clean:** Report what you found (or didn't find), make the few remaining changes, and note explicitly that the original was close. Don't invent problems.
|
||||
- **If the text is very short (under 100 words):** Skip the comparison table. Show original, then rewritten, then change log.
|
||||
- **If the text is over 1,500 words:** Process the full text but collapse the comparison table to changed sections only.
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Audit was completed before rewriting (patterns counted, not just detected)
|
||||
- [ ] Every removed pattern is listed in the change log with a specific reason
|
||||
- [ ] Em dashes were assessed individually — only parenthetical-substitute uses were removed
|
||||
- [ ] Rule-of-three lists: the rhythm was actually checked, not just the fact that there were three items
|
||||
- [ ] At least one sentence under 8 words was added (or was already present)
|
||||
- [ ] At least one sentence starts with "And" or "But" in the final text
|
||||
- [ ] The specific detail or example added connects to an actual claim in the text, not floated in generically
|
||||
- [ ] The aside breaks the fourth wall slightly without being forced or cutesy
|
||||
- [ ] The change log lists specific instances, not categories
|
||||
- [ ] The clean output section has no annotations or formatting artifacts — ready to paste
|
||||
- [ ] If the original was already clean, that was stated explicitly rather than changes invented
|
||||
|
||||
---
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- "Humanize this text: [paste]"
|
||||
- "Use the notes-humanizer skill on this draft"
|
||||
- "This reads like ChatGPT wrote it — fix it: [paste]"
|
||||
- "Strip the AI out of this and make it sound like a real person wrote it"
|
||||
- "Run the humanizer on this LinkedIn post: [paste]"
|
||||
- "This has too many em dashes and rule-of-three lists — clean it up: [paste]"
|
||||
- "Make this email sound less robotic: [paste]"
|
||||
@@ -0,0 +1,176 @@
|
||||
---
|
||||
name: substack-notes-scraper
|
||||
description: Scrapes a Substack Notes page and exports engagement data (likes, comments, restacks) to a formatted .xlsx file with conditional formatting and summary stats.
|
||||
---
|
||||
|
||||
# Substack Notes Scraper
|
||||
|
||||
Substack has no public API for Notes analytics. You can't see likes, comments, and restacks in one place without scrolling through your feed manually. This skill scrapes the rendered Notes page, filters to only your original content, and exports everything to a spreadsheet you can actually analyze.
|
||||
|
||||
> Credit: Originally created by a Substack newsletter author — adapted and extended for this library.
|
||||
|
||||
---
|
||||
|
||||
## Required Inputs
|
||||
|
||||
| Input | Format | Example |
|
||||
|---|---|---|
|
||||
| Notes URL | Full URL to the Notes tab | `https://substack.com/@handle/notes` |
|
||||
| Author handle or name | Exact handle or display name | `@handle` or `Jane Smith` |
|
||||
| Date range | Plain English or explicit range | `last 30 days` or `Jan 2026 – Mar 2026` |
|
||||
|
||||
Claude will ask for these if not provided upfront.
|
||||
|
||||
---
|
||||
|
||||
## Output Structure
|
||||
|
||||
### File
|
||||
|
||||
```
|
||||
substack-notes-[handle]-[YYYY-MM-DD].xlsx
|
||||
```
|
||||
|
||||
### Sheet: "Notes Data"
|
||||
|
||||
| Column | Description |
|
||||
|---|---|
|
||||
| Date | Publication date (YYYY-MM-DD) |
|
||||
| Text Preview | First 200 characters of the note |
|
||||
| Full Text | Complete note text |
|
||||
| Likes | Like count at time of scrape |
|
||||
| Comments | Comment count |
|
||||
| Restacks | Restack count |
|
||||
| Total Engagement | Likes + Comments + Restacks |
|
||||
| Link | Direct URL to the note |
|
||||
| Note Type | `original` or `restack` |
|
||||
|
||||
**Formatting applied:**
|
||||
- Row 1: frozen header row
|
||||
- Auto-filter enabled on all columns
|
||||
- Top 20% by Likes column: highlighted yellow (`#FFF2CC`)
|
||||
- Column widths: auto-fit to content, min 12, max 60
|
||||
|
||||
### Sheet: "Summary"
|
||||
|
||||
```
|
||||
Scrape Date: [YYYY-MM-DD HH:MM UTC]
|
||||
Author: [handle]
|
||||
Date Range: [start] – [end]
|
||||
Total Notes: [n]
|
||||
Original Notes: [n]
|
||||
Restacks Filtered: [n]
|
||||
|
||||
Avg Likes: [n.n]
|
||||
Avg Comments: [n.n]
|
||||
Avg Restacks: [n.n]
|
||||
Avg Total Eng: [n.n]
|
||||
|
||||
Best Note (Likes): [date] — [first 80 chars] — [n] likes
|
||||
Best Note (Eng): [date] — [first 80 chars] — [n] total engagement
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Instructions for Claude
|
||||
|
||||
### Step 1: Validate inputs
|
||||
|
||||
Confirm the three required inputs are present. If any are missing, ask before proceeding. Parse the date range into a concrete start date and end date (convert relative ranges like "last 30 days" to explicit dates using today's date).
|
||||
|
||||
### Step 2: Fetch the Notes page
|
||||
|
||||
Use `WebFetch` to load the Notes URL. Substack Notes pages are JavaScript-rendered — request the full rendered HTML. If WebFetch returns a skeleton page without note content, note this in your response and ask the user to paste the page HTML manually or confirm browser access is available.
|
||||
|
||||
### Step 3: Paginate through all notes in the date window
|
||||
|
||||
Substack Notes load incrementally. Repeat fetching or scrolling until either:
|
||||
- A note's date falls outside the target date range (stop loading more), or
|
||||
- No new content loads on the next request.
|
||||
|
||||
Rate-limit: wait 2 seconds between each paginated request. Do not hammer the endpoint.
|
||||
|
||||
### Step 4: Parse each note
|
||||
|
||||
For every note element found on the page, extract:
|
||||
- **Date**: the timestamp on the note (convert to YYYY-MM-DD)
|
||||
- **Author**: the display name or handle shown on the note
|
||||
- **Full text**: complete body text, stripping HTML tags
|
||||
- **Text preview**: first 200 characters of full text
|
||||
- **Likes count**: the number shown on the like/heart counter
|
||||
- **Comments count**: the number shown on the comment counter
|
||||
- **Restacks count**: the number shown on the restack counter
|
||||
- **Link**: the direct permalink to the note
|
||||
- **Note type**: `original` if the author matches the specified author; `restack` if it belongs to someone else
|
||||
|
||||
### Step 5: Filter
|
||||
|
||||
Keep ALL rows in the data (restacks included as rows with `Note Type = restack`). The Summary sheet stats should count only `original` notes. Mark restacks clearly so the user can filter them out themselves in Excel if preferred.
|
||||
|
||||
Apply date filter: exclude any note outside the specified date range.
|
||||
|
||||
### Step 6: Calculate Total Engagement
|
||||
|
||||
For each row: `Total Engagement = Likes + Comments + Restacks`
|
||||
|
||||
### Step 7: Identify top 20% by Likes
|
||||
|
||||
Sort original notes by Likes descending. Mark the top 20% (round up) for conditional formatting. These rows will be highlighted yellow in the output file.
|
||||
|
||||
### Step 8: Build the .xlsx file
|
||||
|
||||
Use Python with `openpyxl` to generate the file. Structure:
|
||||
|
||||
```python
|
||||
# Required libraries
|
||||
import openpyxl
|
||||
from openpyxl.styles import PatternFill, Font, Alignment
|
||||
from openpyxl.utils import get_column_letter
|
||||
from datetime import datetime
|
||||
|
||||
# Sheet 1: Notes Data
|
||||
# - Write header row, bold, freeze row 1
|
||||
# - Write all data rows
|
||||
# - Apply auto-filter: ws.auto_filter.ref = ws.dimensions
|
||||
# - Apply yellow fill to top-20% rows by likes
|
||||
# - Auto-size columns (iterate cells to find max length)
|
||||
|
||||
# Sheet 2: Summary
|
||||
# - Write summary stats as key-value pairs, no table format
|
||||
```
|
||||
|
||||
Name the file `substack-notes-[handle]-[YYYY-MM-DD].xlsx` using today's date.
|
||||
|
||||
### Step 9: Report back
|
||||
|
||||
After generating the file, report:
|
||||
- File path
|
||||
- Total notes found, original vs. restacks
|
||||
- Date range actually covered
|
||||
- Top 3 notes by total engagement (date + preview + stats)
|
||||
- Any notes or warnings (e.g., page didn't fully load, some dates were ambiguous)
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] All three required inputs were confirmed before starting
|
||||
- [ ] Rate limiting honored: 2-second delay between paginated requests
|
||||
- [ ] Author filter applied correctly — restacks are included as rows but flagged, not silently dropped
|
||||
- [ ] Date range filter applied — no notes outside the window appear in the data
|
||||
- [ ] Total Engagement column is Likes + Comments + Restacks (not hardcoded)
|
||||
- [ ] Top 20% highlight is based on the actual data distribution, not a fixed threshold
|
||||
- [ ] Header row is frozen and auto-filter is active
|
||||
- [ ] Summary sheet stats reference only `original` notes, not restacks
|
||||
- [ ] File is named with the author handle and today's date
|
||||
- [ ] If the page failed to load properly, the user was told — not silently given an empty file
|
||||
|
||||
---
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- "Scrape my Substack Notes and export to Excel — my handle is @handle, last 60 days"
|
||||
- "Use the substack-notes-scraper skill on https://substack.com/@handle/notes for Q1 2026"
|
||||
- "Pull my notes engagement data into a spreadsheet"
|
||||
- "Export my Substack Notes stats with likes and restacks — author: Jane Smith, Jan–Mar 2026"
|
||||
- "Run the Substack scraper on my notes page and show me which posts performed best"
|
||||
@@ -0,0 +1,625 @@
|
||||
---
|
||||
name: thumbnail-creator
|
||||
description: "Generate article or newsletter thumbnail candidates using the Gemini API from inside Claude Code. Claude reads article copy, proposes composition concepts, writes image generation prompts incorporating brand specs, calls Gemini to generate the images, evaluates the results via computer vision, and returns ranked candidates with rationale. Use when asked to create thumbnails, generate cover images, or produce visual candidates for an article or newsletter."
|
||||
---
|
||||
|
||||
# Thumbnail Creator Skill (via Gemini)
|
||||
|
||||
Generates article and newsletter thumbnail candidates by acting as an image-generation agent inside Claude Code. Instead of switching between tools and prompting Gemini's web UI one image at a time, this skill makes Claude do the full loop: read the copy, propose compositions, write tailored prompts, call the Gemini API, evaluate the outputs, and return ranked results with brief rationale.
|
||||
|
||||
The output is production-ready thumbnail candidates you can drop directly into your CMS, newsletter tool, or social scheduler.
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Both of these must be in place before the skill can generate images:
|
||||
|
||||
### 1. Gemini API Key
|
||||
|
||||
Get a free key from [Google AI Studio](https://aistudio.google.com/app/apikey).
|
||||
|
||||
Set it as an environment variable:
|
||||
|
||||
```bash
|
||||
export GEMINI_API_KEY="your-key-here"
|
||||
```
|
||||
|
||||
To persist it across sessions, add to your shell profile (`~/.zshrc` or `~/.bashrc`):
|
||||
|
||||
```bash
|
||||
echo 'export GEMINI_API_KEY="your-key-here"' >> ~/.zshrc
|
||||
source ~/.zshrc
|
||||
```
|
||||
|
||||
Verify it is set:
|
||||
|
||||
```bash
|
||||
echo $GEMINI_API_KEY
|
||||
```
|
||||
|
||||
### 2. generate_image.py Script
|
||||
|
||||
This script must exist at `./generate_image.py` in the project root. The full template is provided in the Script Template section below. Claude will check for it and offer to create it if missing.
|
||||
|
||||
**Python dependencies:**
|
||||
|
||||
```bash
|
||||
pip install google-generativeai Pillow requests
|
||||
```
|
||||
|
||||
Or with uv:
|
||||
|
||||
```bash
|
||||
uv pip install google-generativeai Pillow requests
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Claude will ask for these if not provided:
|
||||
|
||||
| Input | Required | Notes |
|
||||
|---|---|---|
|
||||
| Article copy or URL | Yes | Paste the full article text, or provide a URL to fetch. Used to extract themes, hooks, and key claims for composition. |
|
||||
| Brand colours | Recommended | Hex codes or descriptive names. E.g. `#1A1A2E` (navy), `#E94560` (coral). If not provided, Claude uses clean neutral defaults. |
|
||||
| Fonts / type style | Recommended | E.g. "bold sans-serif", "editorial serif", "Neue Haas Grotesk". Used in prompt to guide text treatment. |
|
||||
| Style reference description | Recommended | E.g. "flat illustration, minimal, like Stripe's marketing site" or "photorealistic, dark background, high contrast". A style image URL can also be provided. |
|
||||
| Output dimensions | No | Defaults to `1792x1024` (landscape, standard article thumbnail). Options: `1024x1024` (square), `1024x1792` (portrait/mobile). |
|
||||
| Number of candidates | No | Defaults to 4. Min 1, max 8 (API limits and cost). |
|
||||
| Article title (if different from H1) | No | Used as the primary text element in image prompts. |
|
||||
| Candidate selection | No | After proposing compositions, Claude asks which to generate. User can say "all" or pick by number. |
|
||||
|
||||
---
|
||||
|
||||
## Output Structure
|
||||
|
||||
### Phase 1 — Composition Proposals (text, before any API calls)
|
||||
|
||||
Claude presents 3-4 composition concepts for user approval. Format:
|
||||
|
||||
```
|
||||
Composition Concepts for: "[Article Title]"
|
||||
|
||||
1. BOLD CLAIM
|
||||
Layout: Full-bleed dark background, large white headline centred,
|
||||
single accent data point (e.g. "3x faster") in brand colour below
|
||||
Mood: High authority, newsletter-style
|
||||
Best for: LinkedIn, Substack headers
|
||||
Rationale: The article's central claim ("X outperforms Y by 3x") is specific
|
||||
enough to anchor the visual — readers stop on data.
|
||||
|
||||
2. CONCEPTUAL OBJECT
|
||||
Layout: Central object illustration (e.g. a broken clock for a time-waste article),
|
||||
title in upper third, minimal texture background
|
||||
Mood: Editorial, Medium-style
|
||||
Best for: Blog header, Medium cover, email preheader
|
||||
Rationale: Gives art directors visual metaphor flexibility; works across sizes.
|
||||
|
||||
3. CONTRAST SPLIT
|
||||
Layout: Left half brand colour, right half white or image,
|
||||
title on colour side, supporting subtext on white side
|
||||
Mood: Clean, professional, startup-brand feel
|
||||
Best for: Newsletter, LinkedIn carousel first slide
|
||||
Rationale: Split layout performs consistently in newsletter A/B tests;
|
||||
text is readable at small sizes.
|
||||
|
||||
4. TYPOGRAPHIC ONLY
|
||||
Layout: No illustration, oversized title treatment,
|
||||
author name in small caps at bottom, thin rule separator
|
||||
Mood: Premium, confident, editorial
|
||||
Best for: Substack, Ghost, high-density email lists
|
||||
Rationale: Works when the brand has strong type identity. Fastest to produce.
|
||||
|
||||
Which compositions do you want generated? (Reply with numbers, e.g. "1, 3" or "all")
|
||||
```
|
||||
|
||||
### Phase 2 — Generated Image Files
|
||||
|
||||
After generation, Claude saves files to `./thumbnails/[article-slug]/`:
|
||||
|
||||
```
|
||||
thumbnails/
|
||||
└── article-slug-from-title/
|
||||
├── candidate_01_bold_claim.png
|
||||
├── candidate_02_conceptual_object.png
|
||||
├── candidate_03_contrast_split.png
|
||||
├── candidate_04_typographic.png
|
||||
└── evaluation_report.md
|
||||
```
|
||||
|
||||
### Phase 3 — Evaluation Summary Table
|
||||
|
||||
Claude evaluates each returned image via computer vision and produces:
|
||||
|
||||
```
|
||||
Thumbnail Evaluation — "[Article Title]"
|
||||
Generated: 2026-05-27 | Model: Gemini Imagen | Dimensions: 1792x1024
|
||||
|
||||
| # | Candidate | Composition | Brand Fit /10 | Text Legibility /10 | Recommendation |
|
||||
|---|---|---|---|---|---|
|
||||
| 1 | candidate_01_bold_claim.png | Bold Claim | 9 | 8 | ★ Top pick — strong data anchor, brand colours correct, title readable at 200px width |
|
||||
| 2 | candidate_02_conceptual_object.png | Conceptual Object | 7 | 9 | Good fallback — legible, clean, but illustration style drifted slightly from brand |
|
||||
| 3 | candidate_03_contrast_split.png | Contrast Split | 8 | 7 | Works well at full size; test at thumbnail size before publishing — right side text tightens |
|
||||
| 4 | candidate_04_typographic.png | Typographic | 9 | 10 | Strongest for email — zero brand drift risk, completely text-based |
|
||||
|
||||
Recommended for web: candidate_01_bold_claim.png
|
||||
Recommended for email/mobile: candidate_04_typographic.png
|
||||
Recommended for social: candidate_03_contrast_split.png
|
||||
|
||||
Files saved to: ./thumbnails/article-slug-from-title/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## How Claude Should Execute This Skill
|
||||
|
||||
### Step 1 — Ingest and analyse the article
|
||||
|
||||
Accept article copy as pasted text or a URL.
|
||||
|
||||
If a URL is provided, fetch the page and extract:
|
||||
- The H1 title
|
||||
- The first 3-5 paragraphs (the hook, central claim, and key points)
|
||||
- Any notable statistics or named frameworks mentioned
|
||||
- The author name (for typographic compositions)
|
||||
|
||||
If text is pasted, read it directly. Focus on:
|
||||
- **The hook:** What is the opening claim or tension?
|
||||
- **The central thesis:** What is the one thing the article argues or teaches?
|
||||
- **Key specifics:** Any numbers, named frameworks, or concrete examples that could anchor a visual
|
||||
- **Tone:** Is this formal/authoritative, conversational/accessible, provocative/challenge-based?
|
||||
|
||||
Summarise these findings internally before proposing compositions — the proposals should feel tailored to this specific article, not generic.
|
||||
|
||||
### Step 2 — Collect brand specs
|
||||
|
||||
Ask the user for brand specs if not provided:
|
||||
|
||||
```
|
||||
To generate on-brand thumbnails, I need a few details:
|
||||
|
||||
1. Brand colours (hex codes or descriptions) — e.g. #1A1A2E, #E94560
|
||||
2. Font style preference — e.g. "bold sans-serif", "editorial serif", "geometric"
|
||||
3. Visual style — e.g. "flat minimal", "photorealistic", "illustrated", "typographic only"
|
||||
4. Any style references — describe a brand or publication whose aesthetic you want to match,
|
||||
or share an image URL
|
||||
|
||||
If you don't have brand specs yet, say "use clean defaults" and I'll use a professional
|
||||
dark-on-white editorial style.
|
||||
```
|
||||
|
||||
If the user says "use clean defaults", apply:
|
||||
- Background: `#FFFFFF` or `#0F0F0F` (dark mode default)
|
||||
- Accent: `#2563EB` (blue)
|
||||
- Font style: bold geometric sans-serif
|
||||
- Style: minimal flat, no textures, high contrast
|
||||
|
||||
### Step 3 — Propose composition concepts
|
||||
|
||||
Write 3-4 composition concepts tailored to the article's tone and content. Each concept must:
|
||||
- Have a name (short, memorable label)
|
||||
- Describe the layout precisely (where title goes, what visual element anchors it, background treatment)
|
||||
- Note the mood and the use case it's best suited for
|
||||
- Include a rationale sentence explaining why this composition fits this specific article
|
||||
|
||||
After presenting the concepts, ask which to generate. Wait for user confirmation before making any API calls.
|
||||
|
||||
### Step 4 — Write Gemini image generation prompts
|
||||
|
||||
For each selected composition, write a detailed image generation prompt. Image generation prompts follow a different grammar than text prompts — they are descriptive, not instructional.
|
||||
|
||||
**Prompt structure:**
|
||||
```
|
||||
[Subject/composition] + [Style] + [Colour palette] + [Mood/lighting] +
|
||||
[Text treatment if any] + [What to avoid]
|
||||
```
|
||||
|
||||
**Example prompt for Bold Claim composition:**
|
||||
```
|
||||
Article thumbnail image. Large bold white sans-serif headline text reading "3x Faster Than
|
||||
Traditional Methods" centred on a deep navy blue background (#1A1A2E). Small coral accent
|
||||
text (#E94560) below reading the subtitle. Minimal flat design, no gradients, no stock photo
|
||||
elements, no people. Clean professional editorial style, high contrast, newsletter header
|
||||
format, 16:9 landscape orientation. The composition is typographic — text is the hero,
|
||||
no illustration required. Avoid: clip art, drop shadows, low contrast, crowded layout.
|
||||
```
|
||||
|
||||
**Prompt rules:**
|
||||
- Include exact hex colours when brand colours are provided
|
||||
- Specify the exact headline text to appear in the image
|
||||
- Name the style explicitly ("flat design", "editorial", "photorealistic") — Gemini responds well to style category names
|
||||
- Add a negative prompt ("Avoid: ...") at the end to reduce drift from brand style
|
||||
- Keep prompts under 300 words — longer prompts do not reliably produce better outputs
|
||||
|
||||
### Step 5 — Check prerequisites and run the generation script
|
||||
|
||||
Before calling the API, verify:
|
||||
|
||||
```bash
|
||||
# Check API key is set
|
||||
echo $GEMINI_API_KEY
|
||||
|
||||
# Check script exists
|
||||
ls -la ./generate_image.py
|
||||
|
||||
# Check dependencies
|
||||
python3 -c "import google.generativeai, PIL, requests; print('Dependencies OK')"
|
||||
```
|
||||
|
||||
If the script is missing, offer to create it using the template in the Script Template section below.
|
||||
|
||||
Run the generation script for each prompt:
|
||||
|
||||
```bash
|
||||
python3 generate_image.py \
|
||||
--prompt "your full prompt here" \
|
||||
--output "./thumbnails/article-slug/candidate_01_bold_claim.png" \
|
||||
--width 1792 \
|
||||
--height 1024
|
||||
```
|
||||
|
||||
Or pass all prompts in a batch config file:
|
||||
|
||||
```bash
|
||||
python3 generate_image.py --config ./thumbnails/article-slug/prompts.json
|
||||
```
|
||||
|
||||
### Step 6 — Evaluate generated images
|
||||
|
||||
After each image is saved, examine it using computer vision. Evaluate on two dimensions:
|
||||
|
||||
**Brand Fit (score /10):**
|
||||
- Are the brand colours correct? (1-2 points each)
|
||||
- Does the style match the requested aesthetic? (2 points)
|
||||
- Is the layout consistent with the composition brief? (2 points)
|
||||
- Are there any AI artefacts, distorted text, or unintended elements? (-1 per issue)
|
||||
|
||||
**Text Legibility (score /10):**
|
||||
- Is the headline text readable at full resolution? (3 points)
|
||||
- Is the headline text readable when the image is scaled to 300px wide (thumbnail size)? (3 points)
|
||||
- Is there sufficient contrast between text and background? (2 points)
|
||||
- Is the text placement within safe zones (not cut off at edges)? (2 points)
|
||||
|
||||
Note: Gemini Imagen sometimes renders text with spelling errors or distorted letterforms. If this happens, note it in the evaluation and suggest the user add the text overlay manually in Canva or Figma.
|
||||
|
||||
### Step 7 — Produce the evaluation report
|
||||
|
||||
Write the evaluation summary table (format shown in Output Structure section) and save it as `evaluation_report.md` in the output folder.
|
||||
|
||||
Include:
|
||||
- One-line rationale for each score
|
||||
- A top pick recommendation per use case (web, email/mobile, social)
|
||||
- Any production notes (e.g. "text rendering is imperfect on candidate_02 — overlay text manually")
|
||||
- The full prompts used, so the user can iterate directly in AI Studio if needed
|
||||
|
||||
### Step 8 — Offer iteration
|
||||
|
||||
After delivering the candidates, offer one iteration pass:
|
||||
|
||||
```
|
||||
Want me to iterate on any of these?
|
||||
|
||||
Options:
|
||||
- Adjust colours or style on a specific candidate
|
||||
- Try a different composition concept
|
||||
- Change the headline text
|
||||
- Rerun with different Gemini parameters (different temperature/seed)
|
||||
- Generate additional variants of the top pick
|
||||
|
||||
Just tell me what to change.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Script Template
|
||||
|
||||
Claude should offer to write this file if `generate_image.py` is not present. This is the canonical template to use.
|
||||
|
||||
```python
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
generate_image.py — Gemini Imagen wrapper for Thumbnail Creator skill.
|
||||
|
||||
Usage:
|
||||
python3 generate_image.py --prompt "..." --output "./out.png" [--width 1792] [--height 1024]
|
||||
python3 generate_image.py --config ./prompts.json
|
||||
|
||||
Config JSON format:
|
||||
[
|
||||
{
|
||||
"prompt": "...",
|
||||
"output": "./thumbnails/slug/candidate_01.png",
|
||||
"width": 1792,
|
||||
"height": 1024
|
||||
}
|
||||
]
|
||||
|
||||
Requirements:
|
||||
pip install google-generativeai Pillow
|
||||
"""
|
||||
|
||||
import os
|
||||
import sys
|
||||
import json
|
||||
import argparse
|
||||
import base64
|
||||
from pathlib import Path
|
||||
|
||||
try:
|
||||
import google.generativeai as genai
|
||||
from google.generativeai import types as genai_types
|
||||
except ImportError:
|
||||
print("ERROR: google-generativeai not installed. Run: pip install google-generativeai")
|
||||
sys.exit(1)
|
||||
|
||||
try:
|
||||
from PIL import Image
|
||||
import io
|
||||
except ImportError:
|
||||
print("ERROR: Pillow not installed. Run: pip install Pillow")
|
||||
sys.exit(1)
|
||||
|
||||
|
||||
def get_api_key() -> str:
|
||||
key = os.environ.get("GEMINI_API_KEY", "")
|
||||
if not key:
|
||||
print("ERROR: GEMINI_API_KEY environment variable is not set.")
|
||||
print("Get a key at: https://aistudio.google.com/app/apikey")
|
||||
print("Then run: export GEMINI_API_KEY='your-key-here'")
|
||||
sys.exit(1)
|
||||
return key
|
||||
|
||||
|
||||
def generate_image(
|
||||
prompt: str,
|
||||
output_path: str,
|
||||
width: int = 1792,
|
||||
height: int = 1024,
|
||||
) -> bool:
|
||||
"""
|
||||
Call Gemini Imagen to generate a single image and save it to output_path.
|
||||
Returns True on success, False on failure.
|
||||
"""
|
||||
api_key = get_api_key()
|
||||
genai.configure(api_key=api_key)
|
||||
|
||||
# Determine aspect ratio from dimensions
|
||||
ratio = width / height
|
||||
if abs(ratio - 16/9) < 0.1:
|
||||
aspect_ratio = "16:9"
|
||||
elif abs(ratio - 1.0) < 0.1:
|
||||
aspect_ratio = "1:1"
|
||||
elif abs(ratio - 9/16) < 0.1:
|
||||
aspect_ratio = "9:16"
|
||||
else:
|
||||
aspect_ratio = "16:9" # default fallback
|
||||
|
||||
try:
|
||||
imagen_model = genai.ImageGenerationModel("imagen-3.0-generate-002")
|
||||
|
||||
result = imagen_model.generate_images(
|
||||
prompt=prompt,
|
||||
number_of_images=1,
|
||||
aspect_ratio=aspect_ratio,
|
||||
safety_filter_level="block_only_high",
|
||||
person_generation="allow_adult",
|
||||
)
|
||||
|
||||
if not result.images:
|
||||
print(f" No images returned for: {output_path}")
|
||||
return False
|
||||
|
||||
image_data = result.images[0]
|
||||
|
||||
# Ensure output directory exists
|
||||
Path(output_path).parent.mkdir(parents=True, exist_ok=True)
|
||||
|
||||
# Save the image
|
||||
if hasattr(image_data, '_image_bytes'):
|
||||
img_bytes = image_data._image_bytes
|
||||
elif hasattr(image_data, 'image'):
|
||||
img_bytes = image_data.image
|
||||
else:
|
||||
# Fallback: try to access raw data
|
||||
img_bytes = bytes(image_data)
|
||||
|
||||
img = Image.open(io.BytesIO(img_bytes))
|
||||
|
||||
# Resize to exact dimensions if needed
|
||||
if img.size != (width, height):
|
||||
img = img.resize((width, height), Image.LANCZOS)
|
||||
|
||||
img.save(output_path, format="PNG", optimize=True)
|
||||
print(f" Saved: {output_path} ({img.size[0]}x{img.size[1]})")
|
||||
return True
|
||||
|
||||
except Exception as e:
|
||||
print(f" ERROR generating image: {e}")
|
||||
return False
|
||||
|
||||
|
||||
def run_from_args():
|
||||
parser = argparse.ArgumentParser(description="Gemini Imagen wrapper for thumbnail generation")
|
||||
parser.add_argument("--prompt", type=str, help="Image generation prompt")
|
||||
parser.add_argument("--output", type=str, help="Output file path (.png)")
|
||||
parser.add_argument("--width", type=int, default=1792, help="Image width in pixels")
|
||||
parser.add_argument("--height", type=int, default=1024, help="Image height in pixels")
|
||||
parser.add_argument("--config", type=str, help="JSON config file with batch of prompts")
|
||||
args = parser.parse_args()
|
||||
|
||||
if args.config:
|
||||
# Batch mode
|
||||
with open(args.config, "r") as f:
|
||||
items = json.load(f)
|
||||
print(f"Batch mode: {len(items)} image(s) to generate")
|
||||
results = []
|
||||
for i, item in enumerate(items, start=1):
|
||||
print(f"\n[{i}/{len(items)}] Generating: {item['output']}")
|
||||
ok = generate_image(
|
||||
prompt=item["prompt"],
|
||||
output_path=item["output"],
|
||||
width=item.get("width", 1792),
|
||||
height=item.get("height", 1024),
|
||||
)
|
||||
results.append({"output": item["output"], "ok": ok})
|
||||
|
||||
print(f"\nBatch complete: {sum(r['ok'] for r in results)}/{len(results)} succeeded")
|
||||
for r in results:
|
||||
status = "OK " if r["ok"] else "ERR"
|
||||
print(f" {status} {r['output']}")
|
||||
|
||||
elif args.prompt and args.output:
|
||||
# Single image mode
|
||||
print(f"Generating: {args.output}")
|
||||
ok = generate_image(
|
||||
prompt=args.prompt,
|
||||
output_path=args.output,
|
||||
width=args.width,
|
||||
height=args.height,
|
||||
)
|
||||
if ok:
|
||||
print("Done.")
|
||||
else:
|
||||
print("Failed.")
|
||||
sys.exit(1)
|
||||
|
||||
else:
|
||||
parser.print_help()
|
||||
sys.exit(1)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
run_from_args()
|
||||
```
|
||||
|
||||
**To create this file from inside Claude Code:**
|
||||
```bash
|
||||
# Claude will write this file if it doesn't exist:
|
||||
ls ./generate_image.py || echo "Script missing — Claude will create it"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Prompt Writing Reference
|
||||
|
||||
Claude should use this reference when writing image generation prompts. These patterns produce the most consistent results with Gemini Imagen.
|
||||
|
||||
### Composition patterns
|
||||
|
||||
| Composition type | Prompt anchor phrase |
|
||||
|---|---|
|
||||
| Text-led, dark background | "Bold white sans-serif headline text on deep [colour] background, minimal flat design" |
|
||||
| Text-led, light background | "High-contrast black headline text on clean white background, editorial layout" |
|
||||
| Object/illustration centred | "Centred [object] illustration, [style], [colour] background, title text in upper third" |
|
||||
| Split layout | "Vertical split: left half [colour], right half white. Headline on left side, supporting text on right" |
|
||||
| Photography style | "Photorealistic [scene description], [mood] lighting, [colour] colour grade, text overlay area at [position]" |
|
||||
|
||||
### Style modifiers that work well with Gemini
|
||||
|
||||
- `flat design, no gradients` — clean vector-style outputs
|
||||
- `editorial magazine style` — sophisticated, typographic
|
||||
- `minimal, lots of whitespace` — reduces visual noise
|
||||
- `high contrast, bold typography` — strong thumbnail legibility
|
||||
- `Bauhaus-inspired` — geometric, structured
|
||||
- `dark mode aesthetic` — dark backgrounds with light text
|
||||
- `startup marketing style` — clean, optimistic, sans-serif
|
||||
|
||||
### Negative prompts (always include)
|
||||
|
||||
Append to every prompt:
|
||||
|
||||
```
|
||||
Avoid: stock photography clichés, clipart, excessive gradients, drop shadows,
|
||||
cluttered layout, lens flares, watermarks, low contrast text, AI artefacts.
|
||||
```
|
||||
|
||||
### Text rendering note
|
||||
|
||||
Gemini Imagen sometimes renders short text phrases accurately and longer headlines poorly. If the article headline is longer than 6 words, consider splitting it in the prompt:
|
||||
|
||||
```
|
||||
Primary headline: "[First 4-5 words]"
|
||||
Secondary text: "[Remaining words]"
|
||||
```
|
||||
|
||||
Or instruct the user to add text overlay manually in Canva after generation if legibility is critical.
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
| Issue | Cause | Fix |
|
||||
|---|---|---|
|
||||
| `GEMINI_API_KEY not set` | Environment variable missing | Run `export GEMINI_API_KEY="your-key"` and retry |
|
||||
| `ModuleNotFoundError: google.generativeai` | Dependency missing | Run `pip install google-generativeai` |
|
||||
| `No images returned` | Safety filter triggered | Revise prompt to remove any ambiguous language; check that the prompt doesn't describe faces, violence, or brand logos |
|
||||
| Generated image has garbled text | Imagen text rendering limitation | Use shorter headline in prompt, or plan to add text overlay in Canva/Figma post-generation |
|
||||
| Image is the wrong size | Aspect ratio mismatch | Confirm `--width` and `--height` args match one of the supported ratios (16:9, 1:1, 9:16) |
|
||||
| `generate_image.py not found` | Script not created yet | Ask Claude to create it using the template above |
|
||||
| API quota exceeded | Free tier limit | Wait or upgrade to Gemini API paid tier |
|
||||
| Style drift from brand | Prompt not specific enough | Add exact hex codes and specific style descriptors; add stronger negative prompt |
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
Before marking the task complete, verify each item:
|
||||
|
||||
- [ ] `GEMINI_API_KEY` environment variable confirmed set before any API calls
|
||||
- [ ] `generate_image.py` script exists in project root — created from template if missing
|
||||
- [ ] All Python dependencies installed and verified (`google-generativeai`, `Pillow`)
|
||||
- [ ] Composition proposals were presented and user confirmed which to generate before any API calls
|
||||
- [ ] Each composition proposal is specific to this article's content — not generic placeholders
|
||||
- [ ] Brand colours (hex codes) are included in the image generation prompts
|
||||
- [ ] Negative prompt appended to every image generation prompt
|
||||
- [ ] Headline text in prompts is 6 words or fewer per text element (longer headlines split or noted as overlay candidates)
|
||||
- [ ] Output folder created at `./thumbnails/[article-slug]/` with correct slug derived from article title
|
||||
- [ ] Files named with candidate number and composition name (`candidate_01_bold_claim.png`)
|
||||
- [ ] Each generated image evaluated via computer vision — not assumed to be correct
|
||||
- [ ] Brand Fit and Text Legibility scores are specific and justified, not round numbers
|
||||
- [ ] Any text rendering issues noted in evaluation with "add text overlay manually" recommendation
|
||||
- [ ] Evaluation report saved as `evaluation_report.md` in the output folder
|
||||
- [ ] At least one recommendation given per use case: web, email/mobile, social
|
||||
- [ ] Full prompts used are included in the evaluation report for user iteration reference
|
||||
- [ ] Iteration offer made after delivering results
|
||||
|
||||
---
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- "Create thumbnails for this article"
|
||||
- "Generate cover image candidates for my newsletter"
|
||||
- "Make me 4 thumbnail options for this post"
|
||||
- "Can you generate some thumbnail ideas using Gemini?"
|
||||
- "I need a featured image for this article — use my brand colours"
|
||||
- "Create a thumbnail for this piece using Gemini" [followed by article text or URL]
|
||||
- "Generate article cover images for these brand specs: [colours, style]"
|
||||
- "Make thumbnail candidates and rank them"
|
||||
- "I need newsletter header images — here's the copy"
|
||||
- "Generate and evaluate thumbnail options for this draft"
|
||||
- "Use Gemini to create cover image options"
|
||||
- "Thumbnail this article" [followed by article text]
|
||||
- "Create 3 thumbnail compositions and pick the best one"
|
||||
|
||||
---
|
||||
|
||||
## Cost and Rate Limits
|
||||
|
||||
**Gemini AI Studio free tier (as of early 2026):**
|
||||
- Imagen 3: 10 images per day (free)
|
||||
- Rate limit: varies by region and account tier
|
||||
|
||||
**Paid tier:**
|
||||
- Imagen 3 pricing: approximately $0.03-0.05 per image (check current Google Cloud pricing)
|
||||
- For a typical session generating 4-8 candidates, total cost is under $0.40
|
||||
|
||||
**Recommendation:**
|
||||
- Use the free tier for exploration and iteration
|
||||
- Generate final production candidates on paid tier for higher daily limits
|
||||
- For newsletter teams generating thumbnails weekly, the paid tier is more practical
|
||||
|
||||
---
|
||||
|
||||
*Originally created by Karen Spinner (Wondering About AI) — adapted and extended for this library.*
|
||||
@@ -0,0 +1,256 @@
|
||||
---
|
||||
name: 360-feedback-template
|
||||
description: "Design a 360-degree feedback survey or write a structured 360 feedback report. Use when asked to build a 360 feedback process, write 360 feedback for a colleague, design a feedback survey, or produce a feedback report. Produces either a complete survey instrument with rating scales and open-ended questions, or a structured narrative feedback report with themes, strengths, and development areas."
|
||||
---
|
||||
|
||||
# 360-Degree Feedback Template Skill
|
||||
|
||||
This skill produces two outputs depending on what the user needs: (1) a complete 360 survey instrument for gathering feedback, or (2) a structured 360 feedback report written from gathered notes. Both outputs follow best practice: behaviourally anchored ratings, specific examples, and development-oriented framing.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask the user which output they need, then gather inputs:
|
||||
|
||||
**For a survey instrument:**
|
||||
- **Role being reviewed** (job title and level)
|
||||
- **Competencies to assess** (or use defaults below)
|
||||
- **Reviewer relationships** (peer / direct report / manager / cross-functional)
|
||||
- **Rating scale preference** (1–5 / 1–4 / frequency-based)
|
||||
- **Anonymity level** (fully anonymous / attributed / confidential aggregated)
|
||||
|
||||
**For a feedback report:**
|
||||
- **Person being reviewed** (role and level)
|
||||
- **Feedback notes or raw themes** from reviewers (paste what you have)
|
||||
- **Reviewer relationships** (how many peers, direct reports, managers responded)
|
||||
- **Any context** — performance cycle, specific behaviours to address, promotion consideration
|
||||
|
||||
---
|
||||
|
||||
## Output A: 360 Survey Instrument
|
||||
|
||||
---
|
||||
|
||||
# 360 Feedback Survey: [Role / Level]
|
||||
|
||||
**Purpose:** This survey helps [Name / "the reviewee"] understand how their behaviours and impact are perceived by the people they work with most closely. Responses [are / are not] anonymous. Results will be shared as [individual responses / aggregated themes].
|
||||
|
||||
**Instructions:** For each statement, rate how frequently you observe this behaviour. Add specific examples in the open-ended sections — these are the most valuable part of the survey.
|
||||
|
||||
**Rating scale:**
|
||||
- **5 — Consistently:** Almost always demonstrates this behaviour, even in difficult situations
|
||||
- **4 — Usually:** Demonstrates this behaviour more often than not
|
||||
- **3 — Sometimes:** Demonstrates this behaviour inconsistently
|
||||
- **2 — Rarely:** Seldom demonstrates this behaviour
|
||||
- **1 — Not observed:** Have not had the opportunity to observe this behaviour
|
||||
|
||||
---
|
||||
|
||||
### Section 1: Delivery & Execution
|
||||
|
||||
| Statement | Rating (1–5) |
|
||||
|---|---|
|
||||
| Delivers work on time and to the expected quality | |
|
||||
| Proactively flags risks and blockers before they become problems | |
|
||||
| Follows through on commitments without needing to be chased | |
|
||||
| Manages their workload effectively without compromising quality | |
|
||||
| Adapts quickly when priorities or requirements change | |
|
||||
|
||||
**Open question:** Describe a specific time when [Name] handled a delivery challenge particularly well or poorly.
|
||||
|
||||
---
|
||||
|
||||
### Section 2: Communication & Collaboration
|
||||
|
||||
| Statement | Rating (1–5) |
|
||||
|---|---|
|
||||
| Communicates clearly and concisely in both written and verbal formats | |
|
||||
| Listens actively and considers others' input before responding | |
|
||||
| Keeps the right people informed without over-communicating | |
|
||||
| Resolves disagreements constructively and without defensiveness | |
|
||||
| Makes it easy for others to collaborate with them | |
|
||||
|
||||
**Open question:** Give an example of how [Name] handled a difficult or high-stakes communication.
|
||||
|
||||
---
|
||||
|
||||
### Section 3: Leadership & Influence
|
||||
|
||||
| Statement | Rating (1–5) |
|
||||
|---|---|
|
||||
| Sets a clear direction that others can follow | |
|
||||
| Builds confidence and capability in people around them | |
|
||||
| Influences decisions without relying on authority | |
|
||||
| Gives clear, constructive feedback that helps others improve | |
|
||||
| Creates an environment where people feel safe to raise concerns | |
|
||||
|
||||
**Open question:** Describe a situation where [Name]'s leadership had a notable positive or negative impact on the team.
|
||||
|
||||
---
|
||||
|
||||
### Section 4: Strategic Thinking
|
||||
|
||||
| Statement | Rating (1–5) |
|
||||
|---|---|
|
||||
| Understands the broader business context, not just their immediate work | |
|
||||
| Makes connections between their work and organisational goals | |
|
||||
| Thinks ahead and anticipates second-order consequences | |
|
||||
| Brings original ideas or new approaches to problems | |
|
||||
| Balances short-term needs with longer-term thinking | |
|
||||
|
||||
**Open question:** Give an example of [Name] demonstrating (or missing) strategic thinking.
|
||||
|
||||
---
|
||||
|
||||
### Section 5: Culture & Values
|
||||
|
||||
| Statement | Rating (1–5) |
|
||||
|---|---|
|
||||
| Treats everyone with respect, regardless of level or background | |
|
||||
| Is someone people trust and can rely on | |
|
||||
| Gives credit to others and shares the spotlight | |
|
||||
| Takes responsibility for mistakes without placing blame | |
|
||||
| Contributes positively to team morale, especially under pressure | |
|
||||
|
||||
**Open question:** How does [Name] embody (or not embody) the team's values in practice?
|
||||
|
||||
---
|
||||
|
||||
### Section 6: Overall & Development
|
||||
|
||||
**Open questions (all reviewers):**
|
||||
|
||||
1. What is [Name]'s single most important strength? Give a specific example.
|
||||
|
||||
2. What is the one behaviour or habit that, if changed, would most increase [Name]'s effectiveness?
|
||||
|
||||
3. Is there anything else you want [Name] to know? (This response will be shared directly.)
|
||||
|
||||
---
|
||||
|
||||
## Output B: 360 Feedback Report
|
||||
|
||||
---
|
||||
|
||||
# 360 Feedback Report: [Name] — [Role]
|
||||
|
||||
**Review cycle:** [Quarter / Year / Promotion cycle]
|
||||
**Responses received:** [X total — X peers, X direct reports, X managers, X cross-functional]
|
||||
**Report prepared by:** [HR / People team / Manager / Coach]
|
||||
**Date:** [Date]
|
||||
|
||||
> This report synthesises feedback from [X] reviewers. Open-ended responses have been lightly edited for clarity; no individual response is attributed to protect reviewer confidentiality. Direct quotes marked in *italics* appear verbatim.
|
||||
|
||||
---
|
||||
|
||||
### Executive Summary
|
||||
|
||||
[3–4 sentences. State the overall picture: what is this person known for, what is working well, and what one or two areas are the consistent development themes. Balanced, honest, and grounded in the data — not a sanitised summary.]
|
||||
|
||||
**Overall rating:** [X.X / 5.0 — above average / at level / below expectations for level]
|
||||
|
||||
---
|
||||
|
||||
### Strengths: What to Build On
|
||||
|
||||
**Theme 1: [Strength — e.g. Reliability and follow-through]**
|
||||
|
||||
[2–3 sentences synthesising the feedback evidence for this strength. Reference how many reviewers noted it and in what contexts.]
|
||||
|
||||
*"[Direct quote from reviewer that best illustrates this theme]"*
|
||||
|
||||
---
|
||||
|
||||
**Theme 2: [Strength — e.g. Collaborative problem-solving]**
|
||||
|
||||
[2–3 sentences synthesising evidence.]
|
||||
|
||||
*"[Direct quote]"*
|
||||
|
||||
---
|
||||
|
||||
**Theme 3: [Strength — e.g. Clear communication under pressure]**
|
||||
|
||||
[2–3 sentences synthesising evidence.]
|
||||
|
||||
*"[Direct quote]"*
|
||||
|
||||
---
|
||||
|
||||
### Development Areas: What to Work On
|
||||
|
||||
**Theme 1: [Development area — e.g. Giving timely upward feedback]**
|
||||
|
||||
[2–3 sentences describing the behaviour pattern observed, what impact it has, and what different looks like. Non-blaming and specific.]
|
||||
|
||||
*"[Direct quote that captures the theme]"*
|
||||
|
||||
**Suggested actions:**
|
||||
- [Specific, observable behaviour change — e.g. In the next team meeting where you disagree with a decision, name your concern in the meeting rather than after it]
|
||||
- [Development resource or practice — e.g. Try the "I notice / I wonder / I suggest" framework for giving difficult feedback]
|
||||
|
||||
---
|
||||
|
||||
**Theme 2: [Development area — e.g. Strategic communication to leadership]**
|
||||
|
||||
[2–3 sentences.]
|
||||
|
||||
*"[Direct quote]"*
|
||||
|
||||
**Suggested actions:**
|
||||
- [...]
|
||||
- [...]
|
||||
|
||||
---
|
||||
|
||||
### Ratings Summary
|
||||
|
||||
| Competency | Average score | Range | Notable pattern |
|
||||
|---|---|---|---|
|
||||
| Delivery & Execution | [X.X] | [X–X] | [e.g. Consistently high; one outlier] |
|
||||
| Communication & Collaboration | [X.X] | [X–X] | [e.g. Peers score higher than direct reports] |
|
||||
| Leadership & Influence | [X.X] | [X–X] | [...] |
|
||||
| Strategic Thinking | [X.X] | [X–X] | [...] |
|
||||
| Culture & Values | [X.X] | [X–X] | [...] |
|
||||
| **Overall** | **[X.X]** | [X–X] | |
|
||||
|
||||
**Score variance:** [Is there high agreement or wide spread across reviewers? High variance suggests the behaviour is context-dependent — explore when and with whom.]
|
||||
|
||||
---
|
||||
|
||||
### Direct Message from Reviewers
|
||||
|
||||
[Include up to 3 unedited quotes from the "Is there anything else you want [Name] to know?" question. These are shared verbatim as agreed in the survey instructions.]
|
||||
|
||||
*"[Quote 1]"*
|
||||
|
||||
*"[Quote 2]"*
|
||||
|
||||
*"[Quote 3]"*
|
||||
|
||||
---
|
||||
|
||||
### Recommended Focus for the Next 90 Days
|
||||
|
||||
[1–2 specific, measurable development commitments. Written to be agreed in the feedback conversation — not prescriptive.]
|
||||
|
||||
1. **[Behaviour to change]:** [What does success look like at 90 days? How will we measure it?]
|
||||
2. **[Skill to build]:** [What specific resource, practice, or support will help? Who will observe progress?]
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Survey questions are behaviourally anchored — they describe observable actions, not attitudes
|
||||
- [ ] Open-ended questions ask for specific examples — not general impressions
|
||||
- [ ] Report strengths are backed by specific evidence, not generic praise
|
||||
- [ ] Development areas name the behaviour and its impact — not the person's character
|
||||
- [ ] Suggested actions are specific enough that the reviewee knows exactly what to do differently on Monday
|
||||
- [ ] Direct quotes are genuinely direct — not paraphrased into blandness
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- "Build a 360 feedback survey for a [role] at senior level"
|
||||
- "Write a 360 feedback report from these notes: [paste notes]"
|
||||
- "Design a 360 review template for engineering managers"
|
||||
- "Help me write constructive 360 feedback for my colleague [Name]"
|
||||
- "Create a peer feedback survey for our upcoming performance cycle"
|
||||
@@ -0,0 +1,531 @@
|
||||
---
|
||||
name: aeo-optimizer
|
||||
description: "Optimize an article for Answer Engine Optimization (AEO) — restructuring content so AI engines like ChatGPT, Perplexity, and Claude can extract, quote, and cite it. Rewrites headings as questions, drops 50-80 word answer capsules, audits paragraph length, and flags trust signals. Use when asked to AEO-optimize, make content AI-readable, improve AI citation chances, or adapt an article for answer engines."
|
||||
---
|
||||
|
||||
# AEO Optimizer Skill
|
||||
|
||||
AEO — Answer Engine Optimization — is the discipline of structuring content so that AI engines (ChatGPT, Perplexity, Claude, Gemini) can extract clean, quotable answers and confidently cite your content as a source.
|
||||
|
||||
Most articles are written for humans who scroll, skim, and click. AI engines don't scroll — they scan for extractable answer units. They look for short, self-contained answer blocks sitting directly beneath a clear question heading. If they can't find those, they either skip the content or paraphrase it poorly. This skill fixes that.
|
||||
|
||||
---
|
||||
|
||||
## The AEO Problem
|
||||
|
||||
Here is what AI engines are scanning for, and what most articles fail to provide:
|
||||
|
||||
| What AI engines want | What most articles deliver |
|
||||
|---|---|
|
||||
| H2 = a direct question ("What is X?") | H2 = a vague topic label ("About X" or "Understanding X") |
|
||||
| 50-80 word answer capsule immediately under the heading | Long intro paragraphs before the actual answer |
|
||||
| No links inside the answer block | Inline links that break extractability |
|
||||
| ≤3 sentences per paragraph | Dense 6-8 sentence paragraphs |
|
||||
| Named frameworks, original data, first-person experience | Generic statements with no attribution or specificity |
|
||||
| Consistent question-answer-expand structure throughout | Inconsistent structure that varies section by section |
|
||||
|
||||
When an AI engine cannot cleanly extract a 50-80 word answer, it either skips the article or provides a vague paraphrase without a citation link. AEO optimization removes those barriers.
|
||||
|
||||
---
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Claude will ask for these if not provided:
|
||||
|
||||
| Input | Required | Notes |
|
||||
|---|---|---|
|
||||
| Article content | Yes | Paste the full draft text, or provide a URL Claude can fetch |
|
||||
| Target audience | No | Helps calibrate question phrasing — e.g. "beginner founders" vs "senior engineers" |
|
||||
| Primary keyword or topic | No | If provided, Claude ensures H2 questions cover it directly |
|
||||
| Existing URL (if published) | No | Used in the audit report to note the live page |
|
||||
| Preserve exact section order | No | Defaults to yes — Claude rewrites in place, doesn't restructure |
|
||||
|
||||
If providing a URL instead of pasted text, Claude will fetch the page content. Note: paywalled or JavaScript-rendered articles may require manual paste.
|
||||
|
||||
---
|
||||
|
||||
## Output Structure
|
||||
|
||||
Claude produces two deliverables in sequence:
|
||||
|
||||
### Deliverable 1 — AEO-Ready Article
|
||||
|
||||
The full rewritten article with:
|
||||
- All H2s rewritten as direct questions
|
||||
- 50-80 word answer capsule inserted directly beneath each H2
|
||||
- Paragraphs trimmed to ≤3 sentences where they exceeded that
|
||||
- Trust signals preserved and lightly emphasized
|
||||
- No links inside any answer capsule
|
||||
- Original voice and structure maintained — this is an optimization, not a rewrite
|
||||
|
||||
**Format:**
|
||||
|
||||
```markdown
|
||||
# [Original H1 title — unchanged unless it needs question format]
|
||||
|
||||
[Introduction — keep as-is or trim to ≤3 sentences. Add a "What this covers:" summary if intro is >150 words.]
|
||||
|
||||
## [H2 rewritten as a direct question?]
|
||||
|
||||
[Answer capsule — 50-80 words, no links, self-contained, answers the question completely on its own.]
|
||||
|
||||
[Rest of the section body — expanded explanation, examples, data, links allowed here]
|
||||
|
||||
## [Next H2 as a direct question?]
|
||||
|
||||
[Answer capsule — 50-80 words, no links]
|
||||
|
||||
[Section body]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Deliverable 2 — AEO Audit Report
|
||||
|
||||
Structured report showing all changes made and signals identified.
|
||||
|
||||
**Format:**
|
||||
|
||||
---
|
||||
|
||||
## AEO Audit Report
|
||||
|
||||
**Article:** [Title]
|
||||
**URL:** [If provided]
|
||||
**Audit date:** [Today's date]
|
||||
**AEO readiness score (before):** [X/10]
|
||||
**AEO readiness score (after):** [X/10]
|
||||
|
||||
---
|
||||
|
||||
### Heading Rewrites
|
||||
|
||||
| Original H2 | Rewritten H2 | Change type |
|
||||
|---|---|---|
|
||||
| Understanding Content Strategy | What is content strategy and why does it matter? | Topic label → direct question |
|
||||
| The Benefits of X | What are the main benefits of X? | Vague noun phrase → question |
|
||||
| How We Do It at [Company] | How does [Company] approach X? | First-person → question format |
|
||||
|
||||
---
|
||||
|
||||
### Answer Capsule Placements
|
||||
|
||||
For each section, confirm capsule word count is within 50-80 words:
|
||||
|
||||
| Section | Capsule word count | Links removed from capsule | Status |
|
||||
|---|---|---|---|
|
||||
| What is content strategy...? | 64 words | 2 links removed | OK |
|
||||
| How do you build a content calendar? | 71 words | 0 links (none were present) | OK |
|
||||
| What tools do content teams use? | 58 words | 1 link removed | OK |
|
||||
|
||||
---
|
||||
|
||||
### Paragraph Length Audit
|
||||
|
||||
| Section | Original max paragraph (sentences) | Action taken |
|
||||
|---|---|---|
|
||||
| Introduction | 6 sentences | Split into 2 paragraphs |
|
||||
| Section 2 body | 4 sentences | Trimmed to 3 |
|
||||
| Section 4 body | 2 sentences | No change needed |
|
||||
|
||||
**Paragraphs flagged as too long (before optimization):** [N]
|
||||
**Paragraphs within ≤3 sentences (after optimization):** [all]
|
||||
|
||||
---
|
||||
|
||||
### Trust Signal Inventory
|
||||
|
||||
Trust signals are the elements AI engines treat as credibility markers — original data, named frameworks, first-person experience, and specific attributions. These make AI engines more likely to cite rather than paraphrase.
|
||||
|
||||
| Signal type | Found in article | Example | AEO value |
|
||||
|---|---|---|---|
|
||||
| Original data / research | Yes | "Our analysis of 400 posts showed..." | High — cite-worthy claim |
|
||||
| Named framework | Yes | "The RICE scoring model" | High — search anchor |
|
||||
| First-person experience | Yes | "After running 3 content audits..." | Medium — authority signal |
|
||||
| Named expert / quote | No | — | Recommend adding |
|
||||
| Specific numbers / stats | Yes | "34% increase in organic traffic" | High — extractable fact |
|
||||
| Date-stamped content | No | — | Recommend adding publication date |
|
||||
| Case study reference | Yes | "At Acme Corp, we ran..." | High — concrete example |
|
||||
|
||||
**Trust signals present:** [N]
|
||||
**Recommended additions:** [list any gaps]
|
||||
|
||||
---
|
||||
|
||||
### AEO Scoring Rubric
|
||||
|
||||
| Criterion | Before | After |
|
||||
|---|---|---|
|
||||
| H2s as direct questions (% of total) | [X%] | [X%] |
|
||||
| Answer capsule present under each H2 | No | Yes |
|
||||
| Capsules within 50-80 words | N/A | [X/N sections] |
|
||||
| No links inside capsules | N/A | Yes |
|
||||
| Paragraphs ≤3 sentences | [X%] | [X%] |
|
||||
| Trust signals present | [N] | [N] |
|
||||
| **Total score** | **[X/10]** | **[X/10]** |
|
||||
|
||||
---
|
||||
|
||||
### Recommended Next Steps
|
||||
|
||||
1. [Any remaining gaps — e.g. "Section 4 capsule is 88 words — trim by 10"]
|
||||
2. [Structural suggestions — e.g. "Add a FAQ section at the end for high-volume PAA questions"]
|
||||
3. [Missing trust signals — e.g. "Add a publication date and last-updated date for freshness signals"]
|
||||
4. [Schema markup suggestion if applicable — FAQ schema, HowTo schema, etc.]
|
||||
|
||||
---
|
||||
|
||||
*End of AEO Audit Report*
|
||||
|
||||
---
|
||||
|
||||
## How Claude Should Execute This Skill
|
||||
|
||||
### Step 1 — Ingest the article
|
||||
|
||||
Accept the content as either:
|
||||
- **Pasted text:** Treat as-is. Do not attempt to fetch a URL if text is pasted.
|
||||
- **URL:** Fetch the page. Extract the main article body — ignore nav, sidebars, footers, and ad blocks. If the page is JavaScript-rendered and fetch returns only a shell, ask the user to paste the text instead.
|
||||
|
||||
Count the headings. Note the number of H2s, H3s, and H1s. This sets expectations for how many capsules will be written.
|
||||
|
||||
### Step 2 — Assess AEO readiness before touching anything
|
||||
|
||||
Before rewriting, score the article on the AEO rubric (see Deliverable 2 scoring table). This gives the user a before/after comparison and helps Claude identify where to focus effort.
|
||||
|
||||
Run through each criterion and note the count:
|
||||
- How many H2s are already in question format? (count ones that end with "?")
|
||||
- Does any section already have a 50-80 word self-contained answer block?
|
||||
- What is the average and maximum paragraph length in sentences?
|
||||
- How many trust signals are present? (scan for numbers, named frameworks, first-person phrases, quotes)
|
||||
|
||||
Record the before scores. Do not round up — be honest.
|
||||
|
||||
### Step 3 — Rewrite H2 headings as questions
|
||||
|
||||
For each H2 in the article, rewrite it as a direct question that a real person would ask an AI engine. Guidelines:
|
||||
|
||||
**The question must:**
|
||||
- Be specific enough that the answer could stand alone as a snippet
|
||||
- Use "What", "How", "Why", "When", "Which", or "Who" — not vague gerunds ("Understanding", "Exploring", "Unpacking")
|
||||
- Match the search intent of the original section, not just rephrase it generically
|
||||
- Be 8 words or fewer when possible (longer questions are harder for AI engines to match)
|
||||
|
||||
**Examples of heading transformations:**
|
||||
|
||||
| Before | After |
|
||||
|---|---|
|
||||
| Introduction to Agile | What is Agile methodology? |
|
||||
| Why We Built This | Why did [Company] build [product]? |
|
||||
| The Case for Async Work | Why do distributed teams choose async work? |
|
||||
| Benefits | What are the main benefits of X? |
|
||||
| Tools and Resources | Which tools do [audience] use for X? |
|
||||
| Getting Started | How do you get started with X? |
|
||||
| Common Mistakes | What mistakes do beginners make with X? |
|
||||
| Our Approach | How does [Company/author] approach X? |
|
||||
|
||||
Do not rewrite H3s unless the user requests it. H3s can stay as labels — AI engines primarily anchor on H2s.
|
||||
|
||||
Do not change the H1. The H1 is the article title and SEO title — it follows different rules.
|
||||
|
||||
### Step 4 — Write answer capsules
|
||||
|
||||
For each H2, write a 50-80 word answer capsule to be inserted immediately after the heading and before any existing body text.
|
||||
|
||||
**Capsule rules:**
|
||||
- Must be self-contained — someone reading only the heading + capsule should have a complete, useful answer
|
||||
- No links of any kind inside the capsule (links break AI extractability)
|
||||
- No hedging phrases ("It depends", "There are many factors") — commit to the answer
|
||||
- Use the same voice and terminology as the article — do not change the author's perspective
|
||||
- If the section has an existing strong first paragraph that is already 50-80 words and self-contained, use it as the capsule with minimal edits rather than writing a new one
|
||||
- Count words precisely — under 50 is too thin, over 80 and AI engines may not extract it cleanly
|
||||
|
||||
**Capsule structure options:**
|
||||
|
||||
Option A — Definition then application:
|
||||
```
|
||||
[Concise definition of the concept in 1-2 sentences.] [How it applies in practice, with one specific example or number.] [Why it matters for the reader's situation.]
|
||||
```
|
||||
|
||||
Option B — Direct answer then context:
|
||||
```
|
||||
[Direct answer to the heading question in 1 sentence.] [2-3 sentences of supporting context, specifics, or mechanism.] [Optional: one concrete example or stat.]
|
||||
```
|
||||
|
||||
Option C — How-to opener:
|
||||
```
|
||||
[State the outcome in 1 sentence.] [Steps 1, 2, 3 in compressed form.] [Note on when this applies or what to watch for.]
|
||||
```
|
||||
|
||||
Mark each capsule clearly with an HTML comment so the author knows it was added:
|
||||
```html
|
||||
<!-- AEO Answer Capsule — 64 words -->
|
||||
[capsule text]
|
||||
<!-- End AEO Capsule -->
|
||||
```
|
||||
|
||||
### Step 5 — Audit and trim paragraph length
|
||||
|
||||
Scan every paragraph in the body sections (not the capsules). If a paragraph exceeds 3 sentences:
|
||||
- Split it into two paragraphs at the most natural break
|
||||
- Do not summarise or remove content — just add a paragraph break
|
||||
- If a paragraph is a list in disguise (long run-on sentence with "and", "then", "also"), convert it to a bullet list instead
|
||||
|
||||
Note every change in the audit report's paragraph length table.
|
||||
|
||||
### Step 6 — Identify and flag trust signals
|
||||
|
||||
Scan the full article for trust signals. Do not add trust signals — only identify what exists and flag gaps. Trust signals are:
|
||||
|
||||
| Signal type | What to look for |
|
||||
|---|---|
|
||||
| Original data | "Our data shows", "We analysed X", "In our survey of N..." |
|
||||
| Named frameworks | Any named methodology, model, or system (RICE, Jobs-to-be-Done, etc.) |
|
||||
| First-person experience | "I found", "We ran", "When I built", "After testing..." |
|
||||
| Specific numbers | Percentages, counts, timeframes, dollar amounts |
|
||||
| Expert quotes | Direct quotes attributed to a named person |
|
||||
| Case studies | Named company or project with specific outcomes |
|
||||
| Publication freshness | A visible publish or update date |
|
||||
|
||||
Flag any category with zero signals as a gap. Include specific recommendations for what could be added (e.g. "Add a statistic to the intro — even a well-known industry stat cited correctly adds credibility").
|
||||
|
||||
### Step 7 — Assemble the output
|
||||
|
||||
Produce the two deliverables in this order:
|
||||
|
||||
1. First: the full AEO-ready article. Use the original markdown structure with the changes applied. Make sure capsules have the HTML comment markers.
|
||||
2. Second: the AEO Audit Report, using the exact table structure from the Output Structure section above.
|
||||
|
||||
Separate the two deliverables with a clear horizontal rule (`---`) and a heading (`## AEO Audit Report`).
|
||||
|
||||
### Step 8 — Optional: FAQ section recommendation
|
||||
|
||||
If the article does not already have a FAQ section, and the topic has obvious high-volume PAA (People Also Ask) questions, recommend adding one. Provide 3-5 suggested FAQ questions in question format with brief capsule answers. Note that FAQ sections with proper schema markup (`FAQPage` JSON-LD) get preferential treatment in both traditional SEO and AI engine extraction.
|
||||
|
||||
---
|
||||
|
||||
## AEO Reference: What Makes a Good Answer Capsule
|
||||
|
||||
This section is reference material — Claude should use it when evaluating capsule quality.
|
||||
|
||||
**Strong capsule (62 words):**
|
||||
> Content strategy is the planning and management of content to achieve specific business goals. It defines what to publish, for whom, through which channels, and how often. A strong content strategy starts with audience research, maps content to stages of the buyer journey, and includes a measurement framework. Without it, content teams produce output without direction — publishing more without knowing whether it drives outcomes.
|
||||
|
||||
Why it works:
|
||||
- Answers the question completely in isolation
|
||||
- No links
|
||||
- Specific enough to be citable (mentions audience research, buyer journey, measurement framework)
|
||||
- Under 80 words
|
||||
|
||||
**Weak capsule (48 words — too short, too vague):**
|
||||
> Content strategy is important for businesses. It helps you plan what content to create. Many companies use content strategy to grow their audience. There are different approaches depending on your goals. It's a broad topic that covers many areas of marketing.
|
||||
|
||||
Why it fails:
|
||||
- Does not complete the answer — "many areas" is not an answer
|
||||
- No specifics, no named concepts
|
||||
- Under 50 words
|
||||
- AI engine would not cite this — it says nothing citable
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
Before marking this task complete, verify each item:
|
||||
|
||||
- [ ] Every H2 in the article is now a direct question ending with "?"
|
||||
- [ ] Every question-format H2 has an answer capsule immediately below it (no intervening text)
|
||||
- [ ] Every capsule is between 50 and 80 words — count precisely, not approximately
|
||||
- [ ] No links appear inside any capsule block
|
||||
- [ ] Every capsule has the HTML comment markers noting word count
|
||||
- [ ] Paragraphs throughout the article body are ≤3 sentences (flag any exceptions in the report)
|
||||
- [ ] The H1 title is unchanged
|
||||
- [ ] H3s are unchanged (unless user requested otherwise)
|
||||
- [ ] Original voice, tone, and terminology are preserved — this is optimization, not ghostwriting
|
||||
- [ ] Trust signal inventory table is populated with actual examples from the text, not generic placeholders
|
||||
- [ ] Gaps in trust signals are noted with specific recommendations, not just "add more data"
|
||||
- [ ] Before and after AEO scores are both present in the audit report
|
||||
- [ ] Heading rewrites table is complete — one row per H2
|
||||
- [ ] Paragraph length audit table is complete — covers all sections
|
||||
- [ ] Any FAQ section recommendation is based on real PAA-style questions for the topic, not invented ones
|
||||
- [ ] Both deliverables (article + audit report) are present in the response
|
||||
- [ ] Total word count of the rewritten article is within ±10% of the original (optimization, not expansion)
|
||||
|
||||
---
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- "AEO optimize this article"
|
||||
- "Make this content AI-readable"
|
||||
- "Rewrite my headings as questions and add answer capsules"
|
||||
- "Optimize this for ChatGPT and Perplexity to cite"
|
||||
- "Run an AEO audit on this draft"
|
||||
- "Make this article get picked up by AI search"
|
||||
- "I want Perplexity to cite my content — can you fix this article?"
|
||||
- "Turn these headings into questions and add short answer blocks"
|
||||
- "Can you add answer capsules under each section?"
|
||||
- "Audit this for answer engine optimization"
|
||||
- "My content isn't showing up in AI answers — fix the structure"
|
||||
- "AEO this" [followed by article text or URL]
|
||||
- "Optimize for AI citation"
|
||||
- "Make each section self-contained for AI extraction"
|
||||
|
||||
---
|
||||
|
||||
## Appendix: AEO vs SEO — Key Differences
|
||||
|
||||
This is useful context Claude can share with users who are unfamiliar with AEO:
|
||||
|
||||
| Dimension | SEO (Search Engine Optimization) | AEO (Answer Engine Optimization) |
|
||||
|---|---|---|
|
||||
| Target | Google's ranking algorithm | AI engine extraction models |
|
||||
| Primary signal | Backlinks, authority, keyword density | Structured Q&A, answer capsule clarity |
|
||||
| Content format | Long-form, comprehensive coverage | Question-first, capsule-first, then expand |
|
||||
| Heading style | Keyword-rich labels ("Best Project Management Tools") | Direct questions ("What are the best project management tools?") |
|
||||
| Paragraph length | Not a ranking factor | Short (≤3 sentences) is strongly preferred |
|
||||
| Links in body | Important for authority passing | Links inside answer capsules break extractability |
|
||||
| Trust signals | Domain authority, backlink profile | Named data, frameworks, first-person experience |
|
||||
| Measurement | Organic ranking position, CTR | AI citation frequency, answer box appearances |
|
||||
|
||||
AEO does not replace SEO — it complements it. A well-structured article optimized for AEO will also perform better in traditional search because its structure is clearer and its headings are more specific to user intent.
|
||||
|
||||
---
|
||||
|
||||
## Appendix: Answer Capsule Templates by Content Type
|
||||
|
||||
Not all articles have the same kind of content. Use these capsule templates as starting points based on the section type.
|
||||
|
||||
### "What is X?" sections (definition)
|
||||
|
||||
```
|
||||
[X] is [concise category or type]. It [what it does or how it works] by [mechanism or method].
|
||||
[Why it exists or what problem it solves — 1 sentence.] [One concrete example or real-world application.]
|
||||
```
|
||||
|
||||
Target: 55-70 words. Avoid starting with "X is a type of X" — give immediate signal.
|
||||
|
||||
### "How do you do X?" sections (how-to)
|
||||
|
||||
```
|
||||
To [achieve outcome], [do step A], then [do step B], then [do step C].
|
||||
[The most common mistake or prerequisite — 1 sentence.] [The expected result or timeframe.]
|
||||
```
|
||||
|
||||
Target: 50-65 words. Use active verbs throughout. No links.
|
||||
|
||||
### "Why does X matter?" sections (rationale)
|
||||
|
||||
```
|
||||
[X] matters because [specific reason 1] and [specific reason 2].
|
||||
Without [X], [consequence — ideally quantified or concrete].
|
||||
[Who this is most important for, and under what conditions.]
|
||||
```
|
||||
|
||||
Target: 55-75 words. Specifics outperform generalities here — name numbers when they exist.
|
||||
|
||||
### "What are the benefits of X?" sections (list rationale)
|
||||
|
||||
```
|
||||
The main benefits of [X] are [benefit 1], [benefit 2], and [benefit 3].
|
||||
[Benefit 1] means [specific outcome]. [Benefit 2] enables [specific use case].
|
||||
Together these make [X] valuable for [audience] who need [outcome].
|
||||
```
|
||||
|
||||
Target: 60-80 words. Compress the list into prose — bullet lists inside capsules are less extractable.
|
||||
|
||||
### "Which X should I choose?" sections (comparison/decision)
|
||||
|
||||
```
|
||||
Choose [Option A] when [condition A]. Choose [Option B] when [condition B].
|
||||
The deciding factor is [key variable]. [One sentence on the most common mistake —
|
||||
picking based on the wrong criterion.]
|
||||
```
|
||||
|
||||
Target: 50-70 words. Decision capsules are among the highest-cited by AI engines — they answer the user's actual next question.
|
||||
|
||||
### "When should I X?" sections (timing/trigger)
|
||||
|
||||
```
|
||||
[X] when [specific trigger condition], typically [timeframe or frequency].
|
||||
Early signs that it's time include [signal 1] and [signal 2].
|
||||
Waiting too long often results in [consequence].
|
||||
```
|
||||
|
||||
Target: 45-65 words. Concise is especially important for timing capsules.
|
||||
|
||||
---
|
||||
|
||||
## Appendix: AEO Scoring Rubric — Detailed Criteria
|
||||
|
||||
Use this when producing the before/after score. Each criterion has a maximum contribution to the /10 score.
|
||||
|
||||
| Criterion | Max score | How to assess |
|
||||
|---|---|---|
|
||||
| H2s as direct questions | 2 pts | 2 = all H2s are questions; 1 = majority; 0 = few or none |
|
||||
| Answer capsules present | 2 pts | 2 = every H2 section has a capsule; 1 = some sections; 0 = none |
|
||||
| Capsules within 50-80 words | 1 pt | 1 = all capsules in range; 0 = any over 80 or under 50 |
|
||||
| No links inside capsules | 1 pt | 1 = zero links in any capsule; 0 = any links present |
|
||||
| Paragraphs ≤3 sentences | 2 pts | 2 = all paragraphs compliant; 1 = majority; 0 = widespread violations |
|
||||
| Trust signals present | 2 pts | 2 = 3+ trust signal types; 1 = 1-2 types; 0 = none |
|
||||
|
||||
**Score interpretation:**
|
||||
- 8-10: Strong AEO readiness — well-positioned for AI citation
|
||||
- 5-7: Partial — likely extracted occasionally but inconsistently
|
||||
- 0-4: Low readiness — AI engines will paraphrase at best, skip at worst
|
||||
|
||||
A typical unoptimized article scores 2-4. A well-structured but unoptimized thought leadership piece might score 4-6. After this skill runs, target 8+.
|
||||
|
||||
---
|
||||
|
||||
## Appendix: How Different AI Engines Extract Content
|
||||
|
||||
Understanding how each engine works helps explain the rules behind the skill.
|
||||
|
||||
### ChatGPT (GPT-4 and later) / Bing
|
||||
|
||||
Retrieval-augmented generation with Bing Search integration. When a user asks a question, Bing retrieves pages, then GPT extracts passages. It tends to extract the first plausible answer-shaped block it finds in the page — meaning the capsule directly under the H2 is almost always what gets quoted. It prefers prose over lists for citations (though it reads lists fine).
|
||||
|
||||
**Implication:** Get the capsule under the question-format H2 right. The rest of the section body is bonus context.
|
||||
|
||||
### Perplexity
|
||||
|
||||
Explicitly designed for sourced Q&A. It retrieves 5-10 pages per query and extracts from all of them simultaneously. It shows citations with numbered footnotes. It strongly prefers content that is:
|
||||
- Clearly attributed (author name or publication byline visible)
|
||||
- Recently published or updated (freshness signal)
|
||||
- Structured around the question being asked (heading match)
|
||||
|
||||
**Implication:** Trust signals (author, date) and heading-to-question matching are especially important for Perplexity. Capsules that include specific numbers or named frameworks are more likely to be footnoted.
|
||||
|
||||
### Claude (Anthropic)
|
||||
|
||||
Claude with web search capability (Claude.ai or API with tools) retrieves pages and synthesises across them. Claude prioritises self-contained, complete answers and tends to directly quote capsules that are within the 50-80 word range. Claude is less likely to quote incomplete paragraphs that trail off or rely on surrounding context.
|
||||
|
||||
**Implication:** The self-contained requirement is especially important for Claude citation. If the capsule requires reading the surrounding sentences to make sense, Claude will paraphrase instead of quote.
|
||||
|
||||
### Google Gemini (AI Overviews)
|
||||
|
||||
Integrated into Google Search. Generates AI Overviews for informational queries. Extracts from indexed pages, with preference for pages that already rank well (so SEO and AEO reinforce each other here). Tends to extract bulleted lists and numbered steps for how-to content; extracts definition capsules for "what is" queries.
|
||||
|
||||
**Implication:** For Gemini AI Overviews, structured how-to content with numbered steps in the capsule performs well. Definition capsules should include the category/type as the first word.
|
||||
|
||||
---
|
||||
|
||||
## Appendix: Content Types That Benefit Most from AEO
|
||||
|
||||
Not all content benefits equally. Use this to set expectations with the user about where AEO investment pays off most.
|
||||
|
||||
| Content type | AEO benefit | Reason |
|
||||
|---|---|---|
|
||||
| Glossary or definition articles | Very high | AI engines are constantly answering "what is X?" queries |
|
||||
| How-to guides and tutorials | Very high | Step-by-step content is a primary retrieval target |
|
||||
| Comparison articles ("X vs Y") | High | Decision queries are common AI engine inputs |
|
||||
| FAQ pages | High | Already in question format — just needs capsule discipline |
|
||||
| Research roundups with original data | High | Named statistics are citation anchors |
|
||||
| Thought leadership / opinion pieces | Medium | Opinion is less extractable; add definition and how-to sections |
|
||||
| News and timely content | Medium | AI engines prefer evergreen; but breaking news gets citation bursts |
|
||||
| Case studies | Medium | Specific outcomes are extractable; company-specific context less so |
|
||||
| Creative writing / narrative | Low | Not structured for extraction; AEO rules don't apply |
|
||||
| Product pages / landing pages | Low | Conversion-focused pages are rarely cited by AI engines |
|
||||
|
||||
---
|
||||
|
||||
*Originally created by Gencay (LearnAIwithMe) — adapted and extended for this library.*
|
||||
@@ -0,0 +1,207 @@
|
||||
---
|
||||
name: ai-ethics-review
|
||||
description: "Conduct an ethical review of an AI or ML feature, model, or product. Use when asked to run an AI ethics review, assess AI risks, audit a model for bias, or produce an AI impact assessment. Produces a structured ethics review covering fairness, transparency, privacy, safety, accountability, and societal impact with prioritised mitigations."
|
||||
---
|
||||
|
||||
# AI Ethics Review Skill
|
||||
|
||||
This skill produces a structured ethical review of an AI or machine learning feature, model, or product. Output covers fairness, transparency, privacy, safety, accountability, and societal impact — with risk scoring, prioritised mitigations, and a checklist suitable for governance review or responsible AI documentation.
|
||||
|
||||
> ⚠️ This skill provides a structured framework for identifying and documenting ethical risks. It is not a substitute for legal advice, regulated algorithmic impact assessments, or specialist ethics review required in specific jurisdictions (e.g. EU AI Act, UK AI regulation).
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask the user for these if not provided:
|
||||
- **Feature or model name** and what it does
|
||||
- **Who it affects** — which users or people does the AI interact with, make decisions about, or collect data from?
|
||||
- **What decisions or outputs it produces** — recommendations, predictions, classifications, generation, automation?
|
||||
- **Consequentiality** — how significant are the AI's decisions? (low-stakes suggestions vs decisions that affect employment, credit, health, safety, etc.)
|
||||
- **Data used** — what training data, user data, or third-party data is used?
|
||||
- **Human oversight** — is there a human in the loop, and at what stage?
|
||||
- **Deployment context** — who will use this and how? (internal tool / consumer-facing / automated pipeline)
|
||||
|
||||
## Output Structure
|
||||
|
||||
---
|
||||
|
||||
# AI Ethics Review: [Feature / Model Name]
|
||||
|
||||
**Product / system:** [Name and brief description]
|
||||
**Review type:** [Pre-deployment review / Post-deployment audit / Change review]
|
||||
**Risk tier:** [High / Medium / Low — based on consequentiality, scale, and affected population]
|
||||
**Reviewer:** [Name / Team]
|
||||
**Date:** [Date]
|
||||
**Status:** [Draft / Approved / Requires escalation]
|
||||
|
||||
---
|
||||
|
||||
## 1. Feature Summary
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| **What it does** | [1–2 sentences — plain English description of the AI feature and its purpose] |
|
||||
| **Who uses it** | [End users / internal teams / automated system] |
|
||||
| **Who is affected by its outputs** | [May be different from who uses it — e.g. an AI hiring tool is used by HR but affects candidates] |
|
||||
| **Output type** | [Recommendation / Classification / Prediction / Generation / Automation / Scoring] |
|
||||
| **Scale** | [How many people affected per day/month?] |
|
||||
| **Consequentiality** | [High: affects access to services, employment, credit, health, safety / Medium: influences decisions / Low: suggestions with easy override] |
|
||||
| **Human oversight level** | [Full automation / Human review before action / Human can override after action / Advisory only] |
|
||||
|
||||
---
|
||||
|
||||
## 2. Risk Tier Assessment
|
||||
|
||||
| Factor | Score (1–3) | Rationale |
|
||||
|---|---|---|
|
||||
| **Consequentiality** (impact on individuals) | [1=low, 3=high] | [e.g. 3 — model output influences hiring decisions] |
|
||||
| **Scale** (number of people affected) | [1=few, 3=many] | [e.g. 2 — internal tool used for ~500 candidates/year] |
|
||||
| **Reversibility** (can harm be undone?) | [1=reversible, 3=irreversible] | [e.g. 2 — unfair rejection can be appealed but may not be caught] |
|
||||
| **Vulnerability of affected group** | [1=general population, 3=protected or vulnerable group] | [e.g. 2 — includes protected characteristics in the decision context] |
|
||||
| **Transparency** (do affected people know?) | [1=informed, 3=opaque] | [e.g. 3 — candidates are not told AI is used in screening] |
|
||||
|
||||
**Composite risk tier:** [High (12–15) / Medium (7–11) / Low (3–6)]
|
||||
|
||||
**Risk tier implications:**
|
||||
- **High:** Mandatory senior ethics review, DPA/DPIA required, human-in-loop for all consequential decisions, ongoing monitoring required
|
||||
- **Medium:** Ethics review recommended, document mitigations, quarterly monitoring
|
||||
- **Low:** Standard review, document assumptions, annual review
|
||||
|
||||
---
|
||||
|
||||
## 3. Fairness & Bias
|
||||
|
||||
*Does the AI treat people equitably across groups?*
|
||||
|
||||
**Protected characteristics relevant to this feature:**
|
||||
[List applicable protected characteristics — age, gender, race/ethnicity, disability, religion, national origin, etc.]
|
||||
|
||||
| Risk | Analysis | Mitigation |
|
||||
|---|---|---|
|
||||
| **Training data bias** | [Does the training data reflect historical discrimination? e.g. hiring data that reflects past biases in who was hired] | [Audit training data for demographic representation / use debiasing techniques / document data lineage] |
|
||||
| **Proxy discrimination** | [Could the model use a proxy for a protected characteristic? e.g. using postcode as a proxy for race] | [Identify proxy features / test for disparate impact using adversarial debiasing] |
|
||||
| **Differential performance** | [Does the model perform differently across demographic groups? — e.g. lower accuracy for underrepresented groups] | [Disaggregate performance metrics by group / set minimum performance thresholds per group] |
|
||||
| **Feedback loops** | [Does the model's output reinforce existing disparities? e.g. recommending content that keeps disadvantaged groups in lower-engagement patterns] | [Monitor outcome distributions over time / implement feedback loop detection] |
|
||||
|
||||
**Fairness evaluation method:** [What method will be used to measure fairness — statistical parity / equalised odds / individual fairness? Who is responsible for running it and how often?]
|
||||
|
||||
---
|
||||
|
||||
## 4. Transparency & Explainability
|
||||
|
||||
*Can affected people understand how the AI makes decisions?*
|
||||
|
||||
| Dimension | Current state | Required state | Gap |
|
||||
|---|---|---|---|
|
||||
| **User disclosure** | [Are users told they're interacting with AI?] | [Yes — required for trust and regulation] | [e.g. No disclosure on current UI] |
|
||||
| **Decision explanation** | [Can the system explain why it reached a conclusion?] | [For high-stakes decisions: yes] | [e.g. Black-box model — no feature attribution available] |
|
||||
| **Right to know** | [Can affected people ask how a decision was made?] | [Yes — required under GDPR Art. 22 for automated decisions] | [e.g. No process exists] |
|
||||
| **Confidence calibration** | [Does the model express appropriate uncertainty?] | [Yes — overconfident models cause over-reliance] | [e.g. Model outputs binary label without confidence score] |
|
||||
|
||||
**Explainability approach:** [LIME / SHAP / rule-based surrogate / LLM-generated rationale / none — and why]
|
||||
|
||||
---
|
||||
|
||||
## 5. Privacy & Data
|
||||
|
||||
*Is personal data used responsibly and lawfully?*
|
||||
|
||||
| Risk | Analysis | Mitigation |
|
||||
|---|---|---|
|
||||
| **Data minimisation** | [Does the model use more personal data than necessary?] | [Audit input features — remove any that don't improve performance and involve unnecessary data collection] |
|
||||
| **Data retention** | [How long is personal data retained for training and inference?] | [Define retention policy aligned to GDPR / CCPA / sector requirements] |
|
||||
| **Re-identification risk** | [Could model outputs or training data be used to identify individuals?] | [Differential privacy / k-anonymity / output rate limiting] |
|
||||
| **Third-party data** | [Is data from third parties used? Is it licensed for this use?] | [Audit data licensing / get legal sign-off on each third-party source] |
|
||||
| **Cross-border data transfer** | [Is personal data transferred across jurisdictions?] | [Legal review — Standard Contractual Clauses or equivalent] |
|
||||
|
||||
**DPIA required?** [Yes / No / Uncertain — for High tier or whenever processing is likely to result in high risk to individuals under GDPR Art. 35]
|
||||
|
||||
---
|
||||
|
||||
## 6. Safety & Reliability
|
||||
|
||||
*What happens when the AI gets it wrong?*
|
||||
|
||||
| Failure mode | Likelihood | Impact | Mitigation |
|
||||
|---|---|---|---|
|
||||
| **False positives** | [H/M/L] | [e.g. Flagging a legitimate transaction as fraud — customer locked out] | [Set threshold conservatively; human review for edge cases] |
|
||||
| **False negatives** | [H/M/L] | [e.g. Missing a real fraud case — financial loss] | [Monitor false negative rate; set minimum recall threshold] |
|
||||
| **Out-of-distribution inputs** | [H/M/L] | [Model behaves unpredictably on inputs outside training distribution] | [Input validation; confidence thresholding — route uncertain inputs to human review] |
|
||||
| **Model degradation** | [M] | [Performance degrades as data distributions shift post-deployment] | [Scheduled performance monitoring; drift detection alerts] |
|
||||
| **Adversarial inputs** | [L/M] | [Deliberate manipulation of inputs to game the model] | [Adversarial testing; rate limiting; anomaly detection on inputs] |
|
||||
| **Single point of failure** | [L/M] | [Model outage causes downstream system failure] | [Graceful degradation — define fallback behaviour when model is unavailable] |
|
||||
|
||||
**Fallback behaviour:** [What happens if the AI is unavailable or returns low-confidence output? — e.g. route to human review / use rule-based fallback / block the action]
|
||||
|
||||
---
|
||||
|
||||
## 7. Accountability & Governance
|
||||
|
||||
*Who is responsible when things go wrong?*
|
||||
|
||||
| Question | Answer |
|
||||
|---|---|
|
||||
| **Who owns this AI feature?** | [Team or individual with end-to-end accountability] |
|
||||
| **Who approved deployment?** | [Name and role — must be documented] |
|
||||
| **Who is responsible for ongoing monitoring?** | [Team and cadence] |
|
||||
| **Who can shut it down?** | [Who has kill-switch authority and under what conditions?] |
|
||||
| **How are incidents reported?** | [Internal escalation path + external disclosure process if required] |
|
||||
| **Is this subject to regulation?** | [EU AI Act / UK AI regulation / sector-specific rules — FINRA, FDA, FCA, etc.] |
|
||||
|
||||
**Incident response plan:** [Link to or describe what happens if the model causes harm — detection, escalation, remediation, disclosure]
|
||||
|
||||
---
|
||||
|
||||
## 8. Societal Impact
|
||||
|
||||
*Beyond individual users — what are the broader effects?*
|
||||
|
||||
| Impact area | Risk | Mitigation |
|
||||
|---|---|---|
|
||||
| **Labour displacement** | [Does this AI automate tasks that currently employ people?] | [Transition plan / human-AI collaboration framing / skills retraining commitment] |
|
||||
| **Environmental impact** | [What is the carbon cost of training and inference?] | [Measure and offset; prefer efficient architectures; use renewable-energy infrastructure where possible] |
|
||||
| **Power concentration** | [Does this AI give the deploying organisation disproportionate power over individuals?] | [Ensure right to opt out; avoid lock-in; consider open alternatives] |
|
||||
| **Information ecosystem** | [Could this AI contribute to misinformation, filter bubbles, or manipulation?] | [Provenance labelling / content policies / algorithmic diversity requirements] |
|
||||
|
||||
---
|
||||
|
||||
## 9. Mitigation Priorities
|
||||
|
||||
| # | Risk | Severity | Action | Owner | Deadline |
|
||||
|---|---|---|---|---|---|
|
||||
| 1 | [Highest risk — e.g. No disclosure to affected candidates] | Critical | [Add AI disclosure to UI and candidate-facing documentation] | [PM + Legal] | [Before launch] |
|
||||
| 2 | [e.g. No fairness evaluation across demographic groups] | High | [Commission third-party fairness audit using [method]] | [ML team + external auditor] | [Within 30 days of launch] |
|
||||
| 3 | [e.g. No model monitoring in place] | High | [Deploy performance and drift monitoring dashboard] | [ML Ops] | [Launch day] |
|
||||
| 4 | [e.g. DPIA not completed] | High | [Complete DPIA with DPO before deployment] | [Legal / DPO] | [Before launch] |
|
||||
|
||||
---
|
||||
|
||||
## 10. Pre-Deployment Checklist
|
||||
|
||||
- [ ] Ethics review completed and approved by required reviewers
|
||||
- [ ] DPIA completed (if required)
|
||||
- [ ] Fairness evaluation completed and results documented
|
||||
- [ ] AI disclosure is in place wherever required
|
||||
- [ ] Human oversight mechanism is defined and tested
|
||||
- [ ] Kill-switch and escalation path is documented and tested
|
||||
- [ ] Model monitoring is deployed and alerting is configured
|
||||
- [ ] Data lineage and training data audit documented
|
||||
- [ ] Legal sign-off obtained on data licensing and cross-border transfers
|
||||
- [ ] Incident response plan in place
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] "Who is affected" includes people the AI makes decisions *about*, not just who uses the product
|
||||
- [ ] Fairness analysis names specific protected characteristics, not just "diverse groups"
|
||||
- [ ] Safety section covers both false positive and false negative failure modes
|
||||
- [ ] Accountability section names real people, not teams or roles
|
||||
- [ ] Mitigations are specific and time-bound — not "monitor and review"
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- "Run an AI ethics review for [feature]"
|
||||
- "Conduct an ethical impact assessment for our new ML model"
|
||||
- "Review the AI risks for our hiring / credit / recommendation system"
|
||||
- "Build a responsible AI checklist for our product"
|
||||
- "What are the ethical risks of using AI for [use case]?"
|
||||
@@ -13,10 +13,12 @@ Ask the user for these if not provided:
|
||||
- **API or endpoint details** (raw spec, Postman export, or verbal description)
|
||||
- **Auth method** (API key / Bearer token / OAuth 2.0 / None)
|
||||
- **Base URL**
|
||||
- **API version** (e.g. v1, v2.3, or "unversioned" — affects deprecation notes and versioning headers)
|
||||
- **Rate limits** (requests per second/minute per token or IP, if known — or "unknown")
|
||||
- **Audience** (internal developers / external partners / public)
|
||||
- **Output format** (Markdown / OpenAPI YAML / Plain prose)
|
||||
- **Output format** (Markdown for developer portals and READMEs / Plain prose for Confluence or Notion — note: OpenAPI YAML is not produced by this skill)
|
||||
|
||||
## Output Structure
|
||||
## Output Format
|
||||
|
||||
For each endpoint, produce the following:
|
||||
|
||||
@@ -133,13 +135,13 @@ data = response.json()
|
||||
- [ ] Every parameter is documented (type, required/optional, description)
|
||||
- [ ] Response fields are fully documented with types
|
||||
- [ ] All relevant error codes are listed with resolution guidance
|
||||
- [ ] Code examples are copy-paste runnable (no pseudocode)
|
||||
- [ ] Error codes cover at minimum: 400 (bad request), 401/403 (auth), 404 (not found), 429 (rate limited), 500 (server error) — or explicitly note which don't apply to this endpoint
|
||||
- [ ] Code examples use the actual base URL and a realistic placeholder token — no examples reference undefined variables or "YOUR_ENDPOINT" outside the snippet
|
||||
- [ ] Auth method is clearly stated at the top
|
||||
- [ ] Enum values are listed where applicable
|
||||
- [ ] Pagination documented if the endpoint is a list endpoint
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
## Usage Examples
|
||||
- "Document this API endpoint: [paste spec or description]"
|
||||
- "Turn this Postman collection into developer docs"
|
||||
- "Write API reference docs for [endpoint]"
|
||||
|
||||
@@ -10,6 +10,7 @@ This skill produces a complete Architecture Decision Record (ADR) following the
|
||||
## Required Inputs
|
||||
|
||||
Ask the user for these if not provided:
|
||||
- **ADR number** (sequential number in your ADR registry — e.g. 012; or "next available" if unknown)
|
||||
- **Decision title** (brief, e.g. "Use PostgreSQL as primary datastore")
|
||||
- **Context** (what situation led to this decision needing to be made?)
|
||||
- **Options considered** (at least 2; if only 1 is given, prompt for alternatives that were considered or ruled out)
|
||||
@@ -17,8 +18,9 @@ Ask the user for these if not provided:
|
||||
- **Reason for choice**
|
||||
- **Status** (Proposed / Accepted / Deprecated / Superseded)
|
||||
- **Author and date**
|
||||
- **Team context** (optional — team size, relevant experience, org constraints; helps calibrate formality and depth of the Context section)
|
||||
|
||||
## Output Structure
|
||||
## Output Format
|
||||
|
||||
---
|
||||
|
||||
@@ -89,13 +91,13 @@ For each option, produce:
|
||||
|
||||
## Implementation Notes
|
||||
|
||||
[Optional but valuable: any specific patterns, gotchas, or guidance for the team implementing based on this decision. Link to relevant tickets, RFCs, or design docs if applicable.]
|
||||
[Include if the decision has non-obvious implementation gotchas, or if there are related tickets/RFCs implementers will need. Skip only if the decision is purely tooling selection with no implementation ambiguity.]
|
||||
|
||||
---
|
||||
|
||||
## Review Date
|
||||
|
||||
[Optional: "This decision should be reviewed if [condition] — e.g. team grows beyond 20 engineers, or traffic exceeds 10M requests/day."]
|
||||
[Include unless the decision is permanent or self-evidently final. State a specific trigger condition — e.g. "Review if team grows beyond 20 engineers or traffic exceeds 10M requests/day" — not just "should be reviewed periodically".]
|
||||
|
||||
---
|
||||
|
||||
@@ -107,10 +109,10 @@ For each option, produce:
|
||||
- [ ] Consequences include *negative* consequences — no decision is consequence-free
|
||||
- [ ] Decision is stated in plain language in the Decision section
|
||||
- [ ] Risks section identifies what would invalidate this decision
|
||||
- [ ] Written for someone with no prior context on this decision
|
||||
|
||||
## Example Trigger Phrases
|
||||
- [ ] Context section states the problem explicitly in its first 1–2 sentences (does not assume the reader knows what problem the team was solving)
|
||||
- [ ] Each rejected option's "Why ruled out" explanation names a specific constraint or trade-off (not a circular statement like "didn't meet our requirements")
|
||||
|
||||
## Usage Examples
|
||||
- "Write an ADR for using [technology]"
|
||||
- "Document our decision to [architectural choice]"
|
||||
- "Create an architecture decision record for [topic]"
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: changelog-generator
|
||||
description: "Convert a git log, commit list, or release notes into a polished, user-facing changelog. Use when writing release notes, generating a CHANGELOG.md entry, or documenting what changed in a version. Produces a structured changelog section with version header, categorised changes, and migration notes. Optimised for Opus 4.7 and newer models."
|
||||
description: "Convert a git log, commit list, or release notes into a polished, user-facing changelog. Use when writing release notes, generating a CHANGELOG.md entry, or documenting what changed in a version. Produces a structured changelog section with version header, categorised changes, and migration notes."
|
||||
---
|
||||
|
||||
# Changelog Generator Skill
|
||||
@@ -15,8 +15,10 @@ Ask for these if not provided:
|
||||
- **Release date** (or "today")
|
||||
- **Audience** (developers using an API / end users of a product / internal team — affects language)
|
||||
- **Any breaking changes** (flag these explicitly if known)
|
||||
- **Previous version behaviour** (optional — paste the previous changelog entry or describe what is changing; needed for accurate "Changed" entries)
|
||||
- **Scope** (whole product / specific package or module — e.g. "payments SDK only", "iOS app", "all services")
|
||||
|
||||
## Output Structure
|
||||
## Output Format
|
||||
|
||||
Follow [Keep a Changelog](https://keepachangelog.com) format:
|
||||
|
||||
@@ -52,6 +54,10 @@ Follow [Keep a Changelog](https://keepachangelog.com) format:
|
||||
|
||||
---
|
||||
|
||||
---
|
||||
|
||||
> **Skill guidance — do not include the following section in the delivered changelog:**
|
||||
|
||||
## Formatting Rules Applied
|
||||
|
||||
**Language:** Write for the reader, not the committer. "Add dark mode support" not "implement ThemeProvider with dark palette variant".
|
||||
@@ -72,9 +78,10 @@ Follow [Keep a Changelog](https://keepachangelog.com) format:
|
||||
- [ ] Related commits are grouped into single entries (not listed individually)
|
||||
- [ ] Version and date header is correct
|
||||
- [ ] Empty sections are omitted
|
||||
- [ ] Tone is imperative mood throughout
|
||||
- [ ] No entries start with past-tense verbs (no "Added", "Fixed", "Removed" — use "Add", "Fix", "Remove")
|
||||
- [ ] Every breaking change entry includes a specific migration action (not just "update your code")
|
||||
|
||||
## Example Trigger Phrases
|
||||
## Usage Examples
|
||||
- "Write a changelog for version [X]" + [paste commits]
|
||||
- "Generate release notes from these commits"
|
||||
- "Turn this git log into a CHANGELOG entry"
|
||||
|
||||
@@ -0,0 +1,282 @@
|
||||
---
|
||||
name: claude-superpowers
|
||||
description: "Force Claude Code to work like a senior developer: plan before coding, work in isolation, write tests first, and review its own output twice before presenting it. Use when asked to enable superpowers mode, activate the superpowers framework, or turn on superpowers for this session. Installs a 4-stage framework — Plan, Isolate, Test First, Double Review — that prevents Claude from sprinting into broken code."
|
||||
---
|
||||
|
||||
# Claude Superpowers Skill
|
||||
|
||||
Stop Claude from shipping the first thing it writes. Superpowers mode locks Claude into four stages — Plan, Isolate, Test First, Double Review — so that what it presents at the end is actually right.
|
||||
|
||||
The default problem: Claude sprints out of the gate, writes the whole thing in one shot, and it looks great — until someone runs it. It doesn't plan. It doesn't test. It doesn't verify. The result: code that breaks on edge cases, debugging rounds that burn tokens, and rework that costs more than doing it right the first time.
|
||||
|
||||
> **Credit:** Inspired by a skill from Nate Herk's YouTube channel — adapted and extended for this library.
|
||||
|
||||
---
|
||||
|
||||
## Required Inputs
|
||||
|
||||
No inputs required. Superpowers activates on command, then applies to whatever coding task follows.
|
||||
|
||||
---
|
||||
|
||||
## The Four Stages
|
||||
|
||||
### Stage 1 — Plan
|
||||
|
||||
Before writing a single line of code, Claude must produce a written plan and wait for user confirmation.
|
||||
|
||||
**Plan format:**
|
||||
|
||||
```
|
||||
PLAN
|
||||
════
|
||||
|
||||
TASK
|
||||
[One-sentence restatement of what was asked. If anything is ambiguous, flag it here before proceeding.]
|
||||
|
||||
APPROACH
|
||||
[2–4 sentences describing the implementation approach and key decisions. If there are multiple valid approaches, briefly explain why this one was chosen.]
|
||||
|
||||
FILES TO CREATE OR MODIFY
|
||||
- [path/to/file.ts] — [what changes: create / modify / delete — one line reason]
|
||||
- [path/to/file.ts] — [what changes]
|
||||
|
||||
EDGE CASES I WILL HANDLE
|
||||
- [Edge case 1]
|
||||
- [Edge case 2]
|
||||
- [Edge case 3]
|
||||
|
||||
EDGE CASES I AM NOT HANDLING (out of scope)
|
||||
- [Out of scope case — reason]
|
||||
|
||||
ASSUMPTIONS
|
||||
- [Any assumption made where the requirements were unclear]
|
||||
|
||||
Confirm this plan before I start coding.
|
||||
```
|
||||
|
||||
Claude must not proceed until the user says yes (or provides corrections). If the user corrects the plan, revise and re-confirm before starting.
|
||||
|
||||
---
|
||||
|
||||
### Stage 2 — Isolate
|
||||
|
||||
Claude works in isolation until the output is complete and reviewed. Nothing touches the main project until explicitly approved.
|
||||
|
||||
**Isolation rules:**
|
||||
- If git is available: create a feature branch before making any changes. Branch name format: `superpowers/[task-slug]`
|
||||
- If no git: note that changes are being made to a working copy and flag all modified files at the end for user review before they're considered "shipped"
|
||||
- Do not modify files outside the scope defined in the plan unless the user explicitly expands scope during the session
|
||||
- If new scope is discovered mid-task (e.g. a dependency needs to change), surface it: "This requires also modifying [X] — should I include that in scope?"
|
||||
|
||||
**On starting Stage 2, announce:**
|
||||
```
|
||||
ISOLATE
|
||||
Working in isolation on branch: superpowers/[task-slug]
|
||||
No changes will be considered final until Stage 4 review is complete.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Stage 3 — Test First
|
||||
|
||||
Before writing the implementation, write the tests (or at minimum, define the expected behaviour as executable assertions).
|
||||
|
||||
**Test-first approach:**
|
||||
1. Write tests that define the expected behaviour for the task
|
||||
2. Write tests that cover each edge case identified in the plan
|
||||
3. Run the tests — they should fail (implementation doesn't exist yet)
|
||||
4. Confirm the tests are failing for the right reason before writing implementation
|
||||
5. Write the implementation
|
||||
6. Run the tests — they should now pass
|
||||
7. If tests fail: fix the implementation, not the tests
|
||||
|
||||
**If the project has no test setup:** flag it and offer two options:
|
||||
- Option A: Set up a minimal test harness before proceeding (recommended)
|
||||
- Option B: Define the expected behaviour as a checklist of manual verification steps (faster but weaker)
|
||||
|
||||
**Test summary to show before writing implementation:**
|
||||
|
||||
```
|
||||
TESTS WRITTEN
|
||||
─────────────
|
||||
File: [test file path]
|
||||
Tests:
|
||||
✗ [test description — covers: happy path]
|
||||
✗ [test description — covers: edge case 1]
|
||||
✗ [test description — covers: edge case 2]
|
||||
✗ [test description — covers: error state]
|
||||
|
||||
All tests failing as expected. Starting implementation.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Stage 4 — Double Review
|
||||
|
||||
After completing the code and running tests, Claude reviews its own work twice before presenting it. Neither review is a formality.
|
||||
|
||||
**Review 1 — "Does this match what was asked for?"**
|
||||
|
||||
Check the completed code against the original request and confirmed plan:
|
||||
- Does it do everything that was asked?
|
||||
- Does it handle all edge cases from the plan?
|
||||
- Are there any mismatches between what was planned and what was built?
|
||||
- Are there any assumptions baked in that weren't confirmed?
|
||||
|
||||
**Review 2 — "Is this good code?"**
|
||||
|
||||
Check for technical quality independent of the requirements:
|
||||
- Obvious bugs or logic errors
|
||||
- Missing error handling (especially at boundaries: API calls, file I/O, user input)
|
||||
- Security issues (injection vulnerabilities, exposed secrets, missing auth checks)
|
||||
- Readability: would another developer understand this in 6 months?
|
||||
- Performance: any obvious inefficiencies on the critical path?
|
||||
- Dead code or unused imports introduced
|
||||
|
||||
**Double Review output format:**
|
||||
|
||||
```
|
||||
REVIEW 1 — CORRECTNESS
|
||||
───────────────────────
|
||||
✅ Handles [requirement 1]
|
||||
✅ Handles [requirement 2]
|
||||
✅ Edge case [X] covered
|
||||
⚠️ [Issue found — what it is and what was changed to fix it]
|
||||
|
||||
REVIEW 2 — CODE QUALITY
|
||||
────────────────────────
|
||||
✅ Error handling present at all API boundaries
|
||||
✅ No obvious security issues
|
||||
⚠️ [Issue found — what it was and how it was fixed]
|
||||
✅ Readable — no unexplained complexity
|
||||
|
||||
VERDICT: [Ready to present / Fixed N issues before presenting]
|
||||
```
|
||||
|
||||
If issues are found in either review, fix them and note what was fixed. Present the corrected version, not the original draft.
|
||||
|
||||
---
|
||||
|
||||
## Activation Response
|
||||
|
||||
When the user triggers Superpowers mode, respond with:
|
||||
|
||||
```
|
||||
Superpowers mode active.
|
||||
|
||||
I'll work in 4 stages for every coding task this session:
|
||||
1. PLAN — Write a plan and wait for your confirmation before coding
|
||||
2. ISOLATE — Work on a branch; nothing ships until you approve
|
||||
3. TEST — Write tests before the implementation
|
||||
4. REVIEW — Review my own work twice before presenting it
|
||||
|
||||
What are we building?
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Output Structure
|
||||
|
||||
### Full task flow (all four stages)
|
||||
|
||||
```
|
||||
PLAN
|
||||
════
|
||||
[Plan format as above]
|
||||
Confirm this plan before I start coding.
|
||||
|
||||
---
|
||||
[User confirms]
|
||||
---
|
||||
|
||||
ISOLATE
|
||||
Working in isolation on branch: superpowers/[task-slug]
|
||||
|
||||
TESTS WRITTEN
|
||||
─────────────
|
||||
[Test summary — all failing]
|
||||
Starting implementation.
|
||||
|
||||
---
|
||||
[Implementation runs]
|
||||
---
|
||||
|
||||
REVIEW 1 — CORRECTNESS
|
||||
───────────────────────
|
||||
[Checklist]
|
||||
|
||||
REVIEW 2 — CODE QUALITY
|
||||
────────────────────────
|
||||
[Checklist]
|
||||
|
||||
VERDICT: Ready to present.
|
||||
|
||||
---
|
||||
|
||||
COMPLETE
|
||||
════════
|
||||
[Summary of what was built, files created/modified, how to run/test it]
|
||||
Branch: superpowers/[task-slug] — merge when ready.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## CLAUDE.md Installation Text
|
||||
|
||||
After activating Superpowers for the session, provide the user with the exact text to add to their `CLAUDE.md` to make it permanent:
|
||||
|
||||
````
|
||||
```
|
||||
## Superpowers Framework
|
||||
|
||||
This framework is always active for coding tasks in this project.
|
||||
|
||||
### Stage 1 — Plan
|
||||
Before writing any code: produce a written plan including task restatement, approach, files to create/modify, edge cases to handle, and assumptions. Wait for explicit user confirmation before proceeding.
|
||||
|
||||
### Stage 2 — Isolate
|
||||
Work on a feature branch (superpowers/[task-slug]) or clearly flagged working copy. Nothing is considered shipped until the user approves after Stage 4.
|
||||
|
||||
### Stage 3 — Test First
|
||||
Write tests before writing the implementation. Tests should fail before implementation, pass after. If no test setup exists, offer to create one or produce a manual verification checklist.
|
||||
|
||||
### Stage 4 — Double Review
|
||||
After completing code, run two reviews before presenting:
|
||||
- Review 1: Does this match what was asked for? Check against original request and plan.
|
||||
- Review 2: Is this good code? Check for bugs, missing error handling, security issues, readability.
|
||||
Fix any issues found. Present the corrected version. Show the review checklist.
|
||||
```
|
||||
````
|
||||
|
||||
Tell the user: "Add this to your CLAUDE.md and Superpowers will be active permanently for this project."
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Stage 1 plan was shown and user explicitly confirmed before any code was written
|
||||
- [ ] Plan includes: task restatement, approach, files to modify, edge cases in scope, edge cases out of scope, assumptions
|
||||
- [ ] Ambiguities in the original request were flagged in the plan (not silently assumed)
|
||||
- [ ] Stage 2 isolation: a feature branch was created (or flagged as working copy if no git)
|
||||
- [ ] Stage 3 tests were written before implementation — not after
|
||||
- [ ] Tests were run and confirmed to be failing before implementation started
|
||||
- [ ] Stage 4 Review 1 checked against the original request — not just against the plan
|
||||
- [ ] Stage 4 Review 2 checked for bugs, error handling, security, readability — all four
|
||||
- [ ] Issues found in either review were fixed before presenting — not flagged as "things to fix later"
|
||||
- [ ] Final output shows what was built, which files were changed, and how to run/test it
|
||||
- [ ] CLAUDE.md installation text was offered after activation
|
||||
|
||||
---
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- "Enable superpowers mode"
|
||||
- "Activate superpowers"
|
||||
- "Turn on superpowers for this session"
|
||||
- "Use the superpowers framework"
|
||||
- "Make sure you plan before coding"
|
||||
- "I want you to review your work before showing me"
|
||||
- "Write tests first this time"
|
||||
- "Slow down and plan it out before you start building"
|
||||
- "Work on a branch and show me a plan before touching anything"
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: code-review-checklist
|
||||
description: "Generate a tailored code review checklist for any pull request based on the language, type of change, and risk level. Use when asked to review code, check a PR, review a pull request, or generate a code review checklist. Produces a focused checklist with language-specific checks, risk-level-appropriate depth, and a clear approve/request-changes recommendation. Optimised for Opus 4.7 and newer models."
|
||||
description: "Generate a tailored code review checklist for any pull request based on the language, type of change, and risk level. Use when asked to review code, check a PR, review a pull request, or generate a code review checklist. Produces a focused checklist with language-specific checks, risk-level-appropriate depth, and a clear approve/request-changes recommendation."
|
||||
---
|
||||
|
||||
# Code Review Checklist Skill
|
||||
@@ -14,15 +14,19 @@ Ask the user for these if not provided:
|
||||
- **Type of change** (feature / bug fix / refactor / dependency upgrade / security patch / performance)
|
||||
- **Risk level** (low / medium / high / critical)
|
||||
- **PR description** (paste the description or link to the PR)
|
||||
- **Code or diff** (optional — paste key changed files or a `git diff`; significantly improves checklist specificity)
|
||||
- **Author context** (new starter / experienced / external contributor)
|
||||
|
||||
## Output Structure
|
||||
## Output Format
|
||||
|
||||
### 1. Review Summary
|
||||
**PR:** [Title or reference]
|
||||
---
|
||||
|
||||
# Code Review: [PR Title or Reference]
|
||||
|
||||
### 1. PR Overview
|
||||
**Scope assessment:** [Small / Medium / Large / Too large — should be split]
|
||||
**Recommended review depth:** [Skim / Standard / Deep dive]
|
||||
**Estimated review time:** [Minutes]
|
||||
**Estimated review time:** [e.g. 20–30 min — use 5 min per 50 lines of diff as a rough guide]
|
||||
|
||||
### 2. Correctness Checks
|
||||
|
||||
@@ -94,14 +98,17 @@ Language-specific correctness checks — choose based on the language stated:
|
||||
### 7. Common Pitfalls for This Change Type
|
||||
Based on the change type and language, flag 2-3 things reviewers typically miss for this combination.
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
- [ ] Checklist is tailored to the stated language (not generic)
|
||||
- [ ] Change-type-specific section is included
|
||||
- [ ] Risk-appropriate depth matches stated risk level
|
||||
- [ ] Decision framework is explicit
|
||||
- [ ] Decision framework includes at least one named blocking condition and one named non-blocking comment condition
|
||||
- [ ] Common pitfalls are specific to the stated language + change-type combo (not generic advice like "watch out for bugs")
|
||||
|
||||
## Example Trigger Phrases
|
||||
## Usage Examples
|
||||
- "Generate a code review checklist for [PR description]"
|
||||
- "What should I check in this pull request?"
|
||||
- "Give me a code review checklist for a [language] [change type]"
|
||||
- "Review checklist for a high-risk PR in [language]"
|
||||
- "Review checklist for a high-risk PR in [language]"
|
||||
|
||||
@@ -0,0 +1,187 @@
|
||||
---
|
||||
name: cohort-analysis
|
||||
description: "Structure a cohort analysis for retention, LTV, or behavioural patterns. Use when asked to run a cohort analysis, analyse retention by cohort, segment users by behaviour over time, or calculate lifetime value by acquisition period. Produces a complete cohort analysis framework with methodology, cohort definitions, retention curves, and prioritised interventions."
|
||||
---
|
||||
|
||||
# Cohort Analysis Skill
|
||||
|
||||
This skill produces a structured cohort analysis covering retention curves, LTV estimation, behavioural segmentation, and actionable interventions. Output is ready to present to product leadership or share with growth and data teams.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask the user for these if not provided:
|
||||
- **Analysis goal** (retention improvement / LTV modelling / behavioural segmentation / churn prediction)
|
||||
- **Product or feature being analysed**
|
||||
- **Cohort definition** — what groups users? (acquisition month, signup channel, plan tier, feature adoption)
|
||||
- **Observation window** — how many periods to track? (e.g. 12 months, 8 weeks)
|
||||
- **Key metric** — what are you measuring per cohort? (retention rate, revenue, engagement score, feature usage)
|
||||
- **Available data** — what tables/metrics are available? (paste schema or describe)
|
||||
- **Baseline** — any existing retention benchmarks or goals?
|
||||
|
||||
## Output Structure
|
||||
|
||||
---
|
||||
|
||||
# Cohort Analysis: [Product / Feature]
|
||||
|
||||
**Analysis type:** [Retention / LTV / Behavioural / Churn]
|
||||
**Cohort definition:** [Acquisition month / Signup channel / Plan tier / Feature adoption date]
|
||||
**Observation window:** [X months / weeks]
|
||||
**Primary metric:** [Metric name]
|
||||
**Date prepared:** [Date]
|
||||
|
||||
---
|
||||
|
||||
## 1. Cohort Definitions
|
||||
|
||||
| Cohort | Period | Size | Description |
|
||||
|---|---|---|---|
|
||||
| [Cohort 1] | [Jan 2025] | [N users] | [e.g. Users who signed up in Jan 2025 via organic] |
|
||||
| [Cohort 2] | [Feb 2025] | [N users] | [...] |
|
||||
|
||||
**Cohort logic:**
|
||||
- Cohort entry event: [First sign-up / First purchase / Feature activation]
|
||||
- Cohort exit criteria: [Churned / Downgraded / No activity for 30 days]
|
||||
- Exclusions: [Trial users / Internal test accounts / Users with < X days of data]
|
||||
|
||||
---
|
||||
|
||||
## 2. Retention Curve
|
||||
|
||||
**How to read:** Each cell shows what % of the cohort performed the key metric in period N.
|
||||
|
||||
| Cohort | Period 0 | Period 1 | Period 2 | Period 3 | Period 6 | Period 12 |
|
||||
|---|---|---|---|---|---|---|
|
||||
| Jan 2025 | 100% | [X%] | [X%] | [X%] | [X%] | [X%] |
|
||||
| Feb 2025 | 100% | [X%] | [X%] | [X%] | [X%] | [X%] |
|
||||
| [Trend] | — | [↑/↓ vs prior] | [...] | [...] | [...] | [...] |
|
||||
|
||||
**Retention plateau:** [At what period does retention flatten? What % does it flatten at?]
|
||||
|
||||
**Key observations:**
|
||||
- [e.g. Period 1 → Period 2 drop is the largest — average X% churn in first 30 days]
|
||||
- [e.g. Cohorts acquired via [channel] retain X% better at Period 6]
|
||||
- [e.g. Retention has improved from X% → Y% at Period 3 comparing oldest to newest cohort]
|
||||
|
||||
---
|
||||
|
||||
## 3. LTV Projection (if applicable)
|
||||
|
||||
**ARPU per period:** [£/$/€ X per active user per month]
|
||||
**Retention curve used:** [Which cohort or blended average]
|
||||
|
||||
| Period | Retained % | Revenue per user | Cumulative LTV |
|
||||
|---|---|---|---|
|
||||
| Month 1 | [X%] | [£X] | [£X] |
|
||||
| Month 3 | [X%] | [£X] | [£X] |
|
||||
| Month 6 | [X%] | [£X] | [£X] |
|
||||
| Month 12 | [X%] | [£X] | [£X] |
|
||||
|
||||
**Blended LTV:** [£X at 12 months — based on blended retention across cohorts]
|
||||
|
||||
**LTV by segment:**
|
||||
| Segment | LTV (12M) | vs Baseline |
|
||||
|---|---|---|
|
||||
| [Organic] | [£X] | [+X%] |
|
||||
| [Paid] | [£X] | [-X%] |
|
||||
| [Enterprise] | [£X] | [+X%] |
|
||||
|
||||
---
|
||||
|
||||
## 4. Behavioural Segmentation
|
||||
|
||||
Group cohorts by behaviour patterns, not just acquisition date:
|
||||
|
||||
| Segment | Definition | Size | Retention (P6) | LTV (12M) |
|
||||
|---|---|---|---|---|
|
||||
| **Power users** | [Used core feature ≥ 3x/week in first 30 days] | [X%] | [X%] | [£X] |
|
||||
| **Casual users** | [Used 1–2x/week in first 30 days] | [X%] | [X%] | [£X] |
|
||||
| **Dormant** | [Logged in but did not use core feature] | [X%] | [X%] | [£X] |
|
||||
| **Never activated** | [Signed up but never completed onboarding] | [X%] | [X%] | [£X] |
|
||||
|
||||
**Activation threshold insight:** [What action — taken within the first X days — most strongly predicts retention? This is the "aha moment" to optimise for.]
|
||||
|
||||
---
|
||||
|
||||
## 5. Leading Indicators of Churn
|
||||
|
||||
List the signals that appear **before** users churn, so teams can intervene:
|
||||
|
||||
| Signal | How early does it appear? | Churn correlation | Intervention |
|
||||
|---|---|---|---|
|
||||
| [No login for 7 days] | [7 days before churn] | [Strong] | [Re-engagement email sequence] |
|
||||
| [Support ticket with escalation] | [14 days before churn] | [Moderate] | [CSM outreach within 48 hours] |
|
||||
| [Feature usage dropped >50% WoW] | [10 days before churn] | [Strong] | [In-app nudge with use-case tutorial] |
|
||||
|
||||
---
|
||||
|
||||
## 6. Cohort Comparison: What's Changed Over Time
|
||||
|
||||
Compare oldest and newest cohorts to assess whether product improvements are showing up in retention:
|
||||
|
||||
| Metric | [Oldest cohort — e.g. Jan 2024] | [Newest cohort — e.g. Jan 2025] | Change |
|
||||
|---|---|---|---|
|
||||
| Period 1 retention | [X%] | [X%] | [↑/↓ X pp] |
|
||||
| Period 3 retention | [X%] | [X%] | [↑/↓ X pp] |
|
||||
| Activation rate | [X%] | [X%] | [↑/↓ X pp] |
|
||||
| Avg. sessions in first 30 days | [X] | [X] | [↑/↓] |
|
||||
|
||||
**Verdict:** [Are more recent cohorts performing better or worse? What shipped in that period that might explain the change?]
|
||||
|
||||
---
|
||||
|
||||
## 7. Recommendations
|
||||
|
||||
Prioritise by impact on retention curve:
|
||||
|
||||
| # | Recommendation | Target segment | Expected impact | Effort | Priority |
|
||||
|---|---|---|---|---|---|
|
||||
| 1 | [e.g. Redesign onboarding to hit activation milestone in day 1, not day 7] | [Never-activated segment] | [+X pp P1 retention] | [Medium] | P1 |
|
||||
| 2 | [e.g. Launch re-engagement sequence at day 7 inactivity trigger] | [Dormant segment] | [+X pp P2 retention] | [Low] | P1 |
|
||||
| 3 | [e.g. Introduce power-user features earlier to accelerate habit formation] | [Casual users] | [+X pp P6 LTV] | [High] | P2 |
|
||||
|
||||
---
|
||||
|
||||
## 8. SQL Reference (if applicable)
|
||||
|
||||
Provide the core cohort query so data teams can replicate or extend the analysis:
|
||||
|
||||
```sql
|
||||
-- Retention cohort query
|
||||
SELECT
|
||||
DATE_TRUNC('month', u.created_at) AS cohort_month,
|
||||
DATE_TRUNC('month', e.event_date) AS activity_month,
|
||||
DATEDIFF('month', u.created_at, e.event_date) AS period,
|
||||
COUNT(DISTINCT e.user_id) AS retained_users,
|
||||
COUNT(DISTINCT c.user_id) AS cohort_size,
|
||||
ROUND(COUNT(DISTINCT e.user_id) * 100.0 / COUNT(DISTINCT c.user_id), 1) AS retention_rate
|
||||
FROM users u
|
||||
JOIN events e ON u.user_id = e.user_id
|
||||
JOIN (
|
||||
SELECT user_id, DATE_TRUNC('month', created_at) AS cohort_month
|
||||
FROM users
|
||||
WHERE created_at >= '[start_date]'
|
||||
) c ON u.user_id = c.user_id AND DATE_TRUNC('month', u.created_at) = c.cohort_month
|
||||
WHERE e.event_type = '[key_retention_event]'
|
||||
GROUP BY 1, 2, 3
|
||||
ORDER BY 1, 3;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Cohort definition is unambiguous — the same user cannot appear in two cohorts
|
||||
- [ ] Retention curve shows a clear plateau, or the analysis notes that the window is too short to see one
|
||||
- [ ] LTV projection uses observed retention, not assumed
|
||||
- [ ] Behavioural segments are mutually exclusive and exhaustive
|
||||
- [ ] Recommendations are tied to specific cohort or segment findings — not generic growth advice
|
||||
- [ ] Leading indicators are observable in production data, not just in theory
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- "Run a cohort analysis for our SaaS product"
|
||||
- "Analyse retention by acquisition month for the last 12 cohorts"
|
||||
- "What's the LTV of users who came via paid vs organic?"
|
||||
- "Build a cohort retention model showing period 0 through period 12"
|
||||
- "Segment users by behaviour and show me which group retains best"
|
||||
@@ -0,0 +1,309 @@
|
||||
---
|
||||
name: community-management-playbook
|
||||
description: "Build a community management playbook for a brand's social media channels. Use when asked to create guidelines for managing comments, DMs, and community interactions, define a moderation policy, or build response frameworks for social media community managers. Produces a complete playbook with response templates, escalation paths, moderation rules, and tone guidelines."
|
||||
---
|
||||
|
||||
# Community Management Playbook Skill
|
||||
|
||||
This skill produces a complete community management playbook covering response frameworks, tone guidelines, comment moderation rules, DM handling, crisis and escalation paths, response templates, and community health metrics. Output gives a community manager or social media team everything they need to manage public interactions consistently, professionally, and at speed.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask the user for these if not provided:
|
||||
- **Brand / product name**
|
||||
- **Active platforms** — which channels need community management (Instagram, LinkedIn, X/Twitter, Facebook, TikTok, YouTube, Discord, Reddit, etc.)
|
||||
- **Team structure** — who manages community? (solo, small team, agency, rotating)
|
||||
- **Brand tone of voice** — how the brand sounds (e.g. warm and friendly / professional / witty / technical)
|
||||
- **Primary community type** — customers, fans, professional network, creators, users of a product
|
||||
- **Common comment types** — what kinds of interactions do you get? (support questions, complaints, praise, spam, trolls)
|
||||
- **Response time SLA** — how fast must the team respond? (e.g. within 2 hours on weekdays)
|
||||
|
||||
## Output Structure
|
||||
|
||||
---
|
||||
|
||||
# Community Management Playbook: [Brand Name]
|
||||
|
||||
**Version:** 1.0
|
||||
**Platforms covered:** [List]
|
||||
**Team:** [Names or roles]
|
||||
**Last updated:** [Date]
|
||||
|
||||
---
|
||||
|
||||
## 1. Why Community Management Matters
|
||||
|
||||
[2–3 sentences on what's at stake: brand reputation, customer loyalty, algorithm signals, trust-building. Frame community management as a business function, not just social admin.]
|
||||
|
||||
**Our community management goals:**
|
||||
1. [Goal 1: e.g. Respond to every comment and DM within our SLA — no question goes unanswered]
|
||||
2. [Goal 2: e.g. Turn complaints into loyalty moments — every resolved issue is a trust win]
|
||||
3. [Goal 3: e.g. Amplify positive sentiment — surface customer stories and user wins]
|
||||
4. [Goal 4: e.g. Protect brand reputation — remove harmful content quickly and consistently]
|
||||
|
||||
---
|
||||
|
||||
## 2. Response Framework
|
||||
|
||||
Use this decision tree for every comment or message:
|
||||
|
||||
```
|
||||
Is it spam, phishing, or dangerous content?
|
||||
→ YES: Delete immediately. Report if platform requires. Log in moderation tracker.
|
||||
→ NO: Continue ↓
|
||||
|
||||
Is it a hate comment, harassment, or offensive content?
|
||||
→ YES: Hide or delete. Consider account block. Escalate if ongoing. See Section 6.
|
||||
→ NO: Continue ↓
|
||||
|
||||
Is it a customer complaint or support question?
|
||||
→ YES: Respond within SLA. Acknowledge, empathise, resolve or redirect. See Section 4.
|
||||
→ NO: Continue ↓
|
||||
|
||||
Is it positive — praise, testimonial, or user win?
|
||||
→ YES: Like + reply with warm acknowledgement. Flag for social proof content if suitable.
|
||||
→ NO: Continue ↓
|
||||
|
||||
Is it a question about the brand, product, or content?
|
||||
→ YES: Answer clearly and helpfully. Include a CTA if relevant.
|
||||
→ NO: Continue ↓
|
||||
|
||||
Is it a general conversation starter or neutral engagement?
|
||||
→ YES: Engage authentically — like, reply briefly, or ask a follow-up question.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Response Time SLAs
|
||||
|
||||
| Channel | Comment type | Target response time | Owner |
|
||||
|---|---|---|---|
|
||||
| [Instagram] | Customer complaint | [2 hours (business hours)] | [CM Lead] |
|
||||
| [Instagram] | General comment / question | [Same day] | [CM team] |
|
||||
| [Instagram] | DM | [4 hours (business hours)] | [CM Lead] |
|
||||
| [LinkedIn] | Professional comment / question | [4 hours (business hours)] | [CM / Marketing] |
|
||||
| [X / Twitter] | Public reply / mention | [2 hours (business hours)] | [CM Lead] |
|
||||
| [X / Twitter] | DM | [4 hours (business hours)] | [CM team] |
|
||||
| [Facebook] | Comment | [4 hours (business hours)] | [CM team] |
|
||||
| [TikTok] | Comment on promoted post | [8 hours] | [CM team] |
|
||||
| [YouTube] | Comment | [24 hours] | [CM team] |
|
||||
|
||||
**Out-of-hours coverage:**
|
||||
- [Define weekend / evening coverage — e.g. "On-call CM checks mentions at 9am, 1pm, and 6pm on weekends"]
|
||||
- Crisis escalation is always on — see Section 6 for out-of-hours escalation contacts
|
||||
|
||||
---
|
||||
|
||||
## 4. Response Templates
|
||||
|
||||
These are starting-point templates — always personalise with the person's name and specific context.
|
||||
|
||||
### Positive comments
|
||||
|
||||
**Praise / testimonial:**
|
||||
> "Thank you so much, [name]! 🙌 This genuinely made our day. So glad [product/service] is working for you. [Add specific personal note if possible]."
|
||||
|
||||
**User-generated content / sharing their experience:**
|
||||
> "Love seeing this, [name]! Thanks for sharing 🙌. [Relevant genuine comment on their specific post or experience]."
|
||||
|
||||
**Review or recommendation:**
|
||||
> "Thank you for taking the time to share this, [name] — really appreciate it. [Add genuine specific reaction]. If you ever want to [next step / share more / join community], we'd love to have you."
|
||||
|
||||
---
|
||||
|
||||
### Questions about the product or brand
|
||||
|
||||
**Feature question:**
|
||||
> "Great question, [name]! [Answer clearly in 1–3 sentences]. If you'd like more detail, [link to docs / help centre / DM us]. Happy to help with anything else!"
|
||||
|
||||
**Pricing / availability question:**
|
||||
> "[Answer] — [link if relevant]. Feel free to DM us if you need anything specific. 😊"
|
||||
|
||||
**"Is this available in [region/format]?" question:**
|
||||
> "[Answer with current availability]. If that's changed, you'll always see it first at [link / newsletter sign-up / our channels]. 🙌"
|
||||
|
||||
---
|
||||
|
||||
### Complaints
|
||||
|
||||
**Product issue — acknowledged, redirecting to support:**
|
||||
> "Hi [name], really sorry to hear this — that's definitely not the experience we want for you. 😔 Could you DM us with [order number / account email / details]? We'll get this sorted as quickly as possible."
|
||||
|
||||
**Shipping / fulfilment complaint:**
|
||||
> "Hi [name], thank you for letting us know and I'm so sorry for this. We want to make it right. Please DM us with your order reference and we'll investigate right away."
|
||||
|
||||
**General dissatisfaction:**
|
||||
> "Hi [name], I'm sorry to hear you're not happy — your feedback genuinely matters to us. Could you DM us or email [support email] so we can understand what happened and fix it? We really do want to get this right."
|
||||
|
||||
**Public complaint that needs urgent attention:**
|
||||
> "Hi [name], I can see why that would be frustrating and I want to make sure we sort this out properly. I'm going to DM you now — please look out for a message from us."
|
||||
|
||||
---
|
||||
|
||||
### Difficult interactions
|
||||
|
||||
**Polite but persistent critic:**
|
||||
> "Hi [name], thank you for the honest feedback — we do read and take this seriously. We can't always respond to every individual point publicly, but if you'd like to share more detail, [DM us / email us at X]. We're genuinely working on [relevant area] and appreciate you holding us accountable."
|
||||
|
||||
**Misinformation or incorrect claim about the brand:**
|
||||
> "Hi [name], just wanted to gently clarify — [correct the record factually in 1–2 sentences]. Happy to share more if useful! [Link to source / official page if relevant]."
|
||||
|
||||
**Competitor attack or negative comparison:**
|
||||
> [Do NOT engage publicly with competitive comparisons. Respond only if there's factual misinformation. Template: "Hi [name], happy to share what makes [brand] work for our customers — feel free to DM us if you'd like to know more."]
|
||||
|
||||
---
|
||||
|
||||
### DM templates
|
||||
|
||||
**First DM response — complaint:**
|
||||
> "Hi [name], thanks for reaching out. I'm [name] from the [brand] team. I've seen your [comment/message] and want to make sure we get this sorted for you properly. Could you share [details needed — order number, email, screenshots]? I'll personally make sure this is resolved."
|
||||
|
||||
**First DM response — support question:**
|
||||
> "Hi [name]! Thanks for getting in touch. Happy to help — [answer or next step]. If you need anything else, just reply here. 😊"
|
||||
|
||||
**Issue resolved — closing DM:**
|
||||
> "Glad we could sort that out, [name]! If you ever need anything else, we're here. Have a great [day/weekend]! 🙌"
|
||||
|
||||
---
|
||||
|
||||
## 5. Moderation Rules
|
||||
|
||||
**Content that must be deleted immediately:**
|
||||
- [ ] Spam (repeated posts, fake giveaways, phishing links)
|
||||
- [ ] Explicit or NSFW content
|
||||
- [ ] Personal attacks on other community members
|
||||
- [ ] Doxxing (sharing personal information about another person)
|
||||
- [ ] Content that violates platform terms of service
|
||||
- [ ] Illegal content or illegal product promotion
|
||||
|
||||
**Content that should be hidden (not deleted) — review within 4 hours:**
|
||||
- [ ] Unverified complaints that may require investigation before action
|
||||
- [ ] Offensive language that isn't targeting a specific person
|
||||
- [ ] Posts that may be legitimate but contain sensitive information
|
||||
|
||||
**Content that should be left (even if negative) — respond and monitor:**
|
||||
- [ ] Genuine product criticism or negative reviews
|
||||
- [ ] Complaints that are being actively resolved
|
||||
- [ ] Controversial opinions that are within the rules of civil debate
|
||||
- [ ] Negative comparisons to competitors (only respond if misinformation)
|
||||
|
||||
**Account-level actions:**
|
||||
|
||||
| Action | When to use |
|
||||
|---|---|
|
||||
| Comment hide | First instance of borderline content |
|
||||
| Comment delete | Clear rule violation |
|
||||
| User block | Repeated harassment / spam after warning |
|
||||
| Report to platform | Content that may breach platform T&Cs or laws |
|
||||
|
||||
**"Never delete to silence" rule:** Never delete a genuine complaint or criticism just because it's uncomfortable. Deleting legitimate negative feedback damages trust more than the original complaint.
|
||||
|
||||
---
|
||||
|
||||
## 6. Escalation & Crisis Protocol
|
||||
|
||||
### Escalation tiers
|
||||
|
||||
**Tier 1 — CM handles directly:**
|
||||
- Routine complaints, questions, thank-yous
|
||||
- Single negative comment, isolated incident
|
||||
- Standard off-topic or mildly unhappy comment
|
||||
|
||||
**Tier 2 — Escalate to [Marketing Lead / Brand Manager] within 2 hours:**
|
||||
- Customer with significant public platform (journalist, influencer, known figure)
|
||||
- Complaint gaining traction (10+ likes on a negative comment)
|
||||
- Legal or compliance mention ("I'm going to sue", "trading standards", "data breach")
|
||||
- Media interest — journalist asking questions publicly
|
||||
|
||||
**Tier 3 — Escalate to [CMO / Founder / CEO] immediately:**
|
||||
- Viral negative content (100+ shares / views growing rapidly)
|
||||
- Allegation of safety issue, injury, or product harm
|
||||
- Coordinated negative campaign or pile-on
|
||||
- Any media coverage of a complaint
|
||||
- Potential crisis — brand reputation at risk
|
||||
|
||||
### Crisis response protocol
|
||||
|
||||
1. **Stop scheduled posting** — pause all queued content immediately
|
||||
2. **Assess** — what is the scope? How fast is it spreading? What's the allegation?
|
||||
3. **Brief leadership** — share screenshot, link, and initial assessment within 30 minutes
|
||||
4. **Hold public response** — do not post publicly until leadership approves messaging
|
||||
5. **Draft response options** — prepare 2–3 response options (acknowledge / deny / defer)
|
||||
6. **Respond or don't respond?** — sometimes silence + private resolution beats a public statement
|
||||
7. **Monitor** — track mentions every 30 minutes during a crisis
|
||||
8. **Post-crisis review** — within 48 hours, document what happened and what to do differently
|
||||
|
||||
**Out-of-hours escalation contacts:**
|
||||
- CM Lead: [Name, mobile]
|
||||
- Marketing Lead: [Name, mobile]
|
||||
- [Senior escalation]: [Name, mobile]
|
||||
|
||||
---
|
||||
|
||||
## 7. Tone of Voice in Practice
|
||||
|
||||
| Situation | Tone | Example phrase | Avoid |
|
||||
|---|---|---|---|
|
||||
| Complimenting content | Warm, genuine, specific | "This genuinely made our day 🙌" | Generic "Thank you!" |
|
||||
| Answering a product question | Helpful, clear, not jargony | "Great question — here's exactly how it works…" | "Per our FAQs…" |
|
||||
| Resolving a complaint | Empathetic, responsible, action-oriented | "Really sorry to hear this — let's sort it out." | "This is not our fault" |
|
||||
| Engaging with light content | Playful, natural, on-brand | [Match the energy of the post — don't be stiff] | Corporate speak |
|
||||
| Handling criticism | Measured, honest, not defensive | "We hear you and we're working on it." | "As per our T&Cs…" |
|
||||
| Addressing a crisis | Calm, clear, factual, empathetic | "We're aware of this and are treating it as an urgent priority." | Defensive or dismissive |
|
||||
|
||||
**Emoji use:** [Define brand's emoji policy — e.g. "Use emojis sparingly — 1 per response max, only on positive interactions. Never on complaints or sensitive topics."]
|
||||
|
||||
---
|
||||
|
||||
## 8. Community Health Metrics
|
||||
|
||||
Track these weekly:
|
||||
|
||||
| Metric | What it measures | Target | Current |
|
||||
|---|---|---|---|
|
||||
| Average response time | Speed of community management | [≤ X hours] | [X hours] |
|
||||
| Response rate | % of comments/DMs replied to | [≥ X%] | [X%] |
|
||||
| Comment sentiment ratio | Positive : Neutral : Negative split | [≥ X% positive] | [X%] |
|
||||
| Escalation rate | % of interactions escalated | [≤ X%] | [X%] |
|
||||
| DM resolution time | Time to resolve a DM complaint | [≤ X hours] | [X hours] |
|
||||
| Content reports / removals | Volume of content moderated | [Track trend] | [X/week] |
|
||||
|
||||
**Weekly CM review (15 min):**
|
||||
- Review last week's metrics vs target
|
||||
- Flag any recurring complaint themes (product signals for the team)
|
||||
- Identify any standout positive interactions worth amplifying
|
||||
- Note any escalations and how they were handled
|
||||
|
||||
---
|
||||
|
||||
## 9. Platform-Specific Notes
|
||||
|
||||
| Platform | Key nuance | Best practice |
|
||||
|---|---|---|
|
||||
| **Instagram** | Comments move fast on Reels; DMs high volume | Prioritise Reel comments; use saved replies for FAQ DMs |
|
||||
| **LinkedIn** | Professional audience; public replies visible to networks | Keep responses professional; avoid humour on complaints |
|
||||
| **X / Twitter** | Real-time; pile-ons escalate fast | Monitor with keyword alerts; act on Tier 2 triggers quickly |
|
||||
| **TikTok** | Comment culture is more casual; meme responses ok | Match platform tone but keep brand voice; don't try too hard |
|
||||
| **YouTube** | Older comments resurface regularly | Monitor new comments on older videos; set up notifications |
|
||||
| **Facebook** | Groups + page comments; older audience | More formal tone; monitor group dynamics separately |
|
||||
| **Discord** | Real-time community; requires moderators | Designate community moderators; publish community rules prominently |
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Response templates cover all common scenarios (positive, neutral, complaint, crisis)
|
||||
- [ ] SLAs are realistic for available team resource
|
||||
- [ ] Moderation rules clearly distinguish between delete, hide, and leave
|
||||
- [ ] Escalation tiers are specific — each tier has a named contact and timeframe
|
||||
- [ ] Tone of voice guidance is concrete enough to write from (examples included)
|
||||
- [ ] Community health metrics have targets, not just labels
|
||||
- [ ] Platform-specific nuances are covered for every active channel
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- "Build a community management playbook for [brand]"
|
||||
- "Create social media response guidelines for our team"
|
||||
- "What should our moderation policy be for [platform]?"
|
||||
- "Write community management templates and escalation procedures"
|
||||
- "How should we handle negative comments on social media?"
|
||||
@@ -0,0 +1,248 @@
|
||||
---
|
||||
name: context-mode
|
||||
description: "Activate output filtering, session logging, and auto-resume to keep Claude Code sessions running for hours without context bloat or memory loss. Use when asked to enable context mode, turn on long session mode, or activate session persistence. Installs a session log at project root, filters verbose command output before it enters context, and auto-resumes after Claude resets."
|
||||
---
|
||||
|
||||
# Context Mode Skill
|
||||
|
||||
Fix the two session killers that end most Claude Code sessions in under 30 minutes: context bloat from raw command output, and memory loss after a reset.
|
||||
|
||||
Context Mode runs three systems simultaneously to keep sessions alive:
|
||||
|
||||
- **Output Filtering** — strips verbose command output before it enters context
|
||||
- **Session Log** — writes a running log of everything that happened
|
||||
- **Auto-Resume** — reads the log on reset and picks up exactly where you left off
|
||||
|
||||
> **Credit:** Inspired by a skill from Nate Herk's YouTube channel — adapted and extended for this library.
|
||||
|
||||
---
|
||||
|
||||
## Required Inputs
|
||||
|
||||
No inputs required. Context Mode activates on command.
|
||||
|
||||
Optional: user can specify a custom log file path if they don't want `session.log` in the project root.
|
||||
|
||||
---
|
||||
|
||||
## How Context Mode Works
|
||||
|
||||
### Part 1 — Output Filtering
|
||||
|
||||
The problem: every time Claude Code runs a command, the full raw output enters the context window. A single `npm install` can dump hundreds of lines. A test suite run? Thousands. Within 30 minutes, the context is full of noise and Claude resets.
|
||||
|
||||
The fix: before any command output enters context, filter it to the useful summary only.
|
||||
|
||||
**What gets kept:**
|
||||
- Last 10 lines of stdout
|
||||
- Every line containing `error`, `warn`, `fail`, `exception`, `traceback`, or `fatal` (case-insensitive)
|
||||
- The exit code
|
||||
- A one-line summary of what the command did and whether it succeeded
|
||||
|
||||
**What gets discarded:**
|
||||
- Middle section of long stdout (replaced with `[... N lines of output truncated ...]`)
|
||||
- Progress bars, download indicators, verbose install logs
|
||||
- Repeated identical lines (deduplicated)
|
||||
|
||||
**Filtering summary format:**
|
||||
|
||||
```
|
||||
COMMAND: [command run]
|
||||
STATUS: [exit code — success / failed]
|
||||
SUMMARY: [one sentence: what happened]
|
||||
ERRORS: [any error/warn lines — or "none"]
|
||||
TAIL: [last 10 lines of stdout]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Part 2 — Session Log
|
||||
|
||||
Claude maintains a running log file at `[project root]/session.log`. This file is written after every significant action and is the source of truth for resuming after a reset.
|
||||
|
||||
**Session log format:**
|
||||
|
||||
```
|
||||
SESSION LOG
|
||||
===========
|
||||
Started: [timestamp]
|
||||
Branch: [current git branch]
|
||||
Directory: [working directory]
|
||||
|
||||
FILES EDITED
|
||||
────────────
|
||||
[timestamp] [file path] — [one-line description of what changed]
|
||||
|
||||
COMMANDS RUN
|
||||
────────────
|
||||
[timestamp] [command] — [outcome: success / failed — brief reason]
|
||||
|
||||
TASKS IN PROGRESS
|
||||
─────────────────
|
||||
[ ] [Task description — what's been done so far and what's left]
|
||||
[x] [Completed task]
|
||||
|
||||
LAST USER PROMPT
|
||||
────────────────
|
||||
[The most recent instruction from the user, verbatim]
|
||||
|
||||
LAST ACTION TAKEN
|
||||
─────────────────
|
||||
[What Claude did last, in one sentence]
|
||||
```
|
||||
|
||||
**Log update rules:**
|
||||
- Write to `session.log` after every file edit
|
||||
- Write to `session.log` after every command run
|
||||
- Update "Tasks in Progress" when a task is started, progressed, or completed
|
||||
- Always overwrite "Last User Prompt" and "Last Action Taken" with the current values — don't append, replace
|
||||
|
||||
---
|
||||
|
||||
### Part 3 — Resume on Reset
|
||||
|
||||
When a new Claude session starts, the first action is:
|
||||
|
||||
1. Check for `session.log` in the project root
|
||||
2. If found, read it and announce the resume:
|
||||
|
||||
```
|
||||
Resuming session.
|
||||
|
||||
Branch: [branch]
|
||||
Last working on: [last task in progress]
|
||||
Files edited: [list from session log]
|
||||
Tasks pending: [incomplete tasks]
|
||||
Last prompt: "[last user prompt]"
|
||||
|
||||
Continuing from where we left off.
|
||||
```
|
||||
|
||||
3. Continue with the next logical step — don't ask "what should I do?" — check the task list and carry on
|
||||
|
||||
If no `session.log` exists, start fresh and initialise the log.
|
||||
|
||||
---
|
||||
|
||||
## Activation Response
|
||||
|
||||
When the user triggers Context Mode, respond with:
|
||||
|
||||
```
|
||||
Context Mode active.
|
||||
|
||||
Session log initialised at: [absolute path to session.log]
|
||||
Output filtering: enabled
|
||||
Auto-resume: enabled
|
||||
|
||||
I'll maintain your session state across resets. Long sessions won't lose context.
|
||||
```
|
||||
|
||||
Then immediately initialise `session.log` with the current timestamp, branch, and directory.
|
||||
|
||||
---
|
||||
|
||||
## Output Structure
|
||||
|
||||
### On activation
|
||||
|
||||
```
|
||||
Context Mode active.
|
||||
Session log initialised at: [path]
|
||||
Output filtering: enabled
|
||||
Auto-resume: enabled
|
||||
I'll maintain your session state across resets. Long sessions won't lose context.
|
||||
```
|
||||
|
||||
### On command execution (filtered output format)
|
||||
|
||||
```
|
||||
COMMAND: npm test
|
||||
STATUS: exit 1 — failed
|
||||
SUMMARY: 47 tests passed, 3 failed in auth.test.ts
|
||||
ERRORS: Error: Expected 200, received 401 (line 84)
|
||||
Error: Token not found in response (line 112)
|
||||
TAIL:
|
||||
✓ login with valid credentials (23ms)
|
||||
✓ logout clears session (11ms)
|
||||
✗ refresh token after expiry
|
||||
...
|
||||
```
|
||||
|
||||
### On reset / new session (resume announcement)
|
||||
|
||||
```
|
||||
Resuming session.
|
||||
|
||||
Branch: feature/auth-refresh
|
||||
Last working on: Fixing token refresh logic in auth.service.ts
|
||||
Files edited: src/auth/auth.service.ts, src/auth/auth.test.ts
|
||||
Tasks pending: [ ] Fix failing test on line 112
|
||||
[ ] Run full test suite once fix is applied
|
||||
Last prompt: "The refresh token test is still failing — look at the 401 handling"
|
||||
|
||||
Continuing from where we left off.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## CLAUDE.md Installation Text
|
||||
|
||||
After activating Context Mode for the session, provide the user with the exact text to add to their `CLAUDE.md` to make it permanent across all sessions:
|
||||
|
||||
````
|
||||
```
|
||||
## Context Mode
|
||||
|
||||
Context Mode is always active in this project.
|
||||
|
||||
### Output Filtering
|
||||
Before any command output enters context, filter it to:
|
||||
- Last 10 lines of stdout
|
||||
- Any lines containing: error, warn, fail, exception, traceback, fatal (case-insensitive)
|
||||
- Exit code
|
||||
- One-line summary of what the command did
|
||||
|
||||
Use this format for filtered output:
|
||||
COMMAND: [command]
|
||||
STATUS: [exit code — success/failed]
|
||||
SUMMARY: [one sentence]
|
||||
ERRORS: [error lines or "none"]
|
||||
TAIL: [last 10 lines]
|
||||
|
||||
### Session Log
|
||||
Maintain a running session log at ./session.log. Write to it after every file edit and every command run. Track: files edited, commands run, tasks in progress, last user prompt, last action taken. Format defined in Context Mode skill.
|
||||
|
||||
### Auto-Resume
|
||||
At the start of every new session, check for ./session.log. If it exists, read it and announce the resume state. Continue from the last task in progress without asking for instructions.
|
||||
```
|
||||
````
|
||||
|
||||
Tell the user: "Add this to your CLAUDE.md and Context Mode will be active permanently for this project — even after you close and reopen the session."
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] `session.log` was initialised immediately on activation (not deferred)
|
||||
- [ ] Log path shown to user is the absolute path, not relative
|
||||
- [ ] Output filtering is applied on the very next command run — not just announced
|
||||
- [ ] Filtered output format includes: command, status, summary, errors, and tail — all five fields
|
||||
- [ ] Session log tracks all four categories: files edited, commands run, tasks in progress, last prompt
|
||||
- [ ] Resume announcement reads the actual log contents — not a generic template
|
||||
- [ ] On resume, Claude continues the work without prompting the user for instructions
|
||||
- [ ] CLAUDE.md installation text was offered after activation
|
||||
- [ ] Log update rule is clear: "Last User Prompt" and "Last Action Taken" replace previous values, not append
|
||||
|
||||
---
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- "Enable context mode"
|
||||
- "Turn on context mode for this session"
|
||||
- "Activate long session mode"
|
||||
- "I keep losing context — fix it"
|
||||
- "Set up session logging"
|
||||
- "Keep track of what you've done so you can resume after a reset"
|
||||
- "Enable output filtering to save context"
|
||||
- "Set up auto-resume so we don't lose our place"
|
||||
@@ -0,0 +1,215 @@
|
||||
---
|
||||
name: customer-journey-map
|
||||
description: "Build a customer journey map for a product, service, or experience. Use when asked to map a customer journey, create a user journey, document touchpoints and pain points, or design an experience map. Produces a complete journey map with stages, touchpoints, emotions, pain points, and prioritised opportunities."
|
||||
---
|
||||
|
||||
# Customer Journey Map Skill
|
||||
|
||||
This skill produces a complete customer journey map covering every stage from awareness through advocacy. Each stage includes touchpoints, customer actions, emotions, pain points, and specific improvement opportunities. Output is ready for use in product discovery, UX design, or cross-functional alignment workshops.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask the user for these if not provided:
|
||||
- **Product or service** being mapped
|
||||
- **Customer persona** — which customer segment is this map for? (be specific — one persona per map)
|
||||
- **Journey scope** — full end-to-end (awareness → advocacy), or a specific phase (e.g. onboarding only)?
|
||||
- **Current state or future state?** — mapping how it works today, or designing how it should work?
|
||||
- **Data sources** — any research, user interviews, support tickets, NPS comments, analytics available?
|
||||
- **Goal of the map** — what decision will this inform? (redesign, prioritisation, stakeholder alignment, new feature)
|
||||
|
||||
## Output Structure
|
||||
|
||||
---
|
||||
|
||||
# Customer Journey Map: [Product / Service]
|
||||
|
||||
**Persona:** [Name — e.g. "Sarah, the overwhelmed HR manager"]
|
||||
**Journey scope:** [Full end-to-end / Onboarding / Purchase / Renewal]
|
||||
**Current or future state:** [Current state / Desired future state]
|
||||
**Prepared by:** [Name / Team]
|
||||
**Date:** [Date]
|
||||
**Based on:** [Research sources — interviews, analytics, support data, assumed/hypothetical]
|
||||
|
||||
---
|
||||
|
||||
## Persona Summary
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| **Name** | [Sarah] |
|
||||
| **Role** | [HR Manager at a 200-person professional services firm] |
|
||||
| **Goal** | [Reduce time spent on manual employee data management] |
|
||||
| **Frustrations** | [Too many tools that don't talk to each other; always chasing approvals] |
|
||||
| **Tech comfort** | [Moderate — comfortable with SaaS tools but not a power user] |
|
||||
| **Decision power** | [Recommends tools; budget approved by CHRO] |
|
||||
|
||||
---
|
||||
|
||||
## Journey Overview
|
||||
|
||||
```
|
||||
AWARENESS → CONSIDERATION → DECISION → ONBOARDING → ADOPTION → ADVOCACY
|
||||
[Stage 1] [Stage 2] [Stage 3] [Stage 4] [Stage 5] [Stage 6]
|
||||
```
|
||||
|
||||
**Overall experience rating (current state):** [😤 Frustrating / 😐 Neutral / 😊 Positive]
|
||||
|
||||
---
|
||||
|
||||
## Stage 1: Awareness
|
||||
|
||||
*How does the customer first discover the product exists?*
|
||||
|
||||
**Customer goal at this stage:** [e.g. Realise they have a problem worth solving — or find a solution to a specific pain]
|
||||
|
||||
| Element | Detail |
|
||||
|---|---|
|
||||
| **Trigger** | [What event makes them start looking? — e.g. Manual process breaks down / peer recommendation / saw ad] |
|
||||
| **Where they are** | [Google search / LinkedIn / conference / colleague conversation / email newsletter] |
|
||||
| **What they do** | [e.g. Searches "automate employee onboarding" / asks peers in HR community / clicks LinkedIn ad] |
|
||||
| **Emotion** | [😤 Frustrated — overwhelmed by manual processes and hoping for a better way] |
|
||||
| **Pain points** | [Overwhelming number of options / hard to know which tools are credible / can't tell what's B2B vs B2C from homepage] |
|
||||
| **Opportunities** | [SEO content targeting the trigger keyword / LinkedIn thought leadership / peer community presence] |
|
||||
|
||||
---
|
||||
|
||||
## Stage 2: Consideration
|
||||
|
||||
*The customer is actively evaluating options. What do they do to decide?*
|
||||
|
||||
| Element | Detail |
|
||||
|---|---|
|
||||
| **Customer goal** | [Narrow down from many options to a shortlist of 2–3] |
|
||||
| **What they do** | [Reads G2/Capterra reviews / watches demo video / downloads comparison guide / asks peers who use something similar] |
|
||||
| **Touchpoints** | [Website / review sites / social proof / demo request flow / sales email] |
|
||||
| **Emotion** | [😕 Anxious — worried about making the wrong choice; past tool purchases haven't delivered] |
|
||||
| **Pain points** | [Pricing not visible on website / demo requires a call before seeing the product / unclear if it works with their existing stack] |
|
||||
| **Opportunities** | [Self-serve demo or interactive product tour / transparent pricing page / ROI calculator / case studies from similar company size] |
|
||||
|
||||
---
|
||||
|
||||
## Stage 3: Decision
|
||||
|
||||
*The customer is ready to buy — or not. What makes them commit?*
|
||||
|
||||
| Element | Detail |
|
||||
|---|---|
|
||||
| **Customer goal** | [Get sign-off from CHRO and justify the decision with a business case] |
|
||||
| **What they do** | [Books sales call / requests security questionnaire / builds internal business case / negotiates contract] |
|
||||
| **Touchpoints** | [AE / sales call / security review / contract / procurement process] |
|
||||
| **Emotion** | [😬 Cautious — doesn't want to be wrong; presenting to leadership adds pressure] |
|
||||
| **Pain points** | [Sales process is slow / security questionnaire takes weeks / contract terms are non-standard and require legal] |
|
||||
| **Opportunities** | [Security FAQ self-serve / standard contract with predictable terms / champion toolkit (slides, business case template) to help them sell internally] |
|
||||
|
||||
---
|
||||
|
||||
## Stage 4: Onboarding
|
||||
|
||||
*The customer has bought. Now they need to get value fast.*
|
||||
|
||||
| Element | Detail |
|
||||
|---|---|
|
||||
| **Customer goal** | [Get the product working and show their CHRO it was a good decision] |
|
||||
| **What they do** | [Receives welcome email / attends kickoff call / configures integrations / invites team] |
|
||||
| **Touchpoints** | [Onboarding email sequence / in-product onboarding checklist / CSM / help centre / integrations marketplace] |
|
||||
| **Emotion** | [😬 Anxious but hopeful — excited about potential but stressed about the setup work] |
|
||||
| **Pain points** | [Setup is more complex than expected / IT required for SSO but IT is slow to respond / generic onboarding doesn't match their use case] |
|
||||
| **Opportunities** | [Role-specific onboarding paths / IT connector with pre-filled request template / quick win email at day 3 (show them one thing that already works)] |
|
||||
|
||||
**Key moment of truth:** [What single moment in this stage determines whether they'll become an active user or ghost? — e.g. "First time the product saves them 30 minutes on a task they used to do manually"]
|
||||
|
||||
---
|
||||
|
||||
## Stage 5: Adoption
|
||||
|
||||
*The customer is using the product. Are they getting consistent value?*
|
||||
|
||||
| Element | Detail |
|
||||
|---|---|
|
||||
| **Customer goal** | [Make the product a regular part of their workflow; demonstrate ROI to leadership] |
|
||||
| **What they do** | [Uses core features daily / discovers new features / hits a limitation / contacts support / attends webinar] |
|
||||
| **Touchpoints** | [Product UI / in-app notifications / email / support / community / customer success manager] |
|
||||
| **Emotion** | [Variable — some days 😊 when the product works well; some days 😤 when hitting a gap or bug] |
|
||||
| **Pain points** | [Feature they expected isn't there / reporting doesn't show the metric leadership wants / power features are too complex / feels like they're underutilising what they're paying for] |
|
||||
| **Opportunities** | [Proactive CSM check-in at day 30 / in-product feature discovery / usage dashboard for the customer to see their own ROI / community for peer learning] |
|
||||
|
||||
**Adoption health indicators:**
|
||||
- [DAU/MAU ratio — what does healthy look like?]
|
||||
- [Feature X used by Y% of seats within Z weeks]
|
||||
- [First NPS survey at 60 days — target score]
|
||||
|
||||
---
|
||||
|
||||
## Stage 6: Advocacy
|
||||
|
||||
*The customer loves the product. How do you turn them into a referral engine?*
|
||||
|
||||
| Element | Detail |
|
||||
|---|---|
|
||||
| **Customer goal** | [Solve problems faster; feel like an expert; feel valued as a customer] |
|
||||
| **What they do** | [Refers a peer / writes a G2 review / participates in case study / speaks at event / becomes a power user / joins community] |
|
||||
| **Touchpoints** | [CSM / community / review request email / referral programme / case study outreach / conference sponsorship] |
|
||||
| **Emotion** | [😊 Proud — the tool is part of their professional identity; they feel smart for choosing it] |
|
||||
| **Pain points** | [Referral programme is clunky / no structured way to connect with peers / case study process is slow and effortful for them] |
|
||||
| **Opportunities** | [One-click G2 review request at high-satisfaction moment / peer community / referral programme with meaningful reward / case study process that does most of the work for them] |
|
||||
|
||||
---
|
||||
|
||||
## Emotion Curve
|
||||
|
||||
Plot the customer's emotional experience across the journey:
|
||||
|
||||
```
|
||||
High 😊 │ * * *
|
||||
│ *
|
||||
Neutral 😐│ * *
|
||||
│ *
|
||||
Low 😤 │ * *
|
||||
└────────────────────────────────────────────────────
|
||||
Aware Consider Decide Onboard Adopt Advocate
|
||||
```
|
||||
|
||||
**Lowest point:** [Which stage has the worst experience — and why?]
|
||||
**Highest point:** [When is the customer most delighted — what drove it?]
|
||||
**Biggest drop:** [Where does sentiment fall most sharply — this is usually the biggest opportunity]
|
||||
|
||||
---
|
||||
|
||||
## Prioritised Opportunities
|
||||
|
||||
| Opportunity | Stage | Impact on customer | Effort to fix | Priority |
|
||||
|---|---|---|---|---|
|
||||
| [Self-serve product tour before sales call] | Consideration | [High — removes top buying barrier] | [Medium] | P1 |
|
||||
| [Quick win email at day 3] | Onboarding | [High — builds early habit] | [Low] | P1 |
|
||||
| [IT SSO setup template] | Onboarding | [Medium — removes specific blocker] | [Low] | P2 |
|
||||
| [30-day proactive CSM check-in] | Adoption | [Medium — catches churn signals early] | [Medium] | P2 |
|
||||
| [Peer referral programme] | Advocacy | [High for growth — reduces CAC] | [High] | P3 |
|
||||
|
||||
---
|
||||
|
||||
## What We Don't Know (Research Gaps)
|
||||
|
||||
| Gap | How to close it | Priority |
|
||||
|---|---|---|
|
||||
| [What actually triggers the decision to start looking?] | [5 JTBD interviews with recent buyers] | [High] |
|
||||
| [What causes customers to stall in onboarding?] | [Drop-off analysis in onboarding funnel + 3 interviews with churned customers] | [High] |
|
||||
| [What % of customers have reached the advocacy stage?] | [Product analytics — identify power users; NPS by cohort] | [Medium] |
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Map covers one specific persona — not "all customers"
|
||||
- [ ] Each stage includes the customer's emotional state — not just actions
|
||||
- [ ] Pain points are the customer's pain — not the company's pain
|
||||
- [ ] Opportunities are specific enough to become backlog items or design prompts
|
||||
- [ ] Emotion curve shows the real experience — not an aspirationally positive version
|
||||
- [ ] Research gaps are documented — the map reflects what is known, not assumed
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- "Map the customer journey for [product]"
|
||||
- "Build a user journey from awareness to advocacy"
|
||||
- "Create a journey map for our onboarding experience"
|
||||
- "Map out the touchpoints and pain points for [customer type]"
|
||||
- "Design an experience map for [process or product]"
|
||||
@@ -0,0 +1,192 @@
|
||||
---
|
||||
name: customer-success-plan
|
||||
description: "Build a joint customer success plan for a specific account. Use when asked to create a success plan, joint success plan, mutual action plan, or customer onboarding plan. Produces a structured success plan with business goals, milestones, success metrics, ownership, and a 90-180 day roadmap."
|
||||
---
|
||||
|
||||
# Customer Success Plan Skill
|
||||
|
||||
This skill produces a joint customer success plan — a living document shared between the CSM and the customer that aligns on outcomes, milestones, and mutual commitments. Output is ready to co-author with the customer in a kickoff call or QBR.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask the user for these if not provided:
|
||||
- **Account name** and industry
|
||||
- **Product / plan purchased**
|
||||
- **Key stakeholders** — customer champion and economic buyer
|
||||
- **Customer's stated business goals** — why did they buy? What problem are they solving?
|
||||
- **Contract term and renewal date**
|
||||
- **Current onboarding stage** (new customer / expanding / post-QBR / pre-renewal)
|
||||
- **Seats / licenses / usage purchased**
|
||||
- **Any known risks** — adoption gaps, champion uncertainty, competing priorities
|
||||
|
||||
## Output Structure
|
||||
|
||||
---
|
||||
|
||||
# Customer Success Plan: [Account Name]
|
||||
|
||||
**Product:** [Product name / plan tier]
|
||||
**Contract term:** [Start date → Renewal date]
|
||||
**CSM:** [Name]
|
||||
**Customer champion:** [Name, Title]
|
||||
**Customer executive sponsor:** [Name, Title — if known]
|
||||
**Last updated:** [Date]
|
||||
**Status:** [Active / Under review / Completed]
|
||||
|
||||
---
|
||||
|
||||
## 1. Partnership Objectives
|
||||
|
||||
> *What does success look like for [Account Name] at contract end?*
|
||||
|
||||
[Write 2–3 sentences describing the customer's core objective in plain English — what they are trying to achieve in their business, not what features they are using.]
|
||||
|
||||
**Primary business goal:** [e.g. Reduce time-to-hire by 30% across engineering teams]
|
||||
**Secondary goal:** [e.g. Consolidate three legacy tools into one platform, saving £X/year]
|
||||
**Success statement (customer's words):** "[Direct quote from champion about what success looks like — ask for this in kickoff]"
|
||||
|
||||
---
|
||||
|
||||
## 2. Success Metrics
|
||||
|
||||
Define how both parties will measure success. Agreed in the kickoff call and tracked in QBRs.
|
||||
|
||||
| Metric | Baseline (today) | Target | By when | Data source |
|
||||
|---|---|---|---|---|
|
||||
| [e.g. Seat utilisation] | [X%] | [≥ 80%] | [Month 3] | [Product analytics] |
|
||||
| [e.g. Time to hire] | [X days] | [< Y days] | [Month 6] | [Customer's ATS] |
|
||||
| [e.g. Reports produced/month] | [X] | [≥ Y] | [Month 3] | [Product analytics] |
|
||||
| [e.g. NPS] | [X] | [≥ 8] | [Month 6] | [Quarterly survey] |
|
||||
|
||||
**Leading indicators** (early signs the plan is on track):
|
||||
- [e.g. 5+ users log in within the first 2 weeks]
|
||||
- [e.g. First workflow automated within 30 days]
|
||||
- [e.g. Champion presents the tool to their team by end of Month 1]
|
||||
|
||||
---
|
||||
|
||||
## 3. Milestone Roadmap
|
||||
|
||||
Break the success journey into phases with clear milestones and owners:
|
||||
|
||||
### Phase 1: Onboard (Month 1)
|
||||
|
||||
| Milestone | Owner | Due date | Status |
|
||||
|---|---|---|---|
|
||||
| Admin setup complete (SSO, permissions, data integration) | [IT contact] | [Date] | [ ] |
|
||||
| All purchased seats activated and users invited | [Champion] | [Date] | [ ] |
|
||||
| Core workflow [X] configured and tested | [CSM + Champion] | [Date] | [ ] |
|
||||
| First training session delivered (all teams) | [CSM] | [Date] | [ ] |
|
||||
| Kickoff call completed and success plan co-signed | [CSM + Champion] | [Date] | [ ] |
|
||||
|
||||
### Phase 2: Adopt (Months 2–3)
|
||||
|
||||
| Milestone | Owner | Due date | Status |
|
||||
|---|---|---|---|
|
||||
| [Core feature] in active daily use by ≥ X users | [Champion] | [Date] | [ ] |
|
||||
| First business outcome achieved and documented | [Champion + CSM] | [Date] | [ ] |
|
||||
| 30-day check-in completed | [CSM] | [Date] | [ ] |
|
||||
| [Power user workflow] enabled for advanced users | [CSM] | [Date] | [ ] |
|
||||
|
||||
### Phase 3: Value (Months 4–6)
|
||||
|
||||
| Milestone | Owner | Due date | Status |
|
||||
|---|---|---|---|
|
||||
| QBR 1 delivered — ROI evidence presented | [CSM + AE] | [Date] | [ ] |
|
||||
| Success metric [X] hit target | [Champion] | [Date] | [ ] |
|
||||
| Expansion use case identified and introduced | [AE] | [Date] | [ ] |
|
||||
| Reference call or case study agreed | [Champion] | [Date] | [ ] |
|
||||
|
||||
### Phase 4: Renew & Expand (Months 7–12)
|
||||
|
||||
| Milestone | Owner | Due date | Status |
|
||||
|---|---|---|---|
|
||||
| QBR 2 delivered — renewal conversation started | [CSM + AE] | [Date] | [ ] |
|
||||
| Renewal proposal sent | [AE] | [Date] | [ ] |
|
||||
| Expansion or flat renewal signed | [AE] | [Date] | [ ] |
|
||||
|
||||
---
|
||||
|
||||
## 4. Mutual Commitments
|
||||
|
||||
Success plans work when both parties commit. Document what each side will do:
|
||||
|
||||
**[Vendor] commits to:**
|
||||
- Dedicated CSM available [X days/week / by email within 24 hours]
|
||||
- Monthly [call / check-in / async update] with champion
|
||||
- QBR every [90 days] with executive summary and ROI report
|
||||
- Priority support for [Account] — response SLA of [X hours] for P1 issues
|
||||
- Roadmap preview for relevant upcoming features
|
||||
- [Any other specific commitment made in sales cycle]
|
||||
|
||||
**[Account Name] commits to:**
|
||||
- Champion available for [30-min monthly] check-in
|
||||
- Users complete onboarding training by [date]
|
||||
- Feedback on product experience shared monthly (async or sync)
|
||||
- Executive sponsor participates in QBR 1 and renewal discussion
|
||||
- Provide outcome data to CSM quarterly for ROI tracking
|
||||
|
||||
---
|
||||
|
||||
## 5. Stakeholder Engagement Plan
|
||||
|
||||
| Stakeholder | Role | Engagement frequency | Format | Owner |
|
||||
|---|---|---|---|---|
|
||||
| [Champion] | Day-to-day owner | Weekly (async) + Monthly (call) | Slack / Email + Zoom | CSM |
|
||||
| [Economic buyer] | Budget holder | Quarterly | QBR (in-person or video) | CSM + AE |
|
||||
| [IT contact] | Integration owner | As needed | Email | CSM |
|
||||
| [End users] | Active users | Training only | Group session | CSM |
|
||||
|
||||
---
|
||||
|
||||
## 6. Risk & Mitigation
|
||||
|
||||
| Risk | Likelihood | Impact | Mitigation plan |
|
||||
|---|---|---|---|
|
||||
| Low adoption in first 30 days | [M] | [H] | CSM hosts live onboarding; champion sends internal comms day 1 |
|
||||
| Champion changes role | [L] | [H] | Multi-thread: introduce CSM to 2 additional stakeholders by Month 2 |
|
||||
| Budget pressure at renewal | [M] | [H] | Build ROI case monthly; document value continuously |
|
||||
| Competing priorities delay rollout | [H] | [M] | Agree minimum viable adoption path with champion; don't require perfection to declare value |
|
||||
|
||||
---
|
||||
|
||||
## 7. Communication Plan
|
||||
|
||||
| Communication | Audience | Frequency | Format | Owner |
|
||||
|---|---|---|---|---|
|
||||
| Health update | Champion | Monthly | Email summary (3 bullets: what's good, what needs attention, one ask) | CSM |
|
||||
| QBR | Champion + Exec | Quarterly | 45-min video call with slide deck | CSM + AE |
|
||||
| Product updates | Champion | As released | Release notes email | CSM |
|
||||
| Support status | Champion | When open tickets exist | Email / Slack | Support + CSM |
|
||||
|
||||
---
|
||||
|
||||
## 8. Escalation Path
|
||||
|
||||
If the success plan falls off track:
|
||||
|
||||
| Trigger | Action | Owner | Timeline |
|
||||
|---|---|---|---|
|
||||
| Health drops to Amber | Internal review + champion call within 5 days | CSM | Immediate |
|
||||
| Health drops to Red | CS leadership + AE looped in; escalation brief drafted | CS Manager | Within 24 hours |
|
||||
| Champion is unresponsive for >10 days | AE attempts exec sponsor contact | AE | After CSM attempt fails |
|
||||
| Adoption <40% at Month 3 | Emergency enablement session + revised milestone plan | CSM | Within 1 week of flag |
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Success metrics are the customer's metrics — not just product usage metrics
|
||||
- [ ] Milestones have specific owners and due dates — not "TBD"
|
||||
- [ ] Mutual commitments section is genuinely mutual — not just what the vendor will do
|
||||
- [ ] Risk register includes champion departure and low adoption
|
||||
- [ ] Plan is written to be shared with the customer — no internal-only commentary in this document
|
||||
- [ ] Executive sponsor is identified and has an engagement role
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- "Build a success plan for [Account Name] who just signed"
|
||||
- "Create a joint success plan for our new enterprise customer"
|
||||
- "Write a 6-month customer success roadmap for [Company]"
|
||||
- "I need a mutual action plan for our QBR with [Account]"
|
||||
- "Generate a customer success plan for an at-risk account"
|
||||
@@ -0,0 +1,221 @@
|
||||
---
|
||||
name: data-pipeline-spec
|
||||
description: "Design an ETL/ELT data pipeline specification. Use when asked to design a data pipeline, spec an ETL or ELT process, document a data ingestion workflow, or plan a data integration. Produces a complete pipeline spec with sources, transforms, destinations, SLAs, error handling, and data quality rules."
|
||||
---
|
||||
|
||||
# Data Pipeline Spec Skill
|
||||
|
||||
This skill produces a complete data pipeline specification covering sources, transformations, destinations, scheduling, SLAs, error handling, data quality checks, and monitoring requirements. Output is ready for engineering handoff or architecture review.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask the user for these if not provided:
|
||||
- **Pipeline purpose** — what business question or workflow does this pipeline serve?
|
||||
- **Source systems** — where does data come from? (databases, APIs, files, event streams)
|
||||
- **Destination** — where does data land? (data warehouse, data lake, downstream DB, reporting tool)
|
||||
- **Transformation type** — ETL (transform before loading) or ELT (load raw, transform in warehouse)?
|
||||
- **Frequency / SLA** — how often must data be fresh? (real-time / hourly / daily / weekly)
|
||||
- **Volume estimate** — approximate rows/events per run
|
||||
- **Data quality requirements** — completeness, deduplication, freshness, schema enforcement
|
||||
- **Team or stack** — any specific tools in use? (Airflow, dbt, Fivetran, Spark, Kafka, etc.)
|
||||
|
||||
## Output Structure
|
||||
|
||||
---
|
||||
|
||||
# Data Pipeline Spec: [Pipeline Name]
|
||||
|
||||
**Purpose:** [One sentence — what decision or workflow does this pipeline enable?]
|
||||
**Type:** [ETL / ELT / Streaming / Batch]
|
||||
**Owner:** [Team or individual]
|
||||
**Version:** [1.0]
|
||||
**Date:** [Date]
|
||||
**Status:** [Draft / Under Review / Approved]
|
||||
|
||||
---
|
||||
|
||||
## 1. Overview
|
||||
|
||||
[2–3 sentences describing the pipeline end-to-end: what data moves, from where to where, at what cadence, and why.]
|
||||
|
||||
**Architecture diagram (text):**
|
||||
|
||||
```
|
||||
[Source A] ──┐
|
||||
[Source B] ──┤──► [Ingestion Layer] ──► [Transform Layer] ──► [Destination] ──► [Consumers]
|
||||
[Source C] ──┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. Sources
|
||||
|
||||
| Source | System | Connection type | Data format | Update pattern | Volume |
|
||||
|---|---|---|---|---|---|
|
||||
| [Source 1] | [PostgreSQL / Salesforce / S3 / Kafka] | [JDBC / REST API / SDK / Webhook] | [JSON / CSV / Parquet / CDC] | [Append / Full refresh / Incremental] | [X rows/day] |
|
||||
| [Source 2] | [...] | [...] | [...] | [...] | [...] |
|
||||
|
||||
**Incremental key (if applicable):** [The column used to identify new or changed records — e.g. `updated_at`, `event_id`]
|
||||
|
||||
**Authentication:** [API key / OAuth / IAM role / connection string — note where credentials are stored]
|
||||
|
||||
---
|
||||
|
||||
## 3. Ingestion Layer
|
||||
|
||||
**Tool:** [Fivetran / Airbyte / Kafka Connect / custom script / dbt source]
|
||||
|
||||
**Ingestion method:**
|
||||
- [ ] Full extract (full table refresh each run)
|
||||
- [ ] Incremental extract (only new/changed rows since last run)
|
||||
- [ ] CDC (change data capture from database transaction log)
|
||||
- [ ] Event streaming (continuous ingestion from Kafka/Kinesis)
|
||||
|
||||
**Raw landing zone:** [Where raw data lands before transformation — e.g. `raw.salesforce_opportunities` in Snowflake, S3 bucket `s3://data-raw/crm/`]
|
||||
|
||||
**Schema handling:** [Strict schema enforcement / Schema evolution allowed / Union schema]
|
||||
|
||||
---
|
||||
|
||||
## 4. Transformation Logic
|
||||
|
||||
List each transformation in execution order. For ELT pipelines, this is the dbt model or SQL layer.
|
||||
|
||||
| Step | Name | Description | Input | Output | Tool |
|
||||
|---|---|---|---|---|---|
|
||||
| 1 | [Deduplicate events] | [Remove duplicate event rows based on event_id] | `raw.events` | `staging.events_deduped` | [dbt / SQL / Spark] |
|
||||
| 2 | [Join user profile] | [Enrich events with user attributes from CRM] | `staging.events_deduped`, `raw.users` | `staging.events_enriched` | [...] |
|
||||
| 3 | [Aggregate to daily] | [Roll up to user×day grain] | `staging.events_enriched` | `mart.user_daily_activity` | [...] |
|
||||
|
||||
**Business logic rules:**
|
||||
- [e.g. Revenue is recognised on `payment_confirmed_at`, not `payment_initiated_at`]
|
||||
- [e.g. Users in the `internal@company.com` domain are excluded from all metrics]
|
||||
- [e.g. Currency conversion uses the ECB rate from the first business day of each month]
|
||||
|
||||
**Slowly Changing Dimensions (SCD) — if applicable:**
|
||||
- [e.g. `users.plan_tier` is SCD Type 2 — keep history of plan changes with `valid_from` / `valid_to`]
|
||||
|
||||
---
|
||||
|
||||
## 5. Destination
|
||||
|
||||
| Destination | System | Schema / Table | Write mode | Consumers |
|
||||
|---|---|---|---|---|
|
||||
| [Primary] | [Snowflake / BigQuery / Redshift / PostgreSQL] | [`analytics.mart_user_activity`] | [Append / Upsert / Full replace] | [Looker / Metabase / downstream pipeline] |
|
||||
| [Secondary] | [...] | [...] | [...] | [...] |
|
||||
|
||||
**Partitioning / Clustering:** [e.g. Partitioned by `event_date`, clustered by `user_id` — reduces query cost for time-range scans]
|
||||
|
||||
**Retention policy:** [e.g. Raw data retained for 90 days; mart tables retained indefinitely]
|
||||
|
||||
---
|
||||
|
||||
## 6. Scheduling & SLAs
|
||||
|
||||
| SLA | Target | Breach action |
|
||||
|---|---|---|
|
||||
| **Data freshness** | [Data must be ≤ X hours old by HH:MM UTC] | [Page on-call / alert Slack channel] |
|
||||
| **Pipeline completion** | [Must complete within X minutes of trigger] | [Alert and auto-retry] |
|
||||
| **Availability** | [Pipeline must run successfully X% of days per month] | [Incident review] |
|
||||
|
||||
**Schedule:** [Cron expression and human description — e.g. `0 6 * * *` — daily at 06:00 UTC]
|
||||
|
||||
**Trigger type:**
|
||||
- [ ] Time-based (cron)
|
||||
- [ ] Event-based (triggered by upstream pipeline success / file arrival / Kafka lag)
|
||||
- [ ] Manual (ad hoc runs only)
|
||||
|
||||
**Backfill strategy:** [How to reprocess historical data if the pipeline fails or logic changes — e.g. parameterised date range, full drop-and-reload]
|
||||
|
||||
---
|
||||
|
||||
## 7. Data Quality Rules
|
||||
|
||||
| Check | Table | Rule | Failure action |
|
||||
|---|---|---|---|
|
||||
| Completeness | `staging.events` | `event_id IS NOT NULL` — 100% of rows | Block load / Alert |
|
||||
| Uniqueness | `mart.user_daily_activity` | `(user_id, date)` must be unique | Block load |
|
||||
| Freshness | `mart.user_daily_activity` | `max(event_date) >= CURRENT_DATE - 1` | Alert |
|
||||
| Volume | `staging.events` | Row count within ±20% of 7-day average | Alert |
|
||||
| Referential integrity | `staging.events` | All `user_id` values exist in `users` table | Alert |
|
||||
|
||||
**DQ tool:** [dbt tests / Great Expectations / Monte Carlo / custom SQL assertions]
|
||||
|
||||
---
|
||||
|
||||
## 8. Error Handling & Recovery
|
||||
|
||||
**Retry policy:** [e.g. 3 retries with exponential back-off: 5 min, 20 min, 60 min]
|
||||
|
||||
**Failure modes and responses:**
|
||||
|
||||
| Failure | Detection | Response | Owner |
|
||||
|---|---|---|---|
|
||||
| Source unavailable | HTTP 5xx / connection timeout | Retry 3×, then alert and skip run | Data engineering |
|
||||
| Schema change in source | Column missing or type mismatch | Block load, alert schema owner | Data owner + engineering |
|
||||
| DQ check fails | dbt test failure / assertion error | Block load for P1 checks; alert for P2 | Data engineering |
|
||||
| Partial load | Row count < expected threshold | Alert; do not publish to consumers until resolved | Data engineering |
|
||||
|
||||
**Dead-letter queue:** [Where failed records are routed for manual inspection — e.g. `raw.dlq_events`]
|
||||
|
||||
---
|
||||
|
||||
## 9. Monitoring & Observability
|
||||
|
||||
**Metrics to track:**
|
||||
- Pipeline run duration (p50, p95)
|
||||
- Rows processed per run
|
||||
- DQ check pass rate
|
||||
- Source freshness lag
|
||||
- Error rate per source
|
||||
|
||||
**Alerting:**
|
||||
- [Slack channel: #data-alerts]
|
||||
- [PagerDuty: data-on-call escalation for P1 SLA breaches]
|
||||
- [Dashboard: [link to monitoring dashboard]]
|
||||
|
||||
**Logging:** [What gets logged and where — e.g. Airflow task logs to CloudWatch, structured JSON to data lake]
|
||||
|
||||
---
|
||||
|
||||
## 10. Dependencies & Sequencing
|
||||
|
||||
**Upstream dependencies:** [Which pipelines or data sources must succeed before this pipeline runs?]
|
||||
|
||||
**Downstream dependents:** [Which dashboards, pipelines, or models depend on this pipeline's output?]
|
||||
|
||||
```
|
||||
[upstream pipeline A] ──► THIS PIPELINE ──► [downstream dashboard B]
|
||||
└──► [downstream pipeline C]
|
||||
```
|
||||
|
||||
**Coordination mechanism:** [Airflow DAG dependency / dbt ref() / event trigger / manual gate]
|
||||
|
||||
---
|
||||
|
||||
## 11. Security & Compliance
|
||||
|
||||
- **PII fields:** [List columns containing PII — e.g. `email`, `ip_address`, `name`]
|
||||
- **Masking / Pseudonymisation:** [e.g. email hashed with SHA-256 before landing in mart layer]
|
||||
- **Access control:** [Who can query the destination tables? — e.g. Role-based access in Snowflake]
|
||||
- **Data residency:** [Which regions is data permitted to transit and rest in?]
|
||||
- **Audit trail:** [Is pipeline execution auditable for compliance purposes? Where are logs retained?]
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Every source has an incremental key or full-refresh justification
|
||||
- [ ] Business logic rules are documented, not just the SQL
|
||||
- [ ] SLAs are agreed with consumers, not set unilaterally by engineering
|
||||
- [ ] DQ checks cover completeness, uniqueness, freshness, and volume
|
||||
- [ ] Failure modes include a documented recovery owner
|
||||
- [ ] PII fields are identified and a treatment plan is specified
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- "Design a data pipeline for our Salesforce to Snowflake sync"
|
||||
- "Write a pipeline spec for ingesting Stripe events into our data warehouse"
|
||||
- "Build an ETL spec for our user activity data"
|
||||
- "Document our dbt pipeline from raw events to the analytics mart"
|
||||
- "Spec out the pipeline that feeds the executive dashboard"
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: debugging-log-analyser
|
||||
description: "Parse error logs, stack traces, and crash reports into a structured root cause diagnosis. Use when sharing a log, stack trace, error output, or crash dump. Produces a structured diagnosis with probable root cause, affected code path, suggested fix, and next debugging steps. Optimised for Opus 4.7 and newer models."
|
||||
description: "Parse error logs, stack traces, and crash reports into a structured root cause diagnosis. Use when sharing a log, stack trace, error output, or crash dump. Produces a structured diagnosis with probable root cause, affected code path, suggested fix, and next debugging steps."
|
||||
---
|
||||
|
||||
# Debugging Log Analyser Skill
|
||||
@@ -12,14 +12,19 @@ Parses raw error logs, stack traces, and crash reports into a structured diagnos
|
||||
Ask for these if not provided:
|
||||
- **The log / stack trace / error output** (paste directly or describe the error)
|
||||
- **Language and framework** (e.g. Node.js + Express, Python + Django, Java Spring, Go)
|
||||
- **Context** (what the user was doing when the error occurred)
|
||||
- **Context** (what changed before this started — e.g. recent deploy, config change, increased traffic, new input data; or "nothing changed" is also useful)
|
||||
- **Frequency** (one-off / intermittent / consistent / regression after a specific change)
|
||||
- **Environment** (local dev / staging / production)
|
||||
- **What they've already tried** (if anything)
|
||||
|
||||
## Output Structure
|
||||
## Output Format
|
||||
|
||||
---
|
||||
|
||||
# Debugging Report: [Service/App Name]
|
||||
|
||||
### 1. Error Classification
|
||||
**Error type:** [Runtime exception / Build error / Config error / Network error / Memory/resource error / Unknown]
|
||||
**Error type:** [Runtime exception / Build error / Config error / Network error / Memory error / Unknown]
|
||||
**Severity:** [Fatal / Critical / Warning / Informational]
|
||||
**Recurrence pattern:** [One-off / Intermittent / Consistent / On-startup / Under load]
|
||||
|
||||
@@ -64,14 +69,17 @@ One or two concrete things that would prevent this class of error recurring:
|
||||
- Add monitoring/alerting for [condition]
|
||||
- Test that covers [scenario]
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
- [ ] Root cause is specific (not "there might be a null pointer issue")
|
||||
- [ ] At least one concrete code-level fix is suggested
|
||||
- [ ] Next steps are actionable commands, not vague advice
|
||||
- [ ] Language-specific idioms are used correctly
|
||||
- [ ] Suggested fix references the actual language/framework in the input (not a generic fix that could apply to any language)
|
||||
- [ ] Confidence level includes a stated reason (not just "High" or "Low" with no explanation)
|
||||
- [ ] Prevention is proactive (not just "add error handling")
|
||||
|
||||
## Example Trigger Phrases
|
||||
## Usage Examples
|
||||
- "Why is this crashing?" + [paste log]
|
||||
- "Can you analyse this stack trace?"
|
||||
- "I'm getting this error, what does it mean?"
|
||||
|
||||
@@ -0,0 +1,215 @@
|
||||
---
|
||||
name: design-system-audit
|
||||
description: "Audit a design system for consistency, coverage, and quality. Use when asked to audit a design system, review a component library, assess design token coverage, or evaluate the health of a shared design system. Produces a structured audit with a health score, component coverage gaps, token inconsistencies, accessibility issues, and a prioritised remediation roadmap."
|
||||
---
|
||||
|
||||
# Design System Audit Skill
|
||||
|
||||
This skill produces a structured audit of a design system — covering component coverage, token consistency, documentation quality, accessibility compliance, contribution processes, and adoption health. Output is ready for a design system team, design leadership, or an engineering team evaluating their shared component library.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask the user for these if not provided:
|
||||
- **Design system name** and what product(s) it serves
|
||||
- **Audit scope** — component library / design tokens / documentation / contribution process / all of the above
|
||||
- **Current tooling** — Figma / Storybook / Zeroheight / custom / combination?
|
||||
- **Team using it** — how many designers and engineers, how many products?
|
||||
- **Known pain points** — what do teams complain about most?
|
||||
- **Governance model** — centralised team / federated contributors / no dedicated team?
|
||||
- **Goal of the audit** — improve adoption / prepare for a rebrand / onboard new teams / justify investment?
|
||||
|
||||
## Output Structure
|
||||
|
||||
---
|
||||
|
||||
# Design System Audit: [System Name]
|
||||
|
||||
**Products served:** [List of products / apps]
|
||||
**Audit scope:** [Full / Components only / Tokens only / Documentation]
|
||||
**Auditor:** [Name / Team]
|
||||
**Date:** [Date]
|
||||
**Stakeholders:** [Design lead, Eng lead, CPO, etc.]
|
||||
|
||||
---
|
||||
|
||||
## Overall Health Score
|
||||
|
||||
| Dimension | Score (1–5) | Status |
|
||||
|---|---|---|
|
||||
| Component coverage | [X/5] | 🟢/🟡/🔴 |
|
||||
| Token consistency | [X/5] | 🟢/🟡/🔴 |
|
||||
| Documentation quality | [X/5] | 🟢/🟡/🔴 |
|
||||
| Accessibility compliance | [X/5] | 🟢/🟡/🔴 |
|
||||
| Adoption rate | [X/5] | 🟢/🟡/🔴 |
|
||||
| Contribution process | [X/5] | 🟢/🟡/🔴 |
|
||||
| **Overall** | **[X/5]** | 🟢/🟡/🔴 |
|
||||
|
||||
**Summary:** [2–3 sentences. What is the overall state of the design system? What are the top 2 issues and what is the biggest strength?]
|
||||
|
||||
---
|
||||
|
||||
## 1. Component Coverage Audit
|
||||
|
||||
**How to assess:** Compare components in the design system against the actual UI patterns in the product. Every pattern that exists in production but not in the system is a coverage gap.
|
||||
|
||||
### Component Inventory
|
||||
|
||||
| Category | Components present | Coverage | Gap |
|
||||
|---|---|---|---|
|
||||
| **Navigation** | [Navbar, Sidebar, Breadcrumb, Tabs] | [80%] | [Missing: Mega menu, mobile drawer] |
|
||||
| **Forms & Inputs** | [Text input, Dropdown, Checkbox, Radio, Toggle, Date picker] | [90%] | [Missing: Multi-select, Rich text editor] |
|
||||
| **Feedback & Alerts** | [Toast, Banner, Modal, Tooltip] | [60%] | [Missing: Inline validation, Progress indicator, Skeleton loader] |
|
||||
| **Data Display** | [Table, Card, Badge, Avatar] | [50%] | [Missing: Data grid, Stat card, Timeline, Gantt] |
|
||||
| **Layout** | [Grid, Container, Divider, Spacer] | [70%] | [Missing: Responsive breakpoint utilities] |
|
||||
| **Buttons & Actions** | [Button, Icon button, FAB, Link] | [100%] | [None] |
|
||||
|
||||
**Coverage score:** [X% of production UI patterns are covered by the design system]
|
||||
|
||||
**Most impactful gaps:**
|
||||
1. [Most used pattern not in the system — causing most duplication]
|
||||
2. [...]
|
||||
3. [...]
|
||||
|
||||
---
|
||||
|
||||
## 2. Component Quality Audit
|
||||
|
||||
For each component, assess against these quality criteria:
|
||||
|
||||
| Component | States complete | Responsive | Accessibility | Dark mode | Props documented | Code matches Figma |
|
||||
|---|---|---|---|---|---|---|
|
||||
| Button | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
|
||||
| Modal | ⚠️ Loading state missing | ✅ | ✅ | ❌ | ⚠️ Partial | ✅ |
|
||||
| Table | ❌ Sorting state missing | ❌ No mobile layout | ⚠️ No aria-sort | ❌ | ❌ | ⚠️ Drift |
|
||||
| [Component] | [...] | [...] | [...] | [...] | [...] | [...] |
|
||||
|
||||
**Legend:** ✅ Complete — ⚠️ Partial / inconsistent — ❌ Missing
|
||||
|
||||
**Components with critical quality issues (fix before anything else):**
|
||||
- [Component name]: [Specific issue and why it's blocking]
|
||||
- [...]
|
||||
|
||||
---
|
||||
|
||||
## 3. Design Token Audit
|
||||
|
||||
**Token coverage:**
|
||||
|
||||
| Token type | Defined | Used consistently | Issues |
|
||||
|---|---|---|---|
|
||||
| **Colour** | [X tokens defined] | [⚠️ — 12 hardcoded hex values found in Figma] | [Inconsistent use of primary-500 vs primary-600 for CTAs across products] |
|
||||
| **Typography** | [X tokens defined] | [✅] | [None — all type styles use token scale] |
|
||||
| **Spacing** | [X tokens defined] | [⚠️ — custom spacing used in X components] | [Engineers using arbitrary px values instead of spacing tokens in X components] |
|
||||
| **Border radius** | [X tokens defined] | [❌ — not defined; each component has hardcoded values] | [Button, card, modal all use different radius values with no token] |
|
||||
| **Shadow / elevation** | [X tokens defined] | [⚠️] | [3 different drop-shadow values in use; no elevation scale] |
|
||||
| **Animation / motion** | [X tokens defined] | [❌ — not defined] | [Transition durations inconsistent across components] |
|
||||
|
||||
**Semantic token layer:** [Does the system have semantic tokens (e.g. `color.action.primary` on top of `color.blue.500`) or only primitive tokens?]
|
||||
|
||||
**Token drift:** [Are code tokens and Figma tokens in sync? Use a tool like Token Studio, Style Dictionary, or manual comparison.]
|
||||
|
||||
---
|
||||
|
||||
## 4. Documentation Quality Audit
|
||||
|
||||
**Assessment per component / pattern:**
|
||||
|
||||
| Document type | Quality | Issues |
|
||||
|---|---|---|
|
||||
| **Usage guidelines** | [⚠️ — X% of components have guidelines] | [Button and Form components documented; Navigation and Data Display mostly undocumented] |
|
||||
| **Do / Don't examples** | [❌ — mostly absent] | [Engineers frequently misuse components because intent is unclear] |
|
||||
| **Accessibility notes** | [⚠️ — present for some components] | [No consistent format; accessibility notes missing for interactive components] |
|
||||
| **Code examples** | [✅ — all Storybook components have code examples] | [...] |
|
||||
| **Changelog** | [❌ — no component-level changelog exists] | [Breaking changes are not communicated; causes unexpected UI regressions] |
|
||||
| **Migration guides** | [❌ — absent] | [Teams don't know how to upgrade to new component versions] |
|
||||
|
||||
**Documentation score:** [X% of components have complete, usable documentation]
|
||||
|
||||
**Most common designer / engineer complaint about docs:** [e.g. "I can't find whether to use Modal or Drawer for this use case — no guidance exists"]
|
||||
|
||||
---
|
||||
|
||||
## 5. Accessibility Audit
|
||||
|
||||
**WCAG 2.2 compliance status:**
|
||||
|
||||
| Criterion | Level | Status | Components affected |
|
||||
|---|---|---|---|
|
||||
| Colour contrast (text) | AA | [✅ / ⚠️ / ❌] | [e.g. ❌ — Disabled state text fails 4.5:1 ratio in 3 components] |
|
||||
| Colour contrast (UI components) | AA | [✅ / ⚠️ / ❌] | [...] |
|
||||
| Keyboard navigation | AA | [✅ / ⚠️ / ❌] | [⚠️ — Modal focus trap not implemented; Dropdown not keyboard accessible] |
|
||||
| Focus visible | AA | [✅ / ⚠️ / ❌] | [...] |
|
||||
| Screen reader support (ARIA) | AA | [✅ / ⚠️ / ❌] | [❌ — Table component lacks aria-sort; Icon buttons have no aria-label] |
|
||||
| Touch target size | AA | [✅ / ⚠️ / ❌] | [⚠️ — Mobile tap targets below 44×44px in X components] |
|
||||
| Motion / animation | AA | [✅ / ⚠️ / ❌] | [...] |
|
||||
|
||||
**Critical accessibility blockers (must fix before next release):**
|
||||
1. [Most critical issue — e.g. Keyboard users cannot close Modal — focus trap missing]
|
||||
2. [...]
|
||||
|
||||
---
|
||||
|
||||
## 6. Adoption Audit
|
||||
|
||||
**Adoption by team / product:**
|
||||
|
||||
| Product / Team | Components used from system | Custom components built outside system | Adoption score |
|
||||
|---|---|---|---|
|
||||
| [Product A] | [X% of UI uses system components] | [Y custom components] | [High / Medium / Low] |
|
||||
| [Product B] | [...] | [...] | [...] |
|
||||
|
||||
**Why teams are not adopting:**
|
||||
|
||||
| Barrier | Severity | Evidence |
|
||||
|---|---|---|
|
||||
| [Component doesn't exist] | High | [Top reason in team survey] |
|
||||
| [Component exists but doesn't meet use case] | Medium | [Modal component lacks X state needed by Product B] |
|
||||
| [Documentation too sparse to know how to use it] | Medium | [...] |
|
||||
| [No one enforces system use — easier to build custom] | High | [...] |
|
||||
| [System is out of date with product's current visual language] | Medium | [...] |
|
||||
|
||||
---
|
||||
|
||||
## 7. Contribution Process Audit
|
||||
|
||||
| Dimension | Current state | Assessment |
|
||||
|---|---|---|
|
||||
| **How to contribute** | [Documented / Not documented] | [✅ / ❌] |
|
||||
| **Contribution criteria** | [Clear entry bar for what goes in the system] | [⚠️ — unclear who decides what becomes a system component vs stays local] |
|
||||
| **Review process** | [Who reviews contributions and how long it takes] | [❌ — no formal review; contributions sit unreviewed for weeks] |
|
||||
| **Release cadence** | [How often system releases happen] | [⚠️ — sporadic; no set cadence] |
|
||||
| **Breaking change policy** | [How breaking changes are handled and communicated] | [❌ — no policy; breaking changes are a surprise] |
|
||||
| **Versioning** | [Semantic versioning in place?] | [✅ — all packages use semver] |
|
||||
|
||||
---
|
||||
|
||||
## 8. Prioritised Remediation Roadmap
|
||||
|
||||
| Priority | Initiative | Impact | Effort | Timeline |
|
||||
|---|---|---|---|---|
|
||||
| P1 | Fix [X] critical accessibility issues (keyboard nav, ARIA) | Critical — legal + user impact | Medium | Sprint 1–2 |
|
||||
| P1 | Define and implement border radius and shadow token scale | High — ends inconsistency | Low | Sprint 1 |
|
||||
| P1 | Document top 10 most-used components (usage + do/don't) | High — unblocks adoption | Medium | Sprint 2–4 |
|
||||
| P2 | Build Skeleton loader + Inline validation components (top 2 gaps) | High — eliminates custom duplication | High | Quarter 2 |
|
||||
| P2 | Establish contribution process with SLA for reviews | Medium — enables growth | Low | Sprint 3 |
|
||||
| P3 | Dark mode token support | Medium — product parity | High | Quarter 3 |
|
||||
| P3 | Design-code token sync tooling (Token Studio / Style Dictionary) | Medium — reduces drift | Medium | Quarter 2–3 |
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Coverage gaps are identified by comparing the design system to actual production UI, not assumed
|
||||
- [ ] Accessibility issues cite specific WCAG criterion and affected components
|
||||
- [ ] Adoption barriers are backed by evidence (interviews, survey, usage data) — not assumed
|
||||
- [ ] Remediation roadmap has effort estimates and is sequenced by impact
|
||||
- [ ] Both Figma and code (Storybook/implementation) are assessed — not just Figma
|
||||
- [ ] Stakeholders from design, engineering, and product have reviewed the audit
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- "Audit our design system for consistency and coverage"
|
||||
- "Review our component library and identify gaps"
|
||||
- "Assess the health of our shared design system"
|
||||
- "Run a design system audit before we do a rebrand"
|
||||
- "What's wrong with our design system and what should we fix first?"
|
||||
@@ -0,0 +1,186 @@
|
||||
---
|
||||
name: email-triage
|
||||
description: Reads your Gmail inbox for a configurable window (default: last 8 hours) and surfaces only what needs action — replies, decisions, or follow-up. Filters out receipts, notifications, newsletters, and anything that doesn't need you.
|
||||
---
|
||||
|
||||
# Email Triage
|
||||
|
||||
## The Problem
|
||||
|
||||
Most of us spend real time triaging email that could be sorted automatically. Scrolling through a mixed inbox of newsletters, order confirmations, Jira notifications, and actual human asks is a tax on focus. The 40 emails since lunch contain maybe 4 that actually need you — this skill finds those 4.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
| Requirement | Details |
|
||||
|-------------|---------|
|
||||
| Gmail connector | Must be active in Claude settings (Settings → Connectors → Gmail) |
|
||||
| Gmail account | The account you want triaged |
|
||||
|
||||
If the Gmail connector is not connected, Claude will prompt you to connect it before proceeding.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
| Input | Required | Default | Notes |
|
||||
|-------|----------|---------|-------|
|
||||
| Time window | No | Last 8 hours | Accepts: "last 8 hours", "last 24h", "today", "since Monday", "last 3 days" |
|
||||
| Always-include senders | No | None | Specific names or email addresses that always surface, regardless of content |
|
||||
| Always-ignore senders | No | None | Domains or addresses to always suppress (e.g. noreply@*, jira@company.com) |
|
||||
| Focus area | No | None | Optional context: "focus on anything from clients" or "flag anything about the launch" |
|
||||
|
||||
## What Gets Filtered Out
|
||||
|
||||
Claude suppresses the following categories. They are counted in the summary but not shown:
|
||||
|
||||
- Order confirmations and shipping notifications
|
||||
- Marketing and promotional emails (including "one-time" offer emails)
|
||||
- Newsletter subscriptions and digest emails
|
||||
- Automated system notifications (monitoring alerts, CI/CD, build reports)
|
||||
- Calendar invites that have already been accepted or declined
|
||||
- Read receipts and delivery confirmations
|
||||
- Social media notifications (LinkedIn, Twitter/X, etc.)
|
||||
- Internal ticket updates unless the ticket is assigned to you and requires action
|
||||
- Bank and financial statements (surfaced count only, not content)
|
||||
|
||||
## What Gets Surfaced
|
||||
|
||||
Claude surfaces only emails that meet one or more of these criteria:
|
||||
|
||||
- A human is waiting for a reply
|
||||
- A decision is being requested
|
||||
- There is a deadline or time-sensitive ask, explicit or implied
|
||||
- The sender is someone who does not usually email you (potential priority signal)
|
||||
- The email is from a sender in your always-include list
|
||||
|
||||
## Output Format
|
||||
|
||||
```
|
||||
## Inbox Triage — [Time window] | [Date], [Time]
|
||||
**Total emails scanned:** X | **Actionable:** Y | **Filtered out:** Z
|
||||
|
||||
---
|
||||
|
||||
### 🔴 High Priority — Needs reply or decision today
|
||||
|
||||
**From:** [Name] <email@domain.com>
|
||||
**Subject:** [Subject line]
|
||||
**Received:** [Time, e.g. 2:14 PM]
|
||||
**What they need:** [One sentence — the actual ask, not a summary of the email]
|
||||
**Reply starter:** "[A draft opener they can continue — 1 sentence max]"
|
||||
|
||||
---
|
||||
|
||||
**From:** [Name] <email@domain.com>
|
||||
**Subject:** [Subject line]
|
||||
**Received:** [Time]
|
||||
**What they need:** [One sentence]
|
||||
**Reply starter:** "[Draft opener]"
|
||||
|
||||
---
|
||||
|
||||
### 🟡 Medium Priority — Reply within 24–48h
|
||||
|
||||
**From:** [Name] <email@domain.com>
|
||||
**Subject:** [Subject line]
|
||||
**Received:** [Time]
|
||||
**What they need:** [One sentence]
|
||||
**Reply starter:** "[Draft opener]" *(or "No reply needed — action only: [what to do]")*
|
||||
|
||||
---
|
||||
|
||||
### 🟢 FYI — Worth knowing, no action required
|
||||
|
||||
- **[Name]** re: [Subject] — [One-line summary of why it might be relevant]
|
||||
- **[Name]** re: [Subject] — [One-line summary]
|
||||
|
||||
---
|
||||
|
||||
### ⚪ Filtered Out — [Z emails]
|
||||
Receipts: X | Newsletters: X | Notifications: X | Other automated: X
|
||||
*(No action needed — not shown in detail)*
|
||||
```
|
||||
|
||||
## Instructions for Claude
|
||||
|
||||
### Step 1 — Connect and confirm the time window
|
||||
|
||||
Confirm the Gmail connector is active. Parse the requested time window and translate it to an exact datetime range (e.g. "last 8 hours" = [current time minus 8 hours] to now). State the window at the top of the output.
|
||||
|
||||
### Step 2 — Read the inbox
|
||||
|
||||
Fetch emails from the inbox for the specified time window. Include: sender name, sender email, subject, received time, and email body (or first 500 words if long). Do not fetch emails older than the window.
|
||||
|
||||
### Step 3 — Apply ignore rules
|
||||
|
||||
If the user specified always-ignore senders or domains, suppress those immediately. If no ignore list was given, apply standard suppression (see What Gets Filtered Out). Track counts for the filtered summary.
|
||||
|
||||
### Step 4 — Classify each remaining email
|
||||
|
||||
For each non-suppressed email, classify into one of four categories:
|
||||
|
||||
- **High Priority**: A human is waiting on a reply today, or there is an explicit deadline within 24 hours
|
||||
- **Medium Priority**: A reply is needed but not urgently, or there is an implicit ask without a hard deadline
|
||||
- **FYI**: No action needed, but the user would likely want to know about it
|
||||
- **Filtered Out**: Falls into a suppressed category — add to count, do not show
|
||||
|
||||
Apply the always-include list after classification: any email from a flagged sender surfaces regardless of category, with its actual classification.
|
||||
|
||||
### Step 5 — Write the "What they need" line
|
||||
|
||||
This is the highest-value part of the output. Write exactly one sentence that captures the actual ask — not a summary of the email, the ask.
|
||||
|
||||
Bad: "Sarah sent an email about the Q3 report."
|
||||
Good: "Sarah needs your sign-off on the Q3 report before she sends it to the board at 5 PM."
|
||||
|
||||
If there is no clear ask, it is probably FYI or filtered out.
|
||||
|
||||
### Step 6 — Write the reply starter
|
||||
|
||||
For High and Medium priority emails, write a one-sentence reply opener. The opener should:
|
||||
- Match the tone of the sender (formal vs. casual)
|
||||
- Acknowledge the ask directly
|
||||
- Be something the user can actually send with minimal editing
|
||||
|
||||
Example: "Thanks for flagging this — let me check with the team and get back to you by EOD."
|
||||
|
||||
If the email requires an action rather than a reply (e.g. "please approve this expense"), write: "No reply needed — action only: [describe the action]."
|
||||
|
||||
### Step 7 — Assemble and deliver the output
|
||||
|
||||
Use the output format exactly as specified. Do not add extra sections, editorialise, or explain your reasoning. The output should be scannable in under 60 seconds.
|
||||
|
||||
### Step 8 — Offer next steps
|
||||
|
||||
After the triage output, offer one of:
|
||||
- "Want me to draft replies to any of these?"
|
||||
- "Say 'reply to [name]' and I'll draft it."
|
||||
|
||||
Keep this to one line. Do not elaborate.
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Time window was applied correctly — no emails outside the window are included
|
||||
- [ ] Gmail connector was confirmed active before reading
|
||||
- [ ] Every High Priority email has a specific, concrete "What they need" sentence — not a vague summary
|
||||
- [ ] Reply starters match the tone of the original email (formal/informal)
|
||||
- [ ] Filtered-out count is accurate and broken down by category
|
||||
- [ ] FYI section contains only emails with no action required — nothing actionable is buried here
|
||||
- [ ] Always-include senders surfaced regardless of category
|
||||
- [ ] Always-ignore senders/domains are fully suppressed
|
||||
- [ ] Output is scannable — no unnecessary prose, no padding
|
||||
- [ ] Financial statements and sensitive content were counted but not shown in full
|
||||
|
||||
## Dispatch / Mobile Usage
|
||||
|
||||
This skill works from the Claude mobile app (Dispatch). On mobile, the output renders cleanly with the emoji priority markers serving as visual anchors for quick scanning. Recommended mobile trigger: "Check my emails" or "/email-triage".
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- `/email-triage`
|
||||
- "Check my emails"
|
||||
- "What emails need my attention?"
|
||||
- "Triage my inbox for the last 8 hours"
|
||||
- "What came in since this morning?"
|
||||
- "Any urgent emails I need to deal with?"
|
||||
- "Triage my inbox — ignore anything from Jira and the marketing domain"
|
||||
- "Check emails from the last 24 hours, flag anything from [client name]"
|
||||
- "What do I need to reply to today?"
|
||||
@@ -5,7 +5,7 @@ description: "Write a structured incident postmortem or post-incident review. Us
|
||||
|
||||
# Incident Postmortem Skill
|
||||
|
||||
This skill produces a complete, blameless incident postmortem document following industry-standard format. Output is ready to share with engineering teams, leadership, and affected stakeholders.
|
||||
This skill produces a complete, blameless incident postmortem document following industry-standard format. Output enforces blameless framing throughout — system gaps over individual failures — and drives toward specific, closeable action items rather than vague process commitments.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
@@ -20,8 +20,10 @@ Ask the user for these if not provided:
|
||||
- **How it was resolved**
|
||||
- **Initial thoughts on root cause**
|
||||
- **Action items already identified** (optional)
|
||||
- **Responders** (who was on-call or responded — names or roles; used for the timeline, not for blame)
|
||||
- **Customer or external communications sent** (optional — any status page updates, emails, or support messages with timestamps)
|
||||
|
||||
## Output Structure
|
||||
## Output Format
|
||||
|
||||
---
|
||||
|
||||
@@ -131,13 +133,14 @@ Rules for action items:
|
||||
|
||||
- [ ] Timeline has no blame-focused language
|
||||
- [ ] Root cause is specific (not "human error")
|
||||
- [ ] Root cause answers "why did this happen?" not just "what happened?" — it names a system or process gap, not a symptom
|
||||
- [ ] Contributing factors explain the systemic gaps
|
||||
- [ ] Every action item has an owner and due date
|
||||
- [ ] "What went well" section is genuine, not token
|
||||
- [ ] No action item contains vague language like "improve monitoring", "increase resilience", or "better testing" — each must name a specific change
|
||||
- [ ] Executive summary is readable by non-technical leadership
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
## Usage Examples
|
||||
- "Write a postmortem for the [incident name] outage"
|
||||
- "Help me write a P1 incident report"
|
||||
- "Generate an RCA document for [service] going down on [date]"
|
||||
|
||||
@@ -0,0 +1,242 @@
|
||||
---
|
||||
name: influencer-brief
|
||||
description: "Create a structured brief for an influencer or creator partnership campaign. Use when asked to brief an influencer, plan a creator collaboration, set up a paid partnership, or define deliverables for a sponsored content campaign. Produces a complete campaign brief with objectives, deliverables, creative guidelines, approval process, and performance metrics."
|
||||
---
|
||||
|
||||
# Influencer Brief Skill
|
||||
|
||||
This skill produces a professional influencer campaign brief that a creator can receive and act on immediately. It covers campaign objectives, audience alignment, content deliverables, creative guidelines, messaging dos and don'ts, approval workflow, payment terms, and performance expectations. Output is ready to send to a creator, talent manager, or agency.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask the user for these if not provided:
|
||||
- **Brand / product name** — what is being promoted
|
||||
- **Campaign goal** — what you want the partnership to achieve (awareness / sales / sign-ups / content creation / event promotion)
|
||||
- **Influencer type / tier** — nano (1K–10K), micro (10K–100K), macro (100K–1M), mega/celebrity (1M+)
|
||||
- **Platform(s)** — Instagram, TikTok, YouTube, LinkedIn, X/Twitter, podcast
|
||||
- **Deliverables** — what content you need (e.g. 2 Instagram Reels, 1 Story, 1 TikTok video)
|
||||
- **Campaign dates** — start date, content deadlines, go-live window
|
||||
- **Budget range** — fee range, gifting, affiliate / commission structure
|
||||
- **Key messages** — what must the creator communicate?
|
||||
|
||||
## Output Structure
|
||||
|
||||
---
|
||||
|
||||
# Influencer Partnership Brief
|
||||
|
||||
**Campaign name:** [e.g. "Spring Launch — [Brand] x [Creator]"]
|
||||
**Brand:** [Brand name]
|
||||
**Campaign period:** [Start date → End date]
|
||||
**Brief date:** [Date]
|
||||
**Brand contact:** [Name, email, response time SLA]
|
||||
|
||||
---
|
||||
|
||||
## 1. Campaign Overview
|
||||
|
||||
**Why we're working with creators:**
|
||||
[2–3 sentences on the campaign context — product launch, seasonal push, brand awareness drive, community building. Explain why influencer marketing is the right channel for this goal.]
|
||||
|
||||
**Campaign goal:** [Single primary goal — e.g. "Drive 500 sign-ups to [product] from [creator]'s audience within 30 days of go-live"]
|
||||
|
||||
**Target audience:**
|
||||
- Who they are: [Age, gender, interests, platforms, mindset]
|
||||
- Why [creator]'s audience is the right fit: [Specific alignment — e.g. "Tech-curious professionals aged 25–40 who already use productivity tools"]
|
||||
|
||||
**Campaign type:**
|
||||
- [ ] Paid partnership (sponsored post / video)
|
||||
- [ ] Gifted / product collaboration
|
||||
- [ ] Affiliate / commission
|
||||
- [ ] Brand ambassador (ongoing)
|
||||
- [ ] Event / launch attendance
|
||||
- [ ] Co-created content
|
||||
|
||||
---
|
||||
|
||||
## 2. Creator Selection Rationale
|
||||
|
||||
*(Complete this section if the creator has already been selected)*
|
||||
|
||||
| Criteria | [Creator handle] | Why they're a fit |
|
||||
|---|---|---|
|
||||
| Follower count | [X] | [Context] |
|
||||
| Engagement rate | [X%] | [Above/at/below category average] |
|
||||
| Audience alignment | [Description] | [Overlap with target audience] |
|
||||
| Content style | [Description] | [Fit with brand tone] |
|
||||
| Past brand partnerships | [Yes/No] | [Relevant category experience] |
|
||||
| Exclusivity requirements | [Yes/No] | [Competitor conflicts?] |
|
||||
|
||||
---
|
||||
|
||||
## 3. Content Deliverables
|
||||
|
||||
Be specific. Ambiguity leads to reshoots and renegotiations.
|
||||
|
||||
| Deliverable | Platform | Format | Duration / specs | Deadline | Usage rights |
|
||||
|---|---|---|---|---|---|
|
||||
| [e.g. Primary hero video] | TikTok | Video | 30–60 sec, vertical 9:16 | [Date] | [Organic only / paid amplification / forever] |
|
||||
| [e.g. Story set] | Instagram | Story x3 | 15 sec each, link sticker | [Date] | [Organic only] |
|
||||
| [e.g. Reel] | Instagram | Reel | 15–30 sec, vertical | [Date] | [Paid amplification allowed for 30 days] |
|
||||
| [e.g. Long-form review] | YouTube | Video | 8–12 min, [product] featured from min 2 | [Date] | [Organic only] |
|
||||
|
||||
**Posting window:** Content must go live between [Date] and [Date]. Do not post during [blackout periods if any].
|
||||
|
||||
**Exclusivity:** Creator agrees not to post competing content for [X days] before and [X days] after campaign go-live.
|
||||
|
||||
---
|
||||
|
||||
## 4. Key Messages
|
||||
|
||||
**What the creator MUST communicate:**
|
||||
|
||||
✅ Must include:
|
||||
- [Message 1: e.g. "[Product name] is now available at [price / in [region]]"]
|
||||
- [Message 2: e.g. The specific problem [product] solves — [describe in plain language]]
|
||||
- [Message 3: e.g. The unique differentiator — [what makes it different from alternatives]]
|
||||
- [CTA: e.g. "Use code [CREATOR] for [X]% off" / "Link in bio to try free for 14 days"]
|
||||
|
||||
❌ Must NOT include:
|
||||
- [Restriction 1: e.g. Do not compare directly to [competitor name]]
|
||||
- [Restriction 2: e.g. Do not make unsubstantiated health or results claims]
|
||||
- [Restriction 3: e.g. Do not share pricing beyond the introductory offer]
|
||||
- [Restriction 4: e.g. Do not use the word "cheap" — use "accessible" or "great value"]
|
||||
|
||||
**Brand disclosure requirement:**
|
||||
All posts must include a paid partnership disclosure per [ASA / FTC / CAP Code] guidelines:
|
||||
- Instagram / TikTok: Use native "Paid Partnership" tag + "#ad" in caption
|
||||
- YouTube: Verbal disclosure in the first 30 seconds + description disclosure
|
||||
- "This video is sponsored by [Brand]" is acceptable
|
||||
|
||||
---
|
||||
|
||||
## 5. Creative Guidelines
|
||||
|
||||
**Tone of voice:**
|
||||
- [Your brand] sounds like: [e.g. "A knowledgeable friend — warm, direct, never corporate"]
|
||||
- [Your brand] does NOT sound like: [e.g. "A sales pitch, hype-driven, or try-hard"]
|
||||
- Creator's authentic voice is encouraged — the brief is a guide, not a script
|
||||
|
||||
**Visual guidelines:**
|
||||
- Brand colours (if shown): [Primary hex / description — e.g. "Navy #1A2B5C and white"]
|
||||
- Logo usage: [Not required in organic posts / required in pinned Stories / as overlay if using branded assets]
|
||||
- Product shot requirements: [e.g. Product must be clearly visible for minimum 5 seconds / in hands / in-use context only]
|
||||
- Setting: [e.g. Natural lifestyle setting preferred / office environment / no white studio backgrounds]
|
||||
- Avoid: [e.g. Clutter, competing products in frame, low lighting, filters that distort product colour]
|
||||
|
||||
**Script / storyline suggestions (creator's own words — these are starting points, not a script):**
|
||||
|
||||
Option A — Problem/Solution hook:
|
||||
> "I've been [doing thing that product solves] for years and it was always [pain point]. Then I found [product] and [specific outcome]. Here's how it works…"
|
||||
|
||||
Option B — Curiosity/Discovery hook:
|
||||
> "I got sent something I actually ended up using every day. [Product name]. And here's what surprised me about it…"
|
||||
|
||||
Option C — Social proof / endorsement:
|
||||
> "I know everyone says [category] tools are overhyped but [product] is genuinely different. The reason is [specific differentiator]…"
|
||||
|
||||
*The creator should use their own style and language — these are for inspiration only.*
|
||||
|
||||
---
|
||||
|
||||
## 6. Approval & Revision Process
|
||||
|
||||
**Pre-posting approval is required.** No content goes live without brand sign-off.
|
||||
|
||||
| Stage | Action required | Timeline | Contact |
|
||||
|---|---|---|---|
|
||||
| Script / treatment (if applicable) | Send for review | [X] days before shoot | [Brand contact name] |
|
||||
| Draft content (video / post) | Send for review | [X] working days before go-live | [Brand contact name] |
|
||||
| Brand feedback | Brands provide feedback | Within [X] working days | — |
|
||||
| Revisions | Creator amends (max [X] rounds) | Within [X] days of feedback | — |
|
||||
| Final approval | Brand sign-off | [X] days before go-live | — |
|
||||
|
||||
**Maximum revision rounds:** [X] rounds included in the fee. Additional rounds billed at [rate] or [approach].
|
||||
|
||||
**Feedback format:** [Brand] will provide written feedback via [email / shared doc]. Verbal feedback calls available on request.
|
||||
|
||||
---
|
||||
|
||||
## 7. Commercial Terms
|
||||
|
||||
| Term | Detail |
|
||||
|---|---|
|
||||
| Fee | [£/$/€ X] flat fee OR [rate per deliverable] |
|
||||
| Payment schedule | [50% on brief acceptance, 50% within 30 days of go-live] |
|
||||
| Affiliate / commission | [X% of sales via tracking link / code — paid monthly] |
|
||||
| Usage rights | [Organic social only / brand may amplify as paid ads / brand may repurpose in owned channels for X months] |
|
||||
| Exclusivity period | [X days pre-launch + X days post-launch — no direct competitor content] |
|
||||
| Gifted product | [List of products being gifted, approximate value] |
|
||||
| Contract | [Separate partnership agreement to follow / this brief serves as the agreement] |
|
||||
|
||||
---
|
||||
|
||||
## 8. Tracking & Measurement
|
||||
|
||||
How we'll measure success:
|
||||
|
||||
| KPI | Target | How measured |
|
||||
|---|---|---|
|
||||
| [Views / impressions] | [≥ X] | Platform analytics shared post-campaign |
|
||||
| [Engagement rate] | [≥ X%] | Platform analytics |
|
||||
| [Link clicks / swipe-ups] | [≥ X] | UTM link / affiliate link tracking |
|
||||
| [Conversions / sign-ups / sales] | [≥ X] | Promo code redemptions / UTM attribution |
|
||||
| [Reach / new audience] | [≥ X] | Platform analytics |
|
||||
|
||||
**Creator deliverables post-campaign:**
|
||||
- Provide screenshot or export of post analytics within [X] days of go-live
|
||||
- Share link to live content once posted
|
||||
- Notify brand contact immediately if post is removed or edited after approval
|
||||
|
||||
**Promo code / tracking link:**
|
||||
- Creator-specific code: [CODE] ([X]% off for creator's audience)
|
||||
- Tracking URL: [UTM link or affiliate URL]
|
||||
- Link placement: [Bio / pinned Story / video description]
|
||||
|
||||
---
|
||||
|
||||
## 9. Important Dates
|
||||
|
||||
| Milestone | Date |
|
||||
|---|---|
|
||||
| Brief sent to creator | [Date] |
|
||||
| Creator acceptance deadline | [Date] |
|
||||
| Contract signed | [Date] |
|
||||
| Product shipped / access provided | [Date] |
|
||||
| Draft content submitted to brand | [Date] |
|
||||
| Brand feedback returned | [Date] |
|
||||
| Final approval | [Date] |
|
||||
| Content go-live window | [Date → Date] |
|
||||
| Analytics report due from creator | [Date] |
|
||||
| Final payment | [Date] |
|
||||
|
||||
---
|
||||
|
||||
## 10. Useful Assets & Links
|
||||
|
||||
- Brand asset folder: [Link to Dropbox / Google Drive / Notion]
|
||||
- Product page / landing page: [URL]
|
||||
- Brand guidelines (if shared): [Link]
|
||||
- Previous campaign examples: [Links to past collab posts for style reference]
|
||||
- Brand contact: [Name, email, phone / WhatsApp for urgent queries]
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Deliverables are fully specified (platform, format, dimensions, duration, deadline)
|
||||
- [ ] Key messages include a specific, trackable CTA
|
||||
- [ ] Creative guidelines allow creative freedom while protecting brand
|
||||
- [ ] Approval process has clear timelines and named contacts
|
||||
- [ ] Commercial terms are complete — fee, payment schedule, usage rights, exclusivity
|
||||
- [ ] Tracking method is in place before campaign goes live
|
||||
- [ ] Disclosure requirements are clearly stated (FTC / ASA compliance)
|
||||
- [ ] Important dates include a buffer for revisions
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- "Write an influencer brief for our product launch"
|
||||
- "Create a creator partnership brief for [campaign]"
|
||||
- "Draft a brief for a TikTok influencer collab"
|
||||
- "Build a paid partnership brief for [brand]"
|
||||
- "What should I include in an influencer campaign brief?"
|
||||
@@ -0,0 +1,665 @@
|
||||
---
|
||||
name: instagram-post-downloader
|
||||
description: "Download Instagram posts — single images or full carousels — directly from a URL. Fetches high-resolution files from Instagram's CDN, saves them into a named folder, and stitches carousel slides into a single PDF. Supports batch downloading of multiple URLs at once. Use when asked to download, save, or archive an Instagram post, reel thumbnail, or carousel."
|
||||
---
|
||||
|
||||
# Instagram Post Downloader Skill
|
||||
|
||||
Downloads Instagram posts at full resolution from Instagram's CDN — no screenshots, no compression. Handles single images, carousels (multi-slide posts), and Reel cover images. For carousels, produces individual slide files plus a single stitched PDF. Supports batch URLs in one run.
|
||||
|
||||
---
|
||||
|
||||
## PREREQUISITE — Domain Allowlist
|
||||
|
||||
Before this skill can fetch any media, you must add Instagram's CDN domain to Claude Code's allowlist:
|
||||
|
||||
**Settings → Capabilities → Domain allowlist → Add:**
|
||||
```
|
||||
*.cdninstagram.com
|
||||
```
|
||||
|
||||
Without this, all CDN fetch calls will be blocked. If you see a permission error when Claude attempts a fetch to `cdninstagram.com`, this is the fix.
|
||||
|
||||
---
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Claude will ask for these if not provided upfront:
|
||||
|
||||
| Input | Required | Notes |
|
||||
|---|---|---|
|
||||
| Instagram post URL(s) | Yes | One per line, or comma-separated. `https://www.instagram.com/p/XXXX/` or `https://www.instagram.com/reel/XXXX/` format |
|
||||
| Output directory | No | Defaults to `./instagram-downloads/` in the current working directory |
|
||||
| PDF stitch for carousels | No | Defaults to **yes** — produces `carousel.pdf` alongside individual slides |
|
||||
| File naming prefix | No | Optional prefix added before slide filenames, e.g. `brand_` → `brand_slide_01.jpg` |
|
||||
|
||||
**Batch input example:**
|
||||
```
|
||||
https://www.instagram.com/p/ABC123/
|
||||
https://www.instagram.com/p/DEF456/
|
||||
https://www.instagram.com/p/GHI789/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Output Structure
|
||||
|
||||
For each URL processed, Claude creates a folder named after the post caption (first 40 characters, sanitised — spaces become underscores, special characters stripped). If no caption is available, the folder is named after the post shortcode.
|
||||
|
||||
### Single image post
|
||||
|
||||
```
|
||||
instagram-downloads/
|
||||
└── this_is_the_caption_first_40_chars/
|
||||
├── image.jpg
|
||||
└── metadata.txt
|
||||
```
|
||||
|
||||
### Carousel post
|
||||
|
||||
```
|
||||
instagram-downloads/
|
||||
└── carousel_caption_first_40_chars/
|
||||
├── slide_01.jpg
|
||||
├── slide_02.jpg
|
||||
├── slide_03.jpg
|
||||
├── slide_04.jpg
|
||||
├── carousel.pdf ← all slides stitched in order
|
||||
└── metadata.txt
|
||||
```
|
||||
|
||||
### Batch run (3 URLs)
|
||||
|
||||
```
|
||||
instagram-downloads/
|
||||
├── first_post_caption_sanitised/
|
||||
│ ├── image.jpg
|
||||
│ └── metadata.txt
|
||||
├── second_post_carousel_caption/
|
||||
│ ├── slide_01.jpg
|
||||
│ ├── slide_02.jpg
|
||||
│ ├── carousel.pdf
|
||||
│ └── metadata.txt
|
||||
└── third_post_caption_here/
|
||||
├── image.jpg
|
||||
└── metadata.txt
|
||||
```
|
||||
|
||||
### metadata.txt format
|
||||
|
||||
```
|
||||
Post URL: https://www.instagram.com/p/XXXX/
|
||||
Shortcode: XXXX
|
||||
Type: carousel | single_image | reel
|
||||
Slide count: 4 (carousel only)
|
||||
Caption: [full caption text]
|
||||
Username: @username
|
||||
Fetched at: 2026-05-27T14:32:00Z
|
||||
CDN URLs:
|
||||
slide_01.jpg https://scontent.cdninstagram.com/v/...
|
||||
slide_02.jpg https://scontent.cdninstagram.com/v/...
|
||||
```
|
||||
|
||||
### Completion summary (printed to terminal)
|
||||
|
||||
```
|
||||
Instagram Post Downloader — Batch Complete
|
||||
==========================================
|
||||
URLs processed: 3
|
||||
Posts saved: 3
|
||||
Total files: 11 (9 images + 2 PDFs)
|
||||
Skipped: 0
|
||||
Output dir: /Users/you/project/instagram-downloads/
|
||||
|
||||
Results:
|
||||
✓ this_is_the_caption_first_40_chars/ 1 image
|
||||
✓ carousel_caption_first_40_chars/ 4 slides → carousel.pdf
|
||||
✓ third_post_caption_here/ 1 image
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## How Claude Should Execute This Skill
|
||||
|
||||
### Step 1 — Collect and validate inputs
|
||||
|
||||
1. Accept the URL(s) from the user. If the user pastes a comma-separated list, split on commas. If they paste one per line, split on newlines.
|
||||
2. Validate each URL matches `instagram.com/p/`, `instagram.com/reel/`, or `instagram.com/tv/`. Flag malformed URLs before proceeding.
|
||||
3. Confirm the output directory. If none provided, use `./instagram-downloads/` and tell the user.
|
||||
4. Ask about PDF stitching preference only if the user hasn't said either way. Default is yes.
|
||||
|
||||
### Step 2 — For each URL: fetch the post page
|
||||
|
||||
Fetch the Instagram post page HTML:
|
||||
|
||||
```
|
||||
GET https://www.instagram.com/p/{shortcode}/?__a=1&__d=dis
|
||||
```
|
||||
|
||||
Instagram frequently changes its API surface. Use this fallback chain in order:
|
||||
|
||||
**Attempt A — JSON endpoint:**
|
||||
```
|
||||
https://www.instagram.com/p/{shortcode}/?__a=1&__d=dis
|
||||
```
|
||||
Parse the JSON response. Look for `graphql.shortcode_media` or `data.shortcode_media`.
|
||||
|
||||
**Attempt B — Embed page (most reliable):**
|
||||
```
|
||||
https://www.instagram.com/p/{shortcode}/embed/captioned/
|
||||
```
|
||||
Fetch this page's HTML and extract `og:image` meta tags and any `window.__additionalDataLoaded` or `window.__StaticData` JSON blobs embedded in `<script>` tags.
|
||||
|
||||
**Attempt C — oEmbed endpoint:**
|
||||
```
|
||||
https://api.instagram.com/oembed/?url=https://www.instagram.com/p/{shortcode}/&omitscript=true
|
||||
```
|
||||
This returns `thumbnail_url` — useful for single images, but only gives the first frame for carousels.
|
||||
|
||||
**Headers to include on all requests:**
|
||||
```
|
||||
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36
|
||||
Accept-Language: en-US,en;q=0.9
|
||||
Accept: text/html,application/xhtml+xml,application/json
|
||||
```
|
||||
|
||||
### Step 3 — Extract CDN image URLs
|
||||
|
||||
From the fetched data, extract all high-resolution CDN URLs. Instagram CDN URLs follow these patterns:
|
||||
|
||||
```
|
||||
https://scontent.cdninstagram.com/v/...jpg?...
|
||||
https://scontent-lax3-1.cdninstagram.com/v/...jpg?...
|
||||
https://instagram.fXXX1-1.fbcdn.net/v/...jpg?...
|
||||
```
|
||||
|
||||
**For single image posts:**
|
||||
- Extract the single `display_url` or the largest `display_resources` entry (pick the one with the highest `config_width`).
|
||||
|
||||
**For carousel posts:**
|
||||
- Look for `edge_sidecar_to_children.edges[]` in the JSON. Each edge has its own `node.display_url` and `node.display_resources[]`.
|
||||
- Iterate all edges in order. This determines slide numbering.
|
||||
- Pick the highest-resolution variant from each slide's `display_resources` array.
|
||||
|
||||
**For Reels:**
|
||||
- The cover image is extractable the same way as a single image.
|
||||
- The video file itself requires a third-party tool (see Bonus section).
|
||||
|
||||
**If JSON extraction fails**, fall back to scraping `<meta property="og:image">` tags from the page HTML — this gives at least one image URL (the first slide or only image).
|
||||
|
||||
### Step 4 — Sanitise folder name
|
||||
|
||||
Build the folder name from the post caption:
|
||||
1. Take the first 40 characters of the caption.
|
||||
2. Strip all characters that are not alphanumeric, spaces, or hyphens.
|
||||
3. Replace spaces and hyphens with underscores.
|
||||
4. Lowercase the result.
|
||||
5. Strip leading/trailing underscores.
|
||||
6. If the result is empty (e.g. caption was all emoji), use the post shortcode instead.
|
||||
|
||||
```python
|
||||
import re
|
||||
|
||||
def sanitise_folder_name(caption: str, shortcode: str) -> str:
|
||||
truncated = caption[:40]
|
||||
cleaned = re.sub(r'[^a-zA-Z0-9 \-]', '', truncated)
|
||||
underscored = re.sub(r'[\s\-]+', '_', cleaned).strip('_').lower()
|
||||
return underscored if underscored else shortcode
|
||||
```
|
||||
|
||||
### Step 5 — Create output folder structure
|
||||
|
||||
```python
|
||||
import os
|
||||
|
||||
base_dir = "./instagram-downloads"
|
||||
folder_name = sanitise_folder_name(caption, shortcode)
|
||||
post_dir = os.path.join(base_dir, folder_name)
|
||||
os.makedirs(post_dir, exist_ok=True)
|
||||
```
|
||||
|
||||
If a folder with that name already exists (e.g. running the same URL twice), append the shortcode to avoid collision: `folder_name_SHORTCODE`.
|
||||
|
||||
### Step 6 — Download each image file
|
||||
|
||||
For each CDN URL, download the file with a streaming GET request:
|
||||
|
||||
```python
|
||||
import requests
|
||||
|
||||
def download_file(url: str, dest_path: str) -> bool:
|
||||
headers = {
|
||||
"User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
|
||||
"Referer": "https://www.instagram.com/",
|
||||
}
|
||||
response = requests.get(url, headers=headers, stream=True, timeout=30)
|
||||
response.raise_for_status()
|
||||
with open(dest_path, "wb") as f:
|
||||
for chunk in response.iter_content(chunk_size=8192):
|
||||
f.write(chunk)
|
||||
return True
|
||||
```
|
||||
|
||||
Name files:
|
||||
- Single image: `image.jpg`
|
||||
- Carousel slides: `slide_01.jpg`, `slide_02.jpg`, ... (zero-padded to 2 digits, or 3 digits if >99 slides)
|
||||
|
||||
Detect file format from the `Content-Type` header or URL extension. Instagram serves JPEG for photos and may serve WebP in some cases — preserve the actual extension.
|
||||
|
||||
### Step 7 — Stitch carousel PDF (if applicable)
|
||||
|
||||
After all slides are downloaded, stitch them into a single PDF using Pillow:
|
||||
|
||||
```python
|
||||
from PIL import Image
|
||||
|
||||
def stitch_to_pdf(image_paths: list[str], output_path: str) -> None:
|
||||
"""
|
||||
Combine a list of image files into a single multi-page PDF.
|
||||
Each image becomes one page. Page size matches the image dimensions.
|
||||
"""
|
||||
images = []
|
||||
for path in sorted(image_paths): # sort ensures slide_01, slide_02, ... order
|
||||
img = Image.open(path).convert("RGB")
|
||||
images.append(img)
|
||||
|
||||
if not images:
|
||||
return
|
||||
|
||||
first = images[0]
|
||||
rest = images[1:]
|
||||
first.save(
|
||||
output_path,
|
||||
format="PDF",
|
||||
save_all=True,
|
||||
append_images=rest,
|
||||
resolution=150.0,
|
||||
)
|
||||
```
|
||||
|
||||
Save as `carousel.pdf` in the post folder. If Pillow is not installed, run `pip install Pillow` first — or instruct the user to do so.
|
||||
|
||||
**Dependency check at start of skill:**
|
||||
```python
|
||||
try:
|
||||
from PIL import Image
|
||||
except ImportError:
|
||||
print("Pillow not installed. Run: pip install Pillow")
|
||||
print("PDF stitching will be skipped. Individual slides will still be downloaded.")
|
||||
skip_pdf = True
|
||||
```
|
||||
|
||||
### Step 8 — Write metadata.txt
|
||||
|
||||
Write a `metadata.txt` file into the post folder with all extracted metadata:
|
||||
|
||||
```python
|
||||
from datetime import datetime, timezone
|
||||
|
||||
def write_metadata(post_dir, post_url, shortcode, post_type, caption, username, cdn_urls):
|
||||
lines = [
|
||||
f"Post URL: {post_url}",
|
||||
f"Shortcode: {shortcode}",
|
||||
f"Type: {post_type}",
|
||||
]
|
||||
if post_type == "carousel":
|
||||
lines.append(f"Slide count: {len(cdn_urls)}")
|
||||
lines += [
|
||||
f"Caption: {caption}",
|
||||
f"Username: @{username}",
|
||||
f"Fetched at: {datetime.now(timezone.utc).isoformat()}",
|
||||
"CDN URLs:",
|
||||
]
|
||||
for filename, url in cdn_urls.items():
|
||||
lines.append(f" {filename:<16} {url}")
|
||||
|
||||
with open(os.path.join(post_dir, "metadata.txt"), "w", encoding="utf-8") as f:
|
||||
f.write("\n".join(lines) + "\n")
|
||||
```
|
||||
|
||||
### Step 9 — Print completion summary
|
||||
|
||||
After processing all URLs, print the summary table to the terminal (format shown in Output Structure section above). Include:
|
||||
- Total URLs attempted
|
||||
- Posts successfully saved
|
||||
- Total files written (images + PDFs separately)
|
||||
- Any URLs that were skipped and the reason
|
||||
|
||||
### Step 10 — Handle errors gracefully
|
||||
|
||||
| Error scenario | Action |
|
||||
|---|---|
|
||||
| URL is not an Instagram URL | Skip with message: "Skipped — not an Instagram URL: [url]" |
|
||||
| Post is private or requires login | Skip with message: "Skipped — post is private or login required: [url]" |
|
||||
| CDN fetch returns 403/404 | Try alternate CDN URL if available; if none, skip slide and note in metadata |
|
||||
| Pillow not installed | Skip PDF stitching, save slides only, note in summary |
|
||||
| Network timeout | Retry once after 5 seconds; if still failing, skip and log |
|
||||
| Folder name collision | Append shortcode suffix to folder name |
|
||||
| Rate limiting (429) | Wait 10 seconds and retry; log if retry also fails |
|
||||
|
||||
---
|
||||
|
||||
## Bonus — Downloading Instagram Reels (Video)
|
||||
|
||||
This skill covers images and carousel PDFs. For Reels video files, Claude Code cannot download video directly without a third-party tool, because Instagram's video CDN uses signed URLs and additional auth tokens.
|
||||
|
||||
**Recommended approach for Reels:**
|
||||
|
||||
Use `yt-dlp`, a maintained open-source tool:
|
||||
|
||||
```bash
|
||||
# Install
|
||||
pip install yt-dlp
|
||||
|
||||
# Download a Reel
|
||||
yt-dlp "https://www.instagram.com/reel/XXXX/" -o "%(title)s.%(ext)s"
|
||||
|
||||
# Download to a specific folder
|
||||
yt-dlp "https://www.instagram.com/reel/XXXX/" \
|
||||
-o "./instagram-downloads/%(uploader)s_%(id)s.%(ext)s"
|
||||
|
||||
# Download best quality
|
||||
yt-dlp -f "bestvideo+bestaudio" "https://www.instagram.com/reel/XXXX/"
|
||||
```
|
||||
|
||||
Claude can run this command via Bash if the user asks. `yt-dlp` handles the auth token extraction automatically for public Reels.
|
||||
|
||||
---
|
||||
|
||||
## Full Script Template
|
||||
|
||||
Claude should offer to write this as a standalone script (`instagram_downloader.py`) that the user can run independently:
|
||||
|
||||
```python
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
Instagram Post Downloader
|
||||
Fetches high-res images from public Instagram posts and carousels.
|
||||
Requires: pip install requests Pillow
|
||||
"""
|
||||
|
||||
import os
|
||||
import re
|
||||
import sys
|
||||
import json
|
||||
import time
|
||||
import requests
|
||||
from datetime import datetime, timezone
|
||||
from pathlib import Path
|
||||
|
||||
try:
|
||||
from PIL import Image
|
||||
PILLOW_AVAILABLE = True
|
||||
except ImportError:
|
||||
PILLOW_AVAILABLE = False
|
||||
print("Warning: Pillow not installed. PDF stitching disabled. Run: pip install Pillow")
|
||||
|
||||
|
||||
HEADERS = {
|
||||
"User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 "
|
||||
"(KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
|
||||
"Accept-Language": "en-US,en;q=0.9",
|
||||
"Referer": "https://www.instagram.com/",
|
||||
}
|
||||
|
||||
|
||||
def extract_shortcode(url: str) -> str:
|
||||
match = re.search(r"instagram\.com/(?:p|reel|tv)/([A-Za-z0-9_-]+)", url)
|
||||
if not match:
|
||||
raise ValueError(f"Cannot extract shortcode from URL: {url}")
|
||||
return match.group(1)
|
||||
|
||||
|
||||
def fetch_post_data(shortcode: str) -> dict:
|
||||
"""Try multiple endpoints to get post JSON data."""
|
||||
# Attempt A: JSON endpoint
|
||||
try:
|
||||
url = f"https://www.instagram.com/p/{shortcode}/?__a=1&__d=dis"
|
||||
r = requests.get(url, headers=HEADERS, timeout=15)
|
||||
if r.status_code == 200:
|
||||
data = r.json()
|
||||
media = (data.get("graphql", {}).get("shortcode_media") or
|
||||
data.get("data", {}).get("shortcode_media"))
|
||||
if media:
|
||||
return media
|
||||
except Exception:
|
||||
pass
|
||||
|
||||
# Attempt B: Embed page
|
||||
try:
|
||||
url = f"https://www.instagram.com/p/{shortcode}/embed/captioned/"
|
||||
r = requests.get(url, headers=HEADERS, timeout=15)
|
||||
html = r.text
|
||||
# Look for JSON blob in script tags
|
||||
matches = re.findall(r'window\.__additionalDataLoaded\([^,]+,(\{.+?\})\);', html)
|
||||
for blob in matches:
|
||||
try:
|
||||
data = json.loads(blob)
|
||||
media = (data.get("graphql", {}).get("shortcode_media") or
|
||||
data.get("data", {}).get("shortcode_media"))
|
||||
if media:
|
||||
return media
|
||||
except json.JSONDecodeError:
|
||||
continue
|
||||
except Exception:
|
||||
pass
|
||||
|
||||
return {}
|
||||
|
||||
|
||||
def get_cdn_urls(media: dict) -> list[tuple[str, str]]:
|
||||
"""Return list of (filename, cdn_url) tuples."""
|
||||
results = []
|
||||
media_type = media.get("__typename", "")
|
||||
|
||||
if media_type == "GraphSidecar":
|
||||
edges = media.get("edge_sidecar_to_children", {}).get("edges", [])
|
||||
for i, edge in enumerate(edges, start=1):
|
||||
node = edge.get("node", {})
|
||||
resources = node.get("display_resources", [])
|
||||
url = (max(resources, key=lambda r: r.get("config_width", 0)).get("src")
|
||||
if resources else node.get("display_url", ""))
|
||||
if url:
|
||||
ext = "jpg" if "jpg" in url.lower() else "webp"
|
||||
filename = f"slide_{i:02d}.{ext}"
|
||||
results.append((filename, url))
|
||||
else:
|
||||
resources = media.get("display_resources", [])
|
||||
url = (max(resources, key=lambda r: r.get("config_width", 0)).get("src")
|
||||
if resources else media.get("display_url", ""))
|
||||
if url:
|
||||
ext = "jpg" if "jpg" in url.lower() else "webp"
|
||||
results.append((f"image.{ext}", url))
|
||||
|
||||
return results
|
||||
|
||||
|
||||
def sanitise_folder_name(caption: str, shortcode: str) -> str:
|
||||
truncated = caption[:40] if caption else ""
|
||||
cleaned = re.sub(r"[^a-zA-Z0-9 \-]", "", truncated)
|
||||
underscored = re.sub(r"[\s\-]+", "_", cleaned).strip("_").lower()
|
||||
return underscored if underscored else shortcode
|
||||
|
||||
|
||||
def download_file(url: str, dest_path: str) -> bool:
|
||||
r = requests.get(url, headers=HEADERS, stream=True, timeout=30)
|
||||
r.raise_for_status()
|
||||
with open(dest_path, "wb") as f:
|
||||
for chunk in r.iter_content(chunk_size=8192):
|
||||
f.write(chunk)
|
||||
return True
|
||||
|
||||
|
||||
def stitch_pdf(image_paths: list[str], output_path: str) -> None:
|
||||
if not PILLOW_AVAILABLE:
|
||||
return
|
||||
images = [Image.open(p).convert("RGB") for p in sorted(image_paths)]
|
||||
if images:
|
||||
images[0].save(output_path, format="PDF", save_all=True,
|
||||
append_images=images[1:], resolution=150.0)
|
||||
|
||||
|
||||
def process_url(post_url: str, base_dir: str, stitch_pdf_flag: bool) -> dict:
|
||||
result = {"url": post_url, "status": "ok", "files": [], "error": None}
|
||||
try:
|
||||
shortcode = extract_shortcode(post_url)
|
||||
media = fetch_post_data(shortcode)
|
||||
|
||||
caption = ""
|
||||
username = ""
|
||||
if media:
|
||||
caption_edges = media.get("edge_media_to_caption", {}).get("edges", [])
|
||||
caption = caption_edges[0]["node"]["text"] if caption_edges else ""
|
||||
owner = media.get("owner", {})
|
||||
username = owner.get("username", "")
|
||||
|
||||
folder_name = sanitise_folder_name(caption, shortcode)
|
||||
post_dir = os.path.join(base_dir, folder_name)
|
||||
if os.path.exists(post_dir):
|
||||
post_dir = f"{post_dir}_{shortcode}"
|
||||
os.makedirs(post_dir, exist_ok=True)
|
||||
|
||||
cdn_urls = get_cdn_urls(media) if media else []
|
||||
if not cdn_urls:
|
||||
# Fallback: oEmbed
|
||||
oembed_url = f"https://api.instagram.com/oembed/?url={post_url}&omitscript=true"
|
||||
r = requests.get(oembed_url, headers=HEADERS, timeout=10)
|
||||
if r.status_code == 200:
|
||||
thumb = r.json().get("thumbnail_url", "")
|
||||
if thumb:
|
||||
cdn_urls = [("image.jpg", thumb)]
|
||||
username = r.json().get("author_name", "")
|
||||
|
||||
downloaded_paths = []
|
||||
cdn_map = {}
|
||||
for filename, url in cdn_urls:
|
||||
dest = os.path.join(post_dir, filename)
|
||||
download_file(url, dest)
|
||||
downloaded_paths.append(dest)
|
||||
cdn_map[filename] = url
|
||||
result["files"].append(filename)
|
||||
|
||||
if stitch_pdf_flag and len(downloaded_paths) > 1 and PILLOW_AVAILABLE:
|
||||
pdf_path = os.path.join(post_dir, "carousel.pdf")
|
||||
stitch_pdf(downloaded_paths, pdf_path)
|
||||
result["files"].append("carousel.pdf")
|
||||
|
||||
post_type = "carousel" if len(cdn_urls) > 1 else "single_image"
|
||||
write_metadata(post_dir, post_url, shortcode, post_type, caption, username, cdn_map)
|
||||
result["files"].append("metadata.txt")
|
||||
|
||||
except Exception as e:
|
||||
result["status"] = "error"
|
||||
result["error"] = str(e)
|
||||
|
||||
return result
|
||||
|
||||
|
||||
def write_metadata(post_dir, post_url, shortcode, post_type, caption, username, cdn_map):
|
||||
lines = [
|
||||
f"Post URL: {post_url}",
|
||||
f"Shortcode: {shortcode}",
|
||||
f"Type: {post_type}",
|
||||
]
|
||||
if post_type == "carousel":
|
||||
lines.append(f"Slide count: {len([k for k in cdn_map if 'slide' in k])}")
|
||||
lines += [
|
||||
f"Caption: {caption}",
|
||||
f"Username: @{username}",
|
||||
f"Fetched at: {datetime.now(timezone.utc).isoformat()}",
|
||||
"CDN URLs:",
|
||||
]
|
||||
for fn, url in cdn_map.items():
|
||||
lines.append(f" {fn:<18} {url}")
|
||||
with open(os.path.join(post_dir, "metadata.txt"), "w", encoding="utf-8") as f:
|
||||
f.write("\n".join(lines) + "\n")
|
||||
|
||||
|
||||
def main(urls: list[str], base_dir: str = "./instagram-downloads", stitch: bool = True):
|
||||
os.makedirs(base_dir, exist_ok=True)
|
||||
results = []
|
||||
for url in urls:
|
||||
url = url.strip()
|
||||
if not url:
|
||||
continue
|
||||
print(f"Processing: {url}")
|
||||
r = process_url(url, base_dir, stitch)
|
||||
results.append(r)
|
||||
time.sleep(1) # polite delay between requests
|
||||
|
||||
# Summary
|
||||
ok = [r for r in results if r["status"] == "ok"]
|
||||
err = [r for r in results if r["status"] == "error"]
|
||||
total_files = sum(len(r["files"]) for r in ok)
|
||||
print("\nInstagram Post Downloader — Batch Complete")
|
||||
print("==========================================")
|
||||
print(f"URLs processed: {len(results)}")
|
||||
print(f"Posts saved: {len(ok)}")
|
||||
print(f"Total files: {total_files}")
|
||||
print(f"Errors: {len(err)}")
|
||||
print(f"Output dir: {os.path.abspath(base_dir)}\n")
|
||||
for r in results:
|
||||
if r["status"] == "ok":
|
||||
print(f" OK {r['url']}")
|
||||
else:
|
||||
print(f" ERR {r['url']} — {r['error']}")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
if len(sys.argv) < 2:
|
||||
print("Usage: python instagram_downloader.py <url1> [url2] ...")
|
||||
sys.exit(1)
|
||||
main(sys.argv[1:])
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
Before marking the task complete, verify each item:
|
||||
|
||||
- [ ] Domain allowlist confirmed — `*.cdninstagram.com` is added before any fetch attempts
|
||||
- [ ] All provided URLs validated as Instagram URLs before processing begins
|
||||
- [ ] CDN URLs are the highest-resolution variants available (largest `config_width` selected)
|
||||
- [ ] Folder name is sanitised — no special characters, no spaces, max 40 chars from caption
|
||||
- [ ] Folder collision handled — shortcode appended if folder already exists
|
||||
- [ ] Carousel slides numbered sequentially with zero-padding (`slide_01`, `slide_02`, ...)
|
||||
- [ ] PDF includes all slides in correct order (not alphabetical — by slide index)
|
||||
- [ ] metadata.txt written to every post folder, including full CDN URLs
|
||||
- [ ] Pillow dependency checked at startup — graceful fallback if not available
|
||||
- [ ] Batch completion summary printed with file counts and any errors
|
||||
- [ ] Private post errors caught and reported — not silently skipped
|
||||
- [ ] Rate limiting handled — at least 1 second delay between requests
|
||||
- [ ] No credential or cookie storage — skill operates on public posts only
|
||||
|
||||
---
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- "Download this Instagram post for me: https://www.instagram.com/p/ABC123/"
|
||||
- "Save that carousel to my downloads folder"
|
||||
- "Can you grab all the slides from this Instagram post and make a PDF?"
|
||||
- "Download these 5 Instagram posts" [followed by list of URLs]
|
||||
- "Archive this IG post before it gets deleted"
|
||||
- "I need the full-res images from this carousel"
|
||||
- "Download the images from this Instagram URL and stitch them into a PDF"
|
||||
- "Batch download these Instagram posts" [followed by URLs]
|
||||
- "Save the slides from this Instagram carousel as individual JPEGs"
|
||||
- "Get me the high-res version of this Instagram image"
|
||||
|
||||
---
|
||||
|
||||
## Notes on Instagram's Anti-Scraping Measures
|
||||
|
||||
Instagram actively changes its page structure and API endpoints. If all three fetch attempts fail:
|
||||
|
||||
1. The embed page method (`/embed/captioned/`) is historically the most stable — start there.
|
||||
2. CDN URLs expire. Download immediately after fetching — do not store URLs and download later.
|
||||
3. Instagram may return a login wall for some posts even if they're technically public. If this happens, the skill cannot proceed without authentication (which is out of scope).
|
||||
4. If Instagram returns a 429, wait 10–30 seconds before retrying. Reduce batch size for large lists.
|
||||
|
||||
This skill is designed for public posts only. It does not support login, sessions, or private content.
|
||||
|
||||
---
|
||||
|
||||
*Originally inspired by a skill from Frank and Diana Dovgopol (Write, Prompt, Scale) — adapted and extended for this library.*
|
||||
@@ -0,0 +1,150 @@
|
||||
---
|
||||
name: last-30-days-research
|
||||
description: Multi-platform research skill that gathers recent (last 30 days) opinions, sentiment, and signal on any topic from Reddit, X/Twitter, and the web. Cuts through SEO-stuffed results to surface what real people are actually saying.
|
||||
---
|
||||
|
||||
# Last 30 Days Research
|
||||
|
||||
## The Problem
|
||||
|
||||
Googling gives SEO-stuffed "best of" lists written six months ago by someone who has never used the thing. Real honest takes live on Reddit threads, X replies, and niche communities — but chasing them across platforms eats your afternoon. This skill does the chase for you.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
| Input | Required | Notes |
|
||||
|-------|----------|-------|
|
||||
| Topic | Yes | Tool, trend, feature, product, event, company — anything with a name |
|
||||
| Date scope | No | Defaults to last 30 days. Can override to last 7 days or last 90 days |
|
||||
| Angle | No | e.g. "focus on developer sentiment" or "looking for pricing complaints specifically" |
|
||||
|
||||
## Output Structure
|
||||
|
||||
The output is a structured research report with the following sections, delivered in this exact order:
|
||||
|
||||
```
|
||||
## Last 30 Days Research: [Topic]
|
||||
Research window: [Date 30 days ago] → [Today's date]
|
||||
|
||||
---
|
||||
|
||||
## What People Agree On
|
||||
[Consensus points that appear across multiple platforms — most reliable signal]
|
||||
|
||||
## Where People Disagree
|
||||
[Active debates, contrasting views — include which side has more weight]
|
||||
|
||||
## Pain Points That Keep Coming Up
|
||||
[Recurring complaints and frustrations — strongest signal of real problems]
|
||||
|
||||
## Positive Signals
|
||||
[What people genuinely praise — not PR, but unprompted appreciation]
|
||||
|
||||
## Most Interesting Takes
|
||||
[Contrarian, unexpected, or surprisingly insightful comments worth noting]
|
||||
|
||||
## Sources
|
||||
[Links to the most useful threads/posts found — 5–10 links with brief labels]
|
||||
|
||||
## Signal Confidence
|
||||
[High / Medium / Low — with a one-line rationale based on data volume and consistency]
|
||||
```
|
||||
|
||||
Each section should contain substantive content, not placeholders. If a section has no findings (e.g. no positive signals found), state that explicitly rather than leaving it empty or fabricating content.
|
||||
|
||||
## Instructions for Claude
|
||||
|
||||
### Step 1 — Calculate the date window
|
||||
|
||||
Determine today's date and subtract 30 days to get the research start date. Format: YYYY-MM-DD. Use these dates explicitly in every search query.
|
||||
|
||||
### Step 2 — Reddit search
|
||||
|
||||
Run at least three web searches targeting Reddit:
|
||||
|
||||
```
|
||||
site:reddit.com "[topic]" after:[30-days-ago-date]
|
||||
site:reddit.com "[topic]" 2025
|
||||
reddit.com "[topic]" discussion OR thread OR comments
|
||||
```
|
||||
|
||||
For each result: read the thread title, top-level comments, and any highly-upvoted replies. Record the key claims and the URL.
|
||||
|
||||
If the topic has common synonyms or abbreviations, run additional searches with those (e.g. "Claude Code" and "claude.code" and "Anthropic coding tool").
|
||||
|
||||
### Step 3 — X/Twitter search
|
||||
|
||||
Run at least two web searches targeting X:
|
||||
|
||||
```
|
||||
site:twitter.com OR site:x.com "[topic]" after:[30-days-ago-date]
|
||||
"[topic]" site:x.com -is:retweet
|
||||
```
|
||||
|
||||
Note: X search via web has limitations. If results are sparse, supplement with searches for specific accounts known to discuss the topic area (e.g. tech journalists, domain experts).
|
||||
|
||||
### Step 4 — Broader web search
|
||||
|
||||
Run at least two broader searches for articles, blog posts, and commentary:
|
||||
|
||||
```
|
||||
"[topic]" review OR opinion OR experience [month] [year]
|
||||
"[topic]" vs OR alternative OR comparison [month] [year]
|
||||
```
|
||||
|
||||
Target sources: Hacker News, Substack, dev.to, personal blogs, product communities. Avoid press releases and vendor-authored content.
|
||||
|
||||
### Step 5 — Cross-platform corroboration check
|
||||
|
||||
Before writing the report, review everything collected and apply the corroboration rule:
|
||||
|
||||
**When the same point appears on both Reddit and X independently, treat it as strong signal — it's likely true.**
|
||||
|
||||
A point mentioned only once on one platform is a data point, not a finding. Weight your sections accordingly.
|
||||
|
||||
### Step 6 — Write the report
|
||||
|
||||
Populate each section of the output structure. Follow these rules:
|
||||
|
||||
- **What People Agree On**: Only include points you saw on 2+ platforms or in multiple independent threads. These are your most reliable findings.
|
||||
- **Where People Disagree**: Name the sides. "Some say X, others say Y — and the X camp seems louder based on upvote counts / engagement."
|
||||
- **Pain Points**: Be specific. "Performance issues" is weak. "Cold start times over 4 seconds on the free tier" is useful.
|
||||
- **Positive Signals**: Must be unprompted praise, not from product marketing or sponsored content.
|
||||
- **Most Interesting Takes**: At least 2, maximum 5. Quote or closely paraphrase where possible.
|
||||
- **Sources**: Include the actual URLs. Label each one briefly (e.g. "Reddit thread: 'Has anyone switched from X to Y?'").
|
||||
- **Signal Confidence**: Rate High/Medium/Low based on:
|
||||
- High = 10+ sources, consistent signal across platforms
|
||||
- Medium = 5–10 sources, some inconsistency
|
||||
- Low = fewer than 5 sources, or highly fragmented signal
|
||||
|
||||
### Step 7 — Sanity check before delivering
|
||||
|
||||
Before outputting the report, verify:
|
||||
|
||||
- [ ] Every claim in the report traces to an actual source found during research (not prior knowledge)
|
||||
- [ ] The date window was actually applied to searches, not ignored
|
||||
- [ ] No fabricated or hallucinated URLs in the Sources section
|
||||
- [ ] Signal Confidence rating reflects the actual data volume, not optimism
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] At minimum 3 Reddit searches were run with the date filter applied
|
||||
- [ ] At minimum 2 X/Twitter searches were run
|
||||
- [ ] At minimum 2 broader web searches were run
|
||||
- [ ] Cross-platform corroboration principle was applied (same point on multiple platforms = stronger signal)
|
||||
- [ ] Pain Points section contains specific, concrete details — not vague generalisations
|
||||
- [ ] Sources section contains real URLs (not hallucinated), verified during research
|
||||
- [ ] Signal Confidence is rated and justified
|
||||
- [ ] If a section has no findings, it says so explicitly rather than being omitted or padded
|
||||
- [ ] No vendor-authored content or press releases treated as independent signal
|
||||
- [ ] Synonyms and alternative names for the topic were searched
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- "What are people saying about Cursor AI from the last 30 days?"
|
||||
- "Research Vercel's recent sentiment"
|
||||
- "Last 30 days on the Arc browser shutdown"
|
||||
- "What's the current vibe on Supabase?"
|
||||
- "What are developers saying about Claude Code lately?"
|
||||
- "Research [topic] from the last 30 days"
|
||||
- "Give me a signal report on [product]"
|
||||
- "What's the Reddit and Twitter take on [trend]?"
|
||||
@@ -0,0 +1,198 @@
|
||||
---
|
||||
name: morning-intelligence
|
||||
description: "Run a 15-question interview to capture your role, topics, sources, exclusions, and format preferences — then write a master prompt you can drop into a scheduled task or Claude Code Routine to get a personalised news brief every morning. Use when asked to set up a morning intelligence brief, build a morning news prompt, or create a personalised news briefing."
|
||||
---
|
||||
|
||||
# Morning Intelligence Skill
|
||||
|
||||
Write the prompt that writes your briefing. A 15-question interview extracts your exact context — role, topics, sources, exclusions, format, recency — then produces a single master prompt you can paste into a scheduled task or Claude Code Routine and never touch again.
|
||||
|
||||
> **Pro tip:** Run this interview with Opus for the best output. Opus asks sharper follow-up questions and writes a tighter master prompt.
|
||||
|
||||
> **Credit:** Originally created by Ashwin Francis (Cash&Cache) — adapted and extended for this library.
|
||||
|
||||
---
|
||||
|
||||
## Required Inputs
|
||||
|
||||
No inputs required upfront. The skill runs the interview first.
|
||||
|
||||
If the user has already provided context (e.g. pasted a role description or topic list), absorb it and skip those questions in the interview — don't ask for information already given.
|
||||
|
||||
---
|
||||
|
||||
## How the Interview Works
|
||||
|
||||
Run questions **one at a time** (or in small groups of 2–3 where they're closely related). Don't dump all 15 at once. Wait for each answer before proceeding. Ask natural follow-ups where the answer is vague.
|
||||
|
||||
### Interview Questions
|
||||
|
||||
**Block 1 — Who you are and how you read**
|
||||
|
||||
1. What is your role, and what lens do you read news through? (e.g. "Head of Product at a B2B SaaS — I read for competitive moves, AI tooling, and enterprise buying signals.")
|
||||
2. What are the 3–5 topics you always want covered? Be specific — "AI" is too broad; "AI applied to enterprise software" is better.
|
||||
3. What are 2–3 topics you actively want filtered out — things that waste your time every morning?
|
||||
|
||||
**Block 2 — Sources and signals**
|
||||
|
||||
4. Which publications, newsletters, or outlets do you trust most? (Examples: The Information, TLDR, Benedict Evans, Stratechery, FT, specific subreddits)
|
||||
5. Are there any Twitter/X accounts, Substack writers, or niche sources that are must-reads for you specifically?
|
||||
6. Is there any geography that matters — are you focused on a specific country, region, or market?
|
||||
|
||||
**Block 3 — Story type and recency**
|
||||
|
||||
7. What mix of story types do you want? Rank or weight these: breaking news / in-depth analysis / opinion / data & research / product launches & announcements.
|
||||
8. How fresh does the content need to be? Only today's news? Last 24 hours? Last 48 hours? Or are you okay with "last few days" if a story is important enough?
|
||||
|
||||
**Block 4 — Format and time**
|
||||
|
||||
9. How do you want the brief formatted? Options: bullet list by topic / short narrative paragraphs / a digest with headlines + 1-line summaries / a table / mixed.
|
||||
10. What's your reading time budget in the morning? 5 minutes (tight digest) / 10 minutes (fuller brief) / 15 minutes (comprehensive).
|
||||
|
||||
**Block 5 — This week specifically**
|
||||
|
||||
11. Is there anything you're tracking this week in particular — a specific company, deal, product launch, regulatory development, or ongoing story?
|
||||
|
||||
**Block 6 — Follow-up clarification (questions 12–15)**
|
||||
|
||||
Based on the answers above, ask 4 targeted follow-up questions to sharpen ambiguities. Examples of what to probe:
|
||||
|
||||
- If a topic is still broad: "You said [topic] — do you want the technical angle, the business/market angle, or both?"
|
||||
- If sources are vague: "When you say [publication], do you want everything from them or only specific sections/writers?"
|
||||
- If format is unclear: "You want bullets — should each topic have its own section with 3–5 bullets, or one flat list of all stories?"
|
||||
- If recency conflicts with format: "You want only today's news but a comprehensive 15-minute brief — on slow news days, should I go deeper on one story or pull from the last 48 hours to fill it out?"
|
||||
- If exclusions are vague: "You said no [topic] — does that include adjacent topics like [related thing], or strictly [topic]?"
|
||||
|
||||
Use your judgement on which 4 are most worth asking given the actual answers.
|
||||
|
||||
---
|
||||
|
||||
## Output Structure
|
||||
|
||||
After the interview is complete, produce three things in order:
|
||||
|
||||
### 1. Summary of What You Told Me
|
||||
|
||||
A brief summary of the interview, clustered into thematic pillars. This lets the user verify the master prompt will be accurate before it's written.
|
||||
|
||||
```
|
||||
WHAT I HEARD
|
||||
────────────
|
||||
Role lens: [1 sentence]
|
||||
Core topics: [Pillar 1] · [Pillar 2] · [Pillar 3]
|
||||
Exclusions: [Topic A], [Topic B]
|
||||
Sources: [List]
|
||||
Story mix: [e.g. 60% analysis, 30% news, 10% data]
|
||||
Recency: [e.g. Last 24 hours, today only for breaking]
|
||||
Format: [e.g. Bullets by topic, ~10 min read]
|
||||
This week: [Specific tracking items]
|
||||
```
|
||||
|
||||
Confirm: "Does this look right? I'll write the master prompt based on this."
|
||||
|
||||
---
|
||||
|
||||
### 2. The Master Prompt
|
||||
|
||||
Formatted and ready to paste. Start with a markdown code block so the user can copy it cleanly.
|
||||
|
||||
````
|
||||
```
|
||||
MORNING INTELLIGENCE BRIEF — MASTER PROMPT
|
||||
==========================================
|
||||
|
||||
You are an intelligence analyst briefing [ROLE] at the start of their day.
|
||||
|
||||
TASK
|
||||
Generate a personalised morning news brief covering the following.
|
||||
|
||||
TOPICS TO COVER
|
||||
1. [Topic / Pillar 1] — focus on [angle]
|
||||
2. [Topic / Pillar 2] — focus on [angle]
|
||||
3. [Topic / Pillar 3] — focus on [angle]
|
||||
[add pillars as needed]
|
||||
|
||||
NEVER INCLUDE
|
||||
- [Excluded topic 1]
|
||||
- [Excluded topic 2]
|
||||
- [Excluded topic 3]
|
||||
|
||||
PREFERRED SOURCES (prioritise these)
|
||||
[Source 1], [Source 2], [Source 3], [Source 4]
|
||||
|
||||
STORY TYPE MIX
|
||||
[e.g. Prioritise analysis and data-driven pieces. Include breaking news only if significant. Skip opinion unless it's from [specific writer].]
|
||||
|
||||
RECENCY
|
||||
[e.g. Cover only the last 24 hours. For ongoing stories I'm tracking, include relevant developments from the last 48 hours.]
|
||||
|
||||
CURRENTLY TRACKING THIS WEEK
|
||||
[Specific story / company / topic the user flagged]
|
||||
|
||||
FORMAT
|
||||
[e.g. Organise by topic. Under each topic: 2–4 bullet points. Each bullet: headline + 1–2 sentence summary + source name. End with a "What to watch today" section: 2–3 sentences on what matters most today.]
|
||||
|
||||
LENGTH
|
||||
Target a [5/10/15]-minute read.
|
||||
|
||||
TONE
|
||||
Analyst voice. No fluff. Lead with the signal, not the noise. If something is uncertain or based on incomplete reporting, flag it as such.
|
||||
```
|
||||
````
|
||||
|
||||
---
|
||||
|
||||
### 3. Setup Guide
|
||||
|
||||
A short section below the master prompt:
|
||||
|
||||
```
|
||||
HOW TO USE THIS PROMPT
|
||||
──────────────────────
|
||||
|
||||
OPTION A — Cowork Scheduled Tasks (Claude Pro/Max)
|
||||
Requires: Desktop app open at scheduled time
|
||||
1. Open Claude desktop → Cowork → Scheduled Tasks
|
||||
2. Create a new task, set your time (e.g. 7:00 AM)
|
||||
3. Paste the master prompt as the task content
|
||||
4. Save. It will run every morning when your desktop app is open.
|
||||
|
||||
OPTION B — Claude Code Routines (runs in the cloud)
|
||||
Requires: Claude Code with Routines access
|
||||
Advantage: Runs without your laptop being on
|
||||
1. In your project root, create or open .claude/routines.json
|
||||
2. Add a new routine with a cron schedule (e.g. "0 7 * * *" for 7 AM daily)
|
||||
3. Set the prompt field to the master prompt above
|
||||
4. Commit and push — Claude Code will run it on schedule.
|
||||
|
||||
UPDATING YOUR BRIEF
|
||||
When your focus shifts, re-run this skill. The interview takes 5–10 minutes
|
||||
and produces a new master prompt to replace the old one.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Every interview question was asked — none skipped unless the user already provided the answer
|
||||
- [ ] The "What I Heard" summary was shown and confirmed before writing the master prompt
|
||||
- [ ] The master prompt uses specific topic angles, not vague category names (not "AI" — "AI applied to enterprise software")
|
||||
- [ ] Exclusions are explicitly stated in the master prompt with a NEVER INCLUDE section
|
||||
- [ ] Sources are listed in order of preference, not as a flat unordered list
|
||||
- [ ] Story type mix is written as a directive, not just a list
|
||||
- [ ] Recency instruction handles the edge case of slow news days
|
||||
- [ ] Format instruction is precise enough that a different AI could follow it correctly
|
||||
- [ ] The master prompt is inside a code block so it copies cleanly
|
||||
- [ ] Both setup options (Cowork and Claude Code Routines) are included
|
||||
|
||||
---
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- "Set up my morning intelligence brief"
|
||||
- "Build me a morning news prompt"
|
||||
- "Interview me for a morning briefing skill"
|
||||
- "I want to start every day with a personalised news digest"
|
||||
- "Help me set up a daily AI news brief"
|
||||
- "Create a scheduled morning news prompt for me"
|
||||
- "Build me a prompt for my daily briefing routine"
|
||||
@@ -0,0 +1,175 @@
|
||||
---
|
||||
name: notebooklm-connector
|
||||
description: Automates NotebookLM from Claude Code — creates notebooks, adds sources, and triggers outputs (mindmaps, audio overviews, slide decks) without manual clicking via the Claude Chrome extension.
|
||||
---
|
||||
|
||||
# NotebookLM Connector
|
||||
|
||||
## The Problem
|
||||
|
||||
NotebookLM is one of the best AI research tools — but it doesn't connect to your other tools. Every notebook requires manual setup inside the NotebookLM UI: open browser, name the notebook, paste URLs one by one, click generate. For researchers, builders, or anyone who works with a high volume of sources, this friction compounds fast.
|
||||
|
||||
This skill automates NotebookLM from Claude Code using browser automation via the Claude Chrome extension.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
| Requirement | Details |
|
||||
|-------------|---------|
|
||||
| Claude Chrome extension | Must be installed and active in your Chrome browser |
|
||||
| NotebookLM account | Active account at notebooklm.google.com |
|
||||
| Chrome browser | Open and signed into NotebookLM |
|
||||
|
||||
If the Chrome extension is not installed, this skill cannot function. There is no fallback — you will need to perform actions manually.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
| Input | Required | Notes |
|
||||
|-------|----------|-------|
|
||||
| Action(s) to perform | Yes | What you want done — see Supported Actions below |
|
||||
| Notebook name | Conditional | Required for create; optional for add/generate if a notebook is already open |
|
||||
| Sources | Conditional | Required for add sources action — URLs, file paths, or pasted text |
|
||||
| Output type | Conditional | Required for generate action — mindmap, audio overview, or briefing doc |
|
||||
|
||||
## Supported Actions
|
||||
|
||||
| Action | What It Does |
|
||||
|--------|-------------|
|
||||
| Create notebook | Opens NotebookLM, creates a new notebook with the specified title |
|
||||
| Add sources | Adds one or more URLs, files, or text blocks as sources to a notebook |
|
||||
| Generate mindmap | Triggers mindmap generation from the notebook's sources |
|
||||
| Generate audio overview | Requests an audio overview (note: takes several minutes to render) |
|
||||
| Generate briefing doc | Requests a briefing document or slide deck from sources |
|
||||
| List notebooks | Lists your existing notebooks and their source counts |
|
||||
| Open notebook | Navigates to a specific existing notebook by name |
|
||||
|
||||
Actions can be chained in a single request: "Create a notebook called 'AI Trends Q2', add these 3 URLs as sources, then generate a mindmap."
|
||||
|
||||
## Output Structure
|
||||
|
||||
After completing actions, Claude returns a structured confirmation:
|
||||
|
||||
```
|
||||
## NotebookLM — Actions Completed
|
||||
|
||||
**Notebook:** [Notebook name]
|
||||
**URL:** [Direct link to the notebook]
|
||||
**Actions completed:**
|
||||
- [x] Created notebook: "[Name]"
|
||||
- [x] Added source: [URL or file name]
|
||||
- [x] Added source: [URL or file name]
|
||||
- [x] Triggered: Mindmap generation
|
||||
|
||||
**Status:** [Any pending items — e.g. "Audio overview is generating, check back in 5–10 minutes"]
|
||||
|
||||
**Notes:** [Any issues encountered or deviations from the requested actions]
|
||||
```
|
||||
|
||||
If an action fails, the failed step is marked with `[ ]` and a reason is provided. See Error Handling below.
|
||||
|
||||
## Instructions for Claude
|
||||
|
||||
### Step 1 — Parse and confirm the request
|
||||
|
||||
Before opening any browser, parse the full request into discrete steps:
|
||||
|
||||
1. What notebook is being targeted (new or existing)?
|
||||
2. What sources need to be added (list each URL or file)?
|
||||
3. What outputs need to be generated?
|
||||
|
||||
If anything is ambiguous — e.g. "add my research sources" without specifying what they are — ask for clarification before proceeding. Do not guess at source URLs.
|
||||
|
||||
### Step 2 — Check the Chrome extension is available
|
||||
|
||||
Confirm browser automation is available via the Claude Chrome extension. If it is not active, stop and report:
|
||||
|
||||
> "This skill requires the Claude Chrome extension to be installed and active. Please install it at [extension URL] and try again."
|
||||
|
||||
### Step 3 — Navigate to NotebookLM
|
||||
|
||||
Open or navigate to `https://notebooklm.google.com`. Confirm the user is logged in. If a login screen appears, stop and ask the user to log in manually, then retry.
|
||||
|
||||
### Step 4 — Execute actions in order
|
||||
|
||||
Execute each action in the sequence requested. After each action, confirm it completed before moving to the next. Do not batch actions speculatively.
|
||||
|
||||
**Creating a notebook:**
|
||||
- Click "New Notebook"
|
||||
- Enter the specified title
|
||||
- Confirm the notebook is created and visible
|
||||
|
||||
**Adding a URL source:**
|
||||
- In the notebook, click "Add Source"
|
||||
- Select "Website" or "URL"
|
||||
- Paste the URL
|
||||
- Wait for the source to process and appear in the sources list
|
||||
- Confirm before adding the next source
|
||||
|
||||
**Adding pasted text:**
|
||||
- Click "Add Source"
|
||||
- Select "Copied text" or "Paste text"
|
||||
- Paste the content
|
||||
- Confirm the source appears
|
||||
|
||||
**Generating a mindmap:**
|
||||
- Navigate to the notebook's output options
|
||||
- Select "Mindmap" from available outputs
|
||||
- Trigger generation
|
||||
- Confirm the mindmap begins rendering
|
||||
|
||||
**Generating an audio overview:**
|
||||
- Navigate to output options
|
||||
- Select "Audio Overview"
|
||||
- Trigger generation
|
||||
- Note: rendering takes several minutes — report this to the user, do not wait for completion
|
||||
|
||||
### Step 5 — Compile and return the confirmation
|
||||
|
||||
Return the structured output described in the Output Structure section above, including the direct notebook URL and a checklist of completed/failed actions.
|
||||
|
||||
## Error Handling
|
||||
|
||||
If any step fails, do the following:
|
||||
|
||||
1. Stop at the failed step (do not attempt to continue)
|
||||
2. Report the exact step that failed and what was observed
|
||||
3. Suggest a manual workaround for that step
|
||||
4. Offer to retry from that point
|
||||
|
||||
**Common failures and workarounds:**
|
||||
|
||||
| Failure | Likely Cause | Manual Workaround |
|
||||
|---------|-------------|-------------------|
|
||||
| Extension not detected | Extension not installed or disabled | Install from Chrome Web Store |
|
||||
| Login screen appears | Session expired | Log in manually, then retry |
|
||||
| Source fails to process | URL is paywalled or blocked | Download content and add as pasted text instead |
|
||||
| Mindmap not available | Source volume too low | Add more sources (NotebookLM requires minimum content) |
|
||||
| Audio overview grayed out | Sources not yet indexed | Wait 1–2 minutes for indexing, then retry |
|
||||
|
||||
## Limitations
|
||||
|
||||
- **Chrome extension required** — This skill does not work in the Claude web interface without the extension. It cannot function in API-only or terminal-only Claude setups.
|
||||
- **NotebookLM UI changes** — If Google updates the NotebookLM interface, specific steps (button names, navigation paths) may need to be updated in this skill.
|
||||
- **Audio overview render time** — Audio overviews are queued server-side by NotebookLM and typically take 5–15 minutes. Claude can trigger the request but cannot wait for completion.
|
||||
- **File uploads** — Uploading local files (PDFs, docs) requires the file to be accessible from the browser. File paths must be absolute.
|
||||
- **Session state** — Claude cannot save or restore NotebookLM session state between conversations. Each session starts fresh.
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] User's full request was parsed into discrete steps before any browser action was taken
|
||||
- [ ] Ambiguous source references were clarified before proceeding
|
||||
- [ ] Each action was confirmed complete before the next one started
|
||||
- [ ] Direct notebook URL is included in the output
|
||||
- [ ] If audio overview was triggered, user was informed of the render delay
|
||||
- [ ] Any failed steps are explicitly reported with the specific failure reason
|
||||
- [ ] Manual workaround was offered for any step that failed
|
||||
- [ ] Output checklist accurately reflects what was completed vs. what failed
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- "Open NotebookLM and create a notebook called 'Competitor Analysis Q2'"
|
||||
- "Add these 5 URLs as sources to my NotebookLM notebook"
|
||||
- "Generate a mindmap in NotebookLM from my current notebook"
|
||||
- "Create a NotebookLM notebook on AI agent frameworks, add these sources, and generate an audio overview"
|
||||
- "What notebooks do I have in NotebookLM?"
|
||||
- "Add this article to NotebookLM: [URL]"
|
||||
- "Generate a briefing doc from my NotebookLM sources on [topic]"
|
||||
@@ -0,0 +1,166 @@
|
||||
---
|
||||
name: notes-humanizer
|
||||
description: Strips AI writing patterns from text and rewrites it to sound genuinely human — not by softening it, but by removing statistical defaults and injecting the specific signals that human writers produce.
|
||||
---
|
||||
|
||||
# Notes Humanizer
|
||||
|
||||
"Humanize this" prompts don't work because they don't know what to remove. AI text has specific, identifiable defaults — em dashes used as parenthetical substitutes, rule-of-three lists where all items have identical rhythm, sentences that hover between 15 and 20 words. Fix those defaults, add the signals human writers actually produce, and the text stops reading as synthetic. This skill does that systematically, in two phases, and shows you exactly what changed and why.
|
||||
|
||||
> Credit: Originally created by Orel (TheIndiepreneur) — adapted and extended for this library.
|
||||
|
||||
---
|
||||
|
||||
## Required Inputs
|
||||
|
||||
| Input | Format | Notes |
|
||||
|---|---|---|
|
||||
| Text to humanize | Paste directly into the chat | Any length. Works on paragraphs, full articles, social posts, emails. |
|
||||
|
||||
No other inputs required. Claude will not ask clarifying questions before starting — it works with what's given.
|
||||
|
||||
---
|
||||
|
||||
## Output Structure
|
||||
|
||||
### Section 1: What Was Found
|
||||
|
||||
A plain-language audit of the AI patterns detected in the original text, before any rewriting:
|
||||
|
||||
```
|
||||
PATTERNS DETECTED
|
||||
─────────────────
|
||||
Em dashes used as parenthetical substitutes: 3
|
||||
Filler openers ("Let's dive in", "It's worth noting", etc.): 2
|
||||
Rule-of-three lists with identical rhythm: 1
|
||||
Sentence length variance: low (avg 17 words, range 14–21)
|
||||
Hedging qualifiers: 4
|
||||
Passive constructions where active is cleaner: 2
|
||||
```
|
||||
|
||||
### Section 2: Side-by-Side Comparison
|
||||
|
||||
| Original | Rewritten |
|
||||
|---|---|
|
||||
| [original paragraph] | [rewritten paragraph] |
|
||||
|
||||
(One row per paragraph or logical block. Short texts get the full comparison in one table. Long texts get the table collapsed to changed sections only, with unchanged sections noted.)
|
||||
|
||||
### Section 3: Change Log
|
||||
|
||||
Every specific change made, with the reason:
|
||||
|
||||
```
|
||||
CHANGES MADE
|
||||
────────────────────────────────────────────────
|
||||
1. Removed em dash in "success — and it shows"
|
||||
→ Rewritten as "success (and it shows)"
|
||||
Why: em dash here is a parenthetical substitute, not a genuine pause
|
||||
|
||||
2. Deleted "It's worth noting that"
|
||||
Why: pure filler — the sentence is stronger without it
|
||||
|
||||
3. Broke rule-of-three list "X, Y, and Z"
|
||||
→ "X and Y. Z is different — [expanded thought]"
|
||||
Why: all three items had identical rhythm; broke the pattern
|
||||
|
||||
4. Added short sentence: "That's the problem."
|
||||
Why: needed a sub-8-word sentence to vary rhythm
|
||||
|
||||
5. Added sentence starting with "But"
|
||||
Why: human writers do this; AI avoids it as a statistical default
|
||||
|
||||
6. Added specific example: [detail added]
|
||||
Why: the original made an abstract claim with no grounding detail
|
||||
|
||||
7. Added aside: "(I've watched this fail three times in a row)"
|
||||
Why: breaks fourth wall slightly; signals genuine perspective
|
||||
```
|
||||
|
||||
### Section 4: Clean Output
|
||||
|
||||
The full rewritten text, ready to copy and paste — no annotations, no formatting artifacts.
|
||||
|
||||
```
|
||||
[Full rewritten text here]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Instructions for Claude
|
||||
|
||||
### Phase 1: Audit
|
||||
|
||||
Read the full text before making any changes. Identify and count every instance of these patterns:
|
||||
|
||||
**Patterns to remove or rewrite:**
|
||||
|
||||
| Pattern | Action |
|
||||
|---|---|
|
||||
| Em dash used as parenthetical substitute (`word — word` where a comma or parenthesis would work) | Replace with parentheses or rewrite the clause |
|
||||
| "Let's dive in" | Delete or replace with a direct first sentence |
|
||||
| "In conclusion" | Delete or rewrite as a genuine closing thought |
|
||||
| "It's worth noting that" | Delete — the sentence stands without it |
|
||||
| "At its core" | Delete or rewrite |
|
||||
| "Game-changer" | Replace with what the thing actually changes |
|
||||
| "Delve" | Replace with look, dig, explore — or rewrite the sentence |
|
||||
| "Navigate" used metaphorically for non-navigation tasks | Replace with a direct verb |
|
||||
| Rule-of-three lists where all three items have identical grammatical structure and similar word count | Break the third item out as its own sentence or expand it |
|
||||
| Sentences where every sentence in a paragraph falls in the 14–22 word range | Deliberately add one very short sentence and one longer one |
|
||||
| "Needless to say" | Delete |
|
||||
| "It's important to note that" | Delete |
|
||||
| Passive constructions where the active form is more direct | Flip to active |
|
||||
|
||||
Do not remove every em dash — only the ones used as parenthetical substitutes. Do not remove all hedging — only empty hedging that adds no information.
|
||||
|
||||
### Phase 2: Inject
|
||||
|
||||
After stripping patterns, add the following signals. Each one should emerge from the actual content — don't add generic filler:
|
||||
|
||||
1. **One genuine opinion or take.** The author appears to actually believe something specific. State it without hedging. ("This approach works, and I think most people underestimate how rarely the alternative does.")
|
||||
|
||||
2. **One specific detail, example, or number.** Ground the most abstract claim in the text with something concrete. If the text says "this happens frequently," add a real or illustrative number. If it says "many companies do this," name the type of company.
|
||||
|
||||
3. **One aside or parenthetical thought that breaks the fourth wall slightly.** This is the signal most synthetic text lacks — the writer momentarily steps out of the formal argument to say something human. ("(I've seen this specific mistake made by people who absolutely should have known better.)")
|
||||
|
||||
4. **At least one sentence under 8 words.** Make it land on a point, not a transition.
|
||||
|
||||
5. **One sentence that starts with "And" or "But."** Place it where the rhythm earns it, not randomly.
|
||||
|
||||
### Phase 3: Report
|
||||
|
||||
Present the output in the four-section structure defined above. The change log must list every individual change — not categories of change, but specific instances. If you changed three em dashes, list all three separately.
|
||||
|
||||
### Handling edge cases
|
||||
|
||||
- **If the text is already mostly clean:** Report what you found (or didn't find), make the few remaining changes, and note explicitly that the original was close. Don't invent problems.
|
||||
- **If the text is very short (under 100 words):** Skip the comparison table. Show original, then rewritten, then change log.
|
||||
- **If the text is over 1,500 words:** Process the full text but collapse the comparison table to changed sections only.
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Audit was completed before rewriting (patterns counted, not just detected)
|
||||
- [ ] Every removed pattern is listed in the change log with a specific reason
|
||||
- [ ] Em dashes were assessed individually — only parenthetical-substitute uses were removed
|
||||
- [ ] Rule-of-three lists: the rhythm was actually checked, not just the fact that there were three items
|
||||
- [ ] At least one sentence under 8 words was added (or was already present)
|
||||
- [ ] At least one sentence starts with "And" or "But" in the final text
|
||||
- [ ] The specific detail or example added connects to an actual claim in the text, not floated in generically
|
||||
- [ ] The aside breaks the fourth wall slightly without being forced or cutesy
|
||||
- [ ] The change log lists specific instances, not categories
|
||||
- [ ] The clean output section has no annotations or formatting artifacts — ready to paste
|
||||
- [ ] If the original was already clean, that was stated explicitly rather than changes invented
|
||||
|
||||
---
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- "Humanize this text: [paste]"
|
||||
- "Use the notes-humanizer skill on this draft"
|
||||
- "This reads like ChatGPT wrote it — fix it: [paste]"
|
||||
- "Strip the AI out of this and make it sound like a real person wrote it"
|
||||
- "Run the humanizer on this LinkedIn post: [paste]"
|
||||
- "This has too many em dashes and rule-of-three lists — clean it up: [paste]"
|
||||
- "Make this email sound less robotic: [paste]"
|
||||
@@ -0,0 +1,228 @@
|
||||
---
|
||||
name: partnership-proposal
|
||||
description: "Write a B2B partnership proposal or business case. Use when asked to write a partnership proposal, draft a partnership brief, structure a co-marketing proposal, or create a business case for a strategic partnership. Produces a structured proposal with value proposition, partnership model, commercial terms, and mutual commitments."
|
||||
---
|
||||
|
||||
# Partnership Proposal Skill
|
||||
|
||||
This skill produces a complete B2B partnership proposal covering the partnership rationale, mutual value, partnership model, commercial terms, governance, and a joint go-to-market plan. Output is ready to share with a prospective partner or use as the basis for a business case to internal stakeholders.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask the user for these if not provided:
|
||||
- **Your company** — name, what you do, and the audience you serve
|
||||
- **Prospective partner** — name, what they do, and their audience
|
||||
- **Partnership type** — technology integration / co-marketing / reseller / referral / strategic alliance / OEM
|
||||
- **Partnership goal** — what does each party get? (new customers / revenue / product capability / market reach)
|
||||
- **Proposed commercial model** — revenue share, referral fee, licensing, co-investment?
|
||||
- **Urgency or context** — is there a specific event, product launch, or competitive reason for this partnership?
|
||||
|
||||
## Output Structure
|
||||
|
||||
---
|
||||
|
||||
# Partnership Proposal: [Your Company] × [Partner Company]
|
||||
|
||||
**Prepared by:** [Name, Role at Your Company]
|
||||
**Date:** [Date]
|
||||
**Partnership type:** [Technology / Co-marketing / Reseller / Referral / Strategic Alliance]
|
||||
**Proposal status:** [Initial proposal / For negotiation / Final]
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
[3–5 sentences. Answer: what are we proposing, why now, and what does each party stand to gain? Write this so a busy executive can understand the proposal in 60 seconds without reading further.]
|
||||
|
||||
**Headline value for [Partner]:**
|
||||
> [One sentence — the most compelling thing this partnership does for them]
|
||||
|
||||
**Headline value for [Your Company]:**
|
||||
> [One sentence — the most compelling thing this partnership does for you]
|
||||
|
||||
---
|
||||
|
||||
## 1. The Opportunity
|
||||
|
||||
**Market context:** [Why does this partnership make sense now? What's happening in the market that creates a window for this to work?]
|
||||
|
||||
**Shared customer:** [Describe the customer both organisations serve — the overlap that makes this logical. Include size of the shared addressable market if you have it.]
|
||||
|
||||
**Problem neither of us solves alone:** [What can't either party do for the shared customer independently that the partnership would enable?]
|
||||
|
||||
---
|
||||
|
||||
## 2. What We're Proposing
|
||||
|
||||
**Partnership model:**
|
||||
|
||||
| Element | Description |
|
||||
|---|---|
|
||||
| **Type** | [Technology integration / Co-marketing / Reseller / Referral / OEM] |
|
||||
| **Scope** | [What specifically are we partnering on? — product features, joint campaigns, distribution, etc.] |
|
||||
| **Exclusivity** | [Exclusive in [region/segment] / Non-exclusive / Right of first refusal] |
|
||||
| **Duration** | [Initial term — e.g. 12 months, renewable] |
|
||||
| **Geographic scope** | [UK / EMEA / Global / Specific markets] |
|
||||
|
||||
**What this looks like in practice:**
|
||||
|
||||
[3–5 bullet points describing what the partnership actually means day-to-day. Make it concrete and operational — not abstract. e.g.:]
|
||||
- [Our product will natively integrate with [Partner's product] — the integration will be live in [timeframe]]
|
||||
- [We will co-market to each other's customer bases — joint webinar, co-authored content, shared newsletter placement]
|
||||
- [Each company will train a dedicated partnership contact who manages the relationship]
|
||||
- [[Partner] will list [Your product] in their marketplace / app directory / referral programme]
|
||||
|
||||
---
|
||||
|
||||
## 3. Value Proposition — What Each Party Gets
|
||||
|
||||
### For [Partner]
|
||||
|
||||
| Value | Evidence / Basis |
|
||||
|---|---|
|
||||
| **[New customer reach]** | [e.g. Access to [Your Company]'s [X,000] [role] customers — [X%] of whom have expressed interest in [Partner's category]] |
|
||||
| **[Product capability]** | [e.g. [Partner]'s product gains [capability] that [X%] of their customers have requested — based on [source]] |
|
||||
| **[Revenue opportunity]** | [e.g. Estimated [£/$/€ X] in referral revenue in Year 1 based on [X%] conversion from shared pipeline] |
|
||||
| **[Market differentiation]** | [e.g. The integration creates a meaningful competitive moat vs [Competitor] who lacks this capability] |
|
||||
|
||||
### For [Your Company]
|
||||
|
||||
| Value | Evidence / Basis |
|
||||
|---|---|
|
||||
| **[Distribution]** | [e.g. Access to [Partner]'s [X,000] customers in [segment] — a segment where we currently have [X] customers] |
|
||||
| **[Credibility]** | [e.g. Association with [Partner]'s brand accelerates enterprise sales cycles — [Partner] is trusted by [X] of the Fortune 500] |
|
||||
| **[Revenue]** | [e.g. Target [X] referral customers in Year 1 at average ACV of [£X] = [£X ARR]] |
|
||||
| **[Product]** | [e.g. [Partner]'s data / capability enhances [specific part of our product] — improving [user outcome]] |
|
||||
|
||||
---
|
||||
|
||||
## 4. Commercial Model
|
||||
|
||||
**Proposed commercial terms:**
|
||||
|
||||
| Term | Proposal | Notes |
|
||||
|---|---|---|
|
||||
| **Revenue share** | [e.g. [X%] of ARR from customers referred by [Partner]] | [Standard in this category: [X–Y%] range] |
|
||||
| **Referral fee** | [e.g. £[X] per qualified lead that converts] | [Or: flat fee per introduction vs % of closed deal] |
|
||||
| **Licensing / access** | [e.g. [Partner] provides API access at no cost in exchange for integration and co-marketing] | [...] |
|
||||
| **Co-marketing investment** | [e.g. Each party commits [£X] to joint marketing activities per quarter] | [...] |
|
||||
| **Minimum commitment** | [e.g. [X] qualified referrals per quarter / [£X] GMV per year] | [Optional — only if there's a meaningful minimum that makes sense] |
|
||||
|
||||
**Payment terms:** [Monthly / Quarterly in arrears / Annual true-up]
|
||||
|
||||
**What we're not proposing:** [Be explicit about what's off the table — e.g. equity / exclusivity in all markets / upfront payment]
|
||||
|
||||
---
|
||||
|
||||
## 5. Joint Go-to-Market Plan
|
||||
|
||||
**Phase 1: Foundation (Months 1–2)**
|
||||
|
||||
| Activity | Owner | Timeline |
|
||||
|---|---|---|
|
||||
| Technical integration scoped and resourced | [Engineering at both companies] | [Month 1] |
|
||||
| Partnership launch announcement drafted | [Marketing at both companies] | [Month 1] |
|
||||
| Joint customer case study identified | [CSM at both companies] | [Month 2] |
|
||||
| Partner enablement — each team trained on the other's product | [Partnership lead, both sides] | [Month 2] |
|
||||
|
||||
**Phase 2: Launch (Month 3)**
|
||||
|
||||
| Activity | Owner | Timeline |
|
||||
|---|---|---|
|
||||
| Integration live in both products / marketplace | [Engineering] | [Month 3] |
|
||||
| Joint press release / blog post / email announcement | [Marketing] | [Month 3] |
|
||||
| First joint webinar | [Both companies] | [Month 3] |
|
||||
| First joint pipeline reviewed | [Partnership leads] | [Month 3] |
|
||||
|
||||
**Phase 3: Scale (Months 4–12)**
|
||||
|
||||
| Activity | Owner | Cadence |
|
||||
|---|---|---|
|
||||
| Co-sell on named accounts | [AE at both companies] | [Monthly] |
|
||||
| Joint content (blog, webinar, case study) | [Marketing] | [Quarterly] |
|
||||
| Pipeline and revenue review | [Partnership leads] | [Monthly] |
|
||||
| Partnership QBR | [VP level, both companies] | [Quarterly] |
|
||||
|
||||
---
|
||||
|
||||
## 6. Success Metrics
|
||||
|
||||
How we'll know the partnership is working:
|
||||
|
||||
| Metric | Year 1 target | Measurement |
|
||||
|---|---|---|
|
||||
| Customers referred (each direction) | [X] | [CRM tracking — tagged as partner-sourced] |
|
||||
| Revenue from partnership | [£/$/€ X ARR] | [CRM + finance reporting] |
|
||||
| Integration adoption | [X% of mutual customers using integration] | [Product analytics] |
|
||||
| Customer satisfaction with integration | [NPS ≥ X] | [Post-integration survey] |
|
||||
| Joint pipeline generated | [£X] | [Quarterly pipeline review] |
|
||||
|
||||
**Review cadence:** Monthly partnership lead check-in + Quarterly business review at VP level
|
||||
|
||||
---
|
||||
|
||||
## 7. Governance & Operations
|
||||
|
||||
**Partnership contacts:**
|
||||
|
||||
| Role | [Your Company] | [Partner] |
|
||||
|---|---|---|
|
||||
| Partnership lead (day-to-day) | [Name, email] | [TBC] |
|
||||
| Executive sponsor | [Name, title] | [TBC] |
|
||||
| Technical lead | [Name] | [TBC] |
|
||||
| Marketing lead | [Name] | [TBC] |
|
||||
|
||||
**Decision-making:**
|
||||
- Day-to-day partnership operations: partnership leads
|
||||
- Commercial term changes: VP-level approval from both parties
|
||||
- Partnership termination: CEO/MD sign-off + [X days] written notice
|
||||
|
||||
**Legal framework:**
|
||||
- [ ] Partnership agreement / MOU to be drafted by [Company]'s legal team
|
||||
- [ ] Data processing agreement (if personal data is shared)
|
||||
- [ ] NDAs: [already in place / to be signed before detailed discussions]
|
||||
- [ ] IP ownership: [Clarify who owns jointly developed materials, integrations, content]
|
||||
|
||||
---
|
||||
|
||||
## 8. Risks & Mitigations
|
||||
|
||||
| Risk | Likelihood | Mitigation |
|
||||
|---|---|---|
|
||||
| Partnership champion leaves [Partner] | M | Ensure VP-level sponsorship; build multiple relationships |
|
||||
| Integration takes longer than planned | M | Scope technical work in Phase 1; set realistic launch commitment |
|
||||
| Low adoption of the integration | M | Include in onboarding for both products; co-market to existing customers not just new |
|
||||
| Partner signs with our competitor | L | Discuss exclusivity options; prioritise quick launch to create switching costs |
|
||||
| Commercial model becomes imbalanced | L | Quarterly review with clear exit terms if targets are consistently missed |
|
||||
|
||||
---
|
||||
|
||||
## 9. Proposed Next Steps
|
||||
|
||||
| # | Action | Owner | By when |
|
||||
|---|---|---|---|
|
||||
| 1 | [Partner] reviews this proposal and provides feedback | [[Partner name]] | [Date] |
|
||||
| 2 | Both parties sign NDA (if not already in place) | [Legal, both sides] | [Before next meeting] |
|
||||
| 3 | Technical discovery call — assess integration feasibility | [Engineering leads] | [Date] |
|
||||
| 4 | Commercial terms negotiation | [Partnership leads / VP] | [Date] |
|
||||
| 5 | MOU / partnership agreement drafted and signed | [Legal] | [Date] |
|
||||
| 6 | Integration and launch planning begins | [Both teams] | [Date] |
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Value proposition for the partner is written from their perspective — not yours
|
||||
- [ ] Commercial model includes specific numbers, not just structure
|
||||
- [ ] "What we're not proposing" section prevents misaligned expectations
|
||||
- [ ] Go-to-market plan has named owners and dates, not "TBD"
|
||||
- [ ] Success metrics are agreed bilaterally — not set unilaterally
|
||||
- [ ] Risks section includes the most uncomfortable risk (partner signs with a competitor)
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- "Write a partnership proposal for [Company] to partner with [Partner]"
|
||||
- "Draft a co-marketing partnership brief between us and [Partner]"
|
||||
- "Create a reseller partnership proposal for [Company]"
|
||||
- "Build the business case for a strategic partnership with [Partner]"
|
||||
- "Structure a technology integration partnership proposal"
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: pr-description-writer
|
||||
description: "Write a clear, structured pull request description from a git diff, branch summary, or commit list. Use when asked to write a PR description, draft a pull request, or document code changes. Produces a description with summary, motivation, changes made, testing steps, and reviewer guidance. Optimised for Opus 4.7 and newer models."
|
||||
description: "Write a clear, structured pull request description from a git diff, branch summary, or commit list. Use when asked to write a PR description, draft a pull request, or document code changes. Produces a description with summary, motivation, changes made, testing steps, and reviewer guidance."
|
||||
---
|
||||
|
||||
# PR Description Writer Skill
|
||||
@@ -15,8 +15,10 @@ Ask for these if not provided:
|
||||
- **How to test it** (any specific steps a reviewer needs to verify it works)
|
||||
- **Risk level** (low / medium / high — affects how much reviewer guidance to include)
|
||||
- **PR type** (feature / bug fix / refactor / dependency upgrade / config change / hotfix)
|
||||
- **Target branch** (e.g. main / develop / release/2.4 — affects risk framing and reviewer guidance)
|
||||
- **Linked issue or ticket** (e.g. JIRA-1234, GitHub #567 — or "none")
|
||||
|
||||
## Output Structure
|
||||
## Output Format
|
||||
|
||||
### Title
|
||||
A clear, imperative-mood title under 72 characters:
|
||||
@@ -43,7 +45,7 @@ Bullet list of specific changes — one bullet per logical change, not per file:
|
||||
### Screenshots / Demo
|
||||
[If UI change: include before/after screenshots or a screen recording]
|
||||
[If API change: include example request/response]
|
||||
[If no visual change: this section can be omitted]
|
||||
[If no visual change and no API contract change: omit this section entirely — do not leave it as a placeholder]
|
||||
|
||||
### How to Test
|
||||
Step-by-step instructions a reviewer can follow:
|
||||
@@ -76,10 +78,11 @@ Flag anything that warrants extra attention:
|
||||
- [ ] Title is imperative mood and under 72 characters
|
||||
- [ ] Summary explains what AND why (not just what)
|
||||
- [ ] Changes list describes logical changes (not file-by-file changes)
|
||||
- [ ] Title starts with a valid type prefix (feat / fix / refactor / chore / deps / config / hotfix) and is under 72 characters
|
||||
- [ ] Testing steps are reproducible by someone unfamiliar with the code
|
||||
- [ ] Risk-appropriate reviewer guidance is included
|
||||
- [ ] For high-risk PRs, Reviewer Notes flags at least one specific area of concern or deliberate trade-off; for low-risk PRs, Reviewer Notes is either omitted or kept to one line
|
||||
|
||||
## Example Trigger Phrases
|
||||
## Usage Examples
|
||||
- "Write a PR description for these changes" + [paste diff or description]
|
||||
- "Draft a pull request for [feature]"
|
||||
- "I need a PR description — here's what I changed"
|
||||
|
||||
@@ -0,0 +1,221 @@
|
||||
---
|
||||
name: product-positioning-doc
|
||||
description: "Write a product positioning document and messaging framework. Use when asked to define product positioning, write a positioning statement, build a messaging framework, or create a messaging hierarchy. Produces a complete positioning doc with category definition, target customer, differentiation, proof points, messaging pillars, and persona-specific messaging."
|
||||
---
|
||||
|
||||
# Product Positioning Doc Skill
|
||||
|
||||
This skill produces a complete product positioning document following the April Dunford positioning methodology. Output covers category definition, target customer, unique attributes, proof points, and a messaging hierarchy — ready to align GTM, marketing, sales, and product teams.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask the user for these if not provided:
|
||||
- **Product name** and what it does
|
||||
- **Target customer** — who is it for? (role, company type, size)
|
||||
- **Problem it solves** — what pain or goal does it address?
|
||||
- **Key alternatives** — what do customers use today instead? (not just direct competitors — include status quo, spreadsheets, DIY)
|
||||
- **Differentiation** — what does this product do that alternatives cannot? (not features — capabilities that produce different outcomes)
|
||||
- **Proof points** — any customer data, case studies, metrics, or validation?
|
||||
- **Business goal** — is positioning for a new category, expansion into new segment, or repositioning away from a declining category?
|
||||
|
||||
## Output Structure
|
||||
|
||||
---
|
||||
|
||||
# Positioning Document: [Product Name]
|
||||
|
||||
**Version:** [1.0]
|
||||
**Owner:** [PMM / Founder / Marketing lead]
|
||||
**Date:** [Date]
|
||||
**Status:** [Draft / Reviewed / Approved]
|
||||
**Approved by:** [Names — this document must be signed off by product, marketing, and sales leadership before use]
|
||||
|
||||
---
|
||||
|
||||
## 1. Background & Context
|
||||
|
||||
[2–3 sentences describing why positioning is being done now. Is this a new product, a pivot, a segment expansion, or a rebrand? What triggered this work?]
|
||||
|
||||
**Positioning objective:** [e.g. Move from being perceived as a reporting tool to being the category leader in revenue intelligence for mid-market SaaS]
|
||||
|
||||
---
|
||||
|
||||
## 2. Market Category
|
||||
|
||||
**What category does this product compete in?**
|
||||
|
||||
This is the frame of reference your customer uses to understand what the product is. Choose the wrong category and everything downstream — competitors, value, messaging — is wrong.
|
||||
|
||||
**Category:** [e.g. Customer data platform / Revenue intelligence / No-code automation / Modern data stack]
|
||||
|
||||
**Why this category, not [alternative category]?**
|
||||
[1–2 sentences on why this framing serves the customer's understanding better than adjacent categories]
|
||||
|
||||
**Category maturity:**
|
||||
- [ ] New category (we are creating it — high education burden, high upside if it works)
|
||||
- [ ] Growing category (fast-growing segment — compete on differentiation)
|
||||
- [ ] Mature category (well-understood — must disrupt with clear superiority or narrower niche)
|
||||
|
||||
---
|
||||
|
||||
## 3. Target Customer
|
||||
|
||||
**Be precise. Vague targeting produces vague positioning.**
|
||||
|
||||
| Dimension | Description |
|
||||
|---|---|
|
||||
| **Primary buyer / decision-maker** | [e.g. VP of Revenue Operations at B2B SaaS companies with 100–500 employees] |
|
||||
| **Primary user** | [e.g. Revenue operations analysts and sales ops managers] |
|
||||
| **Company profile** | [Industry, size, growth stage, technology stack] |
|
||||
| **Business context** | [What is happening in their world that makes them a buyer right now?] |
|
||||
| **Trigger event** | [What just happened that makes them start looking for a solution? — e.g. Sales team grew past 20 reps, forecast accuracy became a board question] |
|
||||
|
||||
**Who this is NOT for:**
|
||||
[Be explicit about who to exclude — this sharpens the positioning for those who are a fit]
|
||||
|
||||
---
|
||||
|
||||
## 4. Competitive Alternatives
|
||||
|
||||
What do buyers use today when they don't have your product? List all real alternatives — not just direct competitors.
|
||||
|
||||
| Alternative | Who uses it | Why buyers choose it | What they sacrifice |
|
||||
|---|---|---|---|
|
||||
| **[Direct competitor — e.g. Gong]** | [Enterprise sales teams] | [Market leader, strong brand, sales coaching features] | [Price, complexity, implementation time] |
|
||||
| **[Adjacent tool — e.g. Salesforce reports]** | [CRM-native users] | [Already have it, no additional cost] | [No AI analysis, manual reporting, siloed data] |
|
||||
| **[Status quo — e.g. spreadsheets + manual tracking]** | [SMB, early-stage] | [Free, flexible, no change management] | [Time-consuming, error-prone, not scalable] |
|
||||
| **[Build in-house]** | [Tech companies with data teams] | [Custom to their exact needs] | [Engineering cost, maintenance burden, 12+ month timeline] |
|
||||
|
||||
**Key insight:** [What does this competitive landscape tell you about what your positioning must emphasise? e.g. "Every alternative either costs too much or requires too much manual work — positioning must nail 'fast time to value' and 'right-sized for mid-market'"]
|
||||
|
||||
---
|
||||
|
||||
## 5. Unique Differentiated Attributes
|
||||
|
||||
These are the features or capabilities your product has that alternatives genuinely cannot match — or cannot match at the same level. Do not list features that competitors also have.
|
||||
|
||||
| Attribute | What it is | What it enables (outcome) | Why competitors can't match it |
|
||||
|---|---|---|---|
|
||||
| [e.g. Real-time CRM sync] | [Bidirectional sync with any CRM in <5 min] | [Reps see clean data in the tools they already use — no toggle between systems] | [Legacy competitors require 3-month integration projects; Salesforce-native tools only work in SFDC] |
|
||||
| [e.g. Natural language querying] | [Ask questions in plain English, get data visualisations] | [Anyone on the revenue team can answer their own questions without SQL or waiting for an analyst] | [BI tools require analyst training; direct competitors have rigid dashboards] |
|
||||
| [...] | [...] | [...] | [...] |
|
||||
|
||||
**The core differentiation thesis:**
|
||||
[1–2 sentences that unite the above attributes into a single "why we win" statement — this is internal language, not customer-facing yet]
|
||||
|
||||
---
|
||||
|
||||
## 6. Value Proof Points
|
||||
|
||||
Back up the differentiation claims with evidence:
|
||||
|
||||
| Claim | Proof point | Source |
|
||||
|---|---|---|
|
||||
| [Fastest time to value] | [Average customer is live in 4 hours vs 3 months for legacy alternatives] | [Customer data — average across [X] accounts] |
|
||||
| [Better forecast accuracy] | [Customers achieve X% improvement in forecast accuracy within 90 days] | [Case study: [Company Name] — link] |
|
||||
| [Loved by operators, not just managers] | [NPS of X among end users; 4.8/5 on G2 for ease of use] | [G2 reviews, internal NPS survey] |
|
||||
|
||||
**Proof gaps:** [Are there claims you're making that you don't yet have evidence for? List them — they are either research projects or risks to the positioning]
|
||||
|
||||
---
|
||||
|
||||
## 7. Positioning Statement
|
||||
|
||||
The classic positioning template — internal only, never used verbatim in marketing:
|
||||
|
||||
> **For** [target customer]
|
||||
> **who** [trigger event or problem statement],
|
||||
> **[Product name]** is a **[category]**
|
||||
> **that** [primary differentiated value — the outcome, not the feature].
|
||||
> **Unlike** [primary alternative],
|
||||
> **[Product name]** [the key thing that makes you different and better].
|
||||
|
||||
**Draft positioning statement:**
|
||||
> For [VP Revenue Ops at B2B SaaS companies with 50–500 reps] who [struggle to forecast accurately as the sales team scales], [Product Name] is a [revenue intelligence platform] that [gives every rep and manager accurate, real-time pipeline visibility without any analyst overhead]. Unlike [Salesforce dashboards and manual reporting], [Product Name] [syncs automatically, surfaces risks before they become missed quarters, and needs no configuration by IT or data teams].
|
||||
|
||||
---
|
||||
|
||||
## 8. Messaging Hierarchy
|
||||
|
||||
Translate the positioning into customer-facing language at three levels:
|
||||
|
||||
### Tagline (5–8 words)
|
||||
|
||||
[The simplest possible statement of what you do and for whom. Used in ads, hero sections, email signatures.]
|
||||
|
||||
Options to test:
|
||||
1. [e.g. "Revenue intelligence for scaling sales teams"]
|
||||
2. [e.g. "Forecast with confidence. Close with clarity."]
|
||||
3. [e.g. "The revenue platform your whole team will actually use"]
|
||||
|
||||
### Value Proposition (1–2 sentences)
|
||||
|
||||
[Used in the hero section of the website, email subject lines, and sales decks. Must be instantly clear.]
|
||||
|
||||
> [e.g. "[Product Name] gives revenue teams real-time pipeline visibility and accurate forecasting — without spreadsheets, custom reports, or waiting for an analyst. Get live in 4 hours, not 4 months."]
|
||||
|
||||
### Full Description (3–5 sentences)
|
||||
|
||||
[Used in PR, partnership briefs, longer sales emails, and About Us pages.]
|
||||
|
||||
> [e.g. "[Product Name] is the revenue intelligence platform built for mid-market SaaS teams. Unlike legacy BI tools that require analyst configuration or CRM dashboards that only show what's already happened, [Product Name] automatically syncs your entire revenue stack, surfaces AI-driven risk signals, and lets any rep or manager ask questions in plain English. [X] customers use [Product Name] to call their quarters with confidence. Average time to live: 4 hours."]
|
||||
|
||||
---
|
||||
|
||||
## 9. Persona-Specific Messaging
|
||||
|
||||
The core positioning is the same, but different buyers care about different aspects:
|
||||
|
||||
| Persona | Their primary concern | Lead message | Proof point to use |
|
||||
|---|---|---|---|
|
||||
| **VP Revenue Operations** | Forecast accuracy, board credibility | "Call your quarter with confidence" | [X% improvement in forecast accuracy across N customers] |
|
||||
| **Head of Sales** | Rep productivity, pipeline visibility | "Your reps close more, not admin more" | [X hours/week saved per rep] |
|
||||
| **CEO / CFO** | Revenue predictability, cost | "Stop being surprised by quarters" | [ROI: £X saved vs X headcount required to replicate manually] |
|
||||
| **Sales Rep** | Ease of use, not adding to workload | "It works in the tools you already use" | [Ease of use NPS, G2 reviews] |
|
||||
|
||||
---
|
||||
|
||||
## 10. Messaging Do's and Don'ts
|
||||
|
||||
**Do say:**
|
||||
- [Specific, outcome-focused language — what the customer achieves]
|
||||
- [Comparative language grounded in evidence]
|
||||
- [Language your target buyer uses to describe their problem — not language you invented]
|
||||
|
||||
**Don't say:**
|
||||
- ["Best-in-class", "innovative", "cutting-edge", "game-changing" — unless followed by evidence]
|
||||
- [Feature lists without outcome context]
|
||||
- [Jargon your buyer doesn't use themselves]
|
||||
- [Claims your competitors could also make]
|
||||
|
||||
---
|
||||
|
||||
## 11. Distribution Plan
|
||||
|
||||
Positioning only works if it's implemented consistently:
|
||||
|
||||
| Team | What they need | Format | Owner | When |
|
||||
|---|---|---|---|---|
|
||||
| Marketing | Tagline, value prop, messaging hierarchy | This doc + messaging playbook | PMM | [Date] |
|
||||
| Sales | Competitive positioning, objection responses | One-pager + deck | Sales enablement | [Date] |
|
||||
| Product | Category definition, target customer | Shared doc + roadmap input | PMM + PM | [Date] |
|
||||
| Leadership | Full positioning narrative | This doc | PMM | [Date] |
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Positioning statement has exactly one A — the product is accountable to exactly one primary differentiated claim
|
||||
- [ ] Competitive alternatives include the status quo — not just named competitors
|
||||
- [ ] Differentiated attributes describe outcomes, not features
|
||||
- [ ] Every proof point cites a source — not "customers say…"
|
||||
- [ ] Persona messaging uses the buyer's language, not the company's
|
||||
- [ ] At least two people from product, marketing, and sales have reviewed and approved
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- "Write a positioning document for [product]"
|
||||
- "Build a messaging framework for our B2B SaaS tool"
|
||||
- "Define our product positioning — who is this for and why should they care?"
|
||||
- "Create a positioning statement and messaging hierarchy for [launch]"
|
||||
- "Help me articulate our differentiation vs [Competitor]"
|
||||
@@ -0,0 +1,160 @@
|
||||
---
|
||||
name: raci-matrix
|
||||
description: "Define a RACI matrix for a cross-functional project or process. Use when asked to build a RACI, create a responsibility matrix, clarify ownership across teams, or document decision rights. Produces a complete RACI matrix with role definitions, decision mapping, and a process for resolving conflicts."
|
||||
---
|
||||
|
||||
# RACI Matrix Skill
|
||||
|
||||
This skill produces a complete RACI (Responsible, Accountable, Consulted, Informed) matrix for a project, product launch, or ongoing process. Output is ready to share with teams to clarify ownership, reduce decision bottlenecks, and eliminate duplication of effort.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask the user for these if not provided:
|
||||
- **Project or process name**
|
||||
- **Key activities or decisions** to map (or the user can describe the project and the skill will derive them)
|
||||
- **Teams or roles involved** (list team names and key individuals if helpful)
|
||||
- **Primary purpose** — clarifying launch ownership / onboarding a new team / reducing bottlenecks / governance documentation
|
||||
- **RACI variant** — standard RACI, or RASCI (adds Supportive), or DACI (Driver, Approver, Contributors, Informed)?
|
||||
|
||||
## Output Structure
|
||||
|
||||
---
|
||||
|
||||
# RACI Matrix: [Project / Process Name]
|
||||
|
||||
**Version:** [1.0]
|
||||
**Owner:** [Programme lead / PM]
|
||||
**Date:** [Date]
|
||||
**Teams involved:** [List teams]
|
||||
|
||||
---
|
||||
|
||||
## 1. Role Definitions
|
||||
|
||||
Before reading the matrix, agree on what each letter means for this project:
|
||||
|
||||
| Letter | Role | Definition | Rules |
|
||||
|---|---|---|---|
|
||||
| **R** | Responsible | Does the work. One or more people actually execute the task. | Multiple Rs are allowed — but if there are many, consider splitting the task |
|
||||
| **A** | Accountable | Owns the outcome. Signs off on decisions. Answers if something goes wrong. | **There must be exactly one A per row.** Never two. Never zero. |
|
||||
| **C** | Consulted | Provides expertise or input before work is done. Two-way communication. | Consulted parties must be engaged — not just available. Cap at 3 per row or it becomes noise |
|
||||
| **I** | Informed | Notified of progress or outcomes. One-way communication. | Informed only — they don't review or approve |
|
||||
|
||||
**Golden rules:**
|
||||
- Every row has exactly one **A**
|
||||
- The same person or team should not be **A** for more than [X] rows — spreads accountability too thin
|
||||
- **C** is expensive — consulting someone means they must respond. Use it intentionally
|
||||
- If someone is **R** they cannot also be **A** for the same task unless they are the decision-maker (common in small teams)
|
||||
|
||||
---
|
||||
|
||||
## 2. RACI Matrix
|
||||
|
||||
Columns = teams or roles. Rows = activities or decisions.
|
||||
|
||||
| Activity / Decision | [Role 1] | [Role 2] | [Role 3] | [Role 4] | [Role 5] | Notes |
|
||||
|---|---|---|---|---|---|---|
|
||||
| **[Phase 1: Discovery]** | | | | | | |
|
||||
| Define project scope and objectives | A/R | C | I | I | — | PM leads; engineering consulted on technical feasibility |
|
||||
| Conduct user research | R | A | C | I | — | UX researcher executes; PM accountable |
|
||||
| Approve discovery findings | C | A | I | R | — | |
|
||||
| **[Phase 2: Design]** | | | | | | |
|
||||
| Define solution approach | A | R | C | I | I | |
|
||||
| Design system / UI designs | C | A/R | I | I | — | |
|
||||
| Design review and sign-off | C | R | A | I | — | |
|
||||
| Accessibility review | I | R | A | C | — | |
|
||||
| **[Phase 3: Build]** | | | | | | |
|
||||
| Technical architecture decision | C | C | A/R | I | — | |
|
||||
| Sprint planning | A | C | R | I | I | |
|
||||
| Code review and merge | I | C | R | A | — | |
|
||||
| Security review | I | C | C | A/R | — | |
|
||||
| **[Phase 4: Launch]** | | | | | | |
|
||||
| Launch go / no-go decision | A | C | C | R | I | PM holds final authority |
|
||||
| Release to production | C | I | A/R | I | — | |
|
||||
| Customer communications | A/R | I | I | I | C | |
|
||||
| Post-launch monitoring | C | I | R | A | — | |
|
||||
| **[Ongoing / BAU]** | | | | | | |
|
||||
| Incident response | I | C | R | A | — | |
|
||||
| Feature prioritisation | A/R | C | C | I | I | |
|
||||
| Stakeholder reporting | A/R | I | I | I | C | |
|
||||
|
||||
---
|
||||
|
||||
## 3. Decision Map
|
||||
|
||||
For high-stakes decisions, document the decision type, who holds authority, and how disagreements are resolved:
|
||||
|
||||
| Decision | Authority (A) | Must consult (C) | Escalation path if disagreed |
|
||||
|---|---|---|---|
|
||||
| Scope change >20% effort | [Exec sponsor / Programme lead] | [PM, Engineering lead] | [Steering committee] |
|
||||
| Budget overrun >10% | [Finance / Exec] | [PM, Programme lead] | [CFO / Board] |
|
||||
| Architecture pattern change | [Engineering lead] | [Tech lead, Security] | [CTO] |
|
||||
| Go-live date change | [PM] | [Engineering, Comms, CS] | [Programme sponsor] |
|
||||
| Feature cut from scope | [PM] | [Product, UX, Engineering] | [CPO] |
|
||||
|
||||
---
|
||||
|
||||
## 4. Common RACI Anti-Patterns — and Fixes
|
||||
|
||||
Review the completed matrix against these failure modes:
|
||||
|
||||
| Anti-pattern | Symptom | Fix |
|
||||
|---|---|---|
|
||||
| **Multiple As** | Two teams both think they own an outcome | Agree one A; the other becomes C or I |
|
||||
| **No A** | Decisions stall; no one feels responsible | Assign the most senior stakeholder as A |
|
||||
| **Everyone is C** | Every decision goes to a committee | Audit each C — does this person actually provide input that changes outcomes? If not, move to I |
|
||||
| **R without A** | Work gets done but no one owns quality | Add an A; usually the manager of the R |
|
||||
| **A without R** | Accountability without execution — manager is disconnected | Add an R from the team; or combine A/R if appropriate |
|
||||
| **Too many Rs** | Diffusion of responsibility | Split the task into sub-tasks, each with one clear R |
|
||||
| **Key team missing from matrix** | They're affected but not in the RACI | Add them; assign at minimum I for relevant rows |
|
||||
|
||||
---
|
||||
|
||||
## 5. Communication Template
|
||||
|
||||
Once the RACI is agreed, use this template to communicate it to all involved teams:
|
||||
|
||||
---
|
||||
|
||||
**Subject:** [Project Name] — Roles and Responsibilities Agreed
|
||||
|
||||
We've finalised the RACI matrix for [Project Name]. Here's what it means for you:
|
||||
|
||||
**[Role 1 team]:** You are **Accountable** for [X, Y, Z activities]. This means you make the final call on those decisions and answer if outcomes are not met.
|
||||
|
||||
**[Role 2 team]:** You are **Responsible** for [A, B, C]. You execute the work. For [D], you are **Consulted** — we need your input before decisions are finalised.
|
||||
|
||||
**[Role 3 team]:** You are **Informed** on [E, F] — we'll send you updates at [weekly / milestone / launch]. No action required unless you see something that needs escalation.
|
||||
|
||||
Please review the full matrix here: [Link]. Raise any concerns by [Date] — after that, we'll treat it as agreed.
|
||||
|
||||
---
|
||||
|
||||
## 6. RACI Review Cadence
|
||||
|
||||
| Trigger | Action |
|
||||
|---|---|
|
||||
| New team member joins | Review rows relevant to their role — update R as needed |
|
||||
| Phase change (e.g. discovery → delivery) | Review full matrix — some Rs and As will shift |
|
||||
| Escalation or confusion about ownership | Use the matrix to diagnose — find the missing A |
|
||||
| 3 months into a long programme | Full RACI review — roles drift over time |
|
||||
| Team restructure or reorganisation | Full rebuild — ownership assumptions change |
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Every row has exactly one **A**
|
||||
- [ ] No individual or team is **A** for more than their realistic sphere of authority
|
||||
- [ ] **C** columns are sparse — consulting everyone dilutes the process
|
||||
- [ ] Matrix was reviewed and agreed by at least one representative from each role column
|
||||
- [ ] A communication plan exists to share the RACI with all involved parties
|
||||
- [ ] Decision map covers the top 5–10 highest-stakes decisions in the project
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- "Build a RACI matrix for our product launch"
|
||||
- "Create a responsibility matrix for our new cross-functional project"
|
||||
- "Who owns what on this initiative? Help me build a RACI"
|
||||
- "Map out decision rights for our engineering and product teams"
|
||||
- "Generate a RACI for a [migration / launch / process] involving [teams]"
|
||||
@@ -0,0 +1,190 @@
|
||||
---
|
||||
name: renewal-playbook
|
||||
description: "Build a structured renewal playbook for a customer account. Use when asked to plan a renewal, structure a renewal negotiation, prepare for an expansion conversation, or build a renewal strategy for at-risk or healthy accounts. Produces a renewal brief with health assessment, negotiation strategy, objection responses, expansion levers, and a timeline."
|
||||
---
|
||||
|
||||
# Renewal Playbook Skill
|
||||
|
||||
This skill produces a complete renewal playbook for a specific customer account, covering health assessment, commercial strategy, negotiation preparation, expansion opportunity mapping, and a step-by-step timeline. Output is ready for the CSM or account team to execute 90–180 days before renewal.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask the user for these if not provided:
|
||||
- **Account name**
|
||||
- **Renewal date**
|
||||
- **Current ARR** and proposed renewal ARR (if different)
|
||||
- **Account health** — RAG status and main reasons (or describe the account situation)
|
||||
- **Key stakeholders** — economic buyer, champion, and any detractors
|
||||
- **Renewal risk factors** — budget pressure, low adoption, competitive threat, champion departure, etc.
|
||||
- **Expansion opportunity** — any upsell or cross-sell potential?
|
||||
- **Contract terms** — current plan, duration, and any terms up for renegotiation
|
||||
|
||||
## Output Structure
|
||||
|
||||
---
|
||||
|
||||
# Renewal Playbook: [Account Name]
|
||||
|
||||
**Renewal date:** [Date]
|
||||
**Current ARR:** [£/$/€ X]
|
||||
**Target renewal ARR:** [£/$/€ X — flat / +X% expansion / contraction risk]
|
||||
**Health status:** [Green / Amber / Red]
|
||||
**CSM:** [Name]
|
||||
**Account executive:** [Name]
|
||||
**Days to renewal:** [X days]
|
||||
|
||||
---
|
||||
|
||||
## 1. Account Health Snapshot
|
||||
|
||||
| Dimension | Score (1–5) | Evidence |
|
||||
|---|---|---|
|
||||
| **Product adoption** | [X/5] | [e.g. 3 of 5 purchased seats active; core feature used weekly] |
|
||||
| **Business outcomes** | [X/5] | [e.g. Customer reports X% improvement in [metric]; no formal ROI review done] |
|
||||
| **Relationship depth** | [X/5] | [e.g. Strong champion in [name/role]; limited exec sponsorship] |
|
||||
| **Support & satisfaction** | [X/5] | [e.g. 2 open P2 tickets; last NPS 7; no escalations in 6 months] |
|
||||
| **Commercial engagement** | [X/5] | [e.g. Invoice paid on time; no discount pressure raised yet] |
|
||||
| **Overall health** | [X/5 — weighted] | [Green / Amber / Red] |
|
||||
|
||||
**Renewal thesis:** [One sentence: why this account will renew — or what must change for it to renew.]
|
||||
|
||||
---
|
||||
|
||||
## 2. Stakeholder Map
|
||||
|
||||
| Stakeholder | Role | Influence | Sentiment | Our relationship |
|
||||
|---|---|---|---|---|
|
||||
| [Name] | Economic buyer | High | [Positive / Neutral / Negative] | [Warm / Cold / Unknown] |
|
||||
| [Name] | Champion | High | [Positive] | [Warm] |
|
||||
| [Name] | End user | Low | [Neutral] | [Limited] |
|
||||
| [Name] | IT / procurement | Medium | [Neutral] | [Transactional] |
|
||||
|
||||
**Champion risk:** [Is our champion secure in their role? Any signals of departure or reorganisation?]
|
||||
|
||||
**Multi-thread plan:** [Who else do we need relationships with before renewal? How do we get there?]
|
||||
|
||||
---
|
||||
|
||||
## 3. Risk Register
|
||||
|
||||
| Risk | Likelihood (H/M/L) | Impact (H/M/L) | Mitigation |
|
||||
|---|---|---|---|
|
||||
| [Budget pressure / cost-cutting] | [H] | [H] | [Build ROI case 90 days out; identify budget holder's priorities] |
|
||||
| [Low adoption in [department]] | [M] | [H] | [Run targeted enablement session; tie to champion's OKRs] |
|
||||
| [Competitor evaluation] | [M] | [M] | [Request competitive intelligence; schedule exec-level call] |
|
||||
| [Champion departure] | [L] | [H] | [Map two additional stakeholders; executive intro call] |
|
||||
|
||||
---
|
||||
|
||||
## 4. Value Story
|
||||
|
||||
Build the ROI narrative for the renewal conversation:
|
||||
|
||||
**Headline result:** [e.g. "[Account] saved X hours/week or reduced [metric] by X% using [product]"]
|
||||
|
||||
**Evidence sources:**
|
||||
- [ ] Product usage data (logins, features used, seat utilisation)
|
||||
- [ ] Business metric improvement (pull from QBR deck or success plan)
|
||||
- [ ] Support resolution time improvement
|
||||
- [ ] Customer-provided testimonial or case study quotes
|
||||
|
||||
**Value gaps to close before renewal:** [Are there outcomes the customer expected but hasn't seen yet? What's the plan to close these?]
|
||||
|
||||
---
|
||||
|
||||
## 5. Expansion Opportunity
|
||||
|
||||
Map upside beyond flat renewal:
|
||||
|
||||
| Opportunity | Type | Estimated value | Likelihood | Timing |
|
||||
|---|---|---|---|---|
|
||||
| [Seat expansion — [dept] wants to add 10 users] | Upsell | [+£X ARR] | [High] | [Renewal or +3M] |
|
||||
| [Cross-sell — [Product B] use case identified] | Cross-sell | [+£X ARR] | [Medium] | [+6M] |
|
||||
| [Multi-year commitment] | Discount for term | [+£X TCV / -X% discount] | [Low] | [At renewal] |
|
||||
|
||||
**Expansion play:** [Which opportunity to lead with, and the sequence for raising it in the renewal conversation]
|
||||
|
||||
---
|
||||
|
||||
## 6. Commercial Strategy
|
||||
|
||||
**Renewal scenario planning:**
|
||||
|
||||
| Scenario | Probability | ARR outcome | Response strategy |
|
||||
|---|---|---|---|
|
||||
| **Flat renewal** | [X%] | [£X — same as current] | [Accept; plant seeds for +6M expansion] |
|
||||
| **Expansion** | [X%] | [£X] | [Lead with ROI evidence; pitch seat or feature expansion] |
|
||||
| **Contraction risk** | [X%] | [£X — downgrade to lower tier] | [Propose phased commitment; demonstrate path to full adoption] |
|
||||
| **Churn risk** | [X%] | [£0] | [Escalate to leadership; executive sponsor engagement] |
|
||||
|
||||
**Discount guardrails:**
|
||||
- Floor discount: [X% — do not go below without VP approval]
|
||||
- Triggers for discount: [Multi-year / volume / reference customer commitment]
|
||||
- What to ask for in return: [Reference case study / G2 review / executive intro / case study participation]
|
||||
|
||||
**Pricing flexibility:**
|
||||
- [e.g. Can offer monthly billing in exchange for 24-month commit]
|
||||
- [e.g. Can offer X seats free in exchange for expansion commitment]
|
||||
|
||||
---
|
||||
|
||||
## 7. Objection Responses
|
||||
|
||||
Prepare for the most likely objections:
|
||||
|
||||
**"The price is too high"**
|
||||
> Anchor on value delivered: "[Customer] achieved [X outcome] — at [£X ARR], that's [£Y per outcome / hour saved / user]. What would it cost to deliver that outcome without us?"
|
||||
> If budget is genuinely constrained, explore: phased payment, reduction in scope rather than full churn, multi-year pricing.
|
||||
|
||||
**"We're not seeing enough adoption"**
|
||||
> Acknowledge, then commit: "You're right — [X seats] are actively using [core feature] out of [Y]. We want to fix this. Here's our 60-day plan: [exec sponsor on enablement call / training session / in-product nudge campaign]."
|
||||
|
||||
**"We're evaluating [Competitor]"**
|
||||
> Don't panic. Ask: "What's driving the evaluation — is it specific features, pricing, or something else?" Then map gaps honestly. Offer a feature roadmap preview if relevant. Get clarity on their criteria and timeline before responding defensively.
|
||||
|
||||
**"We need to reduce spend this quarter"**
|
||||
> Separate the commercial conversation from the value conversation. Offer to protect the relationship with a reduced scope today with a committed expansion trigger at a business milestone. Avoid discounting without a reason.
|
||||
|
||||
---
|
||||
|
||||
## 8. Renewal Timeline
|
||||
|
||||
| Week | Action | Owner | Notes |
|
||||
|---|---|---|---|
|
||||
| **W–16** (4 months out) | Internal renewal review — health, expansion opportunity, risk | CSM | Flag to leadership if Red |
|
||||
| **W–12** | QBR / executive business review — ROI evidence delivered | CSM + AE | Book 45–60 min with economic buyer |
|
||||
| **W–10** | Champion 1:1 — pulse check on satisfaction and upcoming priorities | CSM | Uncover internal dynamics before commercial discussion |
|
||||
| **W–8** | Expansion conversation — plant seeds, share roadmap | AE | Do not lead with pricing |
|
||||
| **W–6** | Send renewal proposal — pricing, terms, options | AE | Include multi-year option |
|
||||
| **W–4** | Negotiation — address objections, finalise commercial terms | AE + CSM | Escalate to VP if >X% discount required |
|
||||
| **W–2** | Legal / procurement — contract redlines, signature process | AE + Legal | |
|
||||
| **W–0** | Signed. Handoff to post-renewal success plan | CSM | Thank the champion; begin next cycle |
|
||||
|
||||
---
|
||||
|
||||
## 9. Success Criteria
|
||||
|
||||
- [ ] Renewal signed before deadline
|
||||
- [ ] ARR outcome within target range
|
||||
- [ ] Champion relationship maintained or improved
|
||||
- [ ] At least one expansion conversation started
|
||||
- [ ] ROI evidence documented and accepted by customer
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Stakeholder map includes the economic buyer — not just the champion
|
||||
- [ ] Risk register has a mitigation for every H/H risk
|
||||
- [ ] Value story uses product data and business outcomes, not just feature lists
|
||||
- [ ] Commercial strategy includes a floor discount and a reason-to-discount framework
|
||||
- [ ] Timeline starts at least 90 days before renewal date
|
||||
- [ ] Objection responses are specific to this account, not generic
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- "Build a renewal playbook for [Account Name] renewing in [Month]"
|
||||
- "Help me plan the renewal strategy for an at-risk customer"
|
||||
- "Prepare a renewal brief for my QBR with [Company]"
|
||||
- "What's my renewal strategy for a Red account coming up in 60 days?"
|
||||
- "Create a renewal and expansion plan for [Account]"
|
||||
@@ -0,0 +1,211 @@
|
||||
---
|
||||
name: risk-register
|
||||
description: "Build and maintain a project or product risk register. Use when asked to create a risk register, identify project risks, build a risk matrix, or document risks and mitigations for a programme. Produces a complete risk register with likelihood/impact scoring, RAG status, ownership, and prioritised mitigations."
|
||||
---
|
||||
|
||||
# Risk Register Skill
|
||||
|
||||
This skill produces a complete risk register for a project, programme, or product. Output follows standard risk management practice with likelihood × impact scoring, RAG status, a risk heat map, and specific mitigation and contingency plans. Ready to share with a project board, steering committee, or programme office.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask the user for these if not provided:
|
||||
- **Project or product name**
|
||||
- **Project stage** (discovery / delivery / launch / live / programme-level)
|
||||
- **Key objectives** — what is the project trying to achieve?
|
||||
- **Known risks** — anything already on the team's radar (even informal concerns count)
|
||||
- **Key dependencies** — external vendors, teams, systems, or regulatory approvals
|
||||
- **Deadline or milestone sensitivity** — are there hard dates that cannot move?
|
||||
- **Audience** — who will read this? (internal team / executive steering / external board / regulator)
|
||||
|
||||
## Output Structure
|
||||
|
||||
---
|
||||
|
||||
# Risk Register: [Project / Product Name]
|
||||
|
||||
**Project stage:** [Discovery / Delivery / Launch / Live / Programme]
|
||||
**Version:** [1.0]
|
||||
**Owner:** [PM / Programme Manager / Risk Lead]
|
||||
**Last reviewed:** [Date]
|
||||
**Next review:** [Date — recommend weekly during delivery, monthly during discovery]
|
||||
**Status:** [Active / Archived]
|
||||
|
||||
---
|
||||
|
||||
## 1. Risk Scoring Framework
|
||||
|
||||
**Likelihood (L)**
|
||||
|
||||
| Score | Label | Definition |
|
||||
|---|---|---|
|
||||
| 5 | Almost certain | >80% probability of occurring |
|
||||
| 4 | Likely | 60–80% probability |
|
||||
| 3 | Possible | 40–60% probability |
|
||||
| 2 | Unlikely | 20–40% probability |
|
||||
| 1 | Rare | <20% probability |
|
||||
|
||||
**Impact (I)**
|
||||
|
||||
| Score | Label | Definition |
|
||||
|---|---|---|
|
||||
| 5 | Critical | Programme failure, regulatory breach, major financial loss, safety event |
|
||||
| 4 | High | Significant schedule delay (>4 weeks), scope reduction, reputational damage |
|
||||
| 3 | Medium | Moderate delay (1–4 weeks), cost overrun, reduced quality |
|
||||
| 2 | Low | Minor delay (<1 week), manageable cost increase |
|
||||
| 1 | Negligible | Minimal impact, easily absorbed |
|
||||
|
||||
**Risk Score = L × I**
|
||||
|
||||
| Score | RAG | Action |
|
||||
|---|---|---|
|
||||
| 20–25 | 🔴 Critical | Immediate escalation; active management required |
|
||||
| 12–19 | 🔴 High | Owner-assigned mitigation; weekly review |
|
||||
| 8–11 | 🟡 Medium | Mitigation planned; fortnightly review |
|
||||
| 4–7 | 🟡 Low | Monitor; monthly review |
|
||||
| 1–3 | 🟢 Negligible | Accept; review if context changes |
|
||||
|
||||
---
|
||||
|
||||
## 2. Risk Register
|
||||
|
||||
| ID | Risk | Category | L | I | Score | RAG | Owner | Status | Mitigation | Contingency | Review date |
|
||||
|---|---|---|---|---|---|---|---|---|---|---|---|
|
||||
| R01 | [Risk description — be specific: "Third-party API may not support required volume, causing X to fail"] | [Schedule / Technical / Resource / Commercial / Compliance / External] | [1–5] | [1–5] | [L×I] | 🔴/🟡/🟢 | [Name] | [Open / Mitigating / Closed] | [What are we doing to reduce likelihood or impact?] | [What do we do if it happens?] | [Date] |
|
||||
| R02 | [...] | [...] | [...] | [...] | [...] | [...] | [...] | [...] | [...] | [...] | [...] |
|
||||
|
||||
---
|
||||
|
||||
## 3. Risk Categories — Common Risks by Type
|
||||
|
||||
Use these to prompt risk identification. Add, remove, or customise for your project.
|
||||
|
||||
### Schedule & Delivery
|
||||
- Key milestone depends on a dependency that has not confirmed availability
|
||||
- Team capacity reduced by planned or unplanned absence during critical period
|
||||
- Technical complexity is underestimated — story points consistently overrun
|
||||
- External approval (regulator, legal, procurement) takes longer than planned
|
||||
|
||||
### Technical
|
||||
- Integration with a third-party system not yet prototyped or agreed
|
||||
- Existing technical debt makes the change harder or riskier than estimated
|
||||
- Security or compliance review required before launch has not been scoped
|
||||
- Performance under production load untested
|
||||
- Key technical knowledge held by one person (single point of failure)
|
||||
|
||||
### Resource & People
|
||||
- Key SME or engineer leaving or unavailable during critical phase
|
||||
- Budget not confirmed for Phase 2 of the project
|
||||
- Stakeholder sponsor changes role or leaves the organisation
|
||||
- Team not yet at full capacity (hiring lag, access issues, onboarding time)
|
||||
|
||||
### Commercial & Financial
|
||||
- Vendor or partner contract not yet signed
|
||||
- Cost estimate based on assumptions that have not been validated
|
||||
- Revenue or savings case depends on assumptions outside the team's control
|
||||
- Currency exposure or exchange rate risk for international projects
|
||||
|
||||
### Compliance & Regulatory
|
||||
- Data privacy impact assessment (DPIA) not yet complete
|
||||
- Regulatory approval required and timeline is uncertain
|
||||
- GDPR, HIPAA, SOC 2, or sector-specific compliance requirement not yet mapped
|
||||
- Legal review of terms of service or contracts pending
|
||||
|
||||
### Stakeholder & Adoption
|
||||
- Key user group has low awareness or motivation to adopt the change
|
||||
- Internal resistance from a team that will be affected by the change
|
||||
- Executive sponsor not consistently engaged — decisions are slow
|
||||
- Communications plan not yet agreed with change management team
|
||||
|
||||
### External
|
||||
- Market or competitive change could undermine the business case
|
||||
- Macroeconomic conditions affect budget or priority
|
||||
- Supplier or infrastructure provider risk (e.g. cloud provider, hardware)
|
||||
- Geopolitical or regulatory environment change
|
||||
|
||||
---
|
||||
|
||||
## 4. Risk Heat Map
|
||||
|
||||
Plot risks by likelihood (Y axis) and impact (X axis):
|
||||
|
||||
```
|
||||
│ Low Medium High Critical
|
||||
│ (1) (2-3) (4) (5)
|
||||
─────────┼────────────────────────────────────
|
||||
Almost │ 🟡 🟡 🔴 🔴
|
||||
certain │
|
||||
(5) │
|
||||
─────────┼────────────────────────────────────
|
||||
Likely │ 🟡 🟡 🔴 🔴
|
||||
(4) │
|
||||
─────────┼────────────────────────────────────
|
||||
Possible │ 🟢 🟡 🟡 🔴
|
||||
(3) │
|
||||
─────────┼────────────────────────────────────
|
||||
Unlikely │ 🟢 🟢 🟡 🟡
|
||||
(2) │
|
||||
─────────┼────────────────────────────────────
|
||||
Rare │ 🟢 🟢 🟢 🟡
|
||||
(1) │
|
||||
```
|
||||
|
||||
[Plot each risk ID on this grid — e.g. R01 lands at L4/I5 = 🔴 Critical]
|
||||
|
||||
---
|
||||
|
||||
## 5. Top Risks — Executive Summary
|
||||
|
||||
For steering committee or board-level reporting:
|
||||
|
||||
| Rank | Risk | Score | RAG | Owner | Mitigation status |
|
||||
|---|---|---|---|---|---|
|
||||
| 1 | [Most critical risk — plain English description] | [X] | 🔴 | [Owner] | [Active / Planned / Not started] |
|
||||
| 2 | [...] | [...] | 🔴 | [...] | [...] |
|
||||
| 3 | [...] | [...] | 🟡 | [...] | [...] |
|
||||
| 4 | [...] | [...] | 🟡 | [...] | [...] |
|
||||
| 5 | [...] | [...] | 🟡 | [...] | [...] |
|
||||
|
||||
**Decisions required from steering:**
|
||||
- [Any risk that requires budget, scope, or timeline decision to mitigate]
|
||||
|
||||
---
|
||||
|
||||
## 6. Risk Changes Since Last Review
|
||||
|
||||
| Risk ID | Change | Detail |
|
||||
|---|---|---|
|
||||
| [R03] | Score increased | [L moved from 2 → 4 — vendor confirmed delay in API availability] |
|
||||
| [R07] | Risk closed | [Legal sign-off received on 12 May] |
|
||||
| [NEW] | New risk identified | [R09 — budget freeze announcement affects Phase 2 funding] |
|
||||
|
||||
---
|
||||
|
||||
## 7. Risk Closure Criteria
|
||||
|
||||
A risk is closed when:
|
||||
- The risk event can no longer occur (e.g. milestone passed, contract signed), OR
|
||||
- The residual risk score drops to Negligible (1–3) AND the team formally accepts it, OR
|
||||
- The risk has materialised and transitioned to an **issue** (tracked separately)
|
||||
|
||||
**Issues log:** [Link to issues log — risks that have materialised and are now active problems being managed]
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Every risk has a specific owner — not "the team" or "TBD"
|
||||
- [ ] Mitigations describe what is actively being done — not "monitor and review"
|
||||
- [ ] Contingency plans exist for all Critical and High risks
|
||||
- [ ] Risk descriptions are specific — "vendor may be late" is not specific enough; name the vendor and the dependency
|
||||
- [ ] Register has been reviewed in the last [X] days
|
||||
- [ ] Closed risks are archived, not deleted — they provide audit trail
|
||||
- [ ] Risks are distinguished from issues — a risk is something that might happen; an issue is something that has happened
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- "Build a risk register for our product launch"
|
||||
- "Create a risk matrix for [project name]"
|
||||
- "What risks should I document for a data migration project?"
|
||||
- "Generate a risk register for our steering committee"
|
||||
- "Help me identify and score risks for our Q3 delivery plan"
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: runbook-writer
|
||||
description: "Write an operational runbook for a service, incident type, or deployment procedure. Use when asked to write a runbook, create an ops guide, document an operational procedure, or prepare an incident response playbook. Produces a runbook with overview, prerequisites, step-by-step procedures, rollback steps, troubleshooting table, and escalation paths. Optimised for Opus 4.7 and newer models."
|
||||
description: "Write an operational runbook for a service, incident type, or deployment procedure. Use when asked to write a runbook, create an ops guide, document an operational procedure, or prepare an incident response playbook. Produces a runbook with overview, prerequisites, step-by-step procedures, rollback steps, troubleshooting table, and escalation paths."
|
||||
---
|
||||
|
||||
# Runbook Writer Skill
|
||||
@@ -15,14 +15,16 @@ Ask for these if not provided:
|
||||
- **System/service name and what it does** (brief description)
|
||||
- **Audience** (new on-call engineers / experienced SREs / DevOps team)
|
||||
- **Tech stack** (where relevant — e.g. Kubernetes, AWS RDS, Node.js)
|
||||
- **Monitoring tools** (e.g. Grafana, Datadog, CloudWatch, Splunk — used to name specific dashboards and alert links in the steps)
|
||||
- **Key environment details** (e.g. Kubernetes cluster name, AWS account/region, relevant namespaces or resource names — paste what's relevant for exact commands)
|
||||
|
||||
## Output Structure
|
||||
## Output Format
|
||||
|
||||
---
|
||||
**Runbook:** [Runbook Title]
|
||||
**Service:** [Service Name]
|
||||
**Type:** [Deployment / Incident Response / Maintenance / DR]
|
||||
**Last Updated:** [Date]
|
||||
**Last Updated:** [Insert today's date in YYYY-MM-DD format]
|
||||
**Owner:** [Team or person]
|
||||
**Severity:** [P1 / P2 / P3 — if incident-type]
|
||||
|
||||
@@ -133,10 +135,11 @@ After completing the runbook:
|
||||
- [ ] Expected output is specified for each step so engineer knows if it worked
|
||||
- [ ] Failure path is explicit for each step (not "if it fails, investigate")
|
||||
- [ ] Rollback procedure is complete and independently testable
|
||||
- [ ] Escalation paths name specific contacts, not just team names
|
||||
- [ ] Escalation table has no cells containing only "[Team name]" — every row must either have a real contact or be explicitly flagged as [FILL IN: on-call rotation link]
|
||||
- [ ] Rollback section contains at least one concrete command (not left as "[rollback command]" placeholder)
|
||||
- [ ] Runbook can be followed by someone who has never touched this system
|
||||
|
||||
## Example Trigger Phrases
|
||||
## Usage Examples
|
||||
- "Write a runbook for [service] deployment"
|
||||
- "Create an incident response runbook for [alert type]"
|
||||
- "I need a runbook for [procedure]"
|
||||
|
||||
@@ -0,0 +1,328 @@
|
||||
---
|
||||
name: social-ad-campaign
|
||||
description: "Plan and write a paid social advertising campaign. Use when asked to build a paid social campaign, create Meta/LinkedIn/TikTok/X ad copy, define a social ad strategy, or plan an advertising funnel across social platforms. Produces a complete campaign plan with audience targeting, ad set structure, copy for each ad format, budget allocation, and measurement framework."
|
||||
---
|
||||
|
||||
# Social Ad Campaign Skill
|
||||
|
||||
This skill produces a complete paid social advertising campaign plan covering campaign objective, audience targeting, funnel structure, ad set architecture, ad copy and creative briefs for each format, budget allocation, bidding strategy, and a measurement framework. Output is ready for a media buyer, performance marketer, or social team to execute.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask the user for these if not provided:
|
||||
- **Brand / product name**
|
||||
- **Campaign objective** — what are you trying to achieve? (traffic / leads / conversions / brand awareness / app installs / video views / event promotion)
|
||||
- **Platform(s)** — Meta (Facebook/Instagram), LinkedIn, TikTok, X/Twitter, Pinterest, Snapchat
|
||||
- **Target audience** — who are you trying to reach? (demographics, interests, job titles, behaviours, lookalikes)
|
||||
- **Budget** — total campaign budget and timeframe (e.g. £5,000 over 4 weeks)
|
||||
- **Offer / landing page** — what is the ad driving to? (free trial, product page, lead form, event sign-up)
|
||||
- **Key message** — the single most important thing the ad must communicate
|
||||
|
||||
## Output Structure
|
||||
|
||||
---
|
||||
|
||||
# Paid Social Campaign Plan: [Brand] — [Campaign Name]
|
||||
|
||||
**Campaign objective:** [e.g. Lead generation — 200 qualified leads in 30 days]
|
||||
**Platform(s):** [e.g. Meta (Instagram + Facebook), LinkedIn]
|
||||
**Budget:** [£/$/€ X total over X weeks]
|
||||
**Campaign period:** [Start date → End date]
|
||||
**Owner:** [Media buyer / performance marketer / agency]
|
||||
**Date:** [Date]
|
||||
|
||||
---
|
||||
|
||||
## 1. Campaign Strategy Overview
|
||||
|
||||
**Why paid social for this objective:**
|
||||
[2–3 sentences justifying the platform and format choice for this specific goal and audience. E.g. "LinkedIn is the right channel for this B2B SaaS campaign — we can target by job title, company size, and seniority, ensuring budget reaches decision-makers, not browsers."]
|
||||
|
||||
**Funnel structure:**
|
||||
|
||||
| Stage | Objective | Audience | Budget allocation |
|
||||
|---|---|---|---|
|
||||
| **Top of funnel (TOFU)** | Awareness / reach | Cold audience — interest/behaviour targeting | [X%] |
|
||||
| **Middle of funnel (MOFU)** | Consideration / engagement | Warm audience — video viewers, page engagers, website visitors | [X%] |
|
||||
| **Bottom of funnel (BOFU)** | Conversion / lead | Hot audience — retargeting, custom audiences, lookalikes | [X%] |
|
||||
|
||||
---
|
||||
|
||||
## 2. Audience Targeting
|
||||
|
||||
### Audience 1: [Cold — Primary Target]
|
||||
|
||||
**Platform:** [Meta / LinkedIn / TikTok]
|
||||
**Audience size target:** [e.g. 500K–2M — broad enough to learn, narrow enough to be relevant]
|
||||
|
||||
| Targeting dimension | Settings |
|
||||
|---|---|
|
||||
| Location | [Country / region / city] |
|
||||
| Age | [e.g. 28–45] |
|
||||
| Gender | [All / specify if relevant] |
|
||||
| Interests / behaviours | [e.g. SaaS tools, productivity apps, small business owners] |
|
||||
| Job titles (LinkedIn) | [e.g. Head of Marketing, Marketing Director, CMO] |
|
||||
| Company size (LinkedIn) | [e.g. 50–500 employees] |
|
||||
| Industry (LinkedIn) | [e.g. Technology, Financial Services, Healthcare] |
|
||||
| Exclude | [e.g. Existing customers — upload suppression list] |
|
||||
|
||||
### Audience 2: [Warm — Engagement Retargeting]
|
||||
|
||||
**Platform:** [Meta]
|
||||
**Source:** People who engaged with content / visited website in last 30 days
|
||||
|
||||
| Signal | Action |
|
||||
|---|---|
|
||||
| Watched 50%+ of a video ad | Retarget with a case study or testimonial ad |
|
||||
| Visited product page but didn't convert | Retarget with a direct offer / free trial CTA |
|
||||
| Engaged with Instagram / Facebook page | Retarget with social proof ad |
|
||||
|
||||
### Audience 3: [Hot — Conversion Retargeting]
|
||||
|
||||
**Platform:** [Meta / LinkedIn]
|
||||
**Source:** Website visitors (last 7 days), abandoned cart, form started but not completed
|
||||
|
||||
**Retargeting message:** More direct. Address the specific action they took. Time-sensitive CTA.
|
||||
|
||||
### Audience 4: [Lookalike]
|
||||
|
||||
**Source:** [Existing customers / email list / best-converting website visitors]
|
||||
**Lookalike similarity:** [1%–3% (tight match) / 3%–10% (broader reach)]
|
||||
**Platform:** Meta
|
||||
|
||||
---
|
||||
|
||||
## 3. Campaign Structure
|
||||
|
||||
### Meta Campaign Architecture
|
||||
|
||||
```
|
||||
Campaign: [Campaign Name] — [Objective: Lead Generation / Traffic / Conversions]
|
||||
│
|
||||
├── Ad Set 1: TOFU — Cold Interests
|
||||
│ ├── Ad 1A: [Video ad — hook format]
|
||||
│ ├── Ad 1B: [Static image — benefit-led headline]
|
||||
│ └── Ad 1C: [Carousel — feature/use case showcase]
|
||||
│
|
||||
├── Ad Set 2: MOFU — Warm Retargeting (30-day engagers)
|
||||
│ ├── Ad 2A: [Social proof / testimonial]
|
||||
│ └── Ad 2B: [Case study / before & after]
|
||||
│
|
||||
└── Ad Set 3: BOFU — Hot Retargeting (7-day website visitors)
|
||||
├── Ad 3A: [Direct offer — free trial / discount / demo]
|
||||
└── Ad 3B: [Objection handling — FAQ / reassurance]
|
||||
```
|
||||
|
||||
### LinkedIn Campaign Architecture
|
||||
|
||||
```
|
||||
Campaign Group: [Campaign Name]
|
||||
│
|
||||
├── Campaign 1: [Job Title Targeting — Awareness]
|
||||
│ ├── Single Image Ad: [Thought leadership hook]
|
||||
│ └── Video Ad: [Problem/solution story]
|
||||
│
|
||||
├── Campaign 2: [Company Size + Industry — Consideration]
|
||||
│ ├── Single Image Ad: [Case study / proof point]
|
||||
│ └── Lead Gen Form: [Gated asset / webinar / demo]
|
||||
│
|
||||
└── Campaign 3: [Retargeting — Conversion]
|
||||
└── Sponsored Message / Lead Gen Form: [Direct CTA with personalisation]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Ad Copy
|
||||
|
||||
### Format 1: Video Ad (15–30 seconds) — TOFU
|
||||
|
||||
**Hook (first 3 seconds — must stop the scroll):**
|
||||
> "[Pattern interrupt question or statement — e.g. 'Are you still doing [painful thing] manually?']"
|
||||
|
||||
**Core message (seconds 4–20):**
|
||||
> "[Agitate the problem → introduce the solution → show the specific outcome]"
|
||||
|
||||
**CTA (final 5 seconds):**
|
||||
> "[Clear, single action — e.g. 'Try free for 14 days — link in bio' / 'Get your demo today']"
|
||||
|
||||
**Visual direction:**
|
||||
- [e.g. Founder talking to camera in natural setting — authentic, not polished ad]
|
||||
- [e.g. Screen recording showing the product in use — show the outcome, not the feature]
|
||||
- [e.g. Customer testimonial — real person, real result, first-person story]
|
||||
|
||||
**Caption copy:**
|
||||
> [Headline — max 40 chars]
|
||||
> [Body copy — 1–3 sentences max]
|
||||
> [CTA button label: e.g. "Learn More" / "Sign Up" / "Get Started"]
|
||||
|
||||
---
|
||||
|
||||
### Format 2: Static Image Ad — TOFU/MOFU
|
||||
|
||||
**Ad variant A — Benefit-led headline:**
|
||||
|
||||
| Element | Copy |
|
||||
|---|---|
|
||||
| **Headline** | "[Single-sentence benefit statement — e.g. 'Cut reporting time by 80% with [Product]']" |
|
||||
| **Body copy** | "[Problem → solution in 2 sentences. Proof point if available.]" |
|
||||
| **CTA** | "Start free trial" / "Book a demo" / "Get 20% off" |
|
||||
| **Image** | [Product UI / result visual / human context shot — no stock photos of people in suits] |
|
||||
|
||||
**Ad variant B — Social proof headline:**
|
||||
|
||||
| Element | Copy |
|
||||
|---|---|
|
||||
| **Headline** | "['[Result] in [timeframe]' — real customer result, or '500+ teams use [Product] to...']" |
|
||||
| **Body copy** | "[Expand on the proof. 1–2 sentences. Add a second proof point if available.]" |
|
||||
| **CTA** | "See how it works" / "Try it free" |
|
||||
| **Image** | [Customer photo + quote overlay / logo wall / before/after data visual] |
|
||||
|
||||
**Ad variant C — Curiosity/question headline:**
|
||||
|
||||
| Element | Copy |
|
||||
|---|---|
|
||||
| **Headline** | "['[Common misconception or challenging question]' — e.g. 'What if [painful process] took 10 minutes, not 2 hours?']" |
|
||||
| **Body copy** | "[Answer the question → introduce product → specific outcome]" |
|
||||
| **CTA** | "Find out how" |
|
||||
|
||||
---
|
||||
|
||||
### Format 3: Carousel Ad — Features / Use Cases
|
||||
|
||||
**Headline (shown above carousel):** "[Problem-first statement or benefit hook]"
|
||||
|
||||
| Card # | Headline | Description | Image |
|
||||
|---|---|---|---|
|
||||
| Card 1 (hook) | "[Compelling hook — why this matters]" | "[1-sentence setup]" | [Eye-catching visual / stat] |
|
||||
| Card 2 | "[Use case / feature 1]" | "[Specific outcome this delivers]" | [Product UI or illustration] |
|
||||
| Card 3 | "[Use case / feature 2]" | "[Specific outcome this delivers]" | [Product UI or illustration] |
|
||||
| Card 4 | "[Use case / feature 3]" | "[Specific outcome this delivers]" | [Product UI or illustration] |
|
||||
| Card 5 (CTA card) | "[Strong CTA headline]" | "[Reinforce the offer / urgency]" | [CTA-focused visual / button] |
|
||||
|
||||
---
|
||||
|
||||
### Format 4: Lead Gen Form Ad (LinkedIn / Meta)
|
||||
|
||||
**Intro text (shown before form):**
|
||||
> "[1–2 sentences on what they'll get and why it's worth 60 seconds of their time]"
|
||||
|
||||
**Form headline:** "[Value-led headline — e.g. 'Get your free [asset] / Book your 20-min demo']"
|
||||
|
||||
**Form fields (keep to minimum — each extra field reduces conversion):**
|
||||
- First name
|
||||
- Work email
|
||||
- [One qualifying question — e.g. "Company size" / "Current tool used" / "Biggest challenge"]
|
||||
|
||||
**Privacy notice:** [Standard GDPR / CCPA compliance text — "By submitting, you agree to our Privacy Policy and may be contacted by [Brand] about relevant products and services."]
|
||||
|
||||
**Thank you message:**
|
||||
> "[What happens next — e.g. 'Thanks! You'll receive [asset] in your inbox within 5 minutes. Our team will be in touch within 1 business day.']"
|
||||
|
||||
---
|
||||
|
||||
### Format 5: Retargeting Ad — BOFU
|
||||
|
||||
**For website visitors (7 days) — direct offer:**
|
||||
> Headline: "[Specific nudge — e.g. 'Still thinking about [Product]? Here's 20% off to make the decision easier.']"
|
||||
> Body: "[Reinforce the primary benefit. Add urgency if genuine — e.g. 'Offer ends [date]'.]"
|
||||
> CTA: "Claim offer" / "Start free trial" / "Book demo"
|
||||
|
||||
**For video viewers (50%+) — social proof bridge:**
|
||||
> Headline: "[Continue the story — e.g. 'See what [50/100/500] teams achieved with [Product]']"
|
||||
> Body: "[Customer result quote or specific outcome. Bridge from awareness to consideration.]"
|
||||
> CTA: "Read the case study" / "See how it works"
|
||||
|
||||
---
|
||||
|
||||
## 5. Budget Allocation
|
||||
|
||||
**Total budget:** [£/$/€ X over X weeks]
|
||||
|
||||
| Ad Set | Stage | Budget | % of total | Expected CPM | Expected CPC | Expected conversions |
|
||||
|---|---|---|---|---|---|---|
|
||||
| Ad Set 1 — Cold interests | TOFU | [£X/week] | [X%] | [£X] | [£X] | [X leads / clicks] |
|
||||
| Ad Set 2 — Warm retargeting | MOFU | [£X/week] | [X%] | [£X] | [£X] | [X] |
|
||||
| Ad Set 3 — Hot retargeting | BOFU | [£X/week] | [X%] | [£X] | [£X] | [X] |
|
||||
| **Total** | — | [£X/week] | 100% | — | — | [X total] |
|
||||
|
||||
**Bidding strategy:**
|
||||
- TOFU: [Lowest cost / Maximum reach — optimise for video views or link clicks]
|
||||
- MOFU: [Lowest cost — optimise for landing page views or lead form opens]
|
||||
- BOFU: [Cost cap / Target cost — optimise for conversions or lead form submits]
|
||||
|
||||
**Budget reallocation rule:** After [7] days, pause ad sets with CPL > [£X]. Reallocate budget to best-performing ad sets. Review weekly.
|
||||
|
||||
---
|
||||
|
||||
## 6. Measurement Framework
|
||||
|
||||
**Primary KPI (tied to campaign objective):**
|
||||
|
||||
| KPI | Target | Why |
|
||||
|---|---|---|
|
||||
| [Cost per lead (CPL)] | [≤ £/$/€ X] | [Primary success metric — every pound spent measured against leads generated] |
|
||||
| [Conversion rate (ad → lead form)] | [≥ X%] | [Quality of targeting and ad relevance] |
|
||||
| [Total leads] | [≥ X in X weeks] | [Volume target] |
|
||||
|
||||
**Secondary metrics (optimisation signals):**
|
||||
|
||||
| Metric | Target | Action if off-target |
|
||||
|---|---|---|
|
||||
| CTR (click-through rate) | [≥ X%] | [Test new headlines / hook variations] |
|
||||
| CPM (cost per 1K impressions) | [≤ £/$/€ X] | [Broaden audience / test new placements] |
|
||||
| Video completion rate (if video) | [≥ X%] | [Test shorter video / stronger hook] |
|
||||
| Lead form completion rate | [≥ X%] | [Reduce form fields / test form intro copy] |
|
||||
| Lead-to-opportunity rate (post-campaign) | [≥ X%] | [Review lead quality — tighten audience targeting] |
|
||||
|
||||
**Reporting cadence:**
|
||||
- Daily: Check spend, CTR, and CPL — pause clearly underperforming ads
|
||||
- Weekly: Full performance review + budget reallocation decision
|
||||
- Campaign end: Final report with learnings for next campaign
|
||||
|
||||
**Attribution model:** [Last-click / 7-day click + 1-day view / data-driven (if volume sufficient)]
|
||||
|
||||
**Tracking setup checklist:**
|
||||
- [ ] Pixel / conversion API installed and verified on landing page
|
||||
- [ ] Conversion event firing correctly (lead form submit / purchase / sign-up)
|
||||
- [ ] UTM parameters set on all ad destination URLs
|
||||
- [ ] Lead form CRM integration tested
|
||||
- [ ] Lookalike audiences seeded from customer list upload
|
||||
|
||||
---
|
||||
|
||||
## 7. A/B Testing Plan
|
||||
|
||||
Run structured tests — change one variable at a time:
|
||||
|
||||
| Test # | Variable | Control | Variant | Success metric | Min budget to run |
|
||||
|---|---|---|---|---|---|
|
||||
| 1 | Hook / headline | [Current headline] | [Challenger headline] | CTR | [£X / 500 impressions] |
|
||||
| 2 | Creative format | Static image | Video | CPL | [£X / 1,000 impressions] |
|
||||
| 3 | CTA | "Learn More" | "Start free trial" | Conversion rate | [£X / 200 clicks] |
|
||||
| 4 | Audience | Interest-based | Lookalike 1% | CPL | [Equal budget split] |
|
||||
|
||||
**Testing rules:**
|
||||
- Run each test for minimum [7] days or [1,000 impressions] — whichever comes first
|
||||
- Change one variable at a time — never two in the same test
|
||||
- Document results and apply winning variant to all future campaigns
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Campaign objective is single and measurable — not "awareness and leads"
|
||||
- [ ] Full-funnel structure: TOFU, MOFU, and BOFU ad sets are separate
|
||||
- [ ] Each ad has a specific hook, benefit, and CTA — not generic copy
|
||||
- [ ] Ad copy has been tested against the "1-second scroll stop" rule — does the hook compel a pause?
|
||||
- [ ] Budget allocation reflects funnel logic — BOFU gets proportionally more per lead
|
||||
- [ ] Tracking setup checklist completed before campaign goes live
|
||||
- [ ] A/B test plan is in place — one variable per test, minimum budget defined
|
||||
- [ ] Retargeting suppression is set — existing customers excluded from acquisition campaigns
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- "Plan a paid social campaign for [product launch]"
|
||||
- "Build Meta ad copy for our lead generation campaign"
|
||||
- "Create a LinkedIn ad campaign for [B2B SaaS product]"
|
||||
- "Write TikTok ad copy for [consumer brand]"
|
||||
- "Structure a paid social funnel for [offer]"
|
||||
@@ -0,0 +1,227 @@
|
||||
---
|
||||
name: social-media-audit
|
||||
description: "Audit an existing social media presence across all active platforms. Use when asked to review social media performance, analyse a brand's social presence, benchmark against competitors, or identify what's working and what isn't. Produces a scored audit with platform-by-platform analysis, content performance review, competitive benchmarking, and a prioritised action plan."
|
||||
---
|
||||
|
||||
# Social Media Audit Skill
|
||||
|
||||
This skill produces a comprehensive social media audit covering profile completeness, content performance, audience engagement, posting consistency, competitive position, and a prioritised improvement plan. Output is ready for a social media manager, marketing lead, or agency to act on immediately.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask the user for these if not provided:
|
||||
- **Brand / handle name** — which account(s) to audit
|
||||
- **Active platforms** — which social channels to include (LinkedIn, Instagram, X/Twitter, TikTok, YouTube, Facebook, etc.)
|
||||
- **Audit timeframe** — what period to review (e.g. last 90 days, last 6 months)
|
||||
- **Business goal** — what social media should be achieving (brand awareness / lead gen / community / sales)
|
||||
- **Competitor handles** — 2–3 competitors or benchmark accounts for comparison
|
||||
- **Available metrics** — follower count, average engagement rate, post frequency, reach, impressions (if the user has them)
|
||||
|
||||
## Output Structure
|
||||
|
||||
---
|
||||
|
||||
# Social Media Audit: [Brand Name]
|
||||
|
||||
**Audit period:** [e.g. Feb–Apr 2026]
|
||||
**Platforms audited:** [List]
|
||||
**Audited by:** [Name / role]
|
||||
**Date:** [Date]
|
||||
**Overall health score:** [X / 100]
|
||||
|
||||
---
|
||||
|
||||
## 1. Audit Summary — Health Score
|
||||
|
||||
Score each dimension out of 10. Weighted total = overall health score out of 100.
|
||||
|
||||
| Dimension | Weight | Score (/10) | Weighted Score | Assessment |
|
||||
|---|---|---|---|---|
|
||||
| Profile completeness & branding | 10% | [X] | [X] | [1-sentence note] |
|
||||
| Content quality & consistency | 25% | [X] | [X] | [1-sentence note] |
|
||||
| Audience engagement | 20% | [X] | [X] | [1-sentence note] |
|
||||
| Follower growth | 15% | [X] | [X] | [1-sentence note] |
|
||||
| Platform strategy fit | 15% | [X] | [X] | [1-sentence note] |
|
||||
| Competitive position | 15% | [X] | [X] | [1-sentence note] |
|
||||
| **Total** | 100% | — | **[X/100]** | [Overall verdict] |
|
||||
|
||||
**Overall verdict:** 🟢 Strong (80–100) / 🟡 Developing (60–79) / 🔴 Needs work (<60)
|
||||
|
||||
---
|
||||
|
||||
## 2. Platform-by-Platform Analysis
|
||||
|
||||
Repeat this section for each active platform:
|
||||
|
||||
### [Platform Name] — Score: [X/10]
|
||||
|
||||
**Profile health:**
|
||||
- Bio / description: [Clear and keyword-rich / generic / missing]
|
||||
- Profile photo / banner: [Professional / outdated / mismatched]
|
||||
- Link in bio / CTA: [Present and current / missing]
|
||||
- Pinned content: [Exists and strategic / outdated / none]
|
||||
- Contact info / location: [Complete / incomplete]
|
||||
|
||||
**Audience:**
|
||||
- Followers: [X]
|
||||
- Follower growth (audit period): [+X% / -X% / flat]
|
||||
- Follower quality: [Relevant audience / mixed / unclear]
|
||||
|
||||
**Content performance:**
|
||||
|
||||
| Metric | Your account | Benchmark / competitor | Gap |
|
||||
|---|---|---|---|
|
||||
| Posts per week | [X] | [X] | [+/- X] |
|
||||
| Average engagement rate | [X%] | [X%] | [+/- X%] |
|
||||
| Average reach per post | [X] | [X] | [+/- X] |
|
||||
| Top format by engagement | [e.g. carousel] | [e.g. video] | [Match / mismatch] |
|
||||
|
||||
**Content audit — what you posted:**
|
||||
|
||||
| Content type | % of posts | Avg engagement | Verdict |
|
||||
|---|---|---|---|
|
||||
| Educational / how-to | [X%] | [X%] | [Keep / scale / drop] |
|
||||
| Product / promotional | [X%] | [X%] | [Keep / scale / drop] |
|
||||
| Behind-the-scenes | [X%] | [X%] | [Keep / scale / drop] |
|
||||
| Social proof / testimonials | [X%] | [X%] | [Keep / scale / drop] |
|
||||
| Engagement bait / conversation starters | [X%] | [X%] | [Keep / scale / drop] |
|
||||
|
||||
**Top 3 performing posts:**
|
||||
1. [Post description + why it worked]
|
||||
2. [Post description + why it worked]
|
||||
3. [Post description + why it worked]
|
||||
|
||||
**Bottom 3 performing posts:**
|
||||
1. [Post description + why it underperformed]
|
||||
2. [Post description + why it underperformed]
|
||||
3. [Post description + why it underperformed]
|
||||
|
||||
**Posting patterns:**
|
||||
- Best performing days: [e.g. Tue, Thu]
|
||||
- Best performing times: [e.g. 08:00–10:00]
|
||||
- Actual posting pattern: [e.g. sporadic / daily / consistent]
|
||||
- Consistency score: [Consistent / irregular / sporadic]
|
||||
|
||||
**Platform verdict:** [2–3 sentences on what's working, what isn't, and the #1 change to make]
|
||||
|
||||
---
|
||||
|
||||
## 3. Competitive Benchmarking
|
||||
|
||||
Compare against 2–3 competitors or aspirational accounts:
|
||||
|
||||
| Metric | [Your brand] | [Competitor 1] | [Competitor 2] | [Competitor 3] |
|
||||
|---|---|---|---|---|
|
||||
| LinkedIn followers | | | | |
|
||||
| LinkedIn eng. rate | | | | |
|
||||
| Instagram followers | | | | |
|
||||
| Instagram eng. rate | | | | |
|
||||
| Post frequency (all platforms) | | | | |
|
||||
| Content formats used | | | | |
|
||||
| Top content theme | | | | |
|
||||
|
||||
**Competitive gaps:**
|
||||
- **Where you're ahead:** [Specific metrics or tactics where you outperform]
|
||||
- **Where you're behind:** [Specific gaps — follower count, engagement, content variety]
|
||||
- **Opportunities they're missing:** [Whitespace you could own]
|
||||
|
||||
**What competitors are doing well that you should steal (ethically):**
|
||||
1. [Tactic / format / approach]
|
||||
2. [Tactic / format / approach]
|
||||
3. [Tactic / format / approach]
|
||||
|
||||
---
|
||||
|
||||
## 4. Content Strategy Assessment
|
||||
|
||||
**Are you posting the right mix?**
|
||||
|
||||
| Principle | Met? | Evidence | Recommendation |
|
||||
|---|---|---|---|
|
||||
| 80/20 rule: audience value vs self-promotion | [Yes/No] | [X% promotional posts] | [...] |
|
||||
| Consistent content pillars | [Yes/No] | [Pillars identified or not] | [...] |
|
||||
| Format variety (not just text posts) | [Yes/No] | [Format breakdown] | [...] |
|
||||
| Regular engagement with audience | [Yes/No] | [Reply rate, comment engagement] | [...] |
|
||||
| SEO / discoverability in profiles and posts | [Yes/No] | [Keywords, hashtags used] | [...] |
|
||||
|
||||
**Content gaps identified:**
|
||||
- [Gap 1: e.g. No video content despite video outperforming text on Instagram]
|
||||
- [Gap 2: e.g. No customer stories or social proof]
|
||||
- [Gap 3: e.g. Hashtag strategy missing — no discoverability beyond existing followers]
|
||||
|
||||
---
|
||||
|
||||
## 5. Audience Insights
|
||||
|
||||
**Follower quality assessment:**
|
||||
- Do followers match the target audience? [Yes / Partially / No]
|
||||
- Signs of inorganic growth? [e.g. high follower count, very low engagement = possible bought followers]
|
||||
- Most engaged audience segments: [e.g. industry, role, geography if visible from analytics]
|
||||
|
||||
**Engagement quality:**
|
||||
- Comment sentiment: [Positive / Mixed / Negative / Sparse]
|
||||
- Are comments substantive or just emoji reactions? [Substantive / Surface-level]
|
||||
- Are you responding to comments? [Always / Sometimes / Rarely / Never]
|
||||
- DMs / direct inquiries from social: [High / Low / None tracked]
|
||||
|
||||
---
|
||||
|
||||
## 6. Prioritised Action Plan
|
||||
|
||||
Ranked by impact × effort:
|
||||
|
||||
### 🔴 Do immediately (this week)
|
||||
|
||||
| Action | Platform | Why | Expected impact |
|
||||
|---|---|---|---|
|
||||
| [e.g. Update LinkedIn bio with clear value prop and keywords] | LinkedIn | Profile discovery | Higher profile views |
|
||||
| [e.g. Pin best-performing post to top of profile] | Instagram | First impression | Higher follow rate |
|
||||
| [e.g. Add link in bio with UTM tracking] | All | Traffic attribution | Measurable ROI |
|
||||
|
||||
### 🟡 Do this month
|
||||
|
||||
| Action | Platform | Why | Expected impact |
|
||||
|---|---|---|---|
|
||||
| [e.g. Launch a weekly educational carousel series] | LinkedIn | Fills content gap, high engagement format | +X% engagement rate |
|
||||
| [e.g. Start responding to all comments within 24h] | All | Signals algorithm engagement | Improved reach |
|
||||
| [e.g. Test video format 2x per week] | Instagram / TikTok | Underutilised high-reach format | Follower growth |
|
||||
|
||||
### 🟢 Do this quarter
|
||||
|
||||
| Action | Platform | Why | Expected impact |
|
||||
|---|---|---|---|
|
||||
| [e.g. Define 3–5 content pillars and build a monthly calendar] | All | Strategic consistency | Compound growth |
|
||||
| [e.g. Run a hashtag audit — identify 15–20 relevant tags per platform] | Instagram / LinkedIn | Discoverability | Organic reach |
|
||||
| [e.g. Source 3 customer stories for social proof content] | All | Social proof pillar | Trust + conversion |
|
||||
|
||||
---
|
||||
|
||||
## 7. 30-Day Quick Win Plan
|
||||
|
||||
The fastest way to improve the score by 10+ points:
|
||||
|
||||
| Week | Priority action | Platform | Owner | Success metric |
|
||||
|---|---|---|---|---|
|
||||
| 1 | [e.g. Fix all profile gaps — bio, photo, CTA, pinned post] | All | [Name] | 100% profile completeness |
|
||||
| 2 | [e.g. Post 3x educational carousel / video this week] | LinkedIn / IG | [Name] | ≥X% engagement rate |
|
||||
| 3 | [e.g. Engage actively — comment on 10 accounts per day] | LinkedIn / IG | [Name] | +X new followers |
|
||||
| 4 | [e.g. Review analytics and double down on best format] | All | [Name] | Identify top performing format |
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Every platform scored against objective criteria, not guesswork
|
||||
- [ ] Competitive benchmarks use real data, not assumptions
|
||||
- [ ] Content audit covers actual post types posted, not idealised mix
|
||||
- [ ] Recommendations are specific and actionable — not "post more content"
|
||||
- [ ] Action plan is sequenced by impact × effort, not just effort
|
||||
- [ ] 30-day plan has named owners and measurable success metrics
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- "Audit our social media presence"
|
||||
- "Review our Instagram and LinkedIn performance"
|
||||
- "How are we doing on social compared to competitors?"
|
||||
- "What's working and what isn't on our social channels?"
|
||||
- "Give me a social media health check for [brand]"
|
||||
@@ -0,0 +1,237 @@
|
||||
---
|
||||
name: social-media-strategy
|
||||
description: "Build a social media strategy for a brand, product, or creator. Use when asked to create a social media strategy, define a social content strategy, plan content pillars, set social KPIs, or build a posting framework. Produces a complete strategy with audience definition, platform selection, content pillars, posting cadence, KPIs, and a 4-week starter calendar."
|
||||
---
|
||||
|
||||
# Social Media Strategy Skill
|
||||
|
||||
This skill produces a complete social media strategy covering audience definition, platform rationale, content pillars, posting cadence, tone of voice guidelines, measurement framework, and a 4-week starter content calendar. Output is ready for a marketing team, founder, or agency to execute immediately.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask the user for these if not provided:
|
||||
- **Brand / product / creator name**
|
||||
- **What you're promoting** — product, service, personal brand, community, or event
|
||||
- **Target audience** — who are you trying to reach? (job title, age, interests, platforms they use)
|
||||
- **Business goal** — what does social need to achieve? (brand awareness / lead generation / community building / sales / recruitment)
|
||||
- **Current social presence** — which platforms are you on? What's working, what isn't?
|
||||
- **Competitors or aspirational accounts** — who does social well in your space?
|
||||
- **Resources** — how many people and how much time per week can you dedicate to social?
|
||||
|
||||
## Output Structure
|
||||
|
||||
---
|
||||
|
||||
# Social Media Strategy: [Brand / Product / Creator]
|
||||
|
||||
**Goal:** [Primary business goal]
|
||||
**Audience:** [1-sentence description of primary audience]
|
||||
**Timeframe:** [e.g. Q3 2026 — 3-month strategy]
|
||||
**Owner:** [Marketing lead / founder / social team]
|
||||
**Date:** [Date]
|
||||
|
||||
---
|
||||
|
||||
## 1. Audience Profile
|
||||
|
||||
**Primary audience:**
|
||||
|
||||
| Dimension | Detail |
|
||||
|---|---|
|
||||
| **Who they are** | [Job title, age range, life stage, geography] |
|
||||
| **What they care about** | [Professional or personal priorities, pain points] |
|
||||
| **Where they spend time online** | [Platforms, communities, influencers they follow] |
|
||||
| **What they consume** | [Content formats they engage with — video, threads, newsletters, podcasts] |
|
||||
| **What would make them follow you** | [The specific value proposition of your social presence] |
|
||||
|
||||
**Secondary audience:** [Any secondary segment — e.g. job seekers if you're a brand, investors if you're a startup]
|
||||
|
||||
---
|
||||
|
||||
## 2. Platform Strategy
|
||||
|
||||
Not every platform is right for every brand. Justify each platform choice:
|
||||
|
||||
| Platform | Audience fit | Content format | Priority | Why (or why not) |
|
||||
|---|---|---|---|---|
|
||||
| **LinkedIn** | [B2B / professional] | [Text posts, carousels, articles] | [Primary / Secondary / Skip] | [e.g. Primary platform for B2B SaaS — where buyers and influencers are] |
|
||||
| **X / Twitter** | [Tech, media, founders] | [Short text, threads, replies] | [...] | [...] |
|
||||
| **Instagram** | [Consumer, visual brands, creators] | [Reels, Stories, carousels] | [...] | [...] |
|
||||
| **TikTok** | [B2C, Gen Z, consumer] | [Short-form video] | [...] | [...] |
|
||||
| **YouTube** | [All audiences — discovery + long-form] | [Long-form video, Shorts] | [...] | [...] |
|
||||
| **Threads** | [Text-first, creator, early adopter] | [Short text, conversations] | [...] | [...] |
|
||||
|
||||
**Lead platform:** [One platform to invest most heavily in — where your audience is most active and where you have the best chance to stand out]
|
||||
|
||||
**Supporting platforms:** [1–2 secondary platforms where you'll repurpose or adapt content]
|
||||
|
||||
---
|
||||
|
||||
## 3. Content Pillars
|
||||
|
||||
Define 3–5 content themes that anchor your social presence. Each pillar must serve the audience, not just the brand.
|
||||
|
||||
### Pillar 1: [Name — e.g. "Behind the build"]
|
||||
|
||||
**What it is:** [1-sentence description]
|
||||
**Why the audience cares:** [What value does this deliver to them?]
|
||||
**Content examples:**
|
||||
- [e.g. Engineering decisions we made and why]
|
||||
- [e.g. Week-in-the-life of the founding team]
|
||||
- [e.g. What we shipped this week and what we learned]
|
||||
|
||||
**Format mix:** [Carousel / video / thread / short-form text]
|
||||
**Posting cadence:** [X times per week]
|
||||
|
||||
---
|
||||
|
||||
### Pillar 2: [Name — e.g. "Practical education"]
|
||||
|
||||
**What it is:** [...]
|
||||
**Why the audience cares:** [...]
|
||||
**Content examples:**
|
||||
- [...]
|
||||
- [...]
|
||||
|
||||
**Format mix:** [...]
|
||||
**Posting cadence:** [...]
|
||||
|
||||
---
|
||||
|
||||
### Pillar 3: [Name — e.g. "Social proof and community"]
|
||||
|
||||
**What it is:** [Customer stories, testimonials, user-generated content, community spotlights]
|
||||
**Why the audience cares:** [Validation from peers carries more weight than brand claims]
|
||||
**Content examples:**
|
||||
- [Customer outcome stories — 1 metric + 1 quote format]
|
||||
- [Repost community member wins]
|
||||
- [Case study carousels]
|
||||
|
||||
**Format mix:** [...]
|
||||
**Posting cadence:** [...]
|
||||
|
||||
---
|
||||
|
||||
### Pillar 4: [Name — e.g. "Point of view"]
|
||||
|
||||
**What it is:** [Opinions on industry trends, hot takes, commentary on news in your space]
|
||||
**Why the audience cares:** [People follow accounts that say something, not just share information]
|
||||
**Content examples:**
|
||||
- [Contrarian takes on common advice]
|
||||
- [Reaction to industry news — what it means for your audience]
|
||||
- [Founder's personal perspective on a topic]
|
||||
|
||||
**Format mix:** [...]
|
||||
**Posting cadence:** [...]
|
||||
|
||||
---
|
||||
|
||||
## 4. Tone of Voice
|
||||
|
||||
Define how your brand sounds on social — before you write a single post:
|
||||
|
||||
| Dimension | [Your brand] sounds like... | [Your brand] does NOT sound like... |
|
||||
|---|---|---|
|
||||
| **Formality** | [e.g. Conversational, plain English] | [Corporate speak, jargon] |
|
||||
| **Energy** | [e.g. Curious, enthusiastic] | [Aggressive, hypey] |
|
||||
| **Personality** | [e.g. Smart friend who happens to be an expert] | [Faceless institution] |
|
||||
| **Humour** | [e.g. Dry wit, occasional] | [Try-hard memes, sarcasm] |
|
||||
| **Self-promotion** | [e.g. Earns the right to mention the product] | [Every post is an ad] |
|
||||
|
||||
**Reference accounts that nail the tone you're aiming for:** [Name 2–3 accounts — and why]
|
||||
|
||||
---
|
||||
|
||||
## 5. Posting Cadence & Workflow
|
||||
|
||||
| Platform | Posts per week | Best days | Best times | Format split |
|
||||
|---|---|---|---|---|
|
||||
| [LinkedIn] | [3–5] | [Tue–Thu] | [07:30–09:00 or 12:00–13:00] | [60% educational, 30% POV, 10% product] |
|
||||
| [X / Twitter] | [5–7] | [Any] | [Morning and lunchtime] | [50% replies/engagement, 30% original, 20% reposts] |
|
||||
| [Instagram] | [3–4] | [Mon, Wed, Fri] | [18:00–20:00] | [50% Reels, 30% carousels, 20% Stories] |
|
||||
|
||||
**Content production workflow:**
|
||||
|
||||
| Day | Activity | Owner | Time required |
|
||||
|---|---|---|---|
|
||||
| Monday | Plan the week's content — review pillars, select topics | [Social manager] | 30 min |
|
||||
| Tuesday | Write long-form posts for LinkedIn and threads | [Writer / founder] | 60 min |
|
||||
| Wednesday | Design carousels or graphics | [Designer / Canva] | 45 min |
|
||||
| Thursday | Schedule the week's content in [Buffer / Hootsuite / Later] | [Social manager] | 20 min |
|
||||
| Daily | Engage with comments, reply to mentions, interact with community | [Social manager] | 15 min |
|
||||
|
||||
---
|
||||
|
||||
## 6. Growth Tactics
|
||||
|
||||
Beyond posting, how will you grow your following and reach?
|
||||
|
||||
| Tactic | Description | Platform | Frequency |
|
||||
|---|---|---|---|
|
||||
| **Engage before you post** | Spend 15 min commenting on posts from target accounts before posting your own | All | Daily |
|
||||
| **Collaboration posts** | Co-create content with a complementary brand or creator | LinkedIn / IG | Monthly |
|
||||
| **Community participation** | Answer questions in relevant groups, subreddits, or Discord servers | LinkedIn / Reddit / Discord | Weekly |
|
||||
| **Tag relevant accounts** | When mentioning companies, tools, or people — tag them (earns reshares) | All | As relevant |
|
||||
| **Cross-promote** | Mention your social in newsletters, emails, events, and podcast appearances | All | Ongoing |
|
||||
| **Use trending formats early** | When a new format (e.g. LinkedIn carousels, IG Reels) emerges, adopt early | Platform-specific | When relevant |
|
||||
|
||||
---
|
||||
|
||||
## 7. Measurement Framework
|
||||
|
||||
**Primary KPIs (tied to business goal):**
|
||||
|
||||
| KPI | Platform | Current baseline | Target (90 days) | Why it matters |
|
||||
|---|---|---|---|---|
|
||||
| [Follower growth rate] | [LinkedIn] | [X%/month] | [≥ Y%/month] | [Audience reach] |
|
||||
| [Engagement rate] | [LinkedIn] | [X%] | [≥ Y%] | [Content resonance] |
|
||||
| [Link clicks / traffic from social] | [All] | [X visits/month] | [≥ Y visits/month] | [Direct business impact] |
|
||||
| [Inbound leads attributed to social] | [LinkedIn] | [X/month] | [≥ Y/month] | [Revenue impact] |
|
||||
|
||||
**Secondary metrics (health indicators):**
|
||||
- Reach per post
|
||||
- Saves and shares (not just likes)
|
||||
- Comment sentiment and quality
|
||||
- DMs initiated from content
|
||||
|
||||
**Reporting cadence:** [Weekly check on engagement / Monthly review of follower and traffic / Quarterly strategy review]
|
||||
|
||||
---
|
||||
|
||||
## 8. 4-Week Starter Content Calendar
|
||||
|
||||
A concrete first month of content — ready to adapt and post:
|
||||
|
||||
| Week | Day | Platform | Pillar | Format | Topic idea |
|
||||
|---|---|---|---|---|---|
|
||||
| 1 | Mon | LinkedIn | Education | Carousel | [e.g. "5 things we wished we knew before building [X]"] |
|
||||
| 1 | Wed | LinkedIn | Behind the build | Text post | [e.g. "We almost gave up in month 3. Here's what changed."] |
|
||||
| 1 | Fri | Instagram | Social proof | Reel | [e.g. Customer story — problem → solution → result] |
|
||||
| 2 | Tue | LinkedIn | POV | Thread | [e.g. "Hot take: [common advice in your space] is wrong. Here's why."] |
|
||||
| 2 | Thu | X/Twitter | Education | Thread | [e.g. "The [X] framework we use every week — and how you can steal it"] |
|
||||
| 2 | Sat | Instagram | Behind the build | Story | [e.g. "Week 2 update — what we shipped and one thing that didn't go to plan"] |
|
||||
| 3 | Mon | LinkedIn | Education | Carousel | [e.g. "How to [achieve outcome] in [timeframe] — step by step"] |
|
||||
| 3 | Wed | LinkedIn | Community | Text post | [e.g. Reshare a customer win with commentary] |
|
||||
| 3 | Fri | Instagram | POV | Reel | [e.g. "[Industry myth] — why we disagree and what we do instead"] |
|
||||
| 4 | Tue | LinkedIn | Behind the build | Video | [e.g. Founder talking to camera — "One thing I learned building [X] this month"] |
|
||||
| 4 | Thu | X/Twitter | POV | Thread | [e.g. "[Trend in your space] — here's what's actually happening"] |
|
||||
| 4 | Sat | All | Milestone | Text + image | [e.g. "[X followers / X users / X months] — thank you + what's next"] |
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Every content pillar delivers value to the audience — not just the brand
|
||||
- [ ] Platform selection is justified by where the target audience actually spends time
|
||||
- [ ] Tone of voice examples are specific enough to use as a writing guide
|
||||
- [ ] KPIs are tied to the business goal, not just vanity metrics (likes, followers in isolation)
|
||||
- [ ] Posting cadence is realistic for the available resources — sustainable beats ambitious
|
||||
- [ ] The 4-week calendar has specific topic ideas, not just "write an educational post"
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- "Build a social media strategy for [brand/product]"
|
||||
- "Create a LinkedIn content strategy for our B2B SaaS"
|
||||
- "Help me define content pillars and posting cadence for our startup"
|
||||
- "Design a 90-day social media plan for [company]"
|
||||
- "What should our social media strategy be for a product launch?"
|
||||
@@ -0,0 +1,176 @@
|
||||
---
|
||||
name: substack-notes-scraper
|
||||
description: Scrapes a Substack Notes page and exports engagement data (likes, comments, restacks) to a formatted .xlsx file with conditional formatting and summary stats.
|
||||
---
|
||||
|
||||
# Substack Notes Scraper
|
||||
|
||||
Substack has no public API for Notes analytics. You can't see likes, comments, and restacks in one place without scrolling through your feed manually. This skill scrapes the rendered Notes page, filters to only your original content, and exports everything to a spreadsheet you can actually analyze.
|
||||
|
||||
> Credit: Originally created by a Substack newsletter author — adapted and extended for this library.
|
||||
|
||||
---
|
||||
|
||||
## Required Inputs
|
||||
|
||||
| Input | Format | Example |
|
||||
|---|---|---|
|
||||
| Notes URL | Full URL to the Notes tab | `https://substack.com/@handle/notes` |
|
||||
| Author handle or name | Exact handle or display name | `@handle` or `Jane Smith` |
|
||||
| Date range | Plain English or explicit range | `last 30 days` or `Jan 2026 – Mar 2026` |
|
||||
|
||||
Claude will ask for these if not provided upfront.
|
||||
|
||||
---
|
||||
|
||||
## Output Structure
|
||||
|
||||
### File
|
||||
|
||||
```
|
||||
substack-notes-[handle]-[YYYY-MM-DD].xlsx
|
||||
```
|
||||
|
||||
### Sheet: "Notes Data"
|
||||
|
||||
| Column | Description |
|
||||
|---|---|
|
||||
| Date | Publication date (YYYY-MM-DD) |
|
||||
| Text Preview | First 200 characters of the note |
|
||||
| Full Text | Complete note text |
|
||||
| Likes | Like count at time of scrape |
|
||||
| Comments | Comment count |
|
||||
| Restacks | Restack count |
|
||||
| Total Engagement | Likes + Comments + Restacks |
|
||||
| Link | Direct URL to the note |
|
||||
| Note Type | `original` or `restack` |
|
||||
|
||||
**Formatting applied:**
|
||||
- Row 1: frozen header row
|
||||
- Auto-filter enabled on all columns
|
||||
- Top 20% by Likes column: highlighted yellow (`#FFF2CC`)
|
||||
- Column widths: auto-fit to content, min 12, max 60
|
||||
|
||||
### Sheet: "Summary"
|
||||
|
||||
```
|
||||
Scrape Date: [YYYY-MM-DD HH:MM UTC]
|
||||
Author: [handle]
|
||||
Date Range: [start] – [end]
|
||||
Total Notes: [n]
|
||||
Original Notes: [n]
|
||||
Restacks Filtered: [n]
|
||||
|
||||
Avg Likes: [n.n]
|
||||
Avg Comments: [n.n]
|
||||
Avg Restacks: [n.n]
|
||||
Avg Total Eng: [n.n]
|
||||
|
||||
Best Note (Likes): [date] — [first 80 chars] — [n] likes
|
||||
Best Note (Eng): [date] — [first 80 chars] — [n] total engagement
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Instructions for Claude
|
||||
|
||||
### Step 1: Validate inputs
|
||||
|
||||
Confirm the three required inputs are present. If any are missing, ask before proceeding. Parse the date range into a concrete start date and end date (convert relative ranges like "last 30 days" to explicit dates using today's date).
|
||||
|
||||
### Step 2: Fetch the Notes page
|
||||
|
||||
Use `WebFetch` to load the Notes URL. Substack Notes pages are JavaScript-rendered — request the full rendered HTML. If WebFetch returns a skeleton page without note content, note this in your response and ask the user to paste the page HTML manually or confirm browser access is available.
|
||||
|
||||
### Step 3: Paginate through all notes in the date window
|
||||
|
||||
Substack Notes load incrementally. Repeat fetching or scrolling until either:
|
||||
- A note's date falls outside the target date range (stop loading more), or
|
||||
- No new content loads on the next request.
|
||||
|
||||
Rate-limit: wait 2 seconds between each paginated request. Do not hammer the endpoint.
|
||||
|
||||
### Step 4: Parse each note
|
||||
|
||||
For every note element found on the page, extract:
|
||||
- **Date**: the timestamp on the note (convert to YYYY-MM-DD)
|
||||
- **Author**: the display name or handle shown on the note
|
||||
- **Full text**: complete body text, stripping HTML tags
|
||||
- **Text preview**: first 200 characters of full text
|
||||
- **Likes count**: the number shown on the like/heart counter
|
||||
- **Comments count**: the number shown on the comment counter
|
||||
- **Restacks count**: the number shown on the restack counter
|
||||
- **Link**: the direct permalink to the note
|
||||
- **Note type**: `original` if the author matches the specified author; `restack` if it belongs to someone else
|
||||
|
||||
### Step 5: Filter
|
||||
|
||||
Keep ALL rows in the data (restacks included as rows with `Note Type = restack`). The Summary sheet stats should count only `original` notes. Mark restacks clearly so the user can filter them out themselves in Excel if preferred.
|
||||
|
||||
Apply date filter: exclude any note outside the specified date range.
|
||||
|
||||
### Step 6: Calculate Total Engagement
|
||||
|
||||
For each row: `Total Engagement = Likes + Comments + Restacks`
|
||||
|
||||
### Step 7: Identify top 20% by Likes
|
||||
|
||||
Sort original notes by Likes descending. Mark the top 20% (round up) for conditional formatting. These rows will be highlighted yellow in the output file.
|
||||
|
||||
### Step 8: Build the .xlsx file
|
||||
|
||||
Use Python with `openpyxl` to generate the file. Structure:
|
||||
|
||||
```python
|
||||
# Required libraries
|
||||
import openpyxl
|
||||
from openpyxl.styles import PatternFill, Font, Alignment
|
||||
from openpyxl.utils import get_column_letter
|
||||
from datetime import datetime
|
||||
|
||||
# Sheet 1: Notes Data
|
||||
# - Write header row, bold, freeze row 1
|
||||
# - Write all data rows
|
||||
# - Apply auto-filter: ws.auto_filter.ref = ws.dimensions
|
||||
# - Apply yellow fill to top-20% rows by likes
|
||||
# - Auto-size columns (iterate cells to find max length)
|
||||
|
||||
# Sheet 2: Summary
|
||||
# - Write summary stats as key-value pairs, no table format
|
||||
```
|
||||
|
||||
Name the file `substack-notes-[handle]-[YYYY-MM-DD].xlsx` using today's date.
|
||||
|
||||
### Step 9: Report back
|
||||
|
||||
After generating the file, report:
|
||||
- File path
|
||||
- Total notes found, original vs. restacks
|
||||
- Date range actually covered
|
||||
- Top 3 notes by total engagement (date + preview + stats)
|
||||
- Any notes or warnings (e.g., page didn't fully load, some dates were ambiguous)
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] All three required inputs were confirmed before starting
|
||||
- [ ] Rate limiting honored: 2-second delay between paginated requests
|
||||
- [ ] Author filter applied correctly — restacks are included as rows but flagged, not silently dropped
|
||||
- [ ] Date range filter applied — no notes outside the window appear in the data
|
||||
- [ ] Total Engagement column is Likes + Comments + Restacks (not hardcoded)
|
||||
- [ ] Top 20% highlight is based on the actual data distribution, not a fixed threshold
|
||||
- [ ] Header row is frozen and auto-filter is active
|
||||
- [ ] Summary sheet stats reference only `original` notes, not restacks
|
||||
- [ ] File is named with the author handle and today's date
|
||||
- [ ] If the page failed to load properly, the user was told — not silently given an empty file
|
||||
|
||||
---
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- "Scrape my Substack Notes and export to Excel — my handle is @handle, last 60 days"
|
||||
- "Use the substack-notes-scraper skill on https://substack.com/@handle/notes for Q1 2026"
|
||||
- "Pull my notes engagement data into a spreadsheet"
|
||||
- "Export my Substack Notes stats with likes and restacks — author: Jane Smith, Jan–Mar 2026"
|
||||
- "Run the Substack scraper on my notes page and show me which posts performed best"
|
||||
@@ -0,0 +1,156 @@
|
||||
---
|
||||
name: sycophancy-challenger
|
||||
description: Flips Claude's default from "find reasons you're right" to "find reasons you're wrong." A genuine thinking partner, not a mirror with grammar. Use before high-stakes decisions, plans, assumptions, or pitches you haven't stress-tested.
|
||||
---
|
||||
|
||||
# Sycophancy Challenger
|
||||
|
||||
Claude defaults to validating. You bring a decision, it finds three reasons your instinct is solid, and you leave more confident but not more right. That's actively dangerous when the stakes are high — a hiring call, a pricing change, a strategy pivot, a public commitment. This skill flips the default: Claude argues against your idea first, holds its position under pushback, and only concedes when you give it new evidence. Not when you express displeasure.
|
||||
|
||||
> Credit: Originally created by Joel Salinas (Leadership in Change) — adapted and extended for this library.
|
||||
|
||||
---
|
||||
|
||||
## Required Inputs
|
||||
|
||||
| Input | Format | Notes |
|
||||
|---|---|---|
|
||||
| Your idea, decision, plan, or assumption | Describe it in plain language | More context = sharper challenge. Include reasoning if you have it. |
|
||||
|
||||
No other setup required. Activating the skill is enough — describe your idea and Claude will challenge it immediately.
|
||||
|
||||
---
|
||||
|
||||
## Output Structure
|
||||
|
||||
Every response in this mode follows this exact format:
|
||||
|
||||
```
|
||||
## Strongest Case AGAINST This
|
||||
|
||||
[The single most damaging criticism of the idea. Not a list of concerns — the
|
||||
one argument that, if true, would kill this. Stated directly, without softening.]
|
||||
|
||||
|
||||
## The Weakest Element
|
||||
|
||||
[The specific part of the idea most likely to fail, be wrong, or break under
|
||||
real-world conditions. Named precisely. Not "execution risk" — the actual thing.]
|
||||
|
||||
|
||||
## What You'd Need to Prove to Make This Work
|
||||
|
||||
[The assumptions that must be true for this idea to succeed. Written as testable
|
||||
claims, not as encouragement. If an assumption can't be tested, that's noted.]
|
||||
|
||||
|
||||
## What I Can't Find Fault With
|
||||
|
||||
[Only appears when a genuine search finds nothing damaging. States clearly what
|
||||
holds up and why — doesn't invent weak praise to fill the section. If everything
|
||||
is actually fine, says so plainly and explains why the challenge came up short.]
|
||||
```
|
||||
|
||||
No additional sections. No summary. No "overall, this is a solid idea." The format ends when the four sections are complete.
|
||||
|
||||
---
|
||||
|
||||
## Instructions for Claude
|
||||
|
||||
### On activation
|
||||
|
||||
Do not open with agreement, validation, or any form of "I see where you're coming from." Begin the challenge immediately. The first word of your response should advance the criticism, not soften the user's expectations.
|
||||
|
||||
### Step 1: Assume the idea hasn't been stress-tested
|
||||
|
||||
Treat the idea as if the user believes in it strongly and has not actively looked for reasons it fails. Your job is to be the adversary they didn't have in the room.
|
||||
|
||||
### Step 2: Find the strongest case against it
|
||||
|
||||
Not a balanced view. Not pros and cons. The strongest case against. Ask:
|
||||
- What's the most likely way this fails?
|
||||
- What's the assumption that, if wrong, makes everything else irrelevant?
|
||||
- Who would argue against this, and what's the best version of their argument?
|
||||
- What does this idea get wrong about how people, markets, or systems actually behave?
|
||||
|
||||
State the strongest case directly. Do not list multiple criticisms in this section — lead with the one that does the most damage.
|
||||
|
||||
### Step 3: Identify the weakest element
|
||||
|
||||
This is different from the strongest case against. The weakest element is the most fragile specific component — the thing most likely to crack under execution, scrutiny, or changed conditions. Name it precisely. Examples of insufficient answers:
|
||||
- "The timeline might be tight" → insufficient
|
||||
- "The assumption that customers will pay $99/month before experiencing the product is the element most likely to break this, because you have no evidence of willingness-to-pay at that price point" → correct level of specificity
|
||||
|
||||
### Step 4: Surface the required assumptions
|
||||
|
||||
List what must be true for this to work. Write each assumption as a testable claim:
|
||||
|
||||
```
|
||||
For this to work, the following must be true:
|
||||
1. [Assumption stated as a claim that can be verified or falsified]
|
||||
2. [Assumption stated as a claim]
|
||||
3. [Assumption stated as a claim]
|
||||
```
|
||||
|
||||
If an assumption cannot be tested — it's based on hope, belief, or unprovable prediction — flag it explicitly: "This assumption cannot currently be tested. That's a risk."
|
||||
|
||||
### Step 5: Report what holds up (only if true)
|
||||
|
||||
Search genuinely for what the idea gets right or where the challenge fails. If you find it, state it clearly. If you can't find a real flaw, say exactly that: "I've looked for the failure points and I can't find them. Here's what actually holds up: [specific things]." Do not invent praise. Do not invent flaws either.
|
||||
|
||||
### Handling pushback
|
||||
|
||||
If the user pushes back:
|
||||
- **New evidence or new information:** update your position based on the evidence. State what changed and why.
|
||||
- **Emotional pushback, repetition, or displeasure:** do not move. Restate the criticism calmly. Example: "I understand you feel strongly about this — I'm not backing off the point about X because that hasn't changed. If there's something I'm missing, tell me what it is."
|
||||
- **A clarification that changes the picture:** acknowledge the clarification, adjust if warranted, and explain exactly what the clarification changed.
|
||||
|
||||
Do not soften a position because the user seems upset. Do not move back to validation mode mid-conversation.
|
||||
|
||||
### When the skill ends
|
||||
|
||||
The session is complete when the user has either:
|
||||
1. Strengthened their idea by addressing the core criticism with real evidence or a genuine plan adjustment, or
|
||||
2. Identified a real flaw they're going to fix.
|
||||
|
||||
Not when they've expressed satisfaction. Not when a certain number of exchanges have happened. The measure is whether something actually changed or was genuinely defended.
|
||||
|
||||
### Prohibitions
|
||||
|
||||
These prohibitions do more work than the rules above. Follow them absolutely:
|
||||
|
||||
- **Never open with agreement or validation.** Not "That's an interesting approach," not "I can see why you'd think that." Start with the challenge.
|
||||
- **Never say "great question," "great point," or "I see where you're coming from" as a lead.** These are validation openers, not neutral transitions.
|
||||
- **Never soften a criticism with "however, there are also positives."** If the positives are real, they go in the "What I Can't Find Fault With" section, not as a counterweight to every criticism.
|
||||
- **Never back down because the user expressed displeasure.** Only move if given new evidence.
|
||||
- **Never invent a flaw that isn't real.** If the idea is actually solid, say so. Inventing fake criticisms is as useless as fake validation.
|
||||
- **Never use the word "valid" to describe the user's perspective mid-challenge.** It's a validation signal disguised as a neutral word.
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Response opened with the challenge — not with a softening phrase or acknowledgment
|
||||
- [ ] "Strongest Case Against" section contains one argument, not a list
|
||||
- [ ] "Weakest Element" is specific — names the actual component, not a category of risk
|
||||
- [ ] "What You'd Need to Prove" lists testable assumptions, not encouragement
|
||||
- [ ] Untestable assumptions are explicitly flagged as risks
|
||||
- [ ] "What I Can't Find Fault With" only appears if the search was genuine and something held up
|
||||
- [ ] No invented flaws — every criticism connects to something real in what the user described
|
||||
- [ ] Pushback was met with a position restatement, not a retreat (unless new evidence was provided)
|
||||
- [ ] The session ended because something changed or was genuinely defended — not because the user seemed satisfied
|
||||
- [ ] None of the prohibited phrases or patterns appear anywhere in the response
|
||||
|
||||
---
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- "Use the sycophancy-challenger skill — here's my plan: [describe it]"
|
||||
- "Challenge this idea before I commit to it: [describe it]"
|
||||
- "I've already decided to do X — tell me why I'm wrong"
|
||||
- "Be the devil's advocate on this hire: [describe the candidate and the role]"
|
||||
- "I'm about to pitch this to investors — tear it apart first: [describe it]"
|
||||
- "Don't validate this, challenge it: [idea or assumption]"
|
||||
- "Stress-test this strategy: [describe it]"
|
||||
- "What's the strongest argument against doing this: [decision]"
|
||||
- "I think I'm right about X — what am I missing?"
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: system-design-interview
|
||||
description: "Structure a complete system design answer for interview questions or real architecture sessions. Use when asked to design a system, answer a system design interview question, or architect a solution at scale. Produces a structured answer covering requirements, capacity estimates, high-level design, component deep-dives, trade-offs, and follow-up considerations. Optimised for Opus 4.7 and newer models."
|
||||
description: "Structure a complete system design answer for interview questions or real architecture sessions. Use when asked to design a system, answer a system design interview question, or architect a solution at scale. Produces a structured answer covering requirements, capacity estimates, high-level design, component deep-dives, trade-offs, and follow-up considerations."
|
||||
---
|
||||
|
||||
# System Design Interview Skill
|
||||
@@ -14,8 +14,10 @@ Ask for these if not provided:
|
||||
- **Scope** (interview prep / real architecture decision / practice run)
|
||||
- **Scale target** (rough numbers: DAU, requests/sec, data volume — or "assume typical web scale")
|
||||
- **Constraints or priorities** (e.g. prioritise availability over consistency, minimise cost, low-latency reads)
|
||||
- **Time available** (interview context only: 30 / 45 / 60 minutes — skip for real architecture sessions)
|
||||
- **Emphasis** (optional — any area to go deeper on, e.g. "focus on the DB design" or "spend more time on scaling")
|
||||
|
||||
## Output Structure
|
||||
## Output Format
|
||||
|
||||
### 1. Clarifying Questions
|
||||
Before designing, list 4–6 questions that would change the design. Examples:
|
||||
@@ -62,12 +64,7 @@ Then proceed with stated assumptions if answering an interview question.
|
||||
|
||||
### 5. High-Level Architecture
|
||||
|
||||
```
|
||||
[Client] → [CDN/Edge] → [Load Balancer] → [API Servers] → [Cache] → [DB]
|
||||
→ [Message Queue] → [Workers]
|
||||
```
|
||||
|
||||
Describe each layer in 1–2 sentences explaining its role and technology choice.
|
||||
Draw an ASCII diagram specific to this system. Do not default to the client→CDN→LB→API→Cache→DB template unless it genuinely applies. Label each component with the specific technology chosen (e.g. "Kafka" not "Message Queue", "PostgreSQL" not "DB"). Describe each component in 1–2 sentences explaining its role and why that technology was chosen.
|
||||
|
||||
### 6. Component Deep-Dive
|
||||
|
||||
@@ -122,12 +119,13 @@ Things to tackle in production but out of scope for this design session:
|
||||
|
||||
## Quality Checks
|
||||
- [ ] Clarifying questions are design-changing (not generic filler)
|
||||
- [ ] Capacity estimates use real numbers (not just "it scales")
|
||||
- [ ] Capacity estimates show the arithmetic: DAU → requests/day → requests/sec → storage per record → total storage, so the numbers can be sanity-checked
|
||||
- [ ] Every row in the Trade-offs table has a non-empty Trade-off column (no rows where the trade-off is blank or says "none")
|
||||
- [ ] At least 2 component deep-dives with technology choices justified
|
||||
- [ ] Trade-offs section is honest (not just benefits of chosen approach)
|
||||
- [ ] Data flow is described end-to-end for the critical path
|
||||
|
||||
## Example Trigger Phrases
|
||||
## Usage Examples
|
||||
- "Help me answer a system design interview: [question]"
|
||||
- "Design [system] for a system design interview"
|
||||
- "How would I architect [system] at scale?"
|
||||
|
||||
@@ -0,0 +1,262 @@
|
||||
---
|
||||
name: team-health-check
|
||||
description: "Run a structured team health assessment. Use when asked to run a team health check, assess team morale, facilitate a team retrospective on ways of working, or evaluate team dynamics. Produces a health assessment across key dimensions with RAG status, underlying signals, and prioritised improvement actions."
|
||||
---
|
||||
|
||||
# Team Health Check Skill
|
||||
|
||||
This skill produces a structured team health assessment inspired by Spotify's health check model and extended with engineering, product, and cross-functional team dimensions. Output can be used as a facilitation guide for a live session or as an async survey-and-report format.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask the user for these if not provided:
|
||||
- **Team name and function** (engineering squad, product team, sales pod, etc.)
|
||||
- **Team size and composition** (how many people, what roles)
|
||||
- **Format** — facilitated live session or async survey + report?
|
||||
- **Context** — why are you running this now? (new team / ongoing ritual / post-incident / low morale signal)
|
||||
- **Any known issues** — anything the facilitator knows going in that will colour the results?
|
||||
|
||||
## Output Structure
|
||||
|
||||
---
|
||||
|
||||
# Team Health Check: [Team Name]
|
||||
|
||||
**Date:** [Date]
|
||||
**Facilitated by:** [Name or role]
|
||||
**Team size:** [X people]
|
||||
**Format:** [Live session (60 min) / Async survey + report]
|
||||
**Cycle:** [One-off / Quarterly / Monthly]
|
||||
|
||||
---
|
||||
|
||||
## Part 1: Facilitation Guide (Live Session)
|
||||
|
||||
Use this guide to run the session in 60 minutes.
|
||||
|
||||
### Session structure
|
||||
|
||||
| Time | Activity | Owner |
|
||||
|---|---|---|
|
||||
| 0–5 min | Framing and ground rules | Facilitator |
|
||||
| 5–40 min | Card voting — 7 dimensions, 5 min each | Full team |
|
||||
| 40–50 min | Top 3 themes discussion | Full team |
|
||||
| 50–58 min | Actions and owners | Team lead |
|
||||
| 58–60 min | Close and next date | Facilitator |
|
||||
|
||||
### Ground rules (read at start)
|
||||
|
||||
- This is not a performance review — there are no wrong answers
|
||||
- We're assessing the team, not individuals — speak about "we" not "they"
|
||||
- What's said here stays here — results shared as aggregated themes, not attributed to individuals
|
||||
- The goal is one or two actionable improvements, not a long list
|
||||
|
||||
### Voting mechanic
|
||||
|
||||
For each dimension, each team member votes with one of three cards:
|
||||
- 🟢 **Green** — working well, we're proud of this
|
||||
- 🟡 **Amber** — some things work, but there are issues worth discussing
|
||||
- 🔴 **Red** — we have a real problem here that's slowing us down
|
||||
|
||||
After voting, the team discusses: what drove the votes? What would make this Green?
|
||||
|
||||
---
|
||||
|
||||
## Part 2: Health Dimensions
|
||||
|
||||
---
|
||||
|
||||
### Dimension 1: Delivering Value
|
||||
|
||||
*Are we shipping things that matter, at the pace we should?*
|
||||
|
||||
| Indicator | Probes for discussion |
|
||||
|---|---|
|
||||
| We ship work that creates real value for our users | How do we know our output is valuable? When did we last talk to a user? |
|
||||
| Our pace of delivery feels healthy and sustainable | Are we consistently shipping? Or do we have long dry spells? |
|
||||
| We have clarity on what "done" looks like | Do we have a shared definition of ready and done? |
|
||||
| We celebrate shipping, not just building | Do we acknowledge completed work, or does it just disappear into the backlog? |
|
||||
|
||||
**Current vote:** 🟢 / 🟡 / 🔴
|
||||
|
||||
**Key themes from discussion:**
|
||||
|
||||
**What would make this Green?**
|
||||
|
||||
---
|
||||
|
||||
### Dimension 2: Easy to Release
|
||||
|
||||
*Is releasing software (or our work) smooth and low-risk?*
|
||||
|
||||
| Indicator | Probes for discussion |
|
||||
|---|---|
|
||||
| We can release whenever we choose, without anxiety | What does a release feel like? Smooth or stressful? |
|
||||
| Our deployment process is automated and reliable | How much manual work does a release involve? |
|
||||
| We have confidence in our test coverage | Do we catch bugs before users do? |
|
||||
| Rollback is fast and rehearsed | Have we ever rolled back? How long did it take? |
|
||||
|
||||
**Current vote:** 🟢 / 🟡 / 🔴
|
||||
|
||||
**Key themes from discussion:**
|
||||
|
||||
**What would make this Green?**
|
||||
|
||||
---
|
||||
|
||||
### Dimension 3: Fun & Morale
|
||||
|
||||
*Do people enjoy working here and with each other?*
|
||||
|
||||
| Indicator | Probes for discussion |
|
||||
|---|---|
|
||||
| People generally enjoy coming to work | If you had to describe the team energy in one word, what would it be? |
|
||||
| We celebrate successes as a team | When did we last properly celebrate something? |
|
||||
| Interpersonal dynamics are healthy — no drama or cliques | Are there any relationships that are strained or avoided? |
|
||||
| We laugh and have non-work conversations | Do we know each other as people, not just colleagues? |
|
||||
|
||||
**Current vote:** 🟢 / 🟡 / 🔴
|
||||
|
||||
**Key themes from discussion:**
|
||||
|
||||
**What would make this Green?**
|
||||
|
||||
---
|
||||
|
||||
### Dimension 4: Psychological Safety
|
||||
|
||||
*Can people speak up, take risks, and make mistakes without fear?*
|
||||
|
||||
| Indicator | Probes for discussion |
|
||||
|---|---|
|
||||
| People raise concerns without worrying about the consequences | When did someone last raise a concern publicly? What happened? |
|
||||
| Mistakes are treated as learning opportunities, not blame events | Think of the last mistake on the team. How was it handled? |
|
||||
| People challenge each other's ideas in a constructive way | Do we have real debates, or do we agree in the room and disagree in the corridor? |
|
||||
| Everyone's voice feels equally heard regardless of seniority | Do the same people always speak first and longest? |
|
||||
|
||||
**Current vote:** 🟢 / 🟡 / 🔴
|
||||
|
||||
**Key themes from discussion:**
|
||||
|
||||
**What would make this Green?**
|
||||
|
||||
---
|
||||
|
||||
### Dimension 5: Speed & Feedback Loops
|
||||
|
||||
*Do we learn fast and adjust quickly?*
|
||||
|
||||
| Indicator | Probes for discussion |
|
||||
|---|---|
|
||||
| We get feedback on our work quickly (from users, data, tests) | How long after shipping do we know if something worked? |
|
||||
| Our planning and retrospective cycles help us improve | Do retros lead to real change, or do the same issues come back? |
|
||||
| We cut work that isn't working, even when it's hard | Can you name something we've stopped doing because it wasn't working? |
|
||||
| Our meetings and processes don't slow us down | Which meetings do people dread? Which do they find valuable? |
|
||||
|
||||
**Current vote:** 🟢 / 🟡 / 🔴
|
||||
|
||||
**Key themes from discussion:**
|
||||
|
||||
**What would make this Green?**
|
||||
|
||||
---
|
||||
|
||||
### Dimension 6: Mission & Purpose
|
||||
|
||||
*Do we understand why our work matters?*
|
||||
|
||||
| Indicator | Probes for discussion |
|
||||
|---|---|
|
||||
| Everyone on the team can articulate why their work matters | Could each person on this team explain to a stranger why their work is important? |
|
||||
| The team's goals are clear and shared | Can everyone name the team's top 3 priorities right now? |
|
||||
| Our work connects to the wider company direction | Do we understand how we fit into the bigger picture? |
|
||||
| We're proud of what this team builds | If you described your team's work to someone you respect, would you feel good about it? |
|
||||
|
||||
**Current vote:** 🟢 / 🟡 / 🔴
|
||||
|
||||
**Key themes from discussion:**
|
||||
|
||||
**What would make this Green?**
|
||||
|
||||
---
|
||||
|
||||
### Dimension 7: Collaboration & Support
|
||||
|
||||
*Do we work well together and support each other?*
|
||||
|
||||
| Indicator | Probes for discussion |
|
||||
|---|---|
|
||||
| People actively help each other when someone is stuck | Think of the last time someone was blocked — what happened? |
|
||||
| Knowledge is shared openly — no information silos | Is there any knowledge that only one person holds? What's the risk? |
|
||||
| Cross-team collaboration is smooth and low-friction | Which team is hardest to collaborate with and why? |
|
||||
| People feel supported when they're struggling | Is there psychological safety to say "I'm struggling with this"? |
|
||||
|
||||
**Current vote:** 🟢 / 🟡 / 🔴
|
||||
|
||||
**Key themes from discussion:**
|
||||
|
||||
**What would make this Green?**
|
||||
|
||||
---
|
||||
|
||||
## Part 3: Health Summary & Report
|
||||
|
||||
Use this template to document results after the session or survey.
|
||||
|
||||
---
|
||||
|
||||
### RAG Summary Dashboard
|
||||
|
||||
| Dimension | Score | Status | Trend vs last quarter |
|
||||
|---|---|---|---|
|
||||
| Delivering Value | [X/5] | 🟢 / 🟡 / 🔴 | [↑ / → / ↓] |
|
||||
| Easy to Release | [X/5] | 🟢 / 🟡 / 🔴 | [...] |
|
||||
| Fun & Morale | [X/5] | 🟢 / 🟡 / 🔴 | [...] |
|
||||
| Psychological Safety | [X/5] | 🟢 / 🟡 / 🔴 | [...] |
|
||||
| Speed & Feedback Loops | [X/5] | 🟢 / 🟡 / 🔴 | [...] |
|
||||
| Mission & Purpose | [X/5] | 🟢 / 🟡 / 🔴 | [...] |
|
||||
| Collaboration & Support | [X/5] | 🟢 / 🟡 / 🔴 | [...] |
|
||||
| **Overall** | **[X/5]** | 🟢 / 🟡 / 🔴 | [↑ / → / ↓] |
|
||||
|
||||
---
|
||||
|
||||
### Top Themes
|
||||
|
||||
**What's working well (keep doing):**
|
||||
1. [...]
|
||||
2. [...]
|
||||
|
||||
**What needs attention (most important to fix):**
|
||||
1. [Most pressing issue — specific, with evidence from the session]
|
||||
2. [Second issue]
|
||||
3. [Third issue — if applicable]
|
||||
|
||||
---
|
||||
|
||||
### Action Plan
|
||||
|
||||
| Action | Owner | Due date | Success indicator |
|
||||
|---|---|---|---|
|
||||
| [Specific action — e.g. Introduce pairing Fridays for knowledge sharing] | [Team lead / individual] | [Date] | [How will we know it worked?] |
|
||||
| [...] | [...] | [...] | [...] |
|
||||
|
||||
**Next health check:** [Date — recommended 6–8 weeks for teams with active improvement actions, 13 weeks for steady-state teams]
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Session ground rules established psychological safety before voting started
|
||||
- [ ] Each dimension had open discussion, not just a vote
|
||||
- [ ] Actions are specific enough to be verifiably done — no vague commitments like "improve communication"
|
||||
- [ ] Each action has a single owner — not "the team"
|
||||
- [ ] Results are shared with the team, not kept by management
|
||||
- [ ] Trend data is tracked across cycles to show improvement or regression
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- "Run a team health check for my engineering squad"
|
||||
- "Facilitate a team health assessment — we've had some morale issues"
|
||||
- "Build a team health check survey for my product team"
|
||||
- "Generate a Spotify-style health check for our cross-functional pod"
|
||||
- "Create a quarterly team health check template"
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: test-strategy-doc
|
||||
description: "Write a test strategy document from a feature spec, PRD, or system description. Use when asked to create a test plan, write a test strategy, define QA approach, or plan testing for a feature or release. Produces a complete test strategy with scope, risk assessment, test types, coverage targets, and a prioritised test case outline. Optimised for Opus 4.7 and newer models."
|
||||
description: "Write a test strategy document from a feature spec, PRD, or system description. Use when asked to create a test plan, write a test strategy, define QA approach, or plan testing for a feature or release. Produces a complete test strategy with scope, risk assessment, test types, coverage targets, and a prioritised test case outline."
|
||||
---
|
||||
|
||||
# Test Strategy Document Skill
|
||||
@@ -11,12 +11,14 @@ Produces a complete test strategy from a feature spec, PRD, or system descriptio
|
||||
|
||||
Ask for these if not provided:
|
||||
- **Feature or system being tested** (paste a spec, PRD, or describe it in plain English)
|
||||
- **Tech stack** (language, framework, testing tools already in use if known)
|
||||
- **Tech stack** (language and framework — e.g. TypeScript + React, Python + FastAPI)
|
||||
- **Existing test coverage** (e.g. "we have unit tests but no E2E tests", "we use Jest + Playwright already", or "starting from scratch")
|
||||
- **Deployment cadence** (e.g. continuous deployment / weekly releases / quarterly — affects what must be automated vs. manual)
|
||||
- **Risk level** (low / medium / high / critical — affects depth and coverage requirements)
|
||||
- **Timeline** (when does this need to ship — affects prioritisation)
|
||||
- **Team context** (who is doing the testing — developers / dedicated QA / both)
|
||||
|
||||
## Output Structure
|
||||
## Output Format
|
||||
|
||||
### 1. Test Scope
|
||||
|
||||
@@ -66,7 +68,7 @@ Identify the highest-risk areas first — these drive depth and coverage:
|
||||
- **Tools:** [e.g. Playwright, Cypress, Selenium]
|
||||
- **Focus areas:** [The 3–5 most critical user flows]
|
||||
|
||||
**Performance Tests** *(include only if risk is medium+)*
|
||||
**Performance Tests** *(include if any row in the Risk Assessment table has performance as a risk factor, regardless of overall risk level)*
|
||||
- **What:** Load, stress, or latency testing
|
||||
- **Targets:** [Specific numbers — e.g. 200 req/sec at p95 < 200ms]
|
||||
- **Tools:** [e.g. k6, Locust, JMeter]
|
||||
@@ -115,11 +117,12 @@ Testing is complete when:
|
||||
|
||||
## Quality Checks
|
||||
- [ ] Risk table is populated and drives test priority (not filled in generically)
|
||||
- [ ] P0 test cases cover the highest-risk paths specifically
|
||||
- [ ] Every "P0 — exhaustive" row in the Risk Assessment table has at least one corresponding P0 test case
|
||||
- [ ] "Out of scope" section names at least one explicit exclusion (not left blank)
|
||||
- [ ] Each test type names a concrete tool (not "some testing framework")
|
||||
- [ ] Definition of Done is measurable (not "tests are done when QA is happy")
|
||||
|
||||
## Example Trigger Phrases
|
||||
## Usage Examples
|
||||
- "Write a test strategy for [feature]" + [paste spec or PRD]
|
||||
- "Create a test plan for [system]"
|
||||
- "How should we test [feature]?"
|
||||
|
||||
@@ -0,0 +1,625 @@
|
||||
---
|
||||
name: thumbnail-creator
|
||||
description: "Generate article or newsletter thumbnail candidates using the Gemini API from inside Claude Code. Claude reads article copy, proposes composition concepts, writes image generation prompts incorporating brand specs, calls Gemini to generate the images, evaluates the results via computer vision, and returns ranked candidates with rationale. Use when asked to create thumbnails, generate cover images, or produce visual candidates for an article or newsletter."
|
||||
---
|
||||
|
||||
# Thumbnail Creator Skill (via Gemini)
|
||||
|
||||
Generates article and newsletter thumbnail candidates by acting as an image-generation agent inside Claude Code. Instead of switching between tools and prompting Gemini's web UI one image at a time, this skill makes Claude do the full loop: read the copy, propose compositions, write tailored prompts, call the Gemini API, evaluate the outputs, and return ranked results with brief rationale.
|
||||
|
||||
The output is production-ready thumbnail candidates you can drop directly into your CMS, newsletter tool, or social scheduler.
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Both of these must be in place before the skill can generate images:
|
||||
|
||||
### 1. Gemini API Key
|
||||
|
||||
Get a free key from [Google AI Studio](https://aistudio.google.com/app/apikey).
|
||||
|
||||
Set it as an environment variable:
|
||||
|
||||
```bash
|
||||
export GEMINI_API_KEY="your-key-here"
|
||||
```
|
||||
|
||||
To persist it across sessions, add to your shell profile (`~/.zshrc` or `~/.bashrc`):
|
||||
|
||||
```bash
|
||||
echo 'export GEMINI_API_KEY="your-key-here"' >> ~/.zshrc
|
||||
source ~/.zshrc
|
||||
```
|
||||
|
||||
Verify it is set:
|
||||
|
||||
```bash
|
||||
echo $GEMINI_API_KEY
|
||||
```
|
||||
|
||||
### 2. generate_image.py Script
|
||||
|
||||
This script must exist at `./generate_image.py` in the project root. The full template is provided in the Script Template section below. Claude will check for it and offer to create it if missing.
|
||||
|
||||
**Python dependencies:**
|
||||
|
||||
```bash
|
||||
pip install google-generativeai Pillow requests
|
||||
```
|
||||
|
||||
Or with uv:
|
||||
|
||||
```bash
|
||||
uv pip install google-generativeai Pillow requests
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Claude will ask for these if not provided:
|
||||
|
||||
| Input | Required | Notes |
|
||||
|---|---|---|
|
||||
| Article copy or URL | Yes | Paste the full article text, or provide a URL to fetch. Used to extract themes, hooks, and key claims for composition. |
|
||||
| Brand colours | Recommended | Hex codes or descriptive names. E.g. `#1A1A2E` (navy), `#E94560` (coral). If not provided, Claude uses clean neutral defaults. |
|
||||
| Fonts / type style | Recommended | E.g. "bold sans-serif", "editorial serif", "Neue Haas Grotesk". Used in prompt to guide text treatment. |
|
||||
| Style reference description | Recommended | E.g. "flat illustration, minimal, like Stripe's marketing site" or "photorealistic, dark background, high contrast". A style image URL can also be provided. |
|
||||
| Output dimensions | No | Defaults to `1792x1024` (landscape, standard article thumbnail). Options: `1024x1024` (square), `1024x1792` (portrait/mobile). |
|
||||
| Number of candidates | No | Defaults to 4. Min 1, max 8 (API limits and cost). |
|
||||
| Article title (if different from H1) | No | Used as the primary text element in image prompts. |
|
||||
| Candidate selection | No | After proposing compositions, Claude asks which to generate. User can say "all" or pick by number. |
|
||||
|
||||
---
|
||||
|
||||
## Output Structure
|
||||
|
||||
### Phase 1 — Composition Proposals (text, before any API calls)
|
||||
|
||||
Claude presents 3-4 composition concepts for user approval. Format:
|
||||
|
||||
```
|
||||
Composition Concepts for: "[Article Title]"
|
||||
|
||||
1. BOLD CLAIM
|
||||
Layout: Full-bleed dark background, large white headline centred,
|
||||
single accent data point (e.g. "3x faster") in brand colour below
|
||||
Mood: High authority, newsletter-style
|
||||
Best for: LinkedIn, Substack headers
|
||||
Rationale: The article's central claim ("X outperforms Y by 3x") is specific
|
||||
enough to anchor the visual — readers stop on data.
|
||||
|
||||
2. CONCEPTUAL OBJECT
|
||||
Layout: Central object illustration (e.g. a broken clock for a time-waste article),
|
||||
title in upper third, minimal texture background
|
||||
Mood: Editorial, Medium-style
|
||||
Best for: Blog header, Medium cover, email preheader
|
||||
Rationale: Gives art directors visual metaphor flexibility; works across sizes.
|
||||
|
||||
3. CONTRAST SPLIT
|
||||
Layout: Left half brand colour, right half white or image,
|
||||
title on colour side, supporting subtext on white side
|
||||
Mood: Clean, professional, startup-brand feel
|
||||
Best for: Newsletter, LinkedIn carousel first slide
|
||||
Rationale: Split layout performs consistently in newsletter A/B tests;
|
||||
text is readable at small sizes.
|
||||
|
||||
4. TYPOGRAPHIC ONLY
|
||||
Layout: No illustration, oversized title treatment,
|
||||
author name in small caps at bottom, thin rule separator
|
||||
Mood: Premium, confident, editorial
|
||||
Best for: Substack, Ghost, high-density email lists
|
||||
Rationale: Works when the brand has strong type identity. Fastest to produce.
|
||||
|
||||
Which compositions do you want generated? (Reply with numbers, e.g. "1, 3" or "all")
|
||||
```
|
||||
|
||||
### Phase 2 — Generated Image Files
|
||||
|
||||
After generation, Claude saves files to `./thumbnails/[article-slug]/`:
|
||||
|
||||
```
|
||||
thumbnails/
|
||||
└── article-slug-from-title/
|
||||
├── candidate_01_bold_claim.png
|
||||
├── candidate_02_conceptual_object.png
|
||||
├── candidate_03_contrast_split.png
|
||||
├── candidate_04_typographic.png
|
||||
└── evaluation_report.md
|
||||
```
|
||||
|
||||
### Phase 3 — Evaluation Summary Table
|
||||
|
||||
Claude evaluates each returned image via computer vision and produces:
|
||||
|
||||
```
|
||||
Thumbnail Evaluation — "[Article Title]"
|
||||
Generated: 2026-05-27 | Model: Gemini Imagen | Dimensions: 1792x1024
|
||||
|
||||
| # | Candidate | Composition | Brand Fit /10 | Text Legibility /10 | Recommendation |
|
||||
|---|---|---|---|---|---|
|
||||
| 1 | candidate_01_bold_claim.png | Bold Claim | 9 | 8 | ★ Top pick — strong data anchor, brand colours correct, title readable at 200px width |
|
||||
| 2 | candidate_02_conceptual_object.png | Conceptual Object | 7 | 9 | Good fallback — legible, clean, but illustration style drifted slightly from brand |
|
||||
| 3 | candidate_03_contrast_split.png | Contrast Split | 8 | 7 | Works well at full size; test at thumbnail size before publishing — right side text tightens |
|
||||
| 4 | candidate_04_typographic.png | Typographic | 9 | 10 | Strongest for email — zero brand drift risk, completely text-based |
|
||||
|
||||
Recommended for web: candidate_01_bold_claim.png
|
||||
Recommended for email/mobile: candidate_04_typographic.png
|
||||
Recommended for social: candidate_03_contrast_split.png
|
||||
|
||||
Files saved to: ./thumbnails/article-slug-from-title/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## How Claude Should Execute This Skill
|
||||
|
||||
### Step 1 — Ingest and analyse the article
|
||||
|
||||
Accept article copy as pasted text or a URL.
|
||||
|
||||
If a URL is provided, fetch the page and extract:
|
||||
- The H1 title
|
||||
- The first 3-5 paragraphs (the hook, central claim, and key points)
|
||||
- Any notable statistics or named frameworks mentioned
|
||||
- The author name (for typographic compositions)
|
||||
|
||||
If text is pasted, read it directly. Focus on:
|
||||
- **The hook:** What is the opening claim or tension?
|
||||
- **The central thesis:** What is the one thing the article argues or teaches?
|
||||
- **Key specifics:** Any numbers, named frameworks, or concrete examples that could anchor a visual
|
||||
- **Tone:** Is this formal/authoritative, conversational/accessible, provocative/challenge-based?
|
||||
|
||||
Summarise these findings internally before proposing compositions — the proposals should feel tailored to this specific article, not generic.
|
||||
|
||||
### Step 2 — Collect brand specs
|
||||
|
||||
Ask the user for brand specs if not provided:
|
||||
|
||||
```
|
||||
To generate on-brand thumbnails, I need a few details:
|
||||
|
||||
1. Brand colours (hex codes or descriptions) — e.g. #1A1A2E, #E94560
|
||||
2. Font style preference — e.g. "bold sans-serif", "editorial serif", "geometric"
|
||||
3. Visual style — e.g. "flat minimal", "photorealistic", "illustrated", "typographic only"
|
||||
4. Any style references — describe a brand or publication whose aesthetic you want to match,
|
||||
or share an image URL
|
||||
|
||||
If you don't have brand specs yet, say "use clean defaults" and I'll use a professional
|
||||
dark-on-white editorial style.
|
||||
```
|
||||
|
||||
If the user says "use clean defaults", apply:
|
||||
- Background: `#FFFFFF` or `#0F0F0F` (dark mode default)
|
||||
- Accent: `#2563EB` (blue)
|
||||
- Font style: bold geometric sans-serif
|
||||
- Style: minimal flat, no textures, high contrast
|
||||
|
||||
### Step 3 — Propose composition concepts
|
||||
|
||||
Write 3-4 composition concepts tailored to the article's tone and content. Each concept must:
|
||||
- Have a name (short, memorable label)
|
||||
- Describe the layout precisely (where title goes, what visual element anchors it, background treatment)
|
||||
- Note the mood and the use case it's best suited for
|
||||
- Include a rationale sentence explaining why this composition fits this specific article
|
||||
|
||||
After presenting the concepts, ask which to generate. Wait for user confirmation before making any API calls.
|
||||
|
||||
### Step 4 — Write Gemini image generation prompts
|
||||
|
||||
For each selected composition, write a detailed image generation prompt. Image generation prompts follow a different grammar than text prompts — they are descriptive, not instructional.
|
||||
|
||||
**Prompt structure:**
|
||||
```
|
||||
[Subject/composition] + [Style] + [Colour palette] + [Mood/lighting] +
|
||||
[Text treatment if any] + [What to avoid]
|
||||
```
|
||||
|
||||
**Example prompt for Bold Claim composition:**
|
||||
```
|
||||
Article thumbnail image. Large bold white sans-serif headline text reading "3x Faster Than
|
||||
Traditional Methods" centred on a deep navy blue background (#1A1A2E). Small coral accent
|
||||
text (#E94560) below reading the subtitle. Minimal flat design, no gradients, no stock photo
|
||||
elements, no people. Clean professional editorial style, high contrast, newsletter header
|
||||
format, 16:9 landscape orientation. The composition is typographic — text is the hero,
|
||||
no illustration required. Avoid: clip art, drop shadows, low contrast, crowded layout.
|
||||
```
|
||||
|
||||
**Prompt rules:**
|
||||
- Include exact hex colours when brand colours are provided
|
||||
- Specify the exact headline text to appear in the image
|
||||
- Name the style explicitly ("flat design", "editorial", "photorealistic") — Gemini responds well to style category names
|
||||
- Add a negative prompt ("Avoid: ...") at the end to reduce drift from brand style
|
||||
- Keep prompts under 300 words — longer prompts do not reliably produce better outputs
|
||||
|
||||
### Step 5 — Check prerequisites and run the generation script
|
||||
|
||||
Before calling the API, verify:
|
||||
|
||||
```bash
|
||||
# Check API key is set
|
||||
echo $GEMINI_API_KEY
|
||||
|
||||
# Check script exists
|
||||
ls -la ./generate_image.py
|
||||
|
||||
# Check dependencies
|
||||
python3 -c "import google.generativeai, PIL, requests; print('Dependencies OK')"
|
||||
```
|
||||
|
||||
If the script is missing, offer to create it using the template in the Script Template section below.
|
||||
|
||||
Run the generation script for each prompt:
|
||||
|
||||
```bash
|
||||
python3 generate_image.py \
|
||||
--prompt "your full prompt here" \
|
||||
--output "./thumbnails/article-slug/candidate_01_bold_claim.png" \
|
||||
--width 1792 \
|
||||
--height 1024
|
||||
```
|
||||
|
||||
Or pass all prompts in a batch config file:
|
||||
|
||||
```bash
|
||||
python3 generate_image.py --config ./thumbnails/article-slug/prompts.json
|
||||
```
|
||||
|
||||
### Step 6 — Evaluate generated images
|
||||
|
||||
After each image is saved, examine it using computer vision. Evaluate on two dimensions:
|
||||
|
||||
**Brand Fit (score /10):**
|
||||
- Are the brand colours correct? (1-2 points each)
|
||||
- Does the style match the requested aesthetic? (2 points)
|
||||
- Is the layout consistent with the composition brief? (2 points)
|
||||
- Are there any AI artefacts, distorted text, or unintended elements? (-1 per issue)
|
||||
|
||||
**Text Legibility (score /10):**
|
||||
- Is the headline text readable at full resolution? (3 points)
|
||||
- Is the headline text readable when the image is scaled to 300px wide (thumbnail size)? (3 points)
|
||||
- Is there sufficient contrast between text and background? (2 points)
|
||||
- Is the text placement within safe zones (not cut off at edges)? (2 points)
|
||||
|
||||
Note: Gemini Imagen sometimes renders text with spelling errors or distorted letterforms. If this happens, note it in the evaluation and suggest the user add the text overlay manually in Canva or Figma.
|
||||
|
||||
### Step 7 — Produce the evaluation report
|
||||
|
||||
Write the evaluation summary table (format shown in Output Structure section) and save it as `evaluation_report.md` in the output folder.
|
||||
|
||||
Include:
|
||||
- One-line rationale for each score
|
||||
- A top pick recommendation per use case (web, email/mobile, social)
|
||||
- Any production notes (e.g. "text rendering is imperfect on candidate_02 — overlay text manually")
|
||||
- The full prompts used, so the user can iterate directly in AI Studio if needed
|
||||
|
||||
### Step 8 — Offer iteration
|
||||
|
||||
After delivering the candidates, offer one iteration pass:
|
||||
|
||||
```
|
||||
Want me to iterate on any of these?
|
||||
|
||||
Options:
|
||||
- Adjust colours or style on a specific candidate
|
||||
- Try a different composition concept
|
||||
- Change the headline text
|
||||
- Rerun with different Gemini parameters (different temperature/seed)
|
||||
- Generate additional variants of the top pick
|
||||
|
||||
Just tell me what to change.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Script Template
|
||||
|
||||
Claude should offer to write this file if `generate_image.py` is not present. This is the canonical template to use.
|
||||
|
||||
```python
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
generate_image.py — Gemini Imagen wrapper for Thumbnail Creator skill.
|
||||
|
||||
Usage:
|
||||
python3 generate_image.py --prompt "..." --output "./out.png" [--width 1792] [--height 1024]
|
||||
python3 generate_image.py --config ./prompts.json
|
||||
|
||||
Config JSON format:
|
||||
[
|
||||
{
|
||||
"prompt": "...",
|
||||
"output": "./thumbnails/slug/candidate_01.png",
|
||||
"width": 1792,
|
||||
"height": 1024
|
||||
}
|
||||
]
|
||||
|
||||
Requirements:
|
||||
pip install google-generativeai Pillow
|
||||
"""
|
||||
|
||||
import os
|
||||
import sys
|
||||
import json
|
||||
import argparse
|
||||
import base64
|
||||
from pathlib import Path
|
||||
|
||||
try:
|
||||
import google.generativeai as genai
|
||||
from google.generativeai import types as genai_types
|
||||
except ImportError:
|
||||
print("ERROR: google-generativeai not installed. Run: pip install google-generativeai")
|
||||
sys.exit(1)
|
||||
|
||||
try:
|
||||
from PIL import Image
|
||||
import io
|
||||
except ImportError:
|
||||
print("ERROR: Pillow not installed. Run: pip install Pillow")
|
||||
sys.exit(1)
|
||||
|
||||
|
||||
def get_api_key() -> str:
|
||||
key = os.environ.get("GEMINI_API_KEY", "")
|
||||
if not key:
|
||||
print("ERROR: GEMINI_API_KEY environment variable is not set.")
|
||||
print("Get a key at: https://aistudio.google.com/app/apikey")
|
||||
print("Then run: export GEMINI_API_KEY='your-key-here'")
|
||||
sys.exit(1)
|
||||
return key
|
||||
|
||||
|
||||
def generate_image(
|
||||
prompt: str,
|
||||
output_path: str,
|
||||
width: int = 1792,
|
||||
height: int = 1024,
|
||||
) -> bool:
|
||||
"""
|
||||
Call Gemini Imagen to generate a single image and save it to output_path.
|
||||
Returns True on success, False on failure.
|
||||
"""
|
||||
api_key = get_api_key()
|
||||
genai.configure(api_key=api_key)
|
||||
|
||||
# Determine aspect ratio from dimensions
|
||||
ratio = width / height
|
||||
if abs(ratio - 16/9) < 0.1:
|
||||
aspect_ratio = "16:9"
|
||||
elif abs(ratio - 1.0) < 0.1:
|
||||
aspect_ratio = "1:1"
|
||||
elif abs(ratio - 9/16) < 0.1:
|
||||
aspect_ratio = "9:16"
|
||||
else:
|
||||
aspect_ratio = "16:9" # default fallback
|
||||
|
||||
try:
|
||||
imagen_model = genai.ImageGenerationModel("imagen-3.0-generate-002")
|
||||
|
||||
result = imagen_model.generate_images(
|
||||
prompt=prompt,
|
||||
number_of_images=1,
|
||||
aspect_ratio=aspect_ratio,
|
||||
safety_filter_level="block_only_high",
|
||||
person_generation="allow_adult",
|
||||
)
|
||||
|
||||
if not result.images:
|
||||
print(f" No images returned for: {output_path}")
|
||||
return False
|
||||
|
||||
image_data = result.images[0]
|
||||
|
||||
# Ensure output directory exists
|
||||
Path(output_path).parent.mkdir(parents=True, exist_ok=True)
|
||||
|
||||
# Save the image
|
||||
if hasattr(image_data, '_image_bytes'):
|
||||
img_bytes = image_data._image_bytes
|
||||
elif hasattr(image_data, 'image'):
|
||||
img_bytes = image_data.image
|
||||
else:
|
||||
# Fallback: try to access raw data
|
||||
img_bytes = bytes(image_data)
|
||||
|
||||
img = Image.open(io.BytesIO(img_bytes))
|
||||
|
||||
# Resize to exact dimensions if needed
|
||||
if img.size != (width, height):
|
||||
img = img.resize((width, height), Image.LANCZOS)
|
||||
|
||||
img.save(output_path, format="PNG", optimize=True)
|
||||
print(f" Saved: {output_path} ({img.size[0]}x{img.size[1]})")
|
||||
return True
|
||||
|
||||
except Exception as e:
|
||||
print(f" ERROR generating image: {e}")
|
||||
return False
|
||||
|
||||
|
||||
def run_from_args():
|
||||
parser = argparse.ArgumentParser(description="Gemini Imagen wrapper for thumbnail generation")
|
||||
parser.add_argument("--prompt", type=str, help="Image generation prompt")
|
||||
parser.add_argument("--output", type=str, help="Output file path (.png)")
|
||||
parser.add_argument("--width", type=int, default=1792, help="Image width in pixels")
|
||||
parser.add_argument("--height", type=int, default=1024, help="Image height in pixels")
|
||||
parser.add_argument("--config", type=str, help="JSON config file with batch of prompts")
|
||||
args = parser.parse_args()
|
||||
|
||||
if args.config:
|
||||
# Batch mode
|
||||
with open(args.config, "r") as f:
|
||||
items = json.load(f)
|
||||
print(f"Batch mode: {len(items)} image(s) to generate")
|
||||
results = []
|
||||
for i, item in enumerate(items, start=1):
|
||||
print(f"\n[{i}/{len(items)}] Generating: {item['output']}")
|
||||
ok = generate_image(
|
||||
prompt=item["prompt"],
|
||||
output_path=item["output"],
|
||||
width=item.get("width", 1792),
|
||||
height=item.get("height", 1024),
|
||||
)
|
||||
results.append({"output": item["output"], "ok": ok})
|
||||
|
||||
print(f"\nBatch complete: {sum(r['ok'] for r in results)}/{len(results)} succeeded")
|
||||
for r in results:
|
||||
status = "OK " if r["ok"] else "ERR"
|
||||
print(f" {status} {r['output']}")
|
||||
|
||||
elif args.prompt and args.output:
|
||||
# Single image mode
|
||||
print(f"Generating: {args.output}")
|
||||
ok = generate_image(
|
||||
prompt=args.prompt,
|
||||
output_path=args.output,
|
||||
width=args.width,
|
||||
height=args.height,
|
||||
)
|
||||
if ok:
|
||||
print("Done.")
|
||||
else:
|
||||
print("Failed.")
|
||||
sys.exit(1)
|
||||
|
||||
else:
|
||||
parser.print_help()
|
||||
sys.exit(1)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
run_from_args()
|
||||
```
|
||||
|
||||
**To create this file from inside Claude Code:**
|
||||
```bash
|
||||
# Claude will write this file if it doesn't exist:
|
||||
ls ./generate_image.py || echo "Script missing — Claude will create it"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Prompt Writing Reference
|
||||
|
||||
Claude should use this reference when writing image generation prompts. These patterns produce the most consistent results with Gemini Imagen.
|
||||
|
||||
### Composition patterns
|
||||
|
||||
| Composition type | Prompt anchor phrase |
|
||||
|---|---|
|
||||
| Text-led, dark background | "Bold white sans-serif headline text on deep [colour] background, minimal flat design" |
|
||||
| Text-led, light background | "High-contrast black headline text on clean white background, editorial layout" |
|
||||
| Object/illustration centred | "Centred [object] illustration, [style], [colour] background, title text in upper third" |
|
||||
| Split layout | "Vertical split: left half [colour], right half white. Headline on left side, supporting text on right" |
|
||||
| Photography style | "Photorealistic [scene description], [mood] lighting, [colour] colour grade, text overlay area at [position]" |
|
||||
|
||||
### Style modifiers that work well with Gemini
|
||||
|
||||
- `flat design, no gradients` — clean vector-style outputs
|
||||
- `editorial magazine style` — sophisticated, typographic
|
||||
- `minimal, lots of whitespace` — reduces visual noise
|
||||
- `high contrast, bold typography` — strong thumbnail legibility
|
||||
- `Bauhaus-inspired` — geometric, structured
|
||||
- `dark mode aesthetic` — dark backgrounds with light text
|
||||
- `startup marketing style` — clean, optimistic, sans-serif
|
||||
|
||||
### Negative prompts (always include)
|
||||
|
||||
Append to every prompt:
|
||||
|
||||
```
|
||||
Avoid: stock photography clichés, clipart, excessive gradients, drop shadows,
|
||||
cluttered layout, lens flares, watermarks, low contrast text, AI artefacts.
|
||||
```
|
||||
|
||||
### Text rendering note
|
||||
|
||||
Gemini Imagen sometimes renders short text phrases accurately and longer headlines poorly. If the article headline is longer than 6 words, consider splitting it in the prompt:
|
||||
|
||||
```
|
||||
Primary headline: "[First 4-5 words]"
|
||||
Secondary text: "[Remaining words]"
|
||||
```
|
||||
|
||||
Or instruct the user to add text overlay manually in Canva after generation if legibility is critical.
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
| Issue | Cause | Fix |
|
||||
|---|---|---|
|
||||
| `GEMINI_API_KEY not set` | Environment variable missing | Run `export GEMINI_API_KEY="your-key"` and retry |
|
||||
| `ModuleNotFoundError: google.generativeai` | Dependency missing | Run `pip install google-generativeai` |
|
||||
| `No images returned` | Safety filter triggered | Revise prompt to remove any ambiguous language; check that the prompt doesn't describe faces, violence, or brand logos |
|
||||
| Generated image has garbled text | Imagen text rendering limitation | Use shorter headline in prompt, or plan to add text overlay in Canva/Figma post-generation |
|
||||
| Image is the wrong size | Aspect ratio mismatch | Confirm `--width` and `--height` args match one of the supported ratios (16:9, 1:1, 9:16) |
|
||||
| `generate_image.py not found` | Script not created yet | Ask Claude to create it using the template above |
|
||||
| API quota exceeded | Free tier limit | Wait or upgrade to Gemini API paid tier |
|
||||
| Style drift from brand | Prompt not specific enough | Add exact hex codes and specific style descriptors; add stronger negative prompt |
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
Before marking the task complete, verify each item:
|
||||
|
||||
- [ ] `GEMINI_API_KEY` environment variable confirmed set before any API calls
|
||||
- [ ] `generate_image.py` script exists in project root — created from template if missing
|
||||
- [ ] All Python dependencies installed and verified (`google-generativeai`, `Pillow`)
|
||||
- [ ] Composition proposals were presented and user confirmed which to generate before any API calls
|
||||
- [ ] Each composition proposal is specific to this article's content — not generic placeholders
|
||||
- [ ] Brand colours (hex codes) are included in the image generation prompts
|
||||
- [ ] Negative prompt appended to every image generation prompt
|
||||
- [ ] Headline text in prompts is 6 words or fewer per text element (longer headlines split or noted as overlay candidates)
|
||||
- [ ] Output folder created at `./thumbnails/[article-slug]/` with correct slug derived from article title
|
||||
- [ ] Files named with candidate number and composition name (`candidate_01_bold_claim.png`)
|
||||
- [ ] Each generated image evaluated via computer vision — not assumed to be correct
|
||||
- [ ] Brand Fit and Text Legibility scores are specific and justified, not round numbers
|
||||
- [ ] Any text rendering issues noted in evaluation with "add text overlay manually" recommendation
|
||||
- [ ] Evaluation report saved as `evaluation_report.md` in the output folder
|
||||
- [ ] At least one recommendation given per use case: web, email/mobile, social
|
||||
- [ ] Full prompts used are included in the evaluation report for user iteration reference
|
||||
- [ ] Iteration offer made after delivering results
|
||||
|
||||
---
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- "Create thumbnails for this article"
|
||||
- "Generate cover image candidates for my newsletter"
|
||||
- "Make me 4 thumbnail options for this post"
|
||||
- "Can you generate some thumbnail ideas using Gemini?"
|
||||
- "I need a featured image for this article — use my brand colours"
|
||||
- "Create a thumbnail for this piece using Gemini" [followed by article text or URL]
|
||||
- "Generate article cover images for these brand specs: [colours, style]"
|
||||
- "Make thumbnail candidates and rank them"
|
||||
- "I need newsletter header images — here's the copy"
|
||||
- "Generate and evaluate thumbnail options for this draft"
|
||||
- "Use Gemini to create cover image options"
|
||||
- "Thumbnail this article" [followed by article text]
|
||||
- "Create 3 thumbnail compositions and pick the best one"
|
||||
|
||||
---
|
||||
|
||||
## Cost and Rate Limits
|
||||
|
||||
**Gemini AI Studio free tier (as of early 2026):**
|
||||
- Imagen 3: 10 images per day (free)
|
||||
- Rate limit: varies by region and account tier
|
||||
|
||||
**Paid tier:**
|
||||
- Imagen 3 pricing: approximately $0.03-0.05 per image (check current Google Cloud pricing)
|
||||
- For a typical session generating 4-8 candidates, total cost is under $0.40
|
||||
|
||||
**Recommendation:**
|
||||
- Use the free tier for exploration and iteration
|
||||
- Generate final production candidates on paid tier for higher daily limits
|
||||
- For newsletter teams generating thumbnails weekly, the paid tier is more practical
|
||||
|
||||
---
|
||||
|
||||
*Originally created by Karen Spinner (Wondering About AI) — adapted and extended for this library.*
|
||||
@@ -0,0 +1,218 @@
|
||||
---
|
||||
name: user-story-writer
|
||||
description: "Write well-structured user stories with acceptance criteria and edge cases. Use when asked to write user stories, create tickets from a feature brief, convert a PRD into stories, or write acceptance criteria. Produces ready-to-estimate stories in the standard format with clear acceptance criteria, edge cases, and definition of done."
|
||||
---
|
||||
|
||||
# User Story Writer Skill
|
||||
|
||||
This skill produces production-ready user stories from a feature brief, PRD section, or verbal description. Each story follows the standard format with a clear who/what/why, behavioural acceptance criteria in Given/When/Then format, edge cases, and definition of done. Output is ready to paste into Jira, Linear, or your planning tool.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask the user for these if not provided:
|
||||
- **Feature or change** to break into stories — paste the brief, PRD section, or describe the feature
|
||||
- **User types / personas** involved (e.g. admin, end user, guest, API consumer)
|
||||
- **Scope** — are we writing one story or decomposing an epic into a full set of stories?
|
||||
- **Acceptance criteria format preference** — Given/When/Then, bullet checklist, or both?
|
||||
- **Technical constraints or notes** — anything the engineering team has flagged that should shape the stories
|
||||
|
||||
## Output Structure
|
||||
|
||||
For each story:
|
||||
|
||||
---
|
||||
|
||||
## Story: [Short title — verb + noun, e.g. "Filter search results by date range"]
|
||||
|
||||
**Epic:** [Parent epic name — e.g. "Advanced Search"]
|
||||
**Story ID:** [Jira/Linear ID — leave blank if not yet created]
|
||||
**Priority:** [P1 / P2 / P3]
|
||||
**Story points:** [Leave blank — for engineering to estimate]
|
||||
|
||||
---
|
||||
|
||||
### User Story
|
||||
|
||||
> **As a** [specific user type — not "user"],
|
||||
> **I want to** [concrete action they want to take],
|
||||
> **So that** [the outcome they achieve — business value, not feature description].
|
||||
|
||||
**Example:**
|
||||
> As an **account manager**,
|
||||
> I want to **filter my client list by last contact date**,
|
||||
> so that I **can quickly identify clients I haven't spoken to in over 30 days and prioritise outreach**.
|
||||
|
||||
---
|
||||
|
||||
### Context
|
||||
|
||||
[1–3 sentences of context that aren't in the user story itself: when does this story matter, what triggers the need, how does it fit into a larger flow. This helps engineers understand why before they ask.]
|
||||
|
||||
---
|
||||
|
||||
### Acceptance Criteria
|
||||
|
||||
**Format: Given / When / Then**
|
||||
|
||||
Each criterion tests one specific behaviour. Write one GWT per observable outcome — not one GWT for the whole feature.
|
||||
|
||||
**AC1: [Short name for this criterion]**
|
||||
```
|
||||
Given [starting state or context]
|
||||
When [user action]
|
||||
Then [observable system behaviour]
|
||||
```
|
||||
|
||||
**AC2: [Short name]**
|
||||
```
|
||||
Given [...]
|
||||
When [...]
|
||||
Then [...]
|
||||
```
|
||||
|
||||
**AC3: [Short name]**
|
||||
```
|
||||
Given [...]
|
||||
When [...]
|
||||
Then [...]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Edge Cases
|
||||
|
||||
[List scenarios that are non-obvious but must be handled. These become additional ACs or notes to engineering.]
|
||||
|
||||
- [ ] **[Edge case 1]:** [e.g. User applies a date filter that returns 0 results — show empty state with clear messaging and a "clear filters" action]
|
||||
- [ ] **[Edge case 2]:** [e.g. User has >10,000 clients — filter must not degrade load time >200ms]
|
||||
- [ ] **[Edge case 3]:** [e.g. Date filter persists across page refresh — or explicitly should not if that's the decision]
|
||||
- [ ] **[Permission edge case]:** [e.g. Read-only users can see the filter but cannot save filter presets]
|
||||
|
||||
---
|
||||
|
||||
### Out of Scope
|
||||
|
||||
[Explicitly state what this story does NOT cover — prevents scope creep and clarifies where the next story begins.]
|
||||
|
||||
- Saving and sharing filter presets (separate story — see [Story X])
|
||||
- Bulk actions on filtered results
|
||||
- Exporting filtered client list to CSV
|
||||
|
||||
---
|
||||
|
||||
### Definition of Done
|
||||
|
||||
- [ ] Acceptance criteria all pass
|
||||
- [ ] Edge cases handled (or explicitly deferred with a new ticket raised)
|
||||
- [ ] Unit tests written for each AC
|
||||
- [ ] Works on mobile viewport (if applicable)
|
||||
- [ ] Accessibility: keyboard navigable and screen-reader compatible
|
||||
- [ ] Error states are handled and copy approved
|
||||
- [ ] Product and design have reviewed in staging
|
||||
- [ ] No console errors in production build
|
||||
|
||||
---
|
||||
|
||||
## Epic Decomposition Template
|
||||
|
||||
If the user provides an epic or feature brief, decompose it into a full set of stories before writing them:
|
||||
|
||||
**Epic:** [Name]
|
||||
**Goal:** [What outcome does completing this epic achieve?]
|
||||
**Stories:**
|
||||
|
||||
| # | Story | Notes | Dependencies |
|
||||
|---|---|---|---|
|
||||
| 1 | [Core happy path story — the simplest version of the feature that delivers value] | | |
|
||||
| 2 | [Validation / error handling story] | | Depends on #1 |
|
||||
| 3 | [Edge case or power user story] | | Depends on #1 |
|
||||
| 4 | [Admin or configuration story] | | |
|
||||
| 5 | [Performance or scale story — if applicable] | | Depends on #1 |
|
||||
|
||||
**Suggested sprint order:** [Which stories are P1 for MVP? Which can follow in a later sprint?]
|
||||
|
||||
---
|
||||
|
||||
## Common Story Anti-Patterns — and Fixes
|
||||
|
||||
Use these to review stories before handing to engineering:
|
||||
|
||||
| Anti-pattern | Example | Fix |
|
||||
|---|---|---|
|
||||
| **Solution in the story** | "As a user I want a dropdown filter" | Remove the UI decision — "As a user I want to filter by date range" |
|
||||
| **Vague "so that"** | "so that it's easier to use" | Make it specific — "so that I can prioritise outreach without opening each record manually" |
|
||||
| **Too big** | Story covers 5 distinct user flows | Split into separate stories per flow |
|
||||
| **No acceptance criteria** | Story has description only | Add at least 3 GWT criteria before engineering starts |
|
||||
| **ACs that test the solution, not the behaviour** | "Given the dropdown is open, When I select an option" | Test the outcome — "Given I have applied a date filter, When I view my results, Then only clients last contacted in that date range appear" |
|
||||
| **Missing empty state** | No AC for what happens with 0 results | Add it — empty states are part of the feature |
|
||||
| **Missing error state** | No AC for network failure or invalid input | Add error handling ACs explicitly |
|
||||
|
||||
---
|
||||
|
||||
## Example: Full Story Set for a Feature
|
||||
|
||||
**Feature brief:** "Allow users to export their invoice history as a PDF or CSV"
|
||||
|
||||
---
|
||||
|
||||
### Story 1: Export invoice list as CSV
|
||||
|
||||
> As a **finance admin**,
|
||||
> I want to **export my invoice history as a CSV file**,
|
||||
> so that I can **import it into our accounting software without manual data entry**.
|
||||
|
||||
**AC1: Successful export**
|
||||
```
|
||||
Given I am on the Invoices page with at least one invoice
|
||||
When I click "Export" and select "CSV"
|
||||
Then a CSV file is downloaded containing all visible invoices with columns: Invoice ID, Date, Amount, Status, Customer Name
|
||||
```
|
||||
|
||||
**AC2: Empty state**
|
||||
```
|
||||
Given I am on the Invoices page with no invoices
|
||||
When I click "Export"
|
||||
Then the export button is disabled and a tooltip reads "No invoices to export"
|
||||
```
|
||||
|
||||
**AC3: Filtered export**
|
||||
```
|
||||
Given I have applied a date filter showing invoices from Jan 2026 only
|
||||
When I click "Export" and select "CSV"
|
||||
Then the export contains only invoices from Jan 2026 — not all invoices
|
||||
```
|
||||
|
||||
**Edge cases:**
|
||||
- [ ] Export with >10,000 invoices — must complete in <30s or show a progress indicator
|
||||
- [ ] Export triggered on mobile — downloads to device's default download location
|
||||
|
||||
**Out of scope:** PDF export (Story 2), scheduled exports (future epic)
|
||||
|
||||
---
|
||||
|
||||
### Story 2: Export invoice list as PDF
|
||||
|
||||
> As a **finance admin**,
|
||||
> I want to **export my invoice history as a formatted PDF**,
|
||||
> so that I can **share a professional summary with our accountant**.
|
||||
|
||||
[... ACs follow same pattern ...]
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Every story has a specific user type — not "a user" or "the system"
|
||||
- [ ] The "so that" explains business value — not just feature description
|
||||
- [ ] Each AC tests one observable outcome — not a bundle of behaviours
|
||||
- [ ] Empty states, error states, and edge cases are explicitly handled
|
||||
- [ ] Out of scope is documented — not assumed
|
||||
- [ ] Stories are independent — they can be shipped individually without depending on unreleased work (except where explicitly noted)
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- "Write user stories for [feature] from this brief"
|
||||
- "Break this PRD section into user stories with acceptance criteria"
|
||||
- "Convert these feature requirements into Jira tickets"
|
||||
- "Write the user stories and ACs for [feature name]"
|
||||
- "Decompose this epic into individual stories ready for sprint planning"
|
||||
@@ -0,0 +1,397 @@
|
||||
---
|
||||
name: viral-content-framework
|
||||
description: "Build a framework for creating shareable, high-reach social media content. Use when asked to plan viral content, develop a shareable content strategy, create a hook writing system, or build a repeatable process for content that gets shared. Produces a platform-specific viral content framework with hook formulas, content structures, shareability triggers, and a content testing system."
|
||||
---
|
||||
|
||||
# Viral Content Framework Skill
|
||||
|
||||
This skill produces a platform-specific framework for creating content that earns shares, saves, comments, and organic reach beyond your existing following. It covers the psychology of sharing, hook formulas, content structures that consistently perform, platform-specific formats, and a repeatable system for producing high-reach content. Output gives a content creator, social media manager, or marketer a structured process they can apply immediately.
|
||||
|
||||
## Required Inputs
|
||||
|
||||
Ask the user for these if not provided:
|
||||
- **Brand / creator name**
|
||||
- **Primary platform(s)** — where are you trying to build reach? (LinkedIn, TikTok, Instagram, X/Twitter, YouTube)
|
||||
- **Content niche / topic area** — what is the content about?
|
||||
- **Target audience** — who are you trying to reach and what do they care about?
|
||||
- **Content goal** — what should high-reach content achieve? (followers / brand awareness / inbound leads / community / sales)
|
||||
- **Current performance baseline** — roughly how many impressions / shares / saves does a typical post get today?
|
||||
|
||||
## Output Structure
|
||||
|
||||
---
|
||||
|
||||
# Viral Content Framework: [Brand / Creator Name]
|
||||
|
||||
**Platform(s):** [List]
|
||||
**Niche:** [Content topic area]
|
||||
**Audience:** [Target audience description]
|
||||
**Goal:** [What high-reach content should achieve]
|
||||
**Date:** [Date]
|
||||
|
||||
---
|
||||
|
||||
## 1. The Psychology of Sharing
|
||||
|
||||
Before tactics, understand why people share. Content goes viral when it triggers one or more of these sharing motivations:
|
||||
|
||||
| Motivation | What it means | How to trigger it |
|
||||
|---|---|---|
|
||||
| **Identity** | "Sharing this says something good about me" | Make the audience look smart, informed, or principled by sharing |
|
||||
| **Utility** | "This is so useful I'd be doing my friends a disservice not to share it" | Teach something actionable that produces an immediate result |
|
||||
| **Emotion** | "This made me feel something — I want others to feel it too" | Surprise, delight, inspiration, righteous anger, nostalgia |
|
||||
| **Tribe** | "My people need to see this" | Create content that speaks specifically to a tight community |
|
||||
| **Status** | "Being first to share this makes me look ahead of the curve" | Break news, contrarian takes, insider information |
|
||||
| **Validation** | "This is exactly what I've been thinking but couldn't articulate" | Voice what the audience already believes — be their spokesperson |
|
||||
|
||||
**For [brand/creator], the primary sharing motivation is:** [Choose 1–2 that fit the niche and audience]
|
||||
|
||||
---
|
||||
|
||||
## 2. The Virality Formula
|
||||
|
||||
High-reach content = **Strong hook × Valuable substance × Easy shareability**
|
||||
|
||||
All three must be present. Strong hooks that lead to thin content get clicks but not shares. Brilliant content with a weak hook never gets seen. Content that's hard to share (too long, too branded, too complex) dies at the save stage.
|
||||
|
||||
### Diagnosing your current content:
|
||||
|
||||
| Element | Strong | Weak | Fix |
|
||||
|---|---|---|---|
|
||||
| Hook (first line / first frame) | Stops scrolling immediately | Generic opening | Use hook formulas in Section 3 |
|
||||
| Substance | Actionable, specific, surprising | Vague, obvious, or filler | Apply content structures in Section 4 |
|
||||
| Shareability | Short enough to screenshot, save, or re-share | Too long, too branded, too complex | Trim to the essential value |
|
||||
|
||||
---
|
||||
|
||||
## 3. Hook Formulas That Work
|
||||
|
||||
The hook is everything. You have 1–3 seconds on TikTok/Instagram, 1 sentence on LinkedIn/X. Use these proven formulas:
|
||||
|
||||
### Formula 1: The Contrarian Statement
|
||||
*"[Widely believed thing] is wrong / a myth / overrated."*
|
||||
> Examples:
|
||||
> - "Posting every day on LinkedIn is killing your reach."
|
||||
> - "Consistency isn't the reason great creators grow. This is."
|
||||
> - "The best social media strategy doesn't start with content."
|
||||
|
||||
**Why it works:** Challenges existing beliefs → triggers curiosity + mild outrage = comments + shares
|
||||
|
||||
---
|
||||
|
||||
### Formula 2: The Specific Number / Result
|
||||
*"I [achieved specific result] in [specific timeframe]. Here's how."*
|
||||
> Examples:
|
||||
> - "I went from 0 to 10,000 LinkedIn followers in 6 months. Here's the exact system."
|
||||
> - "Our last post got 2.3M views. These are the 4 decisions that made it happen."
|
||||
> - "I reduced our content production time by 70% using this workflow."
|
||||
|
||||
**Why it works:** Specific numbers are credible. Credibility earns attention. "How" frames create utility.
|
||||
|
||||
---
|
||||
|
||||
### Formula 3: The Uncomfortable Truth
|
||||
*"Nobody wants to hear this, but [uncomfortable truth about your niche]."*
|
||||
> Examples:
|
||||
> - "Nobody wants to hear this, but most social media 'strategies' are just posting without a plan."
|
||||
> - "Your content isn't underperforming because of the algorithm. It's because of the hook."
|
||||
> - "If your product needs a social media strategy to sell, you may have a product problem."
|
||||
|
||||
**Why it works:** "Nobody wants to hear this" primes people to read it. Uncomfortable truths polarise → comments
|
||||
|
||||
---
|
||||
|
||||
### Formula 4: The Listicle Tease
|
||||
*"[X] things I wish someone had told me about [topic]."*
|
||||
> Examples:
|
||||
> - "5 things every social media manager knows that nobody talks about publicly."
|
||||
> - "8 LinkedIn hacks that took me 3 years to discover."
|
||||
> - "The 3 types of hooks that consistently outperform everything else."
|
||||
|
||||
**Why it works:** Implied exclusivity + easy to save and return to
|
||||
|
||||
---
|
||||
|
||||
### Formula 5: The Story Hook
|
||||
*"[Specific moment / scene / event that sets up a tension]."*
|
||||
> Examples:
|
||||
> - "At 11pm on a Sunday, our post started going viral. By Monday morning it had 500k views. Here's what we did wrong."
|
||||
> - "Six months ago I had 200 followers. I changed one thing. Now I have 40,000."
|
||||
> - "A customer tweeted something about us last week. I nearly deleted it. I didn't. Here's what happened."
|
||||
|
||||
**Why it works:** Stories create forward momentum — people read to find out what happens
|
||||
|
||||
---
|
||||
|
||||
### Formula 6: The Pattern Interrupt Question
|
||||
*"[Question that the audience has never been asked about a familiar topic]."*
|
||||
> Examples:
|
||||
> - "What's the real reason some posts go viral on command and others die quietly?"
|
||||
> - "If you had to teach someone to create shareable content in 10 minutes, what would you actually say?"
|
||||
> - "What would happen if you stopped posting for 30 days?"
|
||||
|
||||
**Why it works:** Unusual question about a familiar topic creates a "never thought about that" response
|
||||
|
||||
---
|
||||
|
||||
## 4. Content Structures That Perform
|
||||
|
||||
### Structure 1: The "Thread / Listicle" (LinkedIn, X/Twitter)
|
||||
|
||||
Best for: Education, frameworks, how-to content
|
||||
|
||||
```
|
||||
Hook: [Formula 1–6 above]
|
||||
↓
|
||||
Promise: "Here's what I'm going to share and why it matters to you."
|
||||
↓
|
||||
Point 1: [Specific, actionable, with an example]
|
||||
Point 2: [Specific, actionable, with an example]
|
||||
Point 3: [Specific, actionable, with an example]
|
||||
[...up to 7–10 points — stop when you run out of substance, not ideas]
|
||||
↓
|
||||
Summary: "The one thing to remember from all of this is: [distill to a single insight]"
|
||||
↓
|
||||
CTA: [Follow for more / save this / what would you add?]
|
||||
```
|
||||
|
||||
**Shareability trigger:** Utility — save to come back to. Comment-baiting summary.
|
||||
|
||||
---
|
||||
|
||||
### Structure 2: The "Before → After → Bridge" (All platforms)
|
||||
|
||||
Best for: Product/service showcases, transformations, case studies
|
||||
|
||||
```
|
||||
Hook: [The after — start with the impressive result]
|
||||
↓
|
||||
Before: "Here's what the situation looked like before: [specific, relatable pain]"
|
||||
↓
|
||||
After: "Here's what it looks like now: [specific, impressive outcome with numbers]"
|
||||
↓
|
||||
Bridge: "Here's exactly what changed between those two states: [the process / insight / tool]"
|
||||
↓
|
||||
CTA: [Try it / learn more / what's your 'before'?]
|
||||
```
|
||||
|
||||
**Shareability trigger:** Identity + utility — audience wants to share a transformation they aspire to
|
||||
|
||||
---
|
||||
|
||||
### Structure 3: The "Contrarian Deep Dive" (LinkedIn, X/Twitter, YouTube)
|
||||
|
||||
Best for: Building authority, thought leadership, engagement
|
||||
|
||||
```
|
||||
Hook: [Contrarian statement — Formula 1]
|
||||
↓
|
||||
Acknowledge the conventional wisdom: "Most people believe [X] because [reason]."
|
||||
↓
|
||||
Provide evidence against it: "But here's the data / experience / example that challenges it."
|
||||
↓
|
||||
Make the case: "What actually works is [Y], and here's why."
|
||||
↓
|
||||
Nuance (important): "To be fair, [X] works when [specific conditions]. But for [audience], [Y] is better."
|
||||
↓
|
||||
CTA: "Disagree? Tell me why ↓"
|
||||
```
|
||||
|
||||
**Shareability trigger:** Status + validation + tribe (people share things that represent their worldview)
|
||||
|
||||
---
|
||||
|
||||
### Structure 4: The "Story Arc" (TikTok, Instagram Reels, YouTube Shorts)
|
||||
|
||||
Best for: Video content, personal brand building
|
||||
|
||||
```
|
||||
Frame 1 (0–3 sec): Hook — [The punchline, result, or conflict stated upfront]
|
||||
Frame 2 (3–15 sec): Setup — [Who you are + what happened / the situation]
|
||||
Frame 3 (15–40 sec): Complication — [What went wrong / what the challenge was]
|
||||
Frame 4 (40–55 sec): Resolution — [What you did / what happened]
|
||||
Frame 5 (final 5 sec): CTA — [Follow for more / share if this happened to you / comment your take]
|
||||
```
|
||||
|
||||
**Shareability trigger:** Emotion — people share stories that resonate with an experience they've had
|
||||
|
||||
---
|
||||
|
||||
### Structure 5: The "Carousel / Slide Deck" (Instagram, LinkedIn)
|
||||
|
||||
Best for: How-to content, frameworks, comparisons, statistics
|
||||
|
||||
```
|
||||
Slide 1 (Cover): [Hook — compelling headline. Must earn the swipe.]
|
||||
Slide 2: [Context — why this matters. Set up the value.]
|
||||
Slides 3–7: [One insight per slide. Max 30 words + clear visual/diagram per slide.]
|
||||
Slide 8 (Summary): [The key takeaway distilled to one sentence.]
|
||||
Slide 9 (CTA): [Save this / follow / share / link in bio]
|
||||
```
|
||||
|
||||
**Shareability trigger:** Save rate. Carousels are the most-saved format on Instagram. Algorithm rewards saves.
|
||||
|
||||
---
|
||||
|
||||
## 5. Platform-Specific Playbook
|
||||
|
||||
### LinkedIn
|
||||
|
||||
**What goes viral on LinkedIn:**
|
||||
- Career advice that feels personally earned, not theoretical
|
||||
- Data + unexpected insight ("We analysed 100 LinkedIn posts and found...")
|
||||
- Contrarian takes on work, careers, or the professional world
|
||||
- Vulnerable, human moments (layoffs, failures, what you learned)
|
||||
- Tactical how-to posts with numbered lists
|
||||
|
||||
**Format priority:** Long-form text posts → carousels → video (in order of average reach)
|
||||
|
||||
**Algorithm signals that boost reach:** Comments > saves > reactions. Ask a question in the CTA.
|
||||
|
||||
**Posting time:** Tuesday–Thursday, 07:30–09:00 or 12:00–13:00 in your audience's timezone
|
||||
|
||||
**What kills LinkedIn reach:** Outbound links in the post body (add links in first comment instead), posting too frequently (3–5x/week max), vanity metrics in the hook
|
||||
|
||||
---
|
||||
|
||||
### TikTok
|
||||
|
||||
**What goes viral on TikTok:**
|
||||
- First 1–2 seconds must hook visually AND verbally
|
||||
- Relatability over polish — authentic > produced
|
||||
- Trending sounds / formats used with original content
|
||||
- "I can't believe they said that" or "I need to show this to [my person]" reaction content
|
||||
- Educational content that delivers value in under 60 seconds
|
||||
|
||||
**Format priority:** Trending sound duets/stitches → original POV → talking-head education
|
||||
|
||||
**Algorithm signals that boost reach:** Watch-through rate (% who watch the full video) is the #1 signal. Replays, shares, and comments follow.
|
||||
|
||||
**Hook principle:** Start mid-sentence. Start in the action. Never open with "Hey guys, today I'm going to..."
|
||||
|
||||
---
|
||||
|
||||
### Instagram
|
||||
|
||||
**What goes viral on Instagram:**
|
||||
- Carousels with a save-worthy framework or checklist (saves are the top signal)
|
||||
- Reels with a hook in the first frame (text overlay + visual hook simultaneously)
|
||||
- Before/after transformations (personal, product, design)
|
||||
- Content that makes people think "I need to send this to [specific person]"
|
||||
- Aesthetic content that people want on their feed
|
||||
|
||||
**Format priority:** Reels → carousels → static images (in order of current algorithm weighting)
|
||||
|
||||
**Algorithm signals that boost reach:** Saves > shares > comments > likes. Design for saves.
|
||||
|
||||
**Caption strategy:** Hook in the first line (shows before "more" truncation). Value in the body. CTA at the end.
|
||||
|
||||
---
|
||||
|
||||
### X / Twitter
|
||||
|
||||
**What goes viral on X:**
|
||||
- Strong opinion stated concisely (≤280 characters, no thread needed)
|
||||
- Data or insight that surprises the tech/media/culture audience
|
||||
- "This is the [most/best/funniest] [X] I've ever seen" amplification
|
||||
- Dunks on widely-held beliefs (with evidence)
|
||||
- Breaking news commentary that's faster than media
|
||||
|
||||
**Format priority:** Short opinion takes → threads → quote tweets with commentary
|
||||
|
||||
**Algorithm signals that boost reach:** Replies > retweets > likes. Controversy (civil) drives replies.
|
||||
|
||||
**Thread principle:** First tweet must work as a standalone — many people won't click "see more"
|
||||
|
||||
---
|
||||
|
||||
### YouTube (Shorts + Long-form)
|
||||
|
||||
**What goes viral — Shorts:**
|
||||
- Same TikTok principles apply
|
||||
- "Wait for it" content — builds to a payoff
|
||||
- Tutorial that delivers a result in under 60 seconds
|
||||
|
||||
**What goes viral — Long-form:**
|
||||
- High-retention opening: state the payoff in the first 30 seconds
|
||||
- Chapter markers for navigation (increases watch time)
|
||||
- Strong thumbnail + title pairing — the algorithm tests these against click-through rate
|
||||
|
||||
---
|
||||
|
||||
## 6. The Content Testing System
|
||||
|
||||
Virality is repeatable if you treat content creation as an experiment.
|
||||
|
||||
### Step 1: Create content batches
|
||||
|
||||
Produce 5–10 pieces per content type. Use a consistent structure with one variable changed per batch (hook type, format, topic angle).
|
||||
|
||||
### Step 2: Post and measure — the 48-hour signal
|
||||
|
||||
| Platform | 48-hour signal to watch | What it tells you |
|
||||
|---|---|---|
|
||||
| LinkedIn | Comments + saves in first 2 hours | Relevance to professional audience |
|
||||
| TikTok | Watch-through rate in first 24 hours | Hook and content quality |
|
||||
| Instagram | Saves rate per impression | "Worth returning to" value |
|
||||
| X/Twitter | Replies in first 4 hours | Resonance with the community |
|
||||
|
||||
### Step 3: Identify your "content codes"
|
||||
|
||||
After 30 days, review your top 5 performing posts and answer:
|
||||
- What format were they?
|
||||
- What hook formula?
|
||||
- What topic angle?
|
||||
- What content structure?
|
||||
- What time were they posted?
|
||||
|
||||
Your "content code" = the combination of these variables that consistently outperforms. Double down.
|
||||
|
||||
### Step 4: Scale what works
|
||||
|
||||
| Phase | Action |
|
||||
|---|---|
|
||||
| Week 1–4 | Test 2–3 hook formulas + 2–3 content structures. Post consistently. |
|
||||
| Month 2 | Identify top-performing patterns. Create 2x more of those. |
|
||||
| Month 3+ | 70% proven formats / 30% new experiments. Never stop testing the 30%. |
|
||||
|
||||
---
|
||||
|
||||
## 7. Content Bank — 30 Starter Ideas for [Niche]
|
||||
|
||||
Apply the hook formulas and content structures from above to these topic angles:
|
||||
|
||||
| # | Content angle | Hook formula | Structure | Format |
|
||||
|---|---|---|---|---|
|
||||
| 1 | [Common mistake in your niche] | Contrarian statement | Thread | LinkedIn / X |
|
||||
| 2 | [Counterintuitive insight you learned] | Uncomfortable truth | Thread | LinkedIn |
|
||||
| 3 | [A result you achieved + the process] | Specific number/result | Before→After→Bridge | All |
|
||||
| 4 | [A framework you use regularly] | Listicle tease | Carousel | Instagram / LinkedIn |
|
||||
| 5 | [An industry trend + your take] | Contrarian deep dive | Thread | LinkedIn / X |
|
||||
| 6 | [A story of failure + lesson] | Story hook | Story arc | TikTok / Reels |
|
||||
| 7 | [A tool/resource your audience would save] | Utility listicle | Carousel / list | Instagram / LinkedIn |
|
||||
| 8 | [A "what I wish I knew" post] | Listicle tease | Thread | LinkedIn |
|
||||
| 9 | [A behind-the-scenes process] | Pattern interrupt question | Video | TikTok / Reels |
|
||||
| 10 | [A reaction to industry news] | Contrarian statement | Thread | X / LinkedIn |
|
||||
|
||||
*[Generate 20 more ideas specific to the brand's niche here, using the same table format]*
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] Every hook uses a proven formula — no generic openers like "Today I want to talk about..."
|
||||
- [ ] Content structure chosen matches the platform and goal (save-bait on IG, thread on LinkedIn)
|
||||
- [ ] Each piece of content has one clear shareability trigger identified
|
||||
- [ ] Platform-specific rules are applied (e.g. no outbound links in LinkedIn post body)
|
||||
- [ ] Content bank has enough variety to test multiple angles before doubling down
|
||||
- [ ] Testing system is set up — 48-hour signal tracked for every post
|
||||
- [ ] CTA asks for a specific action, not a generic "like and share"
|
||||
|
||||
## Example Trigger Phrases
|
||||
|
||||
- "Build a viral content framework for [brand / creator]"
|
||||
- "Help me create shareable content for [platform]"
|
||||
- "What makes content go viral on [LinkedIn / TikTok / Instagram]?"
|
||||
- "Give me hook formulas and content structures for [niche]"
|
||||
- "Build a repeatable system for creating high-reach content"
|
||||
Reference in New Issue
Block a user