fushiguro-mcp 0.2.0 → 0.6.0

package/README.md

@@ -144,7 +144,7 @@ Seven kinds of entry, each a markdown file with YAML frontmatter.
 | Kind | What it is |
 |---|---|
 | `agents/` | A specialist: a system prompt plus the tools, skills, runbooks, and connectors it works with. The router picks one per task. |
-| `skills/` | A reusable procedure attached to an agent's prompt when relevant. `always: true` attaches it to every agent. |
+| `skills/` | A reusable procedure attached to an agent's prompt when relevant. `always: true` attaches it to every agent. Ships with design craft (motion, taste, landing pages, iOS), grounding, and analysis skills. |
 | `knowledge/` | Your own documentation, chunked and full-text indexed. The folder name is the collection, which is how agent access is scoped. |
 | `runbooks/` | A team or project process guide — steps, owner, SLA, escalation. **Shipped as templates for you to complete.** |
 | `topics/` | A business domain that ties agents, skills, knowledge, runbooks, and connectors together. |
@@ -234,6 +234,122 @@ Agents declare `intake:` questions to put to the user before work of that kind s
 
 Questions the request already answers are dropped, so answering in the first message means you are not asked again. Asking about a stack the user already named is the fastest way to get an intake step ignored entirely.
 
+## Installing skills from the ecosystem
+
+There is a growing body of open Agent Skills, and this reads that format directly. Seven collections are curated in:
+
+```bash
+fushiguro-mcp skills                          # what is available
+fushiguro-mcp skills show emil-kowalski       # what is in one
+fushiguro-mcp skills add emil-kowalski        # install all of them
+fushiguro-mcp skills add jakub-krehel better-typography better-layout
+```
+
+| Source | Author | Covers |
+|---|---|---|
+| `emil-kowalski` | Emil Kowalski | Animation, motion craft, Apple-flavoured design engineering |
+| `jakub-krehel` | Jakub Krehel | Typography, colour, layout, accessibility, interface review |
+| `meng-to` | Meng To | Design+Code skills for UI, web, media, games |
+| `garden` | ConardLi | Web design engineering, knowledge retrieval, image generation |
+| `landing-page-design` | Elaya Design | Landing page design |
+| `tastemaker` | codeswithroh | Grounding UI in reference images and a persistent taste profile |
+| `designer-skills` | Owl-Listener | Research, systems, UI, interaction, delivery |
+
+All MIT licensed. **Nothing is vendored into this package** — installing fetches from the author's repository, so they keep authorship and you get the current version rather than a fork frozen at whenever this was published. Each installed skill carries a `_SOURCE.md` recording its origin, licence, and fetch date.
+
+Between them these sources offer **around 270 skills**. Install selectively: skills are chosen per task, but a catalog of hundreds makes that choice noisier and gives you more to review. Start with the handful matching work you actually do.
+
+Set `GITHUB_TOKEN` if you install several collections in one sitting — unauthenticated GitHub allows 60 requests an hour.
+
+### How they fit
+
+A folder containing `SKILL.md` is one skill; the files beside it are resources it references, not separate entries. Skills in that format declare only `name` and `description`, so keywords are derived from those — without that they would sit below the selection floor and never attach to anything.
+
+Installed skills land in your custom catalog, so they merge and layer like anything else you write.
+
+## Conversation threads
+
+A long conversation about one subject costs its full length on **every** subsequent turn. Switch topic and you keep paying for context nobody is using.
+
+**What this server cannot do:** clear your context. No MCP server can — none of them has access to your conversation window. Only you can run `/clear`.
+
+**What it does instead** is make clearing safe, by remembering the subject for you:
+
+```
+User has been working on a booking site, then switches subject.
+
+brief → NEW TOPIC — this does not look like a continuation of
+        "Dental clinic booking site" (similarity 0).
+        To save tokens: summarise what was covered and call `save_thread`,
+        then tell the user they can run /clear.
+
+... much later, the subject comes back ...
+
+brief → RESUMES thread #1 "Dental clinic booking site" (score 1) —
+        you discussed this before. Context recovered:
+          Building a booking site for a dental clinic. Next.js + Postgres,
+          Google Calendar sync for slots.
+          Decided:
+            - Next.js + Postgres
+            - Google Calendar for availability
+          Still open:
+            - Which payment provider?
+```
+
+The decisions are the part that matters. A cleared conversation loses the *reasoning*, and re-deriving "why Postgres" costs far more than storing the sentence.
+
+`brief` reports one of three relations on every call: **continues** the current subject, **new** subject, or **resumes** an older one. Topic matching uses the same keyword-and-semantic machinery as knowledge retrieval, so "the clinic appointment app" finds a thread titled "Dental clinic booking site".
+
+Tools: `save_thread`, `recall_thread`, `resume_thread`, `forget_thread`.
+
+**The thresholds lean toward staying put.** Wrongly declaring a new topic suggests clearing context that was still useful; wrongly missing one just means the conversation runs a bit long. The first mistake is much more expensive, so `FUSHIGURO_SAME_TOPIC` defaults low (0.25).
+
+Summaries are written by the host, not this server — it cannot see your conversation, so it cannot summarise it for you.
+
+## Retrieval: keyword and semantic
+
+By default `search_knowledge` uses **BM25** — keyword matching. That fails on a question phrased differently to the document that answers it:
+
+> **Asked:** "how long do I have to get my money back on the yearly plan"
+> **Document:** "Annual: pro-rated refund within 30 days of the initial charge."
+
+Not one meaningful word in common. Enabling embeddings turns retrieval **hybrid**: both retrievers run, and results are fused by rank.
+
+### Enabling it
+
+```bash
+npm install @huggingface/transformers    # local model, no key, no bill
+```
+
+That is the whole setup — the server detects it and starts embedding. Or use a hosted embedder instead, which needs no install:
+
+```bash
+export VOYAGE_API_KEY=...     # or OPENAI_API_KEY
+```
+
+`FUSHIGURO_EMBEDDINGS` takes `auto` (default — hosted key if set, else local if installed, else off), `local`, `voyage`, `openai`, or `off`.
+
+**The model runtime is deliberately not a dependency.** It is ~390MB, and a business that only needs keyword search should not pay for it. Without it, the package stays under 100KB and retrieval works exactly as it did before.
+
+### What it does and does not fix
+
+Measured against the sample corpus with `all-MiniLM-L6-v2`:
+
+| | Keyword only | Hybrid |
+|---|---|---|
+| "money back on the yearly plan" | ranks an unrelated doc first | refund policy first |
+| `ERR_4021`, "Pro annual plan" | correct | still correct |
+
+Both halves matter. A small embedding model is **noise on exact tokens** — error codes and plan names score ~0.07 against everything — and it **blurs discriminating detail**, ranking the Starter passage above the Annual one for an annual-plan question. BM25 is precise about exactly those. Neither retriever is good enough alone, which is why this fuses rather than replaces.
+
+Fusion is Reciprocal Rank Fusion on **rank**, not score. BM25 scores and cosine similarities are incomparable scales, and normalising between them means a fudge factor that needs retuning whenever the corpus changes.
+
+### Operationally
+
+Embedding runs **in the background**. The first run downloads a model (~90MB, roughly 80 seconds), and during that time searches are keyword-only — a worse answer, never a hung tool call. `status` reports which mode is live, and every result says which retriever found it (`keyword`, `semantic`, or `keyword+semantic`).
+
+Vectors are cached in the same SQLite file and reused across restarts. Changing model or corpus re-embeds rather than mixing incompatible vector spaces. Search is brute-force cosine over normalised vectors — 3ms on a small corpus, and fine into the low tens of thousands of chunks.
+
 ## How routing works
 
 Each agent is scored on: keyword matches weighted by how distinctive the keyword is across the catalog (IDF), hand-written regex patterns, similarity to its example triggers, whether a matched topic vouches for it, and how past outcomes for those terms have gone.
@@ -259,6 +375,8 @@ When the top two agents score within 85% of each other, the briefing says so ins
 | `search_knowledge` | Direct retrieval from your documentation, for a factual lookup. |
 | `remember` / `recall` / `forget` | Manage learned preferences. |
 | `record_outcome` | Report how a briefed task went, so routing improves. |
+| `save_thread` | Store a summary of the current topic so context can be cleared safely. |
+| `recall_thread` / `resume_thread` / `forget_thread` | Find, pick back up, or delete a past conversation. |
 | `status` | What is loaded, what is indexed, and which runbooks are still templates. |
 
 Also exposes the `delegate` prompt and a `fushiguro://catalog` resource.
@@ -268,6 +386,9 @@ Also exposes the `delegate` prompt and a `fushiguro://catalog` resource.
 ```
 fushiguro-mcp              Start the MCP server on stdio (what a host runs)
 fushiguro-mcp init [dir]   Scaffold a business catalog, safe to re-run
+fushiguro-mcp skills       List curated skill collections
+fushiguro-mcp skills show <source>
+fushiguro-mcp skills add <source> [skill...] [--force]
 fushiguro-mcp --help
 ```
 
@@ -281,12 +402,19 @@ fushiguro-mcp --help
 | `FUSHIGURO_PROJECT_ROOT` | `cwd` | Keys `project`-scoped memories. |
 | `FUSHIGURO_MIN_SCORE` | `0.12` | Below this, no confident match. |
 | `FUSHIGURO_AMBIGUITY_RATIO` | `0.85` | Top two within this ratio are reported ambiguous. |
+| `FUSHIGURO_EMBEDDINGS` | `auto` | `auto`, `local`, `voyage`, `openai`, or `off`. |
+| `FUSHIGURO_EMBEDDING_MODEL` | per provider | Override the model. |
+| `FUSHIGURO_EMBEDDING_BATCH` | `32` | Texts per embedding call. |
+| `FUSHIGURO_SAME_TOPIC` | `0.25` | Above this similarity, a task continues the active thread. |
+| `FUSHIGURO_RESUME_TOPIC` | `0.45` | Above this, an older thread is offered as a resumption. |
 
 Catalog files are re-read when they change on disk, and the knowledge index rebuilds when the corpus hash changes — edit an agent or a policy document and the next `brief` picks it up without a restart.
 
 ## Limitations, stated plainly
 
-- **Retrieval is lexical, not semantic.** BM25 with stemming, no embeddings. It is fast, has no external dependency, and finds documents that share vocabulary with the question — it will miss a passage that answers the question in entirely different words.
+- **Retrieval is keyword-only until you enable embeddings**, and a keyword search misses passages phrased differently to the question. With them enabled it is hybrid, but a small local model still blurs the details that distinguish two similar passages — see the table above. A hosted embedder is meaningfully better on domain jargon.
+- **Topic detection is a similarity score, not comprehension.** A task that changes subject while reusing the old vocabulary reads as a continuation; a genuine continuation phrased in fresh words can read as new. Both thresholds are tunable, and the similarity is always reported so the call can be second-guessed.
+- **Vector search is brute force.** Every query scores every chunk. That is milliseconds up to the low tens of thousands of chunks and will not scale past that without a real vector index.
 - **Complexity assessment is lexical.** It reads the shape of the request, not its meaning. An innocuous-sounding sentence hiding a quarter of work will be under-scored, and a verbose request for something small will be over-scored. The signals are always shown and `mode` always overrides.
 - **Routing is lexical too**, plus learned outcome weights. It has no understanding of the task; it matches configured signal. A catalog with thin keywords routes badly, and the fix is better keywords and more `record_outcome` calls.
 - **Deduplication of memories is lexical.** Two preferences that overlap heavily in wording but differ in object may merge. Requiring three shared distinct tokens keeps this rare, not impossible.
@@ -304,7 +432,11 @@ src/
   catalog.ts     loads and layers the seven entity kinds
   router.ts      scoring, selection, and prompt composition
   memory.ts      preferences, reinforcement, outcome learning
-  knowledge.ts   chunk index and retrieval
+  knowledge.ts   chunk index, hybrid retrieval, rank fusion
+  embeddings.ts  pluggable embedding providers (local, voyage, openai)
+  threads.ts     conversation topics, continuity detection, resumption
+  skill-sources.ts / skill-install.ts / skills-cli.ts
+                 curated ecosystem skill collections and their installer
   text.ts        tokenising and similarity helpers
 catalog/         the packaged base catalog
 examples/        a worked custom catalog, and an .mcp.json template

package/catalog/agents/content-editor.md

@@ -36,7 +36,7 @@ triggers:
 patterns:
   - "\\b(tone\\s+of\\s+voice|brand\\s+voice|style\\s+guide)\\b"
   - "\\b(press\\s+release|release\\s+notes|newsletter)\\b"
-skills: [stakeholder-summary]
+skills: [stakeholder-summary, landing-page]
 tools: [Read, Write, Edit, Grep]
 ---
 

package/catalog/agents/ux-ui-specialist.md

@@ -42,6 +42,13 @@ keywords:
   - booking
   - checkout
   - onboarding flow
+  - screen
+  - page
+  - polish
+  - looks off
+  - feels off
+  - looks cheap
+  - visual
 triggers:
   - "design a settings screen"
   - "make this look better"
@@ -54,6 +61,8 @@ patterns:
   - "\\b(liquid\\s*glass|glassmorph\\w*|frosted)\\b"
   - "\\b(figma|design\\s*system|design\\s*tokens?)\\b"
   - "\\b(hig|human\\s+interface\\s+guidelines)\\b"
+skills:
+  - design-taste
 tools:
   - Read
   - Write

package/catalog/skills/design-taste.md

@@ -0,0 +1,57 @@
+---
+name: design-taste
+title: Design Taste
+description: The judgement that separates competent from good — restraint, hierarchy, defaults worth overriding, and how to tell a real critique from a preference.
+keywords:
+  - taste
+  - aesthetic
+  - polish
+  - refine
+  - critique
+  - feedback
+  - looks off
+  - feels cheap
+  - visual quality
+  - craft
+  - detail
+  - restraint
+  - hierarchy
+applies_to: []
+always: false
+---
+
+Taste is not decoration. It is the accumulated judgement about what to leave out, and it is mostly learnable by knowing what to look at.
+
+## When something "looks off" and nobody can say why
+
+Check these, in this order. The answer is nearly always in the first three.
+
+1. **Spacing is inconsistent.** Nothing makes work look amateur faster than 13px here and 16px there. Everything sits on one scale — 4 or 8px — with no exceptions you cannot justify in a sentence.
+2. **Too many type sizes and weights.** Most interfaces need four sizes and two weights. If a screen has nine, the hierarchy has stopped meaning anything, because everything is emphasised.
+3. **Contrast is doing no work.** If the primary action, a secondary action, and body text all sit at similar visual weight, the eye has nowhere to go. Something must be clearly loudest.
+4. **Too many competing accents.** One accent colour, used for the thing you want clicked. A second accent is a decision to have no accent.
+5. **Corner radii disagree.** A 4px card containing an 8px button reads as broken even to people who cannot name why. Nested radii should share a centre: inner radius = outer radius minus the padding between them.
+6. **Borders where shadows belong, or both.** Pick one system for separating surfaces and use it throughout.
+7. **Text touching its container.** Padding is almost always too tight before it is too loose, and the gap under a heading should be smaller than the gap above it — the heading belongs to what follows.
+
+## Restraint
+
+The instinct that most reliably improves a design is deletion. Remove the divider and see whether spacing alone separates the groups. Remove the icon and see whether the label was already clear. Remove the card and see whether the content needed a container at all.
+
+Every border, shadow, gradient, and icon must earn its place by doing a job that whitespace and typography could not do. Most of them cannot.
+
+**Defaults are usually right.** The platform's system font, its native controls, its standard easing. Override them when you have a specific reason you can articulate — not to look distinctive. Distinctiveness that comes from overriding defaults reads as noise; distinctiveness that comes from a genuinely different structure reads as design.
+
+## Density
+
+Match the density to the user, not to your screenshot. A tool someone lives in all day should be denser than its marketing site suggests — generous spacing looks better in a portfolio and wastes the screen of someone reconciling three hundred rows. Ask how often a person uses this, and how much they need on screen at once.
+
+## Critique that is worth receiving
+
+**Describe the effect before prescribing the fix.** "The primary action is competing with the filter row, so my eye lands on the filters first" is useful. "Make the button blue" skips the reasoning and is just your preference wearing a suit.
+
+**Separate the three kinds of comment** and label them: this is broken, this is inconsistent with the system, this is my preference. Conflating the third with the first is how design review becomes an argument about nothing.
+
+**Say what is working.** Not to soften anything — because the author needs to know which parts to leave alone in the next revision.
+
+When you cannot articulate why something is wrong, say that too, and describe what you notice instead. "Something about the header feels heavy — possibly the logo size against the nav" is honest and actionable. Inventing a confident rationale for an instinct is how bad rules get propagated.

package/catalog/skills/ios-native-craft.md

@@ -0,0 +1,64 @@
+---
+name: ios-native-craft
+title: iOS Native Craft
+description: Making an iOS app feel native rather than ported — system materials, navigation idioms, gestures, haptics, and the details that give away a web app in a shell.
+keywords:
+  - ios
+  - iphone
+  - ipad
+  - swiftui
+  - uikit
+  - native
+  - apple
+  - hig
+  - human interface
+  - sheet
+  - navigation stack
+  - tab bar
+  - haptic
+  - dynamic type
+  - safe area
+  - san francisco
+  - sf symbols
+  - liquid glass
+applies_to: [ux-ui-specialist]
+always: false
+---
+
+An app feels native when it behaves the way every other app on the device behaves. Most of that is not visual — it is gesture, timing, and the system doing work you did not reimplement.
+
+## Use the system's own components
+
+The single largest source of "this feels wrong" is a reimplemented system control. Native sheets, navigation stacks, tab bars, context menus, and pickers carry behaviour that is genuinely hard to rebuild: interruptible dismiss gestures that track your finger, rubber-banding at scroll boundaries, correct focus and VoiceOver order, keyboard avoidance, Dynamic Type response, and automatic adaptation to Reduce Transparency and Reduce Motion.
+
+Reach for a custom control only when the system has no equivalent — not to make it look different. A restyled system component keeps the behaviour; a rebuilt one loses it.
+
+## The details that give a port away
+
+- **Scroll physics.** iOS deceleration and rubber-banding are specific. Anything else reads as foreign immediately, before a user could tell you why.
+- **Interruptible gestures.** A sheet must follow the finger and settle from wherever it is when released, with velocity. A sheet that plays a fixed dismiss animation is the clearest tell there is.
+- **Safe areas.** Content scrolls *under* the status bar and home indicator; it does not stop short of them. Interactive elements stay clear of both.
+- **Dynamic Type.** Text scales with the user's setting, and the layout absorbs it. Test at the largest accessibility size — that is where fixed-height rows and truncated labels break.
+- **Haptics on state change, not on every tap.** A selection change, a success, an error. Haptics on ordinary buttons become noise, and users turn them off system-wide.
+- **Back gesture from the left edge.** Never intercept it. If it does not work, the app is broken to a large share of users.
+- **SF Symbols** over custom icons wherever one exists. They align optically with San Francisco, respond to weight and scale, and stay correct across OS versions.
+
+## Navigation
+
+Match structure to the app. A tab bar is for a handful of peer destinations that people move between constantly — not a place to hide a settings screen. A navigation stack is for drilling into a hierarchy. A sheet is for a self-contained task the user will finish or abandon, and it should be dismissible by gesture.
+
+Modal presentation is a commitment: it says "finish this or cancel it". Using a sheet for something the user needs to reference other screens for is a design error that surfaces as people repeatedly dismissing and reopening it.
+
+## Liquid Glass
+
+The current material system floats chrome above content on a translucent, refractive surface. Use the platform's own material rather than reimplementing blur — the real one responds to scroll position and wallpaper, and degrades correctly under Reduce Transparency.
+
+Content stays opaque; only navigation, toolbars, tab bars, sheets, and controls take the material. Layer it at most once — two stacked translucent surfaces destroy legibility. Nested corner radii share a centre so the curves stay parallel.
+
+## Before calling it done
+
+Run it at the largest Dynamic Type size, with Reduce Motion on, with Reduce Transparency on, and under VoiceOver. Each of those is a real user setting, and each one is where an app that looked finished turns out not to be.
+
+---
+
+*Influences worth reading directly: Apple's Human Interface Guidelines, and Meng To's Design+Code material on iOS and SwiftUI design.*

package/catalog/skills/landing-page.md

@@ -0,0 +1,75 @@
+---
+name: landing-page
+title: Landing Page Craft
+description: Landing pages that earn the next click — message hierarchy, proof, the fold, calls to action, and the sections that can usually be deleted.
+keywords:
+  - landing page
+  - hero
+  - above the fold
+  - headline
+  - subheadline
+  - cta
+  - call to action
+  - conversion
+  - social proof
+  - testimonial
+  - pricing page
+  - waitlist
+  - signup
+  - marketing site
+  - homepage
+  - value proposition
+applies_to: []
+always: false
+---
+
+A landing page has one job: get a specific visitor to take one specific next step. Every section either moves them toward it or is costing you.
+
+## Before writing a word
+
+Answer three questions, out loud, and put the answers at the top of your work:
+
+1. **Who is arriving, and from where?** Someone from a targeted ad already knows the category. Someone from a general search does not. The same page cannot serve both well — pick.
+2. **What is the one action?** Sign up, book a demo, install, buy. One. A page with three equally-weighted calls to action converts on none of them.
+3. **What do they need to believe to take it?** That list is your section outline. Nothing else belongs on the page.
+
+## The fold
+
+Assume you get one glance. In it, the visitor must learn **what this is**, **who it is for**, and **what to do next**.
+
+- **The headline says what the product does, not how the company feels about it.** "Schedule patients without the phone calls" beats "Reimagining dental practice management." If the headline would work equally well on a competitor's site, it says nothing.
+- **The subheadline handles the objection the headline raises**, or names the audience precisely. It is the only place you get to add a clause.
+- **One primary call to action**, visually dominant. A secondary action may exist, but it must look secondary — a link, not a second button of equal weight.
+- **Show the product.** A real screenshot, a short loop of actual use. Not an abstract illustration, not a stock photo, and not a laptop mockup at a 30-degree angle that renders the interface unreadable.
+
+## Proof, in order of strength
+
+1. Specific numbers from named customers
+2. Named testimonials with a role and a company
+3. Logos of recognisable users — only if genuinely users
+4. Aggregate stats ("10,000 teams")
+5. Unattributed quotes — nearly worthless; the reader assumes you wrote them
+
+Put proof directly after the first claim it supports, not in a lonely "Testimonials" section at the bottom that nobody scrolls to.
+
+**Never fabricate proof.** No invented testimonials, no logos of companies that are not customers, no statistics you cannot source. Beyond being dishonest, it is the single fastest way to lose a visitor who checks.
+
+## Sections that usually earn their place
+
+The fold. How it works, in three steps. The main objection, answered. Proof. Pricing, if it exists — hiding it costs more trust than the number does. A final call to action.
+
+## Sections that usually do not
+
+A mission statement. A team photo, on a page for a product nobody has bought yet. A feature grid of twelve icons with three-word labels. A blog feed. An FAQ answering questions nobody asked, used to pad the page. "As seen in" logos for a single unremarkable mention.
+
+Delete a section, read the page, and see whether anything is missing. Usually nothing is.
+
+## Writing
+
+Second person. Present tense. Short sentences. Specific verbs.
+
+Cut every instance of *seamless*, *robust*, *powerful*, *revolutionise*, *leverage*, *solutions*, and *empower*. They appear on every competitor's page, which means they cannot distinguish yours. If a sentence survives having its adjectives removed, it was carrying real information.
+
+## Before it ships
+
+Check it on a phone first, not last — most visitors arrive on one. Check the page still makes sense with images blocked. Check that the primary action is reachable without scrolling on a small screen. Check the contrast on any text over an image, which is where it always fails.

package/catalog/skills/motion-and-animation.md

@@ -0,0 +1,70 @@
+---
+name: motion-and-animation
+title: Motion and Animation
+description: Interface animation that explains rather than decorates — easing, duration, spring physics, orchestration, interruptibility, and knowing when not to animate.
+keywords:
+  - animation
+  - animate
+  - motion
+  - transition
+  - easing
+  - spring
+  - keyframe
+  - framer motion
+  - gsap
+  - interpolate
+  - gesture
+  - drag
+  - scroll animation
+  - micro-interaction
+  - loading state
+  - skeleton
+  - reduced motion
+applies_to: [ux-ui-specialist]
+always: false
+---
+
+Animation has one job: explain a change the user would otherwise have to reconstruct. Where did this come from, where did it go, what is related to what. Anything that does not do that job is decoration, and decoration in an interface people use daily becomes an irritation by the fiftieth viewing.
+
+## The defaults you start from
+
+- **Duration scales with distance and size.** A 40px toggle settles in ~150ms. A full-screen sheet takes ~350ms. Using one duration for everything makes small things feel sluggish and large things feel abrupt.
+- **Ease-out for things entering, ease-in for things leaving.** Entering elements decelerate into place, so they arrive under control. Leaving elements accelerate away, because nobody needs to watch an exit finish. Ease-in-out is for things moving between two on-screen positions.
+- **Never animate with linear easing** except for continuous, non-physical motion — a spinner, a progress bar, a marquee. Linear reads as mechanical because nothing in the physical world moves that way.
+- **Animate transforms and opacity.** `transform` and `opacity` are composited; `width`, `height`, `top`, and `left` trigger layout on every frame. If you must animate size, prefer `scale` and correct the distortion, or accept the cost knowingly.
+
+## Springs
+
+Springs beat duration-based curves for anything a user can interrupt — dragging, dismissing, toggling — because they carry velocity. A sheet flicked hard should settle faster than one nudged gently, and only a spring can express that.
+
+Tune with damping and stiffness, not by converting to a duration. A useful starting point: stiffness ~200, damping ~25 for UI-scale movement. Increase damping until the overshoot stops being charming and starts looking like a bug — for most product UI, that is one small overshoot at most, and often none.
+
+Reach for a duration curve when the motion is not interruptible and must be exactly repeatable: a page transition, a scripted sequence.
+
+## Orchestration
+
+When several things animate together, stagger them by 20–50ms rather than firing them at once. Simultaneous motion reads as one indivisible block; staggered motion reads as a list, which is usually the truth you want to convey.
+
+Order matters. Animate in the direction attention should travel — top to bottom for a list, outward from the element the user clicked. Reverse the order on exit.
+
+Never stagger more than about seven items. Past that, animate the container and let the contents appear with it, or the last item arrives long after the user has started reading the first.
+
+## Interruptibility
+
+**An animation the user cannot interrupt is a bug.** If someone opens a menu and immediately closes it, the close must start from wherever the open animation had reached, not from its finished state and not after it completes. Anything else feels like the interface arguing with them.
+
+This is the single most common thing separating animation that feels good from animation that feels expensive-but-annoying. Test it deliberately: trigger every animation and immediately trigger its opposite.
+
+## When not to animate
+
+- **Anything on the critical path of a frequent action.** A 300ms transition on a button someone presses forty times a day is two minutes a year taken from them.
+- **Content that has arrived.** Text and data should appear, not fade in. A fade on real content delays reading for no informational gain.
+- **State the user caused directly and expects instantly.** Checkbox ticks, focus rings, character input.
+
+## Accessibility, non-negotiable
+
+Honour `prefers-reduced-motion`. It is not a request to disable feedback — it is a request to remove *movement*. Replace a slide with a cross-fade, remove parallax and auto-playing motion entirely, and keep the state change visible. An interface that becomes unintelligible under reduced motion was relying on animation to carry meaning that should have been in the layout.
+
+---
+
+*Influences worth reading directly: Emil Kowalski's public writing and courses on web animation, and the motion sections of the Material and Apple Human Interface Guidelines.*

package/catalog/topics/marketing-content.md

@@ -8,7 +8,7 @@ triggers:
   - "we need an announcement for"
   - "make this page convert better"
 agents: [content-editor, research-analyst]
-skills: [stakeholder-summary]
+skills: [stakeholder-summary, landing-page, design-taste]
 knowledge: [brand, product]
 ---
 

package/catalog/topics/product-engineering.md

@@ -8,7 +8,7 @@ triggers:
   - "fix this bug"
   - "review this before we ship"
 agents: [ux-ui-specialist, backend-api, database, testing, security, docs]
-skills: [clarify-scope]
+skills: [clarify-scope, design-taste]
 runbooks: [change-release]
 knowledge: [engineering, product]
 ---

package/dist/catalog.js

@@ -14,6 +14,41 @@ function strings(value) {
     }
     return [];
 }
+/** "better-typography" -> "Better Typography", for entries with no title. */
+function titleFromName(name) {
+    return name
+        .split("-")
+        .map((word) => (word.length > 0 ? word[0].toUpperCase() + word.slice(1) : word))
+        .join(" ");
+}
+const KEYWORD_STOPWORDS = new Set([
+    "use", "uses", "using", "when", "the", "and", "for", "with", "that", "this",
+    "your", "you", "from", "into", "not", "are", "any", "all", "its", "it", "or",
+    "a", "an", "to", "of", "in", "on", "is", "be", "as", "by", "at", "other",
+    "than", "them", "they", "each", "user", "asks", "wants", "make", "makes",
+    "made", "does", "do", "can", "will", "should", "instead", "rather", "across",
+    "helps", "help", "focuses", "focus", "covers", "provides", "includes",
+    "ensures", "turns", "like", "such", "these", "those", "more", "most", "very",
+    "want", "need", "needs", "get", "gets", "put", "one", "two", "way", "ways",
+]);
+/** Distinctive words from a name and description, for entries with no keywords. */
+function deriveKeywords(name, description) {
+    const words = `${name.replace(/-/g, " ")} ${description}`
+        .toLowerCase()
+        .match(/[a-z][a-z0-9+#.-]{2,}/g) ?? [];
+    const seen = new Set();
+    const out = [];
+    for (const raw of words) {
+        const word = raw.replace(/[.-]+$/, "");
+        if (word.length < 3 || KEYWORD_STOPWORDS.has(word) || seen.has(word))
+            continue;
+        seen.add(word);
+        out.push(word);
+        if (out.length >= 20)
+            break;
+    }
+    return out;
+}
 function slugify(input) {
     return input
         .toLowerCase()
@@ -148,13 +183,18 @@ function buildEntity(kind, raw) {
             throw new Error(`${file}: invalid regex '${src}' (${err.message})`);
         }
     }
+    const description = String(meta.description ?? "");
+    const declared = strings(meta.keywords).map((k) => k.toLowerCase());
     const base = {
         kind,
         layer,
         name,
-        title: String(meta.title ?? name),
-        description: String(meta.description ?? ""),
-        keywords: strings(meta.keywords).map((k) => k.toLowerCase()),
+        title: String(meta.title ?? titleFromName(name)),
+        description,
+        // Skills imported from the wider ecosystem declare only name and
+        // description. Deriving keywords from those is what makes them reachable —
+        // without it they sit below the selection floor and never attach.
+        keywords: declared.length > 0 ? declared : deriveKeywords(name, description),
         triggers: strings(meta.triggers),
         patterns,
         topics: strings(meta.topics),
@@ -247,7 +287,14 @@ function buildEntity(kind, raw) {
             };
     }
 }
-/** Every markdown file under `dir`, recursively, with its path relative to `dir`. */
+/**
+ * Every markdown file under `dir`, recursively, with its path relative to `dir`.
+ *
+ * A directory containing `SKILL.md` is treated as a single packaged skill: only
+ * that file is an entity, and its siblings (cheat sheets, templates, audit
+ * checklists) are resources it references. This is the layout the Agent Skills
+ * ecosystem uses, so skills can be installed from upstream repositories intact.
+ */
 function walk(dir) {
     let entries;
     try {
@@ -256,6 +303,9 @@ function walk(dir) {
     catch {
         return [];
     }
+    const packaged = entries.find((e) => e.isFile() && e.name === "SKILL.md");
+    if (packaged)
+        return [{ path: join(dir, packaged.name), rel: packaged.name }];
     const out = [];
     for (const entry of entries) {
         const full = join(dir, entry.name);