binderclip

name

binderclip

description

Runs business analytics pipelines (SEO/GEO audit, finance dashboard, sales outreach, audience personas, funnel CRO, ambient watchers) that stream results to a live dashboard at http://localhost:3500. Executes one pack at a time (marketing, finance, sales, audience, funnels, watchers) or all five analytics packs via run-all. Uses real data from WebFetch, WebSearch, Stripe, Open PageRank, DataForSEO, and Playwright; the watchers pack uses the Monitor tool to poll external sources (Lighthouse scores, competitor pages, Stripe churn, brand mentions, log files, uptime endpoints) and react when conditions fire. Use when the user runs /marketing, /finance, /sales, /audience, /funnels, /run-all, /action-plan, /watch, or any /pack-skill command, or asks to audit a website's SEO, analyze MRR from Stripe, generate cold outreach, build customer personas, audit a signup funnel, or set up ambient watching of any external signal in a repo containing a packs/ directory.

Binderclip Router

Business analytics command center. Binderclip is a dumb event relay (Hono server on :3500) that renders React cards from POSTed events. This skill routes requests to one of six packs — marketing, finance, sales, audience, funnels, watchers — and defines the shared workflow every pack follows.

Each pack is a sequence of skills that POST events as data is discovered, so the dashboard fills in progressively rather than all at the end. The watchers pack is different: instead of running once and finishing, it starts a background Monitor that streams events as external conditions change ("ambient mode").

Mode routing

Parse the user's invocation to pick the pack. Every analytics pack has a full pipeline (end-to-end) and individual skills that can be invoked one at a time.

Invocation	Pack	Arguments	Notes
/marketing <url>	marketing	<url>	SEO/GEO audit, competitors, AI visibility, content
/finance	finance	—	Reads STRIPE_API_KEY from .env.local
/sales <url>	sales	<url>	Pipeline, cold email, enablement
/audience <url>	audience	<url>	Personas, segmentation, research
/funnels <url>	funnels	<url>	Page/signup/pricing CRO, churn
/run-all <url>	all five analytics	<url>	Sequential: marketing → finance → sales → audience → funnels
/watch <type> <target>	watchers	<type> <target>	Starts a persistent Monitor. Types: lighthouse, competitor, stripe-churn, uptime, mentions, log, ai-crawler, stripe-payment-health, stripe-new-signup
/<pack>-skill <skill> <url>	single skill	<skill-name> <url>	Runs one skill from a pack
/action-plan <pack | all>	aggregator	<pack | all>	Ranked findings from completed packs
(empty or unrecognized)	—	—	Show the discovery menu below

Discovery menu

When no recognized invocation is provided:

Binderclip — Business Analytics Command Center

Full pipelines (stream to http://localhost:5173):
  /marketing <url>    SEO/GEO audit + competitors + content ideas
  /finance            MRR, billing, forecast, pricing strategy
  /sales <url>        Pipeline, cold email, enablement
  /audience <url>     Personas, research, free-tool strategy
  /funnels <url>      Page/signup/pricing CRO, churn prevention
  /run-all <url>      All five analytics packs in sequence

Ambient watchers (keep running in the background):
  Generic:
    /watch lighthouse <url>           Poll Lighthouse score, fire on regressions
    /watch competitor <url>           Hash a page, fire on change
    /watch uptime <url>               Curl a health endpoint, fire on 5xx/timeout
    /watch mentions "<brand>"         Poll for new brand mentions
    /watch log <path> [pattern]       Tail a local log, fire on matching lines

  Pack-aligned (each maps to an analytics pack for follow-up investigation):
    /watch ai-crawler <url>           Watch robots.txt AI crawler access    → marketing
    /watch stripe-churn [threshold]   Count cancellations, fire on spike    → finance/funnels
    /watch stripe-payment-health [t]  Count failed charges, fire on spike   → finance
    /watch stripe-new-signup          Fire on each new subscription         → sales

Single skills:
  /marketing-skill <skill> <url>
  /finance-skill <skill>
  /sales-skill <skill> <url>
  /audience-skill <skill> <url>
  /funnels-skill <skill> <url>

Aggregation:
  /action-plan <pack | all>

Prereq: server must be running (bash scripts/start-server.sh)

Standard analytics pack workflow

Every analytics pack pipeline follows this exact structure. Copy this checklist and check items off as you progress:

Pack Progress:
- [ ] Step 1: Read pack agent file (packs/<pack>/agent.md)
- [ ] Step 2: Read pipeline order (packs/<pack>/pack.json)
- [ ] Step 3: For each skill in pipeline order:
    - [ ] Read packs/<pack>/skills/<skill>.md
    - [ ] POST running event
    - [ ] Execute the skill's "## What to do" with real data
    - [ ] DELETE running event
    - [ ] POST completed events progressively
    - [ ] Validate (see Validation loop below)
- [ ] Step 4: POST a pack-level completed summary event (optional)

Step 1 — Read the pack agent file. packs/<pack>/agent.md defines the subagent role, lists tools, documents event types, and lists the skills in the pack with their expected outputs. Load this before any skill.

Step 2 — Read pipeline order. packs/<pack>/pack.json has a pipeline array listing skills in execution order. Respect it — later skills may reference context emitted by earlier ones (especially the product_context generic event from marketing's audit-site, which other packs consume).

Step 3 — For each skill. Read the full skill playbook before executing. Each playbook specifies inputs, research steps (WebFetch, WebSearch, Playwright, curl to Stripe, etc.), calculations, and the exact JSON event templates to POST.

Step 4 — Pack completion. Optional: POST a final pack-level summary event. Most packs skip this; the UI uses skill-level completed events to track progress.

Watcher pack workflow

The watchers pack is structurally different. A watcher skill starts a Monitor invocation and stays resident in the conversation; it does not "run and finish."

Watcher Progress:
- [ ] Step 1: Verify server is reachable (GET http://localhost:3500/health or HEAD /)
- [ ] Step 2: Read packs/watchers/skills/<skill>.md for trigger rules and event schema
- [ ] Step 3: POST a "watcher_started" event so the dashboard shows it's active
- [ ] Step 4: Start a Monitor with the bundled script from packs/watchers/skills/scripts/
- [ ] Step 5: React to each line Monitor emits — parse, validate, POST a "watcher_fired" event, optionally trigger the relevant analytics pack to investigate
- [ ] Step 6: Continue indefinitely; user stops via TaskStop or session end

Watchers use only existing event component types (stat_grid, metric_grid, data_table, content_preview, generic) so no UI changes are required. The watcher_started and watcher_fired events described above are generic events with a title and data payload — the UI renders them as regular cards in the watchers column.

See packs/watchers/agent.md for the full watcher event schema and the Monitor tool conventions.

Event API

All packs POST to http://localhost:3500/api/packs/<pack>/events with:

{
  "skill": "<skill-id>",
  "component": "<component-type>",
  "props": { ... },
  "status": "running" | "completed"
}

Running/completed pattern. Before each skill, POST a running event. When the skill finishes, DELETE the running event and POST completed events:

# Start
curl -s -X POST http://localhost:3500/api/packs/<pack>/events \
  -H 'Content-Type: application/json' \
  -d '{"skill":"<skill>","component":"generic","props":{"title":"Running...","data":"Working"},"status":"running"}'

# Finish
curl -s -X DELETE "http://localhost:3500/api/packs/<pack>/events?skill=<skill>"
# Then POST completed events

POST progressively. Never batch events at the end of a skill — POST each component as soon as its data is ready so the UI fills in visibly. Batching defeats the whole product.

Use real data. Never hardcode example values. Every event must come from actual tool output (WebFetch, WebSearch, Stripe API, Playwright snapshot, etc.).

Validation loop

Before marking a skill complete, run this validation (feedback loop pattern):

1. HTTP status check. Did every POST return a 2xx? If non-2xx, read the server's error body (usually a Zod schema mismatch), fix the payload, retry. Do not proceed with broken events.
2. Event completeness. Did you POST every event type the skill's ## Output Events section declares? A skill that declares 5 events must POST all 5 (unless a conditional says otherwise, e.g. "skip when credentials are absent").
3. Data sanity. Does the data look right? If MRR is $0 but there are 32 active subscribers, something went wrong in the math — don't POST garbage. If the competitors list is empty after WebSearch, the search probably failed — retry or report.

Only after these checks pass, DELETE the running event and proceed to the next skill.

run-all specifics

The run-all command runs the five analytics packs in this exact order: marketing → finance → sales → audience → funnels. The watchers pack is not included in run-all because it's persistent, not one-shot.

Before starting, clear existing events so the dashboard shows fresh data:

for pack in marketing finance sales audience funnels; do
  skills=$(curl -s "http://localhost:3500/api/packs/$pack/events" \
    | python3 -c "import sys,json; events=json.load(sys.stdin); [print(s) for s in set(e['skill'] for e in events)]" 2>/dev/null)
  for skill in $skills; do
    curl -s -X DELETE "http://localhost:3500/api/packs/$pack/events?skill=$skill" > /dev/null
  done
done

Then run each pack's pipeline per the standard workflow. marketing must run first because its audit-site skill emits a product_context generic event that later packs consume.

Pack quick reference

For the full catalog, read each pack's agent.md directly. This table is a table-of-contents; every file listed is one level deep from this skill.

marketing

• Agent: packs/marketing/agent.md
• Pipeline order: audit-site → competitors → ai-visibility → citability → crawlers → programmatic-seo → content-gen
• Skills: packs/marketing/skills/audit-site.md, packs/marketing/skills/competitors.md, packs/marketing/skills/ai-visibility.md, packs/marketing/skills/citability.md, packs/marketing/skills/crawlers.md, packs/marketing/skills/programmatic-seo.md, packs/marketing/skills/content-gen.md
• Requires: WebFetch, WebSearch. Optional: OPEN_PAGERANK_API_KEY, DATAFORSEO_LOGIN/DATAFORSEO_PASSWORD, Playwright (for PageSpeed Lighthouse)

finance

• Agent: packs/finance/agent.md
• Pipeline order: mrr-check → billing-audit → forecast → pricing-strategy
• Skills: packs/finance/skills/mrr-check.md, packs/finance/skills/billing-audit.md, packs/finance/skills/forecast.md, packs/finance/skills/pricing-strategy.md
• Requires: STRIPE_API_KEY in .env.local (source the file; empty-password basic auth)

sales

• Agent: packs/sales/agent.md
• Pipeline order: pipeline-check → cold-email → outreach-gen → sales-enablement
• Skills: packs/sales/skills/pipeline-check.md, packs/sales/skills/cold-email.md, packs/sales/skills/outreach-gen.md, packs/sales/skills/sales-enablement.md
• Requires: WebSearch. Optional: STRIPE_API_KEY (for pipeline-check)

audience

• Agent: packs/audience/agent.md
• Pipeline order: persona-builder → segment-analysis → customer-research → free-tool-strategy
• Skills: packs/audience/skills/persona-builder.md, packs/audience/skills/segment-analysis.md, packs/audience/skills/customer-research.md, packs/audience/skills/free-tool-strategy.md
• Requires: WebFetch, WebSearch. Optional: STRIPE_API_KEY (for segment-analysis)

funnels

• Agent: packs/funnels/agent.md
• Pipeline order: page-cro → signup-flow-cro → pricing-page-cro → conversion-audit → funnel-analysis → churn-prevention
• Skills: packs/funnels/skills/page-cro.md, packs/funnels/skills/signup-flow-cro.md, packs/funnels/skills/pricing-page-cro.md, packs/funnels/skills/conversion-audit.md, packs/funnels/skills/funnel-analysis.md, packs/funnels/skills/churn-prevention.md
• Requires: WebFetch, Playwright (for signup-flow-cro). Optional: STRIPE_API_KEY (for funnel-analysis, churn-prevention)

watchers

• Agent: packs/watchers/agent.md
• Pipeline order: n/a (watchers are invoked individually via /watch <type> <target>; they run until stopped by TaskStop or session end)
• Skill: packs/watchers/skills/watch.md — one generic skill teaching the Monitor-backed polling pattern, with worked examples for every bundled type
• Generic bundled scripts: packs/watchers/skills/scripts/lighthouse-poll.sh, competitor-poll.sh, uptime-poll.sh, mentions-poll.sh, log-tail.sh
• Pack-aligned bundled scripts: packs/watchers/skills/scripts/ai-crawler-poll.sh (→ marketing), stripe-churn-poll.sh (→ finance/funnels), stripe-payment-health-poll.sh (→ finance), stripe-new-signup-poll.sh (→ sales)
• Requires: Monitor tool (built into Claude Code). Optional: the analytics packs (pack-aligned watchers name the pack they map to; when one fires, offer the user the corresponding /<pack> or /<pack>-skill <skill> command as a follow-up). Stripe-based watchers require STRIPE_API_KEY in .env.local.

Gotchas

• Server must be running. Before any POST, verify http://localhost:3500 is up. If not: bash scripts/start-server.sh in a separate terminal. POSTs will fail silently if the server is down.
• Stripe env var is STRIPE_API_KEY. Always source .env.local before any Stripe curl: source .env.local 2>/dev/null. Then reference $STRIPE_API_KEY directly.
• Stripe basic auth. -u "$STRIPE_API_KEY:" — the trailing colon is required (HTTP basic auth with empty password).
• Skill files are the source of truth. When a scoring formula, output schema, or event structure appears in multiple places (this SKILL.md, agent.md, old inlined commands), the version in packs/<pack>/skills/<skill>.md wins. If you see drift, report it; don't silently reconcile.
• run-all is sequential. Later packs reference the product_context generic event from marketing's audit-site. Don't parallelize unless you've verified no cross-pack dependency.
• Pipeline order is in pack.json. The pipeline array dictates execution order, which may differ from the skills list order (funnels is an example). Respect the pipeline array.
• POST progressively, not at the end. The dashboard UX depends on events streaming in as discovered.
• Model selection. Use Sonnet (recommended) or Haiku for pack execution. Pack skills are mechanical work (WebFetch, WebSearch, curl, jq) — Opus burns tokens for no quality gain. Reserve Opus for editing Binderclip's own codebase.
• Pack skills currently lack dedicated Gotchas sections (ongoing cleanup; packs/watchers/skills/lighthouse.md is the first to include one as a reference). Apply judgment based on the pack's agent.md when a skill is ambiguous.

Subagent delegation

For long-running invocations (run-all, or any full pack pipeline), delegating to a subagent is optional but helps keep the main conversation context clean. Inject this SKILL.md's content plus the pack's agent.md plus the relevant skill playbooks into the subagent prompt:

Agent(
  subagent_type="general-purpose",
  model="sonnet",
  description="binderclip <pack>",
  prompt="[content of this SKILL.md]\n\n[content of packs/<pack>/agent.md]\n\n[content of packs/<pack>/skills/<skill>.md for each skill in pipeline]\n\nRun the <pack> pipeline on URL: <url>. POST events as specified."
)

Watchers are the exception — they must run in the main conversation because Monitor notifications need to reach the user interactively.

References

• Pack agents: packs/<pack>/agent.md
• Pack pipelines: packs/<pack>/pack.json
• Pack skills: packs/<pack>/skills/*.md
• Bundled scripts (watchers): packs/watchers/skills/scripts/*.sh
• Zod schemas (server-side validation): src/schemas.ts
• UI component renderers: ui/src/catalog/
• Server implementation: src/server.ts
• Server start script: scripts/start-server.sh
• Action plan aggregator: .claude/commands/action-plan.md