am-will · popey · Mar 17, 2026
diff --git a/skills/agent-browser/SKILL.md b/skills/agent-browser/SKILL.md
@@ -1,12 +1,6 @@
 ---
-name: Agent Browser
-description: A fast Rust-based headless browser automation CLI with Node.js fallback that enables AI agents to navigate, click, type, and snapshot pages via structured commands.
-read_when:
-  - Automating web interactions
-  - Extracting structured data from pages
-  - Filling forms programmatically
-  - Testing web UIs
-metadata: {"clawdbot":{"emoji":"🌐","requires":{"bins":["node","npm"]}}}
+name: agent-browser
+description: "A fast Rust-based headless browser automation CLI with Node.js fallback that enables AI agents to navigate, click, type, snapshot, and extract data from web pages via structured commands. Use when automating web interactions, extracting structured data from pages, filling forms programmatically, testing web UIs, or performing browser-based scraping and navigation tasks."
 ---
 
 # Agent Browser

diff --git a/skills/frontend-design/SKILL.md b/skills/frontend-design/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: frontend-design
-description: Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.
+description: "Create distinctive, production-grade frontend interfaces with high design quality, including responsive layouts, CSS animations, interactive forms, and navigation menus. Use when the user asks to build web components, pages, UI elements, websites, landing pages, dashboards, or HTML/CSS/React applications. Generates creative, polished code with bold typography, cohesive color palettes, and memorable interactions that avoid generic AI aesthetics."
 license: Complete terms in LICENSE.txt
 ---
 

diff --git a/skills/frontend-responsive-ui/SKILL.md b/skills/frontend-responsive-ui/SKILL.md
@@ -1,6 +1,6 @@
 ---
-name: Frontend Responsive Design Standards
-description: Build responsive, mobile-first layouts using fluid containers, flexible units, media queries, and touch-friendly design that works across all screen sizes. Use this skill when creating or modifying UI layouts, responsive grids, breakpoint styles, mobile navigation, or any interface that needs to adapt to different screen sizes. Apply when working with responsive CSS, media queries, viewport settings, flexbox/grid layouts, mobile-first styling, breakpoint definitions (mobile, tablet, desktop), touch target sizing, relative units (rem, em, %), image optimization for different screens, or testing layouts across multiple devices. Use for any task involving multi-device support, responsive design patterns, or adaptive layouts.
+name: frontend-responsive-ui
+description: "Build responsive, mobile-first layouts using fluid containers, flexible units, media queries, and touch-friendly design that works across all screen sizes. Use when creating or modifying UI layouts, responsive grids, breakpoint styles, mobile navigation, or any interface that needs to adapt to different screen sizes. Apply when working with responsive CSS, media queries, viewport settings, flexbox/grid layouts, mobile-first styling, breakpoint definitions (mobile, tablet, desktop), touch target sizing, relative units (rem, em, %), image optimization for different screens, or testing layouts across multiple devices."
 ---
 
 # Frontend Responsive Design Standards

diff --git a/skills/markdown-url/SKILL.md b/skills/markdown-url/SKILL.md
@@ -1,11 +1,6 @@
 ---
 name: markdown-url
-description: |
-  Route any website you need to visit through markdown.new by prefixing the URL.
-
-  **WHEN TO USE:**
-  - You would normally open a website link to read content (docs, blog posts, changelogs, GitHub issues, etc.)
-  - You need a cleaner, Markdown-friendly view for copying notes or summarizing
+description: "Convert web pages to clean markdown format by routing URLs through markdown.new, removing ads and clutter while preserving text and code blocks. Use when reading documentation, blog posts, changelogs, GitHub issues, articles, or any web content where a clean, extractable markdown view is needed for summarizing, copying notes, or quoting."
 ---
 
 # markdown.new URL Prefix

diff --git a/skills/parallel-task-spark/SKILL.md b/skills/parallel-task-spark/SKILL.md
@@ -1,7 +1,6 @@
 ---
 name: parallel-task-spark
-description: >
-  Only to be triggered by explicit /parallel-task-spark commands. 
+description: "Orchestrate parallel task execution by parsing plan files and delegating work to concurrent Sparky subagents using dependency-aware wave scheduling. Launches unblocked tasks in parallel, validates RED-to-GREEN test evidence, and updates plan docs with completion logs. Use when running /parallel-task-spark to execute implementation plans with TDD-driven parallel subagents."
 ---
 
 # Parallel Task Executor (Sparky)

diff --git a/skills/parallel-task/SKILL.md b/skills/parallel-task/SKILL.md
@@ -1,7 +1,6 @@
 ---
 name: parallel-task
-description: >
-  Only to be triggered by explicit /parallel-task commands. 
+description: "Orchestrate parallel task execution by parsing plan files and delegating work to concurrent subagents using dependency-aware wave scheduling. Launches unblocked tasks in parallel, validates RED-to-GREEN test evidence, and updates plan docs with completion logs. Use when running /parallel-task to execute implementation plans with TDD-driven parallel subagents."
 ---
 
 # Parallel Task Executor

diff --git a/skills/parallel/SKILL.md b/skills/parallel/SKILL.md
@@ -1,7 +1,6 @@
 ---
 name: parallel
-description: >
-  Only to be triggered by explicit /parallel-task commands. 
+description: "Orchestrate parallel task execution by parsing plan files, inferring dependency graphs from task content, and delegating work to concurrent subagents in waves. Automatically detects task dependencies, validates with TDD RED-to-GREEN evidence, and updates plan docs with completion logs. Use when running /parallel-task to execute plans that lack explicit dependency annotations."
 ---
 
 # Parallel Task Executor

diff --git a/skills/plan-harder/SKILL.md b/skills/plan-harder/SKILL.md
@@ -1,7 +1,6 @@
 ---
 name: plan-harder
-description: >
-  Use when user specfically says 'plan harder'. 
+description: "Create detailed, phased implementation plans with sprints and atomic tasks, including codebase research, requirement clarification, gotcha identification, and subagent review. Produces structured plans with demo/verification checklists per sprint and specific file paths per task. Use when the user says 'plan harder' or requests a thorough, multi-phase implementation plan with deep analysis."
 ---
 
 # Planner Agent

diff --git a/skills/role-creator/SKILL.md b/skills/role-creator/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: role-creator
-description: Create and install Codex custom agent roles in ~/.codex/config.toml, generate role config files, enforce supported keys, and guide users through required role inputs (model, reasoning effort, developer_instructions).
+description: "Create and install Codex custom agent roles in ~/.codex/config.toml, generate role config files, enforce supported keys, and guide users through required role inputs (model, reasoning effort, developer_instructions). Use when the user wants to create a custom agent, configure Codex roles, set up a new persona, or manage agent role definitions."
 ---
 
 # Role Creator

diff --git a/skills/super-swarm-spark/SKILL.md b/skills/super-swarm-spark/SKILL.md
@@ -1,7 +1,6 @@
 ---
 name: super-swarm-spark
-description: >
-  Only to be triggered by explicit super-swarm-spark commands. 
+description: "Orchestrate high-throughput parallel task execution using a rolling pool of up to 12 concurrent Sparky subagents. Ignores dependency ordering for maximum speed, builds context packs with canonical file paths per task, prevents filename drift across agents, and performs a final integration pass to reconcile parallel-work conflicts. Use when running /super-swarm-spark to execute large plans at maximum concurrency."
 ---
 
 # Parallel Task Executor (Sparky Rolling 12-Agent Pool)

diff --git a/skills/swarm-planner/SKILL.md b/skills/swarm-planner/SKILL.md
@@ -1,8 +1,6 @@
 ---
 name: swarm-planner
-description: >
-  [EXPLICIT INVOCATION ONLY] Creates dependency-aware implementation plans optimized for parallel
-  multi-agent execution.
+description: "Create dependency-aware implementation plans optimized for parallel multi-agent execution. Explores the codebase, fetches current library docs via Context7, clarifies requirements through user input, and produces plans with explicit task dependency graphs and parallel execution wave tables. Use when planning work for multiple parallel agents, breaking down implementations into dependency-mapped tasks, or preparing plans for /parallel-task or /super-swarm-spark execution."
 metadata:
   invocation: explicit-only
 ---
@@ -76,11 +74,11 @@ T7: [depends_on: [T6]] Write integration tests
 
 Tasks with empty/satisfied dependencies can run in parallel (T1, T2 above).
 
-### 4. Save Plan
+### 5. Save Plan
 
 Save to `<topic>-plan.md` in the CWD.
 
-### 5. Subagent Review
+### 6. Subagent Review
 
 After saving, spawn a subagent to review the plan:
 

diff --git a/skills/vercel-react-best-practices/SKILL.md b/skills/vercel-react-best-practices/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: vercel-react-best-practices
-description: React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements.
+description: "React and Next.js performance optimization guidelines from Vercel Engineering covering code splitting, lazy loading, bundle size reduction, caching strategies, and re-render optimization. Use when writing, reviewing, or refactoring React/Next.js code, fixing slow page loads, reducing large bundle sizes, improving Core Web Vitals or Lighthouse scores, or implementing data fetching patterns."
 ---
 
 # Vercel React Best Practices