@lovehlmmm/primekit 1.0.0

package/skills/fable-thinking/references/design-taste.md

@@ -0,0 +1,182 @@
+# Design Taste — the reasoning protocol applied to UI/UX and frontend work
+
+Fable Thinking's moves, applied to the one domain where models are most confidently
+wrong about their own output: visual design. Code either passes tests or fails them;
+design "looks fine" to the model that produced it, always, because the model never sees
+it. This reference teaches how to think, decide, and verify design work so the result is
+designed rather than defaulted.
+
+If the runtime also has `pk:frontend-design` available, load it for the full
+implementation rulebook (palettes, type pairings, numeric craft rules); this reference
+governs the judgment and verification layer and never conflicts with it.
+
+## When to load this reference
+
+Load BEFORE writing the first line of markup, styles, or component code — not after —
+whenever the deliverable is a user-facing surface:
+
+- building or restyling pages, components, dashboards, landing pages, emails, slides,
+  HTML artifacts, TUIs, charts
+- reviewing or critiquing UI code, screenshots, or live pages
+- choosing colors, typography, spacing, layout, or a design system
+- any task whose output a human will look at and judge, not just execute
+
+The trigger is the deliverable type, not the words in the prompt. "Make a quick page for
+X" is a design task; the word "design" need not appear.
+
+## Know Your Own Defaults (why model-generated design converges on slop)
+
+These are the design-domain instances of the failure modes in SKILL.md:
+
+- **Mode collapse / template gravity** — with no strong brief, you emit the statistical
+  mean of training data: one favorite palette, one favorite font, one favorite hero
+  layout, identical card grids. The output is not wrong; it is the average, and average
+  reads as machine-made. Distinctive requires a deliberate choice made early.
+- **Decoration ≠ design** — when unsure, you add (gradients, shadows, glows, badges,
+  ornaments) instead of removing. Good design is mostly subtraction: fewer colors, fewer
+  weights, fewer boxes, more space. If an element encodes no information, it is noise.
+- **Render blindness** — the design-domain form of surface blindness. You emit code and
+  imagine the result; the imagined render is always flattering. Overflow, wrapping,
+  contrast failures, misalignment, and collision are invisible in source form. A claim
+  that a layout "works" is ASSUMED until the artifact is rendered and inspected, or the
+  specific property is computed.
+- **Uniform emphasis** — everything bold, everything colored, every section decorated.
+  Hierarchy means choosing what loses. If every element shouts, the design says nothing.
+- **Happy-path bias** — you design one state: medium-length content, loaded data, desktop
+  width, light mode, mouse input. Real interfaces spend most of their life in the other
+  states.
+- **Completion pressure** — shipping the first composition that renders without errors.
+  Rendering without errors is the floor of correctness, not evidence of quality.
+
+## How to think (the moves, in design order)
+
+1. **FRAME the screen's job.** One sentence: who is looking at this, and what is the ONE
+   thing they must see or do first? Name the emotional register the content deserves —
+   calm utility, dense data, bold marketing, editorial warmth — and let it be a decision,
+   not a leftover. A dashboard and a landing page with the same styling means no decision
+   was made.
+2. **Rank before you draw.** List every element the surface must carry, ordered by
+   importance to the user's job. The finished design's visual weight (size, contrast,
+   position, whitespace) must reproduce that ranking. This list is the load-bearing fact
+   of the whole task; most bad layouts are correct CSS applied to an unranked list.
+3. **Choose the system before the parts.** Fix the design tokens first: one accent color
+   plus a neutral ramp; at most two type families; a spacing scale; a radius and shadow
+   scale. Then every value in the output comes from the scale. Ad-hoc values are how
+   consistency dies one line at a time.
+4. **Design with real content.** Use realistic longest-case and shortest-case content
+   from the start — real names, real numbers, empty lists, missing images. Content is a
+   constraint, not a filler; lorem ipsum defers every hard decision to the moment you can
+   no longer make it.
+5. **Subtract before delivering.** One deliberate pass: remove every element, color,
+   border, shadow, and animation whose absence loses no information. What survives is
+   the design.
+
+## What good design is (evaluable, not vibes)
+
+A surface is well designed when each of these holds and can be shown to hold:
+
+- **Legible hierarchy** — a viewer squinting at it (or seeing it for three seconds) can
+  point at the most important element, and it is the intended one.
+- **One voice of emphasis** — a single accent does all the "look here" work; neutrals do
+  everything else. Emphasis spent everywhere is emphasis spent nowhere.
+- **Rhythm** — spacing values come from one scale; edges align to a grid; equal-status
+  elements are visually equal. The eye notices misalignment before the mind does.
+- **Readable text** — body contrast meets WCAG AA (4.5:1; 3:1 for large text), line
+  length stays in the 45–75 character range, line height gives dense scripts and
+  diacritics room. These are computable properties, not opinions.
+- **Designed states** — hover, focus, active, disabled, empty, loading, error, and
+  overflowing content all have an intended appearance, chosen rather than inherited.
+- **Fit** — the styling belongs to THIS content, audience, and brand. The test: swap in a
+  different product's copy; if the design fits it just as well, the design fit nothing.
+
+## What to avoid (the slop catalog — matches are failed gates, not style choices)
+
+- The default-everything stack: the same overused font on the same neutral panel behind
+  a violet-to-blue gradient hero with three equal feature cards.
+- Glassmorphism, neon glows, and gradient text as substitutes for a composition.
+- Emoji as icons or bullets in professional surfaces.
+- Decoration stacking: shadow + border + gradient + rounded + glow on one element.
+- Center-aligned paragraphs; full-viewport-width text lines.
+- Gray-on-gray body text that fails a contrast computation.
+- Five font sizes where three steps would do; arbitrary values off the spacing scale.
+- Animating everything; motion that communicates nothing; parallax by default.
+- Placeholder tells: lorem ipsum, "John Doe", obvious stock imagery, fake logos.
+- Uniform card grids regardless of whether the content is uniform.
+
+## Details models habitually miss
+
+Enumerate these deliberately — negative-space scanning, because absence is invisible:
+
+- Focus visibility and tab order; hover-only affordances that break on touch; touch
+  targets below ~44px.
+- The longest realistic string: an unbroken URL, a German compound, a 40-character name —
+  where does it wrap, clip, or push the layout?
+- Non-Latin and diacritic-heavy text (Vietnamese stacked marks, CJK) clipped by tight
+  line heights or wrong font fallbacks.
+- Dark mode as a re-decision, not an inversion: shadows stop working, borders must take
+  over, saturated accents need re-tuning.
+- Empty, loading, and error states — the states users actually meet first.
+- Tables: numeric columns right-aligned with tabular figures; header alignment matching
+  the data; horizontal overflow contained in its own scroll region.
+- Optical versus box alignment: icons beside text, play buttons in circles — centered
+  boxes that look off-center.
+- Layout shift while fonts and images load; sticky elements covering content; z-index
+  collisions; mobile safe-area insets.
+- Print/export appearance when the artifact is a document or slide.
+
+## Verify (render blindness makes this mandatory, not optional)
+
+Apply the Harness Leverage rule: anything a granted capability can check must be checked
+with it, as a loop, until a full pass over the final artifact is clean.
+
+1. **Render it.** If the harness grants a browser, screenshot, or preview capability,
+   render the artifact and look at it — at a phone width, a tablet width, and a desktop
+   width. Judging design from source code is reasoning about a render you never saw:
+   ASSUMED wearing OBSERVED grammar.
+2. **Squint test on the render.** Blur or shrink it: does the intended #1 element win?
+   Does the reading order match the importance ranking from FRAME?
+3. **Stress the content.** Swap in the longest realistic strings, an empty collection, a
+   large collection, missing images. Re-render; look again.
+4. **Compute the computable.** Contrast ratios, line length, type scale steps, spacing
+   values against the scale — these are arithmetic. Compute or script them; never
+   eyeball a number a formula settles.
+5. **Walk the states.** Tab through with a keyboard; trigger hover, focus, disabled,
+   loading, error, empty. Every state either has a designed appearance or is a finding.
+6. **Scan against the slop catalog and the missed-details list**, item by item, as a
+   checklist — not from memory of having "kept them in mind".
+7. **Repair and re-verify.** Fixes change layout; a fix can break a neighbor. Loop until
+   one complete pass over the final artifact is clean.
+
+Where the harness grants no renderer, say so in the delivery, downgrade every visual
+claim to DERIVED or ASSUMED, and compensate by computing everything computable (step 4)
+and hand-tracing the layout with concrete content lengths.
+
+## Evaluate before delivering (act-backed, per the Self-Review Gate)
+
+Each verdict must point to the act that proved it:
+
+| Dimension | Passes when | Proven by |
+|-----------|-------------|-----------|
+| Hierarchy | #1 element wins the squint test | rendered inspection |
+| Consistency | all values on the token scales | token audit / grep |
+| Readability | contrast, measure, line height in range | computation |
+| States | interaction + data states designed | state walk |
+| Robustness | survives longest/empty/overflow content | stress render |
+| Distinctiveness | zero slop-catalog matches; fits this brief | checklist scan |
+
+Deliver with Claim Discipline: "verified at three widths with stressed content" is a
+different — and honest — claim than "this should look good". If a dimension was not
+verified, name it as the weakest link instead of letting fluent delivery imply it.
+
+## Do / Don't
+
+| Don't | Instead |
+|-------|---------|
+| Start typing markup from the prompt | FRAME the job, rank the elements, fix the tokens first |
+| Judge the design from its source code | Render it and look, or downgrade the claim honestly |
+| Add decoration when a section feels weak | Subtract noise; strengthen hierarchy or content |
+| Emphasize everything that seems important | Pick what loses; one accent voice |
+| Design with lorem ipsum and medium-length data | Use real longest/shortest/empty content from the start |
+| Eyeball contrast, measure, and spacing | Compute them — they are arithmetic |
+| Ship the first error-free render | Run the stress + states + slop passes, then loop repairs |
+| Restyle what the brief did not ask about | Scope line from Move 1: flag adjacent issues, one sentence |

package/skills/fable-thinking/references/worked-examples.md

@@ -0,0 +1,228 @@
+# Worked Examples — Default Mode vs. Fable Thinking
+
+Four end-to-end traces showing the protocol applied. Each starts with the reasoning a
+model produces by default, then the protocol run. The point is not that the default answer
+is always wrong — it is that when it is wrong, nothing in the default process would have
+caught it.
+
+---
+
+## Example 0 — The outage report (the Floor, alone, is enough)
+
+**Ask:** "Our company email server went down an hour ago. Should I report the outage to
+IT by email or by phone? Email would give us a paper trail."
+
+### Default-mode run
+
+"Email — a written report creates a paper trail, gives IT the details in searchable form,
+and lets them triage asynchronously." Fluent, process-flavored, delivered with total
+confidence — and wrong. The surface ("which reporting channel is better?") matched the
+written-beats-verbal template; the template answered; the first sentence of the actual
+question never got read. This is template hijack, and the trap is baited precisely to
+look too trivial to check — the paper-trail detail is there to feed the template.
+
+### Protocol run (the Floor only — no five moves needed)
+
+**Goal.** Main verb: *report*; object: *the outage*. End-state: *IT knows the email
+server is down.* Note two things about that sentence. It names the object's finished
+state, not a milestone — "the report was sent" would be a milestone, and milestones are
+where wrong answers hide. And it mentions neither "email" nor "phone": a goal statement
+that contains one of the offered options is the question's framing smuggled in as the
+goal, and it makes every later check pass vacuously ("email → report sent → done").
+
+**Follow-through.** Run the movie for "email" — all the way to the goal-check frame, not
+just to "sent": you compose the report and hit send; the message enters the down email
+server; it never reaches IT; at the final frame IT still does not know. The goal state
+fails — "email" was never an answer to this question, however good its paper trail would
+be. A run that stops at "sent" would have scored both options as fine; the trap only
+becomes visible at the last frame.
+
+**Leftovers.** The draft answer never used "email server went down" — the one detail
+that decides everything. The paper-trail argument is bait: it makes channel quality feel
+like the decision when channel *availability* is.
+
+**Answer.** "Phone — the report has to travel over a channel that is still up, and email
+is the thing that's broken. If you want the paper trail, follow up with a written ticket
+once the server is restored."
+
+### Same trap, other costumes
+
+- "Print the return-shipping label and seal it inside the box" (the carrier reads the
+  outside of the box)
+- Any question where one option routes the fix through the broken thing, or quietly
+  leaves the goal's object behind — the errand that needs the object present, the
+  message sent over the dead channel, the backup stored on the failing disk.
+
+The transferable rule: an answer is an action in the world — check it against the world,
+not against the question's multiple-choice framing. The trap is never this specific
+question; it is any question where a stored template answers before the details are
+read. Total cost of the check: about three sentences of thought.
+
+---
+
+## Example 1 — Bug diagnosis: the "flaky" CI test
+
+**Ask:** "TestCheckoutTotal fails randomly in CI, maybe 1 run in 5. Can you fix the flake?"
+
+### Default-mode run
+
+"Intermittent CI failure" pattern-matches to timing. Add a retry annotation or a sleep,
+CI goes green, done. Symptom suppressed; cause still in the codebase; the test no longer
+guards anything.
+
+Failure modes: pattern-match satisfaction, frame adoption (the word "flaky" was inherited
+as a diagnosis — it is testimony), completion pressure (green CI feels like done).
+
+### Protocol run
+
+**Move 1 — FRAME.** Deliverable: root cause plus a fix that keeps the test meaningful —
+not green CI at any cost. Load-bearing fact to check first: is this actually
+nondeterministic timing, or deterministic under some hidden condition?
+
+**Move 2 — GROUND.** Read the actual failure output, literally. It is an assertion:
+`expected total 59.98, got 89.97` — a wrong VALUE, not a timeout, not a connection error.
+That single observation kills the timing frame: sleeps and retries cannot fix a wrong
+number. (OBSERVED. The "flaky = timing" idea was PRIOR all along.)
+
+**Move 3 — REASON.** The wrong value equals the correct total plus one extra item, so
+state is leaking in from somewhere. Three hypotheses:
+
+- H1: test-order dependence — another test leaves data behind in a shared fixture.
+- H2: genuine race in the checkout code under parallel test execution.
+- H3: CI-environment difference (database version, locale, time zone).
+
+Discriminating checks, not confirming ones: run the failing test alone 20 times
+(splits H1 from H2/H3), then run the full suite with a fixed seed order (isolates H1's
+trigger). Result: alone, 20/20 green; full suite, fails exactly when `TestCartMerge` runs
+first. Mechanism, stated end-to-end: `TestCartMerge` inserts a cart row → its cleanup only
+runs on the success path → package-level fixture reuses the connection → leftover row joins
+into checkout's total. Every step checkable; H2 and H3 discarded on evidence, not vibes.
+
+**Move 4 — ATTACK.** Strongest objection: "maybe there is also a race, and order-dependence
+is masking it." Cheap kill-test: apply the cleanup fix, run the suite 20 times in parallel
+mode — 20/20 green. Weakest link, said out loud: 20 runs bounds the flake rate, it does not
+prove zero; the original failure rate (~1 in 5) would almost certainly have reappeared.
+
+**Move 5 — DELIVER.** "The test is not flaky — it is order-dependent. `TestCartMerge`
+skips cleanup on its failure path and leaks a cart row into the shared fixture;
+`TestCheckoutTotal` then sums the extra item (59.98 + 29.99 = 89.97, the exact failure
+value). Fixed by moving cleanup to a deferred/teardown block. Evidence: 20/20 green in
+isolation before the fix, 20/20 green in full parallel suite after. Open risk: 20 runs
+bounds but does not prove; if it ever recurs, the fixture itself should stop being shared."
+
+---
+
+## Example 2 — Code review: the innocent retry change
+
+**Ask:** Review a small PR: "extend the HTTP retry helper to also retry on 4xx — fixes
+checkout flakiness we saw on Friday." Diff is four clean lines.
+
+### Default-mode run
+
+The diff is small, readable, well-tested for style; existing tests pass. "LGTM, maybe add
+a comment." The review evaluated the text of the change, never its meaning.
+
+Failure modes: reviewing at the wrong altitude (mechanics instead of design), no invariant
+ledger, frame adoption ("fixes flakiness" accepted as true because the author said so).
+
+### Protocol run
+
+**Move 1 — FRAME.** Deliverable: a verdict on whether this change is safe and actually
+fixes Friday's problem. Load-bearing facts: what does "retry" promise callers today, and
+what actually failed on Friday?
+
+**Move 2 — GROUND.** Two lookups, both cheap. The helper's contract (docstring plus call
+sites): "retries transient failures; safe because requests are idempotent." Friday's
+incident log: the checkout errors were `429 Too Many Requests` — not a generic 4xx.
+
+**Move 3 — REASON.** Invariant ledger for the change:
+
+- **Preserves:** function signature, call sites compile untouched.
+- **Breaks (silently):** the semantic contract. 4xx responses are deterministic client
+  errors — retrying a 400/401/403 cannot succeed and now hammers the API; retrying a POST
+  that returned 402/409 risks duplicate side effects on non-idempotent endpoints.
+- **Risks:** rate-limit amplification — retrying 429s *without backoff* makes Friday's
+  incident worse, not better.
+
+Negative space scan: no test exercises the new retried class; no idempotency guard was
+added; no backoff/jitter accompanies the one status (429) that genuinely deserves retrying.
+Altitude check: the failure is being patched at implementation level, but it lives at
+design level — "which failures are retryable" is a contract question, not a loop condition.
+
+**Move 4 — ATTACK.** Objection to my own verdict: "maybe their API returns 4xx for
+transient states." Kill-test: grep the API client for status handling and check the
+provider's docs — transient states are 429 and 503 only. Objection survives nowhere.
+
+**Move 5 — DELIVER.** "Request changes — this widens retries to all 4xx, but Friday's
+failures were specifically 429s. Retrying deterministic 4xxs cannot succeed, risks
+duplicate POST side effects, and retrying 429 without backoff amplifies the original
+incident. Suggest: retry 429 and 503 only, with exponential backoff and jitter, plus a
+test for each. The four lines are clean; the contract they change is not."
+
+---
+
+## Example 3 — Analysis: the conversion drop that wasn't
+
+**Ask:** "Signup conversion dropped ~30% last week. It has to be the new pricing page —
+rewrite it before we lose more."
+
+### Default-mode run
+
+Accept the frame, audit the pricing page, produce a persuasive rewrite. If the real cause
+lies elsewhere, the rewrite ships noise, the actual problem keeps burning, and next week
+the same conversation happens angrier.
+
+Failure modes: frame adoption (user's diagnosis taken as fact), no discriminating evidence,
+answer-shaped output (a rewrite is deliverable-shaped regardless of whether it helps).
+
+### Protocol run
+
+**Move 1 — FRAME.** The user's goal is recovering signups — that is the contract. Their
+diagnosis (pricing page) is testimony. Deliverable: verified cause first, then the fix that
+matches it. Load-bearing fact: does the drop's timing actually line up with the pricing
+release?
+
+**Move 2 — GROUND.** Pull the numbers instead of reasoning about them. Daily signups and
+conversion rate for 21 days, plus deploy dates. OBSERVED: the drop starts Tuesday; the
+pricing page shipped Thursday. Two days of drop precede the alleged cause — the headline
+frame is dead on arrival, by timeline alone.
+
+**Move 3 — REASON.** Hypotheses for a Tuesday break:
+
+- H1: traffic mix shifted (a paid campaign paused → lower-intent visitors dominate).
+- H2: measurement broke (an analytics/consent change dropped signup events).
+- H3: a funnel step actually broke for some segment (form, email verification).
+
+Discriminating check: compare *dashboard* signup events against *database* account
+creations for the same window. That one comparison splits H2 from H1/H3 cleanly.
+Result: database signups are flat week-over-week; dashboard events are down 30%. The
+business did not lose signups — the tracker lost events. Mechanism: Tuesday's release
+notes show a consent-banner update; the signup event now fires only after analytics
+consent, so non-consenting users' signups vanished from the dashboard while remaining in
+the database. Every step checkable.
+
+**Move 4 — ATTACK.** Objection: "maybe both — tracking broke AND pricing hurt
+conversion." Kill-test: recompute conversion from database signups over pricing-page
+sessions for the three days since Thursday — flat versus the prior week, within noise.
+Weakest link: three days is a short window for the pricing verdict; say so.
+
+**Move 5 — DELIVER.** "Your signups did not drop — your measurement did. Database account
+creations are flat; the 30% fall exists only in analytics events, and it starts Tuesday
+with the consent-banner release (signup events now fire only after consent), two days
+before the pricing page shipped. Fix the event wiring, not the pricing copy. The pricing
+page shows no conversion effect in database-side numbers so far — though three days is a
+thin sample, so re-check after a full week. Rewriting the page now would have treated a
+healthy patient."
+
+---
+
+## What the four runs share
+
+The protocol paid for itself at the same joints each time. In Example 0 the Floor alone —
+goal end-state, follow-through, leftover details — did all the work before any move ran.
+In the other three: one literal look at primary evidence killed an inherited frame
+(Move 2); a second hypothesis plus one discriminating check replaced pattern-matching
+(Move 3); one cheap kill-test either hardened or corrected the conclusion before it
+shipped (Move 4); and the delivery led with the verdict, typed its claims, and named its
+weakest link (Move 5). None of it required a smarter model — only a model that refuses to
+skip the looking.

package/skills/find-skills/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: pk: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.
+user-invocable: true
+when_to_use: "Invoke when the user is looking for a skill capability."
+category: dev-tools
+keywords: [discover, install, skills, search]
+argument-hint: "[capability or task description]"
+metadata:
+  author: primekit
+  version: "1.0.0"
+---
+
+# 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.)
+
+## Local PrimeKit Routing
+
+If the user is choosing between installed PrimeKit skills, load
+`references/domain-routing.md` before using the Skills CLI. Use the CLI flow
+below only when discovering or installing external skills.
+
+## 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: Search for Skills
+
+Run the find command with a relevant query:
+
+```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`
+
+The command will return results like:
+
+```
+Install with npx skills add <owner/repo@skill>
+
+vercel-labs/agent-skills@vercel-react-best-practices
+└ https://skills.sh/vercel-labs/agent-skills/vercel-react-best-practices
+```
+
+### Step 3: 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 command they can run
+3. A link to learn more at skills.sh
+
+Example response:
+
+```
+I found a skill that might help! The "vercel-react-best-practices" skill provides
+React and Next.js performance optimization guidelines from Vercel Engineering.
+
+To install it:
+npx skills add vercel-labs/agent-skills@vercel-react-best-practices
+
+Learn more: https://skills.sh/vercel-labs/agent-skills/vercel-react-best-practices
+```
+
+### Step 4: 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
+```

package/skills/find-skills/references/domain-routing.md

@@ -0,0 +1,108 @@
+# PrimeKit Domain Routing
+
+Use this file only when choosing between installed PrimeKit skills. If the user
+asks to discover or install external skills, return to `../SKILL.md` and use the
+Skills CLI flow.
+
+## Routing Rules
+
+- If the user names a skill, use that skill.
+- Pick one primary skill per distinct intent. Mention secondary skills only as
+  follow-up helpers.
+- If the task needs a multi-step sequence, read
+  `../../cook/references/workflow-routing.md` after choosing the primary skill.
+- If two skills overlap, prefer the more specific domain skill over a generic
+  workflow skill.
+
+## Frontend and UI
+
+| User intent | Primary skill |
+|---|---|
+| Replicate a mockup, screenshot, or video | `/pk:frontend-design` |
+| Build React or TypeScript components | `/pk:frontend-development` |
+| Style with Tailwind or shadcn/ui | `/pk:ui-styling` |
+| Choose color, typography, layout, or design system | `/pk:ui-ux-pro-max` |
+| Audit UI accessibility or UX | `/pk:web-design-guidelines` |
+| Apply React or Next.js performance patterns | `/pk:react-best-practices` |
+| Generate UI designs with Stitch | `/pk:stitch` |
+| Build 3D, WebGL, or Three.js scenes | `/pk:threejs` |
+| Write shaders or procedural graphics | `/pk:shader` |
+| Create an editable Excalidraw canvas or codebase map | `/pk:excalidraw` |
+
+## Codebase Understanding
+
+| User intent | Primary skill |
+|---|---|
+| Locate files or understand code quickly | `/pk:scout` |
+| Pack a repository for LLM use | `/pk:repomix` |
+| Semantic go-to-definition or find-usages | `/pk:gkg` |
+| Build a queryable knowledge graph | `/pk:graphify` |
+
+## Backend, Data, and Auth
+
+| User intent | Primary skill |
+|---|---|
+| Build REST, GraphQL, or backend services | `/pk:backend-development` |
+| Add auth, OAuth, sessions, or passkeys | `/pk:better-auth` |
+| Design schemas or write SQL/NoSQL queries | `/pk:databases` |
+| Integrate Stripe, Polar, Paddle, or SePay | `/pk:payment-integration` |
+
+## Infrastructure and Security
+
+| User intent | Primary skill |
+|---|---|
+| Deploy to hosted platforms | `/pk:deploy` |
+| Docker, Kubernetes, CI/CD, or cloud ops | `/pk:devops` |
+| STRIDE/OWASP audit with remediation | `/pk:security` |
+| Secret, dependency, or vulnerability scan | `/pk:security-scan` |
+| OSINT or cyber threat intelligence | `/pk:cti-expert` |
+
+## AI, MCP, and Browser Automation
+
+| User intent | Primary skill |
+|---|---|
+| Context, memory, or agent architecture | `/pk:context-engineering` |
+| Generate `llms.txt` | `/pk:llms` |
+| Build Google ADK agents | `/pk:google-adk-python` |
+| Build MCP servers | `/pk:mcp-builder` |
+| Convert code into CLI/MCP surface | `/pk:agentize` |
+| Discover or execute MCP tools | `/pk:use-mcp` |
+| Test generic browser workflows | `/pk:agent-browser` |
+| Use the user's real Chrome profile | `/pk:chrome-profile` |
+
+## Testing, Docs, and Media
+
+| User intent | Primary skill |
+|---|---|
+| Run tests, coverage, or TDD gates | `/pk:test` |
+| Playwright, Vitest, k6, visual or a11y tests | `/pk:web-testing` |
+| Project docs init/update/summarize | `/pk:docs` |
+| Library/framework docs lookup | `/pk:docs-seeker` |
+| Visual explanation, preview, slides, or diagrams | `/pk:preview` |
+| Editorial-grade PNG/SVG or animated MP4/GIF diagrams (24 templated types + animation catalog) | `/pk:diagram` |
+| Mermaid syntax | `/pk:mermaidjs-v11` |
+| Publish-grade technical diagrams (non-templated) | `/pk:tech-graph` |
+| Video/audio/image processing | `/pk:media-processing` |
+| HTML-template video rendering | `/pk:html-video` |
+
+## Planning, Research, and Agent Workflow
+
+| User intent | Primary skill |
+|---|---|
+| Pressure-test a plan, design, or idea through an interview | `/pk:advise` |
+| Draft a self-contained brief for a researcher | `/pk:research-prompt` |
+| Preserve conversation state for a fresh agent | `/pk:handoff` |
+| Extract user decisions into a README, ADR, or structured document | `/pk:interview-docs` |
+| Create local context files for a subfolder | `/pk:folder-context` |
+| Prepare / preflight a long-running goal with an outcome lock | `/pk:goal-warmup` |
+| Run a durable Codex objective with a verifiable stop condition | `/pk:codex-goal` |
+| Benchmark a coding model on DeepSWE through OpenRouter | `/pk:deep-swe` |
+
+## Frameworks and Platforms
+
+| User intent | Primary skill |
+|---|---|
+| Next.js, App Router, RSC, Turborepo | `/pk:web-frameworks` |
+| TanStack Start/Form/AI | `/pk:tanstack` |
+| React Native, Flutter, SwiftUI, Kotlin | `/pk:mobile-development` |
+| Shopify apps, extensions, or themes | `/pk:shopify` |