the-grimoire-cli 0.3.2 → 0.4.0

package/.agents/rules/60-commit-style.md

@@ -1,14 +1,14 @@
----
-updated: 2026-05-31
-description: Conventional Commits and the project's commit/PR conventions.
----
-
-# 60 — Commit style
-
-- **Conventional Commits.** `type(scope): subject` — `feat` `fix` `docs` `refactor` `test` `chore`
-  `perf` `build` `ci`. Imperative mood, lower-case subject, no trailing period.
-- **One logical change per commit.** Reviewable diffs; no "misc fixes" grab-bags.
-- **Hooks run.** husky + lint-staged on commit. **No `--no-verify`** — the one exception is a
-  HOTFIX emergency commit (`20-modes.md`), which must be cleaned up afterward.
-- **Body explains why** when the change is non-obvious. Reference the `journal/backlog/` id or ADR.
-- **Never bypass signing** unless explicitly asked.
+---
+updated: 2026-05-31
+description: Conventional Commits and the project's commit/PR conventions.
+---
+
+# 60 — Commit style
+
+- **Conventional Commits.** `type(scope): subject` — `feat` `fix` `docs` `refactor` `test` `chore`
+  `perf` `build` `ci`. Imperative mood, lower-case subject, no trailing period.
+- **One logical change per commit.** Reviewable diffs; no "misc fixes" grab-bags.
+- **Hooks run.** husky + lint-staged on commit. **No `--no-verify`** — the one exception is a
+  HOTFIX emergency commit (`20-modes.md`), which must be cleaned up afterward.
+- **Body explains why** when the change is non-obvious. Reference the `journal/backlog/` id or ADR.
+- **Never bypass signing** unless explicitly asked.

package/.agents/rules/INDEX.md

@@ -1,18 +1,18 @@
-# rules — index
-
-<!-- GENERATED by `grimoire index`; do not edit by hand. Re-run after adding/renaming files here. -->
-
-| File | What it covers |
-|---|---|
-| `00-always.md` | The non-negotiable rules; violating any is a hard error, not a style nit. |
-| `05-code-quality.md` | Always-on code-quality essentials; the full standard lives in standards/clean-code.md. |
-| `10-working-process.md` | How to work a task end to end: plan, task contract, right altitude, small increments, tools, TDD. |
-| `15-skills.md` | Consult skills/catalog.md and use the right skill/plugin/MCP before improvising. |
-| `20-modes.md` | NORMAL vs HOTFIX: how a user phrase sets the working mode and what each mode requires. |
-| `25-surgical-changes.md` | Touch only what the request needs; do not refactor or "improve" adjacent code. |
-| `30-verification.md` | The independent verifier: the author cannot mark their own work done; verify on fresh context. |
-| `35-context-economy.md` | Keep entry and always-on files lean; push detail to references read on demand. |
-| `40-handoff.md` | Route every incoming request to exactly one home: chat, backlog, hotfix, or field-report. |
-| `45-presentation.md` | When and how to render human-facing deliverables as HTML instead of long Markdown. |
-| `50-security.md` | Server-side authorization, no hardcoded secrets/roles, fail closed. |
-| `60-commit-style.md` | Conventional Commits and the project's commit/PR conventions. |
+# rules — index
+
+<!-- GENERATED by `grimoire index`; do not edit by hand. Re-run after adding/renaming files here. -->
+
+| File | What it covers |
+|---|---|
+| `00-always.md` | The non-negotiable rules; violating any is a hard error, not a style nit. |
+| `05-code-quality.md` | Always-on code-quality essentials; the full standard lives in standards/clean-code.md. |
+| `10-working-process.md` | How to work a task end to end: plan, task contract, right altitude, small increments, tools, TDD. |
+| `15-skills.md` | Consult skills/catalog.md and use the right skill/plugin/MCP before improvising. |
+| `20-modes.md` | NORMAL vs HOTFIX: how a user phrase sets the working mode and what each mode requires. |
+| `25-surgical-changes.md` | Touch only what the request needs; do not refactor or "improve" adjacent code. |
+| `30-verification.md` | The independent verifier: the author cannot mark their own work done; verify on fresh context. |
+| `35-context-economy.md` | Keep entry and always-on files lean; push detail to references read on demand. |
+| `40-handoff.md` | Route every incoming request to exactly one home: chat, backlog, hotfix, or field-report. |
+| `45-presentation.md` | When and how to render human-facing deliverables as HTML instead of long Markdown. |
+| `50-security.md` | Server-side authorization, no hardcoded secrets/roles, fail closed. |
+| `60-commit-style.md` | Conventional Commits and the project's commit/PR conventions. |

package/.agents/skills/INDEX.md

@@ -1,8 +1,8 @@
-# skills — index
-
-<!-- GENERATED by `grimoire index`; do not edit by hand. Re-run after adding/renaming files here. -->
-
-| File | What it covers |
-|---|---|
-| `catalog.md` | Capability catalog — What to reach for, by trigger. |
-| `find-skills/` | Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that ca… |
+# skills — index
+
+<!-- GENERATED by `grimoire index`; do not edit by hand. Re-run after adding/renaming files here. -->
+
+| File | What it covers |
+|---|---|
+| `catalog.md` | Capability catalog — What to reach for, by trigger. |
+| `find-skills/` | Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that ca… |

package/.agents/skills/README.md

@@ -3,4 +3,4 @@
 Portable skill files (Claude Code `skills/` format) that any project inherits. v0.1 ships the
 verification workflow as a command + subagent (`commands/verify.md`, `agents/verifier.md`) rather
 than a standalone skill. Add skills here as patterns prove reusable across projects; they sync as a
-managed path.
+managed path.

package/.agents/skills/catalog.md

@@ -1,106 +1,106 @@
-# Capability catalog
-
-What to reach for, by trigger. **Primary** = default choice. **Alternates** = equivalents when the
-primary is unavailable or you want a second opinion. Anything not here → run `find-skills`.
-
-> The mattpocock engineering skills below require `/setup-matt-pocock-skills` once per repo
-> (configures the issue tracker, triage label vocabulary, and doc layout they consume).
->
-> Bare-named MCPs in this catalog (`context7`, `exa`, `github`) ship **with the `ecc` plugin** —
-> `grimoire bootstrap` enabling `ecc` wires them; they intentionally have no separate `tooling.json`
-> `mcp` entry. Only standalone servers (`playwright`, `stitch`) live in `tooling.json`.
-
-## Process & engineering
-
-| When you are… | Primary | Alternates | Layer |
-|---|---|---|---|
-| starting a new feature | `superpowers:brainstorming` | — | skill |
-| aligning before a change | `grill-me` / `grill-with-docs` | — | skill |
-| writing the implementation plan | `superpowers:writing-plans` | `ecc:plan` | skill |
-| writing code test-first | `tdd` | `superpowers:test-driven-development` | skill |
-| chasing a hard bug / perf regression | `diagnose` | `superpowers:systematic-debugging` | skill |
-| improving architecture (ball of mud) | `improve-codebase-architecture` | — | skill |
-| designing a module's layering | `standards/architecture.md` | `improve-codebase-architecture` | doc |
-| production logging / observability | `standards/observability.md` | — | doc |
-| understanding unfamiliar code | `zoom-out` | — | skill |
-| compacting the session for handoff | `handoff` | — | skill |
-| managing work-state / second brain | `standards/knowledge-management.md` | — | doc |
-| throwaway prototype to flesh out a design | `prototype` | — | skill |
-| turning context into a PRD | `to-prd` | `ecc:plan-prd` | skill |
-| breaking a plan into issues | `to-issues` | — | skill |
-| triaging incoming issues | `triage` | — | skill |
-| writing a new skill | `write-a-skill` | `skill-creator` | skill |
-| isolating parallel work | `superpowers:using-git-worktrees` | `superpowers:dispatching-parallel-agents` | skill |
-
-## Review, security, quality
-
-| When you are… | Primary | Alternates | Layer |
-|---|---|---|---|
-| reviewing before merge | `ecc:code-review` | `superpowers:requesting-code-review`, `/code-review` | skill |
-| auditing security-sensitive code | `ecc:security-review` | `ecc:security-scan` | skill |
-| gating a launch (privacy + security) | `standards/launch-security-checklist.md` | `ecc:security-review`, SAST (`standards/security-scanners.md`) | doc |
-| confirming work is done | `verifier` (Grimoire) | `superpowers:verification-before-completion` | subagent |
-| cleaning dead code | `ecc:refactor-clean` | — | skill |
-| running the quality gate | `ecc:quality-gate` | — | skill |
-| writing or reviewing code to standard | `standards/clean-code.md` | `templates/lint/` (enforcement) | doc |
-| writing or editing an agent-facing doc | `standards/writing.md` | — | doc |
-| guarding structural invariants (drift) | `standards/guardrail-tests.md` | — | doc |
-| recording a decision (incl. no-test rationale) | `codex/decisions/` (`0000-template.md`) | — | doc |
-
-## Web / Next.js (pharmaceutical-hub)
-
-| When you are… | Primary | Alternates | Layer |
-|---|---|---|---|
-| building a React component | `ecc:react-patterns` | `ecc:react-performance` | skill |
-| reviewing React/TSX | `ecc:react-review` | — | skill |
-| writing React tests | `ecc:react-test` | `tdd` | skill |
-| fixing a React/Next build | `ecc:react-build` | `ecc:build-fix` | skill |
-| Next.js / Turbopack specifics | `ecc:nextjs-turbopack` | — | skill |
-| accessibility pass | `ecc:frontend-a11y` | `web-design-guidelines` | skill |
-| designing an API | `ecc:api-design` | `ecc:backend-patterns` | skill |
-| DB schema / queries | `ecc:postgres-patterns` | `ecc:prisma-patterns` | skill |
-| DB migration | `ecc:database-migrations` | — | skill |
-
-## Healthcare (both repos are medical)
-
-| When you are… | Primary | Alternates | Layer |
-|---|---|---|---|
-| handling PHI / privacy | `ecc:healthcare-phi-compliance` | `ecc:hipaa-compliance` | skill |
-| EMR/EHR data patterns | `ecc:healthcare-emr-patterns` | — | skill |
-| clinical decision support | `ecc:healthcare-cdss-patterns` | — | skill |
-| evaluating a health-AI feature | `ecc:healthcare-eval-harness` | — | skill |
-
-## Design / UI
-
-| When you are… | Primary | Alternates | Layer |
-|---|---|---|---|
-| designing UI/UX | `ui-ux-pro-max` | `andrej-karpathy` | skill |
-| turning a mockup into UI code | `stitch` (MCP) | — | mcp |
-
-> **Deprecated — do not use:** `frontend-design` (replaced by `ui-ux-pro-max`).
-
-## Research, docs, MCP
-
-| When you are… | Primary | Alternates | Layer |
-|---|---|---|---|
-| researching an unknown topic | `ecc:deep-research` | `exa` (MCP) | skill |
-| looking up a library / API | `context7` (MCP) | `ecc:documentation-lookup` | mcp |
-| browser QA / e2e / visual check | `playwright` (MCP) | `ecc:e2e-testing` | mcp |
-| repo / PR operations | `ecc:pr` | `github` (MCP), `/pr` | skill |
-| need a capability you lack | `find-skills` | — | skill |
-
-## Presentation (HTML for humans)
-
-Render with `/present` when presentation mode is on (`rules/45-presentation.md`). HTML is an
-ephemeral view; the Markdown/spec stays canonical.
-
-| When you are… | Primary | Alternates | Layer |
-|---|---|---|---|
-| comparing specs / designs side by side | `/present` (HTML) | `superpowers:brainstorming` visual companion | command |
-| presenting a code review to a human | `/present` (HTML dashboard) | `ecc:code-review` | command |
-| writing a report / explainer | `/present` (HTML) | — | command |
-| showing a design prototype | `prototype` | `/present` (HTML) | skill |
-| building a custom editing UI (copy-as-JSON) | `/present` (HTML) | — | command |
-## Communication
-
-`pordee` (Thai-compressed) and `caveman` (terse) are session-level toggles set by the user.
+# Capability catalog
+
+What to reach for, by trigger. **Primary** = default choice. **Alternates** = equivalents when the
+primary is unavailable or you want a second opinion. Anything not here → run `find-skills`.
+
+> The mattpocock engineering skills below require `/setup-matt-pocock-skills` once per repo
+> (configures the issue tracker, triage label vocabulary, and doc layout they consume).
+>
+> Bare-named MCPs in this catalog (`context7`, `exa`, `github`) ship **with the `ecc` plugin** —
+> `grimoire bootstrap` enabling `ecc` wires them; they intentionally have no separate `tooling.json`
+> `mcp` entry. Only standalone servers (`playwright`, `stitch`) live in `tooling.json`.
+
+## Process & engineering
+
+| When you are… | Primary | Alternates | Layer |
+|---|---|---|---|
+| starting a new feature | `superpowers:brainstorming` | — | skill |
+| aligning before a change | `grill-me` / `grill-with-docs` | — | skill |
+| writing the implementation plan | `superpowers:writing-plans` | `ecc:plan` | skill |
+| writing code test-first | `tdd` | `superpowers:test-driven-development` | skill |
+| chasing a hard bug / perf regression | `diagnose` | `superpowers:systematic-debugging` | skill |
+| improving architecture (ball of mud) | `improve-codebase-architecture` | — | skill |
+| designing a module's layering | `standards/architecture.md` | `improve-codebase-architecture` | doc |
+| production logging / observability | `standards/observability.md` | — | doc |
+| understanding unfamiliar code | `zoom-out` | — | skill |
+| compacting the session for handoff | `handoff` | — | skill |
+| managing work-state / second brain | `standards/knowledge-management.md` | — | doc |
+| throwaway prototype to flesh out a design | `prototype` | — | skill |
+| turning context into a PRD | `to-prd` | `ecc:plan-prd` | skill |
+| breaking a plan into issues | `to-issues` | — | skill |
+| triaging incoming issues | `triage` | — | skill |
+| writing a new skill | `write-a-skill` | `skill-creator` | skill |
+| isolating parallel work | `superpowers:using-git-worktrees` | `superpowers:dispatching-parallel-agents` | skill |
+
+## Review, security, quality
+
+| When you are… | Primary | Alternates | Layer |
+|---|---|---|---|
+| reviewing before merge | `ecc:code-review` | `superpowers:requesting-code-review`, `/code-review` | skill |
+| auditing security-sensitive code | `ecc:security-review` | `ecc:security-scan` | skill |
+| gating a launch (privacy + security) | `standards/launch-security-checklist.md` | `ecc:security-review`, SAST (`standards/security-scanners.md`) | doc |
+| confirming work is done | `verifier` (Grimoire) | `superpowers:verification-before-completion` | subagent |
+| cleaning dead code | `ecc:refactor-clean` | — | skill |
+| running the quality gate | `ecc:quality-gate` | — | skill |
+| writing or reviewing code to standard | `standards/clean-code.md` | `templates/lint/` (enforcement) | doc |
+| writing or editing an agent-facing doc | `standards/writing.md` | — | doc |
+| guarding structural invariants (drift) | `standards/guardrail-tests.md` | — | doc |
+| recording a decision (incl. no-test rationale) | `codex/decisions/` (`0000-template.md`) | — | doc |
+
+## Web / Next.js (pharmaceutical-hub)
+
+| When you are… | Primary | Alternates | Layer |
+|---|---|---|---|
+| building a React component | `ecc:react-patterns` | `ecc:react-performance` | skill |
+| reviewing React/TSX | `ecc:react-review` | — | skill |
+| writing React tests | `ecc:react-test` | `tdd` | skill |
+| fixing a React/Next build | `ecc:react-build` | `ecc:build-fix` | skill |
+| Next.js / Turbopack specifics | `ecc:nextjs-turbopack` | — | skill |
+| accessibility pass | `ecc:frontend-a11y` | `web-design-guidelines` | skill |
+| designing an API | `ecc:api-design` | `ecc:backend-patterns` | skill |
+| DB schema / queries | `ecc:postgres-patterns` | `ecc:prisma-patterns` | skill |
+| DB migration | `ecc:database-migrations` | — | skill |
+
+## Healthcare (both repos are medical)
+
+| When you are… | Primary | Alternates | Layer |
+|---|---|---|---|
+| handling PHI / privacy | `ecc:healthcare-phi-compliance` | `ecc:hipaa-compliance` | skill |
+| EMR/EHR data patterns | `ecc:healthcare-emr-patterns` | — | skill |
+| clinical decision support | `ecc:healthcare-cdss-patterns` | — | skill |
+| evaluating a health-AI feature | `ecc:healthcare-eval-harness` | — | skill |
+
+## Design / UI
+
+| When you are… | Primary | Alternates | Layer |
+|---|---|---|---|
+| designing UI/UX | `ui-ux-pro-max` | `andrej-karpathy` | skill |
+| turning a mockup into UI code | `stitch` (MCP) | — | mcp |
+
+> **Deprecated — do not use:** `frontend-design` (replaced by `ui-ux-pro-max`).
+
+## Research, docs, MCP
+
+| When you are… | Primary | Alternates | Layer |
+|---|---|---|---|
+| researching an unknown topic | `ecc:deep-research` | `exa` (MCP) | skill |
+| looking up a library / API | `context7` (MCP) | `ecc:documentation-lookup` | mcp |
+| browser QA / e2e / visual check | `playwright` (MCP) | `ecc:e2e-testing` | mcp |
+| repo / PR operations | `ecc:pr` | `github` (MCP), `/pr` | skill |
+| need a capability you lack | `find-skills` | — | skill |
+
+## Presentation (HTML for humans)
+
+Render with `/present` when presentation mode is on (`rules/45-presentation.md`). HTML is an
+ephemeral view; the Markdown/spec stays canonical.
+
+| When you are… | Primary | Alternates | Layer |
+|---|---|---|---|
+| comparing specs / designs side by side | `/present` (HTML) | `superpowers:brainstorming` visual companion | command |
+| presenting a code review to a human | `/present` (HTML dashboard) | `ecc:code-review` | command |
+| writing a report / explainer | `/present` (HTML) | — | command |
+| showing a design prototype | `prototype` | `/present` (HTML) | skill |
+| building a custom editing UI (copy-as-JSON) | `/present` (HTML) | — | command |
+## Communication
+
+`pordee` (Thai-compressed) and `caveman` (terse) are session-level toggles set by the user.

package/.agents/skills/find-skills/SKILL.md

@@ -1,142 +1,142 @@
----
-name: find-skills
-description: Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.
----
-
-# Find Skills
-
-This skill helps you discover and install skills from the open agent skills ecosystem.
-
-## When to Use This Skill
-
-Use this skill when the user:
-
-- Asks "how do I do X" where X might be a common task with an existing skill
-- Says "find a skill for X" or "is there a skill for X"
-- Asks "can you do X" where X is a specialized capability
-- Expresses interest in extending agent capabilities
-- Wants to search for tools, templates, or workflows
-- Mentions they wish they had help with a specific domain (design, testing, deployment, etc.)
-
-## What is the Skills CLI?
-
-The Skills CLI (`npx skills`) is the package manager for the open agent skills ecosystem. Skills are modular packages that extend agent capabilities with specialized knowledge, workflows, and tools.
-
-**Key commands:**
-
-- `npx skills find [query]` - Search for skills interactively or by keyword
-- `npx skills add <package>` - Install a skill from GitHub or other sources
-- `npx skills check` - Check for skill updates
-- `npx skills update` - Update all installed skills
-
-**Browse skills at:** https://skills.sh/
-
-## How to Help Users Find Skills
-
-### Step 1: Understand What They Need
-
-When a user asks for help with something, identify:
-
-1. The domain (e.g., React, testing, design, deployment)
-2. The specific task (e.g., writing tests, creating animations, reviewing PRs)
-3. Whether this is a common enough task that a skill likely exists
-
-### Step 2: Check the Leaderboard First
-
-Before running a CLI search, check the [skills.sh leaderboard](https://skills.sh/) to see if a well-known skill already exists for the domain. The leaderboard ranks skills by total installs, surfacing the most popular and battle-tested options.
-
-For example, top skills for web development include:
-- `vercel-labs/agent-skills` — React, Next.js, web design (100K+ installs each)
-- `anthropics/skills` — Frontend design, document processing (100K+ installs)
-
-### Step 3: Search for Skills
-
-If the leaderboard doesn't cover the user's need, run the find command:
-
-```bash
-npx skills find [query]
-```
-
-For example:
-
-- User asks "how do I make my React app faster?" → `npx skills find react performance`
-- User asks "can you help me with PR reviews?" → `npx skills find pr review`
-- User asks "I need to create a changelog" → `npx skills find changelog`
-
-### Step 4: Verify Quality Before Recommending
-
-**Do not recommend a skill based solely on search results.** Always verify:
-
-1. **Install count** — Prefer skills with 1K+ installs. Be cautious with anything under 100.
-2. **Source reputation** — Official sources (`vercel-labs`, `anthropics`, `microsoft`) are more trustworthy than unknown authors.
-3. **GitHub stars** — Check the source repository. A skill from a repo with <100 stars should be treated with skepticism.
-
-### Step 5: Present Options to the User
-
-When you find relevant skills, present them to the user with:
-
-1. The skill name and what it does
-2. The install count and source
-3. The install command they can run
-4. A link to learn more at skills.sh
-
-Example response:
-
-```
-I found a skill that might help! The "react-best-practices" skill provides
-React and Next.js performance optimization guidelines from Vercel Engineering.
-(185K installs)
-
-To install it:
-npx skills add vercel-labs/agent-skills@react-best-practices
-
-Learn more: https://skills.sh/vercel-labs/agent-skills/react-best-practices
-```
-
-### Step 6: Offer to Install
-
-If the user wants to proceed, you can install the skill for them:
-
-```bash
-npx skills add <owner/repo@skill> -g -y
-```
-
-The `-g` flag installs globally (user-level) and `-y` skips confirmation prompts.
-
-## Common Skill Categories
-
-When searching, consider these common categories:
-
-| Category        | Example Queries                          |
-| --------------- | ---------------------------------------- |
-| Web Development | react, nextjs, typescript, css, tailwind |
-| Testing         | testing, jest, playwright, e2e           |
-| DevOps          | deploy, docker, kubernetes, ci-cd        |
-| Documentation   | docs, readme, changelog, api-docs        |
-| Code Quality    | review, lint, refactor, best-practices   |
-| Design          | ui, ux, design-system, accessibility     |
-| Productivity    | workflow, automation, git                |
-
-## Tips for Effective Searches
-
-1. **Use specific keywords**: "react testing" is better than just "testing"
-2. **Try alternative terms**: If "deploy" doesn't work, try "deployment" or "ci-cd"
-3. **Check popular sources**: Many skills come from `vercel-labs/agent-skills` or `ComposioHQ/awesome-claude-skills`
-
-## When No Skills Are Found
-
-If no relevant skills exist:
-
-1. Acknowledge that no existing skill was found
-2. Offer to help with the task directly using your general capabilities
-3. Suggest the user could create their own skill with `npx skills init`
-
-Example:
-
-```
-I searched for skills related to "xyz" but didn't find any matches.
-I can still help you with this task directly! Would you like me to proceed?
-
-If this is something you do often, you could create your own skill:
-npx skills init my-xyz-skill
-```
+---
+name: find-skills
+description: Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.
+---
+
+# Find Skills
+
+This skill helps you discover and install skills from the open agent skills ecosystem.
+
+## When to Use This Skill
+
+Use this skill when the user:
+
+- Asks "how do I do X" where X might be a common task with an existing skill
+- Says "find a skill for X" or "is there a skill for X"
+- Asks "can you do X" where X is a specialized capability
+- Expresses interest in extending agent capabilities
+- Wants to search for tools, templates, or workflows
+- Mentions they wish they had help with a specific domain (design, testing, deployment, etc.)
+
+## What is the Skills CLI?
+
+The Skills CLI (`npx skills`) is the package manager for the open agent skills ecosystem. Skills are modular packages that extend agent capabilities with specialized knowledge, workflows, and tools.
+
+**Key commands:**
+
+- `npx skills find [query]` - Search for skills interactively or by keyword
+- `npx skills add <package>` - Install a skill from GitHub or other sources
+- `npx skills check` - Check for skill updates
+- `npx skills update` - Update all installed skills
+
+**Browse skills at:** https://skills.sh/
+
+## How to Help Users Find Skills
+
+### Step 1: Understand What They Need
+
+When a user asks for help with something, identify:
+
+1. The domain (e.g., React, testing, design, deployment)
+2. The specific task (e.g., writing tests, creating animations, reviewing PRs)
+3. Whether this is a common enough task that a skill likely exists
+
+### Step 2: Check the Leaderboard First
+
+Before running a CLI search, check the [skills.sh leaderboard](https://skills.sh/) to see if a well-known skill already exists for the domain. The leaderboard ranks skills by total installs, surfacing the most popular and battle-tested options.
+
+For example, top skills for web development include:
+- `vercel-labs/agent-skills` — React, Next.js, web design (100K+ installs each)
+- `anthropics/skills` — Frontend design, document processing (100K+ installs)
+
+### Step 3: Search for Skills
+
+If the leaderboard doesn't cover the user's need, run the find command:
+
+```bash
+npx skills find [query]
+```
+
+For example:
+
+- User asks "how do I make my React app faster?" → `npx skills find react performance`
+- User asks "can you help me with PR reviews?" → `npx skills find pr review`
+- User asks "I need to create a changelog" → `npx skills find changelog`
+
+### Step 4: Verify Quality Before Recommending
+
+**Do not recommend a skill based solely on search results.** Always verify:
+
+1. **Install count** — Prefer skills with 1K+ installs. Be cautious with anything under 100.
+2. **Source reputation** — Official sources (`vercel-labs`, `anthropics`, `microsoft`) are more trustworthy than unknown authors.
+3. **GitHub stars** — Check the source repository. A skill from a repo with <100 stars should be treated with skepticism.
+
+### Step 5: Present Options to the User
+
+When you find relevant skills, present them to the user with:
+
+1. The skill name and what it does
+2. The install count and source
+3. The install command they can run
+4. A link to learn more at skills.sh
+
+Example response:
+
+```
+I found a skill that might help! The "react-best-practices" skill provides
+React and Next.js performance optimization guidelines from Vercel Engineering.
+(185K installs)
+
+To install it:
+npx skills add vercel-labs/agent-skills@react-best-practices
+
+Learn more: https://skills.sh/vercel-labs/agent-skills/react-best-practices
+```
+
+### Step 6: Offer to Install
+
+If the user wants to proceed, you can install the skill for them:
+
+```bash
+npx skills add <owner/repo@skill> -g -y
+```
+
+The `-g` flag installs globally (user-level) and `-y` skips confirmation prompts.
+
+## Common Skill Categories
+
+When searching, consider these common categories:
+
+| Category        | Example Queries                          |
+| --------------- | ---------------------------------------- |
+| Web Development | react, nextjs, typescript, css, tailwind |
+| Testing         | testing, jest, playwright, e2e           |
+| DevOps          | deploy, docker, kubernetes, ci-cd        |
+| Documentation   | docs, readme, changelog, api-docs        |
+| Code Quality    | review, lint, refactor, best-practices   |
+| Design          | ui, ux, design-system, accessibility     |
+| Productivity    | workflow, automation, git                |
+
+## Tips for Effective Searches
+
+1. **Use specific keywords**: "react testing" is better than just "testing"
+2. **Try alternative terms**: If "deploy" doesn't work, try "deployment" or "ci-cd"
+3. **Check popular sources**: Many skills come from `vercel-labs/agent-skills` or `ComposioHQ/awesome-claude-skills`
+
+## When No Skills Are Found
+
+If no relevant skills exist:
+
+1. Acknowledge that no existing skill was found
+2. Offer to help with the task directly using your general capabilities
+3. Suggest the user could create their own skill with `npx skills init`
+
+Example:
+
+```
+I searched for skills related to "xyz" but didn't find any matches.
+I can still help you with this task directly! Would you like me to proceed?
+
+If this is something you do often, you could create your own skill:
+npx skills init my-xyz-skill
+```