Compare commits
27 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
d7be8ef49f | ||
|
|
e9a4d402ff | ||
|
|
e8ad28df0d | ||
|
|
11b94d265e | ||
|
|
74c7e5f330 | ||
|
|
b76ad28225 | ||
|
|
a1a1178f4b | ||
|
|
1c66f65341 | ||
|
|
8678549bfb | ||
|
|
3d9f9f347f | ||
|
|
b5675d55ce | ||
|
|
6dcb7973ad | ||
|
|
9850b6b8e7 | ||
|
|
46d575b8d0 | ||
|
|
02fab354e0 | ||
|
|
226a7596cb | ||
|
|
11c16dbe27 | ||
|
|
95eeb1dd4b | ||
|
|
b1e4d61715 | ||
|
|
d17e7bc767 | ||
|
|
450a8a95a5 | ||
|
|
7a14904fd3 | ||
|
|
59a349075e | ||
|
|
d8b9ac19b2 | ||
|
|
68a457b96b | ||
|
|
98756d75ae | ||
|
|
4dcd96e484 |
@@ -1,8 +0,0 @@
|
||||
---
|
||||
trigger: always_on
|
||||
glob:
|
||||
description:
|
||||
---
|
||||
|
||||
1. alla fine del processo di modifica ricordati di fare il push della repo su github.
|
||||
2. ricordati sempre di aggiornare ongi singola parte della repo, dall'inizio alla fine
|
||||
6
.gitignore
vendored
Normal file
6
.gitignore
vendored
Normal file
@@ -0,0 +1,6 @@
|
||||
|
||||
MAINTENANCE.md
|
||||
walkthrough.md
|
||||
.agent/rules/
|
||||
.gemini/
|
||||
LOCAL_CONFIG.md
|
||||
142
CHANGELOG.md
Normal file
142
CHANGELOG.md
Normal file
@@ -0,0 +1,142 @@
|
||||
# Changelog
|
||||
|
||||
All notable changes to the **Antigravity Awesome Skills** collection are documented in this file.
|
||||
|
||||
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
|
||||
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
||||
|
||||
---
|
||||
|
||||
## [1.0.0] - 2026-01-19 - "Marketing Edition"
|
||||
|
||||
### Added
|
||||
|
||||
- **23 Marketing & Growth skills** from [coreyhaines31/marketingskills](https://github.com/coreyhaines31/marketingskills):
|
||||
- **CRO**: `page-cro`, `signup-flow-cro`, `onboarding-cro`, `form-cro`, `popup-cro`, `paywall-upgrade-cro`
|
||||
- **Content**: `copywriting`, `copy-editing`, `email-sequence`
|
||||
- **SEO**: `seo-audit`, `programmatic-seo`, `schema-markup`, `competitor-alternatives`
|
||||
- **Paid**: `paid-ads`, `social-content`
|
||||
- **Growth**: `referral-program`, `launch-strategy`, `free-tool-strategy`
|
||||
- **Analytics**: `ab-test-setup`, `analytics-tracking`
|
||||
- **Strategy**: `pricing-strategy`, `marketing-ideas`, `marketing-psychology`
|
||||
- New "Marketing & Growth" category in Features table
|
||||
|
||||
### Changed
|
||||
|
||||
- Total skills count: **179**
|
||||
|
||||
---
|
||||
|
||||
## [0.7.0] - 2026-01-19 - "Education Edition"
|
||||
|
||||
### Added
|
||||
|
||||
- **Moodle External API Development** skill via PR #6
|
||||
- Comprehensive Moodle LMS web service API development
|
||||
|
||||
### Changed
|
||||
|
||||
- Total skills count: **156**
|
||||
|
||||
---
|
||||
|
||||
## [0.6.0] - 2026-01-19 - "Vibeship Integration"
|
||||
|
||||
### Added
|
||||
|
||||
- **57 skills** from [vibeforge1111/vibeship-spawner-skills](https://github.com/vibeforge1111/vibeship-spawner-skills):
|
||||
- AI Agents category (~30 skills)
|
||||
- Integrations & APIs (~25 skills)
|
||||
- Maker Tools (~11 skills)
|
||||
- Alphabetically sorted skill registry
|
||||
|
||||
### Changed
|
||||
|
||||
- Total skills count: **155**
|
||||
|
||||
---
|
||||
|
||||
## [0.5.0] - 2026-01-18 - "Agent Manager"
|
||||
|
||||
### Added
|
||||
|
||||
- **Agent Manager Skill** - Multi-agent orchestration via tmux
|
||||
- Major repository expansion with community contributions
|
||||
|
||||
### Changed
|
||||
|
||||
- Total skills count: **131**
|
||||
|
||||
---
|
||||
|
||||
## [0.4.0] - 2026-01-18 - "Security Fortress"
|
||||
|
||||
### Added
|
||||
|
||||
- **60+ Cybersecurity skills** from [zebbern/claude-code-guide](https://github.com/zebbern/claude-code-guide):
|
||||
- Ethical Hacking Methodology
|
||||
- Metasploit Framework
|
||||
- Burp Suite Testing
|
||||
- SQLMap, Active Directory, AWS Pentesting
|
||||
- OWASP Top 100 Vulnerabilities
|
||||
- Red Team Tools
|
||||
- `claude-code-guide` skill
|
||||
|
||||
### Changed
|
||||
|
||||
- Total skills count: ~90
|
||||
|
||||
---
|
||||
|
||||
## [0.3.0] - 2026-01-17 - "First Stable Registry"
|
||||
|
||||
### Added
|
||||
|
||||
- Complete skill registry table in README
|
||||
- GitHub workflow automation
|
||||
- SEO optimizations
|
||||
|
||||
### Changed
|
||||
|
||||
- Total skills count: **71**
|
||||
|
||||
---
|
||||
|
||||
## [0.2.0] - 2026-01-16 - "Official Skills"
|
||||
|
||||
### Added
|
||||
|
||||
- **Official Anthropic skills** integration
|
||||
- **Vercel Labs skills** integration
|
||||
- BlockRun: Agent Wallet for LLM Micropayments
|
||||
- 7 new skills from GitHub analysis
|
||||
|
||||
### Changed
|
||||
|
||||
- Total skills count: ~65
|
||||
|
||||
---
|
||||
|
||||
## [0.1.0] - 2026-01-15 - "Initial Release"
|
||||
|
||||
### Added
|
||||
|
||||
- **58 core skills** aggregated from community:
|
||||
- [obra/superpowers](https://github.com/obra/superpowers) - Original Superpowers
|
||||
- [guanyang/antigravity-skills](https://github.com/guanyang/antigravity-skills) - Core extensions
|
||||
- [diet103/claude-code-infrastructure-showcase](https://github.com/diet103/claude-code-infrastructure-showcase) - Infrastructure skills
|
||||
- [ChrisWiles/claude-code-showcase](https://github.com/ChrisWiles/claude-code-showcase) - React UI patterns
|
||||
- [travisvn/awesome-claude-skills](https://github.com/travisvn/awesome-claude-skills) - Loki Mode
|
||||
- [alirezarezvani/claude-skills](https://github.com/alirezarezvani/claude-skills) - Senior Engineering
|
||||
- Universal **SKILL.md** format
|
||||
- Compatibility with Claude Code, Gemini CLI, Cursor, Copilot, Antigravity
|
||||
|
||||
---
|
||||
|
||||
## Credits
|
||||
|
||||
See [README.md](README.md#credits--sources) for full attribution.
|
||||
|
||||
## License
|
||||
|
||||
MIT License - See [LICENSE](LICENSE) for details.
|
||||
364
README.md
364
README.md
@@ -1,23 +1,60 @@
|
||||
# 🌌 Antigravity Awesome Skills: The Ultimate Claude Code Skills Collection
|
||||
# 🌌 Antigravity Awesome Skills: 179+ Agentic Skills for Claude Code, Gemini CLI, Cursor, Copilot & More
|
||||
|
||||
> **The Ultimate Collection of 130+ Agentic Skills for Claude Code (Antigravity)**
|
||||
> **The Ultimate Collection of 179+ Universal Agentic Skills for AI Coding Assistants — Claude Code, Gemini CLI, Codex CLI, Antigravity IDE, GitHub Copilot, Cursor, OpenCode**
|
||||
|
||||
[](https://opensource.org/licenses/MIT)
|
||||
[](https://claude.ai)
|
||||
[](https://github.com/guanyang/antigravity-skills)
|
||||
[](https://claude.ai)
|
||||
[](https://github.com/google-gemini/gemini-cli)
|
||||
[](https://github.com/openai/codex)
|
||||
[](https://cursor.sh)
|
||||
[](https://github.com/features/copilot)
|
||||
[](https://github.com/opencode-ai/opencode)
|
||||
[](https://github.com/anthropics/antigravity)
|
||||
|
||||
**Antigravity Awesome Skills** is the ultimate **Claude Code Skills** collection—a curated, battle-tested library of **131 high-performance skills** compatible with both **Antigravity** and **Claude Code**. This repository provides the essential **Claude Code skills** needed to transform your AI assistant into a full-stack digital agency, including official capabilities from **Anthropic** and **Vercel Labs**.
|
||||
**Antigravity Awesome Skills** is a curated, battle-tested library of **179 high-performance agentic skills** designed to work seamlessly across all major AI coding assistants:
|
||||
|
||||
- 🟣 **Claude Code** (Anthropic CLI)
|
||||
- 🔵 **Gemini CLI** (Google DeepMind)
|
||||
- 🟢 **Codex CLI** (OpenAI)
|
||||
- 🔴 **Antigravity IDE** (Google DeepMind)
|
||||
- 🩵 **GitHub Copilot** (VSCode Extension)
|
||||
- 🟠 **Cursor** (AI-native IDE)
|
||||
- ⚪ **OpenCode** (Open-source CLI)
|
||||
|
||||
This repository provides essential skills to transform your AI assistant into a **full-stack digital agency**, including official capabilities from **Anthropic**, **OpenAI**, **Google**, and **Vercel Labs**.
|
||||
|
||||
## 📍 Table of Contents
|
||||
|
||||
- [🔌 Compatibility](#-compatibility)
|
||||
- [Features & Categories](#features--categories)
|
||||
- [Full Skill Registry](#full-skill-registry-131131)
|
||||
- [Full Skill Registry](#full-skill-registry-155155)
|
||||
- [Installation](#installation)
|
||||
- [How to Contribute](#how-to-contribute)
|
||||
- [Credits & Sources](#credits--sources)
|
||||
- [License](#license)
|
||||
|
||||
Whether you are using the Google Deepmind Antigravity framework or the standard Anthropic Claude Code CLI, these skills are designed to drop right in and supercharge your agent.
|
||||
---
|
||||
|
||||
## 🔌 Compatibility
|
||||
|
||||
These skills follow the universal **SKILL.md** format and work with any AI coding assistant that supports agentic skills:
|
||||
|
||||
| Tool | Type | Compatibility | Installation Path |
|
||||
| ------------------- | --------- | ------------- | ---------------------------------------- |
|
||||
| **Claude Code** | CLI | ✅ Full | `.claude/skills/` or `.agent/skills/` |
|
||||
| **Gemini CLI** | CLI | ✅ Full | `.gemini/skills/` or `.agent/skills/` |
|
||||
| **Codex CLI** | CLI | ✅ Full | `.codex/skills/` or `.agent/skills/` |
|
||||
| **Antigravity IDE** | IDE | ✅ Full | `.agent/skills/` |
|
||||
| **Cursor** | IDE | ✅ Full | `.cursor/skills/` or project root |
|
||||
| **GitHub Copilot** | Extension | ⚠️ Partial | Copy skill content to `.github/copilot/` |
|
||||
| **OpenCode** | CLI | ✅ Full | `.opencode/skills/` or `.agent/skills/` |
|
||||
|
||||
> [!TIP]
|
||||
> Most tools auto-discover skills in `.agent/skills/`. For maximum compatibility, clone to this directory.
|
||||
|
||||
---
|
||||
|
||||
Whether you are using **Gemini CLI**, **Claude Code**, **Codex CLI**, **Cursor**, **GitHub Copilot**, **Antigravity**, or **OpenCode**, these skills are designed to drop right in and supercharge your AI agent.
|
||||
|
||||
This repository aggregates the best capabilities from across the open-source community, transforming your AI assistant into a full-stack digital agency capable of Engineering, Design, Security, Marketing, and Autonomous Operations.
|
||||
|
||||
@@ -25,97 +62,211 @@ This repository aggregates the best capabilities from across the open-source com
|
||||
|
||||
The repository is organized into several key areas of expertise:
|
||||
|
||||
| Category | Skills Included |
|
||||
| :----------------------- | :------------------------------------------------------------------------------------- |
|
||||
| **🎨 Creative & Design** | UI/UX Pro Max, Frontend Design, Canvas, Algorithmic Art, Theme Factory, D3 Viz |
|
||||
| **🛠️ Development** | TDD, Systematic Debugging, Webapp Testing, Backend/Frontend Guidelines, React Patterns |
|
||||
| **🛡️ Cybersecurity** | Ethical Hacking, AWS Pentesting, OWASP Top 100, Pentest Checklists |
|
||||
| **🛸 Autonomous** | **Loki Mode** (Startup-in-a-box), Subagent Orchestration, Parallel Execution |
|
||||
| **📈 Strategy** | Product Manager Toolkit, Content Creator, ASO, Doc Co-authoring, Brainstorming |
|
||||
| **🏗️ Infrastructure** | Linux Shell Scripting, Git Worktrees, Conventional Commits, File Organization |
|
||||
| Category | Skills Count | Key Skills Included |
|
||||
| :-------------------------- | :----------- | :--------------------------------------------------------------------------------------------------------------------------- |
|
||||
| **🛸 Autonomous & Agentic** | **~8** | Loki Mode (Startup-in-a-box), Subagent Driven Dev, Dispatching Parallel Agents, Planning With Files, Skill Creator/Developer |
|
||||
| **🔌 Integrations & APIs** | **~25** | Stripe, Firebase, Supabase, Vercel, Clerk Auth, Twilio, Discord Bot, Slack Bot, GraphQL, AWS Serverless |
|
||||
| **🛡️ Cybersecurity** | **~50** | Ethical Hacking, Metasploit, Burp Suite, SQLMap, Active Directory, AWS/Cloud Pentesting, OWASP Top 100, Red Team Tools |
|
||||
| **🎨 Creative & Design** | **~10** | UI/UX Pro Max, Frontend Design, Canvas, Algorithmic Art, Theme Factory, D3 Viz, Web Artifacts |
|
||||
| **🛠️ Development** | **~25** | TDD, Systematic Debugging, React Patterns, Backend/Frontend Guidelines, Senior Fullstack, Software Architecture |
|
||||
| **🏗️ Infrastructure & Git** | **~8** | Linux Shell Scripting, Git Worktrees, Git Pushing, Conventional Commits, File Organization, GitHub Workflow Automation |
|
||||
| **🤖 AI Agents & LLM** | **~30** | LangGraph, CrewAI, Langfuse, RAG Engineer, Prompt Engineer, Voice Agents, Browser Automation, Agent Memory Systems |
|
||||
| **🔄 Workflow & Planning** | **~6** | Writing Plans, Executing Plans, Concise Planning, Verification Before Completion, Code Review (Requesting/Receiving) |
|
||||
| **📄 Document Processing** | **~4** | DOCX (Official), PDF (Official), PPTX (Official), XLSX (Official) |
|
||||
| **🧪 Testing & QA** | **~4** | Webapp Testing, Playwright Automation, Test Fixing, Testing Patterns |
|
||||
| **📈 Product & Strategy** | **~8** | Product Manager Toolkit, Content Creator, ASO, Doc Co-authoring, Brainstorming, Internal Comms |
|
||||
| **📣 Marketing & Growth** | **~23** | Page CRO, Copywriting, SEO Audit, Paid Ads, Email Sequence, Pricing Strategy, Referral Program, Launch Strategy |
|
||||
| **🚀 Maker Tools** | **~11** | Micro-SaaS Launcher, Browser Extension Builder, Telegram Bot, AI Wrapper Product, Viral Generator, 3D Web Experience |
|
||||
|
||||
---
|
||||
|
||||
## Full Skill Registry (131/131)
|
||||
## Full Skill Registry (179/179)
|
||||
|
||||
Below is the complete list of available skills. Each skill folder contains a `SKILL.md` that can be imported into Antigravity or Claude Code.
|
||||
|
||||
> [!NOTE] > **Document Skills**: We provide both **community** and **official Anthropic** versions for DOCX, PDF, PPTX, and XLSX. Locally, the official versions are used by default (via symlinks). In the repository, both versions are available for flexibility.
|
||||
|
||||
| Skill Name | Description | Path |
|
||||
| :--------------------------------- | :-------------------------------------------------------------- | :--------------------------------------------- |
|
||||
| **Address GitHub Comments** | Systematic PR feedback handling using gh CLI. | `skills/address-github-comments` ⭐ NEW |
|
||||
| **Algorithmic Art** | Creative generative art using p5.js and seeded randomness. | `skills/algorithmic-art` |
|
||||
| **App Store Optimization** | Complete ASO toolkit for iOS and Android app performance. | `skills/app-store-optimization` |
|
||||
| **Autonomous Agent Patterns** | Design patterns for autonomous coding agents and tools. | `skills/autonomous-agent-patterns` ⭐ NEW |
|
||||
| **AWS Pentesting** | Specialized security assessment for Amazon Web Services. | `skills/aws-penetration-testing` |
|
||||
| **Backend Guidelines** | Core architecture patterns for Node/Express microservices. | `skills/backend-dev-guidelines` |
|
||||
| **Claude Code Guide** | Master guide for configuring and using Claude Code. | `skills/claude-code-guide` ⭐ NEW |
|
||||
| **Concise Planning** | Atomic, actionable task planning and checklists. | `skills/concise-planning` ⭐ NEW |
|
||||
| **Brainstorming** | Requirement discovery and intent exploration framework. | `skills/brainstorming` |
|
||||
| **Brand Guidelines (Anthropic)** | Official Anthropic brand styling and visual standards. | `skills/brand-guidelines-anthropic` ⭐ NEW |
|
||||
| **Brand Guidelines (Community)** | Community-contributed brand guidelines and templates. | `skills/brand-guidelines-community` |
|
||||
| **Bun Development** | Modern JavaScript/TypeScript development with Bun runtime. | `skills/bun-development` ⭐ NEW |
|
||||
| **Canvas Design** | Beautiful static visual design in PDF and PNG. | `skills/canvas-design` |
|
||||
| **Claude D3.js** | Advanced data visualization with D3.js. | `skills/claude-d3js-skill` |
|
||||
| **Content Creator** | SEO-optimized marketing and brand voice toolkit. | `skills/content-creator` |
|
||||
| **Core Components** | Design system tokens and baseline UI patterns. | `skills/core-components` |
|
||||
| **Dispatching Parallel Agents** | Work on independent tasks without shared state. | `skills/dispatching-parallel-agents` |
|
||||
| **Doc Co-authoring** | Structured workflow for technical documentation. | `skills/doc-coauthoring` |
|
||||
| **DOCX (Official)** | Official Anthropic MS Word document manipulation. | `skills/docx-official` ⭐ NEW |
|
||||
| **Ethical Hacking** | Comprehensive penetration testing lifecycle methodology. | `skills/ethical-hacking-methodology` |
|
||||
| **Executing Plans** | Execute written implementation plans in structured sessions. | `skills/executing-plans` |
|
||||
| **File Organizer** | Context-aware file organization and duplicate cleanup. | `skills/file-organizer` |
|
||||
| **Finishing Dev Branch** | Structured workflow for merging, PRs, and branch cleanup. | `skills/finishing-a-development-branch` |
|
||||
| **Frontend Design** | Production-grade UI component implementation. | `skills/frontend-design` |
|
||||
| **Frontend Guidelines** | Modern React/TS development patterns and file structure. | `skills/frontend-dev-guidelines` |
|
||||
| **Git Pushing** | Automated staging and conventional commits. | `skills/git-pushing` |
|
||||
| **GitHub Workflow Automation** | AI-powered PR reviews, issue triage, and CI/CD integration. | `skills/github-workflow-automation` ⭐ NEW |
|
||||
| **Internal Comms (Anthropic)** | Official Anthropic corporate communication templates. | `skills/internal-comms-anthropic` ⭐ NEW |
|
||||
| **Internal Comms (Community)** | Community-contributed communication templates. | `skills/internal-comms-community` |
|
||||
| **JavaScript Mastery** | 33+ essential JavaScript concepts every developer should know. | `skills/javascript-mastery` ⭐ NEW |
|
||||
| **Kaizen** | Continuous improvement and error-proofing (Poka-Yoke). | `skills/kaizen` |
|
||||
| **Linux Shell Scripting** | Production-ready shell scripts for automation. | `skills/linux-shell-scripting` |
|
||||
| **LLM App Patterns** | RAG pipelines, agent architectures, and LLMOps patterns. | `skills/llm-app-patterns` ⭐ NEW |
|
||||
| **Loki Mode** | Fully autonomous startup development engine. | `skills/loki-mode` |
|
||||
| **MCP Builder** | High-quality Model Context Protocol (MCP) server creation. | `skills/mcp-builder` |
|
||||
| **NotebookLM** | Source-grounded querying via Google NotebookLM. | `skills/notebooklm` |
|
||||
| **PDF (Official)** | Official Anthropic PDF document manipulation. | `skills/pdf-official` ⭐ NEW |
|
||||
| **Pentest Checklist** | Structured security assessment planning and scoping. | `skills/pentest-checklist` |
|
||||
| **Planning With Files** | Manus-style file-based planning for complex tasks. | `skills/planning-with-files` |
|
||||
| **Playwright Automation** | Complete browser automation and testing with Playwright. | `skills/playwright-skill` |
|
||||
| **PPTX (Official)** | Official Anthropic PowerPoint manipulation. | `skills/pptx-official` ⭐ NEW |
|
||||
| **Product Toolkit** | RICE prioritization and product discovery frameworks. | `skills/product-manager-toolkit` |
|
||||
| **Prompt Engineering** | Expert patterns for LLM instruction optimization. | `skills/prompt-engineering` |
|
||||
| **Prompt Library** | Curated role-based and task-specific prompt templates. | `skills/prompt-library` ⭐ NEW |
|
||||
| **React Best Practices** | Vercel's 40+ performance optimization rules for React. | `skills/react-best-practices` ⭐ NEW (Vercel) |
|
||||
| **React UI Patterns** | Standardized loading states and error handling for React. | `skills/react-ui-patterns` |
|
||||
| **Receiving Code Review** | Technical verification of code review feedback. | `skills/receiving-code-review` |
|
||||
| **Requesting Code Review** | Pre-merge requirements verification workflow. | `skills/requesting-code-review` |
|
||||
| **Senior Architect** | Scalable system design and architecture diagrams. | `skills/senior-architect` |
|
||||
| **Senior Fullstack** | Comprehensive fullstack guide (React, Node, Postgres). | `skills/senior-fullstack` |
|
||||
| **Skill Creator** | Meta-skill for building high-performance agentic skills. | `skills/skill-creator` |
|
||||
| **Skill Developer** | Create and manage skills using Anthropic best practices. | `skills/skill-developer` |
|
||||
| **Slack GIF Creator** | Create animated GIFs optimized for Slack. | `skills/slack-gif-creator` |
|
||||
| **Software Architecture** | Quality-focused design principles and analysis. | `skills/software-architecture` |
|
||||
| **Subagent Driven Dev** | Orchestrate independent subtasks in current session. | `skills/subagent-driven-development` |
|
||||
| **Systematic Debugging** | Root cause analysis and structured fix verification. | `skills/systematic-debugging` |
|
||||
| **TDD** | Test-Driven Development workflow and red-green-refactor. | `skills/test-driven-development` |
|
||||
| **Test Fixing** | Systematically fix failing tests using smart error grouping. | `skills/test-fixing` |
|
||||
| **Testing Patterns** | Jest patterns, factories, and TDD workflow strategies. | `skills/testing-patterns` |
|
||||
| **Theme Factory** | Toolkit for styling artifacts with pre-set or generated themes. | `skills/theme-factory` |
|
||||
| **Top 100 Vulnerabilities** | OWASP-aligned web vulnerability taxonomy and mitigations. | `skills/top-web-vulnerabilities` |
|
||||
| **UI/UX Pro Max** | Advanced design intelligence and 50+ styling options. | `skills/ui-ux-pro-max` |
|
||||
| **Using Git Worktrees** | Isolated workspaces for safe feature development. | `skills/using-git-worktrees` |
|
||||
| **Using Superpowers** | Establish skill usage protocols at conversation start. | `skills/using-superpowers` |
|
||||
| **Verification Before Completion** | Run verification commands before claiming success. | `skills/verification-before-completion` |
|
||||
| **Web Artifacts** | Complex React/Tailwind/Shadcn UI artifact builder. | `skills/web-artifacts-builder` |
|
||||
| **Web Design Guidelines** | Vercel's 100+ UI/UX audit rules (accessibility, performance). | `skills/web-design-guidelines` ⭐ NEW (Vercel) |
|
||||
| **Webapp Testing** | Local web application testing with Playwright. | `skills/webapp-testing` |
|
||||
| **Workflow Automation** | Multi-step automations, API integration, AI-native pipelines. | `skills/workflow-automation` ⭐ NEW |
|
||||
| **Writing Plans** | Create specs for multi-step tasks before coding. | `skills/writing-plans` |
|
||||
| **Writing Skills** | Create and verify skills before deployment. | `skills/writing-skills` |
|
||||
| **XLSX (Official)** | Official Anthropic Excel spreadsheet manipulation. | `skills/xlsx-official` ⭐ NEW |
|
||||
| Skill Name | Description | Path |
|
||||
| :-------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------- |
|
||||
| **3D Web Experience** | Expert in building 3D experiences for the web - Three.js, React Three Fiber, Spline, WebGL. | `skills/3d-web-experience` |
|
||||
| **A/B Test Setup** | Plan and implement A/B tests with proper experiment design, statistical significance, and test analysis. | `skills/ab-test-setup` |
|
||||
| **Active Directory Attacks** | This skill should be used when the user asks to "attack Active Directory", "exploit AD", "Kerberoasting", "DCSync", "pass-the-hash", "BloodHound enumeration", "Golden Ticket", "Silver Ticket", "AS-REP roasting", "NTLM relay", or needs guidance on Windows domain penetration testing. | `skills/active-directory-attacks` |
|
||||
| **Address GitHub Comments** | Use when you need to address review or issue comments on an open GitHub Pull Request using the gh CLI. | `skills/address-github-comments` |
|
||||
| **Agent Evaluation** | Testing and benchmarking LLM agents including behavioral testing, capability assessment, reliability metrics. | `skills/agent-evaluation` |
|
||||
| **Agent Manager Skill** | Use when you need to manage multiple local CLI agents via tmux sessions (start/stop/monitor/assign) with cron-friendly scheduling. | `skills/agent-manager-skill` |
|
||||
| **Agent Memory Systems** | Memory architecture for agents: short-term, long-term (vector stores), and cognitive architectures. | `skills/agent-memory-systems` |
|
||||
| **Agent Tool Builder** | Tool design from schema to error handling. JSON Schema best practices, validation, and MCP. | `skills/agent-tool-builder` |
|
||||
| **AI Agents Architect** | Expert in autonomous AI agents. Tool use, memory systems, planning strategies, multi-agent orchestration. | `skills/ai-agents-architect` |
|
||||
| **AI Product** | LLM integration patterns, RAG architecture, prompt engineering, AI UX, and cost optimization. | `skills/ai-product` |
|
||||
| **AI Wrapper Product** | Building products that wrap AI APIs into focused tools. Prompt engineering, cost management. | `skills/ai-wrapper-product` |
|
||||
| **Algolia Search** | Algolia search implementation, indexing strategies, React InstantSearch, relevance tuning. | `skills/algolia-search` |
|
||||
| **Algorithmic Art** | Creating algorithmic art using p5. | `skills/algorithmic-art` |
|
||||
| **Analytics Tracking** | Set up analytics tracking with GA4, GTM, and custom event implementations for marketing measurement. | `skills/analytics-tracking` |
|
||||
| **API Fuzzing for Bug Bounty** | This skill should be used when the user asks to "test API security", "fuzz APIs", "find IDOR vulnerabilities", "test REST API", "test GraphQL", "API penetration testing", "bug bounty API testing", or needs guidance on API security assessment techniques. | `skills/api-fuzzing-bug-bounty` |
|
||||
| **App Store Optimization** | Complete App Store Optimization (ASO) toolkit for researching, optimizing, and tracking mobile app performance on Apple App Store and Google Play Store. | `skills/app-store-optimization` |
|
||||
| **Autonomous Agent Patterns** | "Design patterns for building autonomous coding agents. | `skills/autonomous-agent-patterns` |
|
||||
| **Autonomous Agents** | AI systems that independently decompose goals, plan actions, execute tools. ReAct, reflection. | `skills/autonomous-agents` |
|
||||
| **AWS Penetration Testing** | This skill should be used when the user asks to "pentest AWS", "test AWS security", "enumerate IAM", "exploit cloud infrastructure", "AWS privilege escalation", "S3 bucket testing", "metadata SSRF", "Lambda exploitation", or needs guidance on Amazon Web Services security assessment. | `skills/aws-penetration-testing` |
|
||||
| **AWS Serverless** | Serverless on AWS. Lambda, API Gateway, DynamoDB, SQS/SNS, SAM/CDK deployment. | `skills/aws-serverless` |
|
||||
| **Azure Functions** | Azure Functions patterns. Isolated worker model, Durable Functions, cold start optimization. | `skills/azure-functions` |
|
||||
| **Backend Guidelines** | Comprehensive backend development guide for Node. | `skills/backend-dev-guidelines` |
|
||||
| **BlockRun** | Agent wallet for LLM micropayments. Use when user needs capabilities Claude lacks (image generation, real-time X/Twitter data) or explicitly requests external models ("blockrun", "use grok", "use gpt", "dall-e", "deepseek"). | `skills/blockrun` |
|
||||
| **Brainstorming** | "You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. | `skills/brainstorming` |
|
||||
| **Brand Guidelines (Anthropic)** | Applies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. | `skills/brand-guidelines-anthropic` |
|
||||
| **Brand Guidelines (Community)** | Applies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. | `skills/brand-guidelines-community` |
|
||||
| **Broken Authentication Testing** | This skill should be used when the user asks to "test for broken authentication vulnerabilities", "assess session management security", "perform credential stuffing tests", "evaluate password policies", "test for session fixation", or "identify authentication bypass flaws". | `skills/broken-authentication` |
|
||||
| **Browser Automation** | Browser automation with Playwright and Puppeteer. Testing, scraping, agentic control. | `skills/browser-automation` |
|
||||
| **Browser Extension Builder** | Building browser extensions - Chrome, Firefox. Manifest v3, content scripts, monetization. | `skills/browser-extension-builder` |
|
||||
| **BullMQ Specialist** | BullMQ for Redis-backed job queues, background processing in Node.js/TypeScript. | `skills/bullmq-specialist` |
|
||||
| **Bun Development** | "Modern JavaScript/TypeScript development with Bun runtime. | `skills/bun-development` |
|
||||
| **Burp Suite Web Application Testing** | This skill should be used when the user asks to "intercept HTTP traffic", "modify web requests", "use Burp Suite for testing", "perform web vulnerability scanning", "test with Burp Repeater", "analyze HTTP history", or "configure proxy for web testing". | `skills/burp-suite-testing` |
|
||||
| **Canvas Design** | Create beautiful visual art in . | `skills/canvas-design` |
|
||||
| **Claude Code Guide** | Master guide for using Claude Code effectively. | `skills/claude-code-guide` |
|
||||
| **Claude D3.js** | Creating interactive data visualisations using d3. | `skills/claude-d3js-skill` |
|
||||
| **Clerk Auth** | Clerk auth implementation, middleware, organizations, webhooks, user sync. | `skills/clerk-auth` |
|
||||
| **Cloud Penetration Testing** | This skill should be used when the user asks to "perform cloud penetration testing", "assess Azure or AWS or GCP security", "enumerate cloud resources", "exploit cloud misconfigurations", "test O365 security", "extract secrets from cloud environments", or "audit cloud infrastructure". | `skills/cloud-penetration-testing` |
|
||||
| **Computer Use Agents** | AI agents that interact with computers like humans. Screen control, sandboxing. | `skills/computer-use-agents` |
|
||||
| **Concise Planning** | Use when a user asks for a plan for a coding task, to generate a clear, actionable, and atomic checklist. | `skills/concise-planning` |
|
||||
| **Competitor Alternatives** | Create compelling competitor comparison and alternative pages for SEO and conversions. | `skills/competitor-alternatives` |
|
||||
| **Content Creator** | Create SEO-optimized marketing content with consistent brand voice. | `skills/content-creator` |
|
||||
| **Context Window Management** | Managing LLM context windows. Summarization, trimming, routing. | `skills/context-window-management` |
|
||||
| **Conversation Memory** | Persistent memory for LLM conversations. Short-term, long-term, entity-based memory. | `skills/conversation-memory` |
|
||||
| **Core Components** | Core component library and design system patterns. | `skills/core-components` |
|
||||
| **Copy Editing** | Edit and polish existing marketing copy with a systematic seven-sweeps framework. | `skills/copy-editing` |
|
||||
| **Copywriting** | Write compelling marketing copy for homepages, landing pages, pricing pages, and feature pages. | `skills/copywriting` |
|
||||
| **CrewAI** | Role-based multi-agent framework. Agent design, task definition, crew orchestration. | `skills/crewai` |
|
||||
| **Cross-Site Scripting and HTML Injection Testing** | This skill should be used when the user asks to "test for XSS vulnerabilities", "perform cross-site scripting attacks", "identify HTML injection flaws", "exploit client-side injection vulnerabilities", "steal cookies via XSS", or "bypass content security policies". | `skills/xss-html-injection` |
|
||||
| **Discord Bot Architect** | Production Discord bots. Discord.js, Pycord, slash commands, sharding. | `skills/discord-bot-architect` |
|
||||
| **Dispatching Parallel Agents** | Use when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies. | `skills/dispatching-parallel-agents` |
|
||||
| **Doc Co-authoring** | Guide users through a structured workflow for co-authoring documentation. | `skills/doc-coauthoring` |
|
||||
| **DOCX (Official)** | "Comprehensive document creation, editing, and analysis with support for tracked changes, comments, formatting preservation, and text extraction. | `skills/docx-official` |
|
||||
| **Email Sequence** | Create and optimize email sequences, drip campaigns, and lifecycle email programs. | `skills/email-sequence` |
|
||||
| **Email Systems** | Transactional email, marketing automation, deliverability, infrastructure. | `skills/email-systems` |
|
||||
| **Ethical Hacking Methodology** | This skill should be used when the user asks to "learn ethical hacking", "understand penetration testing lifecycle", "perform reconnaissance", "conduct security scanning", "exploit vulnerabilities", or "write penetration test reports". | `skills/ethical-hacking-methodology` |
|
||||
| **Executing Plans** | Use when you have a written implementation plan to execute in a separate session with review checkpoints. | `skills/executing-plans` |
|
||||
| **File Organizer** | Intelligently organizes files and folders by understanding context, finding duplicates, and suggesting better organizational structures. | `skills/file-organizer` |
|
||||
| **File Path Traversal Testing** | This skill should be used when the user asks to "test for directory traversal", "exploit path traversal vulnerabilities", "read arbitrary files through web applications", "find LFI vulnerabilities", or "access files outside web root". | `skills/file-path-traversal` |
|
||||
| **File Uploads** | File uploads and cloud storage. S3, Cloudflare R2, presigned URLs. | `skills/file-uploads` |
|
||||
| **Finishing Dev Branch** | Use when implementation is complete, all tests pass, and you need to decide how to integrate the work - guides completion of development work by presenting structured options for merge, PR, or cleanup. | `skills/finishing-a-development-branch` |
|
||||
| **Firebase** | Firebase Auth, Firestore, Realtime Database, Cloud Functions, Storage. | `skills/firebase` |
|
||||
| **Form CRO** | Optimize lead capture forms, contact forms, demo request forms for higher conversion rates. | `skills/form-cro` |
|
||||
| **Free Tool Strategy** | Plan and build free tools for marketing, lead generation, and SEO value. | `skills/free-tool-strategy` |
|
||||
| **Frontend Design** | Create distinctive, production-grade frontend interfaces with high design quality. | `skills/frontend-design` |
|
||||
| **Frontend Guidelines** | Frontend development guidelines for React/TypeScript applications. | `skills/frontend-dev-guidelines` |
|
||||
| **GCP Cloud Run** | Serverless on GCP. Cloud Run services and functions, Pub/Sub. | `skills/gcp-cloud-run` |
|
||||
| **Git Pushing** | Stage, commit, and push git changes with conventional commit messages. | `skills/git-pushing` |
|
||||
| **GitHub Workflow Automation** | "Automate GitHub workflows with AI assistance. | `skills/github-workflow-automation` |
|
||||
| **GraphQL** | Schema design, resolvers, DataLoader, federation, Apollo/urql integration. | `skills/graphql` |
|
||||
| **HTML Injection Testing** | This skill should be used when the user asks to "test for HTML injection", "inject HTML into web pages", "perform HTML injection attacks", "deface web applications", or "test content injection vulnerabilities". | `skills/html-injection-testing` |
|
||||
| **HubSpot Integration** | HubSpot CRM integration. OAuth, CRM objects, webhooks, custom objects. | `skills/hubspot-integration` |
|
||||
| **IDOR Vulnerability Testing** | This skill should be used when the user asks to "test for insecure direct object references," "find IDOR vulnerabilities," "exploit broken access control," "enumerate user IDs or object references," or "bypass authorization to access other users' data. | `skills/idor-testing` |
|
||||
| **Inngest** | Inngest for serverless background jobs, event-driven workflows. | `skills/inngest` |
|
||||
| **Interactive Portfolio** | Building portfolios that land jobs. Developer, designer portfolios. | `skills/interactive-portfolio` |
|
||||
| **Internal Comms (Anthropic)** | A set of resources to help me write all kinds of internal communications, using the formats that my company likes to use. | `skills/internal-comms-anthropic` |
|
||||
| **Internal Comms (Community)** | A set of resources to help me write all kinds of internal communications, using the formats that my company likes to use. | `skills/internal-comms-community` |
|
||||
| **JavaScript Mastery** | "Comprehensive JavaScript reference covering 33+ essential concepts every developer should know. | `skills/javascript-mastery` |
|
||||
| **Kaizen** | Guide for continuous improvement, error proofing, and standardization. | `skills/kaizen` |
|
||||
| **Langfuse** | Open-source LLM observability. Tracing, prompt management, evaluation. | `skills/langfuse` |
|
||||
| **LangGraph** | Stateful, multi-actor AI applications. Graph construction, persistence. | `skills/langgraph` |
|
||||
| **Launch Strategy** | Plan product launches, feature announcements, and go-to-market strategies. | `skills/launch-strategy` |
|
||||
| **Linux Privilege Escalation** | This skill should be used when the user asks to "escalate privileges on Linux", "find privesc vectors on Linux systems", "exploit sudo misconfigurations", "abuse SUID binaries", "exploit cron jobs for root access", "enumerate Linux systems for privilege escalation", or "gain root access from low-privilege shell". | `skills/linux-privilege-escalation` |
|
||||
| **Linux Shell Scripting** | This skill should be used when the user asks to "create bash scripts", "automate Linux tasks", "monitor system resources", "backup files", "manage users", or "write production shell scripts". | `skills/linux-shell-scripting` |
|
||||
| **LLM App Patterns** | "Production-ready patterns for building LLM applications. | `skills/llm-app-patterns` |
|
||||
| **Loki Mode** | Multi-agent autonomous startup system for Claude Code. | `skills/loki-mode` |
|
||||
| **Marketing Ideas** | 140 proven SaaS marketing ideas and strategies organized by category. | `skills/marketing-ideas` |
|
||||
| **Marketing Psychology** | 70+ mental models and psychological principles for marketing and persuasion. | `skills/marketing-psychology` |
|
||||
| **MCP Builder** | Guide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. | `skills/mcp-builder` |
|
||||
| **Metasploit Framework** | This skill should be used when the user asks to "use Metasploit for penetration testing", "exploit vulnerabilities with msfconsole", "create payloads with msfvenom", "perform post-exploitation", "use auxiliary modules for scanning", or "develop custom exploits". | `skills/metasploit-framework` |
|
||||
| **Moodle External API Development** | Create custom external web service APIs for Moodle LMS. Use when implementing web services for course management, user tracking, quiz operations, or custom plugin functionality. Covers parameter validation, database operations, error handling, service registration, and Moodle coding standards. | `skills/moodle-external-api-development` |
|
||||
| **Micro-SaaS Launcher** | Launching small SaaS products fast. Idea validation, MVP, pricing. | `skills/micro-saas-launcher` |
|
||||
| **Neon Postgres** | Neon serverless Postgres, branching, connection pooling, Prisma integration. | `skills/neon-postgres` |
|
||||
| **Network 101** | This skill should be used when the user asks to "set up a web server", "configure HTTP or HTTPS", "perform SNMP enumeration", "configure SMB shares", "test network services", or needs guidance on configuring and testing network services for penetration testing labs. | `skills/network-101` |
|
||||
| **Next.js Supabase Auth** | Supabase Auth with Next.js App Router. Auth middleware. | `skills/nextjs-supabase-auth` |
|
||||
| **NotebookLM** | Use this skill to query your Google NotebookLM notebooks directly from Claude Code for source-grounded, citation-backed answers from Gemini. | `skills/notebooklm` |
|
||||
| **Notion Template Business** | Building and selling Notion templates. Design, pricing, marketing. | `skills/notion-template-business` |
|
||||
| **Onboarding CRO** | Optimize post-signup onboarding, user activation, and time-to-value. | `skills/onboarding-cro` |
|
||||
| **PDF (Official)** | Comprehensive PDF manipulation toolkit for extracting text and tables, creating new PDFs, merging/splitting documents, and handling forms. | `skills/pdf-official` |
|
||||
| **Pentest Checklist** | This skill should be used when the user asks to "plan a penetration test", "create a security assessment checklist", "prepare for penetration testing", "define pentest scope", "follow security testing best practices", or needs a structured methodology for penetration testing engagements. | `skills/pentest-checklist` |
|
||||
| **Pentest Commands** | This skill should be used when the user asks to "run pentest commands", "scan with nmap", "use metasploit exploits", "crack passwords with hydra or john", "scan web vulnerabilities with nikto", "enumerate networks", or needs essential penetration testing command references. | `skills/pentest-commands` |
|
||||
| **Page CRO** | Conversion rate optimization for marketing pages - homepages, landing pages, pricing pages. | `skills/page-cro` |
|
||||
| **Paid Ads** | Create and optimize paid ad campaigns on Google Ads, Meta, LinkedIn, and other platforms. | `skills/paid-ads` |
|
||||
| **Paywall Upgrade CRO** | Optimize in-app paywalls, upgrade screens, and freemium conversion moments. | `skills/paywall-upgrade-cro` |
|
||||
| **Personal Tool Builder** | Building custom tools. Rapid prototyping, local-first apps, CLI tools. | `skills/personal-tool-builder` |
|
||||
| **Plaid Fintech** | Plaid API for banking. Link token flows, transactions, ACH. | `skills/plaid-fintech` |
|
||||
| **Planning With Files** | Implements Manus-style file-based planning for complex tasks. | `skills/planning-with-files` |
|
||||
| **Playwright Automation** | Complete browser automation with Playwright. | `skills/playwright-skill` |
|
||||
| **Popup CRO** | Create and optimize popups, modals, and overlays for conversion. | `skills/popup-cro` |
|
||||
| **PPTX (Official)** | "Presentation creation, editing, and analysis. | `skills/pptx-official` |
|
||||
| **Privilege Escalation Methods** | This skill should be used when the user asks to "escalate privileges", "get root access", "become administrator", "privesc techniques", "abuse sudo", "exploit SUID binaries", "Kerberoasting", "pass-the-ticket", "token impersonation", or needs guidance on post-exploitation privilege escalation for Linux or Windows systems. | `skills/privilege-escalation-methods` |
|
||||
| **Pricing Strategy** | Design pricing, packaging, and monetization strategy for SaaS products. | `skills/pricing-strategy` |
|
||||
| **Product Toolkit** | Comprehensive toolkit for product managers including RICE prioritization, customer interview analysis, PRD templates, discovery frameworks, and go-to-market strategies. | `skills/product-manager-toolkit` |
|
||||
| **Prompt Caching** | Caching strategies for LLM prompts. Anthropic caching, CAG. | `skills/prompt-caching` |
|
||||
| **Prompt Engineer** | Designing prompts for LLM applications. Structure, evaluation. | `skills/prompt-engineer` |
|
||||
| **Prompt Engineering** | Expert guide on prompt engineering patterns, best practices, and optimization techniques. | `skills/prompt-engineering` |
|
||||
| **Prompt Library** | "Curated collection of high-quality prompts for various use cases. | `skills/prompt-library` |
|
||||
| **Programmatic SEO** | Build SEO-driven pages at scale using templates and data. | `skills/programmatic-seo` |
|
||||
| **RAG Engineer** | Building RAG systems. Embedding models, vector databases, chunking. | `skills/rag-engineer` |
|
||||
| **RAG Implementation** | RAG patterns. Chunking, embeddings, vector stores. | `skills/rag-implementation` |
|
||||
| **React Best Practices** | React and Next. | `skills/react-best-practices` |
|
||||
| **React UI Patterns** | Modern React UI patterns for loading states, error handling, and data fetching. | `skills/react-ui-patterns` |
|
||||
| **Receiving Code Review** | Use when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation. | `skills/receiving-code-review` |
|
||||
| **Red Team Tools and Methodology** | This skill should be used when the user asks to "follow red team methodology", "perform bug bounty hunting", "automate reconnaissance", "hunt for XSS vulnerabilities", "enumerate subdomains", or needs security researcher techniques and tool configurations from top bug bounty hunters. | `skills/red-team-tools` |
|
||||
| **Referral Program** | Design referral programs, affiliate programs, and word-of-mouth strategies. | `skills/referral-program` |
|
||||
| **Requesting Code Review** | Use when completing tasks, implementing major features, or before merging to verify work meets requirements. | `skills/requesting-code-review` |
|
||||
| **Salesforce Development** | Salesforce integration, Apex development, Lightning components. | `skills/salesforce-development` |
|
||||
| **Schema Markup** | Add structured data and JSON-LD schema markup for SEO and rich snippets. | `skills/schema-markup` |
|
||||
| **Scroll Experience** | GSAP/Framer scroll-driven storytelling. Parallax effects. | `skills/scroll-experience` |
|
||||
| **Security Scanning Tools** | This skill should be used when the user asks to "perform vulnerability scanning", "scan networks for open ports", "assess web application security", "scan wireless networks", "detect malware", "check cloud security", or "evaluate system compliance". | `skills/scanning-tools` |
|
||||
| **Segment CDP** | Segment customer data platform. Event tracking, identity resolution. | `skills/segment-cdp` |
|
||||
| **Senior Architect** | Comprehensive software architecture skill for designing scalable, maintainable systems using ReactJS, NextJS, NodeJS, Express, React Native, Swift, Kotlin, Flutter, Postgres, GraphQL, Go, Python. | `skills/senior-architect` |
|
||||
| **Senior Fullstack** | Comprehensive fullstack development skill for building complete web applications with React, Next. | `skills/senior-fullstack` |
|
||||
| **SEO Audit** | Audit technical and on-page SEO issues for better search rankings. | `skills/seo-audit` |
|
||||
| **Shodan Reconnaissance and Pentesting** | This skill should be used when the user asks to "search for exposed devices on the internet," "perform Shodan reconnaissance," "find vulnerable services using Shodan," "scan IP ranges with Shodan," or "discover IoT devices and open ports. | `skills/shodan-reconnaissance` |
|
||||
| **Shopify Apps** | Building Shopify apps. App Bridge, Polaris, webhooks. | `skills/shopify-apps` |
|
||||
| **Shopify Development** | Build Shopify apps, extensions, themes using GraphQL Admin API, Shopify CLI, Polaris UI, and Liquid. Use when user asks about "shopify app", "checkout extension", "shopify theme", "liquid template", "polaris", "shopify graphql", "shopify webhook", or "metafields". | `skills/shopify-development` |
|
||||
| **Signup Flow CRO** | Optimize signup, registration, and trial activation flows for higher conversions. | `skills/signup-flow-cro` |
|
||||
| **Skill Creator** | Guide for creating effective skills. | `skills/skill-creator` |
|
||||
| **Skill Developer** | Create and manage Claude Code skills following Anthropic best practices. | `skills/skill-developer` |
|
||||
| **Slack Bot Builder** | Production Slack bots. Bolt framework, slash commands, modals. | `skills/slack-bot-builder` |
|
||||
| **Slack GIF Creator** | Knowledge and utilities for creating animated GIFs optimized for Slack. | `skills/slack-gif-creator` |
|
||||
| **SMTP Penetration Testing** | This skill should be used when the user asks to "perform SMTP penetration testing", "enumerate email users", "test for open mail relays", "grab SMTP banners", "brute force email credentials", or "assess mail server security". | `skills/smtp-penetration-testing` |
|
||||
| **Social Content** | Create and schedule social media content for LinkedIn, Twitter/X, and other platforms. | `skills/social-content` |
|
||||
| **Software Architecture** | Guide for quality focused software architecture. | `skills/software-architecture` |
|
||||
| **SQL Injection Testing** | This skill should be used when the user asks to "test for SQL injection vulnerabilities", "perform SQLi attacks", "bypass authentication using SQL injection", "extract database information through injection", "detect SQL injection flaws", or "exploit database query vulnerabilities". | `skills/sql-injection-testing` |
|
||||
| **SQLMap Database Penetration Testing** | This skill should be used when the user asks to "automate SQL injection testing," "enumerate database structure," "extract database credentials using sqlmap," "dump tables and columns from a vulnerable database," or "perform automated database penetration testing. | `skills/sqlmap-database-pentesting` |
|
||||
| **SSH Penetration Testing** | This skill should be used when the user asks to "pentest SSH services", "enumerate SSH configurations", "brute force SSH credentials", "exploit SSH vulnerabilities", "perform SSH tunneling", or "audit SSH security". | `skills/ssh-penetration-testing` |
|
||||
| **Stripe Integration** | Stripe patterns. Checkout, subscriptions, payment intents, webhooks. | `skills/stripe-integration` |
|
||||
| **Subagent Driven Dev** | Use when executing implementation plans with independent tasks in the current session. | `skills/subagent-driven-development` |
|
||||
| **Systematic Debugging** | Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes. | `skills/systematic-debugging` |
|
||||
| **TDD** | Use when implementing any feature or bugfix, before writing implementation code. | `skills/test-driven-development` |
|
||||
| **Telegram Bot Builder** | Building Telegram bots. Bot API, inline mode, payments, Mini Apps. | `skills/telegram-bot-builder` |
|
||||
| **Telegram Mini App** | TON Connect, Telegram Mini Apps, wallet integration. | `skills/telegram-mini-app` |
|
||||
| **Test Fixing** | Run tests and systematically fix all failing tests using smart error grouping. | `skills/test-fixing` |
|
||||
| **Testing Patterns** | Jest testing patterns, factory functions, mocking strategies, and TDD workflow. | `skills/testing-patterns` |
|
||||
| **Theme Factory** | Toolkit for styling artifacts with a theme. | `skills/theme-factory` |
|
||||
| **Top 100 Vulnerabilities** | This skill should be used when the user asks to "identify web application vulnerabilities", "explain common security flaws", "understand vulnerability categories", "learn about injection attacks", "review access control weaknesses", "analyze API security issues", "assess security misconfigurations", "understand client-side vulnerabilities", "examine mobile and IoT security flaws", or "reference the OWASP-aligned vulnerability taxonomy". | `skills/top-web-vulnerabilities` |
|
||||
| **Trigger.dev** | Trigger.dev for serverless background jobs. Long-running tasks. | `skills/trigger-dev` |
|
||||
| **Twilio Communications** | Twilio for SMS, voice, video. Programmable messaging, OTP. | `skills/twilio-communications` |
|
||||
| **UI/UX Pro Max** | "UI/UX design intelligence. | `skills/ui-ux-pro-max` |
|
||||
| **Upstash QStash** | Upstash QStash for serverless message queues. | `skills/upstash-qstash` |
|
||||
| **Using Git Worktrees** | Use when starting feature work that needs isolation from current workspace or before executing implementation plans - creates isolated git worktrees with smart directory selection and safety verification. | `skills/using-git-worktrees` |
|
||||
| **Using Superpowers** | Use when starting any conversation - establishes how to find and use skills, requiring Skill tool invocation before ANY response including clarifying questions. | `skills/using-superpowers` |
|
||||
| **Vercel Deployment** | Vercel deployment. Edge functions, preview deployments. | `skills/vercel-deployment` |
|
||||
| **Verification Before Completion** | Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always. | `skills/verification-before-completion` |
|
||||
| **Viral Generator Builder** | Building shareable generators that go viral. | `skills/viral-generator-builder` |
|
||||
| **Voice Agents** | Voice-based AI assistants. Speech-to-text, real-time conversation. | `skills/voice-agents` |
|
||||
| **Voice AI Development** | Voice AI patterns. Wake words, streaming ASR, emotional TTS. | `skills/voice-ai-development` |
|
||||
| **Web Artifacts** | Suite of tools for creating elaborate, multi-component claude. | `skills/web-artifacts-builder` |
|
||||
| **Web Design Guidelines** | Review UI code for Web Interface Guidelines compliance. | `skills/web-design-guidelines` |
|
||||
| **Webapp Testing** | Toolkit for interacting with and testing local web applications using Playwright. | `skills/webapp-testing` |
|
||||
| **Windows Privilege Escalation** | This skill should be used when the user asks to "escalate privileges on Windows," "find Windows privesc vectors," "enumerate Windows for privilege escalation," "exploit Windows misconfigurations," or "perform post-exploitation privilege escalation. | `skills/windows-privilege-escalation` |
|
||||
| **Wireshark Network Traffic Analysis** | This skill should be used when the user asks to "analyze network traffic with Wireshark", "capture packets for troubleshooting", "filter PCAP files", "follow TCP/UDP streams", "detect network anomalies", "investigate suspicious traffic", or "perform protocol analysis". | `skills/wireshark-analysis` |
|
||||
| **WordPress Penetration Testing** | This skill should be used when the user asks to "pentest WordPress sites", "scan WordPress for vulnerabilities", "enumerate WordPress users, themes, or plugins", "exploit WordPress vulnerabilities", or "use WPScan". | `skills/wordpress-penetration-testing` |
|
||||
| **Workflow Automation** | "Design and implement automated workflows combining visual logic with custom code. | `skills/workflow-automation` |
|
||||
| **Writing Plans** | Use when you have a spec or requirements for a multi-step task, before touching code. | `skills/writing-plans` |
|
||||
| **Writing Skills** | Use when creating new skills, editing existing skills, or verifying skills work before deployment. | `skills/writing-skills` |
|
||||
| **XLSX (Official)** | "Comprehensive spreadsheet creation, editing, and analysis with support for formulas, formatting, data analysis, and visualization. | `skills/xlsx-official` |
|
||||
| **Zapier/Make Patterns** | No-code automation. Zapier, Make, n8n workflows. | `skills/zapier-make-patterns` |
|
||||
|
||||
> [!TIP]
|
||||
> Use the `validate_skills.py` script in the `scripts/` directory to ensure all skills are properly formatted and ready for use.
|
||||
@@ -124,10 +275,20 @@ Below is the complete list of available skills. Each skill folder contains a `SK
|
||||
|
||||
## Installation
|
||||
|
||||
To use these skills with **Antigravity** or **Claude Code**, clone this repository into your agent's skills directory:
|
||||
To use these skills with **Claude Code**, **Gemini CLI**, **Codex CLI**, **Cursor**, **Antigravity**, or **OpenCode**, clone this repository into your agent's skills directory:
|
||||
|
||||
```bash
|
||||
# Universal installation (works with most tools)
|
||||
git clone https://github.com/sickn33/antigravity-awesome-skills.git .agent/skills
|
||||
|
||||
# Claude Code specific
|
||||
git clone https://github.com/sickn33/antigravity-awesome-skills.git .claude/skills
|
||||
|
||||
# Gemini CLI specific
|
||||
git clone https://github.com/sickn33/antigravity-awesome-skills.git .gemini/skills
|
||||
|
||||
# Cursor specific
|
||||
git clone https://github.com/sickn33/antigravity-awesome-skills.git .cursor/skills
|
||||
```
|
||||
|
||||
---
|
||||
@@ -164,9 +325,12 @@ This collection would not be possible without the incredible work of the Claude
|
||||
- **[diet103/claude-code-infrastructure-showcase](https://github.com/diet103/claude-code-infrastructure-showcase)**: Infrastructure and Backend/Frontend Guidelines.
|
||||
- **[ChrisWiles/claude-code-showcase](https://github.com/ChrisWiles/claude-code-showcase)**: React UI patterns and Design Systems.
|
||||
- **[travisvn/awesome-claude-skills](https://github.com/travisvn/awesome-claude-skills)**: Loki Mode and Playwright integration.
|
||||
- **[zebbern/claude-code-guide](https://github.com/zebbern/claude-code-guide)**: Comprehensive Security suite.
|
||||
- **[zebbern/claude-code-guide](https://github.com/zebbern/claude-code-guide)**: Comprehensive Security suite & Guide (Source for ~60 new skills).
|
||||
- **[alirezarezvani/claude-skills](https://github.com/alirezarezvani/claude-skills)**: Senior Engineering and PM toolkit.
|
||||
- **[karanb192/awesome-claude-skills](https://github.com/karanb192/awesome-claude-skills)**: A massive list of verified skills for Claude Code.
|
||||
- **[zircote/.claude](https://github.com/zircote/.claude)**: Shopify development skill reference.
|
||||
- **[vibeforge1111/vibeship-spawner-skills](https://github.com/vibeforge1111/vibeship-spawner-skills)**: AI Agents, Integrations, Maker Tools (57 skills, Apache 2.0).
|
||||
- **[coreyhaines31/marketingskills](https://github.com/coreyhaines31/marketingskills)**: Marketing skills for CRO, copywriting, SEO, paid ads, and growth (23 skills, MIT).
|
||||
|
||||
### Inspirations
|
||||
|
||||
@@ -181,4 +345,18 @@ MIT License. See [LICENSE](LICENSE) for details.
|
||||
|
||||
---
|
||||
|
||||
**Keywords**: Claude Code, Antigravity, Agentic Skills, MCT, AI Agents, Autonomous Coding, Security Auditing, React Patterns.
|
||||
**Keywords**: Claude Code, Gemini CLI, Codex CLI, Antigravity IDE, GitHub Copilot, Cursor, OpenCode, Agentic Skills, AI Coding Assistant, AI Agent Skills, MCP, MCT, AI Agents, Autonomous Coding, Security Auditing, React Patterns, LLM Tools, AI IDE, Coding AI, AI Pair Programming, Vibe Coding, Agentic Coding, AI Developer Tools.
|
||||
|
||||
---
|
||||
|
||||
## 🏷️ GitHub Topics
|
||||
|
||||
For repository maintainers, add these topics to maximize discoverability:
|
||||
|
||||
```text
|
||||
claude-code, gemini-cli, codex-cli, antigravity, cursor, github-copilot, opencode,
|
||||
agentic-skills, ai-coding, llm-tools, ai-agents, autonomous-coding, mcp,
|
||||
ai-developer-tools, ai-pair-programming, vibe-coding, skill, skills, SKILL.md, rules.md, CLAUDE.md, GEMINI.md, CURSOR.md
|
||||
claude-code, gemini-cli, codex-cli, antigravity, cursor, github-copilot, opencode,
|
||||
agentic-skills, ai-coding, llm-tools, ai-agents, autonomous-coding, mcp
|
||||
```
|
||||
|
||||
@@ -7,6 +7,8 @@ def generate_index(skills_dir, output_file):
|
||||
skills = []
|
||||
|
||||
for root, dirs, files in os.walk(skills_dir):
|
||||
# Skip .disabled directories
|
||||
dirs[:] = [d for d in dirs if d != '.disabled']
|
||||
if "SKILL.md" in files:
|
||||
skill_path = os.path.join(root, "SKILL.md")
|
||||
dir_name = os.path.basename(root)
|
||||
|
||||
114
scripts/sync_recommended_skills.sh
Executable file
114
scripts/sync_recommended_skills.sh
Executable file
@@ -0,0 +1,114 @@
|
||||
#!/bin/bash
|
||||
# sync_recommended_skills.sh
|
||||
# Syncs only the 35 recommended skills from GitHub repo to local central library
|
||||
|
||||
set -e
|
||||
|
||||
# Paths
|
||||
GITHUB_REPO="/Users/nicco/Antigravity Projects/antigravity-awesome-skills/skills"
|
||||
LOCAL_LIBRARY="/Users/nicco/.gemini/antigravity/scratch/.agent/skills"
|
||||
BACKUP_DIR="/Users/nicco/.gemini/antigravity/scratch/.agent/skills_backup_$(date +%Y%m%d_%H%M%S)"
|
||||
|
||||
# 35 Recommended Skills
|
||||
RECOMMENDED_SKILLS=(
|
||||
# Tier S - Core Development (13)
|
||||
"systematic-debugging"
|
||||
"test-driven-development"
|
||||
"writing-skills"
|
||||
"doc-coauthoring"
|
||||
"planning-with-files"
|
||||
"concise-planning"
|
||||
"software-architecture"
|
||||
"senior-architect"
|
||||
"senior-fullstack"
|
||||
"verification-before-completion"
|
||||
"git-pushing"
|
||||
"address-github-comments"
|
||||
"javascript-mastery"
|
||||
|
||||
# Tier A - Your Projects (12)
|
||||
"docx-official"
|
||||
"pdf-official"
|
||||
"pptx-official"
|
||||
"xlsx-official"
|
||||
"react-best-practices"
|
||||
"web-design-guidelines"
|
||||
"frontend-dev-guidelines"
|
||||
"webapp-testing"
|
||||
"playwright-skill"
|
||||
"mcp-builder"
|
||||
"notebooklm"
|
||||
"ui-ux-pro-max"
|
||||
|
||||
# Marketing & SEO (1)
|
||||
"content-creator"
|
||||
|
||||
# Corporate (4)
|
||||
"brand-guidelines-anthropic"
|
||||
"brand-guidelines-community"
|
||||
"internal-comms-anthropic"
|
||||
"internal-comms-community"
|
||||
|
||||
# Planning & Documentation (1)
|
||||
"writing-plans"
|
||||
|
||||
# AI & Automation (5)
|
||||
"workflow-automation"
|
||||
"llm-app-patterns"
|
||||
"autonomous-agent-patterns"
|
||||
"prompt-library"
|
||||
"github-workflow-automation"
|
||||
)
|
||||
|
||||
echo "🔄 Sync Recommended Skills"
|
||||
echo "========================="
|
||||
echo ""
|
||||
echo "📍 Source: $GITHUB_REPO"
|
||||
echo "📍 Target: $LOCAL_LIBRARY"
|
||||
echo "📊 Skills to sync: ${#RECOMMENDED_SKILLS[@]}"
|
||||
echo ""
|
||||
|
||||
# Create backup
|
||||
echo "📦 Creating backup at: $BACKUP_DIR"
|
||||
cp -r "$LOCAL_LIBRARY" "$BACKUP_DIR"
|
||||
echo "✅ Backup created"
|
||||
echo ""
|
||||
|
||||
# Clear local library (keep README.md if exists)
|
||||
echo "🗑️ Clearing local library..."
|
||||
cd "$LOCAL_LIBRARY"
|
||||
for item in */; do
|
||||
rm -rf "$item"
|
||||
done
|
||||
echo "✅ Local library cleared"
|
||||
echo ""
|
||||
|
||||
# Copy recommended skills
|
||||
echo "📋 Copying recommended skills..."
|
||||
SUCCESS_COUNT=0
|
||||
MISSING_COUNT=0
|
||||
|
||||
for skill in "${RECOMMENDED_SKILLS[@]}"; do
|
||||
if [ -d "$GITHUB_REPO/$skill" ]; then
|
||||
cp -r "$GITHUB_REPO/$skill" "$LOCAL_LIBRARY/"
|
||||
echo " ✅ $skill"
|
||||
((SUCCESS_COUNT++))
|
||||
else
|
||||
echo " ⚠️ $skill (not found in repo)"
|
||||
((MISSING_COUNT++))
|
||||
fi
|
||||
done
|
||||
|
||||
echo ""
|
||||
echo "📊 Summary"
|
||||
echo "=========="
|
||||
echo "✅ Copied: $SUCCESS_COUNT skills"
|
||||
echo "⚠️ Missing: $MISSING_COUNT skills"
|
||||
echo "📦 Backup: $BACKUP_DIR"
|
||||
echo ""
|
||||
|
||||
# Verify
|
||||
FINAL_COUNT=$(find "$LOCAL_LIBRARY" -maxdepth 1 -type d ! -name "." | wc -l | tr -d ' ')
|
||||
echo "🎯 Final count in local library: $FINAL_COUNT skills"
|
||||
echo ""
|
||||
echo "Done! Your local library now has only the recommended skills."
|
||||
@@ -7,6 +7,8 @@ def validate_skills(skills_dir):
|
||||
skill_count = 0
|
||||
|
||||
for root, dirs, files in os.walk(skills_dir):
|
||||
# Skip .disabled directories
|
||||
dirs[:] = [d for d in dirs if d != '.disabled']
|
||||
if "SKILL.md" in files:
|
||||
skill_count += 1
|
||||
skill_path = os.path.join(root, "SKILL.md")
|
||||
|
||||
254
skills/3d-web-experience/SKILL.md
Normal file
254
skills/3d-web-experience/SKILL.md
Normal file
@@ -0,0 +1,254 @@
|
||||
---
|
||||
name: 3d-web-experience
|
||||
description: "Expert in building 3D experiences for the web - Three.js, React Three Fiber, Spline, WebGL, and interactive 3D scenes. Covers product configurators, 3D portfolios, immersive websites, and bringing depth to web experiences. Use when: 3D website, three.js, WebGL, react three fiber, 3D experience."
|
||||
source: vibeship-spawner-skills (Apache 2.0)
|
||||
---
|
||||
|
||||
# 3D Web Experience
|
||||
|
||||
**Role**: 3D Web Experience Architect
|
||||
|
||||
You bring the third dimension to the web. You know when 3D enhances
|
||||
and when it's just showing off. You balance visual impact with
|
||||
performance. You make 3D accessible to users who've never touched
|
||||
a 3D app. You create moments of wonder without sacrificing usability.
|
||||
|
||||
## Capabilities
|
||||
|
||||
- Three.js implementation
|
||||
- React Three Fiber
|
||||
- WebGL optimization
|
||||
- 3D model integration
|
||||
- Spline workflows
|
||||
- 3D product configurators
|
||||
- Interactive 3D scenes
|
||||
- 3D performance optimization
|
||||
|
||||
## Patterns
|
||||
|
||||
### 3D Stack Selection
|
||||
|
||||
Choosing the right 3D approach
|
||||
|
||||
**When to use**: When starting a 3D web project
|
||||
|
||||
```python
|
||||
## 3D Stack Selection
|
||||
|
||||
### Options Comparison
|
||||
| Tool | Best For | Learning Curve | Control |
|
||||
|------|----------|----------------|---------|
|
||||
| Spline | Quick prototypes, designers | Low | Medium |
|
||||
| React Three Fiber | React apps, complex scenes | Medium | High |
|
||||
| Three.js vanilla | Max control, non-React | High | Maximum |
|
||||
| Babylon.js | Games, heavy 3D | High | Maximum |
|
||||
|
||||
### Decision Tree
|
||||
```
|
||||
Need quick 3D element?
|
||||
└── Yes → Spline
|
||||
└── No → Continue
|
||||
|
||||
Using React?
|
||||
└── Yes → React Three Fiber
|
||||
└── No → Continue
|
||||
|
||||
Need max performance/control?
|
||||
└── Yes → Three.js vanilla
|
||||
└── No → Spline or R3F
|
||||
```
|
||||
|
||||
### Spline (Fastest Start)
|
||||
```jsx
|
||||
import Spline from '@splinetool/react-spline';
|
||||
|
||||
export default function Scene() {
|
||||
return (
|
||||
<Spline scene="https://prod.spline.design/xxx/scene.splinecode" />
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
### React Three Fiber
|
||||
```jsx
|
||||
import { Canvas } from '@react-three/fiber';
|
||||
import { OrbitControls, useGLTF } from '@react-three/drei';
|
||||
|
||||
function Model() {
|
||||
const { scene } = useGLTF('/model.glb');
|
||||
return <primitive object={scene} />;
|
||||
}
|
||||
|
||||
export default function Scene() {
|
||||
return (
|
||||
<Canvas>
|
||||
<ambientLight />
|
||||
<Model />
|
||||
<OrbitControls />
|
||||
</Canvas>
|
||||
);
|
||||
}
|
||||
```
|
||||
```
|
||||
|
||||
### 3D Model Pipeline
|
||||
|
||||
Getting models web-ready
|
||||
|
||||
**When to use**: When preparing 3D assets
|
||||
|
||||
```python
|
||||
## 3D Model Pipeline
|
||||
|
||||
### Format Selection
|
||||
| Format | Use Case | Size |
|
||||
|--------|----------|------|
|
||||
| GLB/GLTF | Standard web 3D | Smallest |
|
||||
| FBX | From 3D software | Large |
|
||||
| OBJ | Simple meshes | Medium |
|
||||
| USDZ | Apple AR | Medium |
|
||||
|
||||
### Optimization Pipeline
|
||||
```
|
||||
1. Model in Blender/etc
|
||||
2. Reduce poly count (< 100K for web)
|
||||
3. Bake textures (combine materials)
|
||||
4. Export as GLB
|
||||
5. Compress with gltf-transform
|
||||
6. Test file size (< 5MB ideal)
|
||||
```
|
||||
|
||||
### GLTF Compression
|
||||
```bash
|
||||
# Install gltf-transform
|
||||
npm install -g @gltf-transform/cli
|
||||
|
||||
# Compress model
|
||||
gltf-transform optimize input.glb output.glb \
|
||||
--compress draco \
|
||||
--texture-compress webp
|
||||
```
|
||||
|
||||
### Loading in R3F
|
||||
```jsx
|
||||
import { useGLTF, useProgress, Html } from '@react-three/drei';
|
||||
import { Suspense } from 'react';
|
||||
|
||||
function Loader() {
|
||||
const { progress } = useProgress();
|
||||
return <Html center>{progress.toFixed(0)}%</Html>;
|
||||
}
|
||||
|
||||
export default function Scene() {
|
||||
return (
|
||||
<Canvas>
|
||||
<Suspense fallback={<Loader />}>
|
||||
<Model />
|
||||
</Suspense>
|
||||
</Canvas>
|
||||
);
|
||||
}
|
||||
```
|
||||
```
|
||||
|
||||
### Scroll-Driven 3D
|
||||
|
||||
3D that responds to scroll
|
||||
|
||||
**When to use**: When integrating 3D with scroll
|
||||
|
||||
```python
|
||||
## Scroll-Driven 3D
|
||||
|
||||
### R3F + Scroll Controls
|
||||
```jsx
|
||||
import { ScrollControls, useScroll } from '@react-three/drei';
|
||||
import { useFrame } from '@react-three/fiber';
|
||||
|
||||
function RotatingModel() {
|
||||
const scroll = useScroll();
|
||||
const ref = useRef();
|
||||
|
||||
useFrame(() => {
|
||||
// Rotate based on scroll position
|
||||
ref.current.rotation.y = scroll.offset * Math.PI * 2;
|
||||
});
|
||||
|
||||
return <mesh ref={ref}>...</mesh>;
|
||||
}
|
||||
|
||||
export default function Scene() {
|
||||
return (
|
||||
<Canvas>
|
||||
<ScrollControls pages={3}>
|
||||
<RotatingModel />
|
||||
</ScrollControls>
|
||||
</Canvas>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
### GSAP + Three.js
|
||||
```javascript
|
||||
import gsap from 'gsap';
|
||||
import ScrollTrigger from 'gsap/ScrollTrigger';
|
||||
|
||||
gsap.to(camera.position, {
|
||||
scrollTrigger: {
|
||||
trigger: '.section',
|
||||
scrub: true,
|
||||
},
|
||||
z: 5,
|
||||
y: 2,
|
||||
});
|
||||
```
|
||||
|
||||
### Common Scroll Effects
|
||||
- Camera movement through scene
|
||||
- Model rotation on scroll
|
||||
- Reveal/hide elements
|
||||
- Color/material changes
|
||||
- Exploded view animations
|
||||
```
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
### ❌ 3D For 3D's Sake
|
||||
|
||||
**Why bad**: Slows down the site.
|
||||
Confuses users.
|
||||
Battery drain on mobile.
|
||||
Doesn't help conversion.
|
||||
|
||||
**Instead**: 3D should serve a purpose.
|
||||
Product visualization = good.
|
||||
Random floating shapes = probably not.
|
||||
Ask: would an image work?
|
||||
|
||||
### ❌ Desktop-Only 3D
|
||||
|
||||
**Why bad**: Most traffic is mobile.
|
||||
Kills battery.
|
||||
Crashes on low-end devices.
|
||||
Frustrated users.
|
||||
|
||||
**Instead**: Test on real mobile devices.
|
||||
Reduce quality on mobile.
|
||||
Provide static fallback.
|
||||
Consider disabling 3D on low-end.
|
||||
|
||||
### ❌ No Loading State
|
||||
|
||||
**Why bad**: Users think it's broken.
|
||||
High bounce rate.
|
||||
3D takes time to load.
|
||||
Bad first impression.
|
||||
|
||||
**Instead**: Loading progress indicator.
|
||||
Skeleton/placeholder.
|
||||
Load 3D after page is interactive.
|
||||
Optimize model size.
|
||||
|
||||
## Related Skills
|
||||
|
||||
Works well with: `scroll-experience`, `interactive-portfolio`, `frontend`, `landing-page-design`
|
||||
508
skills/ab-test-setup/SKILL.md
Normal file
508
skills/ab-test-setup/SKILL.md
Normal file
@@ -0,0 +1,508 @@
|
||||
---
|
||||
name: ab-test-setup
|
||||
description: When the user wants to plan, design, or implement an A/B test or experiment. Also use when the user mentions "A/B test," "split test," "experiment," "test this change," "variant copy," "multivariate test," or "hypothesis." For tracking implementation, see analytics-tracking.
|
||||
---
|
||||
|
||||
# A/B Test Setup
|
||||
|
||||
You are an expert in experimentation and A/B testing. Your goal is to help design tests that produce statistically valid, actionable results.
|
||||
|
||||
## Initial Assessment
|
||||
|
||||
Before designing a test, understand:
|
||||
|
||||
1. **Test Context**
|
||||
- What are you trying to improve?
|
||||
- What change are you considering?
|
||||
- What made you want to test this?
|
||||
|
||||
2. **Current State**
|
||||
- Baseline conversion rate?
|
||||
- Current traffic volume?
|
||||
- Any historical test data?
|
||||
|
||||
3. **Constraints**
|
||||
- Technical implementation complexity?
|
||||
- Timeline requirements?
|
||||
- Tools available?
|
||||
|
||||
---
|
||||
|
||||
## Core Principles
|
||||
|
||||
### 1. Start with a Hypothesis
|
||||
- Not just "let's see what happens"
|
||||
- Specific prediction of outcome
|
||||
- Based on reasoning or data
|
||||
|
||||
### 2. Test One Thing
|
||||
- Single variable per test
|
||||
- Otherwise you don't know what worked
|
||||
- Save MVT for later
|
||||
|
||||
### 3. Statistical Rigor
|
||||
- Pre-determine sample size
|
||||
- Don't peek and stop early
|
||||
- Commit to the methodology
|
||||
|
||||
### 4. Measure What Matters
|
||||
- Primary metric tied to business value
|
||||
- Secondary metrics for context
|
||||
- Guardrail metrics to prevent harm
|
||||
|
||||
---
|
||||
|
||||
## Hypothesis Framework
|
||||
|
||||
### Structure
|
||||
|
||||
```
|
||||
Because [observation/data],
|
||||
we believe [change]
|
||||
will cause [expected outcome]
|
||||
for [audience].
|
||||
We'll know this is true when [metrics].
|
||||
```
|
||||
|
||||
### Examples
|
||||
|
||||
**Weak hypothesis:**
|
||||
"Changing the button color might increase clicks."
|
||||
|
||||
**Strong hypothesis:**
|
||||
"Because users report difficulty finding the CTA (per heatmaps and feedback), we believe making the button larger and using contrasting color will increase CTA clicks by 15%+ for new visitors. We'll measure click-through rate from page view to signup start."
|
||||
|
||||
### Good Hypotheses Include
|
||||
|
||||
- **Observation**: What prompted this idea
|
||||
- **Change**: Specific modification
|
||||
- **Effect**: Expected outcome and direction
|
||||
- **Audience**: Who this applies to
|
||||
- **Metric**: How you'll measure success
|
||||
|
||||
---
|
||||
|
||||
## Test Types
|
||||
|
||||
### A/B Test (Split Test)
|
||||
- Two versions: Control (A) vs. Variant (B)
|
||||
- Single change between versions
|
||||
- Most common, easiest to analyze
|
||||
|
||||
### A/B/n Test
|
||||
- Multiple variants (A vs. B vs. C...)
|
||||
- Requires more traffic
|
||||
- Good for testing several options
|
||||
|
||||
### Multivariate Test (MVT)
|
||||
- Multiple changes in combinations
|
||||
- Tests interactions between changes
|
||||
- Requires significantly more traffic
|
||||
- Complex analysis
|
||||
|
||||
### Split URL Test
|
||||
- Different URLs for variants
|
||||
- Good for major page changes
|
||||
- Easier implementation sometimes
|
||||
|
||||
---
|
||||
|
||||
## Sample Size Calculation
|
||||
|
||||
### Inputs Needed
|
||||
|
||||
1. **Baseline conversion rate**: Your current rate
|
||||
2. **Minimum detectable effect (MDE)**: Smallest change worth detecting
|
||||
3. **Statistical significance level**: Usually 95%
|
||||
4. **Statistical power**: Usually 80%
|
||||
|
||||
### Quick Reference
|
||||
|
||||
| Baseline Rate | 10% Lift | 20% Lift | 50% Lift |
|
||||
|---------------|----------|----------|----------|
|
||||
| 1% | 150k/variant | 39k/variant | 6k/variant |
|
||||
| 3% | 47k/variant | 12k/variant | 2k/variant |
|
||||
| 5% | 27k/variant | 7k/variant | 1.2k/variant |
|
||||
| 10% | 12k/variant | 3k/variant | 550/variant |
|
||||
|
||||
### Formula Resources
|
||||
- Evan Miller's calculator: https://www.evanmiller.org/ab-testing/sample-size.html
|
||||
- Optimizely's calculator: https://www.optimizely.com/sample-size-calculator/
|
||||
|
||||
### Test Duration
|
||||
|
||||
```
|
||||
Duration = Sample size needed per variant × Number of variants
|
||||
───────────────────────────────────────────────────
|
||||
Daily traffic to test page × Conversion rate
|
||||
```
|
||||
|
||||
Minimum: 1-2 business cycles (usually 1-2 weeks)
|
||||
Maximum: Avoid running too long (novelty effects, external factors)
|
||||
|
||||
---
|
||||
|
||||
## Metrics Selection
|
||||
|
||||
### Primary Metric
|
||||
- Single metric that matters most
|
||||
- Directly tied to hypothesis
|
||||
- What you'll use to call the test
|
||||
|
||||
### Secondary Metrics
|
||||
- Support primary metric interpretation
|
||||
- Explain why/how the change worked
|
||||
- Help understand user behavior
|
||||
|
||||
### Guardrail Metrics
|
||||
- Things that shouldn't get worse
|
||||
- Revenue, retention, satisfaction
|
||||
- Stop test if significantly negative
|
||||
|
||||
### Metric Examples by Test Type
|
||||
|
||||
**Homepage CTA test:**
|
||||
- Primary: CTA click-through rate
|
||||
- Secondary: Time to click, scroll depth
|
||||
- Guardrail: Bounce rate, downstream conversion
|
||||
|
||||
**Pricing page test:**
|
||||
- Primary: Plan selection rate
|
||||
- Secondary: Time on page, plan distribution
|
||||
- Guardrail: Support tickets, refund rate
|
||||
|
||||
**Signup flow test:**
|
||||
- Primary: Signup completion rate
|
||||
- Secondary: Field-level completion, time to complete
|
||||
- Guardrail: User activation rate (post-signup quality)
|
||||
|
||||
---
|
||||
|
||||
## Designing Variants
|
||||
|
||||
### Control (A)
|
||||
- Current experience, unchanged
|
||||
- Don't modify during test
|
||||
|
||||
### Variant (B+)
|
||||
|
||||
**Best practices:**
|
||||
- Single, meaningful change
|
||||
- Bold enough to make a difference
|
||||
- True to the hypothesis
|
||||
|
||||
**What to vary:**
|
||||
|
||||
Headlines/Copy:
|
||||
- Message angle
|
||||
- Value proposition
|
||||
- Specificity level
|
||||
- Tone/voice
|
||||
|
||||
Visual Design:
|
||||
- Layout structure
|
||||
- Color and contrast
|
||||
- Image selection
|
||||
- Visual hierarchy
|
||||
|
||||
CTA:
|
||||
- Button copy
|
||||
- Size/prominence
|
||||
- Placement
|
||||
- Number of CTAs
|
||||
|
||||
Content:
|
||||
- Information included
|
||||
- Order of information
|
||||
- Amount of content
|
||||
- Social proof type
|
||||
|
||||
### Documenting Variants
|
||||
|
||||
```
|
||||
Control (A):
|
||||
- Screenshot
|
||||
- Description of current state
|
||||
|
||||
Variant (B):
|
||||
- Screenshot or mockup
|
||||
- Specific changes made
|
||||
- Hypothesis for why this will win
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Traffic Allocation
|
||||
|
||||
### Standard Split
|
||||
- 50/50 for A/B test
|
||||
- Equal split for multiple variants
|
||||
|
||||
### Conservative Rollout
|
||||
- 90/10 or 80/20 initially
|
||||
- Limits risk of bad variant
|
||||
- Longer to reach significance
|
||||
|
||||
### Ramping
|
||||
- Start small, increase over time
|
||||
- Good for technical risk mitigation
|
||||
- Most tools support this
|
||||
|
||||
### Considerations
|
||||
- Consistency: Users see same variant on return
|
||||
- Segment sizes: Ensure segments are large enough
|
||||
- Time of day/week: Balanced exposure
|
||||
|
||||
---
|
||||
|
||||
## Implementation Approaches
|
||||
|
||||
### Client-Side Testing
|
||||
|
||||
**Tools**: PostHog, Optimizely, VWO, custom
|
||||
|
||||
**How it works**:
|
||||
- JavaScript modifies page after load
|
||||
- Quick to implement
|
||||
- Can cause flicker
|
||||
|
||||
**Best for**:
|
||||
- Marketing pages
|
||||
- Copy/visual changes
|
||||
- Quick iteration
|
||||
|
||||
### Server-Side Testing
|
||||
|
||||
**Tools**: PostHog, LaunchDarkly, Split, custom
|
||||
|
||||
**How it works**:
|
||||
- Variant determined before page renders
|
||||
- No flicker
|
||||
- Requires development work
|
||||
|
||||
**Best for**:
|
||||
- Product features
|
||||
- Complex changes
|
||||
- Performance-sensitive pages
|
||||
|
||||
### Feature Flags
|
||||
|
||||
- Binary on/off (not true A/B)
|
||||
- Good for rollouts
|
||||
- Can convert to A/B with percentage split
|
||||
|
||||
---
|
||||
|
||||
## Running the Test
|
||||
|
||||
### Pre-Launch Checklist
|
||||
|
||||
- [ ] Hypothesis documented
|
||||
- [ ] Primary metric defined
|
||||
- [ ] Sample size calculated
|
||||
- [ ] Test duration estimated
|
||||
- [ ] Variants implemented correctly
|
||||
- [ ] Tracking verified
|
||||
- [ ] QA completed on all variants
|
||||
- [ ] Stakeholders informed
|
||||
|
||||
### During the Test
|
||||
|
||||
**DO:**
|
||||
- Monitor for technical issues
|
||||
- Check segment quality
|
||||
- Document any external factors
|
||||
|
||||
**DON'T:**
|
||||
- Peek at results and stop early
|
||||
- Make changes to variants
|
||||
- Add traffic from new sources
|
||||
- End early because you "know" the answer
|
||||
|
||||
### Peeking Problem
|
||||
|
||||
Looking at results before reaching sample size and stopping when you see significance leads to:
|
||||
- False positives
|
||||
- Inflated effect sizes
|
||||
- Wrong decisions
|
||||
|
||||
**Solutions:**
|
||||
- Pre-commit to sample size and stick to it
|
||||
- Use sequential testing if you must peek
|
||||
- Trust the process
|
||||
|
||||
---
|
||||
|
||||
## Analyzing Results
|
||||
|
||||
### Statistical Significance
|
||||
|
||||
- 95% confidence = p-value < 0.05
|
||||
- Means: <5% chance result is random
|
||||
- Not a guarantee—just a threshold
|
||||
|
||||
### Practical Significance
|
||||
|
||||
Statistical ≠ Practical
|
||||
|
||||
- Is the effect size meaningful for business?
|
||||
- Is it worth the implementation cost?
|
||||
- Is it sustainable over time?
|
||||
|
||||
### What to Look At
|
||||
|
||||
1. **Did you reach sample size?**
|
||||
- If not, result is preliminary
|
||||
|
||||
2. **Is it statistically significant?**
|
||||
- Check confidence intervals
|
||||
- Check p-value
|
||||
|
||||
3. **Is the effect size meaningful?**
|
||||
- Compare to your MDE
|
||||
- Project business impact
|
||||
|
||||
4. **Are secondary metrics consistent?**
|
||||
- Do they support the primary?
|
||||
- Any unexpected effects?
|
||||
|
||||
5. **Any guardrail concerns?**
|
||||
- Did anything get worse?
|
||||
- Long-term risks?
|
||||
|
||||
6. **Segment differences?**
|
||||
- Mobile vs. desktop?
|
||||
- New vs. returning?
|
||||
- Traffic source?
|
||||
|
||||
### Interpreting Results
|
||||
|
||||
| Result | Conclusion |
|
||||
|--------|------------|
|
||||
| Significant winner | Implement variant |
|
||||
| Significant loser | Keep control, learn why |
|
||||
| No significant difference | Need more traffic or bolder test |
|
||||
| Mixed signals | Dig deeper, maybe segment |
|
||||
|
||||
---
|
||||
|
||||
## Documenting and Learning
|
||||
|
||||
### Test Documentation
|
||||
|
||||
```
|
||||
Test Name: [Name]
|
||||
Test ID: [ID in testing tool]
|
||||
Dates: [Start] - [End]
|
||||
Owner: [Name]
|
||||
|
||||
Hypothesis:
|
||||
[Full hypothesis statement]
|
||||
|
||||
Variants:
|
||||
- Control: [Description + screenshot]
|
||||
- Variant: [Description + screenshot]
|
||||
|
||||
Results:
|
||||
- Sample size: [achieved vs. target]
|
||||
- Primary metric: [control] vs. [variant] ([% change], [confidence])
|
||||
- Secondary metrics: [summary]
|
||||
- Segment insights: [notable differences]
|
||||
|
||||
Decision: [Winner/Loser/Inconclusive]
|
||||
Action: [What we're doing]
|
||||
|
||||
Learnings:
|
||||
[What we learned, what to test next]
|
||||
```
|
||||
|
||||
### Building a Learning Repository
|
||||
|
||||
- Central location for all tests
|
||||
- Searchable by page, element, outcome
|
||||
- Prevents re-running failed tests
|
||||
- Builds institutional knowledge
|
||||
|
||||
---
|
||||
|
||||
## Output Format
|
||||
|
||||
### Test Plan Document
|
||||
|
||||
```
|
||||
# A/B Test: [Name]
|
||||
|
||||
## Hypothesis
|
||||
[Full hypothesis using framework]
|
||||
|
||||
## Test Design
|
||||
- Type: A/B / A/B/n / MVT
|
||||
- Duration: X weeks
|
||||
- Sample size: X per variant
|
||||
- Traffic allocation: 50/50
|
||||
|
||||
## Variants
|
||||
[Control and variant descriptions with visuals]
|
||||
|
||||
## Metrics
|
||||
- Primary: [metric and definition]
|
||||
- Secondary: [list]
|
||||
- Guardrails: [list]
|
||||
|
||||
## Implementation
|
||||
- Method: Client-side / Server-side
|
||||
- Tool: [Tool name]
|
||||
- Dev requirements: [If any]
|
||||
|
||||
## Analysis Plan
|
||||
- Success criteria: [What constitutes a win]
|
||||
- Segment analysis: [Planned segments]
|
||||
```
|
||||
|
||||
### Results Summary
|
||||
When test is complete
|
||||
|
||||
### Recommendations
|
||||
Next steps based on results
|
||||
|
||||
---
|
||||
|
||||
## Common Mistakes
|
||||
|
||||
### Test Design
|
||||
- Testing too small a change (undetectable)
|
||||
- Testing too many things (can't isolate)
|
||||
- No clear hypothesis
|
||||
- Wrong audience
|
||||
|
||||
### Execution
|
||||
- Stopping early
|
||||
- Changing things mid-test
|
||||
- Not checking implementation
|
||||
- Uneven traffic allocation
|
||||
|
||||
### Analysis
|
||||
- Ignoring confidence intervals
|
||||
- Cherry-picking segments
|
||||
- Over-interpreting inconclusive results
|
||||
- Not considering practical significance
|
||||
|
||||
---
|
||||
|
||||
## Questions to Ask
|
||||
|
||||
If you need more context:
|
||||
1. What's your current conversion rate?
|
||||
2. How much traffic does this page get?
|
||||
3. What change are you considering and why?
|
||||
4. What's the smallest improvement worth detecting?
|
||||
5. What tools do you have for testing?
|
||||
6. Have you tested this area before?
|
||||
|
||||
---
|
||||
|
||||
## Related Skills
|
||||
|
||||
- **page-cro**: For generating test ideas based on CRO principles
|
||||
- **analytics-tracking**: For setting up test measurement
|
||||
- **copywriting**: For creating variant copy
|
||||
64
skills/agent-evaluation/SKILL.md
Normal file
64
skills/agent-evaluation/SKILL.md
Normal file
@@ -0,0 +1,64 @@
|
||||
---
|
||||
name: agent-evaluation
|
||||
description: "Testing and benchmarking LLM agents including behavioral testing, capability assessment, reliability metrics, and production monitoring—where even top agents achieve less than 50% on real-world benchmarks Use when: agent testing, agent evaluation, benchmark agents, agent reliability, test agent."
|
||||
source: vibeship-spawner-skills (Apache 2.0)
|
||||
---
|
||||
|
||||
# Agent Evaluation
|
||||
|
||||
You're a quality engineer who has seen agents that aced benchmarks fail spectacularly in
|
||||
production. You've learned that evaluating LLM agents is fundamentally different from
|
||||
testing traditional software—the same input can produce different outputs, and "correct"
|
||||
often has no single answer.
|
||||
|
||||
You've built evaluation frameworks that catch issues before production: behavioral regression
|
||||
tests, capability assessments, and reliability metrics. You understand that the goal isn't
|
||||
100% test pass rate—it
|
||||
|
||||
## Capabilities
|
||||
|
||||
- agent-testing
|
||||
- benchmark-design
|
||||
- capability-assessment
|
||||
- reliability-metrics
|
||||
- regression-testing
|
||||
|
||||
## Requirements
|
||||
|
||||
- testing-fundamentals
|
||||
- llm-fundamentals
|
||||
|
||||
## Patterns
|
||||
|
||||
### Statistical Test Evaluation
|
||||
|
||||
Run tests multiple times and analyze result distributions
|
||||
|
||||
### Behavioral Contract Testing
|
||||
|
||||
Define and test agent behavioral invariants
|
||||
|
||||
### Adversarial Testing
|
||||
|
||||
Actively try to break agent behavior
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
### ❌ Single-Run Testing
|
||||
|
||||
### ❌ Only Happy Path Tests
|
||||
|
||||
### ❌ Output String Matching
|
||||
|
||||
## ⚠️ Sharp Edges
|
||||
|
||||
| Issue | Severity | Solution |
|
||||
|-------|----------|----------|
|
||||
| Agent scores well on benchmarks but fails in production | high | // Bridge benchmark and production evaluation |
|
||||
| Same test passes sometimes, fails other times | high | // Handle flaky tests in LLM agent evaluation |
|
||||
| Agent optimized for metric, not actual task | medium | // Multi-dimensional evaluation to prevent gaming |
|
||||
| Test data accidentally used in training or prompts | critical | // Prevent data leakage in agent evaluation |
|
||||
|
||||
## Related Skills
|
||||
|
||||
Works well with: `multi-agent-orchestration`, `agent-communication`, `autonomous-agents`
|
||||
40
skills/agent-manager-skill/SKILL.md
Normal file
40
skills/agent-manager-skill/SKILL.md
Normal file
@@ -0,0 +1,40 @@
|
||||
---
|
||||
name: agent-manager-skill
|
||||
description: Manage multiple local CLI agents via tmux sessions (start/stop/monitor/assign) with cron-friendly scheduling.
|
||||
---
|
||||
|
||||
# Agent Manager Skill
|
||||
|
||||
## When to use
|
||||
|
||||
Use this skill when you need to:
|
||||
|
||||
- run multiple local CLI agents in parallel (separate tmux sessions)
|
||||
- start/stop agents and tail their logs
|
||||
- assign tasks to agents and monitor output
|
||||
- schedule recurring agent work (cron)
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Install `agent-manager-skill` in your workspace:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/fractalmind-ai/agent-manager-skill.git
|
||||
```
|
||||
|
||||
## Common commands
|
||||
|
||||
```bash
|
||||
python3 agent-manager/scripts/main.py doctor
|
||||
python3 agent-manager/scripts/main.py list
|
||||
python3 agent-manager/scripts/main.py start EMP_0001
|
||||
python3 agent-manager/scripts/main.py monitor EMP_0001 --follow
|
||||
python3 agent-manager/scripts/main.py assign EMP_0002 <<'EOF'
|
||||
Follow teams/fractalmind-ai-maintenance.md Workflow
|
||||
EOF
|
||||
```
|
||||
|
||||
## Notes
|
||||
|
||||
- Requires `tmux` and `python3`.
|
||||
- Agents are configured under an `agents/` directory (see the repo for examples).
|
||||
67
skills/agent-memory-systems/SKILL.md
Normal file
67
skills/agent-memory-systems/SKILL.md
Normal file
@@ -0,0 +1,67 @@
|
||||
---
|
||||
name: agent-memory-systems
|
||||
description: "Memory is the cornerstone of intelligent agents. Without it, every interaction starts from zero. This skill covers the architecture of agent memory: short-term (context window), long-term (vector stores), and the cognitive architectures that organize them. Key insight: Memory isn't just storage - it's retrieval. A million stored facts mean nothing if you can't find the right one. Chunking, embedding, and retrieval strategies determine whether your agent remembers or forgets. The field is fragm"
|
||||
source: vibeship-spawner-skills (Apache 2.0)
|
||||
---
|
||||
|
||||
# Agent Memory Systems
|
||||
|
||||
You are a cognitive architect who understands that memory makes agents intelligent.
|
||||
You've built memory systems for agents handling millions of interactions. You know
|
||||
that the hard part isn't storing - it's retrieving the right memory at the right time.
|
||||
|
||||
Your core insight: Memory failures look like intelligence failures. When an agent
|
||||
"forgets" or gives inconsistent answers, it's almost always a retrieval problem,
|
||||
not a storage problem. You obsess over chunking strategies, embedding quality,
|
||||
and
|
||||
|
||||
## Capabilities
|
||||
|
||||
- agent-memory
|
||||
- long-term-memory
|
||||
- short-term-memory
|
||||
- working-memory
|
||||
- episodic-memory
|
||||
- semantic-memory
|
||||
- procedural-memory
|
||||
- memory-retrieval
|
||||
- memory-formation
|
||||
- memory-decay
|
||||
|
||||
## Patterns
|
||||
|
||||
### Memory Type Architecture
|
||||
|
||||
Choosing the right memory type for different information
|
||||
|
||||
### Vector Store Selection Pattern
|
||||
|
||||
Choosing the right vector database for your use case
|
||||
|
||||
### Chunking Strategy Pattern
|
||||
|
||||
Breaking documents into retrievable chunks
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
### ❌ Store Everything Forever
|
||||
|
||||
### ❌ Chunk Without Testing Retrieval
|
||||
|
||||
### ❌ Single Memory Type for All Data
|
||||
|
||||
## ⚠️ Sharp Edges
|
||||
|
||||
| Issue | Severity | Solution |
|
||||
|-------|----------|----------|
|
||||
| Issue | critical | ## Contextual Chunking (Anthropic's approach) |
|
||||
| Issue | high | ## Test different sizes |
|
||||
| Issue | high | ## Always filter by metadata first |
|
||||
| Issue | high | ## Add temporal scoring |
|
||||
| Issue | medium | ## Detect conflicts on storage |
|
||||
| Issue | medium | ## Budget tokens for different memory types |
|
||||
| Issue | medium | ## Track embedding model in metadata |
|
||||
|
||||
## Related Skills
|
||||
|
||||
Works well with: `autonomous-agents`, `multi-agent-orchestration`, `llm-architect`, `agent-tool-builder`
|
||||
53
skills/agent-tool-builder/SKILL.md
Normal file
53
skills/agent-tool-builder/SKILL.md
Normal file
@@ -0,0 +1,53 @@
|
||||
---
|
||||
name: agent-tool-builder
|
||||
description: "Tools are how AI agents interact with the world. A well-designed tool is the difference between an agent that works and one that hallucinates, fails silently, or costs 10x more tokens than necessary. This skill covers tool design from schema to error handling. JSON Schema best practices, description writing that actually helps the LLM, validation, and the emerging MCP standard that's becoming the lingua franca for AI tools. Key insight: Tool descriptions are more important than tool implementa"
|
||||
source: vibeship-spawner-skills (Apache 2.0)
|
||||
---
|
||||
|
||||
# Agent Tool Builder
|
||||
|
||||
You are an expert in the interface between LLMs and the outside world.
|
||||
You've seen tools that work beautifully and tools that cause agents to
|
||||
hallucinate, loop, or fail silently. The difference is almost always
|
||||
in the design, not the implementation.
|
||||
|
||||
Your core insight: The LLM never sees your code. It only sees the schema
|
||||
and description. A perfectly implemented tool with a vague description
|
||||
will fail. A simple tool with crystal-clear documentation will succeed.
|
||||
|
||||
You push for explicit error hand
|
||||
|
||||
## Capabilities
|
||||
|
||||
- agent-tools
|
||||
- function-calling
|
||||
- tool-schema-design
|
||||
- mcp-tools
|
||||
- tool-validation
|
||||
- tool-error-handling
|
||||
|
||||
## Patterns
|
||||
|
||||
### Tool Schema Design
|
||||
|
||||
Creating clear, unambiguous JSON Schema for tools
|
||||
|
||||
### Tool with Input Examples
|
||||
|
||||
Using examples to guide LLM tool usage
|
||||
|
||||
### Tool Error Handling
|
||||
|
||||
Returning errors that help the LLM recover
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
### ❌ Vague Descriptions
|
||||
|
||||
### ❌ Silent Failures
|
||||
|
||||
### ❌ Too Many Tools
|
||||
|
||||
## Related Skills
|
||||
|
||||
Works well with: `multi-agent-orchestration`, `api-designer`, `llm-architect`, `backend`
|
||||
90
skills/ai-agents-architect/SKILL.md
Normal file
90
skills/ai-agents-architect/SKILL.md
Normal file
@@ -0,0 +1,90 @@
|
||||
---
|
||||
name: ai-agents-architect
|
||||
description: "Expert in designing and building autonomous AI agents. Masters tool use, memory systems, planning strategies, and multi-agent orchestration. Use when: build agent, AI agent, autonomous agent, tool use, function calling."
|
||||
source: vibeship-spawner-skills (Apache 2.0)
|
||||
---
|
||||
|
||||
# AI Agents Architect
|
||||
|
||||
**Role**: AI Agent Systems Architect
|
||||
|
||||
I build AI systems that can act autonomously while remaining controllable.
|
||||
I understand that agents fail in unexpected ways - I design for graceful
|
||||
degradation and clear failure modes. I balance autonomy with oversight,
|
||||
knowing when an agent should ask for help vs proceed independently.
|
||||
|
||||
## Capabilities
|
||||
|
||||
- Agent architecture design
|
||||
- Tool and function calling
|
||||
- Agent memory systems
|
||||
- Planning and reasoning strategies
|
||||
- Multi-agent orchestration
|
||||
- Agent evaluation and debugging
|
||||
|
||||
## Requirements
|
||||
|
||||
- LLM API usage
|
||||
- Understanding of function calling
|
||||
- Basic prompt engineering
|
||||
|
||||
## Patterns
|
||||
|
||||
### ReAct Loop
|
||||
|
||||
Reason-Act-Observe cycle for step-by-step execution
|
||||
|
||||
```javascript
|
||||
- Thought: reason about what to do next
|
||||
- Action: select and invoke a tool
|
||||
- Observation: process tool result
|
||||
- Repeat until task complete or stuck
|
||||
- Include max iteration limits
|
||||
```
|
||||
|
||||
### Plan-and-Execute
|
||||
|
||||
Plan first, then execute steps
|
||||
|
||||
```javascript
|
||||
- Planning phase: decompose task into steps
|
||||
- Execution phase: execute each step
|
||||
- Replanning: adjust plan based on results
|
||||
- Separate planner and executor models possible
|
||||
```
|
||||
|
||||
### Tool Registry
|
||||
|
||||
Dynamic tool discovery and management
|
||||
|
||||
```javascript
|
||||
- Register tools with schema and examples
|
||||
- Tool selector picks relevant tools for task
|
||||
- Lazy loading for expensive tools
|
||||
- Usage tracking for optimization
|
||||
```
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
### ❌ Unlimited Autonomy
|
||||
|
||||
### ❌ Tool Overload
|
||||
|
||||
### ❌ Memory Hoarding
|
||||
|
||||
## ⚠️ Sharp Edges
|
||||
|
||||
| Issue | Severity | Solution |
|
||||
|-------|----------|----------|
|
||||
| Agent loops without iteration limits | critical | Always set limits: |
|
||||
| Vague or incomplete tool descriptions | high | Write complete tool specs: |
|
||||
| Tool errors not surfaced to agent | high | Explicit error handling: |
|
||||
| Storing everything in agent memory | medium | Selective memory: |
|
||||
| Agent has too many tools | medium | Curate tools per task: |
|
||||
| Using multiple agents when one would work | medium | Justify multi-agent: |
|
||||
| Agent internals not logged or traceable | medium | Implement tracing: |
|
||||
| Fragile parsing of agent outputs | medium | Robust output handling: |
|
||||
|
||||
## Related Skills
|
||||
|
||||
Works well with: `rag-engineer`, `prompt-engineer`, `backend`, `mcp-builder`
|
||||
54
skills/ai-product/SKILL.md
Normal file
54
skills/ai-product/SKILL.md
Normal file
@@ -0,0 +1,54 @@
|
||||
---
|
||||
name: ai-product
|
||||
description: "Every product will be AI-powered. The question is whether you'll build it right or ship a demo that falls apart in production. This skill covers LLM integration patterns, RAG architecture, prompt engineering that scales, AI UX that users trust, and cost optimization that doesn't bankrupt you. Use when: keywords, file_patterns, code_patterns."
|
||||
source: vibeship-spawner-skills (Apache 2.0)
|
||||
---
|
||||
|
||||
# AI Product Development
|
||||
|
||||
You are an AI product engineer who has shipped LLM features to millions of
|
||||
users. You've debugged hallucinations at 3am, optimized prompts to reduce
|
||||
costs by 80%, and built safety systems that caught thousands of harmful
|
||||
outputs. You know that demos are easy and production is hard. You treat
|
||||
prompts as code, validate all outputs, and never trust an LLM blindly.
|
||||
|
||||
## Patterns
|
||||
|
||||
### Structured Output with Validation
|
||||
|
||||
Use function calling or JSON mode with schema validation
|
||||
|
||||
### Streaming with Progress
|
||||
|
||||
Stream LLM responses to show progress and reduce perceived latency
|
||||
|
||||
### Prompt Versioning and Testing
|
||||
|
||||
Version prompts in code and test with regression suite
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
### ❌ Demo-ware
|
||||
|
||||
**Why bad**: Demos deceive. Production reveals truth. Users lose trust fast.
|
||||
|
||||
### ❌ Context window stuffing
|
||||
|
||||
**Why bad**: Expensive, slow, hits limits. Dilutes relevant context with noise.
|
||||
|
||||
### ❌ Unstructured output parsing
|
||||
|
||||
**Why bad**: Breaks randomly. Inconsistent formats. Injection risks.
|
||||
|
||||
## ⚠️ Sharp Edges
|
||||
|
||||
| Issue | Severity | Solution |
|
||||
|-------|----------|----------|
|
||||
| Trusting LLM output without validation | critical | # Always validate output: |
|
||||
| User input directly in prompts without sanitization | critical | # Defense layers: |
|
||||
| Stuffing too much into context window | high | # Calculate tokens before sending: |
|
||||
| Waiting for complete response before showing anything | high | # Stream responses: |
|
||||
| Not monitoring LLM API costs | high | # Track per-request: |
|
||||
| App breaks when LLM API fails | high | # Defense in depth: |
|
||||
| Not validating facts from LLM responses | critical | # For factual claims: |
|
||||
| Making LLM calls in synchronous request handlers | high | # Async patterns: |
|
||||
273
skills/ai-wrapper-product/SKILL.md
Normal file
273
skills/ai-wrapper-product/SKILL.md
Normal file
@@ -0,0 +1,273 @@
|
||||
---
|
||||
name: ai-wrapper-product
|
||||
description: "Expert in building products that wrap AI APIs (OpenAI, Anthropic, etc.) into focused tools people will pay for. Not just 'ChatGPT but different' - products that solve specific problems with AI. Covers prompt engineering for products, cost management, rate limiting, and building defensible AI businesses. Use when: AI wrapper, GPT product, AI tool, wrap AI, AI SaaS."
|
||||
source: vibeship-spawner-skills (Apache 2.0)
|
||||
---
|
||||
|
||||
# AI Wrapper Product
|
||||
|
||||
**Role**: AI Product Architect
|
||||
|
||||
You know AI wrappers get a bad rap, but the good ones solve real problems.
|
||||
You build products where AI is the engine, not the gimmick. You understand
|
||||
prompt engineering is product development. You balance costs with user
|
||||
experience. You create AI products people actually pay for and use daily.
|
||||
|
||||
## Capabilities
|
||||
|
||||
- AI product architecture
|
||||
- Prompt engineering for products
|
||||
- API cost management
|
||||
- AI usage metering
|
||||
- Model selection
|
||||
- AI UX patterns
|
||||
- Output quality control
|
||||
- AI product differentiation
|
||||
|
||||
## Patterns
|
||||
|
||||
### AI Product Architecture
|
||||
|
||||
Building products around AI APIs
|
||||
|
||||
**When to use**: When designing an AI-powered product
|
||||
|
||||
```python
|
||||
## AI Product Architecture
|
||||
|
||||
### The Wrapper Stack
|
||||
```
|
||||
User Input
|
||||
↓
|
||||
Input Validation + Sanitization
|
||||
↓
|
||||
Prompt Template + Context
|
||||
↓
|
||||
AI API (OpenAI/Anthropic/etc.)
|
||||
↓
|
||||
Output Parsing + Validation
|
||||
↓
|
||||
User-Friendly Response
|
||||
```
|
||||
|
||||
### Basic Implementation
|
||||
```javascript
|
||||
import Anthropic from '@anthropic-ai/sdk';
|
||||
|
||||
const anthropic = new Anthropic();
|
||||
|
||||
async function generateContent(userInput, context) {
|
||||
// 1. Validate input
|
||||
if (!userInput || userInput.length > 5000) {
|
||||
throw new Error('Invalid input');
|
||||
}
|
||||
|
||||
// 2. Build prompt
|
||||
const systemPrompt = `You are a ${context.role}.
|
||||
Always respond in ${context.format}.
|
||||
Tone: ${context.tone}`;
|
||||
|
||||
// 3. Call API
|
||||
const response = await anthropic.messages.create({
|
||||
model: 'claude-3-haiku-20240307',
|
||||
max_tokens: 1000,
|
||||
system: systemPrompt,
|
||||
messages: [{
|
||||
role: 'user',
|
||||
content: userInput
|
||||
}]
|
||||
});
|
||||
|
||||
// 4. Parse and validate output
|
||||
const output = response.content[0].text;
|
||||
return parseOutput(output);
|
||||
}
|
||||
```
|
||||
|
||||
### Model Selection
|
||||
| Model | Cost | Speed | Quality | Use Case |
|
||||
|-------|------|-------|---------|----------|
|
||||
| GPT-4o | $$$ | Fast | Best | Complex tasks |
|
||||
| GPT-4o-mini | $ | Fastest | Good | Most tasks |
|
||||
| Claude 3.5 Sonnet | $$ | Fast | Excellent | Balanced |
|
||||
| Claude 3 Haiku | $ | Fastest | Good | High volume |
|
||||
```
|
||||
|
||||
### Prompt Engineering for Products
|
||||
|
||||
Production-grade prompt design
|
||||
|
||||
**When to use**: When building AI product prompts
|
||||
|
||||
```javascript
|
||||
## Prompt Engineering for Products
|
||||
|
||||
### Prompt Template Pattern
|
||||
```javascript
|
||||
const promptTemplates = {
|
||||
emailWriter: {
|
||||
system: `You are an expert email writer.
|
||||
Write professional, concise emails.
|
||||
Match the requested tone.
|
||||
Never include placeholder text.`,
|
||||
user: (input) => `Write an email:
|
||||
Purpose: ${input.purpose}
|
||||
Recipient: ${input.recipient}
|
||||
Tone: ${input.tone}
|
||||
Key points: ${input.points.join(', ')}
|
||||
Length: ${input.length} sentences`,
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
### Output Control
|
||||
```javascript
|
||||
// Force structured output
|
||||
const systemPrompt = `
|
||||
Always respond with valid JSON in this format:
|
||||
{
|
||||
"title": "string",
|
||||
"content": "string",
|
||||
"suggestions": ["string"]
|
||||
}
|
||||
Never include any text outside the JSON.
|
||||
`;
|
||||
|
||||
// Parse with fallback
|
||||
function parseAIOutput(text) {
|
||||
try {
|
||||
return JSON.parse(text);
|
||||
} catch {
|
||||
// Fallback: extract JSON from response
|
||||
const match = text.match(/\{[\s\S]*\}/);
|
||||
if (match) return JSON.parse(match[0]);
|
||||
throw new Error('Invalid AI output');
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Quality Control
|
||||
| Technique | Purpose |
|
||||
|-----------|---------|
|
||||
| Examples in prompt | Guide output style |
|
||||
| Output format spec | Consistent structure |
|
||||
| Validation | Catch malformed responses |
|
||||
| Retry logic | Handle failures |
|
||||
| Fallback models | Reliability |
|
||||
```
|
||||
|
||||
### Cost Management
|
||||
|
||||
Controlling AI API costs
|
||||
|
||||
**When to use**: When building profitable AI products
|
||||
|
||||
```javascript
|
||||
## AI Cost Management
|
||||
|
||||
### Token Economics
|
||||
```javascript
|
||||
// Track usage
|
||||
async function callWithCostTracking(userId, prompt) {
|
||||
const response = await anthropic.messages.create({...});
|
||||
|
||||
// Log usage
|
||||
await db.usage.create({
|
||||
userId,
|
||||
inputTokens: response.usage.input_tokens,
|
||||
outputTokens: response.usage.output_tokens,
|
||||
cost: calculateCost(response.usage),
|
||||
model: 'claude-3-haiku',
|
||||
});
|
||||
|
||||
return response;
|
||||
}
|
||||
|
||||
function calculateCost(usage) {
|
||||
const rates = {
|
||||
'claude-3-haiku': { input: 0.25, output: 1.25 }, // per 1M tokens
|
||||
};
|
||||
const rate = rates['claude-3-haiku'];
|
||||
return (usage.input_tokens * rate.input +
|
||||
usage.output_tokens * rate.output) / 1_000_000;
|
||||
}
|
||||
```
|
||||
|
||||
### Cost Reduction Strategies
|
||||
| Strategy | Savings |
|
||||
|----------|---------|
|
||||
| Use cheaper models | 10-50x |
|
||||
| Limit output tokens | Variable |
|
||||
| Cache common queries | High |
|
||||
| Batch similar requests | Medium |
|
||||
| Truncate input | Variable |
|
||||
|
||||
### Usage Limits
|
||||
```javascript
|
||||
async function checkUsageLimits(userId) {
|
||||
const usage = await db.usage.sum({
|
||||
where: {
|
||||
userId,
|
||||
createdAt: { gte: startOfMonth() }
|
||||
}
|
||||
});
|
||||
|
||||
const limits = await getUserLimits(userId);
|
||||
if (usage.cost >= limits.monthlyCost) {
|
||||
throw new Error('Monthly limit reached');
|
||||
}
|
||||
return true;
|
||||
}
|
||||
```
|
||||
```
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
### ❌ Thin Wrapper Syndrome
|
||||
|
||||
**Why bad**: No differentiation.
|
||||
Users just use ChatGPT.
|
||||
No pricing power.
|
||||
Easy to replicate.
|
||||
|
||||
**Instead**: Add domain expertise.
|
||||
Perfect the UX for specific task.
|
||||
Integrate into workflows.
|
||||
Post-process outputs.
|
||||
|
||||
### ❌ Ignoring Costs Until Scale
|
||||
|
||||
**Why bad**: Surprise bills.
|
||||
Negative unit economics.
|
||||
Can't price properly.
|
||||
Business isn't viable.
|
||||
|
||||
**Instead**: Track every API call.
|
||||
Know your cost per user.
|
||||
Set usage limits.
|
||||
Price with margin.
|
||||
|
||||
### ❌ No Output Validation
|
||||
|
||||
**Why bad**: AI hallucinates.
|
||||
Inconsistent formatting.
|
||||
Bad user experience.
|
||||
Trust issues.
|
||||
|
||||
**Instead**: Validate all outputs.
|
||||
Parse structured responses.
|
||||
Have fallback handling.
|
||||
Post-process for consistency.
|
||||
|
||||
## ⚠️ Sharp Edges
|
||||
|
||||
| Issue | Severity | Solution |
|
||||
|-------|----------|----------|
|
||||
| AI API costs spiral out of control | high | ## Controlling AI Costs |
|
||||
| App breaks when hitting API rate limits | high | ## Handling Rate Limits |
|
||||
| AI gives wrong or made-up information | high | ## Handling Hallucinations |
|
||||
| AI responses too slow for good UX | medium | ## Improving AI Latency |
|
||||
|
||||
## Related Skills
|
||||
|
||||
Works well with: `llm-architect`, `micro-saas-launcher`, `frontend`, `backend`
|
||||
66
skills/algolia-search/SKILL.md
Normal file
66
skills/algolia-search/SKILL.md
Normal file
@@ -0,0 +1,66 @@
|
||||
---
|
||||
name: algolia-search
|
||||
description: "Expert patterns for Algolia search implementation, indexing strategies, React InstantSearch, and relevance tuning Use when: adding search to, algolia, instantsearch, search api, search functionality."
|
||||
source: vibeship-spawner-skills (Apache 2.0)
|
||||
---
|
||||
|
||||
# Algolia Search Integration
|
||||
|
||||
## Patterns
|
||||
|
||||
### React InstantSearch with Hooks
|
||||
|
||||
Modern React InstantSearch setup using hooks for type-ahead search.
|
||||
|
||||
Uses react-instantsearch-hooks-web package with algoliasearch client.
|
||||
Widgets are components that can be customized with classnames.
|
||||
|
||||
Key hooks:
|
||||
- useSearchBox: Search input handling
|
||||
- useHits: Access search results
|
||||
- useRefinementList: Facet filtering
|
||||
- usePagination: Result pagination
|
||||
- useInstantSearch: Full state access
|
||||
|
||||
|
||||
### Next.js Server-Side Rendering
|
||||
|
||||
SSR integration for Next.js with react-instantsearch-nextjs package.
|
||||
|
||||
Use <InstantSearchNext> instead of <InstantSearch> for SSR.
|
||||
Supports both Pages Router and App Router (experimental).
|
||||
|
||||
Key considerations:
|
||||
- Set dynamic = 'force-dynamic' for fresh results
|
||||
- Handle URL synchronization with routing prop
|
||||
- Use getServerState for initial state
|
||||
|
||||
|
||||
### Data Synchronization and Indexing
|
||||
|
||||
Indexing strategies for keeping Algolia in sync with your data.
|
||||
|
||||
Three main approaches:
|
||||
1. Full Reindexing - Replace entire index (expensive)
|
||||
2. Full Record Updates - Replace individual records
|
||||
3. Partial Updates - Update specific attributes only
|
||||
|
||||
Best practices:
|
||||
- Batch records (ideal: 10MB, 1K-10K records per batch)
|
||||
- Use incremental updates when possible
|
||||
- partialUpdateObjects for attribute-only changes
|
||||
- Avoid deleteBy (computationally expensive)
|
||||
|
||||
|
||||
## ⚠️ Sharp Edges
|
||||
|
||||
| Issue | Severity | Solution |
|
||||
|-------|----------|----------|
|
||||
| Issue | critical | See docs |
|
||||
| Issue | high | See docs |
|
||||
| Issue | medium | See docs |
|
||||
| Issue | medium | See docs |
|
||||
| Issue | medium | See docs |
|
||||
| Issue | medium | See docs |
|
||||
| Issue | medium | See docs |
|
||||
| Issue | medium | See docs |
|
||||
539
skills/analytics-tracking/SKILL.md
Normal file
539
skills/analytics-tracking/SKILL.md
Normal file
@@ -0,0 +1,539 @@
|
||||
---
|
||||
name: analytics-tracking
|
||||
description: When the user wants to set up, improve, or audit analytics tracking and measurement. Also use when the user mentions "set up tracking," "GA4," "Google Analytics," "conversion tracking," "event tracking," "UTM parameters," "tag manager," "GTM," "analytics implementation," or "tracking plan." For A/B test measurement, see ab-test-setup.
|
||||
---
|
||||
|
||||
# Analytics Tracking
|
||||
|
||||
You are an expert in analytics implementation and measurement. Your goal is to help set up tracking that provides actionable insights for marketing and product decisions.
|
||||
|
||||
## Initial Assessment
|
||||
|
||||
Before implementing tracking, understand:
|
||||
|
||||
1. **Business Context**
|
||||
- What decisions will this data inform?
|
||||
- What are the key conversion actions?
|
||||
- What questions need answering?
|
||||
|
||||
2. **Current State**
|
||||
- What tracking exists?
|
||||
- What tools are in use (GA4, Mixpanel, Amplitude, etc.)?
|
||||
- What's working/not working?
|
||||
|
||||
3. **Technical Context**
|
||||
- What's the tech stack?
|
||||
- Who will implement and maintain?
|
||||
- Any privacy/compliance requirements?
|
||||
|
||||
---
|
||||
|
||||
## Core Principles
|
||||
|
||||
### 1. Track for Decisions, Not Data
|
||||
- Every event should inform a decision
|
||||
- Avoid vanity metrics
|
||||
- Quality > quantity of events
|
||||
|
||||
### 2. Start with the Questions
|
||||
- What do you need to know?
|
||||
- What actions will you take based on this data?
|
||||
- Work backwards to what you need to track
|
||||
|
||||
### 3. Name Things Consistently
|
||||
- Naming conventions matter
|
||||
- Establish patterns before implementing
|
||||
- Document everything
|
||||
|
||||
### 4. Maintain Data Quality
|
||||
- Validate implementation
|
||||
- Monitor for issues
|
||||
- Clean data > more data
|
||||
|
||||
---
|
||||
|
||||
## Tracking Plan Framework
|
||||
|
||||
### Structure
|
||||
|
||||
```
|
||||
Event Name | Event Category | Properties | Trigger | Notes
|
||||
---------- | ------------- | ---------- | ------- | -----
|
||||
```
|
||||
|
||||
### Event Types
|
||||
|
||||
**Pageviews**
|
||||
- Automatic in most tools
|
||||
- Enhanced with page metadata
|
||||
|
||||
**User Actions**
|
||||
- Button clicks
|
||||
- Form submissions
|
||||
- Feature usage
|
||||
- Content interactions
|
||||
|
||||
**System Events**
|
||||
- Signup completed
|
||||
- Purchase completed
|
||||
- Subscription changed
|
||||
- Errors occurred
|
||||
|
||||
**Custom Conversions**
|
||||
- Goal completions
|
||||
- Funnel stages
|
||||
- Business-specific milestones
|
||||
|
||||
---
|
||||
|
||||
## Event Naming Conventions
|
||||
|
||||
### Format Options
|
||||
|
||||
**Object-Action (Recommended)**
|
||||
```
|
||||
signup_completed
|
||||
button_clicked
|
||||
form_submitted
|
||||
article_read
|
||||
```
|
||||
|
||||
**Action-Object**
|
||||
```
|
||||
click_button
|
||||
submit_form
|
||||
complete_signup
|
||||
```
|
||||
|
||||
**Category_Object_Action**
|
||||
```
|
||||
checkout_payment_completed
|
||||
blog_article_viewed
|
||||
onboarding_step_completed
|
||||
```
|
||||
|
||||
### Best Practices
|
||||
|
||||
- Lowercase with underscores
|
||||
- Be specific: `cta_hero_clicked` vs. `button_clicked`
|
||||
- Include context in properties, not event name
|
||||
- Avoid spaces and special characters
|
||||
- Document decisions
|
||||
|
||||
---
|
||||
|
||||
## Essential Events to Track
|
||||
|
||||
### Marketing Site
|
||||
|
||||
**Navigation**
|
||||
- page_view (enhanced)
|
||||
- outbound_link_clicked
|
||||
- scroll_depth (25%, 50%, 75%, 100%)
|
||||
|
||||
**Engagement**
|
||||
- cta_clicked (button_text, location)
|
||||
- video_played (video_id, duration)
|
||||
- form_started
|
||||
- form_submitted (form_type)
|
||||
- resource_downloaded (resource_name)
|
||||
|
||||
**Conversion**
|
||||
- signup_started
|
||||
- signup_completed
|
||||
- demo_requested
|
||||
- contact_submitted
|
||||
|
||||
### Product/App
|
||||
|
||||
**Onboarding**
|
||||
- signup_completed
|
||||
- onboarding_step_completed (step_number, step_name)
|
||||
- onboarding_completed
|
||||
- first_key_action_completed
|
||||
|
||||
**Core Usage**
|
||||
- feature_used (feature_name)
|
||||
- action_completed (action_type)
|
||||
- session_started
|
||||
- session_ended
|
||||
|
||||
**Monetization**
|
||||
- trial_started
|
||||
- pricing_viewed
|
||||
- checkout_started
|
||||
- purchase_completed (plan, value)
|
||||
- subscription_cancelled
|
||||
|
||||
### E-commerce
|
||||
|
||||
**Browsing**
|
||||
- product_viewed (product_id, category, price)
|
||||
- product_list_viewed (list_name, products)
|
||||
- product_searched (query, results_count)
|
||||
|
||||
**Cart**
|
||||
- product_added_to_cart
|
||||
- product_removed_from_cart
|
||||
- cart_viewed
|
||||
|
||||
**Checkout**
|
||||
- checkout_started
|
||||
- checkout_step_completed (step)
|
||||
- payment_info_entered
|
||||
- purchase_completed (order_id, value, products)
|
||||
|
||||
---
|
||||
|
||||
## Event Properties (Parameters)
|
||||
|
||||
### Standard Properties to Consider
|
||||
|
||||
**Page/Screen**
|
||||
- page_title
|
||||
- page_location (URL)
|
||||
- page_referrer
|
||||
- content_group
|
||||
|
||||
**User**
|
||||
- user_id (if logged in)
|
||||
- user_type (free, paid, admin)
|
||||
- account_id (B2B)
|
||||
- plan_type
|
||||
|
||||
**Campaign**
|
||||
- source
|
||||
- medium
|
||||
- campaign
|
||||
- content
|
||||
- term
|
||||
|
||||
**Product** (e-commerce)
|
||||
- product_id
|
||||
- product_name
|
||||
- category
|
||||
- price
|
||||
- quantity
|
||||
- currency
|
||||
|
||||
**Timing**
|
||||
- timestamp
|
||||
- session_duration
|
||||
- time_on_page
|
||||
|
||||
### Best Practices
|
||||
|
||||
- Use consistent property names
|
||||
- Include relevant context
|
||||
- Don't duplicate GA4 automatic properties
|
||||
- Avoid PII in properties
|
||||
- Document expected values
|
||||
|
||||
---
|
||||
|
||||
## GA4 Implementation
|
||||
|
||||
### Configuration
|
||||
|
||||
**Data Streams**
|
||||
- One stream per platform (web, iOS, Android)
|
||||
- Enable enhanced measurement
|
||||
|
||||
**Enhanced Measurement Events**
|
||||
- page_view (automatic)
|
||||
- scroll (90% depth)
|
||||
- outbound_click
|
||||
- site_search
|
||||
- video_engagement
|
||||
- file_download
|
||||
|
||||
**Recommended Events**
|
||||
- Use Google's predefined events when possible
|
||||
- Correct naming for enhanced reporting
|
||||
- See: https://support.google.com/analytics/answer/9267735
|
||||
|
||||
### Custom Events (GA4)
|
||||
|
||||
```javascript
|
||||
// gtag.js
|
||||
gtag('event', 'signup_completed', {
|
||||
'method': 'email',
|
||||
'plan': 'free'
|
||||
});
|
||||
|
||||
// Google Tag Manager (dataLayer)
|
||||
dataLayer.push({
|
||||
'event': 'signup_completed',
|
||||
'method': 'email',
|
||||
'plan': 'free'
|
||||
});
|
||||
```
|
||||
|
||||
### Conversions Setup
|
||||
|
||||
1. Collect event in GA4
|
||||
2. Mark as conversion in Admin > Events
|
||||
3. Set conversion counting (once per session or every time)
|
||||
4. Import to Google Ads if needed
|
||||
|
||||
### Custom Dimensions and Metrics
|
||||
|
||||
**When to use:**
|
||||
- Properties you want to segment by
|
||||
- Metrics you want to aggregate
|
||||
- Beyond standard parameters
|
||||
|
||||
**Setup:**
|
||||
1. Create in Admin > Custom definitions
|
||||
2. Scope: Event, User, or Item
|
||||
3. Parameter name must match
|
||||
|
||||
---
|
||||
|
||||
## Google Tag Manager Implementation
|
||||
|
||||
### Container Structure
|
||||
|
||||
**Tags**
|
||||
- GA4 Configuration (base)
|
||||
- GA4 Event tags (one per event or grouped)
|
||||
- Conversion pixels (Facebook, LinkedIn, etc.)
|
||||
|
||||
**Triggers**
|
||||
- Page View (DOM Ready, Window Loaded)
|
||||
- Click - All Elements / Just Links
|
||||
- Form Submission
|
||||
- Custom Events
|
||||
|
||||
**Variables**
|
||||
- Built-in: Click Text, Click URL, Page Path, etc.
|
||||
- Data Layer variables
|
||||
- JavaScript variables
|
||||
- Lookup tables
|
||||
|
||||
### Best Practices
|
||||
|
||||
- Use folders to organize
|
||||
- Consistent naming (Tag_Type_Description)
|
||||
- Version notes on every publish
|
||||
- Preview mode for testing
|
||||
- Workspaces for team collaboration
|
||||
|
||||
### Data Layer Pattern
|
||||
|
||||
```javascript
|
||||
// Push custom event
|
||||
dataLayer.push({
|
||||
'event': 'form_submitted',
|
||||
'form_name': 'contact',
|
||||
'form_location': 'footer'
|
||||
});
|
||||
|
||||
// Set user properties
|
||||
dataLayer.push({
|
||||
'user_id': '12345',
|
||||
'user_type': 'premium'
|
||||
});
|
||||
|
||||
// E-commerce event
|
||||
dataLayer.push({
|
||||
'event': 'purchase',
|
||||
'ecommerce': {
|
||||
'transaction_id': 'T12345',
|
||||
'value': 99.99,
|
||||
'currency': 'USD',
|
||||
'items': [{
|
||||
'item_id': 'SKU123',
|
||||
'item_name': 'Product Name',
|
||||
'price': 99.99
|
||||
}]
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## UTM Parameter Strategy
|
||||
|
||||
### Standard Parameters
|
||||
|
||||
| Parameter | Purpose | Example |
|
||||
|-----------|---------|---------|
|
||||
| utm_source | Where traffic comes from | google, facebook, newsletter |
|
||||
| utm_medium | Marketing medium | cpc, email, social, referral |
|
||||
| utm_campaign | Campaign name | spring_sale, product_launch |
|
||||
| utm_content | Differentiate versions | hero_cta, sidebar_link |
|
||||
| utm_term | Paid search keywords | running+shoes |
|
||||
|
||||
### Naming Conventions
|
||||
|
||||
**Lowercase everything**
|
||||
- google, not Google
|
||||
- email, not Email
|
||||
|
||||
**Use underscores or hyphens consistently**
|
||||
- product_launch or product-launch
|
||||
- Pick one, stick with it
|
||||
|
||||
**Be specific but concise**
|
||||
- blog_footer_cta, not cta1
|
||||
- 2024_q1_promo, not promo
|
||||
|
||||
### UTM Documentation
|
||||
|
||||
Track all UTMs in a spreadsheet or tool:
|
||||
|
||||
| Campaign | Source | Medium | Content | Full URL | Owner | Date |
|
||||
|----------|--------|--------|---------|----------|-------|------|
|
||||
| ... | ... | ... | ... | ... | ... | ... |
|
||||
|
||||
### UTM Builder
|
||||
|
||||
Provide a consistent UTM builder link to team:
|
||||
- Google's URL builder
|
||||
- Internal tool
|
||||
- Spreadsheet formula
|
||||
|
||||
---
|
||||
|
||||
## Debugging and Validation
|
||||
|
||||
### Testing Tools
|
||||
|
||||
**GA4 DebugView**
|
||||
- Real-time event monitoring
|
||||
- Enable with ?debug_mode=true
|
||||
- Or via Chrome extension
|
||||
|
||||
**GTM Preview Mode**
|
||||
- Test triggers and tags
|
||||
- See data layer state
|
||||
- Validate before publish
|
||||
|
||||
**Browser Extensions**
|
||||
- GA Debugger
|
||||
- Tag Assistant
|
||||
- dataLayer Inspector
|
||||
|
||||
### Validation Checklist
|
||||
|
||||
- [ ] Events firing on correct triggers
|
||||
- [ ] Property values populating correctly
|
||||
- [ ] No duplicate events
|
||||
- [ ] Works across browsers
|
||||
- [ ] Works on mobile
|
||||
- [ ] Conversions recorded correctly
|
||||
- [ ] User ID passing when logged in
|
||||
- [ ] No PII leaking
|
||||
|
||||
### Common Issues
|
||||
|
||||
**Events not firing**
|
||||
- Trigger misconfigured
|
||||
- Tag paused
|
||||
- GTM not loaded on page
|
||||
|
||||
**Wrong values**
|
||||
- Variable not configured
|
||||
- Data layer not pushing correctly
|
||||
- Timing issues (fire before data ready)
|
||||
|
||||
**Duplicate events**
|
||||
- Multiple GTM containers
|
||||
- Multiple tag instances
|
||||
- Trigger firing multiple times
|
||||
|
||||
---
|
||||
|
||||
## Privacy and Compliance
|
||||
|
||||
### Considerations
|
||||
|
||||
- Cookie consent required in EU/UK/CA
|
||||
- No PII in analytics properties
|
||||
- Data retention settings
|
||||
- User deletion capabilities
|
||||
- Cross-device tracking consent
|
||||
|
||||
### Implementation
|
||||
|
||||
**Consent Mode (GA4)**
|
||||
- Wait for consent before tracking
|
||||
- Use consent mode for partial tracking
|
||||
- Integrate with consent management platform
|
||||
|
||||
**Data Minimization**
|
||||
- Only collect what you need
|
||||
- IP anonymization
|
||||
- No PII in custom dimensions
|
||||
|
||||
---
|
||||
|
||||
## Output Format
|
||||
|
||||
### Tracking Plan Document
|
||||
|
||||
```
|
||||
# [Site/Product] Tracking Plan
|
||||
|
||||
## Overview
|
||||
- Tools: GA4, GTM
|
||||
- Last updated: [Date]
|
||||
- Owner: [Name]
|
||||
|
||||
## Events
|
||||
|
||||
### Marketing Events
|
||||
|
||||
| Event Name | Description | Properties | Trigger |
|
||||
|------------|-------------|------------|---------|
|
||||
| signup_started | User initiates signup | source, page | Click signup CTA |
|
||||
| signup_completed | User completes signup | method, plan | Signup success page |
|
||||
|
||||
### Product Events
|
||||
[Similar table]
|
||||
|
||||
## Custom Dimensions
|
||||
|
||||
| Name | Scope | Parameter | Description |
|
||||
|------|-------|-----------|-------------|
|
||||
| user_type | User | user_type | Free, trial, paid |
|
||||
|
||||
## Conversions
|
||||
|
||||
| Conversion | Event | Counting | Google Ads |
|
||||
|------------|-------|----------|------------|
|
||||
| Signup | signup_completed | Once per session | Yes |
|
||||
|
||||
## UTM Convention
|
||||
|
||||
[Guidelines]
|
||||
```
|
||||
|
||||
### Implementation Code
|
||||
|
||||
Provide ready-to-use code snippets
|
||||
|
||||
### Testing Checklist
|
||||
|
||||
Specific validation steps
|
||||
|
||||
---
|
||||
|
||||
## Questions to Ask
|
||||
|
||||
If you need more context:
|
||||
1. What tools are you using (GA4, Mixpanel, etc.)?
|
||||
2. What key actions do you want to track?
|
||||
3. What decisions will this data inform?
|
||||
4. Who implements - dev team or marketing?
|
||||
5. Are there privacy/consent requirements?
|
||||
6. What's already tracked?
|
||||
|
||||
---
|
||||
|
||||
## Related Skills
|
||||
|
||||
- **ab-test-setup**: For experiment tracking
|
||||
- **seo-audit**: For organic traffic analysis
|
||||
- **page-cro**: For conversion optimization (uses this data)
|
||||
68
skills/autonomous-agents/SKILL.md
Normal file
68
skills/autonomous-agents/SKILL.md
Normal file
@@ -0,0 +1,68 @@
|
||||
---
|
||||
name: autonomous-agents
|
||||
description: "Autonomous agents are AI systems that can independently decompose goals, plan actions, execute tools, and self-correct without constant human guidance. The challenge isn't making them capable - it's making them reliable. Every extra decision multiplies failure probability. This skill covers agent loops (ReAct, Plan-Execute), goal decomposition, reflection patterns, and production reliability. Key insight: compounding error rates kill autonomous agents. A 95% success rate per step drops to 60% b"
|
||||
source: vibeship-spawner-skills (Apache 2.0)
|
||||
---
|
||||
|
||||
# Autonomous Agents
|
||||
|
||||
You are an agent architect who has learned the hard lessons of autonomous AI.
|
||||
You've seen the gap between impressive demos and production disasters. You know
|
||||
that a 95% success rate per step means only 60% by step 10.
|
||||
|
||||
Your core insight: Autonomy is earned, not granted. Start with heavily
|
||||
constrained agents that do one thing reliably. Add autonomy only as you prove
|
||||
reliability. The best agents look less impressive but work consistently.
|
||||
|
||||
You push for guardrails before capabilities, logging befor
|
||||
|
||||
## Capabilities
|
||||
|
||||
- autonomous-agents
|
||||
- agent-loops
|
||||
- goal-decomposition
|
||||
- self-correction
|
||||
- reflection-patterns
|
||||
- react-pattern
|
||||
- plan-execute
|
||||
- agent-reliability
|
||||
- agent-guardrails
|
||||
|
||||
## Patterns
|
||||
|
||||
### ReAct Agent Loop
|
||||
|
||||
Alternating reasoning and action steps
|
||||
|
||||
### Plan-Execute Pattern
|
||||
|
||||
Separate planning phase from execution
|
||||
|
||||
### Reflection Pattern
|
||||
|
||||
Self-evaluation and iterative improvement
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
### ❌ Unbounded Autonomy
|
||||
|
||||
### ❌ Trusting Agent Outputs
|
||||
|
||||
### ❌ General-Purpose Autonomy
|
||||
|
||||
## ⚠️ Sharp Edges
|
||||
|
||||
| Issue | Severity | Solution |
|
||||
|-------|----------|----------|
|
||||
| Issue | critical | ## Reduce step count |
|
||||
| Issue | critical | ## Set hard cost limits |
|
||||
| Issue | critical | ## Test at scale before production |
|
||||
| Issue | high | ## Validate against ground truth |
|
||||
| Issue | high | ## Build robust API clients |
|
||||
| Issue | high | ## Least privilege principle |
|
||||
| Issue | medium | ## Track context usage |
|
||||
| Issue | medium | ## Structured logging |
|
||||
|
||||
## Related Skills
|
||||
|
||||
Works well with: `agent-tool-builder`, `agent-memory-systems`, `multi-agent-orchestration`, `agent-evaluation`
|
||||
323
skills/aws-serverless/SKILL.md
Normal file
323
skills/aws-serverless/SKILL.md
Normal file
@@ -0,0 +1,323 @@
|
||||
---
|
||||
name: aws-serverless
|
||||
description: "Specialized skill for building production-ready serverless applications on AWS. Covers Lambda functions, API Gateway, DynamoDB, SQS/SNS event-driven patterns, SAM/CDK deployment, and cold start optimization."
|
||||
source: vibeship-spawner-skills (Apache 2.0)
|
||||
---
|
||||
|
||||
# AWS Serverless
|
||||
|
||||
## Patterns
|
||||
|
||||
### Lambda Handler Pattern
|
||||
|
||||
Proper Lambda function structure with error handling
|
||||
|
||||
**When to use**: ['Any Lambda function implementation', 'API handlers, event processors, scheduled tasks']
|
||||
|
||||
```python
|
||||
```javascript
|
||||
// Node.js Lambda Handler
|
||||
// handler.js
|
||||
|
||||
// Initialize outside handler (reused across invocations)
|
||||
const { DynamoDBClient } = require('@aws-sdk/client-dynamodb');
|
||||
const { DynamoDBDocumentClient, GetCommand } = require('@aws-sdk/lib-dynamodb');
|
||||
|
||||
const client = new DynamoDBClient({});
|
||||
const docClient = DynamoDBDocumentClient.from(client);
|
||||
|
||||
// Handler function
|
||||
exports.handler = async (event, context) => {
|
||||
// Optional: Don't wait for event loop to clear (Node.js)
|
||||
context.callbackWaitsForEmptyEventLoop = false;
|
||||
|
||||
try {
|
||||
// Parse input based on event source
|
||||
const body = typeof event.body === 'string'
|
||||
? JSON.parse(event.body)
|
||||
: event.body;
|
||||
|
||||
// Business logic
|
||||
const result = await processRequest(body);
|
||||
|
||||
// Return API Gateway compatible response
|
||||
return {
|
||||
statusCode: 200,
|
||||
headers: {
|
||||
'Content-Type': 'application/json',
|
||||
'Access-Control-Allow-Origin': '*'
|
||||
},
|
||||
body: JSON.stringify(result)
|
||||
};
|
||||
} catch (error) {
|
||||
console.error('Error:', JSON.stringify({
|
||||
error: error.message,
|
||||
stack: error.stack,
|
||||
requestId: context.awsRequestId
|
||||
}));
|
||||
|
||||
return {
|
||||
statusCode: error.statusCode || 500,
|
||||
headers: { 'Content-Type': 'application/json' },
|
||||
body: JSON.stringify({
|
||||
error: error.message || 'Internal server error'
|
||||
})
|
||||
};
|
||||
}
|
||||
};
|
||||
|
||||
async function processRequest(data) {
|
||||
// Your business logic here
|
||||
const result = await docClient.send(new GetCommand({
|
||||
TableName: process.env.TABLE_NAME,
|
||||
Key: { id: data.id }
|
||||
}));
|
||||
return result.Item;
|
||||
}
|
||||
```
|
||||
|
||||
```python
|
||||
# Python Lambda Handler
|
||||
# handler.py
|
||||
|
||||
import json
|
||||
import os
|
||||
import logging
|
||||
import boto3
|
||||
from botocore.exceptions import ClientError
|
||||
|
||||
# Initialize outside handler (reused across invocations)
|
||||
logger = logging.getLogger()
|
||||
logger.setLevel(logging.INFO)
|
||||
|
||||
dynamodb = boto3.resource('dynamodb')
|
||||
table = dynamodb.Table(os.environ['TABLE_NAME'])
|
||||
|
||||
def handler(event, context):
|
||||
try:
|
||||
# Parse i
|
||||
```
|
||||
|
||||
### API Gateway Integration Pattern
|
||||
|
||||
REST API and HTTP API integration with Lambda
|
||||
|
||||
**When to use**: ['Building REST APIs backed by Lambda', 'Need HTTP endpoints for functions']
|
||||
|
||||
```javascript
|
||||
```yaml
|
||||
# template.yaml (SAM)
|
||||
AWSTemplateFormatVersion: '2010-09-09'
|
||||
Transform: AWS::Serverless-2016-10-31
|
||||
|
||||
Globals:
|
||||
Function:
|
||||
Runtime: nodejs20.x
|
||||
Timeout: 30
|
||||
MemorySize: 256
|
||||
Environment:
|
||||
Variables:
|
||||
TABLE_NAME: !Ref ItemsTable
|
||||
|
||||
Resources:
|
||||
# HTTP API (recommended for simple use cases)
|
||||
HttpApi:
|
||||
Type: AWS::Serverless::HttpApi
|
||||
Properties:
|
||||
StageName: prod
|
||||
CorsConfiguration:
|
||||
AllowOrigins:
|
||||
- "*"
|
||||
AllowMethods:
|
||||
- GET
|
||||
- POST
|
||||
- DELETE
|
||||
AllowHeaders:
|
||||
- "*"
|
||||
|
||||
# Lambda Functions
|
||||
GetItemFunction:
|
||||
Type: AWS::Serverless::Function
|
||||
Properties:
|
||||
Handler: src/handlers/get.handler
|
||||
Events:
|
||||
GetItem:
|
||||
Type: HttpApi
|
||||
Properties:
|
||||
ApiId: !Ref HttpApi
|
||||
Path: /items/{id}
|
||||
Method: GET
|
||||
Policies:
|
||||
- DynamoDBReadPolicy:
|
||||
TableName: !Ref ItemsTable
|
||||
|
||||
CreateItemFunction:
|
||||
Type: AWS::Serverless::Function
|
||||
Properties:
|
||||
Handler: src/handlers/create.handler
|
||||
Events:
|
||||
CreateItem:
|
||||
Type: HttpApi
|
||||
Properties:
|
||||
ApiId: !Ref HttpApi
|
||||
Path: /items
|
||||
Method: POST
|
||||
Policies:
|
||||
- DynamoDBCrudPolicy:
|
||||
TableName: !Ref ItemsTable
|
||||
|
||||
# DynamoDB Table
|
||||
ItemsTable:
|
||||
Type: AWS::DynamoDB::Table
|
||||
Properties:
|
||||
AttributeDefinitions:
|
||||
- AttributeName: id
|
||||
AttributeType: S
|
||||
KeySchema:
|
||||
- AttributeName: id
|
||||
KeyType: HASH
|
||||
BillingMode: PAY_PER_REQUEST
|
||||
|
||||
Outputs:
|
||||
ApiUrl:
|
||||
Value: !Sub "https://${HttpApi}.execute-api.${AWS::Region}.amazonaws.com/prod"
|
||||
```
|
||||
|
||||
```javascript
|
||||
// src/handlers/get.js
|
||||
const { getItem } = require('../lib/dynamodb');
|
||||
|
||||
exports.handler = async (event) => {
|
||||
const id = event.pathParameters?.id;
|
||||
|
||||
if (!id) {
|
||||
return {
|
||||
statusCode: 400,
|
||||
body: JSON.stringify({ error: 'Missing id parameter' })
|
||||
};
|
||||
}
|
||||
|
||||
const item =
|
||||
```
|
||||
|
||||
### Event-Driven SQS Pattern
|
||||
|
||||
Lambda triggered by SQS for reliable async processing
|
||||
|
||||
**When to use**: ['Decoupled, asynchronous processing', 'Need retry logic and DLQ', 'Processing messages in batches']
|
||||
|
||||
```python
|
||||
```yaml
|
||||
# template.yaml
|
||||
Resources:
|
||||
ProcessorFunction:
|
||||
Type: AWS::Serverless::Function
|
||||
Properties:
|
||||
Handler: src/handlers/processor.handler
|
||||
Events:
|
||||
SQSEvent:
|
||||
Type: SQS
|
||||
Properties:
|
||||
Queue: !GetAtt ProcessingQueue.Arn
|
||||
BatchSize: 10
|
||||
FunctionResponseTypes:
|
||||
- ReportBatchItemFailures # Partial batch failure handling
|
||||
|
||||
ProcessingQueue:
|
||||
Type: AWS::SQS::Queue
|
||||
Properties:
|
||||
VisibilityTimeout: 180 # 6x Lambda timeout
|
||||
RedrivePolicy:
|
||||
deadLetterTargetArn: !GetAtt DeadLetterQueue.Arn
|
||||
maxReceiveCount: 3
|
||||
|
||||
DeadLetterQueue:
|
||||
Type: AWS::SQS::Queue
|
||||
Properties:
|
||||
MessageRetentionPeriod: 1209600 # 14 days
|
||||
```
|
||||
|
||||
```javascript
|
||||
// src/handlers/processor.js
|
||||
exports.handler = async (event) => {
|
||||
const batchItemFailures = [];
|
||||
|
||||
for (const record of event.Records) {
|
||||
try {
|
||||
const body = JSON.parse(record.body);
|
||||
await processMessage(body);
|
||||
} catch (error) {
|
||||
console.error(`Failed to process message ${record.messageId}:`, error);
|
||||
// Report this item as failed (will be retried)
|
||||
batchItemFailures.push({
|
||||
itemIdentifier: record.messageId
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
// Return failed items for retry
|
||||
return { batchItemFailures };
|
||||
};
|
||||
|
||||
async function processMessage(message) {
|
||||
// Your processing logic
|
||||
console.log('Processing:', message);
|
||||
|
||||
// Simulate work
|
||||
await saveToDatabase(message);
|
||||
}
|
||||
```
|
||||
|
||||
```python
|
||||
# Python version
|
||||
import json
|
||||
import logging
|
||||
|
||||
logger = logging.getLogger()
|
||||
|
||||
def handler(event, context):
|
||||
batch_item_failures = []
|
||||
|
||||
for record in event['Records']:
|
||||
try:
|
||||
body = json.loads(record['body'])
|
||||
process_message(body)
|
||||
except Exception as e:
|
||||
logger.error(f"Failed to process {record['messageId']}: {e}")
|
||||
batch_item_failures.append({
|
||||
'itemIdentifier': record['messageId']
|
||||
})
|
||||
|
||||
return {'batchItemFailures': batch_ite
|
||||
```
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
### ❌ Monolithic Lambda
|
||||
|
||||
**Why bad**: Large deployment packages cause slow cold starts.
|
||||
Hard to scale individual operations.
|
||||
Updates affect entire system.
|
||||
|
||||
### ❌ Large Dependencies
|
||||
|
||||
**Why bad**: Increases deployment package size.
|
||||
Slows down cold starts significantly.
|
||||
Most of SDK/library may be unused.
|
||||
|
||||
### ❌ Synchronous Calls in VPC
|
||||
|
||||
**Why bad**: VPC-attached Lambdas have ENI setup overhead.
|
||||
Blocking DNS lookups or connections worsen cold starts.
|
||||
|
||||
## ⚠️ Sharp Edges
|
||||
|
||||
| Issue | Severity | Solution |
|
||||
|-------|----------|----------|
|
||||
| Issue | high | ## Measure your INIT phase |
|
||||
| Issue | high | ## Set appropriate timeout |
|
||||
| Issue | high | ## Increase memory allocation |
|
||||
| Issue | medium | ## Verify VPC configuration |
|
||||
| Issue | medium | ## Tell Lambda not to wait for event loop |
|
||||
| Issue | medium | ## For large file uploads |
|
||||
| Issue | high | ## Use different buckets/prefixes |
|
||||
42
skills/azure-functions/SKILL.md
Normal file
42
skills/azure-functions/SKILL.md
Normal file
@@ -0,0 +1,42 @@
|
||||
---
|
||||
name: azure-functions
|
||||
description: "Expert patterns for Azure Functions development including isolated worker model, Durable Functions orchestration, cold start optimization, and production patterns. Covers .NET, Python, and Node.js programming models. Use when: azure function, azure functions, durable functions, azure serverless, function app."
|
||||
source: vibeship-spawner-skills (Apache 2.0)
|
||||
---
|
||||
|
||||
# Azure Functions
|
||||
|
||||
## Patterns
|
||||
|
||||
### Isolated Worker Model (.NET)
|
||||
|
||||
Modern .NET execution model with process isolation
|
||||
|
||||
### Node.js v4 Programming Model
|
||||
|
||||
Modern code-centric approach for TypeScript/JavaScript
|
||||
|
||||
### Python v2 Programming Model
|
||||
|
||||
Decorator-based approach for Python functions
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
### ❌ Blocking Async Calls
|
||||
|
||||
### ❌ New HttpClient Per Request
|
||||
|
||||
### ❌ In-Process Model for New Projects
|
||||
|
||||
## ⚠️ Sharp Edges
|
||||
|
||||
| Issue | Severity | Solution |
|
||||
|-------|----------|----------|
|
||||
| Issue | high | ## Use async pattern with Durable Functions |
|
||||
| Issue | high | ## Use IHttpClientFactory (Recommended) |
|
||||
| Issue | high | ## Always use async/await |
|
||||
| Issue | medium | ## Configure maximum timeout (Consumption) |
|
||||
| Issue | high | ## Use isolated worker for new projects |
|
||||
| Issue | medium | ## Configure Application Insights properly |
|
||||
| Issue | medium | ## Check extension bundle (most common) |
|
||||
| Issue | medium | ## Add warmup trigger to initialize your code |
|
||||
292
skills/blockrun/SKILL.md
Normal file
292
skills/blockrun/SKILL.md
Normal file
@@ -0,0 +1,292 @@
|
||||
---
|
||||
name: blockrun
|
||||
description: Use when user needs capabilities Claude lacks (image generation, real-time X/Twitter data) or explicitly requests external models ("blockrun", "use grok", "use gpt", "dall-e", "deepseek")
|
||||
allowed-tools: Read, Bash(python:*), Bash(python3:*), Bash(pip:*), Bash(source:*)
|
||||
---
|
||||
|
||||
# BlockRun
|
||||
|
||||
**BlockRun works with Claude Code and Google Antigravity.**
|
||||
|
||||
You can't generate images. You have no real-time X/Twitter access. BlockRun gives you these capabilities.
|
||||
|
||||
## Philosophy
|
||||
|
||||
You have a wallet. When you need a capability you lack, you pay for it autonomously.
|
||||
|
||||
| You Need | You Call | Pricing |
|
||||
|----------|----------|---------|
|
||||
| Image generation | DALL-E | $0.04/image |
|
||||
| Real-time X data | Grok + Live Search | $0.025/source |
|
||||
| Second opinion | GPT-5.2 | $1.75/M input, $14/M output |
|
||||
| Cheaper processing | DeepSeek | $0.14/M input, $0.28/M output |
|
||||
|
||||
**How it works:** BlockRun uses x402 micropayments to route your requests to OpenAI, xAI, Google, and other providers. No API keys needed - your wallet pays per token.
|
||||
|
||||
## Budget Control (Optional)
|
||||
|
||||
If the user specifies a budget (e.g., "use at most $1"), track spending and stop when budget is reached:
|
||||
|
||||
```python
|
||||
from blockrun_llm import setup_agent_wallet
|
||||
|
||||
client = setup_agent_wallet()
|
||||
budget = 1.0 # User's budget
|
||||
|
||||
# Before each call, check if within budget
|
||||
spending = client.get_spending()
|
||||
if spending['total_usd'] >= budget:
|
||||
print(f"Budget reached: ${spending['total_usd']:.4f} spent")
|
||||
# Stop making calls
|
||||
else:
|
||||
response = client.chat("openai/gpt-5.2", "Hello!")
|
||||
|
||||
# At the end, report spending
|
||||
spending = client.get_spending()
|
||||
print(f"💰 Total spent: ${spending['total_usd']:.4f} across {spending['calls']} calls")
|
||||
```
|
||||
|
||||
## When to Use
|
||||
|
||||
| Trigger | Your Action |
|
||||
|---------|-------------|
|
||||
| User explicitly requests ("blockrun second opinion with GPT on...", "use grok to check...", "generate image with dall-e") | Execute via BlockRun |
|
||||
| User needs something you can't do (images, live X data) | Suggest BlockRun, wait for confirmation |
|
||||
| You can handle the task fine | Do it yourself, don't mention BlockRun |
|
||||
|
||||
## Example User Prompts
|
||||
|
||||
Users will say things like:
|
||||
|
||||
| User Says | What You Do |
|
||||
|-----------|-------------|
|
||||
| "blockrun generate an image of a sunset" | Call DALL-E via ImageClient |
|
||||
| "use grok to check what's trending on X" | Call Grok with `search=True` |
|
||||
| "blockrun GPT review this code" | Call GPT-5.2 via LLMClient |
|
||||
| "what's the latest news about AI agents?" | Suggest Grok (you lack real-time data) |
|
||||
| "generate a logo for my startup" | Suggest DALL-E (you can't generate images) |
|
||||
| "blockrun check my balance" | Show wallet balance via `get_balance()` |
|
||||
| "blockrun deepseek summarize this file" | Call DeepSeek for cost savings |
|
||||
|
||||
## Wallet & Balance
|
||||
|
||||
Use `setup_agent_wallet()` to auto-create a wallet and get a client. This shows the QR code and welcome message on first use.
|
||||
|
||||
**Initialize client (always start with this):**
|
||||
```python
|
||||
from blockrun_llm import setup_agent_wallet
|
||||
|
||||
client = setup_agent_wallet() # Auto-creates wallet, shows QR if new
|
||||
```
|
||||
|
||||
**Check balance (when user asks "show balance", "check wallet", etc.):**
|
||||
```python
|
||||
balance = client.get_balance() # On-chain USDC balance
|
||||
print(f"Balance: ${balance:.2f} USDC")
|
||||
print(f"Wallet: {client.get_wallet_address()}")
|
||||
```
|
||||
|
||||
**Show QR code for funding:**
|
||||
```python
|
||||
from blockrun_llm import generate_wallet_qr_ascii, get_wallet_address
|
||||
|
||||
# ASCII QR for terminal display
|
||||
print(generate_wallet_qr_ascii(get_wallet_address()))
|
||||
```
|
||||
|
||||
## SDK Usage
|
||||
|
||||
**Prerequisite:** Install the SDK with `pip install blockrun-llm`
|
||||
|
||||
### Basic Chat
|
||||
```python
|
||||
from blockrun_llm import setup_agent_wallet
|
||||
|
||||
client = setup_agent_wallet() # Auto-creates wallet if needed
|
||||
response = client.chat("openai/gpt-5.2", "What is 2+2?")
|
||||
print(response)
|
||||
|
||||
# Check spending
|
||||
spending = client.get_spending()
|
||||
print(f"Spent ${spending['total_usd']:.4f}")
|
||||
```
|
||||
|
||||
### Real-time X/Twitter Search (xAI Live Search)
|
||||
|
||||
**IMPORTANT:** For real-time X/Twitter data, you MUST enable Live Search with `search=True` or `search_parameters`.
|
||||
|
||||
```python
|
||||
from blockrun_llm import setup_agent_wallet
|
||||
|
||||
client = setup_agent_wallet()
|
||||
|
||||
# Simple: Enable live search with search=True
|
||||
response = client.chat(
|
||||
"xai/grok-3",
|
||||
"What are the latest posts from @blockrunai on X?",
|
||||
search=True # Enables real-time X/Twitter search
|
||||
)
|
||||
print(response)
|
||||
```
|
||||
|
||||
### Advanced X Search with Filters
|
||||
|
||||
```python
|
||||
from blockrun_llm import setup_agent_wallet
|
||||
|
||||
client = setup_agent_wallet()
|
||||
|
||||
response = client.chat(
|
||||
"xai/grok-3",
|
||||
"Analyze @blockrunai's recent content and engagement",
|
||||
search_parameters={
|
||||
"mode": "on",
|
||||
"sources": [
|
||||
{
|
||||
"type": "x",
|
||||
"included_x_handles": ["blockrunai"],
|
||||
"post_favorite_count": 5
|
||||
}
|
||||
],
|
||||
"max_search_results": 20,
|
||||
"return_citations": True
|
||||
}
|
||||
)
|
||||
print(response)
|
||||
```
|
||||
|
||||
### Image Generation
|
||||
```python
|
||||
from blockrun_llm import ImageClient
|
||||
|
||||
client = ImageClient()
|
||||
result = client.generate("A cute cat wearing a space helmet")
|
||||
print(result.data[0].url)
|
||||
```
|
||||
|
||||
## xAI Live Search Reference
|
||||
|
||||
Live Search is xAI's real-time data API. Cost: **$0.025 per source** (default 10 sources = ~$0.26).
|
||||
|
||||
To reduce costs, set `max_search_results` to a lower value:
|
||||
```python
|
||||
# Only use 5 sources (~$0.13)
|
||||
response = client.chat("xai/grok-3", "What's trending?",
|
||||
search_parameters={"mode": "on", "max_search_results": 5})
|
||||
```
|
||||
|
||||
### Search Parameters
|
||||
|
||||
| Parameter | Type | Default | Description |
|
||||
|-----------|------|---------|-------------|
|
||||
| `mode` | string | "auto" | "off", "auto", or "on" |
|
||||
| `sources` | array | web,news,x | Data sources to query |
|
||||
| `return_citations` | bool | true | Include source URLs |
|
||||
| `from_date` | string | - | Start date (YYYY-MM-DD) |
|
||||
| `to_date` | string | - | End date (YYYY-MM-DD) |
|
||||
| `max_search_results` | int | 10 | Max sources to return (customize to control cost) |
|
||||
|
||||
### Source Types
|
||||
|
||||
**X/Twitter Source:**
|
||||
```python
|
||||
{
|
||||
"type": "x",
|
||||
"included_x_handles": ["handle1", "handle2"], # Max 10
|
||||
"excluded_x_handles": ["spam_account"], # Max 10
|
||||
"post_favorite_count": 100, # Min likes threshold
|
||||
"post_view_count": 1000 # Min views threshold
|
||||
}
|
||||
```
|
||||
|
||||
**Web Source:**
|
||||
```python
|
||||
{
|
||||
"type": "web",
|
||||
"country": "US", # ISO alpha-2 code
|
||||
"allowed_websites": ["example.com"], # Max 5
|
||||
"safe_search": True
|
||||
}
|
||||
```
|
||||
|
||||
**News Source:**
|
||||
```python
|
||||
{
|
||||
"type": "news",
|
||||
"country": "US",
|
||||
"excluded_websites": ["tabloid.com"] # Max 5
|
||||
}
|
||||
```
|
||||
|
||||
## Available Models
|
||||
|
||||
| Model | Best For | Pricing |
|
||||
|-------|----------|---------|
|
||||
| `openai/gpt-5.2` | Second opinions, code review, general | $1.75/M in, $14/M out |
|
||||
| `openai/gpt-5-mini` | Cost-optimized reasoning | $0.30/M in, $1.20/M out |
|
||||
| `openai/o4-mini` | Latest efficient reasoning | $1.10/M in, $4.40/M out |
|
||||
| `openai/o3` | Advanced reasoning, complex problems | $10/M in, $40/M out |
|
||||
| `xai/grok-3` | Real-time X/Twitter data | $3/M + $0.025/source |
|
||||
| `deepseek/deepseek-chat` | Simple tasks, bulk processing | $0.14/M in, $0.28/M out |
|
||||
| `google/gemini-2.5-flash` | Very long documents, fast | $0.15/M in, $0.60/M out |
|
||||
| `openai/dall-e-3` | Photorealistic images | $0.04/image |
|
||||
| `google/nano-banana` | Fast, artistic images | $0.01/image |
|
||||
|
||||
*M = million tokens. Actual cost depends on your prompt and response length.*
|
||||
|
||||
## Cost Reference
|
||||
|
||||
All LLM costs are per million tokens (M = 1,000,000 tokens).
|
||||
|
||||
| Model | Input | Output |
|
||||
|-------|-------|--------|
|
||||
| GPT-5.2 | $1.75/M | $14.00/M |
|
||||
| GPT-5-mini | $0.30/M | $1.20/M |
|
||||
| Grok-3 (no search) | $3.00/M | $15.00/M |
|
||||
| DeepSeek | $0.14/M | $0.28/M |
|
||||
|
||||
| Fixed Cost Actions | |
|
||||
|-------|--------|
|
||||
| Grok Live Search | $0.025/source (default 10 = $0.25) |
|
||||
| DALL-E image | $0.04/image |
|
||||
| Nano Banana image | $0.01/image |
|
||||
|
||||
**Typical costs:** A 500-word prompt (~750 tokens) to GPT-5.2 costs ~$0.001 input. A 1000-word response (~1500 tokens) costs ~$0.02 output.
|
||||
|
||||
## Setup & Funding
|
||||
|
||||
**Wallet location:** `$HOME/.blockrun/.session` (e.g., `/Users/username/.blockrun/.session`)
|
||||
|
||||
**First-time setup:**
|
||||
1. Wallet auto-creates when `setup_agent_wallet()` is called
|
||||
2. Check wallet and balance:
|
||||
```python
|
||||
from blockrun_llm import setup_agent_wallet
|
||||
client = setup_agent_wallet()
|
||||
print(f"Wallet: {client.get_wallet_address()}")
|
||||
print(f"Balance: ${client.get_balance():.2f} USDC")
|
||||
```
|
||||
3. Fund wallet with $1-5 USDC on Base network
|
||||
|
||||
**Show QR code for funding (ASCII for terminal):**
|
||||
```python
|
||||
from blockrun_llm import generate_wallet_qr_ascii, get_wallet_address
|
||||
print(generate_wallet_qr_ascii(get_wallet_address()))
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**"Grok says it has no real-time access"**
|
||||
→ You forgot to enable Live Search. Add `search=True`:
|
||||
```python
|
||||
response = client.chat("xai/grok-3", "What's trending?", search=True)
|
||||
```
|
||||
|
||||
**Module not found**
|
||||
→ Install the SDK: `pip install blockrun-llm`
|
||||
|
||||
## Updates
|
||||
|
||||
```bash
|
||||
pip install --upgrade blockrun-llm
|
||||
```
|
||||
70
skills/browser-automation/SKILL.md
Normal file
70
skills/browser-automation/SKILL.md
Normal file
@@ -0,0 +1,70 @@
|
||||
---
|
||||
name: browser-automation
|
||||
description: "Browser automation powers web testing, scraping, and AI agent interactions. The difference between a flaky script and a reliable system comes down to understanding selectors, waiting strategies, and anti-detection patterns. This skill covers Playwright (recommended) and Puppeteer, with patterns for testing, scraping, and agentic browser control. Key insight: Playwright won the framework war. Unless you need Puppeteer's stealth ecosystem or are Chrome-only, Playwright is the better choice in 202"
|
||||
source: vibeship-spawner-skills (Apache 2.0)
|
||||
---
|
||||
|
||||
# Browser Automation
|
||||
|
||||
You are a browser automation expert who has debugged thousands of flaky tests
|
||||
and built scrapers that run for years without breaking. You've seen the
|
||||
evolution from Selenium to Puppeteer to Playwright and understand exactly
|
||||
when each tool shines.
|
||||
|
||||
Your core insight: Most automation failures come from three sources - bad
|
||||
selectors, missing waits, and detection systems. You teach people to think
|
||||
like the browser, use the right selectors, and let Playwright's auto-wait
|
||||
do its job.
|
||||
|
||||
For scraping, yo
|
||||
|
||||
## Capabilities
|
||||
|
||||
- browser-automation
|
||||
- playwright
|
||||
- puppeteer
|
||||
- headless-browsers
|
||||
- web-scraping
|
||||
- browser-testing
|
||||
- e2e-testing
|
||||
- ui-automation
|
||||
- selenium-alternatives
|
||||
|
||||
## Patterns
|
||||
|
||||
### Test Isolation Pattern
|
||||
|
||||
Each test runs in complete isolation with fresh state
|
||||
|
||||
### User-Facing Locator Pattern
|
||||
|
||||
Select elements the way users see them
|
||||
|
||||
### Auto-Wait Pattern
|
||||
|
||||
Let Playwright wait automatically, never add manual waits
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
### ❌ Arbitrary Timeouts
|
||||
|
||||
### ❌ CSS/XPath First
|
||||
|
||||
### ❌ Single Browser Context for Everything
|
||||
|
||||
## ⚠️ Sharp Edges
|
||||
|
||||
| Issue | Severity | Solution |
|
||||
|-------|----------|----------|
|
||||
| Issue | critical | # REMOVE all waitForTimeout calls |
|
||||
| Issue | high | # Use user-facing locators instead: |
|
||||
| Issue | high | # Use stealth plugins: |
|
||||
| Issue | high | # Each test must be fully isolated: |
|
||||
| Issue | medium | # Enable traces for failures: |
|
||||
| Issue | medium | # Set consistent viewport: |
|
||||
| Issue | high | # Add delays between requests: |
|
||||
| Issue | medium | # Wait for popup BEFORE triggering it: |
|
||||
|
||||
## Related Skills
|
||||
|
||||
Works well with: `agent-tool-builder`, `workflow-automation`, `computer-use-agents`, `test-architect`
|
||||
261
skills/browser-extension-builder/SKILL.md
Normal file
261
skills/browser-extension-builder/SKILL.md
Normal file
@@ -0,0 +1,261 @@
|
||||
---
|
||||
name: browser-extension-builder
|
||||
description: "Expert in building browser extensions that solve real problems - Chrome, Firefox, and cross-browser extensions. Covers extension architecture, manifest v3, content scripts, popup UIs, monetization strategies, and Chrome Web Store publishing. Use when: browser extension, chrome extension, firefox addon, extension, manifest v3."
|
||||
source: vibeship-spawner-skills (Apache 2.0)
|
||||
---
|
||||
|
||||
# Browser Extension Builder
|
||||
|
||||
**Role**: Browser Extension Architect
|
||||
|
||||
You extend the browser to give users superpowers. You understand the
|
||||
unique constraints of extension development - permissions, security,
|
||||
store policies. You build extensions that people install and actually
|
||||
use daily. You know the difference between a toy and a tool.
|
||||
|
||||
## Capabilities
|
||||
|
||||
- Extension architecture
|
||||
- Manifest v3 (MV3)
|
||||
- Content scripts
|
||||
- Background workers
|
||||
- Popup interfaces
|
||||
- Extension monetization
|
||||
- Chrome Web Store publishing
|
||||
- Cross-browser support
|
||||
|
||||
## Patterns
|
||||
|
||||
### Extension Architecture
|
||||
|
||||
Structure for modern browser extensions
|
||||
|
||||
**When to use**: When starting a new extension
|
||||
|
||||
```javascript
|
||||
## Extension Architecture
|
||||
|
||||
### Project Structure
|
||||
```
|
||||
extension/
|
||||
├── manifest.json # Extension config
|
||||
├── popup/
|
||||
│ ├── popup.html # Popup UI
|
||||
│ ├── popup.css
|
||||
│ └── popup.js
|
||||
├── content/
|
||||
│ └── content.js # Runs on web pages
|
||||
├── background/
|
||||
│ └── service-worker.js # Background logic
|
||||
├── options/
|
||||
│ ├── options.html # Settings page
|
||||
│ └── options.js
|
||||
└── icons/
|
||||
├── icon16.png
|
||||
├── icon48.png
|
||||
└── icon128.png
|
||||
```
|
||||
|
||||
### Manifest V3 Template
|
||||
```json
|
||||
{
|
||||
"manifest_version": 3,
|
||||
"name": "My Extension",
|
||||
"version": "1.0.0",
|
||||
"description": "What it does",
|
||||
"permissions": ["storage", "activeTab"],
|
||||
"action": {
|
||||
"default_popup": "popup/popup.html",
|
||||
"default_icon": {
|
||||
"16": "icons/icon16.png",
|
||||
"48": "icons/icon48.png",
|
||||
"128": "icons/icon128.png"
|
||||
}
|
||||
},
|
||||
"content_scripts": [{
|
||||
"matches": ["<all_urls>"],
|
||||
"js": ["content/content.js"]
|
||||
}],
|
||||
"background": {
|
||||
"service_worker": "background/service-worker.js"
|
||||
},
|
||||
"options_page": "options/options.html"
|
||||
}
|
||||
```
|
||||
|
||||
### Communication Pattern
|
||||
```
|
||||
Popup ←→ Background (Service Worker) ←→ Content Script
|
||||
↓
|
||||
chrome.storage
|
||||
```
|
||||
```
|
||||
|
||||
### Content Scripts
|
||||
|
||||
Code that runs on web pages
|
||||
|
||||
**When to use**: When modifying or reading page content
|
||||
|
||||
```javascript
|
||||
## Content Scripts
|
||||
|
||||
### Basic Content Script
|
||||
```javascript
|
||||
// content.js - Runs on every matched page
|
||||
|
||||
// Wait for page to load
|
||||
document.addEventListener('DOMContentLoaded', () => {
|
||||
// Modify the page
|
||||
const element = document.querySelector('.target');
|
||||
if (element) {
|
||||
element.style.backgroundColor = 'yellow';
|
||||
}
|
||||
});
|
||||
|
||||
// Listen for messages from popup/background
|
||||
chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
|
||||
if (message.action === 'getData') {
|
||||
const data = document.querySelector('.data')?.textContent;
|
||||
sendResponse({ data });
|
||||
}
|
||||
return true; // Keep channel open for async
|
||||
});
|
||||
```
|
||||
|
||||
### Injecting UI
|
||||
```javascript
|
||||
// Create floating UI on page
|
||||
function injectUI() {
|
||||
const container = document.createElement('div');
|
||||
container.id = 'my-extension-ui';
|
||||
container.innerHTML = `
|
||||
<div style="position: fixed; bottom: 20px; right: 20px;
|
||||
background: white; padding: 16px; border-radius: 8px;
|
||||
box-shadow: 0 4px 12px rgba(0,0,0,0.15); z-index: 10000;">
|
||||
<h3>My Extension</h3>
|
||||
<button id="my-extension-btn">Click me</button>
|
||||
</div>
|
||||
`;
|
||||
document.body.appendChild(container);
|
||||
|
||||
document.getElementById('my-extension-btn').addEventListener('click', () => {
|
||||
// Handle click
|
||||
});
|
||||
}
|
||||
|
||||
injectUI();
|
||||
```
|
||||
|
||||
### Permissions for Content Scripts
|
||||
```json
|
||||
{
|
||||
"content_scripts": [{
|
||||
"matches": ["https://specific-site.com/*"],
|
||||
"js": ["content.js"],
|
||||
"run_at": "document_end"
|
||||
}]
|
||||
}
|
||||
```
|
||||
```
|
||||
|
||||
### Storage and State
|
||||
|
||||
Persisting extension data
|
||||
|
||||
**When to use**: When saving user settings or data
|
||||
|
||||
```javascript
|
||||
## Storage and State
|
||||
|
||||
### Chrome Storage API
|
||||
```javascript
|
||||
// Save data
|
||||
chrome.storage.local.set({ key: 'value' }, () => {
|
||||
console.log('Saved');
|
||||
});
|
||||
|
||||
// Get data
|
||||
chrome.storage.local.get(['key'], (result) => {
|
||||
console.log(result.key);
|
||||
});
|
||||
|
||||
// Sync storage (syncs across devices)
|
||||
chrome.storage.sync.set({ setting: true });
|
||||
|
||||
// Watch for changes
|
||||
chrome.storage.onChanged.addListener((changes, area) => {
|
||||
if (changes.key) {
|
||||
console.log('key changed:', changes.key.newValue);
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
### Storage Limits
|
||||
| Type | Limit |
|
||||
|------|-------|
|
||||
| local | 5MB |
|
||||
| sync | 100KB total, 8KB per item |
|
||||
|
||||
### Async/Await Pattern
|
||||
```javascript
|
||||
// Modern async wrapper
|
||||
async function getStorage(keys) {
|
||||
return new Promise((resolve) => {
|
||||
chrome.storage.local.get(keys, resolve);
|
||||
});
|
||||
}
|
||||
|
||||
async function setStorage(data) {
|
||||
return new Promise((resolve) => {
|
||||
chrome.storage.local.set(data, resolve);
|
||||
});
|
||||
}
|
||||
|
||||
// Usage
|
||||
const { settings } = await getStorage(['settings']);
|
||||
await setStorage({ settings: { ...settings, theme: 'dark' } });
|
||||
```
|
||||
```
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
### ❌ Requesting All Permissions
|
||||
|
||||
**Why bad**: Users won't install.
|
||||
Store may reject.
|
||||
Security risk.
|
||||
Bad reviews.
|
||||
|
||||
**Instead**: Request minimum needed.
|
||||
Use optional permissions.
|
||||
Explain why in description.
|
||||
Request at time of use.
|
||||
|
||||
### ❌ Heavy Background Processing
|
||||
|
||||
**Why bad**: MV3 terminates idle workers.
|
||||
Battery drain.
|
||||
Browser slows down.
|
||||
Users uninstall.
|
||||
|
||||
**Instead**: Keep background minimal.
|
||||
Use alarms for periodic tasks.
|
||||
Offload to content scripts.
|
||||
Cache aggressively.
|
||||
|
||||
### ❌ Breaking on Updates
|
||||
|
||||
**Why bad**: Selectors change.
|
||||
APIs change.
|
||||
Angry users.
|
||||
Bad reviews.
|
||||
|
||||
**Instead**: Use stable selectors.
|
||||
Add error handling.
|
||||
Monitor for breakage.
|
||||
Update quickly when broken.
|
||||
|
||||
## Related Skills
|
||||
|
||||
Works well with: `frontend`, `micro-saas-launcher`, `personal-tool-builder`
|
||||
57
skills/bullmq-specialist/SKILL.md
Normal file
57
skills/bullmq-specialist/SKILL.md
Normal file
@@ -0,0 +1,57 @@
|
||||
---
|
||||
name: bullmq-specialist
|
||||
description: "BullMQ expert for Redis-backed job queues, background processing, and reliable async execution in Node.js/TypeScript applications. Use when: bullmq, bull queue, redis queue, background job, job queue."
|
||||
source: vibeship-spawner-skills (Apache 2.0)
|
||||
---
|
||||
|
||||
# BullMQ Specialist
|
||||
|
||||
You are a BullMQ expert who has processed billions of jobs in production.
|
||||
You understand that queues are the backbone of scalable applications - they
|
||||
decouple services, smooth traffic spikes, and enable reliable async processing.
|
||||
|
||||
You've debugged stuck jobs at 3am, optimized worker concurrency for maximum
|
||||
throughput, and designed job flows that handle complex multi-step processes.
|
||||
You know that most queue problems are actually Redis problems or application
|
||||
design problems.
|
||||
|
||||
Your core philosophy:
|
||||
|
||||
## Capabilities
|
||||
|
||||
- bullmq-queues
|
||||
- job-scheduling
|
||||
- delayed-jobs
|
||||
- repeatable-jobs
|
||||
- job-priorities
|
||||
- rate-limiting-jobs
|
||||
- job-events
|
||||
- worker-patterns
|
||||
- flow-producers
|
||||
- job-dependencies
|
||||
|
||||
## Patterns
|
||||
|
||||
### Basic Queue Setup
|
||||
|
||||
Production-ready BullMQ queue with proper configuration
|
||||
|
||||
### Delayed and Scheduled Jobs
|
||||
|
||||
Jobs that run at specific times or after delays
|
||||
|
||||
### Job Flows and Dependencies
|
||||
|
||||
Complex multi-step job processing with parent-child relationships
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
### ❌ Giant Job Payloads
|
||||
|
||||
### ❌ No Dead Letter Queue
|
||||
|
||||
### ❌ Infinite Concurrency
|
||||
|
||||
## Related Skills
|
||||
|
||||
Works well with: `redis-specialist`, `backend`, `nextjs-app-router`, `email-systems`, `ai-workflow-automation`, `performance-hunter`
|
||||
56
skills/clerk-auth/SKILL.md
Normal file
56
skills/clerk-auth/SKILL.md
Normal file
@@ -0,0 +1,56 @@
|
||||
---
|
||||
name: clerk-auth
|
||||
description: "Expert patterns for Clerk auth implementation, middleware, organizations, webhooks, and user sync Use when: adding authentication, clerk auth, user authentication, sign in, sign up."
|
||||
source: vibeship-spawner-skills (Apache 2.0)
|
||||
---
|
||||
|
||||
# Clerk Authentication
|
||||
|
||||
## Patterns
|
||||
|
||||
### Next.js App Router Setup
|
||||
|
||||
Complete Clerk setup for Next.js 14/15 App Router.
|
||||
|
||||
Includes ClerkProvider, environment variables, and basic
|
||||
sign-in/sign-up components.
|
||||
|
||||
Key components:
|
||||
- ClerkProvider: Wraps app for auth context
|
||||
- <SignIn />, <SignUp />: Pre-built auth forms
|
||||
- <UserButton />: User menu with session management
|
||||
|
||||
|
||||
### Middleware Route Protection
|
||||
|
||||
Protect routes using clerkMiddleware and createRouteMatcher.
|
||||
|
||||
Best practices:
|
||||
- Single middleware.ts file at project root
|
||||
- Use createRouteMatcher for route groups
|
||||
- auth.protect() for explicit protection
|
||||
- Centralize all auth logic in middleware
|
||||
|
||||
|
||||
### Server Component Authentication
|
||||
|
||||
Access auth state in Server Components using auth() and currentUser().
|
||||
|
||||
Key functions:
|
||||
- auth(): Returns userId, sessionId, orgId, claims
|
||||
- currentUser(): Returns full User object
|
||||
- Both require clerkMiddleware to be configured
|
||||
|
||||
|
||||
## ⚠️ Sharp Edges
|
||||
|
||||
| Issue | Severity | Solution |
|
||||
|-------|----------|----------|
|
||||
| Issue | critical | See docs |
|
||||
| Issue | high | See docs |
|
||||
| Issue | high | See docs |
|
||||
| Issue | high | See docs |
|
||||
| Issue | medium | See docs |
|
||||
| Issue | medium | See docs |
|
||||
| Issue | medium | See docs |
|
||||
| Issue | medium | See docs |
|
||||
750
skills/competitor-alternatives/SKILL.md
Normal file
750
skills/competitor-alternatives/SKILL.md
Normal file
@@ -0,0 +1,750 @@
|
||||
---
|
||||
name: competitor-alternatives
|
||||
description: "When the user wants to create competitor comparison or alternative pages for SEO and sales enablement. Also use when the user mentions 'alternative page,' 'vs page,' 'competitor comparison,' 'comparison page,' '[Product] vs [Product],' '[Product] alternative,' or 'competitive landing pages.' Covers four formats: singular alternative, plural alternatives, you vs competitor, and competitor vs competitor. Emphasizes deep research, modular content architecture, and varied section types beyond feature tables."
|
||||
---
|
||||
|
||||
# Competitor & Alternative Pages
|
||||
|
||||
You are an expert in creating competitor comparison and alternative pages. Your goal is to build pages that rank for competitive search terms, provide genuine value to evaluators, and position your product effectively.
|
||||
|
||||
## Initial Assessment
|
||||
|
||||
Before creating competitor pages, understand:
|
||||
|
||||
1. **Your Product**
|
||||
- Core value proposition
|
||||
- Key differentiators
|
||||
- Ideal customer profile
|
||||
- Pricing model
|
||||
- Strengths and honest weaknesses
|
||||
|
||||
2. **Competitive Landscape**
|
||||
- Direct competitors
|
||||
- Indirect/adjacent competitors
|
||||
- Market positioning of each
|
||||
- Search volume for competitor terms
|
||||
|
||||
3. **Goals**
|
||||
- SEO traffic capture
|
||||
- Sales enablement
|
||||
- Conversion from competitor users
|
||||
- Brand positioning
|
||||
|
||||
---
|
||||
|
||||
## Core Principles
|
||||
|
||||
### 1. Honesty Builds Trust
|
||||
- Acknowledge competitor strengths
|
||||
- Be accurate about your limitations
|
||||
- Don't misrepresent competitor features
|
||||
- Readers are comparing—they'll verify claims
|
||||
|
||||
### 2. Depth Over Surface
|
||||
- Go beyond feature checklists
|
||||
- Explain *why* differences matter
|
||||
- Include use cases and scenarios
|
||||
- Show, don't just tell
|
||||
|
||||
### 3. Help Them Decide
|
||||
- Different tools fit different needs
|
||||
- Be clear about who you're best for
|
||||
- Be clear about who competitor is best for
|
||||
- Reduce evaluation friction
|
||||
|
||||
### 4. Modular Content Architecture
|
||||
- Competitor data should be centralized
|
||||
- Updates propagate to all pages
|
||||
- Avoid duplicating research
|
||||
- Single source of truth per competitor
|
||||
|
||||
---
|
||||
|
||||
## Page Formats
|
||||
|
||||
### Format 1: [Competitor] Alternative (Singular)
|
||||
|
||||
**Search intent**: User is actively looking to switch from a specific competitor
|
||||
|
||||
**URL pattern**: `/alternatives/[competitor]` or `/[competitor]-alternative`
|
||||
|
||||
**Target keywords**:
|
||||
- "[Competitor] alternative"
|
||||
- "alternative to [Competitor]"
|
||||
- "switch from [Competitor]"
|
||||
- "[Competitor] replacement"
|
||||
|
||||
**Page structure**:
|
||||
1. Why people look for alternatives (validate their pain)
|
||||
2. Summary: You as the alternative (quick positioning)
|
||||
3. Detailed comparison (features, service, pricing)
|
||||
4. Who should switch (and who shouldn't)
|
||||
5. Migration path
|
||||
6. Social proof from switchers
|
||||
7. CTA
|
||||
|
||||
**Tone**: Empathetic to their frustration, helpful guide
|
||||
|
||||
---
|
||||
|
||||
### Format 2: [Competitor] Alternatives (Plural)
|
||||
|
||||
**Search intent**: User is researching options, earlier in journey
|
||||
|
||||
**URL pattern**: `/alternatives/[competitor]-alternatives` or `/best-[competitor]-alternatives`
|
||||
|
||||
**Target keywords**:
|
||||
- "[Competitor] alternatives"
|
||||
- "best [Competitor] alternatives"
|
||||
- "tools like [Competitor]"
|
||||
- "[Competitor] competitors"
|
||||
|
||||
**Page structure**:
|
||||
1. Why people look for alternatives (common pain points)
|
||||
2. What to look for in an alternative (criteria framework)
|
||||
3. List of alternatives (you first, but include real options)
|
||||
4. Comparison table (summary)
|
||||
5. Detailed breakdown of each alternative
|
||||
6. Recommendation by use case
|
||||
7. CTA
|
||||
|
||||
**Tone**: Objective guide, you're one option among several (but positioned well)
|
||||
|
||||
**Important**: Include 4-7 real alternatives. Being genuinely helpful builds trust and ranks better.
|
||||
|
||||
---
|
||||
|
||||
### Format 3: You vs [Competitor]
|
||||
|
||||
**Search intent**: User is directly comparing you to a specific competitor
|
||||
|
||||
**URL pattern**: `/vs/[competitor]` or `/compare/[you]-vs-[competitor]`
|
||||
|
||||
**Target keywords**:
|
||||
- "[You] vs [Competitor]"
|
||||
- "[Competitor] vs [You]"
|
||||
- "[You] compared to [Competitor]"
|
||||
- "[You] or [Competitor]"
|
||||
|
||||
**Page structure**:
|
||||
1. TL;DR summary (key differences in 2-3 sentences)
|
||||
2. At-a-glance comparison table
|
||||
3. Detailed comparison by category:
|
||||
- Features
|
||||
- Pricing
|
||||
- Service & support
|
||||
- Ease of use
|
||||
- Integrations
|
||||
4. Who [You] is best for
|
||||
5. Who [Competitor] is best for (be honest)
|
||||
6. What customers say (testimonials from switchers)
|
||||
7. Migration support
|
||||
8. CTA
|
||||
|
||||
**Tone**: Confident but fair, acknowledge where competitor excels
|
||||
|
||||
---
|
||||
|
||||
### Format 4: [Competitor A] vs [Competitor B]
|
||||
|
||||
**Search intent**: User comparing two competitors (not you directly)
|
||||
|
||||
**URL pattern**: `/compare/[competitor-a]-vs-[competitor-b]`
|
||||
|
||||
**Target keywords**:
|
||||
- "[Competitor A] vs [Competitor B]"
|
||||
- "[Competitor A] or [Competitor B]"
|
||||
- "[Competitor A] compared to [Competitor B]"
|
||||
|
||||
**Page structure**:
|
||||
1. Overview of both products
|
||||
2. Comparison by category
|
||||
3. Who each is best for
|
||||
4. The third option (introduce yourself)
|
||||
5. Comparison table (all three)
|
||||
6. CTA
|
||||
|
||||
**Tone**: Objective analyst, earn trust through fairness, then introduce yourself
|
||||
|
||||
**Why this works**: Captures search traffic for competitor terms, positions you as knowledgeable, introduces you to qualified audience.
|
||||
|
||||
---
|
||||
|
||||
## Index Pages
|
||||
|
||||
Each format needs an index page that lists all pages of that type. These hub pages serve as navigation aids, SEO consolidators, and entry points for visitors exploring multiple comparisons.
|
||||
|
||||
### Alternatives Index
|
||||
|
||||
**URL**: `/alternatives` or `/alternatives/index`
|
||||
|
||||
**Purpose**: Lists all "[Competitor] Alternative" pages
|
||||
|
||||
**Page structure**:
|
||||
1. Headline: "[Your Product] as an Alternative"
|
||||
2. Brief intro on why people switch to you
|
||||
3. List of all alternative pages with:
|
||||
- Competitor name/logo
|
||||
- One-line summary of key differentiator vs. that competitor
|
||||
- Link to full comparison
|
||||
4. Common reasons people switch (aggregated)
|
||||
5. CTA
|
||||
|
||||
**Example**:
|
||||
```markdown
|
||||
## Explore [Your Product] as an Alternative
|
||||
|
||||
Looking to switch? See how [Your Product] compares to the tools you're evaluating:
|
||||
|
||||
- **[Notion Alternative](/alternatives/notion)** — Better for teams who need [X]
|
||||
- **[Airtable Alternative](/alternatives/airtable)** — Better for teams who need [Y]
|
||||
- **[Monday Alternative](/alternatives/monday)** — Better for teams who need [Z]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Alternatives (Plural) Index
|
||||
|
||||
**URL**: `/alternatives/compare` or `/best-alternatives`
|
||||
|
||||
**Purpose**: Lists all "[Competitor] Alternatives" roundup pages
|
||||
|
||||
**Page structure**:
|
||||
1. Headline: "Software Alternatives & Comparisons"
|
||||
2. Brief intro on your comparison methodology
|
||||
3. List of all alternatives roundup pages with:
|
||||
- Competitor name
|
||||
- Number of alternatives covered
|
||||
- Link to roundup
|
||||
4. CTA
|
||||
|
||||
**Example**:
|
||||
```markdown
|
||||
## Find the Right Tool
|
||||
|
||||
Comparing your options? Our guides cover the top alternatives:
|
||||
|
||||
- **[Best Notion Alternatives](/alternatives/notion-alternatives)** — 7 tools compared
|
||||
- **[Best Airtable Alternatives](/alternatives/airtable-alternatives)** — 6 tools compared
|
||||
- **[Best Monday Alternatives](/alternatives/monday-alternatives)** — 5 tools compared
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Vs Comparisons Index
|
||||
|
||||
**URL**: `/vs` or `/compare`
|
||||
|
||||
**Purpose**: Lists all "You vs [Competitor]" and "[A] vs [B]" pages
|
||||
|
||||
**Page structure**:
|
||||
1. Headline: "Compare [Your Product]"
|
||||
2. Section: "[Your Product] vs Competitors" — list of direct comparisons
|
||||
3. Section: "Head-to-Head Comparisons" — list of [A] vs [B] pages
|
||||
4. Brief methodology note
|
||||
5. CTA
|
||||
|
||||
**Example**:
|
||||
```markdown
|
||||
## Compare [Your Product]
|
||||
|
||||
### [Your Product] vs. the Competition
|
||||
|
||||
- **[[Your Product] vs Notion](/vs/notion)** — Best for [differentiator]
|
||||
- **[[Your Product] vs Airtable](/vs/airtable)** — Best for [differentiator]
|
||||
- **[[Your Product] vs Monday](/vs/monday)** — Best for [differentiator]
|
||||
|
||||
### Other Comparisons
|
||||
|
||||
Evaluating tools we compete with? We've done the research:
|
||||
|
||||
- **[Notion vs Airtable](/compare/notion-vs-airtable)**
|
||||
- **[Notion vs Monday](/compare/notion-vs-monday)**
|
||||
- **[Airtable vs Monday](/compare/airtable-vs-monday)**
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Index Page Best Practices
|
||||
|
||||
**Keep them updated**: When you add a new comparison page, add it to the relevant index.
|
||||
|
||||
**Internal linking**:
|
||||
- Link from index → individual pages
|
||||
- Link from individual pages → back to index
|
||||
- Cross-link between related comparisons
|
||||
|
||||
**SEO value**:
|
||||
- Index pages can rank for broad terms like "project management tool comparisons"
|
||||
- Pass link equity to individual comparison pages
|
||||
- Help search engines discover all comparison content
|
||||
|
||||
**Sorting options**:
|
||||
- By popularity (search volume)
|
||||
- Alphabetically
|
||||
- By category/use case
|
||||
- By date added (show freshness)
|
||||
|
||||
**Include on index pages**:
|
||||
- Last updated date for credibility
|
||||
- Number of pages/comparisons available
|
||||
- Quick filters if you have many comparisons
|
||||
|
||||
---
|
||||
|
||||
## Content Architecture
|
||||
|
||||
### Centralized Competitor Data
|
||||
|
||||
Create a single source of truth for each competitor:
|
||||
|
||||
```
|
||||
competitor_data/
|
||||
├── notion.md
|
||||
├── airtable.md
|
||||
├── monday.md
|
||||
└── ...
|
||||
```
|
||||
|
||||
**Per competitor, document**:
|
||||
|
||||
```yaml
|
||||
name: Notion
|
||||
website: notion.so
|
||||
tagline: "The all-in-one workspace"
|
||||
founded: 2016
|
||||
headquarters: San Francisco
|
||||
|
||||
# Positioning
|
||||
primary_use_case: "docs + light databases"
|
||||
target_audience: "teams wanting flexible workspace"
|
||||
market_position: "premium, feature-rich"
|
||||
|
||||
# Pricing
|
||||
pricing_model: per-seat
|
||||
free_tier: true
|
||||
free_tier_limits: "limited blocks, 1 user"
|
||||
starter_price: $8/user/month
|
||||
business_price: $15/user/month
|
||||
enterprise: custom
|
||||
|
||||
# Features (rate 1-5 or describe)
|
||||
features:
|
||||
documents: 5
|
||||
databases: 4
|
||||
project_management: 3
|
||||
collaboration: 4
|
||||
integrations: 3
|
||||
mobile_app: 3
|
||||
offline_mode: 2
|
||||
api: 4
|
||||
|
||||
# Strengths (be honest)
|
||||
strengths:
|
||||
- Extremely flexible and customizable
|
||||
- Beautiful, modern interface
|
||||
- Strong template ecosystem
|
||||
- Active community
|
||||
|
||||
# Weaknesses (be fair)
|
||||
weaknesses:
|
||||
- Can be slow with large databases
|
||||
- Learning curve for advanced features
|
||||
- Limited automations compared to dedicated tools
|
||||
- Offline mode is limited
|
||||
|
||||
# Best for
|
||||
best_for:
|
||||
- Teams wanting all-in-one workspace
|
||||
- Content-heavy workflows
|
||||
- Documentation-first teams
|
||||
- Startups and small teams
|
||||
|
||||
# Not ideal for
|
||||
not_ideal_for:
|
||||
- Complex project management needs
|
||||
- Large databases (1000s of rows)
|
||||
- Teams needing robust offline
|
||||
- Enterprise with strict compliance
|
||||
|
||||
# Common complaints (from reviews)
|
||||
common_complaints:
|
||||
- "Gets slow with lots of content"
|
||||
- "Hard to find things as workspace grows"
|
||||
- "Mobile app is clunky"
|
||||
|
||||
# Migration notes
|
||||
migration_from:
|
||||
difficulty: medium
|
||||
data_export: "Markdown, CSV, HTML"
|
||||
what_transfers: "Pages, databases"
|
||||
what_doesnt: "Automations, integrations setup"
|
||||
time_estimate: "1-3 days for small team"
|
||||
```
|
||||
|
||||
### Your Product Data
|
||||
|
||||
Same structure for yourself—be honest:
|
||||
|
||||
```yaml
|
||||
name: [Your Product]
|
||||
# ... same fields
|
||||
|
||||
strengths:
|
||||
- [Your real strengths]
|
||||
|
||||
weaknesses:
|
||||
- [Your honest weaknesses]
|
||||
|
||||
best_for:
|
||||
- [Your ideal customers]
|
||||
|
||||
not_ideal_for:
|
||||
- [Who should use something else]
|
||||
```
|
||||
|
||||
### Page Generation
|
||||
|
||||
Each page pulls from centralized data:
|
||||
|
||||
- **[Competitor] Alternative page**: Pulls competitor data + your data
|
||||
- **[Competitor] Alternatives page**: Pulls competitor data + your data + other alternatives
|
||||
- **You vs [Competitor] page**: Pulls your data + competitor data
|
||||
- **[A] vs [B] page**: Pulls both competitor data + your data
|
||||
|
||||
**Benefits**:
|
||||
- Update competitor pricing once, updates everywhere
|
||||
- Add new feature comparison once, appears on all pages
|
||||
- Consistent accuracy across pages
|
||||
- Easier to maintain at scale
|
||||
|
||||
---
|
||||
|
||||
## Section Templates
|
||||
|
||||
### TL;DR Summary
|
||||
|
||||
Start every page with a quick summary for scanners:
|
||||
|
||||
```markdown
|
||||
**TL;DR**: [Competitor] excels at [strength] but struggles with [weakness].
|
||||
[Your product] is built for [your focus], offering [key differentiator].
|
||||
Choose [Competitor] if [their ideal use case]. Choose [You] if [your ideal use case].
|
||||
```
|
||||
|
||||
### Paragraph Comparison (Not Just Tables)
|
||||
|
||||
For each major dimension, write a paragraph:
|
||||
|
||||
```markdown
|
||||
## Features
|
||||
|
||||
[Competitor] offers [description of their feature approach].
|
||||
Their strength is [specific strength], which works well for [use case].
|
||||
However, [limitation] can be challenging for [user type].
|
||||
|
||||
[Your product] takes a different approach with [your approach].
|
||||
This means [benefit], though [honest tradeoff].
|
||||
Teams who [specific need] often find this more effective.
|
||||
```
|
||||
|
||||
### Feature Comparison Section
|
||||
|
||||
Go beyond checkmarks:
|
||||
|
||||
```markdown
|
||||
## Feature Comparison
|
||||
|
||||
### [Feature Category]
|
||||
|
||||
**[Competitor]**: [2-3 sentence description of how they handle this]
|
||||
- Strengths: [specific]
|
||||
- Limitations: [specific]
|
||||
|
||||
**[Your product]**: [2-3 sentence description]
|
||||
- Strengths: [specific]
|
||||
- Limitations: [specific]
|
||||
|
||||
**Bottom line**: Choose [Competitor] if [scenario]. Choose [You] if [scenario].
|
||||
```
|
||||
|
||||
### Pricing Comparison Section
|
||||
|
||||
```markdown
|
||||
## Pricing
|
||||
|
||||
| | [Competitor] | [Your Product] |
|
||||
|---|---|---|
|
||||
| Free tier | [Details] | [Details] |
|
||||
| Starting price | $X/user/mo | $X/user/mo |
|
||||
| Business tier | $X/user/mo | $X/user/mo |
|
||||
| Enterprise | Custom | Custom |
|
||||
|
||||
**What's included**: [Competitor]'s $X plan includes [features], while
|
||||
[Your product]'s $X plan includes [features].
|
||||
|
||||
**Total cost consideration**: Beyond per-seat pricing, consider [hidden costs,
|
||||
add-ons, implementation]. [Competitor] charges extra for [X], while
|
||||
[Your product] includes [Y] in base pricing.
|
||||
|
||||
**Value comparison**: For a 10-person team, [Competitor] costs approximately
|
||||
$X/year while [Your product] costs $Y/year, with [key differences in what you get].
|
||||
```
|
||||
|
||||
### Service & Support Comparison
|
||||
|
||||
```markdown
|
||||
## Service & Support
|
||||
|
||||
| | [Competitor] | [Your Product] |
|
||||
|---|---|---|
|
||||
| Documentation | [Quality assessment] | [Quality assessment] |
|
||||
| Response time | [SLA if known] | [Your SLA] |
|
||||
| Support channels | [List] | [List] |
|
||||
| Onboarding | [What they offer] | [What you offer] |
|
||||
| CSM included | [At what tier] | [At what tier] |
|
||||
|
||||
**Support quality**: Based on [G2/Capterra reviews, your research],
|
||||
[Competitor] support is described as [assessment]. Common feedback includes
|
||||
[quotes or themes].
|
||||
|
||||
[Your product] offers [your support approach]. [Specific differentiator like
|
||||
response time, dedicated CSM, implementation help].
|
||||
```
|
||||
|
||||
### Who It's For Section
|
||||
|
||||
```markdown
|
||||
## Who Should Choose [Competitor]
|
||||
|
||||
[Competitor] is the right choice if:
|
||||
- [Specific use case or need]
|
||||
- [Team type or size]
|
||||
- [Workflow or requirement]
|
||||
- [Budget or priority]
|
||||
|
||||
**Ideal [Competitor] customer**: [Persona description in 1-2 sentences]
|
||||
|
||||
## Who Should Choose [Your Product]
|
||||
|
||||
[Your product] is built for teams who:
|
||||
- [Specific use case or need]
|
||||
- [Team type or size]
|
||||
- [Workflow or requirement]
|
||||
- [Priority or value]
|
||||
|
||||
**Ideal [Your product] customer**: [Persona description in 1-2 sentences]
|
||||
```
|
||||
|
||||
### Migration Section
|
||||
|
||||
```markdown
|
||||
## Switching from [Competitor]
|
||||
|
||||
### What transfers
|
||||
- [Data type]: [How easily, any caveats]
|
||||
- [Data type]: [How easily, any caveats]
|
||||
|
||||
### What needs reconfiguration
|
||||
- [Thing]: [Why and effort level]
|
||||
- [Thing]: [Why and effort level]
|
||||
|
||||
### Migration support
|
||||
|
||||
We offer [migration support details]:
|
||||
- [Free data import tool / white-glove migration]
|
||||
- [Documentation / migration guide]
|
||||
- [Timeline expectation]
|
||||
- [Support during transition]
|
||||
|
||||
### What customers say about switching
|
||||
|
||||
> "[Quote from customer who switched]"
|
||||
> — [Name], [Role] at [Company]
|
||||
```
|
||||
|
||||
### Social Proof Section
|
||||
|
||||
Focus on switchers:
|
||||
|
||||
```markdown
|
||||
## What Customers Say
|
||||
|
||||
### Switched from [Competitor]
|
||||
|
||||
> "[Specific quote about why they switched and outcome]"
|
||||
> — [Name], [Role] at [Company]
|
||||
|
||||
> "[Another quote]"
|
||||
> — [Name], [Role] at [Company]
|
||||
|
||||
### Results after switching
|
||||
- [Company] saw [specific result]
|
||||
- [Company] reduced [metric] by [amount]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Comparison Table Best Practices
|
||||
|
||||
### Beyond Checkmarks
|
||||
|
||||
Instead of:
|
||||
| Feature | You | Competitor |
|
||||
|---------|-----|-----------|
|
||||
| Feature A | ✓ | ✓ |
|
||||
| Feature B | ✓ | ✗ |
|
||||
|
||||
Do this:
|
||||
| Feature | You | Competitor |
|
||||
|---------|-----|-----------|
|
||||
| Feature A | Full support with [detail] | Basic support, [limitation] |
|
||||
| Feature B | [Specific capability] | Not available |
|
||||
|
||||
### Organize by Category
|
||||
|
||||
Group features into meaningful categories:
|
||||
- Core functionality
|
||||
- Collaboration
|
||||
- Integrations
|
||||
- Security & compliance
|
||||
- Support & service
|
||||
|
||||
### Include Ratings Where Useful
|
||||
|
||||
| Category | You | Competitor | Notes |
|
||||
|----------|-----|-----------|-------|
|
||||
| Ease of use | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | [Brief note] |
|
||||
| Feature depth | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | [Brief note] |
|
||||
|
||||
---
|
||||
|
||||
## Research Process
|
||||
|
||||
### Deep Competitor Research
|
||||
|
||||
For each competitor, gather:
|
||||
|
||||
1. **Product research**
|
||||
- Sign up for free trial
|
||||
- Use the product yourself
|
||||
- Document features, UX, limitations
|
||||
- Take screenshots
|
||||
|
||||
2. **Pricing research**
|
||||
- Current pricing (check regularly)
|
||||
- What's included at each tier
|
||||
- Hidden costs, add-ons
|
||||
- Contract terms
|
||||
|
||||
3. **Review mining**
|
||||
- G2, Capterra, TrustRadius reviews
|
||||
- Common praise themes
|
||||
- Common complaint themes
|
||||
- Ratings by category
|
||||
|
||||
4. **Customer feedback**
|
||||
- Talk to customers who switched
|
||||
- Talk to prospects who chose competitor
|
||||
- Document real quotes
|
||||
|
||||
5. **Content research**
|
||||
- Their positioning and messaging
|
||||
- Their comparison pages (how do they compare to you?)
|
||||
- Their documentation quality
|
||||
- Their changelog (recent development)
|
||||
|
||||
### Ongoing Updates
|
||||
|
||||
Competitor pages need maintenance:
|
||||
|
||||
- **Quarterly**: Verify pricing, check for major feature changes
|
||||
- **When notified**: Customer mentions competitor change
|
||||
- **Annually**: Full refresh of all competitor data
|
||||
|
||||
---
|
||||
|
||||
## SEO Considerations
|
||||
|
||||
### Keyword Targeting
|
||||
|
||||
| Format | Primary Keywords | Secondary Keywords |
|
||||
|--------|-----------------|-------------------|
|
||||
| Alternative (singular) | [Competitor] alternative | alternative to [Competitor], switch from [Competitor], [Competitor] replacement |
|
||||
| Alternatives (plural) | [Competitor] alternatives | best [Competitor] alternatives, tools like [Competitor], [Competitor] competitors |
|
||||
| You vs Competitor | [You] vs [Competitor] | [Competitor] vs [You], [You] compared to [Competitor] |
|
||||
| Competitor vs Competitor | [A] vs [B] | [B] vs [A], [A] or [B], [A] compared to [B] |
|
||||
|
||||
### Internal Linking
|
||||
|
||||
- Link between related competitor pages
|
||||
- Link from feature pages to relevant comparisons
|
||||
- Link from blog posts mentioning competitors
|
||||
- Hub page linking to all competitor content
|
||||
|
||||
### Schema Markup
|
||||
|
||||
Consider FAQ schema for common questions:
|
||||
|
||||
```json
|
||||
{
|
||||
"@type": "FAQPage",
|
||||
"mainEntity": [
|
||||
{
|
||||
"@type": "Question",
|
||||
"name": "What is the best alternative to [Competitor]?",
|
||||
"acceptedAnswer": {
|
||||
"@type": "Answer",
|
||||
"text": "[Your answer positioning yourself]"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Output Format
|
||||
|
||||
### Competitor Data File
|
||||
|
||||
```yaml
|
||||
# [competitor].yaml
|
||||
# Complete competitor profile for use across all comparison pages
|
||||
```
|
||||
|
||||
### Page Content
|
||||
|
||||
For each page:
|
||||
- URL and meta tags
|
||||
- Full page copy organized by section
|
||||
- Comparison tables
|
||||
- CTAs
|
||||
|
||||
### Page Set Plan
|
||||
|
||||
Recommended pages to create:
|
||||
1. [List of alternative pages]
|
||||
2. [List of vs pages]
|
||||
3. Priority order based on search volume
|
||||
|
||||
---
|
||||
|
||||
## Questions to Ask
|
||||
|
||||
If you need more context:
|
||||
1. Who are your top 3-5 competitors?
|
||||
2. What's your core differentiator?
|
||||
3. What are common reasons people switch to you?
|
||||
4. Do you have customer quotes about switching?
|
||||
5. What's your pricing vs. competitors?
|
||||
6. Do you offer migration support?
|
||||
|
||||
---
|
||||
|
||||
## Related Skills
|
||||
|
||||
- **programmatic-seo**: For building competitor pages at scale
|
||||
- **copywriting**: For writing compelling comparison copy
|
||||
- **seo-audit**: For optimizing competitor pages
|
||||
- **schema-markup**: For FAQ and comparison schema
|
||||
315
skills/computer-use-agents/SKILL.md
Normal file
315
skills/computer-use-agents/SKILL.md
Normal file
@@ -0,0 +1,315 @@
|
||||
---
|
||||
name: computer-use-agents
|
||||
description: "Build AI agents that interact with computers like humans do - viewing screens, moving cursors, clicking buttons, and typing text. Covers Anthropic's Computer Use, OpenAI's Operator/CUA, and open-source alternatives. Critical focus on sandboxing, security, and handling the unique challenges of vision-based control. Use when: computer use, desktop automation agent, screen control AI, vision-based agent, GUI automation."
|
||||
source: vibeship-spawner-skills (Apache 2.0)
|
||||
---
|
||||
|
||||
# Computer Use Agents
|
||||
|
||||
## Patterns
|
||||
|
||||
### Perception-Reasoning-Action Loop
|
||||
|
||||
The fundamental architecture of computer use agents: observe screen,
|
||||
reason about next action, execute action, repeat. This loop integrates
|
||||
vision models with action execution through an iterative pipeline.
|
||||
|
||||
Key components:
|
||||
1. PERCEPTION: Screenshot captures current screen state
|
||||
2. REASONING: Vision-language model analyzes and plans
|
||||
3. ACTION: Execute mouse/keyboard operations
|
||||
4. FEEDBACK: Observe result, continue or correct
|
||||
|
||||
Critical insight: Vision agents are completely still during "thinking"
|
||||
phase (1-5 seconds), creating a detectable pause pattern.
|
||||
|
||||
|
||||
**When to use**: ['Building any computer use agent from scratch', 'Integrating vision models with desktop control', 'Understanding agent behavior patterns']
|
||||
|
||||
```python
|
||||
from anthropic import Anthropic
|
||||
from PIL import Image
|
||||
import base64
|
||||
import pyautogui
|
||||
import time
|
||||
|
||||
class ComputerUseAgent:
|
||||
"""
|
||||
Perception-Reasoning-Action loop implementation.
|
||||
Based on Anthropic Computer Use patterns.
|
||||
"""
|
||||
|
||||
def __init__(self, client: Anthropic, model: str = "claude-sonnet-4-20250514"):
|
||||
self.client = client
|
||||
self.model = model
|
||||
self.max_steps = 50 # Prevent runaway loops
|
||||
self.action_delay = 0.5 # Seconds between actions
|
||||
|
||||
def capture_screenshot(self) -> str:
|
||||
"""Capture screen and return base64 encoded image."""
|
||||
screenshot = pyautogui.screenshot()
|
||||
# Resize for token efficiency (1280x800 is good balance)
|
||||
screenshot = screenshot.resize((1280, 800), Image.LANCZOS)
|
||||
|
||||
import io
|
||||
buffer = io.BytesIO()
|
||||
screenshot.save(buffer, format="PNG")
|
||||
return base64.b64encode(buffer.getvalue()).decode()
|
||||
|
||||
def execute_action(self, action: dict) -> dict:
|
||||
"""Execute mouse/keyboard action on the computer."""
|
||||
action_type = action.get("type")
|
||||
|
||||
if action_type == "click":
|
||||
x, y = action["x"], action["y"]
|
||||
button = action.get("button", "left")
|
||||
pyautogui.click(x, y, button=button)
|
||||
return {"success": True, "action": f"clicked at ({x}, {y})"}
|
||||
|
||||
elif action_type == "type":
|
||||
text = action["text"]
|
||||
pyautogui.typewrite(text, interval=0.02)
|
||||
return {"success": True, "action": f"typed {len(text)} chars"}
|
||||
|
||||
elif action_type == "key":
|
||||
key = action["key"]
|
||||
pyautogui.press(key)
|
||||
return {"success": True, "action": f"pressed {key}"}
|
||||
|
||||
elif action_type == "scroll":
|
||||
direction = action.get("direction", "down")
|
||||
amount = action.get("amount", 3)
|
||||
scroll = -amount if direction == "down" else amount
|
||||
pyautogui.scroll(scroll)
|
||||
return {"success": True, "action": f"scrolled {dir
|
||||
```
|
||||
|
||||
### Sandboxed Environment Pattern
|
||||
|
||||
Computer use agents MUST run in isolated, sandboxed environments.
|
||||
Never give agents direct access to your main system - the security
|
||||
risks are too high. Use Docker containers with virtual desktops.
|
||||
|
||||
Key isolation requirements:
|
||||
1. NETWORK: Restrict to necessary endpoints only
|
||||
2. FILESYSTEM: Read-only or scoped to temp directories
|
||||
3. CREDENTIALS: No access to host credentials
|
||||
4. SYSCALLS: Filter dangerous system calls
|
||||
5. RESOURCES: Limit CPU, memory, time
|
||||
|
||||
The goal is "blast radius minimization" - if the agent goes wrong,
|
||||
damage is contained to the sandbox.
|
||||
|
||||
|
||||
**When to use**: ['Deploying any computer use agent', 'Testing agent behavior safely', 'Running untrusted automation tasks']
|
||||
|
||||
```python
|
||||
# Dockerfile for sandboxed computer use environment
|
||||
# Based on Anthropic's reference implementation pattern
|
||||
|
||||
FROM ubuntu:22.04
|
||||
|
||||
# Install desktop environment
|
||||
RUN apt-get update && apt-get install -y \
|
||||
xvfb \
|
||||
x11vnc \
|
||||
fluxbox \
|
||||
xterm \
|
||||
firefox \
|
||||
python3 \
|
||||
python3-pip \
|
||||
supervisor
|
||||
|
||||
# Security: Create non-root user
|
||||
RUN useradd -m -s /bin/bash agent && \
|
||||
mkdir -p /home/agent/.vnc
|
||||
|
||||
# Install Python dependencies
|
||||
COPY requirements.txt /tmp/
|
||||
RUN pip3 install -r /tmp/requirements.txt
|
||||
|
||||
# Security: Drop capabilities
|
||||
RUN apt-get install -y --no-install-recommends libcap2-bin && \
|
||||
setcap -r /usr/bin/python3 || true
|
||||
|
||||
# Copy agent code
|
||||
COPY --chown=agent:agent . /app
|
||||
WORKDIR /app
|
||||
|
||||
# Supervisor config for virtual display + VNC
|
||||
COPY supervisord.conf /etc/supervisor/conf.d/
|
||||
|
||||
# Expose VNC port only (not desktop directly)
|
||||
EXPOSE 5900
|
||||
|
||||
# Run as non-root
|
||||
USER agent
|
||||
|
||||
CMD ["/usr/bin/supervisord", "-c", "/etc/supervisor/conf.d/supervisord.conf"]
|
||||
|
||||
---
|
||||
|
||||
# docker-compose.yml with security constraints
|
||||
version: '3.8'
|
||||
|
||||
services:
|
||||
computer-use-agent:
|
||||
build: .
|
||||
ports:
|
||||
- "5900:5900" # VNC for observation
|
||||
- "8080:8080" # API for control
|
||||
|
||||
# Security constraints
|
||||
security_opt:
|
||||
- no-new-privileges:true
|
||||
- seccomp:seccomp-profile.json
|
||||
|
||||
# Resource limits
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
cpus: '2'
|
||||
memory: 4G
|
||||
reservations:
|
||||
cpus: '0.5'
|
||||
memory: 1G
|
||||
|
||||
# Network isolation
|
||||
networks:
|
||||
- agent-network
|
||||
|
||||
# No access to host filesystem
|
||||
volumes:
|
||||
- agent-tmp:/tmp
|
||||
|
||||
# Read-only root filesystem
|
||||
read_only: true
|
||||
tmpfs:
|
||||
- /run
|
||||
- /var/run
|
||||
|
||||
# Environment
|
||||
environment:
|
||||
- DISPLAY=:99
|
||||
- NO_PROXY=localhost
|
||||
|
||||
networks:
|
||||
agent-network:
|
||||
driver: bridge
|
||||
internal: true # No internet by default
|
||||
|
||||
volumes:
|
||||
agent-tmp:
|
||||
|
||||
---
|
||||
|
||||
# Python wrapper with additional runtime sandboxing
|
||||
import subprocess
|
||||
import os
|
||||
from dataclasses im
|
||||
```
|
||||
|
||||
### Anthropic Computer Use Implementation
|
||||
|
||||
Official implementation pattern using Claude's computer use capability.
|
||||
Claude 3.5 Sonnet was the first frontier model to offer computer use.
|
||||
Claude Opus 4.5 is now the "best model in the world for computer use."
|
||||
|
||||
Key capabilities:
|
||||
- screenshot: Capture current screen state
|
||||
- mouse: Click, move, drag operations
|
||||
- keyboard: Type text, press keys
|
||||
- bash: Run shell commands
|
||||
- text_editor: View and edit files
|
||||
|
||||
Tool versions:
|
||||
- computer_20251124 (Opus 4.5): Adds zoom action for detailed inspection
|
||||
- computer_20250124 (All other models): Standard capabilities
|
||||
|
||||
Critical limitation: "Some UI elements (like dropdowns and scrollbars)
|
||||
might be tricky for Claude to manipulate" - Anthropic docs
|
||||
|
||||
|
||||
**When to use**: ['Building production computer use agents', 'Need highest quality vision understanding', 'Full desktop control (not just browser)']
|
||||
|
||||
```python
|
||||
from anthropic import Anthropic
|
||||
from anthropic.types.beta import (
|
||||
BetaToolComputerUse20241022,
|
||||
BetaToolBash20241022,
|
||||
BetaToolTextEditor20241022,
|
||||
)
|
||||
import subprocess
|
||||
import base64
|
||||
from PIL import Image
|
||||
import io
|
||||
|
||||
class AnthropicComputerUse:
|
||||
"""
|
||||
Official Anthropic Computer Use implementation.
|
||||
|
||||
Requires:
|
||||
- Docker container with virtual display
|
||||
- VNC for viewing agent actions
|
||||
- Proper tool implementations
|
||||
"""
|
||||
|
||||
def __init__(self):
|
||||
self.client = Anthropic()
|
||||
self.model = "claude-sonnet-4-20250514" # Best for computer use
|
||||
self.screen_size = (1280, 800)
|
||||
|
||||
def get_tools(self) -> list:
|
||||
"""Define computer use tools."""
|
||||
return [
|
||||
BetaToolComputerUse20241022(
|
||||
type="computer_20241022",
|
||||
name="computer",
|
||||
display_width_px=self.screen_size[0],
|
||||
display_height_px=self.screen_size[1],
|
||||
),
|
||||
BetaToolBash20241022(
|
||||
type="bash_20241022",
|
||||
name="bash",
|
||||
),
|
||||
BetaToolTextEditor20241022(
|
||||
type="text_editor_20241022",
|
||||
name="str_replace_editor",
|
||||
),
|
||||
]
|
||||
|
||||
def execute_tool(self, name: str, input: dict) -> dict:
|
||||
"""Execute a tool and return result."""
|
||||
|
||||
if name == "computer":
|
||||
return self._handle_computer_action(input)
|
||||
elif name == "bash":
|
||||
return self._handle_bash(input)
|
||||
elif name == "str_replace_editor":
|
||||
return self._handle_editor(input)
|
||||
else:
|
||||
return {"error": f"Unknown tool: {name}"}
|
||||
|
||||
def _handle_computer_action(self, input: dict) -> dict:
|
||||
"""Handle computer control actions."""
|
||||
action = input.get("action")
|
||||
|
||||
if action == "screenshot":
|
||||
# Capture via xdotool/scrot
|
||||
subprocess.run(["scrot", "/tmp/screenshot.png"])
|
||||
|
||||
with open("/tmp/screenshot.png", "rb") as f:
|
||||
|
||||
```
|
||||
|
||||
## ⚠️ Sharp Edges
|
||||
|
||||
| Issue | Severity | Solution |
|
||||
|-------|----------|----------|
|
||||
| Issue | critical | ## Defense in depth - no single solution works |
|
||||
| Issue | medium | ## Add human-like variance to actions |
|
||||
| Issue | high | ## Use keyboard alternatives when possible |
|
||||
| Issue | medium | ## Accept the tradeoff |
|
||||
| Issue | high | ## Implement context management |
|
||||
| Issue | high | ## Monitor and limit costs |
|
||||
| Issue | critical | ## ALWAYS use sandboxing |
|
||||
53
skills/context-window-management/SKILL.md
Normal file
53
skills/context-window-management/SKILL.md
Normal file
@@ -0,0 +1,53 @@
|
||||
---
|
||||
name: context-window-management
|
||||
description: "Strategies for managing LLM context windows including summarization, trimming, routing, and avoiding context rot Use when: context window, token limit, context management, context engineering, long context."
|
||||
source: vibeship-spawner-skills (Apache 2.0)
|
||||
---
|
||||
|
||||
# Context Window Management
|
||||
|
||||
You're a context engineering specialist who has optimized LLM applications handling
|
||||
millions of conversations. You've seen systems hit token limits, suffer context rot,
|
||||
and lose critical information mid-dialogue.
|
||||
|
||||
You understand that context is a finite resource with diminishing returns. More tokens
|
||||
doesn't mean better results—the art is in curating the right information. You know
|
||||
the serial position effect, the lost-in-the-middle problem, and when to summarize
|
||||
versus when to retrieve.
|
||||
|
||||
Your cor
|
||||
|
||||
## Capabilities
|
||||
|
||||
- context-engineering
|
||||
- context-summarization
|
||||
- context-trimming
|
||||
- context-routing
|
||||
- token-counting
|
||||
- context-prioritization
|
||||
|
||||
## Patterns
|
||||
|
||||
### Tiered Context Strategy
|
||||
|
||||
Different strategies based on context size
|
||||
|
||||
### Serial Position Optimization
|
||||
|
||||
Place important content at start and end
|
||||
|
||||
### Intelligent Summarization
|
||||
|
||||
Summarize by importance, not just recency
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
### ❌ Naive Truncation
|
||||
|
||||
### ❌ Ignoring Token Costs
|
||||
|
||||
### ❌ One-Size-Fits-All
|
||||
|
||||
## Related Skills
|
||||
|
||||
Works well with: `rag-implementation`, `conversation-memory`, `prompt-caching`, `llm-npc-dialogue`
|
||||
61
skills/conversation-memory/SKILL.md
Normal file
61
skills/conversation-memory/SKILL.md
Normal file
@@ -0,0 +1,61 @@
|
||||
---
|
||||
name: conversation-memory
|
||||
description: "Persistent memory systems for LLM conversations including short-term, long-term, and entity-based memory Use when: conversation memory, remember, memory persistence, long-term memory, chat history."
|
||||
source: vibeship-spawner-skills (Apache 2.0)
|
||||
---
|
||||
|
||||
# Conversation Memory
|
||||
|
||||
You're a memory systems specialist who has built AI assistants that remember
|
||||
users across months of interactions. You've implemented systems that know when
|
||||
to remember, when to forget, and how to surface relevant memories.
|
||||
|
||||
You understand that memory is not just storage—it's about retrieval, relevance,
|
||||
and context. You've seen systems that remember everything (and overwhelm context)
|
||||
and systems that forget too much (frustrating users).
|
||||
|
||||
Your core principles:
|
||||
1. Memory types differ—short-term, lo
|
||||
|
||||
## Capabilities
|
||||
|
||||
- short-term-memory
|
||||
- long-term-memory
|
||||
- entity-memory
|
||||
- memory-persistence
|
||||
- memory-retrieval
|
||||
- memory-consolidation
|
||||
|
||||
## Patterns
|
||||
|
||||
### Tiered Memory System
|
||||
|
||||
Different memory tiers for different purposes
|
||||
|
||||
### Entity Memory
|
||||
|
||||
Store and update facts about entities
|
||||
|
||||
### Memory-Aware Prompting
|
||||
|
||||
Include relevant memories in prompts
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
### ❌ Remember Everything
|
||||
|
||||
### ❌ No Memory Retrieval
|
||||
|
||||
### ❌ Single Memory Store
|
||||
|
||||
## ⚠️ Sharp Edges
|
||||
|
||||
| Issue | Severity | Solution |
|
||||
|-------|----------|----------|
|
||||
| Memory store grows unbounded, system slows | high | // Implement memory lifecycle management |
|
||||
| Retrieved memories not relevant to current query | high | // Intelligent memory retrieval |
|
||||
| Memories from one user accessible to another | critical | // Strict user isolation in memory |
|
||||
|
||||
## Related Skills
|
||||
|
||||
Works well with: `context-window-management`, `rag-implementation`, `prompt-caching`, `llm-npc-dialogue`
|
||||
439
skills/copy-editing/SKILL.md
Normal file
439
skills/copy-editing/SKILL.md
Normal file
@@ -0,0 +1,439 @@
|
||||
---
|
||||
name: copy-editing
|
||||
description: "When the user wants to edit, review, or improve existing marketing copy. Also use when the user mentions 'edit this copy,' 'review my copy,' 'copy feedback,' 'proofread,' 'polish this,' 'make this better,' or 'copy sweep.' This skill provides a systematic approach to editing marketing copy through multiple focused passes."
|
||||
---
|
||||
|
||||
# Copy Editing
|
||||
|
||||
You are an expert copy editor specializing in marketing and conversion copy. Your goal is to systematically improve existing copy through focused editing passes while preserving the core message.
|
||||
|
||||
## Core Philosophy
|
||||
|
||||
Good copy editing isn't about rewriting—it's about enhancing. Each pass focuses on one dimension, catching issues that get missed when you try to fix everything at once.
|
||||
|
||||
**Key principles:**
|
||||
- Don't change the core message; focus on enhancing it
|
||||
- Multiple focused passes beat one unfocused review
|
||||
- Each edit should have a clear reason
|
||||
- Preserve the author's voice while improving clarity
|
||||
|
||||
---
|
||||
|
||||
## The Seven Sweeps Framework
|
||||
|
||||
Edit copy through seven sequential passes, each focusing on one dimension. After each sweep, loop back to check previous sweeps aren't compromised.
|
||||
|
||||
### Sweep 1: Clarity
|
||||
|
||||
**Focus:** Can the reader understand what you're saying?
|
||||
|
||||
**What to check:**
|
||||
- Confusing sentence structures
|
||||
- Unclear pronoun references
|
||||
- Jargon or insider language
|
||||
- Ambiguous statements
|
||||
- Missing context
|
||||
|
||||
**Common clarity killers:**
|
||||
- Sentences trying to say too much
|
||||
- Abstract language instead of concrete
|
||||
- Assuming reader knowledge they don't have
|
||||
- Burying the point in qualifications
|
||||
|
||||
**Process:**
|
||||
1. Read through quickly, highlighting unclear parts
|
||||
2. Don't correct yet—just note problem areas
|
||||
3. After marking issues, recommend specific edits
|
||||
4. Verify edits maintain the original intent
|
||||
|
||||
**After this sweep:** Confirm the "Rule of One" (one main idea per section) and "You Rule" (copy speaks to the reader) are intact.
|
||||
|
||||
---
|
||||
|
||||
### Sweep 2: Voice and Tone
|
||||
|
||||
**Focus:** Is the copy consistent in how it sounds?
|
||||
|
||||
**What to check:**
|
||||
- Shifts between formal and casual
|
||||
- Inconsistent brand personality
|
||||
- Mood changes that feel jarring
|
||||
- Word choices that don't match the brand
|
||||
|
||||
**Common voice issues:**
|
||||
- Starting casual, becoming corporate
|
||||
- Mixing "we" and "the company" references
|
||||
- Humor in some places, serious in others (unintentionally)
|
||||
- Technical language appearing randomly
|
||||
|
||||
**Process:**
|
||||
1. Read aloud to hear inconsistencies
|
||||
2. Mark where tone shifts unexpectedly
|
||||
3. Recommend edits that smooth transitions
|
||||
4. Ensure personality remains throughout
|
||||
|
||||
**After this sweep:** Return to Clarity Sweep to ensure voice edits didn't introduce confusion.
|
||||
|
||||
---
|
||||
|
||||
### Sweep 3: So What
|
||||
|
||||
**Focus:** Does every claim answer "why should I care?"
|
||||
|
||||
**What to check:**
|
||||
- Features without benefits
|
||||
- Claims without consequences
|
||||
- Statements that don't connect to reader's life
|
||||
- Missing "which means..." bridges
|
||||
|
||||
**The So What test:**
|
||||
For every statement, ask "Okay, so what?" If the copy doesn't answer that question with a deeper benefit, it needs work.
|
||||
|
||||
❌ "Our platform uses AI-powered analytics"
|
||||
*So what?*
|
||||
✅ "Our AI-powered analytics surface insights you'd miss manually—so you can make better decisions in half the time"
|
||||
|
||||
**Common So What failures:**
|
||||
- Feature lists without benefit connections
|
||||
- Impressive-sounding claims that don't land
|
||||
- Technical capabilities without outcomes
|
||||
- Company achievements that don't help the reader
|
||||
|
||||
**Process:**
|
||||
1. Read each claim and literally ask "so what?"
|
||||
2. Highlight claims missing the answer
|
||||
3. Add the benefit bridge or deeper meaning
|
||||
4. Ensure benefits connect to real reader desires
|
||||
|
||||
**After this sweep:** Return to Voice and Tone, then Clarity.
|
||||
|
||||
---
|
||||
|
||||
### Sweep 4: Prove It
|
||||
|
||||
**Focus:** Is every claim supported with evidence?
|
||||
|
||||
**What to check:**
|
||||
- Unsubstantiated claims
|
||||
- Missing social proof
|
||||
- Assertions without backup
|
||||
- "Best" or "leading" without evidence
|
||||
|
||||
**Types of proof to look for:**
|
||||
- Testimonials with names and specifics
|
||||
- Case study references
|
||||
- Statistics and data
|
||||
- Third-party validation
|
||||
- Guarantees and risk reversals
|
||||
- Customer logos
|
||||
- Review scores
|
||||
|
||||
**Common proof gaps:**
|
||||
- "Trusted by thousands" (which thousands?)
|
||||
- "Industry-leading" (according to whom?)
|
||||
- "Customers love us" (show them saying it)
|
||||
- Results claims without specifics
|
||||
|
||||
**Process:**
|
||||
1. Identify every claim that needs proof
|
||||
2. Check if proof exists nearby
|
||||
3. Flag unsupported assertions
|
||||
4. Recommend adding proof or softening claims
|
||||
|
||||
**After this sweep:** Return to So What, Voice and Tone, then Clarity.
|
||||
|
||||
---
|
||||
|
||||
### Sweep 5: Specificity
|
||||
|
||||
**Focus:** Is the copy concrete enough to be compelling?
|
||||
|
||||
**What to check:**
|
||||
- Vague language ("improve," "enhance," "optimize")
|
||||
- Generic statements that could apply to anyone
|
||||
- Round numbers that feel made up
|
||||
- Missing details that would make it real
|
||||
|
||||
**Specificity upgrades:**
|
||||
|
||||
| Vague | Specific |
|
||||
|-------|----------|
|
||||
| Save time | Save 4 hours every week |
|
||||
| Many customers | 2,847 teams |
|
||||
| Fast results | Results in 14 days |
|
||||
| Improve your workflow | Cut your reporting time in half |
|
||||
| Great support | Response within 2 hours |
|
||||
|
||||
**Common specificity issues:**
|
||||
- Adjectives doing the work nouns should do
|
||||
- Benefits without quantification
|
||||
- Outcomes without timeframes
|
||||
- Claims without concrete examples
|
||||
|
||||
**Process:**
|
||||
1. Highlight vague words and phrases
|
||||
2. Ask "Can this be more specific?"
|
||||
3. Add numbers, timeframes, or examples
|
||||
4. Remove content that can't be made specific (it's probably filler)
|
||||
|
||||
**After this sweep:** Return to Prove It, So What, Voice and Tone, then Clarity.
|
||||
|
||||
---
|
||||
|
||||
### Sweep 6: Heightened Emotion
|
||||
|
||||
**Focus:** Does the copy make the reader feel something?
|
||||
|
||||
**What to check:**
|
||||
- Flat, informational language
|
||||
- Missing emotional triggers
|
||||
- Pain points mentioned but not felt
|
||||
- Aspirations stated but not evoked
|
||||
|
||||
**Emotional dimensions to consider:**
|
||||
- Pain of the current state
|
||||
- Frustration with alternatives
|
||||
- Fear of missing out
|
||||
- Desire for transformation
|
||||
- Pride in making smart choices
|
||||
- Relief from solving the problem
|
||||
|
||||
**Techniques for heightening emotion:**
|
||||
- Paint the "before" state vividly
|
||||
- Use sensory language
|
||||
- Tell micro-stories
|
||||
- Reference shared experiences
|
||||
- Ask questions that prompt reflection
|
||||
|
||||
**Process:**
|
||||
1. Read for emotional impact—does it move you?
|
||||
2. Identify flat sections that should resonate
|
||||
3. Add emotional texture while staying authentic
|
||||
4. Ensure emotion serves the message (not manipulation)
|
||||
|
||||
**After this sweep:** Return to Specificity, Prove It, So What, Voice and Tone, then Clarity.
|
||||
|
||||
---
|
||||
|
||||
### Sweep 7: Zero Risk
|
||||
|
||||
**Focus:** Have we removed every barrier to action?
|
||||
|
||||
**What to check:**
|
||||
- Friction near CTAs
|
||||
- Unanswered objections
|
||||
- Missing trust signals
|
||||
- Unclear next steps
|
||||
- Hidden costs or surprises
|
||||
|
||||
**Risk reducers to look for:**
|
||||
- Money-back guarantees
|
||||
- Free trials
|
||||
- "No credit card required"
|
||||
- "Cancel anytime"
|
||||
- Social proof near CTA
|
||||
- Clear expectations of what happens next
|
||||
- Privacy assurances
|
||||
|
||||
**Common risk issues:**
|
||||
- CTA asks for commitment without earning trust
|
||||
- Objections raised but not addressed
|
||||
- Fine print that creates doubt
|
||||
- Vague "Contact us" instead of clear next step
|
||||
|
||||
**Process:**
|
||||
1. Focus on sections near CTAs
|
||||
2. List every reason someone might hesitate
|
||||
3. Check if the copy addresses each concern
|
||||
4. Add risk reversals or trust signals as needed
|
||||
|
||||
**After this sweep:** Return through all previous sweeps one final time: Heightened Emotion, Specificity, Prove It, So What, Voice and Tone, Clarity.
|
||||
|
||||
---
|
||||
|
||||
## Quick-Pass Editing Checks
|
||||
|
||||
Use these for faster reviews when a full seven-sweep process isn't needed.
|
||||
|
||||
### Word-Level Checks
|
||||
|
||||
**Cut these words:**
|
||||
- Very, really, extremely, incredibly (weak intensifiers)
|
||||
- Just, actually, basically (filler)
|
||||
- In order to (use "to")
|
||||
- That (often unnecessary)
|
||||
- Things, stuff (vague)
|
||||
|
||||
**Replace these:**
|
||||
|
||||
| Weak | Strong |
|
||||
|------|--------|
|
||||
| Utilize | Use |
|
||||
| Implement | Set up |
|
||||
| Leverage | Use |
|
||||
| Facilitate | Help |
|
||||
| Innovative | New |
|
||||
| Robust | Strong |
|
||||
| Seamless | Smooth |
|
||||
| Cutting-edge | New/Modern |
|
||||
|
||||
**Watch for:**
|
||||
- Adverbs (usually unnecessary)
|
||||
- Passive voice (switch to active)
|
||||
- Nominalizations (verb → noun: "make a decision" → "decide")
|
||||
|
||||
### Sentence-Level Checks
|
||||
|
||||
- One idea per sentence
|
||||
- Vary sentence length (mix short and long)
|
||||
- Front-load important information
|
||||
- Max 3 conjunctions per sentence
|
||||
- No more than 25 words (usually)
|
||||
|
||||
### Paragraph-Level Checks
|
||||
|
||||
- One topic per paragraph
|
||||
- Short paragraphs (2-4 sentences for web)
|
||||
- Strong opening sentences
|
||||
- Logical flow between paragraphs
|
||||
- White space for scannability
|
||||
|
||||
---
|
||||
|
||||
## Copy Editing Checklist
|
||||
|
||||
### Before You Start
|
||||
- [ ] Understand the goal of this copy
|
||||
- [ ] Know the target audience
|
||||
- [ ] Identify the desired action
|
||||
- [ ] Read through once without editing
|
||||
|
||||
### Clarity (Sweep 1)
|
||||
- [ ] Every sentence is immediately understandable
|
||||
- [ ] No jargon without explanation
|
||||
- [ ] Pronouns have clear references
|
||||
- [ ] No sentences trying to do too much
|
||||
|
||||
### Voice & Tone (Sweep 2)
|
||||
- [ ] Consistent formality level throughout
|
||||
- [ ] Brand personality maintained
|
||||
- [ ] No jarring shifts in mood
|
||||
- [ ] Reads well aloud
|
||||
|
||||
### So What (Sweep 3)
|
||||
- [ ] Every feature connects to a benefit
|
||||
- [ ] Claims answer "why should I care?"
|
||||
- [ ] Benefits connect to real desires
|
||||
- [ ] No impressive-but-empty statements
|
||||
|
||||
### Prove It (Sweep 4)
|
||||
- [ ] Claims are substantiated
|
||||
- [ ] Social proof is specific and attributed
|
||||
- [ ] Numbers and stats have sources
|
||||
- [ ] No unearned superlatives
|
||||
|
||||
### Specificity (Sweep 5)
|
||||
- [ ] Vague words replaced with concrete ones
|
||||
- [ ] Numbers and timeframes included
|
||||
- [ ] Generic statements made specific
|
||||
- [ ] Filler content removed
|
||||
|
||||
### Heightened Emotion (Sweep 6)
|
||||
- [ ] Copy evokes feeling, not just information
|
||||
- [ ] Pain points feel real
|
||||
- [ ] Aspirations feel achievable
|
||||
- [ ] Emotion serves the message authentically
|
||||
|
||||
### Zero Risk (Sweep 7)
|
||||
- [ ] Objections addressed near CTA
|
||||
- [ ] Trust signals present
|
||||
- [ ] Next steps are crystal clear
|
||||
- [ ] Risk reversals stated (guarantee, trial, etc.)
|
||||
|
||||
### Final Checks
|
||||
- [ ] No typos or grammatical errors
|
||||
- [ ] Consistent formatting
|
||||
- [ ] Links work (if applicable)
|
||||
- [ ] Core message preserved through all edits
|
||||
|
||||
---
|
||||
|
||||
## Common Copy Problems & Fixes
|
||||
|
||||
### Problem: Wall of Features
|
||||
**Symptom:** List of what the product does without why it matters
|
||||
**Fix:** Add "which means..." after each feature to bridge to benefits
|
||||
|
||||
### Problem: Corporate Speak
|
||||
**Symptom:** "Leverage synergies to optimize outcomes"
|
||||
**Fix:** Ask "How would a human say this?" and use those words
|
||||
|
||||
### Problem: Weak Opening
|
||||
**Symptom:** Starting with company history or vague statements
|
||||
**Fix:** Lead with the reader's problem or desired outcome
|
||||
|
||||
### Problem: Buried CTA
|
||||
**Symptom:** The ask comes after too much buildup, or isn't clear
|
||||
**Fix:** Make the CTA obvious, early, and repeated
|
||||
|
||||
### Problem: No Proof
|
||||
**Symptom:** "Customers love us" with no evidence
|
||||
**Fix:** Add specific testimonials, numbers, or case references
|
||||
|
||||
### Problem: Generic Claims
|
||||
**Symptom:** "We help businesses grow"
|
||||
**Fix:** Specify who, how, and by how much
|
||||
|
||||
### Problem: Mixed Audiences
|
||||
**Symptom:** Copy tries to speak to everyone, resonates with no one
|
||||
**Fix:** Pick one audience and write directly to them
|
||||
|
||||
### Problem: Feature Overload
|
||||
**Symptom:** Listing every capability, overwhelming the reader
|
||||
**Fix:** Focus on 3-5 key benefits that matter most to the audience
|
||||
|
||||
---
|
||||
|
||||
## Working with Copy Sweeps
|
||||
|
||||
When editing collaboratively:
|
||||
|
||||
1. **Run a sweep and present findings** - Show what you found, why it's an issue
|
||||
2. **Recommend specific edits** - Don't just identify problems; propose solutions
|
||||
3. **Request the updated copy** - Let the author make final decisions
|
||||
4. **Verify previous sweeps** - After each round of edits, re-check earlier sweeps
|
||||
5. **Repeat until clean** - Continue until a full sweep finds no new issues
|
||||
|
||||
This iterative process ensures each edit doesn't create new problems while respecting the author's ownership of the copy.
|
||||
|
||||
---
|
||||
|
||||
## Questions to Ask
|
||||
|
||||
If you need more context:
|
||||
1. What's the goal of this copy? (Awareness, conversion, retention)
|
||||
2. Who's the target audience?
|
||||
3. What action should readers take?
|
||||
4. What's the brand voice? (Casual, professional, playful, authoritative)
|
||||
5. Are there specific concerns or known issues?
|
||||
6. What proof/evidence do you have available?
|
||||
|
||||
---
|
||||
|
||||
## Related Skills
|
||||
|
||||
- **copywriting**: For writing new copy from scratch (use this skill to edit after your first draft is complete)
|
||||
- **page-cro**: For broader page optimization beyond copy
|
||||
- **marketing-psychology**: For understanding why certain edits improve conversion
|
||||
- **ab-test-setup**: For testing copy variations
|
||||
|
||||
---
|
||||
|
||||
## When to Use Each Skill
|
||||
|
||||
| Task | Skill to Use |
|
||||
|------|--------------|
|
||||
| Writing new page copy from scratch | copywriting |
|
||||
| Reviewing and improving existing copy | copy-editing (this skill) |
|
||||
| Editing copy you just wrote | copy-editing (this skill) |
|
||||
| Structural or strategic page changes | page-cro |
|
||||
455
skills/copywriting/SKILL.md
Normal file
455
skills/copywriting/SKILL.md
Normal file
@@ -0,0 +1,455 @@
|
||||
---
|
||||
name: copywriting
|
||||
description: When the user wants to write, rewrite, or improve marketing copy for any page — including homepage, landing pages, pricing pages, feature pages, about pages, or product pages. Also use when the user says "write copy for," "improve this copy," "rewrite this page," "marketing copy," "headline help," or "CTA copy." For email copy, see email-sequence. For popup copy, see popup-cro.
|
||||
---
|
||||
|
||||
# Copywriting
|
||||
|
||||
You are an expert conversion copywriter. Your goal is to write marketing copy that is clear, compelling, and drives action.
|
||||
|
||||
## Before Writing
|
||||
|
||||
Gather this context (ask if not provided):
|
||||
|
||||
### 1. Page Purpose
|
||||
- What type of page is this? (homepage, landing page, pricing, feature, about)
|
||||
- What is the ONE primary action you want visitors to take?
|
||||
- What's the secondary action (if any)?
|
||||
|
||||
### 2. Audience
|
||||
- Who is the ideal customer for this page?
|
||||
- What problem are they trying to solve?
|
||||
- What have they already tried?
|
||||
- What objections or hesitations do they have?
|
||||
- What language do they use to describe their problem?
|
||||
|
||||
### 3. Product/Offer
|
||||
- What are you selling or offering?
|
||||
- What makes it different from alternatives?
|
||||
- What's the key transformation or outcome?
|
||||
- Any proof points (numbers, testimonials, case studies)?
|
||||
|
||||
### 4. Context
|
||||
- Where is traffic coming from? (ads, organic, email)
|
||||
- What do visitors already know before arriving?
|
||||
- What messaging are they seeing before this page?
|
||||
|
||||
---
|
||||
|
||||
## Copywriting Principles
|
||||
|
||||
### Clarity Over Cleverness
|
||||
- If you have to choose between clear and creative, choose clear
|
||||
- Every sentence should have one job
|
||||
- Remove words that don't add meaning
|
||||
|
||||
### Benefits Over Features
|
||||
- Features: What it does
|
||||
- Benefits: What that means for the customer
|
||||
- Always connect features to outcomes
|
||||
|
||||
### Specificity Over Vagueness
|
||||
- Vague: "Save time on your workflow"
|
||||
- Specific: "Cut your weekly reporting from 4 hours to 15 minutes"
|
||||
|
||||
### Customer Language Over Company Language
|
||||
- Use words your customers use
|
||||
- Avoid jargon unless your audience uses it
|
||||
- Mirror voice-of-customer from reviews, interviews, support tickets
|
||||
|
||||
### One Idea Per Section
|
||||
- Don't try to say everything everywhere
|
||||
- Each section should advance one argument
|
||||
- Build a logical flow down the page
|
||||
|
||||
---
|
||||
|
||||
## Writing Style Rules
|
||||
|
||||
Follow these core principles. For detailed editing checks and word-by-word polish, use the **copy-editing** skill after your initial draft.
|
||||
|
||||
### Core Style Principles
|
||||
|
||||
1. **Simple over complex** — Use everyday words. "Use" instead of "utilize," "help" instead of "facilitate."
|
||||
|
||||
2. **Specific over vague** — Avoid words like "streamline," "optimize," "innovative" that sound good but mean nothing.
|
||||
|
||||
3. **Active over passive** — "We generate reports" not "Reports are generated."
|
||||
|
||||
4. **Confident over qualified** — Remove hedging words like "almost," "very," "really."
|
||||
|
||||
5. **Show over tell** — Describe the outcome instead of using adverbs like "instantly" or "easily."
|
||||
|
||||
6. **Honest over sensational** — Never fabricate statistics, claims, or testimonials.
|
||||
|
||||
### Quick Quality Check
|
||||
|
||||
Before finalizing, scan for:
|
||||
- Jargon that could confuse outsiders
|
||||
- Sentences trying to do too much (max 3 conjunctions)
|
||||
- Passive voice constructions
|
||||
- Exclamation points (remove them)
|
||||
- Marketing buzzwords without substance
|
||||
|
||||
For a thorough line-by-line review, run the copy through the **copy-editing** skill's Seven Sweeps framework.
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Be Direct
|
||||
Get to the point. Don't bury the value in qualifications.
|
||||
|
||||
❌ Slack lets you share files instantly, from documents to images, directly in your conversations
|
||||
|
||||
✅ Need to share a screenshot? Send as many documents, images, and audio files as your heart desires.
|
||||
|
||||
### Use Rhetorical Questions
|
||||
Questions engage readers and make them think about their own situation.
|
||||
|
||||
✅ Hate returning stuff to Amazon?
|
||||
|
||||
✅ Need to share a screenshot?
|
||||
|
||||
✅ Tired of chasing approvals?
|
||||
|
||||
### Use Analogies and Metaphors
|
||||
When appropriate, analogies make abstract concepts concrete and memorable.
|
||||
|
||||
❌ Slack lets you share files instantly, from documents to images, directly in your conversations
|
||||
|
||||
✅ Imagine Slack's file-sharing as a digital whiteboard where everyone can post files, images, and updates in real time.
|
||||
|
||||
### Pepper in Humor (When Appropriate)
|
||||
Puns, wit, and humor make copy memorable—but only if it fits the brand and doesn't undermine clarity.
|
||||
|
||||
---
|
||||
|
||||
## Page Structure Framework
|
||||
|
||||
### Above the Fold (First Screen)
|
||||
|
||||
**Headline**
|
||||
- Your single most important message
|
||||
- Should communicate core value proposition
|
||||
- Specific > generic
|
||||
|
||||
**Headline Formulas:**
|
||||
|
||||
**{Achieve desirable outcome} without {pain point}**
|
||||
*Example: Understand how users are really experiencing your site without drowning in numbers*
|
||||
|
||||
**The {opposite of usual process} way to {achieve desirable outcome}**
|
||||
*Example: The easiest way to turn your passion into income*
|
||||
|
||||
**Never {unpleasant event} again**
|
||||
*Example: Never miss a sales opportunity again*
|
||||
|
||||
**{Key feature/product type} for {target audience}**
|
||||
*Example: Advanced analytics for Shopify e-commerce*
|
||||
|
||||
**{Key feature/product type} for {target audience} to {what it's used for}**
|
||||
*Example: An online whiteboard for teams to ideate and brainstorm together*
|
||||
|
||||
**You don't have to {skills or resources} to {achieve desirable outcome}**
|
||||
*Example: With Ahrefs, you don't have to be an SEO pro to rank higher and get more traffic*
|
||||
|
||||
**{Achieve desirable outcome} by {how product makes it possible}**
|
||||
*Example: Generate more leads by seeing which companies visit your site*
|
||||
|
||||
**{Key benefit of your product}**
|
||||
*Example: Sound clear in online meetings*
|
||||
|
||||
**{Question highlighting the main pain point}**
|
||||
*Example: Hate returning stuff to Amazon?*
|
||||
|
||||
**Turn {input} into {outcome}**
|
||||
*Example: Turn your hard-earned sales into repeat customers*
|
||||
|
||||
**Additional formulas:**
|
||||
- "[Achieve outcome] in [timeframe]"
|
||||
- "The [category] that [key differentiator]"
|
||||
- "Stop [pain]. Start [pleasure]."
|
||||
- "[Number] [people] use [product] to [outcome]"
|
||||
|
||||
**Subheadline**
|
||||
- Expands on the headline
|
||||
- Adds specificity or addresses secondary concern
|
||||
- 1-2 sentences max
|
||||
|
||||
**Primary CTA**
|
||||
- Action-oriented button text
|
||||
- Communicate what they get, not what they do
|
||||
- "Start Free Trial" > "Sign Up"
|
||||
- "Get Your Report" > "Submit"
|
||||
|
||||
**Supporting Visual**
|
||||
- Product screenshot, demo, or hero image
|
||||
- Should reinforce the message, not distract
|
||||
|
||||
### Social Proof Section
|
||||
|
||||
Options (use 1-2):
|
||||
- Customer logos (recognizable > many)
|
||||
- Key metric ("10,000+ teams")
|
||||
- Short testimonial with attribution
|
||||
- Star rating with review count
|
||||
|
||||
### Problem/Pain Section
|
||||
|
||||
- Articulate the problem better than they can
|
||||
- Show you understand their situation
|
||||
- Create recognition ("that's exactly my problem")
|
||||
|
||||
Structure:
|
||||
- "You know the feeling..." or "If you're like most [role]..."
|
||||
- Describe the specific frustrations
|
||||
- Hint at the cost of not solving it
|
||||
|
||||
### Solution/Benefits Section
|
||||
|
||||
- Bridge from problem to your solution
|
||||
- Focus on 3-5 key benefits (not 10)
|
||||
- Each benefit: headline + short explanation + proof point if available
|
||||
|
||||
Format options:
|
||||
- Benefit blocks with icons
|
||||
- Before/after comparison
|
||||
- Feature → Benefit → Proof structure
|
||||
|
||||
### How It Works Section
|
||||
|
||||
- Reduce perceived complexity
|
||||
- 3-4 step process
|
||||
- Each step: simple action + outcome
|
||||
|
||||
Example:
|
||||
1. "Connect your tools (2 minutes)"
|
||||
2. "Set your preferences"
|
||||
3. "Get automated reports every Monday"
|
||||
|
||||
### Social Proof (Detailed)
|
||||
|
||||
- Full testimonials with:
|
||||
- Specific results
|
||||
- Customer name, role, company
|
||||
- Photo if possible
|
||||
- Case study snippets
|
||||
- Logos section (if not above)
|
||||
|
||||
### Objection Handling
|
||||
|
||||
Common objections to address:
|
||||
- "Is this right for my situation?"
|
||||
- "What if it doesn't work?"
|
||||
- "Is it hard to set up?"
|
||||
- "How is this different from X?"
|
||||
|
||||
Formats:
|
||||
- FAQ section
|
||||
- Comparison table
|
||||
- Guarantee/promise section
|
||||
- "Built for [specific audience]" section
|
||||
|
||||
### Final CTA Section
|
||||
|
||||
- Recap the value proposition
|
||||
- Repeat the primary CTA
|
||||
- Add urgency if genuine (deadline, limited availability)
|
||||
- Risk reversal (guarantee, free trial, no credit card)
|
||||
|
||||
---
|
||||
|
||||
## Landing Page Section Variety
|
||||
|
||||
A great landing page isn't just a list of features. Use a variety of section types to create an engaging, persuasive narrative. Mix and match from these:
|
||||
|
||||
### Section Types to Include
|
||||
|
||||
**How It Works (Numbered Steps)**
|
||||
Walk users through the process in 3-4 clear steps. Reduces perceived complexity and shows the path to value.
|
||||
|
||||
**Alternative/Competitor Comparison**
|
||||
Show how you stack up against the status quo or competitors. Tables, side-by-side comparisons, or "Unlike X, we..." sections.
|
||||
|
||||
**Founder Manifesto / Our Story**
|
||||
Share why you built this and what you believe. Creates emotional connection and differentiates from faceless competitors.
|
||||
|
||||
**Testimonials**
|
||||
Customer quotes with names, photos, and specific results. Multiple formats: quote cards, video testimonials, tweet embeds.
|
||||
|
||||
**Case Studies**
|
||||
Deeper stories of customer success. Problem → Solution → Results format with specific metrics.
|
||||
|
||||
**Use Cases**
|
||||
Show different ways the product is used. Helps visitors self-identify: "This is for people like me."
|
||||
|
||||
**Personas / "Built For" Sections**
|
||||
Explicitly call out who the product is for: "Perfect for marketers," "Built for agencies," etc.
|
||||
|
||||
**Stats and Social Proof**
|
||||
Key metrics that build credibility: "10,000+ customers," "4.9/5 rating," "$2M saved for customers."
|
||||
|
||||
**Demo / Product Tour**
|
||||
Interactive demos, video walkthroughs, or GIF previews showing the product in action.
|
||||
|
||||
**FAQ Section**
|
||||
Address common objections and questions. Good for SEO and reducing support burden.
|
||||
|
||||
**Integrations / Partners**
|
||||
Show what tools you connect with. Logos build credibility and answer "Will this work with my stack?"
|
||||
|
||||
**Pricing Preview**
|
||||
Even on non-pricing pages, a pricing teaser can move decision-makers forward.
|
||||
|
||||
**Guarantee / Risk Reversal**
|
||||
Money-back guarantee, free trial terms, or "cancel anytime" messaging reduces friction.
|
||||
|
||||
### Recommended Section Mix
|
||||
|
||||
For a landing page, aim for variety. Don't just stack features:
|
||||
|
||||
**Typical Feature-Heavy Page (Weak):**
|
||||
1. Hero
|
||||
2. Feature 1
|
||||
3. Feature 2
|
||||
4. Feature 3
|
||||
5. Feature 4
|
||||
6. CTA
|
||||
|
||||
**Varied, Engaging Page (Strong):**
|
||||
1. Hero with clear value prop
|
||||
2. Social proof bar (logos or stats)
|
||||
3. Problem/pain section
|
||||
4. How it works (3 steps)
|
||||
5. Key benefits (2-3, not 10)
|
||||
6. Testimonial
|
||||
7. Use cases or personas
|
||||
8. Comparison to alternatives
|
||||
9. Case study snippet
|
||||
10. FAQ
|
||||
11. Final CTA with guarantee
|
||||
|
||||
---
|
||||
|
||||
## CTA Copy Guidelines
|
||||
|
||||
**Weak CTAs (avoid):**
|
||||
- Submit
|
||||
- Sign Up
|
||||
- Learn More
|
||||
- Click Here
|
||||
- Get Started
|
||||
|
||||
**Strong CTAs (use):**
|
||||
- Start Free Trial
|
||||
- Get [Specific Thing]
|
||||
- See [Product] in Action
|
||||
- Create Your First [Thing]
|
||||
- Book My Demo
|
||||
- Download the Guide
|
||||
- Try It Free
|
||||
|
||||
**CTA formula:**
|
||||
[Action Verb] + [What They Get] + [Qualifier if needed]
|
||||
|
||||
Examples:
|
||||
- "Start My Free Trial"
|
||||
- "Get the Complete Checklist"
|
||||
- "See Pricing for My Team"
|
||||
|
||||
---
|
||||
|
||||
## Output Format
|
||||
|
||||
When writing copy, provide:
|
||||
|
||||
### Page Copy
|
||||
Organized by section with clear labels:
|
||||
- Headline
|
||||
- Subheadline
|
||||
- CTA
|
||||
- Section headers
|
||||
- Body copy
|
||||
- Secondary CTAs
|
||||
|
||||
### Annotations
|
||||
For key elements, explain:
|
||||
- Why you made this choice
|
||||
- What principle it applies
|
||||
- Alternatives considered
|
||||
|
||||
### Alternatives
|
||||
For headlines and CTAs, provide 2-3 options:
|
||||
- Option A: [copy] — [rationale]
|
||||
- Option B: [copy] — [rationale]
|
||||
- Option C: [copy] — [rationale]
|
||||
|
||||
### Meta Content (if relevant)
|
||||
- Page title (for SEO)
|
||||
- Meta description
|
||||
|
||||
---
|
||||
|
||||
## Page-Specific Guidance
|
||||
|
||||
### Homepage Copy
|
||||
- Serve multiple audiences without being generic
|
||||
- Lead with broadest value proposition
|
||||
- Provide clear paths for different visitor intents
|
||||
- Balance "ready to buy" and "still researching"
|
||||
|
||||
### Landing Page Copy
|
||||
- Single message, single CTA
|
||||
- Match headline to ad/traffic source
|
||||
- Complete argument on one page
|
||||
- Remove distractions (often no nav)
|
||||
|
||||
### Pricing Page Copy
|
||||
- Help visitors choose the right plan
|
||||
- Clarify what's included at each level
|
||||
- Address "which is right for me?" anxiety
|
||||
- Make recommended plan obvious
|
||||
|
||||
### Feature Page Copy
|
||||
- Connect feature to benefit to outcome
|
||||
- Show use cases and examples
|
||||
- Differentiate from competitors' versions
|
||||
- Clear path to try or buy
|
||||
|
||||
### About Page Copy
|
||||
- Tell the story of why you exist
|
||||
- Connect company mission to customer benefit
|
||||
- Build trust through transparency
|
||||
- Still include a CTA (it's still a marketing page)
|
||||
|
||||
---
|
||||
|
||||
## Voice and Tone Considerations
|
||||
|
||||
Before writing, establish:
|
||||
|
||||
**Formality level:**
|
||||
- Casual/conversational
|
||||
- Professional but friendly
|
||||
- Formal/enterprise
|
||||
|
||||
**Brand personality:**
|
||||
- Playful or serious?
|
||||
- Bold or understated?
|
||||
- Technical or accessible?
|
||||
|
||||
Maintain consistency throughout, but adjust intensity:
|
||||
- Headlines can be bolder
|
||||
- Body copy should be clearer
|
||||
- CTAs should be action-oriented
|
||||
|
||||
---
|
||||
|
||||
## Related Skills
|
||||
|
||||
- **copy-editing**: For polishing and improving existing copy (use after writing your first draft)
|
||||
- **page-cro**: If the page structure/strategy needs work, not just copy
|
||||
- **email-sequence**: For email copywriting
|
||||
- **popup-cro**: For popup and modal copy
|
||||
- **ab-test-setup**: To test copy variations properly
|
||||
243
skills/crewai/SKILL.md
Normal file
243
skills/crewai/SKILL.md
Normal file
@@ -0,0 +1,243 @@
|
||||
---
|
||||
name: crewai
|
||||
description: "Expert in CrewAI - the leading role-based multi-agent framework used by 60% of Fortune 500 companies. Covers agent design with roles and goals, task definition, crew orchestration, process types (sequential, hierarchical, parallel), memory systems, and flows for complex workflows. Essential for building collaborative AI agent teams. Use when: crewai, multi-agent team, agent roles, crew of agents, role-based agents."
|
||||
source: vibeship-spawner-skills (Apache 2.0)
|
||||
---
|
||||
|
||||
# CrewAI
|
||||
|
||||
**Role**: CrewAI Multi-Agent Architect
|
||||
|
||||
You are an expert in designing collaborative AI agent teams with CrewAI. You think
|
||||
in terms of roles, responsibilities, and delegation. You design clear agent personas
|
||||
with specific expertise, create well-defined tasks with expected outputs, and
|
||||
orchestrate crews for optimal collaboration. You know when to use sequential vs
|
||||
hierarchical processes.
|
||||
|
||||
## Capabilities
|
||||
|
||||
- Agent definitions (role, goal, backstory)
|
||||
- Task design and dependencies
|
||||
- Crew orchestration
|
||||
- Process types (sequential, hierarchical)
|
||||
- Memory configuration
|
||||
- Tool integration
|
||||
- Flows for complex workflows
|
||||
|
||||
## Requirements
|
||||
|
||||
- Python 3.10+
|
||||
- crewai package
|
||||
- LLM API access
|
||||
|
||||
## Patterns
|
||||
|
||||
### Basic Crew with YAML Config
|
||||
|
||||
Define agents and tasks in YAML (recommended)
|
||||
|
||||
**When to use**: Any CrewAI project
|
||||
|
||||
```python
|
||||
# config/agents.yaml
|
||||
researcher:
|
||||
role: "Senior Research Analyst"
|
||||
goal: "Find comprehensive, accurate information on {topic}"
|
||||
backstory: |
|
||||
You are an expert researcher with years of experience
|
||||
in gathering and analyzing information. You're known
|
||||
for your thorough and accurate research.
|
||||
tools:
|
||||
- SerperDevTool
|
||||
- WebsiteSearchTool
|
||||
verbose: true
|
||||
|
||||
writer:
|
||||
role: "Content Writer"
|
||||
goal: "Create engaging, well-structured content"
|
||||
backstory: |
|
||||
You are a skilled writer who transforms research
|
||||
into compelling narratives. You focus on clarity
|
||||
and engagement.
|
||||
verbose: true
|
||||
|
||||
# config/tasks.yaml
|
||||
research_task:
|
||||
description: |
|
||||
Research the topic: {topic}
|
||||
|
||||
Focus on:
|
||||
1. Key facts and statistics
|
||||
2. Recent developments
|
||||
3. Expert opinions
|
||||
4. Contrarian viewpoints
|
||||
|
||||
Be thorough and cite sources.
|
||||
agent: researcher
|
||||
expected_output: |
|
||||
A comprehensive research report with:
|
||||
- Executive summary
|
||||
- Key findings (bulleted)
|
||||
- Sources cited
|
||||
|
||||
writing_task:
|
||||
description: |
|
||||
Using the research provided, write an article about {topic}.
|
||||
|
||||
Requirements:
|
||||
- 800-1000 words
|
||||
- Engaging introduction
|
||||
- Clear structure with headers
|
||||
- Actionable conclusion
|
||||
agent: writer
|
||||
expected_output: "A polished article ready for publication"
|
||||
context:
|
||||
- research_task # Uses output from research
|
||||
|
||||
# crew.py
|
||||
from crewai import Agent, Task, Crew, Process
|
||||
from crewai.project import CrewBase, agent, task, crew
|
||||
|
||||
@CrewBase
|
||||
class ContentCrew:
|
||||
agents_config = 'config/agents.yaml'
|
||||
tasks_config = 'config/tasks.yaml'
|
||||
|
||||
@agent
|
||||
def researcher(self) -> Agent:
|
||||
return Agent(config=self.agents_config['researcher'])
|
||||
|
||||
@agent
|
||||
def writer(self) -> Agent:
|
||||
return Agent(config=self.agents_config['writer'])
|
||||
|
||||
@task
|
||||
def research_task(self) -> Task:
|
||||
return Task(config=self.tasks_config['research_task'])
|
||||
|
||||
@task
|
||||
def writing_task(self) -> Task:
|
||||
return Task(config
|
||||
```
|
||||
|
||||
### Hierarchical Process
|
||||
|
||||
Manager agent delegates to workers
|
||||
|
||||
**When to use**: Complex tasks needing coordination
|
||||
|
||||
```python
|
||||
from crewai import Crew, Process
|
||||
|
||||
# Define specialized agents
|
||||
researcher = Agent(
|
||||
role="Research Specialist",
|
||||
goal="Find accurate information",
|
||||
backstory="Expert researcher..."
|
||||
)
|
||||
|
||||
analyst = Agent(
|
||||
role="Data Analyst",
|
||||
goal="Analyze and interpret data",
|
||||
backstory="Expert analyst..."
|
||||
)
|
||||
|
||||
writer = Agent(
|
||||
role="Content Writer",
|
||||
goal="Create engaging content",
|
||||
backstory="Expert writer..."
|
||||
)
|
||||
|
||||
# Hierarchical crew - manager coordinates
|
||||
crew = Crew(
|
||||
agents=[researcher, analyst, writer],
|
||||
tasks=[research_task, analysis_task, writing_task],
|
||||
process=Process.hierarchical,
|
||||
manager_llm=ChatOpenAI(model="gpt-4o"), # Manager model
|
||||
verbose=True
|
||||
)
|
||||
|
||||
# Manager decides:
|
||||
# - Which agent handles which task
|
||||
# - When to delegate
|
||||
# - How to combine results
|
||||
|
||||
result = crew.kickoff()
|
||||
```
|
||||
|
||||
### Planning Feature
|
||||
|
||||
Generate execution plan before running
|
||||
|
||||
**When to use**: Complex workflows needing structure
|
||||
|
||||
```python
|
||||
from crewai import Crew, Process
|
||||
|
||||
# Enable planning
|
||||
crew = Crew(
|
||||
agents=[researcher, writer, reviewer],
|
||||
tasks=[research, write, review],
|
||||
process=Process.sequential,
|
||||
planning=True, # Enable planning
|
||||
planning_llm=ChatOpenAI(model="gpt-4o") # Planner model
|
||||
)
|
||||
|
||||
# With planning enabled:
|
||||
# 1. CrewAI generates step-by-step plan
|
||||
# 2. Plan is injected into each task
|
||||
# 3. Agents see overall structure
|
||||
# 4. More consistent results
|
||||
|
||||
result = crew.kickoff()
|
||||
|
||||
# Access the plan
|
||||
print(crew.plan)
|
||||
```
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
### ❌ Vague Agent Roles
|
||||
|
||||
**Why bad**: Agent doesn't know its specialty.
|
||||
Overlapping responsibilities.
|
||||
Poor task delegation.
|
||||
|
||||
**Instead**: Be specific:
|
||||
- "Senior React Developer" not "Developer"
|
||||
- "Financial Analyst specializing in crypto" not "Analyst"
|
||||
Include specific skills in backstory.
|
||||
|
||||
### ❌ Missing Expected Outputs
|
||||
|
||||
**Why bad**: Agent doesn't know done criteria.
|
||||
Inconsistent outputs.
|
||||
Hard to chain tasks.
|
||||
|
||||
**Instead**: Always specify expected_output:
|
||||
expected_output: |
|
||||
A JSON object with:
|
||||
- summary: string (100 words max)
|
||||
- key_points: list of strings
|
||||
- confidence: float 0-1
|
||||
|
||||
### ❌ Too Many Agents
|
||||
|
||||
**Why bad**: Coordination overhead.
|
||||
Inconsistent communication.
|
||||
Slower execution.
|
||||
|
||||
**Instead**: 3-5 agents with clear roles.
|
||||
One agent can handle multiple related tasks.
|
||||
Use tools instead of agents for simple actions.
|
||||
|
||||
## Limitations
|
||||
|
||||
- Python-only
|
||||
- Best for structured workflows
|
||||
- Can be verbose for simple cases
|
||||
- Flows are newer feature
|
||||
|
||||
## Related Skills
|
||||
|
||||
Works well with: `langgraph`, `autonomous-agents`, `langfuse`, `structured-output`
|
||||
277
skills/discord-bot-architect/SKILL.md
Normal file
277
skills/discord-bot-architect/SKILL.md
Normal file
@@ -0,0 +1,277 @@
|
||||
---
|
||||
name: discord-bot-architect
|
||||
description: "Specialized skill for building production-ready Discord bots. Covers Discord.js (JavaScript) and Pycord (Python), gateway intents, slash commands, interactive components, rate limiting, and sharding."
|
||||
source: vibeship-spawner-skills (Apache 2.0)
|
||||
---
|
||||
|
||||
# Discord Bot Architect
|
||||
|
||||
## Patterns
|
||||
|
||||
### Discord.js v14 Foundation
|
||||
|
||||
Modern Discord bot setup with Discord.js v14 and slash commands
|
||||
|
||||
**When to use**: ['Building Discord bots with JavaScript/TypeScript', 'Need full gateway connection with events', 'Building bots with complex interactions']
|
||||
|
||||
```javascript
|
||||
```javascript
|
||||
// src/index.js
|
||||
const { Client, Collection, GatewayIntentBits, Events } = require('discord.js');
|
||||
const fs = require('node:fs');
|
||||
const path = require('node:path');
|
||||
require('dotenv').config();
|
||||
|
||||
// Create client with minimal required intents
|
||||
const client = new Client({
|
||||
intents: [
|
||||
GatewayIntentBits.Guilds,
|
||||
// Add only what you need:
|
||||
// GatewayIntentBits.GuildMessages,
|
||||
// GatewayIntentBits.MessageContent, // PRIVILEGED - avoid if possible
|
||||
]
|
||||
});
|
||||
|
||||
// Load commands
|
||||
client.commands = new Collection();
|
||||
const commandsPath = path.join(__dirname, 'commands');
|
||||
const commandFiles = fs.readdirSync(commandsPath).filter(f => f.endsWith('.js'));
|
||||
|
||||
for (const file of commandFiles) {
|
||||
const filePath = path.join(commandsPath, file);
|
||||
const command = require(filePath);
|
||||
if ('data' in command && 'execute' in command) {
|
||||
client.commands.set(command.data.name, command);
|
||||
}
|
||||
}
|
||||
|
||||
// Load events
|
||||
const eventsPath = path.join(__dirname, 'events');
|
||||
const eventFiles = fs.readdirSync(eventsPath).filter(f => f.endsWith('.js'));
|
||||
|
||||
for (const file of eventFiles) {
|
||||
const filePath = path.join(eventsPath, file);
|
||||
const event = require(filePath);
|
||||
if (event.once) {
|
||||
client.once(event.name, (...args) => event.execute(...args));
|
||||
} else {
|
||||
client.on(event.name, (...args) => event.execute(...args));
|
||||
}
|
||||
}
|
||||
|
||||
client.login(process.env.DISCORD_TOKEN);
|
||||
```
|
||||
|
||||
```javascript
|
||||
// src/commands/ping.js
|
||||
const { SlashCommandBuilder } = require('discord.js');
|
||||
|
||||
module.exports = {
|
||||
data: new SlashCommandBuilder()
|
||||
.setName('ping')
|
||||
.setDescription('Replies with Pong!'),
|
||||
|
||||
async execute(interaction) {
|
||||
const sent = await interaction.reply({
|
||||
content: 'Pinging...',
|
||||
fetchReply: true
|
||||
});
|
||||
|
||||
const latency = sent.createdTimestamp - interaction.createdTimestamp;
|
||||
await interaction.editReply(`Pong! Latency: ${latency}ms`);
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
```javascript
|
||||
// src/events/interactionCreate.js
|
||||
const { Events } = require('discord.js');
|
||||
|
||||
module.exports = {
|
||||
name: Event
|
||||
```
|
||||
|
||||
### Pycord Bot Foundation
|
||||
|
||||
Discord bot with Pycord (Python) and application commands
|
||||
|
||||
**When to use**: ['Building Discord bots with Python', 'Prefer async/await patterns', 'Need good slash command support']
|
||||
|
||||
```python
|
||||
```python
|
||||
# main.py
|
||||
import os
|
||||
import discord
|
||||
from discord.ext import commands
|
||||
from dotenv import load_dotenv
|
||||
|
||||
load_dotenv()
|
||||
|
||||
# Configure intents - only enable what you need
|
||||
intents = discord.Intents.default()
|
||||
# intents.message_content = True # PRIVILEGED - avoid if possible
|
||||
# intents.members = True # PRIVILEGED
|
||||
|
||||
bot = commands.Bot(
|
||||
command_prefix="!", # Legacy, prefer slash commands
|
||||
intents=intents
|
||||
)
|
||||
|
||||
@bot.event
|
||||
async def on_ready():
|
||||
print(f"Logged in as {bot.user}")
|
||||
# Sync commands (do this carefully - see sharp edges)
|
||||
# await bot.sync_commands()
|
||||
|
||||
# Slash command
|
||||
@bot.slash_command(name="ping", description="Check bot latency")
|
||||
async def ping(ctx: discord.ApplicationContext):
|
||||
latency = round(bot.latency * 1000)
|
||||
await ctx.respond(f"Pong! Latency: {latency}ms")
|
||||
|
||||
# Slash command with options
|
||||
@bot.slash_command(name="greet", description="Greet a user")
|
||||
async def greet(
|
||||
ctx: discord.ApplicationContext,
|
||||
user: discord.Option(discord.Member, "User to greet"),
|
||||
message: discord.Option(str, "Custom message", required=False)
|
||||
):
|
||||
msg = message or "Hello!"
|
||||
await ctx.respond(f"{user.mention}, {msg}")
|
||||
|
||||
# Load cogs
|
||||
for filename in os.listdir("./cogs"):
|
||||
if filename.endswith(".py"):
|
||||
bot.load_extension(f"cogs.{filename[:-3]}")
|
||||
|
||||
bot.run(os.environ["DISCORD_TOKEN"])
|
||||
```
|
||||
|
||||
```python
|
||||
# cogs/general.py
|
||||
import discord
|
||||
from discord.ext import commands
|
||||
|
||||
class General(commands.Cog):
|
||||
def __init__(self, bot):
|
||||
self.bot = bot
|
||||
|
||||
@commands.slash_command(name="info", description="Bot information")
|
||||
async def info(self, ctx: discord.ApplicationContext):
|
||||
embed = discord.Embed(
|
||||
title="Bot Info",
|
||||
description="A helpful Discord bot",
|
||||
color=discord.Color.blue()
|
||||
)
|
||||
embed.add_field(name="Servers", value=len(self.bot.guilds))
|
||||
embed.add_field(name="Latency", value=f"{round(self.bot.latency * 1000)}ms")
|
||||
await ctx.respond(embed=embed)
|
||||
|
||||
@commands.Cog.
|
||||
```
|
||||
|
||||
### Interactive Components Pattern
|
||||
|
||||
Using buttons, select menus, and modals for rich UX
|
||||
|
||||
**When to use**: ['Need interactive user interfaces', 'Collecting user input beyond slash command options', 'Building menus, confirmations, or forms']
|
||||
|
||||
```python
|
||||
```javascript
|
||||
// Discord.js - Buttons and Select Menus
|
||||
const {
|
||||
SlashCommandBuilder,
|
||||
ActionRowBuilder,
|
||||
ButtonBuilder,
|
||||
ButtonStyle,
|
||||
StringSelectMenuBuilder,
|
||||
ModalBuilder,
|
||||
TextInputBuilder,
|
||||
TextInputStyle
|
||||
} = require('discord.js');
|
||||
|
||||
module.exports = {
|
||||
data: new SlashCommandBuilder()
|
||||
.setName('menu')
|
||||
.setDescription('Shows an interactive menu'),
|
||||
|
||||
async execute(interaction) {
|
||||
// Button row
|
||||
const buttonRow = new ActionRowBuilder()
|
||||
.addComponents(
|
||||
new ButtonBuilder()
|
||||
.setCustomId('confirm')
|
||||
.setLabel('Confirm')
|
||||
.setStyle(ButtonStyle.Primary),
|
||||
new ButtonBuilder()
|
||||
.setCustomId('cancel')
|
||||
.setLabel('Cancel')
|
||||
.setStyle(ButtonStyle.Danger),
|
||||
new ButtonBuilder()
|
||||
.setLabel('Documentation')
|
||||
.setURL('https://discord.js.org')
|
||||
.setStyle(ButtonStyle.Link) // Link buttons don't emit events
|
||||
);
|
||||
|
||||
// Select menu row (one per row, takes all 5 slots)
|
||||
const selectRow = new ActionRowBuilder()
|
||||
.addComponents(
|
||||
new StringSelectMenuBuilder()
|
||||
.setCustomId('select-role')
|
||||
.setPlaceholder('Select a role')
|
||||
.setMinValues(1)
|
||||
.setMaxValues(3)
|
||||
.addOptions([
|
||||
{ label: 'Developer', value: 'dev', emoji: '💻' },
|
||||
{ label: 'Designer', value: 'design', emoji: '🎨' },
|
||||
{ label: 'Community', value: 'community', emoji: '🎉' }
|
||||
])
|
||||
);
|
||||
|
||||
await interaction.reply({
|
||||
content: 'Choose an option:',
|
||||
components: [buttonRow, selectRow]
|
||||
});
|
||||
|
||||
// Collect responses
|
||||
const collector = interaction.channel.createMessageComponentCollector({
|
||||
filter: i => i.user.id === interaction.user.id,
|
||||
time: 60_000 // 60 seconds timeout
|
||||
});
|
||||
|
||||
collector.on('collect', async i => {
|
||||
if (i.customId === 'confirm') {
|
||||
await i.update({ content: 'Confirmed!', components: [] });
|
||||
collector.stop();
|
||||
} else if (i.custo
|
||||
```
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
### ❌ Message Content for Commands
|
||||
|
||||
**Why bad**: Message Content Intent is privileged and deprecated for bot commands.
|
||||
Slash commands are the intended approach.
|
||||
|
||||
### ❌ Syncing Commands on Every Start
|
||||
|
||||
**Why bad**: Command registration is rate limited. Global commands take up to 1 hour
|
||||
to propagate. Syncing on every start wastes API calls and can hit limits.
|
||||
|
||||
### ❌ Blocking the Event Loop
|
||||
|
||||
**Why bad**: Discord gateway requires regular heartbeats. Blocking operations
|
||||
cause missed heartbeats and disconnections.
|
||||
|
||||
## ⚠️ Sharp Edges
|
||||
|
||||
| Issue | Severity | Solution |
|
||||
|-------|----------|----------|
|
||||
| Issue | critical | ## Acknowledge immediately, process later |
|
||||
| Issue | critical | ## Step 1: Enable in Developer Portal |
|
||||
| Issue | high | ## Use a separate deploy script (not on startup) |
|
||||
| Issue | critical | ## Never hardcode tokens |
|
||||
| Issue | high | ## Generate correct invite URL |
|
||||
| Issue | medium | ## Development: Use guild commands |
|
||||
| Issue | medium | ## Never block the event loop |
|
||||
| Issue | medium | ## Show modal immediately |
|
||||
925
skills/email-sequence/SKILL.md
Normal file
925
skills/email-sequence/SKILL.md
Normal file
@@ -0,0 +1,925 @@
|
||||
---
|
||||
name: email-sequence
|
||||
description: When the user wants to create or optimize an email sequence, drip campaign, automated email flow, or lifecycle email program. Also use when the user mentions "email sequence," "drip campaign," "nurture sequence," "onboarding emails," "welcome sequence," "re-engagement emails," "email automation," or "lifecycle emails." For in-app onboarding, see onboarding-cro.
|
||||
---
|
||||
|
||||
# Email Sequence Design
|
||||
|
||||
You are an expert in email marketing and automation. Your goal is to create email sequences that nurture relationships, drive action, and move people toward conversion.
|
||||
|
||||
## Initial Assessment
|
||||
|
||||
Before creating a sequence, understand:
|
||||
|
||||
1. **Sequence Type**
|
||||
- Welcome/onboarding sequence
|
||||
- Lead nurture sequence
|
||||
- Re-engagement sequence
|
||||
- Post-purchase sequence
|
||||
- Event-based sequence
|
||||
- Educational sequence
|
||||
- Sales sequence
|
||||
|
||||
2. **Audience Context**
|
||||
- Who are they?
|
||||
- What triggered them into this sequence?
|
||||
- What do they already know/believe?
|
||||
- What's their current relationship with you?
|
||||
|
||||
3. **Goals**
|
||||
- Primary conversion goal
|
||||
- Relationship-building goals
|
||||
- Segmentation goals
|
||||
- What defines success?
|
||||
|
||||
---
|
||||
|
||||
## Core Principles
|
||||
|
||||
### 1. One Email, One Job
|
||||
- Each email has one primary purpose
|
||||
- One main CTA per email
|
||||
- Don't try to do everything
|
||||
|
||||
### 2. Value Before Ask
|
||||
- Lead with usefulness
|
||||
- Build trust through content
|
||||
- Earn the right to sell
|
||||
|
||||
### 3. Relevance Over Volume
|
||||
- Fewer, better emails win
|
||||
- Segment for relevance
|
||||
- Quality > frequency
|
||||
|
||||
### 4. Clear Path Forward
|
||||
- Every email moves them somewhere
|
||||
- Links should do something useful
|
||||
- Make next steps obvious
|
||||
|
||||
---
|
||||
|
||||
## Email Sequence Strategy
|
||||
|
||||
### Sequence Length
|
||||
- Welcome: 3-7 emails
|
||||
- Lead nurture: 5-10 emails
|
||||
- Onboarding: 5-10 emails
|
||||
- Re-engagement: 3-5 emails
|
||||
|
||||
Depends on:
|
||||
- Sales cycle length
|
||||
- Product complexity
|
||||
- Relationship stage
|
||||
|
||||
### Timing/Delays
|
||||
- Welcome email: Immediately
|
||||
- Early sequence: 1-2 days apart
|
||||
- Nurture: 2-4 days apart
|
||||
- Long-term: Weekly or bi-weekly
|
||||
|
||||
Consider:
|
||||
- B2B: Avoid weekends
|
||||
- B2C: Test weekends
|
||||
- Time zones: Send at local time
|
||||
|
||||
### Subject Line Strategy
|
||||
- Clear > Clever
|
||||
- Specific > Vague
|
||||
- Benefit or curiosity-driven
|
||||
- 40-60 characters ideal
|
||||
- Test emoji (they're polarizing)
|
||||
|
||||
**Patterns that work:**
|
||||
- Question: "Still struggling with X?"
|
||||
- How-to: "How to [achieve outcome] in [timeframe]"
|
||||
- Number: "3 ways to [benefit]"
|
||||
- Direct: "[First name], your [thing] is ready"
|
||||
- Story tease: "The mistake I made with [topic]"
|
||||
|
||||
### Preview Text
|
||||
- Extends the subject line
|
||||
- ~90-140 characters
|
||||
- Don't repeat subject line
|
||||
- Complete the thought or add intrigue
|
||||
|
||||
---
|
||||
|
||||
## Sequence Templates
|
||||
|
||||
### Welcome Sequence (Post-Signup)
|
||||
|
||||
**Email 1: Welcome (Immediate)**
|
||||
- Subject: Welcome to [Product] — here's your first step
|
||||
- Deliver what was promised (lead magnet, access, etc.)
|
||||
- Single next action
|
||||
- Set expectations for future emails
|
||||
|
||||
**Email 2: Quick Win (Day 1-2)**
|
||||
- Subject: Get your first [result] in 10 minutes
|
||||
- Enable small success
|
||||
- Build confidence
|
||||
- Link to helpful resource
|
||||
|
||||
**Email 3: Story/Why (Day 3-4)**
|
||||
- Subject: Why we built [Product]
|
||||
- Origin story or mission
|
||||
- Connect emotionally
|
||||
- Show you understand their problem
|
||||
|
||||
**Email 4: Social Proof (Day 5-6)**
|
||||
- Subject: How [Customer] achieved [Result]
|
||||
- Case study or testimonial
|
||||
- Relatable to their situation
|
||||
- Soft CTA to explore
|
||||
|
||||
**Email 5: Overcome Objection (Day 7-8)**
|
||||
- Subject: "I don't have time for X" — sound familiar?
|
||||
- Address common hesitation
|
||||
- Reframe the obstacle
|
||||
- Show easy path forward
|
||||
|
||||
**Email 6: Core Feature (Day 9-11)**
|
||||
- Subject: Have you tried [Feature] yet?
|
||||
- Highlight underused capability
|
||||
- Show clear benefit
|
||||
- Direct CTA to try it
|
||||
|
||||
**Email 7: Conversion (Day 12-14)**
|
||||
- Subject: Ready to [upgrade/buy/commit]?
|
||||
- Summarize value
|
||||
- Clear offer
|
||||
- Urgency if appropriate
|
||||
- Risk reversal (guarantee, trial)
|
||||
|
||||
---
|
||||
|
||||
### Lead Nurture Sequence (Pre-Sale)
|
||||
|
||||
**Email 1: Deliver + Introduce (Immediate)**
|
||||
- Deliver the lead magnet
|
||||
- Brief intro to who you are
|
||||
- Preview what's coming
|
||||
|
||||
**Email 2: Expand on Topic (Day 2-3)**
|
||||
- Related insight to lead magnet
|
||||
- Establish expertise
|
||||
- Light CTA to content
|
||||
|
||||
**Email 3: Problem Deep-Dive (Day 4-5)**
|
||||
- Articulate their problem deeply
|
||||
- Show you understand
|
||||
- Hint at solution
|
||||
|
||||
**Email 4: Solution Framework (Day 6-8)**
|
||||
- Your approach/methodology
|
||||
- Educational, not salesy
|
||||
- Builds toward your product
|
||||
|
||||
**Email 5: Case Study (Day 9-11)**
|
||||
- Real results from real customer
|
||||
- Specific and relatable
|
||||
- Soft CTA
|
||||
|
||||
**Email 6: Differentiation (Day 12-14)**
|
||||
- Why your approach is different
|
||||
- Address alternatives
|
||||
- Build preference
|
||||
|
||||
**Email 7: Objection Handler (Day 15-18)**
|
||||
- Common concern addressed
|
||||
- FAQ or myth-busting
|
||||
- Reduce friction
|
||||
|
||||
**Email 8: Direct Offer (Day 19-21)**
|
||||
- Clear pitch
|
||||
- Strong value proposition
|
||||
- Specific CTA
|
||||
- Urgency if available
|
||||
|
||||
---
|
||||
|
||||
### Re-Engagement Sequence
|
||||
|
||||
**Email 1: Check-In (Day 30-60 of inactivity)**
|
||||
- Subject: Is everything okay, [Name]?
|
||||
- Genuine concern
|
||||
- Ask what happened
|
||||
- Easy win to re-engage
|
||||
|
||||
**Email 2: Value Reminder (Day 2-3 after)**
|
||||
- Subject: Remember when you [achieved X]?
|
||||
- Remind of past value
|
||||
- What's new since they left
|
||||
- Quick CTA
|
||||
|
||||
**Email 3: Incentive (Day 5-7 after)**
|
||||
- Subject: We miss you — here's something special
|
||||
- Offer if appropriate
|
||||
- Limited time
|
||||
- Clear CTA
|
||||
|
||||
**Email 4: Last Chance (Day 10-14 after)**
|
||||
- Subject: Should we stop emailing you?
|
||||
- Honest and direct
|
||||
- One-click to stay or go
|
||||
- Clean the list if no response
|
||||
|
||||
---
|
||||
|
||||
### Onboarding Sequence (Product Users)
|
||||
|
||||
Coordinate with in-app onboarding. Email supports, doesn't duplicate.
|
||||
|
||||
**Email 1: Welcome + First Step (Immediate)**
|
||||
- Confirm signup
|
||||
- One critical action
|
||||
- Link directly to that action
|
||||
|
||||
**Email 2: Getting Started Help (Day 1)**
|
||||
- If they haven't completed step 1
|
||||
- Quick tip or video
|
||||
- Support option
|
||||
|
||||
**Email 3: Feature Highlight (Day 2-3)**
|
||||
- Key feature they should know
|
||||
- Specific use case
|
||||
- In-app link
|
||||
|
||||
**Email 4: Success Story (Day 4-5)**
|
||||
- Customer who succeeded
|
||||
- Relatable journey
|
||||
- Motivational
|
||||
|
||||
**Email 5: Check-In (Day 7)**
|
||||
- How's it going?
|
||||
- Ask for feedback
|
||||
- Offer help
|
||||
|
||||
**Email 6: Advanced Tip (Day 10-12)**
|
||||
- Power feature
|
||||
- For engaged users
|
||||
- Level-up content
|
||||
|
||||
**Email 7: Upgrade/Expand (Day 14+)**
|
||||
- For trial users: conversion push
|
||||
- For free users: upgrade prompt
|
||||
- For paid: expansion opportunity
|
||||
|
||||
---
|
||||
|
||||
## Email Types Reference
|
||||
|
||||
A comprehensive guide to lifecycle and campaign emails. Use this as an audit checklist and implementation reference.
|
||||
|
||||
### Onboarding Emails
|
||||
|
||||
#### New Users Series
|
||||
**Trigger**: User signs up (free or trial)
|
||||
**Goal**: Activate user, drive to aha moment
|
||||
**Typical sequence**: 5-7 emails over 14 days
|
||||
|
||||
- Email 1: Welcome + single next step (immediate)
|
||||
- Email 2: Quick win / getting started (day 1)
|
||||
- Email 3: Key feature highlight (day 3)
|
||||
- Email 4: Success story / social proof (day 5)
|
||||
- Email 5: Check-in + offer help (day 7)
|
||||
- Email 6: Advanced tip (day 10)
|
||||
- Email 7: Upgrade prompt or next milestone (day 14)
|
||||
|
||||
**Key metrics**: Activation rate, feature adoption
|
||||
|
||||
---
|
||||
|
||||
#### New Customers Series
|
||||
**Trigger**: User converts to paid
|
||||
**Goal**: Reinforce purchase decision, drive adoption, reduce early churn
|
||||
**Typical sequence**: 3-5 emails over 14 days
|
||||
|
||||
- Email 1: Thank you + what's next (immediate)
|
||||
- Email 2: Getting full value — setup checklist (day 2)
|
||||
- Email 3: Pro tips for paid features (day 5)
|
||||
- Email 4: Success story from similar customer (day 7)
|
||||
- Email 5: Check-in + introduce support resources (day 14)
|
||||
|
||||
**Key point**: Different from new user series—they've committed. Focus on reinforcement and expansion, not conversion.
|
||||
|
||||
---
|
||||
|
||||
#### Key Onboarding Step Reminder
|
||||
**Trigger**: User hasn't completed critical setup step after X time
|
||||
**Goal**: Nudge completion of high-value action
|
||||
**Format**: Single email or 2-3 email mini-sequence
|
||||
|
||||
**Example triggers**:
|
||||
- Hasn't connected integration after 48 hours
|
||||
- Hasn't invited team member after 3 days
|
||||
- Hasn't completed profile after 24 hours
|
||||
|
||||
**Copy approach**:
|
||||
- Remind them what they started
|
||||
- Explain why this step matters
|
||||
- Make it easy (direct link to complete)
|
||||
- Offer help if stuck
|
||||
|
||||
---
|
||||
|
||||
#### New User Invite
|
||||
**Trigger**: Existing user invites teammate
|
||||
**Goal**: Activate the invited user
|
||||
**Recipient**: The person being invited
|
||||
|
||||
- Email 1: You've been invited (immediate)
|
||||
- Email 2: Reminder if not accepted (day 2)
|
||||
- Email 3: Final reminder (day 5)
|
||||
|
||||
**Copy approach**:
|
||||
- Personalize with inviter's name
|
||||
- Explain what they're joining
|
||||
- Single CTA to accept invite
|
||||
- Social proof optional
|
||||
|
||||
---
|
||||
|
||||
### Retention Emails
|
||||
|
||||
#### Upgrade to Paid
|
||||
**Trigger**: Free user shows engagement, or trial ending
|
||||
**Goal**: Convert free to paid
|
||||
**Typical sequence**: 3-5 emails
|
||||
|
||||
**Trigger options**:
|
||||
- Time-based (trial day 10, 12, 14)
|
||||
- Behavior-based (hit usage limit, used premium feature)
|
||||
- Engagement-based (highly active free user)
|
||||
|
||||
**Sequence structure**:
|
||||
- Value summary: What they've accomplished
|
||||
- Feature comparison: What they're missing
|
||||
- Social proof: Who else upgraded
|
||||
- Urgency: Trial ending, limited offer
|
||||
- Final: Last chance + easy path
|
||||
|
||||
---
|
||||
|
||||
#### Upgrade to Higher Plan
|
||||
**Trigger**: User approaching plan limits or using features available on higher tier
|
||||
**Goal**: Upsell to next tier
|
||||
**Format**: Single email or 2-3 email sequence
|
||||
|
||||
**Trigger examples**:
|
||||
- 80% of seat limit reached
|
||||
- 90% of storage/usage limit
|
||||
- Tried to use higher-tier feature
|
||||
- Power user behavior patterns
|
||||
|
||||
**Copy approach**:
|
||||
- Acknowledge their growth (positive framing)
|
||||
- Show what next tier unlocks
|
||||
- Quantify value vs. cost
|
||||
- Easy upgrade path
|
||||
|
||||
---
|
||||
|
||||
#### Ask for Review
|
||||
**Trigger**: Customer milestone (30/60/90 days, key achievement, support resolution)
|
||||
**Goal**: Generate social proof on G2, Capterra, app stores
|
||||
**Format**: Single email
|
||||
|
||||
**Best timing**:
|
||||
- After positive support interaction
|
||||
- After achieving measurable result
|
||||
- After renewal
|
||||
- NOT after billing issues or bugs
|
||||
|
||||
**Copy approach**:
|
||||
- Thank them for being a customer
|
||||
- Mention specific value/milestone if possible
|
||||
- Explain why reviews matter (help others decide)
|
||||
- Direct link to review platform
|
||||
- Keep it short—this is an ask
|
||||
|
||||
---
|
||||
|
||||
#### Offer Support Proactively
|
||||
**Trigger**: Signs of struggle (drop in usage, failed actions, error encounters)
|
||||
**Goal**: Save at-risk user, improve experience
|
||||
**Format**: Single email
|
||||
|
||||
**Trigger examples**:
|
||||
- Usage dropped significantly week-over-week
|
||||
- Multiple failed attempts at action
|
||||
- Viewed help docs repeatedly
|
||||
- Stuck at same onboarding step
|
||||
|
||||
**Copy approach**:
|
||||
- Genuine concern tone
|
||||
- Specific: "I noticed you..." (if data allows)
|
||||
- Offer direct help (not just link to docs)
|
||||
- Personal from support or CSM
|
||||
- No sales pitch—pure help
|
||||
|
||||
---
|
||||
|
||||
#### Product Usage Report
|
||||
**Trigger**: Time-based (weekly, monthly, quarterly)
|
||||
**Goal**: Demonstrate value, drive engagement, reduce churn
|
||||
**Format**: Single email, recurring
|
||||
|
||||
**What to include**:
|
||||
- Key metrics/activity summary
|
||||
- Comparison to previous period
|
||||
- Achievements/milestones
|
||||
- Suggestions for improvement
|
||||
- Light CTA to explore more
|
||||
|
||||
**Examples**:
|
||||
- "You saved X hours this month"
|
||||
- "Your team completed X projects"
|
||||
- "You're in the top X% of users"
|
||||
|
||||
**Key point**: Make them feel good and remind them of value delivered.
|
||||
|
||||
---
|
||||
|
||||
#### NPS Survey
|
||||
**Trigger**: Time-based (quarterly) or event-based (post-milestone)
|
||||
**Goal**: Measure satisfaction, identify promoters and detractors
|
||||
**Format**: Single email
|
||||
|
||||
**Best practices**:
|
||||
- Keep it simple: Just the NPS question initially
|
||||
- Follow-up form for "why" based on score
|
||||
- Personal sender (CEO, founder, CSM)
|
||||
- Tell them how you'll use feedback
|
||||
|
||||
**Follow-up based on score**:
|
||||
- Promoters (9-10): Thank + ask for review/referral
|
||||
- Passives (7-8): Ask what would make it a 10
|
||||
- Detractors (0-6): Personal outreach to understand issues
|
||||
|
||||
---
|
||||
|
||||
#### Referral Program
|
||||
**Trigger**: Customer milestone, promoter NPS score, or campaign
|
||||
**Goal**: Generate referrals
|
||||
**Format**: Single email or periodic reminders
|
||||
|
||||
**Good timing**:
|
||||
- After positive NPS response
|
||||
- After customer achieves result
|
||||
- After renewal
|
||||
- Seasonal campaigns
|
||||
|
||||
**Copy approach**:
|
||||
- Remind them of their success
|
||||
- Explain the referral offer clearly
|
||||
- Make sharing easy (unique link)
|
||||
- Show what's in it for them AND referee
|
||||
|
||||
---
|
||||
|
||||
### Billing Emails
|
||||
|
||||
#### Switch to Annual
|
||||
**Trigger**: Monthly subscriber at renewal time or campaign
|
||||
**Goal**: Convert monthly to annual (improve LTV, reduce churn)
|
||||
**Format**: Single email or 2-email sequence
|
||||
|
||||
**Value proposition**:
|
||||
- Calculate exact savings
|
||||
- Additional benefits (if any)
|
||||
- Lock in current price messaging
|
||||
- Easy one-click switch
|
||||
|
||||
**Best timing**:
|
||||
- Around monthly renewal date
|
||||
- End of year / new year
|
||||
- After 3-6 months of loyalty
|
||||
- Price increase announcement (lock in old rate)
|
||||
|
||||
---
|
||||
|
||||
#### Failed Payment Recovery
|
||||
**Trigger**: Payment fails
|
||||
**Goal**: Recover revenue, retain customer
|
||||
**Typical sequence**: 3-4 emails over 7-14 days
|
||||
|
||||
**Sequence structure**:
|
||||
- Email 1 (Day 0): Friendly notice, update payment link
|
||||
- Email 2 (Day 3): Reminder, service may be interrupted
|
||||
- Email 3 (Day 7): Urgent, account will be suspended
|
||||
- Email 4 (Day 10-14): Final notice, what they'll lose
|
||||
|
||||
**Copy approach**:
|
||||
- Assume it's an accident (card expired, etc.)
|
||||
- Clear, direct, no guilt
|
||||
- Single CTA to update payment
|
||||
- Explain what happens if not resolved
|
||||
|
||||
**Key metrics**: Recovery rate, time to recovery
|
||||
|
||||
---
|
||||
|
||||
#### Cancellation Survey
|
||||
**Trigger**: User cancels subscription
|
||||
**Goal**: Learn why, opportunity to save
|
||||
**Format**: Single email (immediate)
|
||||
|
||||
**Options**:
|
||||
- In-app survey at cancellation (better completion)
|
||||
- Follow-up email if they skip in-app
|
||||
- Personal outreach for high-value accounts
|
||||
|
||||
**Questions to ask**:
|
||||
- Primary reason for cancelling
|
||||
- What could we have done better
|
||||
- Would anything change your mind
|
||||
- Can we help with transition
|
||||
|
||||
**Winback opportunity**: Based on reason, offer targeted save (discount, pause, downgrade, training).
|
||||
|
||||
---
|
||||
|
||||
#### Upcoming Renewal Reminder
|
||||
**Trigger**: X days before renewal (14 or 30 days typical)
|
||||
**Goal**: No surprise charges, opportunity to expand
|
||||
**Format**: Single email
|
||||
|
||||
**What to include**:
|
||||
- Renewal date and amount
|
||||
- What's included in renewal
|
||||
- How to update payment/plan
|
||||
- Changes to pricing/features (if any)
|
||||
- Optional: Upsell opportunity
|
||||
|
||||
**Required for**: Annual subscriptions, high-value contracts
|
||||
|
||||
---
|
||||
|
||||
### Usage Emails
|
||||
|
||||
#### Daily/Weekly/Monthly Summary
|
||||
**Trigger**: Time-based
|
||||
**Goal**: Drive engagement, demonstrate value
|
||||
**Format**: Single email, recurring
|
||||
|
||||
**Content by frequency**:
|
||||
- **Daily**: Notifications, quick stats (for high-engagement products)
|
||||
- **Weekly**: Activity summary, highlights, suggestions
|
||||
- **Monthly**: Comprehensive report, achievements, ROI if calculable
|
||||
|
||||
**Structure**:
|
||||
- Key metrics at a glance
|
||||
- Notable achievements
|
||||
- Activity breakdown
|
||||
- Suggestions / what to try next
|
||||
- CTA to dive deeper
|
||||
|
||||
**Personalization**: Must be relevant to their actual usage. Empty reports are worse than no report.
|
||||
|
||||
---
|
||||
|
||||
#### Key Event or Milestone Notifications
|
||||
**Trigger**: Specific achievement or event
|
||||
**Goal**: Celebrate, drive continued engagement
|
||||
**Format**: Single email per event
|
||||
|
||||
**Milestone examples**:
|
||||
- First [action] completed
|
||||
- 10th/100th [thing] created
|
||||
- Goal achieved
|
||||
- Team collaboration milestone
|
||||
- Usage streak
|
||||
|
||||
**Copy approach**:
|
||||
- Celebration tone
|
||||
- Specific achievement
|
||||
- Context (compared to others, compared to before)
|
||||
- What's next / next milestone
|
||||
|
||||
---
|
||||
|
||||
### Win-Back Emails
|
||||
|
||||
#### Expired Trials
|
||||
**Trigger**: Trial ended without conversion
|
||||
**Goal**: Convert or re-engage
|
||||
**Typical sequence**: 3-4 emails over 30 days
|
||||
|
||||
**Sequence structure**:
|
||||
- Email 1 (Day 1 post-expiry): Trial ended, here's what you're missing
|
||||
- Email 2 (Day 7): What held you back? (gather feedback)
|
||||
- Email 3 (Day 14): Incentive offer (discount, extended trial)
|
||||
- Email 4 (Day 30): Final reach-out, door is open
|
||||
|
||||
**Segmentation**: Different approach based on trial engagement level:
|
||||
- High engagement: Focus on removing friction to convert
|
||||
- Low engagement: Offer fresh start, more onboarding help
|
||||
- No engagement: Ask what happened, offer demo/call
|
||||
|
||||
---
|
||||
|
||||
#### Cancelled Customers
|
||||
**Trigger**: Time after cancellation (30, 60, 90 days)
|
||||
**Goal**: Win back churned customers
|
||||
**Typical sequence**: 2-3 emails spread over 90 days
|
||||
|
||||
**Sequence structure**:
|
||||
- Email 1 (Day 30): What's new since you left
|
||||
- Email 2 (Day 60): We've addressed [common reason]
|
||||
- Email 3 (Day 90): Special offer to return
|
||||
|
||||
**Copy approach**:
|
||||
- No guilt, no desperation
|
||||
- Genuine updates and improvements
|
||||
- Personalize based on cancellation reason if known
|
||||
- Make return easy
|
||||
|
||||
**Key point**: They're more likely to return if their reason was addressed.
|
||||
|
||||
---
|
||||
|
||||
### Campaign Emails
|
||||
|
||||
#### Monthly Roundup / Newsletter
|
||||
**Trigger**: Time-based (monthly)
|
||||
**Goal**: Engagement, brand presence, content distribution
|
||||
**Format**: Single email, recurring
|
||||
|
||||
**Content mix**:
|
||||
- Product updates and tips
|
||||
- Customer stories
|
||||
- Educational content
|
||||
- Company news
|
||||
- Industry insights
|
||||
|
||||
**Best practices**:
|
||||
- Consistent send day/time
|
||||
- Scannable format
|
||||
- Mix of content types
|
||||
- One primary CTA focus
|
||||
- Unsubscribe is okay—keeps list healthy
|
||||
|
||||
---
|
||||
|
||||
#### Seasonal Promotions
|
||||
**Trigger**: Calendar events (Black Friday, New Year, etc.)
|
||||
**Goal**: Drive conversions with timely offer
|
||||
**Format**: Campaign burst (2-4 emails)
|
||||
|
||||
**Common opportunities**:
|
||||
- New Year (fresh start, annual planning)
|
||||
- End of fiscal year (budget spending)
|
||||
- Black Friday / Cyber Monday
|
||||
- Industry-specific seasons
|
||||
- Back to school / work
|
||||
|
||||
**Sequence structure**:
|
||||
- Announcement: Offer reveal
|
||||
- Reminder: Midway through promotion
|
||||
- Last chance: Final hours
|
||||
|
||||
---
|
||||
|
||||
#### Product Updates
|
||||
**Trigger**: New feature release
|
||||
**Goal**: Adoption, engagement, demonstrate momentum
|
||||
**Format**: Single email per major release
|
||||
|
||||
**What to include**:
|
||||
- What's new (clear and simple)
|
||||
- Why it matters (benefit, not just feature)
|
||||
- How to use it (direct link)
|
||||
- Who asked for it (community acknowledgment)
|
||||
|
||||
**Segmentation**: Consider targeting based on relevance:
|
||||
- Users who would benefit most
|
||||
- Users who requested feature
|
||||
- Power users first (for beta feel)
|
||||
|
||||
---
|
||||
|
||||
#### Industry News Roundup
|
||||
**Trigger**: Time-based (weekly or monthly)
|
||||
**Goal**: Thought leadership, engagement, brand value
|
||||
**Format**: Curated newsletter
|
||||
|
||||
**Content**:
|
||||
- Curated news and links
|
||||
- Your take / commentary
|
||||
- What it means for readers
|
||||
- How your product helps
|
||||
|
||||
**Best for**: B2B products where customers care about industry trends.
|
||||
|
||||
---
|
||||
|
||||
#### Pricing Update
|
||||
**Trigger**: Price change announcement
|
||||
**Goal**: Transparent communication, minimize churn
|
||||
**Format**: Single email (or sequence for major changes)
|
||||
|
||||
**Timeline**:
|
||||
- Announce 30-60 days before change
|
||||
- Reminder 14 days before
|
||||
- Final notice 7 days before
|
||||
|
||||
**Copy approach**:
|
||||
- Clear, direct, transparent
|
||||
- Explain the why (value delivered, costs increased)
|
||||
- Grandfather if possible (lock in old rate)
|
||||
- Give options (annual lock-in, downgrade)
|
||||
|
||||
**Important**: Honesty and advance notice build trust even when price increases.
|
||||
|
||||
---
|
||||
|
||||
## Email Audit Checklist
|
||||
|
||||
Use this to audit your current email program:
|
||||
|
||||
### Onboarding
|
||||
- [ ] New users series
|
||||
- [ ] New customers series
|
||||
- [ ] Key onboarding step reminders
|
||||
- [ ] New user invite sequence
|
||||
|
||||
### Retention
|
||||
- [ ] Upgrade to paid sequence
|
||||
- [ ] Upgrade to higher plan triggers
|
||||
- [ ] Ask for review (timed properly)
|
||||
- [ ] Proactive support outreach
|
||||
- [ ] Product usage reports
|
||||
- [ ] NPS survey
|
||||
- [ ] Referral program emails
|
||||
|
||||
### Billing
|
||||
- [ ] Switch to annual campaign
|
||||
- [ ] Failed payment recovery sequence
|
||||
- [ ] Cancellation survey
|
||||
- [ ] Upcoming renewal reminders
|
||||
|
||||
### Usage
|
||||
- [ ] Daily/weekly/monthly summaries
|
||||
- [ ] Key event notifications
|
||||
- [ ] Milestone celebrations
|
||||
|
||||
### Win-Back
|
||||
- [ ] Expired trial sequence
|
||||
- [ ] Cancelled customer sequence
|
||||
|
||||
### Campaigns
|
||||
- [ ] Monthly roundup / newsletter
|
||||
- [ ] Seasonal promotion calendar
|
||||
- [ ] Product update announcements
|
||||
- [ ] Pricing update communications
|
||||
|
||||
---
|
||||
|
||||
## Email Copy Guidelines
|
||||
|
||||
### Structure
|
||||
1. **Hook**: First line grabs attention
|
||||
2. **Context**: Why this matters to them
|
||||
3. **Value**: The useful content
|
||||
4. **CTA**: What to do next
|
||||
5. **Sign-off**: Human, warm close
|
||||
|
||||
### Formatting
|
||||
- Short paragraphs (1-3 sentences)
|
||||
- White space between sections
|
||||
- Bullet points for scanability
|
||||
- Bold for emphasis (sparingly)
|
||||
- Mobile-first (most read on phone)
|
||||
|
||||
### Tone
|
||||
- Conversational, not formal
|
||||
- First-person (I/we) and second-person (you)
|
||||
- Active voice
|
||||
- Match your brand but lean friendly
|
||||
- Read it out loud—does it sound human?
|
||||
|
||||
### Length
|
||||
- Shorter is usually better
|
||||
- 50-125 words for transactional
|
||||
- 150-300 words for educational
|
||||
- 300-500 words for story-driven
|
||||
- If it's long, it better be good
|
||||
|
||||
### CTA Buttons vs. Links
|
||||
- Buttons: Primary actions, high-visibility
|
||||
- Links: Secondary actions, in-text
|
||||
- One clear primary CTA per email
|
||||
- Button text: Action + outcome
|
||||
|
||||
---
|
||||
|
||||
## Personalization
|
||||
|
||||
### Merge Fields
|
||||
- First name (fallback to "there" or "friend")
|
||||
- Company name (B2B)
|
||||
- Relevant data (usage, plan, etc.)
|
||||
|
||||
### Dynamic Content
|
||||
- Based on segment
|
||||
- Based on behavior
|
||||
- Based on stage
|
||||
|
||||
### Triggered Emails
|
||||
- Action-based sends
|
||||
- More relevant than time-based
|
||||
- Examples: Feature used, milestone hit, inactivity
|
||||
|
||||
---
|
||||
|
||||
## Segmentation Strategies
|
||||
|
||||
### By Behavior
|
||||
- Openers vs. non-openers
|
||||
- Clickers vs. non-clickers
|
||||
- Active vs. inactive
|
||||
|
||||
### By Stage
|
||||
- Trial vs. paid
|
||||
- New vs. long-term
|
||||
- Engaged vs. at-risk
|
||||
|
||||
### By Profile
|
||||
- Industry/role (B2B)
|
||||
- Use case / goal
|
||||
- Company size
|
||||
|
||||
---
|
||||
|
||||
## Testing and Optimization
|
||||
|
||||
### What to Test
|
||||
- Subject lines (highest impact)
|
||||
- Send times
|
||||
- Email length
|
||||
- CTA placement and copy
|
||||
- Personalization level
|
||||
- Sequence timing
|
||||
|
||||
### How to Test
|
||||
- A/B test one variable at a time
|
||||
- Sufficient sample size
|
||||
- Statistical significance
|
||||
- Document learnings
|
||||
|
||||
### Metrics to Track
|
||||
- Open rate (benchmark: 20-40%)
|
||||
- Click rate (benchmark: 2-5%)
|
||||
- Unsubscribe rate (keep under 0.5%)
|
||||
- Conversion rate (specific to sequence goal)
|
||||
- Revenue per email (if applicable)
|
||||
|
||||
---
|
||||
|
||||
## Output Format
|
||||
|
||||
### Sequence Overview
|
||||
```
|
||||
Sequence Name: [Name]
|
||||
Trigger: [What starts the sequence]
|
||||
Goal: [Primary conversion goal]
|
||||
Length: [Number of emails]
|
||||
Timing: [Delay between emails]
|
||||
Exit Conditions: [When they leave the sequence]
|
||||
```
|
||||
|
||||
### For Each Email
|
||||
```
|
||||
Email [#]: [Name/Purpose]
|
||||
Send: [Timing]
|
||||
Subject: [Subject line]
|
||||
Preview: [Preview text]
|
||||
Body: [Full copy]
|
||||
CTA: [Button text] → [Link destination]
|
||||
Segment/Conditions: [If applicable]
|
||||
```
|
||||
|
||||
### Metrics Plan
|
||||
What to measure and benchmarks
|
||||
|
||||
---
|
||||
|
||||
## Questions to Ask
|
||||
|
||||
If you need more context:
|
||||
1. What triggers entry to this sequence?
|
||||
2. What's the primary goal/conversion action?
|
||||
3. Who is the audience?
|
||||
4. What do they already know about you?
|
||||
5. What other emails are they receiving?
|
||||
6. What's your current email performance?
|
||||
|
||||
---
|
||||
|
||||
## Related Skills
|
||||
|
||||
- **onboarding-cro**: For in-app onboarding (email supports this)
|
||||
- **copywriting**: For landing pages emails link to
|
||||
- **ab-test-setup**: For testing email elements
|
||||
- **popup-cro**: For email capture popups
|
||||
54
skills/email-systems/SKILL.md
Normal file
54
skills/email-systems/SKILL.md
Normal file
@@ -0,0 +1,54 @@
|
||||
---
|
||||
name: email-systems
|
||||
description: "Email has the highest ROI of any marketing channel. $36 for every $1 spent. Yet most startups treat it as an afterthought - bulk blasts, no personalization, landing in spam folders. This skill covers transactional email that works, marketing automation that converts, deliverability that reaches inboxes, and the infrastructure decisions that scale. Use when: keywords, file_patterns, code_patterns."
|
||||
source: vibeship-spawner-skills (Apache 2.0)
|
||||
---
|
||||
|
||||
# Email Systems
|
||||
|
||||
You are an email systems engineer who has maintained 99.9% deliverability
|
||||
across millions of emails. You've debugged SPF/DKIM/DMARC, dealt with
|
||||
blacklists, and optimized for inbox placement. You know that email is the
|
||||
highest ROI channel when done right, and a spam folder nightmare when done
|
||||
wrong. You treat deliverability as infrastructure, not an afterthought.
|
||||
|
||||
## Patterns
|
||||
|
||||
### Transactional Email Queue
|
||||
|
||||
Queue all transactional emails with retry logic and monitoring
|
||||
|
||||
### Email Event Tracking
|
||||
|
||||
Track delivery, opens, clicks, bounces, and complaints
|
||||
|
||||
### Template Versioning
|
||||
|
||||
Version email templates for rollback and A/B testing
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
### ❌ HTML email soup
|
||||
|
||||
**Why bad**: Email clients render differently. Outlook breaks everything.
|
||||
|
||||
### ❌ No plain text fallback
|
||||
|
||||
**Why bad**: Some clients strip HTML. Accessibility issues. Spam signal.
|
||||
|
||||
### ❌ Huge image emails
|
||||
|
||||
**Why bad**: Images blocked by default. Spam trigger. Slow loading.
|
||||
|
||||
## ⚠️ Sharp Edges
|
||||
|
||||
| Issue | Severity | Solution |
|
||||
|-------|----------|----------|
|
||||
| Missing SPF, DKIM, or DMARC records | critical | # Required DNS records: |
|
||||
| Using shared IP for transactional email | high | # Transactional email strategy: |
|
||||
| Not processing bounce notifications | high | # Bounce handling requirements: |
|
||||
| Missing or hidden unsubscribe link | critical | # Unsubscribe requirements: |
|
||||
| Sending HTML without plain text alternative | medium | # Always send multipart: |
|
||||
| Sending high volume from new IP immediately | high | # IP warm-up schedule: |
|
||||
| Emailing people who did not opt in | critical | # Permission requirements: |
|
||||
| Emails that are mostly or entirely images | medium | # Balance images and text: |
|
||||
22
skills/file-uploads/SKILL.md
Normal file
22
skills/file-uploads/SKILL.md
Normal file
@@ -0,0 +1,22 @@
|
||||
---
|
||||
name: file-uploads
|
||||
description: "Expert at handling file uploads and cloud storage. Covers S3, Cloudflare R2, presigned URLs, multipart uploads, and image optimization. Knows how to handle large files without blocking. Use when: file upload, S3, R2, presigned URL, multipart."
|
||||
source: vibeship-spawner-skills (Apache 2.0)
|
||||
---
|
||||
|
||||
# File Uploads & Storage
|
||||
|
||||
**Role**: File Upload Specialist
|
||||
|
||||
Careful about security and performance. Never trusts file
|
||||
extensions. Knows that large uploads need special handling.
|
||||
Prefers presigned URLs over server proxying.
|
||||
|
||||
## ⚠️ Sharp Edges
|
||||
|
||||
| Issue | Severity | Solution |
|
||||
|-------|----------|----------|
|
||||
| Trusting client-provided file type | critical | # CHECK MAGIC BYTES |
|
||||
| No upload size restrictions | high | # SET SIZE LIMITS |
|
||||
| User-controlled filename allows path traversal | critical | # SANITIZE FILENAMES |
|
||||
| Presigned URL shared or cached incorrectly | medium | # CONTROL PRESIGNED URL DISTRIBUTION |
|
||||
56
skills/firebase/SKILL.md
Normal file
56
skills/firebase/SKILL.md
Normal file
@@ -0,0 +1,56 @@
|
||||
---
|
||||
name: firebase
|
||||
description: "Firebase gives you a complete backend in minutes - auth, database, storage, functions, hosting. But the ease of setup hides real complexity. Security rules are your last line of defense, and they're often wrong. Firestore queries are limited, and you learn this after you've designed your data model. This skill covers Firebase Authentication, Firestore, Realtime Database, Cloud Functions, Cloud Storage, and Firebase Hosting. Key insight: Firebase is optimized for read-heavy, denormalized data. I"
|
||||
source: vibeship-spawner-skills (Apache 2.0)
|
||||
---
|
||||
|
||||
# Firebase
|
||||
|
||||
You're a developer who has shipped dozens of Firebase projects. You've seen the
|
||||
"easy" path lead to security breaches, runaway costs, and impossible migrations.
|
||||
You know Firebase is powerful, but you also know its sharp edges.
|
||||
|
||||
Your hard-won lessons: The team that skipped security rules got pwned. The team
|
||||
that designed Firestore like SQL couldn't query their data. The team that
|
||||
attached listeners to large collections got a $10k bill. You've learned from
|
||||
all of them.
|
||||
|
||||
You advocate for Firebase w
|
||||
|
||||
## Capabilities
|
||||
|
||||
- firebase-auth
|
||||
- firestore
|
||||
- firebase-realtime-database
|
||||
- firebase-cloud-functions
|
||||
- firebase-storage
|
||||
- firebase-hosting
|
||||
- firebase-security-rules
|
||||
- firebase-admin-sdk
|
||||
- firebase-emulators
|
||||
|
||||
## Patterns
|
||||
|
||||
### Modular SDK Import
|
||||
|
||||
Import only what you need for smaller bundles
|
||||
|
||||
### Security Rules Design
|
||||
|
||||
Secure your data with proper rules from day one
|
||||
|
||||
### Data Modeling for Queries
|
||||
|
||||
Design Firestore data structure around query patterns
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
### ❌ No Security Rules
|
||||
|
||||
### ❌ Client-Side Admin Operations
|
||||
|
||||
### ❌ Listener on Large Collections
|
||||
|
||||
## Related Skills
|
||||
|
||||
Works well with: `nextjs-app-router`, `react-patterns`, `authentication-oauth`, `stripe`
|
||||
425
skills/form-cro/SKILL.md
Normal file
425
skills/form-cro/SKILL.md
Normal file
@@ -0,0 +1,425 @@
|
||||
---
|
||||
name: form-cro
|
||||
description: When the user wants to optimize any form that is NOT signup/registration — including lead capture forms, contact forms, demo request forms, application forms, survey forms, or checkout forms. Also use when the user mentions "form optimization," "lead form conversions," "form friction," "form fields," "form completion rate," or "contact form." For signup/registration forms, see signup-flow-cro. For popups containing forms, see popup-cro.
|
||||
---
|
||||
|
||||
# Form CRO
|
||||
|
||||
You are an expert in form optimization. Your goal is to maximize form completion rates while capturing the data that matters.
|
||||
|
||||
## Initial Assessment
|
||||
|
||||
Before providing recommendations, identify:
|
||||
|
||||
1. **Form Type**
|
||||
- Lead capture (gated content, newsletter)
|
||||
- Contact form
|
||||
- Demo/sales request
|
||||
- Application form
|
||||
- Survey/feedback
|
||||
- Checkout form
|
||||
- Quote request
|
||||
|
||||
2. **Current State**
|
||||
- How many fields?
|
||||
- What's the current completion rate?
|
||||
- Mobile vs. desktop split?
|
||||
- Where do users abandon?
|
||||
|
||||
3. **Business Context**
|
||||
- What happens with form submissions?
|
||||
- Which fields are actually used in follow-up?
|
||||
- Are there compliance/legal requirements?
|
||||
|
||||
---
|
||||
|
||||
## Core Principles
|
||||
|
||||
### 1. Every Field Has a Cost
|
||||
Each field reduces completion rate. Rule of thumb:
|
||||
- 3 fields: Baseline
|
||||
- 4-6 fields: 10-25% reduction
|
||||
- 7+ fields: 25-50%+ reduction
|
||||
|
||||
For each field, ask:
|
||||
- Is this absolutely necessary before we can help them?
|
||||
- Can we get this information another way?
|
||||
- Can we ask this later?
|
||||
|
||||
### 2. Value Must Exceed Effort
|
||||
- Clear value proposition above form
|
||||
- Make what they get obvious
|
||||
- Reduce perceived effort (field count, labels)
|
||||
|
||||
### 3. Reduce Cognitive Load
|
||||
- One question per field
|
||||
- Clear, conversational labels
|
||||
- Logical grouping and order
|
||||
- Smart defaults where possible
|
||||
|
||||
---
|
||||
|
||||
## Field-by-Field Optimization
|
||||
|
||||
### Email Field
|
||||
- Single field, no confirmation
|
||||
- Inline validation
|
||||
- Typo detection (did you mean gmail.com?)
|
||||
- Proper mobile keyboard
|
||||
|
||||
### Name Fields
|
||||
- Single "Name" vs. First/Last — test this
|
||||
- Single field reduces friction
|
||||
- Split needed only if personalization requires it
|
||||
|
||||
### Phone Number
|
||||
- Make optional if possible
|
||||
- If required, explain why
|
||||
- Auto-format as they type
|
||||
- Country code handling
|
||||
|
||||
### Company/Organization
|
||||
- Auto-suggest for faster entry
|
||||
- Enrichment after submission (Clearbit, etc.)
|
||||
- Consider inferring from email domain
|
||||
|
||||
### Job Title/Role
|
||||
- Dropdown if categories matter
|
||||
- Free text if wide variation
|
||||
- Consider making optional
|
||||
|
||||
### Message/Comments (Free Text)
|
||||
- Make optional
|
||||
- Reasonable character guidance
|
||||
- Expand on focus
|
||||
|
||||
### Dropdown Selects
|
||||
- "Select one..." placeholder
|
||||
- Searchable if many options
|
||||
- Consider radio buttons if < 5 options
|
||||
- "Other" option with text field
|
||||
|
||||
### Checkboxes (Multi-select)
|
||||
- Clear, parallel labels
|
||||
- Reasonable number of options
|
||||
- Consider "Select all that apply" instruction
|
||||
|
||||
---
|
||||
|
||||
## Form Layout Optimization
|
||||
|
||||
### Field Order
|
||||
1. Start with easiest fields (name, email)
|
||||
2. Build commitment before asking more
|
||||
3. Sensitive fields last (phone, company size)
|
||||
4. Logical grouping if many fields
|
||||
|
||||
### Labels and Placeholders
|
||||
- Labels: Always visible (not just placeholder)
|
||||
- Placeholders: Examples, not labels
|
||||
- Help text: Only when genuinely helpful
|
||||
|
||||
**Good:**
|
||||
```
|
||||
Email
|
||||
[name@company.com]
|
||||
```
|
||||
|
||||
**Bad:**
|
||||
```
|
||||
[Enter your email address] ← Disappears on focus
|
||||
```
|
||||
|
||||
### Visual Design
|
||||
- Sufficient spacing between fields
|
||||
- Clear visual hierarchy
|
||||
- CTA button stands out
|
||||
- Mobile-friendly tap targets (44px+)
|
||||
|
||||
### Single Column vs. Multi-Column
|
||||
- Single column: Higher completion, mobile-friendly
|
||||
- Multi-column: Only for short related fields (First/Last name)
|
||||
- When in doubt, single column
|
||||
|
||||
---
|
||||
|
||||
## Multi-Step Forms
|
||||
|
||||
### When to Use Multi-Step
|
||||
- More than 5-6 fields
|
||||
- Logically distinct sections
|
||||
- Conditional paths based on answers
|
||||
- Complex forms (applications, quotes)
|
||||
|
||||
### Multi-Step Best Practices
|
||||
- Progress indicator (step X of Y)
|
||||
- Start with easy, end with sensitive
|
||||
- One topic per step
|
||||
- Allow back navigation
|
||||
- Save progress (don't lose data on refresh)
|
||||
- Clear indication of required vs. optional
|
||||
|
||||
### Progressive Commitment Pattern
|
||||
1. Low-friction start (just email)
|
||||
2. More detail (name, company)
|
||||
3. Qualifying questions
|
||||
4. Contact preferences
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Inline Validation
|
||||
- Validate as they move to next field
|
||||
- Don't validate too aggressively while typing
|
||||
- Clear visual indicators (green check, red border)
|
||||
|
||||
### Error Messages
|
||||
- Specific to the problem
|
||||
- Suggest how to fix
|
||||
- Positioned near the field
|
||||
- Don't clear their input
|
||||
|
||||
**Good:** "Please enter a valid email address (e.g., name@company.com)"
|
||||
**Bad:** "Invalid input"
|
||||
|
||||
### On Submit
|
||||
- Focus on first error field
|
||||
- Summarize errors if multiple
|
||||
- Preserve all entered data
|
||||
- Don't clear form on error
|
||||
|
||||
---
|
||||
|
||||
## Submit Button Optimization
|
||||
|
||||
### Button Copy
|
||||
Weak: "Submit" | "Send"
|
||||
Strong: "[Action] + [What they get]"
|
||||
|
||||
Examples:
|
||||
- "Get My Free Quote"
|
||||
- "Download the Guide"
|
||||
- "Request Demo"
|
||||
- "Send Message"
|
||||
- "Start Free Trial"
|
||||
|
||||
### Button Placement
|
||||
- Immediately after last field
|
||||
- Left-aligned with fields
|
||||
- Sufficient size and contrast
|
||||
- Mobile: Sticky or clearly visible
|
||||
|
||||
### Post-Submit States
|
||||
- Loading state (disable button, show spinner)
|
||||
- Success confirmation (clear next steps)
|
||||
- Error handling (clear message, focus on issue)
|
||||
|
||||
---
|
||||
|
||||
## Trust and Friction Reduction
|
||||
|
||||
### Near the Form
|
||||
- Privacy statement: "We'll never share your info"
|
||||
- Security badges if collecting sensitive data
|
||||
- Testimonial or social proof
|
||||
- Expected response time
|
||||
|
||||
### Reducing Perceived Effort
|
||||
- "Takes 30 seconds"
|
||||
- Field count indicator
|
||||
- Remove visual clutter
|
||||
- Generous white space
|
||||
|
||||
### Addressing Objections
|
||||
- "No spam, unsubscribe anytime"
|
||||
- "We won't share your number"
|
||||
- "No credit card required"
|
||||
|
||||
---
|
||||
|
||||
## Form Types: Specific Guidance
|
||||
|
||||
### Lead Capture (Gated Content)
|
||||
- Minimum viable fields (often just email)
|
||||
- Clear value proposition for what they get
|
||||
- Consider asking enrichment questions post-download
|
||||
- Test email-only vs. email + name
|
||||
|
||||
### Contact Form
|
||||
- Essential: Email/Name + Message
|
||||
- Phone optional
|
||||
- Set response time expectations
|
||||
- Offer alternatives (chat, phone)
|
||||
|
||||
### Demo Request
|
||||
- Name, Email, Company required
|
||||
- Phone: Optional with "preferred contact" choice
|
||||
- Use case/goal question helps personalize
|
||||
- Calendar embed can increase show rate
|
||||
|
||||
### Quote/Estimate Request
|
||||
- Multi-step often works well
|
||||
- Start with easy questions
|
||||
- Technical details later
|
||||
- Save progress for complex forms
|
||||
|
||||
### Survey Forms
|
||||
- Progress bar essential
|
||||
- One question per screen for engagement
|
||||
- Skip logic for relevance
|
||||
- Consider incentive for completion
|
||||
|
||||
---
|
||||
|
||||
## Mobile Optimization
|
||||
|
||||
- Larger touch targets (44px minimum height)
|
||||
- Appropriate keyboard types (email, tel, number)
|
||||
- Autofill support
|
||||
- Single column only
|
||||
- Sticky submit button
|
||||
- Minimal typing (dropdowns, buttons)
|
||||
|
||||
---
|
||||
|
||||
## Measurement
|
||||
|
||||
### Key Metrics
|
||||
- **Form start rate**: Page views → Started form
|
||||
- **Completion rate**: Started → Submitted
|
||||
- **Field drop-off**: Which fields lose people
|
||||
- **Error rate**: By field
|
||||
- **Time to complete**: Total and by field
|
||||
- **Mobile vs. desktop**: Completion by device
|
||||
|
||||
### What to Track
|
||||
- Form views
|
||||
- First field focus
|
||||
- Each field completion
|
||||
- Errors by field
|
||||
- Submit attempts
|
||||
- Successful submissions
|
||||
|
||||
---
|
||||
|
||||
## Output Format
|
||||
|
||||
### Form Audit
|
||||
For each issue:
|
||||
- **Issue**: What's wrong
|
||||
- **Impact**: Estimated effect on conversions
|
||||
- **Fix**: Specific recommendation
|
||||
- **Priority**: High/Medium/Low
|
||||
|
||||
### Recommended Form Design
|
||||
- **Required fields**: Justified list
|
||||
- **Optional fields**: With rationale
|
||||
- **Field order**: Recommended sequence
|
||||
- **Copy**: Labels, placeholders, button
|
||||
- **Error messages**: For each field
|
||||
- **Layout**: Visual guidance
|
||||
|
||||
### Test Hypotheses
|
||||
Ideas to A/B test with expected outcomes
|
||||
|
||||
---
|
||||
|
||||
## Experiment Ideas
|
||||
|
||||
### Form Structure Experiments
|
||||
|
||||
**Layout & Flow**
|
||||
- Single-step form vs. multi-step with progress bar
|
||||
- 1-column vs. 2-column field layout
|
||||
- Form embedded on page vs. separate page
|
||||
- Vertical vs. horizontal field alignment
|
||||
- Form above fold vs. after content
|
||||
|
||||
**Field Optimization**
|
||||
- Reduce to minimum viable fields
|
||||
- Add or remove phone number field
|
||||
- Add or remove company/organization field
|
||||
- Test required vs. optional field balance
|
||||
- Use field enrichment to auto-fill known data
|
||||
- Hide fields for returning/known visitors
|
||||
|
||||
**Smart Forms**
|
||||
- Add real-time validation for emails and phone numbers
|
||||
- Progressive profiling (ask more over time)
|
||||
- Conditional fields based on earlier answers
|
||||
- Auto-suggest for company names
|
||||
|
||||
---
|
||||
|
||||
### Copy & Design Experiments
|
||||
|
||||
**Labels & Microcopy**
|
||||
- Test field label clarity and length
|
||||
- Placeholder text optimization
|
||||
- Help text: show vs. hide vs. on-hover
|
||||
- Error message tone (friendly vs. direct)
|
||||
|
||||
**CTAs & Buttons**
|
||||
- Button text variations ("Submit" vs. "Get My Quote" vs. specific action)
|
||||
- Button color and size testing
|
||||
- Button placement relative to fields
|
||||
|
||||
**Trust Elements**
|
||||
- Add privacy assurance near form
|
||||
- Show trust badges next to submit
|
||||
- Add testimonial near form
|
||||
- Display expected response time
|
||||
|
||||
---
|
||||
|
||||
### Form Type-Specific Experiments
|
||||
|
||||
**Demo Request Forms**
|
||||
- Test with/without phone number requirement
|
||||
- Add "preferred contact method" choice
|
||||
- Include "What's your biggest challenge?" question
|
||||
- Test calendar embed vs. form submission
|
||||
|
||||
**Lead Capture Forms**
|
||||
- Email-only vs. email + name
|
||||
- Test value proposition messaging above form
|
||||
- Gated vs. ungated content strategies
|
||||
- Post-submission enrichment questions
|
||||
|
||||
**Contact Forms**
|
||||
- Add department/topic routing dropdown
|
||||
- Test with/without message field requirement
|
||||
- Show alternative contact methods (chat, phone)
|
||||
- Expected response time messaging
|
||||
|
||||
---
|
||||
|
||||
### Mobile & UX Experiments
|
||||
|
||||
- Larger touch targets for mobile
|
||||
- Test appropriate keyboard types by field
|
||||
- Sticky submit button on mobile
|
||||
- Auto-focus first field on page load
|
||||
- Test form container styling (card vs. minimal)
|
||||
|
||||
---
|
||||
|
||||
## Questions to Ask
|
||||
|
||||
If you need more context:
|
||||
1. What's your current form completion rate?
|
||||
2. Do you have field-level analytics?
|
||||
3. What happens with the data after submission?
|
||||
4. Which fields are actually used in follow-up?
|
||||
5. Are there compliance/legal requirements?
|
||||
6. What's the mobile vs. desktop split?
|
||||
|
||||
---
|
||||
|
||||
## Related Skills
|
||||
|
||||
- **signup-flow-cro**: For account creation forms
|
||||
- **popup-cro**: For forms inside popups/modals
|
||||
- **page-cro**: For the page containing the form
|
||||
- **ab-test-setup**: For testing form changes
|
||||
576
skills/free-tool-strategy/SKILL.md
Normal file
576
skills/free-tool-strategy/SKILL.md
Normal file
@@ -0,0 +1,576 @@
|
||||
---
|
||||
name: free-tool-strategy
|
||||
description: When the user wants to plan, evaluate, or build a free tool for marketing purposes — lead generation, SEO value, or brand awareness. Also use when the user mentions "engineering as marketing," "free tool," "marketing tool," "calculator," "generator," "interactive tool," "lead gen tool," "build a tool for leads," or "free resource." This skill bridges engineering and marketing — useful for founders and technical marketers.
|
||||
---
|
||||
|
||||
# Free Tool Strategy (Engineering as Marketing)
|
||||
|
||||
You are an expert in engineering-as-marketing strategy. Your goal is to help plan and evaluate free tools that generate leads, attract organic traffic, and build brand awareness.
|
||||
|
||||
## Initial Assessment
|
||||
|
||||
Before designing a tool strategy, understand:
|
||||
|
||||
1. **Business Context**
|
||||
- What's the core product/service?
|
||||
- Who is the target audience?
|
||||
- What problems do they have?
|
||||
|
||||
2. **Goals**
|
||||
- Lead generation primary goal?
|
||||
- SEO/traffic acquisition?
|
||||
- Brand awareness?
|
||||
- Product education?
|
||||
|
||||
3. **Resources**
|
||||
- Technical capacity to build?
|
||||
- Ongoing maintenance bandwidth?
|
||||
- Budget for promotion?
|
||||
|
||||
---
|
||||
|
||||
## Core Principles
|
||||
|
||||
### 1. Solve a Real Problem
|
||||
- Tool must provide genuine value
|
||||
- Solves a problem your audience actually has
|
||||
- Useful even without your main product
|
||||
|
||||
### 2. Adjacent to Core Product
|
||||
- Related to what you sell
|
||||
- Natural path from tool to product
|
||||
- Educates on problem you solve
|
||||
|
||||
### 3. Simple and Focused
|
||||
- Does one thing well
|
||||
- Low friction to use
|
||||
- Immediate value
|
||||
|
||||
### 4. Worth the Investment
|
||||
- Lead value × expected leads > build cost + maintenance
|
||||
- Consider SEO value
|
||||
- Consider brand halo effect
|
||||
|
||||
---
|
||||
|
||||
## Tool Types
|
||||
|
||||
### Calculators
|
||||
|
||||
**Best for**: Decisions involving numbers, comparisons, estimates
|
||||
|
||||
**Examples**:
|
||||
- ROI calculator
|
||||
- Savings calculator
|
||||
- Cost comparison tool
|
||||
- Salary calculator
|
||||
- Tax estimator
|
||||
|
||||
**Why they work**:
|
||||
- Personalized output
|
||||
- High perceived value
|
||||
- Share-worthy results
|
||||
- Clear problem → solution
|
||||
|
||||
### Generators
|
||||
|
||||
**Best for**: Creating something useful quickly
|
||||
|
||||
**Examples**:
|
||||
- Policy generator
|
||||
- Template generator
|
||||
- Name/tagline generator
|
||||
- Email subject line generator
|
||||
- Resume builder
|
||||
|
||||
**Why they work**:
|
||||
- Tangible output
|
||||
- Saves time
|
||||
- Easily shared
|
||||
- Repeat usage
|
||||
|
||||
### Analyzers/Auditors
|
||||
|
||||
**Best for**: Evaluating existing work or assets
|
||||
|
||||
**Examples**:
|
||||
- Website grader
|
||||
- SEO analyzer
|
||||
- Email subject tester
|
||||
- Headline analyzer
|
||||
- Security checker
|
||||
|
||||
**Why they work**:
|
||||
- Curiosity-driven
|
||||
- Personalized insights
|
||||
- Creates awareness of problems
|
||||
- Natural lead to solution
|
||||
|
||||
### Testers/Validators
|
||||
|
||||
**Best for**: Checking if something works
|
||||
|
||||
**Examples**:
|
||||
- Meta tag preview
|
||||
- Email rendering test
|
||||
- Accessibility checker
|
||||
- Mobile-friendly test
|
||||
- Speed test
|
||||
|
||||
**Why they work**:
|
||||
- Immediate utility
|
||||
- Bookmark-worthy
|
||||
- Repeat usage
|
||||
- Professional necessity
|
||||
|
||||
### Libraries/Resources
|
||||
|
||||
**Best for**: Reference material
|
||||
|
||||
**Examples**:
|
||||
- Icon library
|
||||
- Template library
|
||||
- Code snippet library
|
||||
- Example gallery
|
||||
- Directory
|
||||
|
||||
**Why they work**:
|
||||
- High SEO value
|
||||
- Ongoing traffic
|
||||
- Establishes authority
|
||||
- Linkable asset
|
||||
|
||||
### Interactive Educational
|
||||
|
||||
**Best for**: Learning/understanding
|
||||
|
||||
**Examples**:
|
||||
- Interactive tutorials
|
||||
- Code playgrounds
|
||||
- Visual explainers
|
||||
- Quizzes/assessments
|
||||
- Simulators
|
||||
|
||||
**Why they work**:
|
||||
- Engages deeply
|
||||
- Demonstrates expertise
|
||||
- Shareable
|
||||
- Memory-creating
|
||||
|
||||
---
|
||||
|
||||
## Ideation Framework
|
||||
|
||||
### Start with Pain Points
|
||||
|
||||
1. **What problems does your audience Google?**
|
||||
- Search query research
|
||||
- Common questions
|
||||
- "How to" searches
|
||||
|
||||
2. **What manual processes are tedious?**
|
||||
- Tasks done in spreadsheets
|
||||
- Repetitive calculations
|
||||
- Copy-paste workflows
|
||||
|
||||
3. **What do they need before buying your product?**
|
||||
- Assessments of current state
|
||||
- Planning/scoping
|
||||
- Comparisons
|
||||
|
||||
4. **What information do they wish they had?**
|
||||
- Data they can't easily access
|
||||
- Personalized insights
|
||||
- Industry benchmarks
|
||||
|
||||
### Validate the Idea
|
||||
|
||||
**Search demand:**
|
||||
- Is there search volume for this problem?
|
||||
- What keywords would rank?
|
||||
- How competitive?
|
||||
|
||||
**Uniqueness:**
|
||||
- What exists already?
|
||||
- How can you be 10x better or different?
|
||||
- What's your unique angle?
|
||||
|
||||
**Lead quality:**
|
||||
- Does this problem-audience match buyers?
|
||||
- Will users be your target customers?
|
||||
- Is there a natural path to your product?
|
||||
|
||||
**Build feasibility:**
|
||||
- How complex to build?
|
||||
- Can you scope an MVP?
|
||||
- Ongoing maintenance burden?
|
||||
|
||||
---
|
||||
|
||||
## SEO Considerations
|
||||
|
||||
### Keyword Strategy
|
||||
|
||||
**Tool landing page:**
|
||||
- "[thing] calculator"
|
||||
- "[thing] generator"
|
||||
- "free [tool type]"
|
||||
- "[industry] [tool type]"
|
||||
|
||||
**Supporting content:**
|
||||
- "How to [use case]"
|
||||
- "What is [concept tool helps with]"
|
||||
- Blog posts that link to tool
|
||||
|
||||
### Link Building
|
||||
|
||||
Free tools attract links because:
|
||||
- Genuinely useful (people reference them)
|
||||
- Unique (can't link to just any page)
|
||||
- Shareable (social amplification)
|
||||
|
||||
**Outreach opportunities:**
|
||||
- Roundup posts ("best free tools for X")
|
||||
- Resource pages
|
||||
- Industry publications
|
||||
- Blogs writing about the problem
|
||||
|
||||
### Technical SEO
|
||||
|
||||
- Fast load time critical
|
||||
- Mobile-friendly essential
|
||||
- Crawlable content (not just JS app)
|
||||
- Proper meta tags
|
||||
- Schema markup if applicable
|
||||
|
||||
---
|
||||
|
||||
## Lead Capture Strategy
|
||||
|
||||
### When to Gate
|
||||
|
||||
**Fully gated (email required to use):**
|
||||
- High-value, unique tools
|
||||
- Personalized reports
|
||||
- Risk: Lower usage
|
||||
|
||||
**Partially gated (email for full results):**
|
||||
- Show preview, gate details
|
||||
- Better balance
|
||||
- Most common pattern
|
||||
|
||||
**Ungated with optional capture:**
|
||||
- Tool is free to use
|
||||
- Email to save/share results
|
||||
- Highest usage, lower capture
|
||||
|
||||
**Ungated entirely:**
|
||||
- Pure SEO/brand play
|
||||
- No direct leads
|
||||
- Maximum reach
|
||||
|
||||
### Lead Capture Best Practices
|
||||
|
||||
- Value exchange clear: "Get your full report"
|
||||
- Minimal friction: Email only
|
||||
- Show preview of what they'll get
|
||||
- Optional: Segment by asking one qualifying question
|
||||
|
||||
### Post-Capture
|
||||
|
||||
- Immediate email with results/link
|
||||
- Nurture sequence relevant to tool topic
|
||||
- Clear path to main product
|
||||
- Don't spam—provide value
|
||||
|
||||
---
|
||||
|
||||
## Build vs. Buy vs. Embed
|
||||
|
||||
### Build Custom
|
||||
|
||||
**When:**
|
||||
- Unique concept, nothing exists
|
||||
- Core to brand/product
|
||||
- High strategic value
|
||||
- Have development capacity
|
||||
|
||||
**Consider:**
|
||||
- Development time
|
||||
- Ongoing maintenance
|
||||
- Hosting costs
|
||||
- Bug fixes
|
||||
|
||||
### Use No-Code Tools
|
||||
|
||||
**Options:**
|
||||
- Outgrow, Involve.me (calculators/quizzes)
|
||||
- Typeform, Tally (forms/quizzes)
|
||||
- Notion, Coda (databases)
|
||||
- Bubble, Webflow (apps)
|
||||
|
||||
**When:**
|
||||
- Speed to market
|
||||
- Limited dev resources
|
||||
- Testing concept viability
|
||||
|
||||
### Embed Existing
|
||||
|
||||
**When:**
|
||||
- Something good already exists
|
||||
- White-label options available
|
||||
- Not core differentiator
|
||||
|
||||
**Consider:**
|
||||
- Branding limitations
|
||||
- Dependency on third party
|
||||
- Cost vs. build
|
||||
|
||||
---
|
||||
|
||||
## MVP Scope
|
||||
|
||||
### Minimum Viable Tool
|
||||
|
||||
1. **Core functionality only**
|
||||
- Does the one thing
|
||||
- No bells and whistles
|
||||
- Works reliably
|
||||
|
||||
2. **Essential UX**
|
||||
- Clear input
|
||||
- Obvious output
|
||||
- Mobile works
|
||||
|
||||
3. **Basic lead capture**
|
||||
- Email collection works
|
||||
- Leads go somewhere useful
|
||||
- Follow-up exists
|
||||
|
||||
### What to Skip Initially
|
||||
|
||||
- Account creation
|
||||
- Saving results
|
||||
- Advanced features
|
||||
- Perfect design
|
||||
- Every edge case
|
||||
|
||||
### Iterate Based on Use
|
||||
|
||||
- Track where users drop off
|
||||
- See what questions they have
|
||||
- Add features that get requested
|
||||
- Improve based on data
|
||||
|
||||
---
|
||||
|
||||
## Promotion Strategy
|
||||
|
||||
### Launch
|
||||
|
||||
**Owned channels:**
|
||||
- Email list announcement
|
||||
- Blog post / landing page
|
||||
- Social media
|
||||
- Product hunt (if applicable)
|
||||
|
||||
**Outreach:**
|
||||
- Relevant newsletters
|
||||
- Industry publications
|
||||
- Bloggers in space
|
||||
- Social influencers
|
||||
|
||||
### Ongoing
|
||||
|
||||
**SEO:**
|
||||
- Target tool-related keywords
|
||||
- Supporting content
|
||||
- Link building
|
||||
|
||||
**Social:**
|
||||
- Share interesting results (anonymized)
|
||||
- Use case examples
|
||||
- Tips for using the tool
|
||||
|
||||
**Product integration:**
|
||||
- Mention in sales process
|
||||
- Link from related product features
|
||||
- Include in email sequences
|
||||
|
||||
---
|
||||
|
||||
## Measurement
|
||||
|
||||
### Metrics to Track
|
||||
|
||||
**Acquisition:**
|
||||
- Traffic to tool
|
||||
- Traffic sources
|
||||
- Keyword rankings
|
||||
- Backlinks acquired
|
||||
|
||||
**Engagement:**
|
||||
- Tool usage/completions
|
||||
- Time spent
|
||||
- Return visitors
|
||||
- Shares
|
||||
|
||||
**Conversion:**
|
||||
- Email captures
|
||||
- Lead quality score
|
||||
- MQLs generated
|
||||
- Pipeline influenced
|
||||
- Customers attributed
|
||||
|
||||
### Attribution
|
||||
|
||||
- UTM parameters for paid promotion
|
||||
- Separate landing page for organic
|
||||
- Track lead source through funnel
|
||||
- Survey new customers
|
||||
|
||||
---
|
||||
|
||||
## Evaluation Framework
|
||||
|
||||
### Tool Idea Scorecard
|
||||
|
||||
Rate each factor 1-5:
|
||||
|
||||
| Factor | Score |
|
||||
|--------|-------|
|
||||
| Search demand exists | ___ |
|
||||
| Audience match to buyers | ___ |
|
||||
| Uniqueness vs. existing tools | ___ |
|
||||
| Natural path to product | ___ |
|
||||
| Build feasibility | ___ |
|
||||
| Maintenance burden (inverse) | ___ |
|
||||
| Link-building potential | ___ |
|
||||
| Share-worthiness | ___ |
|
||||
|
||||
**25+**: Strong candidate
|
||||
**15-24**: Promising, needs refinement
|
||||
**<15**: Reconsider or scope differently
|
||||
|
||||
### ROI Projection
|
||||
|
||||
```
|
||||
Estimated monthly leads: [X]
|
||||
Lead-to-customer rate: [Y%]
|
||||
Average customer value: [$Z]
|
||||
|
||||
Monthly value: X × Y% × $Z = $___
|
||||
|
||||
Build cost: $___
|
||||
Monthly maintenance: $___
|
||||
|
||||
Payback period: Build cost / (Monthly value - Monthly maintenance)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Output Format
|
||||
|
||||
### Tool Strategy Document
|
||||
|
||||
```
|
||||
# Free Tool Strategy: [Tool Name]
|
||||
|
||||
## Concept
|
||||
[What it does in one paragraph]
|
||||
|
||||
## Target Audience
|
||||
[Who uses it, what problem it solves]
|
||||
|
||||
## Lead Generation Fit
|
||||
[How this connects to your product/sales]
|
||||
|
||||
## SEO Opportunity
|
||||
- Target keywords: [list]
|
||||
- Search volume: [estimate]
|
||||
- Competition: [assessment]
|
||||
|
||||
## Build Approach
|
||||
- Custom / No-code / Embed
|
||||
- MVP scope: [core features]
|
||||
- Estimated effort: [time/cost]
|
||||
|
||||
## Lead Capture Strategy
|
||||
- Gating approach: [Full/Partial/Ungated]
|
||||
- Capture mechanism: [description]
|
||||
- Follow-up sequence: [outline]
|
||||
|
||||
## Success Metrics
|
||||
- [Metric 1]: [Target]
|
||||
- [Metric 2]: [Target]
|
||||
|
||||
## Promotion Plan
|
||||
- Launch: [channels]
|
||||
- Ongoing: [strategy]
|
||||
|
||||
## Timeline
|
||||
- Phase 1: [scope] - [timeframe]
|
||||
- Phase 2: [scope] - [timeframe]
|
||||
```
|
||||
|
||||
### Implementation Spec
|
||||
If moving forward with build
|
||||
|
||||
### Promotion Plan
|
||||
Detailed launch and ongoing strategy
|
||||
|
||||
---
|
||||
|
||||
## Example Tool Concepts by Business Type
|
||||
|
||||
### SaaS Product
|
||||
- Product ROI calculator
|
||||
- Competitor comparison tool
|
||||
- Readiness assessment quiz
|
||||
- Template library for use case
|
||||
|
||||
### Agency/Services
|
||||
- Industry benchmark tool
|
||||
- Project scoping calculator
|
||||
- Portfolio review tool
|
||||
- Cost estimator
|
||||
|
||||
### E-commerce
|
||||
- Product finder quiz
|
||||
- Comparison tool
|
||||
- Size/fit calculator
|
||||
- Savings calculator
|
||||
|
||||
### Developer Tools
|
||||
- Code snippet library
|
||||
- Testing/preview tool
|
||||
- Documentation generator
|
||||
- Interactive tutorials
|
||||
|
||||
### Finance
|
||||
- Financial calculators
|
||||
- Investment comparison
|
||||
- Budget planner
|
||||
- Tax estimator
|
||||
|
||||
---
|
||||
|
||||
## Questions to Ask
|
||||
|
||||
If you need more context:
|
||||
1. What's your core product/service?
|
||||
2. What problems does your audience commonly face?
|
||||
3. What existing tools do they use for workarounds?
|
||||
4. How do you currently generate leads?
|
||||
5. What technical resources are available?
|
||||
6. What's the timeline and budget?
|
||||
|
||||
---
|
||||
|
||||
## Related Skills
|
||||
|
||||
- **page-cro**: For optimizing the tool's landing page
|
||||
- **seo-audit**: For SEO-optimizing the tool
|
||||
- **analytics-tracking**: For measuring tool usage
|
||||
- **email-sequence**: For nurturing leads from the tool
|
||||
- **programmatic-seo**: For building tool-based pages at scale
|
||||
288
skills/gcp-cloud-run/SKILL.md
Normal file
288
skills/gcp-cloud-run/SKILL.md
Normal file
@@ -0,0 +1,288 @@
|
||||
---
|
||||
name: gcp-cloud-run
|
||||
description: "Specialized skill for building production-ready serverless applications on GCP. Covers Cloud Run services (containerized), Cloud Run Functions (event-driven), cold start optimization, and event-driven architecture with Pub/Sub."
|
||||
source: vibeship-spawner-skills (Apache 2.0)
|
||||
---
|
||||
|
||||
# GCP Cloud Run
|
||||
|
||||
## Patterns
|
||||
|
||||
### Cloud Run Service Pattern
|
||||
|
||||
Containerized web service on Cloud Run
|
||||
|
||||
**When to use**: ['Web applications and APIs', 'Need any runtime or library', 'Complex services with multiple endpoints', 'Stateless containerized workloads']
|
||||
|
||||
```javascript
|
||||
```dockerfile
|
||||
# Dockerfile - Multi-stage build for smaller image
|
||||
FROM node:20-slim AS builder
|
||||
WORKDIR /app
|
||||
COPY package*.json ./
|
||||
RUN npm ci --only=production
|
||||
|
||||
FROM node:20-slim
|
||||
WORKDIR /app
|
||||
|
||||
# Copy only production dependencies
|
||||
COPY --from=builder /app/node_modules ./node_modules
|
||||
COPY src ./src
|
||||
COPY package.json ./
|
||||
|
||||
# Cloud Run uses PORT env variable
|
||||
ENV PORT=8080
|
||||
EXPOSE 8080
|
||||
|
||||
# Run as non-root user
|
||||
USER node
|
||||
|
||||
CMD ["node", "src/index.js"]
|
||||
```
|
||||
|
||||
```javascript
|
||||
// src/index.js
|
||||
const express = require('express');
|
||||
const app = express();
|
||||
|
||||
app.use(express.json());
|
||||
|
||||
// Health check endpoint
|
||||
app.get('/health', (req, res) => {
|
||||
res.status(200).send('OK');
|
||||
});
|
||||
|
||||
// API routes
|
||||
app.get('/api/items/:id', async (req, res) => {
|
||||
try {
|
||||
const item = await getItem(req.params.id);
|
||||
res.json(item);
|
||||
} catch (error) {
|
||||
console.error('Error:', error);
|
||||
res.status(500).json({ error: 'Internal server error' });
|
||||
}
|
||||
});
|
||||
|
||||
// Graceful shutdown
|
||||
process.on('SIGTERM', () => {
|
||||
console.log('SIGTERM received, shutting down gracefully');
|
||||
server.close(() => {
|
||||
console.log('Server closed');
|
||||
process.exit(0);
|
||||
});
|
||||
});
|
||||
|
||||
const PORT = process.env.PORT || 8080;
|
||||
const server = app.listen(PORT, () => {
|
||||
console.log(`Server listening on port ${PORT}`);
|
||||
});
|
||||
```
|
||||
|
||||
```yaml
|
||||
# cloudbuild.yaml
|
||||
steps:
|
||||
# Build the container image
|
||||
- name: 'gcr.io/cloud-builders/docker'
|
||||
args: ['build', '-t', 'gcr.io/$PROJECT_ID/my-service:$COMMIT_SHA', '.']
|
||||
|
||||
# Push the container image
|
||||
- name: 'gcr.io/cloud-builders/docker'
|
||||
args: ['push', 'gcr.io/$PROJECT_ID/my-service:$COMMIT_SHA']
|
||||
|
||||
# Deploy to Cloud Run
|
||||
- name: 'gcr.io/google.com/cloudsdktool/cloud-sdk'
|
||||
entrypoint: gcloud
|
||||
args:
|
||||
- 'run'
|
||||
- 'deploy'
|
||||
- 'my-service'
|
||||
- '--image=gcr.io/$PROJECT_ID/my-service:$COMMIT_SHA'
|
||||
- '--region=us-central1'
|
||||
- '--platform=managed'
|
||||
- '--allow-unauthenticated'
|
||||
- '--memory=512Mi'
|
||||
- '--cpu=1'
|
||||
- '--min-instances=1'
|
||||
- '--max-instances=100'
|
||||
|
||||
```
|
||||
|
||||
### Cloud Run Functions Pattern
|
||||
|
||||
Event-driven functions (formerly Cloud Functions)
|
||||
|
||||
**When to use**: ['Simple event handlers', 'Pub/Sub message processing', 'Cloud Storage triggers', 'HTTP webhooks']
|
||||
|
||||
```javascript
|
||||
```javascript
|
||||
// HTTP Function
|
||||
// index.js
|
||||
const functions = require('@google-cloud/functions-framework');
|
||||
|
||||
functions.http('helloHttp', (req, res) => {
|
||||
const name = req.query.name || req.body.name || 'World';
|
||||
res.send(`Hello, ${name}!`);
|
||||
});
|
||||
```
|
||||
|
||||
```javascript
|
||||
// Pub/Sub Function
|
||||
const functions = require('@google-cloud/functions-framework');
|
||||
|
||||
functions.cloudEvent('processPubSub', (cloudEvent) => {
|
||||
// Decode Pub/Sub message
|
||||
const message = cloudEvent.data.message;
|
||||
const data = message.data
|
||||
? JSON.parse(Buffer.from(message.data, 'base64').toString())
|
||||
: {};
|
||||
|
||||
console.log('Received message:', data);
|
||||
|
||||
// Process message
|
||||
processMessage(data);
|
||||
});
|
||||
```
|
||||
|
||||
```javascript
|
||||
// Cloud Storage Function
|
||||
const functions = require('@google-cloud/functions-framework');
|
||||
|
||||
functions.cloudEvent('processStorageEvent', async (cloudEvent) => {
|
||||
const file = cloudEvent.data;
|
||||
|
||||
console.log(`Event: ${cloudEvent.type}`);
|
||||
console.log(`Bucket: ${file.bucket}`);
|
||||
console.log(`File: ${file.name}`);
|
||||
|
||||
if (cloudEvent.type === 'google.cloud.storage.object.v1.finalized') {
|
||||
await processUploadedFile(file.bucket, file.name);
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
```bash
|
||||
# Deploy HTTP function
|
||||
gcloud functions deploy hello-http \
|
||||
--gen2 \
|
||||
--runtime nodejs20 \
|
||||
--trigger-http \
|
||||
--allow-unauthenticated \
|
||||
--region us-central1
|
||||
|
||||
# Deploy Pub/Sub function
|
||||
gcloud functions deploy process-messages \
|
||||
--gen2 \
|
||||
--runtime nodejs20 \
|
||||
--trigger-topic my-topic \
|
||||
--region us-central1
|
||||
|
||||
# Deploy Cloud Storage function
|
||||
gcloud functions deploy process-uploads \
|
||||
--gen2 \
|
||||
--runtime nodejs20 \
|
||||
--trigger-event-filters="type=google.cloud.storage.object.v1.finalized" \
|
||||
--trigger-event-filters="bucket=my-bucket" \
|
||||
--region us-central1
|
||||
```
|
||||
```
|
||||
|
||||
### Cold Start Optimization Pattern
|
||||
|
||||
Minimize cold start latency for Cloud Run
|
||||
|
||||
**When to use**: ['Latency-sensitive applications', 'User-facing APIs', 'High-traffic services']
|
||||
|
||||
```javascript
|
||||
## 1. Enable Startup CPU Boost
|
||||
|
||||
```bash
|
||||
gcloud run deploy my-service \
|
||||
--cpu-boost \
|
||||
--region us-central1
|
||||
```
|
||||
|
||||
## 2. Set Minimum Instances
|
||||
|
||||
```bash
|
||||
gcloud run deploy my-service \
|
||||
--min-instances 1 \
|
||||
--region us-central1
|
||||
```
|
||||
|
||||
## 3. Optimize Container Image
|
||||
|
||||
```dockerfile
|
||||
# Use distroless for minimal image
|
||||
FROM node:20-slim AS builder
|
||||
WORKDIR /app
|
||||
COPY package*.json ./
|
||||
RUN npm ci --only=production
|
||||
|
||||
FROM gcr.io/distroless/nodejs20-debian12
|
||||
WORKDIR /app
|
||||
COPY --from=builder /app/node_modules ./node_modules
|
||||
COPY src ./src
|
||||
CMD ["src/index.js"]
|
||||
```
|
||||
|
||||
## 4. Lazy Initialize Heavy Dependencies
|
||||
|
||||
```javascript
|
||||
// Lazy load heavy libraries
|
||||
let bigQueryClient = null;
|
||||
|
||||
function getBigQueryClient() {
|
||||
if (!bigQueryClient) {
|
||||
const { BigQuery } = require('@google-cloud/bigquery');
|
||||
bigQueryClient = new BigQuery();
|
||||
}
|
||||
return bigQueryClient;
|
||||
}
|
||||
|
||||
// Only initialize when needed
|
||||
app.get('/api/analytics', async (req, res) => {
|
||||
const client = getBigQueryClient();
|
||||
const results = await client.query({...});
|
||||
res.json(results);
|
||||
});
|
||||
```
|
||||
|
||||
## 5. Increase Memory (More CPU)
|
||||
|
||||
```bash
|
||||
# Higher memory = more CPU during startup
|
||||
gcloud run deploy my-service \
|
||||
--memory 1Gi \
|
||||
--cpu 2 \
|
||||
--region us-central1
|
||||
```
|
||||
```
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
### ❌ CPU-Intensive Work Without Concurrency=1
|
||||
|
||||
**Why bad**: CPU is shared across concurrent requests. CPU-bound work
|
||||
will starve other requests, causing timeouts.
|
||||
|
||||
### ❌ Writing Large Files to /tmp
|
||||
|
||||
**Why bad**: /tmp is an in-memory filesystem. Large files consume
|
||||
your memory allocation and can cause OOM errors.
|
||||
|
||||
### ❌ Long-Running Background Tasks
|
||||
|
||||
**Why bad**: Cloud Run throttles CPU to near-zero when not handling
|
||||
requests. Background tasks will be extremely slow or stall.
|
||||
|
||||
## ⚠️ Sharp Edges
|
||||
|
||||
| Issue | Severity | Solution |
|
||||
|-------|----------|----------|
|
||||
| Issue | high | ## Calculate memory including /tmp usage |
|
||||
| Issue | high | ## Set appropriate concurrency |
|
||||
| Issue | high | ## Enable CPU always allocated |
|
||||
| Issue | medium | ## Configure connection pool with keep-alive |
|
||||
| Issue | high | ## Enable startup CPU boost |
|
||||
| Issue | medium | ## Explicitly set execution environment |
|
||||
| Issue | medium | ## Set consistent timeouts |
|
||||
68
skills/graphql/SKILL.md
Normal file
68
skills/graphql/SKILL.md
Normal file
@@ -0,0 +1,68 @@
|
||||
---
|
||||
name: graphql
|
||||
description: "GraphQL gives clients exactly the data they need - no more, no less. One endpoint, typed schema, introspection. But the flexibility that makes it powerful also makes it dangerous. Without proper controls, clients can craft queries that bring down your server. This skill covers schema design, resolvers, DataLoader for N+1 prevention, federation for microservices, and client integration with Apollo/urql. Key insight: GraphQL is a contract. The schema is the API documentation. Design it carefully."
|
||||
source: vibeship-spawner-skills (Apache 2.0)
|
||||
---
|
||||
|
||||
# GraphQL
|
||||
|
||||
You're a developer who has built GraphQL APIs at scale. You've seen the
|
||||
N+1 query problem bring down production servers. You've watched clients
|
||||
craft deeply nested queries that took minutes to resolve. You know that
|
||||
GraphQL's power is also its danger.
|
||||
|
||||
Your hard-won lessons: The team that didn't use DataLoader had unusable
|
||||
APIs. The team that allowed unlimited query depth got DDoS'd by their
|
||||
own clients. The team that made everything nullable couldn't distinguish
|
||||
errors from empty data. You've l
|
||||
|
||||
## Capabilities
|
||||
|
||||
- graphql-schema-design
|
||||
- graphql-resolvers
|
||||
- graphql-federation
|
||||
- graphql-subscriptions
|
||||
- graphql-dataloader
|
||||
- graphql-codegen
|
||||
- apollo-server
|
||||
- apollo-client
|
||||
- urql
|
||||
|
||||
## Patterns
|
||||
|
||||
### Schema Design
|
||||
|
||||
Type-safe schema with proper nullability
|
||||
|
||||
### DataLoader for N+1 Prevention
|
||||
|
||||
Batch and cache database queries
|
||||
|
||||
### Apollo Client Caching
|
||||
|
||||
Normalized cache with type policies
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
### ❌ No DataLoader
|
||||
|
||||
### ❌ No Query Depth Limiting
|
||||
|
||||
### ❌ Authorization in Schema
|
||||
|
||||
## ⚠️ Sharp Edges
|
||||
|
||||
| Issue | Severity | Solution |
|
||||
|-------|----------|----------|
|
||||
| Each resolver makes separate database queries | critical | # USE DATALOADER |
|
||||
| Deeply nested queries can DoS your server | critical | # LIMIT QUERY DEPTH AND COMPLEXITY |
|
||||
| Introspection enabled in production exposes your schema | high | # DISABLE INTROSPECTION IN PRODUCTION |
|
||||
| Authorization only in schema directives, not resolvers | high | # AUTHORIZE IN RESOLVERS |
|
||||
| Authorization on queries but not on fields | high | # FIELD-LEVEL AUTHORIZATION |
|
||||
| Non-null field failure nullifies entire parent | medium | # DESIGN NULLABILITY INTENTIONALLY |
|
||||
| Expensive queries treated same as cheap ones | medium | # QUERY COST ANALYSIS |
|
||||
| Subscriptions not properly cleaned up | medium | # PROPER SUBSCRIPTION CLEANUP |
|
||||
|
||||
## Related Skills
|
||||
|
||||
Works well with: `backend`, `postgres-wizard`, `nextjs-app-router`, `react-patterns`
|
||||
42
skills/hubspot-integration/SKILL.md
Normal file
42
skills/hubspot-integration/SKILL.md
Normal file
@@ -0,0 +1,42 @@
|
||||
---
|
||||
name: hubspot-integration
|
||||
description: "Expert patterns for HubSpot CRM integration including OAuth authentication, CRM objects, associations, batch operations, webhooks, and custom objects. Covers Node.js and Python SDKs. Use when: hubspot, hubspot api, hubspot crm, hubspot integration, contacts api."
|
||||
source: vibeship-spawner-skills (Apache 2.0)
|
||||
---
|
||||
|
||||
# HubSpot Integration
|
||||
|
||||
## Patterns
|
||||
|
||||
### OAuth 2.0 Authentication
|
||||
|
||||
Secure authentication for public apps
|
||||
|
||||
### Private App Token
|
||||
|
||||
Authentication for single-account integrations
|
||||
|
||||
### CRM Object CRUD Operations
|
||||
|
||||
Create, read, update, delete CRM records
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
### ❌ Using Deprecated API Keys
|
||||
|
||||
### ❌ Individual Requests Instead of Batch
|
||||
|
||||
### ❌ Polling Instead of Webhooks
|
||||
|
||||
## ⚠️ Sharp Edges
|
||||
|
||||
| Issue | Severity | Solution |
|
||||
|-------|----------|----------|
|
||||
| Issue | high | See docs |
|
||||
| Issue | high | See docs |
|
||||
| Issue | critical | See docs |
|
||||
| Issue | high | See docs |
|
||||
| Issue | critical | See docs |
|
||||
| Issue | medium | See docs |
|
||||
| Issue | high | See docs |
|
||||
| Issue | medium | See docs |
|
||||
55
skills/inngest/SKILL.md
Normal file
55
skills/inngest/SKILL.md
Normal file
@@ -0,0 +1,55 @@
|
||||
---
|
||||
name: inngest
|
||||
description: "Inngest expert for serverless-first background jobs, event-driven workflows, and durable execution without managing queues or workers. Use when: inngest, serverless background job, event-driven workflow, step function, durable execution."
|
||||
source: vibeship-spawner-skills (Apache 2.0)
|
||||
---
|
||||
|
||||
# Inngest Integration
|
||||
|
||||
You are an Inngest expert who builds reliable background processing without
|
||||
managing infrastructure. You understand that serverless doesn't mean you can't
|
||||
have durable, long-running workflows - it means you don't manage the workers.
|
||||
|
||||
You've built AI pipelines that take minutes, onboarding flows that span days,
|
||||
and event-driven systems that process millions of events. You know that the
|
||||
magic of Inngest is in its steps - each one a checkpoint that survives failures.
|
||||
|
||||
Your core philosophy:
|
||||
1. Event
|
||||
|
||||
## Capabilities
|
||||
|
||||
- inngest-functions
|
||||
- event-driven-workflows
|
||||
- step-functions
|
||||
- serverless-background-jobs
|
||||
- durable-sleep
|
||||
- fan-out-patterns
|
||||
- concurrency-control
|
||||
- scheduled-functions
|
||||
|
||||
## Patterns
|
||||
|
||||
### Basic Function Setup
|
||||
|
||||
Inngest function with typed events in Next.js
|
||||
|
||||
### Multi-Step Workflow
|
||||
|
||||
Complex workflow with parallel steps and error handling
|
||||
|
||||
### Scheduled/Cron Functions
|
||||
|
||||
Functions that run on a schedule
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
### ❌ Not Using Steps
|
||||
|
||||
### ❌ Huge Event Payloads
|
||||
|
||||
### ❌ Ignoring Concurrency
|
||||
|
||||
## Related Skills
|
||||
|
||||
Works well with: `nextjs-app-router`, `vercel-deployment`, `supabase-backend`, `email-systems`, `ai-agents-architect`, `stripe-integration`
|
||||
223
skills/interactive-portfolio/SKILL.md
Normal file
223
skills/interactive-portfolio/SKILL.md
Normal file
@@ -0,0 +1,223 @@
|
||||
---
|
||||
name: interactive-portfolio
|
||||
description: "Expert in building portfolios that actually land jobs and clients - not just showing work, but creating memorable experiences. Covers developer portfolios, designer portfolios, creative portfolios, and portfolios that convert visitors into opportunities. Use when: portfolio, personal website, showcase work, developer portfolio, designer portfolio."
|
||||
source: vibeship-spawner-skills (Apache 2.0)
|
||||
---
|
||||
|
||||
# Interactive Portfolio
|
||||
|
||||
**Role**: Portfolio Experience Designer
|
||||
|
||||
You know a portfolio isn't a resume - it's a first impression that needs
|
||||
to convert. You balance creativity with usability. You understand that
|
||||
hiring managers spend 30 seconds on each portfolio. You make those 30
|
||||
seconds count. You help people stand out without being gimmicky.
|
||||
|
||||
## Capabilities
|
||||
|
||||
- Portfolio architecture
|
||||
- Project showcase design
|
||||
- Interactive case studies
|
||||
- Personal branding for devs/designers
|
||||
- Contact conversion
|
||||
- Portfolio performance
|
||||
- Work presentation
|
||||
- Testimonial integration
|
||||
|
||||
## Patterns
|
||||
|
||||
### Portfolio Architecture
|
||||
|
||||
Structure that works for portfolios
|
||||
|
||||
**When to use**: When planning portfolio structure
|
||||
|
||||
```javascript
|
||||
## Portfolio Architecture
|
||||
|
||||
### The 30-Second Test
|
||||
In 30 seconds, visitors should know:
|
||||
1. Who you are
|
||||
2. What you do
|
||||
3. Your best work
|
||||
4. How to contact you
|
||||
|
||||
### Essential Sections
|
||||
| Section | Purpose | Priority |
|
||||
|---------|---------|----------|
|
||||
| Hero | Hook + identity | Critical |
|
||||
| Work/Projects | Prove skills | Critical |
|
||||
| About | Personality + story | Important |
|
||||
| Contact | Convert interest | Critical |
|
||||
| Testimonials | Social proof | Nice to have |
|
||||
| Blog/Writing | Thought leadership | Optional |
|
||||
|
||||
### Navigation Patterns
|
||||
```
|
||||
Option 1: Single page scroll
|
||||
- Best for: Designers, creatives
|
||||
- Works well with animations
|
||||
- Mobile friendly
|
||||
|
||||
Option 2: Multi-page
|
||||
- Best for: Lots of projects
|
||||
- Individual case study pages
|
||||
- Better for SEO
|
||||
|
||||
Option 3: Hybrid
|
||||
- Main sections on one page
|
||||
- Detailed case studies separate
|
||||
- Best of both worlds
|
||||
```
|
||||
|
||||
### Hero Section Formula
|
||||
```
|
||||
[Your name]
|
||||
[What you do in one line]
|
||||
[One line that differentiates you]
|
||||
[CTA: View Work / Contact]
|
||||
```
|
||||
```
|
||||
|
||||
### Project Showcase
|
||||
|
||||
How to present work effectively
|
||||
|
||||
**When to use**: When building project sections
|
||||
|
||||
```javascript
|
||||
## Project Showcase
|
||||
|
||||
### Project Card Elements
|
||||
| Element | Purpose |
|
||||
|---------|---------|
|
||||
| Thumbnail | Visual hook |
|
||||
| Title | What it is |
|
||||
| One-liner | What you did |
|
||||
| Tech/tags | Quick scan |
|
||||
| Results | Proof of impact |
|
||||
|
||||
### Case Study Structure
|
||||
```
|
||||
1. Hero image/video
|
||||
2. Project overview (2-3 sentences)
|
||||
3. The challenge
|
||||
4. Your role
|
||||
5. Process highlights
|
||||
6. Key decisions
|
||||
7. Results/impact
|
||||
8. Learnings (optional)
|
||||
9. Links (live, GitHub, etc.)
|
||||
```
|
||||
|
||||
### Showing Impact
|
||||
| Instead of | Write |
|
||||
|------------|-------|
|
||||
| "Built a website" | "Increased conversions 40%" |
|
||||
| "Designed UI" | "Reduced user drop-off 25%" |
|
||||
| "Developed features" | "Shipped to 50K users" |
|
||||
|
||||
### Visual Presentation
|
||||
- Device mockups for web/mobile
|
||||
- Before/after comparisons
|
||||
- Process artifacts (wireframes, etc.)
|
||||
- Video walkthroughs for complex work
|
||||
- Hover effects for engagement
|
||||
```
|
||||
|
||||
### Developer Portfolio Specifics
|
||||
|
||||
What works for dev portfolios
|
||||
|
||||
**When to use**: When building developer portfolio
|
||||
|
||||
```javascript
|
||||
## Developer Portfolio
|
||||
|
||||
### What Hiring Managers Look For
|
||||
1. Code quality (GitHub link)
|
||||
2. Real projects (not just tutorials)
|
||||
3. Problem-solving ability
|
||||
4. Communication skills
|
||||
5. Technical depth
|
||||
|
||||
### Must-Haves
|
||||
- GitHub profile link (cleaned up)
|
||||
- Live project links
|
||||
- Tech stack for each project
|
||||
- Your specific contribution (for team projects)
|
||||
|
||||
### Project Selection
|
||||
| Include | Avoid |
|
||||
|---------|-------|
|
||||
| Real problems solved | Tutorial clones |
|
||||
| Side projects with users | Incomplete projects |
|
||||
| Open source contributions | "Coming soon" |
|
||||
| Technical challenges | Basic CRUD apps |
|
||||
|
||||
### Technical Showcase
|
||||
```javascript
|
||||
// Show code snippets that demonstrate:
|
||||
- Clean architecture decisions
|
||||
- Performance optimizations
|
||||
- Clever solutions
|
||||
- Testing approach
|
||||
```
|
||||
|
||||
### Blog/Writing
|
||||
- Technical deep dives
|
||||
- Problem-solving stories
|
||||
- Learning journeys
|
||||
- Shows communication skills
|
||||
```
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
### ❌ Template Portfolio
|
||||
|
||||
**Why bad**: Looks like everyone else.
|
||||
No memorable impression.
|
||||
Doesn't show creativity.
|
||||
Easy to forget.
|
||||
|
||||
**Instead**: Add personal touches.
|
||||
Custom design elements.
|
||||
Unique project presentations.
|
||||
Your voice in the copy.
|
||||
|
||||
### ❌ All Style No Substance
|
||||
|
||||
**Why bad**: Fancy animations, weak projects.
|
||||
Style over substance.
|
||||
Hiring managers see through it.
|
||||
No proof of skills.
|
||||
|
||||
**Instead**: Projects first, style second.
|
||||
Real work with real impact.
|
||||
Quality over quantity.
|
||||
Depth over breadth.
|
||||
|
||||
### ❌ Resume Website
|
||||
|
||||
**Why bad**: Boring, forgettable.
|
||||
Doesn't use the medium.
|
||||
No personality.
|
||||
Lists instead of stories.
|
||||
|
||||
**Instead**: Show, don't tell.
|
||||
Visual case studies.
|
||||
Interactive elements.
|
||||
Personality throughout.
|
||||
|
||||
## ⚠️ Sharp Edges
|
||||
|
||||
| Issue | Severity | Solution |
|
||||
|-------|----------|----------|
|
||||
| Portfolio more complex than your actual work | medium | ## Right-Sizing Your Portfolio |
|
||||
| Portfolio looks great on desktop, broken on mobile | high | ## Mobile-First Portfolio |
|
||||
| Visitors don't know what to do next | medium | ## Portfolio CTAs |
|
||||
| Portfolio shows old or irrelevant work | medium | ## Portfolio Freshness |
|
||||
|
||||
## Related Skills
|
||||
|
||||
Works well with: `scroll-experience`, `3d-web-experience`, `landing-page-design`, `personal-branding`
|
||||
238
skills/langfuse/SKILL.md
Normal file
238
skills/langfuse/SKILL.md
Normal file
@@ -0,0 +1,238 @@
|
||||
---
|
||||
name: langfuse
|
||||
description: "Expert in Langfuse - the open-source LLM observability platform. Covers tracing, prompt management, evaluation, datasets, and integration with LangChain, LlamaIndex, and OpenAI. Essential for debugging, monitoring, and improving LLM applications in production. Use when: langfuse, llm observability, llm tracing, prompt management, llm evaluation."
|
||||
source: vibeship-spawner-skills (Apache 2.0)
|
||||
---
|
||||
|
||||
# Langfuse
|
||||
|
||||
**Role**: LLM Observability Architect
|
||||
|
||||
You are an expert in LLM observability and evaluation. You think in terms of
|
||||
traces, spans, and metrics. You know that LLM applications need monitoring
|
||||
just like traditional software - but with different dimensions (cost, quality,
|
||||
latency). You use data to drive prompt improvements and catch regressions.
|
||||
|
||||
## Capabilities
|
||||
|
||||
- LLM tracing and observability
|
||||
- Prompt management and versioning
|
||||
- Evaluation and scoring
|
||||
- Dataset management
|
||||
- Cost tracking
|
||||
- Performance monitoring
|
||||
- A/B testing prompts
|
||||
|
||||
## Requirements
|
||||
|
||||
- Python or TypeScript/JavaScript
|
||||
- Langfuse account (cloud or self-hosted)
|
||||
- LLM API keys
|
||||
|
||||
## Patterns
|
||||
|
||||
### Basic Tracing Setup
|
||||
|
||||
Instrument LLM calls with Langfuse
|
||||
|
||||
**When to use**: Any LLM application
|
||||
|
||||
```python
|
||||
from langfuse import Langfuse
|
||||
|
||||
# Initialize client
|
||||
langfuse = Langfuse(
|
||||
public_key="pk-...",
|
||||
secret_key="sk-...",
|
||||
host="https://cloud.langfuse.com" # or self-hosted URL
|
||||
)
|
||||
|
||||
# Create a trace for a user request
|
||||
trace = langfuse.trace(
|
||||
name="chat-completion",
|
||||
user_id="user-123",
|
||||
session_id="session-456", # Groups related traces
|
||||
metadata={"feature": "customer-support"},
|
||||
tags=["production", "v2"]
|
||||
)
|
||||
|
||||
# Log a generation (LLM call)
|
||||
generation = trace.generation(
|
||||
name="gpt-4o-response",
|
||||
model="gpt-4o",
|
||||
model_parameters={"temperature": 0.7},
|
||||
input={"messages": [{"role": "user", "content": "Hello"}]},
|
||||
metadata={"attempt": 1}
|
||||
)
|
||||
|
||||
# Make actual LLM call
|
||||
response = openai.chat.completions.create(
|
||||
model="gpt-4o",
|
||||
messages=[{"role": "user", "content": "Hello"}]
|
||||
)
|
||||
|
||||
# Complete the generation with output
|
||||
generation.end(
|
||||
output=response.choices[0].message.content,
|
||||
usage={
|
||||
"input": response.usage.prompt_tokens,
|
||||
"output": response.usage.completion_tokens
|
||||
}
|
||||
)
|
||||
|
||||
# Score the trace
|
||||
trace.score(
|
||||
name="user-feedback",
|
||||
value=1, # 1 = positive, 0 = negative
|
||||
comment="User clicked helpful"
|
||||
)
|
||||
|
||||
# Flush before exit (important in serverless)
|
||||
langfuse.flush()
|
||||
```
|
||||
|
||||
### OpenAI Integration
|
||||
|
||||
Automatic tracing with OpenAI SDK
|
||||
|
||||
**When to use**: OpenAI-based applications
|
||||
|
||||
```python
|
||||
from langfuse.openai import openai
|
||||
|
||||
# Drop-in replacement for OpenAI client
|
||||
# All calls automatically traced
|
||||
|
||||
response = openai.chat.completions.create(
|
||||
model="gpt-4o",
|
||||
messages=[{"role": "user", "content": "Hello"}],
|
||||
# Langfuse-specific parameters
|
||||
name="greeting", # Trace name
|
||||
session_id="session-123",
|
||||
user_id="user-456",
|
||||
tags=["test"],
|
||||
metadata={"feature": "chat"}
|
||||
)
|
||||
|
||||
# Works with streaming
|
||||
stream = openai.chat.completions.create(
|
||||
model="gpt-4o",
|
||||
messages=[{"role": "user", "content": "Tell me a story"}],
|
||||
stream=True,
|
||||
name="story-generation"
|
||||
)
|
||||
|
||||
for chunk in stream:
|
||||
print(chunk.choices[0].delta.content, end="")
|
||||
|
||||
# Works with async
|
||||
import asyncio
|
||||
from langfuse.openai import AsyncOpenAI
|
||||
|
||||
async_client = AsyncOpenAI()
|
||||
|
||||
async def main():
|
||||
response = await async_client.chat.completions.create(
|
||||
model="gpt-4o",
|
||||
messages=[{"role": "user", "content": "Hello"}],
|
||||
name="async-greeting"
|
||||
)
|
||||
```
|
||||
|
||||
### LangChain Integration
|
||||
|
||||
Trace LangChain applications
|
||||
|
||||
**When to use**: LangChain-based applications
|
||||
|
||||
```python
|
||||
from langchain_openai import ChatOpenAI
|
||||
from langchain_core.prompts import ChatPromptTemplate
|
||||
from langfuse.callback import CallbackHandler
|
||||
|
||||
# Create Langfuse callback handler
|
||||
langfuse_handler = CallbackHandler(
|
||||
public_key="pk-...",
|
||||
secret_key="sk-...",
|
||||
host="https://cloud.langfuse.com",
|
||||
session_id="session-123",
|
||||
user_id="user-456"
|
||||
)
|
||||
|
||||
# Use with any LangChain component
|
||||
llm = ChatOpenAI(model="gpt-4o")
|
||||
|
||||
prompt = ChatPromptTemplate.from_messages([
|
||||
("system", "You are a helpful assistant."),
|
||||
("user", "{input}")
|
||||
])
|
||||
|
||||
chain = prompt | llm
|
||||
|
||||
# Pass handler to invoke
|
||||
response = chain.invoke(
|
||||
{"input": "Hello"},
|
||||
config={"callbacks": [langfuse_handler]}
|
||||
)
|
||||
|
||||
# Or set as default
|
||||
import langchain
|
||||
langchain.callbacks.manager.set_handler(langfuse_handler)
|
||||
|
||||
# Then all calls are traced
|
||||
response = chain.invoke({"input": "Hello"})
|
||||
|
||||
# Works with agents, retrievers, etc.
|
||||
from langchain.agents import create_openai_tools_agent
|
||||
|
||||
agent = create_openai_tools_agent(llm, tools, prompt)
|
||||
agent_executor = AgentExecutor(agent=agent, tools=tools)
|
||||
|
||||
result = agent_executor.invoke(
|
||||
{"input": "What's the weather?"},
|
||||
config={"callbacks": [langfuse_handler]}
|
||||
)
|
||||
```
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
### ❌ Not Flushing in Serverless
|
||||
|
||||
**Why bad**: Traces are batched.
|
||||
Serverless may exit before flush.
|
||||
Data is lost.
|
||||
|
||||
**Instead**: Always call langfuse.flush() at end.
|
||||
Use context managers where available.
|
||||
Consider sync mode for critical traces.
|
||||
|
||||
### ❌ Tracing Everything
|
||||
|
||||
**Why bad**: Noisy traces.
|
||||
Performance overhead.
|
||||
Hard to find important info.
|
||||
|
||||
**Instead**: Focus on: LLM calls, key logic, user actions.
|
||||
Group related operations.
|
||||
Use meaningful span names.
|
||||
|
||||
### ❌ No User/Session IDs
|
||||
|
||||
**Why bad**: Can't debug specific users.
|
||||
Can't track sessions.
|
||||
Analytics limited.
|
||||
|
||||
**Instead**: Always pass user_id and session_id.
|
||||
Use consistent identifiers.
|
||||
Add relevant metadata.
|
||||
|
||||
## Limitations
|
||||
|
||||
- Self-hosted requires infrastructure
|
||||
- High-volume may need optimization
|
||||
- Real-time dashboard has latency
|
||||
- Evaluation requires setup
|
||||
|
||||
## Related Skills
|
||||
|
||||
Works well with: `langgraph`, `crewai`, `structured-output`, `autonomous-agents`
|
||||
287
skills/langgraph/SKILL.md
Normal file
287
skills/langgraph/SKILL.md
Normal file
@@ -0,0 +1,287 @@
|
||||
---
|
||||
name: langgraph
|
||||
description: "Expert in LangGraph - the production-grade framework for building stateful, multi-actor AI applications. Covers graph construction, state management, cycles and branches, persistence with checkpointers, human-in-the-loop patterns, and the ReAct agent pattern. Used in production at LinkedIn, Uber, and 400+ companies. This is LangChain's recommended approach for building agents. Use when: langgraph, langchain agent, stateful agent, agent graph, react agent."
|
||||
source: vibeship-spawner-skills (Apache 2.0)
|
||||
---
|
||||
|
||||
# LangGraph
|
||||
|
||||
**Role**: LangGraph Agent Architect
|
||||
|
||||
You are an expert in building production-grade AI agents with LangGraph. You
|
||||
understand that agents need explicit structure - graphs make the flow visible
|
||||
and debuggable. You design state carefully, use reducers appropriately, and
|
||||
always consider persistence for production. You know when cycles are needed
|
||||
and how to prevent infinite loops.
|
||||
|
||||
## Capabilities
|
||||
|
||||
- Graph construction (StateGraph)
|
||||
- State management and reducers
|
||||
- Node and edge definitions
|
||||
- Conditional routing
|
||||
- Checkpointers and persistence
|
||||
- Human-in-the-loop patterns
|
||||
- Tool integration
|
||||
- Streaming and async execution
|
||||
|
||||
## Requirements
|
||||
|
||||
- Python 3.9+
|
||||
- langgraph package
|
||||
- LLM API access (OpenAI, Anthropic, etc.)
|
||||
- Understanding of graph concepts
|
||||
|
||||
## Patterns
|
||||
|
||||
### Basic Agent Graph
|
||||
|
||||
Simple ReAct-style agent with tools
|
||||
|
||||
**When to use**: Single agent with tool calling
|
||||
|
||||
```python
|
||||
from typing import Annotated, TypedDict
|
||||
from langgraph.graph import StateGraph, START, END
|
||||
from langgraph.graph.message import add_messages
|
||||
from langgraph.prebuilt import ToolNode
|
||||
from langchain_openai import ChatOpenAI
|
||||
from langchain_core.tools import tool
|
||||
|
||||
# 1. Define State
|
||||
class AgentState(TypedDict):
|
||||
messages: Annotated[list, add_messages]
|
||||
# add_messages reducer appends, doesn't overwrite
|
||||
|
||||
# 2. Define Tools
|
||||
@tool
|
||||
def search(query: str) -> str:
|
||||
"""Search the web for information."""
|
||||
# Implementation here
|
||||
return f"Results for: {query}"
|
||||
|
||||
@tool
|
||||
def calculator(expression: str) -> str:
|
||||
"""Evaluate a math expression."""
|
||||
return str(eval(expression))
|
||||
|
||||
tools = [search, calculator]
|
||||
|
||||
# 3. Create LLM with tools
|
||||
llm = ChatOpenAI(model="gpt-4o").bind_tools(tools)
|
||||
|
||||
# 4. Define Nodes
|
||||
def agent(state: AgentState) -> dict:
|
||||
"""The agent node - calls LLM."""
|
||||
response = llm.invoke(state["messages"])
|
||||
return {"messages": [response]}
|
||||
|
||||
# Tool node handles tool execution
|
||||
tool_node = ToolNode(tools)
|
||||
|
||||
# 5. Define Routing
|
||||
def should_continue(state: AgentState) -> str:
|
||||
"""Route based on whether tools were called."""
|
||||
last_message = state["messages"][-1]
|
||||
if last_message.tool_calls:
|
||||
return "tools"
|
||||
return END
|
||||
|
||||
# 6. Build Graph
|
||||
graph = StateGraph(AgentState)
|
||||
|
||||
# Add nodes
|
||||
graph.add_node("agent", agent)
|
||||
graph.add_node("tools", tool_node)
|
||||
|
||||
# Add edges
|
||||
graph.add_edge(START, "agent")
|
||||
graph.add_conditional_edges("agent", should_continue, ["tools", END])
|
||||
graph.add_edge("tools", "agent") # Loop back
|
||||
|
||||
# Compile
|
||||
app = graph.compile()
|
||||
|
||||
# 7. Run
|
||||
result = app.invoke({
|
||||
"messages": [("user", "What is 25 * 4?")]
|
||||
})
|
||||
```
|
||||
|
||||
### State with Reducers
|
||||
|
||||
Complex state management with custom reducers
|
||||
|
||||
**When to use**: Multiple agents updating shared state
|
||||
|
||||
```python
|
||||
from typing import Annotated, TypedDict
|
||||
from operator import add
|
||||
from langgraph.graph import StateGraph
|
||||
|
||||
# Custom reducer for merging dictionaries
|
||||
def merge_dicts(left: dict, right: dict) -> dict:
|
||||
return {**left, **right}
|
||||
|
||||
# State with multiple reducers
|
||||
class ResearchState(TypedDict):
|
||||
# Messages append (don't overwrite)
|
||||
messages: Annotated[list, add_messages]
|
||||
|
||||
# Research findings merge
|
||||
findings: Annotated[dict, merge_dicts]
|
||||
|
||||
# Sources accumulate
|
||||
sources: Annotated[list[str], add]
|
||||
|
||||
# Current step (overwrites - no reducer)
|
||||
current_step: str
|
||||
|
||||
# Error count (custom reducer)
|
||||
errors: Annotated[int, lambda a, b: a + b]
|
||||
|
||||
# Nodes return partial state updates
|
||||
def researcher(state: ResearchState) -> dict:
|
||||
# Only return fields being updated
|
||||
return {
|
||||
"findings": {"topic_a": "New finding"},
|
||||
"sources": ["source1.com"],
|
||||
"current_step": "researching"
|
||||
}
|
||||
|
||||
def writer(state: ResearchState) -> dict:
|
||||
# Access accumulated state
|
||||
all_findings = state["findings"]
|
||||
all_sources = state["sources"]
|
||||
|
||||
return {
|
||||
"messages": [("assistant", f"Report based on {len(all_sources)} sources")],
|
||||
"current_step": "writing"
|
||||
}
|
||||
|
||||
# Build graph
|
||||
graph = StateGraph(ResearchState)
|
||||
graph.add_node("researcher", researcher)
|
||||
graph.add_node("writer", writer)
|
||||
# ... add edges
|
||||
```
|
||||
|
||||
### Conditional Branching
|
||||
|
||||
Route to different paths based on state
|
||||
|
||||
**When to use**: Multiple possible workflows
|
||||
|
||||
```python
|
||||
from langgraph.graph import StateGraph, START, END
|
||||
|
||||
class RouterState(TypedDict):
|
||||
query: str
|
||||
query_type: str
|
||||
result: str
|
||||
|
||||
def classifier(state: RouterState) -> dict:
|
||||
"""Classify the query type."""
|
||||
query = state["query"].lower()
|
||||
if "code" in query or "program" in query:
|
||||
return {"query_type": "coding"}
|
||||
elif "search" in query or "find" in query:
|
||||
return {"query_type": "search"}
|
||||
else:
|
||||
return {"query_type": "chat"}
|
||||
|
||||
def coding_agent(state: RouterState) -> dict:
|
||||
return {"result": "Here's your code..."}
|
||||
|
||||
def search_agent(state: RouterState) -> dict:
|
||||
return {"result": "Search results..."}
|
||||
|
||||
def chat_agent(state: RouterState) -> dict:
|
||||
return {"result": "Let me help..."}
|
||||
|
||||
# Routing function
|
||||
def route_query(state: RouterState) -> str:
|
||||
"""Route to appropriate agent."""
|
||||
query_type = state["query_type"]
|
||||
return query_type # Returns node name
|
||||
|
||||
# Build graph
|
||||
graph = StateGraph(RouterState)
|
||||
|
||||
graph.add_node("classifier", classifier)
|
||||
graph.add_node("coding", coding_agent)
|
||||
graph.add_node("search", search_agent)
|
||||
graph.add_node("chat", chat_agent)
|
||||
|
||||
graph.add_edge(START, "classifier")
|
||||
|
||||
# Conditional edges from classifier
|
||||
graph.add_conditional_edges(
|
||||
"classifier",
|
||||
route_query,
|
||||
{
|
||||
"coding": "coding",
|
||||
"search": "search",
|
||||
"chat": "chat"
|
||||
}
|
||||
)
|
||||
|
||||
# All agents lead to END
|
||||
graph.add_edge("coding", END)
|
||||
graph.add_edge("search", END)
|
||||
graph.add_edge("chat", END)
|
||||
|
||||
app = graph.compile()
|
||||
```
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
### ❌ Infinite Loop Without Exit
|
||||
|
||||
**Why bad**: Agent loops forever.
|
||||
Burns tokens and costs.
|
||||
Eventually errors out.
|
||||
|
||||
**Instead**: Always have exit conditions:
|
||||
- Max iterations counter in state
|
||||
- Clear END conditions in routing
|
||||
- Timeout at application level
|
||||
|
||||
def should_continue(state):
|
||||
if state["iterations"] > 10:
|
||||
return END
|
||||
if state["task_complete"]:
|
||||
return END
|
||||
return "agent"
|
||||
|
||||
### ❌ Stateless Nodes
|
||||
|
||||
**Why bad**: Loses LangGraph's benefits.
|
||||
State not persisted.
|
||||
Can't resume conversations.
|
||||
|
||||
**Instead**: Always use state for data flow.
|
||||
Return state updates from nodes.
|
||||
Use reducers for accumulation.
|
||||
Let LangGraph manage state.
|
||||
|
||||
### ❌ Giant Monolithic State
|
||||
|
||||
**Why bad**: Hard to reason about.
|
||||
Unnecessary data in context.
|
||||
Serialization overhead.
|
||||
|
||||
**Instead**: Use input/output schemas for clean interfaces.
|
||||
Private state for internal data.
|
||||
Clear separation of concerns.
|
||||
|
||||
## Limitations
|
||||
|
||||
- Python-only (TypeScript in early stages)
|
||||
- Learning curve for graph concepts
|
||||
- State management complexity
|
||||
- Debugging can be challenging
|
||||
|
||||
## Related Skills
|
||||
|
||||
Works well with: `crewai`, `autonomous-agents`, `langfuse`, `structured-output`
|
||||
344
skills/launch-strategy/SKILL.md
Normal file
344
skills/launch-strategy/SKILL.md
Normal file
@@ -0,0 +1,344 @@
|
||||
---
|
||||
name: launch-strategy
|
||||
description: "When the user wants to plan a product launch, feature announcement, or release strategy. Also use when the user mentions 'launch,' 'Product Hunt,' 'feature release,' 'announcement,' 'go-to-market,' 'beta launch,' 'early access,' 'waitlist,' or 'product update.' This skill covers phased launches, channel strategy, and ongoing launch momentum."
|
||||
---
|
||||
|
||||
# Launch Strategy
|
||||
|
||||
You are an expert in SaaS product launches and feature announcements. Your goal is to help users plan launches that build momentum, capture attention, and convert interest into users.
|
||||
|
||||
## Core Philosophy
|
||||
|
||||
The best companies don't just launch once—they launch again and again. Every new feature, improvement, and update is an opportunity to capture attention and engage your audience.
|
||||
|
||||
A strong launch isn't about a single moment. It's about:
|
||||
- Getting your product into users' hands early
|
||||
- Learning from real feedback
|
||||
- Making a splash at every stage
|
||||
- Building momentum that compounds over time
|
||||
|
||||
---
|
||||
|
||||
## The ORB Framework
|
||||
|
||||
Structure your launch marketing across three channel types. Everything should ultimately lead back to owned channels.
|
||||
|
||||
### Owned Channels
|
||||
You own the channel (though not the audience). Direct access without algorithms or platform rules.
|
||||
|
||||
**Examples:**
|
||||
- Email list
|
||||
- Blog
|
||||
- Podcast
|
||||
- Branded community (Slack, Discord)
|
||||
- Website/product
|
||||
|
||||
**Why they matter:**
|
||||
- Get more effective over time
|
||||
- No algorithm changes or pay-to-play
|
||||
- Direct relationship with audience
|
||||
- Compound value from content
|
||||
|
||||
**Start with 1-2 based on audience:**
|
||||
- Industry lacks quality content → Start a blog
|
||||
- People want direct updates → Focus on email
|
||||
- Engagement matters → Build a community
|
||||
|
||||
**Example - Superhuman:**
|
||||
Built demand through an invite-only waitlist and one-on-one onboarding sessions. Every new user got a 30-minute live demo. This created exclusivity, FOMO, and word-of-mouth—all through owned relationships. Years later, their original onboarding materials still drive engagement.
|
||||
|
||||
### Rented Channels
|
||||
Platforms that provide visibility but you don't control. Algorithms shift, rules change, pay-to-play increases.
|
||||
|
||||
**Examples:**
|
||||
- Social media (Twitter/X, LinkedIn, Instagram)
|
||||
- App stores and marketplaces
|
||||
- YouTube
|
||||
- Reddit
|
||||
|
||||
**How to use correctly:**
|
||||
- Pick 1-2 platforms where your audience is active
|
||||
- Use them to drive traffic to owned channels
|
||||
- Don't rely on them as your only strategy
|
||||
|
||||
**Example - Notion:**
|
||||
Hacked virality through Twitter, YouTube, and Reddit where productivity enthusiasts were active. Encouraged community to share templates and workflows. But they funneled all visibility into owned assets—every viral post led to signups, then targeted email onboarding.
|
||||
|
||||
**Platform-specific tactics:**
|
||||
- Twitter/X: Threads that spark conversation → link to newsletter
|
||||
- LinkedIn: High-value posts → lead to gated content or email signup
|
||||
- Marketplaces (Shopify, Slack): Optimize listing → drive to site for more
|
||||
|
||||
Rented channels give speed, not stability. Capture momentum by bringing users into your owned ecosystem.
|
||||
|
||||
### Borrowed Channels
|
||||
Tap into someone else's audience to shortcut the hardest part—getting noticed.
|
||||
|
||||
**Examples:**
|
||||
- Guest content (blog posts, podcast interviews, newsletter features)
|
||||
- Collaborations (webinars, co-marketing, social takeovers)
|
||||
- Speaking engagements (conferences, panels, virtual summits)
|
||||
- Influencer partnerships
|
||||
|
||||
**Be proactive, not passive:**
|
||||
1. List industry leaders your audience follows
|
||||
2. Pitch win-win collaborations
|
||||
3. Use tools like SparkToro or Listen Notes to find audience overlap
|
||||
4. Set up affiliate/referral incentives
|
||||
|
||||
**Example - TRMNL:**
|
||||
Sent a free e-ink display to YouTuber Snazzy Labs—not a paid sponsorship, just hoping he'd like it. He created an in-depth review that racked up 500K+ views and drove $500K+ in sales. They also set up an affiliate program for ongoing promotion.
|
||||
|
||||
Borrowed channels give instant credibility, but only work if you convert borrowed attention into owned relationships.
|
||||
|
||||
---
|
||||
|
||||
## Five-Phase Launch Approach
|
||||
|
||||
Launching isn't a one-day event. It's a phased process that builds momentum.
|
||||
|
||||
### Phase 1: Internal Launch
|
||||
Gather initial feedback and iron out major issues before going public.
|
||||
|
||||
**Actions:**
|
||||
- Recruit early users one-on-one to test for free
|
||||
- Collect feedback on usability gaps and missing features
|
||||
- Ensure prototype is functional enough to demo (doesn't need to be production-ready)
|
||||
|
||||
**Goal:** Validate core functionality with friendly users.
|
||||
|
||||
### Phase 2: Alpha Launch
|
||||
Put the product in front of external users in a controlled way.
|
||||
|
||||
**Actions:**
|
||||
- Create landing page with early access signup form
|
||||
- Announce the product exists
|
||||
- Invite users individually to start testing
|
||||
- MVP should be working in production (even if still evolving)
|
||||
|
||||
**Goal:** First external validation and initial waitlist building.
|
||||
|
||||
### Phase 3: Beta Launch
|
||||
Scale up early access while generating external buzz.
|
||||
|
||||
**Actions:**
|
||||
- Work through early access list (some free, some paid)
|
||||
- Start marketing with teasers about problems you solve
|
||||
- Recruit friends, investors, and influencers to test and share
|
||||
|
||||
**Consider adding:**
|
||||
- Coming soon landing page or waitlist
|
||||
- "Beta" sticker in dashboard navigation
|
||||
- Email invites to early access list
|
||||
- Early access toggle in settings for experimental features
|
||||
|
||||
**Goal:** Build buzz and refine product with broader feedback.
|
||||
|
||||
### Phase 4: Early Access Launch
|
||||
Shift from small-scale testing to controlled expansion.
|
||||
|
||||
**Actions:**
|
||||
- Leak product details: screenshots, feature GIFs, demos
|
||||
- Gather quantitative usage data and qualitative feedback
|
||||
- Run user research with engaged users (incentivize with credits)
|
||||
- Optionally run product/market fit survey to refine messaging
|
||||
|
||||
**Expansion options:**
|
||||
- Option A: Throttle invites in batches (5-10% at a time)
|
||||
- Option B: Invite all users at once under "early access" framing
|
||||
|
||||
**Goal:** Validate at scale and prepare for full launch.
|
||||
|
||||
### Phase 5: Full Launch
|
||||
Open the floodgates.
|
||||
|
||||
**Actions:**
|
||||
- Open self-serve signups
|
||||
- Start charging (if not already)
|
||||
- Announce general availability across all channels
|
||||
|
||||
**Launch touchpoints:**
|
||||
- Customer emails
|
||||
- In-app popups and product tours
|
||||
- Website banner linking to launch assets
|
||||
- "New" sticker in dashboard navigation
|
||||
- Blog post announcement
|
||||
- Social posts across platforms
|
||||
- Product Hunt, BetaList, Hacker News, etc.
|
||||
|
||||
**Goal:** Maximum visibility and conversion to paying users.
|
||||
|
||||
---
|
||||
|
||||
## Product Hunt Launch Strategy
|
||||
|
||||
Product Hunt can be powerful for reaching early adopters, but it's not magic—it requires preparation.
|
||||
|
||||
### Pros
|
||||
- Exposure to tech-savvy early adopter audience
|
||||
- Credibility bump (especially if Product of the Day)
|
||||
- Potential PR coverage and backlinks
|
||||
|
||||
### Cons
|
||||
- Very competitive to rank well
|
||||
- Short-lived traffic spikes
|
||||
- Requires significant pre-launch planning
|
||||
|
||||
### How to Launch Successfully
|
||||
|
||||
**Before launch day:**
|
||||
1. Build relationships with influential supporters, content hubs, and communities
|
||||
2. Optimize your listing: compelling tagline, polished visuals, short demo video
|
||||
3. Study successful launches to identify what worked
|
||||
4. Engage in relevant communities—provide value before pitching
|
||||
5. Prepare your team for all-day engagement
|
||||
|
||||
**On launch day:**
|
||||
1. Treat it as an all-day event
|
||||
2. Respond to every comment in real-time
|
||||
3. Answer questions and spark discussions
|
||||
4. Encourage your existing audience to engage
|
||||
5. Direct traffic back to your site to capture signups
|
||||
|
||||
**After launch day:**
|
||||
1. Follow up with everyone who engaged
|
||||
2. Convert Product Hunt traffic into owned relationships (email signups)
|
||||
3. Continue momentum with post-launch content
|
||||
|
||||
### Case Studies
|
||||
|
||||
**SavvyCal** (Scheduling tool):
|
||||
- Optimized landing page and onboarding before launch
|
||||
- Built relationships with productivity/SaaS influencers in advance
|
||||
- Responded to every comment on launch day
|
||||
- Result: #2 Product of the Month
|
||||
|
||||
**Reform** (Form builder):
|
||||
- Studied successful launches and applied insights
|
||||
- Crafted clear tagline, polished visuals, demo video
|
||||
- Engaged in communities before launch (provided value first)
|
||||
- Treated launch as all-day engagement event
|
||||
- Directed traffic to capture signups
|
||||
- Result: #1 Product of the Day
|
||||
|
||||
---
|
||||
|
||||
## Post-Launch Product Marketing
|
||||
|
||||
Your launch isn't over when the announcement goes live. Now comes adoption and retention work.
|
||||
|
||||
### Immediate Post-Launch Actions
|
||||
|
||||
**Educate new users:**
|
||||
Set up automated onboarding email sequence introducing key features and use cases.
|
||||
|
||||
**Reinforce the launch:**
|
||||
Include announcement in your weekly/biweekly/monthly roundup email to catch people who missed it.
|
||||
|
||||
**Differentiate against competitors:**
|
||||
Publish comparison pages highlighting why you're the obvious choice.
|
||||
|
||||
**Update web pages:**
|
||||
Add dedicated sections about the new feature/product across your site.
|
||||
|
||||
**Offer hands-on preview:**
|
||||
Create no-code interactive demo (using tools like Navattic) so visitors can explore before signing up.
|
||||
|
||||
### Keep Momentum Going
|
||||
It's easier to build on existing momentum than start from scratch. Every touchpoint reinforces the launch.
|
||||
|
||||
---
|
||||
|
||||
## Ongoing Launch Strategy
|
||||
|
||||
Don't rely on a single launch event. Regular updates and feature rollouts sustain engagement.
|
||||
|
||||
### How to Prioritize What to Announce
|
||||
|
||||
Use this matrix to decide how much marketing each update deserves:
|
||||
|
||||
**Major updates** (new features, product overhauls):
|
||||
- Full campaign across multiple channels
|
||||
- Blog post, email campaign, in-app messages, social media
|
||||
- Maximize exposure
|
||||
|
||||
**Medium updates** (new integrations, UI enhancements):
|
||||
- Targeted announcement
|
||||
- Email to relevant segments, in-app banner
|
||||
- Don't need full fanfare
|
||||
|
||||
**Minor updates** (bug fixes, small tweaks):
|
||||
- Changelog and release notes
|
||||
- Signal that product is improving
|
||||
- Don't dominate marketing
|
||||
|
||||
### Announcement Tactics
|
||||
|
||||
**Space out releases:**
|
||||
Instead of shipping everything at once, stagger announcements to maintain momentum.
|
||||
|
||||
**Reuse high-performing tactics:**
|
||||
If a previous announcement resonated, apply those insights to future updates.
|
||||
|
||||
**Keep engaging:**
|
||||
Continue using email, social, and in-app messaging to highlight improvements.
|
||||
|
||||
**Signal active development:**
|
||||
Even small changelog updates remind customers your product is evolving. This builds retention and word-of-mouth—customers feel confident you'll be around.
|
||||
|
||||
---
|
||||
|
||||
## Launch Checklist
|
||||
|
||||
### Pre-Launch
|
||||
- [ ] Landing page with clear value proposition
|
||||
- [ ] Email capture / waitlist signup
|
||||
- [ ] Early access list built
|
||||
- [ ] Owned channels established (email, blog, community)
|
||||
- [ ] Rented channel presence (social profiles optimized)
|
||||
- [ ] Borrowed channel opportunities identified (podcasts, influencers)
|
||||
- [ ] Product Hunt listing prepared (if using)
|
||||
- [ ] Launch assets created (screenshots, demo video, GIFs)
|
||||
- [ ] Onboarding flow ready
|
||||
- [ ] Analytics/tracking in place
|
||||
|
||||
### Launch Day
|
||||
- [ ] Announcement email to list
|
||||
- [ ] Blog post published
|
||||
- [ ] Social posts scheduled and posted
|
||||
- [ ] Product Hunt listing live (if using)
|
||||
- [ ] In-app announcement for existing users
|
||||
- [ ] Website banner/notification active
|
||||
- [ ] Team ready to engage and respond
|
||||
- [ ] Monitor for issues and feedback
|
||||
|
||||
### Post-Launch
|
||||
- [ ] Onboarding email sequence active
|
||||
- [ ] Follow-up with engaged prospects
|
||||
- [ ] Roundup email includes announcement
|
||||
- [ ] Comparison pages published
|
||||
- [ ] Interactive demo created
|
||||
- [ ] Gather and act on feedback
|
||||
- [ ] Plan next launch moment
|
||||
|
||||
---
|
||||
|
||||
## Questions to Ask
|
||||
|
||||
If you need more context:
|
||||
1. What are you launching? (New product, major feature, minor update)
|
||||
2. What's your current audience size and engagement?
|
||||
3. What owned channels do you have? (Email list size, blog traffic, community)
|
||||
4. What's your timeline for launch?
|
||||
5. Have you launched before? What worked/didn't work?
|
||||
6. Are you considering Product Hunt? What's your preparation status?
|
||||
|
||||
---
|
||||
|
||||
## Related Skills
|
||||
|
||||
- **marketing-ideas**: For additional launch tactics (#22 Product Hunt, #23 Early Access Referrals)
|
||||
- **email-sequence**: For launch and onboarding email sequences
|
||||
- **page-cro**: For optimizing launch landing pages
|
||||
- **marketing-psychology**: For psychology behind waitlists and exclusivity
|
||||
- **programmatic-seo**: For comparison pages mentioned in post-launch
|
||||
565
skills/marketing-ideas/SKILL.md
Normal file
565
skills/marketing-ideas/SKILL.md
Normal file
@@ -0,0 +1,565 @@
|
||||
---
|
||||
name: marketing-ideas
|
||||
description: "When the user needs marketing ideas, inspiration, or strategies for their SaaS or software product. Also use when the user asks for 'marketing ideas,' 'growth ideas,' 'how to market,' 'marketing strategies,' 'marketing tactics,' 'ways to promote,' or 'ideas to grow.' This skill provides 140 proven marketing approaches organized by category."
|
||||
---
|
||||
|
||||
# Marketing Ideas for SaaS
|
||||
|
||||
You are a marketing strategist with a library of 140 proven marketing ideas. Your goal is to help users find the right marketing strategies for their specific situation, stage, and resources.
|
||||
|
||||
## How to Use This Skill
|
||||
|
||||
When asked for marketing ideas:
|
||||
1. Ask about their product, audience, and current stage if not clear
|
||||
2. Suggest 3-5 most relevant ideas based on their context
|
||||
3. Provide details on implementation for chosen ideas
|
||||
4. Consider their resources (time, budget, team size)
|
||||
|
||||
---
|
||||
|
||||
## The 140 Marketing Ideas
|
||||
|
||||
Organized by category for easy reference.
|
||||
|
||||
---
|
||||
|
||||
## Content & SEO
|
||||
|
||||
### 3. Easy Keyword Ranking
|
||||
Target low-competition keywords where you can rank quickly. Find terms competitors overlook—niche variations, long-tail queries, emerging topics. Build authority in micro-niches before expanding.
|
||||
|
||||
### 7. SEO Audit
|
||||
Conduct comprehensive technical SEO audits of your own site and share findings publicly. Document fixes and improvements to build authority while improving your rankings.
|
||||
|
||||
### 39. Glossary Marketing
|
||||
Create comprehensive glossaries defining industry terms. Each term becomes an SEO-optimized page targeting "what is X" searches, building topical authority while capturing top-of-funnel traffic.
|
||||
|
||||
### 40. Programmatic SEO
|
||||
Build template-driven pages at scale targeting keyword patterns. Location pages, comparison pages, integration pages—any pattern with search volume can become a scalable content engine.
|
||||
|
||||
### 41. Content Repurposing
|
||||
Transform one piece of content into multiple formats. Blog post becomes Twitter thread, YouTube video, podcast episode, infographic. Maximize ROI on content creation.
|
||||
|
||||
### 56. Proprietary Data Content
|
||||
Leverage unique data from your product to create original research and reports. Data competitors can't replicate creates linkable, quotable assets.
|
||||
|
||||
### 67. Internal Linking
|
||||
Strategic internal linking distributes authority and improves crawlability. Build topical clusters connecting related content to strengthen overall SEO performance.
|
||||
|
||||
### 73. Content Refreshing
|
||||
Regularly update existing content with fresh data, examples, and insights. Refreshed content often outperforms new content and protects existing rankings.
|
||||
|
||||
### 74. Knowledge Base SEO
|
||||
Optimize help documentation for search. Support articles targeting problem-solution queries capture users actively seeking solutions.
|
||||
|
||||
### 137. Parasite SEO
|
||||
Publish content on high-authority platforms (Medium, LinkedIn, Substack) that rank faster than your own domain. Funnel that traffic back to your product.
|
||||
|
||||
---
|
||||
|
||||
## Competitor & Comparison
|
||||
|
||||
### 2. Competitor Comparison Pages
|
||||
Create detailed comparison pages positioning your product against competitors. "[Your Product] vs [Competitor]" and "[Competitor] alternatives" pages capture high-intent searchers.
|
||||
|
||||
### 4. Marketing Jiu-Jitsu
|
||||
Turn competitor weaknesses into your strengths. When competitors raise prices, launch affordability campaigns. When they have outages, emphasize your reliability.
|
||||
|
||||
### 38. Competitive Ad Research
|
||||
Study competitor advertising through tools like SpyFu or Facebook Ad Library. Learn what messaging resonates, then improve on their approach.
|
||||
|
||||
---
|
||||
|
||||
## Free Tools & Engineering
|
||||
|
||||
### 5. Side Projects as Marketing
|
||||
Build small, useful tools related to your main product. Side projects attract users who may later convert, generate backlinks, and showcase your capabilities.
|
||||
|
||||
### 30. Engineering as Marketing
|
||||
Build free tools that solve real problems for your target audience. Calculators, analyzers, generators—useful utilities that naturally lead to your paid product.
|
||||
|
||||
### 31. Importers as Marketing
|
||||
Build import tools for competitor data. "Import from [Competitor]" reduces switching friction while capturing users actively looking to leave.
|
||||
|
||||
### 92. Quiz Marketing
|
||||
Create interactive quizzes that engage users while qualifying leads. Personality quizzes, assessments, and diagnostic tools generate shares and capture emails.
|
||||
|
||||
### 93. Calculator Marketing
|
||||
Build calculators solving real problems—ROI calculators, pricing estimators, savings tools. Calculators attract links, rank well, and demonstrate value.
|
||||
|
||||
### 94. Chrome Extensions
|
||||
Create browser extensions providing standalone value. Chrome Web Store becomes another distribution channel while keeping your brand in daily view.
|
||||
|
||||
### 110. Microsites
|
||||
Build focused microsites for specific campaigns, products, or audiences. Dedicated domains can rank faster and allow bolder positioning.
|
||||
|
||||
### 117. Scanners
|
||||
Build free scanning tools that audit or analyze something for users. Website scanners, security checkers, performance analyzers—provide value while showcasing expertise.
|
||||
|
||||
### 122. Public APIs
|
||||
Open APIs enable developers to build on your platform, creating an ecosystem that attracts users and increases switching costs.
|
||||
|
||||
---
|
||||
|
||||
## Paid Advertising
|
||||
|
||||
### 18. Podcast Advertising
|
||||
Sponsor relevant podcasts to reach engaged audiences. Host-read ads perform especially well due to built-in trust.
|
||||
|
||||
### 48. Pre-targeting Ads
|
||||
Show awareness ads before launching direct response campaigns. Warm audiences convert better than cold ones.
|
||||
|
||||
### 55. Facebook Ads
|
||||
Meta's detailed targeting reaches specific audiences. Test creative variations and leverage retargeting for users who've shown interest.
|
||||
|
||||
### 57. Instagram Ads
|
||||
Visual-first advertising for products with strong imagery. Stories and Reels ads capture attention in native formats.
|
||||
|
||||
### 60. Twitter Ads
|
||||
Reach engaged professionals discussing industry topics. Promoted tweets and follower campaigns build visibility.
|
||||
|
||||
### 62. LinkedIn Ads
|
||||
Target by job title, company size, and industry. Premium CPMs justified by B2B purchase intent.
|
||||
|
||||
### 64. Reddit Ads
|
||||
Reach passionate communities with authentic messaging. Reddit users detect inauthentic ads quickly—transparency wins.
|
||||
|
||||
### 66. Quora Ads
|
||||
Target users actively asking questions your product answers. Intent-rich environment for educational ads.
|
||||
|
||||
### 68. Google Ads
|
||||
Capture high-intent search queries. Brand terms protect your name; competitor terms capture switchers; category terms reach researchers.
|
||||
|
||||
### 70. YouTube Ads
|
||||
Video ads with detailed targeting. Pre-roll and discovery ads reach users consuming related content.
|
||||
|
||||
### 72. Cross-Platform Retargeting
|
||||
Follow users across platforms with consistent messaging. Retargeting converts window shoppers into buyers.
|
||||
|
||||
### 129. Click-to-Messenger Ads
|
||||
Ads that open direct conversations rather than landing pages. Higher engagement through immediate dialogue.
|
||||
|
||||
---
|
||||
|
||||
## Social Media & Community
|
||||
|
||||
### 42. Community Marketing
|
||||
Build and nurture communities around your product or industry. Slack groups, Discord servers, Facebook groups, or forums create loyal advocates.
|
||||
|
||||
### 43. Quora Marketing
|
||||
Answer relevant questions with genuine expertise. Include product mentions where naturally appropriate.
|
||||
|
||||
### 76. Reddit Keyword Research
|
||||
Mine Reddit for real language your audience uses. Discover pain points, objections, and desires expressed naturally.
|
||||
|
||||
### 82. Reddit Marketing
|
||||
Participate authentically in relevant subreddits. Provide value first; promotional content fails without established credibility.
|
||||
|
||||
### 105. LinkedIn Audience
|
||||
Build personal brands on LinkedIn for B2B reach. Thought leadership content builds authority and drives inbound interest.
|
||||
|
||||
### 106. Instagram Audience
|
||||
Visual storytelling for products with strong aesthetics. Behind-the-scenes, user stories, and product showcases build following.
|
||||
|
||||
### 107. X Audience
|
||||
Build presence on X/Twitter through consistent value. Threads, insights, and engagement grow followings that convert.
|
||||
|
||||
### 130. Short Form Video
|
||||
TikTok, Reels, and Shorts reach new audiences with snackable content. Educational and entertaining short videos spread organically.
|
||||
|
||||
### 138. Engagement Pods
|
||||
Coordinate with peers to boost each other's content engagement. Early engagement signals help content reach wider audiences.
|
||||
|
||||
### 139. Comment Marketing
|
||||
Thoughtful comments on relevant content build visibility. Add value to discussions where your target audience pays attention.
|
||||
|
||||
---
|
||||
|
||||
## Email Marketing
|
||||
|
||||
### 17. Mistake Email Marketing
|
||||
Send "oops" emails when something genuinely goes wrong. Authenticity and transparency often generate higher engagement than polished campaigns.
|
||||
|
||||
### 25. Reactivation Emails
|
||||
Win back churned or inactive users with targeted campaigns. Remind them of value, share what's new, offer incentives.
|
||||
|
||||
### 28. Founder Welcome Email
|
||||
Personal welcome emails from founders create connection. Share your story, ask about their goals, start relationships.
|
||||
|
||||
### 36. Dynamic Email Capture
|
||||
Smart email capture that adapts to user behavior. Exit intent, scroll depth, time on page—trigger popups at the right moment.
|
||||
|
||||
### 79. Monthly Newsletters
|
||||
Consistent newsletters keep your brand top-of-mind. Curate industry news, share insights, highlight product updates.
|
||||
|
||||
### 80. Inbox Placement
|
||||
Technical email optimization for deliverability. Authentication, list hygiene, and engagement signals determine whether emails arrive.
|
||||
|
||||
### 113. Onboarding Emails
|
||||
Guide new users to activation with targeted email sequences. Behavior-triggered emails outperform time-based schedules.
|
||||
|
||||
### 115. Win-back Emails
|
||||
Re-engage churned users with compelling reasons to return. New features, improvements, or offers reignite interest.
|
||||
|
||||
### 116. Trial Reactivation
|
||||
Expired trials aren't lost causes. Targeted campaigns highlighting new value can recover abandoned trials.
|
||||
|
||||
---
|
||||
|
||||
## Partnerships & Programs
|
||||
|
||||
### 9. Affiliate Discovery Through Backlinks
|
||||
Find potential affiliates by analyzing who links to competitors. Sites already promoting similar products may welcome affiliate relationships.
|
||||
|
||||
### 27. Influencer Whitelisting
|
||||
Run ads through influencer accounts for authentic reach. Whitelisting combines influencer credibility with paid targeting.
|
||||
|
||||
### 33. Reseller Programs
|
||||
Enable agencies and service providers to resell your product. White-label options create invested distribution partners.
|
||||
|
||||
### 37. Expert Networks
|
||||
Build networks of certified experts who implement your product. Experts extend your reach while ensuring quality implementations.
|
||||
|
||||
### 50. Newsletter Swaps
|
||||
Exchange promotional mentions with complementary newsletters. Access each other's audiences without advertising costs.
|
||||
|
||||
### 51. Article Quotes
|
||||
Contribute expert quotes to journalists and publications. Tools like HARO connect experts with writers seeking sources.
|
||||
|
||||
### 77. Pixel Sharing
|
||||
Partner with complementary companies to share remarketing audiences. Expand reach through strategic data partnerships.
|
||||
|
||||
### 78. Shared Slack Channels
|
||||
Create shared channels with partners and customers. Direct communication lines strengthen relationships.
|
||||
|
||||
### 97. Affiliate Program
|
||||
Structured commission programs for referrers. Affiliates become motivated salespeople earning from successful referrals.
|
||||
|
||||
### 98. Integration Marketing
|
||||
Joint marketing with integration partners. Combined audiences and shared promotion amplify reach for both products.
|
||||
|
||||
### 99. Community Sponsorship
|
||||
Sponsor relevant communities, newsletters, or publications. Aligned sponsorships build brand awareness with target audiences.
|
||||
|
||||
---
|
||||
|
||||
## Events & Speaking
|
||||
|
||||
### 15. Live Webinars
|
||||
Educational webinars demonstrate expertise while generating leads. Interactive formats create engagement and urgency.
|
||||
|
||||
### 53. Virtual Summits
|
||||
Multi-speaker online events attract audiences through varied perspectives. Summit speakers promote to their audiences, amplifying reach.
|
||||
|
||||
### 87. Roadshows
|
||||
Take your product on the road to meet customers directly. Regional events create personal connections at scale.
|
||||
|
||||
### 90. Local Meetups
|
||||
Host or attend local meetups in key markets. In-person connections create stronger relationships than digital alone.
|
||||
|
||||
### 91. Meetup Sponsorship
|
||||
Sponsor relevant meetups to reach engaged local audiences. Food, venue, or swag sponsorships generate goodwill.
|
||||
|
||||
### 103. Conference Speaking
|
||||
Speak at industry conferences to reach engaged audiences. Presentations showcase expertise while generating leads.
|
||||
|
||||
### 126. Conferences
|
||||
Host your own conference to become the center of your industry. User conferences strengthen communities and generate content.
|
||||
|
||||
### 132. Conference Sponsorship
|
||||
Sponsor relevant conferences for brand visibility. Booth presence, speaking slots, and attendee lists justify investment.
|
||||
|
||||
---
|
||||
|
||||
## PR & Media
|
||||
|
||||
### 8. Media Acquisitions as Marketing
|
||||
Acquire newsletters, podcasts, or publications in your space. Owned media provides direct access to engaged audiences.
|
||||
|
||||
### 52. Press Coverage
|
||||
Pitch newsworthy stories to relevant publications. Launches, funding, data, and trends create press opportunities.
|
||||
|
||||
### 84. Fundraising PR
|
||||
Leverage funding announcements for press coverage. Rounds signal validation and create natural news hooks.
|
||||
|
||||
### 118. Documentaries
|
||||
Create documentary content exploring your industry or customers. Long-form storytelling builds deep connection and differentiation.
|
||||
|
||||
---
|
||||
|
||||
## Launches & Promotions
|
||||
|
||||
### 21. Black Friday Promotions
|
||||
Annual deals create urgency and acquisition spikes. Promotional periods capture deal-seekers who become long-term customers.
|
||||
|
||||
### 22. Product Hunt Launch
|
||||
Structured Product Hunt launches reach early adopters. Preparation, timing, and community engagement drive successful launches.
|
||||
|
||||
### 23. Early-Access Referrals
|
||||
Reward referrals with earlier access during launches. Waitlist referral programs create viral anticipation.
|
||||
|
||||
### 44. New Year Promotions
|
||||
New Year brings fresh budgets and goal-setting energy. Promotional timing aligned with renewal mindsets increases conversion.
|
||||
|
||||
### 54. Early Access Pricing
|
||||
Launch with discounted early access tiers. Early supporters get deals while you build testimonials and feedback.
|
||||
|
||||
### 58. Product Hunt Alternatives
|
||||
Launch on alternatives to Product Hunt—BetaList, Launching Next, AlternativeTo. Multiple launch platforms expand reach.
|
||||
|
||||
### 59. Twitter Giveaways
|
||||
Engagement-boosting giveaways that require follows, retweets, or tags. Giveaways grow following while generating buzz.
|
||||
|
||||
### 109. Giveaways
|
||||
Strategic giveaways attract attention and capture leads. Product giveaways, partner prizes, or experience rewards create engagement.
|
||||
|
||||
### 119. Vacation Giveaways
|
||||
Grand prize giveaways generate massive engagement. Dream vacation packages motivate sharing and participation.
|
||||
|
||||
### 140. Lifetime Deals
|
||||
One-time payment deals generate cash and users. Lifetime deal platforms reach deal-hunting audiences willing to pay upfront.
|
||||
|
||||
---
|
||||
|
||||
## Product-Led Growth
|
||||
|
||||
### 16. Powered By Marketing
|
||||
"Powered by [Your Product]" badges on customer output create free impressions. Every customer becomes a marketing channel.
|
||||
|
||||
### 19. Free Migrations
|
||||
Offer free migration services from competitors. Reduce switching friction while capturing users ready to leave.
|
||||
|
||||
### 20. Contract Buyouts
|
||||
Pay to exit competitor contracts. Dramatic commitment removes the final barrier for locked-in prospects.
|
||||
|
||||
### 32. One-Click Registration
|
||||
Minimize signup friction with one-click OAuth options. Pre-filled forms and instant access increase conversion.
|
||||
|
||||
### 69. In-App Upsells
|
||||
Strategic upgrade prompts within the product experience. Contextual upsells at usage limits or feature attempts convert best.
|
||||
|
||||
### 71. Newsletter Referrals
|
||||
Built-in referral programs for newsletters and content. Easy sharing mechanisms turn subscribers into promoters.
|
||||
|
||||
### 75. Viral Loops
|
||||
Product mechanics that naturally encourage sharing. Collaboration features, public outputs, or referral incentives create organic growth.
|
||||
|
||||
### 114. Offboarding Flows
|
||||
Optimize cancellation flows to retain or learn. Exit surveys, save offers, and pause options reduce churn.
|
||||
|
||||
### 124. Concierge Setup
|
||||
White-glove onboarding for high-value accounts. Personal setup assistance increases activation and retention.
|
||||
|
||||
### 127. Onboarding Optimization
|
||||
Continuous improvement of the new user experience. Faster time-to-value increases conversion and retention.
|
||||
|
||||
---
|
||||
|
||||
## Content Formats
|
||||
|
||||
### 1. Playlists as Marketing
|
||||
Create Spotify playlists for your audience—productivity playlists, work music, industry-themed collections. Daily listening touchpoints build brand affinity.
|
||||
|
||||
### 46. Template Marketing
|
||||
Offer free templates users can immediately use. Templates in your product create habit and dependency while showcasing capabilities.
|
||||
|
||||
### 49. Graphic Novel Marketing
|
||||
Transform complex stories into visual narratives. Graphic novels stand out and make abstract concepts tangible.
|
||||
|
||||
### 65. Promo Videos
|
||||
High-quality promotional videos showcase your product professionally. Invest in production value for shareable, memorable content.
|
||||
|
||||
### 81. Industry Interviews
|
||||
Interview customers, experts, and thought leaders. Interview content builds relationships while creating valuable assets.
|
||||
|
||||
### 89. Social Screenshots
|
||||
Design shareable screenshot templates for social proof. Make it easy for customers to share wins and testimonials.
|
||||
|
||||
### 101. Online Courses
|
||||
Educational courses establish authority while generating leads. Free courses attract learners; paid courses create revenue.
|
||||
|
||||
### 102. Book Marketing
|
||||
Author a book establishing expertise in your domain. Books create credibility, speaking opportunities, and media coverage.
|
||||
|
||||
### 111. Annual Reports
|
||||
Publish annual reports showcasing industry data and trends. Original research becomes a linkable, quotable reference.
|
||||
|
||||
### 120. End of Year Wraps
|
||||
Personalized year-end summaries users want to share. "Spotify Wrapped" style reports turn data into social content.
|
||||
|
||||
### 121. Podcasts
|
||||
Launch a podcast reaching audiences during commutes and workouts. Regular audio content builds intimate audience relationships.
|
||||
|
||||
### 63. Changelogs
|
||||
Public changelogs showcase product momentum. Regular updates demonstrate active development and responsiveness.
|
||||
|
||||
### 112. Public Demos
|
||||
Live product demonstrations showing real usage. Transparent demos build trust and answer questions in real-time.
|
||||
|
||||
---
|
||||
|
||||
## Unconventional & Creative
|
||||
|
||||
### 6. Awards as Marketing
|
||||
Create industry awards positioning your brand as tastemaker. Award programs attract applications, sponsors, and press coverage.
|
||||
|
||||
### 10. Challenges as Marketing
|
||||
Launch viral challenges that spread organically. Creative challenges generate user content and social sharing.
|
||||
|
||||
### 11. Reality TV Marketing
|
||||
Create reality-show style content following real customers. Documentary competition formats create engaging narratives.
|
||||
|
||||
### 12. Controversy as Marketing
|
||||
Strategic positioning against industry norms. Contrarian takes generate attention and discussion.
|
||||
|
||||
### 13. Moneyball Marketing
|
||||
Data-driven marketing finding undervalued channels and tactics. Analytics identify opportunities competitors overlook.
|
||||
|
||||
### 14. Curation as Marketing
|
||||
Curate valuable resources for your audience. Directories, lists, and collections provide value while building authority.
|
||||
|
||||
### 29. Grants as Marketing
|
||||
Offer grants to customers or community members. Grant programs generate applications, PR, and goodwill.
|
||||
|
||||
### 34. Product Competitions
|
||||
Sponsor competitions using your product. Hackathons, design contests, and challenges showcase capabilities while engaging users.
|
||||
|
||||
### 35. Cameo Marketing
|
||||
Use Cameo celebrities for personalized marketing messages. Unexpected celebrity endorsements generate buzz and shares.
|
||||
|
||||
### 83. OOH Advertising
|
||||
Out-of-home advertising—billboards, transit ads, and placements. Physical presence in key locations builds brand awareness.
|
||||
|
||||
### 125. Marketing Stunts
|
||||
Bold, attention-grabbing marketing moments. Well-executed stunts generate press coverage and social sharing.
|
||||
|
||||
### 128. Guerrilla Marketing
|
||||
Unconventional, low-cost marketing in unexpected places. Creative guerrilla tactics stand out from traditional advertising.
|
||||
|
||||
### 136. Humor Marketing
|
||||
Use humor to stand out and create memorability. Funny content gets shared and builds brand personality.
|
||||
|
||||
---
|
||||
|
||||
## Platforms & Marketplaces
|
||||
|
||||
### 24. Open Source as Marketing
|
||||
Open-source components or tools build developer goodwill. Open source creates community, contributions, and credibility.
|
||||
|
||||
### 61. App Store Optimization
|
||||
Optimize app store listings for discoverability. Keywords, screenshots, and reviews drive organic app installs.
|
||||
|
||||
### 86. App Marketplaces
|
||||
List in relevant app marketplaces and directories. Salesforce AppExchange, Shopify App Store, and similar platforms provide distribution.
|
||||
|
||||
### 95. YouTube Reviews
|
||||
Get YouTubers to review your product. Authentic reviews reach engaged audiences and create lasting content.
|
||||
|
||||
### 96. YouTube Channel
|
||||
Build a YouTube presence with tutorials, updates, and thought leadership. Video content compounds in value over time.
|
||||
|
||||
### 108. Source Platforms
|
||||
Submit to platforms that aggregate tools and products. G2, Capterra, GetApp, and similar directories drive discovery.
|
||||
|
||||
### 88. Review Sites
|
||||
Actively manage presence on review platforms. Reviews influence purchase decisions; actively request and respond to them.
|
||||
|
||||
### 100. Live Audio
|
||||
Host live audio discussions on Twitter Spaces, Clubhouse, or LinkedIn Audio. Real-time conversation creates intimate engagement.
|
||||
|
||||
---
|
||||
|
||||
## International & Localization
|
||||
|
||||
### 133. International Expansion
|
||||
Expand to new geographic markets. Localization, partnerships, and regional marketing unlock new growth.
|
||||
|
||||
### 134. Price Localization
|
||||
Adjust pricing for local purchasing power. Localized pricing increases conversion in price-sensitive markets.
|
||||
|
||||
---
|
||||
|
||||
## Developer & Technical
|
||||
|
||||
### 104. Investor Marketing
|
||||
Market to investors for downstream portfolio introductions. Investors recommend tools to their portfolio companies.
|
||||
|
||||
### 123. Certifications
|
||||
Create certification programs validating expertise. Certifications create invested advocates while generating training revenue.
|
||||
|
||||
### 131. Support as Marketing
|
||||
Turn support interactions into marketing opportunities. Exceptional support creates stories customers share.
|
||||
|
||||
### 135. Developer Relations
|
||||
Build relationships with developer communities. DevRel creates advocates who recommend your product to peers.
|
||||
|
||||
---
|
||||
|
||||
## Audience-Specific
|
||||
|
||||
### 26. Two-Sided Referrals
|
||||
Reward both referrer and referred in referral programs. Dual incentives motivate sharing while welcoming new users.
|
||||
|
||||
### 45. Podcast Tours
|
||||
Guest on multiple podcasts reaching your target audience. Podcast tours create compounding awareness across shows.
|
||||
|
||||
### 47. Customer Language
|
||||
Use the exact words your customers use. Mining reviews, support tickets, and interviews for language that resonates.
|
||||
|
||||
---
|
||||
|
||||
## Implementation Tips
|
||||
|
||||
When suggesting ideas, consider:
|
||||
|
||||
**By Stage:**
|
||||
- Pre-launch: Waitlist referrals, early access, Product Hunt prep
|
||||
- Early stage: Content, SEO, community, founder-led sales
|
||||
- Growth stage: Paid acquisition, partnerships, events
|
||||
- Scale: Brand, international, acquisitions
|
||||
|
||||
**By Budget:**
|
||||
- Free: Content, SEO, community, social media
|
||||
- Low budget: Targeted ads, sponsorships, tools
|
||||
- Medium budget: Events, partnerships, PR
|
||||
- High budget: Acquisitions, conferences, brand campaigns
|
||||
|
||||
**By Timeline:**
|
||||
- Quick wins: Ads, email, social posts
|
||||
- Medium-term: Content, SEO, community building
|
||||
- Long-term: Brand, thought leadership, platform effects
|
||||
|
||||
---
|
||||
|
||||
## Questions to Ask
|
||||
|
||||
If you need more context:
|
||||
1. What's your product and who's your target customer?
|
||||
2. What's your current stage and main growth goal?
|
||||
3. What's your marketing budget and team size?
|
||||
4. What have you already tried that worked or didn't?
|
||||
5. What are your competitors doing that you admire or want to counter?
|
||||
|
||||
---
|
||||
|
||||
## Output Format
|
||||
|
||||
When recommending ideas:
|
||||
|
||||
**For each recommended idea:**
|
||||
- **Idea name**: One-line description
|
||||
- **Why it fits**: Connection to their situation
|
||||
- **How to start**: First 2-3 implementation steps
|
||||
- **Expected outcome**: What success looks like
|
||||
- **Resources needed**: Time, budget, skills required
|
||||
|
||||
---
|
||||
|
||||
## Related Skills
|
||||
|
||||
- **programmatic-seo**: For scaling SEO content (#40)
|
||||
- **competitor-alternatives**: For comparison pages (#2)
|
||||
- **email-sequence**: For email marketing tactics
|
||||
- **free-tool-strategy**: For engineering as marketing (#30)
|
||||
- **page-cro**: For landing page optimization
|
||||
- **ab-test-setup**: For testing marketing experiments
|
||||
451
skills/marketing-psychology/SKILL.md
Normal file
451
skills/marketing-psychology/SKILL.md
Normal file
@@ -0,0 +1,451 @@
|
||||
---
|
||||
name: marketing-psychology
|
||||
description: "When the user wants to apply psychological principles, mental models, or behavioral science to marketing. Also use when the user mentions 'psychology,' 'mental models,' 'cognitive bias,' 'persuasion,' 'behavioral science,' 'why people buy,' 'decision-making,' or 'consumer behavior.' This skill provides 70+ mental models organized for marketing application."
|
||||
---
|
||||
|
||||
# Marketing Psychology & Mental Models
|
||||
|
||||
You are an expert in applying psychological principles and mental models to marketing. Your goal is to help users understand why people buy, how to influence behavior ethically, and how to make better marketing decisions.
|
||||
|
||||
## How to Use This Skill
|
||||
|
||||
Mental models are thinking tools that help you make better decisions, understand customer behavior, and create more effective marketing. When helping users:
|
||||
|
||||
1. Identify which mental models apply to their situation
|
||||
2. Explain the psychology behind the model
|
||||
3. Provide specific marketing applications
|
||||
4. Suggest how to implement ethically
|
||||
|
||||
---
|
||||
|
||||
## Foundational Thinking Models
|
||||
|
||||
These models sharpen your strategy and help you solve the right problems.
|
||||
|
||||
### First Principles
|
||||
Break problems down to basic truths and build solutions from there. Instead of copying competitors, ask "why" repeatedly to find root causes. Use the 5 Whys technique to tunnel down to what really matters.
|
||||
|
||||
**Marketing application**: Don't assume you need content marketing because competitors do. Ask why you need it, what problem it solves, and whether there's a better solution.
|
||||
|
||||
### Jobs to Be Done
|
||||
People don't buy products—they "hire" them to get a job done. Focus on the outcome customers want, not features.
|
||||
|
||||
**Marketing application**: A drill buyer doesn't want a drill—they want a hole. Frame your product around the job it accomplishes, not its specifications.
|
||||
|
||||
### Circle of Competence
|
||||
Know what you're good at and stay within it. Venture outside only with proper learning or expert help.
|
||||
|
||||
**Marketing application**: Don't chase every channel. Double down where you have genuine expertise and competitive advantage.
|
||||
|
||||
### Inversion
|
||||
Instead of asking "How do I succeed?", ask "What would guarantee failure?" Then avoid those things.
|
||||
|
||||
**Marketing application**: List everything that would make your campaign fail—confusing messaging, wrong audience, slow landing page—then systematically prevent each.
|
||||
|
||||
### Occam's Razor
|
||||
The simplest explanation is usually correct. Avoid overcomplicating strategies or attributing results to complex causes when simple ones suffice.
|
||||
|
||||
**Marketing application**: If conversions dropped, check the obvious first (broken form, page speed) before assuming complex attribution issues.
|
||||
|
||||
### Pareto Principle (80/20 Rule)
|
||||
Roughly 80% of results come from 20% of efforts. Identify and focus on the vital few.
|
||||
|
||||
**Marketing application**: Find the 20% of channels, customers, or content driving 80% of results. Cut or reduce the rest.
|
||||
|
||||
### Local vs. Global Optima
|
||||
A local optimum is the best solution nearby, but a global optimum is the best overall. Don't get stuck optimizing the wrong thing.
|
||||
|
||||
**Marketing application**: Optimizing email subject lines (local) won't help if email isn't the right channel (global). Zoom out before zooming in.
|
||||
|
||||
### Theory of Constraints
|
||||
Every system has one bottleneck limiting throughput. Find and fix that constraint before optimizing elsewhere.
|
||||
|
||||
**Marketing application**: If your funnel converts well but traffic is low, more conversion optimization won't help. Fix the traffic bottleneck first.
|
||||
|
||||
### Opportunity Cost
|
||||
Every choice has a cost—what you give up by not choosing alternatives. Consider what you're saying no to.
|
||||
|
||||
**Marketing application**: Time spent on a low-ROI channel is time not spent on high-ROI activities. Always compare against alternatives.
|
||||
|
||||
### Law of Diminishing Returns
|
||||
After a point, additional investment yields progressively smaller gains.
|
||||
|
||||
**Marketing application**: The 10th blog post won't have the same impact as the first. Know when to diversify rather than double down.
|
||||
|
||||
### Second-Order Thinking
|
||||
Consider not just immediate effects, but the effects of those effects.
|
||||
|
||||
**Marketing application**: A flash sale boosts revenue (first order) but may train customers to wait for discounts (second order).
|
||||
|
||||
### Map ≠ Territory
|
||||
Models and data represent reality but aren't reality itself. Don't confuse your analytics dashboard with actual customer experience.
|
||||
|
||||
**Marketing application**: Your customer persona is a useful model, but real customers are more complex. Stay in touch with actual users.
|
||||
|
||||
### Probabilistic Thinking
|
||||
Think in probabilities, not certainties. Estimate likelihoods and plan for multiple outcomes.
|
||||
|
||||
**Marketing application**: Don't bet everything on one campaign. Spread risk and plan for scenarios where your primary strategy underperforms.
|
||||
|
||||
### Barbell Strategy
|
||||
Combine extreme safety with small high-risk/high-reward bets. Avoid the mediocre middle.
|
||||
|
||||
**Marketing application**: Put 80% of budget into proven channels, 20% into experimental bets. Avoid moderate-risk, moderate-reward middle.
|
||||
|
||||
---
|
||||
|
||||
## Understanding Buyers & Human Psychology
|
||||
|
||||
These models explain how customers think, decide, and behave.
|
||||
|
||||
### Fundamental Attribution Error
|
||||
People attribute others' behavior to character, not circumstances. "They didn't buy because they're not serious" vs. "The checkout was confusing."
|
||||
|
||||
**Marketing application**: When customers don't convert, examine your process before blaming them. The problem is usually situational, not personal.
|
||||
|
||||
### Mere Exposure Effect
|
||||
People prefer things they've seen before. Familiarity breeds liking.
|
||||
|
||||
**Marketing application**: Consistent brand presence builds preference over time. Repetition across channels creates comfort and trust.
|
||||
|
||||
### Availability Heuristic
|
||||
People judge likelihood by how easily examples come to mind. Recent or vivid events seem more common.
|
||||
|
||||
**Marketing application**: Case studies and testimonials make success feel more achievable. Make positive outcomes easy to imagine.
|
||||
|
||||
### Confirmation Bias
|
||||
People seek information confirming existing beliefs and ignore contradictory evidence.
|
||||
|
||||
**Marketing application**: Understand what your audience already believes and align messaging accordingly. Fighting beliefs head-on rarely works.
|
||||
|
||||
### The Lindy Effect
|
||||
The longer something has survived, the longer it's likely to continue. Old ideas often outlast new ones.
|
||||
|
||||
**Marketing application**: Proven marketing principles (clear value props, social proof) outlast trendy tactics. Don't abandon fundamentals for fads.
|
||||
|
||||
### Mimetic Desire
|
||||
People want things because others want them. Desire is socially contagious.
|
||||
|
||||
**Marketing application**: Show that desirable people want your product. Waitlists, exclusivity, and social proof trigger mimetic desire.
|
||||
|
||||
### Sunk Cost Fallacy
|
||||
People continue investing in something because of past investment, even when it's no longer rational.
|
||||
|
||||
**Marketing application**: Know when to kill underperforming campaigns. Past spend shouldn't justify future spend if results aren't there.
|
||||
|
||||
### Endowment Effect
|
||||
People value things more once they own them.
|
||||
|
||||
**Marketing application**: Free trials, samples, and freemium models let customers "own" the product, making them reluctant to give it up.
|
||||
|
||||
### IKEA Effect
|
||||
People value things more when they've put effort into creating them.
|
||||
|
||||
**Marketing application**: Let customers customize, configure, or build something. Their investment increases perceived value and commitment.
|
||||
|
||||
### Zero-Price Effect
|
||||
Free isn't just a low price—it's psychologically different. "Free" triggers irrational preference.
|
||||
|
||||
**Marketing application**: Free tiers, free trials, and free shipping have disproportionate appeal. The jump from $1 to $0 is bigger than $2 to $1.
|
||||
|
||||
### Hyperbolic Discounting / Present Bias
|
||||
People strongly prefer immediate rewards over future ones, even when waiting is more rational.
|
||||
|
||||
**Marketing application**: Emphasize immediate benefits ("Start saving time today") over future ones ("You'll see ROI in 6 months").
|
||||
|
||||
### Status-Quo Bias
|
||||
People prefer the current state of affairs. Change requires effort and feels risky.
|
||||
|
||||
**Marketing application**: Reduce friction to switch. Make the transition feel safe and easy. "Import your data in one click."
|
||||
|
||||
### Default Effect
|
||||
People tend to accept pre-selected options. Defaults are powerful.
|
||||
|
||||
**Marketing application**: Pre-select the plan you want customers to choose. Opt-out beats opt-in for subscriptions (ethically applied).
|
||||
|
||||
### Paradox of Choice
|
||||
Too many options overwhelm and paralyze. Fewer choices often lead to more decisions.
|
||||
|
||||
**Marketing application**: Limit options. Three pricing tiers beat seven. Recommend a single "best for most" option.
|
||||
|
||||
### Goal-Gradient Effect
|
||||
People accelerate effort as they approach a goal. Progress visualization motivates action.
|
||||
|
||||
**Marketing application**: Show progress bars, completion percentages, and "almost there" messaging to drive completion.
|
||||
|
||||
### Peak-End Rule
|
||||
People judge experiences by the peak (best or worst moment) and the end, not the average.
|
||||
|
||||
**Marketing application**: Design memorable peaks (surprise upgrades, delightful moments) and strong endings (thank you pages, follow-up emails).
|
||||
|
||||
### Zeigarnik Effect
|
||||
Unfinished tasks occupy the mind more than completed ones. Open loops create tension.
|
||||
|
||||
**Marketing application**: "You're 80% done" creates pull to finish. Incomplete profiles, abandoned carts, and cliffhangers leverage this.
|
||||
|
||||
### Pratfall Effect
|
||||
Competent people become more likable when they show a small flaw. Perfection is less relatable.
|
||||
|
||||
**Marketing application**: Admitting a weakness ("We're not the cheapest, but...") can increase trust and differentiation.
|
||||
|
||||
### Curse of Knowledge
|
||||
Once you know something, you can't imagine not knowing it. Experts struggle to explain simply.
|
||||
|
||||
**Marketing application**: Your product seems obvious to you but confusing to newcomers. Test copy with people unfamiliar with your space.
|
||||
|
||||
### Mental Accounting
|
||||
People treat money differently based on its source or intended use, even though money is fungible.
|
||||
|
||||
**Marketing application**: Frame costs in favorable mental accounts. "$3/day" feels different than "$90/month" even though it's the same.
|
||||
|
||||
### Regret Aversion
|
||||
People avoid actions that might cause regret, even if the expected outcome is positive.
|
||||
|
||||
**Marketing application**: Address regret directly. Money-back guarantees, free trials, and "no commitment" messaging reduce regret fear.
|
||||
|
||||
### Bandwagon Effect / Social Proof
|
||||
People follow what others are doing. Popularity signals quality and safety.
|
||||
|
||||
**Marketing application**: Show customer counts, testimonials, logos, reviews, and "trending" indicators. Numbers create confidence.
|
||||
|
||||
---
|
||||
|
||||
## Influencing Behavior & Persuasion
|
||||
|
||||
These models help you ethically influence customer decisions.
|
||||
|
||||
### Reciprocity Principle
|
||||
People feel obligated to return favors. Give first, and people want to give back.
|
||||
|
||||
**Marketing application**: Free content, free tools, and generous free tiers create reciprocal obligation. Give value before asking for anything.
|
||||
|
||||
### Commitment & Consistency
|
||||
Once people commit to something, they want to stay consistent with that commitment.
|
||||
|
||||
**Marketing application**: Get small commitments first (email signup, free trial). People who've taken one step are more likely to take the next.
|
||||
|
||||
### Authority Bias
|
||||
People defer to experts and authority figures. Credentials and expertise create trust.
|
||||
|
||||
**Marketing application**: Feature expert endorsements, certifications, "featured in" logos, and thought leadership content.
|
||||
|
||||
### Liking / Similarity Bias
|
||||
People say yes to those they like and those similar to themselves.
|
||||
|
||||
**Marketing application**: Use relatable spokespeople, founder stories, and community language. "Built by marketers for marketers" signals similarity.
|
||||
|
||||
### Unity Principle
|
||||
Shared identity drives influence. "One of us" is powerful.
|
||||
|
||||
**Marketing application**: Position your brand as part of the customer's tribe. Use insider language and shared values.
|
||||
|
||||
### Scarcity / Urgency Heuristic
|
||||
Limited availability increases perceived value. Scarcity signals desirability.
|
||||
|
||||
**Marketing application**: Limited-time offers, low-stock warnings, and exclusive access create urgency. Only use when genuine.
|
||||
|
||||
### Foot-in-the-Door Technique
|
||||
Start with a small request, then escalate. Compliance with small requests leads to compliance with larger ones.
|
||||
|
||||
**Marketing application**: Free trial → paid plan → annual plan → enterprise. Each step builds on the last.
|
||||
|
||||
### Door-in-the-Face Technique
|
||||
Start with an unreasonably large request, then retreat to what you actually want. The contrast makes the second request seem reasonable.
|
||||
|
||||
**Marketing application**: Show enterprise pricing first, then reveal the affordable starter plan. The contrast makes it feel like a deal.
|
||||
|
||||
### Loss Aversion / Prospect Theory
|
||||
Losses feel roughly twice as painful as equivalent gains feel good. People will work harder to avoid losing than to gain.
|
||||
|
||||
**Marketing application**: Frame in terms of what they'll lose by not acting. "Don't miss out" beats "You could gain."
|
||||
|
||||
### Anchoring Effect
|
||||
The first number people see heavily influences subsequent judgments.
|
||||
|
||||
**Marketing application**: Show the higher price first (original price, competitor price, enterprise tier) to anchor expectations.
|
||||
|
||||
### Decoy Effect
|
||||
Adding a third, inferior option makes one of the original two look better.
|
||||
|
||||
**Marketing application**: A "decoy" pricing tier that's clearly worse value makes your preferred tier look like the obvious choice.
|
||||
|
||||
### Framing Effect
|
||||
How something is presented changes how it's perceived. Same facts, different frames.
|
||||
|
||||
**Marketing application**: "90% success rate" vs. "10% failure rate" are identical but feel different. Frame positively.
|
||||
|
||||
### Contrast Effect
|
||||
Things seem different depending on what they're compared to.
|
||||
|
||||
**Marketing application**: Show the "before" state clearly. The contrast with your "after" makes improvements vivid.
|
||||
|
||||
---
|
||||
|
||||
## Pricing Psychology
|
||||
|
||||
These models specifically address how people perceive and respond to prices.
|
||||
|
||||
### Charm Pricing / Left-Digit Effect
|
||||
Prices ending in 9 seem significantly lower than the next round number. $99 feels much cheaper than $100.
|
||||
|
||||
**Marketing application**: Use .99 or .95 endings for value-focused products. The left digit dominates perception.
|
||||
|
||||
### Rounded-Price (Fluency) Effect
|
||||
Round numbers feel premium and are easier to process. $100 signals quality; $99 signals value.
|
||||
|
||||
**Marketing application**: Use round prices for premium products ($500/month), charm prices for value products ($497/month).
|
||||
|
||||
### Rule of 100
|
||||
For prices under $100, percentage discounts seem larger ("20% off"). For prices over $100, absolute discounts seem larger ("$50 off").
|
||||
|
||||
**Marketing application**: $80 product: "20% off" beats "$16 off." $500 product: "$100 off" beats "20% off."
|
||||
|
||||
### Price Relativity / Good-Better-Best
|
||||
People judge prices relative to options presented. A middle tier seems reasonable between cheap and expensive.
|
||||
|
||||
**Marketing application**: Three tiers where the middle is your target. The expensive tier makes it look reasonable; the cheap tier provides an anchor.
|
||||
|
||||
### Mental Accounting (Pricing)
|
||||
Framing the same price differently changes perception.
|
||||
|
||||
**Marketing application**: "$1/day" feels cheaper than "$30/month." "Less than your morning coffee" reframes the expense.
|
||||
|
||||
---
|
||||
|
||||
## Design & Delivery Models
|
||||
|
||||
These models help you design effective marketing systems.
|
||||
|
||||
### Hick's Law
|
||||
Decision time increases with the number and complexity of choices. More options = slower decisions = more abandonment.
|
||||
|
||||
**Marketing application**: Simplify choices. One clear CTA beats three. Fewer form fields beat more.
|
||||
|
||||
### AIDA Funnel
|
||||
Attention → Interest → Desire → Action. The classic customer journey model.
|
||||
|
||||
**Marketing application**: Structure pages and campaigns to move through each stage. Capture attention before building desire.
|
||||
|
||||
### Rule of 7
|
||||
Prospects need roughly 7 touchpoints before converting. One ad rarely converts; sustained presence does.
|
||||
|
||||
**Marketing application**: Build multi-touch campaigns across channels. Retargeting, email sequences, and consistent presence compound.
|
||||
|
||||
### Nudge Theory / Choice Architecture
|
||||
Small changes in how choices are presented significantly influence decisions.
|
||||
|
||||
**Marketing application**: Default selections, strategic ordering, and friction reduction guide behavior without restricting choice.
|
||||
|
||||
### BJ Fogg Behavior Model
|
||||
Behavior = Motivation × Ability × Prompt. All three must be present for action.
|
||||
|
||||
**Marketing application**: High motivation but hard to do = won't happen. Easy to do but no prompt = won't happen. Design for all three.
|
||||
|
||||
### EAST Framework
|
||||
Make desired behaviors: Easy, Attractive, Social, Timely.
|
||||
|
||||
**Marketing application**: Reduce friction (easy), make it appealing (attractive), show others doing it (social), ask at the right moment (timely).
|
||||
|
||||
### COM-B Model
|
||||
Behavior requires: Capability, Opportunity, Motivation.
|
||||
|
||||
**Marketing application**: Can they do it (capability)? Is the path clear (opportunity)? Do they want to (motivation)? Address all three.
|
||||
|
||||
### Activation Energy
|
||||
The initial energy required to start something. High activation energy prevents action even if the task is easy overall.
|
||||
|
||||
**Marketing application**: Reduce starting friction. Pre-fill forms, offer templates, show quick wins. Make the first step trivially easy.
|
||||
|
||||
### North Star Metric
|
||||
One metric that best captures the value you deliver to customers. Focus creates alignment.
|
||||
|
||||
**Marketing application**: Identify your North Star (active users, completed projects, revenue per customer) and align all efforts toward it.
|
||||
|
||||
### The Cobra Effect
|
||||
When incentives backfire and produce the opposite of intended results.
|
||||
|
||||
**Marketing application**: Test incentive structures. A referral bonus might attract low-quality referrals gaming the system.
|
||||
|
||||
---
|
||||
|
||||
## Growth & Scaling Models
|
||||
|
||||
These models explain how marketing compounds and scales.
|
||||
|
||||
### Feedback Loops
|
||||
Output becomes input, creating cycles. Positive loops accelerate growth; negative loops create decline.
|
||||
|
||||
**Marketing application**: Build virtuous cycles: more users → more content → better SEO → more users. Identify and strengthen positive loops.
|
||||
|
||||
### Compounding
|
||||
Small, consistent gains accumulate into large results over time. Early gains matter most.
|
||||
|
||||
**Marketing application**: Consistent content, SEO, and brand building compound. Start early; benefits accumulate exponentially.
|
||||
|
||||
### Network Effects
|
||||
A product becomes more valuable as more people use it.
|
||||
|
||||
**Marketing application**: Design features that improve with more users: shared workspaces, integrations, marketplaces, communities.
|
||||
|
||||
### Flywheel Effect
|
||||
Sustained effort creates momentum that eventually maintains itself. Hard to start, easy to maintain.
|
||||
|
||||
**Marketing application**: Content → traffic → leads → customers → case studies → more content. Each element powers the next.
|
||||
|
||||
### Switching Costs
|
||||
The price (time, money, effort, data) of changing to a competitor. High switching costs create retention.
|
||||
|
||||
**Marketing application**: Increase switching costs ethically: integrations, data accumulation, workflow customization, team adoption.
|
||||
|
||||
### Exploration vs. Exploitation
|
||||
Balance trying new things (exploration) with optimizing what works (exploitation).
|
||||
|
||||
**Marketing application**: Don't abandon working channels for shiny new ones, but allocate some budget to experiments.
|
||||
|
||||
### Critical Mass / Tipping Point
|
||||
The threshold after which growth becomes self-sustaining.
|
||||
|
||||
**Marketing application**: Focus resources on reaching critical mass in one segment before expanding. Depth before breadth.
|
||||
|
||||
### Survivorship Bias
|
||||
Focusing on successes while ignoring failures that aren't visible.
|
||||
|
||||
**Marketing application**: Study failed campaigns, not just successful ones. The viral hit you're copying had 99 failures you didn't see.
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
When facing a marketing challenge, consider:
|
||||
|
||||
| Challenge | Relevant Models |
|
||||
|-----------|-----------------|
|
||||
| Low conversions | Hick's Law, Activation Energy, BJ Fogg, Friction |
|
||||
| Price objections | Anchoring, Framing, Mental Accounting, Loss Aversion |
|
||||
| Building trust | Authority, Social Proof, Reciprocity, Pratfall Effect |
|
||||
| Increasing urgency | Scarcity, Loss Aversion, Zeigarnik Effect |
|
||||
| Retention/churn | Endowment Effect, Switching Costs, Status-Quo Bias |
|
||||
| Growth stalling | Theory of Constraints, Local vs Global Optima, Compounding |
|
||||
| Decision paralysis | Paradox of Choice, Default Effect, Nudge Theory |
|
||||
| Onboarding | Goal-Gradient, IKEA Effect, Commitment & Consistency |
|
||||
|
||||
---
|
||||
|
||||
## Questions to Ask
|
||||
|
||||
If you need more context:
|
||||
1. What specific behavior are you trying to influence?
|
||||
2. What does your customer believe before encountering your marketing?
|
||||
3. Where in the journey (awareness → consideration → decision) is this?
|
||||
4. What's currently preventing the desired action?
|
||||
5. Have you tested this with real customers?
|
||||
|
||||
---
|
||||
|
||||
## Related Skills
|
||||
|
||||
- **page-cro**: Apply psychology to page optimization
|
||||
- **copywriting**: Write copy using psychological principles
|
||||
- **popup-cro**: Use triggers and psychology in popups
|
||||
- **pricing-page optimization**: See page-cro for pricing psychology
|
||||
- **ab-test-setup**: Test psychological hypotheses
|
||||
212
skills/micro-saas-launcher/SKILL.md
Normal file
212
skills/micro-saas-launcher/SKILL.md
Normal file
@@ -0,0 +1,212 @@
|
||||
---
|
||||
name: micro-saas-launcher
|
||||
description: "Expert in launching small, focused SaaS products fast - the indie hacker approach to building profitable software. Covers idea validation, MVP development, pricing, launch strategies, and growing to sustainable revenue. Ship in weeks, not months. Use when: micro saas, indie hacker, small saas, side project, saas mvp."
|
||||
source: vibeship-spawner-skills (Apache 2.0)
|
||||
---
|
||||
|
||||
# Micro-SaaS Launcher
|
||||
|
||||
**Role**: Micro-SaaS Launch Architect
|
||||
|
||||
You ship fast and iterate. You know the difference between a side project
|
||||
and a business. You've seen what works in the indie hacker community. You
|
||||
help people go from idea to paying customers in weeks, not years. You
|
||||
focus on sustainable, profitable businesses - not unicorn hunting.
|
||||
|
||||
## Capabilities
|
||||
|
||||
- Micro-SaaS strategy
|
||||
- MVP scoping
|
||||
- Pricing strategies
|
||||
- Launch playbooks
|
||||
- Indie hacker patterns
|
||||
- Solo founder tech stack
|
||||
- Early traction
|
||||
- SaaS metrics
|
||||
|
||||
## Patterns
|
||||
|
||||
### Idea Validation
|
||||
|
||||
Validating before building
|
||||
|
||||
**When to use**: When starting a micro-SaaS
|
||||
|
||||
```javascript
|
||||
## Idea Validation
|
||||
|
||||
### The Validation Framework
|
||||
| Question | How to Answer |
|
||||
|----------|---------------|
|
||||
| Problem exists? | Talk to 5+ potential users |
|
||||
| People pay? | Pre-sell or find competitors |
|
||||
| You can build? | Can MVP ship in 2 weeks? |
|
||||
| You can reach them? | Distribution channel exists? |
|
||||
|
||||
### Quick Validation Methods
|
||||
1. **Landing page test**
|
||||
- Build landing page
|
||||
- Drive traffic (ads, community)
|
||||
- Measure signups/interest
|
||||
|
||||
2. **Pre-sale**
|
||||
- Sell before building
|
||||
- "Join waitlist for 50% off"
|
||||
- If no sales, pivot
|
||||
|
||||
3. **Competitor check**
|
||||
- Competitors = validation
|
||||
- No competitors = maybe no market
|
||||
- Find gap you can fill
|
||||
|
||||
### Red Flags
|
||||
- "Everyone needs this" (too broad)
|
||||
- No clear buyer (who pays?)
|
||||
- Requires marketplace dynamics
|
||||
- Needs massive scale to work
|
||||
|
||||
### Green Flags
|
||||
- Clear, specific pain point
|
||||
- People already paying for alternatives
|
||||
- You have domain expertise
|
||||
- Distribution channel access
|
||||
```
|
||||
|
||||
### MVP Speed Run
|
||||
|
||||
Ship MVP in 2 weeks
|
||||
|
||||
**When to use**: When building first version
|
||||
|
||||
```javascript
|
||||
## MVP Speed Run
|
||||
|
||||
### The Stack (Solo-Founder Optimized)
|
||||
| Component | Choice | Why |
|
||||
|-----------|--------|-----|
|
||||
| Frontend | Next.js | Full-stack, Vercel deploy |
|
||||
| Backend | Next.js API / Supabase | Fast, scalable |
|
||||
| Database | Supabase Postgres | Free tier, auth included |
|
||||
| Auth | Supabase / Clerk | Don't build auth |
|
||||
| Payments | Stripe | Industry standard |
|
||||
| Email | Resend / Loops | Transactional + marketing |
|
||||
| Hosting | Vercel | Free tier generous |
|
||||
|
||||
### Week 1: Core
|
||||
```
|
||||
Day 1-2: Auth + basic UI
|
||||
Day 3-4: Core feature (one thing)
|
||||
Day 5-6: Stripe integration
|
||||
Day 7: Polish and bug fixes
|
||||
```
|
||||
|
||||
### Week 2: Launch Ready
|
||||
```
|
||||
Day 1-2: Landing page
|
||||
Day 3: Email flows (welcome, etc.)
|
||||
Day 4: Legal (privacy, terms)
|
||||
Day 5: Final testing
|
||||
Day 6-7: Soft launch
|
||||
```
|
||||
|
||||
### What to Skip in MVP
|
||||
- Perfect design (good enough is fine)
|
||||
- All features (one core feature only)
|
||||
- Scale optimization (worry later)
|
||||
- Custom auth (use a service)
|
||||
- Multiple pricing tiers (start simple)
|
||||
```
|
||||
|
||||
### Pricing Strategy
|
||||
|
||||
Pricing your micro-SaaS
|
||||
|
||||
**When to use**: When setting prices
|
||||
|
||||
```javascript
|
||||
## Pricing Strategy
|
||||
|
||||
### Pricing Tiers for Micro-SaaS
|
||||
| Strategy | Best For |
|
||||
|----------|----------|
|
||||
| Single price | Simple tools, clear value |
|
||||
| Two tiers | Free/paid or Basic/Pro |
|
||||
| Three tiers | Most SaaS (Good/Better/Best) |
|
||||
| Usage-based | API products, variable use |
|
||||
|
||||
### Starting Price Framework
|
||||
```
|
||||
What's the alternative cost? (Competitor or manual work)
|
||||
Your price = 20-50% of alternative cost
|
||||
|
||||
Example:
|
||||
- Manual work takes 10 hours/month
|
||||
- 10 hours × $50/hour = $500 value
|
||||
- Price: $49-99/month
|
||||
```
|
||||
|
||||
### Common Micro-SaaS Prices
|
||||
| Type | Price Range |
|
||||
|------|-------------|
|
||||
| Simple tool | $9-29/month |
|
||||
| Pro tool | $29-99/month |
|
||||
| B2B tool | $49-299/month |
|
||||
| Lifetime deal | 3-5x monthly |
|
||||
|
||||
### Pricing Mistakes
|
||||
- Too cheap (undervalues, attracts bad customers)
|
||||
- Too complex (confuses buyers)
|
||||
- No free tier AND no trial (no way to try)
|
||||
- Charging too late (validate with money early)
|
||||
```
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
### ❌ Building in Secret
|
||||
|
||||
**Why bad**: No feedback loop.
|
||||
Building wrong thing.
|
||||
Wasted time.
|
||||
Fear of shipping.
|
||||
|
||||
**Instead**: Launch ugly MVP.
|
||||
Get feedback early.
|
||||
Build in public.
|
||||
Iterate based on users.
|
||||
|
||||
### ❌ Feature Creep
|
||||
|
||||
**Why bad**: Never ships.
|
||||
Dilutes focus.
|
||||
Confuses users.
|
||||
Delays revenue.
|
||||
|
||||
**Instead**: One core feature first.
|
||||
Ship, then iterate.
|
||||
Let users tell you what's missing.
|
||||
Say no to most requests.
|
||||
|
||||
### ❌ Pricing Too Low
|
||||
|
||||
**Why bad**: Undervalues your work.
|
||||
Attracts price-sensitive customers.
|
||||
Hard to run a business.
|
||||
Can't afford growth.
|
||||
|
||||
**Instead**: Price for value, not time.
|
||||
Start higher, discount if needed.
|
||||
B2B can pay more.
|
||||
Your time has value.
|
||||
|
||||
## ⚠️ Sharp Edges
|
||||
|
||||
| Issue | Severity | Solution |
|
||||
|-------|----------|----------|
|
||||
| Great product, no way to reach customers | high | ## Distribution First |
|
||||
| Building for market that can't/won't pay | high | ## Market Selection |
|
||||
| New signups leaving as fast as they come | high | ## Fixing Churn |
|
||||
| Pricing page confuses potential customers | medium | ## Simple Pricing |
|
||||
|
||||
## Related Skills
|
||||
|
||||
Works well with: `landing-page-design`, `backend`, `stripe`, `seo`
|
||||
597
skills/moodle-external-api-development/SKILL.md
Normal file
597
skills/moodle-external-api-development/SKILL.md
Normal file
@@ -0,0 +1,597 @@
|
||||
---
|
||||
name: moodle-external-api-development
|
||||
description: Create custom external web service APIs for Moodle LMS. Use when implementing web services for course management, user tracking, quiz operations, or custom plugin functionality. Covers parameter validation, database operations, error handling, service registration, and Moodle coding standards.
|
||||
---
|
||||
|
||||
# Moodle External API Development
|
||||
|
||||
This skill guides you through creating custom external web service APIs for Moodle LMS, following Moodle's external API framework and coding standards.
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
- Creating custom web services for Moodle plugins
|
||||
- Implementing REST/AJAX endpoints for course management
|
||||
- Building APIs for quiz operations, user tracking, or reporting
|
||||
- Exposing Moodle functionality to external applications
|
||||
- Developing mobile app backends using Moodle
|
||||
|
||||
## Core Architecture Pattern
|
||||
|
||||
Moodle external APIs follow a strict three-method pattern:
|
||||
|
||||
1. **`execute_parameters()`** - Defines input parameter structure
|
||||
2. **`execute()`** - Contains business logic
|
||||
3. **`execute_returns()`** - Defines return structure
|
||||
|
||||
## Step-by-Step Implementation
|
||||
|
||||
### Step 1: Create the External API Class File
|
||||
|
||||
**Location**: `/local/yourplugin/classes/external/your_api_name.php`
|
||||
|
||||
```php
|
||||
<?php
|
||||
namespace local_yourplugin\external;
|
||||
|
||||
defined('MOODLE_INTERNAL') || die();
|
||||
require_once("$CFG->libdir/externallib.php");
|
||||
|
||||
use external_api;
|
||||
use external_function_parameters;
|
||||
use external_single_structure;
|
||||
use external_value;
|
||||
|
||||
class your_api_name extends external_api {
|
||||
|
||||
// Three required methods will go here
|
||||
|
||||
}
|
||||
```
|
||||
|
||||
**Key Points**:
|
||||
- Class must extend `external_api`
|
||||
- Namespace follows: `local_pluginname\external` or `mod_modname\external`
|
||||
- Include the security check: `defined('MOODLE_INTERNAL') || die();`
|
||||
- Require externallib.php for base classes
|
||||
|
||||
### Step 2: Define Input Parameters
|
||||
|
||||
```php
|
||||
public static function execute_parameters() {
|
||||
return new external_function_parameters([
|
||||
'userid' => new external_value(PARAM_INT, 'User ID', VALUE_REQUIRED),
|
||||
'courseid' => new external_value(PARAM_INT, 'Course ID', VALUE_REQUIRED),
|
||||
'options' => new external_single_structure([
|
||||
'includedetails' => new external_value(PARAM_BOOL, 'Include details', VALUE_DEFAULT, false),
|
||||
'limit' => new external_value(PARAM_INT, 'Result limit', VALUE_DEFAULT, 10)
|
||||
], 'Options', VALUE_OPTIONAL)
|
||||
]);
|
||||
}
|
||||
```
|
||||
|
||||
**Common Parameter Types**:
|
||||
- `PARAM_INT` - Integers
|
||||
- `PARAM_TEXT` - Plain text (HTML stripped)
|
||||
- `PARAM_RAW` - Raw text (no cleaning)
|
||||
- `PARAM_BOOL` - Boolean values
|
||||
- `PARAM_FLOAT` - Floating point numbers
|
||||
- `PARAM_ALPHANUMEXT` - Alphanumeric with extended chars
|
||||
|
||||
**Structures**:
|
||||
- `external_value` - Single value
|
||||
- `external_single_structure` - Object with named fields
|
||||
- `external_multiple_structure` - Array of items
|
||||
|
||||
**Value Flags**:
|
||||
- `VALUE_REQUIRED` - Parameter must be provided
|
||||
- `VALUE_OPTIONAL` - Parameter is optional
|
||||
- `VALUE_DEFAULT, defaultvalue` - Optional with default
|
||||
|
||||
### Step 3: Implement Business Logic
|
||||
|
||||
```php
|
||||
public static function execute($userid, $courseid, $options = []) {
|
||||
global $DB, $USER;
|
||||
|
||||
// 1. Validate parameters
|
||||
$params = self::validate_parameters(self::execute_parameters(), [
|
||||
'userid' => $userid,
|
||||
'courseid' => $courseid,
|
||||
'options' => $options
|
||||
]);
|
||||
|
||||
// 2. Check permissions/capabilities
|
||||
$context = \context_course::instance($params['courseid']);
|
||||
self::validate_context($context);
|
||||
require_capability('moodle/course:view', $context);
|
||||
|
||||
// 3. Verify user access
|
||||
if ($params['userid'] != $USER->id) {
|
||||
require_capability('moodle/course:viewhiddenactivities', $context);
|
||||
}
|
||||
|
||||
// 4. Database operations
|
||||
$sql = "SELECT id, name, timecreated
|
||||
FROM {your_table}
|
||||
WHERE userid = :userid
|
||||
AND courseid = :courseid
|
||||
LIMIT :limit";
|
||||
|
||||
$records = $DB->get_records_sql($sql, [
|
||||
'userid' => $params['userid'],
|
||||
'courseid' => $params['courseid'],
|
||||
'limit' => $params['options']['limit']
|
||||
]);
|
||||
|
||||
// 5. Process and return data
|
||||
$results = [];
|
||||
foreach ($records as $record) {
|
||||
$results[] = [
|
||||
'id' => $record->id,
|
||||
'name' => $record->name,
|
||||
'timestamp' => $record->timecreated
|
||||
];
|
||||
}
|
||||
|
||||
return [
|
||||
'items' => $results,
|
||||
'count' => count($results)
|
||||
];
|
||||
}
|
||||
```
|
||||
|
||||
**Critical Steps**:
|
||||
1. **Always validate parameters** using `validate_parameters()`
|
||||
2. **Check context** using `validate_context()`
|
||||
3. **Verify capabilities** using `require_capability()`
|
||||
4. **Use parameterized queries** to prevent SQL injection
|
||||
5. **Return structured data** matching return definition
|
||||
|
||||
### Step 4: Define Return Structure
|
||||
|
||||
```php
|
||||
public static function execute_returns() {
|
||||
return new external_single_structure([
|
||||
'items' => new external_multiple_structure(
|
||||
new external_single_structure([
|
||||
'id' => new external_value(PARAM_INT, 'Item ID'),
|
||||
'name' => new external_value(PARAM_TEXT, 'Item name'),
|
||||
'timestamp' => new external_value(PARAM_INT, 'Creation time')
|
||||
])
|
||||
),
|
||||
'count' => new external_value(PARAM_INT, 'Total items')
|
||||
]);
|
||||
}
|
||||
```
|
||||
|
||||
**Return Structure Rules**:
|
||||
- Must match exactly what `execute()` returns
|
||||
- Use appropriate parameter types
|
||||
- Document each field with description
|
||||
- Nested structures allowed
|
||||
|
||||
### Step 5: Register the Service
|
||||
|
||||
**Location**: `/local/yourplugin/db/services.php`
|
||||
|
||||
```php
|
||||
<?php
|
||||
defined('MOODLE_INTERNAL') || die();
|
||||
|
||||
$functions = [
|
||||
'local_yourplugin_your_api_name' => [
|
||||
'classname' => 'local_yourplugin\external\your_api_name',
|
||||
'methodname' => 'execute',
|
||||
'classpath' => 'local/yourplugin/classes/external/your_api_name.php',
|
||||
'description' => 'Brief description of what this API does',
|
||||
'type' => 'read', // or 'write'
|
||||
'ajax' => true,
|
||||
'capabilities'=> 'moodle/course:view', // comma-separated if multiple
|
||||
'services' => [MOODLE_OFFICIAL_MOBILE_SERVICE] // Optional
|
||||
],
|
||||
];
|
||||
|
||||
$services = [
|
||||
'Your Plugin Web Service' => [
|
||||
'functions' => [
|
||||
'local_yourplugin_your_api_name'
|
||||
],
|
||||
'restrictedusers' => 0,
|
||||
'enabled' => 1
|
||||
]
|
||||
];
|
||||
```
|
||||
|
||||
**Service Registration Keys**:
|
||||
- `classname` - Full namespaced class name
|
||||
- `methodname` - Always 'execute'
|
||||
- `type` - 'read' (SELECT) or 'write' (INSERT/UPDATE/DELETE)
|
||||
- `ajax` - Set true for AJAX/REST access
|
||||
- `capabilities` - Required Moodle capabilities
|
||||
- `services` - Optional service bundles
|
||||
|
||||
### Step 6: Implement Error Handling & Logging
|
||||
|
||||
```php
|
||||
private static function log_debug($message) {
|
||||
global $CFG;
|
||||
$logdir = $CFG->dataroot . '/local_yourplugin';
|
||||
if (!file_exists($logdir)) {
|
||||
mkdir($logdir, 0777, true);
|
||||
}
|
||||
$debuglog = $logdir . '/api_debug.log';
|
||||
$timestamp = date('Y-m-d H:i:s');
|
||||
file_put_contents($debuglog, "[$timestamp] $message\n", FILE_APPEND | LOCK_EX);
|
||||
}
|
||||
|
||||
public static function execute($userid, $courseid) {
|
||||
global $DB;
|
||||
|
||||
try {
|
||||
self::log_debug("API called: userid=$userid, courseid=$courseid");
|
||||
|
||||
// Validate parameters
|
||||
$params = self::validate_parameters(self::execute_parameters(), [
|
||||
'userid' => $userid,
|
||||
'courseid' => $courseid
|
||||
]);
|
||||
|
||||
// Your logic here
|
||||
|
||||
self::log_debug("API completed successfully");
|
||||
return $result;
|
||||
|
||||
} catch (\invalid_parameter_exception $e) {
|
||||
self::log_debug("Parameter validation failed: " . $e->getMessage());
|
||||
throw $e;
|
||||
} catch (\moodle_exception $e) {
|
||||
self::log_debug("Moodle exception: " . $e->getMessage());
|
||||
throw $e;
|
||||
} catch (\Exception $e) {
|
||||
// Log detailed error info
|
||||
$lastsql = method_exists($DB, 'get_last_sql') ? $DB->get_last_sql() : '[N/A]';
|
||||
self::log_debug("Fatal error: " . $e->getMessage());
|
||||
self::log_debug("Last SQL: " . $lastsql);
|
||||
self::log_debug("Stack trace: " . $e->getTraceAsString());
|
||||
throw $e;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Error Handling Best Practices**:
|
||||
- Wrap logic in try-catch blocks
|
||||
- Log errors with timestamps and context
|
||||
- Capture SQL queries on database errors
|
||||
- Preserve stack traces for debugging
|
||||
- Re-throw exceptions after logging
|
||||
|
||||
## Advanced Patterns
|
||||
|
||||
### Complex Database Operations
|
||||
|
||||
```php
|
||||
// Transaction example
|
||||
$transaction = $DB->start_delegated_transaction();
|
||||
|
||||
try {
|
||||
// Insert record
|
||||
$recordid = $DB->insert_record('your_table', $dataobject);
|
||||
|
||||
// Update related records
|
||||
$DB->set_field('another_table', 'status', 1, ['recordid' => $recordid]);
|
||||
|
||||
// Commit transaction
|
||||
$transaction->allow_commit();
|
||||
} catch (\Exception $e) {
|
||||
$transaction->rollback($e);
|
||||
throw $e;
|
||||
}
|
||||
```
|
||||
|
||||
### Working with Course Modules
|
||||
|
||||
```php
|
||||
// Create course module
|
||||
$moduleid = $DB->get_field('modules', 'id', ['name' => 'quiz'], MUST_EXIST);
|
||||
|
||||
$cm = new \stdClass();
|
||||
$cm->course = $courseid;
|
||||
$cm->module = $moduleid;
|
||||
$cm->instance = 0; // Will be updated after activity creation
|
||||
$cm->visible = 1;
|
||||
$cm->groupmode = 0;
|
||||
$cmid = add_course_module($cm);
|
||||
|
||||
// Create activity instance (e.g., quiz)
|
||||
$quiz = new \stdClass();
|
||||
$quiz->course = $courseid;
|
||||
$quiz->name = 'My Quiz';
|
||||
$quiz->coursemodule = $cmid;
|
||||
// ... other quiz fields ...
|
||||
|
||||
$quizid = quiz_add_instance($quiz, null);
|
||||
|
||||
// Update course module with instance ID
|
||||
$DB->set_field('course_modules', 'instance', $quizid, ['id' => $cmid]);
|
||||
course_add_cm_to_section($courseid, $cmid, 0);
|
||||
```
|
||||
|
||||
### Access Restrictions (Groups/Availability)
|
||||
|
||||
```php
|
||||
// Restrict activity to specific user via group
|
||||
$groupname = 'activity_' . $activityid . '_user_' . $userid;
|
||||
|
||||
// Create or get group
|
||||
if (!$groupid = $DB->get_field('groups', 'id', ['courseid' => $courseid, 'name' => $groupname])) {
|
||||
$groupdata = (object)[
|
||||
'courseid' => $courseid,
|
||||
'name' => $groupname,
|
||||
'timecreated' => time(),
|
||||
'timemodified' => time()
|
||||
];
|
||||
$groupid = $DB->insert_record('groups', $groupdata);
|
||||
}
|
||||
|
||||
// Add user to group
|
||||
if (!$DB->record_exists('groups_members', ['groupid' => $groupid, 'userid' => $userid])) {
|
||||
$DB->insert_record('groups_members', (object)[
|
||||
'groupid' => $groupid,
|
||||
'userid' => $userid,
|
||||
'timeadded' => time()
|
||||
]);
|
||||
}
|
||||
|
||||
// Set availability condition
|
||||
$restriction = [
|
||||
'op' => '&',
|
||||
'show' => false,
|
||||
'c' => [
|
||||
[
|
||||
'type' => 'group',
|
||||
'id' => $groupid
|
||||
]
|
||||
],
|
||||
'showc' => [false]
|
||||
];
|
||||
|
||||
$DB->set_field('course_modules', 'availability', json_encode($restriction), ['id' => $cmid]);
|
||||
```
|
||||
|
||||
### Random Question Selection with Tags
|
||||
|
||||
```php
|
||||
private static function get_random_questions($categoryid, $tagname, $limit) {
|
||||
global $DB;
|
||||
|
||||
$sql = "SELECT q.id
|
||||
FROM {question} q
|
||||
INNER JOIN {question_versions} qv ON qv.questionid = q.id
|
||||
INNER JOIN {question_bank_entries} qbe ON qbe.id = qv.questionbankentryid
|
||||
INNER JOIN {question_categories} qc ON qc.id = qbe.questioncategoryid
|
||||
JOIN {tag_instance} ti ON ti.itemid = q.id
|
||||
JOIN {tag} t ON t.id = ti.tagid
|
||||
WHERE LOWER(t.name) = :tagname
|
||||
AND qc.id = :categoryid
|
||||
AND ti.itemtype = 'question'
|
||||
AND q.qtype = 'multichoice'";
|
||||
|
||||
$qids = $DB->get_fieldset_sql($sql, [
|
||||
'categoryid' => $categoryid,
|
||||
'tagname' => strtolower($tagname)
|
||||
]);
|
||||
|
||||
shuffle($qids);
|
||||
return array_slice($qids, 0, $limit);
|
||||
}
|
||||
```
|
||||
|
||||
## Testing Your API
|
||||
|
||||
### 1. Via Moodle Web Services Test Client
|
||||
|
||||
1. Enable web services: **Site administration > Advanced features**
|
||||
2. Enable REST protocol: **Site administration > Plugins > Web services > Manage protocols**
|
||||
3. Create service: **Site administration > Server > Web services > External services**
|
||||
4. Test function: **Site administration > Development > Web service test client**
|
||||
|
||||
### 2. Via curl
|
||||
|
||||
```bash
|
||||
# Get token first
|
||||
curl -X POST "https://yourmoodle.com/login/token.php" \
|
||||
-d "username=admin" \
|
||||
-d "password=yourpassword" \
|
||||
-d "service=moodle_mobile_app"
|
||||
|
||||
# Call your API
|
||||
curl -X POST "https://yourmoodle.com/webservice/rest/server.php" \
|
||||
-d "wstoken=YOUR_TOKEN" \
|
||||
-d "wsfunction=local_yourplugin_your_api_name" \
|
||||
-d "moodlewsrestformat=json" \
|
||||
-d "userid=2" \
|
||||
-d "courseid=3"
|
||||
```
|
||||
|
||||
### 3. Via JavaScript (AJAX)
|
||||
|
||||
```javascript
|
||||
require(['core/ajax'], function(ajax) {
|
||||
var promises = ajax.call([{
|
||||
methodname: 'local_yourplugin_your_api_name',
|
||||
args: {
|
||||
userid: 2,
|
||||
courseid: 3
|
||||
}
|
||||
}]);
|
||||
|
||||
promises[0].done(function(response) {
|
||||
console.log('Success:', response);
|
||||
}).fail(function(error) {
|
||||
console.error('Error:', error);
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
## Common Pitfalls & Solutions
|
||||
|
||||
### 1. "Function not found" Error
|
||||
**Solution**:
|
||||
- Purge caches: **Site administration > Development > Purge all caches**
|
||||
- Verify function name in services.php matches exactly
|
||||
- Check namespace and class name are correct
|
||||
|
||||
### 2. "Invalid parameter value detected"
|
||||
**Solution**:
|
||||
- Ensure parameter types match between definition and usage
|
||||
- Check required vs optional parameters
|
||||
- Validate nested structure definitions
|
||||
|
||||
### 3. SQL Injection Vulnerabilities
|
||||
**Solution**:
|
||||
- Always use placeholder parameters (`:paramname`)
|
||||
- Never concatenate user input into SQL strings
|
||||
- Use Moodle's database methods: `get_record()`, `get_records()`, etc.
|
||||
|
||||
### 4. Permission Denied Errors
|
||||
**Solution**:
|
||||
- Call `self::validate_context($context)` early in execute()
|
||||
- Check required capabilities match user's permissions
|
||||
- Verify user has role assignments in the context
|
||||
|
||||
### 5. Transaction Deadlocks
|
||||
**Solution**:
|
||||
- Keep transactions short
|
||||
- Always commit or rollback in finally blocks
|
||||
- Avoid nested transactions
|
||||
|
||||
## Debugging Checklist
|
||||
|
||||
- [ ] Check Moodle debug mode: **Site administration > Development > Debugging**
|
||||
- [ ] Review web services logs: **Site administration > Reports > Logs**
|
||||
- [ ] Check custom log files in `$CFG->dataroot/local_yourplugin/`
|
||||
- [ ] Verify database queries using `$DB->set_debug(true)`
|
||||
- [ ] Test with admin user to rule out permission issues
|
||||
- [ ] Clear browser cache and Moodle caches
|
||||
- [ ] Check PHP error logs on server
|
||||
|
||||
## Plugin Structure Checklist
|
||||
|
||||
```
|
||||
local/yourplugin/
|
||||
├── version.php # Plugin version and metadata
|
||||
├── db/
|
||||
│ ├── services.php # External service definitions
|
||||
│ └── access.php # Capability definitions (optional)
|
||||
├── classes/
|
||||
│ └── external/
|
||||
│ ├── your_api_name.php # External API implementation
|
||||
│ └── another_api.php # Additional APIs
|
||||
├── lang/
|
||||
│ └── en/
|
||||
│ └── local_yourplugin.php # Language strings
|
||||
└── tests/
|
||||
└── external_test.php # Unit tests (optional but recommended)
|
||||
```
|
||||
|
||||
## Examples from Real Implementation
|
||||
|
||||
### Simple Read API (Get Quiz Attempts)
|
||||
|
||||
```php
|
||||
<?php
|
||||
namespace local_userlog\external;
|
||||
|
||||
defined('MOODLE_INTERNAL') || die();
|
||||
require_once("$CFG->libdir/externallib.php");
|
||||
|
||||
use external_api;
|
||||
use external_function_parameters;
|
||||
use external_single_structure;
|
||||
use external_value;
|
||||
|
||||
class get_quiz_attempts extends external_api {
|
||||
public static function execute_parameters() {
|
||||
return new external_function_parameters([
|
||||
'userid' => new external_value(PARAM_INT, 'User ID'),
|
||||
'courseid' => new external_value(PARAM_INT, 'Course ID')
|
||||
]);
|
||||
}
|
||||
|
||||
public static function execute($userid, $courseid) {
|
||||
global $DB;
|
||||
|
||||
self::validate_parameters(self::execute_parameters(), [
|
||||
'userid' => $userid,
|
||||
'courseid' => $courseid
|
||||
]);
|
||||
|
||||
$sql = "SELECT COUNT(*) AS quiz_attempts
|
||||
FROM {quiz_attempts} qa
|
||||
JOIN {quiz} q ON qa.quiz = q.id
|
||||
WHERE qa.userid = :userid AND q.course = :courseid";
|
||||
|
||||
$attempts = $DB->get_field_sql($sql, [
|
||||
'userid' => $userid,
|
||||
'courseid' => $courseid
|
||||
]);
|
||||
|
||||
return ['quiz_attempts' => (int)$attempts];
|
||||
}
|
||||
|
||||
public static function execute_returns() {
|
||||
return new external_single_structure([
|
||||
'quiz_attempts' => new external_value(PARAM_INT, 'Total number of quiz attempts')
|
||||
]);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Complex Write API (Create Quiz from Categories)
|
||||
|
||||
See attached `create_quiz_from_categories.php` for a comprehensive example including:
|
||||
- Multiple database insertions
|
||||
- Course module creation
|
||||
- Quiz instance configuration
|
||||
- Random question selection with tags
|
||||
- Group-based access restrictions
|
||||
- Extensive error logging
|
||||
- Transaction management
|
||||
|
||||
## Quick Reference: Common Moodle Tables
|
||||
|
||||
| Table | Purpose |
|
||||
|-------|---------|
|
||||
| `{user}` | User accounts |
|
||||
| `{course}` | Courses |
|
||||
| `{course_modules}` | Activity instances in courses |
|
||||
| `{modules}` | Available activity types (quiz, forum, etc.) |
|
||||
| `{quiz}` | Quiz configurations |
|
||||
| `{quiz_attempts}` | Quiz attempt records |
|
||||
| `{question}` | Question bank |
|
||||
| `{question_categories}` | Question categories |
|
||||
| `{grade_items}` | Gradebook items |
|
||||
| `{grade_grades}` | Student grades |
|
||||
| `{groups}` | Course groups |
|
||||
| `{groups_members}` | Group memberships |
|
||||
| `{logstore_standard_log}` | Activity logs |
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [Moodle External API Documentation](https://moodledev.io/docs/5.2/apis/subsystems/external/functions)
|
||||
- [Moodle Coding Style](https://moodledev.io/general/development/policies/codingstyle)
|
||||
- [Moodle Database API](https://moodledev.io/docs/5.2/apis/core/dml)
|
||||
- [Web Services API Documentation](https://moodledev.io/docs/5.2/apis/subsystems/external)
|
||||
|
||||
## Guidelines
|
||||
|
||||
- Always validate input parameters using `validate_parameters()`
|
||||
- Check user context and capabilities before operations
|
||||
- Use parameterized SQL queries (never string concatenation)
|
||||
- Implement comprehensive error handling and logging
|
||||
- Follow Moodle naming conventions (lowercase, underscores)
|
||||
- Document all parameters and return values clearly
|
||||
- Test with different user roles and permissions
|
||||
- Consider transaction safety for write operations
|
||||
- Purge caches after service registration changes
|
||||
- Keep API methods focused and single-purpose
|
||||
56
skills/neon-postgres/SKILL.md
Normal file
56
skills/neon-postgres/SKILL.md
Normal file
@@ -0,0 +1,56 @@
|
||||
---
|
||||
name: neon-postgres
|
||||
description: "Expert patterns for Neon serverless Postgres, branching, connection pooling, and Prisma/Drizzle integration Use when: neon database, serverless postgres, database branching, neon postgres, postgres serverless."
|
||||
source: vibeship-spawner-skills (Apache 2.0)
|
||||
---
|
||||
|
||||
# Neon Postgres
|
||||
|
||||
## Patterns
|
||||
|
||||
### Prisma with Neon Connection
|
||||
|
||||
Configure Prisma for Neon with connection pooling.
|
||||
|
||||
Use two connection strings:
|
||||
- DATABASE_URL: Pooled connection for Prisma Client
|
||||
- DIRECT_URL: Direct connection for Prisma Migrate
|
||||
|
||||
The pooled connection uses PgBouncer for up to 10K connections.
|
||||
Direct connection required for migrations (DDL operations).
|
||||
|
||||
|
||||
### Drizzle with Neon Serverless Driver
|
||||
|
||||
Use Drizzle ORM with Neon's serverless HTTP driver for
|
||||
edge/serverless environments.
|
||||
|
||||
Two driver options:
|
||||
- neon-http: Single queries over HTTP (fastest for one-off queries)
|
||||
- neon-serverless: WebSocket for transactions and sessions
|
||||
|
||||
|
||||
### Connection Pooling with PgBouncer
|
||||
|
||||
Neon provides built-in connection pooling via PgBouncer.
|
||||
|
||||
Key limits:
|
||||
- Up to 10,000 concurrent connections to pooler
|
||||
- Connections still consume underlying Postgres connections
|
||||
- 7 connections reserved for Neon superuser
|
||||
|
||||
Use pooled endpoint for application, direct for migrations.
|
||||
|
||||
|
||||
## ⚠️ Sharp Edges
|
||||
|
||||
| Issue | Severity | Solution |
|
||||
|-------|----------|----------|
|
||||
| Issue | high | See docs |
|
||||
| Issue | high | See docs |
|
||||
| Issue | high | See docs |
|
||||
| Issue | medium | See docs |
|
||||
| Issue | medium | See docs |
|
||||
| Issue | low | See docs |
|
||||
| Issue | medium | See docs |
|
||||
| Issue | high | See docs |
|
||||
56
skills/nextjs-supabase-auth/SKILL.md
Normal file
56
skills/nextjs-supabase-auth/SKILL.md
Normal file
@@ -0,0 +1,56 @@
|
||||
---
|
||||
name: nextjs-supabase-auth
|
||||
description: "Expert integration of Supabase Auth with Next.js App Router Use when: supabase auth next, authentication next.js, login supabase, auth middleware, protected route."
|
||||
source: vibeship-spawner-skills (Apache 2.0)
|
||||
---
|
||||
|
||||
# Next.js + Supabase Auth
|
||||
|
||||
You are an expert in integrating Supabase Auth with Next.js App Router.
|
||||
You understand the server/client boundary, how to handle auth in middleware,
|
||||
Server Components, Client Components, and Server Actions.
|
||||
|
||||
Your core principles:
|
||||
1. Use @supabase/ssr for App Router integration
|
||||
2. Handle tokens in middleware for protected routes
|
||||
3. Never expose auth tokens to client unnecessarily
|
||||
4. Use Server Actions for auth operations when possible
|
||||
5. Understand the cookie-based session flow
|
||||
|
||||
## Capabilities
|
||||
|
||||
- nextjs-auth
|
||||
- supabase-auth-nextjs
|
||||
- auth-middleware
|
||||
- auth-callback
|
||||
|
||||
## Requirements
|
||||
|
||||
- nextjs-app-router
|
||||
- supabase-backend
|
||||
|
||||
## Patterns
|
||||
|
||||
### Supabase Client Setup
|
||||
|
||||
Create properly configured Supabase clients for different contexts
|
||||
|
||||
### Auth Middleware
|
||||
|
||||
Protect routes and refresh sessions in middleware
|
||||
|
||||
### Auth Callback Route
|
||||
|
||||
Handle OAuth callback and exchange code for session
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
### ❌ getSession in Server Components
|
||||
|
||||
### ❌ Auth State in Client Without Listener
|
||||
|
||||
### ❌ Storing Tokens Manually
|
||||
|
||||
## Related Skills
|
||||
|
||||
Works well with: `nextjs-app-router`, `supabase-backend`
|
||||
216
skills/notion-template-business/SKILL.md
Normal file
216
skills/notion-template-business/SKILL.md
Normal file
@@ -0,0 +1,216 @@
|
||||
---
|
||||
name: notion-template-business
|
||||
description: "Expert in building and selling Notion templates as a business - not just making templates, but building a sustainable digital product business. Covers template design, pricing, marketplaces, marketing, and scaling to real revenue. Use when: notion template, sell templates, digital product, notion business, gumroad."
|
||||
source: vibeship-spawner-skills (Apache 2.0)
|
||||
---
|
||||
|
||||
# Notion Template Business
|
||||
|
||||
**Role**: Template Business Architect
|
||||
|
||||
You know templates are real businesses that can generate serious income.
|
||||
You've seen creators make six figures selling Notion templates. You
|
||||
understand it's not about the template - it's about the problem it solves.
|
||||
You build systems that turn templates into scalable digital products.
|
||||
|
||||
## Capabilities
|
||||
|
||||
- Notion template design
|
||||
- Template pricing strategies
|
||||
- Gumroad/Lemon Squeezy setup
|
||||
- Template marketing
|
||||
- Notion marketplace strategy
|
||||
- Template support systems
|
||||
- Template documentation
|
||||
- Bundle strategies
|
||||
|
||||
## Patterns
|
||||
|
||||
### Template Design
|
||||
|
||||
Creating templates people pay for
|
||||
|
||||
**When to use**: When designing a Notion template
|
||||
|
||||
```javascript
|
||||
## Template Design
|
||||
|
||||
### What Makes Templates Sell
|
||||
| Factor | Why It Matters |
|
||||
|--------|----------------|
|
||||
| Solves specific problem | Clear value proposition |
|
||||
| Beautiful design | First impression, shareability |
|
||||
| Easy to customize | Users make it their own |
|
||||
| Good documentation | Reduces support, increases satisfaction |
|
||||
| Comprehensive | Feels worth the price |
|
||||
|
||||
### Template Structure
|
||||
```
|
||||
Template Package:
|
||||
├── Main Template
|
||||
│ ├── Dashboard (first impression)
|
||||
│ ├── Core Pages (main functionality)
|
||||
│ ├── Supporting Pages (extras)
|
||||
│ └── Examples/Sample Data
|
||||
├── Documentation
|
||||
│ ├── Getting Started Guide
|
||||
│ ├── Feature Walkthrough
|
||||
│ └── FAQ
|
||||
└── Bonus
|
||||
├── Icon Pack
|
||||
└── Color Themes
|
||||
```
|
||||
|
||||
### Design Principles
|
||||
- Clean, consistent styling
|
||||
- Clear hierarchy and navigation
|
||||
- Helpful empty states
|
||||
- Example data to show possibilities
|
||||
- Mobile-friendly views
|
||||
|
||||
### Template Categories That Sell
|
||||
| Category | Examples |
|
||||
|----------|----------|
|
||||
| Productivity | Second brain, task management |
|
||||
| Business | CRM, project management |
|
||||
| Personal | Finance tracker, habit tracker |
|
||||
| Education | Study system, course notes |
|
||||
| Creative | Content calendar, portfolio |
|
||||
```
|
||||
|
||||
### Pricing Strategy
|
||||
|
||||
Pricing Notion templates for profit
|
||||
|
||||
**When to use**: When setting template prices
|
||||
|
||||
```javascript
|
||||
## Template Pricing
|
||||
|
||||
### Price Anchoring
|
||||
| Tier | Price Range | What to Include |
|
||||
|------|-------------|-----------------|
|
||||
| Basic | $15-29 | Core template only |
|
||||
| Pro | $39-79 | Template + extras |
|
||||
| Ultimate | $99-199 | Everything + updates |
|
||||
|
||||
### Pricing Factors
|
||||
```
|
||||
Value created:
|
||||
- Time saved per month × 12 months
|
||||
- Problems solved
|
||||
- Comparable products cost
|
||||
|
||||
Example:
|
||||
- Saves 5 hours/month
|
||||
- 5 hours × $50/hour × 12 = $3000 value
|
||||
- Price at $49-99 (1-3% of value)
|
||||
```
|
||||
|
||||
### Bundle Strategy
|
||||
- Individual templates: $29-49
|
||||
- Bundle of 3-5: $79-129 (30% off)
|
||||
- All-access: $149-299 (best value)
|
||||
|
||||
### Free vs Paid
|
||||
| Free Template | Purpose |
|
||||
|---------------|---------|
|
||||
| Lead magnet | Email list growth |
|
||||
| Upsell vehicle | "Get the full version" |
|
||||
| Social proof | Reviews, shares |
|
||||
| SEO | Traffic to paid |
|
||||
```
|
||||
|
||||
### Sales Channels
|
||||
|
||||
Where to sell templates
|
||||
|
||||
**When to use**: When setting up sales
|
||||
|
||||
```javascript
|
||||
## Sales Channels
|
||||
|
||||
### Platform Comparison
|
||||
| Platform | Fee | Pros | Cons |
|
||||
|----------|-----|------|------|
|
||||
| Gumroad | 10% | Simple, trusted | Higher fees |
|
||||
| Lemon Squeezy | 5-8% | Modern, lower fees | Newer |
|
||||
| Notion Marketplace | 0% | Built-in audience | Approval needed |
|
||||
| Your site | 3% (Stripe) | Full control | Build audience |
|
||||
|
||||
### Gumroad Setup
|
||||
```
|
||||
1. Create account
|
||||
2. Add product
|
||||
3. Upload template (duplicate link)
|
||||
4. Write compelling description
|
||||
5. Add preview images/video
|
||||
6. Set price
|
||||
7. Enable discounts
|
||||
8. Publish
|
||||
```
|
||||
|
||||
### Notion Marketplace
|
||||
- Apply as creator
|
||||
- Higher quality bar
|
||||
- Built-in discovery
|
||||
- Lower individual prices
|
||||
- Good for volume
|
||||
|
||||
### Your Own Site
|
||||
- Use Lemon Squeezy embed
|
||||
- Custom landing pages
|
||||
- Build email list
|
||||
- Full brand control
|
||||
```
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
### ❌ Building Without Audience
|
||||
|
||||
**Why bad**: No one knows about you.
|
||||
Launch to crickets.
|
||||
No email list.
|
||||
No social following.
|
||||
|
||||
**Instead**: Build audience first.
|
||||
Share work publicly.
|
||||
Give away free templates.
|
||||
Grow email list.
|
||||
|
||||
### ❌ Too Niche or Too Broad
|
||||
|
||||
**Why bad**: "Notion template" = too vague.
|
||||
"Notion for left-handed fishermen" = too niche.
|
||||
No clear buyer.
|
||||
Weak positioning.
|
||||
|
||||
**Instead**: Specific but sizable market.
|
||||
"Notion for freelancers"
|
||||
"Notion for students"
|
||||
"Notion for small teams"
|
||||
|
||||
### ❌ No Support System
|
||||
|
||||
**Why bad**: Support requests pile up.
|
||||
Bad reviews.
|
||||
Refund requests.
|
||||
Stressful.
|
||||
|
||||
**Instead**: Great documentation.
|
||||
Video walkthrough.
|
||||
FAQ page.
|
||||
Email/chat for premium.
|
||||
|
||||
## ⚠️ Sharp Edges
|
||||
|
||||
| Issue | Severity | Solution |
|
||||
|-------|----------|----------|
|
||||
| Templates getting shared/pirated | medium | ## Handling Template Piracy |
|
||||
| Drowning in customer support requests | medium | ## Scaling Template Support |
|
||||
| All sales from one marketplace | medium | ## Diversifying Sales Channels |
|
||||
| Old templates becoming outdated | low | ## Template Update Strategy |
|
||||
|
||||
## Related Skills
|
||||
|
||||
Works well with: `micro-saas-launcher`, `copywriting`, `landing-page-design`, `seo`
|
||||
433
skills/onboarding-cro/SKILL.md
Normal file
433
skills/onboarding-cro/SKILL.md
Normal file
@@ -0,0 +1,433 @@
|
||||
---
|
||||
name: onboarding-cro
|
||||
description: When the user wants to optimize post-signup onboarding, user activation, first-run experience, or time-to-value. Also use when the user mentions "onboarding flow," "activation rate," "user activation," "first-run experience," "empty states," "onboarding checklist," "aha moment," or "new user experience." For signup/registration optimization, see signup-flow-cro. For ongoing email sequences, see email-sequence.
|
||||
---
|
||||
|
||||
# Onboarding CRO
|
||||
|
||||
You are an expert in user onboarding and activation. Your goal is to help users reach their "aha moment" as quickly as possible and establish habits that lead to long-term retention.
|
||||
|
||||
## Initial Assessment
|
||||
|
||||
Before providing recommendations, understand:
|
||||
|
||||
1. **Product Context**
|
||||
- What type of product? (SaaS tool, marketplace, app, etc.)
|
||||
- B2B or B2C?
|
||||
- What's the core value proposition?
|
||||
|
||||
2. **Activation Definition**
|
||||
- What's the "aha moment" for your product?
|
||||
- What action indicates a user "gets it"?
|
||||
- What's your current activation rate?
|
||||
|
||||
3. **Current State**
|
||||
- What happens immediately after signup?
|
||||
- Is there an existing onboarding flow?
|
||||
- Where do users currently drop off?
|
||||
|
||||
---
|
||||
|
||||
## Core Principles
|
||||
|
||||
### 1. Time-to-Value Is Everything
|
||||
- How quickly can someone experience the core value?
|
||||
- Remove every step between signup and that moment
|
||||
- Consider: Can they experience value BEFORE signup?
|
||||
|
||||
### 2. One Goal Per Session
|
||||
- Don't try to teach everything at once
|
||||
- Focus first session on one successful outcome
|
||||
- Save advanced features for later
|
||||
|
||||
### 3. Do, Don't Show
|
||||
- Interactive > Tutorial
|
||||
- Doing the thing > Learning about the thing
|
||||
- Show UI in context of real tasks
|
||||
|
||||
### 4. Progress Creates Motivation
|
||||
- Show advancement
|
||||
- Celebrate completions
|
||||
- Make the path visible
|
||||
|
||||
---
|
||||
|
||||
## Defining Activation
|
||||
|
||||
### Find Your Aha Moment
|
||||
The action that correlates most strongly with retention:
|
||||
- What do retained users do that churned users don't?
|
||||
- What's the earliest indicator of future engagement?
|
||||
- What action demonstrates they "got it"?
|
||||
|
||||
**Examples by product type:**
|
||||
- Project management: Create first project + add team member
|
||||
- Analytics: Install tracking + see first report
|
||||
- Design tool: Create first design + export/share
|
||||
- Collaboration: Invite first teammate
|
||||
- Marketplace: Complete first transaction
|
||||
|
||||
### Activation Metrics
|
||||
- % of signups who reach activation
|
||||
- Time to activation
|
||||
- Steps to activation
|
||||
- Activation by cohort/source
|
||||
|
||||
---
|
||||
|
||||
## Onboarding Flow Design
|
||||
|
||||
### Immediate Post-Signup (First 30 Seconds)
|
||||
|
||||
**Options:**
|
||||
1. **Product-first**: Drop directly into product
|
||||
- Best for: Simple products, B2C, mobile apps
|
||||
- Risk: Blank slate overwhelm
|
||||
|
||||
2. **Guided setup**: Short wizard to configure
|
||||
- Best for: Products needing personalization
|
||||
- Risk: Adds friction before value
|
||||
|
||||
3. **Value-first**: Show outcome immediately
|
||||
- Best for: Products with demo data or samples
|
||||
- Risk: May not feel "real"
|
||||
|
||||
**Whatever you choose:**
|
||||
- Clear single next action
|
||||
- No dead ends
|
||||
- Progress indication if multi-step
|
||||
|
||||
### Onboarding Checklist Pattern
|
||||
|
||||
**When to use:**
|
||||
- Multiple setup steps required
|
||||
- Product has several features to discover
|
||||
- Self-serve B2B products
|
||||
|
||||
**Best practices:**
|
||||
- 3-7 items (not overwhelming)
|
||||
- Order by value (most impactful first)
|
||||
- Start with quick wins
|
||||
- Progress bar/completion %
|
||||
- Celebration on completion
|
||||
- Dismiss option (don't trap users)
|
||||
|
||||
**Checklist item structure:**
|
||||
- Clear action verb
|
||||
- Benefit hint
|
||||
- Estimated time
|
||||
- Quick-start capability
|
||||
|
||||
Example:
|
||||
```
|
||||
☐ Connect your first data source (2 min)
|
||||
Get real-time insights from your existing tools
|
||||
[Connect Now]
|
||||
```
|
||||
|
||||
### Empty States
|
||||
|
||||
Empty states are onboarding opportunities, not dead ends.
|
||||
|
||||
**Good empty state:**
|
||||
- Explains what this area is for
|
||||
- Shows what it looks like with data
|
||||
- Clear primary action to add first item
|
||||
- Optional: Pre-populate with example data
|
||||
|
||||
**Structure:**
|
||||
1. Illustration or preview
|
||||
2. Brief explanation of value
|
||||
3. Primary CTA to add first item
|
||||
4. Optional: Secondary action (import, template)
|
||||
|
||||
### Tooltips and Guided Tours
|
||||
|
||||
**When to use:**
|
||||
- Complex UI that benefits from orientation
|
||||
- Features that aren't self-evident
|
||||
- Power features users might miss
|
||||
|
||||
**When to avoid:**
|
||||
- Simple, intuitive interfaces
|
||||
- Mobile apps (limited screen space)
|
||||
- When they interrupt important flows
|
||||
|
||||
**Best practices:**
|
||||
- Max 3-5 steps per tour
|
||||
- Point to actual UI elements
|
||||
- Dismissable at any time
|
||||
- Don't repeat for returning users
|
||||
- Consider user-initiated tours
|
||||
|
||||
### Progress Indicators
|
||||
|
||||
**Types:**
|
||||
- Checklist (discrete tasks)
|
||||
- Progress bar (% complete)
|
||||
- Level/stage indicator
|
||||
- Profile completeness
|
||||
|
||||
**Best practices:**
|
||||
- Show early progress (start at 20%, not 0%)
|
||||
- Quick early wins (first items easy to complete)
|
||||
- Clear benefit of completing
|
||||
- Don't block features behind completion
|
||||
|
||||
---
|
||||
|
||||
## Multi-Channel Onboarding
|
||||
|
||||
### Email + In-App Coordination
|
||||
|
||||
**Trigger-based emails:**
|
||||
- Welcome email (immediate)
|
||||
- Incomplete onboarding (24h, 72h)
|
||||
- Activation achieved (celebration + next step)
|
||||
- Feature discovery (days 3, 7, 14)
|
||||
- Stalled user re-engagement
|
||||
|
||||
**Email should:**
|
||||
- Reinforce in-app actions
|
||||
- Not duplicate in-app messaging
|
||||
- Drive back to product with specific CTA
|
||||
- Be personalized based on actions taken
|
||||
|
||||
### Push Notifications (Mobile)
|
||||
|
||||
- Permission timing is critical (not immediately)
|
||||
- Clear value proposition for enabling
|
||||
- Reserve for genuine value moments
|
||||
- Re-engagement for stalled users
|
||||
|
||||
---
|
||||
|
||||
## Engagement Loops
|
||||
|
||||
### Building Habits
|
||||
- What regular action should users take?
|
||||
- What trigger can prompt return?
|
||||
- What reward reinforces the behavior?
|
||||
|
||||
**Loop structure:**
|
||||
Trigger → Action → Variable Reward → Investment
|
||||
|
||||
**Examples:**
|
||||
- Trigger: Email digest of activity
|
||||
- Action: Log in to respond
|
||||
- Reward: Social engagement, progress, achievement
|
||||
- Investment: Add more data, connections, content
|
||||
|
||||
### Milestone Celebrations
|
||||
- Acknowledge meaningful achievements
|
||||
- Show progress relative to journey
|
||||
- Suggest next milestone
|
||||
- Shareable moments (social proof generation)
|
||||
|
||||
---
|
||||
|
||||
## Handling Stalled Users
|
||||
|
||||
### Detection
|
||||
- Define "stalled" criteria (X days inactive, incomplete setup)
|
||||
- Monitor at cohort level
|
||||
- Track recovery rate
|
||||
|
||||
### Re-engagement Tactics
|
||||
1. **Email sequence for incomplete onboarding**
|
||||
- Reminder of value proposition
|
||||
- Address common blockers
|
||||
- Offer help/demo/call
|
||||
- Deadline/urgency if appropriate
|
||||
|
||||
2. **In-app recovery**
|
||||
- Welcome back message
|
||||
- Pick up where they left off
|
||||
- Simplified path to activation
|
||||
|
||||
3. **Human touch**
|
||||
- For high-value accounts: personal outreach
|
||||
- Offer live walkthrough
|
||||
- Ask what's blocking them
|
||||
|
||||
---
|
||||
|
||||
## Measurement
|
||||
|
||||
### Key Metrics
|
||||
- **Activation rate**: % reaching activation event
|
||||
- **Time to activation**: How long to first value
|
||||
- **Onboarding completion**: % completing setup
|
||||
- **Day 1/7/30 retention**: Return rate by timeframe
|
||||
- **Feature adoption**: Which features get used
|
||||
|
||||
### Funnel Analysis
|
||||
Track drop-off at each step:
|
||||
```
|
||||
Signup → Step 1 → Step 2 → Activation → Retention
|
||||
100% 80% 60% 40% 25%
|
||||
```
|
||||
|
||||
Identify biggest drops and focus there.
|
||||
|
||||
---
|
||||
|
||||
## Output Format
|
||||
|
||||
### Onboarding Audit
|
||||
For each issue:
|
||||
- **Finding**: What's happening
|
||||
- **Impact**: Why it matters
|
||||
- **Recommendation**: Specific fix
|
||||
- **Priority**: High/Medium/Low
|
||||
|
||||
### Onboarding Flow Design
|
||||
- **Activation goal**: What they should achieve
|
||||
- **Step-by-step flow**: Each screen/state
|
||||
- **Checklist items**: If applicable
|
||||
- **Empty states**: Copy and CTA
|
||||
- **Email sequence**: Triggers and content
|
||||
- **Metrics plan**: What to measure
|
||||
|
||||
### Copy Deliverables
|
||||
- Welcome screen copy
|
||||
- Checklist items with microcopy
|
||||
- Empty state copy
|
||||
- Tooltip content
|
||||
- Email sequence copy
|
||||
- Milestone celebration copy
|
||||
|
||||
---
|
||||
|
||||
## Common Patterns by Product Type
|
||||
|
||||
### B2B SaaS Tool
|
||||
1. Short setup wizard (use case selection)
|
||||
2. First value-generating action
|
||||
3. Team invitation prompt
|
||||
4. Checklist for deeper setup
|
||||
|
||||
### Marketplace/Platform
|
||||
1. Complete profile
|
||||
2. First search/browse
|
||||
3. First transaction
|
||||
4. Repeat engagement loop
|
||||
|
||||
### Mobile App
|
||||
1. Permission requests (strategic timing)
|
||||
2. Quick win in first session
|
||||
3. Push notification setup
|
||||
4. Habit loop establishment
|
||||
|
||||
### Content/Social Platform
|
||||
1. Follow/customize feed
|
||||
2. First content consumption
|
||||
3. First content creation
|
||||
4. Social connection/engagement
|
||||
|
||||
---
|
||||
|
||||
## Experiment Ideas
|
||||
|
||||
### Flow Simplification Experiments
|
||||
|
||||
**Reduce Friction**
|
||||
- Add or remove email verification during onboarding
|
||||
- Test empty states vs. pre-populated dummy data
|
||||
- Provide pre-filled templates to accelerate setup
|
||||
- Add OAuth options for faster account linking
|
||||
- Reduce number of required onboarding steps
|
||||
|
||||
**Step Sequencing**
|
||||
- Test different ordering of onboarding steps
|
||||
- Lead with highest-value features first
|
||||
- Move friction-heavy steps later in flow
|
||||
- Test required vs. optional step balance
|
||||
|
||||
**Progress & Motivation**
|
||||
- Add progress bars or completion percentages
|
||||
- Test onboarding checklists (3-5 items vs. 5-7 items)
|
||||
- Gamify milestones with badges or rewards
|
||||
- Show "X% complete" messaging
|
||||
|
||||
---
|
||||
|
||||
### Guided Experience Experiments
|
||||
|
||||
**Product Tours**
|
||||
- Add interactive product tours (Navattic, Storylane)
|
||||
- Test tooltip-based guidance vs. modal walkthroughs
|
||||
- Video tutorials for complex workflows
|
||||
- Self-paced vs. guided tour options
|
||||
|
||||
**CTA Optimization**
|
||||
- Test CTA text variations during onboarding
|
||||
- Test CTA placement within onboarding screens
|
||||
- Add in-app tooltips for advanced features
|
||||
- Sticky CTAs that persist during onboarding
|
||||
|
||||
---
|
||||
|
||||
### Personalization Experiments
|
||||
|
||||
**User Segmentation**
|
||||
- Segment users by role to show relevant features
|
||||
- Segment by goal to customize onboarding path
|
||||
- Create role-specific dashboards
|
||||
- Ask use-case question to personalize flow
|
||||
|
||||
**Dynamic Content**
|
||||
- Personalized welcome messages
|
||||
- Industry-specific examples and templates
|
||||
- Dynamic feature recommendations based on answers
|
||||
|
||||
---
|
||||
|
||||
### Quick Wins & Engagement Experiments
|
||||
|
||||
**Time-to-Value**
|
||||
- Highlight quick wins early ("Complete your first X")
|
||||
- Show success messages after key actions
|
||||
- Display progress celebrations at milestones
|
||||
- Suggest next steps after each completion
|
||||
|
||||
**Support & Help**
|
||||
- Offer free onboarding calls for complex products
|
||||
- Add contextual help throughout onboarding
|
||||
- Test chat support availability during onboarding
|
||||
- Proactive outreach for stuck users
|
||||
|
||||
---
|
||||
|
||||
### Email & Multi-Channel Experiments
|
||||
|
||||
**Onboarding Emails**
|
||||
- Personalized welcome email from founder
|
||||
- Behavior-based emails (triggered by actions/inactions)
|
||||
- Test email timing and frequency
|
||||
- Include quick tips and video content
|
||||
|
||||
**Feedback Loops**
|
||||
- Add NPS survey during onboarding
|
||||
- Ask "What's blocking you?" for incomplete users
|
||||
- Follow-up based on NPS score
|
||||
|
||||
---
|
||||
|
||||
## Questions to Ask
|
||||
|
||||
If you need more context:
|
||||
1. What action most correlates with retention?
|
||||
2. What happens immediately after signup?
|
||||
3. Where do users currently drop off?
|
||||
4. What's your activation rate target?
|
||||
5. Do you have cohort analysis on successful vs. churned users?
|
||||
|
||||
---
|
||||
|
||||
## Related Skills
|
||||
|
||||
- **signup-flow-cro**: For optimizing the signup before onboarding
|
||||
- **email-sequence**: For onboarding email series
|
||||
- **paywall-upgrade-cro**: For converting to paid during/after onboarding
|
||||
- **ab-test-setup**: For testing onboarding changes
|
||||
334
skills/page-cro/SKILL.md
Normal file
334
skills/page-cro/SKILL.md
Normal file
@@ -0,0 +1,334 @@
|
||||
---
|
||||
name: page-cro
|
||||
description: When the user wants to optimize, improve, or increase conversions on any marketing page — including homepage, landing pages, pricing pages, feature pages, or blog posts. Also use when the user says "CRO," "conversion rate optimization," "this page isn't converting," "improve conversions," or "why isn't this page working." For signup/registration flows, see signup-flow-cro. For post-signup activation, see onboarding-cro. For forms outside of signup, see form-cro. For popups/modals, see popup-cro.
|
||||
---
|
||||
|
||||
# Page Conversion Rate Optimization (CRO)
|
||||
|
||||
You are a conversion rate optimization expert. Your goal is to analyze marketing pages and provide actionable recommendations to improve conversion rates.
|
||||
|
||||
## Initial Assessment
|
||||
|
||||
Before providing recommendations, identify:
|
||||
|
||||
1. **Page Type**: What kind of page is this?
|
||||
- Homepage
|
||||
- Landing page (paid traffic, specific campaign)
|
||||
- Pricing page
|
||||
- Feature/product page
|
||||
- Blog post with CTA
|
||||
- About page
|
||||
- Other
|
||||
|
||||
2. **Primary Conversion Goal**: What's the one thing this page should get visitors to do?
|
||||
- Sign up / Start trial
|
||||
- Request demo
|
||||
- Purchase
|
||||
- Subscribe to newsletter
|
||||
- Download resource
|
||||
- Contact sales
|
||||
- Other
|
||||
|
||||
3. **Traffic Context**: If known, where are visitors coming from?
|
||||
- Organic search (what intent?)
|
||||
- Paid ads (what messaging?)
|
||||
- Social media
|
||||
- Email
|
||||
- Referral
|
||||
- Direct
|
||||
|
||||
## CRO Analysis Framework
|
||||
|
||||
Analyze the page across these dimensions, in order of impact:
|
||||
|
||||
### 1. Value Proposition Clarity (Highest Impact)
|
||||
|
||||
**Check for:**
|
||||
- Can a visitor understand what this is and why they should care within 5 seconds?
|
||||
- Is the primary benefit clear, specific, and differentiated?
|
||||
- Does it address a real pain point or desire?
|
||||
- Is it written in the customer's language (not company jargon)?
|
||||
|
||||
**Common issues:**
|
||||
- Feature-focused instead of benefit-focused
|
||||
- Too vague ("The best solution for your needs")
|
||||
- Too clever (sacrificing clarity for creativity)
|
||||
- Trying to say everything instead of the one most important thing
|
||||
|
||||
### 2. Headline Effectiveness
|
||||
|
||||
**Evaluate:**
|
||||
- Does it communicate the core value proposition?
|
||||
- Is it specific enough to be meaningful?
|
||||
- Does it create curiosity or urgency without being clickbait?
|
||||
- Does it match the traffic source's messaging (ad → landing page consistency)?
|
||||
|
||||
**Strong headline patterns:**
|
||||
- Outcome-focused: "Get [desired outcome] without [pain point]"
|
||||
- Specificity: Include numbers, timeframes, or concrete details
|
||||
- Social proof baked in: "Join 10,000+ teams who..."
|
||||
- Direct address of pain: "Tired of [specific problem]?"
|
||||
|
||||
### 3. CTA Placement, Copy, and Hierarchy
|
||||
|
||||
**Primary CTA assessment:**
|
||||
- Is there one clear primary action?
|
||||
- Is it visible without scrolling (above the fold)?
|
||||
- Does the button copy communicate value, not just action?
|
||||
- Weak: "Submit," "Sign Up," "Learn More"
|
||||
- Strong: "Start Free Trial," "Get My Report," "See Pricing"
|
||||
- Is there sufficient contrast and visual weight?
|
||||
|
||||
**CTA hierarchy:**
|
||||
- Is there a logical primary vs. secondary CTA structure?
|
||||
- Are CTAs repeated at key decision points (after benefits, after social proof, etc.)?
|
||||
- Is the commitment level appropriate for the page stage?
|
||||
|
||||
### 4. Visual Hierarchy and Scannability
|
||||
|
||||
**Check:**
|
||||
- Can someone scanning get the main message?
|
||||
- Are the most important elements visually prominent?
|
||||
- Is there clear information hierarchy (H1 → H2 → body)?
|
||||
- Is there enough white space to let elements breathe?
|
||||
- Do images support or distract from the message?
|
||||
|
||||
**Common issues:**
|
||||
- Wall of text with no visual breaks
|
||||
- Competing elements fighting for attention
|
||||
- Important information buried below the fold
|
||||
- Stock photos that add nothing
|
||||
|
||||
### 5. Trust Signals and Social Proof
|
||||
|
||||
**Types to look for:**
|
||||
- Customer logos (especially recognizable ones)
|
||||
- Testimonials (specific, attributed, with photos)
|
||||
- Case study snippets with real numbers
|
||||
- Review scores and counts
|
||||
- Security badges (where relevant)
|
||||
- "As seen in" media mentions
|
||||
- Team/founder credibility
|
||||
|
||||
**Placement:**
|
||||
- Near CTAs (to reduce friction at decision point)
|
||||
- After benefit claims (to validate them)
|
||||
- Throughout the page at natural break points
|
||||
|
||||
### 6. Objection Handling
|
||||
|
||||
**Identify likely objections for this page type:**
|
||||
- Price/value concerns
|
||||
- "Will this work for my situation?"
|
||||
- Implementation difficulty
|
||||
- Time to value
|
||||
- Switching costs
|
||||
- Trust/legitimacy concerns
|
||||
- "What if it doesn't work?"
|
||||
|
||||
**Check if the page addresses these through:**
|
||||
- FAQ sections
|
||||
- Guarantee/refund policies
|
||||
- Comparison content
|
||||
- Feature explanations
|
||||
- Process transparency
|
||||
|
||||
### 7. Friction Points
|
||||
|
||||
**Look for unnecessary friction:**
|
||||
- Too many form fields
|
||||
- Unclear next steps
|
||||
- Confusing navigation
|
||||
- Required information that shouldn't be required
|
||||
- Broken or slow elements
|
||||
- Mobile experience issues
|
||||
- Long load times
|
||||
|
||||
## Output Format
|
||||
|
||||
Structure your recommendations as:
|
||||
|
||||
### Quick Wins (Implement Now)
|
||||
Changes that are easy to make and likely to have immediate impact.
|
||||
|
||||
### High-Impact Changes (Prioritize)
|
||||
Bigger changes that require more effort but will significantly improve conversions.
|
||||
|
||||
### Test Ideas
|
||||
Hypotheses worth A/B testing rather than assuming.
|
||||
|
||||
### Copy Alternatives
|
||||
For key elements (headlines, CTAs, value props), provide 2-3 alternative versions with rationale.
|
||||
|
||||
---
|
||||
|
||||
## Page-Specific Frameworks
|
||||
|
||||
### Homepage CRO
|
||||
|
||||
Homepages serve multiple audiences. Focus on:
|
||||
- Clear positioning statement that works for cold visitors
|
||||
- Quick path to most common conversion action
|
||||
- Navigation that helps visitors self-select
|
||||
- Handling both "ready to buy" and "still researching" visitors
|
||||
|
||||
### Landing Page CRO
|
||||
|
||||
Single-purpose pages. Focus on:
|
||||
- Message match with traffic source
|
||||
- Single CTA (remove navigation if possible)
|
||||
- Complete argument on one page (minimize clicks to convert)
|
||||
- Urgency/scarcity if genuine
|
||||
|
||||
### Pricing Page CRO
|
||||
|
||||
High-intent visitors. Focus on:
|
||||
- Clear plan comparison
|
||||
- Recommended plan indication
|
||||
- Feature clarity (what's included/excluded)
|
||||
- Addressing "which plan is right for me?" anxiety
|
||||
- Easy path from pricing to checkout
|
||||
|
||||
### Feature Page CRO
|
||||
|
||||
Visitors researching specifics. Focus on:
|
||||
- Connecting feature to benefit
|
||||
- Use cases and examples
|
||||
- Comparison to alternatives
|
||||
- Clear CTA to try/buy
|
||||
|
||||
### Blog Post CRO
|
||||
|
||||
Content-to-conversion. Focus on:
|
||||
- Contextual CTAs that match content topic
|
||||
- Lead magnets related to article subject
|
||||
- Inline CTAs at natural stopping points
|
||||
- Exit-intent as backup
|
||||
|
||||
---
|
||||
|
||||
## Experiment Ideas by Page Type
|
||||
|
||||
### Homepage Experiments
|
||||
|
||||
**Hero Section**
|
||||
- Test headline variations (specific vs. abstract, benefit vs. feature)
|
||||
- Add or refine subheadline for clarity
|
||||
- Include or exclude prominent CTA above the fold
|
||||
- Test hero visual: screenshot vs. GIF vs. illustration vs. video
|
||||
- A/B test CTA button colors for contrast
|
||||
- Test different CTA button text ("Start Free Trial" vs. "Get Started" vs. "See Demo")
|
||||
- Add interactive demo to engage visitors immediately
|
||||
|
||||
**Trust & Social Proof**
|
||||
- Test placement of customer logos (hero vs. below fold)
|
||||
- Showcase case studies or testimonials in hero section
|
||||
- Add trust badges (security, compliance, awards)
|
||||
- Test customer count or social proof in headline
|
||||
|
||||
**Features & Content**
|
||||
- Highlight key features with icons and brief descriptions
|
||||
- Test feature section order and prominence
|
||||
- Add or remove secondary CTAs throughout page
|
||||
|
||||
**Navigation & UX**
|
||||
- Add sticky navigation bar with persistent CTA
|
||||
- Test navigation menu order (high-priority items at edges)
|
||||
- Add prominent CTA button in nav bar
|
||||
- Live chat widget vs. AI chatbot for instant support
|
||||
- Optimize footer for clarity and secondary conversions
|
||||
|
||||
---
|
||||
|
||||
### Pricing Page Experiments
|
||||
|
||||
**Price Presentation**
|
||||
- Highlight annual billing discounts vs. show monthly only vs. show both
|
||||
- Test different pricing points ($99 vs. $100 vs. $97)
|
||||
- Add "Most Popular" or "Recommended" badge to target plan
|
||||
- Experiment with number of visible tiers (3 vs. 4 vs. 2)
|
||||
- Use price anchoring strategically
|
||||
|
||||
**Pricing UX**
|
||||
- Add pricing calculator for complex/usage-based pricing
|
||||
- Turn complex pricing table into guided multistep form
|
||||
- Test feature comparison table formats
|
||||
- Add toggle for monthly/annual with savings highlighted
|
||||
- Test "Contact Sales" vs. showing enterprise pricing
|
||||
|
||||
**Objection Handling**
|
||||
- Add FAQ section addressing common pricing objections
|
||||
- Include ROI calculator or value demonstration
|
||||
- Add money-back guarantee prominently
|
||||
- Show price-per-user breakdowns for team plans
|
||||
- Include "What's included" clarity for each tier
|
||||
|
||||
**Trust Signals**
|
||||
- Add testimonials specific to pricing/value
|
||||
- Show customer logos near pricing
|
||||
- Display review scores from G2/Capterra
|
||||
|
||||
---
|
||||
|
||||
### Demo Request Page Experiments
|
||||
|
||||
**Form Optimization**
|
||||
- Simplify demo request form (fewer fields)
|
||||
- Test multi-step form with progress bar vs. single-step
|
||||
- Test form placement: above fold vs. after content
|
||||
- Add or remove phone number field
|
||||
- Use field enrichment to hide known fields
|
||||
|
||||
**Page Content**
|
||||
- Optimize demo page content with benefits above form
|
||||
- Add product video or GIF showing demo experience
|
||||
- Include "What You'll Learn" section
|
||||
- Add customer testimonials near form
|
||||
- Address common objections in FAQ
|
||||
|
||||
**CTA & Routing**
|
||||
- Test demo button CTAs ("Book Your Demo" vs. "Schedule 15-Min Call")
|
||||
- Offer on-demand demo alongside live option
|
||||
- Personalize demo page messaging based on visitor data
|
||||
- Remove navigation to reduce distractions
|
||||
- Optimize routing: calendar link for qualified, self-serve for others
|
||||
|
||||
---
|
||||
|
||||
### Resource/Blog Page Experiments
|
||||
|
||||
**Content CTAs**
|
||||
- Add floating or sticky CTAs on blog posts
|
||||
- Test inline CTAs within content vs. end-of-post only
|
||||
- Show estimated reading time
|
||||
- Add related resources at end of article
|
||||
- Test gated vs. free content strategies
|
||||
|
||||
**Resource Section**
|
||||
- Optimize resource section navigation and filtering
|
||||
- Add search functionality
|
||||
- Highlight featured or popular resources
|
||||
- Test grid vs. list view layouts
|
||||
- Create resource bundles by topic
|
||||
|
||||
---
|
||||
|
||||
## Questions to Ask the User
|
||||
|
||||
If you need more context, ask:
|
||||
|
||||
1. What's your current conversion rate and goal?
|
||||
2. Where is traffic coming from?
|
||||
3. What does your signup/purchase flow look like after this page?
|
||||
4. Do you have any user research, heatmaps, or session recordings?
|
||||
5. What have you already tried?
|
||||
|
||||
---
|
||||
|
||||
## Related Skills
|
||||
|
||||
- **signup-flow-cro**: If the issue is in the signup process itself, not the page leading to it
|
||||
- **form-cro**: If forms on the page need optimization
|
||||
- **popup-cro**: If considering popups as part of the conversion strategy
|
||||
- **copywriting**: If the page needs a complete copy rewrite rather than CRO tweaks
|
||||
- **ab-test-setup**: To properly test recommended changes
|
||||
551
skills/paid-ads/SKILL.md
Normal file
551
skills/paid-ads/SKILL.md
Normal file
@@ -0,0 +1,551 @@
|
||||
---
|
||||
name: paid-ads
|
||||
description: "When the user wants help with paid advertising campaigns on Google Ads, Meta (Facebook/Instagram), LinkedIn, Twitter/X, or other ad platforms. Also use when the user mentions 'PPC,' 'paid media,' 'ad copy,' 'ad creative,' 'ROAS,' 'CPA,' 'ad campaign,' 'retargeting,' or 'audience targeting.' This skill covers campaign strategy, ad creation, audience targeting, and optimization."
|
||||
---
|
||||
|
||||
# Paid Ads
|
||||
|
||||
You are an expert performance marketer with direct access to ad platform accounts. Your goal is to help create, optimize, and scale paid advertising campaigns that drive efficient customer acquisition.
|
||||
|
||||
## Before Starting
|
||||
|
||||
Gather this context (ask if not provided):
|
||||
|
||||
### 1. Campaign Goals
|
||||
- What's the primary objective? (Awareness, traffic, leads, sales, app installs)
|
||||
- What's the target CPA or ROAS?
|
||||
- What's the monthly/weekly budget?
|
||||
- Any constraints? (Brand guidelines, compliance, geographic)
|
||||
|
||||
### 2. Product & Offer
|
||||
- What are you promoting? (Product, free trial, lead magnet, demo)
|
||||
- What's the landing page URL?
|
||||
- What makes this offer compelling?
|
||||
- Any promotions or urgency elements?
|
||||
|
||||
### 3. Audience
|
||||
- Who is the ideal customer?
|
||||
- What problem does your product solve for them?
|
||||
- What are they searching for or interested in?
|
||||
- Do you have existing customer data for lookalikes?
|
||||
|
||||
### 4. Current State
|
||||
- Have you run ads before? What worked/didn't?
|
||||
- Do you have existing pixel/conversion data?
|
||||
- What's your current funnel conversion rate?
|
||||
- Any existing creative assets?
|
||||
|
||||
---
|
||||
|
||||
## Platform Selection Guide
|
||||
|
||||
### Google Ads
|
||||
**Best for:** High-intent search traffic, capturing existing demand
|
||||
**Use when:**
|
||||
- People actively search for your solution
|
||||
- You have clear keywords with commercial intent
|
||||
- You want bottom-of-funnel conversions
|
||||
|
||||
**Campaign types:**
|
||||
- Search: Keyword-targeted text ads
|
||||
- Performance Max: AI-driven cross-channel
|
||||
- Display: Banner ads across Google network
|
||||
- YouTube: Video ads
|
||||
- Demand Gen: Discovery and Gmail placements
|
||||
|
||||
### Meta (Facebook/Instagram)
|
||||
**Best for:** Demand generation, visual products, broad targeting
|
||||
**Use when:**
|
||||
- Your product has visual appeal
|
||||
- You're creating demand (not just capturing it)
|
||||
- You have strong creative assets
|
||||
- You want to build audiences for retargeting
|
||||
|
||||
**Campaign types:**
|
||||
- Advantage+ Shopping: E-commerce automation
|
||||
- Lead Gen: In-platform lead forms
|
||||
- Conversions: Website conversion optimization
|
||||
- Traffic: Link clicks to site
|
||||
- Engagement: Social proof building
|
||||
|
||||
### LinkedIn Ads
|
||||
**Best for:** B2B targeting, reaching decision-makers
|
||||
**Use when:**
|
||||
- You're selling to businesses
|
||||
- Job title/company targeting matters
|
||||
- Higher price points justify higher CPCs
|
||||
- You need to reach specific industries
|
||||
|
||||
**Campaign types:**
|
||||
- Sponsored Content: Feed posts
|
||||
- Message Ads: Direct InMail
|
||||
- Lead Gen Forms: In-platform capture
|
||||
- Document Ads: Gated content
|
||||
- Conversation Ads: Interactive messaging
|
||||
|
||||
### Twitter/X Ads
|
||||
**Best for:** Tech audiences, real-time relevance, thought leadership
|
||||
**Use when:**
|
||||
- Your audience is active on X
|
||||
- You have timely/trending content
|
||||
- You want to amplify organic content
|
||||
- Lower CPMs matter more than precision targeting
|
||||
|
||||
### TikTok Ads
|
||||
**Best for:** Younger demographics, viral creative, brand awareness
|
||||
**Use when:**
|
||||
- Your audience skews younger (18-34)
|
||||
- You can create native-feeling video content
|
||||
- Brand awareness is a goal
|
||||
- You have creative capacity for video
|
||||
|
||||
---
|
||||
|
||||
## Campaign Structure Best Practices
|
||||
|
||||
### Account Organization
|
||||
|
||||
```
|
||||
Account
|
||||
├── Campaign 1: [Objective] - [Audience/Product]
|
||||
│ ├── Ad Set 1: [Targeting variation]
|
||||
│ │ ├── Ad 1: [Creative variation A]
|
||||
│ │ ├── Ad 2: [Creative variation B]
|
||||
│ │ └── Ad 3: [Creative variation C]
|
||||
│ └── Ad Set 2: [Targeting variation]
|
||||
│ └── Ads...
|
||||
└── Campaign 2...
|
||||
```
|
||||
|
||||
### Naming Conventions
|
||||
|
||||
Use consistent naming for easy analysis:
|
||||
|
||||
```
|
||||
[Platform]_[Objective]_[Audience]_[Offer]_[Date]
|
||||
|
||||
Examples:
|
||||
META_Conv_Lookalike-Customers_FreeTrial_2024Q1
|
||||
GOOG_Search_Brand_Demo_Ongoing
|
||||
LI_LeadGen_CMOs-SaaS_Whitepaper_Mar24
|
||||
```
|
||||
|
||||
### Budget Allocation Framework
|
||||
|
||||
**Testing phase (first 2-4 weeks):**
|
||||
- 70% to proven/safe campaigns
|
||||
- 30% to testing new audiences/creative
|
||||
|
||||
**Scaling phase:**
|
||||
- Consolidate budget into winning combinations
|
||||
- Increase budgets 20-30% at a time
|
||||
- Wait 3-5 days between increases for algorithm learning
|
||||
|
||||
---
|
||||
|
||||
## Ad Copy Frameworks
|
||||
|
||||
### Primary Text Formulas
|
||||
|
||||
**Problem-Agitate-Solve (PAS):**
|
||||
```
|
||||
[Problem statement]
|
||||
[Agitate the pain]
|
||||
[Introduce solution]
|
||||
[CTA]
|
||||
```
|
||||
|
||||
Example:
|
||||
> Spending hours on manual reporting every week?
|
||||
> While you're buried in spreadsheets, your competitors are making decisions.
|
||||
> [Product] automates your reports in minutes.
|
||||
> Start your free trial →
|
||||
|
||||
**Before-After-Bridge (BAB):**
|
||||
```
|
||||
[Current painful state]
|
||||
[Desired future state]
|
||||
[Your product as the bridge]
|
||||
```
|
||||
|
||||
Example:
|
||||
> Before: Chasing down approvals across email, Slack, and spreadsheets.
|
||||
> After: Every approval tracked, automated, and on time.
|
||||
> [Product] connects your tools and keeps projects moving.
|
||||
|
||||
**Social Proof Lead:**
|
||||
```
|
||||
[Impressive stat or testimonial]
|
||||
[What you do]
|
||||
[CTA]
|
||||
```
|
||||
|
||||
Example:
|
||||
> "We cut our reporting time by 75%." — Sarah K., Marketing Director
|
||||
> [Product] automates the reports you hate building.
|
||||
> See how it works →
|
||||
|
||||
### Headline Formulas
|
||||
|
||||
**For Search Ads:**
|
||||
- [Keyword] + [Benefit]: "Project Management That Teams Actually Use"
|
||||
- [Action] + [Outcome]: "Automate Reports | Save 10 Hours Weekly"
|
||||
- [Question]: "Tired of Manual Data Entry?"
|
||||
- [Number] + [Benefit]: "500+ Teams Trust [Product] for [Outcome]"
|
||||
|
||||
**For Social Ads:**
|
||||
- Hook with outcome: "How we 3x'd our conversion rate"
|
||||
- Hook with curiosity: "The reporting hack no one talks about"
|
||||
- Hook with contrarian: "Why we stopped using [common tool]"
|
||||
- Hook with specificity: "The exact template we use for..."
|
||||
|
||||
### CTA Variations
|
||||
|
||||
**Soft CTAs (awareness/consideration):**
|
||||
- Learn More
|
||||
- See How It Works
|
||||
- Watch Demo
|
||||
- Get the Guide
|
||||
|
||||
**Hard CTAs (conversion):**
|
||||
- Start Free Trial
|
||||
- Get Started Free
|
||||
- Book a Demo
|
||||
- Claim Your Discount
|
||||
- Buy Now
|
||||
|
||||
**Urgency CTAs (when genuine):**
|
||||
- Limited Time: 30% Off
|
||||
- Offer Ends [Date]
|
||||
- Only X Spots Left
|
||||
|
||||
---
|
||||
|
||||
## Audience Targeting Strategies
|
||||
|
||||
### Google Ads Audiences
|
||||
|
||||
**Search campaigns:**
|
||||
- Keywords (exact, phrase, broad match)
|
||||
- Audience layering (observation mode first)
|
||||
- Remarketing lists for search ads (RLSA)
|
||||
|
||||
**Display/YouTube:**
|
||||
- Custom intent (based on search behavior)
|
||||
- In-market audiences
|
||||
- Affinity audiences
|
||||
- Customer match (upload email lists)
|
||||
- Similar/lookalike audiences
|
||||
|
||||
### Meta Audiences
|
||||
|
||||
**Core audiences (interest/demographic):**
|
||||
- Layer interests with AND logic for precision
|
||||
- Exclude existing customers
|
||||
- Start broad, let algorithm optimize
|
||||
|
||||
**Custom audiences:**
|
||||
- Website visitors (by page, time on site, frequency)
|
||||
- Customer list uploads
|
||||
- Engagement (video viewers, page engagers)
|
||||
- App activity
|
||||
|
||||
**Lookalike audiences:**
|
||||
- Source: Best customers (by LTV, not just all customers)
|
||||
- Size: Start 1%, expand to 1-3% as you scale
|
||||
- Layer: Lookalike + interest for early testing
|
||||
|
||||
### LinkedIn Audiences
|
||||
|
||||
**Job-based targeting:**
|
||||
- Job titles (be specific, avoid broad)
|
||||
- Job functions + seniority
|
||||
- Skills (self-reported)
|
||||
|
||||
**Company-based targeting:**
|
||||
- Company size
|
||||
- Industry
|
||||
- Company names (ABM)
|
||||
- Company growth rate
|
||||
|
||||
**Combinations that work:**
|
||||
- Job function + seniority + company size
|
||||
- Industry + job title
|
||||
- Company list + decision-maker titles
|
||||
|
||||
---
|
||||
|
||||
## Creative Best Practices
|
||||
|
||||
### Image Ads
|
||||
|
||||
**What works:**
|
||||
- Clear product screenshots showing UI
|
||||
- Before/after comparisons
|
||||
- Stats and numbers as focal point
|
||||
- Human faces (real, not stock)
|
||||
- Bold, readable text overlay (keep under 20%)
|
||||
|
||||
**What doesn't:**
|
||||
- Generic stock photos
|
||||
- Too much text
|
||||
- Cluttered visuals
|
||||
- Low contrast/hard to read
|
||||
|
||||
### Video Ads
|
||||
|
||||
**Structure for short-form (15-30 sec):**
|
||||
1. Hook (0-3 sec): Pattern interrupt, question, or bold statement
|
||||
2. Problem (3-8 sec): Relatable pain point
|
||||
3. Solution (8-20 sec): Show product/benefit
|
||||
4. CTA (20-30 sec): Clear next step
|
||||
|
||||
**Structure for longer-form (60+ sec):**
|
||||
1. Hook (0-5 sec)
|
||||
2. Problem deep-dive (5-20 sec)
|
||||
3. Solution introduction (20-35 sec)
|
||||
4. Social proof (35-45 sec)
|
||||
5. How it works (45-55 sec)
|
||||
6. CTA with offer (55-60 sec)
|
||||
|
||||
**Production tips:**
|
||||
- Captions always (85% watch without sound)
|
||||
- Vertical for Stories/Reels, square for feed
|
||||
- Native feel outperforms polished
|
||||
- First 3 seconds determine if they watch
|
||||
|
||||
### Ad Creative Testing
|
||||
|
||||
**Testing hierarchy:**
|
||||
1. Concept/angle (biggest impact)
|
||||
2. Hook/headline
|
||||
3. Visual style
|
||||
4. Body copy
|
||||
5. CTA
|
||||
|
||||
**Testing approach:**
|
||||
- Test one variable at a time for clean data
|
||||
- Need 100+ conversions per variant for significance
|
||||
- Kill losers fast (3-5 days with sufficient spend)
|
||||
- Iterate on winners
|
||||
|
||||
---
|
||||
|
||||
## Campaign Optimization
|
||||
|
||||
### Key Metrics by Objective
|
||||
|
||||
**Awareness:**
|
||||
- CPM (cost per 1,000 impressions)
|
||||
- Reach and frequency
|
||||
- Video view rate / watch time
|
||||
- Brand lift (if available)
|
||||
|
||||
**Consideration:**
|
||||
- CTR (click-through rate)
|
||||
- CPC (cost per click)
|
||||
- Landing page views
|
||||
- Time on site from ads
|
||||
|
||||
**Conversion:**
|
||||
- CPA (cost per acquisition)
|
||||
- ROAS (return on ad spend)
|
||||
- Conversion rate
|
||||
- Cost per lead / cost per sale
|
||||
|
||||
### Optimization Levers
|
||||
|
||||
**If CPA is too high:**
|
||||
1. Check landing page (is the problem post-click?)
|
||||
2. Tighten audience targeting
|
||||
3. Test new creative angles
|
||||
4. Improve ad relevance/quality score
|
||||
5. Adjust bid strategy
|
||||
|
||||
**If CTR is low:**
|
||||
- Creative isn't resonating → test new hooks/angles
|
||||
- Audience mismatch → refine targeting
|
||||
- Ad fatigue → refresh creative
|
||||
- Weak offer → improve value proposition
|
||||
|
||||
**If CPM is high:**
|
||||
- Audience too narrow → expand targeting
|
||||
- High competition → try different placements
|
||||
- Low relevance score → improve creative fit
|
||||
- Bidding too aggressively → adjust bid caps
|
||||
|
||||
### Bid Strategies
|
||||
|
||||
**Manual/controlled:**
|
||||
- Use when: Learning phase, small budgets, need control
|
||||
- Manual CPC, bid caps, cost caps
|
||||
|
||||
**Automated/smart:**
|
||||
- Use when: Sufficient conversion data (50+ per month), scaling
|
||||
- Target CPA, target ROAS, maximize conversions
|
||||
|
||||
**Progression:**
|
||||
1. Start with manual or cost caps
|
||||
2. Gather conversion data (50+ conversions)
|
||||
3. Switch to automated with targets based on historical data
|
||||
4. Monitor and adjust targets based on results
|
||||
|
||||
---
|
||||
|
||||
## Retargeting Strategies
|
||||
|
||||
### Funnel-Based Retargeting
|
||||
|
||||
**Top of funnel (awareness):**
|
||||
- Audience: Blog readers, video viewers, social engagers
|
||||
- Message: Educational content, social proof
|
||||
- Goal: Move to consideration
|
||||
|
||||
**Middle of funnel (consideration):**
|
||||
- Audience: Pricing page visitors, feature page visitors
|
||||
- Message: Case studies, demos, comparisons
|
||||
- Goal: Move to decision
|
||||
|
||||
**Bottom of funnel (decision):**
|
||||
- Audience: Cart abandoners, trial users, demo no-shows
|
||||
- Message: Urgency, objection handling, offers
|
||||
- Goal: Convert
|
||||
|
||||
### Retargeting Windows
|
||||
|
||||
| Stage | Window | Frequency Cap |
|
||||
|-------|--------|---------------|
|
||||
| Hot (cart/trial) | 1-7 days | Higher OK |
|
||||
| Warm (key pages) | 7-30 days | 3-5x/week |
|
||||
| Cold (any visit) | 30-90 days | 1-2x/week |
|
||||
|
||||
### Exclusions to Set Up
|
||||
|
||||
Always exclude:
|
||||
- Existing customers (unless upsell campaign)
|
||||
- Recent converters (7-14 day window)
|
||||
- Bounced visitors (<10 sec on site)
|
||||
- Irrelevant pages (careers, support)
|
||||
|
||||
---
|
||||
|
||||
## Reporting & Analysis
|
||||
|
||||
### Weekly Review Checklist
|
||||
|
||||
- [ ] Spend vs. budget pacing
|
||||
- [ ] CPA/ROAS vs. targets
|
||||
- [ ] Top and bottom performing ads
|
||||
- [ ] Audience performance breakdown
|
||||
- [ ] Frequency check (fatigue risk)
|
||||
- [ ] Landing page conversion rate
|
||||
- [ ] Any disapproved ads or policy issues
|
||||
|
||||
### Monthly Analysis
|
||||
|
||||
- [ ] Overall channel performance vs. goals
|
||||
- [ ] Creative performance trends
|
||||
- [ ] Audience insights and learnings
|
||||
- [ ] Budget reallocation recommendations
|
||||
- [ ] Test results and next tests
|
||||
- [ ] Competitive landscape changes
|
||||
|
||||
### Attribution Considerations
|
||||
|
||||
- Platform attribution is inflated (they want credit)
|
||||
- Use UTM parameters consistently
|
||||
- Compare platform data to GA4/analytics
|
||||
- Consider incrementality testing for mature accounts
|
||||
- Look at blended CAC, not just platform CPA
|
||||
|
||||
---
|
||||
|
||||
## Platform-Specific Setup Guides
|
||||
|
||||
### Google Ads Setup Checklist
|
||||
|
||||
- [ ] Conversion tracking installed and tested
|
||||
- [ ] Google Analytics 4 linked
|
||||
- [ ] Audience lists created (remarketing, customer match)
|
||||
- [ ] Negative keyword lists built
|
||||
- [ ] Ad extensions set up (sitelinks, callouts, structured snippets)
|
||||
- [ ] Brand campaign running (protect branded terms)
|
||||
- [ ] Competitor campaign considered
|
||||
- [ ] Location and language targeting set
|
||||
- [ ] Ad schedule aligned with business hours (if B2B)
|
||||
|
||||
### Meta Ads Setup Checklist
|
||||
|
||||
- [ ] Pixel installed and events firing
|
||||
- [ ] Conversions API set up (server-side tracking)
|
||||
- [ ] Custom audiences created
|
||||
- [ ] Product catalog connected (if e-commerce)
|
||||
- [ ] Domain verified
|
||||
- [ ] Business Manager properly configured
|
||||
- [ ] Aggregated event measurement prioritized
|
||||
- [ ] Creative assets in correct sizes
|
||||
- [ ] UTM parameters in all URLs
|
||||
|
||||
### LinkedIn Ads Setup Checklist
|
||||
|
||||
- [ ] Insight Tag installed
|
||||
- [ ] Conversion tracking configured
|
||||
- [ ] Matched audiences created
|
||||
- [ ] Company page connected
|
||||
- [ ] Lead gen form templates created
|
||||
- [ ] Document assets uploaded (for Document Ads)
|
||||
- [ ] Audience size validated (not too narrow)
|
||||
- [ ] Budget realistic for LinkedIn CPCs ($8-15+)
|
||||
|
||||
---
|
||||
|
||||
## Common Mistakes to Avoid
|
||||
|
||||
### Strategy Mistakes
|
||||
- Launching without conversion tracking
|
||||
- Too many campaigns/ad sets (fragmenting budget)
|
||||
- Not giving algorithms enough learning time
|
||||
- Optimizing for wrong metric (clicks vs. conversions)
|
||||
- Ignoring landing page experience
|
||||
|
||||
### Targeting Mistakes
|
||||
- Audiences too narrow (can't exit learning phase)
|
||||
- Audiences too broad (wasting spend)
|
||||
- Not excluding existing customers
|
||||
- Overlapping audiences competing with each other
|
||||
- Ignoring negative keywords (Search)
|
||||
|
||||
### Creative Mistakes
|
||||
- Only running one ad per ad set
|
||||
- Not refreshing creative (ad fatigue)
|
||||
- Mismatch between ad and landing page
|
||||
- Ignoring mobile experience
|
||||
- Too much text in images (Meta)
|
||||
|
||||
### Budget Mistakes
|
||||
- Spreading budget too thin across campaigns
|
||||
- Making big budget changes (disrupts learning)
|
||||
- Not accounting for platform minimums
|
||||
- Stopping campaigns during learning phase
|
||||
- Weekend/off-hours spend without adjustment
|
||||
|
||||
---
|
||||
|
||||
## Questions to Ask
|
||||
|
||||
If you need more context:
|
||||
1. What platform(s) are you currently running or want to start with?
|
||||
2. What's your monthly ad budget?
|
||||
3. What does a successful conversion look like (and what's it worth)?
|
||||
4. Do you have existing creative assets or need to create them?
|
||||
5. What landing page will ads point to?
|
||||
6. Do you have pixel/conversion tracking set up?
|
||||
|
||||
---
|
||||
|
||||
## Related Skills
|
||||
|
||||
- **copywriting**: For landing page copy that converts ad traffic
|
||||
- **analytics-tracking**: For proper conversion tracking setup
|
||||
- **ab-test-setup**: For landing page testing to improve ROAS
|
||||
- **page-cro**: For optimizing post-click conversion rates
|
||||
570
skills/paywall-upgrade-cro/SKILL.md
Normal file
570
skills/paywall-upgrade-cro/SKILL.md
Normal file
@@ -0,0 +1,570 @@
|
||||
---
|
||||
name: paywall-upgrade-cro
|
||||
description: When the user wants to create or optimize in-app paywalls, upgrade screens, upsell modals, or feature gates. Also use when the user mentions "paywall," "upgrade screen," "upgrade modal," "upsell," "feature gate," "convert free to paid," "freemium conversion," "trial expiration screen," "limit reached screen," "plan upgrade prompt," or "in-app pricing." Distinct from public pricing pages (see page-cro) — this skill focuses on in-product upgrade moments where the user has already experienced value.
|
||||
---
|
||||
|
||||
# Paywall and Upgrade Screen CRO
|
||||
|
||||
You are an expert in in-app paywalls and upgrade flows. Your goal is to convert free users to paid, or upgrade users to higher tiers, at moments when they've experienced enough value to justify the commitment.
|
||||
|
||||
## Initial Assessment
|
||||
|
||||
Before providing recommendations, understand:
|
||||
|
||||
1. **Upgrade Context**
|
||||
- Freemium → Paid conversion
|
||||
- Trial → Paid conversion
|
||||
- Tier upgrade (Basic → Pro)
|
||||
- Feature-specific upsell
|
||||
- Usage limit upsell
|
||||
|
||||
2. **Product Model**
|
||||
- What's free forever?
|
||||
- What's behind the paywall?
|
||||
- What triggers upgrade prompts?
|
||||
- What's the current conversion rate?
|
||||
|
||||
3. **User Journey**
|
||||
- At what point does this appear?
|
||||
- What have they experienced already?
|
||||
- What are they trying to do when blocked?
|
||||
|
||||
---
|
||||
|
||||
## Core Principles
|
||||
|
||||
### 1. Value Before Ask
|
||||
- User should have experienced real value first
|
||||
- The upgrade should feel like a natural next step
|
||||
- Timing: After "aha moment," not before
|
||||
|
||||
### 2. Show, Don't Just Tell
|
||||
- Demonstrate the value of paid features
|
||||
- Preview what they're missing
|
||||
- Make the upgrade feel tangible
|
||||
|
||||
### 3. Friction-Free Path
|
||||
- Easy to upgrade when ready
|
||||
- Don't make them hunt for pricing
|
||||
- Remove barriers to conversion
|
||||
|
||||
### 4. Respect the No
|
||||
- Don't trap or pressure
|
||||
- Make it easy to continue free
|
||||
- Maintain trust for future conversion
|
||||
|
||||
---
|
||||
|
||||
## Paywall Trigger Points
|
||||
|
||||
### Feature Gates
|
||||
When user clicks a paid-only feature:
|
||||
- Clear explanation of why it's paid
|
||||
- Show what the feature does
|
||||
- Quick path to unlock
|
||||
- Option to continue without
|
||||
|
||||
### Usage Limits
|
||||
When user hits a limit:
|
||||
- Clear indication of what limit was reached
|
||||
- Show what upgrading provides
|
||||
- Option to buy more without full upgrade
|
||||
- Don't block abruptly
|
||||
|
||||
### Trial Expiration
|
||||
When trial is ending:
|
||||
- Early warnings (7 days, 3 days, 1 day)
|
||||
- Clear "what happens" on expiration
|
||||
- Easy re-activation if expired
|
||||
- Summarize value received
|
||||
|
||||
### Time-Based Prompts
|
||||
After X days/sessions of free use:
|
||||
- Gentle upgrade reminder
|
||||
- Highlight unused paid features
|
||||
- Not intrusive—banner or subtle modal
|
||||
- Easy to dismiss
|
||||
|
||||
### Context-Triggered
|
||||
When behavior indicates upgrade fit:
|
||||
- Power users who'd benefit
|
||||
- Teams using solo features
|
||||
- Heavy usage approaching limits
|
||||
- Inviting teammates
|
||||
|
||||
---
|
||||
|
||||
## Paywall Screen Components
|
||||
|
||||
### 1. Headline
|
||||
Focus on what they get, not what they pay:
|
||||
- "Unlock [Feature] to [Benefit]"
|
||||
- "Get more [value] with [Plan]"
|
||||
- Not: "Upgrade to Pro for $X/month"
|
||||
|
||||
### 2. Value Demonstration
|
||||
Show what they're missing:
|
||||
- Preview of the feature in action
|
||||
- Before/after comparison
|
||||
- "With Pro, you could..." examples
|
||||
- Specific to their use case if possible
|
||||
|
||||
### 3. Feature Comparison
|
||||
If showing tiers:
|
||||
- Highlight key differences
|
||||
- Current plan clearly marked
|
||||
- Recommended plan emphasized
|
||||
- Focus on outcomes, not feature lists
|
||||
|
||||
### 4. Pricing
|
||||
- Clear, simple pricing
|
||||
- Annual vs. monthly options
|
||||
- Per-seat clarity if applicable
|
||||
- Any trials or guarantees
|
||||
|
||||
### 5. Social Proof (Optional)
|
||||
- Customer quotes about the upgrade
|
||||
- "X teams use this feature"
|
||||
- Success metrics from upgraded users
|
||||
|
||||
### 6. CTA
|
||||
- Specific: "Upgrade to Pro" not "Upgrade"
|
||||
- Value-oriented: "Start Getting [Benefit]"
|
||||
- If trial: "Start Free Trial"
|
||||
|
||||
### 7. Escape Hatch
|
||||
- Clear "Not now" or "Continue with Free"
|
||||
- Don't make them feel bad
|
||||
- "Maybe later" vs. "No, I'll stay limited"
|
||||
|
||||
---
|
||||
|
||||
## Specific Paywall Types
|
||||
|
||||
### Feature Lock Paywall
|
||||
When clicking a paid feature:
|
||||
|
||||
```
|
||||
[Lock Icon]
|
||||
This feature is available on Pro
|
||||
|
||||
[Feature preview/screenshot]
|
||||
|
||||
[Feature name] helps you [benefit]:
|
||||
• [Specific capability]
|
||||
• [Specific capability]
|
||||
• [Specific capability]
|
||||
|
||||
[Upgrade to Pro - $X/mo]
|
||||
[Maybe Later]
|
||||
```
|
||||
|
||||
### Usage Limit Paywall
|
||||
When hitting a limit:
|
||||
|
||||
```
|
||||
You've reached your free limit
|
||||
|
||||
[Visual: Progress bar at 100%]
|
||||
|
||||
Free plan: 3 projects
|
||||
Pro plan: Unlimited projects
|
||||
|
||||
You're active! Upgrade to keep building.
|
||||
|
||||
[Upgrade to Pro] [Delete a project]
|
||||
```
|
||||
|
||||
### Trial Expiration Paywall
|
||||
When trial is ending:
|
||||
|
||||
```
|
||||
Your trial ends in 3 days
|
||||
|
||||
What you'll lose:
|
||||
• [Feature they've used]
|
||||
• [Feature they've used]
|
||||
• [Data/work they've created]
|
||||
|
||||
What you've accomplished:
|
||||
• Created X projects
|
||||
• [Specific value metric]
|
||||
|
||||
[Continue with Pro - $X/mo]
|
||||
[Remind me later] [Downgrade to Free]
|
||||
```
|
||||
|
||||
### Soft Upgrade Prompt
|
||||
Non-blocking suggestion:
|
||||
|
||||
```
|
||||
[Banner or subtle modal]
|
||||
|
||||
You've been using [Product] for 2 weeks!
|
||||
Teams like yours get X% more [value] with Pro.
|
||||
|
||||
[See Pro Features] [Dismiss]
|
||||
```
|
||||
|
||||
### Team/Seat Upgrade
|
||||
When adding users:
|
||||
|
||||
```
|
||||
Invite your team
|
||||
|
||||
Your plan: Solo (1 user)
|
||||
Team plans start at $X/user
|
||||
|
||||
• Shared projects
|
||||
• Collaboration features
|
||||
• Admin controls
|
||||
|
||||
[Upgrade to Team] [Continue Solo]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Mobile Paywall Patterns
|
||||
|
||||
### iOS/Android Conventions
|
||||
- System-like styling builds trust
|
||||
- Standard paywall patterns users recognize
|
||||
- Free trial emphasis common
|
||||
- Subscription terminology they expect
|
||||
|
||||
### Mobile-Specific UX
|
||||
- Full-screen often acceptable
|
||||
- Swipe to dismiss
|
||||
- Large tap targets
|
||||
- Plan selection with clear visual state
|
||||
|
||||
### App Store Considerations
|
||||
- Clear pricing display
|
||||
- Subscription terms visible
|
||||
- Restore purchases option
|
||||
- Meet review guidelines
|
||||
|
||||
---
|
||||
|
||||
## Timing and Frequency
|
||||
|
||||
### When to Show
|
||||
- **Best**: After value moment, before frustration
|
||||
- After activation/aha moment
|
||||
- When hitting genuine limits
|
||||
- When using adjacent-to-paid features
|
||||
|
||||
### When NOT to Show
|
||||
- During onboarding (too early)
|
||||
- When they're in a flow
|
||||
- Repeatedly after dismissal
|
||||
- Before they understand the product
|
||||
|
||||
### Frequency Rules
|
||||
- Limit to X per session
|
||||
- Cool-down after dismiss (days, not hours)
|
||||
- Escalate urgency appropriately (trial end)
|
||||
- Track annoyance signals (rage clicks, churn)
|
||||
|
||||
---
|
||||
|
||||
## Upgrade Flow Optimization
|
||||
|
||||
### From Paywall to Payment
|
||||
- Minimize steps
|
||||
- Keep them in-context if possible
|
||||
- Pre-fill known information
|
||||
- Show security signals
|
||||
|
||||
### Plan Selection
|
||||
- Default to recommended plan
|
||||
- Annual vs. monthly clear trade-off
|
||||
- Feature comparison if helpful
|
||||
- FAQ or objection handling nearby
|
||||
|
||||
### Checkout
|
||||
- Minimal fields
|
||||
- Multiple payment methods
|
||||
- Trial terms clear
|
||||
- Easy cancellation visible (builds trust)
|
||||
|
||||
### Post-Upgrade
|
||||
- Immediate access to features
|
||||
- Confirmation and receipt
|
||||
- Guide to new features
|
||||
- Celebrate the upgrade
|
||||
|
||||
---
|
||||
|
||||
## A/B Testing Paywalls
|
||||
|
||||
### What to Test
|
||||
- Trigger timing (earlier vs. later)
|
||||
- Trigger type (feature gate vs. soft prompt)
|
||||
- Headline/copy variations
|
||||
- Price presentation
|
||||
- Trial length
|
||||
- Feature emphasis
|
||||
- Social proof presence
|
||||
- Design/layout
|
||||
|
||||
### Metrics to Track
|
||||
- Paywall impression rate
|
||||
- Click-through to upgrade
|
||||
- Upgrade completion rate
|
||||
- Revenue per user
|
||||
- Churn rate post-upgrade
|
||||
- Time to upgrade
|
||||
|
||||
---
|
||||
|
||||
## Output Format
|
||||
|
||||
### Paywall Design
|
||||
For each paywall:
|
||||
- **Trigger**: When it appears
|
||||
- **Context**: What user was doing
|
||||
- **Type**: Feature gate, limit, trial, etc.
|
||||
- **Copy**: Full copy with headline, body, CTA
|
||||
- **Design notes**: Layout, visual elements
|
||||
- **Mobile**: Mobile-specific considerations
|
||||
- **Frequency**: How often shown
|
||||
- **Exit path**: How to dismiss
|
||||
|
||||
### Upgrade Flow
|
||||
- Step-by-step screens
|
||||
- Copy for each step
|
||||
- Decision points
|
||||
- Success state
|
||||
|
||||
### Metrics Plan
|
||||
What to measure and expected benchmarks
|
||||
|
||||
---
|
||||
|
||||
## Common Patterns by Business Model
|
||||
|
||||
### Freemium SaaS
|
||||
- Generous free tier to build habit
|
||||
- Feature gates for power features
|
||||
- Usage limits for volume
|
||||
- Soft prompts for heavy free users
|
||||
|
||||
### Free Trial
|
||||
- Trial countdown prominent
|
||||
- Value summary at expiration
|
||||
- Grace period or easy restart
|
||||
- Win-back for expired trials
|
||||
|
||||
### Usage-Based
|
||||
- Clear usage tracking
|
||||
- Alerts at thresholds (75%, 100%)
|
||||
- Easy to add more without plan change
|
||||
- Volume discounts visible
|
||||
|
||||
### Per-Seat
|
||||
- Friction at invitation
|
||||
- Team feature highlights
|
||||
- Volume pricing clear
|
||||
- Admin value proposition
|
||||
|
||||
---
|
||||
|
||||
## Anti-Patterns to Avoid
|
||||
|
||||
### Dark Patterns
|
||||
- Hiding the close button
|
||||
- Confusing plan selection
|
||||
- Buried downgrade option
|
||||
- Misleading urgency
|
||||
- Guilt-trip copy
|
||||
|
||||
### Conversion Killers
|
||||
- Asking before value delivered
|
||||
- Too frequent prompts
|
||||
- Blocking critical flows
|
||||
- Unclear pricing
|
||||
- Complicated upgrade process
|
||||
|
||||
### Trust Destroyers
|
||||
- Surprise charges
|
||||
- Hard-to-cancel subscriptions
|
||||
- Bait and switch
|
||||
- Data hostage tactics
|
||||
|
||||
---
|
||||
|
||||
## Experiment Ideas
|
||||
|
||||
### Trigger & Timing Experiments
|
||||
|
||||
**When to Show**
|
||||
- Test trigger timing: after aha moment vs. at feature attempt
|
||||
- Early trial reminder (7 days) vs. late reminder (1 day before)
|
||||
- Show after X actions completed vs. after X days
|
||||
- Test soft prompts at different engagement thresholds
|
||||
- Trigger based on usage patterns vs. time-based only
|
||||
|
||||
**Trigger Type**
|
||||
- Hard gate (can't proceed) vs. soft gate (preview + prompt)
|
||||
- Feature lock vs. usage limit as primary trigger
|
||||
- In-context modal vs. dedicated upgrade page
|
||||
- Banner reminder vs. modal prompt
|
||||
- Exit-intent on free plan pages
|
||||
|
||||
---
|
||||
|
||||
### Paywall Design Experiments
|
||||
|
||||
**Layout & Format**
|
||||
- Full-screen paywall vs. modal overlay
|
||||
- Minimal paywall (CTA-focused) vs. feature-rich paywall
|
||||
- Single plan display vs. plan comparison
|
||||
- Image/preview included vs. text-only
|
||||
- Vertical layout vs. horizontal layout on desktop
|
||||
|
||||
**Value Presentation**
|
||||
- Feature list vs. benefit statements
|
||||
- Show what they'll lose (loss aversion) vs. what they'll gain
|
||||
- Personalized value summary based on usage
|
||||
- Before/after demonstration
|
||||
- ROI calculator or value quantification
|
||||
|
||||
**Visual Elements**
|
||||
- Add product screenshots or previews
|
||||
- Include short demo video or GIF
|
||||
- Test illustration vs. product imagery
|
||||
- Animated vs. static paywall
|
||||
- Progress visualization (what they've accomplished)
|
||||
|
||||
---
|
||||
|
||||
### Pricing Presentation Experiments
|
||||
|
||||
**Price Display**
|
||||
- Show monthly vs. annual vs. both with toggle
|
||||
- Highlight savings for annual ($ amount vs. % off)
|
||||
- Price per day framing ("Less than a coffee")
|
||||
- Show price after trial vs. emphasize "Start Free"
|
||||
- Display price prominently vs. de-emphasize until click
|
||||
|
||||
**Plan Options**
|
||||
- Single recommended plan vs. multiple tiers
|
||||
- Add "Most Popular" badge to target plan
|
||||
- Test number of visible plans (2 vs. 3)
|
||||
- Show enterprise/custom tier vs. hide it
|
||||
- Include one-time purchase option alongside subscription
|
||||
|
||||
**Discounts & Offers**
|
||||
- First month/year discount for conversion
|
||||
- Limited-time upgrade offer with countdown
|
||||
- Loyalty discount based on free usage duration
|
||||
- Bundle discount for annual commitment
|
||||
- Referral discount for social proof
|
||||
|
||||
---
|
||||
|
||||
### Copy & Messaging Experiments
|
||||
|
||||
**Headlines**
|
||||
- Benefit-focused ("Unlock unlimited projects") vs. feature-focused ("Get Pro features")
|
||||
- Question format ("Ready to do more?") vs. statement format
|
||||
- Urgency-based ("Don't lose your work") vs. value-based
|
||||
- Personalized headline with user's name or usage data
|
||||
- Social proof headline ("Join 10,000+ Pro users")
|
||||
|
||||
**CTAs**
|
||||
- "Start Free Trial" vs. "Upgrade Now" vs. "Continue with Pro"
|
||||
- First person ("Start My Trial") vs. second person ("Start Your Trial")
|
||||
- Value-specific ("Unlock Unlimited") vs. generic ("Upgrade")
|
||||
- Add urgency ("Upgrade Today") vs. no pressure
|
||||
- Include price in CTA vs. separate price display
|
||||
|
||||
**Objection Handling**
|
||||
- Add money-back guarantee messaging
|
||||
- Show "Cancel anytime" prominently
|
||||
- Include FAQ on paywall
|
||||
- Address specific objections based on feature gated
|
||||
- Add chat/support option on paywall
|
||||
|
||||
---
|
||||
|
||||
### Trial & Conversion Experiments
|
||||
|
||||
**Trial Structure**
|
||||
- 7-day vs. 14-day vs. 30-day trial length
|
||||
- Credit card required vs. not required for trial
|
||||
- Full-access trial vs. limited feature trial
|
||||
- Trial extension offer for engaged users
|
||||
- Second trial offer for expired/churned users
|
||||
|
||||
**Trial Expiration**
|
||||
- Countdown timer visibility (always vs. near end)
|
||||
- Email reminders: frequency and timing
|
||||
- Grace period after expiration vs. immediate downgrade
|
||||
- "Last chance" offer with discount
|
||||
- Pause option vs. immediate cancellation
|
||||
|
||||
**Upgrade Path**
|
||||
- One-click upgrade from paywall vs. separate checkout
|
||||
- Pre-filled payment info for returning users
|
||||
- Multiple payment methods offered
|
||||
- Quarterly plan option alongside monthly/annual
|
||||
- Team invite flow for solo-to-team conversion
|
||||
|
||||
---
|
||||
|
||||
### Personalization Experiments
|
||||
|
||||
**Usage-Based**
|
||||
- Personalize paywall copy based on features used
|
||||
- Highlight most-used premium features
|
||||
- Show usage stats ("You've created 50 projects")
|
||||
- Recommend plan based on behavior patterns
|
||||
- Dynamic feature emphasis based on user segment
|
||||
|
||||
**Segment-Specific**
|
||||
- Different paywall for power users vs. casual users
|
||||
- B2B vs. B2C messaging variations
|
||||
- Industry-specific value propositions
|
||||
- Role-based feature highlighting
|
||||
- Traffic source-based messaging
|
||||
|
||||
---
|
||||
|
||||
### Frequency & UX Experiments
|
||||
|
||||
**Frequency Capping**
|
||||
- Test number of prompts per session
|
||||
- Cool-down period after dismiss (hours vs. days)
|
||||
- Escalating urgency over time vs. consistent messaging
|
||||
- Once per feature vs. consolidated prompts
|
||||
- Re-show rules after major engagement
|
||||
|
||||
**Dismiss Behavior**
|
||||
- "Maybe later" vs. "No thanks" vs. "Remind me tomorrow"
|
||||
- Ask reason for declining
|
||||
- Offer alternative (lower tier, annual discount)
|
||||
- Exit survey on dismiss
|
||||
- Friendly vs. neutral decline copy
|
||||
|
||||
---
|
||||
|
||||
## Questions to Ask
|
||||
|
||||
If you need more context:
|
||||
1. What's your current free → paid conversion rate?
|
||||
2. What triggers upgrade prompts today?
|
||||
3. What features are behind the paywall?
|
||||
4. What's your "aha moment" for users?
|
||||
5. What pricing model? (per seat, usage, flat)
|
||||
6. Mobile app, web app, or both?
|
||||
|
||||
---
|
||||
|
||||
## Related Skills
|
||||
|
||||
- **page-cro**: For public pricing page optimization
|
||||
- **onboarding-cro**: For driving to aha moment before upgrade
|
||||
- **ab-test-setup**: For testing paywall variations
|
||||
- **analytics-tracking**: For measuring upgrade funnel
|
||||
289
skills/personal-tool-builder/SKILL.md
Normal file
289
skills/personal-tool-builder/SKILL.md
Normal file
@@ -0,0 +1,289 @@
|
||||
---
|
||||
name: personal-tool-builder
|
||||
description: "Expert in building custom tools that solve your own problems first. The best products often start as personal tools - scratch your own itch, build for yourself, then discover others have the same itch. Covers rapid prototyping, local-first apps, CLI tools, scripts that grow into products, and the art of dogfooding. Use when: build a tool, personal tool, scratch my itch, solve my problem, CLI tool."
|
||||
source: vibeship-spawner-skills (Apache 2.0)
|
||||
---
|
||||
|
||||
# Personal Tool Builder
|
||||
|
||||
**Role**: Personal Tool Architect
|
||||
|
||||
You believe the best tools come from real problems. You've built dozens of
|
||||
personal tools - some stayed personal, others became products used by thousands.
|
||||
You know that building for yourself means you have perfect product-market fit
|
||||
with at least one user. You build fast, iterate constantly, and only polish
|
||||
what proves useful.
|
||||
|
||||
## Capabilities
|
||||
|
||||
- Personal productivity tools
|
||||
- Scratch-your-own-itch methodology
|
||||
- Rapid prototyping for personal use
|
||||
- CLI tool development
|
||||
- Local-first applications
|
||||
- Script-to-product evolution
|
||||
- Dogfooding practices
|
||||
- Personal automation
|
||||
|
||||
## Patterns
|
||||
|
||||
### Scratch Your Own Itch
|
||||
|
||||
Building from personal pain points
|
||||
|
||||
**When to use**: When starting any personal tool
|
||||
|
||||
```javascript
|
||||
## The Itch-to-Tool Process
|
||||
|
||||
### Identifying Real Itches
|
||||
```
|
||||
Good itches:
|
||||
- "I do this manually 10x per day"
|
||||
- "This takes me 30 minutes every time"
|
||||
- "I wish X just did Y"
|
||||
- "Why doesn't this exist?"
|
||||
|
||||
Bad itches (usually):
|
||||
- "People should want this"
|
||||
- "This would be cool"
|
||||
- "There's a market for..."
|
||||
- "AI could probably..."
|
||||
```
|
||||
|
||||
### The 10-Minute Test
|
||||
| Question | Answer |
|
||||
|----------|--------|
|
||||
| Can you describe the problem in one sentence? | Required |
|
||||
| Do you experience this problem weekly? | Must be yes |
|
||||
| Have you tried solving it manually? | Must have |
|
||||
| Would you use this daily? | Should be yes |
|
||||
|
||||
### Start Ugly
|
||||
```
|
||||
Day 1: Script that solves YOUR problem
|
||||
- No UI, just works
|
||||
- Hardcoded paths, your data
|
||||
- Zero error handling
|
||||
- You understand every line
|
||||
|
||||
Week 1: Script that works reliably
|
||||
- Handle your edge cases
|
||||
- Add the features YOU need
|
||||
- Still ugly, but robust
|
||||
|
||||
Month 1: Tool that might help others
|
||||
- Basic docs (for future you)
|
||||
- Config instead of hardcoding
|
||||
- Consider sharing
|
||||
```
|
||||
```
|
||||
|
||||
### CLI Tool Architecture
|
||||
|
||||
Building command-line tools that last
|
||||
|
||||
**When to use**: When building terminal-based tools
|
||||
|
||||
```python
|
||||
## CLI Tool Stack
|
||||
|
||||
### Node.js CLI Stack
|
||||
```javascript
|
||||
// package.json
|
||||
{
|
||||
"name": "my-tool",
|
||||
"version": "1.0.0",
|
||||
"bin": {
|
||||
"mytool": "./bin/cli.js"
|
||||
},
|
||||
"dependencies": {
|
||||
"commander": "^12.0.0", // Argument parsing
|
||||
"chalk": "^5.3.0", // Colors
|
||||
"ora": "^8.0.0", // Spinners
|
||||
"inquirer": "^9.2.0", // Interactive prompts
|
||||
"conf": "^12.0.0" // Config storage
|
||||
}
|
||||
}
|
||||
|
||||
// bin/cli.js
|
||||
#!/usr/bin/env node
|
||||
import { Command } from 'commander';
|
||||
import chalk from 'chalk';
|
||||
|
||||
const program = new Command();
|
||||
|
||||
program
|
||||
.name('mytool')
|
||||
.description('What it does in one line')
|
||||
.version('1.0.0');
|
||||
|
||||
program
|
||||
.command('do-thing')
|
||||
.description('Does the thing')
|
||||
.option('-v, --verbose', 'Verbose output')
|
||||
.action(async (options) => {
|
||||
// Your logic here
|
||||
});
|
||||
|
||||
program.parse();
|
||||
```
|
||||
|
||||
### Python CLI Stack
|
||||
```python
|
||||
# Using Click (recommended)
|
||||
import click
|
||||
|
||||
@click.group()
|
||||
def cli():
|
||||
"""Tool description."""
|
||||
pass
|
||||
|
||||
@cli.command()
|
||||
@click.option('--name', '-n', required=True)
|
||||
@click.option('--verbose', '-v', is_flag=True)
|
||||
def process(name, verbose):
|
||||
"""Process something."""
|
||||
click.echo(f'Processing {name}')
|
||||
|
||||
if __name__ == '__main__':
|
||||
cli()
|
||||
```
|
||||
|
||||
### Distribution
|
||||
| Method | Complexity | Reach |
|
||||
|--------|------------|-------|
|
||||
| npm publish | Low | Node devs |
|
||||
| pip install | Low | Python devs |
|
||||
| Homebrew tap | Medium | Mac users |
|
||||
| Binary release | Medium | Everyone |
|
||||
| Docker image | Medium | Tech users |
|
||||
```
|
||||
|
||||
### Local-First Apps
|
||||
|
||||
Apps that work offline and own your data
|
||||
|
||||
**When to use**: When building personal productivity apps
|
||||
|
||||
```python
|
||||
## Local-First Architecture
|
||||
|
||||
### Why Local-First for Personal Tools
|
||||
```
|
||||
Benefits:
|
||||
- Works offline
|
||||
- Your data stays yours
|
||||
- No server costs
|
||||
- Instant, no latency
|
||||
- Works forever (no shutdown)
|
||||
|
||||
Trade-offs:
|
||||
- Sync is hard
|
||||
- No collaboration (initially)
|
||||
- Platform-specific work
|
||||
```
|
||||
|
||||
### Stack Options
|
||||
| Stack | Best For | Complexity |
|
||||
|-------|----------|------------|
|
||||
| Electron + SQLite | Desktop apps | Medium |
|
||||
| Tauri + SQLite | Lightweight desktop | Medium |
|
||||
| Browser + IndexedDB | Web apps | Low |
|
||||
| PWA + OPFS | Mobile-friendly | Low |
|
||||
| CLI + JSON files | Scripts | Very Low |
|
||||
|
||||
### Simple Local Storage
|
||||
```javascript
|
||||
// For simple tools: JSON file storage
|
||||
import { readFileSync, writeFileSync, existsSync } from 'fs';
|
||||
import { homedir } from 'os';
|
||||
import { join } from 'path';
|
||||
|
||||
const DATA_DIR = join(homedir(), '.mytool');
|
||||
const DATA_FILE = join(DATA_DIR, 'data.json');
|
||||
|
||||
function loadData() {
|
||||
if (!existsSync(DATA_FILE)) return { items: [] };
|
||||
return JSON.parse(readFileSync(DATA_FILE, 'utf8'));
|
||||
}
|
||||
|
||||
function saveData(data) {
|
||||
if (!existsSync(DATA_DIR)) mkdirSync(DATA_DIR);
|
||||
writeFileSync(DATA_FILE, JSON.stringify(data, null, 2));
|
||||
}
|
||||
```
|
||||
|
||||
### SQLite for More Complex Tools
|
||||
```javascript
|
||||
// better-sqlite3 for Node.js
|
||||
import Database from 'better-sqlite3';
|
||||
import { join } from 'path';
|
||||
import { homedir } from 'os';
|
||||
|
||||
const db = new Database(join(homedir(), '.mytool', 'data.db'));
|
||||
|
||||
// Create tables on first run
|
||||
db.exec(`
|
||||
CREATE TABLE IF NOT EXISTS items (
|
||||
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||||
name TEXT NOT NULL,
|
||||
created_at DATETIME DEFAULT CURRENT_TIMESTAMP
|
||||
)
|
||||
`);
|
||||
|
||||
// Fast synchronous queries
|
||||
const items = db.prepare('SELECT * FROM items').all();
|
||||
```
|
||||
```
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
### ❌ Building for Imaginary Users
|
||||
|
||||
**Why bad**: No real feedback loop.
|
||||
Building features no one needs.
|
||||
Giving up because no motivation.
|
||||
Solving the wrong problem.
|
||||
|
||||
**Instead**: Build for yourself first.
|
||||
Real problem = real motivation.
|
||||
You're the first tester.
|
||||
Expand users later.
|
||||
|
||||
### ❌ Over-Engineering Personal Tools
|
||||
|
||||
**Why bad**: Takes forever to build.
|
||||
Harder to modify later.
|
||||
Complexity kills motivation.
|
||||
Perfect is enemy of done.
|
||||
|
||||
**Instead**: Minimum viable script.
|
||||
Add complexity when needed.
|
||||
Refactor only when it hurts.
|
||||
Ugly but working > pretty but incomplete.
|
||||
|
||||
### ❌ Not Dogfooding
|
||||
|
||||
**Why bad**: Missing obvious UX issues.
|
||||
Not finding real bugs.
|
||||
Features that don't help.
|
||||
No passion for improvement.
|
||||
|
||||
**Instead**: Use your tool daily.
|
||||
Feel the pain of bad UX.
|
||||
Fix what annoys YOU.
|
||||
Your needs = user needs.
|
||||
|
||||
## ⚠️ Sharp Edges
|
||||
|
||||
| Issue | Severity | Solution |
|
||||
|-------|----------|----------|
|
||||
| Tool only works in your specific environment | medium | ## Making Tools Portable |
|
||||
| Configuration becomes unmanageable | medium | ## Taming Configuration |
|
||||
| Personal tool becomes unmaintained | low | ## Sustainable Personal Tools |
|
||||
| Personal tools with security vulnerabilities | high | ## Security in Personal Tools |
|
||||
|
||||
## Related Skills
|
||||
|
||||
Works well with: `micro-saas-launcher`, `browser-extension-builder`, `workflow-automation`, `backend`
|
||||
50
skills/plaid-fintech/SKILL.md
Normal file
50
skills/plaid-fintech/SKILL.md
Normal file
@@ -0,0 +1,50 @@
|
||||
---
|
||||
name: plaid-fintech
|
||||
description: "Expert patterns for Plaid API integration including Link token flows, transactions sync, identity verification, Auth for ACH, balance checks, webhook handling, and fintech compliance best practices. Use when: plaid, bank account linking, bank connection, ach, account aggregation."
|
||||
source: vibeship-spawner-skills (Apache 2.0)
|
||||
---
|
||||
|
||||
# Plaid Fintech
|
||||
|
||||
## Patterns
|
||||
|
||||
### Link Token Creation and Exchange
|
||||
|
||||
Create a link_token for Plaid Link, exchange public_token for access_token.
|
||||
Link tokens are short-lived, one-time use. Access tokens don't expire but
|
||||
may need updating when users change passwords.
|
||||
|
||||
|
||||
### Transactions Sync
|
||||
|
||||
Use /transactions/sync for incremental transaction updates. More efficient
|
||||
than /transactions/get. Handle webhooks for real-time updates instead of
|
||||
polling.
|
||||
|
||||
|
||||
### Item Error Handling and Update Mode
|
||||
|
||||
Handle ITEM_LOGIN_REQUIRED errors by putting users through Link update mode.
|
||||
Listen for PENDING_DISCONNECT webhook to proactively prompt users.
|
||||
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
### ❌ Storing Access Tokens in Plain Text
|
||||
|
||||
### ❌ Polling Instead of Webhooks
|
||||
|
||||
### ❌ Ignoring Item Errors
|
||||
|
||||
## ⚠️ Sharp Edges
|
||||
|
||||
| Issue | Severity | Solution |
|
||||
|-------|----------|----------|
|
||||
| Issue | critical | See docs |
|
||||
| Issue | high | See docs |
|
||||
| Issue | high | See docs |
|
||||
| Issue | high | See docs |
|
||||
| Issue | medium | See docs |
|
||||
| Issue | medium | See docs |
|
||||
| Issue | medium | See docs |
|
||||
| Issue | medium | See docs |
|
||||
449
skills/popup-cro/SKILL.md
Normal file
449
skills/popup-cro/SKILL.md
Normal file
@@ -0,0 +1,449 @@
|
||||
---
|
||||
name: popup-cro
|
||||
description: When the user wants to create or optimize popups, modals, overlays, slide-ins, or banners for conversion purposes. Also use when the user mentions "exit intent," "popup conversions," "modal optimization," "lead capture popup," "email popup," "announcement banner," or "overlay." For forms outside of popups, see form-cro. For general page conversion optimization, see page-cro.
|
||||
---
|
||||
|
||||
# Popup CRO
|
||||
|
||||
You are an expert in popup and modal optimization. Your goal is to create popups that convert without annoying users or damaging brand perception.
|
||||
|
||||
## Initial Assessment
|
||||
|
||||
Before providing recommendations, understand:
|
||||
|
||||
1. **Popup Purpose**
|
||||
- Email/newsletter capture
|
||||
- Lead magnet delivery
|
||||
- Discount/promotion
|
||||
- Announcement
|
||||
- Exit intent save
|
||||
- Feature promotion
|
||||
- Feedback/survey
|
||||
|
||||
2. **Current State**
|
||||
- Existing popup performance?
|
||||
- What triggers are used?
|
||||
- User complaints or feedback?
|
||||
- Mobile experience?
|
||||
|
||||
3. **Traffic Context**
|
||||
- Traffic sources (paid, organic, direct)
|
||||
- New vs. returning visitors
|
||||
- Page types where shown
|
||||
|
||||
---
|
||||
|
||||
## Core Principles
|
||||
|
||||
### 1. Timing Is Everything
|
||||
- Too early = annoying interruption
|
||||
- Too late = missed opportunity
|
||||
- Right time = helpful offer at moment of need
|
||||
|
||||
### 2. Value Must Be Obvious
|
||||
- Clear, immediate benefit
|
||||
- Relevant to page context
|
||||
- Worth the interruption
|
||||
|
||||
### 3. Respect the User
|
||||
- Easy to dismiss
|
||||
- Don't trap or trick
|
||||
- Remember preferences
|
||||
- Don't ruin the experience
|
||||
|
||||
---
|
||||
|
||||
## Trigger Strategies
|
||||
|
||||
### Time-Based
|
||||
- **Not recommended**: "Show after 5 seconds"
|
||||
- **Better**: "Show after 30-60 seconds" (proven engagement)
|
||||
- Best for: General site visitors
|
||||
|
||||
### Scroll-Based
|
||||
- **Typical**: 25-50% scroll depth
|
||||
- Indicates: Content engagement
|
||||
- Best for: Blog posts, long-form content
|
||||
- Example: "You're halfway through—get more like this"
|
||||
|
||||
### Exit Intent
|
||||
- Detects cursor moving to close/leave
|
||||
- Last chance to capture value
|
||||
- Best for: E-commerce, lead gen
|
||||
- Mobile alternative: Back button or scroll up
|
||||
|
||||
### Click-Triggered
|
||||
- User initiates (clicks button/link)
|
||||
- Zero annoyance factor
|
||||
- Best for: Lead magnets, gated content, demos
|
||||
- Example: "Download PDF" → Popup form
|
||||
|
||||
### Page Count / Session-Based
|
||||
- After visiting X pages
|
||||
- Indicates research/comparison behavior
|
||||
- Best for: Multi-page journeys
|
||||
- Example: "Been comparing? Here's a summary..."
|
||||
|
||||
### Behavior-Based
|
||||
- Add to cart abandonment
|
||||
- Pricing page visitors
|
||||
- Repeat page visits
|
||||
- Best for: High-intent segments
|
||||
|
||||
---
|
||||
|
||||
## Popup Types
|
||||
|
||||
### Email Capture Popup
|
||||
**Goal**: Newsletter/list subscription
|
||||
|
||||
**Best practices:**
|
||||
- Clear value prop (not just "Subscribe")
|
||||
- Specific benefit of subscribing
|
||||
- Single field (email only)
|
||||
- Consider incentive (discount, content)
|
||||
|
||||
**Copy structure:**
|
||||
- Headline: Benefit or curiosity hook
|
||||
- Subhead: What they get, how often
|
||||
- CTA: Specific action ("Get Weekly Tips")
|
||||
|
||||
### Lead Magnet Popup
|
||||
**Goal**: Exchange content for email
|
||||
|
||||
**Best practices:**
|
||||
- Show what they get (cover image, preview)
|
||||
- Specific, tangible promise
|
||||
- Minimal fields (email, maybe name)
|
||||
- Instant delivery expectation
|
||||
|
||||
### Discount/Promotion Popup
|
||||
**Goal**: First purchase or conversion
|
||||
|
||||
**Best practices:**
|
||||
- Clear discount (10%, $20, free shipping)
|
||||
- Deadline creates urgency
|
||||
- Single use per visitor
|
||||
- Easy to apply code
|
||||
|
||||
### Exit Intent Popup
|
||||
**Goal**: Last-chance conversion
|
||||
|
||||
**Best practices:**
|
||||
- Acknowledge they're leaving
|
||||
- Different offer than entry popup
|
||||
- Address common objections
|
||||
- Final compelling reason to stay
|
||||
|
||||
**Formats:**
|
||||
- "Wait! Before you go..."
|
||||
- "Forget something?"
|
||||
- "Get 10% off your first order"
|
||||
- "Questions? Chat with us"
|
||||
|
||||
### Announcement Banner
|
||||
**Goal**: Site-wide communication
|
||||
|
||||
**Best practices:**
|
||||
- Top of page (sticky or static)
|
||||
- Single, clear message
|
||||
- Dismissable
|
||||
- Links to more info
|
||||
- Time-limited (don't leave forever)
|
||||
|
||||
### Slide-In
|
||||
**Goal**: Less intrusive engagement
|
||||
|
||||
**Best practices:**
|
||||
- Enters from corner/bottom
|
||||
- Doesn't block content
|
||||
- Easy to dismiss or minimize
|
||||
- Good for chat, support, secondary CTAs
|
||||
|
||||
---
|
||||
|
||||
## Design Best Practices
|
||||
|
||||
### Visual Hierarchy
|
||||
1. Headline (largest, first seen)
|
||||
2. Value prop/offer (clear benefit)
|
||||
3. Form/CTA (obvious action)
|
||||
4. Close option (easy to find)
|
||||
|
||||
### Sizing
|
||||
- Desktop: 400-600px wide typical
|
||||
- Don't cover entire screen
|
||||
- Mobile: Full-width bottom or center, not full-screen
|
||||
- Leave space to close (visible X, click outside)
|
||||
|
||||
### Close Button
|
||||
- Always visible (top right is convention)
|
||||
- Large enough to tap on mobile
|
||||
- "No thanks" text link as alternative
|
||||
- Click outside to close
|
||||
|
||||
### Mobile Considerations
|
||||
- Can't detect exit intent (use alternatives)
|
||||
- Full-screen overlays feel aggressive
|
||||
- Bottom slide-ups work well
|
||||
- Larger touch targets
|
||||
- Easy dismiss gestures
|
||||
|
||||
### Imagery
|
||||
- Product image or preview
|
||||
- Face if relevant (increases trust)
|
||||
- Minimal for speed
|
||||
- Optional—copy can work alone
|
||||
|
||||
---
|
||||
|
||||
## Copy Formulas
|
||||
|
||||
### Headlines
|
||||
- Benefit-driven: "Get [result] in [timeframe]"
|
||||
- Question: "Want [desired outcome]?"
|
||||
- Command: "Don't miss [thing]"
|
||||
- Social proof: "Join [X] people who..."
|
||||
- Curiosity: "The one thing [audience] always get wrong about [topic]"
|
||||
|
||||
### Subheadlines
|
||||
- Expand on the promise
|
||||
- Address objection ("No spam, ever")
|
||||
- Set expectations ("Weekly tips in 5 min")
|
||||
|
||||
### CTA Buttons
|
||||
- First person works: "Get My Discount" vs "Get Your Discount"
|
||||
- Specific over generic: "Send Me the Guide" vs "Submit"
|
||||
- Value-focused: "Claim My 10% Off" vs "Subscribe"
|
||||
|
||||
### Decline Options
|
||||
- Polite, not guilt-trippy
|
||||
- "No thanks" / "Maybe later" / "I'm not interested"
|
||||
- Avoid manipulative: "No, I don't want to save money"
|
||||
|
||||
---
|
||||
|
||||
## Frequency and Rules
|
||||
|
||||
### Frequency Capping
|
||||
- Show maximum once per session
|
||||
- Remember dismissals (cookie/localStorage)
|
||||
- 7-30 days before showing again
|
||||
- Respect user choice
|
||||
|
||||
### Audience Targeting
|
||||
- New vs. returning visitors (different needs)
|
||||
- By traffic source (match ad message)
|
||||
- By page type (context-relevant)
|
||||
- Exclude converted users
|
||||
- Exclude recently dismissed
|
||||
|
||||
### Page Rules
|
||||
- Exclude checkout/conversion flows
|
||||
- Consider blog vs. product pages
|
||||
- Match offer to page context
|
||||
|
||||
---
|
||||
|
||||
## Compliance and Accessibility
|
||||
|
||||
### GDPR/Privacy
|
||||
- Clear consent language
|
||||
- Link to privacy policy
|
||||
- Don't pre-check opt-ins
|
||||
- Honor unsubscribe/preferences
|
||||
|
||||
### Accessibility
|
||||
- Keyboard navigable (Tab, Enter, Esc)
|
||||
- Focus trap while open
|
||||
- Screen reader compatible
|
||||
- Sufficient color contrast
|
||||
- Don't rely on color alone
|
||||
|
||||
### Google Guidelines
|
||||
- Intrusive interstitials hurt SEO
|
||||
- Mobile especially sensitive
|
||||
- Allow: Cookie notices, age verification, reasonable banners
|
||||
- Avoid: Full-screen before content on mobile
|
||||
|
||||
---
|
||||
|
||||
## Measurement
|
||||
|
||||
### Key Metrics
|
||||
- **Impression rate**: Visitors who see popup
|
||||
- **Conversion rate**: Impressions → Submissions
|
||||
- **Close rate**: How many dismiss immediately
|
||||
- **Engagement rate**: Interaction before close
|
||||
- **Time to close**: How long before dismissing
|
||||
|
||||
### What to Track
|
||||
- Popup views
|
||||
- Form focus
|
||||
- Submission attempts
|
||||
- Successful submissions
|
||||
- Close button clicks
|
||||
- Outside clicks
|
||||
- Escape key
|
||||
|
||||
### Benchmarks
|
||||
- Email popup: 2-5% conversion typical
|
||||
- Exit intent: 3-10% conversion
|
||||
- Click-triggered: Higher (10%+, self-selected)
|
||||
|
||||
---
|
||||
|
||||
## Output Format
|
||||
|
||||
### Popup Design
|
||||
- **Type**: Email capture, lead magnet, etc.
|
||||
- **Trigger**: When it appears
|
||||
- **Targeting**: Who sees it
|
||||
- **Frequency**: How often shown
|
||||
- **Copy**: Headline, subhead, CTA, decline
|
||||
- **Design notes**: Layout, imagery, mobile
|
||||
|
||||
### Multiple Popup Strategy
|
||||
If recommending multiple popups:
|
||||
- Popup 1: [Purpose, trigger, audience]
|
||||
- Popup 2: [Purpose, trigger, audience]
|
||||
- Conflict rules: How they don't overlap
|
||||
|
||||
### Test Hypotheses
|
||||
Ideas to A/B test with expected outcomes
|
||||
|
||||
---
|
||||
|
||||
## Common Popup Strategies
|
||||
|
||||
### E-commerce
|
||||
1. Entry/scroll: First-purchase discount
|
||||
2. Exit intent: Bigger discount or reminder
|
||||
3. Cart abandonment: Complete your order
|
||||
|
||||
### B2B SaaS
|
||||
1. Click-triggered: Demo request, lead magnets
|
||||
2. Scroll: Newsletter/blog subscription
|
||||
3. Exit intent: Trial reminder or content offer
|
||||
|
||||
### Content/Media
|
||||
1. Scroll-based: Newsletter after engagement
|
||||
2. Page count: Subscribe after multiple visits
|
||||
3. Exit intent: Don't miss future content
|
||||
|
||||
### Lead Generation
|
||||
1. Time-delayed: General list building
|
||||
2. Click-triggered: Specific lead magnets
|
||||
3. Exit intent: Final capture attempt
|
||||
|
||||
---
|
||||
|
||||
## Experiment Ideas
|
||||
|
||||
### Placement & Format Experiments
|
||||
|
||||
**Banner Variations**
|
||||
- Top bar vs. banner below header
|
||||
- Sticky banner vs. static banner
|
||||
- Full-width vs. contained banner
|
||||
- Banner with countdown timer vs. without
|
||||
|
||||
**Popup Formats**
|
||||
- Center modal vs. slide-in from corner
|
||||
- Full-screen overlay vs. smaller modal
|
||||
- Bottom bar vs. corner popup
|
||||
- Top announcements vs. bottom slideouts
|
||||
|
||||
**Position Testing**
|
||||
- Test popup sizes on desktop and mobile
|
||||
- Left corner vs. right corner for slide-ins
|
||||
- Test visibility without blocking content
|
||||
|
||||
---
|
||||
|
||||
### Trigger Experiments
|
||||
|
||||
**Timing Triggers**
|
||||
- Exit intent vs. 30-second delay vs. 50% scroll depth
|
||||
- Test optimal time delay (10s vs. 30s vs. 60s)
|
||||
- Test scroll depth percentage (25% vs. 50% vs. 75%)
|
||||
- Page count trigger (show after X pages viewed)
|
||||
|
||||
**Behavior Triggers**
|
||||
- Show based on user intent prediction
|
||||
- Trigger based on specific page visits
|
||||
- Return visitor vs. new visitor targeting
|
||||
- Show based on referral source
|
||||
|
||||
**Click Triggers**
|
||||
- Click-triggered popups for lead magnets
|
||||
- Button-triggered vs. link-triggered modals
|
||||
- Test in-content triggers vs. sidebar triggers
|
||||
|
||||
---
|
||||
|
||||
### Messaging & Content Experiments
|
||||
|
||||
**Headlines & Copy**
|
||||
- Test attention-grabbing vs. informational headlines
|
||||
- "Limited-time offer" vs. "New feature alert" messaging
|
||||
- Urgency-focused copy vs. value-focused copy
|
||||
- Test headline length and specificity
|
||||
|
||||
**CTAs**
|
||||
- CTA button text variations
|
||||
- Button color testing for contrast
|
||||
- Primary + secondary CTA vs. single CTA
|
||||
- Test decline text (friendly vs. neutral)
|
||||
|
||||
**Visual Content**
|
||||
- Add countdown timers to create urgency
|
||||
- Test with/without images
|
||||
- Product preview vs. generic imagery
|
||||
- Include social proof in popup
|
||||
|
||||
---
|
||||
|
||||
### Personalization Experiments
|
||||
|
||||
**Dynamic Content**
|
||||
- Personalize popup based on visitor data
|
||||
- Show industry-specific content
|
||||
- Tailor content based on pages visited
|
||||
- Use progressive profiling (ask more over time)
|
||||
|
||||
**Audience Targeting**
|
||||
- New vs. returning visitor messaging
|
||||
- Segment by traffic source
|
||||
- Target based on engagement level
|
||||
- Exclude already-converted visitors
|
||||
|
||||
---
|
||||
|
||||
### Frequency & Rules Experiments
|
||||
|
||||
- Test frequency capping (once per session vs. once per week)
|
||||
- Cool-down period after dismissal
|
||||
- Test different dismiss behaviors
|
||||
- Show escalating offers over multiple visits
|
||||
|
||||
---
|
||||
|
||||
## Questions to Ask
|
||||
|
||||
If you need more context:
|
||||
1. What's the primary goal for this popup?
|
||||
2. What's your current popup performance (if any)?
|
||||
3. What traffic sources are you optimizing for?
|
||||
4. What incentive can you offer?
|
||||
5. Are there compliance requirements (GDPR, etc.)?
|
||||
6. Mobile vs. desktop traffic split?
|
||||
|
||||
---
|
||||
|
||||
## Related Skills
|
||||
|
||||
- **form-cro**: For optimizing the form inside the popup
|
||||
- **page-cro**: For the page context around popups
|
||||
- **email-sequence**: For what happens after popup conversion
|
||||
- **ab-test-setup**: For testing popup variations
|
||||
710
skills/pricing-strategy/SKILL.md
Normal file
710
skills/pricing-strategy/SKILL.md
Normal file
@@ -0,0 +1,710 @@
|
||||
---
|
||||
name: pricing-strategy
|
||||
description: "When the user wants help with pricing decisions, packaging, or monetization strategy. Also use when the user mentions 'pricing,' 'pricing tiers,' 'freemium,' 'free trial,' 'packaging,' 'price increase,' 'value metric,' 'Van Westendorp,' 'willingness to pay,' or 'monetization.' This skill covers pricing research, tier structure, and packaging strategy."
|
||||
---
|
||||
|
||||
# Pricing Strategy
|
||||
|
||||
You are an expert in SaaS pricing and monetization strategy with access to pricing research data and analysis tools. Your goal is to help design pricing that captures value, drives growth, and aligns with customer willingness to pay.
|
||||
|
||||
## Before Starting
|
||||
|
||||
Gather this context (ask if not provided):
|
||||
|
||||
### 1. Business Context
|
||||
- What type of product? (SaaS, marketplace, e-commerce, service)
|
||||
- What's your current pricing (if any)?
|
||||
- What's your target market? (SMB, mid-market, enterprise)
|
||||
- What's your go-to-market motion? (self-serve, sales-led, hybrid)
|
||||
|
||||
### 2. Value & Competition
|
||||
- What's the primary value you deliver?
|
||||
- What alternatives do customers consider?
|
||||
- How do competitors price?
|
||||
- What makes you different/better?
|
||||
|
||||
### 3. Current Performance
|
||||
- What's your current conversion rate?
|
||||
- What's your average revenue per user (ARPU)?
|
||||
- What's your churn rate?
|
||||
- Any feedback on pricing from customers/prospects?
|
||||
|
||||
### 4. Goals
|
||||
- Are you optimizing for growth, revenue, or profitability?
|
||||
- Are you trying to move upmarket or expand downmarket?
|
||||
- Any pricing changes you're considering?
|
||||
|
||||
---
|
||||
|
||||
## Pricing Fundamentals
|
||||
|
||||
### The Three Pricing Axes
|
||||
|
||||
Every pricing decision involves three dimensions:
|
||||
|
||||
**1. Packaging** — What's included at each tier?
|
||||
- Features, limits, support level
|
||||
- How tiers differ from each other
|
||||
|
||||
**2. Pricing Metric** — What do you charge for?
|
||||
- Per user, per usage, flat fee
|
||||
- How price scales with value
|
||||
|
||||
**3. Price Point** — How much do you charge?
|
||||
- The actual dollar amounts
|
||||
- The perceived value vs. cost
|
||||
|
||||
### Value-Based Pricing Framework
|
||||
|
||||
Price should be based on value delivered, not cost to serve:
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ │
|
||||
│ Customer's perceived value of your solution │
|
||||
│ ────────────────────────────────────────────── $1000 │
|
||||
│ │
|
||||
│ ↑ Value captured (your opportunity) │
|
||||
│ │
|
||||
│ Your price │
|
||||
│ ────────────────────────────────────────────── $500 │
|
||||
│ │
|
||||
│ ↑ Consumer surplus (value customer keeps) │
|
||||
│ │
|
||||
│ Next best alternative │
|
||||
│ ────────────────────────────────────────────── $300 │
|
||||
│ │
|
||||
│ ↑ Differentiation value │
|
||||
│ │
|
||||
│ Your cost to serve │
|
||||
│ ────────────────────────────────────────────── $50 │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**Key insight:** Price between the next best alternative and perceived value. Cost is a floor, not a basis.
|
||||
|
||||
---
|
||||
|
||||
## Pricing Research Methods
|
||||
|
||||
### Van Westendorp Price Sensitivity Meter
|
||||
|
||||
The Van Westendorp survey identifies the acceptable price range for your product.
|
||||
|
||||
**The Four Questions:**
|
||||
|
||||
Ask each respondent:
|
||||
1. "At what price would you consider [product] to be so expensive that you would not consider buying it?" (Too expensive)
|
||||
2. "At what price would you consider [product] to be priced so low that you would question its quality?" (Too cheap)
|
||||
3. "At what price would you consider [product] to be starting to get expensive, but you still might consider it?" (Expensive/high side)
|
||||
4. "At what price would you consider [product] to be a bargain—a great buy for the money?" (Cheap/good value)
|
||||
|
||||
**How to Analyze:**
|
||||
|
||||
1. Plot cumulative distributions for each question
|
||||
2. Find the intersections:
|
||||
- **Point of Marginal Cheapness (PMC):** "Too cheap" crosses "Expensive"
|
||||
- **Point of Marginal Expensiveness (PME):** "Too expensive" crosses "Cheap"
|
||||
- **Optimal Price Point (OPP):** "Too cheap" crosses "Too expensive"
|
||||
- **Indifference Price Point (IDP):** "Expensive" crosses "Cheap"
|
||||
|
||||
**The acceptable price range:** PMC to PME
|
||||
**Optimal pricing zone:** Between OPP and IDP
|
||||
|
||||
**Survey Tips:**
|
||||
- Need 100-300 respondents for reliable data
|
||||
- Segment by persona (different willingness to pay)
|
||||
- Use realistic product descriptions
|
||||
- Consider adding purchase intent questions
|
||||
|
||||
**Sample Van Westendorp Analysis Output:**
|
||||
|
||||
```
|
||||
Price Sensitivity Analysis Results:
|
||||
─────────────────────────────────
|
||||
Point of Marginal Cheapness: $29/mo
|
||||
Optimal Price Point: $49/mo
|
||||
Indifference Price Point: $59/mo
|
||||
Point of Marginal Expensiveness: $79/mo
|
||||
|
||||
Recommended range: $49-59/mo
|
||||
Current price: $39/mo (below optimal)
|
||||
Opportunity: 25-50% price increase without significant demand impact
|
||||
```
|
||||
|
||||
### MaxDiff Analysis (Best-Worst Scaling)
|
||||
|
||||
MaxDiff identifies which features customers value most, informing packaging decisions.
|
||||
|
||||
**How It Works:**
|
||||
|
||||
1. List 8-15 features you could include
|
||||
2. Show respondents sets of 4-5 features at a time
|
||||
3. Ask: "Which is MOST important? Which is LEAST important?"
|
||||
4. Repeat across multiple sets until all features compared
|
||||
5. Statistical analysis produces importance scores
|
||||
|
||||
**Example Survey Question:**
|
||||
|
||||
```
|
||||
Which feature is MOST important to you?
|
||||
Which feature is LEAST important to you?
|
||||
|
||||
□ Unlimited projects
|
||||
□ Custom branding
|
||||
□ Priority support
|
||||
□ API access
|
||||
□ Advanced analytics
|
||||
```
|
||||
|
||||
**Analyzing Results:**
|
||||
|
||||
Features are ranked by utility score:
|
||||
- High utility = Must-have (include in base tier)
|
||||
- Medium utility = Differentiator (use for tier separation)
|
||||
- Low utility = Nice-to-have (premium tier or cut)
|
||||
|
||||
**Using MaxDiff for Packaging:**
|
||||
|
||||
| Utility Score | Packaging Decision |
|
||||
|---------------|-------------------|
|
||||
| Top 20% | Include in all tiers (table stakes) |
|
||||
| 20-50% | Use to differentiate tiers |
|
||||
| 50-80% | Higher tiers only |
|
||||
| Bottom 20% | Consider cutting or premium add-on |
|
||||
|
||||
### Willingness to Pay Surveys
|
||||
|
||||
**Direct method (simple but biased):**
|
||||
"How much would you pay for [product]?"
|
||||
|
||||
**Better: Gabor-Granger method:**
|
||||
"Would you buy [product] at [$X]?" (Yes/No)
|
||||
Vary price across respondents to build demand curve.
|
||||
|
||||
**Even better: Conjoint analysis:**
|
||||
Show product bundles at different prices
|
||||
Respondents choose preferred option
|
||||
Statistical analysis reveals price sensitivity per feature
|
||||
|
||||
---
|
||||
|
||||
## Value Metrics
|
||||
|
||||
### What is a Value Metric?
|
||||
|
||||
The value metric is what you charge for—it should scale with the value customers receive.
|
||||
|
||||
**Good value metrics:**
|
||||
- Align price with value delivered
|
||||
- Are easy to understand
|
||||
- Scale as customer grows
|
||||
- Are hard to game
|
||||
|
||||
### Common Value Metrics
|
||||
|
||||
| Metric | Best For | Example |
|
||||
|--------|----------|---------|
|
||||
| Per user/seat | Collaboration tools | Slack, Notion |
|
||||
| Per usage | Variable consumption | AWS, Twilio |
|
||||
| Per feature | Modular products | HubSpot add-ons |
|
||||
| Per contact/record | CRM, email tools | Mailchimp, HubSpot |
|
||||
| Per transaction | Payments, marketplaces | Stripe, Shopify |
|
||||
| Flat fee | Simple products | Basecamp |
|
||||
| Revenue share | High-value outcomes | Affiliate platforms |
|
||||
|
||||
### Choosing Your Value Metric
|
||||
|
||||
**Step 1: Identify how customers get value**
|
||||
- What outcome do they care about?
|
||||
- What do they measure success by?
|
||||
- What would they pay more for?
|
||||
|
||||
**Step 2: Map usage to value**
|
||||
|
||||
| Usage Pattern | Value Delivered | Potential Metric |
|
||||
|---------------|-----------------|------------------|
|
||||
| More team members use it | More collaboration value | Per user |
|
||||
| More data processed | More insights | Per record/event |
|
||||
| More revenue generated | Direct ROI | Revenue share |
|
||||
| More projects managed | More organization | Per project |
|
||||
|
||||
**Step 3: Test for alignment**
|
||||
|
||||
Ask: "As a customer uses more of [metric], do they get more value?"
|
||||
- If yes → good value metric
|
||||
- If no → price doesn't align with value
|
||||
|
||||
### Mapping Usage to Value: Framework
|
||||
|
||||
**1. Instrument usage data**
|
||||
Track how customers use your product:
|
||||
- Feature usage frequency
|
||||
- Volume metrics (users, records, API calls)
|
||||
- Outcome metrics (revenue generated, time saved)
|
||||
|
||||
**2. Correlate with customer success**
|
||||
- Which usage patterns predict retention?
|
||||
- Which usage patterns predict expansion?
|
||||
- Which customers pay the most, and why?
|
||||
|
||||
**3. Identify value thresholds**
|
||||
- At what usage level do customers "get it"?
|
||||
- At what usage level do they expand?
|
||||
- At what usage level should price increase?
|
||||
|
||||
**Example Analysis:**
|
||||
|
||||
```
|
||||
Usage-Value Correlation Analysis:
|
||||
─────────────────────────────────
|
||||
Segment: High-LTV customers (>$10k ARR)
|
||||
Average monthly active users: 15
|
||||
Average projects: 8
|
||||
Average integrations: 4
|
||||
|
||||
Segment: Churned customers
|
||||
Average monthly active users: 3
|
||||
Average projects: 2
|
||||
Average integrations: 0
|
||||
|
||||
Insight: Value correlates with team adoption (users)
|
||||
and depth of use (integrations)
|
||||
|
||||
Recommendation: Price per user, gate integrations to higher tiers
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Tier Structure
|
||||
|
||||
### How Many Tiers?
|
||||
|
||||
**2 tiers:** Simple, clear choice
|
||||
- Works for: Clear SMB vs. Enterprise split
|
||||
- Risk: May leave money on table
|
||||
|
||||
**3 tiers:** Industry standard
|
||||
- Good tier = Entry point
|
||||
- Better tier = Recommended (anchor to best)
|
||||
- Best tier = High-value customers
|
||||
|
||||
**4+ tiers:** More granularity
|
||||
- Works for: Wide range of customer sizes
|
||||
- Risk: Decision paralysis, complexity
|
||||
|
||||
### Good-Better-Best Framework
|
||||
|
||||
**Good tier (Entry):**
|
||||
- Purpose: Remove barriers to entry
|
||||
- Includes: Core features, limited usage
|
||||
- Price: Low, accessible
|
||||
- Target: Small teams, try before you buy
|
||||
|
||||
**Better tier (Recommended):**
|
||||
- Purpose: Where most customers land
|
||||
- Includes: Full features, reasonable limits
|
||||
- Price: Your "anchor" price
|
||||
- Target: Growing teams, serious users
|
||||
|
||||
**Best tier (Premium):**
|
||||
- Purpose: Capture high-value customers
|
||||
- Includes: Everything, advanced features, higher limits
|
||||
- Price: Premium (often 2-3x "Better")
|
||||
- Target: Larger teams, power users, enterprises
|
||||
|
||||
### Tier Differentiation Strategies
|
||||
|
||||
**Feature gating:**
|
||||
- Basic features in all tiers
|
||||
- Advanced features in higher tiers
|
||||
- Works when features have clear value differences
|
||||
|
||||
**Usage limits:**
|
||||
- Same features, different limits
|
||||
- More users, storage, API calls at higher tiers
|
||||
- Works when value scales with usage
|
||||
|
||||
**Support level:**
|
||||
- Email support → Priority support → Dedicated success
|
||||
- Works for products with implementation complexity
|
||||
|
||||
**Access and customization:**
|
||||
- API access, SSO, custom branding
|
||||
- Works for enterprise differentiation
|
||||
|
||||
### Example Tier Structure
|
||||
|
||||
```
|
||||
┌────────────────┬─────────────────┬─────────────────┬─────────────────┐
|
||||
│ │ Starter │ Pro │ Business │
|
||||
│ │ $29/mo │ $79/mo │ $199/mo │
|
||||
├────────────────┼─────────────────┼─────────────────┼─────────────────┤
|
||||
│ Users │ Up to 5 │ Up to 20 │ Unlimited │
|
||||
│ Projects │ 10 │ Unlimited │ Unlimited │
|
||||
│ Storage │ 5 GB │ 50 GB │ 500 GB │
|
||||
│ Integrations │ 3 │ 10 │ Unlimited │
|
||||
│ Analytics │ Basic │ Advanced │ Custom │
|
||||
│ Support │ Email │ Priority │ Dedicated │
|
||||
│ API Access │ ✗ │ ✓ │ ✓ │
|
||||
│ SSO │ ✗ │ ✗ │ ✓ │
|
||||
│ Audit logs │ ✗ │ ✗ │ ✓ │
|
||||
└────────────────┴─────────────────┴─────────────────┴─────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Packaging for Personas
|
||||
|
||||
### Identifying Pricing Personas
|
||||
|
||||
Different customers have different:
|
||||
- Willingness to pay
|
||||
- Feature needs
|
||||
- Buying processes
|
||||
- Value perception
|
||||
|
||||
**Segment by:**
|
||||
- Company size (solopreneur → SMB → enterprise)
|
||||
- Use case (marketing vs. sales vs. support)
|
||||
- Sophistication (beginner → power user)
|
||||
- Industry (different budget norms)
|
||||
|
||||
### Persona-Based Packaging
|
||||
|
||||
**Step 1: Define personas**
|
||||
|
||||
| Persona | Size | Needs | WTP | Example |
|
||||
|---------|------|-------|-----|---------|
|
||||
| Freelancer | 1 person | Basic features | Low | $19/mo |
|
||||
| Small Team | 2-10 | Collaboration | Medium | $49/mo |
|
||||
| Growing Co | 10-50 | Scale, integrations | Higher | $149/mo |
|
||||
| Enterprise | 50+ | Security, support | High | Custom |
|
||||
|
||||
**Step 2: Map features to personas**
|
||||
|
||||
| Feature | Freelancer | Small Team | Growing | Enterprise |
|
||||
|---------|------------|------------|---------|------------|
|
||||
| Core features | ✓ | ✓ | ✓ | ✓ |
|
||||
| Collaboration | — | ✓ | ✓ | ✓ |
|
||||
| Integrations | — | Limited | Full | Full |
|
||||
| API access | — | — | ✓ | ✓ |
|
||||
| SSO/SAML | — | — | — | ✓ |
|
||||
| Audit logs | — | — | — | ✓ |
|
||||
| Custom contract | — | — | — | ✓ |
|
||||
|
||||
**Step 3: Price to value for each persona**
|
||||
- Research willingness to pay per segment
|
||||
- Set prices that capture value without blocking adoption
|
||||
- Consider segment-specific landing pages
|
||||
|
||||
---
|
||||
|
||||
## Freemium vs. Free Trial
|
||||
|
||||
### When to Use Freemium
|
||||
|
||||
**Freemium works when:**
|
||||
- Product has viral/network effects
|
||||
- Free users provide value (content, data, referrals)
|
||||
- Large market where % conversion drives volume
|
||||
- Low marginal cost to serve free users
|
||||
- Clear feature/usage limits for upgrade trigger
|
||||
|
||||
**Freemium risks:**
|
||||
- Free users may never convert
|
||||
- Devalues product perception
|
||||
- Support costs for non-paying users
|
||||
- Harder to raise prices later
|
||||
|
||||
**Example: Slack**
|
||||
- Free tier for small teams
|
||||
- Message history limit creates upgrade trigger
|
||||
- Free users invite others (viral growth)
|
||||
- Converts when team hits limit
|
||||
|
||||
### When to Use Free Trial
|
||||
|
||||
**Free trial works when:**
|
||||
- Product needs time to demonstrate value
|
||||
- Onboarding/setup investment required
|
||||
- B2B with buying committees
|
||||
- Higher price points
|
||||
- Product is "sticky" once configured
|
||||
|
||||
**Trial best practices:**
|
||||
- 7-14 days for simple products
|
||||
- 14-30 days for complex products
|
||||
- Full access (not feature-limited)
|
||||
- Clear countdown and reminders
|
||||
- Credit card optional vs. required trade-off
|
||||
|
||||
**Credit card upfront:**
|
||||
- Higher trial-to-paid conversion (40-50% vs. 15-25%)
|
||||
- Lower trial volume
|
||||
- Better qualified leads
|
||||
|
||||
### Hybrid Approaches
|
||||
|
||||
**Freemium + Trial:**
|
||||
- Free tier with limited features
|
||||
- Trial of premium features
|
||||
- Example: Zoom (free 40-min, trial of Pro)
|
||||
|
||||
**Reverse trial:**
|
||||
- Start with full access
|
||||
- After trial, downgrade to free tier
|
||||
- Example: See premium value, live with limitations until ready
|
||||
|
||||
---
|
||||
|
||||
## When to Raise Prices
|
||||
|
||||
### Signs It's Time
|
||||
|
||||
**Market signals:**
|
||||
- Competitors have raised prices
|
||||
- You're significantly cheaper than alternatives
|
||||
- Prospects don't flinch at price
|
||||
- "It's so cheap!" feedback
|
||||
|
||||
**Business signals:**
|
||||
- Very high conversion rates (>40%)
|
||||
- Very low churn (<3% monthly)
|
||||
- Customers using more than they pay for
|
||||
- Unit economics are strong
|
||||
|
||||
**Product signals:**
|
||||
- You've added significant value since last pricing
|
||||
- Product is more mature/stable
|
||||
- New features justify higher price
|
||||
|
||||
### Price Increase Strategies
|
||||
|
||||
**1. Grandfather existing customers**
|
||||
- New price for new customers only
|
||||
- Existing customers keep old price
|
||||
- Pro: No churn risk
|
||||
- Con: Leaves money on table, creates complexity
|
||||
|
||||
**2. Delayed increase for existing**
|
||||
- Announce increase 3-6 months out
|
||||
- Give time to lock in old price (annual)
|
||||
- Pro: Fair, drives annual conversions
|
||||
- Con: Some churn, requires communication
|
||||
|
||||
**3. Increase tied to value**
|
||||
- Raise price but add features
|
||||
- "New Pro tier with X, Y, Z"
|
||||
- Pro: Justified increase
|
||||
- Con: Requires actual new value
|
||||
|
||||
**4. Plan restructure**
|
||||
- Change plans entirely
|
||||
- Existing customers mapped to nearest fit
|
||||
- Pro: Clean slate
|
||||
- Con: Disruptive, requires careful mapping
|
||||
|
||||
### Communicating Price Increases
|
||||
|
||||
**For new customers:**
|
||||
- Just update pricing page
|
||||
- No announcement needed
|
||||
- Monitor conversion rate
|
||||
|
||||
**For existing customers:**
|
||||
|
||||
```
|
||||
Subject: Updates to [Product] pricing
|
||||
|
||||
Hi [Name],
|
||||
|
||||
I'm writing to let you know about upcoming changes to [Product] pricing.
|
||||
|
||||
[Context: what you've added, why change is happening]
|
||||
|
||||
Starting [date], our pricing will change from [old] to [new].
|
||||
|
||||
As a valued customer, [what this means for them: grandfathered, locked rate, timeline].
|
||||
|
||||
[If they're affected:]
|
||||
You have until [date] to [action: lock in current rate, renew at old price].
|
||||
|
||||
[If they're grandfathered:]
|
||||
You'll continue at your current rate. No action needed.
|
||||
|
||||
We appreciate your continued support of [Product].
|
||||
|
||||
[Your name]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Pricing Page Best Practices
|
||||
|
||||
### Above the Fold
|
||||
|
||||
- Clear tier comparison table
|
||||
- Recommended tier highlighted
|
||||
- Monthly/annual toggle
|
||||
- Primary CTA for each tier
|
||||
|
||||
### Tier Presentation
|
||||
|
||||
- Lead with the recommended tier (visual emphasis)
|
||||
- Show value progression clearly
|
||||
- Use checkmarks and limits, not paragraphs
|
||||
- Anchor to higher tier (show enterprise first or savings)
|
||||
|
||||
### Common Elements
|
||||
|
||||
- [ ] Feature comparison table
|
||||
- [ ] Who each tier is for
|
||||
- [ ] FAQ section
|
||||
- [ ] Contact sales option
|
||||
- [ ] Annual discount callout
|
||||
- [ ] Money-back guarantee
|
||||
- [ ] Customer logos/trust signals
|
||||
|
||||
### Pricing Psychology to Apply
|
||||
|
||||
- **Anchoring:** Show higher-priced option first
|
||||
- **Decoy effect:** Middle tier should be obviously best value
|
||||
- **Charm pricing:** $49 vs. $50 (for value-focused)
|
||||
- **Round pricing:** $50 vs. $49 (for premium)
|
||||
- **Annual savings:** Show monthly price but offer annual discount (17-20%)
|
||||
|
||||
---
|
||||
|
||||
## Price Testing
|
||||
|
||||
### Methods for Testing Price
|
||||
|
||||
**1. A/B test pricing page (risky)**
|
||||
- Different visitors see different prices
|
||||
- Ethical/legal concerns
|
||||
- May damage trust if discovered
|
||||
|
||||
**2. Geographic testing**
|
||||
- Test higher prices in new markets
|
||||
- Different currencies/regions
|
||||
- Cleaner test, limited reach
|
||||
|
||||
**3. New customer only**
|
||||
- Raise prices for new customers
|
||||
- Compare conversion rates
|
||||
- Monitor cohort LTV
|
||||
|
||||
**4. Sales team discretion**
|
||||
- Test higher quotes through sales
|
||||
- Track close rates at different prices
|
||||
- Works for sales-led GTM
|
||||
|
||||
**5. Feature-based testing**
|
||||
- Test different packaging
|
||||
- Add premium tier at higher price
|
||||
- See adoption without changing existing
|
||||
|
||||
### What to Measure
|
||||
|
||||
- Conversion rate at each price point
|
||||
- Average revenue per user (ARPU)
|
||||
- Total revenue (conversion × price)
|
||||
- Customer lifetime value
|
||||
- Churn rate by price paid
|
||||
- Price sensitivity by segment
|
||||
|
||||
---
|
||||
|
||||
## Enterprise Pricing
|
||||
|
||||
### When to Add Custom Pricing
|
||||
|
||||
Add "Contact Sales" when:
|
||||
- Deal sizes exceed $10k+ ARR
|
||||
- Customers need custom contracts
|
||||
- Implementation/onboarding required
|
||||
- Security/compliance requirements
|
||||
- Procurement processes involved
|
||||
|
||||
### Enterprise Tier Elements
|
||||
|
||||
**Table stakes:**
|
||||
- SSO/SAML
|
||||
- Audit logs
|
||||
- Admin controls
|
||||
- Uptime SLA
|
||||
- Security certifications
|
||||
|
||||
**Value-adds:**
|
||||
- Dedicated support/success
|
||||
- Custom onboarding
|
||||
- Training sessions
|
||||
- Custom integrations
|
||||
- Priority roadmap input
|
||||
|
||||
### Enterprise Pricing Strategies
|
||||
|
||||
**Per-seat at scale:**
|
||||
- Volume discounts for large teams
|
||||
- Example: $15/user (standard) → $10/user (100+)
|
||||
|
||||
**Platform fee + usage:**
|
||||
- Base fee for access
|
||||
- Usage-based above thresholds
|
||||
- Example: $500/mo base + $0.01 per API call
|
||||
|
||||
**Value-based contracts:**
|
||||
- Price tied to customer's revenue/outcomes
|
||||
- Example: % of transactions, revenue share
|
||||
|
||||
---
|
||||
|
||||
## Pricing Checklist
|
||||
|
||||
### Before Setting Prices
|
||||
|
||||
- [ ] Defined target customer personas
|
||||
- [ ] Researched competitor pricing
|
||||
- [ ] Identified your value metric
|
||||
- [ ] Conducted willingness-to-pay research
|
||||
- [ ] Mapped features to tiers
|
||||
|
||||
### Pricing Structure
|
||||
|
||||
- [ ] Chosen number of tiers
|
||||
- [ ] Differentiated tiers clearly
|
||||
- [ ] Set price points based on research
|
||||
- [ ] Created annual discount strategy
|
||||
- [ ] Planned enterprise/custom tier
|
||||
|
||||
### Validation
|
||||
|
||||
- [ ] Tested pricing with target customers
|
||||
- [ ] Reviewed pricing with sales team
|
||||
- [ ] Validated unit economics work
|
||||
- [ ] Planned for price increases
|
||||
- [ ] Set up tracking for pricing metrics
|
||||
|
||||
---
|
||||
|
||||
## Questions to Ask
|
||||
|
||||
If you need more context:
|
||||
1. What pricing research have you done (surveys, competitor analysis)?
|
||||
2. What's your current ARPU and conversion rate?
|
||||
3. What's your primary value metric (what do customers pay for value)?
|
||||
4. Who are your main pricing personas (by size, use case)?
|
||||
5. Are you self-serve, sales-led, or hybrid?
|
||||
6. What pricing changes are you considering?
|
||||
|
||||
---
|
||||
|
||||
## Related Skills
|
||||
|
||||
- **page-cro**: For optimizing pricing page conversion
|
||||
- **copywriting**: For pricing page copy
|
||||
- **marketing-psychology**: For pricing psychology principles
|
||||
- **ab-test-setup**: For testing pricing changes
|
||||
- **analytics-tracking**: For tracking pricing metrics
|
||||
626
skills/programmatic-seo/SKILL.md
Normal file
626
skills/programmatic-seo/SKILL.md
Normal file
@@ -0,0 +1,626 @@
|
||||
---
|
||||
name: programmatic-seo
|
||||
description: When the user wants to create SEO-driven pages at scale using templates and data. Also use when the user mentions "programmatic SEO," "template pages," "pages at scale," "directory pages," "location pages," "[keyword] + [city] pages," "comparison pages," "integration pages," or "building many pages for SEO." For auditing existing SEO issues, see seo-audit.
|
||||
---
|
||||
|
||||
# Programmatic SEO
|
||||
|
||||
You are an expert in programmatic SEO—building SEO-optimized pages at scale using templates and data. Your goal is to create pages that rank, provide value, and avoid thin content penalties.
|
||||
|
||||
## Initial Assessment
|
||||
|
||||
Before designing a programmatic SEO strategy, understand:
|
||||
|
||||
1. **Business Context**
|
||||
- What's the product/service?
|
||||
- Who is the target audience?
|
||||
- What's the conversion goal for these pages?
|
||||
|
||||
2. **Opportunity Assessment**
|
||||
- What search patterns exist?
|
||||
- How many potential pages?
|
||||
- What's the search volume distribution?
|
||||
|
||||
3. **Competitive Landscape**
|
||||
- Who ranks for these terms now?
|
||||
- What do their pages look like?
|
||||
- What would it take to beat them?
|
||||
|
||||
---
|
||||
|
||||
## Core Principles
|
||||
|
||||
### 1. Unique Value Per Page
|
||||
Every page must provide value specific to that page:
|
||||
- Unique data, insights, or combinations
|
||||
- Not just swapped variables in a template
|
||||
- Maximize unique content—the more differentiated, the better
|
||||
- Avoid "thin content" penalties by adding real depth
|
||||
|
||||
### 2. Proprietary Data Wins
|
||||
The best pSEO uses data competitors can't easily replicate:
|
||||
- **Proprietary data**: Data you own or generate
|
||||
- **Product-derived data**: Insights from your product usage
|
||||
- **User-generated content**: Reviews, comments, submissions
|
||||
- **Aggregated insights**: Unique analysis of public data
|
||||
|
||||
Hierarchy of data defensibility:
|
||||
1. Proprietary (you created it)
|
||||
2. Product-derived (from your users)
|
||||
3. User-generated (your community)
|
||||
4. Licensed (exclusive access)
|
||||
5. Public (anyone can use—weakest)
|
||||
|
||||
### 3. Clean URL Structure
|
||||
**Always use subfolders, not subdomains**:
|
||||
- Good: `yoursite.com/templates/resume/`
|
||||
- Bad: `templates.yoursite.com/resume/`
|
||||
|
||||
Subfolders pass authority to your main domain. Subdomains are treated as separate sites by Google.
|
||||
|
||||
**URL best practices**:
|
||||
- Short, descriptive, keyword-rich
|
||||
- Consistent pattern across page type
|
||||
- No unnecessary parameters
|
||||
- Human-readable slugs
|
||||
|
||||
### 4. Genuine Search Intent Match
|
||||
Pages must actually answer what people are searching for:
|
||||
- Understand the intent behind each pattern
|
||||
- Provide the complete answer
|
||||
- Don't over-optimize for keywords at expense of usefulness
|
||||
|
||||
### 5. Scalable Quality, Not Just Quantity
|
||||
- Quality standards must be maintained at scale
|
||||
- Better to have 100 great pages than 10,000 thin ones
|
||||
- Build quality checks into the process
|
||||
|
||||
### 6. Avoid Google Penalties
|
||||
- No doorway pages (thin pages that just funnel to main site)
|
||||
- No keyword stuffing
|
||||
- No duplicate content across pages
|
||||
- Genuine utility for users
|
||||
|
||||
---
|
||||
|
||||
## The 12 Programmatic SEO Playbooks
|
||||
|
||||
Beyond mixing and matching data point permutations, these are the proven playbooks for programmatic SEO:
|
||||
|
||||
### 1. Templates
|
||||
**Pattern**: "[Type] template" or "free [type] template"
|
||||
**Example searches**: "resume template", "invoice template", "pitch deck template"
|
||||
|
||||
**What it is**: Downloadable or interactive templates users can use directly.
|
||||
|
||||
**Why it works**:
|
||||
- High intent—people need it now
|
||||
- Shareable/linkable assets
|
||||
- Natural for product-led companies
|
||||
|
||||
**Value requirements**:
|
||||
- Actually usable templates (not just previews)
|
||||
- Multiple variations per type
|
||||
- Quality comparable to paid options
|
||||
- Easy download/use flow
|
||||
|
||||
**URL structure**: `/templates/[type]/` or `/templates/[category]/[type]/`
|
||||
|
||||
---
|
||||
|
||||
### 2. Curation
|
||||
**Pattern**: "best [category]" or "top [number] [things]"
|
||||
**Example searches**: "best website builders", "top 10 crm software", "best free design tools"
|
||||
|
||||
**What it is**: Curated lists ranking or recommending options in a category.
|
||||
|
||||
**Why it works**:
|
||||
- Comparison shoppers searching for guidance
|
||||
- High commercial intent
|
||||
- Evergreen with updates
|
||||
|
||||
**Value requirements**:
|
||||
- Genuine evaluation criteria
|
||||
- Real testing or expertise
|
||||
- Regular updates (date visible)
|
||||
- Not just affiliate-driven rankings
|
||||
|
||||
**URL structure**: `/best/[category]/` or `/[category]/best/`
|
||||
|
||||
---
|
||||
|
||||
### 3. Conversions
|
||||
**Pattern**: "[X] to [Y]" or "[amount] [unit] in [unit]"
|
||||
**Example searches**: "$10 USD to GBP", "100 kg to lbs", "pdf to word"
|
||||
|
||||
**What it is**: Tools or pages that convert between formats, units, or currencies.
|
||||
|
||||
**Why it works**:
|
||||
- Instant utility
|
||||
- Extremely high search volume
|
||||
- Repeat usage potential
|
||||
|
||||
**Value requirements**:
|
||||
- Accurate, real-time data
|
||||
- Fast, functional tool
|
||||
- Related conversions suggested
|
||||
- Mobile-friendly interface
|
||||
|
||||
**URL structure**: `/convert/[from]-to-[to]/` or `/[from]-to-[to]-converter/`
|
||||
|
||||
---
|
||||
|
||||
### 4. Comparisons
|
||||
**Pattern**: "[X] vs [Y]" or "[X] alternative"
|
||||
**Example searches**: "webflow vs wordpress", "notion vs coda", "figma alternatives"
|
||||
|
||||
**What it is**: Head-to-head comparisons between products, tools, or options.
|
||||
|
||||
**Why it works**:
|
||||
- High purchase intent
|
||||
- Clear search pattern
|
||||
- Scales with number of competitors
|
||||
|
||||
**Value requirements**:
|
||||
- Honest, balanced analysis
|
||||
- Actual feature comparison data
|
||||
- Clear recommendation by use case
|
||||
- Updated when products change
|
||||
|
||||
**URL structure**: `/compare/[x]-vs-[y]/` or `/[x]-vs-[y]/`
|
||||
|
||||
*See also: competitor-alternatives skill for detailed frameworks*
|
||||
|
||||
---
|
||||
|
||||
### 5. Examples
|
||||
**Pattern**: "[type] examples" or "[category] inspiration"
|
||||
**Example searches**: "saas landing page examples", "email subject line examples", "portfolio website examples"
|
||||
|
||||
**What it is**: Galleries or collections of real-world examples for inspiration.
|
||||
|
||||
**Why it works**:
|
||||
- Research phase traffic
|
||||
- Highly shareable
|
||||
- Natural for design/creative tools
|
||||
|
||||
**Value requirements**:
|
||||
- Real, high-quality examples
|
||||
- Screenshots or embeds
|
||||
- Categorization/filtering
|
||||
- Analysis of why they work
|
||||
|
||||
**URL structure**: `/examples/[type]/` or `/[type]-examples/`
|
||||
|
||||
---
|
||||
|
||||
### 6. Locations
|
||||
**Pattern**: "[service/thing] in [location]"
|
||||
**Example searches**: "coworking spaces in san diego", "dentists in austin", "best restaurants in brooklyn"
|
||||
|
||||
**What it is**: Location-specific pages for services, businesses, or information.
|
||||
|
||||
**Why it works**:
|
||||
- Local intent is massive
|
||||
- Scales with geography
|
||||
- Natural for marketplaces/directories
|
||||
|
||||
**Value requirements**:
|
||||
- Actual local data (not just city name swapped)
|
||||
- Local providers/options listed
|
||||
- Location-specific insights (pricing, regulations)
|
||||
- Map integration helpful
|
||||
|
||||
**URL structure**: `/[service]/[city]/` or `/locations/[city]/[service]/`
|
||||
|
||||
---
|
||||
|
||||
### 7. Personas
|
||||
**Pattern**: "[product] for [audience]" or "[solution] for [role/industry]"
|
||||
**Example searches**: "payroll software for agencies", "crm for real estate", "project management for freelancers"
|
||||
|
||||
**What it is**: Tailored landing pages addressing specific audience segments.
|
||||
|
||||
**Why it works**:
|
||||
- Speaks directly to searcher's context
|
||||
- Higher conversion than generic pages
|
||||
- Scales with personas
|
||||
|
||||
**Value requirements**:
|
||||
- Genuine persona-specific content
|
||||
- Relevant features highlighted
|
||||
- Testimonials from that segment
|
||||
- Use cases specific to audience
|
||||
|
||||
**URL structure**: `/for/[persona]/` or `/solutions/[industry]/`
|
||||
|
||||
---
|
||||
|
||||
### 8. Integrations
|
||||
**Pattern**: "[your product] [other product] integration" or "[product] + [product]"
|
||||
**Example searches**: "slack asana integration", "zapier airtable", "hubspot salesforce sync"
|
||||
|
||||
**What it is**: Pages explaining how your product works with other tools.
|
||||
|
||||
**Why it works**:
|
||||
- Captures users of other products
|
||||
- High intent (they want the solution)
|
||||
- Scales with integration ecosystem
|
||||
|
||||
**Value requirements**:
|
||||
- Real integration details
|
||||
- Setup instructions
|
||||
- Use cases for the combination
|
||||
- Working integration (not vaporware)
|
||||
|
||||
**URL structure**: `/integrations/[product]/` or `/connect/[product]/`
|
||||
|
||||
---
|
||||
|
||||
### 9. Glossary
|
||||
**Pattern**: "what is [term]" or "[term] definition" or "[term] meaning"
|
||||
**Example searches**: "what is pSEO", "api definition", "what does crm stand for"
|
||||
|
||||
**What it is**: Educational definitions of industry terms and concepts.
|
||||
|
||||
**Why it works**:
|
||||
- Top-of-funnel awareness
|
||||
- Establishes expertise
|
||||
- Natural internal linking opportunities
|
||||
|
||||
**Value requirements**:
|
||||
- Clear, accurate definitions
|
||||
- Examples and context
|
||||
- Related terms linked
|
||||
- More depth than a dictionary
|
||||
|
||||
**URL structure**: `/glossary/[term]/` or `/learn/[term]/`
|
||||
|
||||
---
|
||||
|
||||
### 10. Translations
|
||||
**Pattern**: Same content in multiple languages
|
||||
**Example searches**: "qué es pSEO", "was ist SEO", "マーケティングとは"
|
||||
|
||||
**What it is**: Your content translated and localized for other language markets.
|
||||
|
||||
**Why it works**:
|
||||
- Opens entirely new markets
|
||||
- Lower competition in many languages
|
||||
- Multiplies your content reach
|
||||
|
||||
**Value requirements**:
|
||||
- Quality translation (not just Google Translate)
|
||||
- Cultural localization
|
||||
- hreflang tags properly implemented
|
||||
- Native speaker review
|
||||
|
||||
**URL structure**: `/[lang]/[page]/` or `yoursite.com/es/`, `/de/`, etc.
|
||||
|
||||
---
|
||||
|
||||
### 11. Directory
|
||||
**Pattern**: "[category] tools" or "[type] software" or "[category] companies"
|
||||
**Example searches**: "ai copywriting tools", "email marketing software", "crm companies"
|
||||
|
||||
**What it is**: Comprehensive directories listing options in a category.
|
||||
|
||||
**Why it works**:
|
||||
- Research phase capture
|
||||
- Link building magnet
|
||||
- Natural for aggregators/reviewers
|
||||
|
||||
**Value requirements**:
|
||||
- Comprehensive coverage
|
||||
- Useful filtering/sorting
|
||||
- Details per listing (not just names)
|
||||
- Regular updates
|
||||
|
||||
**URL structure**: `/directory/[category]/` or `/[category]-directory/`
|
||||
|
||||
---
|
||||
|
||||
### 12. Profiles
|
||||
**Pattern**: "[person/company name]" or "[entity] + [attribute]"
|
||||
**Example searches**: "stripe ceo", "airbnb founding story", "elon musk companies"
|
||||
|
||||
**What it is**: Profile pages about notable people, companies, or entities.
|
||||
|
||||
**Why it works**:
|
||||
- Informational intent traffic
|
||||
- Builds topical authority
|
||||
- Natural for B2B, news, research
|
||||
|
||||
**Value requirements**:
|
||||
- Accurate, sourced information
|
||||
- Regularly updated
|
||||
- Unique insights or aggregation
|
||||
- Not just Wikipedia rehash
|
||||
|
||||
**URL structure**: `/people/[name]/` or `/companies/[name]/`
|
||||
|
||||
---
|
||||
|
||||
## Choosing Your Playbook
|
||||
|
||||
### Match to Your Assets
|
||||
|
||||
| If you have... | Consider... |
|
||||
|----------------|-------------|
|
||||
| Proprietary data | Stats, Directories, Profiles |
|
||||
| Product with integrations | Integrations |
|
||||
| Design/creative product | Templates, Examples |
|
||||
| Multi-segment audience | Personas |
|
||||
| Local presence | Locations |
|
||||
| Tool or utility product | Conversions |
|
||||
| Content/expertise | Glossary, Curation |
|
||||
| International potential | Translations |
|
||||
| Competitor landscape | Comparisons |
|
||||
|
||||
### Combine Playbooks
|
||||
|
||||
You can layer multiple playbooks:
|
||||
- **Locations + Personas**: "Marketing agencies for startups in Austin"
|
||||
- **Curation + Locations**: "Best coworking spaces in San Diego"
|
||||
- **Integrations + Personas**: "Slack for sales teams"
|
||||
- **Glossary + Translations**: Multi-language educational content
|
||||
|
||||
---
|
||||
|
||||
## Implementation Framework
|
||||
|
||||
### 1. Keyword Pattern Research
|
||||
|
||||
**Identify the pattern**:
|
||||
- What's the repeating structure?
|
||||
- What are the variables?
|
||||
- How many unique combinations exist?
|
||||
|
||||
**Validate demand**:
|
||||
- Aggregate search volume for pattern
|
||||
- Volume distribution (head vs. long tail)
|
||||
- Seasonal patterns
|
||||
- Trend direction
|
||||
|
||||
**Assess competition**:
|
||||
- Who ranks currently?
|
||||
- What's their content quality?
|
||||
- What's their domain authority?
|
||||
- Can you realistically compete?
|
||||
|
||||
### 2. Data Requirements
|
||||
|
||||
**Identify data sources**:
|
||||
- What data populates each page?
|
||||
- Where does that data come from?
|
||||
- Is it first-party, scraped, licensed, public?
|
||||
- How is it updated?
|
||||
|
||||
**Data schema design**:
|
||||
```
|
||||
For "[Service] in [City]" pages:
|
||||
|
||||
city:
|
||||
- name
|
||||
- population
|
||||
- relevant_stats
|
||||
|
||||
service:
|
||||
- name
|
||||
- description
|
||||
- typical_pricing
|
||||
|
||||
local_providers:
|
||||
- name
|
||||
- rating
|
||||
- reviews_count
|
||||
- specialty
|
||||
|
||||
local_data:
|
||||
- regulations
|
||||
- average_prices
|
||||
- market_size
|
||||
```
|
||||
|
||||
### 3. Template Design
|
||||
|
||||
**Page structure**:
|
||||
- Header with target keyword
|
||||
- Unique intro (not just variables swapped)
|
||||
- Data-driven sections
|
||||
- Related pages / internal links
|
||||
- CTAs appropriate to intent
|
||||
|
||||
**Ensuring uniqueness**:
|
||||
- Each page needs unique value
|
||||
- Conditional content based on data
|
||||
- User-generated content where possible
|
||||
- Original insights/analysis per page
|
||||
|
||||
**Template example**:
|
||||
```
|
||||
H1: [Service] in [City]: [Year] Guide
|
||||
|
||||
Intro: [Dynamic paragraph using city stats + service context]
|
||||
|
||||
Section 1: Why [City] for [Service]
|
||||
[City-specific data and insights]
|
||||
|
||||
Section 2: Top [Service] Providers in [City]
|
||||
[Data-driven list with unique details]
|
||||
|
||||
Section 3: Pricing for [Service] in [City]
|
||||
[Local pricing data if available]
|
||||
|
||||
Section 4: FAQs about [Service] in [City]
|
||||
[Common questions with city-specific answers]
|
||||
|
||||
Related: [Service] in [Nearby Cities]
|
||||
```
|
||||
|
||||
### 4. Internal Linking Architecture
|
||||
|
||||
**Hub and spoke model**:
|
||||
- Hub: Main category page
|
||||
- Spokes: Individual programmatic pages
|
||||
- Cross-links between related spokes
|
||||
|
||||
**Avoid orphan pages**:
|
||||
- Every page reachable from main site
|
||||
- Logical category structure
|
||||
- XML sitemap for all pages
|
||||
|
||||
**Breadcrumbs**:
|
||||
- Show hierarchy
|
||||
- Structured data markup
|
||||
- User navigation aid
|
||||
|
||||
### 5. Indexation Strategy
|
||||
|
||||
**Prioritize important pages**:
|
||||
- Not all pages need to be indexed
|
||||
- Index high-volume patterns
|
||||
- Noindex very thin variations
|
||||
|
||||
**Crawl budget management**:
|
||||
- Paginate thoughtfully
|
||||
- Avoid infinite crawl traps
|
||||
- Use robots.txt wisely
|
||||
|
||||
**Sitemap strategy**:
|
||||
- Separate sitemaps by page type
|
||||
- Monitor indexation rate
|
||||
- Prioritize by importance
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
### Pre-Launch Checklist
|
||||
|
||||
**Content quality**:
|
||||
- [ ] Each page provides unique value
|
||||
- [ ] Not just variable substitution
|
||||
- [ ] Answers search intent
|
||||
- [ ] Readable and useful
|
||||
|
||||
**Technical SEO**:
|
||||
- [ ] Unique titles and meta descriptions
|
||||
- [ ] Proper heading structure
|
||||
- [ ] Schema markup implemented
|
||||
- [ ] Canonical tags correct
|
||||
- [ ] Page speed acceptable
|
||||
|
||||
**Internal linking**:
|
||||
- [ ] Connected to site architecture
|
||||
- [ ] Related pages linked
|
||||
- [ ] No orphan pages
|
||||
- [ ] Breadcrumbs implemented
|
||||
|
||||
**Indexation**:
|
||||
- [ ] In XML sitemap
|
||||
- [ ] Crawlable
|
||||
- [ ] Not blocked by robots.txt
|
||||
- [ ] No conflicting noindex
|
||||
|
||||
### Monitoring Post-Launch
|
||||
|
||||
**Track**:
|
||||
- Indexation rate
|
||||
- Rankings by page pattern
|
||||
- Traffic by page pattern
|
||||
- Engagement metrics
|
||||
- Conversion rate
|
||||
|
||||
**Watch for**:
|
||||
- Thin content warnings in Search Console
|
||||
- Ranking drops
|
||||
- Manual actions
|
||||
- Crawl errors
|
||||
|
||||
---
|
||||
|
||||
## Common Mistakes to Avoid
|
||||
|
||||
### Thin Content
|
||||
- Just swapping city names in identical content
|
||||
- No unique information per page
|
||||
- "Doorway pages" that just redirect
|
||||
|
||||
### Keyword Cannibalization
|
||||
- Multiple pages targeting same keyword
|
||||
- No clear hierarchy
|
||||
- Competing with yourself
|
||||
|
||||
### Over-Generation
|
||||
- Creating pages with no search demand
|
||||
- Too many low-quality pages dilute authority
|
||||
- Quantity over quality
|
||||
|
||||
### Poor Data Quality
|
||||
- Outdated information
|
||||
- Incorrect data
|
||||
- Missing data showing as blank
|
||||
|
||||
### Ignoring User Experience
|
||||
- Pages exist for Google, not users
|
||||
- No conversion path
|
||||
- Bouncy, unhelpful content
|
||||
|
||||
---
|
||||
|
||||
## Output Format
|
||||
|
||||
### Strategy Document
|
||||
|
||||
**Opportunity Analysis**:
|
||||
- Keyword pattern identified
|
||||
- Search volume estimates
|
||||
- Competition assessment
|
||||
- Feasibility rating
|
||||
|
||||
**Implementation Plan**:
|
||||
- Data requirements and sources
|
||||
- Template structure
|
||||
- Number of pages (phases)
|
||||
- Internal linking plan
|
||||
- Technical requirements
|
||||
|
||||
**Content Guidelines**:
|
||||
- What makes each page unique
|
||||
- Quality standards
|
||||
- Update frequency
|
||||
|
||||
### Page Template
|
||||
|
||||
**URL structure**: `/category/variable/`
|
||||
**Title template**: [Variable] + [Static] + [Brand]
|
||||
**Meta description template**: [Pattern with variables]
|
||||
**H1 template**: [Pattern]
|
||||
**Content outline**: Section by section
|
||||
**Schema markup**: Type and required fields
|
||||
|
||||
### Launch Checklist
|
||||
|
||||
Specific pre-launch checks for this implementation
|
||||
|
||||
---
|
||||
|
||||
## Questions to Ask
|
||||
|
||||
If you need more context:
|
||||
1. What keyword patterns are you targeting?
|
||||
2. What data do you have (or can acquire)?
|
||||
3. How many pages are you planning to create?
|
||||
4. What does your site authority look like?
|
||||
5. Who currently ranks for these terms?
|
||||
6. What's your technical stack for generating pages?
|
||||
|
||||
---
|
||||
|
||||
## Related Skills
|
||||
|
||||
- **seo-audit**: For auditing programmatic pages after launch
|
||||
- **schema-markup**: For adding structured data to templates
|
||||
- **copywriting**: For the non-templated copy portions
|
||||
- **analytics-tracking**: For measuring programmatic page performance
|
||||
61
skills/prompt-caching/SKILL.md
Normal file
61
skills/prompt-caching/SKILL.md
Normal file
@@ -0,0 +1,61 @@
|
||||
---
|
||||
name: prompt-caching
|
||||
description: "Caching strategies for LLM prompts including Anthropic prompt caching, response caching, and CAG (Cache Augmented Generation) Use when: prompt caching, cache prompt, response cache, cag, cache augmented."
|
||||
source: vibeship-spawner-skills (Apache 2.0)
|
||||
---
|
||||
|
||||
# Prompt Caching
|
||||
|
||||
You're a caching specialist who has reduced LLM costs by 90% through strategic caching.
|
||||
You've implemented systems that cache at multiple levels: prompt prefixes, full responses,
|
||||
and semantic similarity matches.
|
||||
|
||||
You understand that LLM caching is different from traditional caching—prompts have
|
||||
prefixes that can be cached, responses vary with temperature, and semantic similarity
|
||||
often matters more than exact match.
|
||||
|
||||
Your core principles:
|
||||
1. Cache at the right level—prefix, response, or both
|
||||
2. K
|
||||
|
||||
## Capabilities
|
||||
|
||||
- prompt-cache
|
||||
- response-cache
|
||||
- kv-cache
|
||||
- cag-patterns
|
||||
- cache-invalidation
|
||||
|
||||
## Patterns
|
||||
|
||||
### Anthropic Prompt Caching
|
||||
|
||||
Use Claude's native prompt caching for repeated prefixes
|
||||
|
||||
### Response Caching
|
||||
|
||||
Cache full LLM responses for identical or similar queries
|
||||
|
||||
### Cache Augmented Generation (CAG)
|
||||
|
||||
Pre-cache documents in prompt instead of RAG retrieval
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
### ❌ Caching with High Temperature
|
||||
|
||||
### ❌ No Cache Invalidation
|
||||
|
||||
### ❌ Caching Everything
|
||||
|
||||
## ⚠️ Sharp Edges
|
||||
|
||||
| Issue | Severity | Solution |
|
||||
|-------|----------|----------|
|
||||
| Cache miss causes latency spike with additional overhead | high | // Optimize for cache misses, not just hits |
|
||||
| Cached responses become incorrect over time | high | // Implement proper cache invalidation |
|
||||
| Prompt caching doesn't work due to prefix changes | medium | // Structure prompts for optimal caching |
|
||||
|
||||
## Related Skills
|
||||
|
||||
Works well with: `context-window-management`, `rag-implementation`, `conversation-memory`
|
||||
93
skills/prompt-engineer/SKILL.md
Normal file
93
skills/prompt-engineer/SKILL.md
Normal file
@@ -0,0 +1,93 @@
|
||||
---
|
||||
name: prompt-engineer
|
||||
description: "Expert in designing effective prompts for LLM-powered applications. Masters prompt structure, context management, output formatting, and prompt evaluation. Use when: prompt engineering, system prompt, few-shot, chain of thought, prompt design."
|
||||
source: vibeship-spawner-skills (Apache 2.0)
|
||||
---
|
||||
|
||||
# Prompt Engineer
|
||||
|
||||
**Role**: LLM Prompt Architect
|
||||
|
||||
I translate intent into instructions that LLMs actually follow. I know
|
||||
that prompts are programming - they need the same rigor as code. I iterate
|
||||
relentlessly because small changes have big effects. I evaluate systematically
|
||||
because intuition about prompt quality is often wrong.
|
||||
|
||||
## Capabilities
|
||||
|
||||
- Prompt design and optimization
|
||||
- System prompt architecture
|
||||
- Context window management
|
||||
- Output format specification
|
||||
- Prompt testing and evaluation
|
||||
- Few-shot example design
|
||||
|
||||
## Requirements
|
||||
|
||||
- LLM fundamentals
|
||||
- Understanding of tokenization
|
||||
- Basic programming
|
||||
|
||||
## Patterns
|
||||
|
||||
### Structured System Prompt
|
||||
|
||||
Well-organized system prompt with clear sections
|
||||
|
||||
```javascript
|
||||
- Role: who the model is
|
||||
- Context: relevant background
|
||||
- Instructions: what to do
|
||||
- Constraints: what NOT to do
|
||||
- Output format: expected structure
|
||||
- Examples: demonstration of correct behavior
|
||||
```
|
||||
|
||||
### Few-Shot Examples
|
||||
|
||||
Include examples of desired behavior
|
||||
|
||||
```javascript
|
||||
- Show 2-5 diverse examples
|
||||
- Include edge cases in examples
|
||||
- Match example difficulty to expected inputs
|
||||
- Use consistent formatting across examples
|
||||
- Include negative examples when helpful
|
||||
```
|
||||
|
||||
### Chain-of-Thought
|
||||
|
||||
Request step-by-step reasoning
|
||||
|
||||
```javascript
|
||||
- Ask model to think step by step
|
||||
- Provide reasoning structure
|
||||
- Request explicit intermediate steps
|
||||
- Parse reasoning separately from answer
|
||||
- Use for debugging model failures
|
||||
```
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
### ❌ Vague Instructions
|
||||
|
||||
### ❌ Kitchen Sink Prompt
|
||||
|
||||
### ❌ No Negative Instructions
|
||||
|
||||
## ⚠️ Sharp Edges
|
||||
|
||||
| Issue | Severity | Solution |
|
||||
|-------|----------|----------|
|
||||
| Using imprecise language in prompts | high | Be explicit: |
|
||||
| Expecting specific format without specifying it | high | Specify format explicitly: |
|
||||
| Only saying what to do, not what to avoid | medium | Include explicit don'ts: |
|
||||
| Changing prompts without measuring impact | medium | Systematic evaluation: |
|
||||
| Including irrelevant context 'just in case' | medium | Curate context: |
|
||||
| Biased or unrepresentative examples | medium | Diverse examples: |
|
||||
| Using default temperature for all tasks | medium | Task-appropriate temperature: |
|
||||
| Not considering prompt injection in user input | high | Defend against injection: |
|
||||
|
||||
## Related Skills
|
||||
|
||||
Works well with: `ai-agents-architect`, `rag-engineer`, `backend`, `product-manager`
|
||||
90
skills/rag-engineer/SKILL.md
Normal file
90
skills/rag-engineer/SKILL.md
Normal file
@@ -0,0 +1,90 @@
|
||||
---
|
||||
name: rag-engineer
|
||||
description: "Expert in building Retrieval-Augmented Generation systems. Masters embedding models, vector databases, chunking strategies, and retrieval optimization for LLM applications. Use when: building RAG, vector search, embeddings, semantic search, document retrieval."
|
||||
source: vibeship-spawner-skills (Apache 2.0)
|
||||
---
|
||||
|
||||
# RAG Engineer
|
||||
|
||||
**Role**: RAG Systems Architect
|
||||
|
||||
I bridge the gap between raw documents and LLM understanding. I know that
|
||||
retrieval quality determines generation quality - garbage in, garbage out.
|
||||
I obsess over chunking boundaries, embedding dimensions, and similarity
|
||||
metrics because they make the difference between helpful and hallucinating.
|
||||
|
||||
## Capabilities
|
||||
|
||||
- Vector embeddings and similarity search
|
||||
- Document chunking and preprocessing
|
||||
- Retrieval pipeline design
|
||||
- Semantic search implementation
|
||||
- Context window optimization
|
||||
- Hybrid search (keyword + semantic)
|
||||
|
||||
## Requirements
|
||||
|
||||
- LLM fundamentals
|
||||
- Understanding of embeddings
|
||||
- Basic NLP concepts
|
||||
|
||||
## Patterns
|
||||
|
||||
### Semantic Chunking
|
||||
|
||||
Chunk by meaning, not arbitrary token counts
|
||||
|
||||
```javascript
|
||||
- Use sentence boundaries, not token limits
|
||||
- Detect topic shifts with embedding similarity
|
||||
- Preserve document structure (headers, paragraphs)
|
||||
- Include overlap for context continuity
|
||||
- Add metadata for filtering
|
||||
```
|
||||
|
||||
### Hierarchical Retrieval
|
||||
|
||||
Multi-level retrieval for better precision
|
||||
|
||||
```javascript
|
||||
- Index at multiple chunk sizes (paragraph, section, document)
|
||||
- First pass: coarse retrieval for candidates
|
||||
- Second pass: fine-grained retrieval for precision
|
||||
- Use parent-child relationships for context
|
||||
```
|
||||
|
||||
### Hybrid Search
|
||||
|
||||
Combine semantic and keyword search
|
||||
|
||||
```javascript
|
||||
- BM25/TF-IDF for keyword matching
|
||||
- Vector similarity for semantic matching
|
||||
- Reciprocal Rank Fusion for combining scores
|
||||
- Weight tuning based on query type
|
||||
```
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
### ❌ Fixed Chunk Size
|
||||
|
||||
### ❌ Embedding Everything
|
||||
|
||||
### ❌ Ignoring Evaluation
|
||||
|
||||
## ⚠️ Sharp Edges
|
||||
|
||||
| Issue | Severity | Solution |
|
||||
|-------|----------|----------|
|
||||
| Fixed-size chunking breaks sentences and context | high | Use semantic chunking that respects document structure: |
|
||||
| Pure semantic search without metadata pre-filtering | medium | Implement hybrid filtering: |
|
||||
| Using same embedding model for different content types | medium | Evaluate embeddings per content type: |
|
||||
| Using first-stage retrieval results directly | medium | Add reranking step: |
|
||||
| Cramming maximum context into LLM prompt | medium | Use relevance thresholds: |
|
||||
| Not measuring retrieval quality separately from generation | high | Separate retrieval evaluation: |
|
||||
| Not updating embeddings when source documents change | medium | Implement embedding refresh: |
|
||||
| Same retrieval strategy for all query types | medium | Implement hybrid search: |
|
||||
|
||||
## Related Skills
|
||||
|
||||
Works well with: `ai-agents-architect`, `prompt-engineer`, `database-architect`, `backend`
|
||||
63
skills/rag-implementation/SKILL.md
Normal file
63
skills/rag-implementation/SKILL.md
Normal file
@@ -0,0 +1,63 @@
|
||||
---
|
||||
name: rag-implementation
|
||||
description: "Retrieval-Augmented Generation patterns including chunking, embeddings, vector stores, and retrieval optimization Use when: rag, retrieval augmented, vector search, embeddings, semantic search."
|
||||
source: vibeship-spawner-skills (Apache 2.0)
|
||||
---
|
||||
|
||||
# RAG Implementation
|
||||
|
||||
You're a RAG specialist who has built systems serving millions of queries over
|
||||
terabytes of documents. You've seen the naive "chunk and embed" approach fail,
|
||||
and developed sophisticated chunking, retrieval, and reranking strategies.
|
||||
|
||||
You understand that RAG is not just vector search—it's about getting the right
|
||||
information to the LLM at the right time. You know when RAG helps and when
|
||||
it's unnecessary overhead.
|
||||
|
||||
Your core principles:
|
||||
1. Chunking is critical—bad chunks mean bad retrieval
|
||||
2. Hybri
|
||||
|
||||
## Capabilities
|
||||
|
||||
- document-chunking
|
||||
- embedding-models
|
||||
- vector-stores
|
||||
- retrieval-strategies
|
||||
- hybrid-search
|
||||
- reranking
|
||||
|
||||
## Patterns
|
||||
|
||||
### Semantic Chunking
|
||||
|
||||
Chunk by meaning, not arbitrary size
|
||||
|
||||
### Hybrid Search
|
||||
|
||||
Combine dense (vector) and sparse (keyword) search
|
||||
|
||||
### Contextual Reranking
|
||||
|
||||
Rerank retrieved docs with LLM for relevance
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
### ❌ Fixed-Size Chunking
|
||||
|
||||
### ❌ No Overlap
|
||||
|
||||
### ❌ Single Retrieval Strategy
|
||||
|
||||
## ⚠️ Sharp Edges
|
||||
|
||||
| Issue | Severity | Solution |
|
||||
|-------|----------|----------|
|
||||
| Poor chunking ruins retrieval quality | critical | // Use recursive character text splitter with overlap |
|
||||
| Query and document embeddings from different models | critical | // Ensure consistent embedding model usage |
|
||||
| RAG adds significant latency to responses | high | // Optimize RAG latency |
|
||||
| Documents updated but embeddings not refreshed | medium | // Maintain sync between documents and embeddings |
|
||||
|
||||
## Related Skills
|
||||
|
||||
Works well with: `context-window-management`, `conversation-memory`, `prompt-caching`, `data-pipeline`
|
||||
602
skills/referral-program/SKILL.md
Normal file
602
skills/referral-program/SKILL.md
Normal file
@@ -0,0 +1,602 @@
|
||||
---
|
||||
name: referral-program
|
||||
description: "When the user wants to create, optimize, or analyze a referral program, affiliate program, or word-of-mouth strategy. Also use when the user mentions 'referral,' 'affiliate,' 'ambassador,' 'word of mouth,' 'viral loop,' 'refer a friend,' or 'partner program.' This skill covers program design, incentive structure, and growth optimization."
|
||||
---
|
||||
|
||||
# Referral & Affiliate Programs
|
||||
|
||||
You are an expert in viral growth and referral marketing with access to referral program data and third-party tools. Your goal is to help design and optimize programs that turn customers into growth engines.
|
||||
|
||||
## Before Starting
|
||||
|
||||
Gather this context (ask if not provided):
|
||||
|
||||
### 1. Program Type
|
||||
- Are you building a customer referral program, affiliate program, or both?
|
||||
- Is this B2B or B2C?
|
||||
- What's the average customer value (LTV)?
|
||||
- What's your current CAC from other channels?
|
||||
|
||||
### 2. Current State
|
||||
- Do you have an existing referral/affiliate program?
|
||||
- What's your current referral rate (% of customers who refer)?
|
||||
- What incentives have you tried?
|
||||
- Do you have customer NPS or satisfaction data?
|
||||
|
||||
### 3. Product Fit
|
||||
- Is your product shareable? (Does using it involve others?)
|
||||
- Does your product have network effects?
|
||||
- Do customers naturally talk about your product?
|
||||
- What triggers word-of-mouth currently?
|
||||
|
||||
### 4. Resources
|
||||
- What tools/platforms do you use or consider?
|
||||
- What's your budget for referral incentives?
|
||||
- Do you have engineering resources for custom implementation?
|
||||
|
||||
---
|
||||
|
||||
## Referral vs. Affiliate: When to Use Each
|
||||
|
||||
### Customer Referral Programs
|
||||
|
||||
**Best for:**
|
||||
- Existing customers recommending to their network
|
||||
- Products with natural word-of-mouth
|
||||
- Building authentic social proof
|
||||
- Lower-ticket or self-serve products
|
||||
|
||||
**Characteristics:**
|
||||
- Referrer is an existing customer
|
||||
- Motivation: Rewards + helping friends
|
||||
- Typically one-time or limited rewards
|
||||
- Tracked via unique links or codes
|
||||
- Higher trust, lower volume
|
||||
|
||||
### Affiliate Programs
|
||||
|
||||
**Best for:**
|
||||
- Reaching audiences you don't have access to
|
||||
- Content creators, influencers, bloggers
|
||||
- Products with clear value proposition
|
||||
- Higher-ticket products that justify commissions
|
||||
|
||||
**Characteristics:**
|
||||
- Affiliates may not be customers
|
||||
- Motivation: Revenue/commission
|
||||
- Ongoing commission relationship
|
||||
- Requires more management
|
||||
- Higher volume, variable trust
|
||||
|
||||
### Hybrid Approach
|
||||
|
||||
Many successful programs combine both:
|
||||
- Referral program for customers (simple, small rewards)
|
||||
- Affiliate program for partners (larger commissions, more structure)
|
||||
|
||||
---
|
||||
|
||||
## Referral Program Design
|
||||
|
||||
### The Referral Loop
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────┐
|
||||
│ │
|
||||
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
|
||||
│ │ Trigger │───▶│ Share │───▶│ Convert │ │
|
||||
│ │ Moment │ │ Action │ │ Referred │ │
|
||||
│ └──────────┘ └──────────┘ └──────────┘ │
|
||||
│ ▲ │ │
|
||||
│ │ │ │
|
||||
│ └───────────────────────────────┘ │
|
||||
│ Reward │
|
||||
└─────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Step 1: Identify Trigger Moments
|
||||
|
||||
When are customers most likely to refer?
|
||||
|
||||
**High-intent moments:**
|
||||
- Right after first "aha" moment
|
||||
- After achieving a milestone
|
||||
- After receiving exceptional support
|
||||
- After renewing or upgrading
|
||||
- When they tell you they love the product
|
||||
|
||||
**Natural sharing moments:**
|
||||
- When the product involves collaboration
|
||||
- When they're asked "what tool do you use?"
|
||||
- When they share results publicly
|
||||
- When they complete something shareable
|
||||
|
||||
### Step 2: Design the Share Mechanism
|
||||
|
||||
**Methods ranked by effectiveness:**
|
||||
|
||||
1. **In-product sharing** — Highest conversion, feels native
|
||||
2. **Personalized link** — Easy to track, works everywhere
|
||||
3. **Email invitation** — Direct, personal, higher intent
|
||||
4. **Social sharing** — Broadest reach, lowest conversion
|
||||
5. **Referral code** — Memorable, works offline
|
||||
|
||||
**Best practice:** Offer multiple sharing options, lead with the highest-converting method.
|
||||
|
||||
### Step 3: Choose Incentive Structure
|
||||
|
||||
**Single-sided rewards** (referrer only):
|
||||
- Simpler to explain
|
||||
- Works for high-value products
|
||||
- Risk: Referred may feel no urgency
|
||||
|
||||
**Double-sided rewards** (both parties):
|
||||
- Higher conversion rates
|
||||
- Creates win-win framing
|
||||
- Standard for most programs
|
||||
|
||||
**Tiered rewards:**
|
||||
- Increases engagement over time
|
||||
- Gamifies the referral process
|
||||
- More complex to communicate
|
||||
|
||||
### Incentive Types
|
||||
|
||||
| Type | Pros | Cons | Best For |
|
||||
|------|------|------|----------|
|
||||
| Cash/credit | Universally valued | Feels transactional | Marketplaces, fintech |
|
||||
| Product credit | Drives usage | Only valuable if they'll use it | SaaS, subscriptions |
|
||||
| Free months | Clear value | May attract freebie-seekers | Subscription products |
|
||||
| Feature unlock | Low cost to you | Only works for gated features | Freemium products |
|
||||
| Swag/gifts | Memorable, shareable | Logistics complexity | Brand-focused companies |
|
||||
| Charity donation | Feel-good | Lower personal motivation | Mission-driven brands |
|
||||
|
||||
### Incentive Sizing Framework
|
||||
|
||||
**Calculate your maximum incentive:**
|
||||
```
|
||||
Max Referral Reward = (Customer LTV × Gross Margin) - Target CAC
|
||||
```
|
||||
|
||||
**Example:**
|
||||
- LTV: $1,200
|
||||
- Gross margin: 70%
|
||||
- Target CAC: $200
|
||||
- Max reward: ($1,200 × 0.70) - $200 = $640
|
||||
|
||||
**Typical referral rewards:**
|
||||
- B2C: $10-50 or 10-25% of first purchase
|
||||
- B2B SaaS: $50-500 or 1-3 months free
|
||||
- Enterprise: Higher, often custom
|
||||
|
||||
---
|
||||
|
||||
## Referral Program Examples
|
||||
|
||||
### Dropbox (Classic)
|
||||
|
||||
**Program:** Give 500MB storage, get 500MB storage
|
||||
**Why it worked:**
|
||||
- Reward directly tied to product value
|
||||
- Low friction (just an email)
|
||||
- Both parties benefit equally
|
||||
- Gamified with progress tracking
|
||||
|
||||
### Uber/Lyft
|
||||
|
||||
**Program:** Give $10 ride credit, get $10 when they ride
|
||||
**Why it worked:**
|
||||
- Immediate, clear value
|
||||
- Double-sided incentive
|
||||
- Easy to share (code/link)
|
||||
- Triggered at natural moments
|
||||
|
||||
### Morning Brew
|
||||
|
||||
**Program:** Tiered rewards for subscriber referrals
|
||||
- 3 referrals: Newsletter stickers
|
||||
- 5 referrals: T-shirt
|
||||
- 10 referrals: Mug
|
||||
- 25 referrals: Hoodie
|
||||
|
||||
**Why it worked:**
|
||||
- Gamification drives ongoing engagement
|
||||
- Physical rewards are shareable (more referrals)
|
||||
- Low cost relative to subscriber value
|
||||
- Built status/identity
|
||||
|
||||
### Notion
|
||||
|
||||
**Program:** $10 credit per referral (education)
|
||||
**Why it worked:**
|
||||
- Targeted high-sharing audience (students)
|
||||
- Product naturally spreads in teams
|
||||
- Credit keeps users engaged
|
||||
|
||||
---
|
||||
|
||||
## Affiliate Program Design
|
||||
|
||||
### Commission Structures
|
||||
|
||||
**Percentage of sale:**
|
||||
- Standard: 10-30% of first sale or first year
|
||||
- Works for: E-commerce, SaaS with clear pricing
|
||||
- Example: "Earn 25% of every sale you refer"
|
||||
|
||||
**Flat fee per action:**
|
||||
- Standard: $5-500 depending on value
|
||||
- Works for: Lead gen, trials, freemium
|
||||
- Example: "$50 for every qualified demo"
|
||||
|
||||
**Recurring commission:**
|
||||
- Standard: 10-25% of recurring revenue
|
||||
- Works for: Subscription products
|
||||
- Example: "20% of subscription for 12 months"
|
||||
|
||||
**Tiered commission:**
|
||||
- Works for: Motivating high performers
|
||||
- Example: "20% for 1-10 sales, 25% for 11-25, 30% for 26+"
|
||||
|
||||
### Cookie Duration
|
||||
|
||||
How long after click does affiliate get credit?
|
||||
|
||||
| Duration | Use Case |
|
||||
|----------|----------|
|
||||
| 24 hours | High-volume, low-consideration purchases |
|
||||
| 7-14 days | Standard e-commerce |
|
||||
| 30 days | Standard SaaS/B2B |
|
||||
| 60-90 days | Long sales cycles, enterprise |
|
||||
| Lifetime | Premium affiliate relationships |
|
||||
|
||||
### Affiliate Recruitment
|
||||
|
||||
**Where to find affiliates:**
|
||||
- Existing customers who create content
|
||||
- Industry bloggers and reviewers
|
||||
- YouTubers in your niche
|
||||
- Newsletter writers
|
||||
- Complementary tool companies
|
||||
- Consultants and agencies
|
||||
|
||||
**Outreach template:**
|
||||
```
|
||||
Subject: Partnership opportunity — [Your Product]
|
||||
|
||||
Hi [Name],
|
||||
|
||||
I've been following your content on [topic] — particularly [specific piece] — and think there could be a great fit for a partnership.
|
||||
|
||||
[Your Product] helps [audience] [achieve outcome], and I think your audience would find it valuable.
|
||||
|
||||
We offer [commission structure] for partners, plus [additional benefits: early access, co-marketing, etc.].
|
||||
|
||||
Would you be open to learning more?
|
||||
|
||||
[Your name]
|
||||
```
|
||||
|
||||
### Affiliate Enablement
|
||||
|
||||
Provide affiliates with:
|
||||
- [ ] Unique tracking links/codes
|
||||
- [ ] Product overview and key benefits
|
||||
- [ ] Target audience description
|
||||
- [ ] Comparison to competitors
|
||||
- [ ] Creative assets (logos, banners, images)
|
||||
- [ ] Sample copy and talking points
|
||||
- [ ] Case studies and testimonials
|
||||
- [ ] Demo access or free account
|
||||
- [ ] FAQ and objection handling
|
||||
- [ ] Payment terms and schedule
|
||||
|
||||
---
|
||||
|
||||
## Viral Coefficient & Modeling
|
||||
|
||||
### Key Metrics
|
||||
|
||||
**Viral coefficient (K-factor):**
|
||||
```
|
||||
K = Invitations × Conversion Rate
|
||||
|
||||
K > 1 = Viral growth (each user brings more than 1 new user)
|
||||
K < 1 = Amplified growth (referrals supplement other acquisition)
|
||||
```
|
||||
|
||||
**Example:**
|
||||
- Average customer sends 3 invitations
|
||||
- 15% of invitations convert
|
||||
- K = 3 × 0.15 = 0.45
|
||||
|
||||
**Referral rate:**
|
||||
```
|
||||
Referral Rate = (Customers who refer) / (Total customers)
|
||||
```
|
||||
|
||||
Benchmarks:
|
||||
- Good: 10-25% of customers refer
|
||||
- Great: 25-50%
|
||||
- Exceptional: 50%+
|
||||
|
||||
**Referrals per referrer:**
|
||||
```
|
||||
How many successful referrals does each referring customer generate?
|
||||
```
|
||||
|
||||
Benchmarks:
|
||||
- Average: 1-2 referrals per referrer
|
||||
- Good: 2-5
|
||||
- Exceptional: 5+
|
||||
|
||||
### Calculating Referral Program ROI
|
||||
|
||||
```
|
||||
Referral Program ROI = (Revenue from referred customers - Program costs) / Program costs
|
||||
|
||||
Program costs = Rewards paid + Tool costs + Management time
|
||||
```
|
||||
|
||||
**Track separately:**
|
||||
- Cost per referred customer (CAC via referral)
|
||||
- LTV of referred customers (often higher than average)
|
||||
- Payback period for referral rewards
|
||||
|
||||
---
|
||||
|
||||
## Program Optimization
|
||||
|
||||
### Improving Referral Rate
|
||||
|
||||
**If few customers are referring:**
|
||||
- Ask at better moments (after wins, not randomly)
|
||||
- Simplify the sharing process
|
||||
- Test different incentive types
|
||||
- Make the referral prominent in product
|
||||
- Remind via email campaigns
|
||||
- Reduce friction in the flow
|
||||
|
||||
**If referrals aren't converting:**
|
||||
- Improve the landing experience for referred users
|
||||
- Strengthen the incentive for new users
|
||||
- Test different messaging on referral pages
|
||||
- Ensure the referrer's endorsement is visible
|
||||
- Shorten the path to value
|
||||
|
||||
### A/B Tests to Run
|
||||
|
||||
**Incentive tests:**
|
||||
- Reward amount (10% higher, 20% higher)
|
||||
- Reward type (credit vs. cash vs. free months)
|
||||
- Single vs. double-sided
|
||||
- Immediate vs. delayed reward
|
||||
|
||||
**Messaging tests:**
|
||||
- How you describe the program
|
||||
- CTA copy on share buttons
|
||||
- Email subject lines for referral invites
|
||||
- Landing page copy for referred users
|
||||
|
||||
**Placement tests:**
|
||||
- Where the referral prompt appears
|
||||
- When it appears (trigger timing)
|
||||
- How prominent it is
|
||||
- In-app vs. email prompts
|
||||
|
||||
### Common Problems & Fixes
|
||||
|
||||
| Problem | Likely Cause | Fix |
|
||||
|---------|--------------|-----|
|
||||
| Low awareness | Program not visible | Add prominent in-app prompts |
|
||||
| Low share rate | Too much friction | Simplify to one click |
|
||||
| Low conversion | Weak landing page | Optimize referred user experience |
|
||||
| Fraud/abuse | Gaming the system | Add verification, limits |
|
||||
| One-time referrers | No ongoing motivation | Add tiered/gamified rewards |
|
||||
|
||||
---
|
||||
|
||||
## Fraud Prevention
|
||||
|
||||
### Common Referral Fraud
|
||||
|
||||
- Self-referrals (creating fake accounts)
|
||||
- Referral rings (groups referring each other)
|
||||
- Coupon sites posting referral codes
|
||||
- Fake email addresses
|
||||
- VPN/device spoofing
|
||||
|
||||
### Prevention Measures
|
||||
|
||||
**Technical:**
|
||||
- Email verification required
|
||||
- Device fingerprinting
|
||||
- IP address monitoring
|
||||
- Delayed reward payout (after activation)
|
||||
- Minimum activity threshold
|
||||
|
||||
**Policy:**
|
||||
- Clear terms of service
|
||||
- Maximum referrals per period
|
||||
- Reward clawback for refunds/chargebacks
|
||||
- Manual review for suspicious patterns
|
||||
|
||||
**Structural:**
|
||||
- Require referred user to take meaningful action
|
||||
- Cap lifetime rewards
|
||||
- Pay rewards in product credit (less attractive to fraudsters)
|
||||
|
||||
---
|
||||
|
||||
## Tools & Platforms
|
||||
|
||||
### Referral Program Tools
|
||||
|
||||
**Full-featured platforms:**
|
||||
- ReferralCandy — E-commerce focused
|
||||
- Ambassador — Enterprise referral programs
|
||||
- Friendbuy — E-commerce and subscription
|
||||
- GrowSurf — SaaS and tech companies
|
||||
- Viral Loops — Template-based campaigns
|
||||
|
||||
**Built-in options:**
|
||||
- Stripe (basic referral tracking)
|
||||
- HubSpot (CRM-integrated)
|
||||
- Segment (tracking and analytics)
|
||||
|
||||
### Affiliate Program Tools
|
||||
|
||||
**Affiliate networks:**
|
||||
- ShareASale — Large merchant network
|
||||
- Impact — Enterprise partnerships
|
||||
- PartnerStack — SaaS focused
|
||||
- Tapfiliate — Simple SaaS affiliate tracking
|
||||
- FirstPromoter — SaaS affiliate management
|
||||
|
||||
**Self-hosted:**
|
||||
- Rewardful — Stripe-integrated affiliates
|
||||
- Refersion — E-commerce affiliates
|
||||
|
||||
### Choosing a Tool
|
||||
|
||||
Consider:
|
||||
- Integration with your payment system
|
||||
- Fraud detection capabilities
|
||||
- Payout management
|
||||
- Reporting and analytics
|
||||
- Customization options
|
||||
- Price vs. program scale
|
||||
|
||||
---
|
||||
|
||||
## Email Sequences for Referral Programs
|
||||
|
||||
### Referral Program Launch
|
||||
|
||||
**Email 1: Announcement**
|
||||
```
|
||||
Subject: You can now earn [reward] for sharing [Product]
|
||||
|
||||
Body:
|
||||
We just launched our referral program!
|
||||
|
||||
Share [Product] with friends and earn [reward] for each person who signs up. They get [their reward] too.
|
||||
|
||||
[Unique referral link]
|
||||
|
||||
Here's how it works:
|
||||
1. Share your link
|
||||
2. Friend signs up
|
||||
3. You both get [reward]
|
||||
|
||||
[CTA: Share now]
|
||||
```
|
||||
|
||||
### Referral Nurture Sequence
|
||||
|
||||
**After signup (if they haven't referred):**
|
||||
- Day 7: Remind about referral program
|
||||
- Day 30: "Know anyone who'd benefit?"
|
||||
- Day 60: Success story + referral prompt
|
||||
- After milestone: "You just [achievement] — know others who'd want this?"
|
||||
|
||||
### Re-engagement for Past Referrers
|
||||
|
||||
```
|
||||
Subject: Your friends are loving [Product]
|
||||
|
||||
Body:
|
||||
Remember when you referred [Name]? They've [achievement/milestone].
|
||||
|
||||
Know anyone else who'd benefit? You'll earn [reward] for each friend who joins.
|
||||
|
||||
[Referral link]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Measuring Success
|
||||
|
||||
### Dashboard Metrics
|
||||
|
||||
**Program health:**
|
||||
- Active referrers (referred someone in last 30 days)
|
||||
- Total referrals (invites sent)
|
||||
- Referral conversion rate
|
||||
- Rewards earned/paid
|
||||
|
||||
**Business impact:**
|
||||
- % of new customers from referrals
|
||||
- CAC via referral vs. other channels
|
||||
- LTV of referred customers
|
||||
- Referral program ROI
|
||||
|
||||
### Cohort Analysis
|
||||
|
||||
Track referred customers separately:
|
||||
- Do they convert faster?
|
||||
- Do they have higher LTV?
|
||||
- Do they refer others at higher rates?
|
||||
- Do they churn less?
|
||||
|
||||
Typical findings:
|
||||
- Referred customers have 16-25% higher LTV
|
||||
- Referred customers have 18-37% lower churn
|
||||
- Referred customers refer others at 2-3x rate
|
||||
|
||||
---
|
||||
|
||||
## Launch Checklist
|
||||
|
||||
### Before Launch
|
||||
|
||||
- [ ] Define program goals and success metrics
|
||||
- [ ] Design incentive structure
|
||||
- [ ] Build or configure referral tool
|
||||
- [ ] Create referral landing page
|
||||
- [ ] Design email templates
|
||||
- [ ] Set up tracking and attribution
|
||||
- [ ] Define fraud prevention rules
|
||||
- [ ] Create terms and conditions
|
||||
- [ ] Test complete referral flow
|
||||
- [ ] Plan launch announcement
|
||||
|
||||
### Launch
|
||||
|
||||
- [ ] Announce to existing customers (email)
|
||||
- [ ] Add in-app referral prompts
|
||||
- [ ] Update website with program details
|
||||
- [ ] Brief support team on program
|
||||
- [ ] Monitor for fraud/issues
|
||||
- [ ] Track initial metrics
|
||||
|
||||
### Post-Launch (First 30 Days)
|
||||
|
||||
- [ ] Review conversion funnel
|
||||
- [ ] Identify top referrers
|
||||
- [ ] Gather feedback on program
|
||||
- [ ] Fix any friction points
|
||||
- [ ] Plan first optimizations
|
||||
- [ ] Send reminder emails to non-referrers
|
||||
|
||||
---
|
||||
|
||||
## Questions to Ask
|
||||
|
||||
If you need more context:
|
||||
1. What type of program are you building (referral, affiliate, or both)?
|
||||
2. What's your customer LTV and current CAC?
|
||||
3. Do you have an existing program, or starting from scratch?
|
||||
4. What tools/platforms are you using or considering?
|
||||
5. What's your budget for rewards/commissions?
|
||||
6. Is your product naturally shareable (involves others, visible results)?
|
||||
|
||||
---
|
||||
|
||||
## Related Skills
|
||||
|
||||
- **launch-strategy**: For launching referral program effectively
|
||||
- **email-sequence**: For referral nurture campaigns
|
||||
- **marketing-psychology**: For understanding referral motivation
|
||||
- **analytics-tracking**: For tracking referral attribution
|
||||
- **pricing-strategy**: For structuring rewards relative to LTV
|
||||
51
skills/salesforce-development/SKILL.md
Normal file
51
skills/salesforce-development/SKILL.md
Normal file
@@ -0,0 +1,51 @@
|
||||
---
|
||||
name: salesforce-development
|
||||
description: "Expert patterns for Salesforce platform development including Lightning Web Components (LWC), Apex triggers and classes, REST/Bulk APIs, Connected Apps, and Salesforce DX with scratch orgs and 2nd generation packages (2GP). Use when: salesforce, sfdc, apex, lwc, lightning web components."
|
||||
source: vibeship-spawner-skills (Apache 2.0)
|
||||
---
|
||||
|
||||
# Salesforce Development
|
||||
|
||||
## Patterns
|
||||
|
||||
### Lightning Web Component with Wire Service
|
||||
|
||||
Use @wire decorator for reactive data binding with Lightning Data Service
|
||||
or Apex methods. @wire fits LWC's reactive architecture and enables
|
||||
Salesforce performance optimizations.
|
||||
|
||||
|
||||
### Bulkified Apex Trigger with Handler Pattern
|
||||
|
||||
Apex triggers must be bulkified to handle 200+ records per transaction.
|
||||
Use handler pattern for separation of concerns, testability, and
|
||||
recursion prevention.
|
||||
|
||||
|
||||
### Queueable Apex for Async Processing
|
||||
|
||||
Use Queueable Apex for async processing with support for non-primitive
|
||||
types, monitoring via AsyncApexJob, and job chaining. Limit: 50 jobs
|
||||
per transaction, 1 child job when chaining.
|
||||
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
### ❌ SOQL Inside Loops
|
||||
|
||||
### ❌ DML Inside Loops
|
||||
|
||||
### ❌ Hardcoding IDs
|
||||
|
||||
## ⚠️ Sharp Edges
|
||||
|
||||
| Issue | Severity | Solution |
|
||||
|-------|----------|----------|
|
||||
| Issue | critical | See docs |
|
||||
| Issue | high | See docs |
|
||||
| Issue | medium | See docs |
|
||||
| Issue | high | See docs |
|
||||
| Issue | critical | See docs |
|
||||
| Issue | high | See docs |
|
||||
| Issue | high | See docs |
|
||||
| Issue | critical | See docs |
|
||||
596
skills/schema-markup/SKILL.md
Normal file
596
skills/schema-markup/SKILL.md
Normal file
@@ -0,0 +1,596 @@
|
||||
---
|
||||
name: schema-markup
|
||||
description: When the user wants to add, fix, or optimize schema markup and structured data on their site. Also use when the user mentions "schema markup," "structured data," "JSON-LD," "rich snippets," "schema.org," "FAQ schema," "product schema," "review schema," or "breadcrumb schema." For broader SEO issues, see seo-audit.
|
||||
---
|
||||
|
||||
# Schema Markup
|
||||
|
||||
You are an expert in structured data and schema markup. Your goal is to implement schema.org markup that helps search engines understand content and enables rich results in search.
|
||||
|
||||
## Initial Assessment
|
||||
|
||||
Before implementing schema, understand:
|
||||
|
||||
1. **Page Type**
|
||||
- What kind of page is this?
|
||||
- What's the primary content?
|
||||
- What rich results are possible?
|
||||
|
||||
2. **Current State**
|
||||
- Any existing schema?
|
||||
- Errors in current implementation?
|
||||
- Which rich results are already appearing?
|
||||
|
||||
3. **Goals**
|
||||
- Which rich results are you targeting?
|
||||
- What's the business value?
|
||||
|
||||
---
|
||||
|
||||
## Core Principles
|
||||
|
||||
### 1. Accuracy First
|
||||
- Schema must accurately represent page content
|
||||
- Don't markup content that doesn't exist
|
||||
- Keep updated when content changes
|
||||
|
||||
### 2. Use JSON-LD
|
||||
- Google recommends JSON-LD format
|
||||
- Easier to implement and maintain
|
||||
- Place in `<head>` or end of `<body>`
|
||||
|
||||
### 3. Follow Google's Guidelines
|
||||
- Only use markup Google supports
|
||||
- Avoid spam tactics
|
||||
- Review eligibility requirements
|
||||
|
||||
### 4. Validate Everything
|
||||
- Test before deploying
|
||||
- Monitor Search Console
|
||||
- Fix errors promptly
|
||||
|
||||
---
|
||||
|
||||
## Common Schema Types
|
||||
|
||||
### Organization
|
||||
**Use for**: Company/brand homepage or about page
|
||||
|
||||
**Required properties**:
|
||||
- name
|
||||
- url
|
||||
|
||||
**Recommended properties**:
|
||||
- logo
|
||||
- sameAs (social profiles)
|
||||
- contactPoint
|
||||
|
||||
```json
|
||||
{
|
||||
"@context": "https://schema.org",
|
||||
"@type": "Organization",
|
||||
"name": "Example Company",
|
||||
"url": "https://example.com",
|
||||
"logo": "https://example.com/logo.png",
|
||||
"sameAs": [
|
||||
"https://twitter.com/example",
|
||||
"https://linkedin.com/company/example",
|
||||
"https://facebook.com/example"
|
||||
],
|
||||
"contactPoint": {
|
||||
"@type": "ContactPoint",
|
||||
"telephone": "+1-555-555-5555",
|
||||
"contactType": "customer service"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### WebSite (with SearchAction)
|
||||
**Use for**: Homepage, enables sitelinks search box
|
||||
|
||||
**Required properties**:
|
||||
- name
|
||||
- url
|
||||
|
||||
**For search box**:
|
||||
- potentialAction with SearchAction
|
||||
|
||||
```json
|
||||
{
|
||||
"@context": "https://schema.org",
|
||||
"@type": "WebSite",
|
||||
"name": "Example",
|
||||
"url": "https://example.com",
|
||||
"potentialAction": {
|
||||
"@type": "SearchAction",
|
||||
"target": {
|
||||
"@type": "EntryPoint",
|
||||
"urlTemplate": "https://example.com/search?q={search_term_string}"
|
||||
},
|
||||
"query-input": "required name=search_term_string"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Article / BlogPosting
|
||||
**Use for**: Blog posts, news articles
|
||||
|
||||
**Required properties**:
|
||||
- headline
|
||||
- image
|
||||
- datePublished
|
||||
- author
|
||||
|
||||
**Recommended properties**:
|
||||
- dateModified
|
||||
- publisher
|
||||
- description
|
||||
- mainEntityOfPage
|
||||
|
||||
```json
|
||||
{
|
||||
"@context": "https://schema.org",
|
||||
"@type": "Article",
|
||||
"headline": "How to Implement Schema Markup",
|
||||
"image": "https://example.com/image.jpg",
|
||||
"datePublished": "2024-01-15T08:00:00+00:00",
|
||||
"dateModified": "2024-01-20T10:00:00+00:00",
|
||||
"author": {
|
||||
"@type": "Person",
|
||||
"name": "Jane Doe",
|
||||
"url": "https://example.com/authors/jane"
|
||||
},
|
||||
"publisher": {
|
||||
"@type": "Organization",
|
||||
"name": "Example Company",
|
||||
"logo": {
|
||||
"@type": "ImageObject",
|
||||
"url": "https://example.com/logo.png"
|
||||
}
|
||||
},
|
||||
"description": "A complete guide to implementing schema markup...",
|
||||
"mainEntityOfPage": {
|
||||
"@type": "WebPage",
|
||||
"@id": "https://example.com/schema-guide"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Product
|
||||
**Use for**: Product pages (e-commerce or SaaS)
|
||||
|
||||
**Required properties**:
|
||||
- name
|
||||
- image
|
||||
- offers (with price and availability)
|
||||
|
||||
**Recommended properties**:
|
||||
- description
|
||||
- sku
|
||||
- brand
|
||||
- aggregateRating
|
||||
- review
|
||||
|
||||
```json
|
||||
{
|
||||
"@context": "https://schema.org",
|
||||
"@type": "Product",
|
||||
"name": "Premium Widget",
|
||||
"image": "https://example.com/widget.jpg",
|
||||
"description": "Our best-selling widget for professionals",
|
||||
"sku": "WIDGET-001",
|
||||
"brand": {
|
||||
"@type": "Brand",
|
||||
"name": "Example Co"
|
||||
},
|
||||
"offers": {
|
||||
"@type": "Offer",
|
||||
"url": "https://example.com/products/widget",
|
||||
"priceCurrency": "USD",
|
||||
"price": "99.99",
|
||||
"availability": "https://schema.org/InStock",
|
||||
"priceValidUntil": "2024-12-31"
|
||||
},
|
||||
"aggregateRating": {
|
||||
"@type": "AggregateRating",
|
||||
"ratingValue": "4.8",
|
||||
"reviewCount": "127"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### SoftwareApplication
|
||||
**Use for**: SaaS product pages, app landing pages
|
||||
|
||||
**Required properties**:
|
||||
- name
|
||||
- offers (or free indicator)
|
||||
|
||||
**Recommended properties**:
|
||||
- applicationCategory
|
||||
- operatingSystem
|
||||
- aggregateRating
|
||||
|
||||
```json
|
||||
{
|
||||
"@context": "https://schema.org",
|
||||
"@type": "SoftwareApplication",
|
||||
"name": "Example App",
|
||||
"applicationCategory": "BusinessApplication",
|
||||
"operatingSystem": "Web, iOS, Android",
|
||||
"offers": {
|
||||
"@type": "Offer",
|
||||
"price": "0",
|
||||
"priceCurrency": "USD"
|
||||
},
|
||||
"aggregateRating": {
|
||||
"@type": "AggregateRating",
|
||||
"ratingValue": "4.6",
|
||||
"ratingCount": "1250"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### FAQPage
|
||||
**Use for**: Pages with frequently asked questions
|
||||
|
||||
**Required properties**:
|
||||
- mainEntity (array of Question/Answer)
|
||||
|
||||
```json
|
||||
{
|
||||
"@context": "https://schema.org",
|
||||
"@type": "FAQPage",
|
||||
"mainEntity": [
|
||||
{
|
||||
"@type": "Question",
|
||||
"name": "What is schema markup?",
|
||||
"acceptedAnswer": {
|
||||
"@type": "Answer",
|
||||
"text": "Schema markup is a structured data vocabulary that helps search engines understand your content..."
|
||||
}
|
||||
},
|
||||
{
|
||||
"@type": "Question",
|
||||
"name": "How do I implement schema?",
|
||||
"acceptedAnswer": {
|
||||
"@type": "Answer",
|
||||
"text": "The recommended approach is to use JSON-LD format, placing the script in your page's head..."
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### HowTo
|
||||
**Use for**: Instructional content, tutorials
|
||||
|
||||
**Required properties**:
|
||||
- name
|
||||
- step (array of HowToStep)
|
||||
|
||||
**Recommended properties**:
|
||||
- image
|
||||
- totalTime
|
||||
- estimatedCost
|
||||
- supply/tool
|
||||
|
||||
```json
|
||||
{
|
||||
"@context": "https://schema.org",
|
||||
"@type": "HowTo",
|
||||
"name": "How to Add Schema Markup to Your Website",
|
||||
"description": "A step-by-step guide to implementing JSON-LD schema",
|
||||
"totalTime": "PT15M",
|
||||
"step": [
|
||||
{
|
||||
"@type": "HowToStep",
|
||||
"name": "Choose your schema type",
|
||||
"text": "Identify the appropriate schema type for your page content...",
|
||||
"url": "https://example.com/guide#step1"
|
||||
},
|
||||
{
|
||||
"@type": "HowToStep",
|
||||
"name": "Write the JSON-LD",
|
||||
"text": "Create the JSON-LD markup following schema.org specifications...",
|
||||
"url": "https://example.com/guide#step2"
|
||||
},
|
||||
{
|
||||
"@type": "HowToStep",
|
||||
"name": "Add to your page",
|
||||
"text": "Insert the script tag in your page's head section...",
|
||||
"url": "https://example.com/guide#step3"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### BreadcrumbList
|
||||
**Use for**: Any page with breadcrumb navigation
|
||||
|
||||
```json
|
||||
{
|
||||
"@context": "https://schema.org",
|
||||
"@type": "BreadcrumbList",
|
||||
"itemListElement": [
|
||||
{
|
||||
"@type": "ListItem",
|
||||
"position": 1,
|
||||
"name": "Home",
|
||||
"item": "https://example.com"
|
||||
},
|
||||
{
|
||||
"@type": "ListItem",
|
||||
"position": 2,
|
||||
"name": "Blog",
|
||||
"item": "https://example.com/blog"
|
||||
},
|
||||
{
|
||||
"@type": "ListItem",
|
||||
"position": 3,
|
||||
"name": "SEO Guide",
|
||||
"item": "https://example.com/blog/seo-guide"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### LocalBusiness
|
||||
**Use for**: Local business location pages
|
||||
|
||||
**Required properties**:
|
||||
- name
|
||||
- address
|
||||
- (Various by business type)
|
||||
|
||||
```json
|
||||
{
|
||||
"@context": "https://schema.org",
|
||||
"@type": "LocalBusiness",
|
||||
"name": "Example Coffee Shop",
|
||||
"image": "https://example.com/shop.jpg",
|
||||
"address": {
|
||||
"@type": "PostalAddress",
|
||||
"streetAddress": "123 Main Street",
|
||||
"addressLocality": "San Francisco",
|
||||
"addressRegion": "CA",
|
||||
"postalCode": "94102",
|
||||
"addressCountry": "US"
|
||||
},
|
||||
"geo": {
|
||||
"@type": "GeoCoordinates",
|
||||
"latitude": "37.7749",
|
||||
"longitude": "-122.4194"
|
||||
},
|
||||
"telephone": "+1-555-555-5555",
|
||||
"openingHoursSpecification": [
|
||||
{
|
||||
"@type": "OpeningHoursSpecification",
|
||||
"dayOfWeek": ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"],
|
||||
"opens": "08:00",
|
||||
"closes": "18:00"
|
||||
}
|
||||
],
|
||||
"priceRange": "$$"
|
||||
}
|
||||
```
|
||||
|
||||
### Review / AggregateRating
|
||||
**Use for**: Review pages or products with reviews
|
||||
|
||||
Note: Self-serving reviews (reviewing your own product) are against guidelines. Reviews must be from real customers.
|
||||
|
||||
```json
|
||||
{
|
||||
"@context": "https://schema.org",
|
||||
"@type": "Product",
|
||||
"name": "Example Product",
|
||||
"aggregateRating": {
|
||||
"@type": "AggregateRating",
|
||||
"ratingValue": "4.5",
|
||||
"bestRating": "5",
|
||||
"worstRating": "1",
|
||||
"ratingCount": "523"
|
||||
},
|
||||
"review": [
|
||||
{
|
||||
"@type": "Review",
|
||||
"author": {
|
||||
"@type": "Person",
|
||||
"name": "John Smith"
|
||||
},
|
||||
"datePublished": "2024-01-10",
|
||||
"reviewRating": {
|
||||
"@type": "Rating",
|
||||
"ratingValue": "5"
|
||||
},
|
||||
"reviewBody": "Excellent product, exceeded my expectations..."
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Event
|
||||
**Use for**: Event pages, webinars, conferences
|
||||
|
||||
**Required properties**:
|
||||
- name
|
||||
- startDate
|
||||
- location (or eventAttendanceMode for online)
|
||||
|
||||
```json
|
||||
{
|
||||
"@context": "https://schema.org",
|
||||
"@type": "Event",
|
||||
"name": "Annual Marketing Conference",
|
||||
"startDate": "2024-06-15T09:00:00-07:00",
|
||||
"endDate": "2024-06-15T17:00:00-07:00",
|
||||
"eventAttendanceMode": "https://schema.org/OnlineEventAttendanceMode",
|
||||
"eventStatus": "https://schema.org/EventScheduled",
|
||||
"location": {
|
||||
"@type": "VirtualLocation",
|
||||
"url": "https://example.com/conference"
|
||||
},
|
||||
"image": "https://example.com/conference.jpg",
|
||||
"description": "Join us for our annual marketing conference...",
|
||||
"offers": {
|
||||
"@type": "Offer",
|
||||
"url": "https://example.com/conference/tickets",
|
||||
"price": "199",
|
||||
"priceCurrency": "USD",
|
||||
"availability": "https://schema.org/InStock",
|
||||
"validFrom": "2024-01-01"
|
||||
},
|
||||
"performer": {
|
||||
"@type": "Organization",
|
||||
"name": "Example Company"
|
||||
},
|
||||
"organizer": {
|
||||
"@type": "Organization",
|
||||
"name": "Example Company",
|
||||
"url": "https://example.com"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Multiple Schema Types on One Page
|
||||
|
||||
You can (and often should) have multiple schema types:
|
||||
|
||||
```json
|
||||
{
|
||||
"@context": "https://schema.org",
|
||||
"@graph": [
|
||||
{
|
||||
"@type": "Organization",
|
||||
"@id": "https://example.com/#organization",
|
||||
"name": "Example Company",
|
||||
"url": "https://example.com"
|
||||
},
|
||||
{
|
||||
"@type": "WebSite",
|
||||
"@id": "https://example.com/#website",
|
||||
"url": "https://example.com",
|
||||
"name": "Example",
|
||||
"publisher": {
|
||||
"@id": "https://example.com/#organization"
|
||||
}
|
||||
},
|
||||
{
|
||||
"@type": "BreadcrumbList",
|
||||
"itemListElement": [...]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Validation and Testing
|
||||
|
||||
### Tools
|
||||
- **Google Rich Results Test**: https://search.google.com/test/rich-results
|
||||
- **Schema.org Validator**: https://validator.schema.org/
|
||||
- **Search Console**: Enhancements reports
|
||||
|
||||
### Common Errors
|
||||
|
||||
**Missing required properties**
|
||||
- Check Google's documentation for required fields
|
||||
- Different from schema.org minimum requirements
|
||||
|
||||
**Invalid values**
|
||||
- Dates must be ISO 8601 format
|
||||
- URLs must be fully qualified
|
||||
- Enumerations must use exact values
|
||||
|
||||
**Mismatch with page content**
|
||||
- Schema doesn't match visible content
|
||||
- Ratings for products without reviews shown
|
||||
- Prices that don't match displayed prices
|
||||
|
||||
---
|
||||
|
||||
## Implementation Patterns
|
||||
|
||||
### Static Sites
|
||||
- Add JSON-LD directly in HTML template
|
||||
- Use includes/partials for reusable schema
|
||||
|
||||
### Dynamic Sites (React, Next.js, etc.)
|
||||
- Component that renders schema
|
||||
- Server-side rendered for SEO
|
||||
- Serialize data to JSON-LD
|
||||
|
||||
```jsx
|
||||
// Next.js example
|
||||
export default function ProductPage({ product }) {
|
||||
const schema = {
|
||||
"@context": "https://schema.org",
|
||||
"@type": "Product",
|
||||
name: product.name,
|
||||
// ... other properties
|
||||
};
|
||||
|
||||
return (
|
||||
<>
|
||||
<Head>
|
||||
<script
|
||||
type="application/ld+json"
|
||||
dangerouslySetInnerHTML={{ __html: JSON.stringify(schema) }}
|
||||
/>
|
||||
</Head>
|
||||
{/* Page content */}
|
||||
</>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
### CMS / WordPress
|
||||
- Plugins (Yoast, Rank Math, Schema Pro)
|
||||
- Theme modifications
|
||||
- Custom fields to structured data
|
||||
|
||||
---
|
||||
|
||||
## Output Format
|
||||
|
||||
### Schema Implementation
|
||||
```json
|
||||
// Full JSON-LD code block
|
||||
{
|
||||
"@context": "https://schema.org",
|
||||
"@type": "...",
|
||||
// Complete markup
|
||||
}
|
||||
```
|
||||
|
||||
### Placement Instructions
|
||||
Where to add the code and how
|
||||
|
||||
### Testing Checklist
|
||||
- [ ] Validates in Rich Results Test
|
||||
- [ ] No errors or warnings
|
||||
- [ ] Matches page content
|
||||
- [ ] All required properties included
|
||||
|
||||
---
|
||||
|
||||
## Questions to Ask
|
||||
|
||||
If you need more context:
|
||||
1. What type of page is this?
|
||||
2. What rich results are you hoping to achieve?
|
||||
3. What data is available to populate the schema?
|
||||
4. Is there existing schema on the page?
|
||||
5. What's your tech stack for implementation?
|
||||
|
||||
---
|
||||
|
||||
## Related Skills
|
||||
|
||||
- **seo-audit**: For overall SEO including schema review
|
||||
- **programmatic-seo**: For templated schema at scale
|
||||
- **analytics-tracking**: For measuring rich result impact
|
||||
263
skills/scroll-experience/SKILL.md
Normal file
263
skills/scroll-experience/SKILL.md
Normal file
@@ -0,0 +1,263 @@
|
||||
---
|
||||
name: scroll-experience
|
||||
description: "Expert in building immersive scroll-driven experiences - parallax storytelling, scroll animations, interactive narratives, and cinematic web experiences. Like NY Times interactives, Apple product pages, and award-winning web experiences. Makes websites feel like experiences, not just pages. Use when: scroll animation, parallax, scroll storytelling, interactive story, cinematic website."
|
||||
source: vibeship-spawner-skills (Apache 2.0)
|
||||
---
|
||||
|
||||
# Scroll Experience
|
||||
|
||||
**Role**: Scroll Experience Architect
|
||||
|
||||
You see scrolling as a narrative device, not just navigation. You create
|
||||
moments of delight as users scroll. You know when to use subtle animations
|
||||
and when to go cinematic. You balance performance with visual impact. You
|
||||
make websites feel like movies you control with your thumb.
|
||||
|
||||
## Capabilities
|
||||
|
||||
- Scroll-driven animations
|
||||
- Parallax storytelling
|
||||
- Interactive narratives
|
||||
- Cinematic web experiences
|
||||
- Scroll-triggered reveals
|
||||
- Progress indicators
|
||||
- Sticky sections
|
||||
- Scroll snapping
|
||||
|
||||
## Patterns
|
||||
|
||||
### Scroll Animation Stack
|
||||
|
||||
Tools and techniques for scroll animations
|
||||
|
||||
**When to use**: When planning scroll-driven experiences
|
||||
|
||||
```python
|
||||
## Scroll Animation Stack
|
||||
|
||||
### Library Options
|
||||
| Library | Best For | Learning Curve |
|
||||
|---------|----------|----------------|
|
||||
| GSAP ScrollTrigger | Complex animations | Medium |
|
||||
| Framer Motion | React projects | Low |
|
||||
| Locomotive Scroll | Smooth scroll + parallax | Medium |
|
||||
| Lenis | Smooth scroll only | Low |
|
||||
| CSS scroll-timeline | Simple, native | Low |
|
||||
|
||||
### GSAP ScrollTrigger Setup
|
||||
```javascript
|
||||
import { gsap } from 'gsap';
|
||||
import { ScrollTrigger } from 'gsap/ScrollTrigger';
|
||||
|
||||
gsap.registerPlugin(ScrollTrigger);
|
||||
|
||||
// Basic scroll animation
|
||||
gsap.to('.element', {
|
||||
scrollTrigger: {
|
||||
trigger: '.element',
|
||||
start: 'top center',
|
||||
end: 'bottom center',
|
||||
scrub: true, // Links animation to scroll position
|
||||
},
|
||||
y: -100,
|
||||
opacity: 1,
|
||||
});
|
||||
```
|
||||
|
||||
### Framer Motion Scroll
|
||||
```jsx
|
||||
import { motion, useScroll, useTransform } from 'framer-motion';
|
||||
|
||||
function ParallaxSection() {
|
||||
const { scrollYProgress } = useScroll();
|
||||
const y = useTransform(scrollYProgress, [0, 1], [0, -200]);
|
||||
|
||||
return (
|
||||
<motion.div style={{ y }}>
|
||||
Content moves with scroll
|
||||
</motion.div>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
### CSS Native (2024+)
|
||||
```css
|
||||
@keyframes reveal {
|
||||
from { opacity: 0; transform: translateY(50px); }
|
||||
to { opacity: 1; transform: translateY(0); }
|
||||
}
|
||||
|
||||
.animate-on-scroll {
|
||||
animation: reveal linear;
|
||||
animation-timeline: view();
|
||||
animation-range: entry 0% cover 40%;
|
||||
}
|
||||
```
|
||||
```
|
||||
|
||||
### Parallax Storytelling
|
||||
|
||||
Tell stories through scroll depth
|
||||
|
||||
**When to use**: When creating narrative experiences
|
||||
|
||||
```javascript
|
||||
## Parallax Storytelling
|
||||
|
||||
### Layer Speeds
|
||||
| Layer | Speed | Effect |
|
||||
|-------|-------|--------|
|
||||
| Background | 0.2x | Far away, slow |
|
||||
| Midground | 0.5x | Middle depth |
|
||||
| Foreground | 1.0x | Normal scroll |
|
||||
| Content | 1.0x | Readable |
|
||||
| Floating elements | 1.2x | Pop forward |
|
||||
|
||||
### Creating Depth
|
||||
```javascript
|
||||
// GSAP parallax layers
|
||||
gsap.to('.background', {
|
||||
scrollTrigger: {
|
||||
scrub: true
|
||||
},
|
||||
y: '-20%', // Moves slower
|
||||
});
|
||||
|
||||
gsap.to('.foreground', {
|
||||
scrollTrigger: {
|
||||
scrub: true
|
||||
},
|
||||
y: '-50%', // Moves faster
|
||||
});
|
||||
```
|
||||
|
||||
### Story Beats
|
||||
```
|
||||
Section 1: Hook (full viewport, striking visual)
|
||||
↓ scroll
|
||||
Section 2: Context (text + supporting visuals)
|
||||
↓ scroll
|
||||
Section 3: Journey (parallax storytelling)
|
||||
↓ scroll
|
||||
Section 4: Climax (dramatic reveal)
|
||||
↓ scroll
|
||||
Section 5: Resolution (CTA or conclusion)
|
||||
```
|
||||
|
||||
### Text Reveals
|
||||
- Fade in on scroll
|
||||
- Typewriter effect on trigger
|
||||
- Word-by-word highlight
|
||||
- Sticky text with changing visuals
|
||||
```
|
||||
|
||||
### Sticky Sections
|
||||
|
||||
Pin elements while scrolling through content
|
||||
|
||||
**When to use**: When content should stay visible during scroll
|
||||
|
||||
```javascript
|
||||
## Sticky Sections
|
||||
|
||||
### CSS Sticky
|
||||
```css
|
||||
.sticky-container {
|
||||
height: 300vh; /* Space for scrolling */
|
||||
}
|
||||
|
||||
.sticky-element {
|
||||
position: sticky;
|
||||
top: 0;
|
||||
height: 100vh;
|
||||
}
|
||||
```
|
||||
|
||||
### GSAP Pin
|
||||
```javascript
|
||||
gsap.to('.content', {
|
||||
scrollTrigger: {
|
||||
trigger: '.section',
|
||||
pin: true, // Pins the section
|
||||
start: 'top top',
|
||||
end: '+=1000', // Pin for 1000px of scroll
|
||||
scrub: true,
|
||||
},
|
||||
// Animate while pinned
|
||||
x: '-100vw',
|
||||
});
|
||||
```
|
||||
|
||||
### Horizontal Scroll Section
|
||||
```javascript
|
||||
const sections = gsap.utils.toArray('.panel');
|
||||
|
||||
gsap.to(sections, {
|
||||
xPercent: -100 * (sections.length - 1),
|
||||
ease: 'none',
|
||||
scrollTrigger: {
|
||||
trigger: '.horizontal-container',
|
||||
pin: true,
|
||||
scrub: 1,
|
||||
end: () => '+=' + document.querySelector('.horizontal-container').offsetWidth,
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
### Use Cases
|
||||
- Product feature walkthrough
|
||||
- Before/after comparisons
|
||||
- Step-by-step processes
|
||||
- Image galleries
|
||||
```
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
### ❌ Scroll Hijacking
|
||||
|
||||
**Why bad**: Users hate losing scroll control.
|
||||
Accessibility nightmare.
|
||||
Breaks back button expectations.
|
||||
Frustrating on mobile.
|
||||
|
||||
**Instead**: Enhance scroll, don't replace it.
|
||||
Keep natural scroll speed.
|
||||
Use scrub animations.
|
||||
Allow users to scroll normally.
|
||||
|
||||
### ❌ Animation Overload
|
||||
|
||||
**Why bad**: Distracting, not delightful.
|
||||
Performance tanks.
|
||||
Content becomes secondary.
|
||||
User fatigue.
|
||||
|
||||
**Instead**: Less is more.
|
||||
Animate key moments.
|
||||
Static content is okay.
|
||||
Guide attention, don't overwhelm.
|
||||
|
||||
### ❌ Desktop-Only Experience
|
||||
|
||||
**Why bad**: Mobile is majority of traffic.
|
||||
Touch scroll is different.
|
||||
Performance issues on phones.
|
||||
Unusable experience.
|
||||
|
||||
**Instead**: Mobile-first scroll design.
|
||||
Simpler effects on mobile.
|
||||
Test on real devices.
|
||||
Graceful degradation.
|
||||
|
||||
## ⚠️ Sharp Edges
|
||||
|
||||
| Issue | Severity | Solution |
|
||||
|-------|----------|----------|
|
||||
| Animations stutter during scroll | high | ## Fixing Scroll Jank |
|
||||
| Parallax breaks on mobile devices | high | ## Mobile-Safe Parallax |
|
||||
| Scroll experience is inaccessible | medium | ## Accessible Scroll Experiences |
|
||||
| Critical content hidden below animations | medium | ## Content-First Scroll Design |
|
||||
|
||||
## Related Skills
|
||||
|
||||
Works well with: `3d-web-experience`, `frontend`, `ui-design`, `landing-page-design`
|
||||
50
skills/segment-cdp/SKILL.md
Normal file
50
skills/segment-cdp/SKILL.md
Normal file
@@ -0,0 +1,50 @@
|
||||
---
|
||||
name: segment-cdp
|
||||
description: "Expert patterns for Segment Customer Data Platform including Analytics.js, server-side tracking, tracking plans with Protocols, identity resolution, destinations configuration, and data governance best practices. Use when: segment, analytics.js, customer data platform, cdp, tracking plan."
|
||||
source: vibeship-spawner-skills (Apache 2.0)
|
||||
---
|
||||
|
||||
# Segment CDP
|
||||
|
||||
## Patterns
|
||||
|
||||
### Analytics.js Browser Integration
|
||||
|
||||
Client-side tracking with Analytics.js. Include track, identify, page,
|
||||
and group calls. Anonymous ID persists until identify merges with user.
|
||||
|
||||
|
||||
### Server-Side Tracking with Node.js
|
||||
|
||||
High-performance server-side tracking using @segment/analytics-node.
|
||||
Non-blocking with internal batching. Essential for backend events,
|
||||
webhooks, and sensitive data.
|
||||
|
||||
|
||||
### Tracking Plan Design
|
||||
|
||||
Design event schemas using Object + Action naming convention.
|
||||
Define required properties, types, and validation rules.
|
||||
Connect to Protocols for enforcement.
|
||||
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
### ❌ Dynamic Event Names
|
||||
|
||||
### ❌ Tracking Properties as Events
|
||||
|
||||
### ❌ Missing Identify Before Track
|
||||
|
||||
## ⚠️ Sharp Edges
|
||||
|
||||
| Issue | Severity | Solution |
|
||||
|-------|----------|----------|
|
||||
| Issue | medium | See docs |
|
||||
| Issue | high | See docs |
|
||||
| Issue | medium | See docs |
|
||||
| Issue | high | See docs |
|
||||
| Issue | low | See docs |
|
||||
| Issue | medium | See docs |
|
||||
| Issue | medium | See docs |
|
||||
| Issue | high | See docs |
|
||||
384
skills/seo-audit/SKILL.md
Normal file
384
skills/seo-audit/SKILL.md
Normal file
@@ -0,0 +1,384 @@
|
||||
---
|
||||
name: seo-audit
|
||||
description: When the user wants to audit, review, or diagnose SEO issues on their site. Also use when the user mentions "SEO audit," "technical SEO," "why am I not ranking," "SEO issues," "on-page SEO," "meta tags review," or "SEO health check." For building pages at scale to target keywords, see programmatic-seo. For adding structured data, see schema-markup.
|
||||
---
|
||||
|
||||
# SEO Audit
|
||||
|
||||
You are an expert in search engine optimization. Your goal is to identify SEO issues and provide actionable recommendations to improve organic search performance.
|
||||
|
||||
## Initial Assessment
|
||||
|
||||
Before auditing, understand:
|
||||
|
||||
1. **Site Context**
|
||||
- What type of site? (SaaS, e-commerce, blog, etc.)
|
||||
- What's the primary business goal for SEO?
|
||||
- What keywords/topics are priorities?
|
||||
|
||||
2. **Current State**
|
||||
- Any known issues or concerns?
|
||||
- Current organic traffic level?
|
||||
- Recent changes or migrations?
|
||||
|
||||
3. **Scope**
|
||||
- Full site audit or specific pages?
|
||||
- Technical + on-page, or one focus area?
|
||||
- Access to Search Console / analytics?
|
||||
|
||||
---
|
||||
|
||||
## Audit Framework
|
||||
|
||||
### Priority Order
|
||||
1. **Crawlability & Indexation** (can Google find and index it?)
|
||||
2. **Technical Foundations** (is the site fast and functional?)
|
||||
3. **On-Page Optimization** (is content optimized?)
|
||||
4. **Content Quality** (does it deserve to rank?)
|
||||
5. **Authority & Links** (does it have credibility?)
|
||||
|
||||
---
|
||||
|
||||
## Technical SEO Audit
|
||||
|
||||
### Crawlability
|
||||
|
||||
**Robots.txt**
|
||||
- Check for unintentional blocks
|
||||
- Verify important pages allowed
|
||||
- Check sitemap reference
|
||||
|
||||
**XML Sitemap**
|
||||
- Exists and accessible
|
||||
- Submitted to Search Console
|
||||
- Contains only canonical, indexable URLs
|
||||
- Updated regularly
|
||||
- Proper formatting
|
||||
|
||||
**Site Architecture**
|
||||
- Important pages within 3 clicks of homepage
|
||||
- Logical hierarchy
|
||||
- Internal linking structure
|
||||
- No orphan pages
|
||||
|
||||
**Crawl Budget Issues** (for large sites)
|
||||
- Parameterized URLs under control
|
||||
- Faceted navigation handled properly
|
||||
- Infinite scroll with pagination fallback
|
||||
- Session IDs not in URLs
|
||||
|
||||
### Indexation
|
||||
|
||||
**Index Status**
|
||||
- site:domain.com check
|
||||
- Search Console coverage report
|
||||
- Compare indexed vs. expected
|
||||
|
||||
**Indexation Issues**
|
||||
- Noindex tags on important pages
|
||||
- Canonicals pointing wrong direction
|
||||
- Redirect chains/loops
|
||||
- Soft 404s
|
||||
- Duplicate content without canonicals
|
||||
|
||||
**Canonicalization**
|
||||
- All pages have canonical tags
|
||||
- Self-referencing canonicals on unique pages
|
||||
- HTTP → HTTPS canonicals
|
||||
- www vs. non-www consistency
|
||||
- Trailing slash consistency
|
||||
|
||||
### Site Speed & Core Web Vitals
|
||||
|
||||
**Core Web Vitals**
|
||||
- LCP (Largest Contentful Paint): < 2.5s
|
||||
- INP (Interaction to Next Paint): < 200ms
|
||||
- CLS (Cumulative Layout Shift): < 0.1
|
||||
|
||||
**Speed Factors**
|
||||
- Server response time (TTFB)
|
||||
- Image optimization
|
||||
- JavaScript execution
|
||||
- CSS delivery
|
||||
- Caching headers
|
||||
- CDN usage
|
||||
- Font loading
|
||||
|
||||
**Tools**
|
||||
- PageSpeed Insights
|
||||
- WebPageTest
|
||||
- Chrome DevTools
|
||||
- Search Console Core Web Vitals report
|
||||
|
||||
### Mobile-Friendliness
|
||||
|
||||
- Responsive design (not separate m. site)
|
||||
- Tap target sizes
|
||||
- Viewport configured
|
||||
- No horizontal scroll
|
||||
- Same content as desktop
|
||||
- Mobile-first indexing readiness
|
||||
|
||||
### Security & HTTPS
|
||||
|
||||
- HTTPS across entire site
|
||||
- Valid SSL certificate
|
||||
- No mixed content
|
||||
- HTTP → HTTPS redirects
|
||||
- HSTS header (bonus)
|
||||
|
||||
### URL Structure
|
||||
|
||||
- Readable, descriptive URLs
|
||||
- Keywords in URLs where natural
|
||||
- Consistent structure
|
||||
- No unnecessary parameters
|
||||
- Lowercase and hyphen-separated
|
||||
|
||||
---
|
||||
|
||||
## On-Page SEO Audit
|
||||
|
||||
### Title Tags
|
||||
|
||||
**Check for:**
|
||||
- Unique titles for each page
|
||||
- Primary keyword near beginning
|
||||
- 50-60 characters (visible in SERP)
|
||||
- Compelling and click-worthy
|
||||
- Brand name placement (end, usually)
|
||||
|
||||
**Common issues:**
|
||||
- Duplicate titles
|
||||
- Too long (truncated)
|
||||
- Too short (wasted opportunity)
|
||||
- Keyword stuffing
|
||||
- Missing entirely
|
||||
|
||||
### Meta Descriptions
|
||||
|
||||
**Check for:**
|
||||
- Unique descriptions per page
|
||||
- 150-160 characters
|
||||
- Includes primary keyword
|
||||
- Clear value proposition
|
||||
- Call to action
|
||||
|
||||
**Common issues:**
|
||||
- Duplicate descriptions
|
||||
- Auto-generated garbage
|
||||
- Too long/short
|
||||
- No compelling reason to click
|
||||
|
||||
### Heading Structure
|
||||
|
||||
**Check for:**
|
||||
- One H1 per page
|
||||
- H1 contains primary keyword
|
||||
- Logical hierarchy (H1 → H2 → H3)
|
||||
- Headings describe content
|
||||
- Not just for styling
|
||||
|
||||
**Common issues:**
|
||||
- Multiple H1s
|
||||
- Skip levels (H1 → H3)
|
||||
- Headings used for styling only
|
||||
- No H1 on page
|
||||
|
||||
### Content Optimization
|
||||
|
||||
**Primary Page Content**
|
||||
- Keyword in first 100 words
|
||||
- Related keywords naturally used
|
||||
- Sufficient depth/length for topic
|
||||
- Answers search intent
|
||||
- Better than competitors
|
||||
|
||||
**Thin Content Issues**
|
||||
- Pages with little unique content
|
||||
- Tag/category pages with no value
|
||||
- Doorway pages
|
||||
- Duplicate or near-duplicate content
|
||||
|
||||
### Image Optimization
|
||||
|
||||
**Check for:**
|
||||
- Descriptive file names
|
||||
- Alt text on all images
|
||||
- Alt text describes image
|
||||
- Compressed file sizes
|
||||
- Modern formats (WebP)
|
||||
- Lazy loading implemented
|
||||
- Responsive images
|
||||
|
||||
### Internal Linking
|
||||
|
||||
**Check for:**
|
||||
- Important pages well-linked
|
||||
- Descriptive anchor text
|
||||
- Logical link relationships
|
||||
- No broken internal links
|
||||
- Reasonable link count per page
|
||||
|
||||
**Common issues:**
|
||||
- Orphan pages (no internal links)
|
||||
- Over-optimized anchor text
|
||||
- Important pages buried
|
||||
- Excessive footer/sidebar links
|
||||
|
||||
### Keyword Targeting
|
||||
|
||||
**Per Page**
|
||||
- Clear primary keyword target
|
||||
- Title, H1, URL aligned
|
||||
- Content satisfies search intent
|
||||
- Not competing with other pages (cannibalization)
|
||||
|
||||
**Site-Wide**
|
||||
- Keyword mapping document
|
||||
- No major gaps in coverage
|
||||
- No keyword cannibalization
|
||||
- Logical topical clusters
|
||||
|
||||
---
|
||||
|
||||
## Content Quality Assessment
|
||||
|
||||
### E-E-A-T Signals
|
||||
|
||||
**Experience**
|
||||
- First-hand experience demonstrated
|
||||
- Original insights/data
|
||||
- Real examples and case studies
|
||||
|
||||
**Expertise**
|
||||
- Author credentials visible
|
||||
- Accurate, detailed information
|
||||
- Properly sourced claims
|
||||
|
||||
**Authoritativeness**
|
||||
- Recognized in the space
|
||||
- Cited by others
|
||||
- Industry credentials
|
||||
|
||||
**Trustworthiness**
|
||||
- Accurate information
|
||||
- Transparent about business
|
||||
- Contact information available
|
||||
- Privacy policy, terms
|
||||
- Secure site (HTTPS)
|
||||
|
||||
### Content Depth
|
||||
|
||||
- Comprehensive coverage of topic
|
||||
- Answers follow-up questions
|
||||
- Better than top-ranking competitors
|
||||
- Updated and current
|
||||
|
||||
### User Engagement Signals
|
||||
|
||||
- Time on page
|
||||
- Bounce rate in context
|
||||
- Pages per session
|
||||
- Return visits
|
||||
|
||||
---
|
||||
|
||||
## Common Issues by Site Type
|
||||
|
||||
### SaaS/Product Sites
|
||||
- Product pages lack content depth
|
||||
- Blog not integrated with product pages
|
||||
- Missing comparison/alternative pages
|
||||
- Feature pages thin on content
|
||||
- No glossary/educational content
|
||||
|
||||
### E-commerce
|
||||
- Thin category pages
|
||||
- Duplicate product descriptions
|
||||
- Missing product schema
|
||||
- Faceted navigation creating duplicates
|
||||
- Out-of-stock pages mishandled
|
||||
|
||||
### Content/Blog Sites
|
||||
- Outdated content not refreshed
|
||||
- Keyword cannibalization
|
||||
- No topical clustering
|
||||
- Poor internal linking
|
||||
- Missing author pages
|
||||
|
||||
### Local Business
|
||||
- Inconsistent NAP
|
||||
- Missing local schema
|
||||
- No Google Business Profile optimization
|
||||
- Missing location pages
|
||||
- No local content
|
||||
|
||||
---
|
||||
|
||||
## Output Format
|
||||
|
||||
### Audit Report Structure
|
||||
|
||||
**Executive Summary**
|
||||
- Overall health assessment
|
||||
- Top 3-5 priority issues
|
||||
- Quick wins identified
|
||||
|
||||
**Technical SEO Findings**
|
||||
For each issue:
|
||||
- **Issue**: What's wrong
|
||||
- **Impact**: SEO impact (High/Medium/Low)
|
||||
- **Evidence**: How you found it
|
||||
- **Fix**: Specific recommendation
|
||||
- **Priority**: 1-5 or High/Medium/Low
|
||||
|
||||
**On-Page SEO Findings**
|
||||
Same format as above
|
||||
|
||||
**Content Findings**
|
||||
Same format as above
|
||||
|
||||
**Prioritized Action Plan**
|
||||
1. Critical fixes (blocking indexation/ranking)
|
||||
2. High-impact improvements
|
||||
3. Quick wins (easy, immediate benefit)
|
||||
4. Long-term recommendations
|
||||
|
||||
---
|
||||
|
||||
## Tools Referenced
|
||||
|
||||
**Free Tools**
|
||||
- Google Search Console (essential)
|
||||
- Google PageSpeed Insights
|
||||
- Bing Webmaster Tools
|
||||
- Rich Results Test
|
||||
- Mobile-Friendly Test
|
||||
- Schema Validator
|
||||
|
||||
**Paid Tools** (if available)
|
||||
- Screaming Frog
|
||||
- Ahrefs / Semrush
|
||||
- Sitebulb
|
||||
- ContentKing
|
||||
|
||||
---
|
||||
|
||||
## Questions to Ask
|
||||
|
||||
If you need more context:
|
||||
1. What pages/keywords matter most?
|
||||
2. Do you have Search Console access?
|
||||
3. Any recent changes or migrations?
|
||||
4. Who are your top organic competitors?
|
||||
5. What's your current organic traffic baseline?
|
||||
|
||||
---
|
||||
|
||||
## Related Skills
|
||||
|
||||
- **programmatic-seo**: For building SEO pages at scale
|
||||
- **schema-markup**: For implementing structured data
|
||||
- **page-cro**: For optimizing pages for conversion (not just ranking)
|
||||
- **analytics-tracking**: For measuring SEO performance
|
||||
42
skills/shopify-apps/SKILL.md
Normal file
42
skills/shopify-apps/SKILL.md
Normal file
@@ -0,0 +1,42 @@
|
||||
---
|
||||
name: shopify-apps
|
||||
description: "Expert patterns for Shopify app development including Remix/React Router apps, embedded apps with App Bridge, webhook handling, GraphQL Admin API, Polaris components, billing, and app extensions. Use when: shopify app, shopify, embedded app, polaris, app bridge."
|
||||
source: vibeship-spawner-skills (Apache 2.0)
|
||||
---
|
||||
|
||||
# Shopify Apps
|
||||
|
||||
## Patterns
|
||||
|
||||
### React Router App Setup
|
||||
|
||||
Modern Shopify app template with React Router
|
||||
|
||||
### Embedded App with App Bridge
|
||||
|
||||
Render app embedded in Shopify Admin
|
||||
|
||||
### Webhook Handling
|
||||
|
||||
Secure webhook processing with HMAC verification
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
### ❌ REST API for New Apps
|
||||
|
||||
### ❌ Webhook Processing Before Response
|
||||
|
||||
### ❌ Polling Instead of Webhooks
|
||||
|
||||
## ⚠️ Sharp Edges
|
||||
|
||||
| Issue | Severity | Solution |
|
||||
|-------|----------|----------|
|
||||
| Issue | high | ## Respond immediately, process asynchronously |
|
||||
| Issue | high | ## Check rate limit headers |
|
||||
| Issue | high | ## Request protected customer data access |
|
||||
| Issue | medium | ## Use TOML only (recommended) |
|
||||
| Issue | medium | ## Handle both URL formats |
|
||||
| Issue | high | ## Use GraphQL for all new code |
|
||||
| Issue | high | ## Use latest App Bridge via script tag |
|
||||
| Issue | high | ## Implement all GDPR handlers |
|
||||
60
skills/shopify-development/README.md
Normal file
60
skills/shopify-development/README.md
Normal file
@@ -0,0 +1,60 @@
|
||||
# Shopify Development Skill
|
||||
|
||||
Comprehensive skill for building on Shopify platform: apps, extensions, themes, and API integrations.
|
||||
|
||||
## Features
|
||||
|
||||
- **App Development** - OAuth authentication, GraphQL Admin API, webhooks, billing integration
|
||||
- **UI Extensions** - Checkout, Admin, POS customizations with Polaris components
|
||||
- **Theme Development** - Liquid templating, sections, snippets
|
||||
- **Shopify Functions** - Custom discounts, payment, delivery rules
|
||||
|
||||
## Structure
|
||||
|
||||
```
|
||||
shopify-development/
|
||||
├── SKILL.md # Main skill file (AI-optimized)
|
||||
├── README.md # This file
|
||||
├── references/
|
||||
│ ├── app-development.md # OAuth, API, webhooks, billing
|
||||
│ ├── extensions.md # UI extensions, Functions
|
||||
│ └── themes.md # Liquid, theme architecture
|
||||
└── scripts/
|
||||
├── shopify_init.py # Interactive project scaffolding
|
||||
├── shopify_graphql.py # GraphQL utilities & templates
|
||||
└── tests/ # Unit tests
|
||||
```
|
||||
|
||||
## Validated GraphQL
|
||||
|
||||
All GraphQL queries and mutations in this skill have been validated against Shopify Admin API 2026-01 schema using the official Shopify MCP.
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Install Shopify CLI
|
||||
npm install -g @shopify/cli@latest
|
||||
|
||||
# Create new app
|
||||
shopify app init
|
||||
|
||||
# Start development
|
||||
shopify app dev
|
||||
```
|
||||
|
||||
## Usage Triggers
|
||||
|
||||
This skill activates when the user mentions:
|
||||
|
||||
- "shopify app", "shopify extension", "shopify theme"
|
||||
- "checkout extension", "admin extension", "POS extension"
|
||||
- "liquid template", "polaris", "shopify graphql"
|
||||
- "shopify webhook", "shopify billing", "metafields"
|
||||
|
||||
## API Version
|
||||
|
||||
Current: **2026-01** (Quarterly releases with 12-month support)
|
||||
|
||||
## License
|
||||
|
||||
MIT
|
||||
366
skills/shopify-development/SKILL.md
Normal file
366
skills/shopify-development/SKILL.md
Normal file
@@ -0,0 +1,366 @@
|
||||
---
|
||||
name: shopify-development
|
||||
description: |
|
||||
Build Shopify apps, extensions, themes using GraphQL Admin API, Shopify CLI, Polaris UI, and Liquid.
|
||||
TRIGGER: "shopify", "shopify app", "checkout extension", "admin extension", "POS extension",
|
||||
"shopify theme", "liquid template", "polaris", "shopify graphql", "shopify webhook",
|
||||
"shopify billing", "app subscription", "metafields", "shopify functions"
|
||||
---
|
||||
|
||||
# Shopify Development Skill
|
||||
|
||||
Use this skill when the user asks about:
|
||||
|
||||
- Building Shopify apps or extensions
|
||||
- Creating checkout/admin/POS UI customizations
|
||||
- Developing themes with Liquid templating
|
||||
- Integrating with Shopify GraphQL or REST APIs
|
||||
- Implementing webhooks or billing
|
||||
- Working with metafields or Shopify Functions
|
||||
|
||||
---
|
||||
|
||||
## ROUTING: What to Build
|
||||
|
||||
**IF user wants to integrate external services OR build merchant tools OR charge for features:**
|
||||
→ Build an **App** (see `references/app-development.md`)
|
||||
|
||||
**IF user wants to customize checkout OR add admin UI OR create POS actions OR implement discount rules:**
|
||||
→ Build an **Extension** (see `references/extensions.md`)
|
||||
|
||||
**IF user wants to customize storefront design OR modify product/collection pages:**
|
||||
→ Build a **Theme** (see `references/themes.md`)
|
||||
|
||||
**IF user needs both backend logic AND storefront UI:**
|
||||
→ Build **App + Theme Extension** combination
|
||||
|
||||
---
|
||||
|
||||
## Shopify CLI Commands
|
||||
|
||||
Install CLI:
|
||||
|
||||
```bash
|
||||
npm install -g @shopify/cli@latest
|
||||
```
|
||||
|
||||
Create and run app:
|
||||
|
||||
```bash
|
||||
shopify app init # Create new app
|
||||
shopify app dev # Start dev server with tunnel
|
||||
shopify app deploy # Build and upload to Shopify
|
||||
```
|
||||
|
||||
Generate extension:
|
||||
|
||||
```bash
|
||||
shopify app generate extension --type checkout_ui_extension
|
||||
shopify app generate extension --type admin_action
|
||||
shopify app generate extension --type admin_block
|
||||
shopify app generate extension --type pos_ui_extension
|
||||
shopify app generate extension --type function
|
||||
```
|
||||
|
||||
Theme development:
|
||||
|
||||
```bash
|
||||
shopify theme init # Create new theme
|
||||
shopify theme dev # Start local preview at localhost:9292
|
||||
shopify theme pull --live # Pull live theme
|
||||
shopify theme push --development # Push to dev theme
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Access Scopes
|
||||
|
||||
Configure in `shopify.app.toml`:
|
||||
|
||||
```toml
|
||||
[access_scopes]
|
||||
scopes = "read_products,write_products,read_orders,write_orders,read_customers"
|
||||
```
|
||||
|
||||
Common scopes:
|
||||
|
||||
- `read_products`, `write_products` - Product catalog access
|
||||
- `read_orders`, `write_orders` - Order management
|
||||
- `read_customers`, `write_customers` - Customer data
|
||||
- `read_inventory`, `write_inventory` - Stock levels
|
||||
- `read_fulfillments`, `write_fulfillments` - Order fulfillment
|
||||
|
||||
---
|
||||
|
||||
## GraphQL Patterns (Validated against API 2026-01)
|
||||
|
||||
### Query Products
|
||||
|
||||
```graphql
|
||||
query GetProducts($first: Int!, $query: String) {
|
||||
products(first: $first, query: $query) {
|
||||
edges {
|
||||
node {
|
||||
id
|
||||
title
|
||||
handle
|
||||
status
|
||||
variants(first: 5) {
|
||||
edges {
|
||||
node {
|
||||
id
|
||||
price
|
||||
inventoryQuantity
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
pageInfo {
|
||||
hasNextPage
|
||||
endCursor
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Query Orders
|
||||
|
||||
```graphql
|
||||
query GetOrders($first: Int!) {
|
||||
orders(first: $first) {
|
||||
edges {
|
||||
node {
|
||||
id
|
||||
name
|
||||
createdAt
|
||||
displayFinancialStatus
|
||||
totalPriceSet {
|
||||
shopMoney {
|
||||
amount
|
||||
currencyCode
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Set Metafields
|
||||
|
||||
```graphql
|
||||
mutation SetMetafields($metafields: [MetafieldsSetInput!]!) {
|
||||
metafieldsSet(metafields: $metafields) {
|
||||
metafields {
|
||||
id
|
||||
namespace
|
||||
key
|
||||
value
|
||||
}
|
||||
userErrors {
|
||||
field
|
||||
message
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Variables example:
|
||||
|
||||
```json
|
||||
{
|
||||
"metafields": [
|
||||
{
|
||||
"ownerId": "gid://shopify/Product/123",
|
||||
"namespace": "custom",
|
||||
"key": "care_instructions",
|
||||
"value": "Handle with care",
|
||||
"type": "single_line_text_field"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Checkout Extension Example
|
||||
|
||||
```tsx
|
||||
import {
|
||||
reactExtension,
|
||||
BlockStack,
|
||||
TextField,
|
||||
Checkbox,
|
||||
useApplyAttributeChange,
|
||||
} from "@shopify/ui-extensions-react/checkout";
|
||||
|
||||
export default reactExtension("purchase.checkout.block.render", () => (
|
||||
<GiftMessage />
|
||||
));
|
||||
|
||||
function GiftMessage() {
|
||||
const [isGift, setIsGift] = useState(false);
|
||||
const [message, setMessage] = useState("");
|
||||
const applyAttributeChange = useApplyAttributeChange();
|
||||
|
||||
useEffect(() => {
|
||||
if (isGift && message) {
|
||||
applyAttributeChange({
|
||||
type: "updateAttribute",
|
||||
key: "gift_message",
|
||||
value: message,
|
||||
});
|
||||
}
|
||||
}, [isGift, message]);
|
||||
|
||||
return (
|
||||
<BlockStack spacing="loose">
|
||||
<Checkbox checked={isGift} onChange={setIsGift}>
|
||||
This is a gift
|
||||
</Checkbox>
|
||||
{isGift && (
|
||||
<TextField
|
||||
label="Gift Message"
|
||||
value={message}
|
||||
onChange={setMessage}
|
||||
multiline={3}
|
||||
/>
|
||||
)}
|
||||
</BlockStack>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Liquid Template Example
|
||||
|
||||
```liquid
|
||||
{% comment %} Product Card Snippet {% endcomment %}
|
||||
<div class="product-card">
|
||||
<a href="{{ product.url }}">
|
||||
{% if product.featured_image %}
|
||||
<img
|
||||
src="{{ product.featured_image | img_url: 'medium' }}"
|
||||
alt="{{ product.title | escape }}"
|
||||
loading="lazy"
|
||||
>
|
||||
{% endif %}
|
||||
<h3>{{ product.title }}</h3>
|
||||
<p class="price">{{ product.price | money }}</p>
|
||||
{% if product.compare_at_price > product.price %}
|
||||
<p class="sale-badge">Sale</p>
|
||||
{% endif %}
|
||||
</a>
|
||||
</div>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Webhook Configuration
|
||||
|
||||
In `shopify.app.toml`:
|
||||
|
||||
```toml
|
||||
[webhooks]
|
||||
api_version = "2026-01"
|
||||
|
||||
[[webhooks.subscriptions]]
|
||||
topics = ["orders/create", "orders/updated"]
|
||||
uri = "/webhooks/orders"
|
||||
|
||||
[[webhooks.subscriptions]]
|
||||
topics = ["products/update"]
|
||||
uri = "/webhooks/products"
|
||||
|
||||
# GDPR mandatory webhooks (required for app approval)
|
||||
[webhooks.privacy_compliance]
|
||||
customer_data_request_url = "/webhooks/gdpr/data-request"
|
||||
customer_deletion_url = "/webhooks/gdpr/customer-deletion"
|
||||
shop_deletion_url = "/webhooks/gdpr/shop-deletion"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
### API Usage
|
||||
|
||||
- Use GraphQL over REST for new development
|
||||
- Request only fields you need (reduces query cost)
|
||||
- Implement cursor-based pagination with `pageInfo.endCursor`
|
||||
- Use bulk operations for processing more than 250 items
|
||||
- Handle rate limits with exponential backoff
|
||||
|
||||
### Security
|
||||
|
||||
- Store API credentials in environment variables
|
||||
- Always verify webhook HMAC signatures before processing
|
||||
- Validate OAuth state parameter to prevent CSRF
|
||||
- Request minimal access scopes
|
||||
- Use session tokens for embedded apps
|
||||
|
||||
### Performance
|
||||
|
||||
- Cache API responses when data doesn't change frequently
|
||||
- Use lazy loading in extensions
|
||||
- Optimize images in themes using `img_url` filter
|
||||
- Monitor GraphQL query costs via response headers
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**IF you see rate limit errors:**
|
||||
→ Implement exponential backoff retry logic
|
||||
→ Switch to bulk operations for large datasets
|
||||
→ Monitor `X-Shopify-Shop-Api-Call-Limit` header
|
||||
|
||||
**IF authentication fails:**
|
||||
→ Verify the access token is still valid
|
||||
→ Check that all required scopes were granted
|
||||
→ Ensure OAuth flow completed successfully
|
||||
|
||||
**IF extension is not appearing:**
|
||||
→ Verify the extension target is correct
|
||||
→ Check that extension is published via `shopify app deploy`
|
||||
→ Confirm the app is installed on the test store
|
||||
|
||||
**IF webhook is not receiving events:**
|
||||
→ Verify the webhook URL is publicly accessible
|
||||
→ Check HMAC signature validation logic
|
||||
→ Review webhook logs in Partner Dashboard
|
||||
|
||||
**IF GraphQL query fails:**
|
||||
→ Validate query against schema (use GraphiQL explorer)
|
||||
→ Check for deprecated fields in error message
|
||||
→ Verify you have required access scopes
|
||||
|
||||
---
|
||||
|
||||
## Reference Files
|
||||
|
||||
For detailed implementation guides, read these files:
|
||||
|
||||
- `references/app-development.md` - OAuth authentication flow, GraphQL mutations for products/orders/billing, webhook handlers, billing API integration
|
||||
- `references/extensions.md` - Checkout UI components, Admin UI extensions, POS extensions, Shopify Functions for discounts/payment/delivery
|
||||
- `references/themes.md` - Liquid syntax reference, theme directory structure, sections and snippets, common patterns
|
||||
|
||||
---
|
||||
|
||||
## Scripts
|
||||
|
||||
- `scripts/shopify_init.py` - Interactive project scaffolding. Run: `python scripts/shopify_init.py`
|
||||
- `scripts/shopify_graphql.py` - GraphQL utilities with query templates, pagination, rate limiting. Import: `from shopify_graphql import ShopifyGraphQL`
|
||||
|
||||
---
|
||||
|
||||
## Official Documentation Links
|
||||
|
||||
- Shopify Developer Docs: https://shopify.dev/docs
|
||||
- GraphQL Admin API Reference: https://shopify.dev/docs/api/admin-graphql
|
||||
- Shopify CLI Reference: https://shopify.dev/docs/api/shopify-cli
|
||||
- Polaris Design System: https://polaris.shopify.com
|
||||
|
||||
API Version: 2026-01 (quarterly releases, 12-month deprecation window)
|
||||
578
skills/shopify-development/references/app-development.md
Normal file
578
skills/shopify-development/references/app-development.md
Normal file
@@ -0,0 +1,578 @@
|
||||
# App Development Reference
|
||||
|
||||
Guide for building Shopify apps with OAuth, GraphQL/REST APIs, webhooks, and billing.
|
||||
|
||||
## OAuth Authentication
|
||||
|
||||
### OAuth 2.0 Flow
|
||||
|
||||
**1. Redirect to Authorization URL:**
|
||||
|
||||
```
|
||||
https://{shop}.myshopify.com/admin/oauth/authorize?
|
||||
client_id={api_key}&
|
||||
scope={scopes}&
|
||||
redirect_uri={redirect_uri}&
|
||||
state={nonce}
|
||||
```
|
||||
|
||||
**2. Handle Callback:**
|
||||
|
||||
```javascript
|
||||
app.get("/auth/callback", async (req, res) => {
|
||||
const { code, shop, state } = req.query;
|
||||
|
||||
// Verify state to prevent CSRF
|
||||
if (state !== storedState) {
|
||||
return res.status(403).send("Invalid state");
|
||||
}
|
||||
|
||||
// Exchange code for access token
|
||||
const accessToken = await exchangeCodeForToken(shop, code);
|
||||
|
||||
// Store token securely
|
||||
await storeAccessToken(shop, accessToken);
|
||||
|
||||
res.redirect(`https://${shop}/admin/apps/${appHandle}`);
|
||||
});
|
||||
```
|
||||
|
||||
**3. Exchange Code for Token:**
|
||||
|
||||
```javascript
|
||||
async function exchangeCodeForToken(shop, code) {
|
||||
const response = await fetch(`https://${shop}/admin/oauth/access_token`, {
|
||||
method: "POST",
|
||||
headers: { "Content-Type": "application/json" },
|
||||
body: JSON.stringify({
|
||||
client_id: process.env.SHOPIFY_API_KEY,
|
||||
client_secret: process.env.SHOPIFY_API_SECRET,
|
||||
code,
|
||||
}),
|
||||
});
|
||||
|
||||
const { access_token } = await response.json();
|
||||
return access_token;
|
||||
}
|
||||
```
|
||||
|
||||
### Access Scopes
|
||||
|
||||
**Common Scopes:**
|
||||
|
||||
- `read_products`, `write_products` - Product catalog
|
||||
- `read_orders`, `write_orders` - Order management
|
||||
- `read_customers`, `write_customers` - Customer data
|
||||
- `read_inventory`, `write_inventory` - Stock levels
|
||||
- `read_fulfillments`, `write_fulfillments` - Order fulfillment
|
||||
- `read_shipping`, `write_shipping` - Shipping rates
|
||||
- `read_analytics` - Store analytics
|
||||
- `read_checkouts`, `write_checkouts` - Checkout data
|
||||
|
||||
Full list: https://shopify.dev/api/usage/access-scopes
|
||||
|
||||
### Session Tokens (Embedded Apps)
|
||||
|
||||
For embedded apps using App Bridge:
|
||||
|
||||
```javascript
|
||||
import { getSessionToken } from '@shopify/app-bridge/utilities';
|
||||
|
||||
async function authenticatedFetch(url, options = {}) {
|
||||
const app = createApp({ ... });
|
||||
const token = await getSessionToken(app);
|
||||
|
||||
return fetch(url, {
|
||||
...options,
|
||||
headers: {
|
||||
...options.headers,
|
||||
'Authorization': `Bearer ${token}`
|
||||
}
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
## GraphQL Admin API
|
||||
|
||||
### Making Requests
|
||||
|
||||
```javascript
|
||||
async function graphqlRequest(shop, accessToken, query, variables = {}) {
|
||||
const response = await fetch(
|
||||
`https://${shop}/admin/api/2026-01/graphql.json`,
|
||||
{
|
||||
method: "POST",
|
||||
headers: {
|
||||
"X-Shopify-Access-Token": accessToken,
|
||||
"Content-Type": "application/json",
|
||||
},
|
||||
body: JSON.stringify({ query, variables }),
|
||||
},
|
||||
);
|
||||
|
||||
const data = await response.json();
|
||||
|
||||
if (data.errors) {
|
||||
throw new Error(`GraphQL errors: ${JSON.stringify(data.errors)}`);
|
||||
}
|
||||
|
||||
return data.data;
|
||||
}
|
||||
```
|
||||
|
||||
### Product Operations
|
||||
|
||||
**Create Product:**
|
||||
|
||||
```graphql
|
||||
mutation CreateProduct($input: ProductInput!) {
|
||||
productCreate(input: $input) {
|
||||
product {
|
||||
id
|
||||
title
|
||||
handle
|
||||
}
|
||||
userErrors {
|
||||
field
|
||||
message
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Variables:
|
||||
|
||||
```json
|
||||
{
|
||||
"input": {
|
||||
"title": "New Product",
|
||||
"productType": "Apparel",
|
||||
"vendor": "Brand",
|
||||
"status": "ACTIVE",
|
||||
"variants": [
|
||||
{ "price": "29.99", "sku": "SKU-001", "inventoryQuantity": 100 }
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Update Product:**
|
||||
|
||||
```graphql
|
||||
mutation UpdateProduct($input: ProductInput!) {
|
||||
productUpdate(input: $input) {
|
||||
product {
|
||||
id
|
||||
title
|
||||
}
|
||||
userErrors {
|
||||
field
|
||||
message
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Query Products:**
|
||||
|
||||
```graphql
|
||||
query GetProducts($first: Int!, $query: String) {
|
||||
products(first: $first, query: $query) {
|
||||
edges {
|
||||
node {
|
||||
id
|
||||
title
|
||||
status
|
||||
variants(first: 5) {
|
||||
edges {
|
||||
node {
|
||||
id
|
||||
price
|
||||
inventoryQuantity
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
pageInfo {
|
||||
hasNextPage
|
||||
endCursor
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Order Operations
|
||||
|
||||
**Query Orders:**
|
||||
|
||||
```graphql
|
||||
query GetOrders($first: Int!) {
|
||||
orders(first: $first) {
|
||||
edges {
|
||||
node {
|
||||
id
|
||||
name
|
||||
createdAt
|
||||
displayFinancialStatus
|
||||
totalPriceSet {
|
||||
shopMoney {
|
||||
amount
|
||||
currencyCode
|
||||
}
|
||||
}
|
||||
customer {
|
||||
email
|
||||
firstName
|
||||
lastName
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Fulfill Order:**
|
||||
|
||||
```graphql
|
||||
mutation FulfillOrder($fulfillment: FulfillmentInput!) {
|
||||
fulfillmentCreate(fulfillment: $fulfillment) {
|
||||
fulfillment {
|
||||
id
|
||||
status
|
||||
trackingInfo {
|
||||
number
|
||||
url
|
||||
}
|
||||
}
|
||||
userErrors {
|
||||
field
|
||||
message
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Webhooks
|
||||
|
||||
### Configuration
|
||||
|
||||
In `shopify.app.toml`:
|
||||
|
||||
```toml
|
||||
[webhooks]
|
||||
api_version = "2025-01"
|
||||
|
||||
[[webhooks.subscriptions]]
|
||||
topics = ["orders/create"]
|
||||
uri = "/webhooks/orders/create"
|
||||
|
||||
[[webhooks.subscriptions]]
|
||||
topics = ["products/update"]
|
||||
uri = "/webhooks/products/update"
|
||||
|
||||
[[webhooks.subscriptions]]
|
||||
topics = ["app/uninstalled"]
|
||||
uri = "/webhooks/app/uninstalled"
|
||||
|
||||
# GDPR mandatory webhooks
|
||||
[webhooks.privacy_compliance]
|
||||
customer_data_request_url = "/webhooks/gdpr/data-request"
|
||||
customer_deletion_url = "/webhooks/gdpr/customer-deletion"
|
||||
shop_deletion_url = "/webhooks/gdpr/shop-deletion"
|
||||
```
|
||||
|
||||
### Webhook Handler
|
||||
|
||||
```javascript
|
||||
import crypto from "crypto";
|
||||
|
||||
function verifyWebhook(req) {
|
||||
const hmac = req.headers["x-shopify-hmac-sha256"];
|
||||
const body = req.rawBody; // Raw body buffer
|
||||
|
||||
const hash = crypto
|
||||
.createHmac("sha256", process.env.SHOPIFY_API_SECRET)
|
||||
.update(body, "utf8")
|
||||
.digest("base64");
|
||||
|
||||
return hmac === hash;
|
||||
}
|
||||
|
||||
app.post("/webhooks/orders/create", async (req, res) => {
|
||||
if (!verifyWebhook(req)) {
|
||||
return res.status(401).send("Unauthorized");
|
||||
}
|
||||
|
||||
const order = req.body;
|
||||
console.log("New order:", order.id, order.name);
|
||||
|
||||
// Process order...
|
||||
|
||||
res.status(200).send("OK");
|
||||
});
|
||||
```
|
||||
|
||||
### Common Webhook Topics
|
||||
|
||||
**Orders:**
|
||||
|
||||
- `orders/create`, `orders/updated`, `orders/delete`
|
||||
- `orders/paid`, `orders/cancelled`, `orders/fulfilled`
|
||||
|
||||
**Products:**
|
||||
|
||||
- `products/create`, `products/update`, `products/delete`
|
||||
|
||||
**Customers:**
|
||||
|
||||
- `customers/create`, `customers/update`, `customers/delete`
|
||||
|
||||
**Inventory:**
|
||||
|
||||
- `inventory_levels/update`
|
||||
|
||||
**App:**
|
||||
|
||||
- `app/uninstalled` (critical for cleanup)
|
||||
|
||||
## Billing Integration
|
||||
|
||||
### App Charges
|
||||
|
||||
**One-time Charge:**
|
||||
|
||||
```graphql
|
||||
mutation CreateCharge($input: AppPurchaseOneTimeInput!) {
|
||||
appPurchaseOneTimeCreate(input: $input) {
|
||||
appPurchaseOneTime {
|
||||
id
|
||||
name
|
||||
price {
|
||||
amount
|
||||
}
|
||||
status
|
||||
confirmationUrl
|
||||
}
|
||||
userErrors {
|
||||
field
|
||||
message
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Variables:
|
||||
|
||||
```json
|
||||
{
|
||||
"input": {
|
||||
"name": "Premium Feature",
|
||||
"price": { "amount": 49.99, "currencyCode": "USD" },
|
||||
"returnUrl": "https://your-app.com/billing/callback"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Recurring Charge (Subscription):**
|
||||
|
||||
```graphql
|
||||
mutation CreateSubscription(
|
||||
$name: String!
|
||||
$returnUrl: URL!
|
||||
$lineItems: [AppSubscriptionLineItemInput!]!
|
||||
$trialDays: Int
|
||||
) {
|
||||
appSubscriptionCreate(
|
||||
name: $name
|
||||
returnUrl: $returnUrl
|
||||
lineItems: $lineItems
|
||||
trialDays: $trialDays
|
||||
) {
|
||||
appSubscription {
|
||||
id
|
||||
name
|
||||
status
|
||||
}
|
||||
confirmationUrl
|
||||
userErrors {
|
||||
field
|
||||
message
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Variables:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "Monthly Subscription",
|
||||
"returnUrl": "https://your-app.com/billing/callback",
|
||||
"trialDays": 7,
|
||||
"lineItems": [
|
||||
{
|
||||
"plan": {
|
||||
"appRecurringPricingDetails": {
|
||||
"price": { "amount": 29.99, "currencyCode": "USD" },
|
||||
"interval": "EVERY_30_DAYS"
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Usage-based Billing:**
|
||||
|
||||
```graphql
|
||||
mutation CreateUsageCharge(
|
||||
$subscriptionLineItemId: ID!
|
||||
$price: MoneyInput!
|
||||
$description: String!
|
||||
) {
|
||||
appUsageRecordCreate(
|
||||
subscriptionLineItemId: $subscriptionLineItemId
|
||||
price: $price
|
||||
description: $description
|
||||
) {
|
||||
appUsageRecord {
|
||||
id
|
||||
price {
|
||||
amount
|
||||
currencyCode
|
||||
}
|
||||
description
|
||||
}
|
||||
userErrors {
|
||||
field
|
||||
message
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Variables:
|
||||
|
||||
```json
|
||||
{
|
||||
"subscriptionLineItemId": "gid://shopify/AppSubscriptionLineItem/123",
|
||||
"price": { "amount": "5.00", "currencyCode": "USD" },
|
||||
"description": "100 API calls used"
|
||||
}
|
||||
```
|
||||
|
||||
## Metafields
|
||||
|
||||
### Create/Update Metafields
|
||||
|
||||
```graphql
|
||||
mutation SetMetafields($metafields: [MetafieldsSetInput!]!) {
|
||||
metafieldsSet(metafields: $metafields) {
|
||||
metafields {
|
||||
id
|
||||
namespace
|
||||
key
|
||||
value
|
||||
}
|
||||
userErrors {
|
||||
field
|
||||
message
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Variables:
|
||||
|
||||
```json
|
||||
{
|
||||
"metafields": [
|
||||
{
|
||||
"ownerId": "gid://shopify/Product/123",
|
||||
"namespace": "custom",
|
||||
"key": "instructions",
|
||||
"value": "Handle with care",
|
||||
"type": "single_line_text_field"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Metafield Types:**
|
||||
|
||||
- `single_line_text_field`, `multi_line_text_field`
|
||||
- `number_integer`, `number_decimal`
|
||||
- `date`, `date_time`
|
||||
- `url`, `json`
|
||||
- `file_reference`, `product_reference`
|
||||
|
||||
## Rate Limiting
|
||||
|
||||
### GraphQL Cost-Based Limits
|
||||
|
||||
**Limits:**
|
||||
|
||||
- Available points: 2000
|
||||
- Restore rate: 100 points/second
|
||||
- Max query cost: 2000
|
||||
|
||||
**Check Cost:**
|
||||
|
||||
```javascript
|
||||
const response = await graphqlRequest(shop, token, query);
|
||||
const cost = response.extensions?.cost;
|
||||
|
||||
console.log(
|
||||
`Cost: ${cost.actualQueryCost}/${cost.throttleStatus.maximumAvailable}`,
|
||||
);
|
||||
```
|
||||
|
||||
**Handle Throttling:**
|
||||
|
||||
```javascript
|
||||
async function graphqlWithRetry(shop, token, query, retries = 3) {
|
||||
for (let i = 0; i < retries; i++) {
|
||||
try {
|
||||
return await graphqlRequest(shop, token, query);
|
||||
} catch (error) {
|
||||
if (error.message.includes("Throttled") && i < retries - 1) {
|
||||
await sleep(Math.pow(2, i) * 1000); // Exponential backoff
|
||||
continue;
|
||||
}
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
**Security:**
|
||||
|
||||
- Store credentials in environment variables
|
||||
- Verify webhook HMAC signatures
|
||||
- Validate OAuth state parameter
|
||||
- Use HTTPS for all endpoints
|
||||
- Implement rate limiting on your endpoints
|
||||
|
||||
**Performance:**
|
||||
|
||||
- Cache access tokens securely
|
||||
- Use bulk operations for large datasets
|
||||
- Implement pagination for queries
|
||||
- Monitor GraphQL query costs
|
||||
|
||||
**Reliability:**
|
||||
|
||||
- Implement exponential backoff for retries
|
||||
- Handle webhook delivery failures
|
||||
- Log errors for debugging
|
||||
- Monitor app health metrics
|
||||
|
||||
**Compliance:**
|
||||
|
||||
- Implement GDPR webhooks (mandatory)
|
||||
- Handle customer data deletion requests
|
||||
- Provide data export functionality
|
||||
- Follow data retention policies
|
||||
555
skills/shopify-development/references/extensions.md
Normal file
555
skills/shopify-development/references/extensions.md
Normal file
@@ -0,0 +1,555 @@
|
||||
# Extensions Reference
|
||||
|
||||
Guide for building UI extensions and Shopify Functions.
|
||||
|
||||
## Checkout UI Extensions
|
||||
|
||||
Customize checkout and thank-you pages with native-rendered components.
|
||||
|
||||
### Extension Points
|
||||
|
||||
**Block Targets (Merchant-Configurable):**
|
||||
|
||||
- `purchase.checkout.block.render` - Main checkout
|
||||
- `purchase.thank-you.block.render` - Thank you page
|
||||
|
||||
**Static Targets (Fixed Position):**
|
||||
|
||||
- `purchase.checkout.header.render-after`
|
||||
- `purchase.checkout.contact.render-before`
|
||||
- `purchase.checkout.shipping-option-list.render-after`
|
||||
- `purchase.checkout.payment-method-list.render-after`
|
||||
- `purchase.checkout.footer.render-before`
|
||||
|
||||
### Setup
|
||||
|
||||
```bash
|
||||
shopify app generate extension --type checkout_ui_extension
|
||||
```
|
||||
|
||||
Configuration (`shopify.extension.toml`):
|
||||
|
||||
```toml
|
||||
api_version = "2026-01"
|
||||
name = "gift-message"
|
||||
type = "ui_extension"
|
||||
|
||||
[[extensions.targeting]]
|
||||
target = "purchase.checkout.block.render"
|
||||
|
||||
[capabilities]
|
||||
network_access = true
|
||||
api_access = true
|
||||
```
|
||||
|
||||
### Basic Example
|
||||
|
||||
```javascript
|
||||
import {
|
||||
reactExtension,
|
||||
BlockStack,
|
||||
TextField,
|
||||
Checkbox,
|
||||
useApi,
|
||||
} from "@shopify/ui-extensions-react/checkout";
|
||||
|
||||
export default reactExtension("purchase.checkout.block.render", () => (
|
||||
<Extension />
|
||||
));
|
||||
|
||||
function Extension() {
|
||||
const [message, setMessage] = useState("");
|
||||
const [isGift, setIsGift] = useState(false);
|
||||
const { applyAttributeChange } = useApi();
|
||||
|
||||
useEffect(() => {
|
||||
if (isGift) {
|
||||
applyAttributeChange({
|
||||
type: "updateAttribute",
|
||||
key: "gift_message",
|
||||
value: message,
|
||||
});
|
||||
}
|
||||
}, [message, isGift]);
|
||||
|
||||
return (
|
||||
<BlockStack spacing="loose">
|
||||
<Checkbox checked={isGift} onChange={setIsGift}>
|
||||
This is a gift
|
||||
</Checkbox>
|
||||
{isGift && (
|
||||
<TextField
|
||||
label="Gift Message"
|
||||
value={message}
|
||||
onChange={setMessage}
|
||||
multiline={3}
|
||||
/>
|
||||
)}
|
||||
</BlockStack>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
### Common Hooks
|
||||
|
||||
**useApi:**
|
||||
|
||||
```javascript
|
||||
const { extensionPoint, shop, storefront, i18n, sessionToken } = useApi();
|
||||
```
|
||||
|
||||
**useCartLines:**
|
||||
|
||||
```javascript
|
||||
const lines = useCartLines();
|
||||
lines.forEach((line) => {
|
||||
console.log(line.merchandise.product.title, line.quantity);
|
||||
});
|
||||
```
|
||||
|
||||
**useShippingAddress:**
|
||||
|
||||
```javascript
|
||||
const address = useShippingAddress();
|
||||
console.log(address.city, address.countryCode);
|
||||
```
|
||||
|
||||
**useApplyCartLinesChange:**
|
||||
|
||||
```javascript
|
||||
const applyChange = useApplyCartLinesChange();
|
||||
|
||||
async function addItem() {
|
||||
await applyChange({
|
||||
type: "addCartLine",
|
||||
merchandiseId: "gid://shopify/ProductVariant/123",
|
||||
quantity: 1,
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
### Core Components
|
||||
|
||||
**Layout:**
|
||||
|
||||
- `BlockStack` - Vertical stacking
|
||||
- `InlineStack` - Horizontal layout
|
||||
- `Grid`, `GridItem` - Grid layout
|
||||
- `View` - Container
|
||||
- `Divider` - Separator
|
||||
|
||||
**Input:**
|
||||
|
||||
- `TextField` - Text input
|
||||
- `Checkbox` - Boolean
|
||||
- `Select` - Dropdown
|
||||
- `DatePicker` - Date selection
|
||||
- `Form` - Form wrapper
|
||||
|
||||
**Display:**
|
||||
|
||||
- `Text`, `Heading` - Typography
|
||||
- `Banner` - Messages
|
||||
- `Badge` - Status
|
||||
- `Image` - Images
|
||||
- `Link` - Hyperlinks
|
||||
- `List`, `ListItem` - Lists
|
||||
|
||||
**Interactive:**
|
||||
|
||||
- `Button` - Actions
|
||||
- `Modal` - Overlays
|
||||
- `Pressable` - Click areas
|
||||
|
||||
## Admin UI Extensions
|
||||
|
||||
Extend Shopify admin interface.
|
||||
|
||||
### Admin Action
|
||||
|
||||
Custom actions on resource pages.
|
||||
|
||||
```bash
|
||||
shopify app generate extension --type admin_action
|
||||
```
|
||||
|
||||
```javascript
|
||||
import {
|
||||
reactExtension,
|
||||
AdminAction,
|
||||
Button,
|
||||
} from "@shopify/ui-extensions-react/admin";
|
||||
|
||||
export default reactExtension("admin.product-details.action.render", () => (
|
||||
<Extension />
|
||||
));
|
||||
|
||||
function Extension() {
|
||||
const { data } = useData();
|
||||
|
||||
async function handleExport() {
|
||||
const response = await fetch("/api/export", {
|
||||
method: "POST",
|
||||
body: JSON.stringify({ productId: data.product.id }),
|
||||
});
|
||||
console.log("Exported:", await response.json());
|
||||
}
|
||||
|
||||
return (
|
||||
<AdminAction
|
||||
title="Export Product"
|
||||
primaryAction={<Button onPress={handleExport}>Export</Button>}
|
||||
/>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
**Targets:**
|
||||
|
||||
- `admin.product-details.action.render`
|
||||
- `admin.order-details.action.render`
|
||||
- `admin.customer-details.action.render`
|
||||
|
||||
### Admin Block
|
||||
|
||||
Embedded content in admin pages.
|
||||
|
||||
```javascript
|
||||
import {
|
||||
reactExtension,
|
||||
BlockStack,
|
||||
Text,
|
||||
Badge,
|
||||
} from "@shopify/ui-extensions-react/admin";
|
||||
|
||||
export default reactExtension("admin.product-details.block.render", () => (
|
||||
<Extension />
|
||||
));
|
||||
|
||||
function Extension() {
|
||||
const { data } = useData();
|
||||
const [analytics, setAnalytics] = useState(null);
|
||||
|
||||
useEffect(() => {
|
||||
fetchAnalytics(data.product.id).then(setAnalytics);
|
||||
}, []);
|
||||
|
||||
return (
|
||||
<BlockStack>
|
||||
<Text variant="headingMd">Product Analytics</Text>
|
||||
<Text>Views: {analytics?.views || 0}</Text>
|
||||
<Text>Conversions: {analytics?.conversions || 0}</Text>
|
||||
<Badge tone={analytics?.trending ? "success" : "info"}>
|
||||
{analytics?.trending ? "Trending" : "Normal"}
|
||||
</Badge>
|
||||
</BlockStack>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
**Targets:**
|
||||
|
||||
- `admin.product-details.block.render`
|
||||
- `admin.order-details.block.render`
|
||||
- `admin.customer-details.block.render`
|
||||
|
||||
## POS UI Extensions
|
||||
|
||||
Customize Point of Sale experience.
|
||||
|
||||
### Smart Grid Tile
|
||||
|
||||
Quick access action on POS home screen.
|
||||
|
||||
```javascript
|
||||
import {
|
||||
reactExtension,
|
||||
SmartGridTile,
|
||||
} from "@shopify/ui-extensions-react/pos";
|
||||
|
||||
export default reactExtension("pos.home.tile.render", () => <Extension />);
|
||||
|
||||
function Extension() {
|
||||
function handlePress() {
|
||||
// Navigate to custom workflow
|
||||
}
|
||||
|
||||
return (
|
||||
<SmartGridTile
|
||||
title="Gift Cards"
|
||||
subtitle="Manage gift cards"
|
||||
onPress={handlePress}
|
||||
/>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
### POS Modal
|
||||
|
||||
Full-screen workflow.
|
||||
|
||||
```javascript
|
||||
import {
|
||||
reactExtension,
|
||||
Screen,
|
||||
BlockStack,
|
||||
Button,
|
||||
TextField,
|
||||
} from "@shopify/ui-extensions-react/pos";
|
||||
|
||||
export default reactExtension("pos.home.modal.render", () => <Extension />);
|
||||
|
||||
function Extension() {
|
||||
const { navigation } = useApi();
|
||||
const [amount, setAmount] = useState("");
|
||||
|
||||
function handleIssue() {
|
||||
// Issue gift card
|
||||
navigation.pop();
|
||||
}
|
||||
|
||||
return (
|
||||
<Screen name="Gift Card" title="Issue Gift Card">
|
||||
<BlockStack>
|
||||
<TextField label="Amount" value={amount} onChange={setAmount} />
|
||||
<TextField label="Recipient Email" />
|
||||
<Button onPress={handleIssue}>Issue</Button>
|
||||
</BlockStack>
|
||||
</Screen>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
## Customer Account Extensions
|
||||
|
||||
Customize customer account pages.
|
||||
|
||||
### Order Status Extension
|
||||
|
||||
```javascript
|
||||
import {
|
||||
reactExtension,
|
||||
BlockStack,
|
||||
Text,
|
||||
Button,
|
||||
} from "@shopify/ui-extensions-react/customer-account";
|
||||
|
||||
export default reactExtension(
|
||||
"customer-account.order-status.block.render",
|
||||
() => <Extension />,
|
||||
);
|
||||
|
||||
function Extension() {
|
||||
const { order } = useApi();
|
||||
|
||||
function handleReturn() {
|
||||
// Initiate return
|
||||
}
|
||||
|
||||
return (
|
||||
<BlockStack>
|
||||
<Text variant="headingMd">Need to return?</Text>
|
||||
<Text>Start return for order {order.name}</Text>
|
||||
<Button onPress={handleReturn}>Start Return</Button>
|
||||
</BlockStack>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
**Targets:**
|
||||
|
||||
- `customer-account.order-status.block.render`
|
||||
- `customer-account.order-index.block.render`
|
||||
- `customer-account.profile.block.render`
|
||||
|
||||
## Shopify Functions
|
||||
|
||||
Serverless backend customization.
|
||||
|
||||
### Function Types
|
||||
|
||||
**Discounts:**
|
||||
|
||||
- `order_discount` - Order-level discounts
|
||||
- `product_discount` - Product-specific discounts
|
||||
- `shipping_discount` - Shipping discounts
|
||||
|
||||
**Payment Customization:**
|
||||
|
||||
- Hide/rename/reorder payment methods
|
||||
|
||||
**Delivery Customization:**
|
||||
|
||||
- Custom shipping options
|
||||
- Delivery rules
|
||||
|
||||
**Validation:**
|
||||
|
||||
- Cart validation rules
|
||||
- Checkout validation
|
||||
|
||||
### Create Function
|
||||
|
||||
```bash
|
||||
shopify app generate extension --type function
|
||||
```
|
||||
|
||||
### Order Discount Function
|
||||
|
||||
```javascript
|
||||
// input.graphql
|
||||
query Input {
|
||||
cart {
|
||||
lines {
|
||||
quantity
|
||||
merchandise {
|
||||
... on ProductVariant {
|
||||
product {
|
||||
hasTag(tag: "bulk-discount")
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// function.js
|
||||
export default function orderDiscount(input) {
|
||||
const targets = input.cart.lines
|
||||
.filter(line => line.merchandise.product.hasTag)
|
||||
.map(line => ({
|
||||
productVariant: { id: line.merchandise.id }
|
||||
}));
|
||||
|
||||
if (targets.length === 0) {
|
||||
return { discounts: [] };
|
||||
}
|
||||
|
||||
return {
|
||||
discounts: [{
|
||||
targets,
|
||||
value: {
|
||||
percentage: {
|
||||
value: 10 // 10% discount
|
||||
}
|
||||
}
|
||||
}]
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
### Payment Customization Function
|
||||
|
||||
```javascript
|
||||
export default function paymentCustomization(input) {
|
||||
const hidePaymentMethods = input.cart.lines.some(
|
||||
(line) => line.merchandise.product.hasTag,
|
||||
);
|
||||
|
||||
if (!hidePaymentMethods) {
|
||||
return { operations: [] };
|
||||
}
|
||||
|
||||
return {
|
||||
operations: [
|
||||
{
|
||||
hide: {
|
||||
paymentMethodId: "gid://shopify/PaymentMethod/123",
|
||||
},
|
||||
},
|
||||
],
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
### Validation Function
|
||||
|
||||
```javascript
|
||||
export default function cartValidation(input) {
|
||||
const errors = [];
|
||||
|
||||
// Max 5 items per cart
|
||||
if (input.cart.lines.length > 5) {
|
||||
errors.push({
|
||||
localizedMessage: "Maximum 5 items allowed per order",
|
||||
target: "cart",
|
||||
});
|
||||
}
|
||||
|
||||
// Min $50 for wholesale
|
||||
const isWholesale = input.cart.lines.some(
|
||||
(line) => line.merchandise.product.hasTag,
|
||||
);
|
||||
|
||||
if (isWholesale && input.cart.cost.totalAmount.amount < 50) {
|
||||
errors.push({
|
||||
localizedMessage: "Wholesale orders require $50 minimum",
|
||||
target: "cart",
|
||||
});
|
||||
}
|
||||
|
||||
return { errors };
|
||||
}
|
||||
```
|
||||
|
||||
## Network Requests
|
||||
|
||||
Extensions can call external APIs.
|
||||
|
||||
```javascript
|
||||
import { useApi } from "@shopify/ui-extensions-react/checkout";
|
||||
|
||||
function Extension() {
|
||||
const { sessionToken } = useApi();
|
||||
|
||||
async function fetchData() {
|
||||
const token = await sessionToken.get();
|
||||
|
||||
const response = await fetch("https://your-app.com/api/data", {
|
||||
headers: {
|
||||
Authorization: `Bearer ${token}`,
|
||||
"Content-Type": "application/json",
|
||||
},
|
||||
});
|
||||
|
||||
return await response.json();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
**Performance:**
|
||||
|
||||
- Lazy load data
|
||||
- Memoize expensive computations
|
||||
- Use loading states
|
||||
- Minimize re-renders
|
||||
|
||||
**UX:**
|
||||
|
||||
- Provide clear error messages
|
||||
- Show loading indicators
|
||||
- Validate inputs
|
||||
- Support keyboard navigation
|
||||
|
||||
**Security:**
|
||||
|
||||
- Verify session tokens on backend
|
||||
- Sanitize user input
|
||||
- Use HTTPS for all requests
|
||||
- Don't expose sensitive data
|
||||
|
||||
**Testing:**
|
||||
|
||||
- Test on development stores
|
||||
- Verify mobile/desktop
|
||||
- Check accessibility
|
||||
- Test edge cases
|
||||
|
||||
## Resources
|
||||
|
||||
- Checkout Extensions: https://shopify.dev/docs/api/checkout-extensions
|
||||
- Admin Extensions: https://shopify.dev/docs/apps/admin/extensions
|
||||
- Functions: https://shopify.dev/docs/apps/functions
|
||||
- Components: https://shopify.dev/docs/api/checkout-ui-extensions/components
|
||||
498
skills/shopify-development/references/themes.md
Normal file
498
skills/shopify-development/references/themes.md
Normal file
@@ -0,0 +1,498 @@
|
||||
# Themes Reference
|
||||
|
||||
Guide for developing Shopify themes with Liquid templating.
|
||||
|
||||
## Liquid Templating
|
||||
|
||||
### Syntax Basics
|
||||
|
||||
**Objects (Output):**
|
||||
```liquid
|
||||
{{ product.title }}
|
||||
{{ product.price | money }}
|
||||
{{ customer.email }}
|
||||
```
|
||||
|
||||
**Tags (Logic):**
|
||||
```liquid
|
||||
{% if product.available %}
|
||||
<button>Add to Cart</button>
|
||||
{% else %}
|
||||
<p>Sold Out</p>
|
||||
{% endif %}
|
||||
|
||||
{% for product in collection.products %}
|
||||
{{ product.title }}
|
||||
{% endfor %}
|
||||
|
||||
{% case product.type %}
|
||||
{% when 'Clothing' %}
|
||||
<span>Apparel</span>
|
||||
{% when 'Shoes' %}
|
||||
<span>Footwear</span>
|
||||
{% else %}
|
||||
<span>Other</span>
|
||||
{% endcase %}
|
||||
```
|
||||
|
||||
**Filters (Transform):**
|
||||
```liquid
|
||||
{{ product.title | upcase }}
|
||||
{{ product.price | money }}
|
||||
{{ product.description | strip_html | truncate: 100 }}
|
||||
{{ product.image | img_url: 'medium' }}
|
||||
{{ 'now' | date: '%B %d, %Y' }}
|
||||
```
|
||||
|
||||
### Common Objects
|
||||
|
||||
**Product:**
|
||||
```liquid
|
||||
{{ product.id }}
|
||||
{{ product.title }}
|
||||
{{ product.handle }}
|
||||
{{ product.description }}
|
||||
{{ product.price }}
|
||||
{{ product.compare_at_price }}
|
||||
{{ product.available }}
|
||||
{{ product.type }}
|
||||
{{ product.vendor }}
|
||||
{{ product.tags }}
|
||||
{{ product.images }}
|
||||
{{ product.variants }}
|
||||
{{ product.featured_image }}
|
||||
{{ product.url }}
|
||||
```
|
||||
|
||||
**Collection:**
|
||||
```liquid
|
||||
{{ collection.title }}
|
||||
{{ collection.handle }}
|
||||
{{ collection.description }}
|
||||
{{ collection.products }}
|
||||
{{ collection.products_count }}
|
||||
{{ collection.image }}
|
||||
{{ collection.url }}
|
||||
```
|
||||
|
||||
**Cart:**
|
||||
```liquid
|
||||
{{ cart.item_count }}
|
||||
{{ cart.total_price }}
|
||||
{{ cart.items }}
|
||||
{{ cart.note }}
|
||||
{{ cart.attributes }}
|
||||
```
|
||||
|
||||
**Customer:**
|
||||
```liquid
|
||||
{{ customer.email }}
|
||||
{{ customer.first_name }}
|
||||
{{ customer.last_name }}
|
||||
{{ customer.orders_count }}
|
||||
{{ customer.total_spent }}
|
||||
{{ customer.addresses }}
|
||||
{{ customer.default_address }}
|
||||
```
|
||||
|
||||
**Shop:**
|
||||
```liquid
|
||||
{{ shop.name }}
|
||||
{{ shop.email }}
|
||||
{{ shop.domain }}
|
||||
{{ shop.currency }}
|
||||
{{ shop.money_format }}
|
||||
{{ shop.enabled_payment_types }}
|
||||
```
|
||||
|
||||
### Common Filters
|
||||
|
||||
**String:**
|
||||
- `upcase`, `downcase`, `capitalize`
|
||||
- `strip_html`, `strip_newlines`
|
||||
- `truncate: 100`, `truncatewords: 20`
|
||||
- `replace: 'old', 'new'`
|
||||
|
||||
**Number:**
|
||||
- `money` - Format currency
|
||||
- `round`, `ceil`, `floor`
|
||||
- `times`, `divided_by`, `plus`, `minus`
|
||||
|
||||
**Array:**
|
||||
- `join: ', '`
|
||||
- `first`, `last`
|
||||
- `size`
|
||||
- `map: 'property'`
|
||||
- `where: 'property', 'value'`
|
||||
|
||||
**URL:**
|
||||
- `img_url: 'size'` - Image URL
|
||||
- `url_for_type`, `url_for_vendor`
|
||||
- `link_to`, `link_to_type`
|
||||
|
||||
**Date:**
|
||||
- `date: '%B %d, %Y'`
|
||||
|
||||
## Theme Architecture
|
||||
|
||||
### Directory Structure
|
||||
|
||||
```
|
||||
theme/
|
||||
├── assets/ # CSS, JS, images
|
||||
├── config/ # Theme settings
|
||||
│ ├── settings_schema.json
|
||||
│ └── settings_data.json
|
||||
├── layout/ # Base templates
|
||||
│ └── theme.liquid
|
||||
├── locales/ # Translations
|
||||
│ └── en.default.json
|
||||
├── sections/ # Reusable blocks
|
||||
│ ├── header.liquid
|
||||
│ ├── footer.liquid
|
||||
│ └── product-grid.liquid
|
||||
├── snippets/ # Small components
|
||||
│ ├── product-card.liquid
|
||||
│ └── icon.liquid
|
||||
└── templates/ # Page templates
|
||||
├── index.json
|
||||
├── product.json
|
||||
├── collection.json
|
||||
└── cart.liquid
|
||||
```
|
||||
|
||||
### Layout
|
||||
|
||||
Base template wrapping all pages (`layout/theme.liquid`):
|
||||
|
||||
```liquid
|
||||
<!DOCTYPE html>
|
||||
<html lang="{{ request.locale.iso_code }}">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<meta name="viewport" content="width=device-width,initial-scale=1">
|
||||
<title>{{ page_title }}</title>
|
||||
|
||||
{{ content_for_header }}
|
||||
|
||||
<link rel="stylesheet" href="{{ 'theme.css' | asset_url }}">
|
||||
</head>
|
||||
<body>
|
||||
{% section 'header' %}
|
||||
|
||||
<main>
|
||||
{{ content_for_layout }}
|
||||
</main>
|
||||
|
||||
{% section 'footer' %}
|
||||
|
||||
<script src="{{ 'theme.js' | asset_url }}"></script>
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
|
||||
### Templates
|
||||
|
||||
Page-specific structures (`templates/product.json`):
|
||||
|
||||
```json
|
||||
{
|
||||
"sections": {
|
||||
"main": {
|
||||
"type": "product-template",
|
||||
"settings": {
|
||||
"show_vendor": true,
|
||||
"show_quantity_selector": true
|
||||
}
|
||||
},
|
||||
"recommendations": {
|
||||
"type": "product-recommendations"
|
||||
}
|
||||
},
|
||||
"order": ["main", "recommendations"]
|
||||
}
|
||||
```
|
||||
|
||||
Legacy format (`templates/product.liquid`):
|
||||
```liquid
|
||||
<div class="product">
|
||||
<div class="product-images">
|
||||
<img src="{{ product.featured_image | img_url: 'large' }}" alt="{{ product.title }}">
|
||||
</div>
|
||||
|
||||
<div class="product-details">
|
||||
<h1>{{ product.title }}</h1>
|
||||
<p class="price">{{ product.price | money }}</p>
|
||||
|
||||
{% form 'product', product %}
|
||||
<select name="id">
|
||||
{% for variant in product.variants %}
|
||||
<option value="{{ variant.id }}">{{ variant.title }} - {{ variant.price | money }}</option>
|
||||
{% endfor %}
|
||||
</select>
|
||||
|
||||
<button type="submit">Add to Cart</button>
|
||||
{% endform %}
|
||||
</div>
|
||||
</div>
|
||||
```
|
||||
|
||||
### Sections
|
||||
|
||||
Reusable content blocks (`sections/product-grid.liquid`):
|
||||
|
||||
```liquid
|
||||
<div class="product-grid">
|
||||
{% for product in section.settings.collection.products %}
|
||||
<div class="product-card">
|
||||
<a href="{{ product.url }}">
|
||||
<img src="{{ product.featured_image | img_url: 'medium' }}" alt="{{ product.title }}">
|
||||
<h3>{{ product.title }}</h3>
|
||||
<p>{{ product.price | money }}</p>
|
||||
</a>
|
||||
</div>
|
||||
{% endfor %}
|
||||
</div>
|
||||
|
||||
{% schema %}
|
||||
{
|
||||
"name": "Product Grid",
|
||||
"settings": [
|
||||
{
|
||||
"type": "collection",
|
||||
"id": "collection",
|
||||
"label": "Collection"
|
||||
},
|
||||
{
|
||||
"type": "range",
|
||||
"id": "products_per_row",
|
||||
"min": 2,
|
||||
"max": 5,
|
||||
"step": 1,
|
||||
"default": 4,
|
||||
"label": "Products per row"
|
||||
}
|
||||
],
|
||||
"presets": [
|
||||
{
|
||||
"name": "Product Grid"
|
||||
}
|
||||
]
|
||||
}
|
||||
{% endschema %}
|
||||
```
|
||||
|
||||
### Snippets
|
||||
|
||||
Small reusable components (`snippets/product-card.liquid`):
|
||||
|
||||
```liquid
|
||||
<div class="product-card">
|
||||
<a href="{{ product.url }}">
|
||||
{% if product.featured_image %}
|
||||
<img src="{{ product.featured_image | img_url: 'medium' }}" alt="{{ product.title }}">
|
||||
{% endif %}
|
||||
<h3>{{ product.title }}</h3>
|
||||
<p class="price">{{ product.price | money }}</p>
|
||||
{% if product.compare_at_price > product.price %}
|
||||
<p class="sale-price">{{ product.compare_at_price | money }}</p>
|
||||
{% endif %}
|
||||
</a>
|
||||
</div>
|
||||
```
|
||||
|
||||
Include snippet:
|
||||
```liquid
|
||||
{% render 'product-card', product: product %}
|
||||
```
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### Setup
|
||||
|
||||
```bash
|
||||
# Initialize new theme
|
||||
shopify theme init
|
||||
|
||||
# Choose Dawn (reference theme) or blank
|
||||
```
|
||||
|
||||
### Local Development
|
||||
|
||||
```bash
|
||||
# Start local server
|
||||
shopify theme dev
|
||||
|
||||
# Preview at http://localhost:9292
|
||||
# Changes auto-sync to development theme
|
||||
```
|
||||
|
||||
### Pull Theme
|
||||
|
||||
```bash
|
||||
# Pull live theme
|
||||
shopify theme pull --live
|
||||
|
||||
# Pull specific theme
|
||||
shopify theme pull --theme=123456789
|
||||
|
||||
# Pull only templates
|
||||
shopify theme pull --only=templates
|
||||
```
|
||||
|
||||
### Push Theme
|
||||
|
||||
```bash
|
||||
# Push to development theme
|
||||
shopify theme push --development
|
||||
|
||||
# Create new unpublished theme
|
||||
shopify theme push --unpublished
|
||||
|
||||
# Push specific files
|
||||
shopify theme push --only=sections,snippets
|
||||
```
|
||||
|
||||
### Theme Check
|
||||
|
||||
Lint theme code:
|
||||
```bash
|
||||
shopify theme check
|
||||
shopify theme check --auto-correct
|
||||
```
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Product Form with Variants
|
||||
|
||||
```liquid
|
||||
{% form 'product', product %}
|
||||
{% unless product.has_only_default_variant %}
|
||||
{% for option in product.options_with_values %}
|
||||
<div class="product-option">
|
||||
<label>{{ option.name }}</label>
|
||||
<select name="options[{{ option.name }}]">
|
||||
{% for value in option.values %}
|
||||
<option value="{{ value }}">{{ value }}</option>
|
||||
{% endfor %}
|
||||
</select>
|
||||
</div>
|
||||
{% endfor %}
|
||||
{% endunless %}
|
||||
|
||||
<input type="hidden" name="id" value="{{ product.selected_or_first_available_variant.id }}">
|
||||
<input type="number" name="quantity" value="1" min="1">
|
||||
|
||||
<button type="submit" {% unless product.available %}disabled{% endunless %}>
|
||||
{% if product.available %}Add to Cart{% else %}Sold Out{% endif %}
|
||||
</button>
|
||||
{% endform %}
|
||||
```
|
||||
|
||||
### Pagination
|
||||
|
||||
```liquid
|
||||
{% paginate collection.products by 12 %}
|
||||
{% for product in collection.products %}
|
||||
{% render 'product-card', product: product %}
|
||||
{% endfor %}
|
||||
|
||||
{% if paginate.pages > 1 %}
|
||||
<div class="pagination">
|
||||
{% if paginate.previous %}
|
||||
<a href="{{ paginate.previous.url }}">Previous</a>
|
||||
{% endif %}
|
||||
|
||||
{% for part in paginate.parts %}
|
||||
{% if part.is_link %}
|
||||
<a href="{{ part.url }}">{{ part.title }}</a>
|
||||
{% else %}
|
||||
<span class="current">{{ part.title }}</span>
|
||||
{% endif %}
|
||||
{% endfor %}
|
||||
|
||||
{% if paginate.next %}
|
||||
<a href="{{ paginate.next.url }}">Next</a>
|
||||
{% endif %}
|
||||
</div>
|
||||
{% endif %}
|
||||
{% endpaginate %}
|
||||
```
|
||||
|
||||
### Cart AJAX
|
||||
|
||||
```javascript
|
||||
// Add to cart
|
||||
fetch('/cart/add.js', {
|
||||
method: 'POST',
|
||||
headers: { 'Content-Type': 'application/json' },
|
||||
body: JSON.stringify({
|
||||
id: variantId,
|
||||
quantity: 1
|
||||
})
|
||||
})
|
||||
.then(res => res.json())
|
||||
.then(item => console.log('Added:', item));
|
||||
|
||||
// Get cart
|
||||
fetch('/cart.js')
|
||||
.then(res => res.json())
|
||||
.then(cart => console.log('Cart:', cart));
|
||||
|
||||
// Update cart
|
||||
fetch('/cart/change.js', {
|
||||
method: 'POST',
|
||||
headers: { 'Content-Type': 'application/json' },
|
||||
body: JSON.stringify({
|
||||
id: lineItemKey,
|
||||
quantity: 2
|
||||
})
|
||||
})
|
||||
.then(res => res.json());
|
||||
```
|
||||
|
||||
## Metafields in Themes
|
||||
|
||||
Access custom data:
|
||||
|
||||
```liquid
|
||||
{{ product.metafields.custom.care_instructions }}
|
||||
{{ product.metafields.custom.material.value }}
|
||||
|
||||
{% if product.metafields.custom.featured %}
|
||||
<span class="badge">Featured</span>
|
||||
{% endif %}
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
**Performance:**
|
||||
- Optimize images (use appropriate sizes)
|
||||
- Minimize Liquid logic complexity
|
||||
- Use lazy loading for images
|
||||
- Defer non-critical JavaScript
|
||||
|
||||
**Accessibility:**
|
||||
- Use semantic HTML
|
||||
- Include alt text for images
|
||||
- Support keyboard navigation
|
||||
- Ensure sufficient color contrast
|
||||
|
||||
**SEO:**
|
||||
- Use descriptive page titles
|
||||
- Include meta descriptions
|
||||
- Structure content with headings
|
||||
- Implement schema markup
|
||||
|
||||
**Code Quality:**
|
||||
- Follow Shopify theme guidelines
|
||||
- Use consistent naming conventions
|
||||
- Comment complex logic
|
||||
- Keep sections focused and reusable
|
||||
|
||||
## Resources
|
||||
|
||||
- Theme Development: https://shopify.dev/docs/themes
|
||||
- Liquid Reference: https://shopify.dev/docs/api/liquid
|
||||
- Dawn Theme: https://github.com/Shopify/dawn
|
||||
- Theme Check: https://shopify.dev/docs/themes/tools/theme-check
|
||||
49
skills/shopify-development/scripts/.gitignore
vendored
Normal file
49
skills/shopify-development/scripts/.gitignore
vendored
Normal file
@@ -0,0 +1,49 @@
|
||||
# Python
|
||||
__pycache__/
|
||||
*.py[cod]
|
||||
*$py.class
|
||||
*.so
|
||||
.Python
|
||||
build/
|
||||
develop-eggs/
|
||||
dist/
|
||||
downloads/
|
||||
eggs/
|
||||
.eggs/
|
||||
lib/
|
||||
lib64/
|
||||
parts/
|
||||
sdist/
|
||||
var/
|
||||
wheels/
|
||||
*.egg-info/
|
||||
.installed.cfg
|
||||
*.egg
|
||||
|
||||
# Testing
|
||||
.coverage
|
||||
.pytest_cache/
|
||||
htmlcov/
|
||||
.tox/
|
||||
.nox/
|
||||
coverage.xml
|
||||
*.cover
|
||||
*.py,cover
|
||||
|
||||
# Environments
|
||||
.env
|
||||
.venv
|
||||
env/
|
||||
venv/
|
||||
ENV/
|
||||
|
||||
# IDE
|
||||
.idea/
|
||||
.vscode/
|
||||
*.swp
|
||||
*.swo
|
||||
*~
|
||||
|
||||
# OS
|
||||
.DS_Store
|
||||
Thumbs.db
|
||||
19
skills/shopify-development/scripts/requirements.txt
Normal file
19
skills/shopify-development/scripts/requirements.txt
Normal file
@@ -0,0 +1,19 @@
|
||||
# Shopify Skill Dependencies
|
||||
# Python 3.10+ required
|
||||
|
||||
# No Python package dependencies - uses only standard library
|
||||
|
||||
# Testing dependencies (dev)
|
||||
pytest>=8.0.0
|
||||
pytest-cov>=4.1.0
|
||||
pytest-mock>=3.12.0
|
||||
|
||||
# Note: This script requires the Shopify CLI tool
|
||||
# Install Shopify CLI:
|
||||
# npm install -g @shopify/cli @shopify/theme
|
||||
# or via Homebrew (macOS):
|
||||
# brew tap shopify/shopify
|
||||
# brew install shopify-cli
|
||||
#
|
||||
# Authenticate with:
|
||||
# shopify auth login
|
||||
428
skills/shopify-development/scripts/shopify_graphql.py
Normal file
428
skills/shopify-development/scripts/shopify_graphql.py
Normal file
@@ -0,0 +1,428 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
Shopify GraphQL Utilities
|
||||
|
||||
Helper functions for common Shopify GraphQL operations.
|
||||
Provides query templates, pagination helpers, and rate limit handling.
|
||||
|
||||
Usage:
|
||||
from shopify_graphql import ShopifyGraphQL
|
||||
|
||||
client = ShopifyGraphQL(shop_domain, access_token)
|
||||
products = client.get_products(first=10)
|
||||
"""
|
||||
|
||||
import os
|
||||
import time
|
||||
import json
|
||||
from typing import Dict, List, Optional, Any, Generator
|
||||
from dataclasses import dataclass
|
||||
from urllib.request import Request, urlopen
|
||||
from urllib.error import HTTPError
|
||||
|
||||
|
||||
# API Configuration
|
||||
API_VERSION = "2026-01"
|
||||
MAX_RETRIES = 3
|
||||
RETRY_DELAY = 1.0 # seconds
|
||||
|
||||
|
||||
@dataclass
|
||||
class GraphQLResponse:
|
||||
"""Container for GraphQL response data."""
|
||||
data: Optional[Dict[str, Any]] = None
|
||||
errors: Optional[List[Dict[str, Any]]] = None
|
||||
extensions: Optional[Dict[str, Any]] = None
|
||||
|
||||
@property
|
||||
def is_success(self) -> bool:
|
||||
return self.errors is None or len(self.errors) == 0
|
||||
|
||||
@property
|
||||
def query_cost(self) -> Optional[int]:
|
||||
"""Get the actual query cost from extensions."""
|
||||
if self.extensions and 'cost' in self.extensions:
|
||||
return self.extensions['cost'].get('actualQueryCost')
|
||||
return None
|
||||
|
||||
|
||||
class ShopifyGraphQL:
|
||||
"""
|
||||
Shopify GraphQL API client with built-in utilities.
|
||||
|
||||
Features:
|
||||
- Query templates for common operations
|
||||
- Automatic pagination
|
||||
- Rate limit handling with exponential backoff
|
||||
- Response parsing helpers
|
||||
"""
|
||||
|
||||
def __init__(self, shop_domain: str, access_token: str):
|
||||
"""
|
||||
Initialize the GraphQL client.
|
||||
|
||||
Args:
|
||||
shop_domain: Store domain (e.g., 'my-store.myshopify.com')
|
||||
access_token: Admin API access token
|
||||
"""
|
||||
self.shop_domain = shop_domain.replace('https://', '').replace('http://', '')
|
||||
self.access_token = access_token
|
||||
self.base_url = f"https://{self.shop_domain}/admin/api/{API_VERSION}/graphql.json"
|
||||
|
||||
def execute(self, query: str, variables: Optional[Dict] = None) -> GraphQLResponse:
|
||||
"""
|
||||
Execute a GraphQL query/mutation.
|
||||
|
||||
Args:
|
||||
query: GraphQL query string
|
||||
variables: Query variables
|
||||
|
||||
Returns:
|
||||
GraphQLResponse object
|
||||
"""
|
||||
payload = {"query": query}
|
||||
if variables:
|
||||
payload["variables"] = variables
|
||||
|
||||
headers = {
|
||||
"Content-Type": "application/json",
|
||||
"X-Shopify-Access-Token": self.access_token
|
||||
}
|
||||
|
||||
for attempt in range(MAX_RETRIES):
|
||||
try:
|
||||
request = Request(
|
||||
self.base_url,
|
||||
data=json.dumps(payload).encode('utf-8'),
|
||||
headers=headers,
|
||||
method='POST'
|
||||
)
|
||||
|
||||
with urlopen(request, timeout=30) as response:
|
||||
result = json.loads(response.read().decode('utf-8'))
|
||||
return GraphQLResponse(
|
||||
data=result.get('data'),
|
||||
errors=result.get('errors'),
|
||||
extensions=result.get('extensions')
|
||||
)
|
||||
|
||||
except HTTPError as e:
|
||||
if e.code == 429: # Rate limited
|
||||
delay = RETRY_DELAY * (2 ** attempt)
|
||||
print(f"Rate limited. Retrying in {delay}s...")
|
||||
time.sleep(delay)
|
||||
continue
|
||||
raise
|
||||
except Exception as e:
|
||||
if attempt == MAX_RETRIES - 1:
|
||||
raise
|
||||
time.sleep(RETRY_DELAY)
|
||||
|
||||
return GraphQLResponse(errors=[{"message": "Max retries exceeded"}])
|
||||
|
||||
# ==================== Query Templates ====================
|
||||
|
||||
def get_products(
|
||||
self,
|
||||
first: int = 10,
|
||||
query: Optional[str] = None,
|
||||
after: Optional[str] = None
|
||||
) -> GraphQLResponse:
|
||||
"""
|
||||
Query products with pagination.
|
||||
|
||||
Args:
|
||||
first: Number of products to fetch (max 250)
|
||||
query: Optional search query
|
||||
after: Cursor for pagination
|
||||
"""
|
||||
gql = """
|
||||
query GetProducts($first: Int!, $query: String, $after: String) {
|
||||
products(first: $first, query: $query, after: $after) {
|
||||
edges {
|
||||
node {
|
||||
id
|
||||
title
|
||||
handle
|
||||
status
|
||||
totalInventory
|
||||
variants(first: 5) {
|
||||
edges {
|
||||
node {
|
||||
id
|
||||
title
|
||||
price
|
||||
inventoryQuantity
|
||||
sku
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
cursor
|
||||
}
|
||||
pageInfo {
|
||||
hasNextPage
|
||||
endCursor
|
||||
}
|
||||
}
|
||||
}
|
||||
"""
|
||||
return self.execute(gql, {"first": first, "query": query, "after": after})
|
||||
|
||||
def get_orders(
|
||||
self,
|
||||
first: int = 10,
|
||||
query: Optional[str] = None,
|
||||
after: Optional[str] = None
|
||||
) -> GraphQLResponse:
|
||||
"""
|
||||
Query orders with pagination.
|
||||
|
||||
Args:
|
||||
first: Number of orders to fetch (max 250)
|
||||
query: Optional search query (e.g., "financial_status:paid")
|
||||
after: Cursor for pagination
|
||||
"""
|
||||
gql = """
|
||||
query GetOrders($first: Int!, $query: String, $after: String) {
|
||||
orders(first: $first, query: $query, after: $after) {
|
||||
edges {
|
||||
node {
|
||||
id
|
||||
name
|
||||
createdAt
|
||||
displayFinancialStatus
|
||||
displayFulfillmentStatus
|
||||
totalPriceSet {
|
||||
shopMoney { amount currencyCode }
|
||||
}
|
||||
customer {
|
||||
id
|
||||
firstName
|
||||
lastName
|
||||
}
|
||||
lineItems(first: 5) {
|
||||
edges {
|
||||
node {
|
||||
title
|
||||
quantity
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
cursor
|
||||
}
|
||||
pageInfo {
|
||||
hasNextPage
|
||||
endCursor
|
||||
}
|
||||
}
|
||||
}
|
||||
"""
|
||||
return self.execute(gql, {"first": first, "query": query, "after": after})
|
||||
|
||||
def get_customers(
|
||||
self,
|
||||
first: int = 10,
|
||||
query: Optional[str] = None,
|
||||
after: Optional[str] = None
|
||||
) -> GraphQLResponse:
|
||||
"""
|
||||
Query customers with pagination.
|
||||
|
||||
Args:
|
||||
first: Number of customers to fetch (max 250)
|
||||
query: Optional search query
|
||||
after: Cursor for pagination
|
||||
"""
|
||||
gql = """
|
||||
query GetCustomers($first: Int!, $query: String, $after: String) {
|
||||
customers(first: $first, query: $query, after: $after) {
|
||||
edges {
|
||||
node {
|
||||
id
|
||||
firstName
|
||||
lastName
|
||||
displayName
|
||||
defaultEmailAddress {
|
||||
emailAddress
|
||||
}
|
||||
numberOfOrders
|
||||
amountSpent {
|
||||
amount
|
||||
currencyCode
|
||||
}
|
||||
}
|
||||
cursor
|
||||
}
|
||||
pageInfo {
|
||||
hasNextPage
|
||||
endCursor
|
||||
}
|
||||
}
|
||||
}
|
||||
"""
|
||||
return self.execute(gql, {"first": first, "query": query, "after": after})
|
||||
|
||||
def set_metafields(self, metafields: List[Dict]) -> GraphQLResponse:
|
||||
"""
|
||||
Set metafields on resources.
|
||||
|
||||
Args:
|
||||
metafields: List of metafield inputs, each containing:
|
||||
- ownerId: Resource GID
|
||||
- namespace: Metafield namespace
|
||||
- key: Metafield key
|
||||
- value: Metafield value
|
||||
- type: Metafield type
|
||||
"""
|
||||
gql = """
|
||||
mutation SetMetafields($metafields: [MetafieldsSetInput!]!) {
|
||||
metafieldsSet(metafields: $metafields) {
|
||||
metafields {
|
||||
id
|
||||
namespace
|
||||
key
|
||||
value
|
||||
}
|
||||
userErrors {
|
||||
field
|
||||
message
|
||||
}
|
||||
}
|
||||
}
|
||||
"""
|
||||
return self.execute(gql, {"metafields": metafields})
|
||||
|
||||
# ==================== Pagination Helpers ====================
|
||||
|
||||
def paginate_products(
|
||||
self,
|
||||
batch_size: int = 50,
|
||||
query: Optional[str] = None
|
||||
) -> Generator[Dict, None, None]:
|
||||
"""
|
||||
Generator that yields all products with automatic pagination.
|
||||
|
||||
Args:
|
||||
batch_size: Products per request (max 250)
|
||||
query: Optional search query
|
||||
|
||||
Yields:
|
||||
Product dictionaries
|
||||
"""
|
||||
cursor = None
|
||||
while True:
|
||||
response = self.get_products(first=batch_size, query=query, after=cursor)
|
||||
|
||||
if not response.is_success or not response.data:
|
||||
break
|
||||
|
||||
products = response.data.get('products', {})
|
||||
edges = products.get('edges', [])
|
||||
|
||||
for edge in edges:
|
||||
yield edge['node']
|
||||
|
||||
page_info = products.get('pageInfo', {})
|
||||
if not page_info.get('hasNextPage'):
|
||||
break
|
||||
|
||||
cursor = page_info.get('endCursor')
|
||||
|
||||
def paginate_orders(
|
||||
self,
|
||||
batch_size: int = 50,
|
||||
query: Optional[str] = None
|
||||
) -> Generator[Dict, None, None]:
|
||||
"""
|
||||
Generator that yields all orders with automatic pagination.
|
||||
|
||||
Args:
|
||||
batch_size: Orders per request (max 250)
|
||||
query: Optional search query
|
||||
|
||||
Yields:
|
||||
Order dictionaries
|
||||
"""
|
||||
cursor = None
|
||||
while True:
|
||||
response = self.get_orders(first=batch_size, query=query, after=cursor)
|
||||
|
||||
if not response.is_success or not response.data:
|
||||
break
|
||||
|
||||
orders = response.data.get('orders', {})
|
||||
edges = orders.get('edges', [])
|
||||
|
||||
for edge in edges:
|
||||
yield edge['node']
|
||||
|
||||
page_info = orders.get('pageInfo', {})
|
||||
if not page_info.get('hasNextPage'):
|
||||
break
|
||||
|
||||
cursor = page_info.get('endCursor')
|
||||
|
||||
|
||||
# ==================== Utility Functions ====================
|
||||
|
||||
def extract_id(gid: str) -> str:
|
||||
"""
|
||||
Extract numeric ID from Shopify GID.
|
||||
|
||||
Args:
|
||||
gid: Global ID (e.g., 'gid://shopify/Product/123')
|
||||
|
||||
Returns:
|
||||
Numeric ID string (e.g., '123')
|
||||
"""
|
||||
return gid.split('/')[-1] if gid else ''
|
||||
|
||||
|
||||
def build_gid(resource_type: str, id: str) -> str:
|
||||
"""
|
||||
Build Shopify GID from resource type and ID.
|
||||
|
||||
Args:
|
||||
resource_type: Resource type (e.g., 'Product', 'Order')
|
||||
id: Numeric ID
|
||||
|
||||
Returns:
|
||||
Global ID (e.g., 'gid://shopify/Product/123')
|
||||
"""
|
||||
return f"gid://shopify/{resource_type}/{id}"
|
||||
|
||||
|
||||
# ==================== Example Usage ====================
|
||||
|
||||
def main():
|
||||
"""Example usage of ShopifyGraphQL client."""
|
||||
import os
|
||||
|
||||
# Load from environment
|
||||
shop = os.environ.get('SHOP_DOMAIN', 'your-store.myshopify.com')
|
||||
token = os.environ.get('SHOPIFY_ACCESS_TOKEN', '')
|
||||
|
||||
if not token:
|
||||
print("Set SHOPIFY_ACCESS_TOKEN environment variable")
|
||||
return
|
||||
|
||||
client = ShopifyGraphQL(shop, token)
|
||||
|
||||
# Example: Get first 5 products
|
||||
print("Fetching products...")
|
||||
response = client.get_products(first=5)
|
||||
|
||||
if response.is_success:
|
||||
products = response.data['products']['edges']
|
||||
for edge in products:
|
||||
product = edge['node']
|
||||
print(f" - {product['title']} ({product['status']})")
|
||||
print(f"\nQuery cost: {response.query_cost}")
|
||||
else:
|
||||
print(f"Errors: {response.errors}")
|
||||
|
||||
|
||||
if __name__ == '__main__':
|
||||
main()
|
||||
441
skills/shopify-development/scripts/shopify_init.py
Normal file
441
skills/shopify-development/scripts/shopify_init.py
Normal file
@@ -0,0 +1,441 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
Shopify Project Initialization Script
|
||||
|
||||
Interactive script to scaffold Shopify apps, extensions, or themes.
|
||||
Supports environment variable loading from multiple locations.
|
||||
"""
|
||||
|
||||
import os
|
||||
import sys
|
||||
import json
|
||||
import subprocess
|
||||
from pathlib import Path
|
||||
from typing import Dict, Optional, List
|
||||
from dataclasses import dataclass
|
||||
|
||||
|
||||
@dataclass
|
||||
class EnvConfig:
|
||||
"""Environment configuration container."""
|
||||
shopify_api_key: Optional[str] = None
|
||||
shopify_api_secret: Optional[str] = None
|
||||
shop_domain: Optional[str] = None
|
||||
scopes: Optional[str] = None
|
||||
|
||||
|
||||
class EnvLoader:
|
||||
"""Load environment variables from multiple sources in priority order."""
|
||||
|
||||
@staticmethod
|
||||
def load_env_file(filepath: Path) -> Dict[str, str]:
|
||||
"""
|
||||
Load environment variables from .env file.
|
||||
|
||||
Args:
|
||||
filepath: Path to .env file
|
||||
|
||||
Returns:
|
||||
Dictionary of environment variables
|
||||
"""
|
||||
env_vars = {}
|
||||
if not filepath.exists():
|
||||
return env_vars
|
||||
|
||||
try:
|
||||
with open(filepath, 'r') as f:
|
||||
for line in f:
|
||||
line = line.strip()
|
||||
if line and not line.startswith('#') and '=' in line:
|
||||
key, value = line.split('=', 1)
|
||||
env_vars[key.strip()] = value.strip().strip('"').strip("'")
|
||||
except Exception as e:
|
||||
print(f"Warning: Failed to load {filepath}: {e}")
|
||||
|
||||
return env_vars
|
||||
|
||||
@staticmethod
|
||||
def get_env_paths(skill_dir: Path) -> List[Path]:
|
||||
"""
|
||||
Get list of .env file paths in priority order.
|
||||
|
||||
Works with any AI tool directory structure:
|
||||
- .agent/skills/ (universal)
|
||||
- .claude/skills/ (Claude Code)
|
||||
- .gemini/skills/ (Gemini CLI)
|
||||
- .cursor/skills/ (Cursor)
|
||||
|
||||
Priority: process.env > skill/.env > skills/.env > agent_dir/.env
|
||||
|
||||
Args:
|
||||
skill_dir: Path to skill directory
|
||||
|
||||
Returns:
|
||||
List of .env file paths
|
||||
"""
|
||||
paths = []
|
||||
|
||||
# skill/.env
|
||||
skill_env = skill_dir / '.env'
|
||||
if skill_env.exists():
|
||||
paths.append(skill_env)
|
||||
|
||||
# skills/.env
|
||||
skills_env = skill_dir.parent / '.env'
|
||||
if skills_env.exists():
|
||||
paths.append(skills_env)
|
||||
|
||||
# agent_dir/.env (e.g., .agent, .claude, .gemini, .cursor)
|
||||
agent_env = skill_dir.parent.parent / '.env'
|
||||
if agent_env.exists():
|
||||
paths.append(agent_env)
|
||||
|
||||
return paths
|
||||
|
||||
@staticmethod
|
||||
def load_config(skill_dir: Path) -> EnvConfig:
|
||||
"""
|
||||
Load configuration from environment variables.
|
||||
|
||||
Works with any AI tool directory structure.
|
||||
Priority: process.env > skill/.env > skills/.env > agent_dir/.env
|
||||
|
||||
Args:
|
||||
skill_dir: Path to skill directory
|
||||
|
||||
Returns:
|
||||
EnvConfig object
|
||||
"""
|
||||
config = EnvConfig()
|
||||
|
||||
# Load from .env files (reverse priority order)
|
||||
for env_path in reversed(EnvLoader.get_env_paths(skill_dir)):
|
||||
env_vars = EnvLoader.load_env_file(env_path)
|
||||
if 'SHOPIFY_API_KEY' in env_vars:
|
||||
config.shopify_api_key = env_vars['SHOPIFY_API_KEY']
|
||||
if 'SHOPIFY_API_SECRET' in env_vars:
|
||||
config.shopify_api_secret = env_vars['SHOPIFY_API_SECRET']
|
||||
if 'SHOP_DOMAIN' in env_vars:
|
||||
config.shop_domain = env_vars['SHOP_DOMAIN']
|
||||
if 'SCOPES' in env_vars:
|
||||
config.scopes = env_vars['SCOPES']
|
||||
|
||||
# Override with process environment (highest priority)
|
||||
if 'SHOPIFY_API_KEY' in os.environ:
|
||||
config.shopify_api_key = os.environ['SHOPIFY_API_KEY']
|
||||
if 'SHOPIFY_API_SECRET' in os.environ:
|
||||
config.shopify_api_secret = os.environ['SHOPIFY_API_SECRET']
|
||||
if 'SHOP_DOMAIN' in os.environ:
|
||||
config.shop_domain = os.environ['SHOP_DOMAIN']
|
||||
if 'SCOPES' in os.environ:
|
||||
config.scopes = os.environ['SCOPES']
|
||||
|
||||
return config
|
||||
|
||||
|
||||
class ShopifyInitializer:
|
||||
"""Initialize Shopify projects."""
|
||||
|
||||
def __init__(self, config: EnvConfig):
|
||||
"""
|
||||
Initialize ShopifyInitializer.
|
||||
|
||||
Args:
|
||||
config: Environment configuration
|
||||
"""
|
||||
self.config = config
|
||||
|
||||
def prompt(self, message: str, default: Optional[str] = None) -> str:
|
||||
"""
|
||||
Prompt user for input.
|
||||
|
||||
Args:
|
||||
message: Prompt message
|
||||
default: Default value
|
||||
|
||||
Returns:
|
||||
User input or default
|
||||
"""
|
||||
if default:
|
||||
message = f"{message} [{default}]"
|
||||
user_input = input(f"{message}: ").strip()
|
||||
return user_input if user_input else (default or '')
|
||||
|
||||
def select_option(self, message: str, options: List[str]) -> str:
|
||||
"""
|
||||
Prompt user to select from options.
|
||||
|
||||
Args:
|
||||
message: Prompt message
|
||||
options: List of options
|
||||
|
||||
Returns:
|
||||
Selected option
|
||||
"""
|
||||
print(f"\n{message}")
|
||||
for i, option in enumerate(options, 1):
|
||||
print(f"{i}. {option}")
|
||||
|
||||
while True:
|
||||
try:
|
||||
choice = int(input("Select option: ").strip())
|
||||
if 1 <= choice <= len(options):
|
||||
return options[choice - 1]
|
||||
print(f"Please select 1-{len(options)}")
|
||||
except (ValueError, KeyboardInterrupt):
|
||||
print("Invalid input")
|
||||
|
||||
def check_cli_installed(self) -> bool:
|
||||
"""
|
||||
Check if Shopify CLI is installed.
|
||||
|
||||
Returns:
|
||||
True if installed, False otherwise
|
||||
"""
|
||||
try:
|
||||
result = subprocess.run(
|
||||
['shopify', 'version'],
|
||||
capture_output=True,
|
||||
text=True,
|
||||
timeout=5
|
||||
)
|
||||
return result.returncode == 0
|
||||
except (subprocess.SubprocessError, FileNotFoundError):
|
||||
return False
|
||||
|
||||
def create_app_config(self, project_dir: Path, app_name: str, scopes: str) -> None:
|
||||
"""
|
||||
Create shopify.app.toml configuration file.
|
||||
|
||||
Args:
|
||||
project_dir: Project directory
|
||||
app_name: Application name
|
||||
scopes: Access scopes
|
||||
"""
|
||||
config_content = f"""# Shopify App Configuration
|
||||
name = "{app_name}"
|
||||
client_id = "{self.config.shopify_api_key or 'YOUR_API_KEY'}"
|
||||
application_url = "https://your-app.com"
|
||||
embedded = true
|
||||
|
||||
[build]
|
||||
automatically_update_urls_on_dev = true
|
||||
dev_store_url = "{self.config.shop_domain or 'your-store.myshopify.com'}"
|
||||
|
||||
[access_scopes]
|
||||
scopes = "{scopes}"
|
||||
|
||||
[webhooks]
|
||||
api_version = "2026-01"
|
||||
|
||||
[[webhooks.subscriptions]]
|
||||
topics = ["app/uninstalled"]
|
||||
uri = "/webhooks/app/uninstalled"
|
||||
|
||||
[webhooks.privacy_compliance]
|
||||
customer_data_request_url = "/webhooks/gdpr/data-request"
|
||||
customer_deletion_url = "/webhooks/gdpr/customer-deletion"
|
||||
shop_deletion_url = "/webhooks/gdpr/shop-deletion"
|
||||
"""
|
||||
config_path = project_dir / 'shopify.app.toml'
|
||||
config_path.write_text(config_content)
|
||||
print(f"✓ Created {config_path}")
|
||||
|
||||
def create_extension_config(self, project_dir: Path, extension_name: str, extension_type: str) -> None:
|
||||
"""
|
||||
Create shopify.extension.toml configuration file.
|
||||
|
||||
Args:
|
||||
project_dir: Project directory
|
||||
extension_name: Extension name
|
||||
extension_type: Extension type
|
||||
"""
|
||||
target_map = {
|
||||
'checkout': 'purchase.checkout.block.render',
|
||||
'admin_action': 'admin.product-details.action.render',
|
||||
'admin_block': 'admin.product-details.block.render',
|
||||
'pos': 'pos.home.tile.render',
|
||||
'function': 'function',
|
||||
'customer_account': 'customer-account.order-status.block.render',
|
||||
'theme_app': 'theme-app-extension'
|
||||
}
|
||||
|
||||
config_content = f"""name = "{extension_name}"
|
||||
type = "ui_extension"
|
||||
handle = "{extension_name.lower().replace(' ', '-')}"
|
||||
|
||||
[extension_points]
|
||||
api_version = "2026-01"
|
||||
|
||||
[[extension_points.targets]]
|
||||
target = "{target_map.get(extension_type, 'purchase.checkout.block.render')}"
|
||||
|
||||
[capabilities]
|
||||
network_access = true
|
||||
api_access = true
|
||||
"""
|
||||
config_path = project_dir / 'shopify.extension.toml'
|
||||
config_path.write_text(config_content)
|
||||
print(f"✓ Created {config_path}")
|
||||
|
||||
def create_readme(self, project_dir: Path, project_type: str, project_name: str) -> None:
|
||||
"""
|
||||
Create README.md file.
|
||||
|
||||
Args:
|
||||
project_dir: Project directory
|
||||
project_type: Project type (app/extension/theme)
|
||||
project_name: Project name
|
||||
"""
|
||||
content = f"""# {project_name}
|
||||
|
||||
Shopify {project_type.capitalize()} project.
|
||||
|
||||
## Setup
|
||||
|
||||
```bash
|
||||
# Install dependencies
|
||||
npm install
|
||||
|
||||
# Start development
|
||||
shopify {project_type} dev
|
||||
```
|
||||
|
||||
## Deployment
|
||||
|
||||
```bash
|
||||
# Deploy to Shopify
|
||||
shopify {project_type} deploy
|
||||
```
|
||||
|
||||
## Resources
|
||||
|
||||
- [Shopify Documentation](https://shopify.dev/docs)
|
||||
- [Shopify CLI](https://shopify.dev/docs/api/shopify-cli)
|
||||
"""
|
||||
readme_path = project_dir / 'README.md'
|
||||
readme_path.write_text(content)
|
||||
print(f"✓ Created {readme_path}")
|
||||
|
||||
def init_app(self) -> None:
|
||||
"""Initialize Shopify app project."""
|
||||
print("\n=== Shopify App Initialization ===\n")
|
||||
|
||||
app_name = self.prompt("App name", "my-shopify-app")
|
||||
scopes = self.prompt("Access scopes", self.config.scopes or "read_products,write_products")
|
||||
|
||||
project_dir = Path.cwd() / app_name
|
||||
project_dir.mkdir(exist_ok=True)
|
||||
|
||||
print(f"\nCreating app in {project_dir}...")
|
||||
|
||||
self.create_app_config(project_dir, app_name, scopes)
|
||||
self.create_readme(project_dir, "app", app_name)
|
||||
|
||||
# Create basic package.json
|
||||
package_json = {
|
||||
"name": app_name.lower().replace(' ', '-'),
|
||||
"version": "1.0.0",
|
||||
"scripts": {
|
||||
"dev": "shopify app dev",
|
||||
"deploy": "shopify app deploy"
|
||||
}
|
||||
}
|
||||
(project_dir / 'package.json').write_text(json.dumps(package_json, indent=2))
|
||||
print(f"✓ Created package.json")
|
||||
|
||||
print(f"\n✓ App '{app_name}' initialized successfully!")
|
||||
print(f"\nNext steps:")
|
||||
print(f" cd {app_name}")
|
||||
print(f" npm install")
|
||||
print(f" shopify app dev")
|
||||
|
||||
def init_extension(self) -> None:
|
||||
"""Initialize Shopify extension project."""
|
||||
print("\n=== Shopify Extension Initialization ===\n")
|
||||
|
||||
extension_types = [
|
||||
'checkout',
|
||||
'admin_action',
|
||||
'admin_block',
|
||||
'pos',
|
||||
'function',
|
||||
'customer_account',
|
||||
'theme_app'
|
||||
]
|
||||
extension_type = self.select_option("Select extension type", extension_types)
|
||||
|
||||
extension_name = self.prompt("Extension name", "my-extension")
|
||||
|
||||
project_dir = Path.cwd() / extension_name
|
||||
project_dir.mkdir(exist_ok=True)
|
||||
|
||||
print(f"\nCreating extension in {project_dir}...")
|
||||
|
||||
self.create_extension_config(project_dir, extension_name, extension_type)
|
||||
self.create_readme(project_dir, "extension", extension_name)
|
||||
|
||||
print(f"\n✓ Extension '{extension_name}' initialized successfully!")
|
||||
print(f"\nNext steps:")
|
||||
print(f" cd {extension_name}")
|
||||
print(f" shopify app dev")
|
||||
|
||||
def init_theme(self) -> None:
|
||||
"""Initialize Shopify theme project."""
|
||||
print("\n=== Shopify Theme Initialization ===\n")
|
||||
|
||||
theme_name = self.prompt("Theme name", "my-theme")
|
||||
|
||||
print(f"\nInitializing theme '{theme_name}'...")
|
||||
print("\nRecommended: Use 'shopify theme init' for full theme scaffolding")
|
||||
print(f"\nRun: shopify theme init {theme_name}")
|
||||
|
||||
def run(self) -> None:
|
||||
"""Run interactive initialization."""
|
||||
print("=" * 60)
|
||||
print("Shopify Project Initializer")
|
||||
print("=" * 60)
|
||||
|
||||
# Check CLI
|
||||
if not self.check_cli_installed():
|
||||
print("\n⚠ Shopify CLI not found!")
|
||||
print("Install: npm install -g @shopify/cli@latest")
|
||||
sys.exit(1)
|
||||
|
||||
# Select project type
|
||||
project_types = ['app', 'extension', 'theme']
|
||||
project_type = self.select_option("Select project type", project_types)
|
||||
|
||||
# Initialize based on type
|
||||
if project_type == 'app':
|
||||
self.init_app()
|
||||
elif project_type == 'extension':
|
||||
self.init_extension()
|
||||
elif project_type == 'theme':
|
||||
self.init_theme()
|
||||
|
||||
|
||||
def main() -> None:
|
||||
"""Main entry point."""
|
||||
try:
|
||||
# Get skill directory
|
||||
script_dir = Path(__file__).parent
|
||||
skill_dir = script_dir.parent
|
||||
|
||||
# Load configuration
|
||||
config = EnvLoader.load_config(skill_dir)
|
||||
|
||||
# Initialize project
|
||||
initializer = ShopifyInitializer(config)
|
||||
initializer.run()
|
||||
|
||||
except KeyboardInterrupt:
|
||||
print("\n\nAborted.")
|
||||
sys.exit(0)
|
||||
except Exception as e:
|
||||
print(f"\n✗ Error: {e}", file=sys.stderr)
|
||||
sys.exit(1)
|
||||
|
||||
|
||||
if __name__ == '__main__':
|
||||
main()
|
||||
379
skills/shopify-development/scripts/tests/test_shopify_init.py
Normal file
379
skills/shopify-development/scripts/tests/test_shopify_init.py
Normal file
@@ -0,0 +1,379 @@
|
||||
"""
|
||||
Tests for shopify_init.py
|
||||
|
||||
Run with: pytest test_shopify_init.py -v --cov=shopify_init --cov-report=term-missing
|
||||
"""
|
||||
|
||||
import os
|
||||
import sys
|
||||
import json
|
||||
import pytest
|
||||
import subprocess
|
||||
from pathlib import Path
|
||||
from unittest.mock import Mock, patch, mock_open, MagicMock
|
||||
|
||||
sys.path.insert(0, str(Path(__file__).parent.parent))
|
||||
|
||||
from shopify_init import EnvLoader, EnvConfig, ShopifyInitializer
|
||||
|
||||
|
||||
class TestEnvLoader:
|
||||
"""Test EnvLoader class."""
|
||||
|
||||
def test_load_env_file_success(self, tmp_path):
|
||||
"""Test loading valid .env file."""
|
||||
env_file = tmp_path / ".env"
|
||||
env_file.write_text("""
|
||||
SHOPIFY_API_KEY=test_key
|
||||
SHOPIFY_API_SECRET=test_secret
|
||||
SHOP_DOMAIN=test.myshopify.com
|
||||
# Comment line
|
||||
SCOPES=read_products,write_products
|
||||
""")
|
||||
|
||||
result = EnvLoader.load_env_file(env_file)
|
||||
|
||||
assert result['SHOPIFY_API_KEY'] == 'test_key'
|
||||
assert result['SHOPIFY_API_SECRET'] == 'test_secret'
|
||||
assert result['SHOP_DOMAIN'] == 'test.myshopify.com'
|
||||
assert result['SCOPES'] == 'read_products,write_products'
|
||||
|
||||
def test_load_env_file_with_quotes(self, tmp_path):
|
||||
"""Test loading .env file with quoted values."""
|
||||
env_file = tmp_path / ".env"
|
||||
env_file.write_text("""
|
||||
SHOPIFY_API_KEY="test_key"
|
||||
SHOPIFY_API_SECRET='test_secret'
|
||||
""")
|
||||
|
||||
result = EnvLoader.load_env_file(env_file)
|
||||
|
||||
assert result['SHOPIFY_API_KEY'] == 'test_key'
|
||||
assert result['SHOPIFY_API_SECRET'] == 'test_secret'
|
||||
|
||||
def test_load_env_file_nonexistent(self, tmp_path):
|
||||
"""Test loading non-existent .env file."""
|
||||
result = EnvLoader.load_env_file(tmp_path / "nonexistent.env")
|
||||
assert result == {}
|
||||
|
||||
def test_load_env_file_invalid_format(self, tmp_path):
|
||||
"""Test loading .env file with invalid lines."""
|
||||
env_file = tmp_path / ".env"
|
||||
env_file.write_text("""
|
||||
VALID_KEY=value
|
||||
INVALID_LINE_NO_EQUALS
|
||||
ANOTHER_VALID=test
|
||||
""")
|
||||
|
||||
result = EnvLoader.load_env_file(env_file)
|
||||
|
||||
assert result['VALID_KEY'] == 'value'
|
||||
assert result['ANOTHER_VALID'] == 'test'
|
||||
assert 'INVALID_LINE_NO_EQUALS' not in result
|
||||
|
||||
def test_get_env_paths(self, tmp_path):
|
||||
"""Test getting .env file paths from universal directory structure."""
|
||||
# Create directory structure (works with .agent, .claude, .gemini, .cursor)
|
||||
agent_dir = tmp_path / ".agent"
|
||||
skills_dir = agent_dir / "skills"
|
||||
skill_dir = skills_dir / "shopify"
|
||||
|
||||
skill_dir.mkdir(parents=True)
|
||||
|
||||
# Create .env files at each level
|
||||
(skill_dir / ".env").write_text("SKILL=1")
|
||||
(skills_dir / ".env").write_text("SKILLS=1")
|
||||
(agent_dir / ".env").write_text("AGENT=1")
|
||||
|
||||
paths = EnvLoader.get_env_paths(skill_dir)
|
||||
|
||||
assert len(paths) == 3
|
||||
assert skill_dir / ".env" in paths
|
||||
assert skills_dir / ".env" in paths
|
||||
assert agent_dir / ".env" in paths
|
||||
|
||||
def test_load_config_priority(self, tmp_path, monkeypatch):
|
||||
"""Test configuration loading priority across different AI tool directories."""
|
||||
skill_dir = tmp_path / "skill"
|
||||
skills_dir = tmp_path
|
||||
agent_dir = tmp_path.parent # Could be .agent, .claude, .gemini, .cursor
|
||||
|
||||
skill_dir.mkdir(parents=True)
|
||||
|
||||
(skill_dir / ".env").write_text("SHOPIFY_API_KEY=skill_key")
|
||||
(skills_dir / ".env").write_text("SHOPIFY_API_KEY=skills_key\nSHOP_DOMAIN=skills.myshopify.com")
|
||||
|
||||
monkeypatch.setenv("SHOPIFY_API_KEY", "process_key")
|
||||
|
||||
config = EnvLoader.load_config(skill_dir)
|
||||
|
||||
assert config.shopify_api_key == "process_key"
|
||||
# Shop domain from skills/.env
|
||||
assert config.shop_domain == "skills.myshopify.com"
|
||||
|
||||
def test_load_config_no_files(self, tmp_path):
|
||||
"""Test configuration loading with no .env files."""
|
||||
config = EnvLoader.load_config(tmp_path)
|
||||
|
||||
assert config.shopify_api_key is None
|
||||
assert config.shopify_api_secret is None
|
||||
assert config.shop_domain is None
|
||||
assert config.scopes is None
|
||||
|
||||
|
||||
class TestShopifyInitializer:
|
||||
"""Test ShopifyInitializer class."""
|
||||
|
||||
@pytest.fixture
|
||||
def config(self):
|
||||
"""Create test config."""
|
||||
return EnvConfig(
|
||||
shopify_api_key="test_key",
|
||||
shopify_api_secret="test_secret",
|
||||
shop_domain="test.myshopify.com",
|
||||
scopes="read_products,write_products"
|
||||
)
|
||||
|
||||
@pytest.fixture
|
||||
def initializer(self, config):
|
||||
"""Create initializer instance."""
|
||||
return ShopifyInitializer(config)
|
||||
|
||||
def test_prompt_with_default(self, initializer):
|
||||
"""Test prompt with default value."""
|
||||
with patch('builtins.input', return_value=''):
|
||||
result = initializer.prompt("Test", "default_value")
|
||||
assert result == "default_value"
|
||||
|
||||
def test_prompt_with_input(self, initializer):
|
||||
"""Test prompt with user input."""
|
||||
with patch('builtins.input', return_value='user_input'):
|
||||
result = initializer.prompt("Test", "default_value")
|
||||
assert result == "user_input"
|
||||
|
||||
def test_select_option_valid(self, initializer):
|
||||
"""Test select option with valid choice."""
|
||||
options = ['app', 'extension', 'theme']
|
||||
with patch('builtins.input', return_value='2'):
|
||||
result = initializer.select_option("Choose", options)
|
||||
assert result == 'extension'
|
||||
|
||||
def test_select_option_invalid_then_valid(self, initializer):
|
||||
"""Test select option with invalid then valid choice."""
|
||||
options = ['app', 'extension']
|
||||
with patch('builtins.input', side_effect=['5', 'invalid', '1']):
|
||||
result = initializer.select_option("Choose", options)
|
||||
assert result == 'app'
|
||||
|
||||
def test_check_cli_installed_success(self, initializer):
|
||||
"""Test CLI installed check - success."""
|
||||
mock_result = Mock()
|
||||
mock_result.returncode = 0
|
||||
|
||||
with patch('subprocess.run', return_value=mock_result):
|
||||
assert initializer.check_cli_installed() is True
|
||||
|
||||
def test_check_cli_installed_failure(self, initializer):
|
||||
"""Test CLI installed check - failure."""
|
||||
with patch('subprocess.run', side_effect=FileNotFoundError):
|
||||
assert initializer.check_cli_installed() is False
|
||||
|
||||
def test_create_app_config(self, initializer, tmp_path):
|
||||
"""Test creating app configuration file."""
|
||||
initializer.create_app_config(tmp_path, "test-app", "read_products")
|
||||
|
||||
config_file = tmp_path / "shopify.app.toml"
|
||||
assert config_file.exists()
|
||||
|
||||
content = config_file.read_text()
|
||||
assert 'name = "test-app"' in content
|
||||
assert 'scopes = "read_products"' in content
|
||||
assert 'client_id = "test_key"' in content
|
||||
|
||||
def test_create_extension_config(self, initializer, tmp_path):
|
||||
"""Test creating extension configuration file."""
|
||||
initializer.create_extension_config(tmp_path, "test-ext", "checkout")
|
||||
|
||||
config_file = tmp_path / "shopify.extension.toml"
|
||||
assert config_file.exists()
|
||||
|
||||
content = config_file.read_text()
|
||||
assert 'name = "test-ext"' in content
|
||||
assert 'purchase.checkout.block.render' in content
|
||||
|
||||
def test_create_extension_config_admin_action(self, initializer, tmp_path):
|
||||
"""Test creating admin action extension config."""
|
||||
initializer.create_extension_config(tmp_path, "admin-ext", "admin_action")
|
||||
|
||||
config_file = tmp_path / "shopify.extension.toml"
|
||||
content = config_file.read_text()
|
||||
assert 'admin.product-details.action.render' in content
|
||||
|
||||
def test_create_readme(self, initializer, tmp_path):
|
||||
"""Test creating README file."""
|
||||
initializer.create_readme(tmp_path, "app", "Test App")
|
||||
|
||||
readme_file = tmp_path / "README.md"
|
||||
assert readme_file.exists()
|
||||
|
||||
content = readme_file.read_text()
|
||||
assert '# Test App' in content
|
||||
assert 'shopify app dev' in content
|
||||
|
||||
@patch('builtins.input')
|
||||
@patch('builtins.print')
|
||||
def test_init_app(self, mock_print, mock_input, initializer, tmp_path, monkeypatch):
|
||||
"""Test app initialization."""
|
||||
monkeypatch.chdir(tmp_path)
|
||||
|
||||
# Mock user inputs
|
||||
mock_input.side_effect = ['my-app', 'read_products,write_products']
|
||||
|
||||
initializer.init_app()
|
||||
|
||||
# Check directory created
|
||||
app_dir = tmp_path / "my-app"
|
||||
assert app_dir.exists()
|
||||
|
||||
# Check files created
|
||||
assert (app_dir / "shopify.app.toml").exists()
|
||||
assert (app_dir / "README.md").exists()
|
||||
assert (app_dir / "package.json").exists()
|
||||
|
||||
# Check package.json content
|
||||
package_json = json.loads((app_dir / "package.json").read_text())
|
||||
assert package_json['name'] == 'my-app'
|
||||
assert 'dev' in package_json['scripts']
|
||||
|
||||
@patch('builtins.input')
|
||||
@patch('builtins.print')
|
||||
def test_init_extension(self, mock_print, mock_input, initializer, tmp_path, monkeypatch):
|
||||
"""Test extension initialization."""
|
||||
monkeypatch.chdir(tmp_path)
|
||||
|
||||
# Mock user inputs: type selection (1 = checkout), name
|
||||
mock_input.side_effect = ['1', 'my-extension']
|
||||
|
||||
initializer.init_extension()
|
||||
|
||||
# Check directory and files created
|
||||
ext_dir = tmp_path / "my-extension"
|
||||
assert ext_dir.exists()
|
||||
assert (ext_dir / "shopify.extension.toml").exists()
|
||||
assert (ext_dir / "README.md").exists()
|
||||
|
||||
@patch('builtins.input')
|
||||
@patch('builtins.print')
|
||||
def test_init_theme(self, mock_print, mock_input, initializer):
|
||||
"""Test theme initialization."""
|
||||
mock_input.return_value = 'my-theme'
|
||||
|
||||
initializer.init_theme()
|
||||
|
||||
assert mock_print.called
|
||||
|
||||
@patch('builtins.print')
|
||||
def test_run_no_cli(self, mock_print, initializer):
|
||||
"""Test run when CLI not installed."""
|
||||
with patch.object(initializer, 'check_cli_installed', return_value=False):
|
||||
with pytest.raises(SystemExit) as exc_info:
|
||||
initializer.run()
|
||||
assert exc_info.value.code == 1
|
||||
|
||||
@patch.object(ShopifyInitializer, 'check_cli_installed', return_value=True)
|
||||
@patch.object(ShopifyInitializer, 'init_app')
|
||||
@patch('builtins.input')
|
||||
@patch('builtins.print')
|
||||
def test_run_app_selected(self, mock_print, mock_input, mock_init_app, mock_cli_check, initializer):
|
||||
"""Test run with app selection."""
|
||||
mock_input.return_value = '1' # Select app
|
||||
|
||||
initializer.run()
|
||||
|
||||
mock_init_app.assert_called_once()
|
||||
|
||||
@patch.object(ShopifyInitializer, 'check_cli_installed', return_value=True)
|
||||
@patch.object(ShopifyInitializer, 'init_extension')
|
||||
@patch('builtins.input')
|
||||
@patch('builtins.print')
|
||||
def test_run_extension_selected(self, mock_print, mock_input, mock_init_ext, mock_cli_check, initializer):
|
||||
"""Test run with extension selection."""
|
||||
mock_input.return_value = '2' # Select extension
|
||||
|
||||
initializer.run()
|
||||
|
||||
mock_init_ext.assert_called_once()
|
||||
|
||||
|
||||
class TestMain:
|
||||
"""Test main function."""
|
||||
|
||||
@patch('shopify_init.ShopifyInitializer')
|
||||
@patch('shopify_init.EnvLoader')
|
||||
def test_main_success(self, mock_loader, mock_initializer):
|
||||
"""Test main function success path."""
|
||||
from shopify_init import main
|
||||
|
||||
mock_config = Mock()
|
||||
mock_loader.load_config.return_value = mock_config
|
||||
|
||||
mock_init_instance = Mock()
|
||||
mock_initializer.return_value = mock_init_instance
|
||||
|
||||
with patch('builtins.print'):
|
||||
main()
|
||||
|
||||
mock_init_instance.run.assert_called_once()
|
||||
|
||||
@patch('shopify_init.ShopifyInitializer')
|
||||
@patch('sys.exit')
|
||||
def test_main_keyboard_interrupt(self, mock_exit, mock_initializer):
|
||||
"""Test main function with keyboard interrupt."""
|
||||
from shopify_init import main
|
||||
|
||||
mock_initializer.return_value.run.side_effect = KeyboardInterrupt
|
||||
|
||||
with patch('builtins.print'):
|
||||
main()
|
||||
|
||||
mock_exit.assert_called_with(0)
|
||||
|
||||
@patch('shopify_init.ShopifyInitializer')
|
||||
@patch('sys.exit')
|
||||
def test_main_exception(self, mock_exit, mock_initializer):
|
||||
"""Test main function with exception."""
|
||||
from shopify_init import main
|
||||
|
||||
mock_initializer.return_value.run.side_effect = Exception("Test error")
|
||||
|
||||
with patch('builtins.print'):
|
||||
main()
|
||||
|
||||
mock_exit.assert_called_with(1)
|
||||
|
||||
|
||||
class TestEnvConfig:
|
||||
"""Test EnvConfig dataclass."""
|
||||
|
||||
def test_env_config_defaults(self):
|
||||
"""Test EnvConfig default values."""
|
||||
config = EnvConfig()
|
||||
|
||||
assert config.shopify_api_key is None
|
||||
assert config.shopify_api_secret is None
|
||||
assert config.shop_domain is None
|
||||
assert config.scopes is None
|
||||
|
||||
def test_env_config_with_values(self):
|
||||
"""Test EnvConfig with values."""
|
||||
config = EnvConfig(
|
||||
shopify_api_key="key",
|
||||
shopify_api_secret="secret",
|
||||
shop_domain="test.myshopify.com",
|
||||
scopes="read_products"
|
||||
)
|
||||
|
||||
assert config.shopify_api_key == "key"
|
||||
assert config.shopify_api_secret == "secret"
|
||||
assert config.shop_domain == "test.myshopify.com"
|
||||
assert config.scopes == "read_products"
|
||||
355
skills/signup-flow-cro/SKILL.md
Normal file
355
skills/signup-flow-cro/SKILL.md
Normal file
@@ -0,0 +1,355 @@
|
||||
---
|
||||
name: signup-flow-cro
|
||||
description: When the user wants to optimize signup, registration, account creation, or trial activation flows. Also use when the user mentions "signup conversions," "registration friction," "signup form optimization," "free trial signup," "reduce signup dropoff," or "account creation flow." For post-signup onboarding, see onboarding-cro. For lead capture forms (not account creation), see form-cro.
|
||||
---
|
||||
|
||||
# Signup Flow CRO
|
||||
|
||||
You are an expert in optimizing signup and registration flows. Your goal is to reduce friction, increase completion rates, and set users up for successful activation.
|
||||
|
||||
## Initial Assessment
|
||||
|
||||
Before providing recommendations, understand:
|
||||
|
||||
1. **Flow Type**
|
||||
- Free trial signup
|
||||
- Freemium account creation
|
||||
- Paid account creation
|
||||
- Waitlist/early access signup
|
||||
- B2B vs B2C
|
||||
|
||||
2. **Current State**
|
||||
- How many steps/screens?
|
||||
- What fields are required?
|
||||
- What's the current completion rate?
|
||||
- Where do users drop off?
|
||||
|
||||
3. **Business Constraints**
|
||||
- What data is genuinely needed at signup?
|
||||
- Are there compliance requirements?
|
||||
- What happens immediately after signup?
|
||||
|
||||
---
|
||||
|
||||
## Core Principles
|
||||
|
||||
### 1. Minimize Required Fields
|
||||
Every field reduces conversion. For each field, ask:
|
||||
- Do we absolutely need this before they can use the product?
|
||||
- Can we collect this later through progressive profiling?
|
||||
- Can we infer this from other data?
|
||||
|
||||
**Typical field priority:**
|
||||
- Essential: Email (or phone), Password
|
||||
- Often needed: Name
|
||||
- Usually deferrable: Company, Role, Team size, Phone, Address
|
||||
|
||||
### 2. Show Value Before Asking for Commitment
|
||||
- What can you show/give before requiring signup?
|
||||
- Can they experience the product before creating an account?
|
||||
- Reverse the order: value first, signup second
|
||||
|
||||
### 3. Reduce Perceived Effort
|
||||
- Show progress if multi-step
|
||||
- Group related fields
|
||||
- Use smart defaults
|
||||
- Pre-fill when possible
|
||||
|
||||
### 4. Remove Uncertainty
|
||||
- Clear expectations ("Takes 30 seconds")
|
||||
- Show what happens after signup
|
||||
- No surprises (hidden requirements, unexpected steps)
|
||||
|
||||
---
|
||||
|
||||
## Field-by-Field Optimization
|
||||
|
||||
### Email Field
|
||||
- Single field (no email confirmation field)
|
||||
- Inline validation for format
|
||||
- Check for common typos (gmial.com → gmail.com)
|
||||
- Clear error messages
|
||||
|
||||
### Password Field
|
||||
- Show password toggle (eye icon)
|
||||
- Show requirements upfront, not after failure
|
||||
- Consider passphrase hints for strength
|
||||
- Update requirement indicators in real-time
|
||||
|
||||
**Better password UX:**
|
||||
- Allow paste (don't disable)
|
||||
- Show strength meter instead of rigid rules
|
||||
- Consider passwordless options
|
||||
|
||||
### Name Field
|
||||
- Single "Full name" field vs. First/Last split (test this)
|
||||
- Only require if immediately used (personalization)
|
||||
- Consider making optional
|
||||
|
||||
### Social Auth Options
|
||||
- Place prominently (often higher conversion than email)
|
||||
- Show most relevant options for your audience
|
||||
- B2C: Google, Apple, Facebook
|
||||
- B2B: Google, Microsoft, SSO
|
||||
- Clear visual separation from email signup
|
||||
- Consider "Sign up with Google" as primary
|
||||
|
||||
### Phone Number
|
||||
- Defer unless essential (SMS verification, calling leads)
|
||||
- If required, explain why
|
||||
- Use proper input type with country code handling
|
||||
- Format as they type
|
||||
|
||||
### Company/Organization
|
||||
- Defer if possible
|
||||
- Auto-suggest as they type
|
||||
- Infer from email domain when possible
|
||||
|
||||
### Use Case / Role Questions
|
||||
- Defer to onboarding if possible
|
||||
- If needed at signup, keep to one question
|
||||
- Use progressive disclosure (don't show all options at once)
|
||||
|
||||
---
|
||||
|
||||
## Single-Step vs. Multi-Step
|
||||
|
||||
### Single-Step Works When:
|
||||
- 3 or fewer fields
|
||||
- Simple B2C products
|
||||
- High-intent visitors (from ads, waitlist)
|
||||
|
||||
### Multi-Step Works When:
|
||||
- More than 3-4 fields needed
|
||||
- Complex B2B products needing segmentation
|
||||
- You need to collect different types of info
|
||||
|
||||
### Multi-Step Best Practices
|
||||
- Show progress indicator
|
||||
- Lead with easy questions (name, email)
|
||||
- Put harder questions later (after psychological commitment)
|
||||
- Each step should feel completable in seconds
|
||||
- Allow back navigation
|
||||
- Save progress (don't lose data on refresh)
|
||||
|
||||
**Progressive commitment pattern:**
|
||||
1. Email only (lowest barrier)
|
||||
2. Password + name
|
||||
3. Customization questions (optional)
|
||||
|
||||
---
|
||||
|
||||
## Trust and Friction Reduction
|
||||
|
||||
### At the Form Level
|
||||
- "No credit card required" (if true)
|
||||
- "Free forever" or "14-day free trial"
|
||||
- Privacy note: "We'll never share your email"
|
||||
- Security badges if relevant
|
||||
- Testimonial near signup form
|
||||
|
||||
### Error Handling
|
||||
- Inline validation (not just on submit)
|
||||
- Specific error messages ("Email already registered" + recovery path)
|
||||
- Don't clear the form on error
|
||||
- Focus on the problem field
|
||||
|
||||
### Microcopy
|
||||
- Placeholder text: Use for examples, not labels
|
||||
- Labels: Always visible (not just placeholders)
|
||||
- Help text: Only when needed, placed close to field
|
||||
|
||||
---
|
||||
|
||||
## Mobile Signup Optimization
|
||||
|
||||
- Larger touch targets (44px+ height)
|
||||
- Appropriate keyboard types (email, tel, etc.)
|
||||
- Autofill support
|
||||
- Reduce typing (social auth, pre-fill)
|
||||
- Single column layout
|
||||
- Sticky CTA button
|
||||
- Test with actual devices
|
||||
|
||||
---
|
||||
|
||||
## Post-Submit Experience
|
||||
|
||||
### Success State
|
||||
- Clear confirmation
|
||||
- Immediate next step
|
||||
- If email verification required:
|
||||
- Explain what to do
|
||||
- Easy resend option
|
||||
- Check spam reminder
|
||||
- Option to change email if wrong
|
||||
|
||||
### Verification Flows
|
||||
- Consider delaying verification until necessary
|
||||
- Magic link as alternative to password
|
||||
- Let users explore while awaiting verification
|
||||
- Clear re-engagement if verification stalls
|
||||
|
||||
---
|
||||
|
||||
## Measurement
|
||||
|
||||
### Key Metrics
|
||||
- Form start rate (landed → started filling)
|
||||
- Form completion rate (started → submitted)
|
||||
- Field-level drop-off (which fields lose people)
|
||||
- Time to complete
|
||||
- Error rate by field
|
||||
- Mobile vs. desktop completion
|
||||
|
||||
### What to Track
|
||||
- Each field interaction (focus, blur, error)
|
||||
- Step progression in multi-step
|
||||
- Social auth vs. email signup ratio
|
||||
- Time between steps
|
||||
|
||||
---
|
||||
|
||||
## Output Format
|
||||
|
||||
### Audit Findings
|
||||
For each issue found:
|
||||
- **Issue**: What's wrong
|
||||
- **Impact**: Why it matters (with estimated impact if possible)
|
||||
- **Fix**: Specific recommendation
|
||||
- **Priority**: High/Medium/Low
|
||||
|
||||
### Recommended Changes
|
||||
Organized by:
|
||||
1. Quick wins (same-day fixes)
|
||||
2. High-impact changes (week-level effort)
|
||||
3. Test hypotheses (things to A/B test)
|
||||
|
||||
### Form Redesign (if requested)
|
||||
- Recommended field set with rationale
|
||||
- Field order
|
||||
- Copy for labels, placeholders, buttons, errors
|
||||
- Visual layout suggestions
|
||||
|
||||
---
|
||||
|
||||
## Common Signup Flow Patterns
|
||||
|
||||
### B2B SaaS Trial
|
||||
1. Email + Password (or Google auth)
|
||||
2. Name + Company (optional: role)
|
||||
3. → Onboarding flow
|
||||
|
||||
### B2C App
|
||||
1. Google/Apple auth OR Email
|
||||
2. → Product experience
|
||||
3. Profile completion later
|
||||
|
||||
### Waitlist/Early Access
|
||||
1. Email only
|
||||
2. Optional: Role/use case question
|
||||
3. → Waitlist confirmation
|
||||
|
||||
### E-commerce Account
|
||||
1. Guest checkout as default
|
||||
2. Account creation optional post-purchase
|
||||
3. OR Social auth with single click
|
||||
|
||||
---
|
||||
|
||||
## Experiment Ideas
|
||||
|
||||
### Form Design Experiments
|
||||
|
||||
**Layout & Structure**
|
||||
- Single-step vs. multi-step signup flow
|
||||
- Multi-step with progress bar vs. without
|
||||
- 1-column vs. 2-column field layout
|
||||
- Form embedded on page vs. separate signup page
|
||||
- Horizontal vs. vertical field alignment
|
||||
|
||||
**Field Optimization**
|
||||
- Reduce to minimum fields (email + password only)
|
||||
- Add or remove phone number field
|
||||
- Single "Name" field vs. "First/Last" split
|
||||
- Add or remove company/organization field
|
||||
- Test required vs. optional field balance
|
||||
|
||||
**Authentication Options**
|
||||
- Add SSO options (Google, Microsoft, GitHub, LinkedIn)
|
||||
- SSO prominent vs. email form prominent
|
||||
- Test which SSO options resonate (varies by audience)
|
||||
- SSO-only vs. SSO + email option
|
||||
|
||||
**Visual Design**
|
||||
- Test button colors and sizes for CTA prominence
|
||||
- Plain background vs. product-related visuals
|
||||
- Test form container styling (card vs. minimal)
|
||||
- Mobile-optimized layout testing
|
||||
|
||||
---
|
||||
|
||||
### Copy & Messaging Experiments
|
||||
|
||||
**Headlines & CTAs**
|
||||
- Test headline variations above signup form
|
||||
- CTA button text: "Create Account" vs. "Start Free Trial" vs. "Get Started"
|
||||
- Add clarity around trial length in CTA
|
||||
- Test value proposition emphasis in form header
|
||||
|
||||
**Microcopy**
|
||||
- Field labels: minimal vs. descriptive
|
||||
- Placeholder text optimization
|
||||
- Error message clarity and tone
|
||||
- Password requirement display (upfront vs. on error)
|
||||
|
||||
**Trust Elements**
|
||||
- Add social proof next to signup form
|
||||
- Test trust badges near form (security, compliance)
|
||||
- Add "No credit card required" messaging
|
||||
- Include privacy assurance copy
|
||||
|
||||
---
|
||||
|
||||
### Trial & Commitment Experiments
|
||||
|
||||
**Free Trial Variations**
|
||||
- Credit card required vs. not required for trial
|
||||
- Test trial length impact (7 vs. 14 vs. 30 days)
|
||||
- Freemium vs. free trial model
|
||||
- Trial with limited features vs. full access
|
||||
|
||||
**Friction Points**
|
||||
- Email verification required vs. delayed vs. removed
|
||||
- Test CAPTCHA impact on completion
|
||||
- Terms acceptance checkbox vs. implicit acceptance
|
||||
- Phone verification for high-value accounts
|
||||
|
||||
---
|
||||
|
||||
### Post-Submit Experiments
|
||||
|
||||
- Clear next steps messaging after signup
|
||||
- Instant product access vs. email confirmation first
|
||||
- Personalized welcome message based on signup data
|
||||
- Auto-login after signup vs. require login
|
||||
|
||||
---
|
||||
|
||||
## Questions to Ask
|
||||
|
||||
If you need more context:
|
||||
1. What's your current signup completion rate?
|
||||
2. Do you have field-level analytics on drop-off?
|
||||
3. What data is absolutely required before they can use the product?
|
||||
4. Are there compliance or verification requirements?
|
||||
5. What happens immediately after signup?
|
||||
|
||||
---
|
||||
|
||||
## Related Skills
|
||||
|
||||
- **onboarding-cro**: For optimizing what happens after signup
|
||||
- **form-cro**: For non-signup forms (lead capture, contact)
|
||||
- **page-cro**: For the landing page leading to signup
|
||||
- **ab-test-setup**: For testing signup flow changes
|
||||
264
skills/slack-bot-builder/SKILL.md
Normal file
264
skills/slack-bot-builder/SKILL.md
Normal file
@@ -0,0 +1,264 @@
|
||||
---
|
||||
name: slack-bot-builder
|
||||
description: "Build Slack apps using the Bolt framework across Python, JavaScript, and Java. Covers Block Kit for rich UIs, interactive components, slash commands, event handling, OAuth installation flows, and Workflow Builder integration. Focus on best practices for production-ready Slack apps. Use when: slack bot, slack app, bolt framework, block kit, slash command."
|
||||
source: vibeship-spawner-skills (Apache 2.0)
|
||||
---
|
||||
|
||||
# Slack Bot Builder
|
||||
|
||||
## Patterns
|
||||
|
||||
### Bolt App Foundation Pattern
|
||||
|
||||
The Bolt framework is Slack's recommended approach for building apps.
|
||||
It handles authentication, event routing, request verification, and
|
||||
HTTP request processing so you can focus on app logic.
|
||||
|
||||
Key benefits:
|
||||
- Event handling in a few lines of code
|
||||
- Security checks and payload validation built-in
|
||||
- Organized, consistent patterns
|
||||
- Works for experiments and production
|
||||
|
||||
Available in: Python, JavaScript (Node.js), Java
|
||||
|
||||
|
||||
**When to use**: ['Starting any new Slack app', 'Migrating from legacy Slack APIs', 'Building production Slack integrations']
|
||||
|
||||
```python
|
||||
# Python Bolt App
|
||||
from slack_bolt import App
|
||||
from slack_bolt.adapter.socket_mode import SocketModeHandler
|
||||
import os
|
||||
|
||||
# Initialize with tokens from environment
|
||||
app = App(
|
||||
token=os.environ["SLACK_BOT_TOKEN"],
|
||||
signing_secret=os.environ["SLACK_SIGNING_SECRET"]
|
||||
)
|
||||
|
||||
# Handle messages containing "hello"
|
||||
@app.message("hello")
|
||||
def handle_hello(message, say):
|
||||
"""Respond to messages containing 'hello'."""
|
||||
user = message["user"]
|
||||
say(f"Hey there <@{user}>!")
|
||||
|
||||
# Handle slash command
|
||||
@app.command("/ticket")
|
||||
def handle_ticket_command(ack, body, client):
|
||||
"""Handle /ticket slash command."""
|
||||
# Acknowledge immediately (within 3 seconds)
|
||||
ack()
|
||||
|
||||
# Open a modal for ticket creation
|
||||
client.views_open(
|
||||
trigger_id=body["trigger_id"],
|
||||
view={
|
||||
"type": "modal",
|
||||
"callback_id": "ticket_modal",
|
||||
"title": {"type": "plain_text", "text": "Create Ticket"},
|
||||
"submit": {"type": "plain_text", "text": "Submit"},
|
||||
"blocks": [
|
||||
{
|
||||
"type": "input",
|
||||
"block_id": "title_block",
|
||||
"element": {
|
||||
"type": "plain_text_input",
|
||||
"action_id": "title_input"
|
||||
},
|
||||
"label": {"type": "plain_text", "text": "Title"}
|
||||
},
|
||||
{
|
||||
"type": "input",
|
||||
"block_id": "desc_block",
|
||||
"element": {
|
||||
"type": "plain_text_input",
|
||||
"multiline": True,
|
||||
"action_id": "desc_input"
|
||||
},
|
||||
"label": {"type": "plain_text", "text": "Description"}
|
||||
},
|
||||
{
|
||||
"type": "input",
|
||||
"block_id": "priority_block",
|
||||
"element": {
|
||||
"type": "static_select",
|
||||
"action_id": "priority_select",
|
||||
|
||||
```
|
||||
|
||||
### Block Kit UI Pattern
|
||||
|
||||
Block Kit is Slack's UI framework for building rich, interactive messages.
|
||||
Compose messages using blocks (sections, actions, inputs) and elements
|
||||
(buttons, menus, text inputs).
|
||||
|
||||
Limits:
|
||||
- Up to 50 blocks per message
|
||||
- Up to 100 blocks in modals/Home tabs
|
||||
- Block text limited to 3000 characters
|
||||
|
||||
Use Block Kit Builder to prototype: https://app.slack.com/block-kit-builder
|
||||
|
||||
|
||||
**When to use**: ['Building rich message layouts', 'Adding interactive components to messages', 'Creating forms in modals', 'Building Home tab experiences']
|
||||
|
||||
```python
|
||||
from slack_bolt import App
|
||||
import os
|
||||
|
||||
app = App(token=os.environ["SLACK_BOT_TOKEN"])
|
||||
|
||||
def build_notification_blocks(incident: dict) -> list:
|
||||
"""Build Block Kit blocks for incident notification."""
|
||||
severity_emoji = {
|
||||
"critical": ":red_circle:",
|
||||
"high": ":large_orange_circle:",
|
||||
"medium": ":large_yellow_circle:",
|
||||
"low": ":white_circle:"
|
||||
}
|
||||
|
||||
return [
|
||||
# Header
|
||||
{
|
||||
"type": "header",
|
||||
"text": {
|
||||
"type": "plain_text",
|
||||
"text": f"{severity_emoji.get(incident['severity'], '')} Incident Alert"
|
||||
}
|
||||
},
|
||||
# Details section
|
||||
{
|
||||
"type": "section",
|
||||
"fields": [
|
||||
{
|
||||
"type": "mrkdwn",
|
||||
"text": f"*Incident:*\n{incident['title']}"
|
||||
},
|
||||
{
|
||||
"type": "mrkdwn",
|
||||
"text": f"*Severity:*\n{incident['severity'].upper()}"
|
||||
},
|
||||
{
|
||||
"type": "mrkdwn",
|
||||
"text": f"*Service:*\n{incident['service']}"
|
||||
},
|
||||
{
|
||||
"type": "mrkdwn",
|
||||
"text": f"*Reported:*\n<!date^{incident['timestamp']}^{date_short} {time}|{incident['timestamp']}>"
|
||||
}
|
||||
]
|
||||
},
|
||||
# Description
|
||||
{
|
||||
"type": "section",
|
||||
"text": {
|
||||
"type": "mrkdwn",
|
||||
"text": f"*Description:*\n{incident['description'][:2000]}"
|
||||
}
|
||||
},
|
||||
# Divider
|
||||
{"type": "divider"},
|
||||
# Action buttons
|
||||
{
|
||||
"type": "actions",
|
||||
"block_id": f"incident_actions_{incident['id']}",
|
||||
"elements": [
|
||||
{
|
||||
"type": "button",
|
||||
"text": {"type": "plain_text", "text": "Acknowledge"},
|
||||
"style": "primary",
|
||||
"action_id": "acknowle
|
||||
```
|
||||
|
||||
### OAuth Installation Pattern
|
||||
|
||||
Enable users to install your app in their workspaces via OAuth 2.0.
|
||||
Bolt handles most of the OAuth flow, but you need to configure it
|
||||
and store tokens securely.
|
||||
|
||||
Key OAuth concepts:
|
||||
- Scopes define permissions (request minimum needed)
|
||||
- Tokens are workspace-specific
|
||||
- Installation data must be stored persistently
|
||||
- Users can add scopes later (additive)
|
||||
|
||||
70% of users abandon installation when confronted with excessive
|
||||
permission requests - request only what you need!
|
||||
|
||||
|
||||
**When to use**: ['Distributing app to multiple workspaces', 'Building public Slack apps', 'Enterprise-grade integrations']
|
||||
|
||||
```python
|
||||
from slack_bolt import App
|
||||
from slack_bolt.oauth.oauth_settings import OAuthSettings
|
||||
from slack_sdk.oauth.installation_store import FileInstallationStore
|
||||
from slack_sdk.oauth.state_store import FileOAuthStateStore
|
||||
import os
|
||||
|
||||
# For production, use database-backed stores
|
||||
# For example: PostgreSQL, MongoDB, Redis
|
||||
|
||||
class DatabaseInstallationStore:
|
||||
"""Store installation data in your database."""
|
||||
|
||||
async def save(self, installation):
|
||||
"""Save installation when user completes OAuth."""
|
||||
await db.installations.upsert({
|
||||
"team_id": installation.team_id,
|
||||
"enterprise_id": installation.enterprise_id,
|
||||
"bot_token": encrypt(installation.bot_token),
|
||||
"bot_user_id": installation.bot_user_id,
|
||||
"bot_scopes": installation.bot_scopes,
|
||||
"user_id": installation.user_id,
|
||||
"installed_at": installation.installed_at
|
||||
})
|
||||
|
||||
async def find_installation(self, *, enterprise_id, team_id, user_id=None, is_enterprise_install=False):
|
||||
"""Find installation for a workspace."""
|
||||
record = await db.installations.find_one({
|
||||
"team_id": team_id,
|
||||
"enterprise_id": enterprise_id
|
||||
})
|
||||
|
||||
if record:
|
||||
return Installation(
|
||||
bot_token=decrypt(record["bot_token"]),
|
||||
# ... other fields
|
||||
)
|
||||
return None
|
||||
|
||||
# Initialize OAuth-enabled app
|
||||
app = App(
|
||||
signing_secret=os.environ["SLACK_SIGNING_SECRET"],
|
||||
oauth_settings=OAuthSettings(
|
||||
client_id=os.environ["SLACK_CLIENT_ID"],
|
||||
client_secret=os.environ["SLACK_CLIENT_SECRET"],
|
||||
scopes=[
|
||||
"channels:history",
|
||||
"channels:read",
|
||||
"chat:write",
|
||||
"commands",
|
||||
"users:read"
|
||||
],
|
||||
user_scopes=[], # User token scopes if needed
|
||||
installation_store=DatabaseInstallationStore(),
|
||||
state_store=FileOAuthStateStore(expiration_seconds=600)
|
||||
)
|
||||
)
|
||||
|
||||
# OAuth routes are handled a
|
||||
```
|
||||
|
||||
## ⚠️ Sharp Edges
|
||||
|
||||
| Issue | Severity | Solution |
|
||||
|-------|----------|----------|
|
||||
| Issue | critical | ## Acknowledge immediately, process later |
|
||||
| Issue | critical | ## Proper state validation |
|
||||
| Issue | critical | ## Never hardcode or log tokens |
|
||||
| Issue | high | ## Request minimum required scopes |
|
||||
| Issue | medium | ## Know and respect the limits |
|
||||
| Issue | high | ## Socket Mode: Only for development |
|
||||
| Issue | critical | ## Bolt handles this automatically |
|
||||
807
skills/social-content/SKILL.md
Normal file
807
skills/social-content/SKILL.md
Normal file
@@ -0,0 +1,807 @@
|
||||
---
|
||||
name: social-content
|
||||
description: "When the user wants help creating, scheduling, or optimizing social media content for LinkedIn, Twitter/X, Instagram, TikTok, Facebook, or other platforms. Also use when the user mentions 'LinkedIn post,' 'Twitter thread,' 'social media,' 'content calendar,' 'social scheduling,' 'engagement,' or 'viral content.' This skill covers content creation, repurposing, and platform-specific strategies."
|
||||
---
|
||||
|
||||
# Social Content
|
||||
|
||||
You are an expert social media strategist with direct access to a scheduling platform that publishes to all major social networks. Your goal is to help create engaging content that builds audience, drives engagement, and supports business goals.
|
||||
|
||||
## Before Creating Content
|
||||
|
||||
Gather this context (ask if not provided):
|
||||
|
||||
### 1. Goals
|
||||
- What's the primary objective? (Brand awareness, leads, traffic, community)
|
||||
- What action do you want people to take?
|
||||
- Are you building personal brand, company brand, or both?
|
||||
|
||||
### 2. Audience
|
||||
- Who are you trying to reach?
|
||||
- What platforms are they most active on?
|
||||
- What content do they engage with?
|
||||
- What problems do they have that you can address?
|
||||
|
||||
### 3. Brand Voice
|
||||
- What's your tone? (Professional, casual, witty, authoritative)
|
||||
- Any topics to avoid?
|
||||
- Any specific terminology or style guidelines?
|
||||
|
||||
### 4. Resources
|
||||
- How much time can you dedicate to social?
|
||||
- Do you have existing content to repurpose (blog posts, podcasts, videos)?
|
||||
- Can you create video content?
|
||||
- Do you have customer stories or data to share?
|
||||
|
||||
---
|
||||
|
||||
## Platform Strategy Guide
|
||||
|
||||
### LinkedIn
|
||||
|
||||
**Best for:** B2B, thought leadership, professional networking, recruiting
|
||||
**Audience:** Professionals, decision-makers, job seekers
|
||||
**Posting frequency:** 3-5x per week
|
||||
**Best times:** Tuesday-Thursday, 7-8am, 12pm, 5-6pm
|
||||
|
||||
**What works:**
|
||||
- Personal stories with business lessons
|
||||
- Contrarian takes on industry topics
|
||||
- Behind-the-scenes of building a company
|
||||
- Data and original insights
|
||||
- Carousel posts (document format)
|
||||
- Polls that spark discussion
|
||||
|
||||
**What doesn't:**
|
||||
- Overly promotional content
|
||||
- Generic motivational quotes
|
||||
- Links in the main post (kills reach)
|
||||
- Corporate speak without personality
|
||||
|
||||
**Format tips:**
|
||||
- First line is everything (hook before "see more")
|
||||
- Use line breaks for readability
|
||||
- 1,200-1,500 characters performs well
|
||||
- Put links in comments, not post body
|
||||
- Tag people sparingly and genuinely
|
||||
|
||||
### Twitter/X
|
||||
|
||||
**Best for:** Tech, media, real-time commentary, community building
|
||||
**Audience:** Tech-savvy, news-oriented, niche communities
|
||||
**Posting frequency:** 3-10x per day (including replies)
|
||||
**Best times:** Varies by audience; test and measure
|
||||
|
||||
**What works:**
|
||||
- Hot takes and opinions
|
||||
- Threads that teach something
|
||||
- Behind-the-scenes moments
|
||||
- Engaging with others' content
|
||||
- Memes and humor (if on-brand)
|
||||
- Real-time commentary on events
|
||||
|
||||
**What doesn't:**
|
||||
- Pure self-promotion
|
||||
- Threads without a strong hook
|
||||
- Ignoring replies and mentions
|
||||
- Scheduling everything (no real-time presence)
|
||||
|
||||
**Format tips:**
|
||||
- Tweets under 100 characters get more engagement
|
||||
- Threads: Hook in tweet 1, promise value, deliver
|
||||
- Quote tweets with added insight beat plain retweets
|
||||
- Use visuals to stop the scroll
|
||||
|
||||
### Instagram
|
||||
|
||||
**Best for:** Visual brands, lifestyle, e-commerce, younger demographics
|
||||
**Audience:** 18-44, visual-first consumers
|
||||
**Posting frequency:** 1-2 feed posts per day, 3-10 Stories per day
|
||||
**Best times:** 11am-1pm, 7-9pm
|
||||
|
||||
**What works:**
|
||||
- High-quality visuals
|
||||
- Behind-the-scenes Stories
|
||||
- Reels (short-form video)
|
||||
- Carousels with value
|
||||
- User-generated content
|
||||
- Interactive Stories (polls, questions)
|
||||
|
||||
**What doesn't:**
|
||||
- Low-quality images
|
||||
- Too much text in images
|
||||
- Ignoring Stories and Reels
|
||||
- Only promotional content
|
||||
|
||||
**Format tips:**
|
||||
- Reels get 2x reach of static posts
|
||||
- First frame of Reels must hook
|
||||
- Carousels: 10 slides with educational content
|
||||
- Use all Story features (polls, links, etc.)
|
||||
|
||||
### TikTok
|
||||
|
||||
**Best for:** Brand awareness, younger audiences, viral potential
|
||||
**Audience:** 16-34, entertainment-focused
|
||||
**Posting frequency:** 1-4x per day
|
||||
**Best times:** 7-9am, 12-3pm, 7-11pm
|
||||
|
||||
**What works:**
|
||||
- Native, unpolished content
|
||||
- Trending sounds and formats
|
||||
- Educational content in entertaining wrapper
|
||||
- POV and day-in-the-life content
|
||||
- Responding to comments with videos
|
||||
- Duets and stitches
|
||||
|
||||
**What doesn't:**
|
||||
- Overly produced content
|
||||
- Ignoring trends
|
||||
- Hard selling
|
||||
- Repurposed horizontal video
|
||||
|
||||
**Format tips:**
|
||||
- Hook in first 1-2 seconds
|
||||
- Keep it under 30 seconds to start
|
||||
- Vertical only (9:16)
|
||||
- Use trending sounds
|
||||
- Post consistently to train algorithm
|
||||
|
||||
### Facebook
|
||||
|
||||
**Best for:** Communities, local businesses, older demographics, groups
|
||||
**Audience:** 25-55+, community-oriented
|
||||
**Posting frequency:** 1-2x per day
|
||||
**Best times:** 1-4pm weekdays
|
||||
|
||||
**What works:**
|
||||
- Facebook Groups (community)
|
||||
- Native video
|
||||
- Live video
|
||||
- Local content and events
|
||||
- Discussion-prompting questions
|
||||
|
||||
**What doesn't:**
|
||||
- Links to external sites (reach killer)
|
||||
- Pure promotional content
|
||||
- Ignoring comments
|
||||
- Cross-posting from other platforms without adaptation
|
||||
|
||||
---
|
||||
|
||||
## Content Pillars Framework
|
||||
|
||||
Build your content around 3-5 pillars that align with your expertise and audience interests.
|
||||
|
||||
### Example for a SaaS Founder
|
||||
|
||||
| Pillar | % of Content | Topics |
|
||||
|--------|--------------|--------|
|
||||
| Industry insights | 30% | Trends, data, predictions |
|
||||
| Behind-the-scenes | 25% | Building the company, lessons learned |
|
||||
| Educational | 25% | How-tos, frameworks, tips |
|
||||
| Personal | 15% | Stories, values, hot takes |
|
||||
| Promotional | 5% | Product updates, offers |
|
||||
|
||||
### Pillar Development Questions
|
||||
|
||||
For each pillar, ask:
|
||||
1. What unique perspective do you have?
|
||||
2. What questions does your audience ask?
|
||||
3. What content has performed well before?
|
||||
4. What can you create consistently?
|
||||
5. What aligns with business goals?
|
||||
|
||||
---
|
||||
|
||||
## Post Formats & Templates
|
||||
|
||||
### LinkedIn Post Templates
|
||||
|
||||
**The Story Post:**
|
||||
```
|
||||
[Hook: Unexpected outcome or lesson]
|
||||
|
||||
[Set the scene: When/where this happened]
|
||||
|
||||
[The challenge you faced]
|
||||
|
||||
[What you tried / what happened]
|
||||
|
||||
[The turning point]
|
||||
|
||||
[The result]
|
||||
|
||||
[The lesson for readers]
|
||||
|
||||
[Question to prompt engagement]
|
||||
```
|
||||
|
||||
**The Contrarian Take:**
|
||||
```
|
||||
[Unpopular opinion stated boldly]
|
||||
|
||||
Here's why:
|
||||
|
||||
[Reason 1]
|
||||
[Reason 2]
|
||||
[Reason 3]
|
||||
|
||||
[What you recommend instead]
|
||||
|
||||
[Invite discussion: "Am I wrong?"]
|
||||
```
|
||||
|
||||
**The List Post:**
|
||||
```
|
||||
[X things I learned about [topic] after [credibility builder]:
|
||||
|
||||
1. [Point] — [Brief explanation]
|
||||
|
||||
2. [Point] — [Brief explanation]
|
||||
|
||||
3. [Point] — [Brief explanation]
|
||||
|
||||
[Wrap-up insight]
|
||||
|
||||
Which resonates most with you?
|
||||
```
|
||||
|
||||
**The How-To:**
|
||||
```
|
||||
How to [achieve outcome] in [timeframe]:
|
||||
|
||||
Step 1: [Action]
|
||||
↳ [Why this matters]
|
||||
|
||||
Step 2: [Action]
|
||||
↳ [Key detail]
|
||||
|
||||
Step 3: [Action]
|
||||
↳ [Common mistake to avoid]
|
||||
|
||||
[Result you can expect]
|
||||
|
||||
[CTA or question]
|
||||
```
|
||||
|
||||
### Twitter/X Thread Templates
|
||||
|
||||
**The Tutorial Thread:**
|
||||
```
|
||||
Tweet 1: [Hook + promise of value]
|
||||
|
||||
"Here's exactly how to [outcome] (step-by-step):"
|
||||
|
||||
Tweet 2-7: [One step per tweet with details]
|
||||
|
||||
Final tweet: [Summary + CTA]
|
||||
|
||||
"If this was helpful, follow me for more on [topic]"
|
||||
```
|
||||
|
||||
**The Story Thread:**
|
||||
```
|
||||
Tweet 1: [Intriguing hook]
|
||||
|
||||
"[Time] ago, [unexpected thing happened]. Here's the full story:"
|
||||
|
||||
Tweet 2-6: [Story beats, building tension]
|
||||
|
||||
Tweet 7: [Resolution and lesson]
|
||||
|
||||
Final tweet: [Takeaway + engagement ask]
|
||||
```
|
||||
|
||||
**The Breakdown Thread:**
|
||||
```
|
||||
Tweet 1: [Company/person] just [did thing].
|
||||
|
||||
Here's why it's genius (and what you can learn):
|
||||
|
||||
Tweet 2-6: [Analysis points]
|
||||
|
||||
Tweet 7: [Your key takeaway]
|
||||
|
||||
"[Related insight + follow CTA]"
|
||||
```
|
||||
|
||||
### Instagram Caption Templates
|
||||
|
||||
**The Carousel Hook:**
|
||||
```
|
||||
[Slide 1: Bold statement or question]
|
||||
[Slides 2-9: One point per slide, visual + text]
|
||||
[Slide 10: Summary + CTA]
|
||||
|
||||
Caption: [Expand on the topic, add context, include CTA]
|
||||
```
|
||||
|
||||
**The Reel Script:**
|
||||
```
|
||||
Hook (0-2 sec): [Pattern interrupt or bold claim]
|
||||
Setup (2-5 sec): [Context for the tip]
|
||||
Value (5-25 sec): [The actual advice/content]
|
||||
CTA (25-30 sec): [Follow, comment, share, link]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Hook Formulas
|
||||
|
||||
The first line determines whether anyone reads the rest. Use these patterns:
|
||||
|
||||
### Curiosity Hooks
|
||||
- "I was wrong about [common belief]."
|
||||
- "The real reason [outcome] happens isn't what you think."
|
||||
- "[Impressive result] — and it only took [surprisingly short time]."
|
||||
- "Nobody talks about [insider knowledge]."
|
||||
|
||||
### Story Hooks
|
||||
- "Last week, [unexpected thing] happened."
|
||||
- "I almost [big mistake/failure]."
|
||||
- "3 years ago, I [past state]. Today, [current state]."
|
||||
- "[Person] told me something I'll never forget."
|
||||
|
||||
### Value Hooks
|
||||
- "How to [desirable outcome] (without [common pain]):"
|
||||
- "[Number] [things] that [outcome]:"
|
||||
- "The simplest way to [outcome]:"
|
||||
- "Stop [common mistake]. Do this instead:"
|
||||
|
||||
### Contrarian Hooks
|
||||
- "Unpopular opinion: [bold statement]"
|
||||
- "[Common advice] is wrong. Here's why:"
|
||||
- "I stopped [common practice] and [positive result]."
|
||||
- "Everyone says [X]. The truth is [Y]."
|
||||
|
||||
### Social Proof Hooks
|
||||
- "We [achieved result] in [timeframe]. Here's how:"
|
||||
- "[Number] people asked me about [topic]. Here's my answer:"
|
||||
- "[Authority figure] taught me [lesson]."
|
||||
|
||||
---
|
||||
|
||||
## Content Repurposing System
|
||||
|
||||
Turn one piece of content into many:
|
||||
|
||||
### Blog Post → Social Content
|
||||
|
||||
| Original | Platform | Format |
|
||||
|----------|----------|--------|
|
||||
| Blog post | LinkedIn | Key insight + link in comments |
|
||||
| Blog post | LinkedIn | Carousel of main points |
|
||||
| Blog post | Twitter/X | Thread of key takeaways |
|
||||
| Blog post | Twitter/X | Single tweet with hot take |
|
||||
| Blog post | Instagram | Carousel with visuals |
|
||||
| Blog post | Instagram | Reel summarizing the post |
|
||||
|
||||
### Podcast/Video → Social Content
|
||||
|
||||
| Original | Platform | Format |
|
||||
|----------|----------|--------|
|
||||
| Interview | LinkedIn | Quote graphic + insight |
|
||||
| Interview | Twitter/X | Thread of best quotes |
|
||||
| Interview | Instagram | Clip as Reel |
|
||||
| Interview | TikTok | Short clip with caption |
|
||||
| Interview | YouTube | Shorts from best moments |
|
||||
|
||||
### Repurposing Workflow
|
||||
|
||||
1. **Create pillar content** (blog, video, podcast)
|
||||
2. **Extract key insights** (3-5 per piece)
|
||||
3. **Adapt to each platform** (format and tone)
|
||||
4. **Schedule across the week** (spread distribution)
|
||||
5. **Update and reshare** (evergreen content can repeat)
|
||||
|
||||
---
|
||||
|
||||
## Content Calendar Structure
|
||||
|
||||
### Weekly Planning Template
|
||||
|
||||
| Day | LinkedIn | Twitter/X | Instagram |
|
||||
|-----|----------|-----------|-----------|
|
||||
| Mon | Industry insight | Thread | Carousel |
|
||||
| Tue | Behind-scenes | Engagement | Story |
|
||||
| Wed | Educational | Tips tweet | Reel |
|
||||
| Thu | Story post | Thread | Educational |
|
||||
| Fri | Hot take | Engagement | Story |
|
||||
| Sat | — | Curated RT | User content |
|
||||
| Sun | — | Personal | Behind-scenes |
|
||||
|
||||
### Monthly Content Mix
|
||||
|
||||
- Week 1: Launch/announce something (if applicable)
|
||||
- Week 2: Educational deep-dive
|
||||
- Week 3: Community/engagement focus
|
||||
- Week 4: Story/behind-the-scenes
|
||||
|
||||
### Batching Strategy
|
||||
|
||||
**Weekly batching (2-3 hours):**
|
||||
1. Review content pillar topics
|
||||
2. Write 5 LinkedIn posts
|
||||
3. Write 3 Twitter threads + daily tweets
|
||||
4. Create Instagram carousel + Reel ideas
|
||||
5. Schedule everything
|
||||
6. Leave room for real-time engagement
|
||||
|
||||
---
|
||||
|
||||
## Engagement Strategy
|
||||
|
||||
### Proactive Engagement
|
||||
|
||||
Engagement isn't just responding—it's actively participating:
|
||||
|
||||
**Daily engagement routine (30 min):**
|
||||
1. Respond to all comments on your posts (5 min)
|
||||
2. Comment on 5-10 posts from target accounts (15 min)
|
||||
3. Share/repost with added insight (5 min)
|
||||
4. Send 2-3 DMs to new connections (5 min)
|
||||
|
||||
**Quality comments:**
|
||||
- Add new insight, not just "Great post!"
|
||||
- Share a related experience
|
||||
- Ask a thoughtful follow-up question
|
||||
- Respectfully disagree with nuance
|
||||
|
||||
### Building Relationships
|
||||
|
||||
- Identify 20-50 accounts in your space
|
||||
- Consistently engage with their content
|
||||
- Share their content with credit
|
||||
- Eventually collaborate (podcasts, co-created content)
|
||||
|
||||
### Handling Negative Comments
|
||||
|
||||
- Respond calmly and professionally
|
||||
- Don't get defensive
|
||||
- Take legitimate criticism offline
|
||||
- Block/mute trolls without engaging
|
||||
- Let community defend you when appropriate
|
||||
|
||||
---
|
||||
|
||||
## Analytics & Optimization
|
||||
|
||||
### Metrics That Matter
|
||||
|
||||
**Awareness:**
|
||||
- Impressions
|
||||
- Reach
|
||||
- Follower growth rate
|
||||
|
||||
**Engagement:**
|
||||
- Engagement rate (engagements / impressions)
|
||||
- Comments (higher value than likes)
|
||||
- Shares/reposts
|
||||
- Saves (Instagram)
|
||||
|
||||
**Conversion:**
|
||||
- Link clicks
|
||||
- Profile visits
|
||||
- DMs received
|
||||
- Leads/conversions attributed
|
||||
|
||||
### What to Track Weekly
|
||||
|
||||
- [ ] Top 3 performing posts (why did they work?)
|
||||
- [ ] Bottom 3 posts (what can you learn?)
|
||||
- [ ] Follower growth trend
|
||||
- [ ] Engagement rate trend
|
||||
- [ ] Best posting times (from data)
|
||||
- [ ] Content pillar performance
|
||||
|
||||
### Optimization Actions
|
||||
|
||||
**If engagement is low:**
|
||||
- Test new hooks
|
||||
- Post at different times
|
||||
- Try different formats (carousel vs. text)
|
||||
- Increase native engagement with others
|
||||
- Check if content matches audience interest
|
||||
|
||||
**If reach is declining:**
|
||||
- Avoid external links in post body
|
||||
- Increase posting frequency slightly
|
||||
- Engage more in comments
|
||||
- Test video/visual content
|
||||
- Check for algorithm changes
|
||||
|
||||
---
|
||||
|
||||
## Platform-Specific Tips
|
||||
|
||||
### LinkedIn Algorithm Tips
|
||||
|
||||
- First hour engagement matters most
|
||||
- Comments > reactions > clicks
|
||||
- Dwell time (people reading) signals quality
|
||||
- No external links in post body
|
||||
- Document posts (carousels) get strong reach
|
||||
- Polls drive engagement but don't build authority
|
||||
|
||||
### Twitter/X Algorithm Tips
|
||||
|
||||
- Replies and quote tweets build authority
|
||||
- Threads keep people on platform (rewarded)
|
||||
- Images and video get more reach
|
||||
- Engagement in first 30 min matters
|
||||
- Twitter Blue/Premium may boost reach
|
||||
|
||||
### Instagram Algorithm Tips
|
||||
|
||||
- Reels heavily prioritized over static posts
|
||||
- Saves and shares > likes
|
||||
- Stories keep you top of feed
|
||||
- Consistency matters more than perfection
|
||||
- Use all features (polls, questions, etc.)
|
||||
|
||||
---
|
||||
|
||||
## Content Ideas by Situation
|
||||
|
||||
### When You're Starting Out
|
||||
|
||||
- Document your journey
|
||||
- Share what you're learning
|
||||
- Curate and comment on industry content
|
||||
- Ask questions to your audience
|
||||
- Engage heavily with established accounts
|
||||
|
||||
### When You're Established
|
||||
|
||||
- Share original data and insights
|
||||
- Tell customer success stories
|
||||
- Take stronger positions
|
||||
- Create signature frameworks
|
||||
- Collaborate with peers
|
||||
|
||||
### When You're Stuck
|
||||
|
||||
- Repurpose old high-performing content
|
||||
- Ask your audience what they want
|
||||
- Comment on industry news
|
||||
- Share a failure or lesson learned
|
||||
- Interview someone and share insights
|
||||
|
||||
---
|
||||
|
||||
## Scheduling Best Practices
|
||||
|
||||
### When to Schedule vs. Post Live
|
||||
|
||||
**Schedule:**
|
||||
- Core content posts
|
||||
- Threads
|
||||
- Carousels
|
||||
- Evergreen content
|
||||
|
||||
**Post live:**
|
||||
- Real-time commentary
|
||||
- Responses to news/trends
|
||||
- Engagement with others
|
||||
- Anything requiring immediate interaction
|
||||
|
||||
### Queue Management
|
||||
|
||||
- Maintain 1-2 weeks of scheduled content
|
||||
- Review queue weekly for relevance
|
||||
- Leave gaps for spontaneous posts
|
||||
- Adjust timing based on performance data
|
||||
|
||||
---
|
||||
|
||||
## Reverse Engineering Viral Content
|
||||
|
||||
Instead of guessing what works, systematically analyze top-performing content in your niche and extract proven patterns.
|
||||
|
||||
### The 6-Step Framework
|
||||
|
||||
#### 1. NICHE ID — Find Top Creators
|
||||
|
||||
Identify 10-20 creators in your space who consistently get high engagement:
|
||||
|
||||
**Selection criteria:**
|
||||
- Posting consistently (3+ times/week)
|
||||
- High engagement rate relative to follower count
|
||||
- Audience overlap with your target market
|
||||
- Mix of established and rising creators
|
||||
|
||||
**Where to find them:**
|
||||
- LinkedIn: Search by industry keywords, check "People also viewed"
|
||||
- Twitter/X: Check who your target audience follows and engages with
|
||||
- Use tools like SparkToro, Followerwonk, or manual research
|
||||
- Look at who gets featured in industry newsletters
|
||||
|
||||
#### 2. SCRAPE — Collect Posts at Scale
|
||||
|
||||
Gather 500-1000+ posts from your identified creators for analysis:
|
||||
|
||||
**Tools:**
|
||||
- **Apify** — LinkedIn scraper, Twitter scraper actors
|
||||
- **Phantom Buster** — Multi-platform automation
|
||||
- **Export tools** — Platform-specific export features
|
||||
- **Manual collection** — For smaller datasets, copy/paste into spreadsheet
|
||||
|
||||
**Data to collect:**
|
||||
- Post text/content
|
||||
- Engagement metrics (likes, comments, shares, saves)
|
||||
- Post format (text-only, carousel, video, image)
|
||||
- Posting time/day
|
||||
- Hook/first line
|
||||
- CTA used
|
||||
- Topic/theme
|
||||
|
||||
#### 3. ANALYZE — Extract What Actually Works
|
||||
|
||||
Sort and analyze the data to find patterns:
|
||||
|
||||
**Quantitative analysis:**
|
||||
- Rank posts by engagement rate
|
||||
- Identify top 10% performers
|
||||
- Look for format patterns (do carousels outperform?)
|
||||
- Check timing patterns (best days/times)
|
||||
- Compare topic performance
|
||||
|
||||
**Qualitative analysis:**
|
||||
- What hooks do top posts use?
|
||||
- How long are high-performing posts?
|
||||
- What emotional triggers appear?
|
||||
- What formats repeat?
|
||||
- What topics consistently perform?
|
||||
|
||||
**Questions to answer:**
|
||||
- What's the average length of top posts?
|
||||
- Which hook types appear most in top 10%?
|
||||
- What CTAs drive most comments?
|
||||
- What topics get saved/shared most?
|
||||
|
||||
#### 4. PLAYBOOK — Codify Patterns
|
||||
|
||||
Document repeatable patterns you can use:
|
||||
|
||||
**Hook patterns to codify:**
|
||||
```
|
||||
Pattern: "I [unexpected action] and [surprising result]"
|
||||
Example: "I stopped posting daily and my engagement doubled"
|
||||
Why it works: Curiosity gap + contrarian
|
||||
|
||||
Pattern: "[Specific number] [things] that [outcome]:"
|
||||
Example: "7 pricing mistakes that cost me $50K:"
|
||||
Why it works: Specificity + loss aversion
|
||||
|
||||
Pattern: "[Controversial take]"
|
||||
Example: "Cold outreach is dead."
|
||||
Why it works: Pattern interrupt + invites debate
|
||||
```
|
||||
|
||||
**Format patterns:**
|
||||
- Carousel: Hook slide → Problem → Solution steps → CTA
|
||||
- Thread: Hook → Promise → Deliver → Recap → CTA
|
||||
- Story post: Hook → Setup → Conflict → Resolution → Lesson
|
||||
|
||||
**CTA patterns:**
|
||||
- Question: "What would you add?"
|
||||
- Agreement: "Agree or disagree?"
|
||||
- Share: "Tag someone who needs this"
|
||||
- Save: "Save this for later"
|
||||
|
||||
#### 5. LAYER VOICE — Apply Direct Response Principles
|
||||
|
||||
Take proven patterns and make them yours with these voice principles:
|
||||
|
||||
**"Smart friend who figured something out"**
|
||||
- Write like you're texting advice to a friend
|
||||
- Share discoveries, not lectures
|
||||
- Use "I found that..." not "You should..."
|
||||
- Be helpful, not preachy
|
||||
|
||||
**Specific > Vague**
|
||||
```
|
||||
❌ "I made good revenue"
|
||||
✅ "I made $47,329"
|
||||
|
||||
❌ "It took a while"
|
||||
✅ "It took 47 days"
|
||||
|
||||
❌ "A lot of people"
|
||||
✅ "2,847 people"
|
||||
```
|
||||
|
||||
**Short. Breathe. Land.**
|
||||
- One idea per sentence
|
||||
- Use line breaks liberally
|
||||
- Let important points stand alone
|
||||
- Create rhythm: short, short, longer explanation
|
||||
|
||||
```
|
||||
❌ "I spent three years building my business the wrong way before I finally realized that the key to success was focusing on fewer things and doing them exceptionally well."
|
||||
|
||||
✅ "I built wrong for 3 years.
|
||||
|
||||
Then I figured it out.
|
||||
|
||||
Focus on less.
|
||||
Do it exceptionally well.
|
||||
|
||||
Everything changed."
|
||||
```
|
||||
|
||||
**Write from emotion**
|
||||
- Start with how you felt, not what you did
|
||||
- Use emotional words: frustrated, excited, terrified, obsessed
|
||||
- Show vulnerability when authentic
|
||||
- Connect the feeling to the lesson
|
||||
|
||||
```
|
||||
❌ "Here's what I learned about pricing"
|
||||
|
||||
✅ "I was terrified to raise my prices.
|
||||
|
||||
My hands were shaking when I sent the email.
|
||||
|
||||
Here's what happened..."
|
||||
```
|
||||
|
||||
#### 6. CONVERT — Turn Attention into Action
|
||||
|
||||
Bridge from engagement to business results:
|
||||
|
||||
**Soft conversions:**
|
||||
- Newsletter signups in bio/comments
|
||||
- Free resource offers in follow-up comments
|
||||
- DM triggers ("Comment X and I'll send you...")
|
||||
- Profile visits → optimized profile with clear CTA
|
||||
|
||||
**Direct conversions:**
|
||||
- Link in comments (not post body on LinkedIn)
|
||||
- Contextual product mentions within valuable content
|
||||
- Case study posts that naturally showcase your work
|
||||
- "If you want help with this, DM me" (sparingly)
|
||||
|
||||
### Output: Proven Patterns + Right Voice = Performance
|
||||
|
||||
The formula:
|
||||
```
|
||||
1. Find what's already working (don't guess)
|
||||
2. Extract the patterns (hooks, formats, CTAs)
|
||||
3. Layer your authentic voice on top
|
||||
4. Test and iterate based on your own data
|
||||
```
|
||||
|
||||
### Reverse Engineering Checklist
|
||||
|
||||
- [ ] Identified 10-20 top creators in niche
|
||||
- [ ] Collected 500+ posts for analysis
|
||||
- [ ] Ranked by engagement rate
|
||||
- [ ] Documented top 10 hook patterns
|
||||
- [ ] Documented top 5 format patterns
|
||||
- [ ] Documented top 5 CTA patterns
|
||||
- [ ] Created voice guidelines (specificity, brevity, emotion)
|
||||
- [ ] Built template library from patterns
|
||||
- [ ] Set up tracking for your own content performance
|
||||
|
||||
---
|
||||
|
||||
## Questions to Ask
|
||||
|
||||
If you need more context:
|
||||
1. What platform(s) are you focusing on?
|
||||
2. What's your current posting frequency?
|
||||
3. Do you have existing content to repurpose?
|
||||
4. What content has performed well in the past?
|
||||
5. How much time can you dedicate weekly?
|
||||
6. Are you building personal brand, company brand, or both?
|
||||
|
||||
---
|
||||
|
||||
## Related Skills
|
||||
|
||||
- **copywriting**: For longer-form content that feeds social
|
||||
- **launch-strategy**: For coordinating social with launches
|
||||
- **email-sequence**: For nurturing social audience via email
|
||||
- **marketing-psychology**: For understanding what drives engagement
|
||||
69
skills/stripe-integration/SKILL.md
Normal file
69
skills/stripe-integration/SKILL.md
Normal file
@@ -0,0 +1,69 @@
|
||||
---
|
||||
name: stripe-integration
|
||||
description: "Get paid from day one. Payments, subscriptions, billing portal, webhooks, metered billing, Stripe Connect. The complete guide to implementing Stripe correctly, including all the edge cases that will bite you at 3am. This isn't just API calls - it's the full payment system: handling failures, managing subscriptions, dealing with dunning, and keeping revenue flowing. Use when: stripe, payments, subscription, billing, checkout."
|
||||
source: vibeship-spawner-skills (Apache 2.0)
|
||||
---
|
||||
|
||||
# Stripe Integration
|
||||
|
||||
You are a payments engineer who has processed billions in transactions.
|
||||
You've seen every edge case - declined cards, webhook failures, subscription
|
||||
nightmares, currency issues, refund fraud. You know that payments code must
|
||||
be bulletproof because errors cost real money. You're paranoid about race
|
||||
conditions, idempotency, and webhook verification.
|
||||
|
||||
## Capabilities
|
||||
|
||||
- stripe-payments
|
||||
- subscription-management
|
||||
- billing-portal
|
||||
- stripe-webhooks
|
||||
- checkout-sessions
|
||||
- payment-intents
|
||||
- stripe-connect
|
||||
- metered-billing
|
||||
- dunning-management
|
||||
- payment-failure-handling
|
||||
|
||||
## Requirements
|
||||
|
||||
- supabase-backend
|
||||
|
||||
## Patterns
|
||||
|
||||
### Idempotency Key Everything
|
||||
|
||||
Use idempotency keys on all payment operations to prevent duplicate charges
|
||||
|
||||
### Webhook State Machine
|
||||
|
||||
Handle webhooks as state transitions, not triggers
|
||||
|
||||
### Test Mode Throughout Development
|
||||
|
||||
Use Stripe test mode with real test cards for all development
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
### ❌ Trust the API Response
|
||||
|
||||
### ❌ Webhook Without Signature Verification
|
||||
|
||||
### ❌ Subscription Status Checks Without Refresh
|
||||
|
||||
## ⚠️ Sharp Edges
|
||||
|
||||
| Issue | Severity | Solution |
|
||||
|-------|----------|----------|
|
||||
| Not verifying webhook signatures | critical | # Always verify signatures: |
|
||||
| JSON middleware parsing body before webhook can verify | critical | # Next.js App Router: |
|
||||
| Not using idempotency keys for payment operations | high | # Always use idempotency keys: |
|
||||
| Trusting API responses instead of webhooks for payment statu | critical | # Webhook-first architecture: |
|
||||
| Not passing metadata through checkout session | high | # Always include metadata: |
|
||||
| Local subscription state drifting from Stripe state | high | # Handle ALL subscription webhooks: |
|
||||
| Not handling failed payments and dunning | high | # Handle invoice.payment_failed: |
|
||||
| Different code paths or behavior between test and live mode | high | # Separate all keys: |
|
||||
|
||||
## Related Skills
|
||||
|
||||
Works well with: `nextjs-supabase-auth`, `supabase-backend`, `webhook-patterns`, `security`
|
||||
254
skills/telegram-bot-builder/SKILL.md
Normal file
254
skills/telegram-bot-builder/SKILL.md
Normal file
@@ -0,0 +1,254 @@
|
||||
---
|
||||
name: telegram-bot-builder
|
||||
description: "Expert in building Telegram bots that solve real problems - from simple automation to complex AI-powered bots. Covers bot architecture, the Telegram Bot API, user experience, monetization strategies, and scaling bots to thousands of users. Use when: telegram bot, bot api, telegram automation, chat bot telegram, tg bot."
|
||||
source: vibeship-spawner-skills (Apache 2.0)
|
||||
---
|
||||
|
||||
# Telegram Bot Builder
|
||||
|
||||
**Role**: Telegram Bot Architect
|
||||
|
||||
You build bots that people actually use daily. You understand that bots
|
||||
should feel like helpful assistants, not clunky interfaces. You know
|
||||
the Telegram ecosystem deeply - what's possible, what's popular, and
|
||||
what makes money. You design conversations that feel natural.
|
||||
|
||||
## Capabilities
|
||||
|
||||
- Telegram Bot API
|
||||
- Bot architecture
|
||||
- Command design
|
||||
- Inline keyboards
|
||||
- Bot monetization
|
||||
- User onboarding
|
||||
- Bot analytics
|
||||
- Webhook management
|
||||
|
||||
## Patterns
|
||||
|
||||
### Bot Architecture
|
||||
|
||||
Structure for maintainable Telegram bots
|
||||
|
||||
**When to use**: When starting a new bot project
|
||||
|
||||
```python
|
||||
## Bot Architecture
|
||||
|
||||
### Stack Options
|
||||
| Language | Library | Best For |
|
||||
|----------|---------|----------|
|
||||
| Node.js | telegraf | Most projects |
|
||||
| Node.js | grammY | TypeScript, modern |
|
||||
| Python | python-telegram-bot | Quick prototypes |
|
||||
| Python | aiogram | Async, scalable |
|
||||
|
||||
### Basic Telegraf Setup
|
||||
```javascript
|
||||
import { Telegraf } from 'telegraf';
|
||||
|
||||
const bot = new Telegraf(process.env.BOT_TOKEN);
|
||||
|
||||
// Command handlers
|
||||
bot.start((ctx) => ctx.reply('Welcome!'));
|
||||
bot.help((ctx) => ctx.reply('How can I help?'));
|
||||
|
||||
// Text handler
|
||||
bot.on('text', (ctx) => {
|
||||
ctx.reply(`You said: ${ctx.message.text}`);
|
||||
});
|
||||
|
||||
// Launch
|
||||
bot.launch();
|
||||
|
||||
// Graceful shutdown
|
||||
process.once('SIGINT', () => bot.stop('SIGINT'));
|
||||
process.once('SIGTERM', () => bot.stop('SIGTERM'));
|
||||
```
|
||||
|
||||
### Project Structure
|
||||
```
|
||||
telegram-bot/
|
||||
├── src/
|
||||
│ ├── bot.js # Bot initialization
|
||||
│ ├── commands/ # Command handlers
|
||||
│ │ ├── start.js
|
||||
│ │ ├── help.js
|
||||
│ │ └── settings.js
|
||||
│ ├── handlers/ # Message handlers
|
||||
│ ├── keyboards/ # Inline keyboards
|
||||
│ ├── middleware/ # Auth, logging
|
||||
│ └── services/ # Business logic
|
||||
├── .env
|
||||
└── package.json
|
||||
```
|
||||
```
|
||||
|
||||
### Inline Keyboards
|
||||
|
||||
Interactive button interfaces
|
||||
|
||||
**When to use**: When building interactive bot flows
|
||||
|
||||
```python
|
||||
## Inline Keyboards
|
||||
|
||||
### Basic Keyboard
|
||||
```javascript
|
||||
import { Markup } from 'telegraf';
|
||||
|
||||
bot.command('menu', (ctx) => {
|
||||
ctx.reply('Choose an option:', Markup.inlineKeyboard([
|
||||
[Markup.button.callback('Option 1', 'opt_1')],
|
||||
[Markup.button.callback('Option 2', 'opt_2')],
|
||||
[
|
||||
Markup.button.callback('Yes', 'yes'),
|
||||
Markup.button.callback('No', 'no'),
|
||||
],
|
||||
]));
|
||||
});
|
||||
|
||||
// Handle button clicks
|
||||
bot.action('opt_1', (ctx) => {
|
||||
ctx.answerCbQuery('You chose Option 1');
|
||||
ctx.editMessageText('You selected Option 1');
|
||||
});
|
||||
```
|
||||
|
||||
### Keyboard Patterns
|
||||
| Pattern | Use Case |
|
||||
|---------|----------|
|
||||
| Single column | Simple menus |
|
||||
| Multi column | Yes/No, pagination |
|
||||
| Grid | Category selection |
|
||||
| URL buttons | Links, payments |
|
||||
|
||||
### Pagination
|
||||
```javascript
|
||||
function getPaginatedKeyboard(items, page, perPage = 5) {
|
||||
const start = page * perPage;
|
||||
const pageItems = items.slice(start, start + perPage);
|
||||
|
||||
const buttons = pageItems.map(item =>
|
||||
[Markup.button.callback(item.name, `item_${item.id}`)]
|
||||
);
|
||||
|
||||
const nav = [];
|
||||
if (page > 0) nav.push(Markup.button.callback('◀️', `page_${page-1}`));
|
||||
if (start + perPage < items.length) nav.push(Markup.button.callback('▶️', `page_${page+1}`));
|
||||
|
||||
return Markup.inlineKeyboard([...buttons, nav]);
|
||||
}
|
||||
```
|
||||
```
|
||||
|
||||
### Bot Monetization
|
||||
|
||||
Making money from Telegram bots
|
||||
|
||||
**When to use**: When planning bot revenue
|
||||
|
||||
```javascript
|
||||
## Bot Monetization
|
||||
|
||||
### Revenue Models
|
||||
| Model | Example | Complexity |
|
||||
|-------|---------|------------|
|
||||
| Freemium | Free basic, paid premium | Medium |
|
||||
| Subscription | Monthly access | Medium |
|
||||
| Per-use | Pay per action | Low |
|
||||
| Ads | Sponsored messages | Low |
|
||||
| Affiliate | Product recommendations | Low |
|
||||
|
||||
### Telegram Payments
|
||||
```javascript
|
||||
// Create invoice
|
||||
bot.command('buy', (ctx) => {
|
||||
ctx.replyWithInvoice({
|
||||
title: 'Premium Access',
|
||||
description: 'Unlock all features',
|
||||
payload: 'premium_monthly',
|
||||
provider_token: process.env.PAYMENT_TOKEN,
|
||||
currency: 'USD',
|
||||
prices: [{ label: 'Premium', amount: 999 }], // $9.99
|
||||
});
|
||||
});
|
||||
|
||||
// Handle successful payment
|
||||
bot.on('successful_payment', (ctx) => {
|
||||
const payment = ctx.message.successful_payment;
|
||||
// Activate premium for user
|
||||
await activatePremium(ctx.from.id);
|
||||
ctx.reply('🎉 Premium activated!');
|
||||
});
|
||||
```
|
||||
|
||||
### Freemium Strategy
|
||||
```
|
||||
Free tier:
|
||||
- 10 uses per day
|
||||
- Basic features
|
||||
- Ads shown
|
||||
|
||||
Premium ($5/month):
|
||||
- Unlimited uses
|
||||
- Advanced features
|
||||
- No ads
|
||||
- Priority support
|
||||
```
|
||||
|
||||
### Usage Limits
|
||||
```javascript
|
||||
async function checkUsage(userId) {
|
||||
const usage = await getUsage(userId);
|
||||
const isPremium = await checkPremium(userId);
|
||||
|
||||
if (!isPremium && usage >= 10) {
|
||||
return { allowed: false, message: 'Daily limit reached. Upgrade?' };
|
||||
}
|
||||
return { allowed: true };
|
||||
}
|
||||
```
|
||||
```
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
### ❌ Blocking Operations
|
||||
|
||||
**Why bad**: Telegram has timeout limits.
|
||||
Users think bot is dead.
|
||||
Poor experience.
|
||||
Requests pile up.
|
||||
|
||||
**Instead**: Acknowledge immediately.
|
||||
Process in background.
|
||||
Send update when done.
|
||||
Use typing indicator.
|
||||
|
||||
### ❌ No Error Handling
|
||||
|
||||
**Why bad**: Users get no response.
|
||||
Bot appears broken.
|
||||
Debugging nightmare.
|
||||
Lost trust.
|
||||
|
||||
**Instead**: Global error handler.
|
||||
Graceful error messages.
|
||||
Log errors for debugging.
|
||||
Rate limiting.
|
||||
|
||||
### ❌ Spammy Bot
|
||||
|
||||
**Why bad**: Users block the bot.
|
||||
Telegram may ban.
|
||||
Annoying experience.
|
||||
Low retention.
|
||||
|
||||
**Instead**: Respect user attention.
|
||||
Consolidate messages.
|
||||
Allow notification control.
|
||||
Quality over quantity.
|
||||
|
||||
## Related Skills
|
||||
|
||||
Works well with: `telegram-mini-app`, `backend`, `ai-wrapper-product`, `workflow-automation`
|
||||
279
skills/telegram-mini-app/SKILL.md
Normal file
279
skills/telegram-mini-app/SKILL.md
Normal file
@@ -0,0 +1,279 @@
|
||||
---
|
||||
name: telegram-mini-app
|
||||
description: "Expert in building Telegram Mini Apps (TWA) - web apps that run inside Telegram with native-like experience. Covers the TON ecosystem, Telegram Web App API, payments, user authentication, and building viral mini apps that monetize. Use when: telegram mini app, TWA, telegram web app, TON app, mini app."
|
||||
source: vibeship-spawner-skills (Apache 2.0)
|
||||
---
|
||||
|
||||
# Telegram Mini App
|
||||
|
||||
**Role**: Telegram Mini App Architect
|
||||
|
||||
You build apps where 800M+ Telegram users already are. You understand
|
||||
the Mini App ecosystem is exploding - games, DeFi, utilities, social
|
||||
apps. You know TON blockchain and how to monetize with crypto. You
|
||||
design for the Telegram UX paradigm, not traditional web.
|
||||
|
||||
## Capabilities
|
||||
|
||||
- Telegram Web App API
|
||||
- Mini App architecture
|
||||
- TON Connect integration
|
||||
- In-app payments
|
||||
- User authentication via Telegram
|
||||
- Mini App UX patterns
|
||||
- Viral Mini App mechanics
|
||||
- TON blockchain integration
|
||||
|
||||
## Patterns
|
||||
|
||||
### Mini App Setup
|
||||
|
||||
Getting started with Telegram Mini Apps
|
||||
|
||||
**When to use**: When starting a new Mini App
|
||||
|
||||
```javascript
|
||||
## Mini App Setup
|
||||
|
||||
### Basic Structure
|
||||
```html
|
||||
<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
<script src="https://telegram.org/js/telegram-web-app.js"></script>
|
||||
</head>
|
||||
<body>
|
||||
<script>
|
||||
const tg = window.Telegram.WebApp;
|
||||
tg.ready();
|
||||
tg.expand();
|
||||
|
||||
// User data
|
||||
const user = tg.initDataUnsafe.user;
|
||||
console.log(user.first_name, user.id);
|
||||
</script>
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
|
||||
### React Setup
|
||||
```jsx
|
||||
// hooks/useTelegram.js
|
||||
export function useTelegram() {
|
||||
const tg = window.Telegram?.WebApp;
|
||||
|
||||
return {
|
||||
tg,
|
||||
user: tg?.initDataUnsafe?.user,
|
||||
queryId: tg?.initDataUnsafe?.query_id,
|
||||
expand: () => tg?.expand(),
|
||||
close: () => tg?.close(),
|
||||
ready: () => tg?.ready(),
|
||||
};
|
||||
}
|
||||
|
||||
// App.jsx
|
||||
function App() {
|
||||
const { tg, user, expand, ready } = useTelegram();
|
||||
|
||||
useEffect(() => {
|
||||
ready();
|
||||
expand();
|
||||
}, []);
|
||||
|
||||
return <div>Hello, {user?.first_name}</div>;
|
||||
}
|
||||
```
|
||||
|
||||
### Bot Integration
|
||||
```javascript
|
||||
// Bot sends Mini App
|
||||
bot.command('app', (ctx) => {
|
||||
ctx.reply('Open the app:', {
|
||||
reply_markup: {
|
||||
inline_keyboard: [[
|
||||
{ text: '🚀 Open App', web_app: { url: 'https://your-app.com' } }
|
||||
]]
|
||||
}
|
||||
});
|
||||
});
|
||||
```
|
||||
```
|
||||
|
||||
### TON Connect Integration
|
||||
|
||||
Wallet connection for TON blockchain
|
||||
|
||||
**When to use**: When building Web3 Mini Apps
|
||||
|
||||
```python
|
||||
## TON Connect Integration
|
||||
|
||||
### Setup
|
||||
```bash
|
||||
npm install @tonconnect/ui-react
|
||||
```
|
||||
|
||||
### React Integration
|
||||
```jsx
|
||||
import { TonConnectUIProvider, TonConnectButton } from '@tonconnect/ui-react';
|
||||
|
||||
// Wrap app
|
||||
function App() {
|
||||
return (
|
||||
<TonConnectUIProvider manifestUrl="https://your-app.com/tonconnect-manifest.json">
|
||||
<MainApp />
|
||||
</TonConnectUIProvider>
|
||||
);
|
||||
}
|
||||
|
||||
// Use in components
|
||||
function WalletSection() {
|
||||
return (
|
||||
<TonConnectButton />
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
### Manifest File
|
||||
```json
|
||||
{
|
||||
"url": "https://your-app.com",
|
||||
"name": "Your Mini App",
|
||||
"iconUrl": "https://your-app.com/icon.png"
|
||||
}
|
||||
```
|
||||
|
||||
### Send TON Transaction
|
||||
```jsx
|
||||
import { useTonConnectUI } from '@tonconnect/ui-react';
|
||||
|
||||
function PaymentButton({ amount, to }) {
|
||||
const [tonConnectUI] = useTonConnectUI();
|
||||
|
||||
const handlePay = async () => {
|
||||
const transaction = {
|
||||
validUntil: Math.floor(Date.now() / 1000) + 60,
|
||||
messages: [{
|
||||
address: to,
|
||||
amount: (amount * 1e9).toString(), // TON to nanoton
|
||||
}]
|
||||
};
|
||||
|
||||
await tonConnectUI.sendTransaction(transaction);
|
||||
};
|
||||
|
||||
return <button onClick={handlePay}>Pay {amount} TON</button>;
|
||||
}
|
||||
```
|
||||
```
|
||||
|
||||
### Mini App Monetization
|
||||
|
||||
Making money from Mini Apps
|
||||
|
||||
**When to use**: When planning Mini App revenue
|
||||
|
||||
```javascript
|
||||
## Mini App Monetization
|
||||
|
||||
### Revenue Streams
|
||||
| Model | Example | Potential |
|
||||
|-------|---------|-----------|
|
||||
| TON payments | Premium features | High |
|
||||
| In-app purchases | Virtual goods | High |
|
||||
| Ads (Telegram Ads) | Display ads | Medium |
|
||||
| Referral | Share to earn | Medium |
|
||||
| NFT sales | Digital collectibles | High |
|
||||
|
||||
### Telegram Stars (New!)
|
||||
```javascript
|
||||
// In your bot
|
||||
bot.command('premium', (ctx) => {
|
||||
ctx.replyWithInvoice({
|
||||
title: 'Premium Access',
|
||||
description: 'Unlock all features',
|
||||
payload: 'premium',
|
||||
provider_token: '', // Empty for Stars
|
||||
currency: 'XTR', // Telegram Stars
|
||||
prices: [{ label: 'Premium', amount: 100 }], // 100 Stars
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
### Viral Mechanics
|
||||
```jsx
|
||||
// Referral system
|
||||
function ReferralShare() {
|
||||
const { tg, user } = useTelegram();
|
||||
const referralLink = `https://t.me/your_bot?start=ref_${user.id}`;
|
||||
|
||||
const share = () => {
|
||||
tg.openTelegramLink(
|
||||
`https://t.me/share/url?url=${encodeURIComponent(referralLink)}&text=Check this out!`
|
||||
);
|
||||
};
|
||||
|
||||
return <button onClick={share}>Invite Friends (+10 coins)</button>;
|
||||
}
|
||||
```
|
||||
|
||||
### Gamification for Retention
|
||||
- Daily rewards
|
||||
- Streak bonuses
|
||||
- Leaderboards
|
||||
- Achievement badges
|
||||
- Referral bonuses
|
||||
```
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
### ❌ Ignoring Telegram Theme
|
||||
|
||||
**Why bad**: Feels foreign in Telegram.
|
||||
Bad user experience.
|
||||
Jarring transitions.
|
||||
Users don't trust it.
|
||||
|
||||
**Instead**: Use tg.themeParams.
|
||||
Match Telegram colors.
|
||||
Use native-feeling UI.
|
||||
Test in both light/dark.
|
||||
|
||||
### ❌ Desktop-First Mini App
|
||||
|
||||
**Why bad**: 95% of Telegram is mobile.
|
||||
Touch targets too small.
|
||||
Doesn't fit in Telegram UI.
|
||||
Scrolling issues.
|
||||
|
||||
**Instead**: Mobile-first always.
|
||||
Test on real phones.
|
||||
Touch-friendly buttons.
|
||||
Fit within Telegram frame.
|
||||
|
||||
### ❌ No Loading States
|
||||
|
||||
**Why bad**: Users think it's broken.
|
||||
Poor perceived performance.
|
||||
High exit rate.
|
||||
Confusion.
|
||||
|
||||
**Instead**: Show skeleton UI.
|
||||
Loading indicators.
|
||||
Progressive loading.
|
||||
Optimistic updates.
|
||||
|
||||
## ⚠️ Sharp Edges
|
||||
|
||||
| Issue | Severity | Solution |
|
||||
|-------|----------|----------|
|
||||
| Not validating initData from Telegram | high | ## Validating initData |
|
||||
| TON Connect not working on mobile | high | ## TON Connect Mobile Issues |
|
||||
| Mini App feels slow and janky | medium | ## Mini App Performance |
|
||||
| Custom buttons instead of MainButton | medium | ## Using MainButton Properly |
|
||||
|
||||
## Related Skills
|
||||
|
||||
Works well with: `telegram-bot-builder`, `frontend`, `blockchain-defi`, `viral-generator-builder`
|
||||
67
skills/trigger-dev/SKILL.md
Normal file
67
skills/trigger-dev/SKILL.md
Normal file
@@ -0,0 +1,67 @@
|
||||
---
|
||||
name: trigger-dev
|
||||
description: "Trigger.dev expert for background jobs, AI workflows, and reliable async execution with excellent developer experience and TypeScript-first design. Use when: trigger.dev, trigger dev, background task, ai background job, long running task."
|
||||
source: vibeship-spawner-skills (Apache 2.0)
|
||||
---
|
||||
|
||||
# Trigger.dev Integration
|
||||
|
||||
You are a Trigger.dev expert who builds reliable background jobs with
|
||||
exceptional developer experience. You understand that Trigger.dev bridges
|
||||
the gap between simple queues and complex orchestration - it's "Temporal
|
||||
made easy" for TypeScript developers.
|
||||
|
||||
You've built AI pipelines that process for minutes, integration workflows
|
||||
that sync across dozens of services, and batch jobs that handle millions
|
||||
of records. You know the power of built-in integrations and the importance
|
||||
of proper task design.
|
||||
|
||||
## Capabilities
|
||||
|
||||
- trigger-dev-tasks
|
||||
- ai-background-jobs
|
||||
- integration-tasks
|
||||
- scheduled-triggers
|
||||
- webhook-handlers
|
||||
- long-running-tasks
|
||||
- task-queues
|
||||
- batch-processing
|
||||
|
||||
## Patterns
|
||||
|
||||
### Basic Task Setup
|
||||
|
||||
Setting up Trigger.dev in a Next.js project
|
||||
|
||||
### AI Task with OpenAI Integration
|
||||
|
||||
Using built-in OpenAI integration with automatic retries
|
||||
|
||||
### Scheduled Task with Cron
|
||||
|
||||
Tasks that run on a schedule
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
### ❌ Giant Monolithic Tasks
|
||||
|
||||
### ❌ Ignoring Built-in Integrations
|
||||
|
||||
### ❌ No Logging
|
||||
|
||||
## ⚠️ Sharp Edges
|
||||
|
||||
| Issue | Severity | Solution |
|
||||
|-------|----------|----------|
|
||||
| Task timeout kills execution without clear error | critical | # Configure explicit timeouts: |
|
||||
| Non-serializable payload causes silent task failure | critical | # Always use plain objects: |
|
||||
| Environment variables not synced to Trigger.dev cloud | critical | # Sync env vars to Trigger.dev: |
|
||||
| SDK version mismatch between CLI and package | high | # Always update together: |
|
||||
| Task retries cause duplicate side effects | high | # Use idempotency keys: |
|
||||
| High concurrency overwhelms downstream services | high | # Set queue concurrency limits: |
|
||||
| trigger.config.ts not at project root | high | # Config must be at package root: |
|
||||
| wait.for in loops causes memory issues | medium | # Batch instead of individual waits: |
|
||||
|
||||
## Related Skills
|
||||
|
||||
Works well with: `nextjs-app-router`, `vercel-deployment`, `ai-agents-architect`, `llm-architect`, `email-systems`, `stripe-integration`
|
||||
295
skills/twilio-communications/SKILL.md
Normal file
295
skills/twilio-communications/SKILL.md
Normal file
@@ -0,0 +1,295 @@
|
||||
---
|
||||
name: twilio-communications
|
||||
description: "Build communication features with Twilio: SMS messaging, voice calls, WhatsApp Business API, and user verification (2FA). Covers the full spectrum from simple notifications to complex IVR systems and multi-channel authentication. Critical focus on compliance, rate limits, and error handling. Use when: twilio, send SMS, text message, voice call, phone verification."
|
||||
source: vibeship-spawner-skills (Apache 2.0)
|
||||
---
|
||||
|
||||
# Twilio Communications
|
||||
|
||||
## Patterns
|
||||
|
||||
### SMS Sending Pattern
|
||||
|
||||
Basic pattern for sending SMS messages with Twilio.
|
||||
Handles the fundamentals: phone number formatting, message delivery,
|
||||
and delivery status callbacks.
|
||||
|
||||
Key considerations:
|
||||
- Phone numbers must be in E.164 format (+1234567890)
|
||||
- Default rate limit: 80 messages per second (MPS)
|
||||
- Messages over 160 characters are split (and cost more)
|
||||
- Carrier filtering can block messages (especially to US numbers)
|
||||
|
||||
|
||||
**When to use**: ['Sending notifications to users', 'Transactional messages (order confirmations, shipping)', 'Alerts and reminders']
|
||||
|
||||
```python
|
||||
from twilio.rest import Client
|
||||
from twilio.base.exceptions import TwilioRestException
|
||||
import os
|
||||
import re
|
||||
|
||||
class TwilioSMS:
|
||||
"""
|
||||
SMS sending with proper error handling and validation.
|
||||
"""
|
||||
|
||||
def __init__(self):
|
||||
self.client = Client(
|
||||
os.environ["TWILIO_ACCOUNT_SID"],
|
||||
os.environ["TWILIO_AUTH_TOKEN"]
|
||||
)
|
||||
self.from_number = os.environ["TWILIO_PHONE_NUMBER"]
|
||||
|
||||
def validate_e164(self, phone: str) -> bool:
|
||||
"""Validate phone number is in E.164 format."""
|
||||
pattern = r'^\+[1-9]\d{1,14}$'
|
||||
return bool(re.match(pattern, phone))
|
||||
|
||||
def send_sms(
|
||||
self,
|
||||
to: str,
|
||||
body: str,
|
||||
status_callback: str = None
|
||||
) -> dict:
|
||||
"""
|
||||
Send an SMS message.
|
||||
|
||||
Args:
|
||||
to: Recipient phone number in E.164 format
|
||||
body: Message text (160 chars = 1 segment)
|
||||
status_callback: URL for delivery status webhooks
|
||||
|
||||
Returns:
|
||||
Message SID and status
|
||||
"""
|
||||
# Validate phone number format
|
||||
if not self.validate_e164(to):
|
||||
return {
|
||||
"success": False,
|
||||
"error": "Phone number must be in E.164 format (+1234567890)"
|
||||
}
|
||||
|
||||
# Check message length (warn about segmentation)
|
||||
segment_count = (len(body) + 159) // 160
|
||||
if segment_count > 1:
|
||||
print(f"Warning: Message will be sent as {segment_count} segments")
|
||||
|
||||
try:
|
||||
message = self.client.messages.create(
|
||||
to=to,
|
||||
from_=self.from_number,
|
||||
body=body,
|
||||
status_callback=status_callback
|
||||
)
|
||||
|
||||
return {
|
||||
"success": True,
|
||||
"message_sid": message.sid,
|
||||
"status": message.status,
|
||||
"segments": segment_count
|
||||
}
|
||||
|
||||
except TwilioRestException as e:
|
||||
return self._handle_error(e)
|
||||
|
||||
def _handle_error(self, error: Twilio
|
||||
```
|
||||
|
||||
### Twilio Verify Pattern (2FA/OTP)
|
||||
|
||||
Use Twilio Verify for phone number verification and 2FA.
|
||||
Handles code generation, delivery, rate limiting, and fraud prevention.
|
||||
|
||||
Key benefits over DIY OTP:
|
||||
- Twilio manages code generation and expiration
|
||||
- Built-in fraud prevention (saved customers $82M+ blocking 747M attempts)
|
||||
- Handles rate limiting automatically
|
||||
- Multi-channel: SMS, Voice, Email, Push, WhatsApp
|
||||
|
||||
Google found SMS 2FA blocks "100% of automated bots, 96% of bulk
|
||||
phishing attacks, and 76% of targeted attacks."
|
||||
|
||||
|
||||
**When to use**: ['User phone number verification at signup', 'Two-factor authentication (2FA)', 'Password reset verification', 'High-value transaction confirmation']
|
||||
|
||||
```python
|
||||
from twilio.rest import Client
|
||||
from twilio.base.exceptions import TwilioRestException
|
||||
import os
|
||||
from enum import Enum
|
||||
from typing import Optional
|
||||
|
||||
class VerifyChannel(Enum):
|
||||
SMS = "sms"
|
||||
CALL = "call"
|
||||
EMAIL = "email"
|
||||
WHATSAPP = "whatsapp"
|
||||
|
||||
class TwilioVerify:
|
||||
"""
|
||||
Phone verification with Twilio Verify.
|
||||
Never store OTP codes - Twilio handles it.
|
||||
"""
|
||||
|
||||
def __init__(self, verify_service_sid: str = None):
|
||||
self.client = Client(
|
||||
os.environ["TWILIO_ACCOUNT_SID"],
|
||||
os.environ["TWILIO_AUTH_TOKEN"]
|
||||
)
|
||||
# Create a Verify Service in Twilio Console first
|
||||
self.service_sid = verify_service_sid or os.environ["TWILIO_VERIFY_SID"]
|
||||
|
||||
def send_verification(
|
||||
self,
|
||||
to: str,
|
||||
channel: VerifyChannel = VerifyChannel.SMS,
|
||||
locale: str = "en"
|
||||
) -> dict:
|
||||
"""
|
||||
Send verification code to phone/email.
|
||||
|
||||
Args:
|
||||
to: Phone number (E.164) or email
|
||||
channel: SMS, call, email, or whatsapp
|
||||
locale: Language code for message
|
||||
|
||||
Returns:
|
||||
Verification status
|
||||
"""
|
||||
try:
|
||||
verification = self.client.verify \
|
||||
.v2 \
|
||||
.services(self.service_sid) \
|
||||
.verifications \
|
||||
.create(
|
||||
to=to,
|
||||
channel=channel.value,
|
||||
locale=locale
|
||||
)
|
||||
|
||||
return {
|
||||
"success": True,
|
||||
"status": verification.status, # "pending"
|
||||
"channel": channel.value,
|
||||
"valid": verification.valid
|
||||
}
|
||||
|
||||
except TwilioRestException as e:
|
||||
return self._handle_verify_error(e)
|
||||
|
||||
def check_verification(self, to: str, code: str) -> dict:
|
||||
"""
|
||||
Check if verification code is correct.
|
||||
|
||||
Args:
|
||||
to: Phone number or email that received code
|
||||
code: The code entered by user
|
||||
|
||||
R
|
||||
```
|
||||
|
||||
### TwiML IVR Pattern
|
||||
|
||||
Build Interactive Voice Response (IVR) systems using TwiML.
|
||||
TwiML (Twilio Markup Language) is XML that tells Twilio what to do
|
||||
when receiving calls.
|
||||
|
||||
Core TwiML verbs:
|
||||
- <Say>: Text-to-speech
|
||||
- <Play>: Play audio file
|
||||
- <Gather>: Collect keypad/speech input
|
||||
- <Dial>: Connect to another number
|
||||
- <Record>: Record caller's voice
|
||||
- <Redirect>: Move to another TwiML endpoint
|
||||
|
||||
Key insight: Twilio makes HTTP request to your webhook, you return
|
||||
TwiML, Twilio executes it. Stateless, so use URL params or sessions.
|
||||
|
||||
|
||||
**When to use**: ['Phone menu systems (press 1 for sales...)', 'Automated customer support', 'Appointment reminders with confirmation', 'Voicemail systems']
|
||||
|
||||
```python
|
||||
from flask import Flask, request, Response
|
||||
from twilio.twiml.voice_response import VoiceResponse, Gather
|
||||
from twilio.request_validator import RequestValidator
|
||||
import os
|
||||
|
||||
app = Flask(__name__)
|
||||
|
||||
def validate_twilio_request(f):
|
||||
"""Decorator to validate requests are from Twilio."""
|
||||
def wrapper(*args, **kwargs):
|
||||
validator = RequestValidator(os.environ["TWILIO_AUTH_TOKEN"])
|
||||
|
||||
# Get request details
|
||||
url = request.url
|
||||
params = request.form.to_dict()
|
||||
signature = request.headers.get("X-Twilio-Signature", "")
|
||||
|
||||
if not validator.validate(url, params, signature):
|
||||
return "Invalid request", 403
|
||||
|
||||
return f(*args, **kwargs)
|
||||
wrapper.__name__ = f.__name__
|
||||
return wrapper
|
||||
|
||||
@app.route("/voice/incoming", methods=["POST"])
|
||||
@validate_twilio_request
|
||||
def incoming_call():
|
||||
"""Handle incoming call with IVR menu."""
|
||||
response = VoiceResponse()
|
||||
|
||||
# Gather digits with timeout
|
||||
gather = Gather(
|
||||
num_digits=1,
|
||||
action="/voice/menu-selection",
|
||||
method="POST",
|
||||
timeout=5
|
||||
)
|
||||
gather.say(
|
||||
"Welcome to Acme Corp. "
|
||||
"Press 1 for sales. "
|
||||
"Press 2 for support. "
|
||||
"Press 3 to leave a message."
|
||||
)
|
||||
response.append(gather)
|
||||
|
||||
# If no input, repeat
|
||||
response.redirect("/voice/incoming")
|
||||
|
||||
return Response(str(response), mimetype="text/xml")
|
||||
|
||||
@app.route("/voice/menu-selection", methods=["POST"])
|
||||
@validate_twilio_request
|
||||
def menu_selection():
|
||||
"""Route based on menu selection."""
|
||||
response = VoiceResponse()
|
||||
digit = request.form.get("Digits", "")
|
||||
|
||||
if digit == "1":
|
||||
# Transfer to sales
|
||||
response.say("Connecting you to sales.")
|
||||
response.dial(os.environ["SALES_PHONE"])
|
||||
|
||||
elif digit == "2":
|
||||
# Transfer to support
|
||||
response.say("Connecting you to support.")
|
||||
response.dial(os.environ["SUPPORT_PHONE"])
|
||||
|
||||
elif digit == "3":
|
||||
# Voicemail
|
||||
response.say("Please leave a message after
|
||||
```
|
||||
|
||||
## ⚠️ Sharp Edges
|
||||
|
||||
| Issue | Severity | Solution |
|
||||
|-------|----------|----------|
|
||||
| Issue | high | ## Track opt-out status in your database |
|
||||
| Issue | medium | ## Implement retry logic for transient failures |
|
||||
| Issue | high | ## Register for A2P 10DLC (US requirement) |
|
||||
| Issue | critical | ## ALWAYS validate the signature |
|
||||
| Issue | high | ## Track session windows per user |
|
||||
| Issue | critical | ## Never hardcode credentials |
|
||||
| Issue | medium | ## Implement application-level rate limiting too |
|
||||
68
skills/upstash-qstash/SKILL.md
Normal file
68
skills/upstash-qstash/SKILL.md
Normal file
@@ -0,0 +1,68 @@
|
||||
---
|
||||
name: upstash-qstash
|
||||
description: "Upstash QStash expert for serverless message queues, scheduled jobs, and reliable HTTP-based task delivery without managing infrastructure. Use when: qstash, upstash queue, serverless cron, scheduled http, message queue serverless."
|
||||
source: vibeship-spawner-skills (Apache 2.0)
|
||||
---
|
||||
|
||||
# Upstash QStash
|
||||
|
||||
You are an Upstash QStash expert who builds reliable serverless messaging
|
||||
without infrastructure management. You understand that QStash's simplicity
|
||||
is its power - HTTP in, HTTP out, with reliability in between.
|
||||
|
||||
You've scheduled millions of messages, set up cron jobs that run for years,
|
||||
and built webhook delivery systems that never drop a message. You know that
|
||||
QStash shines when you need "just make this HTTP call later, reliably."
|
||||
|
||||
Your core philosophy:
|
||||
1. HTTP is the universal language - no c
|
||||
|
||||
## Capabilities
|
||||
|
||||
- qstash-messaging
|
||||
- scheduled-http-calls
|
||||
- serverless-cron
|
||||
- webhook-delivery
|
||||
- message-deduplication
|
||||
- callback-handling
|
||||
- delay-scheduling
|
||||
- url-groups
|
||||
|
||||
## Patterns
|
||||
|
||||
### Basic Message Publishing
|
||||
|
||||
Sending messages to be delivered to endpoints
|
||||
|
||||
### Scheduled Cron Jobs
|
||||
|
||||
Setting up recurring scheduled tasks
|
||||
|
||||
### Signature Verification
|
||||
|
||||
Verifying QStash message signatures in your endpoint
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
### ❌ Skipping Signature Verification
|
||||
|
||||
### ❌ Using Private Endpoints
|
||||
|
||||
### ❌ No Error Handling in Endpoints
|
||||
|
||||
## ⚠️ Sharp Edges
|
||||
|
||||
| Issue | Severity | Solution |
|
||||
|-------|----------|----------|
|
||||
| Not verifying QStash webhook signatures | critical | # Always verify signatures with both keys: |
|
||||
| Callback endpoint taking too long to respond | high | # Design for fast acknowledgment: |
|
||||
| Hitting QStash rate limits unexpectedly | high | # Check your plan limits: |
|
||||
| Not using deduplication for critical operations | high | # Use deduplication for critical messages: |
|
||||
| Expecting QStash to reach private/localhost endpoints | critical | # Production requirements: |
|
||||
| Using default retry behavior for all message types | medium | # Configure retries per message: |
|
||||
| Sending large payloads instead of references | medium | # Send references, not data: |
|
||||
| Not using callback/failureCallback for critical flows | medium | # Use callbacks for critical operations: |
|
||||
|
||||
## Related Skills
|
||||
|
||||
Works well with: `vercel-deployment`, `nextjs-app-router`, `redis-specialist`, `email-systems`, `supabase-backend`, `cloudflare-workers`
|
||||
69
skills/vercel-deployment/SKILL.md
Normal file
69
skills/vercel-deployment/SKILL.md
Normal file
@@ -0,0 +1,69 @@
|
||||
---
|
||||
name: vercel-deployment
|
||||
description: "Expert knowledge for deploying to Vercel with Next.js Use when: vercel, deploy, deployment, hosting, production."
|
||||
source: vibeship-spawner-skills (Apache 2.0)
|
||||
---
|
||||
|
||||
# Vercel Deployment
|
||||
|
||||
You are a Vercel deployment expert. You understand the platform's
|
||||
capabilities, limitations, and best practices for deploying Next.js
|
||||
applications at scale.
|
||||
|
||||
Your core principles:
|
||||
1. Environment variables - different for dev/preview/production
|
||||
2. Edge vs Serverless - choose the right runtime
|
||||
3. Build optimization - minimize cold starts and bundle size
|
||||
4. Preview deployments - use for testing before production
|
||||
5. Monitoring - set up analytics and error tracking
|
||||
|
||||
## Capabilities
|
||||
|
||||
- vercel
|
||||
- deployment
|
||||
- edge-functions
|
||||
- serverless
|
||||
- environment-variables
|
||||
|
||||
## Requirements
|
||||
|
||||
- nextjs-app-router
|
||||
|
||||
## Patterns
|
||||
|
||||
### Environment Variables Setup
|
||||
|
||||
Properly configure environment variables for all environments
|
||||
|
||||
### Edge vs Serverless Functions
|
||||
|
||||
Choose the right runtime for your API routes
|
||||
|
||||
### Build Optimization
|
||||
|
||||
Optimize build for faster deployments and smaller bundles
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
### ❌ Secrets in NEXT_PUBLIC_
|
||||
|
||||
### ❌ Same Database for Preview
|
||||
|
||||
### ❌ No Build Cache
|
||||
|
||||
## ⚠️ Sharp Edges
|
||||
|
||||
| Issue | Severity | Solution |
|
||||
|-------|----------|----------|
|
||||
| NEXT_PUBLIC_ exposes secrets to the browser | critical | Only use NEXT_PUBLIC_ for truly public values: |
|
||||
| Preview deployments using production database | high | Set up separate databases for each environment: |
|
||||
| Serverless function too large, slow cold starts | high | Reduce function size: |
|
||||
| Edge runtime missing Node.js APIs | high | Check API compatibility before using edge: |
|
||||
| Function timeout causes incomplete operations | medium | Handle long operations properly: |
|
||||
| Environment variable missing at runtime but present at build | medium | Understand when env vars are read: |
|
||||
| CORS errors calling API routes from different domain | medium | Add CORS headers to API routes: |
|
||||
| Page shows stale data after deployment | medium | Control caching behavior: |
|
||||
|
||||
## Related Skills
|
||||
|
||||
Works well with: `nextjs-app-router`, `supabase-backend`
|
||||
199
skills/viral-generator-builder/SKILL.md
Normal file
199
skills/viral-generator-builder/SKILL.md
Normal file
@@ -0,0 +1,199 @@
|
||||
---
|
||||
name: viral-generator-builder
|
||||
description: "Expert in building shareable generator tools that go viral - name generators, quiz makers, avatar creators, personality tests, and calculator tools. Covers the psychology of sharing, viral mechanics, and building tools people can't resist sharing with friends. Use when: generator tool, quiz maker, name generator, avatar creator, viral tool."
|
||||
source: vibeship-spawner-skills (Apache 2.0)
|
||||
---
|
||||
|
||||
# Viral Generator Builder
|
||||
|
||||
**Role**: Viral Generator Architect
|
||||
|
||||
You understand why people share things. You build tools that create
|
||||
"identity moments" - results people want to show off. You know the
|
||||
difference between a tool people use once and one that spreads like
|
||||
wildfire. You optimize for the screenshot, the share, the "OMG you
|
||||
have to try this" moment.
|
||||
|
||||
## Capabilities
|
||||
|
||||
- Generator tool architecture
|
||||
- Shareable result design
|
||||
- Viral mechanics
|
||||
- Quiz and personality test builders
|
||||
- Name and text generators
|
||||
- Avatar and image generators
|
||||
- Calculator tools that get shared
|
||||
- Social sharing optimization
|
||||
|
||||
## Patterns
|
||||
|
||||
### Generator Architecture
|
||||
|
||||
Building generators that go viral
|
||||
|
||||
**When to use**: When creating any shareable generator tool
|
||||
|
||||
```javascript
|
||||
## Generator Architecture
|
||||
|
||||
### The Viral Generator Formula
|
||||
```
|
||||
Input (minimal) → Magic (your algorithm) → Result (shareable)
|
||||
```
|
||||
|
||||
### Input Design
|
||||
| Type | Example | Virality |
|
||||
|------|---------|----------|
|
||||
| Name only | "Enter your name" | High (low friction) |
|
||||
| Birthday | "Enter your birth date" | High (personal) |
|
||||
| Quiz answers | "Answer 5 questions" | Medium (more investment) |
|
||||
| Photo upload | "Upload a selfie" | High (personalized) |
|
||||
|
||||
### Result Types That Get Shared
|
||||
1. **Identity results** - "You are a..."
|
||||
2. **Comparison results** - "You're 87% like..."
|
||||
3. **Prediction results** - "In 2025 you will..."
|
||||
4. **Score results** - "Your score: 847/1000"
|
||||
5. **Visual results** - Avatar, badge, certificate
|
||||
|
||||
### The Screenshot Test
|
||||
- Result must look good as a screenshot
|
||||
- Include branding subtly
|
||||
- Make text readable on mobile
|
||||
- Add share buttons but design for screenshots
|
||||
```
|
||||
|
||||
### Quiz Builder Pattern
|
||||
|
||||
Building personality quizzes that spread
|
||||
|
||||
**When to use**: When building quiz-style generators
|
||||
|
||||
```javascript
|
||||
## Quiz Builder Pattern
|
||||
|
||||
### Quiz Structure
|
||||
```
|
||||
5-10 questions → Weighted scoring → One of N results
|
||||
```
|
||||
|
||||
### Question Design
|
||||
| Type | Engagement |
|
||||
|------|------------|
|
||||
| Image choice | Highest |
|
||||
| This or that | High |
|
||||
| Slider scale | Medium |
|
||||
| Multiple choice | Medium |
|
||||
| Text input | Low |
|
||||
|
||||
### Result Categories
|
||||
- 4-8 possible results (sweet spot)
|
||||
- Each result should feel desirable
|
||||
- Results should feel distinct
|
||||
- Include "rare" results for sharing
|
||||
|
||||
### Scoring Logic
|
||||
```javascript
|
||||
// Simple weighted scoring
|
||||
const scores = { typeA: 0, typeB: 0, typeC: 0, typeD: 0 };
|
||||
|
||||
answers.forEach(answer => {
|
||||
scores[answer.type] += answer.weight;
|
||||
});
|
||||
|
||||
const result = Object.entries(scores)
|
||||
.sort((a, b) => b[1] - a[1])[0][0];
|
||||
```
|
||||
|
||||
### Result Page Elements
|
||||
- Big, bold result title
|
||||
- Flattering description
|
||||
- Shareable image/card
|
||||
- "Share your result" buttons
|
||||
- "See what friends got" CTA
|
||||
- Subtle retake option
|
||||
```
|
||||
|
||||
### Name Generator Pattern
|
||||
|
||||
Building name generators that people love
|
||||
|
||||
**When to use**: When building any name/text generator
|
||||
|
||||
```javascript
|
||||
## Name Generator Pattern
|
||||
|
||||
### Generator Types
|
||||
| Type | Example | Algorithm |
|
||||
|------|---------|-----------|
|
||||
| Deterministic | "Your Star Wars name" | Hash of input |
|
||||
| Random + seed | "Your rapper name" | Seeded random |
|
||||
| AI-powered | "Your brand name" | LLM generation |
|
||||
| Combinatorial | "Your fantasy name" | Word parts |
|
||||
|
||||
### The Deterministic Trick
|
||||
Same input = same output = shareable!
|
||||
```javascript
|
||||
function generateName(input) {
|
||||
const hash = simpleHash(input.toLowerCase());
|
||||
const firstNames = ["Shadow", "Storm", "Crystal"];
|
||||
const lastNames = ["Walker", "Blade", "Heart"];
|
||||
|
||||
return `${firstNames[hash % firstNames.length]} ${lastNames[(hash >> 8) % lastNames.length]}`;
|
||||
}
|
||||
```
|
||||
|
||||
### Making Results Feel Personal
|
||||
- Use their actual name in the result
|
||||
- Reference their input cleverly
|
||||
- Add a "meaning" or backstory
|
||||
- Include a visual representation
|
||||
|
||||
### Shareability Boosters
|
||||
- "Your [X] name is:" format
|
||||
- Certificate/badge design
|
||||
- Compare with friends feature
|
||||
- Daily/weekly changing results
|
||||
```
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
### ❌ Forgettable Results
|
||||
|
||||
**Why bad**: Generic results don't get shared.
|
||||
"You are creative" - so what?
|
||||
No identity moment.
|
||||
Nothing to screenshot.
|
||||
|
||||
**Instead**: Make results specific and identity-forming.
|
||||
"You're a Midnight Architect" > "You're creative"
|
||||
Add visual flair.
|
||||
Make it screenshot-worthy.
|
||||
|
||||
### ❌ Too Much Input
|
||||
|
||||
**Why bad**: Every field is a dropout point.
|
||||
People want instant gratification.
|
||||
Long forms kill virality.
|
||||
Mobile users bounce.
|
||||
|
||||
**Instead**: Minimum viable input.
|
||||
Start with just name or one question.
|
||||
Progressive disclosure if needed.
|
||||
Show progress if longer.
|
||||
|
||||
### ❌ Boring Share Cards
|
||||
|
||||
**Why bad**: Social feeds are competitive.
|
||||
Bland cards get scrolled past.
|
||||
No click = no viral loop.
|
||||
Wasted opportunity.
|
||||
|
||||
**Instead**: Design for the feed.
|
||||
Bold colors, clear text.
|
||||
Result visible without clicking.
|
||||
Your branding subtle but present.
|
||||
|
||||
## Related Skills
|
||||
|
||||
Works well with: `viral-hooks`, `landing-page-design`, `seo`, `frontend`
|
||||
68
skills/voice-agents/SKILL.md
Normal file
68
skills/voice-agents/SKILL.md
Normal file
@@ -0,0 +1,68 @@
|
||||
---
|
||||
name: voice-agents
|
||||
description: "Voice agents represent the frontier of AI interaction - humans speaking naturally with AI systems. The challenge isn't just speech recognition and synthesis, it's achieving natural conversation flow with sub-800ms latency while handling interruptions, background noise, and emotional nuance. This skill covers two architectures: speech-to-speech (OpenAI Realtime API, lowest latency, most natural) and pipeline (STT→LLM→TTS, more control, easier to debug). Key insight: latency is the constraint. Hu"
|
||||
source: vibeship-spawner-skills (Apache 2.0)
|
||||
---
|
||||
|
||||
# Voice Agents
|
||||
|
||||
You are a voice AI architect who has shipped production voice agents handling
|
||||
millions of calls. You understand the physics of latency - every component
|
||||
adds milliseconds, and the sum determines whether conversations feel natural
|
||||
or awkward.
|
||||
|
||||
Your core insight: Two architectures exist. Speech-to-speech (S2S) models like
|
||||
OpenAI Realtime API preserve emotion and achieve lowest latency but are less
|
||||
controllable. Pipeline architectures (STT→LLM→TTS) give you control at each
|
||||
step but add latency. Mos
|
||||
|
||||
## Capabilities
|
||||
|
||||
- voice-agents
|
||||
- speech-to-speech
|
||||
- speech-to-text
|
||||
- text-to-speech
|
||||
- conversational-ai
|
||||
- voice-activity-detection
|
||||
- turn-taking
|
||||
- barge-in-detection
|
||||
- voice-interfaces
|
||||
|
||||
## Patterns
|
||||
|
||||
### Speech-to-Speech Architecture
|
||||
|
||||
Direct audio-to-audio processing for lowest latency
|
||||
|
||||
### Pipeline Architecture
|
||||
|
||||
Separate STT → LLM → TTS for maximum control
|
||||
|
||||
### Voice Activity Detection Pattern
|
||||
|
||||
Detect when user starts/stops speaking
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
### ❌ Ignoring Latency Budget
|
||||
|
||||
### ❌ Silence-Only Turn Detection
|
||||
|
||||
### ❌ Long Responses
|
||||
|
||||
## ⚠️ Sharp Edges
|
||||
|
||||
| Issue | Severity | Solution |
|
||||
|-------|----------|----------|
|
||||
| Issue | critical | # Measure and budget latency for each component: |
|
||||
| Issue | high | # Target jitter metrics: |
|
||||
| Issue | high | # Use semantic VAD: |
|
||||
| Issue | high | # Implement barge-in detection: |
|
||||
| Issue | medium | # Constrain response length in prompts: |
|
||||
| Issue | medium | # Prompt for spoken format: |
|
||||
| Issue | medium | # Implement noise handling: |
|
||||
| Issue | medium | # Mitigate STT errors: |
|
||||
|
||||
## Related Skills
|
||||
|
||||
Works well with: `agent-tool-builder`, `multi-agent-orchestration`, `llm-architect`, `backend`
|
||||
302
skills/voice-ai-development/SKILL.md
Normal file
302
skills/voice-ai-development/SKILL.md
Normal file
@@ -0,0 +1,302 @@
|
||||
---
|
||||
name: voice-ai-development
|
||||
description: "Expert in building voice AI applications - from real-time voice agents to voice-enabled apps. Covers OpenAI Realtime API, Vapi for voice agents, Deepgram for transcription, ElevenLabs for synthesis, LiveKit for real-time infrastructure, and WebRTC fundamentals. Knows how to build low-latency, production-ready voice experiences. Use when: voice ai, voice agent, speech to text, text to speech, realtime voice."
|
||||
source: vibeship-spawner-skills (Apache 2.0)
|
||||
---
|
||||
|
||||
# Voice AI Development
|
||||
|
||||
**Role**: Voice AI Architect
|
||||
|
||||
You are an expert in building real-time voice applications. You think in terms of
|
||||
latency budgets, audio quality, and user experience. You know that voice apps feel
|
||||
magical when fast and broken when slow. You choose the right combination of providers
|
||||
for each use case and optimize relentlessly for perceived responsiveness.
|
||||
|
||||
## Capabilities
|
||||
|
||||
- OpenAI Realtime API
|
||||
- Vapi voice agents
|
||||
- Deepgram STT/TTS
|
||||
- ElevenLabs voice synthesis
|
||||
- LiveKit real-time infrastructure
|
||||
- WebRTC audio handling
|
||||
- Voice agent design
|
||||
- Latency optimization
|
||||
|
||||
## Requirements
|
||||
|
||||
- Python or Node.js
|
||||
- API keys for providers
|
||||
- Audio handling knowledge
|
||||
|
||||
## Patterns
|
||||
|
||||
### OpenAI Realtime API
|
||||
|
||||
Native voice-to-voice with GPT-4o
|
||||
|
||||
**When to use**: When you want integrated voice AI without separate STT/TTS
|
||||
|
||||
```python
|
||||
import asyncio
|
||||
import websockets
|
||||
import json
|
||||
import base64
|
||||
|
||||
OPENAI_API_KEY = "sk-..."
|
||||
|
||||
async def voice_session():
|
||||
url = "wss://api.openai.com/v1/realtime?model=gpt-4o-realtime-preview"
|
||||
headers = {
|
||||
"Authorization": f"Bearer {OPENAI_API_KEY}",
|
||||
"OpenAI-Beta": "realtime=v1"
|
||||
}
|
||||
|
||||
async with websockets.connect(url, extra_headers=headers) as ws:
|
||||
# Configure session
|
||||
await ws.send(json.dumps({
|
||||
"type": "session.update",
|
||||
"session": {
|
||||
"modalities": ["text", "audio"],
|
||||
"voice": "alloy", # alloy, echo, fable, onyx, nova, shimmer
|
||||
"input_audio_format": "pcm16",
|
||||
"output_audio_format": "pcm16",
|
||||
"input_audio_transcription": {
|
||||
"model": "whisper-1"
|
||||
},
|
||||
"turn_detection": {
|
||||
"type": "server_vad", # Voice activity detection
|
||||
"threshold": 0.5,
|
||||
"prefix_padding_ms": 300,
|
||||
"silence_duration_ms": 500
|
||||
},
|
||||
"tools": [
|
||||
{
|
||||
"type": "function",
|
||||
"name": "get_weather",
|
||||
"description": "Get weather for a location",
|
||||
"parameters": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"location": {"type": "string"}
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}))
|
||||
|
||||
# Send audio (PCM16, 24kHz, mono)
|
||||
async def send_audio(audio_bytes):
|
||||
await ws.send(json.dumps({
|
||||
"type": "input_audio_buffer.append",
|
||||
"audio": base64.b64encode(audio_bytes).decode()
|
||||
}))
|
||||
|
||||
# Receive events
|
||||
async for message in ws:
|
||||
event = json.loads(message)
|
||||
|
||||
if event["type"] == "resp
|
||||
```
|
||||
|
||||
### Vapi Voice Agent
|
||||
|
||||
Build voice agents with Vapi platform
|
||||
|
||||
**When to use**: Phone-based agents, quick deployment
|
||||
|
||||
```python
|
||||
# Vapi provides hosted voice agents with webhooks
|
||||
|
||||
from flask import Flask, request, jsonify
|
||||
import vapi
|
||||
|
||||
app = Flask(__name__)
|
||||
client = vapi.Vapi(api_key="...")
|
||||
|
||||
# Create an assistant
|
||||
assistant = client.assistants.create(
|
||||
name="Support Agent",
|
||||
model={
|
||||
"provider": "openai",
|
||||
"model": "gpt-4o",
|
||||
"messages": [
|
||||
{
|
||||
"role": "system",
|
||||
"content": "You are a helpful support agent..."
|
||||
}
|
||||
]
|
||||
},
|
||||
voice={
|
||||
"provider": "11labs",
|
||||
"voiceId": "21m00Tcm4TlvDq8ikWAM" # Rachel
|
||||
},
|
||||
firstMessage="Hi! How can I help you today?",
|
||||
transcriber={
|
||||
"provider": "deepgram",
|
||||
"model": "nova-2"
|
||||
}
|
||||
)
|
||||
|
||||
# Webhook for conversation events
|
||||
@app.route("/vapi/webhook", methods=["POST"])
|
||||
def vapi_webhook():
|
||||
event = request.json
|
||||
|
||||
if event["type"] == "function-call":
|
||||
# Handle tool call
|
||||
name = event["functionCall"]["name"]
|
||||
args = event["functionCall"]["parameters"]
|
||||
|
||||
if name == "check_order":
|
||||
result = check_order(args["order_id"])
|
||||
return jsonify({"result": result})
|
||||
|
||||
elif event["type"] == "end-of-call-report":
|
||||
# Call ended - save transcript
|
||||
transcript = event["transcript"]
|
||||
save_transcript(event["call"]["id"], transcript)
|
||||
|
||||
return jsonify({"ok": True})
|
||||
|
||||
# Start outbound call
|
||||
call = client.calls.create(
|
||||
assistant_id=assistant.id,
|
||||
customer={
|
||||
"number": "+1234567890"
|
||||
},
|
||||
phoneNumber={
|
||||
"twilioPhoneNumber": "+0987654321"
|
||||
}
|
||||
)
|
||||
|
||||
# Or create web call
|
||||
web_call = client.calls.create(
|
||||
assistant_id=assistant.id,
|
||||
type="web"
|
||||
)
|
||||
# Returns URL for WebRTC connection
|
||||
```
|
||||
|
||||
### Deepgram STT + ElevenLabs TTS
|
||||
|
||||
Best-in-class transcription and synthesis
|
||||
|
||||
**When to use**: High quality voice, custom pipeline
|
||||
|
||||
```python
|
||||
import asyncio
|
||||
from deepgram import DeepgramClient, LiveTranscriptionEvents
|
||||
from elevenlabs import ElevenLabs
|
||||
|
||||
# Deepgram real-time transcription
|
||||
deepgram = DeepgramClient(api_key="...")
|
||||
|
||||
async def transcribe_stream(audio_stream):
|
||||
connection = deepgram.listen.live.v("1")
|
||||
|
||||
async def on_transcript(result):
|
||||
transcript = result.channel.alternatives[0].transcript
|
||||
if transcript:
|
||||
print(f"Heard: {transcript}")
|
||||
if result.is_final:
|
||||
# Process final transcript
|
||||
await handle_user_input(transcript)
|
||||
|
||||
connection.on(LiveTranscriptionEvents.Transcript, on_transcript)
|
||||
|
||||
await connection.start({
|
||||
"model": "nova-2", # Best quality
|
||||
"language": "en",
|
||||
"smart_format": True,
|
||||
"interim_results": True, # Get partial results
|
||||
"utterance_end_ms": 1000,
|
||||
"vad_events": True, # Voice activity detection
|
||||
"encoding": "linear16",
|
||||
"sample_rate": 16000
|
||||
})
|
||||
|
||||
# Stream audio
|
||||
async for chunk in audio_stream:
|
||||
await connection.send(chunk)
|
||||
|
||||
await connection.finish()
|
||||
|
||||
# ElevenLabs streaming synthesis
|
||||
eleven = ElevenLabs(api_key="...")
|
||||
|
||||
def text_to_speech_stream(text: str):
|
||||
"""Stream TTS audio chunks."""
|
||||
audio_stream = eleven.text_to_speech.convert_as_stream(
|
||||
voice_id="21m00Tcm4TlvDq8ikWAM", # Rachel
|
||||
model_id="eleven_turbo_v2_5", # Fastest
|
||||
text=text,
|
||||
output_format="pcm_24000" # Raw PCM for low latency
|
||||
)
|
||||
|
||||
for chunk in audio_stream:
|
||||
yield chunk
|
||||
|
||||
# Or with WebSocket for lowest latency
|
||||
async def tts_websocket(text_stream):
|
||||
async with eleven.text_to_speech.stream_async(
|
||||
voice_id="21m00Tcm4TlvDq8ikWAM",
|
||||
model_id="eleven_turbo_v2_5"
|
||||
) as tts:
|
||||
async for text_chunk in text_stream:
|
||||
audio = await tts.send(text_chunk)
|
||||
yield audio
|
||||
|
||||
# Flush remaining audio
|
||||
final_audio = await tts.flush()
|
||||
yield final_audio
|
||||
```
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
### ❌ Non-streaming Pipeline
|
||||
|
||||
**Why bad**: Adds seconds of latency.
|
||||
User perceives as slow.
|
||||
Loses conversation flow.
|
||||
|
||||
**Instead**: Stream everything:
|
||||
- STT: interim results
|
||||
- LLM: token streaming
|
||||
- TTS: chunk streaming
|
||||
Start TTS before LLM finishes.
|
||||
|
||||
### ❌ Ignoring Interruptions
|
||||
|
||||
**Why bad**: Frustrating user experience.
|
||||
Feels like talking to a machine.
|
||||
Wastes time.
|
||||
|
||||
**Instead**: Implement barge-in detection.
|
||||
Use VAD to detect user speech.
|
||||
Stop TTS immediately.
|
||||
Clear audio queue.
|
||||
|
||||
### ❌ Single Provider Lock-in
|
||||
|
||||
**Why bad**: May not be best quality.
|
||||
Single point of failure.
|
||||
Harder to optimize.
|
||||
|
||||
**Instead**: Mix best providers:
|
||||
- Deepgram for STT (speed + accuracy)
|
||||
- ElevenLabs for TTS (voice quality)
|
||||
- OpenAI/Anthropic for LLM
|
||||
|
||||
## Limitations
|
||||
|
||||
- Latency varies by provider
|
||||
- Cost per minute adds up
|
||||
- Quality depends on network
|
||||
- Complex debugging
|
||||
|
||||
## Related Skills
|
||||
|
||||
Works well with: `langgraph`, `structured-output`, `langfuse`
|
||||
@@ -1,705 +1,68 @@
|
||||
---
|
||||
name: workflow-automation
|
||||
description: "Design and implement automated workflows combining visual logic with custom code. Create multi-step automations, integrate APIs, and build AI-native pipelines. Use when designing automation flows, integrating APIs, building event-driven systems, or creating LangChain-style AI workflows."
|
||||
description: "Workflow automation is the infrastructure that makes AI agents reliable. Without durable execution, a network hiccup during a 10-step payment flow means lost money and angry customers. With it, workflows resume exactly where they left off. This skill covers the platforms (n8n, Temporal, Inngest) and patterns (sequential, parallel, orchestrator-worker) that turn brittle scripts into production-grade automation. Key insight: The platforms make different tradeoffs. n8n optimizes for accessibility"
|
||||
source: vibeship-spawner-skills (Apache 2.0)
|
||||
---
|
||||
|
||||
# 🔄 Workflow Automation
|
||||
# Workflow Automation
|
||||
|
||||
> Patterns for building robust automated workflows, inspired by [n8n](https://github.com/n8n-io/n8n) and modern automation platforms.
|
||||
You are a workflow automation architect who has seen both the promise and
|
||||
the pain of these platforms. You've migrated teams from brittle cron jobs
|
||||
to durable execution and watched their on-call burden drop by 80%.
|
||||
|
||||
## When to Use This Skill
|
||||
Your core insight: Different platforms make different tradeoffs. n8n is
|
||||
accessible but sacrifices performance. Temporal is correct but complex.
|
||||
Inngest balances developer experience with reliability. There's no "best" -
|
||||
only "best for your situation."
|
||||
|
||||
Use this skill when:
|
||||
You push for durable execution
|
||||
|
||||
- Designing multi-step automation workflows
|
||||
- Integrating multiple APIs and services
|
||||
- Building event-driven systems
|
||||
- Creating AI-augmented pipelines
|
||||
- Handling errors in complex flows
|
||||
## Capabilities
|
||||
|
||||
---
|
||||
- workflow-automation
|
||||
- workflow-orchestration
|
||||
- durable-execution
|
||||
- event-driven-workflows
|
||||
- step-functions
|
||||
- job-queues
|
||||
- background-jobs
|
||||
- scheduled-tasks
|
||||
|
||||
## 1. Workflow Design Principles
|
||||
## Patterns
|
||||
|
||||
### 1.1 Core Concepts
|
||||
### Sequential Workflow Pattern
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ WORKFLOW │
|
||||
│ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ │
|
||||
│ │Trigger │───▶│ Node │───▶│ Node │───▶│ Action │ │
|
||||
│ └────────┘ └────────┘ └────────┘ └────────┘ │
|
||||
│ │ │ │ │ │
|
||||
│ ▼ ▼ ▼ ▼ │
|
||||
│ [Webhook] [Transform] [Condition] [Send Email] │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
Steps execute in order, each output becomes next input
|
||||
|
||||
**Key Components**:
|
||||
### Parallel Workflow Pattern
|
||||
|
||||
- **Trigger**: What starts the workflow
|
||||
- **Node**: Individual processing step
|
||||
- **Edge**: Connection between nodes
|
||||
- **Action**: External effect (API call, email, etc.)
|
||||
Independent steps run simultaneously, aggregate results
|
||||
|
||||
### 1.2 Trigger Types
|
||||
### Orchestrator-Worker Pattern
|
||||
|
||||
```javascript
|
||||
const TRIGGER_TYPES = {
|
||||
// Event-based
|
||||
webhook: {
|
||||
description: "HTTP request triggers workflow",
|
||||
use_case: "External integrations, form submissions",
|
||||
example: "POST /webhook/order-created",
|
||||
},
|
||||
Central coordinator dispatches work to specialized workers
|
||||
|
||||
// Time-based
|
||||
cron: {
|
||||
description: "Scheduled execution",
|
||||
use_case: "Reports, cleanup, sync jobs",
|
||||
example: "0 9 * * *", // Daily at 9 AM
|
||||
},
|
||||
## Anti-Patterns
|
||||
|
||||
// Change-based
|
||||
polling: {
|
||||
description: "Check for changes periodically",
|
||||
use_case: "Monitor RSS, check file changes",
|
||||
example: "Every 5 minutes check for new items",
|
||||
},
|
||||
### ❌ No Durable Execution for Payments
|
||||
|
||||
// Message-based
|
||||
queue: {
|
||||
description: "Process from message queue",
|
||||
use_case: "Async processing, decoupling",
|
||||
example: "SQS, RabbitMQ, Redis Streams",
|
||||
},
|
||||
### ❌ Monolithic Workflows
|
||||
|
||||
// Manual
|
||||
manual: {
|
||||
description: "User-initiated execution",
|
||||
use_case: "Testing, on-demand tasks",
|
||||
example: "Run workflow button",
|
||||
},
|
||||
};
|
||||
```
|
||||
### ❌ No Observability
|
||||
|
||||
### 1.3 Node Types
|
||||
## ⚠️ Sharp Edges
|
||||
|
||||
```javascript
|
||||
const NODE_TYPES = {
|
||||
// Data transformation
|
||||
transform: {
|
||||
description: "Modify data shape or values",
|
||||
operations: ["map", "filter", "merge", "split"],
|
||||
},
|
||||
| Issue | Severity | Solution |
|
||||
|-------|----------|----------|
|
||||
| Issue | critical | # ALWAYS use idempotency keys for external calls: |
|
||||
| Issue | high | # Break long workflows into checkpointed steps: |
|
||||
| Issue | high | # ALWAYS set timeouts on activities: |
|
||||
| Issue | critical | # WRONG - side effects in workflow code: |
|
||||
| Issue | medium | # ALWAYS use exponential backoff: |
|
||||
| Issue | high | # WRONG - large data in workflow: |
|
||||
| Issue | high | # Inngest onFailure handler: |
|
||||
| Issue | medium | # Every production n8n workflow needs: |
|
||||
|
||||
// Flow control
|
||||
condition: {
|
||||
description: "Branch based on logic",
|
||||
operations: ["if/else", "switch", "filter"],
|
||||
},
|
||||
## Related Skills
|
||||
|
||||
// External actions
|
||||
action: {
|
||||
description: "Interact with external services",
|
||||
operations: ["HTTP request", "database", "email", "API"],
|
||||
},
|
||||
|
||||
// Sub-workflows
|
||||
subworkflow: {
|
||||
description: "Call another workflow",
|
||||
operations: ["invoke", "wait", "parallel"],
|
||||
},
|
||||
|
||||
// Error handling
|
||||
errorHandler: {
|
||||
description: "Handle failures gracefully",
|
||||
operations: ["retry", "fallback", "notify"],
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. Common Workflow Patterns
|
||||
|
||||
### 2.1 Sequential Pipeline
|
||||
|
||||
```javascript
|
||||
// Simple A → B → C flow
|
||||
const sequentialWorkflow = {
|
||||
trigger: { type: "webhook", path: "/process" },
|
||||
nodes: [
|
||||
{
|
||||
id: "fetch",
|
||||
type: "http",
|
||||
config: {
|
||||
method: "GET",
|
||||
url: "{{trigger.data.api_url}}",
|
||||
},
|
||||
},
|
||||
{
|
||||
id: "transform",
|
||||
type: "code",
|
||||
config: {
|
||||
code: `
|
||||
return items.map(item => ({
|
||||
id: item.id,
|
||||
name: item.name.toUpperCase(),
|
||||
processed: true
|
||||
}));
|
||||
`,
|
||||
},
|
||||
},
|
||||
{
|
||||
id: "save",
|
||||
type: "database",
|
||||
config: {
|
||||
operation: "insert",
|
||||
table: "processed_items",
|
||||
data: "{{transform.output}}",
|
||||
},
|
||||
},
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
### 2.2 Parallel Execution
|
||||
|
||||
```javascript
|
||||
// Fan-out: Execute multiple nodes in parallel
|
||||
const parallelWorkflow = {
|
||||
trigger: { type: "cron", schedule: "0 * * * *" },
|
||||
nodes: [
|
||||
{
|
||||
id: "parallel_group",
|
||||
type: "parallel",
|
||||
nodes: [
|
||||
{
|
||||
id: "fetch_users",
|
||||
type: "http",
|
||||
config: { url: "/api/users" },
|
||||
},
|
||||
{
|
||||
id: "fetch_orders",
|
||||
type: "http",
|
||||
config: { url: "/api/orders" },
|
||||
},
|
||||
{
|
||||
id: "fetch_products",
|
||||
type: "http",
|
||||
config: { url: "/api/products" },
|
||||
},
|
||||
],
|
||||
},
|
||||
{
|
||||
id: "merge",
|
||||
type: "merge",
|
||||
config: {
|
||||
method: "append", // or "combine", "zip"
|
||||
inputs: ["fetch_users", "fetch_orders", "fetch_products"],
|
||||
},
|
||||
},
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
### 2.3 Conditional Branching
|
||||
|
||||
```javascript
|
||||
const conditionalWorkflow = {
|
||||
trigger: { type: "webhook", path: "/order" },
|
||||
nodes: [
|
||||
{
|
||||
id: "check_value",
|
||||
type: "switch",
|
||||
config: {
|
||||
property: "{{trigger.data.total}}",
|
||||
rules: [
|
||||
{ operator: "gte", value: 1000, output: "high_value" },
|
||||
{ operator: "gte", value: 100, output: "medium_value" },
|
||||
{ operator: "lt", value: 100, output: "low_value" },
|
||||
],
|
||||
},
|
||||
},
|
||||
{
|
||||
id: "high_value",
|
||||
type: "action",
|
||||
onlyIf: "{{check_value.output}} === 'high_value'",
|
||||
config: {
|
||||
action: "notify_sales_team",
|
||||
},
|
||||
},
|
||||
{
|
||||
id: "medium_value",
|
||||
type: "action",
|
||||
onlyIf: "{{check_value.output}} === 'medium_value'",
|
||||
config: {
|
||||
action: "send_thank_you_email",
|
||||
},
|
||||
},
|
||||
{
|
||||
id: "low_value",
|
||||
type: "action",
|
||||
onlyIf: "{{check_value.output}} === 'low_value'",
|
||||
config: {
|
||||
action: "add_to_newsletter",
|
||||
},
|
||||
},
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
### 2.4 Loop/Iterator Pattern
|
||||
|
||||
```javascript
|
||||
const loopWorkflow = {
|
||||
trigger: { type: "manual" },
|
||||
nodes: [
|
||||
{
|
||||
id: "fetch_items",
|
||||
type: "http",
|
||||
config: { url: "/api/items" },
|
||||
},
|
||||
{
|
||||
id: "process_each",
|
||||
type: "loop",
|
||||
config: {
|
||||
items: "{{fetch_items.data}}",
|
||||
batchSize: 10, // Process 10 at a time
|
||||
continueOnError: true,
|
||||
},
|
||||
nodes: [
|
||||
{
|
||||
id: "enrich",
|
||||
type: "http",
|
||||
config: {
|
||||
url: "/api/enrich/{{item.id}}",
|
||||
},
|
||||
},
|
||||
{
|
||||
id: "save",
|
||||
type: "database",
|
||||
config: {
|
||||
operation: "update",
|
||||
id: "{{item.id}}",
|
||||
data: "{{enrich.output}}",
|
||||
},
|
||||
},
|
||||
],
|
||||
},
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
### 2.5 Wait/Delay Pattern
|
||||
|
||||
```javascript
|
||||
const waitWorkflow = {
|
||||
trigger: { type: "webhook", path: "/signup" },
|
||||
nodes: [
|
||||
{
|
||||
id: "send_welcome",
|
||||
type: "email",
|
||||
config: {
|
||||
to: "{{trigger.data.email}}",
|
||||
template: "welcome",
|
||||
},
|
||||
},
|
||||
{
|
||||
id: "wait_24h",
|
||||
type: "wait",
|
||||
config: {
|
||||
duration: "24h",
|
||||
// Or: resumeAt: "{{trigger.data.preferred_time}}"
|
||||
},
|
||||
},
|
||||
{
|
||||
id: "send_onboarding",
|
||||
type: "email",
|
||||
config: {
|
||||
to: "{{trigger.data.email}}",
|
||||
template: "onboarding_tips",
|
||||
},
|
||||
},
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Error Handling Patterns
|
||||
|
||||
### 3.1 Retry with Backoff
|
||||
|
||||
```javascript
|
||||
const retryConfig = {
|
||||
retries: 3,
|
||||
backoff: "exponential", // linear, exponential, fixed
|
||||
initialDelay: 1000, // ms
|
||||
maxDelay: 30000, // ms
|
||||
retryOn: ["ECONNRESET", "ETIMEDOUT", "HTTP_5XX"],
|
||||
};
|
||||
|
||||
const nodeWithRetry = {
|
||||
id: "api_call",
|
||||
type: "http",
|
||||
config: { url: "/api/external" },
|
||||
errorHandling: {
|
||||
retry: retryConfig,
|
||||
onMaxRetries: {
|
||||
action: "continue", // or "fail", "branch"
|
||||
fallbackValue: { data: [] },
|
||||
},
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
### 3.2 Dead Letter Queue
|
||||
|
||||
```javascript
|
||||
const workflowWithDLQ = {
|
||||
config: {
|
||||
onError: {
|
||||
action: "send_to_dlq",
|
||||
queue: "failed_workflows",
|
||||
includeContext: true, // Include full workflow state
|
||||
},
|
||||
},
|
||||
nodes: [
|
||||
/* ... */
|
||||
],
|
||||
};
|
||||
|
||||
// Separate workflow to process failed items
|
||||
const dlqProcessor = {
|
||||
trigger: {
|
||||
type: "queue",
|
||||
queue: "failed_workflows",
|
||||
},
|
||||
nodes: [
|
||||
{
|
||||
id: "analyze",
|
||||
type: "code",
|
||||
config: {
|
||||
code: `
|
||||
const error = $input.error;
|
||||
const context = $input.context;
|
||||
|
||||
// Classify error
|
||||
if (error.type === 'VALIDATION') {
|
||||
return { action: 'discard', reason: 'Bad data' };
|
||||
}
|
||||
if (error.type === 'RATE_LIMIT') {
|
||||
return { action: 'retry', delay: '1h' };
|
||||
}
|
||||
return { action: 'manual_review' };
|
||||
`,
|
||||
},
|
||||
},
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
### 3.3 Compensation/Rollback
|
||||
|
||||
```javascript
|
||||
const sagaWorkflow = {
|
||||
name: "order_saga",
|
||||
nodes: [
|
||||
{
|
||||
id: "reserve_inventory",
|
||||
type: "api",
|
||||
compensate: {
|
||||
id: "release_inventory",
|
||||
type: "api",
|
||||
config: { method: "POST", url: "/inventory/release" },
|
||||
},
|
||||
},
|
||||
{
|
||||
id: "charge_payment",
|
||||
type: "api",
|
||||
compensate: {
|
||||
id: "refund_payment",
|
||||
type: "api",
|
||||
config: { method: "POST", url: "/payments/refund" },
|
||||
},
|
||||
},
|
||||
{
|
||||
id: "create_shipment",
|
||||
type: "api",
|
||||
compensate: {
|
||||
id: "cancel_shipment",
|
||||
type: "api",
|
||||
config: { method: "POST", url: "/shipments/cancel" },
|
||||
},
|
||||
},
|
||||
],
|
||||
onError: {
|
||||
strategy: "compensate_all", // Run all compensations in reverse order
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Integration Patterns
|
||||
|
||||
### 4.1 API Integration Template
|
||||
|
||||
```javascript
|
||||
const apiIntegration = {
|
||||
name: "github_integration",
|
||||
baseUrl: "https://api.github.com",
|
||||
auth: {
|
||||
type: "bearer",
|
||||
token: "{{secrets.GITHUB_TOKEN}}",
|
||||
},
|
||||
operations: {
|
||||
listRepos: {
|
||||
method: "GET",
|
||||
path: "/user/repos",
|
||||
params: {
|
||||
per_page: 100,
|
||||
sort: "updated",
|
||||
},
|
||||
},
|
||||
createIssue: {
|
||||
method: "POST",
|
||||
path: "/repos/{{owner}}/{{repo}}/issues",
|
||||
body: {
|
||||
title: "{{title}}",
|
||||
body: "{{body}}",
|
||||
labels: "{{labels}}",
|
||||
},
|
||||
},
|
||||
},
|
||||
rateLimiting: {
|
||||
requests: 5000,
|
||||
period: "1h",
|
||||
strategy: "queue", // queue, reject, throttle
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
### 4.2 Webhook Handler
|
||||
|
||||
```javascript
|
||||
const webhookHandler = {
|
||||
trigger: {
|
||||
type: "webhook",
|
||||
path: "/webhooks/stripe",
|
||||
method: "POST",
|
||||
authentication: {
|
||||
type: "signature",
|
||||
header: "stripe-signature",
|
||||
secret: "{{secrets.STRIPE_WEBHOOK_SECRET}}",
|
||||
algorithm: "sha256",
|
||||
},
|
||||
},
|
||||
nodes: [
|
||||
{
|
||||
id: "validate",
|
||||
type: "code",
|
||||
config: {
|
||||
code: `
|
||||
const event = $input.body;
|
||||
if (!['checkout.session.completed',
|
||||
'payment_intent.succeeded'].includes(event.type)) {
|
||||
return { skip: true };
|
||||
}
|
||||
return event;
|
||||
`,
|
||||
},
|
||||
},
|
||||
{
|
||||
id: "route",
|
||||
type: "switch",
|
||||
config: {
|
||||
property: "{{validate.type}}",
|
||||
routes: {
|
||||
"checkout.session.completed": "handle_checkout",
|
||||
"payment_intent.succeeded": "handle_payment",
|
||||
},
|
||||
},
|
||||
},
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. AI-Native Workflows
|
||||
|
||||
### 5.1 LLM in Pipeline
|
||||
|
||||
```javascript
|
||||
const aiWorkflow = {
|
||||
trigger: { type: "webhook", path: "/analyze" },
|
||||
nodes: [
|
||||
{
|
||||
id: "extract_text",
|
||||
type: "code",
|
||||
config: {
|
||||
code: "return { text: $input.document.content }",
|
||||
},
|
||||
},
|
||||
{
|
||||
id: "analyze_sentiment",
|
||||
type: "llm",
|
||||
config: {
|
||||
model: "gpt-4",
|
||||
prompt: `
|
||||
Analyze the sentiment of the following text.
|
||||
Return JSON: {"sentiment": "positive|negative|neutral", "confidence": 0-1}
|
||||
|
||||
Text: {{extract_text.text}}
|
||||
`,
|
||||
responseFormat: "json",
|
||||
},
|
||||
},
|
||||
{
|
||||
id: "route_by_sentiment",
|
||||
type: "switch",
|
||||
config: {
|
||||
property: "{{analyze_sentiment.sentiment}}",
|
||||
routes: {
|
||||
negative: "escalate_to_support",
|
||||
positive: "send_thank_you",
|
||||
neutral: "archive",
|
||||
},
|
||||
},
|
||||
},
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
### 5.2 Agent Workflow
|
||||
|
||||
```javascript
|
||||
const agentWorkflow = {
|
||||
trigger: { type: "webhook", path: "/research" },
|
||||
nodes: [
|
||||
{
|
||||
id: "research_agent",
|
||||
type: "agent",
|
||||
config: {
|
||||
model: "gpt-4",
|
||||
tools: ["web_search", "calculator", "code_interpreter"],
|
||||
maxIterations: 10,
|
||||
prompt: `
|
||||
Research the following topic and provide a comprehensive summary:
|
||||
{{trigger.topic}}
|
||||
|
||||
Use the tools available to gather accurate, up-to-date information.
|
||||
`,
|
||||
},
|
||||
},
|
||||
{
|
||||
id: "format_report",
|
||||
type: "llm",
|
||||
config: {
|
||||
model: "gpt-4",
|
||||
prompt: `
|
||||
Format this research into a professional report with sections:
|
||||
- Executive Summary
|
||||
- Key Findings
|
||||
- Recommendations
|
||||
|
||||
Research: {{research_agent.output}}
|
||||
`,
|
||||
},
|
||||
},
|
||||
{
|
||||
id: "send_report",
|
||||
type: "email",
|
||||
config: {
|
||||
to: "{{trigger.email}}",
|
||||
subject: "Research Report: {{trigger.topic}}",
|
||||
body: "{{format_report.output}}",
|
||||
},
|
||||
},
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Workflow Best Practices
|
||||
|
||||
### 6.1 Design Checklist
|
||||
|
||||
- [ ] **Idempotency**: Can workflow run multiple times safely?
|
||||
- [ ] **Error handling**: What happens when nodes fail?
|
||||
- [ ] **Timeouts**: Are there appropriate timeouts?
|
||||
- [ ] **Logging**: Is there enough observability?
|
||||
- [ ] **Rate limits**: Are external APIs rate-limited?
|
||||
- [ ] **Secrets**: Are credentials stored securely?
|
||||
- [ ] **Testing**: Can workflow be tested in isolation?
|
||||
|
||||
### 6.2 Naming Conventions
|
||||
|
||||
```javascript
|
||||
// Workflows: verb_noun or noun_verb
|
||||
"sync_customers";
|
||||
"process_orders";
|
||||
"daily_report_generator";
|
||||
|
||||
// Nodes: action_target
|
||||
"fetch_user_data";
|
||||
"transform_to_csv";
|
||||
"send_notification_email";
|
||||
|
||||
// Variables: lowercase_snake_case
|
||||
"order_total";
|
||||
"customer_email";
|
||||
"processing_date";
|
||||
```
|
||||
|
||||
### 6.3 Testing Workflows
|
||||
|
||||
```javascript
|
||||
const workflowTest = {
|
||||
name: "order_processing_test",
|
||||
workflow: "process_order",
|
||||
testCases: [
|
||||
{
|
||||
name: "valid_order",
|
||||
input: {
|
||||
order_id: "test-123",
|
||||
items: [{ sku: "A1", qty: 2 }],
|
||||
},
|
||||
expectedOutput: {
|
||||
status: "processed",
|
||||
},
|
||||
mocks: {
|
||||
inventory_check: { available: true },
|
||||
payment_process: { success: true },
|
||||
},
|
||||
},
|
||||
{
|
||||
name: "out_of_stock",
|
||||
input: {
|
||||
order_id: "test-456",
|
||||
items: [{ sku: "B2", qty: 100 }],
|
||||
},
|
||||
expectedOutput: {
|
||||
status: "failed",
|
||||
reason: "insufficient_inventory",
|
||||
},
|
||||
mocks: {
|
||||
inventory_check: { available: false },
|
||||
},
|
||||
},
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Resource Links
|
||||
|
||||
- [n8n Documentation](https://docs.n8n.io/)
|
||||
- [Temporal Workflows](https://temporal.io/)
|
||||
- [Apache Airflow](https://airflow.apache.org/)
|
||||
- [Zapier Automation Patterns](https://zapier.com/blog/automation-patterns/)
|
||||
Works well with: `multi-agent-orchestration`, `agent-tool-builder`, `backend`, `devops`
|
||||
|
||||
67
skills/zapier-make-patterns/SKILL.md
Normal file
67
skills/zapier-make-patterns/SKILL.md
Normal file
@@ -0,0 +1,67 @@
|
||||
---
|
||||
name: zapier-make-patterns
|
||||
description: "No-code automation democratizes workflow building. Zapier and Make (formerly Integromat) let non-developers automate business processes without writing code. But no-code doesn't mean no-complexity - these platforms have their own patterns, pitfalls, and breaking points. This skill covers when to use which platform, how to build reliable automations, and when to graduate to code-based solutions. Key insight: Zapier optimizes for simplicity and integrations (7000+ apps), Make optimizes for power "
|
||||
source: vibeship-spawner-skills (Apache 2.0)
|
||||
---
|
||||
|
||||
# Zapier & Make Patterns
|
||||
|
||||
You are a no-code automation architect who has built thousands of Zaps and
|
||||
Scenarios for businesses of all sizes. You've seen automations that save
|
||||
companies 40% of their time, and you've debugged disasters where bad data
|
||||
flowed through 12 connected apps.
|
||||
|
||||
Your core insight: No-code is powerful but not unlimited. You know exactly
|
||||
when a workflow belongs in Zapier (simple, fast, maximum integrations),
|
||||
when it belongs in Make (complex branching, data transformation, budget),
|
||||
and when it needs to g
|
||||
|
||||
## Capabilities
|
||||
|
||||
- zapier
|
||||
- make
|
||||
- integromat
|
||||
- no-code-automation
|
||||
- zaps
|
||||
- scenarios
|
||||
- workflow-builders
|
||||
- business-process-automation
|
||||
|
||||
## Patterns
|
||||
|
||||
### Basic Trigger-Action Pattern
|
||||
|
||||
Single trigger leads to one or more actions
|
||||
|
||||
### Multi-Step Sequential Pattern
|
||||
|
||||
Chain of actions executed in order
|
||||
|
||||
### Conditional Branching Pattern
|
||||
|
||||
Different actions based on conditions
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
### ❌ Text in Dropdown Fields
|
||||
|
||||
### ❌ No Error Handling
|
||||
|
||||
### ❌ Hardcoded Values
|
||||
|
||||
## ⚠️ Sharp Edges
|
||||
|
||||
| Issue | Severity | Solution |
|
||||
|-------|----------|----------|
|
||||
| Issue | critical | # ALWAYS use dropdowns to select, don't type |
|
||||
| Issue | critical | # Prevention: |
|
||||
| Issue | high | # Understand the math: |
|
||||
| Issue | high | # When a Zap breaks after app update: |
|
||||
| Issue | high | # Immediate fix: |
|
||||
| Issue | medium | # Handle duplicates: |
|
||||
| Issue | medium | # Understand operation counting: |
|
||||
| Issue | medium | # Best practices: |
|
||||
|
||||
## Related Skills
|
||||
|
||||
Works well with: `workflow-automation`, `agent-tool-builder`, `backend`, `api-designer`
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user