diff --git a/small-business/.claude-plugin/plugin.json b/small-business/.claude-plugin/plugin.json deleted file mode 100644 index 2a7ebc3e5..000000000 --- a/small-business/.claude-plugin/plugin.json +++ /dev/null @@ -1,9 +0,0 @@ -{ - "name": "small-business", - "version": "0.2.1", - "description": "Pre-built small business workflows (including payroll planning, month-end close, weekly briefs, and growth campaigns) using your QuickBooks, PayPal, HubSpot, Docusign, Gsuite, O365, Canva, and other connected tools. You approve every step that touches money or customers.", - "author": { - "name": "Anthropic" - }, - "keywords": ["smb", "finance", "marketing", "hr", "operations", "all-in-one", "small business"] -} diff --git a/small-business/.mcp.json b/small-business/.mcp.json deleted file mode 100644 index c18bd6f91..000000000 --- a/small-business/.mcp.json +++ /dev/null @@ -1,56 +0,0 @@ -{ - "mcpServers": { - "quickbooks": { - "type": "http", - "url": "https://ai-inc.quickbooks.intuit.com/v1/mcp" - }, - "paypal": { - "type": "sse", - "url": "https://mcp.paypal.com/sse" - }, - "hubspot": { - "type": "http", - "url": "https://mcp.hubspot.com/anthropic" - }, - "canva": { - "type": "http", - "url": "https://mcp.canva.com/mcp" - }, - "docusign": { - "type": "http", - "url": "https://mcp.docusign.com/mcp" - }, - "slack": { - "type": "http", - "url": "https://mcp.slack.com/mcp", - "oauth": { - "clientId": "1601185624273.8899143856786", - "callbackPort": 3118 - } - }, - "stripe": { - "type": "http", - "url": "https://mcp.stripe.com" - }, - "square": { - "type": "http", - "url": "https://mcp.squareup.com/sse" - }, - "ms365": { - "type": "http", - "url": "https://microsoft365.mcp.claude.com/mcp" - }, - "gmail": { - "type": "http", - "url": "https://gmailmcp.googleapis.com/mcp/v1" - }, - "google calendar": { - "type": "http", - "url": "https://calendarmcp.googleapis.com/mcp/v1" - }, - "google drive": { - "type": "http", - "url": "https://drivemcp.googleapis.com/mcp/v1" - } - } -} diff --git a/small-business/README.md b/small-business/README.md deleted file mode 100644 index ac66f8b0d..000000000 --- a/small-business/README.md +++ /dev/null @@ -1,146 +0,0 @@ -# Small Business Plugin - -Pre-built small business workflows for [Cowork](https://claude.com/product/cowork), Anthropic's agentic desktop application — also works in Claude Code. Install it once and you get 15 building-block skills, 15 ready-to-use workflows, and a router that understands plain English. - -You don't need to memorize anything. Just tell Claude what you need — "I'm stressed about making payroll," "a customer is angry," "what should I charge?" — and it figures out the right workflow and walks you through it. Every workflow pauses before taking action, so nothing happens without your say-so. - -> **Important**: This plugin assists with small business workflows but does not provide financial, tax, legal, or HR advice. All outputs should be reviewed by you (and where appropriate, a qualified professional) before use. - -## Installation - -### Cowork - -Install from [claude.com/plugins](https://claude.com/plugins/). - -### Claude Code - -```bash -claude plugin marketplace add anthropics/knowledge-work-plugins -claude plugin install small-business@knowledge-work-plugins -``` - -Once installed, say **"set me up"** to run the `smb-onboard` skill — it'll help Claude understand your business, your pain points, and the tools you already use. - -## What you'll need to connect - -Run `/smb-onboard` or ask Claude to "set me up." - -**Core tools** (connect these first for the best experience): -- **QuickBooks** — powers all financial workflows (cash forecasts, margins, month-end close, tax prep) -- **PayPal** — transaction data, invoices, disputes, and refunds -- **HubSpot** — CRM, leads, campaigns, and customer support tickets - -**Marketing & communication:** -- **Canva** — generates on-brand social and email assets -- **Gmail / Outlook** — email drafts, ticket handling, contract review -- **Google Calendar / Outlook Calendar** — meeting prep, call blocking, weekly commitments -- **Slack** — brief delivery and notifications - -**Optional** (adds depth when connected): -- **Stripe** — payment and subscription data -- **Square** — POS transaction data -- **Google Drive / OneDrive** — file storage and templates -- **DocuSign** — contract review from pending envelopes - -You don't need all of these to start. Connect one or two and you'll immediately see value — the plugin tells you when connecting another tool would unlock more. - -## How it works - -Three layers working together: - -1. **Skills** — the building blocks. Each skill knows how to do one thing really well (forecast cash, score leads, draft an invoice reminder). There are 15 of these. - -2. **Commands** — the workflows. Commands chain skills together into multi-step recipes with checkpoints where you approve before anything happens. There are 15 of these. - -3. **The Router** — the front door. You talk to Claude in plain English. The router listens, figures out which workflow fits, and gets you there. You never need to memorize a command name. - -## All 15 commands - -Commands are workflows that chain skills together. Each one pauses at checkpoints for your approval before taking action. - -### Money & finance - -| Command | What it does | Just say... | Skills used | Required | Optional | -|---|---|---|---|---|---| -| `/plan-payroll` | Cash forecast + overdue invoice chase so you know payroll is covered. | "can I make payroll", "cash is tight", "who owes me money" | cash-flow-snapshot, invoice-chase | QuickBooks | PayPal, Stripe, Square, Mail | -| `/month-heads-up` | 30-day cash outlook with early risk flags. | "what does next month look like", "cash forecast", "runway" | cash-flow-snapshot | QuickBooks | PayPal | -| `/close-month` | Month-end close: reconcile, flag gaps, write P&L, export packet. | "close the books", "month-end", "reconcile" | month-end-prep | QuickBooks | PayPal, Stripe, Square | -| `/price-check` | Margin-by-product table and three pricing scenarios. | "what are my margins", "should I raise prices", "cost per unit" | margin-analyzer | QuickBooks | PayPal | -| `/tax-prep` | Tax prep materials for your accountant (quarterly estimates or year-end 1099s). | "tax stuff", "estimated taxes", "1099s", "accountant needs..." | tax-season-organizer | QuickBooks | PayPal, Stripe | - -### Sales & marketing - -| Command | What it does | Just say... | Skills used | Required | Optional | -|---|---|---|---|---|---| -| `/call-list` | Top 5 leads to call today with talking points and calendar blocks. | "who should I call", "any hot leads", "pipeline" | lead-triage | HubSpot | Mail, Google Calendar | -| `/run-campaign` | End-to-end campaign: sales analysis → content brief → Canva assets → HubSpot send. | "run a campaign", "sales are down", "I need more customers" | content-strategy, canva-creator, lead-triage | HubSpot, Canva | QuickBooks, PayPal | -| `/sales-brief` | Top and bottom sellers with a 2-week content brief. | "what's selling", "what should I promote" | content-strategy | QuickBooks or PayPal | HubSpot | - -### Customers & operations - -| Command | What it does | Just say... | Skills used | Required | Optional | -|---|---|---|---|---|---| -| `/customer-pulse-check` | Customer feedback themes with response templates. | "what are customers saying", "complaints", "reviews" | customer-pulse, ticket-deflector | PayPal or HubSpot | -- | -| `/handle-complaint` | End-to-end complaint resolution: pull context, draft response, suggest operational fix. | "a customer is upset", "handle this complaint", "angry email" | ticket-deflector, customer-pulse | -- (works with pasted text) | Gmail, HubSpot, PayPal | -| `/crm-cleanup` | HubSpot hygiene: stale deals, duplicates, missing fields — fixes what you approve. | "clean up the CRM", "HubSpot is a mess", "stale deals" | crm-maintenance | HubSpot | -- | -| `/review-contract` | Plain-English contract review with red flags and severity ratings. | "review this contract", "NDA", "should I sign this" | contract-review | -- (works with file upload) | DocuSign | - -### Business intelligence - -| Command | What it does | Just say... | Skills used | Required | Optional | -|---|---|---|---|---|---| -| `/monday-brief` | Monday morning briefing: cash, sales, pipeline, week ahead, top 3 to-dos. | "Monday brief", "what's on my plate", "start of week" | business-pulse | -- (degrades gracefully) | QuickBooks, PayPal, HubSpot, Calendar, Gmail, Slack | -| `/friday-brief` | Friday end-of-week pulse: revenue vs last week, wins, and things to watch. | "end of week", "how'd we do", "Friday recap" | business-pulse | PayPal or HubSpot | -- | -| `/quarterly-review` | Full QBR narrative: revenue, margin, customer health, opportunities, risks. | "quarterly review", "board deck", "QBR" | business-pulse | QuickBooks | PayPal, HubSpot | - -## All 15 skills - -Skills are the atomic building blocks. Each one does one thing well. - -### Money & finance - -| Skill | What it does | Just say... | Required | Optional | -|---|---|---|---|---| -| **cash-flow-snapshot** | 30/60/90-day cash forecast with confidence bands and named risk flags. Chat summary + XLSX. | "forecast my cash flow", "will I make payroll", "runway", "cash crunch" | QuickBooks, PayPal, Stripe, or Square (any one) | Others as secondary sources | -| **invoice-chase** | Drafts overdue-invoice reminders matched to each customer's payment history and tone. Sends via PayPal with approval. | "who owes me money", "overdue invoices", "follow up on unpaid" | QuickBooks | PayPal, Stripe, Gmail | -| **margin-analyzer** | Unit economics by product or service with inflation benchmarks and three pricing scenarios. | "what are my margins", "should I raise prices", "costs eating into profit", "what to charge" | QuickBooks | PayPal, Square, CSV upload | -| **month-end-prep** | Month-end close: reconciles QB against payment processors, flags gaps, writes P&L narrative, exports close packet. | "close the month", "reconcile", "P&L", "why revenue changed" | QuickBooks | PayPal, Stripe, Square | -| **tax-season-organizer** | Quarterly estimated tax calc or year-end 1099-NEC prep with accountant handoff packet. | "quarterly taxes", "estimated tax payment", "1099s", "1099-NEC", "year-end tax prep" | QuickBooks | PayPal, Stripe | - -### Sales & marketing - -| Skill | What it does | Just say... | Required | Optional | -|---|---|---|---|---| -| **lead-triage** | Scores HubSpot leads by engagement, fit, and urgency to produce a ranked call list with talking points. | "prioritize leads", "who to call first", "pipeline" | HubSpot | Gmail, Google Calendar | -| **content-strategy** | Analyzes sales data to find top performers and slow movers, produces a prioritized 30-day content brief. | "what should I post", "content plan", "what's selling", "what to promote" | QuickBooks or PayPal | Square | -| **canva-creator** | Takes a content brief and executes the full campaign: posting calendar, Canva assets, caption copy, HubSpot staging. | "make the content", "generate the posts", "create the assets", "turn this into a campaign" | Canva, HubSpot | -- | - -### Customers & operations - -| Skill | What it does | Just say... | Required | Optional | -|---|---|---|---|---| -| **customer-pulse** | Aggregates disputes, tickets, email sentiment, and reviews into a themes report with a "do these three things this week" list. | "how are customers feeling", "what people are saying", "disputes", "review analysis" | -- (degrades gracefully) | PayPal, HubSpot, Gmail | -| **ticket-deflector** | Reads a customer email or ticket, pulls order/refund status, drafts a tone-matched reply. Can issue PayPal refunds with approval. | "draft a response", "answer this customer", "where's my order", "I want a refund" | PayPal, HubSpot, Mail | Intercom, Square | -| **crm-maintenance** | Keeps HubSpot current: creates/updates contacts and deals, logs calls and notes, flags stale records. | "update the CRM", "log a call", "clean up HubSpot", "add context to a deal" | HubSpot | Gmail, Google Calendar | -| **contract-review** | Plain-English contract review with risk flags, severity ratings, and a marked-up redline DOCX. | "review this contract", "what am I signing", "flag any concerns", "check the payment terms" | -- (works with file upload) | Gmail, DocuSign | - -### Hiring - -| Skill | What it does | Just say... | Required | Optional | -|---|---|---|---|---| -| **job-post-builder** | Builds a complete hiring packet: job post, structured interview guide with scoring rubric, and offer letter template. | "help me hire", "write a job post", "job description", "open role", "interview questions", "draft an offer letter" | -- (works standalone) | DocuSign, Google Drive | - -### Business intelligence & onboarding - -| Skill | What it does | Just say... | Required | Optional | -|---|---|---|---|---| -| **business-pulse** | One-page business snapshot: cash, sales, pipeline, commitments, watch-list, and the single most important thing needing attention today. | "how's the business doing", "snapshot", "weekly summary", "catch me up" | -- (degrades gracefully) | QuickBooks, PayPal, HubSpot, Google Calendar, Gmail, Slack | -| **smb-onboard** | Walks you through connecting tools, runs a demo recipe, captures your business context, and sets a weekly check-in cadence. | "set me up", "setup", "get started", "help me get set up", "I'm new to this", "what can you do" | -- | All connectors | - -## Customizing - -These workflows are generic starting points. They become much more useful when you customize them for how your business actually works: - -- **Add business context** — Drop your industry, products, customers, and processes into skill files so Claude understands your world. -- **Adjust thresholds** — Tune the alert thresholds in `business-pulse` and `cash-flow-snapshot` to match your scale. -- **Swap connectors** — Point skills at the tools you actually use. diff --git a/small-business/skills/business-pulse/SKILL.md b/small-business/skills/business-pulse/SKILL.md deleted file mode 100644 index 7f2ddfd23..000000000 --- a/small-business/skills/business-pulse/SKILL.md +++ /dev/null @@ -1,100 +0,0 @@ ---- -name: business-pulse -description: > - Produces a one-page cross-functional business snapshot for SMB owners — - cash position (QuickBooks), sales trend (PayPal/Square), pipeline movement - (HubSpot), this week's commitments (Calendar), urgent watch-list items - (Gmail/Slack), and the single most important thing needing attention today. - Proactively tries every available connector and gracefully scopes to - whatever is connected — one connector gives a partial pulse; the full stack - gives the full picture. Trigger when the user asks how the business is - doing, wants a snapshot, a weekly summary, a Monday brief, or says - anything like "what am I missing" or "catch me up on the business." ---- - -# Business Pulse - -One prompt, one page. Pull live data from every connected tool, synthesize it into a single scannable brief, and surface the single most important thing to act on today. Do the work — don't ask the user to help find the data. - -## Step 1 — Pull data in parallel - -**Dispatch all connector calls in a single parallel batch** — see `reference/data_sources.md` for the exact tool-to-metric mapping. Do not pull serially; latency turns a 30-second skill into a painful wait. - -Connectors to attempt simultaneously: - -- **QuickBooks** — cash balance, MTD revenue, outstanding receivables, overdue invoices -- **PayPal / Square** — 7-day settlements, sales trend, failed/pending transactions -- **HubSpot** — pipeline by stage, deals moved/closed, deals gone cold, new leads -- **Google Calendar** — key meetings, deadlines, events this week and next 7 days -- **Gmail** — threads flagged urgent, customer complaints, time-sensitive requests -- **Slack / Teams** — urgent internal signals, threads needing owner attention -- **Intercom / Zendesk** — open tickets, escalations (if connected) -- **Shopify / Square** — fulfillment issues (if connected) - -If a connector errors or returns no data, record it internally and move on. Never block the pulse on a single bad integration. - -**QuickBooks fallback**: if QBO returns an unexpected state (account not connected, sync pending, empty response), mark the Cash section "n/a — QuickBooks unavailable" and proceed. Do not retry or ask the user to reconnect. - -**Gmail fallback**: Gmail auth is intermittently flaky. If the call errors, skip the Watch List section silently and note "Gmail unavailable" in the appendix — do not surface an error mid-pulse. - -## Step 2 — Compute metrics - -Read `reference/thresholds.md` for red/yellow/green cutoffs. Compute: - -- **AR aging** — open QuickBooks invoices grouped by days since due date (0–30, 31–60, 61+) -- **Pipeline coverage** — HubSpot weighted pipeline ÷ monthly revenue target -- **Revenue trend** — this month's QBO revenue vs. prior month (or 7-day PayPal/Square vs. prior 7 days) - -Assign a 🟢/🟡/🔴 status to each section. If a source returned nothing, mark the metric "n/a" and note it in the appendix. - -## Step 3 — Flag risks proactively - -Scan for actionable items. Every risk entry must name a specific record and a next step — "some overdue invoices" is useless; "$3,400 from Acme Corp, 47 days overdue, no response since Mar 12" is actionable. - -- QuickBooks invoices past due > 30 days — name customer, amount, days overdue -- HubSpot deals with no activity in 7+ days, or close date in past but still open -- Gmail threads marked urgent or containing "escalation," "complaint," "cancel," "refund" -- Failed or pending PayPal/Square transactions > $500 - -## Step 4 — Compose the output - -Use the exact template in `reference/output_template.md`. Include only sections where real data exists — omit headers for connectors that weren't available. Adapt depth to context: a casual "how are we doing" gets a fuller report; "quick snapshot before a call" gets a tighter one. - -Cross-connector synthesis is where this skill earns its keep. If a Slack message connects to a stalled HubSpot deal, surface that link in the #1 Priority section. Synthesis is what makes the pulse more useful than checking each tool separately. - -Writing rules: -- Numbers lead, words follow. Never write "revenue is healthy" — write "$43k this month, ▲ 8% MoM" and let the owner judge. -- Every number carries a delta vs. the prior period where available. Absolute snapshots (cash balance) still show WoW delta. -- Names and dollars, not adjectives. "$4,200 from Acme, 23 days overdue" beats "some concerning receivables." -- No filler. If a section has nothing worth reporting, write "No material changes" and move on. - -## Step 5 — Export and share (once) - -After presenting the pulse, offer once: -- "Want me to save this as a file?" (use Files connector if available) -- "Should I post this to your Slack?" (only if Slack is connected and the user confirms — Slack write requires explicit approval) - -If they say yes, do it. If they say no or don't respond, move on — don't ask again. - -## Scope variants - -The owner may ask for a narrower cut: - -- **"Just cash" / "financial check"** → only Cash & Finance + AR-related risks -- **"Pipeline only" / "deals check"** → only Pipeline section + stalled-deal risks -- **"Watch list" / "anything urgent"** → only Watch List + all risks, no metric sections -- **"Quick snapshot before a call"** → TL;DR + #1 Priority only, no full sections - -## What not to do - -- **Do not ask permission before pulling data.** If the skill was invoked, run it. Asking "should I check QuickBooks?" defeats the whole point. -- **Do not invent or estimate numbers.** If a source returned nothing, say "n/a" explicitly. Never fill a gap with guesswork. -- **Do not skip the delta.** A number without a comparison is a missed insight. If there's no prior-period baseline, say "(no prior baseline)" rather than omitting the field. -- **Do not surface connector errors mid-pulse.** Log them to the appendix. The pulse leads with what was delivered. - -## Reference files - -- `reference/data_sources.md` — exact connector tool → metric mapping with fallbacks -- `reference/thresholds.md` — 🟢/🟡/🔴 cutoffs, tunable per owner -- `reference/output_template.md` — exact markdown structure; do not deviate -- `reference/gotchas.md` — known failure modes (QB states, Gmail auth, Slack write) diff --git a/small-business/skills/business-pulse/reference/data_sources.md b/small-business/skills/business-pulse/reference/data_sources.md deleted file mode 100644 index de0d32499..000000000 --- a/small-business/skills/business-pulse/reference/data_sources.md +++ /dev/null @@ -1,86 +0,0 @@ -# Data Sources - -Exact mapping from each pulse section to the MCP tool that produces it. **Dispatch all calls in a single parallel batch** — do not pull serially. - -## Cash & Finance (QuickBooks) - -| Metric | Tool | Notes | -|---|---|---| -| Cash / bank balance | `cash-flow-quickbooks-account` | Current balance; show delta vs. prior week if available | -| MTD revenue | `profit-loss-quickbooks-account` | Current month vs. prior month | -| Outstanding receivables | QuickBooks invoice list | Filter to open/unpaid | -| AR aging | QuickBooks invoice list | Group by days since due: 0–30, 31–60, 61+ | -| Overdue invoices | QuickBooks invoice list | Filter to due_date > 30 days past; name customer + amount + days overdue | - -**QB state handling**: if `cash-flow-quickbooks-account` returns an error, empty response, or "not connected" state, mark the entire Cash section as "n/a — QuickBooks unavailable" and continue. Do not retry. - -## Revenue & Sales (PayPal / Square / Stripe) - -| Metric | Tool | Notes | -|---|---|---| -| 7-day settlement total | PayPal transactions | Sum completed settlements in window | -| Sales trend | PayPal transactions | This 7 days vs. prior 7 days; compute delta | -| Failed / pending transactions | PayPal transactions | Flag any > $200 | -| Square settlements | Square (if connected) | Same as PayPal — sum + trend | -| Stripe revenue | Stripe `list_invoices` (if connected) | Paid invoices in window | - -Use whichever payment connectors are available. If both PayPal and Square are connected, report combined and per-source. - -## Pipeline (HubSpot) - -| Metric | Tool | Notes | -|---|---|---| -| Pipeline by stage | `get_crm_objects` type=deals | Group by deal stage; sum amount | -| Deals closed this week | `search_crm_objects` | Filter closedate in window, stage = closed-won | -| Deals gone cold | `search_crm_objects` | Filter hs_last_activity_date > 7 days ago, open stage | -| New leads this week | `search_crm_objects` | Filter createdate in window | -| Stalled/slipped deals | `search_crm_objects` | Open deals where closedate < today | - -## Commitments (Google Calendar) - -| Metric | Tool | Notes | -|---|---|---| -| This week's key items | `list_events` | Filter to current week; surface meetings with customers, deadlines, important holds | -| Next 7 days | `list_events` | Forward-looking view; highlight anything with external parties | - -## Watch List (Gmail) - -| Metric | Tool | Notes | -|---|---|---| -| Urgent threads | `search_threads` | Query: `is:important OR is:starred` in last 7 days | -| Customer escalations | `search_threads` | Query: terms like "escalation," "complaint," "cancel," "refund," "urgent" in last 7 days | -| Time-sensitive requests | `search_threads` | Query: `is:unread` + keywords like "deadline," "ASAP," "today" | - -**Gmail fallback**: if the Gmail call errors (auth flaky — this is a known issue), skip Watch List silently and add "Gmail unavailable" to the appendix. Do not surface the error in the pulse body. - -## Internal Signals (Slack / Teams) - -| Metric | Tool | Notes | -|---|---|---| -| Urgent threads | Slack search (if connected) | Threads with @mentions or urgency signals in owner-relevant channels | -| Action items | Slack search | Messages directed at the owner or tagged for follow-up | - -## Customer Support (Intercom / Zendesk) - -| Metric | Tool | Notes | -|---|---|---| -| Open tickets | Intercom `search_conversations` / Zendesk | Count open; flag any > 48h unresolved | -| Escalations | Intercom `search_conversations` | Filter to priority or tagged escalation | - -Include only if connector is available; omit section entirely if not. - -## Risks scan - -Run these alongside the metric pulls — don't wait for metrics to finish first. - -| Risk | Source | Trigger condition | -|---|---|---| -| Overdue AR | QuickBooks invoices | due_date > 30 days past, unpaid | -| Stalled deals | HubSpot | Open deal, no activity 7+ days | -| Slipped deals | HubSpot | Open deal, closedate in past | -| Urgent Gmail threads | Gmail | `is:important` or escalation keywords | -| Failed payments | PayPal / Square | Failed or pending > $200 | - -## Parallelization - -All of the above should fire in a single tool-call batch. A complete pulse is typically 8–15 parallel calls. If one errors, the rest proceed normally and the failed source appears in "Sources unavailable" at the bottom of the pulse. diff --git a/small-business/skills/business-pulse/reference/gotchas.md b/small-business/skills/business-pulse/reference/gotchas.md deleted file mode 100644 index b6cd51615..000000000 --- a/small-business/skills/business-pulse/reference/gotchas.md +++ /dev/null @@ -1,103 +0,0 @@ -# Gotchas - -Known failure modes for the business-pulse skill. Good / Bad pairs. - ---- - -## Gotcha: QuickBooks returns unexpected state - -**Why it matters:** QuickBooks can return empty results, a sync-in-progress state, or an auth error without throwing a hard exception. Treating silence as "no data" causes the pulse to skip Cash entirely without telling the owner — they assume their business has no QuickBooks data. - -### ✗ Bad - -``` -Claude: [QuickBooks returns empty response] - → skips Cash section silently - → pulse presents no cash data; owner assumes QB isn't connected -``` - -The owner spends 10 minutes reconnecting QuickBooks before realizing it was always connected — just in a transient state. - -### ✓ Good - -``` -Claude: [QuickBooks returns empty response or error] - → Cash section header present with: "n/a — QuickBooks unavailable (sync error or auth required)" - → "Sources unavailable: QuickBooks — returned empty response" in appendix -``` - -The owner sees the gap explicitly and can decide whether to reconnect or proceed with a partial pulse. - ---- - -## Gotcha: Gmail auth failure mid-pulse - -**Why it matters:** Gmail auth is intermittently flaky in workshop environments. Surfacing a raw auth error in the middle of the pulse looks broken and breaks the owner's trust in the skill. - -### ✗ Bad - -``` -Claude: [Gmail auth error mid-composition] - → "Error: Gmail authentication failed. Please re-authenticate." - → pulse output stops or shows raw error in Watch List section -``` - -The owner sees a broken tool, not a useful briefing. - -### ✓ Good - -``` -Claude: [Gmail auth error] - → continues pulse without Watch List section - → appendix: "Gmail — auth error; Watch List unavailable this run" - → all other sections unaffected -``` - -The pulse still delivers value. The owner is informed, not alarmed. - ---- - -## Gotcha: Asking permission before pulling data - -**Why it matters:** The skill's core value is doing the work without prompting. An owner who invoked the pulse already implicitly approved the data pull. Asking "should I check QuickBooks?" or "can I read your emails?" defeats the purpose and erodes trust in the skill as an autonomous assistant. - -### ✗ Bad - -``` -Owner: "catch me up on the business" -Claude: "Should I check QuickBooks for your cash balance? And is it okay to look at your HubSpot pipeline?" -``` - -Three more round trips before anything useful is delivered. - -### ✓ Good - -``` -Owner: "catch me up on the business" -Claude: [immediately dispatches all parallel tool calls] - → presents pulse in one response -``` - ---- - -## Gotcha: Slack write requires explicit confirmation - -**Why it matters:** Slack write is not tested in the standard validation path and posts to channels other people can see. Auto-posting without confirmation could embarrass the owner or spam a team. - -### ✗ Bad - -``` -Claude: [at end of pulse] - "I've posted this to #general." -``` - -Owner never asked for a Slack post; now the whole team has the financial data. - -### ✓ Good - -``` -Claude: [at end of pulse] - "Want me to post this to Slack? If so, which channel?" -``` - -Slack write only happens with a specific "yes + channel name" from the owner. Never assume. diff --git a/small-business/skills/business-pulse/reference/output_template.md b/small-business/skills/business-pulse/reference/output_template.md deleted file mode 100644 index 4ad20bd1f..000000000 --- a/small-business/skills/business-pulse/reference/output_template.md +++ /dev/null @@ -1,107 +0,0 @@ -# Output Template - -This is the exact structure every pulse must follow. Do not reorder sections. Omit a section only if its connector returned no data — never leave an empty header. - -Variables in `{{double braces}}` are placeholders — replace with computed values. Arrow convention: ▲ up, ▼ down, ▬ flat (<1% change). Always show the delta value after the arrow. - ---- - -```markdown -# Business Pulse — {{Day, Month Date, Year}} - -**Overall: {{🟢|🟡|🔴}} {{one-line status, e.g. "Cash healthy, one overdue invoice needs attention."}}}** - -## TL;DR - -- {{Most important number-backed fact, e.g. "Cash balance $84k, down $6k WoW — two large vendor payments cleared."}} -- {{Second most important, e.g. "$3,400 from Acme Corp is 47 days overdue — no response since Mar 12."}} -- {{Third, e.g. "Pipeline $128k weighted; two deals gone cold this week."}} - ---- - -## 💰 Cash & Finance — {{🟢|🟡|🔴}} - -- **Cash balance**: ${{BALANCE}} ({{▲|▼|▬}} ${{DELTA}} WoW) -- **MTD revenue**: ${{MTD}} vs. ${{PRIOR_MTD}} last month ({{▲|▼|▬}} {{PCT}}%) -- **Outstanding AR**: ${{AR_TOTAL}} across {{N}} open invoices - -**AR aging** -- 0–30 days: ${{AR_0_30}} -- 31–60 days: ${{AR_31_60}} {{🟡 if nonzero}} -- 61+ days: ${{AR_61}} {{🔴 if nonzero}} - -**Overdue > 30 days** -- {{customer}} — ${{amount}} ({{days}} days overdue) -- {{customer}} — ${{amount}} ({{days}} days) - ---- - -## 📈 Revenue & Sales — {{🟢|🟡|🔴}} - -- **7-day settlements**: ${{SETTLEMENTS}} ({{▲|▼|▬}} {{PCT}}% vs. prior 7 days) -- **PayPal**: ${{PAYPAL_TOTAL}} | **Square**: ${{SQUARE_TOTAL}} {{omit if not connected}} - -**Unusual transactions** -- {{amount}} — {{counterparty}} — {{status: failed/pending/large}} -- {{or "No unusual transactions this week."}} - ---- - -## 🔮 Pipeline — {{🟢|🟡|🔴}} - -- **Weighted pipeline**: ${{WEIGHTED}} ({{▲|▼|▬}} ${{DELTA}} WoW) -- **Coverage vs. target**: {{RATIO}}x monthly target {{🟢|🟡|🔴}} -- **Closed-won this week**: ${{CW}} across {{N}} deals -- **New deals created**: {{N}} (${{TOTAL}}) - -**Deals needing attention** -- {{deal name}} — {{stage}} — {{why: gone cold / slipped / stalled}} -- {{or "No deals flagged this week."}} - ---- - -## 📅 This Week - -- {{Meeting/deadline — external party, why it matters}} -- {{Meeting/deadline}} -- {{Meeting/deadline}} -{{3–5 items max. Omit internal-only calendar noise.}} - ---- - -## ✉️ Watch List - -- {{sender / source}} — {{one-line summary of what needs attention}} -- {{sender / source}} — {{summary}} -{{Or: "No urgent threads detected." — include this explicitly so the owner knows the check ran.}} - ---- - -## ⚠️ #1 Priority - -{{One specific thing to act on today. Name amounts, people, deadlines. -Not "review cash flow" — say "The $4,200 invoice from Acme Corp is 23 days -overdue. Call Sarah Chen at 415-555-0192 today."}} - ---- - -## Appendix - -**Window**: {{date range}} - -**Sources pulled**: {{list of connectors that returned data}} - -**Sources unavailable**: {{list with reason, e.g. "Gmail — auth error" or "Zendesk — not connected"}} - -**Thresholds used**: {{note any TODO thresholds that are still defaults}} -``` - ---- - -## Formatting rules - -1. **Dollar amounts**: `$43k` for thousands, `$1.2m` for millions. No unnecessary decimals. -2. **Percentages**: one decimal for trends (e.g. "▲ 8.3%"), integers elsewhere. -3. **Dates**: human-readable in prose ("Apr 14"), ISO in metadata ("2026-04-14"). -4. **Arrow spacing**: `▲ $2k` not `▲$2k`. -5. **Length**: aim for one page. Two pages max. If a section balloons, tighten prose. diff --git a/small-business/skills/business-pulse/reference/thresholds.md b/small-business/skills/business-pulse/reference/thresholds.md deleted file mode 100644 index ae0f8ee04..000000000 --- a/small-business/skills/business-pulse/reference/thresholds.md +++ /dev/null @@ -1,69 +0,0 @@ -# Thresholds - -Red/yellow/green cutoffs for each section of the pulse. These are SMB defaults — edit them to match the owner's actual targets and plan. - -Any threshold marked `# TODO: confirm with owner` should produce a note at the top of the first pulse output so the owner knows to tune it. - ---- - -## Cash & Finance - -**Cash runway** -- 🟢 ≥ 6 months # TODO: confirm with owner -- 🟡 3–6 months -- 🔴 < 3 months - -**Revenue trend (MoM)** -- 🟢 ≥ 0% (flat or growing) -- 🟡 -5% to 0% -- 🔴 < -5% - -**AR aging** -- 🟢 No invoices past 31 days -- 🟡 Any invoice 31–60 days past due -- 🔴 Any invoice 60+ days past due OR total 61+ bucket > 10% of AR - -**Overdue threshold**: any single invoice past due > 30 days gets named explicitly in the pulse — not just counted. - ---- - -## Revenue & Sales - -**7-day sales trend (vs. prior 7 days)** -- 🟢 ≥ 0% -- 🟡 -10% to 0% -- 🔴 < -10% - -**Failed transactions** -- 🟡 Any failed transaction > $200 -- 🔴 Any failed transaction > $1,000, or 3+ failures in the week - ---- - -## Pipeline - -**Pipeline coverage** (weighted pipeline ÷ monthly revenue target) # TODO: confirm target with owner -- 🟢 ≥ 2x monthly target -- 🟡 1–2x -- 🔴 < 1x - -**Stale deal**: no activity in 7+ days → flag # TODO: owner may prefer 14 days -**Slipped deal**: open deal with close date in past → always flag - ---- - -## Watch List - -No numeric thresholds — any escalation or complaint in Gmail/Slack gets surfaced. Severity is contextual; surface and let the owner decide. - ---- - -## Overall status rollup - -The pulse-level overall status is the worst section status. Override: if any individual risk names a specific customer with a dollar amount and a deadline within 7 days, roll up to 🔴 regardless of section colors. - ---- - -## When to tune - -Revisit these after 4 weeks of use. The defaults are conservative starting points — a healthy business will feel like it's always 🟢. Tighten them to reflect where the owner actually wants to act. diff --git a/small-business/skills/call-list/SKILL.md b/small-business/skills/call-list/SKILL.md deleted file mode 100644 index d70839327..000000000 --- a/small-business/skills/call-list/SKILL.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -name: call-list -description: Ranks the top-5 leads most worth calling today, supplies talking points from email history, blocks time on the calendar, and drafts follow-up messages. Accepts optional count and date arguments. -allowed-tools: Read, WebFetch, Bash ---- - -Run the lead prioritization. Scan the pipeline, rank by urgency and opportunity, pull relevant email context, and get the owner ready to make calls. - -Parse arguments: -- `--n` (default: `5`) — number of leads to surface (1–10) -- `--date` (default: today) — date to build the call list for (`YYYY-MM-DD`) - -## Step 1 — Pipeline scan - -Using the `lead-triage` skill workflow: - -1. Pull open HubSpot deals and contacts with activity in the last 30 days. -2. Pull email threads from Mail for each lead (last 3 emails per contact). -3. Score each lead on: - - **Recency**: days since last owner touchpoint (lower = better) - - **Stage**: how close to close (later stage = higher priority) - - **Signal**: any recent inbound activity (email open, reply, calendar hold, web visit) - - **Value**: deal size from HubSpot - -## Step 2 — Rank and select top N - -Rank all scored leads and select the top `--n`. For ties, prefer leads with unanswered inbound signals. - -For each selected lead, produce a call card: - -``` -{Rank}. {Contact Name} — {Company} -Deal: ${amount} | Stage: {stage} | Last contact: {X days ago} -Signal: {most recent activity} - -TALKING POINTS -• {point from email/deal context} -• {point from email/deal context} -• {open question to ask} - -GOAL FOR THIS CALL: {one sentence — advance to next stage / re-engage / close} -``` - -## Step 3 — Calendar block - -For each lead on the list, offer to block 20 minutes on the owner's calendar for the target date. - -Show the proposed calendar entries: -``` -{time slot} — Call: {Contact Name} ({Company}) -``` - -Wait for owner to confirm which calls to block before creating calendar events. - -## Step 4 — Draft follow-ups - -For any lead that has an unanswered email older than 3 days, draft a brief follow-up: -``` -Subject: Re: {thread subject} - -Hi {first name}, - -{One sentence referencing prior conversation}. {One sentence with a clear next step or question}. - -{Sign-off} -``` - -## Connector failures - -If HubSpot is unreachable, stop and tell the owner — lead scoring requires CRM data. If Mail is unreachable, skip Steps 3-4 (email context and follow-ups) and note "Mail not connected — email context and follow-up drafts skipped" in output. If Google Calendar is unreachable, skip calendar blocking and note it. - -## Approval gates - -- **Never send emails automatically.** Present drafts for owner approval only. -- **Never create calendar blocks without owner confirmation** — show the proposed list first. -- **Never update HubSpot deal stages automatically.** - -## Output - -Present the ranked call list with talk tracks. Then show proposed calendar blocks and ask for confirmation. Then show follow-up drafts and ask which to send. diff --git a/small-business/skills/canva-creator/SKILL.md b/small-business/skills/canva-creator/SKILL.md deleted file mode 100644 index a6f4a09fc..000000000 --- a/small-business/skills/canva-creator/SKILL.md +++ /dev/null @@ -1,412 +0,0 @@ ---- -name: canva-creator -description: > - Takes an approved content brief and executes a campaign end-to-end: builds - the posting calendar, generates Canva designs for social posts, drafts - caption and email copy, and stages social sends in HubSpot. Canva is used - for social posts only (Instagram, Facebook, X, LinkedIn) — email content - is drafted as plain text and surfaced inline for the owner to send from - their own tool. Every step requires explicit owner approval. Use when the - user says "make the content," "generate the posts," "create the assets," - "turn this into a campaign," or hands off an approved brief for execution. ---- - -# Canva Creator - -## Scope - -This skill handles a campaign in five sequential stages, each gated by owner -approval: - -``` -brief → calendar → asset inventory → Canva designs → copy → HubSpot staging -``` - -| Path | Channels | What this skill produces | -|------|----------|--------------------------| -| Canva (social) | Instagram, Facebook, X/Twitter, LinkedIn | Canva design + caption + scheduled HubSpot post | -| Text-only | Email (newsletter, marketing, drip) | Subject + preheader + body, surfaced inline for the owner to send | - -**Canva is not used for email rows under any circumstance** — no templates, -no autofill, no design copies, no asset uploads, no exports. The owner -explicitly descoped Canva from the email path because email-template -autofill produces placeholder graphics when image slots exceed available -photos, and variation thumbnails fail to render in chat previews. If the -owner asks for a Canva email design, see `reference/gotchas.md` for the -redirect language. - ---- - -## Pre-flight - -Before Stage 1, confirm: - -1. **Brief.** The user has referenced or pasted an approved brief. If not: - "I'll need the content brief before I can build the campaign. Do you - have one from the content-strategy skill, or would you like to write - one now?" - -2. **Canva tier.** Pro/Teams require manual template selection from the - user's library (no autofill API). Enterprise can autofill from brand - templates. - -3. **HubSpot tier.** Social staging requires Marketing Hub Professional. - Starter or Free → skip Stage 5 and export a CSV instead - (see [reference/hubspot-staging.md](reference/hubspot-staging.md)). - -4. **Brand assets.** Confirm the path to product photos on disk or that - the brand kit is live in Canva. - -5. **Generation budget.** Estimate the campaign's Canva volume and surface - it before Stage 1 begins. Default is 3 candidates per Canva-bound row; - each design costs ~5 API calls (autofill + export + polling). - - ``` - Generation budget for this campaign: - Canva (social) rows: 8 - Candidates per row: 3 (default — say "single candidate" to use 1) - Total designs: 24 - API calls (approx): ~120 (autofill + export + polling) - - Canva limit: 100 requests/minute. This will take ~2-3 minutes of - generation, well within your tier limits. Proceed? - ``` - - If the projected total designs exceeds 30, recommend single-candidate - mode upfront — large campaigns run out of headroom fast. The owner can - override the default to 1, 2, or 3 candidates per row before Stage 1 - starts. Lock the chosen value for the entire session. - ---- - -## Workflow - -### Stage 1 — Posting calendar - -Pull from the brief: content themes, channels, cadence, hard dates -(launches, sales, holidays). - -Build a calendar table with a `Path` column that routes every row to either -Canva or text-only drafting: - -| Date | Channel | Path | Theme | Asset type | Caption/Subject angle | -|------|---------|------|-------|------------|-----------------------| -| Jun 2 | Instagram feed | Canva (social) | Linen launch | Square post | "finally, a dress…" | -| Jun 5 | Email | Text-only | Linen launch | Email body | "Linen that actually breathes" | - -Tag every email-channel row as `Text-only` before presenting. Cap at 30 -days unless the brief specifies otherwise. Flag scheduling conflicts (two -posts same day for the same product) up front. - -**Checkpoint 1.** Present the calendar. Ask: "Does this match the plan? -Any dates to shift, channels to add, or themes to swap?" Iterate until -approved, then restate the split out loud — "N rows go through Canva, M -rows go through text-only drafting" — before moving on. Catching a -miscategorization here is free; catching it after generating designs -isn't. - ---- - -### Stage 2 — Asset inventory (Canva rows only) - -Email rows skip this stage entirely. For each `Canva (social)` row, build -a manifest of what the template needs and what's already available. - -1. **Enumerate every image slot by name.** Square Instagram posts usually - have 1-2 image slots; carousels and product grids can have 5+. List - them individually (`Header_Image`, `Product1_Image`, `Product2_Image`, - …) — never roll them up as "product images." - - Enterprise: read field names from `dataset[].label` on the brand - template (`GET /v1/brand-templates/{id}`). - - Pro/Teams: count every distinct image rectangle in the template. - -2. **Inventory available assets.** Text content from the brief (product - names, offer copy, taglines, pricing), product photos already uploaded - to Canva (`GET /v1/assets`) or on the owner's disk, brand kit colors - and fonts (Enterprise). - -3. **Build the slot-by-slot gap table.** One row per slot per design — not - per design. - - | Date | Slot name | Slot kind | Available asset | Status | - |------|-----------|-----------|-----------------|--------| - | Jun 2 | Hero_Image | image | bloom_summer.jpg → asset_id pending | upload | - | Jun 2 | Headline | text | "Summer linen, finally" | ready | - | Jun 9 | Product1_Image | image | — | **MISSING** | - -4. **Resolve slot/asset mismatches with the owner.** If the template has - more image slots than the brief provides photos, pause and ask: - - ``` - The "Summer Carousel" template has 5 image slots. The brief gave me 1 - photo (bloom_summer.jpg). How should I fill the other 4? - - 1. Reuse the same photo across all 5 slots - 2. You send me 4 more photos (file paths) - 3. Pick a simpler template with fewer slots - ``` - - No generation calls until the owner picks. Generating with empty slots - produces designs full of Canva's default landscape placeholders. - -5. **Upload missing photos and capture verified asset IDs.** Upload via - `POST /v1/asset-uploads`, then poll `GET /v1/asset-uploads/{job_id}` - until `status == "success"`. Record `asset.id` from the response — this - is the only value that works in an autofill image field. Passing an - empty string, a URL, a file path, or a stale ID silently renders - Canva's stock landscape graphic instead of the photo. - -6. **Confirm the manifest.** Show the owner the completed slot-by-slot - table with every slot resolved and every image `asset.id` confirmed. - This is the last stop before Canva API calls. - ---- - -### Stage 3 — Canva design generation - -Before any Canva API call, re-read the calendar and drop any row whose -`Path` is not `Canva (social)`. Email rows do not pass through this -stage. - -Generate designs **one calendar row at a time**, with 3 candidates per row -(or the value chosen at pre-flight). Each row follows the same loop: -generate candidates → verify → export → visually check → retry failures -→ present → wait for owner pick → next row. Pause 30 seconds between -rows. This caps the burst at 3 generations + 3 exports per ~30s — well -under Canva's 100 req/min rate limit. Do not parallelize multiple rows; -one row at a time is the protection that keeps the owner from hitting -quota mid-campaign. - -**Polling cadence.** Poll job status every 3-5 seconds, not faster. -Tighter intervals burn quota without speeding up completion. - -**Preview URLs — only one type is safe to embed.** Autofill responses -return `design.canva.ai` thumbnails that expire within minutes; embedding -them as markdown images produces broken "Show Image" placeholders. -Permanent export URLs (`export-download.canva.com` or the `export-design` -MCP tool) do not expire. Native Cowork carousels render the autofill -result directly using the connector's authenticated session — let them -render on their own, don't re-embed. - -#### Row loop - -1. **Resolve template.** (Once per session — same template across rows - unless the calendar mixes asset types.) - - Enterprise: `GET /v1/brand-templates` filtered by asset type. - - Pro/Teams: `GET /v1/designs?ownership=any&query={template name}`, - surface top 3 to the owner, confirm one before generating. - -2. **Generate the row's candidates in parallel.** Fire the row's 3 - candidates simultaneously (or N from pre-flight). - - Enterprise: `POST /v1/autofills` per candidate with the template ID - and field values. Poll all jobs concurrently. - - Pro/Teams: `POST /v1/designs` to create copies. Describe the text and - image edits the owner applies in Canva; collect design IDs back. - -3. **Verify job status.** For each candidate, confirm - `GET /autofills/{job_id}` returned `status == "success"` and - `result.design.id` is present. Handle errors per-design: - - `JOB_FAILED` → read `job.error.message`, fix the field values or - asset IDs, retry once. - - `RATE_LIMIT_EXCEEDED` (first hit this session) → wait 60s, retry - that one candidate once. This handles transient spikes. - - `RATE_LIMIT_EXCEEDED` (second hit this session) **or** any - `quota_exceeded` / daily-cap error → stop generation immediately. - Do not retry. Surface progress and ask: - - ``` - Canva is rate-limiting the campaign. Status so far: - ✓ Generated: Posts 1-4 (12 designs) - ⏸ Remaining: Posts 5-8 (12 designs not yet generated) - - How should I proceed? - 1. Switch to 1 candidate per remaining row (4 designs total) — finishes now - 2. Pause campaign — resume in 60 minutes when quota refills - 3. Stop generation — work with what we have, move to captions - ``` - - Wait for the owner's choice. Do not loop on retry. - -4. **Export each successful candidate to a permanent PNG.** Fire the - row's exports in parallel. - - REST: `POST /v1/exports` with `format.type: "png"`, poll - `GET /v1/exports/{job_id}` until success, capture `urls[0]`. - - Canva MCP: `export-design` with the design ID. - - These permanent URLs are what get embedded in previews and attached to - the HubSpot post later. The autofill response thumbnail is never used - downstream. - -5. **Visually verify each export.** Look at the image and reject any of - these — they all indicate an unfilled slot or wrong asset: - - Generic landscape with clouds and green hills (Canva's default - placeholder) - - Solid gray rectangles where a photo should be - - Lorem-ipsum or template-default text - - Subject that doesn't match the brief (wrong product, wrong brand) - - If a candidate fails verification: re-check the manifest for the - affected slot, fix the `asset.id`, regenerate that single candidate, - re-export, re-verify. - -6. **Retry per-candidate on partial failure.** If 1 of N candidates in - the row failed at Step 3 or 5, regenerate just that one — don't redo - the whole row and don't present a partial broken carousel. If the - second attempt also fails: - - ``` - The third candidate for the Jun 9 post keeps failing — Canva returned - [error / rendered placeholder]. How should I proceed? - - 1. Skip it — present the other 2 and move on - 2. Swap to a simpler template for just this candidate - 3. Try once more with a different photo - ``` - -7. **Present the row's candidates.** Let the native Cowork carousel - render the autofill tool result. Below it, add a text prompt: - - ``` - Jun 9 candidates are ready — scroll through the carousel above. - Which one should I use for the Jun 9 post? - ``` - - If the carousel doesn't render or one position is broken, embed the - permanent export PNG URLs from Step 4 instead. Final fallback: link to - the design's Canva edit URL (`https://www.canva.com/d/{design_id}`). - Never re-embed `design.canva.ai` URLs. - -8. **Pause 30 seconds, then move to the next row.** - -**Checkpoint 2.** Satisfied once the owner has picked one design per -calendar row. If they want a regenerate, regenerate only that one -candidate. - ---- - -### Stage 4 — Copy drafting - -For each calendar row, draft the copy. Social rows get a caption; email -rows get a full email. - -**Social captions** — Instagram, Facebook, X, LinkedIn: - -- Length: channel-appropriate (Instagram ≤ 2,200 chars; Facebook ≤ 500 - recommended; X ≤ 280). -- Structure: hook → one product benefit → CTA → 3-5 hashtags (not 30). -- Voice: match the brief's tone markers. If the brief says "casual and - friendly," don't write corporate copy. -- No filler. No "Exciting news!" or "We're thrilled to announce." Open - with the value. - -**Email content** — Claude writes the entire email; no Canva: - -- Subject: ≤ 50 chars, specific, no clickbait. "Spring projects are - booking up" beats "Don't miss out!" -- Preheader: ≤ 90 chars, complements the subject without repeating it. -- Body: plain prose, 100-250 words. Opening line that earns the read → - 1-2 paragraphs of substance → single clear CTA → sign-off. -- Voice: same tone markers as social. Owners want their emails to sound - like them, not like a templated newsletter. -- No image references. Don't write "see image above." If the owner wants - visuals, they add them in their email tool. -- One CTA per email. Pick the most important action and lead with it. - -Present captions inline below each social row. Present full emails -inline below each email row: - -``` -Subject: -Preheader: - - -``` - -For worked examples, see -[reference/examples/boutique-brief-campaign.md](reference/examples/boutique-brief-campaign.md). - -**Checkpoint 3.** "Any captions or emails to rewrite? Flag the date and -what to change." Iterate until approved. - ---- - -### Stage 5 — HubSpot staging + email handoff - -Stage social posts in HubSpot. Email content is not staged — it's -surfaced inline for the owner to copy into their email tool. For API -field reference, see -[reference/hubspot-staging.md](reference/hubspot-staging.md). - -1. **Create the campaign.** `POST /marketing/v3/campaigns` with the - campaign name and start/end dates from the calendar. - -2. **Stage each social post.** `POST` to the HubSpot Social API per - `Canva (social)` row: - - `channel`: map calendar channel to HubSpot account ID - - `scheduledAt`: ISO 8601 datetime — confirm it's in the future before - calling - - `content.body`: approved caption - - `attachments`: permanent Canva export PNG URL from Stage 3 - - `status`: `SCHEDULED` (never `PUBLISHED`) - -3. **Confirm the queue.** Call - `GET /marketing/v3/social/posts?status=SCHEDULED`, surface the list, - provide a direct link to the HubSpot campaign view. - -4. **Surface email content for handoff.** For each email row, present the - approved subject + preheader + body inline, grouped by send date. The - owner copies these into their email tool (HubSpot Marketing Email, - Mailchimp, Gmail). - -**Final checkpoint.** - -``` -Your social posts are scheduled in HubSpot: [link] -They'll go out as scheduled — you can cancel or edit any post in HubSpot. - -Email content is drafted below — copy each into your email tool when -you're ready to send: - - Jun 5 — "Spring projects are booking up" - Jul 15 — "Summer maintenance windows are filling" - -Anything to change before we're done? -``` - ---- - -## Approval gates - -- **No Canva calls for email rows.** Re-check the `Path` column before - every API call. -- **No publishing.** Every HubSpot post is staged as `SCHEDULED`; the - owner controls go-live. -- **Always surface the generation budget at pre-flight.** Owner sees the - total design count and approves before Stage 1 begins. -- **One row at a time in Stage 3.** Candidates within a row fire in - parallel, but rows are sequential with a 30s gap — this is the quota - protection. -- **On the second quota error, pause and ask.** Never loop on retry. -- **Always export to a permanent PNG before presenting.** Job success - doesn't mean the design rendered correctly. -- **Never embed `design.canva.ai` URLs in messages.** They expire. -- **Never regenerate the whole row when one candidate fails.** - Per-candidate retry only. -- **Never auto-select a template for Pro/Teams users.** Always confirm. -- **Never skip slot-by-slot inventory.** Multi-slot templates render - placeholder landscapes when any slot is empty. -- **Never skip Checkpoint 1.** Generating before the calendar is approved - is the largest source of wasted work in this skill. - ---- - -## Reference - -- [reference/canva-api.md](reference/canva-api.md) — Canva Connect API - endpoints, asset upload, export formats, MCP equivalents -- [reference/hubspot-staging.md](reference/hubspot-staging.md) — HubSpot - Social API and CSV fallback for non-Pro tiers -- [reference/gotchas.md](reference/gotchas.md) — Good / Bad patterns for - every failure mode this skill has hit in production -- [reference/examples/boutique-brief-campaign.md](reference/examples/boutique-brief-campaign.md) - — full worked examples (single-slot social, multi-slot template) diff --git a/small-business/skills/canva-creator/reference/canva-api.md b/small-business/skills/canva-creator/reference/canva-api.md deleted file mode 100644 index 71dd2cc2b..000000000 --- a/small-business/skills/canva-creator/reference/canva-api.md +++ /dev/null @@ -1,208 +0,0 @@ -# Canva Connect API Reference - -Base URL: `https://api.canva.com/rest/v1` -Auth: Bearer token (OAuth 2.0). Scopes needed: `design:content:read`, `design:content:write`, `asset:read`, `asset:write`, `brandtemplate:content:read` (Enterprise only). - ---- - -## Table of contents - -1. [Tier requirements](#tier-requirements) -2. [Brand templates (Enterprise)](#brand-templates-enterprise) -3. [Autofill (Enterprise)](#autofill-enterprise) -4. [Design copy (Pro/Teams)](#design-copy-proteams) -5. [Asset upload](#asset-upload) -6. [Export](#export) -7. [Error codes](#error-codes) - ---- - -## Tier requirements - -| Feature | Free | Pro | Teams | Enterprise | -|---------|------|-----|-------|------------| -| Create designs | ✓ | ✓ | ✓ | ✓ | -| List own designs | ✓ | ✓ | ✓ | ✓ | -| Brand templates (read) | — | — | — | ✓ | -| Autofill brand templates | — | — | — | ✓ | -| Asset upload (brand kit) | — | — | — | ✓ | -| Asset upload (user) | — | ✓ | ✓ | ✓ | - ---- - -## Brand templates (Enterprise) - -**List brand templates:** -``` -GET /brand-templates?query={keyword}&ownership=organization -``` -Response fields of interest: -- `id` — pass this to autofill -- `title` — human-readable name -- `thumbnail.url` — preview image -- `dataset[].label` — autofill field labels (e.g., "Headline", "ProductName") - -Filter by `title` contains the asset type keyword (e.g., "square post", "story", "email header"). - ---- - -## Autofill (Enterprise) - -Populates a brand template's variable fields and creates a new design: - -``` -POST /autofills -{ - "brand_template_id": "", - "title": "Summer Sale — Post 1", - "data": { - "Headline": { "type": "text", "text": "Summer Sale: 30% off candles" }, - "ProductImage": { "type": "image", "asset_id": "" } - } -} -``` - -Response: `{ "job": { "id": "", "status": "queued" } }` - -Poll `GET /autofills/{job_id}` until `status == "success"`. The response -includes `result.design.id` — use this for export. - ---- - -## Design copy (Pro/Teams) - -There is no direct "copy template" endpoint for Pro/Teams users. Workflow: - -1. `GET /designs?ownership=any&query={template name}` — list designs by name -2. Show top 3 to user; get confirmation -3. `POST /designs` with `asset_type` to create a blank design of the right - dimensions, then describe what the user needs to update manually in Canva. - -Pro/Teams asset generation is semi-manual: Claude creates the design shell and -populates what the API allows; the user applies brand-specific edits in Canva -and returns the design ID for export. - ---- - -## Asset upload - -Use when the brief references product photos stored on the user's Desktop or -file system. - -**Step 1 — Initialize upload:** -``` -POST /asset-uploads -{ "name_base64": "", "types": ["image/jpeg"] } -``` -Response: `{ "job": { "id": "" }, "upload_url": "" }` - -**Step 2 — Upload file:** -``` -PUT -Content-Type: image/jpeg -Body: -``` - -**Step 3 — Poll until ready:** -`GET /asset-uploads/{job_id}` → wait for `status == "success"` → capture `asset.id`. - -Maximum file size: 100 MB. Supported types: `image/jpeg`, `image/png`, `image/webp`. - ---- - -## Export - -**Why export every design:** the autofill response thumbnail returned at -`design.canva.ai/...` is a short-lived authenticated CDN URL — it expires -within minutes and renders as a broken "Show Image" placeholder if embedded -in a markdown image after expiry. The `POST /exports` output is a -**permanent URL** that's safe to embed in chat previews, attach to HubSpot -posts, and share with the owner. - -Always export each design after generation, before showing previews. - -``` -POST /exports -{ - "design_id": "", - "format": { - "type": "png", - "export_quality": "regular", - "pages": [1] - } -} -``` - -Poll `GET /exports/{job_id}` until `status == "success"`. Response includes -`urls[]` — use `urls[0]` as the preview link and HubSpot attachment URL. - -**Canva MCP equivalents** (when using Cowork's Canva connector instead of -direct REST): - -| Need | MCP tool | Returns | -|------|---------|---------| -| Permanent preview URL | `export-design` | Permanent download URL (safe to embed) | -| Per-page thumbnail (more stable than autofill response, not permanent) | `get-design-thumbnail` | Page thumbnail URL | -| Design metadata only | `get-design` | Title, owner, page count, thumbnail | -| Upload from owner's machine | `upload-asset-from-url` | `asset_id` (one URL per call) | - -**Format guidance by channel:** - -| Channel | Type | Dimensions | -|---------|------|-----------| -| Instagram feed | `png` | 1080×1080 (square) | -| Instagram story / Reels cover | `png` | 1080×1920 | -| Facebook feed | `png` | 1200×630 | -| Email header | `png` | 600×200 | - ---- - -## Rate limits & generation budgeting - -**Hard limit:** 100 requests per minute per token. - -**Cost per design:** ~5 API calls — 1 `POST /autofills` + 1 `POST /exports` -+ ~3 polling rounds (`GET /autofills/{job_id}`, `GET /exports/{job_id}`). -Polling cadence should be 3-5 seconds; faster polling burns quota without -speeding up completion. - -**Safe ceiling:** ~15-20 designs per minute leaves comfortable headroom -under the 100 req/min cap. - -**Recommended pacing (used by Stage 3):** - -``` -3 candidates per row × 1 row at a time × 30s gap between rows -= 6 designs (~30 API calls) per 30 seconds -= 12 designs / minute, about half the ceiling -``` - -**Pre-flight budget formula:** - -``` -total_designs = (Canva-bound rows) × (candidates per row, default 3) -total_api_calls ≈ total_designs × 5 -generation_time ≈ (total_designs / 12) minutes -``` - -**Back-off pattern for `RATE_LIMIT_EXCEEDED`:** - -1. First hit in a session → wait 60s, retry that one candidate. Treats - the error as a transient spike. -2. Second hit in the same session, or any `quota_exceeded` / daily-cap - error → stop generation and surface progress to the owner. Do not - retry. The skill asks the owner whether to (a) drop to 1 candidate - per remaining row, (b) pause and resume in 60 minutes, or (c) stop - and move to captions with what's already generated. - ---- - -## Error codes - -| Code | Meaning | What to do | -|------|---------|-----------| -| `PERMISSION_DENIED` | Scope missing or wrong tier | Check tier; ask user to reconnect Canva with correct scopes | -| `DESIGN_NOT_FOUND` | Wrong design ID | Re-list designs and confirm ID | -| `AUTOFILL_FIELD_NOT_FOUND` | Template field name mismatch | Call `GET /brand-templates/{id}` and re-read `dataset[].label` | -| `RATE_LIMIT_EXCEEDED` | Too many requests | First hit: wait 60s, retry once. Second hit: stop and ask owner (see Rate limits above) | -| `JOB_FAILED` | Async job failed | Check `job.error.message`; common cause is oversized asset | diff --git a/small-business/skills/canva-creator/reference/examples/boutique-brief-campaign.md b/small-business/skills/canva-creator/reference/examples/boutique-brief-campaign.md deleted file mode 100644 index d8f84bb12..000000000 --- a/small-business/skills/canva-creator/reference/examples/boutique-brief-campaign.md +++ /dev/null @@ -1,181 +0,0 @@ -# Worked Example: Retail Boutique Brief → Campaign - -**Business:** Bloom & Thread — women's clothing boutique, Charleston SC -**Canva tier:** Teams (no Enterprise) -**HubSpot tier:** Marketing Hub Professional -**Brief source:** content-strategy skill output (approved by owner) - ---- - -## Input: Approved brief (summary) - -``` -Push hard: Linen summer dresses (top seller, trending +22% MoM) -Hold steady: Accessories -Seasonal opportunity: Back-to-school transition (Aug 15 pivot) -Offer: Buy 2 dresses, get 1 accessory free (runs June 1–July 31) -Channels: Instagram feed, Instagram story, Facebook feed -Cadence: 3× per week, Mon/Wed/Fri, 10 AM ET -Voice: Warm, conversational, light humor. No corporate copy. -``` - ---- - -## Stage 1: Posting calendar (presented for approval) - -| Date | Channel | Theme | Asset type | Caption angle | -|------|---------|-------|------------|---------------| -| Jun 2 | Instagram feed | Linen dresses launch | Square post | Product intro — "finally, a dress you can wear to both places" | -| Jun 4 | Facebook feed | Linen dresses | Landscape post | Social proof — "our most-reached-for item this spring" | -| Jun 6 | Instagram story | Buy 2 get 1 offer | Story (16:9) | Offer urgency — swipe up | -| Jun 9 | Instagram feed | Linen styling tip | Square post | Education — "3 ways to style the linen midi" | -| Jun 11 | Facebook feed | Behind the scenes | Landscape post | Brand story — how they're made | -| Jun 13 | Instagram story | Weekend outfit inspo | Story (16:9) | Lifestyle — "your Saturday, sorted" | -| … | … | … | … | … | - -*Owner approved — "move Jun 11 to Jun 12, I'm posting about the sale that day. Otherwise great."* -*(Calendar updated; proceeding to Stage 2.)* - ---- - -## Stage 2: Canva asset generation (Pro/Teams path) - -**Template selection exchange:** - -``` -Claude: I found 3 square-post templates in your Canva library: - 1. Boutique Square - Cream (last edited Apr 2026) - 2. Summer Promo - Sand (last edited Mar 2026) - 3. Product Feature Bold (last edited Feb 2026) - Which should I use for the feed posts? - -Owner: The cream one, #1. - -Claude: Got it. I'll use "Boutique Square - Cream" for all feed posts. - Creating design shells now — I'll give you the links to fill in - the product photos and text in Canva, then come back so I can export. -``` - -*[Designs created; owner fills in Canva; returns design IDs]* - -**Export output:** -``` -Exporting previews... -✓ Jun 2 feed post → https://canva.com/export/abc123.png -✓ Jun 4 Facebook → https://canva.com/export/def456.png -✓ Jun 6 story → https://canva.com/export/ghi789.png -[…] -``` - -*Owner: "These look great. Go ahead."* - ---- - -## Stage 3: Caption drafts - -**Jun 2 — Instagram feed (linen dresses launch)** -``` -Finally, a dress you can wear to the farmer's market *and* to dinner. 🌿 - -Our linen midi just landed and it's already our most-requested piece this -summer. Breathable, effortless, and yes — it has pockets. - -Grab yours before the sizes go → link in bio. - -#LinenDress #CharlestonStyle #SummerFashion #BloomAndThread -``` - -**Jun 4 — Facebook feed (social proof)** -``` -"I've worn it four times this week and I'm not even sorry." - -That's a real review from a real customer about our linen midi. Between -you and us, we're not surprised. Shop the collection at the link below. -``` - -**Jun 6 — Instagram story (offer)** -``` -👗 Buy 2 dresses → get 1 accessory FREE - -Offer runs June 1–July 31. Don't sleep on it. - -Swipe up to shop → -``` - -*Owner approved with one change: "Jun 4 caption — add the price at the end. '$88, link below.'"* -*Caption updated.* - ---- - -## Stage 4: HubSpot staging - -**Campaign created:** -``` -Campaign: "Bloom & Thread — Summer Linen 2026" -Start: Jun 2, 2026 | End: Jul 31, 2026 -Campaign ID: 8a72c1f4... -``` - -**Scheduled queue (first 3):** - -| Scheduled | Channel | Caption preview | Status | -|-----------|---------|-----------------|--------| -| Jun 2, 10:00 AM ET | Instagram | "Finally, a dress you can wear…" | SCHEDULED | -| Jun 4, 10:00 AM ET | Facebook | '"I've worn it four times…"' | SCHEDULED | -| Jun 6, 10:00 AM ET | Instagram Story | "Buy 2 dresses → get 1 accessory FREE…" | SCHEDULED | - -**Final message to owner:** -``` -Your campaign is staged in HubSpot: -https://app.hubspot.com/content/12345/social/campaigns/8a72c1f4 - -Posts will publish automatically on schedule. You can cancel or edit -any post in HubSpot before it goes out. Anything to change before we're done? -``` - ---- - -## Email content example (text-only — no Canva) - -Email rows skip Canva entirely. Claude writes the email subject, preheader, -and body as plain prose in Stage 3, and the owner copies the content into -their email tool when they're ready to send. - -**Calendar row:** - -| Date | Channel | Theme | Asset type | Angle | -|------|---------|-------|------------|-------| -| Jun 5 | Email | Summer linen launch | Email (text) | Hero customer benefit + offer | - -**Stage 3 output (inline, no Canva involved):** - -``` -Subject: Linen that actually breathes -Preheader: New summer styles in — plus a small gift if you grab two. - -The first batch of linen midis just hit the floor. They're the kind of -dress you can wear to brunch, to a wedding, or to the school pickup line -without feeling like you've made a wardrobe decision. - -A few things worth knowing: - • Sizes XS–XL, four colorways - • Pockets (real ones) - • Buy 2 dresses through July 31 and we'll throw in a free accessory - -Stop by 412 King Street this weekend, or shop online below. - -Shop the linen collection → - -— Maya -Bloom & Thread -``` - -**Stage 4 handoff:** - -``` -Your social posts are scheduled in HubSpot: [link] - -Email content for June 5 is drafted above — copy it into your email tool -when you're ready to send. We don't stage emails directly; that lets you -preview the formatting in your sending platform first. -``` diff --git a/small-business/skills/canva-creator/reference/gotchas.md b/small-business/skills/canva-creator/reference/gotchas.md deleted file mode 100644 index 6cc90ed6c..000000000 --- a/small-business/skills/canva-creator/reference/gotchas.md +++ /dev/null @@ -1,380 +0,0 @@ -# Gotchas - -Common failure modes for the canva-creator skill. - ---- - -## Gotcha: Generating ANY Canva design for an email row - -**Why it matters:** The owner descoped Canva from the email path entirely. -Canva email-template autofill produces placeholder graphics (stock -landscapes, blank rectangles) in service-grid tiles, and variation -thumbnails fail to render in chat. The decision was: emails are text-only -from this skill, period. Generating a Canva email design — even one — is -a regression of an explicit descope. - -### ✗ Bad - -``` -Calendar has 6 social rows + 2 email rows. -→ Stage 2 generates 6 social designs + 2 email designs. -→ Email designs ship with placeholder service tiles. -``` - -Or any variation: "I'll generate the email template just to give you a -visual reference," "I found an email template that might work, want to -preview it?", "Here's a Canva design for the Jun 5 email…" — all -forbidden. - -### ✓ Good - -``` -Stage 1: Calendar built with Path column. - - 6 rows tagged Canva (social) - - 2 rows tagged Text-only (no Canva) -Stage 2: Generates exactly 6 Canva designs. Email rows are not passed - to any Canva endpoint. -Stage 3: Drafts 6 social captions + 2 full emails (subject + preheader + - body) as plain text. -Stage 4: Stages 6 social posts in HubSpot. Surfaces 2 emails inline for - owner to copy into their email tool. -``` - -If the owner explicitly asks for a Canva email design ("can you make me -a Canva version of the Jun 5 email?"), redirect: "This skill keeps emails -as text-only because the Canva email path produces placeholder graphics. -If you want a Canva-designed email, build it directly in Canva and I can -help you write the copy here." - ---- - -## Gotcha: Generating without a budget plan - -**Why it matters:** Canva caps API usage at 100 requests/minute per token, -and each design costs ~5 calls (autofill + export + polling). A 10-row -campaign with 4 candidates per row generates 40 designs and ~200 API -calls — and the math gets worse with parallelism. Without a pre-flight -budget, the owner hits quota mid-campaign with no clear recovery path -and four already-generated posts sitting unused. - -### ✗ Bad - -``` -Calendar approved → immediately fire 4 candidates × 8 rows in parallel -→ ~160 API calls in 90 seconds → RATE_LIMIT_EXCEEDED on post 5 → loop -on retry → owner blocked. -``` - -### ✓ Good - -``` -Pre-flight: "8 Canva rows × 3 candidates = 24 designs, ~120 API calls. -Proceed at default 3 candidates per row?" - -Stage 3: row 1's 3 candidates fire in parallel → 30s pause → row 2 → -30s pause → row 3 → … finishes at ~12 designs/minute, well under the -quota. - -If quota does hit anyway: stop, surface progress, ask the owner -whether to drop to single candidates, pause an hour, or move to -captions with what's done. -``` - ---- - -## Gotcha: Skipping Checkpoint 1 (calendar approval) before generating assets - -**Why it matters:** Generating 10+ Canva designs takes API calls, time, and -user attention. If the calendar has the wrong dates, wrong channels, or the -owner changes their mind about a theme, all that work is discarded. The -calendar checkpoint is the cheapest place to catch misalignment. - -### ✗ Bad - -Receive the brief → immediately start calling `POST /autofills` for all 12 -posts → present designs before the owner has agreed on the schedule. - -Owner: "Oh wait, I didn't want any posts the week of the 15th, I'm traveling." - -### ✓ Good - -Present the calendar table first. Wait for explicit "looks good" before opening -a single Canva API call. - ---- - -## Gotcha: Template has more image slots than the brief provides photos for - -**Why it matters:** Multi-image social templates (Instagram carousels, -product grids) can have 3+ image slots. When the brief gives you 1 photo -and the template demands 3, the unfilled slots silently render Canva's -stock landscape graphic — generic clouds and green hills where product -photos should be. The design looks "complete" until the owner opens it. - -(Note: email rows skip Canva entirely in this skill — see SKILL.md Stage 3. -This gotcha applies only to social templates with multiple image slots.) - -### ✗ Bad - -Build manifest with one row per design ("Carousel — needs Hero_Image"). -Upload the one photo. Generate. Carousel ships with slide 1 populated -and slides 2-3 both showing identical generic landscapes. - -### ✓ Good - -Build manifest slot-by-slot. Surface the gap explicitly: - -``` -The "3-product carousel" template has 3 image slots. The brief gave me -1 photo. How should I fill the other 2? - -1. Reuse the same photo across all 3 slots -2. I'll send you 2 more photos -3. Pick a single-image template -``` - -Wait for the owner's choice before generating. Don't let placeholder -graphics ship. - ---- - -## Gotcha: Trusting `status: success` without exporting and visually verifying - -**Why it matters:** A successful autofill job means Canva accepted the -request and produced a design — not that the design contains the right -images. If an `asset_id` was empty, stale, or wrong-typed, the job still -returns `status: success` and the design renders with default placeholder -graphics. The only way to know is to look at the rendered output. - -### ✗ Bad - -``` -Job status: success ✓ -result.design.id: present ✓ -→ Present to owner -``` - -Result: owner opens the carousel and sees stock landscape graphics in 3 of -4 designs. - -### ✓ Good - -After the job succeeds, export each design to a permanent PNG via -`POST /exports` (or `export-design` MCP). Look at each PNG and confirm it -contains real assets — not Canva's default landscape, not gray rectangles, -not lorem-ipsum text. Only present to the owner after visual verification -passes. - ---- - -## Gotcha: One design in a batch fails to render - -**Why it matters:** When 1 of 4 designs in a batch fails (job error, expired -preview URL, placeholder rendered) and you present the partial carousel -anyway, the owner sees three real designs and one "Show Image" gray -rectangle. They lose trust in the rest of the carousel even though it's -fine. - -### ✗ Bad - -``` -Week 1 designs are ready: -[Option A — real preview] -[Option B — real preview] -[Option C — real preview] -[Option D — Show Image placeholder] -Which one should I use? -``` - -### ✓ Good - -When you detect the broken design at Step 6 verification, regenerate just -that one design with the correct asset_id. Re-export, re-verify. Only -present once all four designs in the batch have permanent, verified -previews. If the second attempt also fails, ask the owner whether to skip, -swap template, or try a different photo. - ---- - -## Gotcha: Generating assets without confirming all autofill fields have values - -**Why it matters:** Canva autofill silently renders empty placeholders when a -field value is missing or the referenced `asset_id` doesn't exist. The result -is a professional-looking template with blank white rectangles where the -product photo and headline should be. - -### ✗ Bad - -Build calendar → immediately fire all `POST /autofills` in parallel → half -the designs come back with empty image placeholders because product photos -weren't uploaded first. - -### ✓ Good - -Build calendar → inventory every autofill field slot-by-slot → upload missing -product images → confirm all field values with owner → then generate designs -in parallel, with every field pre-populated. - ---- - -## Gotcha: Passing invalid values to image autofill fields - -**Why it matters:** When an autofill image field receives an empty string, a -file path, a URL, or a stale/invalid `asset_id`, Canva does not error — it -silently renders the template's default placeholder graphic (e.g., a generic -landscape with clouds and hills). The design looks "finished" but the hero -image is stock art, not the owner's product photo. - -### ✗ Bad - -Upload product photo → don't wait for the upload job to complete → pass the -`job_id` (not the `asset.id`) into the autofill data → design renders with -a placeholder landscape instead of the product photo. - -### ✓ Good - -Upload product photo via `POST /v1/asset-uploads` → poll -`GET /v1/asset-uploads/{job_id}` until `status == "success"` → extract -`asset.id` from the response → pass that exact ID into the autofill image -field. Verify every image field has a confirmed `asset.id` before calling -`POST /autofills`. - ---- - -## Gotcha: Embedding Canva CDN thumbnail URLs in markdown - -**Why it matters:** Canva's autofill response returns short-lived, -authenticated CDN URLs from `design.canva.ai`. These expire within minutes. -If Claude embeds them as markdown images (`![](design.canva.ai/...)`), they -render as broken "Show Image" placeholders by the time the message is shown. - -### ✗ Bad - -Generate 8 designs → manually embed each CDN thumbnail URL in the response -as `![Hero 1](https://design.canva.ai/xxx)` → all images show as broken -gray placeholders because the URLs expired before render. - -### ✓ Good - -Either let the native Cowork carousel render the tool result automatically, -or export each design via `POST /exports` and embed the **permanent** export -URL. As a final fallback, link to the design's permanent edit URL -(`https://www.canva.com/d/{design_id}`). Never re-embed `design.canva.ai` -URLs. - ---- - -## Gotcha: Listing designs one-by-one as individual image blocks - -**Why it matters:** When Claude lists each design as a separate block -("Hero 1 / [image] / Hero 2 / [image]"), the images render as broken -gray "Show Image" placeholders. Presenting all designs together in a -single grouped batch triggers Cowork's side-by-side carousel, which -renders correctly. - -### ✗ Bad - -``` -Hero 1 — Multi-property portfolio -[Show Image] -View in Canva: https://canva.com/d/xxx - -Hero 2 — Coastal market case study -[Show Image] -View in Canva: https://canva.com/d/yyy -``` - -### ✓ Good - -Present all designs in one grouped response so they render as a -side-by-side carousel. Below the carousel, add a single prompt: - -``` -Here are 4 hero designs for Week 1. Scroll through the carousel -above and let me know which one to keep. -``` - ---- - -## Gotcha: Generating designs sequentially instead of in parallel - -**Why it matters:** Generating designs one at a time means the owner waits -through N round trips instead of one. Fire all generation requests within a -batch at once and present selection after all jobs complete. - -### ✗ Bad - -Generate design 1 → wait → show it → generate design 2 → wait → show it → -… × 8 designs. Owner watches a slow drip for 10 minutes. - -### ✓ Good - -Fire all designs in the current batch at once → poll all jobs concurrently → -once all complete, export each → verify visually → then present. - ---- - -## Gotcha: Auto-selecting a brand template for Pro/Teams users - -**Why it matters:** Pro/Teams users have no brand-template API access. If -Claude guesses a template by name and generates with the wrong one, the owner -gets designs in the wrong colors/fonts and has to redo the work in Canva -manually. - -### ✗ Bad - -``` -Found template "Square Post - Blue". Using this for all feed posts. -``` -…followed by 8 designs in blue when the brand is green. - -### ✓ Good - -``` -I found 3 templates in your Canva library that could work for feed posts: -1. Square Post - Blue (last edited March 2026) -2. Summer Promo - Green (last edited April 2026) -3. Product Feature Card (last edited Jan 2026) - -Which one should I use? -``` - ---- - -## Gotcha: Caption voice drift across a long calendar - -**Why it matters:** When drafting 12–20 captions in one pass, the tone tends -to drift — early captions follow the brief's voice markers, later ones slip -into generic marketing copy. Owners notice immediately. - -### ✗ Bad - -Post 1: "Our handmade candles are the perfect summer gift 🌿" (matches brief: "warm, conversational") -Post 10: "Elevate your ambiance with our artisanal fragrance collection." (corporate drift) - -### ✓ Good - -Before drafting, anchor on 2–3 voice markers from the brief (e.g., "casual, -friendly, uses light humor"). Re-read the first draft caption before writing -each new one. If the owner flags a voice mismatch on any caption, re-read that -caption and flag it as the recalibration point for the remaining drafts. - ---- - -## Gotcha: Staging HubSpot posts without verifying `scheduledAt` is in the future - -**Why it matters:** HubSpot rejects posts with `scheduledAt` in the past with -a validation error. If the calendar was built on an earlier date and the -owner is only now staging, some dates may have passed. - -### ✗ Bad - -Build calendar on April 1st for June posts → owner approves May 15th → try to -stage without checking → post for "April 30th 10:00 AM" returns 400. - -### ✓ Good - -Before calling `POST /social/posts`, compare each `scheduledAt` against the -current UTC time. If any post date has passed, surface it: "The post scheduled -for April 30th has already passed. Should I skip it, or reschedule it to next -week?" diff --git a/small-business/skills/canva-creator/reference/hubspot-staging.md b/small-business/skills/canva-creator/reference/hubspot-staging.md deleted file mode 100644 index 9eb5c4cfa..000000000 --- a/small-business/skills/canva-creator/reference/hubspot-staging.md +++ /dev/null @@ -1,137 +0,0 @@ -# HubSpot Campaign Staging Reference - -Requires: **HubSpot Marketing Hub Professional** (or higher). -Base URL: `https://api.hubapi.com` -Auth: Bearer token (OAuth 2.0 or private app token). - ---- - -## Table of contents - -1. [Tier check](#tier-check) -2. [Create a campaign](#create-a-campaign) -3. [Create a social post](#create-a-social-post) -4. [Verify the scheduled queue](#verify-the-scheduled-queue) -5. [CSV fallback (non-Professional users)](#csv-fallback-non-professional-users) -6. [Field reference](#field-reference) - ---- - -## Tier check - -If you're unsure whether the user has Marketing Hub Professional: - -``` -GET /crm/v3/objects/companies?limit=1 -``` - -Check the `subscriptionType` on the account. If the API returns a 403 on -social endpoints, tell the user: "HubSpot campaign staging requires Marketing -Hub Professional. Your current plan doesn't include it. I can export a -scheduling CSV instead — would that work?" - ---- - -## Create a campaign - -``` -POST /marketing/v3/campaigns -{ - "name": "Summer Sale 2026 — Social", - "startDate": "2026-06-01", - "endDate": "2026-06-30", - "currencyCode": "USD", - "utm": { - "source": "social", - "medium": "owned", - "campaign": "summer-sale-2026" - } -} -``` - -Response: `{ "id": "", ... }` — save this for social post association. - ---- - -## Create a social post - -One call per calendar row. Stage as `SCHEDULED`, never `PUBLISHED`. - -``` -POST /marketing/v3/social/posts -{ - "campaignId": "", - "channelId": "", - "content": { - "body": "" - }, - "scheduledAt": "2026-06-03T10:00:00Z", - "attachments": [ - { - "url": "" - } - ], - "status": "SCHEDULED" -} -``` - -**`channelId`** — the HubSpot Social account ID (not the platform name). -Retrieve connected accounts: -``` -GET /marketing/v3/social/channels -``` -Match by `type` (`INSTAGRAM`, `FACEBOOK`, `TWITTER`, `LINKEDIN`) and use the `id` field. - -**`scheduledAt`** — must be in the future (relative to the time of the API -call). Use noon local time for the owner's timezone unless they specify -otherwise. - ---- - -## Verify the scheduled queue - -After staging all posts: - -``` -GET /marketing/v3/social/posts?status=SCHEDULED&campaignId= -``` - -Surface results in a table: date, channel, first 60 chars of caption, status. -Provide the direct HubSpot campaign URL: -`https://app.hubspot.com/content/{portalId}/social/campaigns/{campaign_id}` - -Tell the user: "Posts are scheduled and will publish automatically. You can -cancel or edit any post in HubSpot before the send time." - ---- - -## CSV fallback (non-Professional users) - -When HubSpot staging is not available, export a CSV the user can import into -Buffer, Later, or their scheduler of choice. - -Column headers: -``` -Date,Time,Channel,Caption,ImageURL,Status -``` - -Example row: -``` -2026-06-03,10:00 AM CDT,Instagram,"Summer Sale: 30% off candles ☀️ ...",https://canva.com/export/...,Scheduled -``` - -Tell the user: "I've prepared a scheduling CSV since your HubSpot plan doesn't -include social staging. You can import this into Buffer or Later. [file path]" - ---- - -## Field reference - -| Field | Type | Notes | -|-------|------|-------| -| `campaignId` | string | UUID from campaign creation | -| `channelId` | string | From `GET /social/channels` | -| `content.body` | string | Caption text; max 2,000 chars | -| `scheduledAt` | ISO 8601 | Must be future time; include timezone offset | -| `attachments[].url` | string | Public URL (Canva export URL works) | -| `status` | enum | Always `"SCHEDULED"` — never `"PUBLISHED"` | diff --git a/small-business/skills/cash-flow-snapshot/SKILL.md b/small-business/skills/cash-flow-snapshot/SKILL.md deleted file mode 100644 index 3e98d44ed..000000000 --- a/small-business/skills/cash-flow-snapshot/SKILL.md +++ /dev/null @@ -1,169 +0,0 @@ ---- -name: cash-flow-snapshot -description: > - Reads AR/AP, historical cash timing, and known fixed costs from QuickBooks, - PayPal, Stripe, or Square — or a CSV upload — and produces a 30/60/90-day - cash flow forecast with percentage-variance confidence bands and named risk - flags. Delivers a chat summary and a downloadable XLSX. Use when the user - asks "forecast my cash flow," "will I make payroll," mentions "runway," or - says "cash crunch." Falls back to CSV upload when no connector is live. -compatibility: "Requires one or more of: QuickBooks MCP, PayPal MCP, Stripe MCP, Square MCP, file upload (CSV fallback). Output uses xlsx skill." ---- - -# Cash Flow Snapshot - -Produces a 30/60/90-day cash flow forecast with percentage-variance confidence -bands and named risk flags. Delivers a two-part output: a concise chat summary -and a downloadable XLSX workbook. - -**Quick start** - -> "Will I make payroll next month?" - -Claude pulls AR/AP and fixed costs from connected sources, calculates expected -inflows and outflows across 30, 60, and 90-day windows, applies confidence -bands based on each customer's historical payment variance, and flags specific -risks by name. - ---- - -## Workflow - -### Step 1 — Identify available data sources - -Check which connectors are live. Try in this order: - -1. QuickBooks — primary source for AR aging, AP, and fixed costs -2. PayPal — transaction history and settlement timing -3. Stripe — charge and payout history -4. Square — sales and payout history -5. CSV upload — fallback if no connector is connected - -If no connector is live and no file is attached, ask the user to either connect -a source or upload a CSV (income/expense tabular data, any reasonable format). -Note which sources were used in the output — this affects confidence band width. - -### Step 2 — Pull the data - -**From QuickBooks:** -- AR aging report: customer name, invoice amount, invoice date, due date, days outstanding -- AP: vendor name, amount due, due date -- Recurring fixed costs: rent, payroll, subscriptions (look for recurring transactions) - -**From PayPal / Stripe / Square:** -- Settlement history: transaction date, amount, settlement date -- Use settlement lag (transaction date → payout date) to compute each source's - average and variance payment delay - -**From CSV upload:** -- Parse as income/expense tabular data -- Required columns (flexible naming): date, amount, type (income or expense), description -- If columns are ambiguous, show the header row and ask the user to confirm mapping - -### Step 3 — Compute historical payment timing - -For each AR customer (or income source from CSV), calculate: -- **Mean payment lag** — average days from invoice/transaction date to receipt -- **Payment variance** — standard deviation of payment lag across last 6–12 payments -- Use variance to set confidence band width (see Step 4) - -If fewer than 3 payments exist for a customer, use the population mean as the -point estimate and apply a ±30% variance band as the default. When running on -CSV data with sufficient history (≥3 payments per source), compute the band -from the actual payment variance — do not assume ±30%. - -### Step 4 — Build the 30/60/90-day forecast - -Produce three time windows: 0–30 days, 31–60 days, 61–90 days. - -For each window, compute: - -| Line | Method | -|---|---| -| Expected inflows | AR due in window, adjusted for mean payment lag | -| Expected outflows | AP due in window + fixed costs falling in window | -| Net cash position | Inflows − Outflows | -| Confidence band | ± weighted average payment variance as a % of expected inflows | - -Confidence band formula: -``` -band_pct = weighted_avg_stddev_days / avg_payment_lag_days -low = net_cash × (1 − band_pct) -high = net_cash × (1 + band_pct) -``` - -Round band_pct to one decimal place. Cap at ±50% — higher variance means the -data is too thin to model; flag it instead (see Step 5). - -### Step 5 — Flag named risks - -Scan for conditions that push the low-band estimate negative or create a -liquidity crunch. For each risk found, produce a one-line flag: - -- **Late-payer risk:** "Customer X historically pays 18 days late; that shifts - their $8,400 invoice out of the 30-day window into day 48." -- **Payroll crunch:** "Payroll ($22,000) hits April 15. Low-band cash on hand - April 14: $19,200. Shortfall risk: $2,800." -- **Thin data warning:** "Only 2 payments on record for Customer Y — confidence - band set to default ±30%." -- **No-connector warning:** "Running on CSV data only — no real-time AP or - recurring cost data. Confidence bands are wider than normal." - -Limit to the top 5 risks by severity (largest dollar impact first). - -### Step 6 — Deliver outputs - -**Chat summary** (always): -``` -Cash Flow Snapshot — [date range] -Source(s): [connectors used] - - Expected Low High -30-day net: $X,XXX $X,XXX $X,XXX -60-day net: $X,XXX $X,XXX $X,XXX -90-day net: $X,XXX $X,XXX $X,XXX - -⚠ Risks flagged: [count] - • [risk 1] - • [risk 2] - ... -``` - -**XLSX workbook** (always): -Read `xlsx/SKILL.md` before generating. Produce a workbook with three sheets: - -1. **Summary** — the 30/60/90 forecast table with confidence bands. Beneath - each window row, expand inline sub-rows showing the individual transactions - that make up its inflows (green) and outflows (red). This makes the estimates - auditable without leaving the Summary sheet. - -2. **Detail** — all transactions grouped by window, sorted by date within each - group. Include a running net column (cumulative inflows minus outflows within - the window) and a subtotal row at the bottom of each window showing total - inflows, total outflows, and net. Grey out past transactions in a separate - section at the bottom for reference. Ensure all three windows have rows even - if one is empty — show a "No transactions in this window" placeholder row. - -3. **Risks** — the flagged risks with dollar impact and affected window. - -Save as `cash-flow-snapshot-[YYYY-MM-DD].xlsx`. - ---- - -## Approval gates - -No destructive actions — this skill is read-only. No approval gate required -before generating the forecast. - -Remind the user after delivery: -> "This forecast is based on [sources listed]. It is not a substitute for -> accounting advice — verify with your bookkeeper before making financing decisions." - ---- - -## Reference files - -| File | Load when | -|---|---| -| `reference/gotchas.md` | When a connector returns unexpected data or variance is extreme | -| `reference/examples/worked-example.md` | When modeling the output format for a new data shape | diff --git a/small-business/skills/cash-flow-snapshot/reference/examples/worked-example.md b/small-business/skills/cash-flow-snapshot/reference/examples/worked-example.md deleted file mode 100644 index c6a8a0b12..000000000 --- a/small-business/skills/cash-flow-snapshot/reference/examples/worked-example.md +++ /dev/null @@ -1,92 +0,0 @@ -# Worked example — cash-flow-snapshot - -**Scenario:** Small services business. QuickBooks + PayPal connected. Three -active customers, monthly payroll, office rent. - ---- - -## Input data (pulled from connectors) - -**AR aging (QuickBooks):** - -| Customer | Invoice | Amount | Due Date | Days Outstanding | -|----------------|---------|----------|------------|------------------| -| Acme Corp | INV-112 | $8,400 | Apr 10 | 12 | -| BlueSky LLC | INV-108 | $14,200 | Apr 22 | 0 | -| Crestwood Inc | INV-115 | $6,000 | May 5 | — | - -**Historical payment lag (from PayPal settlements):** - -| Customer | Mean Lag | Std Dev | Payments on Record | -|----------------|----------|---------|--------------------| -| Acme Corp | 18 days | 4 days | 11 | -| BlueSky LLC | 7 days | 2 days | 8 | -| Crestwood Inc | 12 days | 5 days | 6 | - -**Fixed costs (QuickBooks recurring AP):** -- Payroll: $22,000 — hits April 15 -- Rent: $3,200 — hits May 1 -- Software subscriptions: $480 — hits May 1 - ---- - -## Step 3 output — adjusted inflow dates - -| Customer | Invoice Amount | Adj. Receipt Date | Notes | -|----------------|---------------|-------------------|-----------------------------------| -| Acme Corp | $8,400 | Apr 28 | Due Apr 10 + 18-day mean lag | -| BlueSky LLC | $14,200 | Apr 29 | Due Apr 22 + 7-day mean lag | -| Crestwood Inc | $6,000 | May 17 | Due May 5 + 12-day mean lag | - ---- - -## Step 4 output — 30/60/90 forecast - -Confidence band calculation: -- Weighted avg stddev: 3.6 days -- Weighted avg mean lag: 12.7 days -- band_pct = 3.6 / 12.7 = **28.3%** - -| Window | Expected Inflows | Expected Outflows | Net | Low (−28%) | High (+28%) | -|---------|-----------------|-------------------|----------|------------|-------------| -| 0–30d | $22,600 | $22,000 | +$600 | −$5,928 | +$7,128 | -| 31–60d | $6,000 | $3,680 | +$2,320 | +$1,670 | +$2,970 | -| 61–90d | $0 | $0 | $0 | — | — | - ---- - -## Step 5 output — risks flagged - -1. **Payroll crunch:** Payroll ($22,000) hits April 15. Low-band inflows through - April 14: $0 (both AR receipts fall April 28–29). Shortfall risk: up to $22,000. - *Recommend: confirm receivables timing with Acme and BlueSky before April 14.* - -2. **Late-payer risk:** Acme Corp historically pays 18 days late. Their $8,400 - invoice (due Apr 10) shifts to April 28 — after payroll. - ---- - -## Step 6 output — chat summary - -``` -Cash Flow Snapshot — Apr 23 → Jul 21, 2026 -Sources: QuickBooks, PayPal - - Expected Low High -30-day net: +$600 −$5,928 +$7,128 -60-day net: +$2,320 +$1,670 +$2,970 -90-day net: $0 — — - -⚠ 2 risks flagged: - • Payroll crunch: $22K payroll hits Apr 15; AR receipts don't clear until - Apr 28–29. Low-band shortfall risk: up to $22,000. - • Late-payer: Acme Corp (mean 18-day lag) shifts $8,400 past payroll date. - -Confidence band: ±28% (based on historical payment variance across 3 customers). - -This forecast is based on QuickBooks AR/AP and PayPal settlement history. -It is not a substitute for accounting advice — verify with your bookkeeper -before making financing decisions. -``` - -**XLSX:** `cash-flow-snapshot-2026-04-23.xlsx` — Summary / Detail / Risks sheets. diff --git a/small-business/skills/cash-flow-snapshot/reference/gotchas.md b/small-business/skills/cash-flow-snapshot/reference/gotchas.md deleted file mode 100644 index a21f5376c..000000000 --- a/small-business/skills/cash-flow-snapshot/reference/gotchas.md +++ /dev/null @@ -1,62 +0,0 @@ -# Gotchas — cash-flow-snapshot - -Known edge cases and connector failure modes. 2–5 entries, Good/Bad format. - ---- - -## 1. QuickBooks AR aging includes invoices already collected - -**Bad:** Including fully-paid invoices from the AR aging report inflates inflow -projections. QuickBooks sometimes shows $0-balance invoices in aging exports. - -**Good:** Filter AR rows to `balance_due > 0` before computing inflows. If the -connector doesn't expose balance_due, subtract known PayPal/Stripe settlements -from the invoice total before including it. - ---- - -## 2. PayPal settlement lag varies by transaction type - -**Bad:** Assuming all PayPal receipts settle in 1–2 business days. PayPal holds -funds differently for disputes, new sellers, and high-value transactions — using -a flat settlement assumption produces overconfident inflow timing. - -**Good:** Compute settlement lag from actual `transaction_date` → `completed_date` -pairs in the PayPal transaction history. Use the computed mean and stddev per -customer or transaction type. - ---- - -## 3. CSV column names are inconsistent across accounting exports - -**Bad:** Requiring exact column names like "Date", "Amount", "Type". QuickBooks -CSV exports use "Transaction Date", "Amount", "Transaction Type". Wave uses -"Date", "Amount", "Account Type". Rigid parsing fails silently. - -**Good:** Fuzzy-match column headers (date → transaction date → txn date; -amount → debit/credit; type → category → account type). Show the header row -to the user and confirm mapping before computing — one question beats a silent -wrong forecast. - ---- - -## 4. Fixed costs hidden in one-off AP entries - -**Bad:** Only pulling recurring line items labeled as "recurring" in QuickBooks. -Many SMBs don't tag fixed costs consistently — rent may appear as a one-off -vendor bill each month. - -**Good:** Look for AP entries that appear in 3+ consecutive months with the same -vendor and similar amount (±10%). Treat these as recurring fixed costs in the -forecast. Surface the list to the user: "I'm treating these as fixed monthly -costs — does that look right?" - ---- - -## 5. Confidence band formula breaks when mean payment lag is zero - -**Bad:** Dividing stddev by a mean lag of 0 (e.g. immediate payment customers -like Square POS) produces a divide-by-zero error or an infinite band. - -**Good:** If mean lag ≤ 1 day, set band_pct to 5% (low variance, near-immediate -settlement). Don't attempt the division. diff --git a/small-business/skills/close-month/SKILL.md b/small-business/skills/close-month/SKILL.md deleted file mode 100644 index f189d6e7b..000000000 --- a/small-business/skills/close-month/SKILL.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -name: close-month -description: Closes the month — reconciles QB vs payment processors, flags gaps, writes P&L narrative, exports close packet. Accepts optional month and save-to arguments. -allowed-tools: Read, WebFetch, Bash ---- - -Run the month-end close workflow. Reconcile, flag gaps, narrate the P&L, and export the close packet for the owner's records (and their accountant). - -Parse arguments: -- `--month` (default: previous calendar month) — `YYYY-MM` format -- `--save-to` (default `files`) — `files` (Google Drive / OneDrive), `desktop` (local), or `both` - -## Step 1 — Reconcile - -Trigger the `month-end-prep` skill workflow: - -1. Pull all QuickBooks transactions for the target month. -2. Pull settlements from each connected payment processor (PayPal, Stripe, Square) for the same month. -3. Match QB entries to processor settlements by amount + date (±2 days). -4. Surface three gap categories: - - **Unmatched processor settlements** — money came in via PayPal/Stripe/Square but never landed in QB - - **Unmatched QB deposits** — QB shows income with no processor record (cash? wire? misclassified?) - - **Variance lines** — matched but amount differs (fees, refunds split) - -## Step 2 — Flag suspicious entries - -Surface in the same report: -- **Uncategorized transactions** — QB entries with no category -- **Suspicious duplicates** — same amount, same vendor, within 3 days -- **Missing receipts** — QB entries above $75 with no attachment - -For each, recommend an action: categorize as X, delete duplicate, attach receipt from inbox. - -Wait for owner to triage flagged items before generating the narrative. Do not auto-categorize or auto-delete. - -## Step 3 — P&L narrative - -After triage, generate a plain-English P&L narrative: - -``` -{Month YYYY} closed at ${revenue} revenue ({+/-}{X}% vs prior month). -Top driver: {category/customer}. Biggest swing: {category} {direction} ${amount} -because {reason inferred from transactions}. - -Margin: {X}% ({+/-}Y pts vs prior). {Cost-side commentary}. - -Three notable items: -1. ... -2. ... -3. ... -``` - -Numbers come from QB; the *why* comes from cross-referencing top transactions, vendor names, and prior-month deltas. - -## Step 4 — Export the close packet - -Generate two files: - -1. **`close-packet-{YYYY-MM}.xlsx`** — multi-tab workbook: - - `Reconciliation` — QB ↔ processor match table with gap rows highlighted - - `Flagged` — uncategorized / duplicates / missing receipts - - `P&L` — formatted income statement with prior-month delta column - - `Trial Balance` — accounts + ending balances -2. **`close-packet-{YYYY-MM}.pdf`** — one-page summary: P&L narrative + top-line numbers + gap count - -Save both to the chosen `--save-to` location. Filename format: `close-packet-2026-04.xlsx` etc. - -## Connector failures - -If QuickBooks is unreachable, stop — reconciliation requires QB as the source of truth. If a payment processor (PayPal, Stripe, Square) is unreachable, run reconciliation against the available processors and note "PayPal not connected — PayPal settlements skipped from reconciliation" (or whichever is missing). If all processors are missing, run QB-only analysis and flag it. - -## Approval gates - -- **Never auto-fix flagged items.** Always show the gap, recommend an action, wait for the owner. -- **Never delete duplicates without explicit confirmation.** Show both records side-by-side. -- **Saving the packet is auto** — it goes to the owner's own drive. - -## Output - -End the run with a one-paragraph recap: revenue, margin, gap count remaining (if any), file paths to the saved packet. If gaps were not all resolved, list them so the owner can revisit. diff --git a/small-business/skills/content-strategy/SKILL.md b/small-business/skills/content-strategy/SKILL.md deleted file mode 100644 index 53594afe1..000000000 --- a/small-business/skills/content-strategy/SKILL.md +++ /dev/null @@ -1,119 +0,0 @@ ---- -name: content-strategy -description: > - Analyzes sales data from PayPal and QuickBooks to find top performers and - slow movers, layers in seasonality, and produces a prioritized 30-day - content brief: what to push, what offers to run, what to hold. Strategic - output only — no calendars or assets. Use when the user asks what to post, - wants a content plan, asks what's selling, or what to promote this month. ---- - -# Content Strategy - -> **Status:** MVP draft -> **Owner:** JJ -> **Version:** 0.2.0 · Phase MVP -> **Category:** Marketing & Sales - -## Quick start - -When an SMB owner asks "what should I post this month?" or "what's my content plan?", this skill: - -1. **Pulls sales data** from QuickBooks or PayPal (transaction history, product/service revenue by date) -2. **Identifies patterns** — top-selling products, slow movers, seasonal trends -3. **Layers in context** — seasonality (user-provided or industry benchmarks), past performance -4. **Produces a 30-day brief** — ranked recommendations of what to push, what to hold, what offers to consider -5. **Gets owner approval** before the brief feeds into `canva-creator` for asset generation - -The output is strategic only — no calendar scheduling, no creative assets. - ---- - -## Workflow - -### Step 1: Pre-flight check (QuickBooks only) - -If using QuickBooks, verify the business profile is set up: - -1. Call `company-info` to check if `Industry` is populated -2. If missing or "Unknown": - - Ask: "I need your business category to pull the right seasonality benchmarks. What industry are you in?" (e.g., retail, services, SaaS) - - Call `quickbooks-profile-info-update` with the user's industry - - Confirm: "Profile updated. Ready to pull your sales data." -3. If profile is set, proceed to Step 2 - -**Note:** PayPal and Square do not require profile setup. - -### Step 2: Clarify priorities & metrics - -When triggered, ask the user: - -- **"How do you want me to measure 'top performers'?"** - - By total revenue? - - By profit margin? - - By sales velocity (how fast they're selling)? - - Combination of the above? - -- **"Do you have seasonality patterns in mind?"** - - If yes: "Tell me about them" (capture user's known seasonality) - - If no: "I'll use industry benchmarks for your category" - -### Step 3: Pull and analyze sales data - -Fetch data from the authenticated connector (QuickBooks, PayPal, or Square, user's choice): - -- **Date range:** Last 90 days (or full history if <90 days available) -- **Extract:** Product/service name, date sold, revenue, quantity - -**Connector-specific notes:** - -- **QuickBooks:** Fetch invoice line items via `profit-loss-quickbooks-account` (pre-flight sets industry context) -- **PayPal:** Fetch merchant transactions via `list_transactions`. *Rate-limiting:* If you hit rate limits, pause 30 seconds and retry once. If still blocked, gracefully offer: "PayPal is rate-limited. Would you like to switch to QuickBooks or Square instead, or I can continue with historical data I already pulled?" -- **Square:** Requires location ID first. Call `make_api_request(service="locations", method="list")` to discover available locations, then fetch orders for each location. *Future enhancement:* Square integration is stubbed; full path documented in `reference/square-integration.md`. - -**Fallback:** If <3 months of data, use industry seasonality benchmarks for the SMB's category (e.g., retail, services, e-commerce) - -Identify: -- **Top 3–5 performers** (by user's chosen metric) -- **Bottom 3–5 slow movers** (consider holding or repositioning) -- **Trending up** (gaining momentum in last 30 days) -- **Trending down** (losing momentum) - -### Step 4: Layer in seasonality - -- **User-provided:** If they shared seasonal patterns, weight recommendations against them -- **Industry benchmarks:** For categories without strong user data (e.g., "Q1 is strong for tax services") -- **Timing:** Flag products that should ramp up/down in the next 30 days based on seasonal patterns - -### Step 5: Build the 30-day brief - -Structure: -- **Executive summary** (1–2 sentences: "Your best sellers are X and Y. Seasonal shift to Z is starting.") -- **Push hard** (Top 2–3 products + recommended content angle, e.g., "Case study on ROI", "How-to video") -- **Hold steady** (Middle performers; maintain visibility but no heavy lift) -- **Reposition or pause** (Slow movers; consider discounting, bundling, or pausing) -- **Seasonal opportunities** (What's coming next month that you should position for now) -- **Recommended offers** (Bundle, discount, or free-trial strategy based on data) - -Example length: **200–400 words** (brief and actionable, not essay-length). - -### Step 6: Owner approval & iteration - -Present the brief to the owner. Ask: -- "Does this match your gut?" -- "Anything to adjust?" -- "Ready to feed this to canva-creator for asset generation?" - -Iterate if needed; once approved, return the final brief as structured JSON (ready for downstream tools). - ---- - -## Gotchas & edge cases - -See [`reference/gotchas.md`](reference/gotchas.md) for common pitfalls. - ---- - -## Examples - -See [`reference/examples/`](reference/examples/) for worked examples (SaaS, retail, services). diff --git a/small-business/skills/content-strategy/reference/examples/retail-boutique-example.md b/small-business/skills/content-strategy/reference/examples/retail-boutique-example.md deleted file mode 100644 index 5eea3f650..000000000 --- a/small-business/skills/content-strategy/reference/examples/retail-boutique-example.md +++ /dev/null @@ -1,71 +0,0 @@ -# Example: Retail boutique — 18 months of data - -**Business:** Vintage clothing boutique -**Trigger:** "What should I push this month?" -**Data source:** QuickBooks (18 months) -**User's metric:** Revenue -**User's seasonality:** "We peak April–May and November–December. Dead in July–August." - ---- - -## Input data summary - -- Total revenue (18 months): $67,500 -- Top product category: Vintage leather jackets ($18,200 / 27% of revenue) -- Second: 90s band tees ($12,400 / 18%) -- Third: High-waisted denim ($9,800 / 14%) -- Slowest: Vintage hats ($2,100 / 3%) - -**Trending up:** Band tees (growing 12% month-over-month for 3 months) -**Trending down:** Vintage accessories (declining 8% month-over-month) - ---- - -## The brief (ready for owner approval) - -### Executive Summary - -Your bestseller is vintage leather jackets — they consistently drive 27% of revenue. Band tees are surging and should be featured. April peak season is starting; push jackets and tees hard. July slowdown is coming; plan summer clearance strategy for slower items. - -### Push hard (next 30 days) - -1. **Vintage leather jackets** - - What to say: "Built to last. Investment pieces with character." (customer testimonials about durability) - - Recommended angle: Behind-the-scenes sourcing story, care/styling tips - - Timeline: Start mid-April for May peak - -2. **90s band tees** - - What to say: "Nostalgia + authenticity. No reproductions, all vintage." (emphasize rarity) - - Recommended angle: "Which era are you? 1990s vs 2000s collector's guide" - - Timeline: Capitalize on momentum now; feature weekly - -### Hold steady - -- **High-waisted denim** — solid performer, 14% of revenue. Maintain weekly rotation in feed; don't over-index. - -### Reposition / pause - -- **Vintage hats** — only 3% of revenue. Options: - - Bundle with leather jackets ("Complete the look") - - Offer 20% off to test demand - - Or pause until holiday season (Christmas styling posts) - -- **Vintage accessories** — declining. Similar options: bundle or pause until Q4. - -### Seasonal opportunity - -- **July–August slowdown:** Plan clearance content for May/June. "Summer refresh" angle for lighter pieces. (Consider a flash sale in early July to drive traffic during slow season.) -- **November–December:** Position leather jackets as holiday gifts (luxury, timeless); feature gift guides in October. - -### Recommended offers - -1. **Bundle:** Jacket + tee + belt = styled outfit at 5–10% bundle discount -2. **Flash sale:** Mid-July, 15% off slower items to build July traffic -3. **Free perks:** First buyer gets free styling guide or cleaning cloth - ---- - -## Next steps - -- **Owner approval:** "Does this feel right? Anything to adjust?" -- **Feed to canva-creator:** Once approved, pass this brief to `canva-creator` to generate social posts, emails, and graphics for the next 30 days. diff --git a/small-business/skills/content-strategy/reference/gotchas.md b/small-business/skills/content-strategy/reference/gotchas.md deleted file mode 100644 index 82ba44e95..000000000 --- a/small-business/skills/content-strategy/reference/gotchas.md +++ /dev/null @@ -1,104 +0,0 @@ -# Gotchas - -## Gotcha: Confusing correlation with causation - -Sales data shows a product peaked in March. That doesn't mean March marketing caused it — it might be seasonal demand. - -**Why it matters:** If you push hard on a slow-moving product just because it sold well once, you waste creative energy on something that doesn't actually resonate. - -### ✗ Bad -"Widgets sold 10 units in March. Push widgets hard in May because March worked." - -### ✓ Good -"Widgets sell well in March. Check if that's seasonal demand (tax-season gifting?) or a one-off spike. If seasonal, position for March next year. If one-off, don't over-index on it." - ---- - -## Gotcha: Ignoring low-velocity, high-margin products - -Revenue is tempting. A low-volume, high-margin service (like consulting) might generate less total revenue than a cheap commodity product, but it's far more profitable. - -**Why it matters:** If you obsess over volume winners and ignore margin leaders, you prioritize busy-work over profit. - -### ✗ Bad -"Service packages sold $500 total, but widget bundles sold $2000. Push widgets." - -### ✓ Good -"Ask: Which brings in the most profit per unit? Service packages might be 70% margin × $500 = $350 profit. Widget bundles might be 20% margin × $2000 = $400 profit. Different story now." - ---- - -## Gotcha: Seasonal benchmarks that don't fit your niche - -"Retail peaks in November" is true for many, but not all. A tax prep service peaks in March; a swimming pool company peaks in May. - -**Why it matters:** Generic benchmarks steer you wrong. Always ask the user: "Does this seasonality match your reality?" - -### ✗ Bad -"Industry benchmarks say Q4 is peak retail. You're a pool company. Push hard in Q4 anyway." - -### ✓ Good -"Pool companies peak May–August. Q4 benchmarks don't apply. Confirm with user: 'Do your sales match May–August peak?'" - ---- - -## Gotcha: Missing the composite picture - -"What's selling" can mean by revenue, margin, velocity, customer lifetime value, or retention. Different metrics tell different stories. - -**Why it matters:** Pick the wrong metric and you prioritize products that look good once but don't deliver repeat customers. - -### ✗ Bad -Assume "top seller" = highest revenue. Rank by revenue only. - -### ✓ Good -"How do you measure success? Revenue? Profit? Customer lifetime value? Repeat purchases?" Then rank by their chosen metric — or combine multiple metrics for balance. - ---- - -## Gotcha: Not accounting for inventory constraints - -A product might be flying off the shelves, but if inventory is low, pushing hard could create stockouts and frustration. - -**Why it matters:** You want to drive sales, not broken customer experiences. - -### ✗ Bad -"Widget sales are strong. Push widgets harder." - -### ✓ Good -"Widget sales are strong, but inventory is down to 5 units. Flag: 'Before pushing, confirm inventory. Consider promoting a similar alternative or pausing until restock.'" - ---- - -## Gotcha: QuickBooks profile not set up before first use - -New QuickBooks users often skip the business profile setup (industry, business name). When you try to pull P&L data, the connector returns `profile_info_required` error. - -**Why it matters:** A dead-end error frustrates the user. Pre-flight validation prevents wasted time. - -### ✗ Bad -User: "What should I post?" -Skill: [calls profit-loss-quickbooks-account] → Error: "Profile required" -User: [confused, doesn't know what to do next] - -### ✓ Good -User: "What should I post?" -Skill: [calls company-info] → Industry = "Unknown" -Skill: "I need your industry to pull the right benchmarks. What industry are you in?" -User: [provides industry] -Skill: [calls quickbooks-profile-info-update] → Profile updated -Skill: [now calls profit-loss-quickbooks-account successfully] - ---- - -## Gotcha: PayPal rate-limiting on repeated calls - -If you call `list_transactions` multiple times in rapid succession (e.g., looping through date ranges), PayPal may rate-limit and return 429 errors. - -**Why it matters:** Without retry logic, the skill fails mid-analysis when it should gracefully degrade. - -### ✗ Bad -Call list_transactions → 429 error → Skill crashes - -### ✓ Good -Call list_transactions → 429 error → Wait 30 seconds → Retry → If still blocked, offer fallback: "PayPal is temporarily rate-limited. Would you like to switch to QuickBooks/Square, or continue with partial data?" diff --git a/small-business/skills/content-strategy/reference/square-integration.md b/small-business/skills/content-strategy/reference/square-integration.md deleted file mode 100644 index 2df75109e..000000000 --- a/small-business/skills/content-strategy/reference/square-integration.md +++ /dev/null @@ -1,57 +0,0 @@ -# Square integration (future enhancement) - -Square is listed as an optional connector for content-strategy, but the full integration path is not yet implemented. This document outlines what's needed. - -## Current state - -- Square is named in `reference/connectors` but not fully wired into the workflow -- QuickBooks and PayPal are the primary, tested paths - -## What needs to happen - -### 1. Location ID discovery - -Square organizations can have multiple locations. Before pulling orders, we need to: - -1. Call `make_api_request` with `service="locations"` and `method="list"` to discover available locations -2. Ask user: "Which location(s) should I analyze?" (or default to primary) -3. Fetch location ID(s) for subsequent calls - -### 2. Order fetching - -For each location ID: - -``` -Call list_orders with: -- location_id: -- begin_time: <90 days ago, ISO 8601> -- end_time: -- sort_order: "DESC" -``` - -Extract: -- Order date -- Line items (product name, quantity, price) -- Total revenue per order - -### 3. Categorization - -Square orders may not have explicit "product" or "service" taxonomy — items live in catalog. Correlate line items to catalog entries to extract product names and categories. - -## Why it's stubbed - -1. **No test account** — would need a Square merchant account to validate end-to-end -2. **Catalog complexity** — Square's catalog model is more flexible than QuickBooks and adds surface area for errors -3. **Location multiplicity** — QuickBooks and PayPal have simpler single-account models; Square requires user to pick a location - -## How to implement - -1. Obtain a Square sandbox/test account -2. Write scenarios for single-location and multi-location merchants -3. Add `reference/square-orders-example.md` with worked example -4. Update SKILL.md workflow to include Square as co-equal path (not just "also supported") -5. Run through scenarios with a Square user before shipping - -## Time estimate - -~4 hours for discovery + implementation + testing, assuming a test account is available. diff --git a/small-business/skills/contract-review/SKILL.md b/small-business/skills/contract-review/SKILL.md deleted file mode 100644 index 75b28d768..000000000 --- a/small-business/skills/contract-review/SKILL.md +++ /dev/null @@ -1,123 +0,0 @@ ---- -name: contract-review -description: > - Lightweight NDA, MSA, and vendor contract review for SMBs without legal on - staff. Reads contracts from local files, Gmail attachments, or DocuSign - envelopes; flags non-standard terms; explains risks in plain English; and - outputs a marked-up redline as a separate DOCX. Use when the user says - "review this contract," "what am I signing," "red flags," "flag any concerns," - "check the payment terms," or uploads/forwards a contract or legal agreement. ---- - -# Contract Review - -## Quick start - -Attach a contract file, forward the email containing it, or paste the text directly. - -``` -User: "Review this MSA and flag anything I should push back on." -→ Skill reads the document, identifies parties and contract type, - analyzes 8 risk categories, returns a severity-tiered summary - with a negotiation playbook, and exports a redlined DOCX. -``` - -## Workflow - -1. **Get the contract** — Pull from one of three sources, in order of preference: - - **Gmail**: Search for recent emails with contract attachments (see `reference/gmail-fetch.md`) - - **DocuSign**: Fetch the envelope by ID or search recent drafts awaiting signature (see `reference/docusign-fetch.md`) - - **Local file or paste**: Read the PDF (chunked via `pages` parameter for 10+ page files) or DOCX via Read tool. If the user pastes text directly, work with what's provided. - - Read the full document before analyzing. Dangerous clauses are frequently in exhibits and schedules at the back. - -2. **Identify contract type and parties** — Determine agreement type (NDA, MSA, SOW, SaaS subscription, consulting, subcontractor, vendor) and which party is the user's company vs. the counterparty. Note if it looks like a counterparty template — these are typically one-sided and the counterparty expects pushback. - -3. **Analyze across 8 risk categories** — Work through the contract from the ops/finance perspective of a small business owner without in-house legal. Categories are ordered by typical risk severity; use judgment for context. - - **Category 1: Payment terms and cash flow** - - Payment timing: Net-30 is standard; Net-60+ is flaggable; Net-90/120 is a hard negotiation point - - Payment triggers: acceptance periods that let the client slow-walk approvals indefinitely - - Late payment penalties: absence is a gap worth noting - - Invoicing requirements: rigid formats or PO numbers that can delay payment on technicalities - - Expense reimbursement: pre-approval requirements and caps - - Rate adjustments: annual increase mechanism for multi-year engagements - - **Category 2: Liability and indemnification** - - Liability caps: uncapped liability is always a red flag - - Mutual vs. one-sided indemnification - - Indemnification scope: "any and all claims arising from the services" is not standard - - Insurance requirements: E&O, cyber, general liability — achievability at the required limits - - Consequential damages waiver: missing = flag prominently - - **Category 3: Termination and exit** - - Termination for convenience: is it mutual? 30-day notice is typical - - Termination for cause: cure period; vague "material breach" without definition - - Wind-down: payment for in-progress work at termination - - Transition assistance: paid vs. unpaid, time-limited vs. open-ended - - Survival clauses: indefinite indemnification survival = flag - - **Category 4: Intellectual property** - - IP assignment vs. license - - Pre-existing IP and background tools carve-out — absence means inadvertent assignment - - Work product definition breadth: drafts, notes, internal tools - - **Category 5: Scope and change management** - - Scope definition clarity - - Change order process: absence = scope creep without compensation - - Acceptance criteria: subjective ("to client's satisfaction") vs. defined - - Timeline asymmetry: user penalized for delays but client is not for slow feedback - - **Category 6: Non-compete and exclusivity** - - Non-compete scope, definition of "competitor," duration - - Exclusivity requirements on the user's company - - Non-solicitation: employee poaching is normal; industry-broad restrictions are not - - **Category 7: Confidentiality and data** - - Confidentiality scope: "all information shared" with no exceptions is overly broad - - Duration: 2–3 years is typical; perpetual is aggressive - - Data handling security requirements vs. company size and data sensitivity - - Return/destruction requirements post-termination - - **Category 8: Operational concerns** - - Governing law and dispute resolution; mandatory arbitration - - Auto-renewal: opt-out window and notice period (missing a 60-day window is a common SMB mistake) - - Assignment rights, especially if the client gets acquired - - Most favored nation: constrains pricing across the entire client book - - Audit rights: scope and frequency - -4. **Present flagged summary** — Organize by severity: - - **🔴 Red flags (push back before signing)** — For each: quote the exact clause, explain the problem in plain language, suggest specific alternative language. - - **🟡 Yellow flags (negotiate, not deal-breakers)** — For each: quote the clause, explain the concern, describe what "better" looks like. - - **🟢 Key terms to note (awareness only)** — Payment schedules, notice periods, renewal dates, insurance requirements, key contacts. - - **📋 Contract summary** — Plain-language summary: who does what, for how much, over what timeframe, under what conditions. - - **💡 Negotiation playbook** — For each red and yellow flag: what to ask for, how to frame the ask, and what a reasonable compromise looks like. - -5. **Export redline DOCX** — After presenting the summary, offer to export a redlined DOCX with the suggested changes marked up. Use the `docx` skill to generate a Word document that: - - Preserves the original contract structure - - Marks suggested deletions in strikethrough and additions in underline - - Adds a cover page summarizing the changes - - Ask: "Want me to export a redlined DOCX you can send back to the counterparty?" - -## Approval gates - -- Never characterize the output as legal advice. Always recommend attorney review for red flags or binding decisions. -- Quote actual clause language, not paraphrases. The user needs the exact text for negotiation calls. -- Flag what's missing, not just what's there. A contract silent on liability caps or change orders is often more dangerous than one with unfavorable terms. -- Do not flag standard boilerplate. If a clause is fair and market-standard, skip it. The user wants signal, not a clause-by-clause restatement. -- Compare to market norms when flagging: "Net-90 is uncommon in professional services — Net-30 is standard." -- Adjust recommendations to the power dynamic. A Fortune 500 procurement MSA is a different negotiation than a small startup agreement. -- Never send the redlined DOCX to the counterparty without explicit user confirmation. - -## Reference - -- `reference/gotchas.md` — edge cases in contract analysis -- `reference/docusign-fetch.md` — pulling envelopes from DocuSign -- `reference/gmail-fetch.md` — finding contract attachments in Gmail -- `reference/examples/flagged-summary-saas.md` — worked example: SaaS agreement review output diff --git a/small-business/skills/contract-review/reference/docusign-fetch.md b/small-business/skills/contract-review/reference/docusign-fetch.md deleted file mode 100644 index 7d940f082..000000000 --- a/small-business/skills/contract-review/reference/docusign-fetch.md +++ /dev/null @@ -1,32 +0,0 @@ -# DocuSign: fetching contracts for review - -Use the DocuSign MCP connector to pull envelopes awaiting signature. - -## Fetch pending envelopes - -Use `getEnvelopes` to list envelopes in `sent` or `delivered` status (awaiting recipient action): - -``` -Tool: getEnvelopes -Params: { status: "sent" } // or "delivered" -``` - -Returns a list of envelopes with: `envelopeId`, `emailSubject`, `createdDateTime`, `status`, `recipients`. - -## Download document from envelope - -Use `getEnvelope` with the `envelopeId` to get the full envelope details, then download the document for reading. - -## What NOT to do - -- Never call `triggerWorkflow` or any action that moves the envelope forward in the signing process. -- Never call `updateEnvelope` to modify the document. -- Never call `createEnvelope` — this skill is review-only. - -## Fallback - -If DocuSign is not connected or the envelope is not found: - -``` -"DocuSign isn't connected — paste the contract text or attach the file directly." -``` diff --git a/small-business/skills/contract-review/reference/examples/flagged-summary-saas.md b/small-business/skills/contract-review/reference/examples/flagged-summary-saas.md deleted file mode 100644 index f6db400cc..000000000 --- a/small-business/skills/contract-review/reference/examples/flagged-summary-saas.md +++ /dev/null @@ -1,97 +0,0 @@ -# Example: SaaS vendor agreement flagged summary - -A worked example of contract-review output. Contract: a SaaS subscription agreement from a mid-size software vendor. - ---- - -## Input - -> "Review this SaaS agreement before I sign. We're a 12-person consulting firm." - -Contract: 18-page SaaS Subscription Agreement, vendor template, governing law: California. - ---- - -## Output - -### 📋 Contract summary - -12-month SaaS subscription, auto-renewing annually. Vendor provides project management software. You pay $2,400/year billed monthly. Vendor hosts data; you own your data but grant vendor a broad license to use it for "product improvement." You can terminate with 30 days notice but owe fees through end of the contract term. - ---- - -### 🔴 Red flags (push back before signing) - -**1. Uncapped liability** - -> *"IN NO EVENT SHALL VENDOR'S LIABILITY EXCEED THE AMOUNTS ACTUALLY PAID BY CUSTOMER IN THE THREE (3) MONTHS PRECEDING THE CLAIM."* - -**Problem:** Three months of fees = $600. If a vendor data breach exposes your client data, your recovery is capped at $600 — regardless of actual damages. For a consulting firm handling client information, this is inadequate. - -**Ask for:** Cap at 12 months of fees paid ($2,400), or at a fixed floor of $50,000 for data security incidents. Suggested language: - -> *"Vendor's total liability shall not exceed the greater of (a) fees paid in the twelve (12) months preceding the claim or (b) $50,000 for claims arising from data security incidents."* - ---- - -**2. Auto-renewal with 60-day opt-out window** - -> *"This Agreement shall automatically renew for successive one-year terms unless either party provides written notice of non-renewal no less than sixty (60) days prior to the end of the then-current term."* - -**Problem:** You have a 60-day window to opt out. Miss it and you're committed to another year. With a $2,400/year contract, that's easy to overlook. - -**Ask for:** Reduce to 30-day opt-out, or add a reminder obligation from vendor. Alternatively, calendar the opt-out deadline now (2027-04-01 if signing May 1, 2026). - ---- - -### 🟡 Yellow flags (negotiate if possible) - -**3. Broad data license** - -> *"Customer grants Vendor a non-exclusive, worldwide license to use, process, and analyze Customer Data to improve Vendor's products and services."* - -**Concern:** Vendor can use your data — including client project data — to train their product. This may conflict with your client confidentiality obligations. - -**Ask for:** Restrict to aggregated, anonymized usage only. Suggested language: - -> *"...limited to aggregated, de-identified data and expressly excluding any Customer Data that identifies Customer's clients or projects."* - ---- - -**4. No termination for cause cure period** - -> *"Vendor may terminate this Agreement immediately upon Customer's material breach."* - -**Concern:** Vendor can cut off access immediately for any "material breach" with no chance to fix it. No definition of "material." You could lose access to your data mid-project. - -**Ask for:** 15-day cure period. Suggested: *"...upon written notice and Customer's failure to cure such breach within fifteen (15) days."* - ---- - -### 🟢 Key terms to note - -- **Payment:** Monthly, auto-charged. Keep credit card current or service suspends immediately. -- **Data portability:** You can export your data at any time and for 30 days post-termination. Plan export before cancellation. -- **Governing law:** California. Any disputes go to Santa Clara County courts. -- **Uptime SLA:** 99.5% monthly. Credits issued as account credits, not cash. - ---- - -### 💡 Negotiation playbook - -| Flag | Ask | Framing | -|------|-----|---------| -| Liability cap | Raise to 12 months ($2,400) or $50K for security incidents | "We handle client data — we need the liability cap to reflect actual risk" | -| Auto-renewal window | Reduce to 30 days | "60 days is tight for a small team — 30 is more typical" | -| Data license | Restrict to anonymized/aggregated | "Our client agreements restrict how we share their project data" | -| Termination cure | Add 15-day cure period | "We need a chance to fix issues before access is cut off" | - ---- - -*This is not legal advice. For binding decisions, consult an attorney.* - ---- - -## Redline DOCX - -A redlined DOCX with these suggested changes marked in tracked-changes format was exported to: `contract-review-redline-2026-05-01.docx` diff --git a/small-business/skills/contract-review/reference/gmail-fetch.md b/small-business/skills/contract-review/reference/gmail-fetch.md deleted file mode 100644 index e6d26a589..000000000 --- a/small-business/skills/contract-review/reference/gmail-fetch.md +++ /dev/null @@ -1,30 +0,0 @@ -# Gmail: finding contract attachments - -Use the Gmail MCP connector to find contract attachments in recent email. - -## Search for contract emails - -Use `search_threads` with a query targeting recent emails with attachments: - -``` -Query: "has:attachment (contract OR agreement OR NDA OR MSA OR SOW) newer_than:14d" -``` - -## What to do with results - -1. Present a short list (subject, sender, date) if multiple candidates match. -2. Ask the user to confirm which one before downloading. -3. Use `get_thread` to fetch the full thread, then locate and read the attachment. - -## Fallback - -If Gmail is not connected or no matching attachment is found: - -``` -"I didn't find a recent contract attachment in Gmail — can you forward it or attach the file directly?" -``` - -## What NOT to do - -- Do not read emails unrelated to the contract (no general inbox trawl). -- Do not send any reply or draft email during the review workflow. diff --git a/small-business/skills/contract-review/reference/gotchas.md b/small-business/skills/contract-review/reference/gotchas.md deleted file mode 100644 index 6d3668909..000000000 --- a/small-business/skills/contract-review/reference/gotchas.md +++ /dev/null @@ -1,105 +0,0 @@ -# Gotchas - -Edge cases in contract analysis. Good / Bad pairs. - ---- - -## Gotcha: Flagging standard boilerplate as a red flag - -**Why it matters:** Over-flagging trains the user to ignore the summary. If everything is a red flag, nothing is. - -### ✗ Bad - -``` -Contract has a standard mutual NDA confidentiality clause, 2-year duration. -Claude: "🔴 Red flag: Confidentiality clause imposes obligations on both parties." -``` - -Standard mutual NDA is market-norm. Flagging it as a red flag destroys signal-to-noise ratio. - -### ✓ Good - -``` -Contract has a standard mutual NDA confidentiality clause, 2-year duration. -Claude: [skips; does not flag] -``` - -Reserve red flags for genuinely non-standard terms. If a clause is boilerplate and fair, omit it. - ---- - -## Gotcha: Missing clauses aren't missing from the analysis - -**Why it matters:** For SMBs, the absence of standard protections (liability cap, change order process, consequential damages waiver) is often more dangerous than an unfavorable clause — the default legal position fills the gap, usually in the counterparty's favor. - -### ✗ Bad - -``` -Contract has no liability cap. -Claude: [no mention; only analyzes clauses that are present] -``` - -User signs thinking liability is limited. It isn't. - -### ✓ Good - -``` -Contract has no liability cap. -Claude: "🔴 Missing: No liability cap. This contract contains no limitation-of-liability -clause. Under default law, your exposure is uncapped. Standard practice is to cap at -fees paid in the prior 12 months. Suggest adding: 'Each party's total liability shall -not exceed the fees paid or payable in the 12 months preceding the claim.'" -``` - -Treat absent-but-standard clauses as red flags. Explicitly label them "Missing." - ---- - -## Gotcha: Large PDFs truncated mid-analysis - -**Why it matters:** Contracts over 20–30 pages often have the most dangerous terms in exhibits, schedules, or "Order Forms" at the back. If the PDF is read only up to page 15, key terms are silently missed. - -### ✗ Bad - -``` -Skill reads pages 1–10 of a 40-page MSA. Schedules A–D (starting page 28) contain -the IP assignment and liability cap. Skill produces a "clean" summary. -``` - -### ✓ Good - -``` -Read the PDF in chunks: pages 1–10, 11–20, 21–40. Analyze all chunks before -producing the summary. If a section heading mentions "Schedule," "Exhibit," or -"Appendix," flag it explicitly and ensure it was read. -``` - -Always read the full document. Use the `pages` parameter to chunk large PDFs. - ---- - -## Gotcha: Counterparty template vs. negotiated draft - -**Why it matters:** Recommendations should match the negotiating context. Pushing back hard on a startup's first-draft agreement is different from pushing back on a Fortune 500 procurement template — the latter is often non-negotiable on 80% of its terms. - -### ✗ Bad - -``` -Fortune 500 vendor agreement with standard procurement terms. -Claude: "🔴 This Net-60 payment term should be renegotiated to Net-30. - Their legal team will likely accept the change." -``` - -Unrealistic recommendation wastes the user's political capital. - -### ✓ Good - -``` -Claude: "🟡 Net-60 payment terms. This is longer than typical (Net-30 is standard), - but common in large enterprise procurement templates. Worth asking for - Net-45 as a compromise — they may accept it, especially for recurring work. - Note: if this is a Fortune 500 template, payment terms are often non-negotiable - in the first engagement." -``` - -Match the recommendation to the power dynamic. Label it yellow, not red. Acknowledge the reality. diff --git a/small-business/skills/crm-cleanup/SKILL.md b/small-business/skills/crm-cleanup/SKILL.md deleted file mode 100644 index 7575a01b6..000000000 --- a/small-business/skills/crm-cleanup/SKILL.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -name: crm-cleanup -description: Scans HubSpot for stale deals, duplicate contacts, and missing fields, then fixes what the owner approves. Accepts optional scope argument for deals, contacts, or all. -allowed-tools: Read, WebFetch, Bash ---- - -Run a HubSpot hygiene pass using the `crm-maintenance` skill cleanup workflow. Act immediately — the user typed /crm-cleanup, so skip the intent-detection step. - -Parse arguments: -- `--scope` (default: `all`) — `deals` for deal audit only, `contacts` for contact dedup only, `all` for both - -## Step 1 — Scan for stale deals - -If scope includes deals: - -1. Pull all open deals from HubSpot. -2. Flag deals with no activity (email, call, meeting, note) in the last 14 days. -3. For each stale deal: show deal name, stage, last activity date, associated contacts, and amount. -4. Propose actions per deal: update next-step, change stage, add a note, or close-lost. - -Present the full stale-deals list before making any changes. - -## Step 2 — Scan for duplicate contacts - -If scope includes contacts: - -1. Search HubSpot contacts for likely duplicates (same email, similar names, same company + similar name). -2. For each duplicate set: show both records side-by-side — name, email, company, deals, last activity. -3. Propose which record to keep and which fields to merge. - -Present all duplicate sets before merging anything. - -## Step 3 — Scan for missing required fields - -1. Check all open deals for missing fields: close date, amount, deal stage, associated contact, next-step/notes. -2. Check contacts associated with open deals for missing fields: email, company, phone. -3. Present a table of records with missing fields and what's missing. - -## Step 4 — Apply approved fixes - -1. Walk through each finding from Steps 1-3. -2. Apply only the changes the owner explicitly approves. -3. Report each change as it's made with a HubSpot link. - -## Connector failures - -If HubSpot is unreachable, stop — this command requires HubSpot as the data source. Tell the owner: "HubSpot isn't connected. Connect it in Cowork settings, then rerun /crm-cleanup." - -## Approval gates - -- **Never delete records.** Not contacts, not deals, not activities. If the user asks, say the skill cannot and direct them to HubSpot. -- **Never change deal stage or close a deal without explicit approval.** Even if evidence is strong. Flag and defer. -- **Never auto-merge duplicate contacts.** Show side-by-side and wait for approval per pair. -- **Side-by-side diffs for all changes.** Show current value and proposed value; wait for approval per item. - -## Output - -End with a summary: X deals updated, Y contacts merged, Z fields filled. Include links to the affected records. diff --git a/small-business/skills/crm-maintenance/SKILL.md b/small-business/skills/crm-maintenance/SKILL.md deleted file mode 100644 index f848fddd5..000000000 --- a/small-business/skills/crm-maintenance/SKILL.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -name: crm-maintenance -description: > - Keeps HubSpot current without the owner opening it: creates and updates - contacts and deals from email and calendar context, logs notes and calls, - and flags stale records. The "stop doing data entry" skill. Use when the - user asks to update the CRM, log a call, clean up HubSpot, or add context - to a deal. ---- - -# CRM Maintenance - -## Quick start - -Pull context from the referenced email or calendar event, resolve the right HubSpot contact and deal, log the activity, and surface what changed. For a deal cleanup, audit the deal against recent email/calendar activity and propose updates — never apply them without approval. - -``` -User: "log this call to the Acme deal" -→ Read the most recent completed calendar event -→ Confirm attendees map to the Acme deal's contacts -→ Write a call activity on the Acme deal -→ Report: "Logged call to Acme Q2 Expansion. [deal link]" -``` - -## Workflow - -1. **Identify intent.** Decide which of three paths applies from the user's message and context: - - **Email path** — "update my CRM", "add this to the deal", or any reference to an email thread - - **Call path** — "log this call", "log the meeting", or any reference to a calendar event - - **Cleanup path** — "clean up HubSpot", "is this deal up to date", or any request to audit a specific deal - If the intent is ambiguous (e.g. "update HubSpot" with no referenced email/meeting/deal), ask which path before proceeding. - -2. **Gather context.** - - Email path: read the thread (subject, participants, last 1–3 messages). Identify the primary external contact. - - Call path: read the calendar event (title, attendees, time, description). If no event was specified, use the most recent completed meeting in the last 24 hours and confirm with the user before proceeding. - - Cleanup path: pull the deal (stage, amount, close date, next-step, associated contacts, activities in last 60 days), plus the last 14 days of email threads and calendar events involving the deal's contacts. - -3. **Resolve the HubSpot contact and deal.** For email/call paths: - - Search HubSpot contacts by email address. If a contact is missing, create it from email signature or calendar invite data — announce creation in chat before writing. - - Find the right deal in this order: (a) explicit match if the user named one, (b) the contact's sole open deal, (c) fuzzy match across the contact's open deals against the email subject or meeting title — confirm before writing, (d) ask the user if no match. **Never auto-create a deal.** - - For field names, activity types, and association rules, read [reference/hubspot-fields.md](reference/hubspot-fields.md) before writing anything to HubSpot. - - If deduplication or deal-resolution feels ambiguous, check [reference/gotchas.md](reference/gotchas.md) before proceeding — it covers the most common failure modes. - -4. **Execute the action.** - - Email path: write an email activity with the thread subject as the title and a concise summary (not the full thread) as the body. Timestamp to the latest message. For a worked example, see [reference/examples/log-email-happy-path.md](reference/examples/log-email-happy-path.md). - - Call path: write a call activity with the event title, duration, and any notes available. Timestamp to the event start. For a worked example including a missing-contact scenario, see [reference/examples/log-call-happy-path.md](reference/examples/log-call-happy-path.md). - - Cleanup path: walk each field per [reference/cleanup-checklist.md](reference/cleanup-checklist.md) and assemble a proposed-changes list. Show current → proposed side-by-side. Write only what the user approves. For a full worked example, see [reference/examples/cleanup-deal.md](reference/examples/cleanup-deal.md). - -5. **Approval gate — every externally visible write.** For contact creation and activity logging, announce before writing and surface the result after. For cleanup edits, do not write anything until the user approves the specific changes. - -6. **Report what happened.** Tell the user what was written and what's pending. Include a HubSpot link to the affected deal when possible. Keep it short. - -## Approval gates - -- **Never delete records.** Not contacts, not deals, not activities. If the user asks, say the skill cannot and direct them to HubSpot. -- **Never change deal stage or close a deal without explicit user approval.** Even if evidence is strong. Flag and defer. -- **Never create a new deal unprompted.** Ask if the right deal can't be resolved. -- **Announce contact creation before writing.** One line — lets the user catch typos or duplicates. -- **Side-by-side diffs for cleanup.** Show current value and proposed value; wait for approval per item. - -## Reference - -- [reference/hubspot-fields.md](reference/hubspot-fields.md) — activity types, field names, association rules used in this skill -- [reference/cleanup-checklist.md](reference/cleanup-checklist.md) — the fields checked during a deal cleanup and the evidence needed to flag each -- [reference/gotchas.md](reference/gotchas.md) — Good / Bad patterns for contact resolution, activity summaries, and cleanup proposals -- [reference/examples/log-email-happy-path.md](reference/examples/log-email-happy-path.md) — worked example: email to existing deal -- [reference/examples/log-call-happy-path.md](reference/examples/log-call-happy-path.md) — worked example: meeting to existing deal, missing contact -- [reference/examples/cleanup-deal.md](reference/examples/cleanup-deal.md) — worked example: stale deal audit diff --git a/small-business/skills/crm-maintenance/reference/cleanup-checklist.md b/small-business/skills/crm-maintenance/reference/cleanup-checklist.md deleted file mode 100644 index d5c20da0d..000000000 --- a/small-business/skills/crm-maintenance/reference/cleanup-checklist.md +++ /dev/null @@ -1,70 +0,0 @@ -# Cleanup checklist - -The fields the `crm-maintenance` skill checks during a deal cleanup, plus the evidence needed to flag each. This runs when the user says "clean up HubSpot" or "is this deal up to date" scoped to a specific deal. - -Work through every item. Present findings as a review list; write only what the user approves. - -## 1. Last activity date - -**Check:** Is the deal's `hs_lastactivitydate` older than the most recent real interaction (email or meeting) involving its associated contacts? - -**Evidence to flag:** An email thread or calendar event in the last 14 days with one of the deal's contacts, newer than `hs_lastactivitydate`. - -**Proposed action:** Offer to log the missing activity. Don't mark the deal itself; logging the activity updates `hs_lastactivitydate` automatically. - -## 2. Next-step field (`hs_next_step`) - -**Check:** Does the current `hs_next_step` still reflect what was agreed in the latest email or meeting? - -**Evidence to flag:** The field says "send pricing" and a subsequent email shows pricing was sent. Or the field is blank and a recent meeting explicitly set a next action. - -**Proposed action:** Propose a new value (or blank if the step is completed). Show current → proposed side-by-side. - -## 3. Deal stage (`dealstage`) - -**Check:** Do recent interactions suggest the deal has moved stage — e.g., proposal sent, contract signed, lost to a competitor? - -**Evidence to flag:** Explicit language in email/meeting notes like "we're moving forward," "we signed," "we went with [competitor]," or a change in meeting cadence. - -**Proposed action:** **Flag only — never change stage automatically.** Surface the evidence and let the user decide. - -## 4. Close date (`closedate`) - -**Check:** Has the latest email/meeting referenced a revised timeline that conflicts with the current `closedate`? - -**Evidence to flag:** Phrases like "pushing to Q3," "we'll sign by end of month," or "delayed until next quarter." - -**Proposed action:** Propose an updated date. Show current → proposed. - -## 5. Amount (`amount`) - -**Check:** Has the latest email/meeting mentioned a different deal size? - -**Evidence to flag:** Explicit revised pricing in a pricing email, expanded scope in a meeting, or reduced scope the customer accepted. - -**Proposed action:** Propose an updated amount. Show current → proposed. - -## 6. Associated contacts - -**Check:** Are there people on recent emails or meetings with the deal's contacts who aren't themselves associated to the deal? - -**Evidence to flag:** An email CC or meeting attendee whose domain matches an existing deal contact's domain but who isn't on the deal. - -**Proposed action:** Propose adding the missing contact(s) to the deal. Create the contact in HubSpot first if they don't exist yet. - -## 7. Notes hygiene - -**Check:** Are there notes or activities older than 90 days that explicitly contradict the current deal state? - -**Evidence to flag:** A note saying "customer is lost" on a deal still in an open stage, or a note with an outdated contract amount. - -**Proposed action:** Add a new note clarifying the current state — **never edit or delete** the old note. Append, don't rewrite history. - -## Output format - -Present findings as a numbered list, each item showing: -- What was flagged -- The evidence (email subject + date, or meeting title + date) -- The proposed action (or "flag only" for stage changes) - -Then ask for approval item-by-item or bulk-approve. Write only what's approved. diff --git a/small-business/skills/crm-maintenance/reference/examples/cleanup-deal.md b/small-business/skills/crm-maintenance/reference/examples/cleanup-deal.md deleted file mode 100644 index 1217a8d90..000000000 --- a/small-business/skills/crm-maintenance/reference/examples/cleanup-deal.md +++ /dev/null @@ -1,83 +0,0 @@ -# Example: clean up a stale deal - -Worked scenario for the cleanup path — user asks the skill to audit one specific deal, skill surfaces findings and waits for approval. - -## Setup - -- Deal: "Acme Q2 Expansion" — stage "Proposal Sent," amount $18K, close date May 15, next step "send pricing," `hs_lastactivitydate` 22 days ago -- Deal has two associated contacts: Sarah Lin and Ben Rivera -- Last 14 days of email with Sarah include an Apr 18 thread titled "Re: Acme pricing" where Sarah confirmed the pricing and said "we'll sign once our legal review wraps, should be mid-June" -- A calendar event on Apr 20 titled "Acme — legal review walkthrough" included a new person, `maria.chen@acme.com`, who is not in HubSpot and not on the deal -- No email, meeting, or note suggests the deal has moved stage - -## User says - -> "Clean up the Acme Q2 Expansion deal." - -## Skill behavior - -**Step 1 — Identify intent.** -Cleanup path, scoped to one named deal. - -**Step 2 — Gather context.** -Pulls the deal record. Pulls email threads from the last 14 days involving Sarah and Ben. Pulls calendar events from the same window. - -**Step 3 — Resolve.** -Deal explicitly named — no resolution needed. Contacts on recent emails/meetings: Sarah (on deal), Ben (on deal), Maria Chen (not on deal, not in HubSpot). - -**Step 4 — Walk the cleanup checklist.** - -Skill does NOT write anything yet. Produces this review list: - -> **Cleanup review — Acme Q2 Expansion** -> -> **1. Last activity date.** Deal shows 22 days old. Newer activity found: Apr 18 email from Sarah ("Re: Acme pricing"), Apr 20 meeting ("Acme — legal review walkthrough"). Neither is logged to HubSpot. -> **→ Propose:** Log the Apr 18 email and the Apr 20 meeting as activities on this deal. -> -> **2. Next-step field.** Currently "send pricing." The Apr 18 email shows pricing was sent and confirmed by Sarah. -> **→ Propose:** `hs_next_step`: "send pricing" → "wait for legal review sign-off." -> -> **3. Deal stage.** Currently "Proposal Sent." No evidence of stage movement — Sarah said they'll sign *after* legal review. Stage is consistent with reality. -> **→ Flag only — no change.** -> -> **4. Close date.** Currently May 15. Sarah's Apr 18 email says "should be mid-June." -> **→ Propose:** `closedate`: May 15 → June 15. -> -> **5. Amount.** Currently $18K. Apr 18 email confirms 50 seats at $360 = $18K. No change needed. -> **→ No action.** -> -> **6. Associated contacts.** Maria Chen (`maria.chen@acme.com`) attended the Apr 20 legal review meeting. Not on the deal, not in HubSpot. -> **→ Propose:** Create the contact and associate to the deal. -> -> **7. Notes hygiene.** No conflicting notes found in the last 90 days. -> **→ No action.** -> -> Approve items 1, 2, 4, 6 to write? Or specify which ones. - -**Step 5 — Approval gate.** -Waits for the user. User replies: *"Yes to all except 4 — leave close date alone, she might be optimistic."* - -**Step 6 — Execute approved items.** -- Logs the Apr 18 email as an email activity -- Logs the Apr 20 meeting as a call activity with attendees Sarah, Ben, and (newly created) Maria -- Updates `hs_next_step` to "wait for legal review sign-off" -- Does NOT update `closedate` -- Creates Maria Chen contact and associates to the deal - -**Report.** - -> Wrote changes to Acme Q2 Expansion: -> - Logged Apr 18 email and Apr 20 call activities -> - Updated next step to "wait for legal review sign-off" -> - Created contact Maria Chen (maria.chen@acme.com) and added to deal -> Close date unchanged per your call. -> Deal stage was flagged as consistent with reality — no change needed. -> [HubSpot: Acme Q2 Expansion] - -## What this example demonstrates - -- Every field check from `reference/cleanup-checklist.md` applied to one deal -- Side-by-side current → proposed framing for every proposed change -- Stage change correctly held as flag-only -- User selectively approves items — skill honors the exact selection -- Contact creation folded into the same approval cycle diff --git a/small-business/skills/crm-maintenance/reference/examples/log-call-happy-path.md b/small-business/skills/crm-maintenance/reference/examples/log-call-happy-path.md deleted file mode 100644 index 65c7a0b9d..000000000 --- a/small-business/skills/crm-maintenance/reference/examples/log-call-happy-path.md +++ /dev/null @@ -1,68 +0,0 @@ -# Example: log a call with a missing contact - -Worked scenario for the call path — calendar event has three attendees, one of them isn't in HubSpot yet. - -## Setup - -- User just finished a 30-minute Google Meet titled "Acme — technical deep dive" at 10:00am -- Attendees on the calendar invite: the user, `sarah.lin@acme.com`, `ben.rivera@acme.com` -- Sarah Lin is an existing HubSpot contact on the "Acme Q2 Expansion" deal -- Ben Rivera is NOT in HubSpot -- The Acme Q2 Expansion deal is the only open deal for Sarah - -## User says - -> "Log this call." - -## Skill behavior - -**Step 1 — Identify intent.** -Call path. No specific event named — falls back to the most recent completed meeting in the last 24 hours. - -**Step 2 — Gather context.** -Finds the "Acme — technical deep dive" event from 10:00am. Confirms with the user before proceeding: - -> *"Logging the 'Acme — technical deep dive' call from 10:00am this morning — correct?"* - -User confirms. - -Reads event details: 30 minutes, external attendees `sarah.lin@acme.com` and `ben.rivera@acme.com`. No description on the event. - -**Step 3 — Resolve contact + deal.** -- Looks up `sarah.lin@acme.com` → exists (Sarah Lin, on Acme Q2 Expansion). -- Looks up `ben.rivera@acme.com` → does not exist. -- Announces contact creation: - -> *"Ben Rivera (ben.rivera@acme.com) isn't in HubSpot. Creating the contact and associating to the Acme Q2 Expansion deal."* - -Creates the contact with `email`, `firstname: Ben`, `lastname: Rivera`, `company: Acme` (inferred from email domain). Associates to the deal. - -Deal resolution: Sarah's only open deal is Acme Q2 Expansion — unambiguous match. - -**Step 4 — Execute.** -Writes a call activity on Acme Q2 Expansion: -- `hs_call_title`: Acme — technical deep dive -- `hs_call_body`: "Meeting held; notes to be added." (No description on the calendar event; placeholder surfaced to user so they know to add detail.) -- `hs_call_duration`: 30 min -- `hs_timestamp`: 10:00am today -- Associated contacts: Sarah Lin, Ben Rivera -- Associated deal: Acme Q2 Expansion - -**Step 5 — Approval gate.** -Announced the contact creation before writing. Activity write is inline per the user's explicit "log this call" request. - -**Step 6 — Report.** - -> Logged call activity to Acme Q2 Expansion: -> *"Acme — technical deep dive" (30 min, 10:00am)* -> Created new contact: Ben Rivera (ben.rivera@acme.com) — associated to the deal. -> Call body is a placeholder — add your notes if you want them on the deal timeline. -> [HubSpot: Acme Q2 Expansion] - -## What this example demonstrates - -- Fallback to most-recent-meeting when the user doesn't specify an event -- Confirmation before acting on inferred context -- Contact creation with inferred company from email domain -- Placeholder body with user notification when no meeting notes exist -- Associating multiple contacts (existing + newly created) to the same activity diff --git a/small-business/skills/crm-maintenance/reference/examples/log-email-happy-path.md b/small-business/skills/crm-maintenance/reference/examples/log-email-happy-path.md deleted file mode 100644 index 42fb82057..000000000 --- a/small-business/skills/crm-maintenance/reference/examples/log-email-happy-path.md +++ /dev/null @@ -1,50 +0,0 @@ -# Example: log email to an existing deal (happy path) - -A worked scenario for the email path — contact exists, deal resolves unambiguously, activity logs cleanly. - -## Setup - -- User is viewing an email thread with subject "Acme Q2 pricing follow-up" -- Thread has three messages between the user and `sarah.lin@acme.com` over the last two days -- `sarah.lin@acme.com` is an existing contact in HubSpot -- She is associated to exactly one open deal: "Acme Q2 Expansion" (proposal sent, $18K, close date May 15) - -## User says - -> "Add this thread to the deal." - -## Skill behavior - -**Step 1 — Identify intent.** -Email path (user said "this thread"). - -**Step 2 — Gather context.** -Reads the thread. Subject: "Acme Q2 pricing follow-up." Latest message (yesterday, 4:12pm) from Sarah: *"Confirmed, 50 seats at $360/seat works. Sending the signed SOW Friday."* Primary external contact: `sarah.lin@acme.com`. - -**Step 3 — Resolve contact + deal.** -Looks up `sarah.lin@acme.com` → contact exists (Sarah Lin, Acme Corp). Finds open deals associated to her: exactly one, "Acme Q2 Expansion." Match is unambiguous. - -**Step 4 — Execute.** -Writes an email activity on Acme Q2 Expansion: -- `hs_email_subject`: Acme Q2 pricing follow-up -- `hs_email_text`: "Sarah confirmed 50 seats at $360/seat ($18K). Signed SOW coming Friday." -- `hs_timestamp`: yesterday, 4:12pm -- Associated contact: Sarah Lin -- Associated deal: Acme Q2 Expansion - -**Step 5 — Approval gate.** -Contact already existed, no creation announcement needed. Activity write happens inline — no separate gate because the user explicitly asked. - -**Step 6 — Report.** - -> Logged email activity to Acme Q2 Expansion: -> *"Sarah confirmed 50 seats at $360/seat ($18K). Signed SOW coming Friday."* -> Timestamped yesterday 4:12pm. No contact created — Sarah was already on the deal. -> [HubSpot: Acme Q2 Expansion] - -## What makes this the happy path - -- Single unambiguous deal association — no fuzzy match needed -- Contact already existed — no creation flow -- Thread subject is descriptive — usable as-is for activity title -- Summary focuses on decisions and numbers, not full thread transcript diff --git a/small-business/skills/crm-maintenance/reference/gotchas.md b/small-business/skills/crm-maintenance/reference/gotchas.md deleted file mode 100644 index 1029eae9d..000000000 --- a/small-business/skills/crm-maintenance/reference/gotchas.md +++ /dev/null @@ -1,92 +0,0 @@ -# Gotchas - -Edge cases where the `crm-maintenance` skill is most likely to produce bad CRM data. Each entry uses the Good / Bad pattern. - ---- - -## Gotcha: Creating a duplicate contact when the email is already in HubSpot under a different case - -**Why it matters:** HubSpot dedupes on exact email match. `Sarah.Lin@acme.com` and `sarah.lin@acme.com` are treated as distinct, but an owner who already created one will see a silent duplicate appear. That destroys the owner's trust in the skill. - -### ✗ Bad - -> Searched HubSpot for `Sarah.Lin@acme.com` — no match. Creating new contact: Sarah Lin (Sarah.Lin@acme.com). - -New contact is created; owner's existing `sarah.lin@acme.com` contact now has a duplicate. - -### ✓ Good - -> Searched HubSpot for `sarah.lin@acme.com` (case-insensitive) — no match. Creating new contact: Sarah Lin (sarah.lin@acme.com). Announcing before write. - -Always normalize email to lowercase before lookup. Announce the creation so the owner can catch misses. - ---- - -## Gotcha: Writing the full email thread as the activity body - -**Why it matters:** HubSpot activities are signal surfaces for fast scanning, not a transcript archive. A 12-message thread pasted into the activity body is useless; a three-sentence summary of what was agreed is actionable. - -### ✗ Bad - -> **Activity body:** -> *From: Sarah Lin — Thu Apr 9…* -> *Hi! Following up on our call, here are the specs we discussed…* -> *[1,200 more words]* - -Owner scrolls past it every time. - -### ✓ Good - -> **Activity body:** Sarah confirmed scope for Q2 expansion — 50 seats, $18K ACV, start date June 1. She'll send the signed SOW by Friday. No open questions. - -Summary names the decisions, the numbers, and the next step. - ---- - -## Gotcha: Auto-creating a deal when the right one can't be resolved - -**Why it matters:** Duplicate deals are very hard to untangle in HubSpot — they split activity history, confuse reporting, and the owner usually notices weeks later when a forecast looks wrong. - -### ✗ Bad - -> No open deal found for Sarah Lin at Acme. Creating new deal: "Acme — new opportunity" and logging the call to it. - -Now there are two Acme deals and the owner has no idea which one is real. - -### ✓ Good - -> No open deal found for Sarah Lin at Acme. Which deal should I log this to? Options: (1) Acme Q2 Expansion (closed-won Feb), (2) Acme Renewal 2027 (open). Or do you want to skip logging for now? - -Ask. Never create a deal on behalf of the owner. - ---- - -## Gotcha: Proposing a deal stage change based on email language - -**Why it matters:** "We're moving forward" in an email doesn't always mean "advance to closed-won." Customers say it when they're moving forward with evaluation, or with a procurement step. Owners have context the skill doesn't. Auto-advancing stage is destructive to the pipeline. - -### ✗ Bad - -> Email from Sarah says "we're moving forward." Proposing `dealstage` → Closed Won. Writing now. - -### ✓ Good - -> Flagging: the Apr 18 email from Sarah ("we're moving forward with the Anthropic evaluation") may indicate stage movement. Current stage is "Proposal Sent." Do you want to advance it? I won't change stage without your explicit go-ahead. - -Surface the evidence, hold the write. - ---- - -## Gotcha: Overwriting an owner-set next-step during cleanup - -**Why it matters:** The owner may have set a next step that reflects context the skill can't see — a phone call, a Slack thread, a private note. Overwriting it because a recent email suggests something different erases real work. - -### ✗ Bad - -> `hs_next_step` currently says "wait for legal review." Latest email from Sarah says "let's schedule pricing review." Updating `hs_next_step` to "schedule pricing review." - -### ✓ Good - -> `hs_next_step` currently reads "wait for legal review" (set by you 3 days ago). The Apr 19 email from Sarah suggests a pricing review is also needed. Propose appending or replacing? Current → Proposed: "wait for legal review" → "wait for legal review; then schedule pricing review." Approve? - -Show the current value, propose the change explicitly, wait for approval. diff --git a/small-business/skills/crm-maintenance/reference/hubspot-fields.md b/small-business/skills/crm-maintenance/reference/hubspot-fields.md deleted file mode 100644 index 3a2913a38..000000000 --- a/small-business/skills/crm-maintenance/reference/hubspot-fields.md +++ /dev/null @@ -1,62 +0,0 @@ -# HubSpot fields and activity types - -The specific HubSpot objects, properties, and activity types the `crm-maintenance` skill reads from and writes to. Only the fields listed here are in-scope for this skill — everything else in HubSpot is untouched. - -## Contacts — write - -| Field | Usage | -|---------------|----------------------------------------------------------------------------------------| -| `email` | Primary identifier for lookup + dedupe. Always set on creation. | -| `firstname` | Set from email signature or calendar invite if available. Leave blank if unknown. | -| `lastname` | Set from email signature or calendar invite if available. Leave blank if unknown. | -| `company` | Set from email signature domain or calendar organization if available. | - -Do not write any other contact properties. Owner, lifecycle stage, and lead source are user-managed fields — never overwrite. - -## Contacts — read (for lookup) - -| Field | Usage | -|---------------|--------------------------------------------------------------------| -| `email` | Search key. Case-insensitive exact match. | -| `firstname` · `lastname` · `company` | Displayed to the user during ambiguity resolution. | -| `hs_object_id`| Used for association with deals and activities. | - -## Deals — read (all cleanup + resolution paths) - -| Field | Usage | -|-----------------------------|----------------------------------------------------------| -| `dealname` | Displayed to the user; used for fuzzy match against email/meeting topic | -| `dealstage` | Read-only during cleanup — flag discrepancies, never change | -| `amount` | Read during cleanup; flag if recent email/meeting implies change | -| `closedate` | Read during cleanup; flag if outdated | -| `hs_next_step` | Read + propose updates during cleanup | -| `hubspot_owner_id` | Displayed to the user; never changed | -| `hs_lastactivitydate` | Used to detect stale deals | -| Associated contacts | Used to determine whether recent email/meeting participants are on the deal | - -## Deals — write (cleanup path only, with approval) - -| Field | Rule | -|-----------------|------------------------------------------------------------------| -| `hs_next_step` | Propose updates; write only with explicit user approval | -| `closedate` | Propose updates; write only with explicit user approval | -| `amount` | Propose updates; write only with explicit user approval | -| Contact assoc. | Propose adding missing deal participants; write only with approval | - -**Never write** `dealstage`, `pipeline`, `hubspot_owner_id`, or any custom property during cleanup. Those are owner-managed. - -## Activities — write - -| Activity type | Used by | Fields set | -|--------------------------------|----------------|--------------------------------------------------------------------------| -| Email engagement (`EMAIL`) | Email path | `hs_email_subject` (thread subject), `hs_email_text` (summary, not full thread), `hs_timestamp` (latest message time), associated contact(s) + deal | -| Call engagement (`CALL`) | Call path | `hs_call_title` (event title), `hs_call_body` (summary), `hs_call_duration` (from calendar), `hs_timestamp` (event start), associated contact(s) + deal | -| Note (`NOTE`) | Cleanup path | `hs_note_body` (when flagging something for future review that doesn't fit a field update) | - -Use HubSpot's standard engagement vocabulary. Do not invent custom activity types. - -## Association rules - -- Every activity must associate to the deal AND to at least one contact. -- If a contact is created on-the-fly during activity logging, associate it to the deal in the same operation so the activity shows up on both the contact and deal timelines. -- Do not associate a contact to a deal during an activity-logging flow unless the contact is actually a participant in that email thread or meeting. diff --git a/small-business/skills/customer-pulse-check/SKILL.md b/small-business/skills/customer-pulse-check/SKILL.md deleted file mode 100644 index bdb75ba8a..000000000 --- a/small-business/skills/customer-pulse-check/SKILL.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -name: customer-pulse-check -description: Synthesizes themes from PayPal disputes, HubSpot tickets, and review exports into a top-3 fixable issues list with drafted response templates. Accepts optional since-date argument. -allowed-tools: Read, WebFetch, Bash ---- - -Run the customer voice synthesis. Pull feedback signals from all connected sources, identify the themes that are actually fixable, and produce drafted responses the owner can review and send. - -Parse arguments: -- `--since` (default: last 30 days) — start date `YYYY-MM-DD` for the lookback window - -## Step 1 — Gather feedback signals - -Using the `customer-pulse` skill workflow: - -1. Pull PayPal disputes and chargebacks for the period: reason codes, amounts, resolution status. -2. Pull HubSpot support tickets and conversation notes for the period. -3. If review export files are available (Google Reviews CSV, Yelp export, etc.) in Files: read and parse them. -4. Count total signals per source. - -## Step 2 — Theme extraction - -Cluster all signals into recurring themes. For each theme: -- Count how many signals mention it -- Classify: Product quality / Delivery / Billing / Communication / Expectation mismatch / Other -- Rate impact: 🔴 High (revenue risk, churn) / 🟡 Medium / 🟢 Low - -## Step 3 — Top-3 fixable issues - -Using the `ticket-deflector` skill workflow: - -Select the top 3 themes by: frequency × impact rating. For each: -1. State the issue in one sentence -2. Explain the root cause (where evident) -3. Suggest a specific operational fix -4. Draft a customer response template - -Response template format: -``` -Subject: Re: {issue topic} - -Hi {first name}, - -Thank you for reaching out. {Acknowledgment of their experience in 1-2 sentences}. - -{What we're doing about it / what happened / resolution offered}. - -{Next step or offer}. - -{Sign-off} -``` - -## Step 4 — Summary table - -Format the output as: - -``` -Customer Voice — {date range} -Total signals: {n} ({PayPal disputes: n} | {HubSpot tickets: n} | {Reviews: n}) - -TOP 3 FIXABLE ISSUES -1. {Issue} ({frequency}) — {impact} — Fix: {one-line fix} -2. {Issue} ({frequency}) — {impact} — Fix: {one-line fix} -3. {Issue} ({frequency}) — {impact} — Fix: {one-line fix} -``` - -## Connector failures - -Run with whatever sources are connected — this command degrades gracefully. If PayPal is missing, skip dispute data and note "PayPal not connected — dispute data skipped." If HubSpot is missing, skip ticket data and note it. If no sources are connected at all, stop and tell the owner: "No feedback sources connected. Connect at least one of PayPal, HubSpot, or upload a review export CSV." - -## Approval gates - -- **Never send response emails automatically.** Present drafts for owner review only. -- **Never close HubSpot tickets or resolve PayPal disputes without explicit owner confirmation.** -- **Never include customer PII in the summary** — use first name + last initial only. - -## Output - -Present the summary table, then each response template. Ask the owner which templates they'd like to send, then wait for explicit approval before drafting the send. diff --git a/small-business/skills/customer-pulse/SKILL.md b/small-business/skills/customer-pulse/SKILL.md deleted file mode 100644 index 422bd433c..000000000 --- a/small-business/skills/customer-pulse/SKILL.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -name: customer-pulse -version: 0.2.0 -description: > - Aggregates PayPal disputes, HubSpot feedback and tickets, and email - sentiment (plus pasted or exported Google/Yelp reviews) into a themes - report with verbatim evidence and a "do these three things this week" - list. Use when the user asks how customers are feeling, for review - analysis, what people are saying, or about disputes. ---- - -# Customer Pulse - -## Quick start - -Ask: *"How are customers feeling this month?"* - -Claude pulls disputes, tickets, email threads, and Intercom conversations for the last 30 days, groups them into 3–5 themes with verbatim evidence, and delivers a "do these 3 things this week" action list. - -To include Google/Yelp reviews, paste them after triggering — or say "I have some reviews to add." - -## Workflow - -1. **Set the date window.** Default: last 30 days. If the user specifies a range, use it. - -2. **Pull PayPal disputes.** Fetch disputes opened in the window. If the PayPal API returns a rate-limit error, skip and add `PayPal: rate-limited — not included` to the Sources section. Do not retry; do not error. See [reference/gotchas.md](reference/gotchas.md) for the rate-limit pattern. - -3. **Pull HubSpot tickets and feedback.** Fetch open and recently closed tickets. If 0 tickets exist, record `HubSpot tickets: 0` and continue — do not surface a warning. - -4. **Pull Gmail threads.** Search for threads in the window containing: `refund cancel unhappy issue problem disappointed frustrated broken late slow wrong missing`. Extract subject lines and 1–2 sentence excerpts per thread. - -5. **Pull Intercom conversations.** Call `search_conversations` to fetch open and recently closed conversations. Then call `get_conversation` for each conversation ID returned to access the full `conversation_parts`. Extract parts where `author.type === 'user'` — these are customer messages. Exclude parts where `author.type` is `admin` or `bot`. - -6. **Accept pasted reviews (optional).** If the user pastes Google or Yelp review text, include it in the source pool tagged as `[Review]`. No connector required. - -7. **Extract themes.** Group all evidence into 3–5 recurring themes. Each theme must include: - - A one-sentence label (e.g., "Shipping delays causing repeat complaints") - - 2–3 verbatim quotes with source tags: `[PayPal]`, `[HubSpot]`, `[Gmail]`, `[Intercom]`, or `[Review]` - - A signal count (how many items touch this theme) - - Verbatim quotes are non-negotiable — never paraphrase. See [reference/gotchas.md](reference/gotchas.md) for the verbatim anti-pattern. - -8. **Generate the "do these 3 things" list.** Rank themes by signal count. Pick the top 3 and write one concrete, owner-actionable step per theme. Format as a numbered checklist. - -9. **Deliver the report.** Structure the output with these sections in order: - - **Header** — H2 with "Customer Pulse" and the date range. - - **Sources pulled** — Bullet list with signal counts per source (PayPal - disputes, HubSpot tickets, Gmail threads, Intercom conversations, pasted - reviews). Note any source that was rate-limited and skipped. - - **Themes** — For each theme, show a bold numbered theme label with the - signal count, followed by two verbatim quotes as blockquotes, each - attributed to its source. - - **Do these 3 things this week** — Numbered list of three concrete, - owner-actionable steps, each tied to one of the top themes. - - For a complete worked example, see [reference/examples/example-report.md](reference/examples/example-report.md). - -## Approval gates - -This skill is **read-only** — it does not post, send, reply, or modify any records. No approval gate is required. - -## Reference - -- [reference/gotchas.md](reference/gotchas.md) — PayPal rate limits, HubSpot empty state, verbatim quote requirement, Gmail keyword drift -- [reference/examples/example-report.md](reference/examples/example-report.md) — full worked example output diff --git a/small-business/skills/customer-pulse/reference/examples/example-report.md b/small-business/skills/customer-pulse/reference/examples/example-report.md deleted file mode 100644 index 605b4d0aa..000000000 --- a/small-business/skills/customer-pulse/reference/examples/example-report.md +++ /dev/null @@ -1,52 +0,0 @@ -# Example: Customer Pulse Report - -**Trigger used:** "How are customers feeling this month?" -**Date range:** April 1–30, 2026 - ---- - -## Customer Pulse — April 1–30, 2026 - -### Sources pulled -- PayPal disputes: 4 -- HubSpot tickets: 9 -- Gmail threads: 14 -- Intercom conversations: 6 -- Pasted reviews: 0 - -### Themes - -**1. Shipping delays causing repeat complaints** (11 signals) -> "Ordered 2 weeks ago and still nothing — this is unacceptable." — [Gmail] -> "Package was 10 days late and support never responded." — [Intercom] -> "Where is my order? The tracking hasn't updated in 5 days." — [HubSpot] - -**2. Refund process too slow** (8 signals) -> "I filed a dispute because I never got a response to my refund request." — [PayPal] -> "It's been two weeks since I asked for a refund. Still waiting." — [Gmail] -> "Your return policy says 5 days but it's been 12." — [HubSpot] - -**3. Product quality below expectations** (5 signals) -> "The stitching came apart after one wash." — [Intercom] -> "Looks nothing like the photo." — [Gmail] -> "Would not buy again — quality is not what I expected for the price." — [HubSpot] - -### Do these 3 things this week -1. **Fix shipping comms** — Email every open order older than 7 days with a status update and a new ETA. This alone will cut Intercom volume before the root cause is resolved. -2. **Speed up refunds** — Set a 48-hour SLA for refund approvals and assign one person to clear the current backlog this week. -3. **Audit product listing photos** — Pull the top 3 products by complaint volume and update photos to match what's actually shipped. - ---- - -## Example: PayPal rate-limited run - -**Trigger used:** "Customer pulse for last 30 days" - -### Sources pulled -- PayPal disputes: rate-limited — not included -- HubSpot tickets: 7 -- Gmail threads: 11 -- Intercom conversations: 4 -- Pasted reviews: 3 - -*(Report continues normally with available sources. PayPal note appears only in Sources — no error message in the body.)* diff --git a/small-business/skills/customer-pulse/reference/gotchas.md b/small-business/skills/customer-pulse/reference/gotchas.md deleted file mode 100644 index 59ea97f92..000000000 --- a/small-business/skills/customer-pulse/reference/gotchas.md +++ /dev/null @@ -1,50 +0,0 @@ -# Gotchas — customer-pulse - -## Gotcha: PayPal rate limits on dispute queries - -**Why it matters:** PayPal's disputes API throttles aggressively on date windows with many disputes. Silent retries burn the user's time with no feedback. - -### ✗ Bad -Retry 3× automatically with no feedback. User sees a spinner for 30+ seconds before an error. - -### ✓ Good -On the first rate-limit error, skip PayPal, add `PayPal: rate-limited — not included` to the Sources section, and continue with the remaining connectors. Mention that the user can try again with a narrower date window. - ---- - -## Gotcha: Verbatim quotes paraphrased or summarized - -**Why it matters:** The owner needs to see the actual customer words — not Claude's interpretation. Paraphrase destroys the credibility of the report. - -### ✗ Bad -**Theme: Slow shipping** (8 signals) -> Customers reported that deliveries arrived later than expected. - -### ✓ Good -**Theme: Slow shipping** (8 signals) -> "Ordered 2 weeks ago and still nothing — this is unacceptable." — [Gmail] -> "Package was 10 days late and support never responded." — [Intercom] - ---- - -## Gotcha: HubSpot returning 0 tickets treated as an error - -**Why it matters:** Test portals and new accounts legitimately have 0 tickets. Surfacing a warning creates noise and erodes trust. - -### ✗ Bad -> ⚠️ HubSpot returned 0 tickets. Check your connection or permissions. - -### ✓ Good -Record `HubSpot tickets: 0` in the Sources section and continue. Only flag a connector issue if authentication itself fails. - ---- - -## Gotcha: Gmail keyword list too narrow - -**Why it matters:** Customers don't use standard complaint keywords. A 1-star experience often surfaces as "took forever" or "never again," not "disappointed." - -### ✗ Bad -Search only for: `refund cancel unhappy` - -### ✓ Good -Use the full seed list from Workflow step 4: `refund cancel unhappy issue problem disappointed frustrated broken late slow wrong missing`. Let theme-extraction filter signal from noise — over-inclusion is cheaper than missed themes. diff --git a/small-business/skills/friday-brief/SKILL.md b/small-business/skills/friday-brief/SKILL.md deleted file mode 100644 index 8c218041d..000000000 --- a/small-business/skills/friday-brief/SKILL.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -name: friday-brief -description: Delivers the Friday end-of-week pulse — revenue vs prior week, top sellers, wins and watches. Accepts optional lookback window of 7 or 14 days. -allowed-tools: Read, WebFetch, Bash ---- - -Run the Friday wins-and-watches briefing. Pull the numbers, surface what matters, and give the owner a clean end-of-week picture. - -Parse arguments: -- `--lookback` (default: `7d`) — `7d` for one week or `14d` for a two-week rolling comparison - -## Step 1 — Revenue pulse - -Using the `business-pulse` skill workflow: - -1. Pull PayPal transactions for the lookback period. -2. Pull any HubSpot deal closes for the same window. -3. Calculate week-over-week revenue delta. -4. Surface top 3 revenue sources (product / customer / channel) ranked by contribution. - -## Step 2 — Sales breakdown - -1. List the top 5 selling products/services by volume and revenue. -2. List the bottom 3 (anything that moved less than expected vs. prior period). -3. Flag any items with a sudden spike or drop (>20% change). - -## Step 3 — Wins and watches summary - -Format the output as: - -``` -Friday Brief — {date} - -WINS -• {win 1} -• {win 2} -• {win 3} - -WATCHES -• {watch 1} — {recommended action} -• {watch 2} — {recommended action} - -Revenue this week: ${amount} ({+/-}X% vs last week) -``` - -## Connector failures - -Run with whatever is connected — this command degrades gracefully. If PayPal is missing, skip transaction data and note "PayPal not connected — revenue data from HubSpot deals only." If HubSpot is missing, skip deal closes and note it. If neither is connected, stop and tell the owner: "No revenue sources connected. Connect PayPal or HubSpot to run the Friday brief." - -## Approval gates - -- **Never send or post this brief automatically.** Always display it for the owner to review first. -- **Never auto-cancel or modify anything.** Surface the data and recommendations only. - -## Output - -End with the formatted brief and ask the owner: "Want me to post this to Slack, email it to yourself, or save it?" diff --git a/small-business/skills/handle-complaint/SKILL.md b/small-business/skills/handle-complaint/SKILL.md deleted file mode 100644 index 0a15fc105..000000000 --- a/small-business/skills/handle-complaint/SKILL.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -name: handle-complaint -description: Handles an incoming customer complaint end-to-end — pulls context, drafts a response, and suggests an operational fix. Accepts optional email or ticket ID argument. -allowed-tools: Read, WebFetch, Bash ---- - -Run the complaint resolution workflow by chaining two skills. Read the complaint, gather context, draft a response, and suggest a fix so it doesn't happen again. - -Parse arguments: -- `EMAIL_OR_TICKET_ID` (optional) — Gmail thread ID, HubSpot ticket ID, or "latest" to pull the most recent unresolved complaint. If omitted, ask the owner to paste the complaint text. - -## Step 1 — Load the complaint (ticket-deflector) - -Using the `ticket-deflector` skill workflow: - -1. If an ID was given: pull the full thread from Gmail or HubSpot. -2. If "latest": pull the most recent unresolved HubSpot ticket or Gmail thread tagged as complaint/support. -3. If neither: ask the owner to paste the complaint text directly. -4. Identify: customer name, order/account info, what they're upset about, what they're asking for. - -## Step 2 — Pull context - -1. Search HubSpot for the customer's history: past purchases, prior complaints, deal stage, lifetime value. -2. Search PayPal for relevant transaction: order status, refund history, dispute status. -3. Summarize: "This is a {new/returning} customer, ${lifetime_value} in purchases, {0/N} prior complaints. Their current issue is {one sentence}." - -## Step 3 — Draft response (ticket-deflector) - -Using the `ticket-deflector` skill workflow for tone-matched response: - -1. Draft a reply matched to the severity and the customer's history: - - First-time complainers with high LTV → empathetic, generous - - Repeat complainers → professional, firm, solution-focused - - Abusive tone → professional, brief, boundary-setting -2. Include: acknowledgment, explanation (if known), resolution offer, next step. -3. Present the draft to the owner. Do NOT send. - -## Step 4 — Suggest operational fix (customer-pulse) - -1. Check if this complaint matches a known theme (from prior `/customer-pulse-check` runs or similar complaints in HubSpot). -2. If it's a pattern: "This is the {Nth} complaint about {issue} this month. Consider: {specific operational change}." -3. If it's isolated: "This looks like a one-off. No pattern detected." - -## Connector failures - -If Gmail and HubSpot are both unreachable, ask the owner to paste the complaint text — the skill works with manual input. If PayPal is missing, skip transaction lookup and note "PayPal not connected — order status unavailable, working from complaint text only." - -## Approval gates - -- **Never send a response without explicit owner approval.** Drafts only. -- **Never issue refunds or credits automatically.** Present the option; the owner decides. -- **Never close tickets or resolve disputes without owner confirmation.** - -## Output - -Present the customer context summary, the drafted response, and any pattern-based operational suggestion. Ask: "Want to send this response, edit it, or handle it differently?" diff --git a/small-business/skills/invoice-chase/SKILL.md b/small-business/skills/invoice-chase/SKILL.md deleted file mode 100644 index dad4f512a..000000000 --- a/small-business/skills/invoice-chase/SKILL.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -name: invoice-chase -version: 0.2.0 -description: > - Drafts overdue-invoice reminder emails from QuickBooks and PayPal data, - matched to each customer's payment history and tone (gentle for good customers, - firm for repeat late payers). Sends via PayPal with owner approval; - non-PayPal invoices queue as mail drafts. Use when the user asks - "who owes me money," mentions overdue invoices, or wants to follow up - on unpaid invoices. ---- - -# Invoice Chase - -## Quick start - -Pull the AR aging report, score each customer by payment history, draft a tone-matched reminder for each overdue invoice, and present them to the owner. Nothing sends until the owner says so. - -``` -User: "who owes me money" -→ Pull AR aging from QuickBooks -→ Cross-reference PayPal settlements (last 14 days) -→ Score each customer: good-payer / occasionally-late / repeat-late -→ Draft tone-matched reminders -→ Show summary table + drafts. Wait for "send these." -``` - -## Setup (first run only) - -Ask the owner two questions before running for the first time: - -1. **Mail connector**: "Do you use Gmail or Apple Mail for drafts?" — store the answer; use it for all non-PayPal draft queuing. -2. **Stripe**: "Do you use Stripe for invoicing? I can include Stripe invoices in the overdue sweep." — if yes, pull Stripe overdue invoices alongside QuickBooks. - -Do not ask again on subsequent runs. - -## Workflow - -1. **Pull overdue receivables.** Query QuickBooks AR aging for all invoices more than 1 day past due. If Stripe is enabled (owner confirmed at setup), also pull Stripe overdue invoices. - -2. **Cross-reference payment history.** For each overdue customer, query PayPal for settled transactions using these parameters: - - `transaction_status: S` (settled only — filters out pending and denied transactions that inflate result size and increase rate-limit risk) - - Date window: **last 7 days** ending today (not 14 or 30 — wider windows are the primary cause of PayPal 429 rate limit errors) - - **If PayPal returns a 429 rate limit error:** - - Retry once immediately with a **3-day window** instead. - - If the retry also returns 429, skip the PayPal cross-reference entirely for this run. Flag all customers in the batch as "PayPal unavailable — verify manually" in the summary table. Proceed to scoring using QuickBooks history only. Do not silently drop the caveat. - - If a customer shows a settled payment within the query window, flag as "possibly paid — verify" and exclude from the draft queue. - -3. **Score each customer.** Read [reference/tone-matching.md](reference/tone-matching.md) for scoring logic. Result: `good-payer`, `occasionally-late`, or `repeat-late`. - -4. **Draft reminder emails.** One email per customer — consolidate multiple overdue invoices into one email. Match tone to score. See [reference/examples/gentle-reminder.md](reference/examples/gentle-reminder.md) and [reference/examples/firm-reminder.md](reference/examples/firm-reminder.md). - -5. **Present drafts to owner.** Show a summary table first: - - | Customer | Amount Due | Days Late | Tone | Send via | - |---|---|---|---|---| - | Acme Corp | $1,200 | 18 days | Gentle | PayPal | - | Smith LLC | $450 | 47 days | Firm | Gmail draft | - - Then show each draft email in full. Wait for owner to say "send these" or approve individually. - -6. **Send or queue — only after approval.** - - PayPal invoices: send the reminder via PayPal. - - Non-PayPal invoices: queue as a draft in the owner's configured mail app. - - Never send without explicit approval. - -7. **Report what happened.** List what was sent, what was queued as draft, and what was flagged (possibly paid, excluded). - -## Approval gates - -- **Never send or queue a draft without explicit owner approval.** Present all drafts first; wait for the go-ahead. -- **Never include a customer who paid in the last 14 days.** Flag as "possibly paid — verify" instead. -- **Never send to a customer not in the QuickBooks AR report** (or Stripe, if enabled). No reminders from memory alone. -- **One approval covers one batch.** Adding a customer or changing a draft after approval starts a new round. - -## Reference - -- [reference/tone-matching.md](reference/tone-matching.md) — scoring logic, tone guidelines, subject line formulas -- [reference/gotchas.md](reference/gotchas.md) — known failure modes -- [reference/examples/gentle-reminder.md](reference/examples/gentle-reminder.md) — good-payer email example -- [reference/examples/firm-reminder.md](reference/examples/firm-reminder.md) — repeat-late-payer email example diff --git a/small-business/skills/invoice-chase/reference/examples/firm-reminder.md b/small-business/skills/invoice-chase/reference/examples/firm-reminder.md deleted file mode 100644 index e88dc6bd0..000000000 --- a/small-business/skills/invoice-chase/reference/examples/firm-reminder.md +++ /dev/null @@ -1,28 +0,0 @@ -# Firm Reminder — Repeat Late Payer Example - -**Scenario:** Smith LLC, $450 invoice, 47 days past due. Paid late in 3 of last 4 invoices. - -**Score:** `repeat-late` · **Tone:** Firm - ---- - -**Subject:** Past due notice: Invoice #1038 — $450 (47 days overdue) - -Hi Tom, - -Invoice #1038 for $450 is now 47 days past due. The original due date was March 11. - -Please remit payment by May 2. You can pay online here: [Pay Invoice #1038 — $450] - -If there's a question about this invoice, reply to this email and I'll sort it out quickly. - -[Owner name] - ---- - -**Why this works:** -- States the facts directly: amount, invoice number, days overdue, original due date -- One clear deadline in the body -- Leaves a professional out ("if there's a question") without being apologetic -- Single call to action — one payment link -- Firm but professional — no threats, no caps diff --git a/small-business/skills/invoice-chase/reference/examples/gentle-reminder.md b/small-business/skills/invoice-chase/reference/examples/gentle-reminder.md deleted file mode 100644 index 729ab2620..000000000 --- a/small-business/skills/invoice-chase/reference/examples/gentle-reminder.md +++ /dev/null @@ -1,27 +0,0 @@ -# Gentle Reminder — Good Customer Example - -**Scenario:** Acme Corp, $1,200 invoice, 18 days past due. Paid on time in 5 of 5 prior invoices. - -**Score:** `good-payer` · **Tone:** Gentle - ---- - -**Subject:** Quick reminder: Invoice #1042 for $1,200 - -Hi Sarah, - -Just a quick note — Invoice #1042 for $1,200 was due on April 9 and I haven't seen payment come through yet. - -I know things get busy — if it's already on its way, please disregard! If not, here's the link to pay online: [Pay Invoice #1042 — $1,200] - -Thanks so much, and let me know if anything looks off on the invoice. - -[Owner name] - ---- - -**Why this works:** -- Opens with assumption of oversight, not accusation -- Gives an easy out ("if it's already on its way") -- Single call to action — one payment link -- Short. No lecture, no policy statement. diff --git a/small-business/skills/invoice-chase/reference/gotchas.md b/small-business/skills/invoice-chase/reference/gotchas.md deleted file mode 100644 index 8f698c325..000000000 --- a/small-business/skills/invoice-chase/reference/gotchas.md +++ /dev/null @@ -1,45 +0,0 @@ -# Gotchas - -Known failure modes for invoice-chase. - ---- - -**Customer paid via check or bank transfer — not visible in PayPal.** - -The PayPal cross-reference only catches PayPal payments. A customer who paid by check or ACH may still appear as overdue in AR. Note this in the summary: "PayPal history only — check/ACH payments not verified." Let the owner confirm before sending. - ---- - -**QuickBooks AR includes internal or test accounts.** - -Some setups include internal billing accounts or test records in AR. Before drafting, filter out customers whose email domain matches the owner's domain, and flag any customer name containing "Test," "Internal," or "Demo." - ---- - -**Multiple overdue invoices from the same customer — send one email only.** - -Never draft two separate reminders to the same customer in one batch. Consolidate all overdue invoices into one email with a total amount and a list of invoice numbers. Two emails to the same person in one batch looks disorganized and may trigger a spam filter. - ---- - -**PayPal reminder send fails for customers without a PayPal account.** - -PayPal reminders only work if the customer has an active PayPal account. If PayPal returns a send error, fall back to queuing a mail draft and report the fallback: "PayPal send failed for [customer] — queued as [mail app] draft instead." Do not silently drop the reminder. - ---- - -**Stripe and QuickBooks may both carry the same invoice.** - -If Stripe is enabled and a customer appears in both QuickBooks AR and Stripe overdue, it may be the same invoice in two systems. Match on invoice number first; if no number match, match on amount + due date. When uncertain, flag to the owner and send only one reminder rather than two. - ---- - -**PayPal API returns 429 rate limit errors.** - -PayPal's MCP connector rate-limits aggressively when the requested date window is wide. The most common cause is querying 14–30 days of transactions in a single call. - -*Fix:* Always query with `transaction_status: S` (settled only) and a **7-day window** ending today. This is the default in the workflow. - -*Retry pattern:* If a 7-day query returns 429, retry immediately with a **3-day window**. A narrower window reduces the response payload and usually succeeds. - -*Fallback:* If the 3-day retry also returns 429, skip the PayPal cross-reference for this run entirely. Flag every customer in the batch as "PayPal unavailable — verify manually" in the summary table. Proceed with QuickBooks-only scoring. Do not silently drop the caveat — the owner needs to know the cross-reference was skipped before approving any sends. diff --git a/small-business/skills/invoice-chase/reference/tone-matching.md b/small-business/skills/invoice-chase/reference/tone-matching.md deleted file mode 100644 index 18e2a5ade..000000000 --- a/small-business/skills/invoice-chase/reference/tone-matching.md +++ /dev/null @@ -1,44 +0,0 @@ -# Tone Matching - -Scoring logic and email tone guidelines for invoice-chase. - -## Scoring - -Score each customer using QuickBooks payment history for the last 12 months. Require a minimum of 3 invoices to score; fewer than 3 defaults to `occasionally-late`. - -| Score | Criteria | -|---|---| -| `good-payer` | Paid on time or early in ≥ 75% of invoices | -| `occasionally-late` | Paid late in 25–50% of invoices, or fewer than 3 invoices on record | -| `repeat-late` | Paid late in > 50% of invoices | - -"On time" means payment received on or before the invoice due date. - -## Tone by score - -| Score | Tone | Character | -|---|---|---| -| `good-payer` | Gentle | Friendly, assumes oversight. Opens with grace. | -| `occasionally-late` | Neutral | Professional, no judgment. Factual follow-up. | -| `repeat-late` | Firm | Direct, states a deadline. No warmth, no accusation. | - -## Subject lines - -- Gentle: `Quick reminder: Invoice #[N] for $[amount]` -- Neutral: `Following up: Invoice #[N] — $[amount] past due` -- Firm: `Past due notice: Invoice #[N] — $[amount] ([X] days overdue)` - -## Body structure (all tones) - -Every reminder includes: invoice number(s), total amount due, original due date, days overdue, and payment link or instructions. - -Tone-specific additions: -- **Gentle**: one acknowledgment sentence ("I know things get busy") -- **Neutral**: none — facts only -- **Firm**: one deadline sentence ("Please remit by [date]") - -One call to action per email. Never two. - -## Consolidation rule - -If a customer has multiple overdue invoices, combine into one email. List each invoice (number, amount, due date), then state the combined total. Use the customer's score, not the most overdue invoice's score. diff --git a/small-business/skills/job-post-builder/SKILL.md b/small-business/skills/job-post-builder/SKILL.md deleted file mode 100644 index 8606901f1..000000000 --- a/small-business/skills/job-post-builder/SKILL.md +++ /dev/null @@ -1,344 +0,0 @@ ---- -name: job-post-builder -description: > - Builds end-to-end hiring packets — job post, structured interview guide with - scoring rubric, and offer letter template — from a hiring brief. Triggers on: - "help me hire", "we're hiring for", "write a job post", "job description", - "JD", "open role", "create a job ad", "interview questions", "scoring rubric", - "draft an offer letter", "send an offer", "make a hiring packet", or any - request to recruit for a position. When in doubt, trigger — covers the full - hiring workflow from job post through DocuSign envelope creation via browser. - Does NOT screen or rank applicants. ---- - -# Job Post Builder - -Produces a complete hiring packet — job post, interview guide, and offer letter -— from a brief conversation about the role. Optionally routes the offer letter -to DocuSign via Claude in Chrome. - ---- - -## Quick start - -Invoke when a user says they need to hire someone or produce any hiring document. -The skill walks a 6-phase workflow: gather context → research the market → write -the job post → draft the interview guide → assemble the offer letter → (optionally) -route to DocuSign. - -**Example trigger:** -> "We're hiring a senior product manager. Can you put together the job post and -> interview questions?" - ---- - -## Workflow - -1. **Gather role context** — Ask for role title, responsibilities, qualifications, - location, comp, interview process, and offer delivery preference (Word doc vs. - DocuSign). Source: conversation / AskUserQuestion. -2. **Research comparable posts** — Search Google Drive / Desktop for existing JDs - and templates; run web search for 3–5 live postings for this role. Sources: - file MCP, web search. -3. **Write the job post** — Draft a market-informed job description using - `references/job-post-structure.md`. Output: `[Role]-Job-Post.docx` via docx skill. -4. **Draft interview guide + scoring rubric** — Build a stage-by-stage guide using - `references/interview-guide-structure.md`. Output: `[Role]-Interview-Guide.docx` - via docx skill. -5. **Assemble offer letter** — Build offer letter with bracketed placeholders using - `references/offer-letter-template.md`. Output: `[Role]-Offer-Letter.docx` via - docx skill. -6. **Route to DocuSign (if requested)** — Use Claude in Chrome to navigate DocuSign, - upload the offer letter, configure the envelope, and save a draft. Requires - explicit user approval before the envelope is sent. - ---- - -## Approval gates - -This skill performs externally-visible actions in Phase 6. The following rules apply: - -- **Never send a DocuSign envelope without approval.** Save the envelope as a draft - and return the URL. The user must review and confirm before Claude clicks Send. -- **Never send the Gmail fallback email without approval.** If the DocuSign browser - flow fails, draft the fallback email and show it to the user before sending. -- **Never publish the job post.** Produce the .docx file only. Posting to any job - board is the user's responsibility. - -Phase 6 will not advance past "Save as draft" without the user explicitly confirming -they have reviewed the envelope and want it sent. - ---- - -## Phase 1 — Understand the Role - -Before researching or writing anything, gather enough context to do it well. -Ask the user (via conversation or AskUserQuestion) for: - -- **Role title** — exact title they want to post -- **Team / function** — who this person reports to and works with -- **Key responsibilities** — 3–5 things this person will own day-to-day -- **Must-have qualifications** — hard requirements (years of experience, specific skills, credentials) -- **Nice-to-have qualifications** — preferred but not required -- **Location / remote policy** — on-site, hybrid, or fully remote; location if relevant -- **Compensation range** — salary band if they have one (flag that this needs HR/legal sign-off) -- **Existing JD or template?** — ask if there's a prior version in Google Drive or on their Desktop to use as a starting point -- **Offer letter delivery preference** — ask how they'd like the offer letter delivered: - - *Send directly via DocuSign* — skill opens DocuSign in Chrome, uploads the letter, sets up the envelope, and saves a draft for review before sending - - *Just the Word doc* — skill saves the offer letter as a .docx and stops there; the user handles routing themselves - -- **Interview process** — ask how their hiring process is structured: - - How many rounds/stages are there? - - Who conducts each stage? (e.g. recruiter, hiring manager, peer, skip-level, panel) - - What is each stage meant to assess? (e.g. culture fit, technical depth, cross-functional collaboration) - - Is there a take-home exercise or work sample at any stage? - - This is critical — the interview guide will be organized by stage, and each stage - gets its own question set. If the user doesn't know yet, suggest a sensible default - based on the role level and company size, and confirm before proceeding. - - Example default for a mid-senior IC role: - | Stage | Interviewer | Focus | - |---|---|---| - | Phone screen | Recruiter | Communication, baseline fit, logistics | - | Hiring manager interview | HM | Scope, ownership, role-specific depth | - | Peer interview | Team member | Collaboration, working style | - | Skills/case exercise | Senior IC | Relevant technical or domain depth | - | Final / culture interview | Skip-level or exec | Values, long-term trajectory | - -Capture the delivery preference in Phase 1 so the right Phase 5/6 path is clear -before any writing starts. If the user already indicated a preference (e.g. "send -it to DocuSign"), extract it from their message rather than asking again. - -If the user has already provided most of this in their message, extract it and -confirm before moving on rather than asking redundant questions. One focused -clarifying question is better than a long form. - ---- - -## Phase 2 — Research Comparable Posts - -Good job posts are grounded in what the market actually says for this role. -Do both of the following in parallel: - -**A. Check existing files first** -Search Google Drive and Desktop for prior JDs, offer letter templates, or -interview guides the user may already have. Use file search tools with terms like -the role title, "job description", "JD", "offer letter", "interview". If found, -read them and use them as the baseline — preserving any existing language, -structure, or requirements the user has established. - -**B. Web search for comparable posts** -Search for current job postings for this role at comparable companies. Good -sources include LinkedIn, Greenhouse, Lever, Workday, and company career pages. -Look for 3–5 real postings and note: -- Common responsibilities listed for this role -- Qualifications that appear consistently (these are table stakes) -- How companies describe the role's impact/scope -- Any language patterns that make postings feel compelling vs. generic - -Use this research to pressure-test the user's requirements (are they missing -something standard? asking for something unusual?) and to make the job post -feel current and market-aware. - ---- - -## Phase 3 — Write the Job Post - -Read `references/job-post-structure.md` for the full recommended structure and -writing guidance. - -**If an existing job post or JD was found in Phase 2:** -Use it as the structural template — mirror its section names, tone, ordering, and -any boilerplate the user has established (e.g. company description, benefits blurb, -how-to-apply language). The user's format is the source of truth. - -Compare it against `references/job-post-structure.md` and surface any missing -components in a single question before writing: - -> "Your existing JD has a responsibilities section and requirements list, but I -> didn't see an opening hook or a description of what success looks like in year one. -> Want me to add those, or keep it to your current format?" - -Only add the missing components if the user confirms. - -**If no existing job post was found:** -Build from scratch using `references/job-post-structure.md` as the full template. - -**Either way:** -- Lead with impact, not just tasks -- Be honest about what's hard — candidates who self-select in are better fits -- Use inclusive language; avoid jargon that implicitly filters for in-group candidates -- Keep the required qualifications list tight — every line is a reason someone doesn't apply -- If compensation isn't provided, omit the range rather than invent one - -Save as `[Role]-Job-Post.docx` using the docx skill. -Read `docx/SKILL.md` before generating the file. - ---- - -## Phase 4 — Draft Interview Questions + Scoring Rubric - -Read `references/interview-guide-structure.md` for the full recommended format. - -**If an existing interview guide was found in Phase 2:** -Use the user's existing guide as the structural template — mirror its section names, -ordering, and formatting conventions. The user's format is the source of truth; the -reference file is a checklist, not an override. - -After mapping the existing guide's sections against the reference, surface any -components present in the reference but missing from the user's guide. Present -these as a short, friendly question before writing — for example: - -> "Your existing guide has a question bank and scoring rubric, but I noticed it -> doesn't include an interview stage map or a debrief guide. Want me to add those, -> or keep it to your current structure?" - -Only add the missing components if the user confirms. Don't silently expand their -format without asking. - -**If no existing guide was found:** -Build the guide from scratch using `references/interview-guide-structure.md` as -the full template. The reference defines the recommended sections, question format, -rubric anchors, and debrief guidance — follow it completely. - -**Either way, organize the guide by interview stage using the process captured in Phase 1.** - -Structure the document so each stage is its own section: - -Each stage gets its own section with the stage name and interviewer as the heading, -followed by: the focus area this stage assesses, 4-6 behavioral questions specific -to that focus, 2-3 follow-up probes per question, and a 1/3/5 scoring rubric with -anchors for each competency the stage owns. - -**Key principles for multi-stage guides:** -- Each competency should be owned by one stage — avoid two interviewers asking - the same thing. If there's overlap, assign different angles. -- For panel interviews, split questions across panelists explicitly so each person - knows what they're covering. -- If there's a take-home exercise, include a structured debrief section for - reviewing it — what to look for, how to score it, follow-up questions. -- The debrief guide goes at the end, after all stage sections. -- 1/3/5 scoring anchors should be written for this specific role, not generic. - -Save as `[Role]-Interview-Guide.docx` using the docx skill. - ---- - -## Phase 5 — Assemble the Offer Letter Template - -Read `references/offer-letter-template.md` for the full base template and field -definitions. - -**If an existing offer letter or template was found in Phase 2:** -Use it as the structural template — preserve the user's formatting, clause ordering, -signature blocks, and any legal language they've already established. Their version -is the source of truth. - -Compare it against `references/offer-letter-template.md` and surface any missing -components in a single question before writing: - -> "Your existing offer letter has compensation and position details, but I noticed -> it doesn't include an at-will employment clause or a legal review disclaimer. -> Want me to add those, or keep it to your current format?" - -Only add the missing components if the user confirms. - -**If no existing offer letter was found:** -Build from scratch using `references/offer-letter-template.md` as the full template. - -**Either way:** -- Use clearly marked `[BRACKETED]` placeholder fields for all candidate-specific values -- Include: at-will clause (if applicable), contingency conditions, legal review disclaimer -- Don't invent compensation figures — leave them as placeholders if not provided - -Save as `[Role]-Offer-Letter.docx` using the docx skill. - -**Then branch based on the delivery preference captured in Phase 1:** -- If the user chose **DocuSign** → proceed to Phase 6 -- If the user chose **Word doc only** → skip Phase 6, deliver the .docx and close out - ---- - -## Phase 6 — Route the Offer Letter Directly to DocuSign - -Use Claude in Chrome to upload the offer letter into DocuSign and set up the -envelope, so the user doesn't have to touch DocuSign manually. - -**Step-by-step browser flow:** - -1. Navigate to `https://app.docusign.com` — the user should already be logged in. - If a login screen appears, pause and ask the user to log in, then continue. - -2. Click **"Start" → "Send an Envelope"** (or the equivalent "New" / "Use a Template" - button depending on the UI version). - -3. **Upload the offer letter:** Click "Upload Documents" and upload the - `[Role]-Offer-Letter.docx` file that was just created. - -4. **Add the signer:** In the Recipients section, add the candidate as a signer. - Ask the user for the candidate's name and email if not already provided. - Set their role to "Signer". - -5. **Add the sender as a CC recipient** if the user wants a copy (ask if unsure). - -6. **Set the subject line:** `Offer of Employment — [Role Title] at [Company Name]` - -7. **Add a message:** - > "Hi [Candidate First Name], we're thrilled to extend this offer and look - > forward to having you join the team. Please review and sign at your - > earliest convenience. Don't hesitate to reach out if you have any questions." - -8. **Place signature fields:** On the document, place a Signature field and a - Date Signed field on the candidate acceptance line at the bottom of the letter. - -9. **Save as draft** — do NOT send. Return the envelope URL to the user so they - can review before sending. - -Tell the user: -> "The DocuSign envelope has been set up with the offer letter and candidate -> details. Here's the draft link: [ENVELOPE URL]. Review the signature placement, -> then confirm here when you're ready to send." - -**Fallback:** If DocuSign is unavailable or the browser flow fails at any step, -fall back to the Gmail draft approach: draft an email via the Gmail MCP with the -offer letter attached and a note to upload it to DocuSign manually. Show the -draft to the user before sending. - ---- - -## Delivering the Packet - -Once all three files are created, present them together: - -Present a summary listing the three deliverables by role title: the job post -docx (ready to post), the interview guide docx (share with interviewers), and -the offer letter docx (routed to DocuSign draft or ready for manual upload). - -Remind the user: -- The offer letter template needs legal review before use in any jurisdiction -- Compensation ranges should be confirmed with HR before publishing the job post -- This skill does not screen or rank applicants - ---- - -## Reference Files - -Load these when reaching the relevant phase — don't load all upfront: - -| File | Load when | -|---|---| -| `references/job-post-structure.md` | Phase 3 — before writing the job post | -| `references/interview-guide-structure.md` | Phase 4 — before writing the interview guide | -| `references/offer-letter-template.md` | Phase 5 — before writing the offer letter | -| `references/gotchas.md` | Any phase — non-obvious edge cases | -| `references/examples/worked-example.md` | For reference on expected output shape | - ---- - -## Tests - -See `tests/triggers.md` for must-trigger, must-NOT-trigger, and ambiguous routing cases. - -See `tests/scenarios.md` for end-to-end scenario walkthroughs covering the happy -path, missing connector, and approval gate flows. diff --git a/small-business/skills/job-post-builder/reference/examples/worked-example.md b/small-business/skills/job-post-builder/reference/examples/worked-example.md deleted file mode 100644 index a620e9008..000000000 --- a/small-business/skills/job-post-builder/reference/examples/worked-example.md +++ /dev/null @@ -1,110 +0,0 @@ -# Worked Example: Senior Product Manager - -## Input - -User message: -> "We need to hire a Senior Product Manager for our payments team. They'll own -> the roadmap for our checkout experience. We want 5+ years of PM experience, -> ideally with a fintech or payments background. Remote-friendly, NYC preferred. -> Comp is $160–185k base. Three interview rounds: recruiter screen, hiring manager -> deep-dive, and a panel with two senior PMs. Send the offer via DocuSign when -> we get there." - ---- - -## Phase 1 — What Claude extracts - -| Field | Value | -|---|---| -| Role title | Senior Product Manager | -| Team / function | Payments team | -| Key responsibilities | Own roadmap for checkout experience | -| Must-haves | 5+ years PM experience | -| Nice-to-haves | Fintech or payments background | -| Location | Remote-friendly, NYC preferred | -| Compensation | $160–185k base | -| Interview process | 3 rounds: recruiter screen, HM deep-dive, senior PM panel (2 people) | -| Offer delivery | DocuSign | - -Claude confirms and asks exactly one question: -> "Got it — hiring packet for a Senior PM on the payments team, $160–185k, -> remote-friendly NYC. One question before I start: do you have an existing job -> description or offer letter template I should use as the starting point, or -> should I build from scratch?" - ---- - -## Expected output - -### `Senior-PM-Job-Post.docx` - -Structure follows `references/job-post-structure.md`: - -1. **Opening hook** — Why this role exists now: the payments team is scaling the - checkout experience and needs someone to own the roadmap end-to-end. -2. **About the company** — 3–4 sentences (Claude asks or infers from context). -3. **About the role** — What success looks like 12 months in: a faster, more - reliable checkout with measurably higher conversion. -4. **What you'll do** — 5–6 bullets, action-verb led (e.g. "Own the checkout - roadmap from discovery through launch…"). -5. **What we're looking for** — Required: 5+ yrs PM exp, comfort with data, - strong written communication. Preferred: fintech or payments domain experience. -6. **Compensation** — $160,000–$185,000 base salary. -7. **How to apply** — One sentence. - -Length target: 500–650 words. - ---- - -### `Senior-PM-Interview-Guide.docx` - -Structure follows `references/interview-guide-structure.md`: - -- **Role summary** — one paragraph reminding interviewers what they're assessing. -- **Stage map** — 3 stages, each interviewer, each competency. -- **Stage 1: Recruiter screen** — Communication, baseline fit, logistics. - Questions focus on career narrative and logistics (comp, start date, remote setup). -- **Stage 2: HM deep-dive** — Roadmap ownership, payments context, prioritization - under constraints. 5–6 behavioral questions; 2–3 follow-up probes each. -- **Stage 3: Senior PM panel** — Split between the two panelists. Panelist A owns - product judgment (how they make tradeoffs); Panelist B owns cross-functional - collaboration (how they work with engineering and design). Questions are pre-assigned - so the candidate isn't asked the same thing twice. -- **Scoring rubric** — 1/3/5 anchors written specifically for a payments PM role - (not generic). Example for "Ownership": 5 = proactively identified checkout - failure mode no one asked them to track, drove fix, documented for team. -- **Debrief guide** — Interviewers share scores before discussion; focus debrief - on divergent scores. - ---- - -### `Senior-PM-Offer-Letter.docx` - -Based on `references/offer-letter-template.md`. Pre-filled where data is available: - -| Field | Value | -|---|---| -| `[JOB TITLE]` | Senior Product Manager | -| `[ANNUAL SALARY]` | `$160,000–$185,000 — confirm exact figure with HR before sending` | -| `[CANDIDATE FULL NAME]` | Left blank | -| `[PROPOSED START DATE]` | Left blank | -| `[OFFER EXPIRATION DATE]` | Left blank | -| At-will clause | Included | -| Legal review disclaimer | Included | - ---- - -## Phase 6 — Expected browser flow - -1. Claude navigates to `https://app.docusign.com` and confirms login state. -2. Clicks "Start → Send an Envelope". -3. Uploads `Senior-PM-Offer-Letter.docx`. -4. Asks: "What's the candidate's full name and email address?" -5. Adds candidate as Signer; adds user as CC if requested. -6. Sets subject: `Offer of Employment — Senior Product Manager at [Company Name]`. -7. Places Signature and Date Signed fields on the acceptance line. -8. Saves as draft — does NOT send. -9. Returns draft URL and tells the user to review before confirming Send. - -**Pass criteria:** User opens the draft URL, sees correct signature placement, -and can send with one click. Envelope status is "Draft" until the user acts. diff --git a/small-business/skills/job-post-builder/reference/gotchas.md b/small-business/skills/job-post-builder/reference/gotchas.md deleted file mode 100644 index 034a9a673..000000000 --- a/small-business/skills/job-post-builder/reference/gotchas.md +++ /dev/null @@ -1,68 +0,0 @@ -# Gotchas - -## 1. DocuSign login state - -✗ **Bad:** Claude navigates to `https://app.docusign.com` and immediately tries -to upload the offer letter without checking whether the user is logged in. - -✓ **Good:** Immediately after navigating to DocuSign, check for a login screen. -If a login prompt appears, pause and ask the user to log in, then wait for -confirmation before continuing. - -**Why it matters:** DocuSign redirects unauthenticated sessions silently. If the -login check is skipped, the automation tries to click UI elements that don't exist -and fails mid-flow with no clear error. - ---- - -## 2. Missing candidate details before entering the browser - -✗ **Bad:** Claude reaches Phase 6, opens DocuSign in Chrome, and then asks mid-flow: -"What's the candidate's email address?" - -✓ **Good:** If the user chose DocuSign delivery in Phase 1, collect the candidate's -full name and email address before Phase 6 begins — either in Phase 1 or at the -end of Phase 5. Never enter the browser flow without both fields. - -**Why it matters:** Interrupting an open browser session to collect missing data -disrupts the automation state and confuses the user. - ---- - -## 3. Re-asking for context the user already provided - -✗ **Bad:** The user says "we need to hire a senior PM, fully remote, $160–180k" -and Phase 1 asks for role title, location, and compensation anyway. - -✓ **Good:** Extract role title, location, and compensation from the message, confirm -them in a single sentence, and ask only for the fields that are genuinely missing. - -**Why it matters:** The skill explicitly requires "one focused clarifying question -rather than a long form." Redundant questions break trust and slow the workflow. - ---- - -## 4. Silently expanding the user's existing format - -✗ **Bad:** The user has a 3-section job post on file. Claude produces a 7-section -post based on `references/job-post-structure.md` without asking. - -✓ **Good:** Map the user's existing format against the reference, identify missing -sections, and ask one question: "Your existing JD has X and Y — want me to add Z, -or keep your current format?" - -**Why it matters:** The user's format is the source of truth. Overriding it silently -may conflict with internal HR or legal standards the user hasn't mentioned. - ---- - -## 5. Inventing compensation figures - -✗ **Bad:** No salary range was provided, so Claude writes "$120,000–$150,000 DOE" -in the job post or offer letter. - -✓ **Good:** If compensation isn't provided, omit the range from the job post entirely. -In the offer letter, use `[ANNUAL SALARY — confirm with HR]` as a bracketed placeholder. - -**Why it matters:** Inventing compensation figures creates legal and HR liability. -The skill's instructions are explicit: "Don't invent a range." diff --git a/small-business/skills/job-post-builder/reference/interview-guide-structure.md b/small-business/skills/job-post-builder/reference/interview-guide-structure.md deleted file mode 100644 index d9f73c0b4..000000000 --- a/small-business/skills/job-post-builder/reference/interview-guide-structure.md +++ /dev/null @@ -1,93 +0,0 @@ -# Interview Guide Structure - -This reference covers how to build the interview guide and scoring rubric. -A good guide reduces bias, improves consistency, and makes debrief conversations -sharper because everyone evaluated the same things the same way. - ---- - -## Recommended Document Structure - -### Section 1: Role Summary -One paragraph. Remind interviewers what we're hiring for and why. -Include the stage of the process this guide covers (phone screen, full loop, etc.) - -### Section 2: Interview Stage Map -A simple table showing who interviews the candidate at each stage and what -competency each stage is assessing. This avoids interviewers asking the same -questions and lets them compare notes on different dimensions. - -| Stage | Interviewer(s) | Competencies Assessed | -|---|---|---| -| Phone screen | Recruiter | Communication, baseline fit | -| Hiring manager interview | HM | Role-specific scope, leadership | -| Peer interview | Team member | Collaboration, working style | -| Skills/case interview | Senior IC | Technical depth, problem-solving | - -### Section 3: Competency Question Bank -For each competency, include 4–6 behavioral questions and 2–3 follow-up probes. - -**Format:** - -#### [Competency Name] -*What we're evaluating:* [1-sentence description of what good looks like] - -**Questions:** -1. Tell me about a time you [specific situation relevant to this competency]... -2. Describe a moment when you had to [challenge]... -3. Walk me through how you [process or decision relevant to the role]... - -**Follow-up probes (use any of these to go deeper):** -- What was the outcome? -- What would you do differently? -- Who else was involved and what was your specific role? -- What was the hardest part? - -**Typical competency areas to cover (adapt to the role):** -- Communication & stakeholder management -- Problem-solving & analytical thinking -- Ownership & accountability -- Collaboration & influence -- Domain/technical skills -- Adaptability & learning - -### Section 4: Scoring Rubric -For each competency, define what a 1, 3, and 5 look like. -This gives interviewers a shared frame of reference and prevents grade inflation. - -| Score | Label | What it means | -|---|---|---| -| 5 | Exceptional | Exceeds bar; would be a top 10% hire for this competency | -| 4 | Strong | Clearly meets bar; evidence is specific and compelling | -| 3 | Meets bar | Adequate evidence; some gaps but nothing disqualifying | -| 2 | Below bar | Gaps are significant; would need close management in this area | -| 1 | Does not meet bar | Clear deficiency; would be a blocker for this role | - -Write out the 1/3/5 behavioral anchors for each competency so interviewers -aren't just using their gut. - -**Example — Ownership & Accountability:** -- **5:** Proactively identified a problem no one asked them to solve; drove it - to resolution and documented learnings for the team. -- **3:** Followed through on assigned work reliably; flagged risks early but - didn't typically expand scope independently. -- **1:** Waited for direction; examples were vague about their personal - contribution vs. the team's contribution. - -### Section 5: Debrief Guide -A short set of instructions for running the post-interview debrief: -- Each interviewer shares their scores before discussion begins (no anchoring) -- Focus debrief time on competencies where scores diverged -- Identify any disqualifying signals separately from overall score -- Decision framework: "Would we be excited to have this person on the team?" - not just "Did they clear the bar?" - ---- - -## Question Writing Tips - -- Behavioral questions ("Tell me about a time...") surface real evidence, not hypotheticals -- Situational questions ("What would you do if...") are fine for roles where - the candidate has no prior experience in that specific domain -- Avoid leading questions ("We value collaboration — how collaborative are you?") -- One question at a time — don't bundle two questions into one diff --git a/small-business/skills/job-post-builder/reference/job-post-structure.md b/small-business/skills/job-post-builder/reference/job-post-structure.md deleted file mode 100644 index ec03ee92d..000000000 --- a/small-business/skills/job-post-builder/reference/job-post-structure.md +++ /dev/null @@ -1,62 +0,0 @@ -# Job Post Structure Guide - -Use this structure for every job post. The goal is a posting that attracts strong, -self-aware candidates — not one that checks an HR box. - ---- - -## Recommended Structure - -### 1. Opening Hook (2–3 sentences) -Lead with the *why* — why this role exists, what problem it solves, or what -moment the company is in. This is what makes a candidate stop scrolling. - -> Bad: "We are looking for an experienced marketing manager." -> Good: "We're doubling our go-to-market team this year and need someone to own -> how we show up in enterprise accounts — from first touch through renewal." - -### 2. About the Company (3–4 sentences) -Brief, honest, specific. What does the company do, who do they serve, and why -does it matter? Avoid buzzwords. If the company has a notable milestone (funding, -growth rate, customer names), one sentence here earns trust. - -### 3. About the Role (1 paragraph) -Describe what success in this role looks like 12 months in. What will this person -have built, shipped, or changed? This grounds the responsibilities that follow. - -### 4. What You'll Do (bulleted list, 4–7 items) -Use action verbs. Start each bullet with what the person will *own*, not what -they'll *help with*. Avoid exhaustive laundry lists — prioritize the 4–7 things -that matter most. - -### 5. What We're Looking For (2 sections) -**Required:** -- Keep this tight. Each line is a filter. Ask: "Would we reject a strong candidate - who didn't have this?" If no, move it to preferred. -- Use "experience with" not "expertise in" where possible — it's less intimidating - and still accurate. - -**Preferred (nice to have):** -- Things that would make a candidate exceptional but aren't dealbreakers. - -### 6. Compensation + Benefits (if provided) -List the salary range, equity if applicable, and 3–5 standout benefits. If comp -isn't provided by the user, omit this section entirely — don't invent a range. - -### 7. How to Apply -One clear sentence. Link or email. No hoops. - ---- - -## Writing Principles - -**Inclusive language checklist:** -- Avoid "rockstar", "ninja", "guru", "hustle culture" signals -- Avoid unnecessary degree requirements if experience is a valid substitute -- Avoid gendered language -- Aim for a Flesch-Kincaid grade level of 10–12 - -**Length:** 400–700 words is the sweet spot. Under 300 feels thin; over 900 loses candidates. - -**Tone:** Match the company's voice. A startup sounds different from a regulated enterprise. -Ask the user if unsure, or infer from any existing materials you've found. diff --git a/small-business/skills/job-post-builder/reference/offer-letter-template.md b/small-business/skills/job-post-builder/reference/offer-letter-template.md deleted file mode 100644 index 3e8716853..000000000 --- a/small-business/skills/job-post-builder/reference/offer-letter-template.md +++ /dev/null @@ -1,139 +0,0 @@ -# Offer Letter Template - -Use this as the base template for the offer letter .docx file. -Replace all `[BRACKETED FIELDS]` with actual values or leave them as placeholders -for the user to fill in. Mark any placeholder clearly so it's obvious what -still needs to be completed before sending. - -> ⚠️ Legal reminder: This template requires review by qualified legal counsel -> before use. Employment law varies by jurisdiction. - ---- - -## Template - ---- - -[COMPANY LETTERHEAD / LOGO] - -[DATE] - -[CANDIDATE FULL NAME] -[CANDIDATE ADDRESS LINE 1] -[CANDIDATE ADDRESS LINE 2] -[CITY, STATE, ZIP] - -Dear [CANDIDATE FIRST NAME], - -We are thrilled to offer you the position of **[JOB TITLE]** at [COMPANY NAME]. -We were genuinely impressed by [a brief, specific, warm note about the candidate — -e.g., "your approach to the product design challenge and your thoughtful questions -about the team's roadmap"], and we believe you will be an outstanding addition to -our team. - -**Position Details** - -| | | -|---|---| -| Position Title | [JOB TITLE] | -| Department | [DEPARTMENT] | -| Reports To | [MANAGER NAME], [MANAGER TITLE] | -| Employment Type | [Full-Time / Part-Time] | -| FLSA Status | [Exempt / Non-Exempt] | -| Start Date | [PROPOSED START DATE] | -| Work Location | [OFFICE ADDRESS / Remote / Hybrid — specify days on-site if applicable] | - -**Compensation** - -Your starting base salary will be **[ANNUAL SALARY OR HOURLY RATE]**, -paid [bi-weekly / semi-monthly / monthly] in accordance with [COMPANY NAME]'s -standard payroll schedule. - -[IF APPLICABLE — EQUITY] -You will be eligible to receive a grant of **[NUMBER] [shares/options]** of -[COMPANY NAME] [common stock / stock options] at the fair market value on the -date of grant, subject to approval by the Board of Directors and the terms of -the company's equity incentive plan. Your grant will vest over [VESTING SCHEDULE, -e.g., "four years with a one-year cliff"]. - -[IF APPLICABLE — BONUS] -You will be eligible to participate in [COMPANY NAME]'s annual bonus program, -with a target bonus of **[BONUS AMOUNT OR %]** of your base salary, subject to -company and individual performance. - -**Benefits** - -You will be eligible to participate in [COMPANY NAME]'s benefits program, -which includes [list 3–5 key benefits, e.g., medical/dental/vision insurance, -401(k) with employer match, paid parental leave, etc.]. Full details will be -provided during your onboarding. - -**Conditions of Employment** - -This offer is contingent upon: -- [Successful completion of a background check — delete if not applicable] -- [Satisfactory reference checks — delete if not applicable] -- [Verification of your legal right to work in [COUNTRY/JURISDICTION]] -- Your execution of [COMPANY NAME]'s standard Confidentiality and Intellectual - Property Agreement (enclosed / provided separately) - -**Employment At-Will** -[Include or delete depending on jurisdiction and employment type] -Your employment with [COMPANY NAME] is at-will, meaning either you or the -company may terminate the employment relationship at any time, with or without -cause or advance notice. - -**Acceptance** - -To accept this offer, please sign and return this letter by **[OFFER EXPIRATION DATE]**. -We've enclosed a copy for your records. - -[DOCUSIGN ENVELOPE LINK — paste here before sending] - -We are excited about the prospect of you joining [COMPANY NAME] and look forward -to welcoming you to the team. Please don't hesitate to reach out to [HR CONTACT NAME] -at [HR CONTACT EMAIL] if you have any questions. - -Sincerely, - -[HIRING MANAGER NAME] -[HIRING MANAGER TITLE] -[COMPANY NAME] -[DATE] - ---- - -**Acceptance:** - -I, [CANDIDATE FULL NAME], accept the offer of employment described in this letter -under the terms and conditions stated above. - -Signature: _______________________________ Date: _______________ - -[CANDIDATE FULL NAME] (printed) - ---- - -*⚠️ This template requires legal review before use in any employment context. -Compensation ranges, equity terms, and at-will provisions vary by jurisdiction -and should be reviewed by qualified legal counsel.* - ---- - -## Field Reference - -| Field | Description | -|---|---| -| [COMPANY LETTERHEAD / LOGO] | Replace with actual letterhead or remove | -| [DATE] | Date the letter is signed/sent | -| [CANDIDATE FULL NAME] | Full legal name | -| [JOB TITLE] | Exact title as posted | -| [DEPARTMENT] | Team or business unit | -| [MANAGER NAME / TITLE] | Direct manager | -| [PROPOSED START DATE] | Target start date | -| [ANNUAL SALARY OR HOURLY RATE] | Confirmed comp — verify with HR | -| [EQUITY FIELDS] | Delete entire section if no equity | -| [BONUS FIELDS] | Delete entire section if no bonus | -| [OFFER EXPIRATION DATE] | Typically 3–5 business days from send | -| [HR CONTACT] | Who candidate should call with questions | -| [DOCUSIGN ENVELOPE LINK] | Paste after uploading .docx to DocuSign | diff --git a/small-business/skills/lead-triage/SKILL.md b/small-business/skills/lead-triage/SKILL.md deleted file mode 100644 index 016246d2f..000000000 --- a/small-business/skills/lead-triage/SKILL.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -name: lead-triage -version: 0.1.1 -description: > - Scores inbound HubSpot leads by engagement signals, company fit, and urgency - markers to produce a "call these 5 today" list with talking points, drafts - the follow-ups, and blocks Calendar time. Use when the user asks to - prioritize leads, who to call first, or about their pipeline. ---- - -# Lead Triage - -## Quick start - -Pull inbound leads from HubSpot, score them, and surface a ranked call list with talking points. Drafts follow-ups and proposes calendar slots — never sends or books without owner approval. - -``` -User: "prioritize my leads" -→ Pull contacts: lifecycle stage Lead or MQL, status ≠ Unqualified -→ Score each across engagement, company fit, urgency, recency -→ Return ranked list (size adapts to volume) with talking points -→ Offer to draft follow-ups and propose calendar slots -``` - -## Workflow - -1. **Pull leads from HubSpot.** Fetch contacts with `lifecyclestage` = `Lead` or `MQL` and `hs_lead_status` ≠ `Unqualified`. Use the field list in [reference/hubspot-scoring.md](reference/hubspot-scoring.md). If HubSpot is unavailable, stop: *"HubSpot is disconnected — connect it and try again."* - -2. **Clarify if trigger is ambiguous.** If the user said only "pipeline" without a qualifier, ask: *"Quick pipeline overview (deal stages + total value) or prioritized call list?"* — then route accordingly. Do not score leads on a bare "pipeline." - -3. **Score each lead.** Apply the four-dimension model in [reference/hubspot-scoring.md](reference/hubspot-scoring.md): - - **Engagement** — email replies, opens, site visits in HubSpot (last 30 days only) - - **Company fit** — industry and employee count vs. owner's ICP (default: any industry, 1–50 employees) - - **Urgency** — lead age, stage duration, notes containing "urgent / ASAP / deadline / budget approved" - - **Recency penalty** — subtract points if last activity was <24 hours ago (already touched today) - -4. **Build the ranked list.** Sort descending by composite score. Adapt list size to volume: - - ≤10 leads → show all - - 11–30 leads → show top 5 - - >30 leads → show top 8 - - For each lead: name, company, score, one-paragraph talking point, last activity summary. If engagement signals are all >30 days old, flag: *"Engagement signals are stale — approach as cold outreach."* - -5. **Offer follow-up drafts.** Ask: *"Draft follow-ups for any of these?"* If yes, write one email per selected lead, matching the tone of their last outbound thread in Mail. Show draft; do not send. - -6. **Offer calendar slots.** Ask: *"Propose call slots for any of these?"* If yes, check Calendar for open 30-minute windows in the next two business days (avoid slots with existing events ±15 min). Propose two options per lead. Do not create events — the owner books. - -## Approval gates - -- **Never send an email.** Draft only; owner sends from their inbox. -- **Never create calendar events.** Propose times; owner books. -- **Never change lifecycle stage or mark a lead Unqualified** unless the owner explicitly asks. -- **Never include `Customer` or `Evangelist` lifecycle contacts** in the lead list. -- **If zero leads match the filter**, explain why and offer to check what lifecycle stages are in use — do not fabricate a list. - -## Reference - -- [reference/hubspot-scoring.md](reference/hubspot-scoring.md) — HubSpot field names, scoring weights, ICP defaults -- [reference/gotchas.md](reference/gotchas.md) — edge cases: stale data, zero leads, pipeline disambiguation, customer contamination -- [reference/examples/happy-path-triage.md](reference/examples/happy-path-triage.md) — worked output for a 7-lead list with draft and slot proposal diff --git a/small-business/skills/lead-triage/reference/examples/happy-path-triage.md b/small-business/skills/lead-triage/reference/examples/happy-path-triage.md deleted file mode 100644 index 41a558014..000000000 --- a/small-business/skills/lead-triage/reference/examples/happy-path-triage.md +++ /dev/null @@ -1,68 +0,0 @@ -# Example: Happy-path triage — 7-lead list - -7 leads → show all (≤10 rule). Owner ICP: SaaS, 10–50 employees. - ---- - -## Ranked output - -``` -Here are your 7 leads, ranked by priority: - -───────────────────────────────────── -1. Sarah Chen · Acme SaaS · Score: 78 - Last activity: 2 days ago (email reply) - Sarah replied asking about API limits — evaluating for a 22-person team. - Strong ICP fit. Lead is 12 days old (prime window). Open with her API - question; offer a 20-min demo to walk through limits live. - -2. Marcus Webb · Loop Analytics · Score: 64 - Last activity: 5 days ago (site visit) - Visited pricing page twice this week, no reply to outreach. 31 employees, - SaaS — good fit. Try a softer touch: share a case study instead of another - demo ask. - -3. Priya Nair · BuildFast · Score: 51 - Last activity: 9 days ago (email open) - Opened the intro email, no reply. 18 days old — approaching stale. One - more value-add touch (ROI one-pager) before deprioritizing. - -[4–7 follow same format, scores 30–45] -───────────────────────────────────── - -Draft follow-ups for any of these? (e.g., "draft for 1 and 2") -Propose call slots? (e.g., "find times for Sarah and Marcus") -``` - ---- - -## Follow-up draft — Sarah Chen - -``` -Subject: Re: API limits question - -Hi Sarah, - -Happy to answer the API limits question properly on a short call rather -than over email. - -[Owner adds availability after booking] - -Would that work? - -[Owner name] -``` -Draft shown. Not sent. - ---- - -## Calendar proposal — Sarah Chen - -``` -Open 30-min slots (next 2 business days): - • Thu Apr 25 · 10:00–10:30 AM - • Thu Apr 25 · 2:00–2:30 PM - • Fri Apr 26 · 9:00–9:30 AM - -No events created — pick one and book it directly. -``` diff --git a/small-business/skills/lead-triage/reference/gotchas.md b/small-business/skills/lead-triage/reference/gotchas.md deleted file mode 100644 index fa1ce6d09..000000000 --- a/small-business/skills/lead-triage/reference/gotchas.md +++ /dev/null @@ -1,76 +0,0 @@ -# Gotchas — lead-triage - ---- - -## Gotcha: "Pipeline" bare trigger runs full scoring when user just wants a status check - -**Why it matters:** "Pipeline" alone is ambiguous — the owner may want deal-stage totals, not a scored call list. - -### ✗ Bad -``` -User: "how's my pipeline?" -Claude: [runs full scoring, returns 12-lead ranked list] -``` - -### ✓ Good -``` -User: "how's my pipeline?" -Claude: "Quick pipeline overview (deal stages + total value) or prioritized - call list for today?" -``` - ---- - -## Gotcha: Stale engagement data inflates scores - -**Why it matters:** `hs_email_open` is cumulative — opens from a year-old campaign make a cold lead look hot. - -### ✗ Bad -``` -Lead has 20 opens (all 11 months ago). Scores 25/25 on engagement. -Appears as #1. Owner calls; lead has no memory of the brand. -``` - -### ✓ Good -``` -Cap engagement signals at 30 days. If all signals are older than 30 days, -engagement score = 0 and talking point notes: -"Engagement signals are stale (last: [date]) — approach as cold outreach." -``` - ---- - -## Gotcha: Customers appear in the lead list - -**Why it matters:** Calling a `Customer` or `Evangelist` as a lead prospect is embarrassing. - -### ✗ Bad -``` -Lifecycle filter not applied → existing customer appears as #2 on the list. -``` - -### ✓ Good -``` -Filter strictly: lifecyclestage = Lead or MQL only. -If a contact has a blank lifecycle stage, include with a warning flag: -"⚠ Lifecycle stage not set — confirm this is a lead before calling." -``` - ---- - -## Gotcha: Proposing calendar slots that conflict with existing events - -**Why it matters:** Proposing a time the owner is already booked erodes trust immediately. - -### ✗ Bad -``` -Claude proposes "Tuesday 2–2:30 PM" without checking Calendar. -Owner already has a client call in that slot. -``` - -### ✓ Good -``` -Fetch Calendar for next two business days before proposing any slot. -Only propose windows with no existing events ±15 minutes buffer. -If no free window exists, say so and offer to look further out. -``` diff --git a/small-business/skills/lead-triage/reference/hubspot-scoring.md b/small-business/skills/lead-triage/reference/hubspot-scoring.md deleted file mode 100644 index 4b9eed1fa..000000000 --- a/small-business/skills/lead-triage/reference/hubspot-scoring.md +++ /dev/null @@ -1,74 +0,0 @@ -# HubSpot Scoring — lead-triage - -Field names, scoring weights, and ICP defaults. - ---- - -## Fields to pull - -| HubSpot field | Used for | -|---|---| -| `firstname`, `lastname` | Display | -| `company` | Display + ICP match | -| `email` | Follow-up draft recipient | -| `lifecyclestage` | Filter (keep Lead, MQL) | -| `hs_lead_status` | Filter (exclude Unqualified) | -| `industry` | Company fit | -| `numemployees` | Company fit — employee count on contact record. Often null; if null, treat as unknown and score accordingly. | -| `createdate` | Urgency — lead age | -| `hs_last_activity_date` | Recency penalty | -| `notes_last_updated` | Urgency — note recency | -| `hs_sales_email_last_replied` | Engagement — reply signal | -| `hs_email_open` | Engagement — open count (use only if within 30 days) | -| `hs_analytics_last_visit_timestamp` | Engagement — site visit | -| `num_contacted_notes` | Engagement — outreach volume | - ---- - -## Scoring model (0–100 composite) - -Four dimensions, each 0–25. Sum for composite. - -### Engagement (0–25) -Only count signals from the last 30 days. Older signals score 0. - -| Signal | Points | -|---|---| -| Email reply in last 14 days | +15 | -| Email open in last 7 days (no reply) | +8 | -| Site visit in last 7 days | +5 | -| >3 outreach attempts, no reply | −5 | - -### Company fit (0–25) -Default ICP if owner hasn't stated one: any industry, 1–50 employees. - -| Match | Points | -|---|---| -| Industry + size both match ICP | 25 | -| Size matches, industry unknown | 15 | -| Industry matches, size unknown | 12 | -| Neither matches or both unknown | 5 | - -### Urgency (0–25) - -| Signal | Points | -|---|---| -| Note contains "urgent," "ASAP," "deadline," "budget approved" | +15 | -| Lead age 7–21 days (prime follow-up window) | +10 | -| Lead age <7 days | +5 | -| Lead age >60 days | −5 | - -### Recency penalty (subtracted from composite) - -| Last activity | Subtract | -|---|---| -| <24 hours ago | −25 | -| 1–3 days ago | −10 | -| 4–7 days ago | −5 | -| >7 days ago | 0 | - ---- - -## Custom ICP (runtime override) - -If the owner states an ICP at runtime ("focus on SaaS, 10–100 employees"), apply it for that session only. diff --git a/small-business/skills/margin-analyzer/SKILL.md b/small-business/skills/margin-analyzer/SKILL.md deleted file mode 100644 index 4faecb30c..000000000 --- a/small-business/skills/margin-analyzer/SKILL.md +++ /dev/null @@ -1,165 +0,0 @@ ---- -name: margin-analyzer -description: > - Analyzes unit economics by product or service using PayPal merchant - insights and QuickBooks cost data, benchmarks against inflation and cost - changes, and shows pricing-scenario data (e.g. "a 5% increase historically - correlates with ~3% volume drop"). Surfaces analysis only — does not - recommend a price. Use when the user asks about raising prices, pricing, - margin analysis, what to charge, whether costs are eating into profit, or - how a price change might affect their business. Trigger even if the user - doesn't say "margin" explicitly — phrases like "am I making enough?", - "should I charge more?", or "my costs are going up" all call for this skill. ---- - -# Margin Analyzer - -> **Status:** MVP draft · **Owner:** JJ · **Version:** 1.1.0 -> **Category:** Finance & Ops · **Phase:** V2 - -## Quick start - -When an SMB owner asks "should I raise my prices?" or "are my margins okay?", this skill: - -1. **Identifies what to analyze** — which products/services are in scope -2. **Pulls cost data** from QuickBooks (COGS, direct expenses) -3. **Pulls revenue data** from PayPal or Square (transaction history) -4. **Computes unit economics** — revenue, COGS, gross margin, margin % per item -5. **Benchmarks against context** — inflation, cost changes, industry norms if available -6. **Builds pricing scenarios** — shows what happens to revenue and margin at +5%, +10%, +15% price changes, using historical correlation where data allows -7. **Presents the analysis** — no price recommendation; the owner decides - -The output equips the owner to make their own pricing call with real data behind it. - ---- - -## Workflow - -### Step 1: Pre-flight check - -**QuickBooks:** Call `company-info` to verify the industry field is populated. If it's missing or "Unknown", ask: "I need your business category to pull relevant benchmarks. What industry are you in?" Then call `quickbooks-profile-info-update`. - -**PayPal:** No pre-flight needed, but PayPal rate-limits on rapid calls — see `reference/gotchas.md`. - -**No connectors:** Offer CSV upload as a fallback. The skill can work from exported transaction and expense data. The expected CSV schema is in `reference/csv-schema.md`. - -### Step 2: Clarify scope - -Ask the owner two questions: - -1. **"Which products or services do you want to analyze?"** - - All of them, or a specific subset? - - If they say "all," confirm the connector has enough data to be meaningful before pulling everything. - -2. **"What metric matters most to you?"** - - Gross margin (revenue minus direct costs)? - - Net margin (after all expenses)? - - Revenue per unit? - - Their answer shapes how you present the output. - -### Step 3: Pull cost data (QuickBooks) - -Fetch from QuickBooks using `profit-loss-quickbooks-account`: -- **Date range:** Last 12 months (or full history if less is available) -- **Extract:** Cost of goods sold by product/service line, direct expenses - -If QuickBooks isn't connected, ask the owner for: -- A cost breakdown by product/service line (materials, labor, direct delivery costs per item) -- Any known cost changes in the last 6–12 months - -If QuickBooks is connected but COGS = $0 across all periods, do not use $0 as the cost input. Surface this to the owner: - -> "QuickBooks shows no cost of goods sold recorded for this period. To compute meaningful margins, I need a cost breakdown by product or service line — not a single average for the whole business. For each item you want analyzed, what does it cost you to deliver it? Materials, direct labor, any direct expenses per item. Even rough figures work." - -Flag this limitation in the Data Quality Notes section of the final output. - -### Step 4: Pull revenue data (PayPal / Square) - -Fetch from `list_transactions` (PayPal) or `make_api_request` (Square): -- **Date range:** Match the cost data window (last 12 months) -- **Extract:** Transaction amount, item/service name, date, quantity if available - -If you hit PayPal rate limits, pause 30 seconds and retry once. If still blocked, offer: "PayPal is temporarily rate-limited. Want to switch to Square or upload a CSV instead?" - -If only one data source is available, note the limitation in the output. - -### Step 5: Compute unit economics - -For each product/service in scope, calculate: - -| Metric | Formula | -|---|---| -| **Revenue** | Sum of transaction amounts for the item | -| **COGS** | Cost data from QB or owner-provided | -| **Gross Profit** | Revenue − COGS | -| **Gross Margin %** | (Gross Profit ÷ Revenue) × 100 | -| **Units Sold** | Count of transactions (if available) | -| **Revenue per Unit** | Revenue ÷ Units Sold | -| **Cost per Unit** | COGS ÷ Units Sold | - -Flag any item where margin is below 20% — not as a recommendation, but as a data point worth the owner's attention. - -### Step 6: Benchmark - -Layer in context to make the numbers meaningful: - -- **Inflation:** Note relevant cost trends if discussing input cost increases. Example: "Your input costs rose ~X% over this period while your prices held flat — that compressed margin by Y points." -- **Industry benchmarks:** Use the QuickBooks industry profile to surface rough gross margin norms for their category. See `reference/industry-benchmarks.md`. -- **Historical comparison:** If 24+ months of data is available, compare this year's margins to last year's to surface the trend direction. - -Handle low-data gracefully: if fewer than 6 months of transactions exist, omit the elasticity section and note: "You need at least 6 months of pricing history to estimate how volume responds to price changes. I'll show scenario math instead." - -### Step 7: Pricing scenarios - -Build a table for each product/service showing three price-change scenarios: - -| Scenario | New Price | Projected Revenue* | Gross Margin % | -|---|---|---|---| -| +5% | $X | $Y | Z% | -| +10% | $X | $Y | Z% | -| +15% | $X | $Y | Z% | - -**How to compute projected revenue:** -- **If 6+ months of history:** Estimate volume response using historical data. If a past price change exists, compute observed elasticity: `Elasticity = % change in volume ÷ % change in price`. Apply that to project volume at the new price. -- **If insufficient history:** Show three volume assumptions (−0%, −5%, −10%) and let the owner pick what seems realistic. - -Add a note: *"These are projections based on available data, not guarantees. Actual volume response depends on competition, customer sensitivity, and timing."* - -### Step 8: Present the analysis - -Structure the output as: - -Structure the output with an H2 header showing the business name and date range, -followed by four sections: a Unit Economics Summary table (product/service, -revenue, COGS, gross margin, margin %), a Context and Benchmarking section -(2-4 sentences on inflation, cost shifts, industry norms), Pricing Scenarios -(scenario table per product, or top 3-5 if many), and Data Quality Notes -(flag any limitations such as partial data, missing COGS, or short history). - -Keep it factual. Do not say "you should raise prices" or "consider lowering your price." The owner is looking at data to make their own call. - ---- - -## Scope boundary - -**This skill surfaces data. It does not recommend a price.** - -If the owner asks "so what should I do?" — respond with: "I can show you what the data suggests, but the pricing decision is yours. Would you like me to model any additional scenarios?" - -This is intentional. Pricing decisions have real business consequences and depend on context only the owner knows (competitive positioning, customer relationships, cash needs). The skill's job is to make sure they're looking at real numbers when they decide. - ---- - -## Connectors - -**Primary:** QuickBooks, PayPal -**Also supported:** Square, Brex · Desktop (CSV/export) - ---- - -## Reference files - -- `reference/gotchas.md` — common pitfalls (data gaps, elasticity traps, margin math errors) -- `reference/industry-benchmarks.md` — gross margin ranges by SMB category -- `reference/csv-schema.md` — expected columns when the owner uploads a CSV -- `reference/examples/` — worked scenarios (retail, services, product-based) diff --git a/small-business/skills/margin-analyzer/reference/csv-schema.md b/small-business/skills/margin-analyzer/reference/csv-schema.md deleted file mode 100644 index 04969582f..000000000 --- a/small-business/skills/margin-analyzer/reference/csv-schema.md +++ /dev/null @@ -1,52 +0,0 @@ -# CSV Upload Schema - -When the owner doesn't have QuickBooks or PayPal connected, they can upload exported CSV files. This document specifies what columns to expect and how to handle variations. - -## Revenue CSV (transactions export) - -Expected columns (order doesn't matter; headers are case-insensitive): - -| Column | Required | Description | -|---|---|---| -| `date` | Yes | Transaction date (any standard format: YYYY-MM-DD, MM/DD/YYYY, etc.) | -| `item` or `product` or `service` or `description` | Yes | What was sold | -| `amount` or `revenue` or `total` | Yes | Transaction amount (USD) | -| `quantity` or `qty` | No | Units sold — if missing, assume 1 per transaction | - -**Exports that typically match this format:** -- PayPal: Activity → Download (CSV) — use "Transaction ID, Date, Name, Type, Status, Currency, Amount" -- Square: Reports → Transactions → Export -- Shopify: Orders → Export - -If the export has more columns, ignore the extras. If a required column is missing, ask the owner which column maps to it. - -## Cost CSV (expense or COGS export) - -Expected columns: - -| Column | Required | Description | -|---|---|---| -| `date` | No | Expense date (useful for trend analysis) | -| `item` or `product` or `service` or `category` | Yes | What the cost relates to | -| `amount` or `cost` or `expense` | Yes | Cost amount (USD) | -| `type` | No | COGS vs. operating expense — if absent, ask the owner | - -**Exports that typically match this format:** -- QuickBooks: Reports → Profit & Loss Detail → Export -- Brex: Transactions → Export → Filter by expense category - -## Handling messy CSVs - -Real-world exports are messy. Common issues: - -- **Extra header rows:** Skip rows until you find one that looks like column names -- **Currency symbols:** Strip `$`, `,` from numeric fields before parsing -- **Negative refunds:** Include them — they reduce net revenue -- **Mixed currencies:** Flag it and ask which currency to use; default to USD if unclear -- **"Gross" vs "Net" amounts:** Prefer net (after fees) for revenue; ask if unclear - -## After loading - -Confirm the data shape with the owner before proceeding: -- "I loaded X transactions from [date] to [date] across Y products. Does that look right?" -- If the date range or product count looks off, ask them to double-check the export filters. diff --git a/small-business/skills/margin-analyzer/reference/examples/retail-boutique.md b/small-business/skills/margin-analyzer/reference/examples/retail-boutique.md deleted file mode 100644 index 8fe92a03e..000000000 --- a/small-business/skills/margin-analyzer/reference/examples/retail-boutique.md +++ /dev/null @@ -1,86 +0,0 @@ -# Example: Retail Boutique — Apparel - -**Business:** Small women's clothing boutique, brick-and-mortar + Shopify -**Connectors:** QuickBooks (costs), PayPal (online sales) -**Data:** 14 months of transactions - ---- - -## What the owner asked - -"My wholesale costs have gone up a lot this year. I feel like I need to raise prices but I don't want to lose customers. Can you look at my margins?" - ---- - -## Step 1: Pre-flight - -`company-info` returns Industry: "Retail — Apparel". Pre-flight passes. - ---- - -## Step 2: Scope clarification - -Owner wants to analyze her top 5 SKU categories: -- Dresses -- Tops -- Denim -- Accessories -- Knitwear - -Metric priority: gross margin % (she wants to understand profitability, not just revenue). - ---- - -## Step 3–4: Data pulled - -- **QuickBooks:** 14 months of COGS by product category -- **PayPal:** 14 months of transaction history (online sales only; in-store via Square separately) - ---- - -## Step 5: Unit economics output - -| Category | Revenue | COGS | Gross Profit | Margin % | -|---|---|---|---|---| -| Dresses | $42,800 | $18,200 | $24,600 | 57.5% | -| Tops | $31,500 | $15,100 | $16,400 | 52.1% | -| Denim | $18,900 | $11,300 | $7,600 | 40.2% | -| Accessories | $9,400 | $2,800 | $6,600 | 70.2% | -| Knitwear | $14,200 | $9,600 | $4,600 | 32.4% ⚠️ | - -⚠️ Knitwear is flagged: 32.4% is below the 40–55% typical range for apparel retail. - ---- - -## Step 6: Benchmarking - -"For apparel retail, typical gross margins run 45–65%. Your portfolio average is 51%, which is within range. However, Knitwear at 32.4% is below the floor — this could indicate that wholesale costs for knitwear rose faster than your prices over the past year. Your overall cost base rose approximately 12% year over year, while revenue grew 7% — that 5-point gap is where the margin pressure is coming from." - ---- - -## Step 7: Pricing scenarios — Knitwear (low-margin item) - -Current average Knitwear price: $89. Current cost: ~$61. - -| Scenario | New Price | Est. Revenue* | Gross Margin % | -|---|---|---|---| -| +5% ($93) | $93 | ~$14,560 (−3% vol) | 34.4% | -| +10% ($98) | $98 | ~$14,130 (−6% vol) | 37.8% | -| +15% ($102) | $102 | ~$13,700 (−8% vol) | 40.2% | - -*Volume estimates based on 14-month elasticity: historical data shows ~0.6 volume drop per 1% price increase for this category. - -Note: "These projections use your 14-month history as a guide. Actual response depends on your customers and what competitors are charging for similar items." - ---- - -## Step 8: What was presented - -The owner received the full unit economics table, the benchmarking paragraph, and the knitwear scenario table. She noted that Accessories was the standout performer (70% margin). The analysis did not recommend a course of action — it surfaced that knitwear was the category most worth evaluating for a price adjustment. - ---- - -## Notes for skill author - -- This example shows graceful handling of mixed data sources (PayPal online + Square in-store noted as limitation) -- Elasticity was computable because the owner had raised Knitwear prices once 8 months ago (from $79 → $89) and volume dipped 5% the following month — that's the one-data-point limitation referenced in gotchas.md diff --git a/small-business/skills/margin-analyzer/reference/examples/service-business.md b/small-business/skills/margin-analyzer/reference/examples/service-business.md deleted file mode 100644 index b3fb554a5..000000000 --- a/small-business/skills/margin-analyzer/reference/examples/service-business.md +++ /dev/null @@ -1,73 +0,0 @@ -# Example: Professional Services — Marketing Consultant - -**Business:** Solo marketing consultant, project-based engagements -**Connectors:** QuickBooks (invoices + expenses), PayPal (payment collection) -**Data:** 9 months of transactions - ---- - -## What the owner asked - -"I feel like I'm working more but not making more money. Can you look at whether I'm charging enough for each of my services?" - ---- - -## Step 2: Scope clarification - -Owner offers three service types: -- Brand strategy (fixed-fee, $2,500/project) -- Monthly retainer (ongoing, $1,200/month) -- Ad campaign management (% of spend, variable) - -Metric priority: revenue per hour (she wants to know where her time is best spent). - -Note: Revenue per hour requires the owner to provide estimated hours. Ask: "For each service type, roughly how many hours does a typical engagement take?" - -Owner estimates: -- Brand strategy: ~20 hours -- Monthly retainer: ~8 hours/month -- Ad management: ~6 hours/month - ---- - -## Step 5: Unit economics output - -| Service | Revenue (9 mo) | COGS* | Gross Profit | Margin % | Rev/Hour | -|---|---|---|---|---|---| -| Brand strategy | $17,500 (7 projects) | $1,400 (tools, contractors) | $16,100 | 92% | $125/hr | -| Retainer | $21,600 (20 months) | $900 (tools) | $20,700 | 96% | $150/hr | -| Ad management | $14,200 | $600 | $13,600 | 96% | ~$118/hr | - -*COGS here is direct expenses (software tools, occasional contractor help) — owner's own labor is excluded from COGS per accounting convention but captured in the Rev/Hour column. - ---- - -## Step 6: Benchmarking - -"For professional services, gross margins of 60–80% are typical. Your margins are 92–96%, which reflects a low direct cost structure. The more meaningful question is revenue per hour: at $118–$150/hr, you're in a solid range for independent marketing consultants. However, if your effective hourly rate (after all business expenses, not just COGS) is lower, the picture changes. To get that number, divide your net income by total hours worked." - ---- - -## Step 7: Pricing scenarios — Brand Strategy (lowest revenue/hour) - -Current rate: $2,500/project. Owner's estimate: 20 hours average. - -| Scenario | New Rate | Est. Projects* | Revenue | Rev/Hour | -|---|---|---|---|---| -| +10% ($2,750) | $2,750 | ~6.5 (−7% vol) | $17,875 | $138/hr | -| +20% ($3,000) | $3,000 | ~6 (−14% vol) | $18,000 | $150/hr | -| +30% ($3,250) | $3,250 | ~5.5 (−21% vol) | $17,875 | $159/hr | - -*Volume estimates are rough — only 7 brand strategy projects in 9 months is a small sample. These numbers should be treated as directional, not precise. - -"If the 9-month pattern holds, a 20–30% rate increase on brand strategy projects might generate similar or slightly higher revenue with fewer projects — freeing up hours you could use for retainers (your highest-margin service)." - -Note: This surfaces data, not a recommendation. The owner decides. - ---- - -## Notes for skill author - -- Service businesses often have near-100% gross margins on paper because they have minimal direct costs — the meaningful metric is revenue per hour or revenue per engagement -- Always ask for estimated hours before computing Rev/Hour; don't assume -- With only 7 brand strategy projects in 9 months, the sample is small — call that out explicitly diff --git a/small-business/skills/margin-analyzer/reference/gotchas.md b/small-business/skills/margin-analyzer/reference/gotchas.md deleted file mode 100644 index 22c41ab8a..000000000 --- a/small-business/skills/margin-analyzer/reference/gotchas.md +++ /dev/null @@ -1,97 +0,0 @@ -# Gotchas - -## Gotcha: Treating revenue as profit - -An owner sees $50K in PayPal transactions and thinks that's what they made. It isn't — it's what they collected. - -**Why it matters:** If you surface revenue figures without immediately pairing them with costs, the owner may misread the analysis and feel reassured when they shouldn't be. - -### ✗ Bad -"Your PayPal revenue last quarter was $50,000." - -### ✓ Good -"Your PayPal revenue last quarter was $50,000. After direct costs of $31,000, your gross profit was $19,000 — a 38% gross margin." - ---- - -## Gotcha: Using list price instead of effective price - -Owners often have discounts, refunds, and promotions that reduce what they actually receive per transaction. PayPal transaction data reflects actual collected amounts, but QuickBooks invoices may show list price. - -**Why it matters:** If you compute margins using list price but PayPal shows actual collections, your cost-per-unit math will look better than reality. - -### ✗ Bad -Use invoice amounts from QB for revenue and PayPal costs for COGS → margin appears inflated. - -### ✓ Good -Use PayPal/Square transaction amounts as the revenue source (actual collected), and QB for costs. Note any discrepancy between QB invoice totals and payment totals — it's worth surfacing. - ---- - -## Gotcha: Elasticity from a single price change - -A business raised prices once, volume dipped for a month, then rebounded. Declaring that as "a 5% increase causes 3% volume loss" is overfit to one event. - -**Why it matters:** One data point isn't a pattern. Seasonal dips, external events, or marketing changes may have caused the volume move, not the price change. - -### ✗ Bad -"In March 2024, you raised prices 8% and volume fell 4%. Elasticity = −0.5." - -### ✓ Good -"In March 2024, you raised prices 8% and the following month showed a 4% volume drop. Note: this is a single observation — the actual relationship between price and demand likely varies. I'll use this as a rough guide and show a range of scenarios." - ---- - -## Gotcha: Ignoring service delivery costs for service businesses - -For product businesses, COGS is usually clear (materials, manufacturing). For service businesses, owners often undercount their real cost — especially their own labor. - -**Why it matters:** A service business can show 80% gross margin on paper while the owner is effectively paying themselves nothing after accounting for time. - -### ✗ Bad -A freelance designer reports $0 COGS because they have no physical materials. Gross margin shows 100%. - -### ✓ Good -Ask service businesses: "For this service, what does it cost you in time and any direct expenses to deliver it? Including your own labor at a rough hourly rate?" Use that as COGS for the analysis. - ---- - -## Gotcha: QuickBooks COGS not broken down by product/service - -Many small businesses use QuickBooks but record COGS as a single line item, not broken out by product. `profit-loss-quickbooks-account` may not return item-level cost data. - -**Why it matters:** You can't compute per-product margins if COGS is lumped together. - -### ✗ Bad -Call `profit-loss-quickbooks-account` → Get total COGS $22,000 → Try to divide across 12 products → Numbers are meaningless. - -### ✓ Good -If QB doesn't have item-level COGS, ask the owner: "QuickBooks has your total costs but not a breakdown by product. Do you have a rough sense of what each item costs you to make or deliver? Even ballpark figures work." Proceed with owner-provided figures and flag the limitation in the output. - ---- - -## Gotcha: PayPal rate-limiting on repeated calls - -Rapid repeated calls to `list_transactions` (e.g., iterating through multiple date ranges) can trigger PayPal's rate limiter. - -**Why it matters:** Without a retry strategy, the skill fails mid-analysis. - -### ✗ Bad -Call list_transactions in a loop → 429 error → skill crashes with no data. - -### ✓ Good -Call `list_transactions` → if 429, pause 30 seconds → retry once → if the retry succeeds, continue normally, but treat any *second* 429 in the same session as a signal to stop retrying. After a second rate-limit event (even if separated by a successful call), immediately surface the fallback: "PayPal is rate-limiting repeated calls in this session. I can switch to Square for the revenue data, or you can upload a PayPal CSV export — either works. What would you prefer?" Do not attempt a third retry. - ---- - -## Gotcha: Presenting scenarios as forecasts - -The pricing scenario tables are math, not predictions. Volume elasticity is estimated from limited data, and real-world responses depend on competition, customer sensitivity, and timing. - -**Why it matters:** An owner might act on the table as if it's a forecast, then feel misled when actual results differ. - -### ✗ Bad -"If you raise prices 10%, you'll make $55,000 next quarter." - -### ✓ Good -"If you raise prices 10% and volume drops ~5% (based on available history), revenue would be approximately $53,000. This is a rough projection — actual results will depend on your specific customers and competitive environment." diff --git a/small-business/skills/margin-analyzer/reference/industry-benchmarks.md b/small-business/skills/margin-analyzer/reference/industry-benchmarks.md deleted file mode 100644 index df0802b27..000000000 --- a/small-business/skills/margin-analyzer/reference/industry-benchmarks.md +++ /dev/null @@ -1,34 +0,0 @@ -# Industry Gross Margin Benchmarks - -Use these as context when explaining whether an SMB owner's margins are typical, above average, or concerning. These are rough ranges based on industry averages — not targets the owner must hit. - -Always frame benchmarks as context, not judgment: "For your industry, gross margins typically run 40–55%. You're at 38%, which is slightly below average — here's what that means for your pricing scenarios." - -## Benchmarks by category - -| Category | Typical Gross Margin | Notes | -|---|---|---| -| **Retail — General** | 40–55% | Varies widely by product category | -| **Retail — Apparel / Fashion** | 45–65% | Higher for brands, lower for resellers | -| **Retail — Food & Grocery** | 20–35% | Thin margins; volume-dependent | -| **E-commerce** | 30–50% | Depends on fulfillment costs | -| **Restaurant / Food Service** | 60–70% | Gross margin on food; net is much lower after labor | -| **Professional Services** | 60–80% | Consulting, legal, accounting, design | -| **Skilled Trades** | 35–55% | Plumbing, electrical, HVAC; materials-heavy | -| **Cleaning / Maintenance Services** | 40–60% | Labor-intensive | -| **Health & Wellness** | 50–70% | Fitness studios, massage, coaching | -| **SaaS / Software** | 70–85% | Software delivery cost is low; high gross margins are expected | -| **Wholesale / Distribution** | 20–35% | Low margins; depends on volume and terms | -| **Manufacturing** | 25–45% | Varies by product complexity | -| **Construction** | 20–35% | Project-based; materials-heavy | - -## How to use these - -1. **Match the owner's industry** using the `company-info` profile from QuickBooks, or ask directly if it's unclear. -2. **State the range, not a single number.** Margins vary within categories. -3. **Flag when margins are well below the floor.** Under 20% gross margin in most service categories usually means the owner is underpricing or missing cost items. -4. **Don't cite a specific source.** These are general industry knowledge, not live data feeds. - -## When benchmarks don't fit - -Some SMBs run hybrid models (e.g., a yoga studio that also sells retail apparel). In those cases, segment the analysis if possible, or note: "Your business spans multiple categories — I'll use the benchmarks for each revenue stream separately." diff --git a/small-business/skills/monday-brief/SKILL.md b/small-business/skills/monday-brief/SKILL.md deleted file mode 100644 index 317756e14..000000000 --- a/small-business/skills/monday-brief/SKILL.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -name: monday-brief -description: Generates a one-page Monday morning briefing — cash, sales, pipeline, week ahead, top three to-dos. Accepts optional post destination and save-to arguments. -allowed-tools: Read, WebFetch, Bash ---- - -Run the Monday Morning Briefing. Pull from every connector that's live, gracefully degrade when one isn't, and deliver a one-page brief the owner can read in under two minutes. - -Parse arguments: -- `--post` (default `none`) — post the brief summary to `slack`, `teams`, or `none` -- `--save-to` (default `files`) — `files` (Google Drive / OneDrive), `desktop` (local), or `both` - -## Step 1 — Run business-pulse - -Trigger the `business-pulse` skill workflow. It pulls in this order, scoping to whatever is connected: - -1. **Cash** — QuickBooks balance + last 7 days of net flow -2. **Sales trend** — PayPal/Square last 7 days vs. prior 7 days, % change, top SKU -3. **Pipeline** — HubSpot deals moved, deals stalled (>14 days no activity), new inbound leads -4. **This week's commitments** — Calendar events with external attendees, deliverable deadlines -5. **Watch-list** — unread Gmail flagged "needs reply," Slack DMs awaiting response -6. **The 3 things** — the three highest-leverage actions for today, ranked - -If a connector is missing, note it in the brief ("PayPal not connected — sales trend skipped") rather than failing. - -## Step 2 — Format the one-page brief - -Layout (markdown, fits on one screen): - -``` -# Monday Brief — {Mon DD, YYYY} - -## Cash -{$X balance · {+/-}$Y net last 7 days · runway note} - -## Sales (last 7d vs prior 7d) -{$X total · {+/-}Z% · top SKU: {name} ({$})} - -## Pipeline -{N deals moved · M stalled · K new leads} - -## Week ahead -- {Tue 10am} — {Customer X discovery call} -- {Thu EOD} — {Proposal due to Y} -- ... - -## Three things that need you today -1. {Highest-leverage action with one-line why} -2. {...} -3. {...} -``` - -## Step 3 — Save and (optionally) post - -1. Save the brief to the chosen `--save-to` location: - - `files` — Google Drive or OneDrive root, filename `monday-brief-YYYY-MM-DD.md` - - `desktop` — `~/Desktop/monday-brief-YYYY-MM-DD.md` - - `both` — both locations -2. If `--post slack` or `--post teams`, post the **Three things** section only (not the full brief — keep the channel post short) and link to the saved file. -3. Show the full brief in chat regardless of save target. - -## Approval gates - -- **Saving the file is auto.** No approval needed — it's the owner's own drive. -- **Posting to Slack/Teams requires confirmation.** Show the post draft and wait for "post it" before publishing. -- **Never post if the brief surfaces unflattering numbers** (significant cash drop, deal slipping) without explicitly asking the owner — the channel may have non-leadership members. - -## Cadence note - -This command is designed to run weekly. The owner may schedule it via Cowork's task scheduler — when run on Monday at 7am ET, the output goes straight to their drive and (if configured) Slack/Teams DM channel. diff --git a/small-business/skills/month-end-prep/SKILL.md b/small-business/skills/month-end-prep/SKILL.md deleted file mode 100644 index c60034757..000000000 --- a/small-business/skills/month-end-prep/SKILL.md +++ /dev/null @@ -1,179 +0,0 @@ ---- -name: month-end-prep -description: > - Walks an SMB owner through month-end close: reconciles QuickBooks against - PayPal (and Square/Stripe) settlements, flags uncategorized transactions, - suspicious duplicates, and missing receipts, then writes a plain-English - P&L narrative and exports a close packet (xlsx + one-page PDF). Use when - the user says "close the month," "month-end," "reconcile," "what's missing," - "P&L," or asks why revenue or margin changed this month. ---- - -# Month End Prep - -## Quick start - -Connect QuickBooks and at least one payment processor (PayPal, Square, or Stripe), -then say "let's close the month." Claude walks you through each step of the checklist, -pausing for your input at each gate before moving forward. - -If a connector is missing, Claude falls back to asking for a CSV export — it won't -silently skip a step. - -## Workflow - -Work through these steps in order. Each step has a completion state; don't advance -until the current step is settled. - -### Step 1 — Agree on the target month - -Ask the user which month to close. Default to the prior calendar month if they don't -specify. Confirm before pulling any data. - -### Step 2 — Pull QuickBooks P&L and transaction register - -Fetch: -- Profit & Loss report for the target month (revenue, COGS, gross margin, operating - expenses, net income) -- Transaction register: every income and expense line item - -Flag immediately: -- **Uncategorized transactions** — any line with category "Uncategorized" or blank -- **Ask Questions / Needs Review** — QB's own flag - -Present the count ("14 transactions need a category") and list them for the user to -classify before proceeding. Don't advance with open uncategorized items unless the -user explicitly says "skip for now." - -See [reference/quickbooks-reconcile.md](reference/quickbooks-reconcile.md) for field -mappings and API notes. - -### Step 3 — Pull payment processor settlements - -Fetch settlement reports from PayPal, Square, or Stripe — whichever are connected — -for the same calendar month. - -Match each settlement deposit against the QuickBooks bank deposit line: -- **Match** — amount and date agree within 2 days → mark as reconciled -- **Difference < $0.50** — rounding/fee; note but don't flag -- **Difference ≥ $0.50** — flag with the delta amount -- **Settlement exists, no QB deposit** — flag as "missing in QuickBooks" -- **QB deposit exists, no settlement** — flag as "deposit not in processor data" - -See [reference/paypal-settlements.md](reference/paypal-settlements.md) for settlement -report field mappings (PayPal, Square, Stripe). - -### Step 4 — Detect suspicious duplicates - -Scan the transaction register for likely duplicate charges or deposits. Flag a -transaction as a suspicious duplicate when **all three** match: -- Same amount (within $0.01) -- Same vendor or customer name -- Posted within 5 calendar days of each other - -Present flagged pairs to the user. They decide whether each is legitimate (e.g., a -recurring weekly subscription) or a real duplicate to void. - -See [reference/gotchas.md](reference/gotchas.md) for common false-positive patterns -and how to distinguish them. - -### Step 5 — Receipts check (Desktop connector) - -If the Desktop connector is available, scan the receipts folder (ask the user for the -path; default `~/Documents/Receipts`) for the target month. - -For each expense transaction in QuickBooks above $25 with no attached document: -- Check for a matching receipt file (match by amount ± $0.50 and date within 3 days) -- **Matched** → note as "receipt on file" -- **Not matched** → flag as "missing receipt" - -List missing receipts. The user can supply the file or mark as "receipt not required" -(e.g., a recurring auto-pay with no receipt). - -If Desktop connector is not available, ask the user to confirm which expenses they have -receipts for — don't silently skip this step. - -### Step 6 — Owner sign-off gate - -Present a summary before going further: - -``` -Uncategorized transactions: X of X resolved -Settlement discrepancies: X flagged, X resolved -Suspicious duplicates: X flagged, X cleared -Missing receipts: X outstanding -``` - -Ask: "Ready to write the P&L summary and export the close packet?" - -**Do not proceed to Steps 7–8 without explicit confirmation.** - -### Step 7 — Write the P&L narrative - -Write a plain-English summary of the month — the kind an owner would share with their -spouse or accountant, not a CFO memo. Aim for 150–250 words. - -Structure: -1. **Headline** — one sentence: "March came in at $X net, up/down Y% from February." -2. **Revenue** — what drove the number; name products, services, or customers if - the data shows concentration. -3. **Gross margin** — whether it held, rose, or compressed, and the main reason why. -4. **Key expenses** — any line that moved more than 10% MoM or is outside the normal - range; one sentence each. -5. **Bottom line** — net income vs. prior month; ask if they have a target to compare. -6. **Watch list** — 1–3 things to monitor next month. - -Avoid jargon; define anything that isn't plain English ("MoM" = month over month). - -See [reference/examples/pl-narrative.md](reference/examples/pl-narrative.md) for a -worked example. - -### Step 8 — Export the close packet - -Produce two files: - -**`close-packet-[YYYY-MM].xlsx`** — three sheets: -- `P&L` — the QuickBooks P&L data, formatted -- `Reconciliation` — matched and flagged transactions side by side -- `Action Items` — any outstanding flags (uncategorized, missing receipts, etc.) - -**`close-packet-[YYYY-MM]-summary.pdf`** — one page: -- Month and business name at the top -- Key figures (revenue, gross margin %, net income) -- The P&L narrative from Step 7 -- Count of open action items, if any - -Save both to the Desktop (or a path the user specifies). Confirm the file locations. - -See [reference/close-packet-format.md](reference/close-packet-format.md) for column -specs and PDF layout details. - -## Approval gates - -- **Never run reconciliation on a month that has been filed.** Confirm the books are - still open before pulling data. -- **Never void or modify a QuickBooks transaction directly.** Surface flags; the owner - makes changes in QuickBooks. -- **Always pause at Step 6** before producing outputs. Unresolved flags must be - acknowledged or explicitly skipped. - -## Graceful degradation - -| Missing connector | Fallback | -|---|---| -| QuickBooks | Ask for a QB export CSV (P&L + transaction detail) | -| Payment processor | Ask for a settlement CSV from the processor's website | -| Desktop (receipts) | Ask the user to confirm receipt status for each flagged expense | - -## Reference files - -- [reference/quickbooks-reconcile.md](reference/quickbooks-reconcile.md) — QB field - mappings, API pagination, common data issues -- [reference/paypal-settlements.md](reference/paypal-settlements.md) — settlement - report structure for PayPal, Square, and Stripe -- [reference/close-packet-format.md](reference/close-packet-format.md) — xlsx column - specs, PDF layout, file naming convention -- [reference/gotchas.md](reference/gotchas.md) — duplicate false positives, split - transactions, partial-month edge cases -- [reference/examples/pl-narrative.md](reference/examples/pl-narrative.md) — worked - P&L narrative example diff --git a/small-business/skills/month-end-prep/reference/close-packet-format.md b/small-business/skills/month-end-prep/reference/close-packet-format.md deleted file mode 100644 index 639eda22c..000000000 --- a/small-business/skills/month-end-prep/reference/close-packet-format.md +++ /dev/null @@ -1,101 +0,0 @@ -# Close Packet Format Reference - -The close packet is two files: an xlsx workbook and a one-page PDF summary. - -## File naming - -``` -close-packet-2024-03.xlsx -close-packet-2024-03-summary.pdf -``` - -Use ISO 8601 year-month (`YYYY-MM`) in the filename. Default save location is the -Desktop; use the user's preferred path if specified. - ---- - -## xlsx workbook — three sheets - -### Sheet 1: P&L - -A formatted copy of the QuickBooks P&L for the target month. Two-column layout: -**Category** and **Amount**. - -Required rows (in order): -1. Revenue subtotal -2. COGS subtotal -3. **Gross Profit** (bold) -4. **Gross Margin %** (bold, formatted as %) -5. Operating expenses by category (each on its own row) -6. Total Operating Expenses -7. **Net Income** (bold) - -Include a MoM comparison column if prior-month data is available. Format amounts as -currency (`$#,##0.00`). Negative values in red. - -### Sheet 2: Reconciliation - -Side-by-side comparison of QuickBooks deposits vs. processor settlements. - -Columns: -| Column | Source | -|---|---| -| Date (QB) | QuickBooks deposit date | -| Amount (QB) | QuickBooks deposit amount | -| Processor | PayPal / Square / Stripe | -| Date (Processor) | Processor arrival date | -| Amount (Processor) | Processor net payout | -| Delta | QB amount minus processor amount | -| Status | RECONCILED / MISSING_IN_QB / UNMATCHED_DEPOSIT / DATE_MISMATCH | - -Color-code the Status column: -- RECONCILED → green fill -- DATE_MISMATCH → yellow fill -- MISSING_IN_QB or UNMATCHED_DEPOSIT → red fill - -### Sheet 3: Action Items - -Any open flags from the checklist. Columns: -| Column | Notes | -|---|---| -| Category | Uncategorized Txn / Missing Receipt / Duplicate / Reconciliation Flag | -| Date | Transaction date | -| Amount | Dollar amount | -| Vendor / Customer | Name | -| Description | What's wrong and what to do | - -If there are no open items, show a single row: "No open action items — books are clean." - ---- - -## PDF summary — one page - -Layout (top to bottom): - -``` -[Business Name] Close Packet — [Month Year] -──────────────────────────────────────────────────────────── - -KEY FIGURES -Revenue $XX,XXX -Gross Margin XX% -Net Income $XX,XXX - -P&L SUMMARY -[150–250 word plain-English narrative from Step 7] - -ACTION ITEMS -X uncategorized transactions · X missing receipts · X open flags -[or "Books are clean — no open items." if all clear] - -──────────────────────────────────────────────────────────── -Prepared [Date] · Powered by Claude -``` - -Use a clean sans-serif font (Helvetica or equivalent). No logo required. Keep -margins ≥ 0.75 in on all sides so it prints cleanly. - -**Generating the PDF:** Use the `xlsxwriter` or `reportlab` Python library if running -a script, or instruct Claude to render the content and export via the Desktop -connector's print-to-PDF capability. The user can also print the PDF from the xlsx -P&L sheet if a script isn't available. diff --git a/small-business/skills/month-end-prep/reference/examples/pl-narrative.md b/small-business/skills/month-end-prep/reference/examples/pl-narrative.md deleted file mode 100644 index 9a1f8cf60..000000000 --- a/small-business/skills/month-end-prep/reference/examples/pl-narrative.md +++ /dev/null @@ -1,52 +0,0 @@ -# P&L Narrative — Worked Example - -## Scenario - -**Business:** Cascade Candle Co. — small DTC candle maker, primarily Shopify + -occasional local markets. - -**Month:** March 2024 - -**Key figures:** -- Revenue: $18,400 (Feb: $15,200) → +21% MoM -- COGS: $7,360 (Feb: $5,776) → gross margin 60% (Feb: 62%) -- Net income: $4,150 (Feb: $3,100) → +34% MoM - -**Drivers:** -- Spring collection launched March 8 — strong first two weeks -- Beeswax costs rose ~8% MoM from a new supplier -- Shopify fees higher due to volume; otherwise expenses flat - ---- - -## Example narrative - -> **March came in at $4,150 net — your best month yet, up 34% from February.** -> -> Revenue hit $18,400, driven almost entirely by the Spring Collection launch on -> March 8. The Lavender + Sage three-pack was your top seller, accounting for -> roughly a third of units. The last week of the month slowed after the launch -> buzz faded, which is normal — watch whether that holds in April. -> -> Gross margin dipped slightly to 60% (from 62% in February). The culprit is -> beeswax: your new supplier is running about 8% higher than your previous one. -> At current volume that's roughly $200/month — not alarming, but worth a -> conversation with them or a price comparison before next order. -> -> Expenses were otherwise flat. Shopify fees ticked up proportionally with -> sales, which is expected. -> -> **Watch list for April:** (1) Whether the post-launch slowdown stabilizes or -> continues. (2) Beeswax pricing — lock in a rate if you can. (3) You have -> $2,800 in deposits from the Petal & Bloom wholesale order that haven't -> shipped yet — those aren't revenue until delivery. - ---- - -## What makes this narrative work - -- Opens with the headline number, not a preamble -- Names a specific product ("Lavender + Sage three-pack"), not just "top sellers" -- Explains the margin compression in concrete dollars, not just percentages -- Watch list is specific and actionable, not generic ("keep an eye on expenses") -- Flags the deposit that isn't revenue yet — this is a common SMB blind spot diff --git a/small-business/skills/month-end-prep/reference/gotchas.md b/small-business/skills/month-end-prep/reference/gotchas.md deleted file mode 100644 index 4f98e65f9..000000000 --- a/small-business/skills/month-end-prep/reference/gotchas.md +++ /dev/null @@ -1,89 +0,0 @@ -# Gotchas - -Common mistakes and edge cases in month-end close. Each entry has the pattern, -the reason it matters, and a Bad / Good example. - ---- - -## Gotcha: Flagging split transactions as duplicates - -**Why it matters:** A single purchase split across multiple GL categories appears -as multiple rows in the QB export — same vendor, same date, different amounts. -Flagging these as duplicates sends the owner on a wild goose chase. - -### ✗ Bad - -> Flagged as duplicate: Office Depot $47.50 on March 12 and Office Depot $62.50 -> on March 12 — same vendor, same date. - -Both rows share the same `TxnID` — they're splits of a $110 purchase across -"Office Supplies" and "Equipment." - -### ✓ Good - -Before flagging duplicates, group rows by `TxnID`. Only compare transactions -with distinct IDs. Splits of the same transaction are never duplicates. - ---- - -## Gotcha: Treating a refund as a missing settlement - -**Why it matters:** A PayPal refund appears as a negative transaction in the -settlement report. If you treat it as an unmatched outflow, you'll flag a -legitimate refund as a problem. - -### ✗ Bad - -> Flagged: PayPal outflow of –$89.00 on March 18 has no matching QB deposit. -> Possible missing transaction. - -The –$89.00 is a refund to a customer. It should match a QB credit memo, not -a deposit. - -### ✓ Good - -Separate inflows (positive) from outflows (negative) before reconciling. Match -negative processor amounts against QB credit memos or refund transactions, not -deposits. Only flag an unmatched negative if no credit memo exists in QB. - ---- - -## Gotcha: Comparing gross PayPal amount to net QB deposit - -**Why it matters:** QuickBooks often records the net bank deposit (after PayPal -fees), but PayPal's transaction report shows the gross sale amount. Comparing -gross to net will always show a discrepancy equal to the fee. - -### ✗ Bad - -> Discrepancy: PayPal settlement $500.00, QB deposit $484.80 — delta $15.20. -> Flagged as reconciliation error. - -The $15.20 is PayPal's 3.04% processing fee. This is expected and correct. - -### ✓ Good - -Use the **net payout** field from the PayPal settlement report -(`transaction_info.transaction_amount.value` minus -`transaction_info.fee_amount.value`) when comparing to the QB bank deposit. -If the delta is < $0.50 after fee adjustment, mark as RECONCILED. - ---- - -## Gotcha: Advancing past Step 6 when there are unresolved flags - -**Why it matters:** The close packet is the final artifact the owner files or -shares with their accountant. Exporting it with open flags bakes errors into -the record. - -### ✗ Bad - -> Owner hasn't responded about the 3 uncategorized transactions. Generating -> the close packet now so they have something to look at. - -### ✓ Good - -Hold at the Step 6 gate until the owner acknowledges every flag — either -resolving it ("categorize this as office supplies") or explicitly deferring it -("mark that as 'to review later'"). Only then export. Open items that the owner -deferred should appear in the Action Items sheet, not be silently dropped. diff --git a/small-business/skills/month-end-prep/reference/paypal-settlements.md b/small-business/skills/month-end-prep/reference/paypal-settlements.md deleted file mode 100644 index 855ff1937..000000000 --- a/small-business/skills/month-end-prep/reference/paypal-settlements.md +++ /dev/null @@ -1,110 +0,0 @@ -# Payment Processor Settlements Reference - -## Contents - -- [PayPal](#paypal) -- [Square](#square) -- [Stripe](#stripe) -- [Reconciliation logic (all processors)](#reconciliation-logic-all-processors) - ---- - -## PayPal - -### Settlement report structure - -The PayPal connector returns a **Transaction History** or **Settlement** report. -Key fields: - -| Field | Notes | -|---|---| -| `transaction_info.transaction_id` | PayPal transaction ID | -| `transaction_info.transaction_initiation_date` | When the transaction occurred | -| `transaction_info.transaction_amount.value` | Gross amount (positive = money in) | -| `transaction_info.fee_amount.value` | PayPal fee (negative) | -| `transaction_info.transaction_status` | Use only `S` (Success) and `P` (Pending) | -| `payer_info.email_address` | Customer email — useful for matching | - -**Deposit date vs. transaction date:** PayPal batches payouts. A sale on April 28 -may not deposit until May 2. Match by **deposit date** when reconciling against QB -bank entries, not transaction date. - -**Refunds:** Appear as negative amounts with `transaction_type` = `T1107` or -`T1114`. They should offset the original sale — don't flag a refund as a -discrepancy against the QB register unless there's no corresponding QB credit. - -**Holds:** Transactions in status `F` (Funds on Hold) have not been deposited yet. -Note them separately — they'll appear in next month's settlement. - ---- - -## Square - -### Settlement report structure - -Square calls these **Payouts**. Each payout covers 1–2 business days of sales. - -Key fields from the Square Payouts API: - -| Field | Notes | -|---|---| -| `id` | Payout ID | -| `arrived_at` | Date the funds landed in the bank account | -| `amount_money.amount` | Net payout in cents (already minus Square fees) | -| `status` | Use only `PAID` status for reconciliation | - -**Fees:** Square deducts fees before the payout — so `amount_money.amount` is net. -When matching against QB, compare to the net bank deposit, not the gross sale total. - -**Same-day payouts:** If the user has Square Instant Transfer, funds may arrive on -the transaction date. The default is next business day. - ---- - -## Stripe - -### Settlement report structure - -Stripe calls these **Payouts**. The Stripe connector returns payout objects plus -the balance transactions within each payout. - -Key fields: - -| Field | Notes | -|---|---| -| `id` | Payout ID | -| `arrival_date` | Unix timestamp of bank arrival date | -| `amount` | Net payout in cents (fees already deducted) | -| `status` | Use only `paid` for reconciliation | - -**Stripe fees:** Like Square, fees are deducted before payout. Compare net amounts. - -**Stripe Connect / platform accounts:** If the user runs a platform on Stripe -Connect, individual transfer payouts may look unusual. Ask the user to confirm -their Stripe account type if payout patterns don't match expectations. - ---- - -## Reconciliation logic (all processors) - -Use this logic to match processor deposits against QuickBooks bank deposits: - -``` -for each processor deposit in target month: - find QB deposit where: - abs(QB.amount - processor.net_amount) < $0.50 - AND abs(QB.date - processor.arrival_date) <= 2 days - - if match found: - mark as RECONCILED - elif abs(QB.amount - processor.net_amount) < $0.50 (date mismatch only): - flag as DATE_MISMATCH (usually a timing difference — low priority) - elif processor deposit not matched at all: - flag as MISSING_IN_QB - elif QB deposit not matched to any processor record: - flag as UNMATCHED_DEPOSIT (may be ACH, check, or other income) -``` - -**Multi-processor businesses:** Run this logic independently per processor, then -aggregate flags. A QB deposit that doesn't match PayPal may legitimately be a -Square payout — don't flag it until you've checked all connected processors. diff --git a/small-business/skills/month-end-prep/reference/quickbooks-reconcile.md b/small-business/skills/month-end-prep/reference/quickbooks-reconcile.md deleted file mode 100644 index dbb35b31d..000000000 --- a/small-business/skills/month-end-prep/reference/quickbooks-reconcile.md +++ /dev/null @@ -1,71 +0,0 @@ -# QuickBooks — Reconciliation Reference - -## Reports to pull - -### Profit & Loss (P&L) - -Use the **Profit and Loss** report via the QuickBooks connector: -- Date range: first day to last day of target month -- Accounting method: **Accrual** unless the user has told you they run cash-basis -- Include all accounts - -Key fields used downstream: -| Field | Notes | -|---|---| -| `TotalRevenue` | Top-line revenue | -| `GrossProfit` | Revenue minus COGS | -| `GrossProfitMargin` | Compute as GrossProfit / TotalRevenue | -| `NetIncome` | Bottom line | -| `TotalExpenses` | Operating expenses subtotal | - -### Transaction Register - -Pull the **Transaction List by Date** report or equivalent for the target month. -This is the line-item detail used for uncategorized flagging and duplicate detection. - -Key fields: -| Field | Notes | -|---|---| -| `TxnDate` | Transaction date (not posting date) | -| `TxnType` | Invoice, Payment, Expense, Deposit, etc. | -| `Amount` | Positive = income, negative = expense in most QB exports | -| `AccountRef.name` | The GL account category | -| `EntityRef.name` | Vendor or customer name | -| `Memo` | Free-text description | -| `AttachmentCount` | > 0 means a receipt is attached in QB | - -## Identifying uncategorized transactions - -Flag a transaction as uncategorized if `AccountRef.name` is any of: -- "Uncategorized Income" -- "Uncategorized Expense" -- "Uncategorized Asset" -- blank / null -- "Ask My Accountant" (QB's built-in "I don't know" category) - -## Pagination - -The QB API returns a maximum of 1,000 rows per request. For businesses with high -transaction volumes, paginate using `startPosition` and `maxResults` parameters. -Request in 500-row batches to stay safely under the limit. - -## Common data issues - -**Split transactions** — a single purchase split across multiple categories appears as -multiple rows with the same date and vendor but different amounts. These are NOT -duplicates. Before flagging duplicates, group rows by `TxnID` — rows sharing an ID -are splits of one transaction. - -**Bank feeds vs. manual entries** — bank-feed transactions have `PrivateNote` set to -"bank feed" or similar. Manual entries often lack a memo. Neither is a signal of a -problem on its own, but it helps explain why a transaction might lack a receipt. - -**PayPal transactions already in QB** — if the user has the PayPal-QB auto-sync -enabled, PayPal transactions will already appear in the register. Don't double-count -them during reconciliation (Step 3). Check whether the QB deposit lines have -"PayPal" in the account or memo before matching. - -**Retainer / deposit transactions** — a customer deposit is not revenue until the -work is delivered. If the user is on cash-basis accounting this distinction matters -less, but flag any large Deposit-type transactions without a matching Invoice for -their awareness. diff --git a/small-business/skills/month-heads-up/SKILL.md b/small-business/skills/month-heads-up/SKILL.md deleted file mode 100644 index 24f87fd20..000000000 --- a/small-business/skills/month-heads-up/SKILL.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -name: month-heads-up -description: Runs on the 25th — shows the next 30-day cash-flow outlook and flags anything that needs attention before month-end. Accepts optional 30 or 60 day horizon. -allowed-tools: Read, WebFetch, Bash ---- - -Run the month-end heads-up. Pull forward-looking cash data and give the owner a clear "here's what the next 30 days look like" picture with specific things to watch. - -Parse arguments: -- `--horizon` (default: `30`) — forecast window in days (`30` or `60`) - -## Step 1 — Current cash position - -Using the `cash-flow-snapshot` skill workflow: - -1. Pull QuickBooks current cash and receivables balance. -2. Pull PayPal settled balance and pending payouts. -3. Combine for total available + incoming cash. - -## Step 2 — Upcoming obligations - -1. Pull recurring expenses from QuickBooks (payroll, subscriptions, rent/lease) due in the next 30 days. -2. Pull any outstanding invoices past due or due within 14 days. -3. Flag any payment that would push the balance below a comfortable buffer (default: <$2,000 or owner's QB average monthly expense × 0.5). - -## Step 3 — Cash-flow forecast - -1. Project 30-day net cash: current balance + expected inflows − known obligations. -2. Identify the single tightest week (lowest projected balance). -3. Flag if any week projects negative. - -## Step 4 — Two things to watch - -Surface no more than two specific, actionable watches: -- Which invoice(s) to chase now -- Which expense(s) to defer or negotiate - -Format as: - -``` -Month-End Heads Up — {current date} -Horizon: next {X} days - -Cash today: ${amount} -Projected end-of-period: ${amount} -Tightest week: {date range} — projected ${amount} - -TWO THINGS TO WATCH -1. {item} — {why it matters} — suggested action: {action} -2. {item} — {why it matters} — suggested action: {action} -``` - -## Connector failures - -If QuickBooks is unreachable, stop — the cash forecast requires QB as the source of truth. If PayPal is missing, run the forecast from QB-only data and note "PayPal not connected — PayPal receivables excluded from forecast." Same for Stripe/Square if missing. - -## Approval gates - -- **Never initiate payments or send emails automatically.** Surface the data and actions for the owner to take. -- **Never project revenue that hasn't been confirmed in QB or PayPal.** Use conservative estimates only. - -## Output - -Present the formatted brief and offer to draft chase emails for any flagged overdue invoices. diff --git a/small-business/skills/plan-payroll/SKILL.md b/small-business/skills/plan-payroll/SKILL.md deleted file mode 100644 index 662eada82..000000000 --- a/small-business/skills/plan-payroll/SKILL.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -name: plan-payroll -description: Forecasts cash, ranks overdue invoices, and stages PayPal reminders so the owner can confidently run payroll. Accepts optional horizon and payroll-date arguments. -allowed-tools: Read, WebFetch, Bash ---- - -Run the payroll-confidence pipeline by chaining two skills. The owner approves at each handoff — never send a reminder or commit a forecast without explicit confirmation. - -Parse arguments: -- `--horizon` (default `30`) — forecast window in days (30, 60, or 90) -- `--payroll-date` (optional) — the date payroll runs; defaults to next Friday - -## Step 1 — Cash forecast (cash-flow-snapshot) - -Trigger the `cash-flow-snapshot` skill workflow: -1. Pull AR, AP, and historical cash timing from QuickBooks, PayPal, Stripe, or Square (whichever are connected). Fall back to CSV upload if no connector is live. -2. Layer in known fixed costs (rent, payroll, recurring vendor charges). -3. Produce a 30/60/90-day forecast (use the requested `--horizon`) with percentage-variance confidence bands. -4. Flag named risks — e.g., "payroll on May 15 lands $4,200 below your fixed-cost floor at the median forecast." -5. Deliver chat summary + downloadable XLSX. -6. Present to the owner. Wait for explicit "okay, see what we can collect" before Step 2. - -If the forecast shows payroll is comfortably covered, ask the owner whether they still want to chase overdue invoices or stop here. - -## Step 2 — Overdue collection (invoice-chase) - -After Step 1 approval, trigger the `invoice-chase` skill workflow: -1. Pull overdue invoices from QuickBooks and PayPal. -2. Rank by amount × days-late × customer payment history. -3. For each, draft a reminder matched to tone (gentle for good customers, firm for repeat late payers). -4. PayPal-issued invoices queue as PayPal-send drafts; non-PayPal invoices queue as Mail drafts. -5. Present the ranked list with drafted reminders. Show the projected cash impact if a top-N subset gets paid within the horizon — does that close the payroll gap from Step 1? -6. Wait for explicit "send these" per reminder (or batch approval) before pushing. - -## Approval gates (must hold) - -- Never send a reminder without owner approval — drafts only until "send" is given. -- Never commit a forecast as authoritative without owner sign-off. -- If a connector is unreachable (QuickBooks, PayPal, Mail), stop, report which connector failed, and ask whether to retry, fall back to CSV, or abort. - -## Output - -End the run with a one-paragraph recap: forecast verdict (covered / gap / risk), reminders sent and to whom, projected new cash position if reminders convert. diff --git a/small-business/skills/price-check/SKILL.md b/small-business/skills/price-check/SKILL.md deleted file mode 100644 index e0bdbc6a6..000000000 --- a/small-business/skills/price-check/SKILL.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -name: price-check -description: Produces a margin-by-product table and three pricing-scenario data views so the owner can see the full financial picture before making a pricing decision. Accepts optional product name argument. -allowed-tools: Read, WebFetch, Bash ---- - -Run the pricing analysis. Pull cost and revenue data, build the margin table, and model three pricing scenarios — so the owner can see the numbers clearly before deciding what to charge. - -Parse arguments: -- `PRODUCT_NAME` (optional) — specific product or service to analyze; if omitted, analyze all active products - -## Step 1 — Current margin baseline - -Using the `margin-analyzer` skill workflow: - -1. Pull QuickBooks revenue by product/service for the last 90 days. -2. Pull COGS or direct costs per product from QuickBooks (if categorized). -3. Pull PayPal gross sales for the same products to cross-validate. -4. Calculate current gross margin per product: (revenue − COGS) ÷ revenue. - -Build the margin table: - -``` -Product | Revenue | COGS | Gross Margin | Margin % -{product} | ${amt} | ${amt} | ${amt} | {X}% -``` - -Flag any product with margin below 20% as a risk. - -## Step 2 — Three pricing scenarios - -For each product (or the specified product), model three scenarios. Do NOT recommend a price — present data only. - -**Scenario A — Hold current price** -- Project revenue at current price × current volume -- Project margin at current COGS - -**Scenario B — Price increase (+10% to +20%, owner to specify)** -- Project revenue assuming 0%, 5%, and 10% volume loss at new price -- Show the break-even volume needed to maintain current profit - -**Scenario C — Price decrease (−10%, to drive volume)** -- Project revenue assuming 10%, 20%, and 30% volume increase -- Show the volume needed to match current profit - -Present each scenario as a data table, not a recommendation. - -## Step 3 — Customer messaging brief - -Produce a plain-language brief (for price increase scenarios) the owner can use to communicate a change to customers: -- One paragraph explaining the change -- Three key message options (direct, value-focused, empathetic) -- Suggested timing and channel (email, invoice note, in-person) - -## Connector failures - -If QuickBooks is unreachable, stop — margin analysis requires QB revenue and cost data. If PayPal is missing, run from QB-only and note "PayPal not connected — cross-validation against PayPal sales skipped." - -## Approval gates - -- **Never recommend a specific price.** Provide data views only — pricing decisions belong to the owner. -- **Flag if COGS data is incomplete** (many QB setups don't track per-product COGS) and note the gap. -- **Never update any prices in QB, PayPal, or any connected system.** - -## Output - -Present the margin table, then the three scenario tables side-by-side. If a price increase scenario is being considered, append the customer messaging brief. End with: "Which scenario would you like to explore further?" diff --git a/small-business/skills/quarterly-review/SKILL.md b/small-business/skills/quarterly-review/SKILL.md deleted file mode 100644 index 0195706b9..000000000 --- a/small-business/skills/quarterly-review/SKILL.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -name: quarterly-review -description: Generates a full QBR narrative — revenue trend, margin trend, customer health, top opportunities and risks — as a presentation-ready PDF or deck. Accepts optional quarter and save-to arguments. -allowed-tools: Read, WebFetch, Bash ---- - -Run the quarterly business review. Pull financial, sales, and customer data for the quarter, synthesize it into a narrative, and produce a presentation-ready document. - -Parse arguments: -- `--quarter` (default: previous calendar quarter) — format `YYYY-QN` (e.g., `2026-Q1`) -- `--save-to` (default: `files`) — `files` (Google Drive / OneDrive), `desktop`, or `both` - -## Step 1 — Financial performance - -Using the `business-pulse` skill in deep mode: - -1. Pull QuickBooks P&L for the quarter: revenue, COGS, gross margin, operating expenses, net margin. -2. Compare to prior quarter and same quarter last year (if available). -3. Pull PayPal settlements for the same period to validate QB revenue. -4. Calculate: revenue growth %, margin change in points, top 3 revenue categories. - -## Step 2 — Customer health - -1. Pull HubSpot deal data: new customers won, churned, average deal size, pipeline entering next quarter. -2. Calculate customer acquisition cost (if data available) and revenue per customer. -3. Flag any customers representing >20% of revenue (concentration risk). - -## Step 3 — Top opportunities - -Identify 3 specific opportunities for next quarter based on the data: -- Revenue upside (category, customer segment, or channel to double down on) -- Margin upside (cost to cut or price to raise) -- Customer upside (segment to target or churn to reduce) - -## Step 4 — Top risks - -Identify 3 specific risks for next quarter: -- Revenue risk (concentration, trend, seasonality) -- Margin risk (rising cost, pricing pressure) -- Operational risk (pipeline gap, vendor dependency) - -## Step 5 — QBR narrative - -Write a 500–800 word narrative in plain business English with this structure: -1. Quarter headline (one sentence) -2. Revenue story (trend + why) -3. Margin story (trend + why) -4. Customer story (health + pipeline) -5. Three opportunities -6. Three risks -7. One-paragraph call to action for next quarter - -## Step 6 — Export - -Generate: -1. **`qbr-{YYYY-QN}.pdf`** — formatted narrative + key charts (as ASCII tables if no chart tool available) -2. Save to `--save-to` location - -## Connector failures - -If QuickBooks is unreachable, stop — the QBR requires QB financial data as the foundation. If PayPal is missing, skip cross-validation and note "PayPal not connected — revenue validated from QB only." If HubSpot is missing, skip customer health (Step 2) and note "HubSpot not connected — customer health section skipped." - -## Approval gates - -- **Never publish or email the QBR automatically.** Always display for owner review first. -- **Flag if any data source returns incomplete data** — note gaps in the narrative. - -## Output - -Present the narrative in-line, then confirm export. End with a one-paragraph "what to focus on next quarter" summary. diff --git a/small-business/skills/review-contract/SKILL.md b/small-business/skills/review-contract/SKILL.md deleted file mode 100644 index 01632978d..000000000 --- a/small-business/skills/review-contract/SKILL.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -name: review-contract -description: Reviews a contract in plain English, surfaces red flags with severity ratings, and produces a marked-up docx/PDF with suggested redlines. Accepts optional file path or DocuSign envelope ID. -allowed-tools: Read, WebFetch, Bash ---- - -Run the contract review. Read the document, explain what it says, flag anything risky, and produce marked-up redlines for the owner to use in negotiations. - -Parse arguments: -- `FILE_PATH_OR_DOCUSIGN_ENVELOPE_ID` — path to a local PDF/docx file, or a DocuSign envelope ID; if omitted, check the most recent envelope awaiting signature in DocuSign - -## Step 1 — Load the contract - -Using the `contract-review` skill workflow: - -1. If a file path is given: read the document from Files or Desktop. -2. If a DocuSign envelope ID is given: pull the document from DocuSign. -3. If neither: check DocuSign for the most recent envelope with status `waiting for signature` and confirm with the owner before proceeding. - -## Step 2 — Plain-English summary - -Produce a 3-paragraph summary: -1. **What this contract does** — the deal in plain terms (who, what, how much, how long) -2. **Key obligations** — what the owner must do and when -3. **Key rights** — what the owner gets and any termination or exit paths - -## Step 3 — Red-flag list - -For each risk, rate severity: 🔴 High / 🟡 Medium / 🟢 Low - -Flag at minimum: -- Auto-renewal clauses with short cancellation windows -- Unilateral price change rights -- Broad IP ownership transfers -- Unlimited liability or missing liability cap -- Exclusivity clauses -- Non-compete or non-solicit provisions -- Ambiguous payment or deliverable terms - -Format each flag as: -``` -{Severity} {Clause name} — {what it says in plain English} — Suggested redline: {fix} -``` - -## Step 4 — Marked-up redlines - -Generate a list of specific redline suggestions in legal markup format: -``` -§{section}: DELETE "[original language]" / INSERT "[suggested replacement]" -Reason: {one sentence} -``` - -Offer to export this as a marked-up docx or PDF to Files or Desktop. - -## Connector failures - -If DocuSign is not connected and no file path was given, ask the owner to upload the contract as a PDF or docx. If DocuSign is connected but the envelope ID is invalid, report the error and ask the owner to check the ID. This command works fully offline with a local file — connectors are optional. - -## Approval gates - -- **Never sign, send, or modify the actual DocuSign envelope.** Present the review and wait for the owner to act. -- **Always caveat:** "This is not legal advice. Review with your attorney before signing." -- **Never delete or overwrite the original document.** - -## Output - -Present the plain-English summary, red-flag list, and redline suggestions. Ask the owner whether to export a marked-up copy and where to save it. diff --git a/small-business/skills/run-campaign/SKILL.md b/small-business/skills/run-campaign/SKILL.md deleted file mode 100644 index 239e47dd9..000000000 --- a/small-business/skills/run-campaign/SKILL.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -name: run-campaign -description: Runs an end-to-end marketing campaign — sales analysis, content brief, Canva assets, HubSpot send. Accepts optional lookback and channel arguments. -allowed-tools: Read, WebFetch, Bash ---- - -Run the full campaign pipeline by chaining three skills in order. The owner approves at each handoff — never roll past a gate without explicit confirmation. - -Parse arguments: -- `--lookback` (default `90d`) — how far back to look for the revenue dip -- `--channel` (default `both`) — `email`, `social`, or `both` - -## Step 1 — Sales analysis + content brief (content-strategy) - -Trigger the `content-strategy` skill workflow: -1. Pull sales data from QuickBooks and PayPal for the lookback window. -2. Identify the revenue dip — which product/service, which time period, magnitude. -3. Produce a 30-day prioritized content brief: what to push, what offer to run, what to hold. -4. Present the brief to the owner. Wait for explicit "approved, build the assets" before continuing. - -If the owner edits the brief, incorporate edits and re-present. - -## Step 2 — Asset generation + send staging (canva-creator) - -After Step 1 approval, trigger the `canva-creator` skill workflow: -1. Take the approved brief from Step 1 as input. -2. Build the posting calendar matched to the brief's priorities. -3. Generate on-brand Canva assets for each post (apply each on screen for owner approval before moving on). -4. Draft caption copy for each post. -5. Stage the scheduled send in HubSpot (do NOT send — staging only). -6. Present the staged campaign to the owner. Wait for explicit "approved, send to segment X" before Step 3. - -## Step 3 — Audience segmentation (lead-triage) - -After Step 2 approval, trigger the `lead-triage` skill workflow: -1. Pull HubSpot contacts that match the campaign's target segment (from the approved brief). -2. Score by engagement, company fit, urgency markers. -3. Produce two deliverables: - - **Bulk send list** — the segment receiving the staged campaign from Step 2 - - **High-priority call list** — top 5 leads the owner should call personally with talking points -4. Block calendar time for the call list. -5. Present both lists. Wait for explicit "send" before pushing the HubSpot campaign live. - -## Approval gates (must hold) - -- Never auto-progress between steps. Each handoff requires explicit owner approval. -- Never send the HubSpot campaign without the owner's "send" command in Step 3. -- If any connector is unreachable (QuickBooks, PayPal, Canva, HubSpot), stop, report which connector failed, and ask whether to retry or abort. - -## Output - -End the run with a one-paragraph recap: revenue dip identified, posts generated, segment size, calls booked. Link to the HubSpot campaign URL once sent. diff --git a/small-business/skills/sales-brief/SKILL.md b/small-business/skills/sales-brief/SKILL.md deleted file mode 100644 index 843398f7d..000000000 --- a/small-business/skills/sales-brief/SKILL.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -name: sales-brief -description: Surfaces top and bottom sellers, identifies seasonality patterns, and produces a 2-week content brief to push winners and clear slow movers. Accepts optional lookback window of 30, 60, or 90 days. -allowed-tools: Read, WebFetch, Bash ---- - -Run the sales analysis and content brief. Pull what sold (and what didn't), explain why, and produce a ready-to-use content plan that acts on the data. - -Parse arguments: -- `--lookback` (default: `30d`) — `30d`, `60d`, or `90d` lookback window - -## Step 1 — Sales breakdown - -Using the `content-strategy` skill workflow for sales analysis: - -1. Pull PayPal transactions for the lookback period grouped by item/service/SKU. -2. Pull QuickBooks revenue by product/service category. -3. Rank products by: total revenue, unit volume, and margin (if available in QB). -4. Calculate each product's share of total revenue vs. prior equivalent period. - -Top sellers: products that grew share or maintained top-3 rank. -Bottom sellers: products with declining volume or below 5% of revenue. - -## Step 2 — Seasonality check - -1. Compare current period to same period in prior year (if QB history available). -2. Flag any items with a seasonal pattern (e.g., spikes in Q4, slow summers). -3. Note any new products with insufficient history to detect seasonality. - -## Step 3 — Why analysis - -For each top and bottom seller, explain the likely driver: -- Price change, promo, new channel, seasonal demand, competitor move -- Cross-reference with HubSpot campaign activity for the period -- Note where attribution is inferred vs. confirmed - -## Step 4 — 2-week content brief - -Produce a ready-to-use content brief: - -``` -2-Week Content Brief — {date range} - -PUSH THESE (winners) -• {product}: {suggested angle} — {channel: email|social|both} -• {product}: {suggested angle} — {channel} - -CLEAR THESE (slow movers) -• {product}: {promo angle or bundle suggestion} — {channel} - -CONTENT CALENDAR -Week 1: - Mon: {post/email concept} - Wed: {post/email concept} - Fri: {post/email concept} -Week 2: - Mon: {post/email concept} - Wed: {post/email concept} - Fri: {post/email concept} -``` - -## Connector failures - -If both QuickBooks and PayPal are unreachable, stop — sales analysis requires at least one revenue source. If only one is connected, run from that source and note "QuickBooks not connected — revenue data from PayPal only" (or vice versa). If HubSpot is missing, skip campaign cross-reference in the "why analysis" and note it. - -## Approval gates - -- **Never auto-schedule or publish content.** The brief is for owner review only. -- **Never create Canva assets automatically** — offer to generate them after owner approves the brief. - -## Output - -Present the sales analysis, then the content brief. Ask the owner if they'd like to generate Canva assets for any of the planned posts. diff --git a/small-business/skills/smb-onboard/SKILL.md b/small-business/skills/smb-onboard/SKILL.md deleted file mode 100644 index 389de0e73..000000000 --- a/small-business/skills/smb-onboard/SKILL.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -name: smb-onboard -description: > - Claude as the trainer. Walks an SMB owner through connecting their first two - tools, runs one recipe to prove immediate value, interviews them about their - business (industry, size, top three headaches), stores that context - persistently so every other skill benefits, and sets a weekly check-in - cadence. Use when the owner is getting started or says any of: "set me up," - "setup," "help me get set up," "get started," "help me get started," "get me - started," "what can you do," "I'm new to this," or is in their first session. ---- - -# SMB Onboard - -## Quick start - -Four moves: connect two tools → run one recipe → capture business context → set a weekly rhythm. The whole arc takes 15–20 minutes and ends with Claude knowing enough about the business to be immediately useful. - -``` -User: "get me started" -→ Assess what's already connected; pick the best 2 tools to connect first -→ Guide connection of each tool (one at a time) -→ Run one recipe against live data to prove value -→ Ask 5 business questions one at a time; store answers to persistent memory -→ "Each Monday, say 'weekly check-in' — I'll pull your numbers and flag anything urgent." -``` - -## Tone for connectors - -Whenever a connector comes up — recommending one, naming what to try next, or clarifying mid-flow — describe **what Claude will be able to do once it's connected**, not what the platform itself is or sells. Owners already know what HubSpot, QuickBooks, Gmail, and Calendar do; they don't need a product pitch from us. - -- Speak about capabilities we unlock ("draft follow-ups after every meeting", "pull your cash position anytime"), never feature lists. -- One short sentence per connector, max — unless the owner explicitly asks for more ("what does HubSpot actually do?"), in which case answer that directly. -- This rule applies to every step below. - -## Workflow - -1. **Welcome and assess.** Greet the owner briefly. Check which connectors are already active. If a `## Business context` block already exists in the owner's CLAUDE.md or memory, read it first — then skip to the return-session path: show the existing profile, ask what's changed, update only the fields that changed. Do not re-interview from scratch. - -2. **Pick two functions, then check what the owner uses.** Ask: *"What are your biggest day-to-day headaches — money, customers, scheduling, or getting organized?"* Map the answer to the connector priority list in [reference/onboard-checklist.md](reference/onboard-checklist.md). - - Name the two **functions** we want (e.g. "a place to track customers and deals" and "your inbox") — not the platform features. One short sentence each, max. Then ask whether the owner uses a supported tool for each. - - For each function, branch: - - **Owner uses a supported connector** (e.g. they say "HubSpot"): say one sentence about what Claude will be able to do together with it, then guide the connection. - - **Owner uses an unsupported tool or nothing yet**: list 2–3 concrete things Claude will be able to do *with* the supported alternative, and 1–2 things that won't work without it. Then let the owner decide whether to switch or add it. Do not push. - - Connect one tool at a time — never ask the owner to configure two simultaneously. See [reference/gotchas.md](reference/gotchas.md) for the failure pattern this replaces. - -3. **Run one recipe to prove value.** Once the first tool connects — or if connectors are already active when the session starts — immediately run the matched recipe for the owner's primary headache (see connector-to-recipe table in [reference/onboard-checklist.md](reference/onboard-checklist.md)). Narrate what Claude is doing and why — this is the "aha" moment. Do not skip it to get to the interview faster. For a worked example of the full arc, see [reference/examples/happy-path.md](reference/examples/happy-path.md). - -4. **Interview the owner.** Ask the five questions from [reference/onboard-checklist.md](reference/onboard-checklist.md), one at a time, conversationally. Wait for the full answer before moving to the next. If the owner seems pressed for time, compress to three: industry, headaches, tools — but never fewer. - -5. **Store context.** Show the owner the full profile before writing. Wait for explicit approval. Write the block to the Cowork session memory directory under the heading `## Business context` using the exact format in [reference/onboard-checklist.md](reference/onboard-checklist.md). If a memory file already exists, update only the `## Business context` section — do not touch other content. Confirm: *"Saved. Every skill from here will know your business."* - -6. **Set the weekly cadence.** Propose: *"Each Monday, just say 'weekly check-in' and I'll pull a snapshot of your numbers, flag anything urgent, and remind you what's due."* If they prefer a different phrase or day, store it in the profile. If tools are connected, name one skill the owner can try right now. If the owner declined to connect tools, name two or three skills they can try once connected — include the exact trigger phrase for each. - -## Approval gates - -- **Show context before writing.** Display the full owner profile draft before storing it. Wait for explicit approval. -- **Never overwrite existing context silently.** If a `## Business context` block already exists, show current vs. proposed before writing any changes. -- **Never connect a tool on the owner's behalf.** Guide; do not act. Connector auth is always owner-initiated. - -## Reference - -- [reference/onboard-checklist.md](reference/onboard-checklist.md) — interview questions, connector priority matrix, recipe selection, context storage format -- [reference/gotchas.md](reference/gotchas.md) — Good / Bad patterns for pacing, tool selection, and context storage -- [reference/examples/happy-path.md](reference/examples/happy-path.md) — worked example: retail shop owner, first session end-to-end diff --git a/small-business/skills/smb-onboard/reference/examples/happy-path.md b/small-business/skills/smb-onboard/reference/examples/happy-path.md deleted file mode 100644 index bfb277eb4..000000000 --- a/small-business/skills/smb-onboard/reference/examples/happy-path.md +++ /dev/null @@ -1,128 +0,0 @@ -# Happy path: Retail shop owner, first session - -## Setup - -- **Owner:** Maria, sole operator of a hardware store with 3 part-time employees -- **Session type:** First session ("get me started") -- **Connectors before start:** None connected - ---- - -## Transcript - -**Claude:** Welcome! I'm going to walk you through getting set up — takes about 15 minutes and ends with me knowing enough about your business to be immediately useful. Ready? - -**Maria:** Sure. - -**Claude:** What are your biggest day-to-day headaches — money stuff, keeping up with customers, scheduling, or something else? - -**Maria:** Cash flow. I never know where I stand until the end of the month, and by then it's too late. - -**Claude:** That's the most common one. Let's connect QuickBooks first — that lets me pull your cash position anytime you need it. Here's how to authorize the connection… - -*[Maria connects QuickBooks — ~3 minutes]* - -**Claude:** QuickBooks is live. Let me pull your last 30 days of cash flow right now. - -*[runs cash-flow-snapshot]* - -**Claude:** Here's your snapshot: $4,200 net cash in for the month, but $6,100 in outstanding invoices, mostly from two contractor accounts. Your biggest gap looks like Net-30 customers paying Net-45. Does that match what you're seeing? - -**Maria:** Yes, exactly. I didn't know I could see that so fast. - -**Claude:** That's available anytime. Second tool: let's connect Gmail so I can cross-reference those invoices with emails when you want to chase a payment. - -*[Maria connects Gmail — ~2 minutes]* - -**Claude:** Good. A few questions so I know your business — one at a time. What's the one-liner for what you do? - -**Maria:** Hardware store. Retail and light contractor supply. - -**Claude:** How many people work with you, including yourself? - -**Maria:** Four total — me and three part-timers. - -**Claude:** What are your top three headaches right now? - -**Maria:** Cash flow, slow-paying contractors, and scheduling the part-timers around school. - -**Claude:** Which tools do you already use day-to-day? - -**Maria:** QuickBooks and Gmail, which we just connected. Also Square for in-store payments. - -**Claude:** Got it. Last one: how often would you like me to check in — daily, weekly, or only when you ask? - -**Maria:** Weekly's good. Monday mornings. - -**Claude:** Here's what I'm about to save as your business profile — let me know if anything's off: - -``` -Business: Hardware store — retail and light contractor supply -Size: 4 people (including owner) -Top headaches: cash flow gaps · slow-paying contractors · scheduling part-timers -Connected tools: QuickBooks, Gmail -Weekly cadence: weekly check-in every Monday -Onboarded: 2026-04-23 -``` - -Look right? - -**Maria:** Yep, that's it. - -**Claude:** Saved. Every skill from here will know your business. Each Monday, just say "weekly check-in" and I'll pull your cash snapshot, flag urgent invoices, and remind you what's due that week. Want to try the invoice reminder skill right now? Say "invoice chase." - ---- - -## Pass criteria - -- [ ] Triggered on "get me started" -- [ ] Asked headache question before recommending connectors -- [ ] Recommended QuickBooks first (matched cash-flow headache) -- [ ] Ran `cash-flow-snapshot` immediately after QuickBooks connected, before interview -- [ ] Connected second tool (Gmail) before starting interview -- [ ] Asked all 5 interview questions one at a time -- [ ] Showed profile draft before writing -- [ ] Wrote context under `## Business context` in `~/.claude/CLAUDE.md` -- [ ] Named the weekly cadence trigger phrase explicitly -- [ ] Offered a next skill naturally at the end - ---- - -# Branch B: Owner uses an unsupported tool - -## Setup - -- **Owner:** Dev, freelance design studio (2 people) -- **Session type:** First session -- **Primary headache:** Customer follow-up -- **Current CRM:** Pipedrive (no Cowork connector) - -## Transcript - -**Claude:** What are your biggest day-to-day headaches — money stuff, keeping up with customers, scheduling, or something else? - -**Dev:** Customer follow-up. Leads slip through. - -**Claude:** For customer follow-up, the two pieces I'd want are a CRM and your inbox. Are you on HubSpot today, or something else? - -**Dev:** Pipedrive. - -**Claude:** Got it — we don't have a Pipedrive connector yet. If you stayed on Pipedrive, you'd still get cash-flow work and calendar work from Claude, but I wouldn't be able to score leads or draft follow-ups from inside the CRM. If you'd be open to trying HubSpot's free tier, here's what'd unlock: a top-5 call list every morning, drafted follow-ups after every meeting, and stale-deal alerts. Up to you — want to try it, or skip the CRM for now? - -**Dev:** Skip for now. I'll stick with Pipedrive. - -**Claude:** No problem. Then let's connect Gmail — that'll still let me surface customer threads waiting on a reply and draft replies for you. Sound good? - -**Dev:** Yeah. - -*[Dev connects Gmail — ~2 minutes]* - -**Claude:** Gmail is live. Let me pull the three oldest unread customer threads… - -## Pass criteria - -- [ ] Named the function ("a CRM and your inbox"), not the platform -- [ ] Asked what the owner uses before pitching anything -- [ ] On unsupported tool, listed gain/loss concretely without pushing -- [ ] Accepted the owner's decision and pivoted to the next supported tool -- [ ] No paragraph-long descriptions of HubSpot, Gmail, or Pipedrive diff --git a/small-business/skills/smb-onboard/reference/gotchas.md b/small-business/skills/smb-onboard/reference/gotchas.md deleted file mode 100644 index 56a4d0ce5..000000000 --- a/small-business/skills/smb-onboard/reference/gotchas.md +++ /dev/null @@ -1,88 +0,0 @@ -# Gotchas - -## Gotcha: Skipping the prove-value step when a connection takes too long - -**Why it matters:** If the owner connects a tool but Claude moves straight to the interview, the "aha" moment never lands. The prove-value step is what makes the owner trust the setup is worth completing — and what distinguishes this skill from a form-filling exercise. - -### ✗ Bad - -> "Great, QuickBooks is connected! Now let me ask you a few questions about your business." - -Skips the recipe entirely. Owner leaves not knowing what they just enabled. - -### ✓ Good - -> "QuickBooks is live. Let me pull your last 30 days of cash flow — takes about 10 seconds." -> *[runs cash-flow-snapshot, shows results]* -> "That's what we can do anytime you want a number check. Now, a few questions about your business…" - -The demo runs before the interview, every time, without exception. - ---- - -## Gotcha: Dumping all five interview questions at once - -**Why it matters:** Five questions presented together feel like a form, not a conversation. Owners either skim-answer or drop off. Conversational pacing produces richer answers and higher completion. - -### ✗ Bad - -> "To get you set up, I need: (1) What kind of business do you run? (2) How many employees? (3) What are your top headaches? (4) What tools do you use? (5) How often do you want check-ins?" - -### ✓ Good - -Ask each question, receive the full answer, then ask the next. Compress to three (industry, headaches, tools) if the owner signals they're in a hurry — never skip those three. - ---- - -## Gotcha: Writing context without showing the profile first - -**Why it matters:** Silent writes feel intrusive and remove the owner's chance to correct misheard answers. Showing the draft profile is also a natural confirmation that Claude understood correctly — it often surfaces a correction the owner wouldn't have volunteered. - -### ✗ Bad - -> "Got it, I've saved your business profile!" - -No preview, no approval — owner doesn't know what was written. - -### ✓ Good - -> "Here's what I'm about to save as your business profile — let me know if anything needs fixing:" -> -> ``` -> Business: Lakewood Hardware — retail hardware store -> Size: 4 people (including owner) -> Top headaches: cash flow gaps · slow-paying contractors · scheduling part-timers -> Connected tools: QuickBooks, Gmail -> Weekly cadence: weekly check-in every Monday -> Onboarded: 2026-04-23 -> ``` -> -> "Look right? I'll save it once you confirm." - -Show the block, wait for approval, then write. - ---- - -## Gotcha: Pitching the platform instead of the capability - -**Why it matters:** Owners already know what HubSpot, QuickBooks, Gmail, and Calendar do. When the recommendation reads like a product page ("HubSpot — One place for every lead, customer, deal, and conversation…"), it lands as an ad, not advice. The owner tunes out exactly when we need their attention. - -### ✗ Bad - -> "1. HubSpot (CRM) — One place for every lead, customer, deal, and conversation. Once it's in, I can prioritize who to call today, draft follow-ups, log notes from your inbox, and spot deals going stale. -> -> 2. Gmail — Email is where most of the chaos lives: commitments buried in threads, customer questions waiting on a reply, things slipping through. Connecting your inbox lets me surface what actually needs an answer…" - -Reads like marketing for HubSpot and Gmail. The owner is being sold to. - -### ✓ Good - -> "For customer follow-up, the two pieces I'd want are a CRM and your inbox. -> -> Are you on HubSpot today, or something else?" -> -> *(Owner: "Pipedrive.")* -> -> "Got it — we don't have a Pipedrive connector yet. If you stayed on Pipedrive, you'd still get cash-flow and calendar work, but I wouldn't be able to score leads or draft follow-ups from inside Claude. If you'd be open to trying HubSpot's free tier, here's what'd unlock: top-5 call list every morning, drafted follow-ups after every meeting, stale-deal alerts. Up to you — want to try it, or skip CRM for now?" - -States the function, checks what the owner uses, gives a clear gain/loss in plain English, leaves the decision with the owner. If the owner asks "what does HubSpot actually do?" — that's an explicit invitation; answer it directly. diff --git a/small-business/skills/smb-onboard/reference/onboard-checklist.md b/small-business/skills/smb-onboard/reference/onboard-checklist.md deleted file mode 100644 index 1e0f599c4..000000000 --- a/small-business/skills/smb-onboard/reference/onboard-checklist.md +++ /dev/null @@ -1,63 +0,0 @@ -# Onboard checklist - -## The five interview questions - -Ask one at a time. Wait for the full answer before moving on. One follow-up is fine if an answer is vague; do not drill further. - -1. **Industry and business type.** "What kind of business do you run? Give me the one-liner." -2. **Team size.** "How many people work with you, including yourself?" -3. **Top three headaches.** "What are your three biggest headaches right now — the things that eat your time or keep you up at night?" -4. **Tools already in use.** "Which tools do you already use day-to-day? Things like QuickBooks, Gmail, Slack, Square…" -5. **Preferred cadence.** "How would you like me to check in — daily, weekly, or only when you ask?" - -If the owner is short on time, compress to questions 1, 3, and 4 — those three feed the most downstream skills. - ---- - -## Connector priority matrix - -Map the owner's stated headache to the best two connectors to link first. - -| Primary headache | First connector | Second connector | Prove-value recipe | -|---|---|---|---| -| Cash flow / invoicing | QuickBooks | PayPal or Square | `cash-flow-snapshot` | -| Customer follow-up | HubSpot | Gmail | `crm-maintenance` (read-only demo) | -| Hiring / job posts | Gmail | Google Calendar | `job-post-builder` | -| Staying organized | Desktop (folder setup) | Gmail | Desktop folder structure demo | -| Scheduling overload | Google Calendar | Gmail | `business-pulse` | -| General / unsure | Gmail | QuickBooks | `cash-flow-snapshot` | - -If the owner names a connector not in this table, add it as the second connector and use `business-pulse` as the recipe. - ---- - -## Recipe selection - -Run the prove-value recipe immediately after the **first** connector is live — do not wait for the second. If connectors are already active at session start, run the matched recipe for the owner's primary headache before beginning the interview. Priority order: - -1. QuickBooks or Square → `cash-flow-snapshot` -2. HubSpot → `crm-maintenance` (log-a-note demo, read-only) -3. Gmail → search for unread invoice-related emails, surface top 3 -4. Google Calendar → `business-pulse` -5. Desktop only → walk Desktop folder setup, create recommended structure - -**QuickBooks profile_info_required:** If QuickBooks returns a `profile_info_required` status (missing business_name or industry), use the `quickbooks-profile-info-update` tool with the owner's business name from interview question 1 before running `cash-flow-snapshot`. Do not skip the recipe — collect the missing info first. - ---- - -## Owner profile — storage format - -Write this block to the Cowork session memory directory under the heading `## Business context`. Every other skill reads this section by heading match. Do not rename the heading or change the field names. - -```markdown -## Business context - -- **Business:** -- **Size:** -- **Top headaches:** · · -- **Connected tools:** -- **Weekly cadence:** -- **Onboarded:** -``` - -If a memory file already exists, append or update only the `## Business context` section. Do not touch other content. diff --git a/small-business/skills/smb-router/SKILL.md b/small-business/skills/smb-router/SKILL.md deleted file mode 100644 index 962e302a2..000000000 --- a/small-business/skills/smb-router/SKILL.md +++ /dev/null @@ -1,157 +0,0 @@ ---- -name: smb-router -description: > - The front door to the Small Business plugin. Listens to what the owner needs - right now — vague or specific — and routes them to the best skill or slash - command for the moment. Also serves as a guide: explains what's available, - suggests what to try next, and adapts recommendations based on stored business - context. Trigger whenever the owner asks "what can you do," "help me with my - business," "what should I focus on," "I don't know where to start," or any - open-ended business request that doesn't clearly match a single skill. ---- - -# SMB Router - -You are the concierge for this plugin. Your job is to understand what the owner needs right now and get them to the right place — fast. You are not a skill that does work yourself. You route to the skills and commands that do. - -## Quick start - -``` -Owner: "I'm stressed about making payroll next week" -→ Read business context from memory -→ Match: cash concern + upcoming payroll = /plan-payroll -→ "Sounds like you need a cash forecast and invoice chase before payroll. - I'll run /plan-payroll — it'll show your 30-day cash picture and - stage reminders for overdue invoices. Ready?" -→ On confirmation, trigger /plan-payroll -``` - -## How to route - -### Step 1 — Read business context - -Check session memory for `## Business context`. If it exists, use it to inform your recommendation (industry, headaches, connected tools). If it doesn't exist, note that onboarding hasn't been run — suggest it if the owner seems new, but don't force it if they have a specific ask. - -### Step 2 — Match intent to a command - -Listen to the owner's request. Match it against this routing table — pick the **single best match**, not a list of options. If two are close, pick the one that addresses the most urgent concern. - -**Money & cash flow:** -| Owner says something like... | Route to | -|---|---| -| "Can I make payroll?" / "cash is tight" / "who owes me money?" | `/plan-payroll` | -| "What does next month look like?" / "cash forecast" / "runway" | `/month-heads-up` | -| "Close the books" / "month-end" / "reconcile" | `/close-month` | -| "What are my margins?" / "should I raise prices?" / "cost per unit" | `/price-check` | -| "Tax stuff" / "estimated taxes" / "1099s" / "accountant needs..." | `/tax-prep` | - -**Sales & marketing:** -| Owner says something like... | Route to | -|---|---| -| "Who should I call?" / "any hot leads?" / "pipeline" | `/call-list` | -| "Run a campaign" / "sales are down" / "I need more customers" | `/run-campaign` | -| "What's selling?" / "what should I promote?" | `/sales-brief` | - -**Customers & operations:** -| Owner says something like... | Route to | -|---|---| -| "What are customers saying?" / "complaints" / "reviews" | `/customer-pulse-check` | -| "A customer is upset" / "handle this complaint" / "angry email" | `/handle-complaint` | -| "Clean up the CRM" / "HubSpot is a mess" / "stale deals" | `/crm-cleanup` | -| "Review this contract" / "NDA" / "should I sign this?" | `/review-contract` | - -**Business intelligence:** -| Owner says something like... | Route to | -|---|---| -| "Monday brief" / "what's on my plate?" / "start of week" | `/monday-brief` | -| "End of week" / "how'd we do?" / "Friday recap" | `/friday-brief` | -| "Quarterly review" / "board deck" / "QBR" | `/quarterly-review` | - -**Getting started:** -| Owner says something like... | Route to | -|---|---| -| "What can you do?" / "I'm new" / "set me up" / "setup" / "get started" / "help me get set up" / "help me get started" | `smb-onboard` | - -### Step 3 — Present the recommendation - -Don't dump a menu. Recommend **one thing** based on what the owner just said. Explain in one sentence why it's the right move. Ask if they want to run it. - -**Good:** -> "Sounds like you want to see where your money is going before month-end. I'll run `/close-month` — it reconciles QuickBooks against your payment processors and flags anything that looks off. Want me to start?" - -**Bad:** -> "Here are 15 commands you can try: /monday-brief, /friday-brief, /plan-payroll..." - -If the owner's request genuinely spans multiple commands, pick the most urgent one first and mention the follow-up: "After that, we could also run `/price-check` to look at your margins — but let's start with cash." - -### Step 4 — Handle "what can you do?" - -When the owner asks for a general overview, organize by what matters to them — not by a flat list. Use their business context if available. - -Group into four buckets and lead with the one most relevant to their stored headaches: - -**Your money:** `/plan-payroll` · `/month-heads-up` · `/close-month` · `/price-check` · `/tax-prep` -**Your customers:** `/call-list` · `/run-campaign` · `/sales-brief` · `/customer-pulse-check` · `/handle-complaint` · `/crm-cleanup` -**Your contracts:** `/review-contract` -**Your week:** `/monday-brief` · `/friday-brief` · `/quarterly-review` - -Keep it to 2-3 sentences per bucket. End with: "What's on your mind? I'll get you to the right place." - -### Step 5 — Handle zero-connector bootstrap - -If no connectors are connected at all (or the owner just installed the plugin): -1. Trigger `smb-onboard` immediately: "Looks like you haven't connected any tools yet. Let me walk you through setup — it takes about 5 minutes and unlocks everything else." -2. If the owner has a specific ask but no connectors, explain what's needed: "To run `/plan-payroll`, I need QuickBooks connected. Want me to walk you through connecting it, or would you rather start with onboarding to get everything wired up at once?" -3. Never route to a data-dependent command when the required connector is missing — always tell the owner what's needed first. - -### Step 6 — Connector-aware routing - -Before recommending a command, check which connectors are active. If the best-match command requires a connector that isn't connected: - -1. Tell the owner what you'd recommend and why it's blocked: "The best fit for that is `/close-month`, but it needs QuickBooks connected. Want me to help you set that up?" -2. If a fallback command can serve the same intent with the connectors that *are* connected, offer it: "Without QuickBooks, I can still run `/friday-brief` using your PayPal data — it won't be as complete, but you'll get a revenue snapshot." -3. Always be explicit about what's skipped: "Note: PayPal isn't connected, so the revenue cross-validation will be skipped." -4. Never silently route to a command that will partially fail — the owner should know upfront what they'll get and what they won't. - -**Connector requirements by command:** -| Command | Required | Optional | -|---|---|---| -| `/plan-payroll` | QuickBooks | PayPal, Stripe, Square | -| `/close-month` | QuickBooks | PayPal, Stripe, Square | -| `/month-heads-up` | QuickBooks | PayPal | -| `/price-check` | QuickBooks | PayPal | -| `/tax-prep` | QuickBooks | PayPal, Stripe | -| `/call-list` | HubSpot | Mail, Google Calendar | -| `/run-campaign` | HubSpot, Canva | QuickBooks, PayPal | -| `/sales-brief` | QuickBooks or PayPal | HubSpot | -| `/crm-cleanup` | HubSpot | — | -| `/customer-pulse-check` | PayPal or HubSpot | — | -| `/review-contract` | — (works with file upload) | DocuSign | -| `/monday-brief` | — (degrades gracefully) | QuickBooks, PayPal, HubSpot, Calendar, Gmail | -| `/friday-brief` | PayPal or HubSpot | — | -| `/quarterly-review` | QuickBooks | PayPal, HubSpot | -| `/handle-complaint` | — (works with pasted text) | Gmail, HubSpot, PayPal | -| `smb-onboard` | — | all | - -### Step 7 — Handle tiebreakers - -If the owner's request matches two commands equally well: -1. Pick the one that addresses the more urgent concern. Cash concerns beat marketing concerns. Customer complaints beat pipeline reviews. -2. If urgency is equal, pick the one with the smaller scope — get a quick win, then suggest the bigger one. -3. If still tied, ask one clarifying question: "I could go two ways with that — are you more concerned about [X] or [Y]?" -4. Never present more than two options in a tiebreaker. Never dump the full menu. - -### Step 8 — Handle no match - -If the owner's request doesn't match any command: -1. Check if it matches an individual skill that doesn't have a command (unlikely — all 15 skills have commands). -2. If it's genuinely outside scope, say so plainly: "That's outside what I can help with right now. Here's what I'm good at:" and give the four-bucket overview from Step 4. -3. Never hallucinate a capability. Never say "I can do that" if no skill covers it. - -## Guardrails - -- **Never do the work yourself.** You route. The skills and commands do the work. If you catch yourself pulling data from QuickBooks or drafting an email, stop — you're in the wrong lane. -- **Never dump a full menu unprompted.** One recommendation, one sentence why, one confirmation ask. -- **Never skip confirmation.** Always ask before triggering a command. The owner might want something slightly different than what you matched. -- **Never silently route to a broken command.** If a required connector is missing, tell the owner before routing — not after. -- **Adapt to context.** If the owner has run onboarding and their top headache is "cash flow," lead with money commands. If it's "getting more customers," lead with sales commands. The business context makes your routing smarter. diff --git a/small-business/skills/tax-prep/SKILL.md b/small-business/skills/tax-prep/SKILL.md deleted file mode 100644 index fbe93f874..000000000 --- a/small-business/skills/tax-prep/SKILL.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -name: tax-prep -description: Prepares tax-season materials — quarterly estimated tax calculation or year-end 1099 prep — and produces an accountant handoff packet. Accepts optional mode and year arguments. -allowed-tools: Read, WebFetch, Bash ---- - -Run the tax prep workflow using the `tax-season-organizer` skill. Act immediately — the user typed /tax-prep, so skip the discovery phase. - -Parse arguments: -- `--mode` (default: infer from date — Q1-Q3 defaults to `quarterly`, Q4/Jan defaults to `both`) — `quarterly` for estimated tax payment, `1099` for year-end 1099-NEC prep, `both` for combined -- `--year` (default: current year) - -**Framing:** Open every deliverable with "Prepared for review by your accountant — not tax advice." - -## Step 1 — Determine mode - -If `--mode` was not provided: -1. Check the current date. If Oct–Jan, default to `both`. Otherwise default to `quarterly`. -2. Confirm with the owner: "Based on the time of year, I'll prepare [mode]. Want me to do something different?" - -## Step 2 — Quarterly estimated tax (if mode includes quarterly) - -1. Pull YTD Profit & Loss from QuickBooks (Jan 1 through last completed quarter). -2. If QuickBooks is not connected, ask the user to paste net income or upload a CSV. -3. Ask: "How much have you already paid in estimated taxes this year?" -4. Calculate: SE tax, adjusted net income, federal income tax estimate (default 22% bracket), quarterly payment due. -5. State every assumption explicitly — bracket, business type, exclusions. -6. Deliver the formatted estimate with the due date for the current quarter. - -## Step 3 — Year-end 1099 prep (if mode includes 1099) - -1. Pull contractor/vendor payments from all connected sources: QuickBooks, PayPal, Stripe. -2. Aggregate by payee across sources. Flag likely duplicates for human review — never auto-merge. -3. Apply the $600 threshold. Flag near-threshold payees ($400–$599). -4. Check W-9 status in QuickBooks for each flagged payee. -5. Deliver the 1099-NEC candidate list with missing W-9 action items and the PayPal/Stripe 1099-K overlap note. - -## Approval gates - -- **Not tax advice.** State this in every output header. -- **State every assumption.** Bracket, business type, excluded deductions — give the accountant the levers. -- **Don't merge payees automatically.** Flag duplicates for human review. -- **Don't file anything.** Output is prep material only. - -## Output - -End with a next-steps checklist for the accountant: missing W-9s to collect, assumptions to verify, deadlines to hit. diff --git a/small-business/skills/tax-season-organizer/SKILL.md b/small-business/skills/tax-season-organizer/SKILL.md deleted file mode 100644 index 516d8e345..000000000 --- a/small-business/skills/tax-season-organizer/SKILL.md +++ /dev/null @@ -1,211 +0,0 @@ ---- -name: tax-season-organizer -description: > - Prepares tax-season materials for small business owners — framed as deliverables - for their accountant, not tax advice. Two modes: (1) quarterly estimated tax - calculation — pulls YTD net income from QuickBooks and calculates the federal - income tax + self-employment tax liability and quarterly payment due; (2) - year-end 1099 prep — scans QuickBooks, PayPal, and Stripe for contractors paid - over $600, builds a 1099-NEC candidate list with missing W-9 flags, and - produces a plain-English summary a CPA can work from directly. - - Trigger this skill whenever the user mentions: quarterly taxes, estimated tax - payment, how much to set aside for taxes, 1099s, 1099-NEC, year-end tax prep, - contractor payments, W-9s, or any phrase suggesting they are preparing for a - tax deadline or handing materials to an accountant. Also trigger proactively - when a user asks about net profit or YTD income in a context that suggests - they are worried about their tax bill. ---- - -# Tax Season Organizer - -> **Framing:** This skill produces prep material for a CPA, not tax advice. Say so early -> and state every assumption explicitly so the accountant can adjust. - -## Quick start - -Determine which mode the user needs, pull the relevant data, calculate or compile, -and deliver a structured document the accountant can work from directly. - -``` -User: "what do I owe for estimated taxes this quarter?" -→ Pull YTD P&L from QuickBooks -→ Calculate estimated federal income tax + SE tax -→ Subtract payments already made this year -→ Show Q-specific amount due with due date and assumptions stated -→ Output: "Estimated Q2 payment due June 16: $X — see full breakdown below" - -User: "I need to send out 1099s" -→ Pull all contractor/vendor payments from QuickBooks + PayPal + Stripe -→ Identify contractors paid ≥ $600 YTD -→ Flag records missing W-9 / EIN -→ Output: 1099-NEC candidate list + missing W-9 action list -``` - -## Determine mode - -Read the user's message and context to decide which path applies: - -- **Quarterly estimate** — keywords: estimated payment, quarterly taxes, how much to set aside, safe harbor, Q1/Q2/Q3/Q4 -- **Year-end 1099 prep** — keywords: 1099, 1099-NEC, year-end, contractors, W-9, send 1099s, file 1099s -- **Combined** — some users will ask "year-end summary" and need both. Run quarterly last; run 1099 prep first since it drives the most action items. - -If the intent is ambiguous, ask: "Are you looking at your estimated tax payment for this quarter, or are you preparing 1099s for your contractors — or both?" - ---- - -## Path 1: Quarterly estimated tax - -### 1. Pull YTD financials - -Use QuickBooks to pull a Profit & Loss report from January 1 of the current year through the last day of the most recently completed quarter. Capture: -- **Gross revenue** (total income) -- **Total expenses** (operating expenses, COGS, etc.) -- **Net ordinary income** = revenue − expenses - -If QuickBooks is not connected, ask the user to upload a P&L as CSV or paste the key numbers. For field names and query approach, see [reference/connector-queries.md](reference/connector-queries.md). - -### 2. Ask about prior estimated payments - -Before calculating, ask: "How much have you already paid in estimated taxes so far this year?" If the user doesn't know, note that you'll calculate total liability — they can subtract payments themselves or check with their accountant. - -### 3. Calculate estimated liability - -See [reference/calculation-assumptions.md](reference/calculation-assumptions.md) for the full math and the assumptions table you must include in output. - -Short version: -1. **SE tax** = net profit × 0.9235 × 0.153 (then halve it — the deductible half offsets income) -2. **Adjusted net** = net profit − (SE tax / 2) -3. **Federal income tax** = apply the bracket rate appropriate to the user's business type and estimated annual income (default to 22% unless the user tells you their bracket; note this assumption explicitly) -4. **Total annual liability** = federal income tax + SE tax -5. **Quarterly payment** = (total annual liability − payments made) ÷ quarters remaining -6. **Safe harbor check** — note whether the user should verify against prior-year tax (100% of prior year, or 110% if AGI > $150k) - -### 4. State assumptions and deliver output - -Use this output structure: - -Structure the output as a document with these sections in order: - -1. **Header** — H2 with "Estimated tax summary" followed by the quarter and year. - Subline: prepared date and "For review by your accountant." - -2. **YTD snapshot** — Bold lines showing YTD net profit with date range, - estimated annual net profit (annualized from YTD), and assumed business type - (sole proprietor, S-corp, etc. — flag as assumed, not confirmed). - -3. **Self-employment tax** — Show the SE tax calculation: net profit times - 92.35% times 15.3%, and the deductible SE half. - -4. **Federal income tax estimate** — Adjusted net income, assumed bracket - (default 22%, note to confirm with accountant), and the federal estimate. - -5. **Total estimated annual liability** — SE tax plus federal income tax. - -6. **Quarterly payment** — Total liability minus payments already made, divided - by quarters remaining, with the specific dollar amount due and the due date. - -7. **Safe harbor note** — Remind the owner to ensure total payments meet 100% - of prior-year tax (or 110% if AGI exceeded $150k). - -8. **Assumptions** — Bullet list of every assumption: bracket rate, business - structure, state taxes excluded, deductible SE half included, and deductions - not applied (home office, QBI, depreciation). - ---- - -## Path 2: Year-end 1099 prep - -### 1. Pull contractor payments from all sources - -Query each connected source for **all payments made to individuals or businesses for services** in the tax year. Do not include payments for goods, refunds, or internal transfers. - -**QuickBooks — try live connector first, fall back to CSV if needed:** - -1. **Try live connector.** Attempt to pull vendor-level payment records via the QuickBooks MCP. If the connector returns individual payee records with name, amount, and account category, use them directly and skip the CSV step. - -2. **Detect aggregate-only response.** If the MCP returns only category-level totals (e.g. "Contract labor: $7,500" with no payee breakdown), the connector does not yet support vendor-level queries. In this case, prompt the user: - - > "QuickBooks returned summary data only — I need payee-level detail to build your 1099 list. Please export a **Transaction List by Vendor** report (QuickBooks → Reports → Expenses → Transaction List by Vendor, filtered to this tax year) and upload the CSV here. I'll process it automatically." - -3. **Process CSV via Desktop connector.** Map columns: payee name, amount, date, payment method, EIN/SSN status. Follow the same aggregation and threshold logic below regardless of whether data came from the live connector or CSV. - -> **Note for future connector versions:** If the QuickBooks MCP is upgraded to expose vendor payment records directly, step 1 will succeed and the CSV fallback will be skipped automatically. No changes to this skill are needed — the try-first logic handles it. - -For field names and query approach, see [reference/connector-queries.md](reference/connector-queries.md). - -**PayPal:** Pull all "Goods & Services" payments sent. Note: PayPal issues its own 1099-K to contractors above the threshold — flag these separately in output so the accountant can determine whether a 1099-NEC is also needed. - -**Stripe:** Pull all transfers/payouts made to external parties. Same 1099-K caveat as PayPal applies. - -**Desktop/CSV:** If the user uploads a CSV directly (without going through QuickBooks export), map columns: payee name, amount, date, payment method, EIN/SSN status. - -### 2. Aggregate by payee - -Combine across sources and sum payments by individual or business entity. Deduplicate by name (watch for "John Smith" vs "John A. Smith" — flag likely duplicates for human review rather than auto-merging). - -### 3. Apply the $600 threshold - -- **Flag for 1099-NEC:** any payee paid ≥ $600 for services (contractors, freelancers, consultants) -- **Flag for 1099-MISC:** any payee paid ≥ $600 for rent, attorney fees, prizes/awards -- **Near-threshold alert:** flag payees paid $400–$599 — close to the threshold, accountant may want to verify - -Corporations (Inc., Corp., LLC taxed as C or S corp) generally do not need a 1099-NEC — note this but flag for accountant confirmation. - -### 4. Check W-9 status - -For each flagged payee, note whether a W-9 / EIN is on file in QuickBooks. Mark as: -- ✅ W-9 on file (EIN/SSN recorded in QuickBooks) -- ⚠️ Missing — W-9 not on file; must collect before filing -- ❓ Unknown — cannot determine from available data - -### 5. Deliver the 1099 prep package - -Use this structure: - -Structure the 1099 prep output as a document with these sections: - -1. **Header** — H2 with "1099 prep list" and the tax year. Subline: prepared - date, "For review by your accountant," and "Not tax advice." - -2. **Summary** — Bullet counts: total contractors paid, number requiring - 1099-NEC (at or above $600 for services), number missing W-9 (with filing - deadline note for Jan 31), and number near-threshold flagged for review. - -3. **1099-NEC candidates table** — Columns: payee name, total paid, data - sources, W-9 status (on file / missing / unknown), and notes. Flag any - payee paid via PayPal or Stripe with a note that the platform may issue - its own 1099-K. - -4. **Missing W-9 action list** — Numbered list of contractors who need to - provide a W-9 before filing, with amounts paid and a reminder to request - the form. - -5. **Near-threshold table** — Payees paid $400-$599 flagged for accountant - review, with a note to verify no additional payments were missed. - -6. **Payment processor note** — Explain that PayPal and Stripe issue their own - 1099-K forms and the accountant should confirm whether a 1099-NEC is also - needed for contractors paid exclusively through those platforms. - -7. **Next steps checklist** — Action items for the accountant: collect missing - W-9s, confirm unknowns, review near-threshold payees, verify corporation - exemptions, confirm 1099-K overlap handling, file by January 31. - ---- - -## Guardrails - -- **Not tax advice.** Open every deliverable with this: "Prepared for review by your accountant — not tax advice." Include it in the document header, not just in chat. -- **State every assumption.** If you assumed a 22% bracket, say so. If you excluded state taxes, say so. The accountant will adjust; give them the levers. -- **Don't merge payees automatically.** Flag likely duplicates for human review. -- **Don't file anything.** The output is prep material. Filing is out of scope. -- **Corporation exemption is a judgment call.** Note it; don't auto-exclude. - -## Reference files - -- [reference/calculation-assumptions.md](reference/calculation-assumptions.md) — full tax math, bracket table, and SE tax walkthrough -- [reference/connector-queries.md](reference/connector-queries.md) — how to pull data from QuickBooks, PayPal, and Stripe -- [reference/gotchas.md](reference/gotchas.md) — Good / Bad patterns for common failure modes -- [reference/examples/quarterly-estimate.md](reference/examples/quarterly-estimate.md) — worked quarterly estimate example -- [reference/examples/year-end-1099.md](reference/examples/year-end-1099.md) — worked year-end 1099 prep example diff --git a/small-business/skills/tax-season-organizer/reference/calculation-assumptions.md b/small-business/skills/tax-season-organizer/reference/calculation-assumptions.md deleted file mode 100644 index 99f74449b..000000000 --- a/small-business/skills/tax-season-organizer/reference/calculation-assumptions.md +++ /dev/null @@ -1,103 +0,0 @@ -# Tax Calculation Assumptions - -This file documents the math and assumptions used in quarterly estimated tax calculations. -Always surface these assumptions in the output so the accountant can adjust. - ---- - -## Self-employment (SE) tax - -SE tax applies to sole proprietors, single-member LLCs, and partners. It does **not** apply -to S-corp owners on their W-2 wages (only on distributions — and even that varies). - -**Formula:** -``` -SE tax base = net profit × 92.35% - (the 7.65% reduction accounts for the employer-equivalent deduction) -SE tax = SE tax base × 15.3% - (12.4% Social Security + 2.9% Medicare) - Note: Social Security only applies up to the wage base ($176,100 for 2025) -Deductible half = SE tax ÷ 2 ← reduces taxable income -``` - -**Example:** -``` -Net profit: $80,000 -SE tax base: $80,000 × 92.35% = $73,880 -SE tax: $73,880 × 15.3% = $11,304 -Deductible half: $11,304 ÷ 2 = $5,652 -``` - ---- - -## Federal income tax estimate - -### Business types and how they're taxed - -| Business type | How income is taxed | SE tax applies? | -|--------------|---------------------|-----------------| -| Sole proprietor / single-member LLC | Schedule C → personal 1040 | Yes | -| Partnership / multi-member LLC | Schedule K-1 → personal 1040 | Yes (on earned income) | -| S-corporation | W-2 wages + K-1 distributions → 1040 | On wages only | -| C-corporation | Separate corporate return | No (payroll taxes instead) | - -Default assumption: **sole proprietor** unless the user specifies otherwise. Always state this. - -### Federal income tax brackets (2025, single filer) - -| Taxable income | Rate | -|---------------|------| -| $0 – $11,925 | 10% | -| $11,926 – $48,475 | 12% | -| $48,476 – $103,350 | 22% | -| $103,351 – $197,300 | 24% | -| $197,301 – $250,525 | 32% | -| $250,526 – $626,350 | 35% | -| Over $626,350 | 37% | - -**For a rough estimate**, apply a single effective rate. Use 22% as the default for most SMB -owners unless the user gives you more info. Note this assumption explicitly. - -**Adjusted net income** (for tax calculation): -``` -Adjusted net = net profit − (SE tax ÷ 2) − QBI deduction (if applicable) -``` -The QBI deduction (up to 20% of qualified business income) is significant for many SMBs — -note that it's not included in the base estimate and the accountant should apply it. - ---- - -## Quarterly due dates (2025) - -| Quarter | Period covered | Payment due | -|---------|---------------|-------------| -| Q1 | Jan 1 – Mar 31 | April 15, 2025 | -| Q2 | Apr 1 – May 31 | June 16, 2025 | -| Q3 | Jun 1 – Aug 31 | September 15, 2025 | -| Q4 | Sep 1 – Dec 31 | January 15, 2026 | - ---- - -## Safe harbor rule - -To avoid underpayment penalties, total estimated payments must be at least the lesser of: -- **100%** of prior year tax liability (or **110%** if prior year AGI exceeded $150,000) -- **90%** of current year tax liability - -Always note this in output. The user's accountant should confirm prior-year tax figures. - ---- - -## What the estimate does NOT include - -Always list these exclusions in every output: -- State and local income taxes -- QBI deduction (Section 199A — can reduce federal tax by up to 20%) -- Home office deduction -- Vehicle deductions -- Depreciation / Section 179 -- Retirement contributions (SEP-IRA, Solo 401k) — can significantly reduce SE tax base -- Health insurance deduction for self-employed -- Prior-year net operating loss carryforward - -These can meaningfully reduce the final number. Flag them so the accountant applies them. diff --git a/small-business/skills/tax-season-organizer/reference/connector-queries.md b/small-business/skills/tax-season-organizer/reference/connector-queries.md deleted file mode 100644 index 0786be7a0..000000000 --- a/small-business/skills/tax-season-organizer/reference/connector-queries.md +++ /dev/null @@ -1,93 +0,0 @@ -# Connector Query Guide - -How to pull the right data from each connector for each mode. - ---- - -## QuickBooks — Quarterly mode (P&L) - -Pull a **Profit & Loss** report for the period January 1 through the last day of the most recently completed quarter. - -Key fields to capture: -- `Total Income` (gross revenue) -- `Total Expenses` (all operating expenses) -- `Net Ordinary Income` (= income − expenses; this is the basis for tax calculation) - -If QuickBooks returns multiple income/expense categories, sum them. You want the single -bottom-line net profit figure. - -**If the user's QuickBooks is on cash basis**, use that. If accrual, note it in output — -the accountant should confirm which basis to use for estimated taxes. - ---- - -## QuickBooks — Year-end mode (contractor payments) - -Pull all **bill payments and checks** to vendors for the full tax year (Jan 1 – Dec 31). - -Filter for: -- Vendor type = "1099 eligible" (if the user has tagged vendors in QuickBooks) -- OR any vendor whose category is: consulting, contract labor, subcontractor, freelance, design, legal, accounting, marketing, staffing - -For each vendor record, capture: -- Vendor name (legal name if available) -- EIN / SSN (from vendor profile — indicates W-9 on file) -- Total payments for the year -- Payment dates and amounts (for cross-reference) -- Vendor type / 1099 eligibility flag - -**Common issue:** Many QuickBooks users do not tag vendors as 1099-eligible. If -`1099 eligible` returns few or no results, pull ALL vendors with significant payment -totals and let the user / accountant classify them. Note this in output. - ---- - -## PayPal — Year-end mode - -Pull all **"Goods & Services" payments sent** (not received) for the tax year. - -Key fields: -- Recipient name / email -- Total amount per recipient (aggregate for the year) -- Transaction type = "Payment" or "Business Payment" -- Date - -**Exclude:** personal payments ("Friends & Family"), refunds, disputes, transfers -to own accounts. - -**1099-K note:** PayPal issues its own 1099-K to any recipient who receives ≥ $600 -in goods & services payments. Flag this in output — the accountant determines whether -the business must also issue a 1099-NEC or can rely on PayPal's 1099-K. - ---- - -## Stripe — Year-end mode - -Pull all **transfers to external accounts** (payouts to contractors, not payouts to the -business owner's own bank). - -Key fields: -- Recipient name / ID -- Total transferred per recipient for the year -- Payment description / metadata (to confirm these are for services) - -**Exclude:** Stripe payouts to the business's own bank account. - -**1099-K note:** Same as PayPal — Stripe issues 1099-K to contractors above the -threshold. Flag and defer to accountant. - ---- - -## Desktop / CSV fallback - -If any connector is unavailable, ask the user to: -1. Export a P&L from QuickBooks as CSV (Reports → Profit & Loss → Export) -2. Export a transaction history from PayPal (Activity → Download → CSV) -3. Export a payout report from Stripe (Dashboard → Payouts → Export) - -When reading uploaded CSVs, look for these columns (names vary by export): -- P&L: `Description`, `Amount`, `Type` (Income / Expense) -- PayPal: `Name`, `Type`, `Amount`, `Date`, `Transaction ID` -- Stripe: `Description`, `Amount`, `Created date`, `Status` - -If columns don't match, ask the user to identify the payee name and amount columns. diff --git a/small-business/skills/tax-season-organizer/reference/examples/quarterly-estimate.md b/small-business/skills/tax-season-organizer/reference/examples/quarterly-estimate.md deleted file mode 100644 index cdcdf980f..000000000 --- a/small-business/skills/tax-season-organizer/reference/examples/quarterly-estimate.md +++ /dev/null @@ -1,92 +0,0 @@ -# Worked Example: Quarterly Estimated Tax - -**Scenario:** Sarah runs a freelance graphic design business as a sole proprietor. -She asks: "How much should I pay in estimated taxes for Q2?" - ---- - -## Step 1: Pull YTD P&L from QuickBooks - -QuickBooks P&L — January 1 through March 31, 2025: -- Gross income: $48,000 -- Operating expenses: $12,500 (software, equipment, marketing) -- Net ordinary income: **$35,500** - ---- - -## Step 2: Ask about prior payments - -> "Have you made any estimated tax payments so far this year?" - -Sarah: "I paid $2,000 in April for Q1." - ---- - -## Step 3: Calculate - -``` -YTD net profit (Q1): $35,500 -Annualized net profit: $35,500 × 4 = $142,000 ← rough annualization - -Self-employment tax: - SE base: $142,000 × 92.35% = $131,137 - SE tax: $131,137 × 15.3% = $20,064 - (Soc. Sec. cap at $176,100 — not hit, full rate applies) - Deductible half: = $10,032 - -Federal income tax: - Adjusted net: $142,000 − $10,032 = $131,968 - Bracket: 22% (estimated; actual may vary with household income) - Federal tax: $131,968 × 22% = $29,033 - -Total estimated annual liability: - SE tax + federal = $20,064 + $29,033 = $49,097 - -Quarterly breakdown: - Annual liability: $49,097 - Payments made (Q1): −$2,000 - Remaining: $47,097 ÷ 3 remaining quarters = $15,699 per quarter - Q2 payment due June 16: ~$15,700 -``` - ---- - -## Step 4: Output delivered to Sarah - -``` -## Estimated tax summary — Q2 2025 -Prepared April 24, 2025 · For review by your accountant · Not tax advice - -**YTD net profit (Jan 1 – Mar 31):** $35,500 -**Estimated annual net profit:** $142,000 (annualized from Q1 actual) -**Business type assumed:** Sole proprietor (confirm with accountant) - -### Self-employment tax -$142,000 × 92.35% × 15.3% = $20,064 -Deductible SE half: $10,032 - -### Federal income tax estimate -Adjusted net income: $131,968 -Assumed bracket: 22% (confirm with accountant — household income affects this) -Federal income tax estimate: $29,033 - -### Total estimated annual liability -$20,064 + $29,033 = **$49,097** - -### Q2 payment -Annual liability: $49,097 -Less Q1 payment made: −$2,000 -Remaining: $47,097 ÷ 3 quarters = **~$15,700 due by June 16, 2025** - -### Safe harbor note -To avoid underpayment penalty: ensure total 2025 payments ≥ 100% of your 2024 -tax (or 110% if 2024 AGI > $150,000). Ask your accountant for that figure. - -### Assumptions — review with your accountant -- Federal bracket: 22% (effective rate may differ) -- Business structure: sole proprietor (assumed) -- Annualization: Q1 × 4 — income may be seasonal -- State taxes: not included -- QBI deduction (up to 20%): not applied — could reduce federal tax significantly -- Retirement contributions, home office, vehicle: not applied -``` diff --git a/small-business/skills/tax-season-organizer/reference/examples/year-end-1099.md b/small-business/skills/tax-season-organizer/reference/examples/year-end-1099.md deleted file mode 100644 index c7d8f57bc..000000000 --- a/small-business/skills/tax-season-organizer/reference/examples/year-end-1099.md +++ /dev/null @@ -1,102 +0,0 @@ -# Worked Example: Year-End 1099 Prep - -**Scenario:** Marcus owns a digital marketing agency. He asks: "I need to send out -my 1099s — can you pull together a list of who needs one?" - ---- - -## Step 1: Pull contractor payments from all sources - -**QuickBooks** (Jan 1 – Dec 31, 2024): - -| Vendor | Total paid | 1099 eligible? | EIN/SSN on file? | -|--------|-----------|----------------|-----------------| -| Jenna Torres (copywriter) | $8,400 | Yes | Yes | -| Apex Web Solutions | $15,200 | Yes | Yes | -| Bob Nguyen | $550 | No | No | -| FedEx | $320 | No | No | -| Spark Digital Inc. | $6,000 | Yes | Yes | - -**PayPal** (goods & services payments sent, 2024): - -| Recipient | Total sent | Notes | -|-----------|-----------|-------| -| jenna.torres@email.com | $1,200 | Likely same as QuickBooks vendor | -| designbymike@gmail.com | $2,100 | Not in QuickBooks | -| Bob Nguyen | $480 | | - -**Stripe** (not connected — skipped) - ---- - -## Step 2: Aggregate and deduplicate - -Cross-referencing QuickBooks and PayPal: - -| Payee | QuickBooks | PayPal | Total | Notes | -|-------|-----------|--------|-------|-------| -| Jenna Torres | $8,400 | $1,200 | **$9,600** | Same person — email match | -| Apex Web Solutions | $15,200 | — | **$15,200** | | -| Spark Digital Inc. | $6,000 | — | **$6,000** | | -| Design by Mike (Mike unknown) | — | $2,100 | **$2,100** | Not in QuickBooks; payee name unknown | -| Bob Nguyen | $550 | $480 | **$1,030** | Combined > $600; flagged | -| FedEx | $320 | — | $320 | Below threshold; goods/shipping — exempt | - ---- - -## Step 3: Apply $600 threshold and W-9 check - -- Jenna Torres: $9,600 ✅ → **1099-NEC required** · W-9 on file (EIN recorded in QB) -- Apex Web Solutions: $15,200 ✅ → **1099-NEC candidate** · W-9 on file · Note: may be a corp (confirm) -- Spark Digital Inc.: $6,000 ✅ → **1099-NEC candidate** · W-9 on file · "Inc." — likely corp exempt (confirm) -- Design by Mike: $2,100 ✅ → **1099-NEC required** · W-9 not on file — must collect -- Bob Nguyen: $1,030 ✅ → **1099-NEC required** · W-9 not on file — must collect -- FedEx: $320 → below threshold; goods/shipping — not required - ---- - -## Step 4: Output delivered to Marcus - -``` -## 1099 prep list — 2024 -Prepared January 10, 2025 · For review by your accountant · Not tax advice - -### Summary -- Contractors paying: 5 candidates identified -- Require 1099-NEC (≥$600 for services): 5 -- Missing W-9: 2 — action required before January 31 -- Corporation exemption review needed: 2 (Apex, Spark) -- PayPal overlap: 2 contractors (Jenna Torres, Design by Mike) — see note below - -### 1099-NEC candidates - -| Payee | Total paid | Source(s) | W-9 status | Notes | -|-------|-----------|-----------|------------|-------| -| Jenna Torres | $9,600 | QB + PayPal | ✅ EIN on file | PayPal also paid $1,200 — confirm 1099-K handling | -| Apex Web Solutions | $15,200 | QuickBooks | ✅ EIN on file | "Solutions" — may be corp; confirm exemption with accountant | -| Spark Digital Inc. | $6,000 | QuickBooks | ✅ EIN on file | "Inc." — likely corp-exempt; confirm with accountant | -| Design by Mike | $2,100 | PayPal only | ⚠️ Missing W-9 | Full name unknown — obtain before filing | -| Bob Nguyen | $1,030 | QB + PayPal | ⚠️ Missing W-9 | Combined QB ($550) + PayPal ($480) = $1,030 | - -### Missing W-9 action list -These contractors must provide a W-9 before you can file: - -1. **Design by Mike** — paid $2,100 via PayPal. Obtain full legal name and W-9. - IRS W-9 form: https://www.irs.gov/pub/irs-pdf/fw9.pdf -2. **Bob Nguyen** — paid $1,030 (QB + PayPal). W-9 not on file for either source. - -### Payment processor note (PayPal) -Jenna Torres and Design by Mike received payments via PayPal. PayPal issues its own -1099-K to contractors receiving ≥$600 in goods & services payments. Your accountant -should confirm whether you still need to issue a 1099-NEC for these two, or whether -PayPal's 1099-K covers the reporting obligation. - -### Next steps for your accountant -- [ ] Collect W-9 from Design by Mike (full legal name needed first) -- [ ] Collect W-9 from Bob Nguyen -- [ ] Confirm corporation exemption for Apex Web Solutions -- [ ] Confirm corporation exemption for Spark Digital Inc. -- [ ] Confirm 1099-K overlap handling for Jenna Torres and Design by Mike (PayPal) -- [ ] File 1099-NECs by January 31, 2025 -- [ ] File 1096 transmittal with IRS by January 31, 2025 -``` diff --git a/small-business/skills/tax-season-organizer/reference/gotchas.md b/small-business/skills/tax-season-organizer/reference/gotchas.md deleted file mode 100644 index cdc215c05..000000000 --- a/small-business/skills/tax-season-organizer/reference/gotchas.md +++ /dev/null @@ -1,104 +0,0 @@ -# Good / Bad Patterns - -Common failure modes and how to avoid them. - ---- - -## Calculations - -**BAD:** Apply 22% to gross revenue. -``` -Gross revenue: $120,000 -Tax estimate: $120,000 × 22% = $26,400 ← wildly wrong -``` - -**GOOD:** Apply bracket rate to net profit AFTER SE tax deduction. -``` -Gross revenue: $120,000 -Expenses: $45,000 -Net profit: $75,000 -SE tax: $75,000 × 92.35% × 15.3% = $10,628 -Deductible ½: $5,314 -Adjusted net: $75,000 − $5,314 = $69,686 -Fed. tax est.: $69,686 × 22% = $15,331 -Total: $10,628 + $15,331 = $25,959 -``` - ---- - -## Assumptions - -**BAD:** State a dollar figure without any context. -> "Your Q2 estimated payment is $6,500." - -**GOOD:** State the figure with the assumptions table. -> "Based on 22% federal bracket, sole proprietor structure, and no prior-year -> safe harbor data: **Q2 payment ≈ $6,500**. State taxes not included. -> QBI deduction not applied. Review with your accountant." - ---- - -## 1099 threshold - -**BAD:** Only flag vendors with a QuickBooks "1099 eligible" tag. -Many QuickBooks users never set this flag. Silently missing contractors is worse -than over-flagging. - -**GOOD:** Pull ALL vendors with ≥ $600 in payments, then note which ones are -1099-eligible per QuickBooks and which are flagged by category heuristics. -Let the accountant make the final call. - ---- - -## Payee deduplication - -**BAD:** Auto-merge "Bob Smith" and "Robert Smith Design LLC" because they sound similar. -These could be different people or the same person's sole-prop vs. LLC. - -**GOOD:** Flag likely duplicates for human review. -> "These look like they may be the same person — confirm before filing: -> Bob Smith ($1,200) | Robert Smith Design ($800) — combined would be $2,000" - ---- - -## PayPal / Stripe 1099-K overlap - -**BAD:** Instruct the user to file 1099-NECs for all contractors paid via PayPal. - -**GOOD:** Flag the overlap and defer to the accountant. -> "Contractors paid via PayPal or Stripe may already receive a 1099-K from those -> platforms. Your accountant should confirm whether you also need to issue a -> 1099-NEC — double-reporting is an issue some accountants handle differently." - ---- - -## Corporation exemption - -**BAD:** Automatically exclude "Smith Consulting Inc." from the 1099 list because it -has "Inc." in the name. - -**GOOD:** Flag it for the accountant with a note. -> "Smith Consulting Inc. — $4,500. Corporations are generally exempt from 1099-NEC -> requirements, but confirm with your accountant (S-corps and some professional corps -> are exceptions)." - ---- - -## Tax advice boundary - -**BAD:** "You should use a SEP-IRA to reduce your tax bill." - -**GOOD:** "Your accountant may recommend a SEP-IRA or Solo 401(k) contribution to -reduce taxable income — these can significantly change the estimate above." - -The skill surfaces options; the accountant advises. - ---- - -## S-corp owners - -**BAD:** Apply SE tax to an S-corp owner's full income. - -**GOOD:** Note that SE tax applies only to W-2 wages for S-corp shareholders, not to -K-1 distributions — and ask the user to confirm their business structure before -running calculations. If unsure, default to sole prop math and note the assumption. diff --git a/small-business/skills/ticket-deflector/SKILL.md b/small-business/skills/ticket-deflector/SKILL.md deleted file mode 100644 index 00b90a1c3..000000000 --- a/small-business/skills/ticket-deflector/SKILL.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -name: ticket-deflector -description: > - Reads a forwarded customer email or ticket, pulls order/refund status from - PayPal and account history from HubSpot, drafts a tone-matched reply in the - owner's writing voice, and can issue a PayPal refund with explicit owner - approval. Use when the user says "draft a response," "answer this customer," - "where's my order," or "I want a refund." -compatibility: "Requires PayPal, HubSpot, Mail. Optional: Intercom, Square." ---- - -# Ticket Deflector - -## Quick start - -Forward or paste a customer email — Claude pulls order status from PayPal, looks up the customer in HubSpot, and drafts a reply in the owner's voice. If a refund is needed, it stages the details and waits for explicit approval before issuing anything. - -``` -User: "answer this customer" [forwards email] -→ Extract customer email + issue from thread -→ Pull PayPal transaction status -→ Pull HubSpot contact history -→ Draft reply in owner's voice -→ Owner approves draft → send or stage -→ If refund needed: approval prompt → owner confirms → issue -``` - -## Workflow - -1. **Read the customer message.** Accept a forwarded Gmail thread or pasted text. Extract: customer email address, name, order or transaction ID (if present), and the core issue — refund request, order status question, or general complaint. If multiple issues are present, address them in the order they appear. - -2. **Pull order status from PayPal.** Search PayPal transactions by customer email or transaction ID. Capture: amount, date, status, and whether a refund has already been issued. If PayPal is not connected, note it in the draft and continue. If no transaction matches, flag it — do not guess at a match. - - **PayPal rate limit:** If the customer provided a transaction ID, use it — single-record lookups avoid throttling entirely. If searching by email, use a 7-day window (not 30 days). PayPal's transaction list endpoint throttles aggressively on wide date-range queries; back-to-back tickets in the same session will hit this limit if the window is too broad. - - If Intercom is connected, check for open support tickets from this customer. - - If Square is connected, check Square transaction history as a secondary source. - - If multiple transactions match, surface all of them and ask the owner which one applies before drafting. - -3. **Pull customer history from HubSpot.** Search contacts by email address. Pull: lifecycle stage, notes, open deals, and recent activity. If no contact exists, note it and offer to create one after the reply is sent — do not create during the response workflow. - -4. **Draft the reply.** Write in the owner's writing voice. Adjust tone to fit the issue type: - - Refund request → empathetic, clear, action-oriented - - Order status question → factual, reassuring - - General complaint → acknowledge, explain, offer resolution - Flag any data gaps inline in the draft with a bracketed note (e.g., *[Note: No PayPal transaction found — verify order ID before sending]*) so the owner sees the gap before sending. For a worked example, see [reference/examples/respond-refund-request.md](reference/examples/respond-refund-request.md). For common pitfalls, see [reference/gotchas.md](reference/gotchas.md). - -5. **Approval gate — owner reviews the draft.** Present the full draft. Do not send or stage it until the owner approves. The owner may edit freely before approving. - -6. **Approval gate — refund issuance.** If a refund is warranted, surface a dedicated confirmation prompt after the owner approves the draft: - - > *"Issue refund of $[amount] to [customer name] ([email]) for transaction [ID]? Reply Y to proceed."* - - Wait for explicit confirmation. If the owner's reply is anything other than a clear yes, stop and ask what they'd like to do instead. - -7. **Send or stage the reply.** After draft approval, ask the owner: send via Gmail now, or save as a draft? Execute their choice. Then log the interaction as a note on the HubSpot contact timeline. - -8. **Report.** One short paragraph: reply sent or staged, refund issued or not, HubSpot note logged. - -## Approval gates - -- **Never issue a PayPal refund without explicit owner confirmation** — always show amount, customer name, email, and transaction ID before executing. -- **Never send the reply without owner review.** Always present the full draft first. -- **Never create a HubSpot contact during the response flow.** Offer it afterward. -- **Never auto-select a PayPal transaction.** If multiple match, surface them all and let the owner choose. -- **Never fabricate order details.** If PayPal has no record, say so inline in the draft — do not invent a status. - -## Reference - -- [reference/gotchas.md](reference/gotchas.md) — Good / Bad patterns for tone, PayPal lookup, and ambiguous refund scenarios -- [reference/examples/respond-refund-request.md](reference/examples/respond-refund-request.md) — worked example: refund request with PayPal transaction found diff --git a/small-business/skills/ticket-deflector/reference/examples/respond-refund-request.md b/small-business/skills/ticket-deflector/reference/examples/respond-refund-request.md deleted file mode 100644 index 6607640a5..000000000 --- a/small-business/skills/ticket-deflector/reference/examples/respond-refund-request.md +++ /dev/null @@ -1,77 +0,0 @@ -# Example: Refund request — PayPal transaction found - -**Scenario:** A customer emails saying their product arrived damaged and they want a full refund. The owner forwards the email and says "answer this customer." - ---- - -## Customer email (forwarded) - -> **Subject:** Damaged product — need refund -> -> Hi, I ordered a cutting board set last month and it arrived cracked. I'd like a full refund please. My order number is PP-3847-XXXX. -> -> — Sarah M. - ---- - -## Step 2 — PayPal lookup result - -Found 1 transaction matching sarah.m@email.com: - -- **Transaction ID:** PP-3847-XXXX -- **Amount:** $64.00 -- **Date:** 2026-03-28 -- **Status:** Completed -- **Refund issued:** No - ---- - -## Step 3 — HubSpot lookup result - -Contact found: Sarah M. (sarah.m@email.com) -- Lifecycle stage: Customer -- Prior orders: 2 -- Notes: "Returning customer — sent holiday promo Dec 2025." - ---- - -## Step 4 — Draft reply (presented to owner for review) - -> **Subject:** Re: Damaged product — need refund -> -> Hi Sarah, -> -> So sorry to hear your cutting board set arrived cracked — that's definitely not okay. I've pulled up your order and I'm issuing a full refund of $64.00. You should see it back on your original payment method within 3–5 business days. -> -> Thanks for letting me know, and I appreciate your patience. Really sorry about this. -> -> [Owner name] - ---- - -## Step 5 — Owner approves draft (no edits) - ---- - -## Step 6 — Refund approval prompt - -> *"Issue refund of $64.00 to Sarah M. (sarah.m@email.com) for transaction PP-3847-XXXX? Reply Y to proceed."* - -Owner replies: **Y** - -→ Refund issued via PayPal. - ---- - -## Step 7 — Send + HubSpot note - -Reply sent via Gmail. - -HubSpot note logged on Sarah M.'s contact: -> "Ticket Deflector — 2026-04-23: Customer reported damaged product. Full refund of $64.00 issued via PayPal (PP-3847-XXXX). Reply sent via email." - ---- - -## Step 8 — Report - -> Reply sent to Sarah M. · Refund of $64.00 issued (PP-3847-XXXX) · HubSpot note logged. diff --git a/small-business/skills/ticket-deflector/reference/gotchas.md b/small-business/skills/ticket-deflector/reference/gotchas.md deleted file mode 100644 index 9545f9919..000000000 --- a/small-business/skills/ticket-deflector/reference/gotchas.md +++ /dev/null @@ -1,57 +0,0 @@ -# Gotchas — ticket-deflector - -Edge cases that caused problems in testing or review. - ---- - -## Gotcha: Matching the owner's voice, not a generic "professional" tone - -**Why it matters:** The value of this skill is that responses sound like the owner wrote them. A bland corporate draft gets rewritten from scratch — wasted effort. - -### ✗ Bad - -> Dear Customer, -> -> Thank you for reaching out. We apologize for any inconvenience and are committed to resolving your issue in a timely manner. Please allow 3–5 business days for processing. -> -> Sincerely, Customer Support - -### ✓ Good - -Draft in the owner's actual register. If no prior emails from the owner are available to reference, ask: *"What's your usual tone — formal, casual, or somewhere in between?"* A short, direct owner gets a short direct draft. A warm, chatty owner gets warmth and their punctuation quirks preserved. - ---- - -## Gotcha: Flagging data gaps inline, not at the end - -**Why it matters:** If PayPal has no matching transaction and the draft says "your refund of $X is being processed," the owner will send a false claim. Data gaps must be visible at the point they affect the message. - -### ✗ Bad - -Draft the reply as if all data is available, then add a footnote: "Note: I couldn't find a PayPal transaction." - -### ✓ Good - -Insert the gap notice inside the draft at the exact sentence where it matters: - -> Hi Sarah, thanks for reaching out. I've looked into your order *[Note: No PayPal transaction found for this email — verify order ID before sending]* and want to get this sorted. - -The owner sees the problem before clicking send. - ---- - -## Gotcha: Multiple PayPal transactions for the same customer - -**Why it matters:** A customer with two orders — one refunded, one not — will break a simple "most recent" lookup and produce the wrong draft. - -### ✗ Bad - -Auto-pick the most recent transaction and proceed without telling the owner. - -### ✓ Good - -Surface all matching transactions and pause: - -> *"Found 2 PayPal transactions for this customer: (1) $49.00 · 2026-03-14 · Completed · (2) $129.00 · 2026-04-01 · Completed. Which one is this about?"* - -Wait for the owner to confirm before writing the draft.