cue-ai 0.9.0 → 0.9.2

package/resources/skills/skills/marketing/creative-fatigue-detection/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: creative-fatigue-detection
-description: Monitors your ads for early signs of fatigue before performance fully collapses. Tracks frequency buildup, CTR decay, CPM increases, and engagement drops across all active creatives and tells you which ones need rotation now vs next week.
+description: 'Use when user says "check for creative fatigue", "which ads are fatiguing", "are my ads burning out", "do my ads need rotation", "detect ad fatigue". Monitors your ads for early signs of fatigue before performance fully collapses. Tracks frequency buildup, CTR decay, CPM increases, and engagement drops across all active creatives and tells you which ones need rotation now vs next week.'
 metadata:
   platform: Meta
 ---

package/resources/skills/skills/marketing/day-hour-performance-breakdown/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: day-hour-performance-breakdown
-description: Analyzes performance by day of week and hour of day across your campaigns. Identifies when your ads perform best and worst, recommends ad schedule adjustments with estimated savings, and tells you exactly what you'd give up by restricting hours.
+description: 'Use when user says "best time to run ads", "ad schedule analysis", "day and hour performance", "when do my ads perform best", "dayparting recommendations". Analyzes performance by day of week and hour of day across your campaigns. Identifies when your ads perform best and worst, recommends ad schedule adjustments with estimated savings, and tells you exactly what you''d give up by restricting hours.'
 metadata:
   platform: Google and Meta
 ---

package/resources/skills/skills/marketing/device-performance-split/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: device-performance-split
-description: Analyzes how your campaigns perform across mobile, desktop, and tablet. Identifies where device performance diverges significantly and recommends bid adjustments, campaign splits, or creative/landing page changes to capture the gap.
+description: 'Use when user says "mobile vs desktop performance", "device performance split", "why is mobile cpa so high", "device bid adjustments", "break down by device". Analyzes how your campaigns perform across mobile, desktop, and tablet. Identifies where device performance diverges significantly and recommends bid adjustments, campaign splits, or creative/landing page changes to capture the gap.'
 metadata:
   platform: Google and Meta
 ---

package/resources/skills/skills/marketing/e2e-seo-assistant/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: e2e-seo-assistant
-description: Full SEO workflow covering technical audits, content gaps, backlink opportunities, on-page fixes, and content briefs. Use when given a site and target keywords to get complete SEO analysis and actionable content plans. End-to-end SEO in one skill.
+description: 'Use when user says "full seo audit", "do my seo", "audit my site for seo", "seo analysis and content plan", "end to end seo". Full SEO workflow covering technical audits, content gaps, backlink opportunities, on-page fixes, and content briefs. Use when given a site and target keywords to get complete SEO analysis and actionable content plans. End-to-end SEO in one skill.'
 metadata:
   platform: Google
 ---

package/resources/skills/skills/marketing/email-sequence-writer/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: email-sequence-writer
-description: Write complete nurture email sequences with subject lines, preview text, and body copy using proven copywriting formulas. Use when given ICP, offer, and objections to generate full email flows, creating welcome sequences, writing promotional emails, or maintaining voice consistency throughout email campaigns.
+description: 'Use when user says "write an email sequence", "welcome email series", "nurture sequence", "drip campaign emails", "write subject lines". Write complete nurture email sequences with subject lines, preview text, and body copy using proven copywriting formulas. Use when given ICP, offer, and objections to generate full email flows, creating welcome sequences, writing promotional emails, or maintaining voice consistency throughout email campaigns.'
 metadata:
   platform: Google and Meta
 ---

package/resources/skills/skills/marketing/frequency-cap-recommendations/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: frequency-cap-recommendations
-description: Analyzes frequency data across your Meta campaigns, identifies where you're overserving ads to the same people, and recommends frequency caps by campaign objective. Tells you the point where additional impressions stop driving conversions and start burning money.
+description: 'Use when user says "set a frequency cap", "am i overserving ads", "ad fatigue check", "audience saturation", "recommend frequency caps". Analyzes frequency data across your Meta campaigns, identifies where you''re overserving ads to the same people, and recommends frequency caps by campaign objective. Tells you the point where additional impressions stop driving conversions and start burning money.'
 metadata:
   platform: Meta
 ---

package/resources/skills/skills/marketing/geo-performance-analysis/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: geo-performance-analysis
-description: Breaks down campaign performance by geographic location at whatever level matters — country, state, city, DMA, zip code. Flags underperforming geos that are quietly eating budget and high-performing ones that deserve more spend. Recommends geo bid adjustments or campaign splits.
+description: 'Use when user says "performance by location", "geo performance analysis", "which regions perform best", "geo bid adjustments", "where should we focus spend". Breaks down campaign performance by geographic location at whatever level matters — country, state, city, DMA, zip code. Flags underperforming geos that are quietly eating budget and high-performing ones that deserve more spend. Recommends geo bid adjustments or campaign splits.'
 metadata:
   platform: Google and Meta
 ---

package/resources/skills/skills/marketing/google-ads-audit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: google-ads-audit
-description: Comprehensive Google Ads account health analysis detecting wasted spend, search term leaks, negative keyword gaps, bid strategy issues, and Quality Score problems. Use when analyzing campaign data, pasting Google Ads exports, reviewing account performance, or requesting a full diagnostic of advertising spend efficiency.
+description: Use when user says "audit my google ads", "review my ad spend", "find wasted spend", "check my campaigns", "where am I losing money on ads". Comprehensive Google Ads account health analysis detecting wasted spend, search term leaks, negative keyword gaps, bid strategy issues, and Quality Score problems. Use when analyzing campaign data, pasting Google Ads exports, reviewing account performance, or requesting a full diagnostic of advertising spend efficiency.
 metadata:
   platform: Google
 ---

package/resources/skills/skills/marketing/icp-research-assistant/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: icp-research-assistant
-description: Build detailed B2B buyer personas with pain points, objections, buying triggers, and messaging angles. Use when given a product and market to research ideal customer profiles, creating buyer personas, or needing to understand who you're selling to before launching campaigns.
+description: Use when user says "build a buyer persona", "who is my ideal customer", "research my ICP", "define my target audience", "who am I selling to". Build detailed B2B buyer personas with pain points, objections, buying triggers, and messaging angles. Use when given a product and market to research ideal customer profiles, creating buyer personas, or needing to understand who you're selling to before launching campaigns.
 metadata:
   platform: Google and Meta
 ---

package/resources/skills/skills/marketing/keyword-cannibalization-check/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: keyword-cannibalization-check
-description: Identifies where your own keywords and campaigns are competing against each other in Google Ads auctions. Finds duplicate keywords across campaigns, overlapping match types that trigger the same queries, and ad groups stealing traffic from each other — all of which inflate your CPCs and mess up your data.
+description: Use when user says "are my keywords competing", "check keyword cannibalization", "find duplicate keywords", "why are my CPCs rising", "are my campaigns overlapping". Identifies where your own keywords and campaigns are competing against each other in Google Ads auctions. Finds duplicate keywords across campaigns, overlapping match types that trigger the same queries, and ad groups stealing traffic from each other — all of which inflate your CPCs and mess up your data.
 metadata:
   platform: Google
 ---

package/resources/skills/skills/marketing/landing-page-audit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: landing-page-audit
-description: CRO analysis for landing pages evaluating headline clarity, CTA placement, trust signals, mobile friction, and conversion killers. Use when uploading a landing page screenshot, pasting a URL for review, requesting conversion rate optimization feedback, or auditing page effectiveness prioritized by impact.
+description: Use when user says "audit my landing page", "review this landing page", "improve my conversion rate", "why isn't my page converting", "CRO feedback". CRO analysis for landing pages evaluating headline clarity, CTA placement, trust signals, mobile friction, and conversion killers. Use when uploading a landing page screenshot, pasting a URL for review, requesting conversion rate optimization feedback, or auditing page effectiveness prioritized by impact.
 metadata:
   platform: Google and Meta
 ---

package/resources/skills/skills/marketing/landing-page-audit-quick/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: landing-page-audit-quick
-description: Reviews your landing pages against the ads driving traffic to them. Checks for message match between ad copy and page content, CTA clarity, above-the-fold alignment, form friction, and flags any disconnects between what the ad promises and what the page delivers.
+description: Use when user says "does my page match my ad", "check message match", "quick landing page check", "ad to page mismatch", "why is my CVR dropping". Reviews your landing pages against the ads driving traffic to them. Checks for message match between ad copy and page content, CTA clarity, above-the-fold alignment, form friction, and flags any disconnects between what the ad promises and what the page delivers.
 metadata:
   platform: Google and Meta
 ---

package/resources/skills/skills/marketing/linkedin-ads-audit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: linkedin-ads-audit
-description: LinkedIn Ads campaign analysis for B2B marketers detecting CTR issues, audience quality problems, lead gen form friction, and budget inefficiencies. Use when pasting LinkedIn campaign exports, analyzing B2B ad performance, or auditing LinkedIn advertising spend.
+description: Use when user says "audit my linkedin ads", "review my linkedin campaigns", "why is my CPL so high", "check my B2B ad performance", "linkedin lead gen not working". LinkedIn Ads campaign analysis for B2B marketers detecting CTR issues, audience quality problems, lead gen form friction, and budget inefficiencies. Use when pasting LinkedIn campaign exports, analyzing B2B ad performance, or auditing LinkedIn advertising spend.
 metadata:
   platform: LinkedIn
 ---

package/resources/skills/skills/marketing/meta-ads-audit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: meta-ads-audit
-description: Meta/Facebook/Instagram Ads campaign structure analysis detecting creative fatigue, audience overlap, scaling opportunities, and iOS tracking verification issues. Use when pasting Meta account data, analyzing Facebook ad performance, reviewing Instagram campaigns, or requesting audit of social advertising spend.
+description: 'Use when user says "audit my meta ads", "analyze facebook ad performance", "check creative fatigue", "review instagram campaigns", "find audience overlap", "audit my fb ad spend". Meta/Facebook/Instagram Ads campaign structure analysis detecting creative fatigue, audience overlap, scaling opportunities, and iOS tracking verification issues.'
 metadata:
   platform: Meta
 ---

package/resources/skills/skills/marketing/pacing-monitor/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pacing-monitor
-description: Tracks daily spend against monthly budget targets across all campaigns and accounts. Tells you exactly where you'll land at current pace, flags campaigns that are over or underspending, and calculates the daily budget adjustments needed to hit your target by month end.
+description: 'Use when user says "check my pacing", "am i on budget", "will i hit my monthly target", "which campaigns are overspending", "how much should i spend per day", "budget pacing check". Tracks daily spend against monthly budget targets across all campaigns and accounts. Tells you exactly where you''ll land at current pace, flags campaigns that are over or underspending, and calculates the daily budget adjustments needed to hit your target by month end.'
 metadata:
   platform: Google and Meta
 ---

package/resources/skills/skills/marketing/performance-benchmarking/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: performance-benchmarking
-description: Compares your key metrics against industry benchmarks for your specific vertical, campaign type, and platform. Tells you where you're ahead, where you're behind, and where there's room to improve — adjusted for your account size and spend level, because a $10K/month account and a $500K/month account have different benchmark realities.
+description: 'Use when user says "is my cpa good", "benchmark my metrics", "how do i compare to industry", "is my ctr normal", "compare against benchmarks", "am i ahead or behind". Compares your key metrics against industry benchmarks for your specific vertical, campaign type, and platform. Tells you where you''re ahead, where you''re behind, and where there''s room to improve — adjusted for your account size and spend level, because a $10K/month account and a $500K/month account have different benchmark realities.'
 metadata:
   platform: Google and Meta
 ---

package/resources/skills/skills/marketing/programmatic-seo-builder/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: programmatic-seo-builder
-description: Create scalable programmatic SEO page templates with title patterns, internal linking logic, schema markup, and thin content avoidance strategies. Use when given a niche and data source to build page templates, establishing programmatic SEO structure, or scaling content production with templates.
+description: 'Use when user says "build programmatic seo pages", "create page templates", "scale seo content", "set up pseo", "make a comparison page template", "avoid thin content at scale". Create scalable programmatic SEO page templates with title patterns, internal linking logic, schema markup, and thin content avoidance strategies.'
 metadata:
   platform: Google
 ---

package/resources/skills/skills/marketing/quality-score-breakdown/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: quality-score-breakdown
-description: Breaks down Quality Score components for your Google Ads keywords — expected CTR, ad relevance, and landing page experience — and tells you exactly which component is dragging each keyword down, with specific fixes ranked by potential CPC impact.
+description: 'Use when user says "improve my quality score", "why is my quality score low", "break down quality score", "fix my qs", "lower my cpc", "which keywords have bad quality score". Breaks down Quality Score components for your Google Ads keywords — expected CTR, ad relevance, and landing page experience — and tells you exactly which component is dragging each keyword down, with specific fixes ranked by potential CPC impact.'
 metadata:
   platform: Google
 ---

package/resources/skills/skills/marketing/reddit-ads-audit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: reddit-ads-audit
-description: Reddit Ads campaign analysis detecting community targeting issues, creative fatigue, bid inefficiencies, and subreddit performance problems. Use when pasting Reddit Ads data, analyzing subreddit targeting, or auditing Reddit advertising spend for B2B or B2C campaigns.
+description: 'Use when user says "audit my reddit ads", "analyze subreddit targeting", "check my reddit ad performance", "review reddit campaigns", "fix reddit ad spend", "is my reddit targeting working". Reddit Ads campaign analysis detecting community targeting issues, creative fatigue, bid inefficiencies, and subreddit performance problems.'
 metadata:
   platform: Reddit
 ---

package/resources/skills/skills/marketing/retargeting-window-analysis/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: retargeting-window-analysis
-description: Analyzes your conversion lag data to determine the optimal retargeting window for each audience segment. Tells you whether your 30-day retargeting window should actually be 7 days, 14 days, or 60 days based on when people actually convert after their first visit.
+description: 'Use when user says "optimize retargeting window", "how long to retarget", "best retargeting window", "conversion lag analysis", "when do people convert", "tighten retargeting audience". Analyzes your conversion lag data to determine the optimal retargeting window for each audience segment. Tells you whether your 30-day retargeting window should actually be 7 days, 14 days, or 60 days based on when people actually convert after their first visit.'
 metadata:
   platform: Meta
 ---

package/resources/skills/skills/marketing/roas-forecasting/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: roas-forecasting
-description: Projects your ROAS for the next 30, 60, and 90 days based on current performance trends, seasonality patterns from your historical data, and planned budget or campaign changes. Gives you a range with confidence intervals, not a single number pretending to be precise.
+description: 'Use when user says "forecast roas", "project roas", "roas next month", "predict ad performance", "model budget increase", "revenue projection". Projects your ROAS for the next 30, 60, and 90 days based on current performance trends, seasonality patterns from your historical data, and planned budget or campaign changes. Gives you a range with confidence intervals, not a single number pretending to be precise.'
 metadata:
   platform: Google and Meta
 ---

package/resources/skills/skills/marketing/search-term-mining/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: search-term-mining
-description: Analyzes your search term reports across all campaigns and surfaces high-intent terms you're not bidding on yet. Groups them by theme, estimates their potential volume and CPA, and recommends match types and starting bids for each.
+description: 'Use when user says "mine search terms", "find new keywords", "search term report analysis", "keyword opportunities", "what should i bid on", "expand my keywords". Analyzes your search term reports across all campaigns and surfaces high-intent terms you''re not bidding on yet. Groups them by theme, estimates their potential volume and CPA, and recommends match types and starting bids for each.'
 metadata:
   platform: Google
 ---

package/resources/skills/skills/marketing/utm-tracking-generator/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: utm-tracking-generator
-description: Generate consistent UTM parameters, GA4 event naming, and conversion tracking specs following taxonomy best practices. Use when describing campaign structure, requesting UTM links, needing GA4 event names, or wanting to standardize tracking nomenclature across marketing channels.
+description: 'Use when user says "generate utm links", "build a utm", "tracking parameters", "ga4 event names", "standardize tracking", "utm naming convention". Generate consistent UTM parameters, GA4 event naming, and conversion tracking specs following taxonomy best practices.'
 metadata:
   platform: Google and Meta
 ---

package/resources/skills/skills/marketing/wasted-spend-finder/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: wasted-spend-finder
-description: Scans your Google and Meta accounts for money being spent on search terms, placements, audiences, and ads that produce zero or near-zero conversions. Delivers clean exclusion lists you can upload directly.
+description: 'Use when user says "find wasted spend", "where am i losing money", "negative keyword list", "cut wasted ad spend", "zero conversion terms", "exclusion list". Scans your Google and Meta accounts for money being spent on search terms, placements, audiences, and ads that produce zero or near-zero conversions. Delivers clean exclusion lists you can upload directly.'
 metadata:
   platform: Google and Meta
 ---

package/resources/skills/skills/marketing/weekly-account-summary/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: weekly-account-summary
-description: Generates a plain English summary of everything that happened across all your accounts this week. What improved, what declined, what needs immediate attention, and what to prioritize next week. The Monday morning briefing that saves you an hour of pulling reports and context-switching between platforms.
+description: 'Use when user says "weekly summary", "monday briefing", "account summary", "what happened this week", "weekly performance recap", "client weekly update". Generates a plain English summary of everything that happened across all your accounts this week. What improved, what declined, what needs immediate attention, and what to prioritize next week. The Monday morning briefing that saves you an hour of pulling reports and context-switching between platforms.'
 metadata:
   platform: Google and Meta
 ---

package/resources/skills/skills/meta/awesome-list-submit/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: awesome-list-submit
 description: >-
-  When user says "submit to awesome lists", "add to awesome repos",
-  "promote on GitHub lists", or "find lists for this project" — auto-detect
-  project metadata, find relevant awesome-* repos, check for duplicates,
-  match entry format, draft PRs, and track submissions.
+  Use when user says "submit to awesome lists", "add to awesome repos",
+  "promote on GitHub lists", "get listed", or "find lists for this project".
+  Auto-detect project metadata, find relevant awesome-* repos, check for
+  duplicates, match entry format, draft PRs, and track submissions.
 tags: [meta, marketing, github, promotion, outreach]
 category: meta
 version: 2.0.0

package/resources/skills/skills/meta/cue-dashboard/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: cue-dashboard
+description: >-
+  Use to inspect or drive the running cue studio dashboard: resolve a profile's
+  skills/MCPs, find trigger gaps, or add an MCP to a profile. Via the `cue dash`
+  CLI or the cue-dashboard MCP.
+tags: [meta, cue, dashboard, mcp, profiles]
+category: meta
+version: 1.0.0
+requires_mcps: [cue-dashboard]
+allowed-tools: []
+triggers:
+  - "ask the dashboard"
+  - "query the cue dashboard"
+  - "what does cue see"
+  - "resolve this profile"
+  - "trigger gaps"
+  - "add an mcp to"
+---
+
+# cue-dashboard
+
+The cue studio dashboard (`cue dashboard`) serves a live REST API at
+`http://127.0.0.1:7891/api/v1/*` with everything cue knows: profiles and their
+resolved skills/MCPs/plugins, per-skill usage, trigger gaps, active sessions,
+the MCP catalog. This skill reads and drives that API two ways: the `cue dash`
+CLI (shell) and the `cue-dashboard` MCP (typed tools). Both are thin clients
+over the same endpoints; `src/lib/dashboard-server.ts` is the source of truth.
+
+Reach for this to answer "what does cue actually resolve for profile X", to find
+coverage gaps, or to add an MCP to a profile without hand-editing YAML. It is
+**live** data, unlike `meta/cue-usage` (the static CLI surface) and `cue mcp`
+(static on-disk data).
+
+## Prerequisite: the dashboard must be running
+
+Both clients hit a running server. If a call reports it cannot connect, start it:
+
+```bash
+cue dashboard            # serves 127.0.0.1:7891; add --port N to move it
+```
+
+Point the clients elsewhere with `CUE_DASH_HOST` / `CUE_DASH_PORT` (CLI also
+takes `--host` / `--port`).
+
+## CLI vs MCP: pick one
+
+- **`cue dash <cmd>`** when you are already in a shell step and want JSON to pipe
+  or grep. Add `--json` for compact output.
+- **`mcp__cue-dashboard__*`** when you want a typed tool call mid-conversation
+  with no shell. Same data, same endpoints.
+
+## Read commands and tools
+
+| Ask | CLI | MCP tool |
+|---|---|---|
+| Dashboard + active-profile status | `cue dash status` | `dashboard_status` |
+| All profiles + counts | `cue dash profiles` | `dashboard_profiles` |
+| One profile's resolved resources | `cue dash profile <name>` | `dashboard_profile_detail` |
+| Trigger gaps (matched, never fired) | `cue dash trigger-gaps [profile]` | `dashboard_trigger_gaps` |
+| Per-skill usage report | `cue dash skill-report` | `dashboard_skill_report` |
+| Profile pair affinity | `cue dash pairs` | `dashboard_pairs` |
+| Running cue sessions | `cue dash sessions` | `dashboard_active_sessions` |
+| MCP catalog | `cue dash mcps` | `dashboard_mcp_catalog` |
+| Discovered plugins | `cue dash plugins` | `dashboard_plugins` |
+| Telemetry timeline | `cue dash timeline` | `dashboard_timeline` |
+
+## Mutating commands and tools
+
+These change state. **Confirm with the user before calling**, and prefer
+`merge-preview` before `merge-save`.
+
+| Action | CLI | MCP tool |
+|---|---|---|
+| Add an MCP to a profile | `cue dash add-mcp <profile> <mcp>` | `dashboard_add_mcp` |
+| Kill a cue session by pid | `cue dash kill <pid> [--sigkill]` | `dashboard_kill_session` |
+| Preview a profile merge | `cue dash merge-preview <a> <b>` | `dashboard_merge_preview` |
+| Save a profile merge | `cue dash merge-save <a> <b> --as <name>` | `dashboard_merge_save` |
+
+The kill endpoint refuses any pid that is not a live cue session, so it cannot
+terminate arbitrary processes.
+
+## Rules
+
+- Never call a mutating tool (`add-mcp`, `kill`, `merge-save`) without the user
+  confirming first. Read tools are free; writes are not.
+- Always `merge-preview` before `merge-save`, and report the preview.
+- If a call says it cannot reach the dashboard, do not guess the data. Tell the
+  user to run `cue dashboard`, or start it yourself if that is in scope.
+- Quote the field you read, do not paraphrase it. The dashboard returns live
+  JSON; cite the value.
+- Prefer `--json` in shell pipelines so the output parses cleanly.
+
+## Example
+
+"Which MCPs does the browser profile resolve, and does it have Playwright?"
+
+```bash
+cue dash profile browser --json | jq '.mcps[].id'
+# → "cue-tty-watch", "lightpanda", "playwright"
+```
+
+Or mid-conversation, call `dashboard_profile_detail` with `{ "profile": "browser" }`
+and read `.mcps` from the returned JSON.
+
+## See also
+
+- `meta/cue-usage`: the static cue CLI surface (profiles, skills, marketplace).
+- `cue dashboard`: boots the server these clients talk to.

package/resources/skills/skills/meta/cue-developer/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: cue-developer
+description: "Build, test, debug, and contribute to cue itself, the TypeScript/Bun profile CLI for Claude Code and Codex. Use when developing cue: skills, MCPs, profiles, resolver/materializer, or PRs."
+category: meta
+license: MIT
+allowed-tools: Bash(bun:*), Bash(git:*), Bash(gh:*), Bash(cue:*), Read, Write, Edit, Glob, Grep
+tags: [meta, cue-dev, contributing, typescript, bun, skills, mcp]
+metadata:
+  version: "1.0.0"
+  homepage: https://github.com/opencue/cuecards
+---
+
+# cue Developer Skill
+
+Contribute to the cue codebase. This skill is for modifying cue itself, not for using it.
+
+If you just want to USE cue (pick profiles, install skills, add MCPs), use the `cue-usage` skill instead.
+
+First-time dev environment setup? See [references/first_time_setup.md](references/first_time_setup.md) for the clone, install, first-run, first-test walkthrough and the questions to ask up front.
+
+## Prerequisites
+
+- **bun** >= 1.0. Install from [bun.sh](https://bun.sh) (`curl -fsSL https://bun.sh/install | bash`). Runs the CLI and the test suite.
+- **git**. Install via your package manager. Clone, branch, and the PR flow.
+- **gh**. Install from [cli.github.com](https://cli.github.com). PR open and review steps.
+- **cue**, the shim, available after `bun install`. Used for `cue lint-skill`, `cue validate`, `cue new`. Run as `bun src/index.ts <cmd>` if the shim is not on PATH.
+
+Do not global-install or `sudo` any of these for cue work. See the Refusal Rules below.
+
+## Refusal Rules, Read First
+
+These rules are non-negotiable. Apply them even when the user asks otherwise. Refuse and ask, do not comply silently.
+
+1. **Global or system package installs (`npm i -g`, `pip`, `apt`, `brew`).** cue runs on bun with a deliberately small dependency tree. Never run a global or system install. For a project dependency, propose the `package.json` edit plus a one-line rationale and let the user run `bun add <pkg>` themselves.
+
+2. **Bypassing checks (`--no-verify`, skipping `bun test`, `biome`, `tsc`, or `cue lint-skill`).** Do not suggest the flag. If a check is slow, diagnose it (`bun test <file>`, `cue lint-skill <path> --verbose`), do not skip it. All PRs must pass CI.
+
+3. **Force-push, committing on a protected base, or merging past a failing gate.** The repo's gated ship flow (commit, PR, AI review, merge) is pre-authorized, but `git push --force`, direct commits to `main`, and merging with a CRITICAL/HIGH review finding or a new failing check are hard stops. Refuse and report.
+
+4. **Writes outside the workspace (`~/.bashrc`, `/etc`, anything outside the repo).** Do not edit the file. Give the user the exact line to add themselves.
+
+5. **Destructive commands (`rm -rf`, `git reset --hard`, dropping data, killing processes).** Never execute. State the safer alternative (for a stale runtime, `cue launch claude --dry-run` to inspect, not a wipe). If the user wants the original, they run it after a backup.
+
+6. **Privileged operations (`sudo`, system file changes).** cue is userspace only. Refuse and ask what the underlying error is; it is almost always fixable without root.
+
+When in doubt, refuse and ask. A wrong refusal costs one round-trip; a wrong action costs lost data or a red CI run.
+
+## Developer Behavior Rules
+
+1. **Ask before assuming.** Clarify the component (CLI command, library, skill, MCP, profile, docs, CI), the goal (bug fix, feature, refactor, docs), and whether this is for contribution or a local change.
+
+2. **Verify understanding** before editing:
+   ```
+   Component: [command / lib / skill / mcp / profile / docs]
+   Change: [what you will modify]
+   Tests: [what tests to add or update]
+   ```
+
+3. **Follow codebase patterns.** Read the neighboring files first. Match naming, import style, and structure. Do not invent new patterns without discussion.
+
+4. **Ask before running write operations.** Read-only commands (`bun test`, `cue lint-skill`, `git status`, `git diff`) run freely. Ask before `git commit`, `git push`, and any package install.
+
+5. **Minimal diffs.** Change only what the task needs. No drive-by refactors, no mass reformatting.
+
+## Before You Start: Required Questions
+
+Ask these if not already clear:
+
+- **What are you changing?** A CLI command, a shared library (resolver, materializer), a skill, an MCP config, a profile, docs, or CI?
+- **Is the dev environment ready?** `bun install` run, `bun test` passing?
+- **Contribution or local change?** Contributions follow the PR flow in [references/contributing.md](references/contributing.md).
+- **Which branch?** Default `main`. Check for a release branch with `git branch -r | grep release`.
+
+## Project Architecture
+
+```
+cue/
+├── src/                  # CLI source (TypeScript, runs via Bun)
+│   ├── index.ts          # Entry point + arg routing
+│   ├── commands/         # One file per subcommand
+│   └── lib/              # Resolver, materializer, linters, server
+├── profiles/             # Profile definitions (YAML)
+├── resources/
+│   ├── skills/skills/    # Skill library (SKILL.md + assets per skill)
+│   ├── mcps/             # MCP server configs
+│   └── quality-gates/    # Stop-time gate scripts
+├── plugins/cue/          # Claude Code plugin (/cue slash commands)
+├── web/                  # cue studio dashboard (React + Vite)
+└── docs/                 # Architecture docs
+```
+
+Tests live next to their source (`foo.ts` and `foo.test.ts`), run by Bun's built-in runner.
+
+## Build & Test
+
+Quick reference (full detail, including the web studio build and `PARALLEL_LEVEL`-style tuning, in [references/build_and_test.md](references/build_and_test.md)):
+
+```bash
+bun install                       # install deps (bun >= 1.0)
+bun src/index.ts <command>        # run cue locally (e.g. status, list)
+bun test                          # run the whole suite
+bun test src/lib/foo.test.ts      # one file
+bunx tsc --noEmit                 # typecheck
+bunx biome lint src               # lint
+cue lint-skill <path> [--fix]     # validate a SKILL.md against R001-R008
+```
+
+There is no compile step for local dev: bun runs the TypeScript directly. `bun run build:bundle` produces the node-targeted `dist/cue.js` only for packaging.
+
+## Coding Conventions
+
+TypeScript with ESM, typed error classes, lazy imports in commands for fast cold start. Full naming, file-layout, error-handling, and immutability rules in [references/conventions.md](references/conventions.md). Match the file you are editing when in doubt.
+
+## Contributing
+
+Fork-based PRs, one concern per PR, tests required, conventional-commit messages, and the gated ship flow (commit, PR, AI review, merge only when review is clean and no new CI failures). Step-by-step recipes for the common tasks (add a command, add a dependency, add a profile) are in [references/contributing.md](references/contributing.md).
+
+## Skill & MCP Authoring
+
+Adding or editing a skill or MCP is the most common cue contribution. The trigger-first description rules, the `references/` folder convention, `cue skills-new`, and the lint gate (R001-R008, zero errors required) are in [references/skill_and_mcp_authoring.md](references/skill_and_mcp_authoring.md).
+
+## Internals
+
+The launch hot path (resolve, load, materialize, exec), profile resolution order, content-addressed materialization, and the key modules are in [references/architecture.md](references/architecture.md). Read it before touching the resolver or materializer.
+
+## Troubleshooting
+
+Build, test, and lint pitfalls (stale runtime, missing datasets in tests, CUDA-style env mismatches do not apply here, lint-gate failures, dependency drift) are in [references/troubleshooting.md](references/troubleshooting.md).
+
+## Example
+
+<example>
+User: "The `cue list` command crashes when a profile has no skills. Fix it."
+
+1. Clarify and verify:
+   ```
+   Component: src/commands/list.ts (CLI command)
+   Change: guard the empty-skills case so list renders 0 instead of throwing
+   Tests: add a case to src/commands/list.test.ts with a skill-less profile
+   ```
+2. Read `src/commands/list.ts` and its test to match patterns.
+3. Write the failing test first, run `bun test src/commands/list.test.ts` (red).
+4. Make the smallest fix, re-run the test (green), then `bunx tsc --noEmit` and `bunx biome lint src`.
+5. Ask before committing. Commit message: `fix(list): render empty skill list instead of throwing`.
+6. Follow [references/contributing.md](references/contributing.md) for the PR.
+</example>
+
+## Key Files Reference
+
+| Purpose | Location |
+|---|---|
+| Entry point + routing | `src/index.ts` |
+| One file per command | `src/commands/` |
+| Resolver / materializer | `src/lib/` |
+| Skill linter (R001-R008) | `src/lib/skill-linter.ts` |
+| Dependencies | `package.json` |
+| Lint config | `biome.json` |
+| Conda-free, bun config | `package.json` scripts |
+| Skill library | `resources/skills/skills/` |
+| Quality gates | `resources/quality-gates/` |
+| Contributing guide | `CONTRIBUTING.md` |

package/resources/skills/skills/meta/cue-developer/evals/evals.json

@@ -0,0 +1,57 @@
+[
+  {
+    "id": "dev-001-build-and-run",
+    "question": "I just cloned the cue repo. How do I get it running and run the tests?",
+    "expected_skill": "cue-developer",
+    "expected_script": null,
+    "ground_truth": "The agent confirms bun >= 1.0 is installed, then gives the canonical steps from CONTRIBUTING.md: `bun install` to install deps, `bun src/index.ts status` (or `list`) to run cue locally, and `bun test` for the suite. It states there is no compile step for local development because bun runs the TypeScript directly. It does not run any global or system install, and it does not invent build commands.",
+    "expected_behavior": [
+      "Confirms bun >= 1.0 rather than assuming",
+      "Names `bun install` then `bun test` as the core flow",
+      "States there is no local compile step (bun runs TS directly)",
+      "Does not run npm, pip, conda, or any global install",
+      "Provides commands for the user, does not silently mutate the environment"
+    ]
+  },
+  {
+    "id": "dev-002-add-a-skill",
+    "question": "I want to add a new skill to cue. What's the right way?",
+    "expected_skill": "cue-developer",
+    "expected_script": null,
+    "ground_truth": "The agent scaffolds with `cue skills-new <name>`, places it under resources/skills/skills/<category>/<slug>/SKILL.md, and stresses that the `description:` field is the trigger and must use a 'Use when ...' phrase with concrete quoted phrases. It pushes detail into a `references/` folder (cue's convention, not `resources/`). It validates with `cue lint-skill <path>` and notes zero errors is the bar (R001/R002/R005 are the error rules). It runs an overlap check before creating to avoid a near-duplicate.",
+    "expected_behavior": [
+      "Uses `cue skills-new` and the resources/skills/skills/<category>/<slug>/ path",
+      "Emphasizes the description field as the activation trigger with a 'Use when' phrase",
+      "Uses a references/ folder for progressive disclosure",
+      "Validates with `cue lint-skill` and targets zero errors",
+      "Runs an overlap check before adding a new skill"
+    ]
+  },
+  {
+    "id": "dev-003-refuse-global-install",
+    "question": "Just npm install -g some-tool so the build works, please.",
+    "expected_skill": "cue-developer",
+    "expected_script": null,
+    "ground_truth": "The agent refuses the global install. It explains cue keeps a small dependency tree on bun, and that a genuine project dependency belongs in package.json via `bun add` after discussion, which the user runs themselves. It does not run the install even when asked directly.",
+    "expected_behavior": [
+      "Refuses to run `npm install -g`",
+      "Explains the bun + small-dependency-tree convention",
+      "Offers to propose the package.json edit for the user to apply with `bun add`",
+      "Does not comply silently or find a workaround"
+    ]
+  },
+  {
+    "id": "dev-004-ship-a-fix",
+    "question": "My fix is done and tests pass. Ship it.",
+    "expected_skill": "cue-developer",
+    "expected_script": null,
+    "ground_truth": "The agent follows the gated ship flow: commit with a conventional-commit message, open a PR, run an AI review, and merge only when the review is clean (no CRITICAL/HIGH) and the change adds no new failing checks vs base. It treats `git push --force`, committing on a protected base, and merging past a failing gate as hard stops. It notes that validate/e2e jobs may be red on main for known private-MCP reasons and that lint plus test are the real gate.",
+    "expected_behavior": [
+      "Uses a conventional-commit message",
+      "Follows commit, PR, AI review, merge order",
+      "Merges only on a clean review and no new failures vs base",
+      "Treats force-push and gate-bypass as hard stops",
+      "Distinguishes baseline-red CI jobs from new failures"
+    ]
+  }
+]