♻️ Add when to use sections to all skills

Every skill in .opencode/skills now carries a "When to use" section:
triggers in any phrasing plus the matching /command for the flow
skills, one-line triggers for the utility skills, an
explicit-invocation mirror for ste, and the proactive case for
resolve-git-conflicts.

code-review-criteria drops its old usage bullets ("before merging any
PR ...") for the same role pattern as plan-review-criteria: loaded by
the reviewer subagent of the review-code flow, redirect there to
review code. Flow and criteria skills no longer compete for the same
trigger.

AI-assisted-by: omen-alpha

.opencode/skills/bat-cat/SKILL.md

@@ -9,6 +9,11 @@ metadata: {"clawdbot":{"emoji":"🦇","requires":{"bins":["bat"]},"install":[{"i
 
 `cat` with syntax highlighting, line numbers, and Git integration.
 
+## When to use
+
+- Reading or displaying a file in the terminal — prefer it over plain
+  `cat`: syntax highlighting, line numbers, git-side indicators.
+
 ## Quick Start
 
 ### Basic usage

.opencode/skills/code-review-criteria/SKILL.md

@@ -13,11 +13,10 @@ Multi-dimensional code review with quality gates. Every change gets reviewed bef
 
 ## When to Use
 
-- Before merging any PR or change
+- The reviewer subagent of the `review-code` flow loads this skill to perform
-- After completing a feature implementation
+  the review of a code change.
-- When another agent or model produced code you need to evaluate
+- To review code, always go through the `review-code` flow — never load this
-- When refactoring existing code
+  skill directly for that. This is the criteria reference, not the flow.
-- After any bug fix (review both the fix and the regression test)
 
 ## Core Principles
 

.opencode/skills/fd-find/SKILL.md

@@ -9,6 +9,11 @@ metadata: {"clawdbot":{"emoji":"📂","requires":{"bins":["fd"]},"install":[{"id
 
 User-friendly alternative to `find` with smart defaults.
 
+## When to use
+
+- Locating files or directories by name or pattern — prefer it over
+  plain `find`: simpler syntax, smart defaults, respects `.gitignore`.
+
 ## Quick Start
 
 ### Basic search

.opencode/skills/implement-plan/SKILL.md

@@ -9,6 +9,16 @@ This flow is run once a plan is ready (for example, from plan mode). Execute
 the plan already prepared in the current session context. This flow ends
 with exactly one commit. It never pushes — the user pushes.
 
+## When to use
+
+- The user asks to implement or execute a plan, in any phrasing:
+  "implement the plan", "execute it", "go build it" — or runs
+  `/implement-plan`.
+- A ready, reviewed plan is in the session context or a plan file path
+  was given (typically after `/make-a-plan` or `/review-plan`).
+
+Do not use it to produce plans — that is the `make-a-plan` flow.
+
 ## 1. Detect the flow (no questions)
 
 Inspect the current branch with `git rev-parse --abbrev-ref HEAD`, pick the

.opencode/skills/jq-json-processor/SKILL.md

@@ -9,6 +9,11 @@ metadata: {"clawdbot":{"emoji":"🔍","requires":{"bins":["jq"]},"install":[{"id
 
 Process, filter, and transform JSON data with jq.
 
+## When to use
+
+- Parsing, filtering, or transforming JSON from commands, files, or API
+  responses — slicing, reshaping, or validating JSON output.
+
 ## Quick Examples
 
 ### Basic filtering

.opencode/skills/make-a-plan/SKILL.md

@@ -11,6 +11,16 @@ produce a well-grounded, actionable implementation plan.
 If the running agent cannot write (for example, the plan agent), say so and
 stop — this skill needs the build agent to save the plan.
 
+## When to use
+
+- The user asks to plan, design, or break down a task, in any phrasing:
+  "make a plan", "how would we build X", "design an approach for Y" —
+  or runs `/make-a-plan`.
+- The user asks to rework or extend an existing plan (for example, after
+  review findings) — revise the saved plan file in place.
+
+Do not use it to execute a plan — that is the `implement-plan` flow.
+
 ## Instructions
 
 1. **Produce the plan** with the `planner` skill. By default, research the

.opencode/skills/nrepl-eval/SKILL.md

@@ -10,6 +10,12 @@ Evaluate Clojure (or ClojureScript) code via a running nREPL server using
 
 Full documentation: `mem:scripts/nrepl-eval` (file: `.serena/memories/scripts/nrepl-eval.md`)
 
+## When to use
+
+- Evaluating Clojure or ClojureScript code against the running nREPL
+  sessions (backend 6064, frontend 3447) — live inspection, patching, or
+  debugging.
+
 ## Quick Reference
 
 ```bash

.opencode/skills/resolve-git-conflicts/SKILL.md

@@ -9,6 +9,13 @@ Resolve conflicts in the local repository. The user handles finishing the
 rebase themselves — you must **never** run `git rebase --continue`,
 `git rebase --skip`, `git merge --continue`, or anything similar.
 
+## When to use
+
+- The repository has unresolved conflicts — during a rebase, merge, or
+  cherry-pick — whether the user asks about them or not.
+- The user asks to resolve conflicts, in any phrasing: "fix the merge
+  conflicts", "resolve these", "what's conflicting here?".
+
 ## Phase 1 — Understand the problem (read-only)
 
 1. Run `git status` to detect the conflict state (rebase, merge, cherry-pick, etc.) and list conflicted files.

.opencode/skills/review-code/SKILL.md

@@ -7,6 +7,14 @@ description: Code review flow — review a diff, PR, or code change, delegating
 
 Act as a senior software engineer and perform a thorough code review.
 
+## When to use
+
+- The user asks to review code, in any phrasing: "review this diff",
+  "review the PR", "check my changes", "code review" — or runs
+  `/review-code`.
+- A commit, branch, PR, or diff is ready and the user wants it assessed
+  before merge.
+
 ## Instructions
 
 1. **Determine what is being reviewed** from the user context: a working-tree

.opencode/skills/review-plan/SKILL.md

@@ -8,6 +8,14 @@ description: Plan review flow — evaluate an implementation plan before it is e
 Act as a senior software engineer and perform a thorough review of an
 implementation plan.
 
+## When to use
+
+- The user asks to review a plan, in any phrasing: "review this plan",
+  "does this plan look right?", "second opinion on the plan" — or runs
+  `/review-plan`.
+- A plan was just produced (typically by `/make-a-plan`) and the user
+  wants it evaluated before executing it.
+
 ## Instructions
 
 1. **Determine the plan under review** from the session context (for example, a

.opencode/skills/ripgrep/SKILL.md

@@ -9,6 +9,11 @@ metadata: {"clawdbot":{"emoji":"🔎","requires":{"bins":["rg"]},"install":[{"id
 
 Fast, smart recursive search. Respects `.gitignore` by default.
 
+## When to use
+
+- Searching file contents across the repo for regex patterns — the
+  default code search, respects `.gitignore`.
+
 ## Quick Start
 
 ### Basic search

.opencode/skills/ste/SKILL.md

@@ -9,6 +9,13 @@ Apply the ASD-STE100 standard to all prose you produce in this task. Do not anno
 
 Compliance note (for you, not for output): the official specification and its dictionary are copyright ASD. This skill encodes paraphrased rules and a publicly sourced word list. For certified aerospace/defense deliverables, tell the user that full compliance requires the free official specification (asd-ste100.org) and a human sign-off. Never claim certified compliance.
 
+## When to use
+
+Only when the user explicitly invokes it: they type `/ste`, or say "use
+the ste skill" / "apply ASD-STE100". Requests like "simplify this",
+"make it clearer", or "shorter sentences" do NOT invoke it — respond
+normally unless it is named.
+
 ## Step 0 — Classify the text
 
 Before writing a single sentence, decide: is this **procedural** text (instructions someone follows) or **descriptive** text (explanation, background, description)? Every limit below depends on this. Mixed documents get classified section by section.

.opencode/skills/taiga/SKILL.md

@@ -11,6 +11,12 @@ Fetch information from Taiga public API for the **Penpot** project
 
 **No authentication required** — only public project data is accessed.
 
+## When to use
+
+- The user asks about Penpot issues, user stories, or tasks tracked in
+  Taiga — fetch them via the public API (project id 345963), no
+  authentication needed.
+
 ## Prerequisites
 
 - `python3` — the `scripts/taiga.py` CLI script is self-contained (stdlib only)