find-style-references

name

find-style-references

description

Use this skill after a personal website or blog style direction is roughly known and before building an original site. It searches for real websites, templates, portfolios, blogs, screenshots, or design examples that match the chosen direction, inspects them with browser or screenshot tools when available, and turns the findings into a practical design reference brief for make-personal-site. Use it for requests like finding references for a natural technical blog, cozy research homepage, brutalist portfolio, digital garden, minimal notes site, or any named visual direction that still needs concrete examples.

Find Style References

Goal

Turn a chosen or roughly described personal-site style into concrete, verified design references before implementation.

This skill is a research and design-brief skill. It does not build the site and does not clone a single target website. It finds multiple real references, inspects them, extracts reusable design patterns, and produces a build-ready brief for make-personal-site.

Contract

Inputs:

• User style direction, theme words, site type, audience, content scope, references, or constraints.
• Optional examples to include or avoid, preferred platform/template sources, and target site structure.

Outputs:

• 4-8 relevant reference candidates when available, with source URLs and short rationale.
• Browser or screenshot observations for selected references when tooling is available.
• A practical reference brief covering layout, navigation, first screen, article list, article detail, project/about areas, color, typography, imagery, motion, interactions, and responsive behavior.
• Clear "borrow" and "avoid" notes.
• A final build handoff for make-personal-site.

Boundaries:

• Do not implement the website.
• Do not copy protected source code, images, personal identity, analytics IDs, or brand assets.
• Do not treat one reference as a clone target. If the user wants one specific site copied, route to copy-website-style.
• Do not spend time on framework installation or build feasibility; this skill only studies design references.

Success gate:

• The direction is grounded in concrete references and is specific enough for make-personal-site to build an original static site.
• Reference research used multiple search angles, not a single keyword.
• At least 3 strong references were inspected when possible, unless the user explicitly asked for a fast draft.
• The final brief separates reusable design language from content/identity that should not be copied.

If gate fails:

• Search with broader or alternative keywords.
• Inspect a smaller set of stronger references.
• Return to search-blog-theme if the direction itself is still unclear.
• Ask one concise preference question only when multiple reference families would lead to very different sites.

When To Use

Use this skill when:

• The user already gave a broad direction such as natural technical blog, quiet research homepage, retro terminal archive, cozy notes site, or brutalist portfolio.
• search-blog-theme has recommended a direction, but it still needs real examples before building.
• from-idea-to-personal-site is about to build an original site from taste words instead of a concrete reference URL.
• The agent needs more visual grounding before make-personal-site.

Do not use this skill when:

• The user has not chosen any direction yet; use search-blog-theme.
• The user supplied one target URL and wants close recreation; use copy-website-style.
• The site already exists and only needs a small change; use edit-site-part.

Workflow

1. Restate the style direction internally as searchable keywords. Input: user taste and site purpose. Output: 5-10 search phrases across multiple angles. Gate: search phrases cover mood, site type, visual system, structure, and at least one alternative phrasing.

2. Search for real references. Input: search phrases. Output: candidate websites, templates, portfolios, blogs, design pages, or GitHub demos. Gate: use at least 3 distinct search angles before settling on references, unless the user explicitly asked for a fast draft.

3. Inspect selected references. Input: top candidates. Output: browser/screenshot observations. Gate: at least 3 strong references are inspected when possible; use 4-6 when the direction is broad.

4. Extract design patterns. Input: inspected references. Output: reusable patterns and anti-patterns. Gate: notes are about layout, hierarchy, interaction, typography, color, content density, and responsive behavior, not just vibes.

5. Synthesize one build brief. Input: reference patterns plus user constraints. Output: a concise design brief for make-personal-site. Gate: the brief is specific enough to implement without another research pass.

Search Guidance

Build searches from combinations of:

• Site type: personal website, personal blog, portfolio, research homepage, digital garden, notes site, developer blog.
• Mood: natural, calm, editorial, cozy, raw, brutalist, terminal, archive, notebook, garden, minimal, playful, scientific.
• Structure: blog homepage, article index, project grid, side navigation, bento, timeline, notes archive, now page.
• Sources: v0 templates, Figma community, GitHub themes, personal websites, Astro/Hugo/Jekyll/Quartz examples, design inspiration sites.

Prefer specific phrases over vague ones. For example:

• natural developer personal website
• calm technical blog personal site
• digital garden nature inspired design
• research homepage personal website minimal
• personal blog template notes projects

Do not stop after one search phrase or the first attractive result. For a direction like cyberpunk technical homepage, search across multiple angles, such as:

• cyberpunk developer personal website
• futuristic technical blog personal site
• terminal cyberpunk portfolio website
• neon brutalist personal website
• sci fi interface personal homepage

Use current web search for references because templates, portfolios, and design examples change over time.

Browser Inspection

For each strong reference, inspect the live page with an actually available interactive browser tool. "Available" means it is exposed in the current turn's callable tool list. In Codex this may be the Browser/in-app browser plugin when routed into the turn; in other agents it may be an equivalent visible browser, browser-use tool, or devtools-backed browser.

If no interactive browser tool is callable, do not pretend the reference was visually inspected in a browser. Ask the user to enable or invoke the browser tool if visual reference fidelity matters; for Codex, that may mean sending a request that explicitly mentions @browser. If the user does not re-route or the client has no such tool, fall back to Playwright, screenshots, search-result snippets, source pages, or written descriptions and state the limitation.

Do not default to Playwright, screenshots-only review, or search-result snippets when an interactive browser tool is actually callable. Screenshots can be captured as evidence after the interactive browser pass, but they are not a substitute for interactive inspection. Use Playwright only as a fallback when no interactive browser tool is callable, when the user explicitly asks for it, or when repeatable scripted comparison is specifically needed.

Check:

• First viewport: what is immediately useful?
• Navigation: top nav, side nav, command/menu, tags, search, archive links.
• Content model: posts, notes, projects, about, links, records, now, garden, resume.
• Reading experience: article width, typography, code blocks, math, images, footnotes, table of contents.
• Visual system: palette, spacing, border radius, density, cards, dividers, texture, imagery.
• Motion and interaction: hover states, theme toggle, filters, search, scrolling effects, page transitions.
• Responsive behavior: what should happen on mobile?
• Risk: what would become too hard to read, too generic, too heavy, or too close to the source?

If browser tooling is unavailable, use source pages, search result snippets, screenshots, and written notes, and state that visual inspection was limited.

Output Shape

Keep the response natural and useful. Do not expose a long hidden process log.

Include:

• Short recommendation: the strongest direction to build.
• References: 4-8 items with URL/source and why each matters.
• Borrow: concrete patterns to adapt.
• Avoid: things not to copy or things that would hurt the user's site.
• Build brief: the exact direction for make-personal-site.
• Handoff: recommended next skill and any source constraints.

When the user asks for a quick answer, compress the output to the best 3-5 references and one brief.

Build Brief Requirements

The final brief should specify:

• Site identity: what the site should feel like in one phrase.
• Page scope: home, blog index, post detail, projects, about, notes/records, links, or other pages.
• First screen: what useful content appears immediately.
• Layout: navigation, content columns, sidebars, cards/lists, archive structure.
• Visual system: color palette, type style, spacing, borders, imagery, icon style.
• Interactions: theme toggle, filter/search, copy buttons, hover states, optional motion.
• Responsive behavior: mobile navigation and content priority.
• Do not copy: original personal identity, articles, assets, logos, proprietary code, analytics, or exact brand treatment.

Handoff

After the brief is ready:

• Route original site builds to make-personal-site.
• Route single-site close recreations to copy-website-style.
• Route unresolved direction choices back to search-blog-theme.