huseyingayiran/inspiration-skills

---

name: inspiration-references description: Finds, shows, compares and critiques real design references from the Inspiration library by VASA.Works (via its MCP server): website sections, UI screens, decks, branding, OG images, editorial, illustration, motion, fonts and palettes. Also manages the user's Inspiration boards and imported X bookmarks. Use when the user wants inspiration, examples of a pattern, references for a page, a moodboard, or more like a reference. metadata: version: "1.1.0"

Inspiration References

Turn a brief into a short, honest set of real references: search the library, look at the actual images, say what each one does that fits, and help the user narrow down. A good answer is 4 to 6 references the user can act on, not a dump of 12 links.

When to use

• Requests like "find inspiration for", "show me good pricing pages", "what do great onboarding flows look like", "references for a fintech hero", "build a moodboard", "more like this one", "compare these two", "save these to a board", "what's on my boards", "search my X bookmarks".
• Also when the user never says "Inspiration" but wants real examples of a design pattern.
• Not for designing and building a page (use inspiration-art-direction), a palette or font kit (use inspiration-brand-kit), or code changes with no reference question.

Tools are named here by bare name (search_inspiration). In your client they carry a server prefix such as mcp__plugin_inspiration_inspiration__ (Claude Code plugin install), mcp__inspiration__, or a connector name.

1. Check setup

Look for a tool named search_inspiration under any prefix. If the host lists tools as deferred, loading it through the host's tool search counts as available. If it is missing, read references/setup.md, give the user the one step for their client, and stop. If they want to continue anyway, say plainly that you cannot show library references and offer general guidance from your own knowledge. Never invent ids, titles, image URLs, or descriptions.

2. Translate the brief

Pull out four things: what (category and subtype), look (style, color, theme, typography), feel (mood), context (industry). Put the specific, visual words in query and only the clear-cut constraints in filters.

search_inspiration(
  query="dark SaaS pricing with a highlighted middle tier",
  category="website-sections",
  filters={"subtype": ["pricing", "pricing-table"], "theme": ["dark"]},
  limit=6)

• filters are AND across keys and any-of within a key. One to three keys is usually right; more keys mostly produce zero results.
• subtype means section type for website-sections (hero, pricing, cta, footer...), slide role for slide-decks (cover, traction, the-ask...), and asset type elsewhere (logo, poster, dashboard...). Values and recipes per category: references/search-recipes.md.
• When the brief is vague or you are unsure of a value, call list_facets(category=..., top=25). It is unmetered. If it errors, keep using the values in references/search-recipes.md in filters; drop a filter only if that search returns zero results.
• If the user names a brand whose look they want, pass brand="<website-styles slug>" to re-rank toward it, or a profile dict (palette, style, mood, typography, industry, tags, theme).
• Zero results return suggestions. Retry once with a suggestion or with one filter removed; tell the user what you relaxed.

Use limit=6 so the whole set fits one image call. limit=1 is for "just give me one" and adds alternates.

3. Look before you talk

Search returns URLs and metadata, not pixels. Call get_image once with the list of ids (up to 6) and look at every image before writing anything about it.

For each reference give:

• Id and title (the id is what boards and follow-ups use).
• What it actually does that fits the brief, in one or two lines, from the image: layout, hierarchy, type treatment, color proportion, a notable detail.
• Fit label when it is not a full match: "partial: dark and editorial, but no highlighted tier". Honest labels beat padding the list.

Then add two or three lines of synthesis: the patterns the strong ones share, and the one you would start from and why. Keep titles, tags, and filter matches out of your descriptions unless the image confirms them. A result that passed theme: dark can still be a light page; label it partial. Describe only what is visible: motion, hover states, and scroll effects are not visible in a still.

4. More, narrower, or similar

• More of the same search: repeat it with exclude_ids=[ids already shown] (best) or offset=6. Check has_more first.
• More like this one: similar_items(id, limit=6), or get_inspiration(id, similar=6) when you also want the seed's facets in the same call.
• Like this, but changed ("lighter", "more playful", "for fintech"): read the seed's facets (get_inspiration(id)) and look at the seed image, then search with its subtype and the changed constraint as a filter or query words, excluding the seed. If get_inspiration errors, find the seed's row with a plain search_inspiration(query="<words from the slug>", category="<seed category>", limit=3) (no verbose, no brand), open its image_url, and take the look from the pixels. Note what changed compared with the seed.
• Details on a few: get_inspiration([ids], detail="standard") in one call. detail="full" is large; use it only when a field you need is missing.

5. Compare references

When the user asks which is better or how they differ, put the candidates side by side from the images you already fetched (fetch any missing ones in one batch):

	Ref A	Ref B
Hierarchy
Type
Color and contrast
Density and spacing
What to take

End with a recommendation tied to the user's brief, plus what to leave behind from each. Take principles, not pixels: never suggest copying logos, copy, imagery, or licensed typefaces.

6. Boards

Boards live on the user's Inspiration account at inspiration.vasa.works.

• Write only on an explicit ask or a yes to your offer. Searching, viewing, or liking a result is not permission. After showing results, offer once: "Want me to save these to a board?"
• save_to_board(title, ids=[...]) creates the board, or appends if a board with that title exists. It returns board_url, item_count, added, and already_in_board. Share the URL.
• save_to_board(title, query=..., filters=..., category=..., limit=...) searches and saves in one call; only use it when the user asked to save "whatever you find" without reviewing first.
• list_my_boards() for "my boards". get_board(board) (id or slug) to show one; then get_image on up to 6 of its item ids if the user wants to see them.
• add_to_board(board, item_ids) to add to a specific existing board; create_board(title, item_ids) for an empty or seeded new one.
• Errors: board_limit or item_limit (tell the user, suggest an existing board), rate_limited (wait, retry once), nothing_to_save (pass ids).

7. The user's X bookmarks

If the user mentions their own bookmarks or saved posts, call search_x_bookmarks(query, limit=10). It searches only their imported bookmarks. A "status": "not_connected" result includes connect_url; pass it on. Results carry tweet text, image URLs, and a post link. Describe an image only if you could actually view it; otherwise quote the saved text and say you have not seen the image.

Budget

Free accounts get 50 metered calls per UTC month. A typical request takes 3 to 5:

Step	Calls
list_facets (only if vague)	0, unmetered
search_inspiration	1 (2 with one retry)
get_image, one batch of up to 6	1
one follow-up (more, similar, compare, save)	1 or 2

Batch everything: get_image takes up to 6 ids, get_inspiration takes a list. Never loop one call per item.

Quota and errors

Read references/library-rules.md the first time a tool returns an error, quota_exhausted or capped, or when get_image fails (it has the image fallback through the public image_url, no metered call). The short version: quota_exhausted stops all metered calls (link https://inspiration.vasa.works/pricing, finish with what you have), capped means no further pages, not_found means re-search (never guess an id), subscription_required means sign in, and the same server error on two different tools means degraded mode. Errored calls count toward the budget. Board errors are in section 6.

Rules

• Fidelity. Describe only what you saw in images you actually opened (get_image, or the image_url fallback). Never claim details from titles alone.
• Principles, not pixels. References inform; they are not templates to copy.
• Name the library only. Call it the Inspiration library or Inspiration by VASA.Works. Do not speculate about where items came from. Never link a third-party site as an item's origin. Font foundry or license pages, the user's own bookmark post links, and board URLs are fine.
• No silent board writes.