fix: slim skill descriptions (#992)

tmchow · web-flow · commit 69542983848c · 2026-06-24T10:42:16.000-07:00
diff --git a/skills/ce-brainstorm/SKILL.md b/skills/ce-brainstorm/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: ce-brainstorm
-description: 'Explore requirements and approaches through collaborative dialogue, then write a right-sized requirements document. Use when the user says "let''s brainstorm", "what should we build", or "help me think through X", presents a vague or ambitious feature request, or seems unsure about scope or direction -- even without explicitly asking to brainstorm.'
+description: 'Explore vague or ambitious ideas into right-sized requirements. Use when the user wants to brainstorm, think through scope, decide what to build, or needs collaborative product framing before planning.'
 argument-hint: "[feature idea or problem to explore] [output:html]"
 ---
 
diff --git a/skills/ce-code-review/SKILL.md b/skills/ce-code-review/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: ce-code-review
-description: "Structured code review using tiered persona agents, confidence-gated findings, and a merge/dedup pipeline. In interactive mode it applies safe, verified fixes and commits them when the working tree is clean (it never pushes); in mode:agent it reports only and the caller applies. Use when reviewing code changes before creating a PR."
+description: "Structured code review for bugs, regressions, tests, and standards. Use before PRs or when asked for review; interactive mode can fix locally, while mode:agent reports only for pipeline callers."
 argument-hint: "[mode:agent] [blank to review current branch, or provide PR link]"
 ---
 
diff --git a/skills/ce-commit-push-pr/SKILL.md b/skills/ce-commit-push-pr/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: ce-commit-push-pr
-description: Commit, push, and open a PR with an adaptive, value-first description that scales in depth with the change. Use when the user says "commit and PR", "ship this", "create a PR", or "open a pull request". Also handles description-only flows ("write a PR description", "rewrite the PR body", "describe this PR") without committing or pushing.
+description: Commit, push, and open a PR. Use when asked to ship/open a PR, or for PR-description-only flows like writing, rewriting, or describing a PR body.
 ---
 
 # Git Commit, Push, and PR
diff --git a/skills/ce-commit/SKILL.md b/skills/ce-commit/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: ce-commit
-description: Create a git commit with a clear, value-communicating message. Use when the user says "commit", "commit this", "save my changes", "create a commit", or wants to commit staged or unstaged work. Produces well-structured commit messages that follow repo conventions when they exist, and defaults to conventional commit format otherwise.
+description: Create a git commit with a clear, value-communication message. Use when the user asks to commit/save staged or unstaged changes with a repo-appropriate, value-communicating message.
 ---
 
 # Git Commit
diff --git a/skills/ce-compound-refresh/SKILL.md b/skills/ce-compound-refresh/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: ce-compound-refresh
-description: Refresh stale learning and pattern docs under docs/solutions/ by reviewing them against the current codebase, then updating, consolidating, or deleting drifted ones. Use when the user asks to "refresh my learnings", "audit docs/solutions/", "clean up stale learnings", or "consolidate overlapping docs", or when ce-compound flags an older doc as superseded. Do not trigger for general refactor, debugging, or code-review work unless the user has explicitly pointed at docs/solutions/.
+description: Refresh docs/solutions learnings against the current codebase. Use when auditing stale, overlapping, superseded, or drifted learnings; avoid general refactor, debugging, or code review unless docs/solutions is explicit.
 argument-hint: "[optional: scope hint — directory, filename, module, or keyword] [mode:headless] "
 ---
 
diff --git a/skills/ce-compound/SKILL.md b/skills/ce-compound/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: ce-compound
-description: Document a recently solved problem to compound your team's knowledge or CONCEPTS.md, the project's shared domain vocabulary.
+description: Document a recently solved problem or durable project vocabulary in docs/solutions/ or CONCEPTS.md. Use when capturing a learning after work.
 argument-hint: "[optional: brief context] [mode:headless] "
 ---
 
diff --git a/skills/ce-debug/SKILL.md b/skills/ce-debug/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: ce-debug
-description: 'Systematically find root causes and fix bugs. Use when debugging errors, investigating test failures, reproducing bugs from issue trackers (GitHub, Linear, Jira), or when stuck on a problem after failed fix attempts. Also use when the user says ''debug this'', ''why is this failing'', ''fix this bug'', ''trace this error'', or pastes stack traces, error messages, or issue references.'
+description: 'Diagnosis loop for bugs and failing behavior. Use for errors, stack traces, regressions, failed tests, issue-tracker bugs, stuck investigations after failed fixes, or asks to debug/fix a bug.'
 argument-hint: "[issue reference, error message, test path, or description of broken behavior]"
 ---
 
diff --git a/skills/ce-doc-review/SKILL.md b/skills/ce-doc-review/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: ce-doc-review
-description: Review requirements or plan documents using parallel persona agents that surface role-specific issues. Use when a requirements document or plan document exists and the user wants to improve it.
+description: Review requirements, plans, or specs with role-specific lenses. Use when the user wants to improve an existing planning document.
 argument-hint: "[mode:headless] [path/to/document.md]"
 ---
 
diff --git a/skills/ce-dogfood-beta/SKILL.md b/skills/ce-dogfood-beta/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: ce-dogfood-beta
-description: "[BETA] Dogfood the active branch end-to-end as a QA engineer. Diffs the branch against main, builds an exhaustive browser test matrix of every change (full user journeys, not just features), drives the app with agent-browser, then auto-fixes issues, adds regression tests, and commits each fix until the matrix is green. Use when you want a hands-off 'test everything we just built and make it actually work' pass before shipping."
+description: "[BETA] Hands-off end-to-end branch dogfood pass with browser testing, auto-fixes, regression tests, and fix commits."
 disable-model-invocation: true
 argument-hint: "[PR number, branch name, or blank for current branch] [--port PORT]"
 ---
diff --git a/skills/ce-ideate/SKILL.md b/skills/ce-ideate/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: ce-ideate
-description: "Generate and critically evaluate grounded ideas about a topic. Use when asking what to improve, requesting idea generation, exploring surprising directions, or wanting the AI to proactively suggest strong options before brainstorming one in depth. Triggers on phrases like 'what should I improve', 'give me ideas', 'ideate on X', 'surprise me', 'what would you change', or any request for AI-generated suggestions rather than refining the user's own idea."
+description: "Generate and evaluate grounded ideas. Use when the user asks for ideas, improvements, surprising options, or AI-generated directions before choosing one to develop; use ce-brainstorm to refine the user's own idea."
 argument-hint: "[feature, focus area, or constraint] [output:md]"
 
 ---
diff --git a/skills/ce-optimize/SKILL.md b/skills/ce-optimize/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: ce-optimize
-description: "Run metric-driven iterative optimization loops -- define a measurable goal, run parallel experiments, measure each against hard gates or LLM-as-judge scores, keep improvements, and converge on the best solution. Use when optimizing clustering quality, search relevance, build performance, prompt quality, or any measurable outcome that benefits from systematic experimentation."
+description: "Run metric-driven optimization loops. Use when improving measurable outcomes such as search relevance, clustering quality, build performance, prompt quality, or scored behavior through experiments."
 argument-hint: "[path to optimization spec YAML, or describe the optimization goal]"
 ---
 
diff --git a/skills/ce-plan/SKILL.md b/skills/ce-plan/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: ce-plan
-description: "Create structured plans for multi-step tasks -- software features, research workflows, events, study plans, or any goal that benefits from breakdown. Also deepens existing plans with interactive sub-agent review. Use when the user says 'plan this', 'create a plan', 'how should we build', 'break this down', or when a brainstorm doc is ready for planning. Use 'deepen the plan' or 'deepening pass' for the deepening flow. For exploratory requests, prefer ce-brainstorm first."
+description: "Create structured plans for multi-step work, including software and non-software tasks. Use when asked to plan, break down implementation, plan from requirements, or deepen an existing plan; prefer ce-brainstorm for exploratory framing."
 argument-hint: "[optional: feature description, requirements doc path, plan path to deepen, or any task to plan] [output:html]"
 ---
 
diff --git a/skills/ce-polish/SKILL.md b/skills/ce-polish/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: ce-polish
-description: "Start the dev server, open the feature in a browser, and iterate on improvements together. Manual invocation only — type /ce-polish to run it."
+description: "Start the dev server, inspect the feature in browser, and iterate on polish."
 disable-model-invocation: true
 argument-hint: "[PR number, branch name, or blank for current branch]"
 ---
diff --git a/skills/ce-product-pulse/SKILL.md b/skills/ce-product-pulse/SKILL.md
@@ -1,6 +1,7 @@
 ---
 name: ce-product-pulse
-description: "Generate a time-windowed pulse report on what users experienced and how the product performed - usage, quality, errors, signals worth investigating. Use when the user says 'run a pulse', 'show me the pulse', 'how are we doing', 'weekly recap', 'launch-day check', or passes a time window like '24h' or '7d'. Configures via .compound-engineering/config.local.yaml and saves reports to docs/pulse-reports/."
+description: "Generate time-windowed product pulse reports from configured signals."
+disable-model-invocation: true
 argument-hint: "[lookback window, e.g. '24h', '7d', '1h'; default 24h]"
 allowed-tools:
   - Read
diff --git a/skills/ce-promote/SKILL.md b/skills/ce-promote/SKILL.md
@@ -1,6 +1,7 @@
 ---
 name: ce-promote
-description: "Draft user-facing announcement and marketing copy for a feature that just shipped — an X post or thread, a changelog blurb, a LinkedIn post, an email, a blog intro, or a short demo script. Spiral-agnostic by default; voice-matched via the Spiral CLI when it is installed and authed. Use when the user says 'promote this', 'draft the announcement', 'write the launch copy', 'market this feature', 'announce this feature', 'write the release tweet', or 'ce-promote'."
+description: "Draft launch or promotion copy for a shipped feature."
+disable-model-invocation: true
 argument-hint: "[optional: what shipped and/or channels, e.g. 'a tweet thread and a LinkedIn post']"
 ---
 
diff --git a/skills/ce-proof/SKILL.md b/skills/ce-proof/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: ce-proof
-description: Publish, view, comment on, and edit markdown via Proof (proofeditor.ai) — create a shareable doc, read a shared doc, and make comment/suggestion/block edits over its API. Use when the user says "view this in proof", "share to proof", "publish to proof", or wants a shareable markdown surface for a spec, plan, or draft, including publish handoffs from ce-brainstorm, ce-ideate, or ce-plan. Do not trigger on "proof" meaning evidence, math proofs, proof-of-concept, or "proofread this".
+description: Publish, read, comment on, or edit markdown in Proof. Use for Proof links, sharing specs/plans/drafts, or publish handoffs from planning workflows; avoid proofread, math, evidence, or proof-of-concept meanings.
 allowed-tools:
   - Bash
   - Read
diff --git a/skills/ce-resolve-pr-feedback/SKILL.md b/skills/ce-resolve-pr-feedback/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: ce-resolve-pr-feedback
-description: Resolve PR review feedback by evaluating validity and fixing issues in parallel. Use when addressing PR review comments, resolving review threads, or fixing code review feedback.
+description: Resolve PR review feedback. Use when addressing review comments, resolving review threads, or fixing code-review feedback.
 argument-hint: "[PR number, comment URL, or blank for current branch's PR]"
 allowed-tools: Bash(gh *), Bash(git *), Read
 ---
diff --git a/skills/ce-riffrec-feedback-analysis/SKILL.md b/skills/ce-riffrec-feedback-analysis/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: ce-riffrec-feedback-analysis
-description: Riffrec product-feedback workflow. ALWAYS load when the user posts a `riffrec-*.zip`, a bundle with `session.json` + `events.json` + `recording.webm` + `voice.webm`, a video/audio recording for product feedback, or asks how to capture and share Riffrec sessions. Routes between setup, quick bug report, and extensive analysis.
+description: Analyze Riffrec feedback captures from bundles or standalone recordings. Always load for `riffrec-*.zip`, `session.json` + `events.json` + `recording.webm` + `voice.webm` bundles, `.mp4`/`.mov`/`.webm` videos, `.m4a`/`.mp3`/`.wav` audio, or capture/share requests.
 ---
 
 # Riffrec Feedback Analysis
diff --git a/skills/ce-setup/SKILL.md b/skills/ce-setup/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: ce-setup
-description: "Check Compound Engineering health and repo-local config. Reports optional tool capabilities, removes obsolete local config, refreshes the config example, and helps safely gitignore machine-local settings. Use when verifying setup, troubleshooting missing optional tools, or onboarding a repo."
+description: "Check Compound Engineering health and repo-local config."
 disable-model-invocation: true
 ---
 
diff --git a/skills/ce-simplify-code/SKILL.md b/skills/ce-simplify-code/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: ce-simplify-code
-description: "Simplify and refine recently changed code for clarity, reuse, quality, and efficiency while preserving behavior."
+description: "Simplify recently changed code for clarity, reuse, quality, and efficiency while preserving behavior. Use for tidy/refactor passes; use ce-debug for bugs."
 argument-hint: "[blank to simplify current branch changes, or describe what to simplify]"
 ---
 
diff --git a/skills/ce-strategy/SKILL.md b/skills/ce-strategy/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: ce-strategy
-description: "Create or maintain STRATEGY.md - the product's target problem, approach, users, key metrics, and tracks of work. Use when starting a new product, updating direction, or when prompts like 'write our strategy', 'update the roadmap', 'what are we working on', or 'set up the strategy doc' come up. Also triggers when ce-ideate, ce-brainstorm, or ce-plan need upstream grounding and no strategy doc exists yet."
+description: "Create or update STRATEGY.md. Use when starting a product, changing direction or roadmap, or when ce-ideate, ce-brainstorm, or ce-plan need upstream product grounding."
 argument-hint: "[optional: section to revisit, e.g. 'metrics' or 'approach']"
 ---
 
diff --git a/skills/ce-test-browser/SKILL.md b/skills/ce-test-browser/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: ce-test-browser
-description: Run browser tests on pages affected by current PR or branch
+description: Run browser tests for pages affected by the current branch or PR.
 argument-hint: "[PR number, branch name, 'current', or --port PORT]"
 ---
 
diff --git a/skills/ce-test-xcode/SKILL.md b/skills/ce-test-xcode/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: ce-test-xcode
-description: "Build and test iOS apps on simulator using XcodeBuildMCP. Use after making iOS code changes, before creating a PR, or when verifying app behavior and checking for crashes on simulator."
+description: "Build and test iOS apps on simulator with XcodeBuildMCP."
 argument-hint: "[scheme name or 'current' to use default]"
 disable-model-invocation: true
 ---
diff --git a/skills/ce-work-beta/SKILL.md b/skills/ce-work-beta/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: ce-work-beta
-description: "[BETA] Execute work with external delegate support. Same as ce-work but includes experimental Codex delegation mode for token-conserving code implementation."
+description: "[BETA] Execute ce-work with external delegate support."
 disable-model-invocation: true
 argument-hint: "[Plan doc path or description of work. Blank to auto use latest plan doc] [delegate:codex]"
 ---
diff --git a/skills/ce-work/SKILL.md b/skills/ce-work/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: ce-work
-description: Execute work efficiently while maintaining quality and finishing features
+description: Execute a plan or concrete work prompt end-to-end. Use when implementing from docs/plans, a spec path, or a clear build request; use ce-debug for open-ended bugs.
 argument-hint: "[Plan doc path or description of work. Blank to auto use latest plan doc]"
 ---
 
diff --git a/skills/ce-worktree/SKILL.md b/skills/ce-worktree/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: ce-worktree
-description: Ensure work happens in an isolated git worktree without disturbing the current checkout. Use when starting work that should stay isolated, or when `ce-work` or `ce-code-review` offers a worktree option. Detects existing isolation first, prefers the harness's native worktree tool, and falls back to plain git.
+description: Set up isolated git worktrees. Use when starting isolated work, or when ce-work/ce-code-review offers a worktree option; detect existing isolation first.
 ---
 
 # Worktree Isolation
diff --git a/skills/lfg/SKILL.md b/skills/lfg/SKILL.md
@@ -1,6 +1,7 @@
 ---
 name: lfg
-description: Run the full autonomous engineering pipeline end-to-end (plan, work, code review, test, commit, push, open PR, watch CI, fix CI failures until green). Use only when the user explicitly requests hands-off execution of a software task and provides a feature description; do not auto-route casual conversation here.
+description: Run the full hands-off engineering pipeline from planning through a green PR.
+disable-model-invocation: true
 argument-hint: "[feature description]"
 ---
 
diff --git a/src/utils/legacy-cleanup.ts b/src/utils/legacy-cleanup.ts
diff --git a/tests/legacy-cleanup.test.ts b/tests/legacy-cleanup.test.ts
diff --git a/tests/skill-conventions.test.ts b/tests/skill-conventions.test.ts
