mirror of
https://github.com/NousResearch/hermes-agent.git
synced 2026-11-17 04:11:35 +00:00
SKILL.md is restructured to authoring standard 5 (When to Use, Prerequisites, How to Run, Quick Reference, Procedure, Pitfalls, Verification) — headings only, upstream body text kept. The asset references still carried the upstream per-CLI routing tables and command lines for other agent products; those are replaced with the native `image_generate` route (product names are allowed only in LICENSE and credit lines). `WebSearch` residue in recon docs/refscout becomes `web_search`. source.mjs wrote its ~2.6MB Google Fonts metadata cache to $TEMP||$TMPDIR||'.', which is the project cwd on most Linux shells; it now uses os.tmpdir() and Pitfalls documents the location. Network-access note now mentions that moodboard.mjs also downloads the image URLs the search hosts return. Docs page regenerated for this skill only.
210 lines
12 KiB
Markdown
210 lines
12 KiB
Markdown
# recon.md — scouting live references and building a moodboard
|
||
|
||
Taste is not invented at the desk. Every director watches films before shooting one, and the
|
||
reflex table in `taste.md` only tells you what to *avoid* — recon tells you what is currently
|
||
*alive*. Two commands do the gathering; you do the reading. Both write into `design/`, both are
|
||
cheap, both are bounded: recon is a short pass at the top of phase 0, not a research project.
|
||
|
||
| | command | answers |
|
||
|---|---|---|
|
||
| **A** | `node scripts/refscout.mjs` | *how do the best sites in this space actually work?* — live sites, their real stack, their scroll mechanics, screenshots |
|
||
| **B** | `node scripts/moodboard.mjs` | *what should this feel like?* — palette, light, composition, type energy, texture |
|
||
|
||
Run A when the brief has a **mechanic** question (direct register, "wow", scroll choreography).
|
||
Run B when the brief has a **look** question (any register with an undecided art direction).
|
||
Most briefs want both, in that order, ~5 minutes total. Skip either without guilt when the brief
|
||
already fixes that axis (existing brand book → skip B; "boring docs site" → skip A).
|
||
|
||
Both need `playwright` (`npm i -D playwright && npx playwright install chromium`). No API keys,
|
||
no logins, no paid services.
|
||
|
||
---
|
||
|
||
## A. refscout — take the references apart
|
||
|
||
```bash
|
||
# harvest what is winning right now, profile it
|
||
node scripts/refscout.mjs --from awwwards --limit 8
|
||
|
||
# same, filtered by the gallery's own category or a text search
|
||
node scripts/refscout.mjs --from awwwards:scrolling --limit 6
|
||
node scripts/refscout.mjs --from awwwards --search "coffee" --limit 5
|
||
|
||
# or profile sites you already know / found with web_search
|
||
node scripts/refscout.mjs https://a.com https://b.com --shots 4
|
||
```
|
||
|
||
Output lands in `design/refs/`: `REFERENCES.md` (read it), `refs.json`, `shots/*.png`.
|
||
|
||
**Finding candidates.** `--from awwwards` is the only harvester wired in, because it is the only
|
||
gallery whose listing *and* detail pages render reliably headless and expose the outbound site
|
||
URL. For everything else — godly.website, curated.design, minimal.gallery, land-book, siteinspire,
|
||
thefwa, lapa.ninja, mobbin — use `web_search` to find the write-ups, then pass the site URLs to
|
||
refscout positionally. Searching for the *page about* a site is more reliable than scraping the
|
||
gallery that lists it.
|
||
|
||
**Naming a technique you can see but can't name.** originkit.dev is a catalogue of ~160 motion
|
||
effects, each with a live preview and a name — useful when a reference does something you want to
|
||
describe in the commit-sheet and have no word for. Browse it, take the vocabulary, then build the
|
||
thing yourself; the components are React/framer-motion behind a signup, and half the catalogue is
|
||
the exact drop-in ornament `slopscan` exists to keep out.
|
||
|
||
### Reading a fingerprint
|
||
|
||
Each entry reports what the page actually loaded and did, not what its marketing says:
|
||
|
||
- **stack** — libraries found in the JS the page really fetched. Bundlers hide globals, so this is
|
||
matched against bundle text; treat it as strong evidence, not proof. `GSAP + ScrollTrigger +
|
||
ScrollSmoother + Lenis` is the house style of the entire awwwards top tier — seeing it for the
|
||
fifth time is the useful signal, not a coincidence.
|
||
- **mechanics** — the derived read: pinned scenes (counted from `.pin-spacer` elements ScrollTrigger
|
||
leaves in the DOM), WebGL driven by scroll, sticky stacks, CSS `animation-timeline`, mix-blend
|
||
layers, custom cursor, scrubbed video. This is the column you are actually shopping in.
|
||
- **page shape** — `22× viewport tall · 14 sections` tells you the scroll budget the reference spends.
|
||
A 22× page with 4 pinned scenes is a different film from a 3× page with one WebGL hero, and the
|
||
difference is a decision you have to make too.
|
||
- **type / palette** — the fonts and colours as painted, sampled from computed styles. `LayGrotesk +
|
||
PPNeueMontrealMono`, `Thunder + PP Fraktion Mono` — this is where you learn that the top tier is not
|
||
running Inter, which is exactly ban #8 with receipts. The display face is measured as the largest
|
||
*painted* text (`Thunder, sans-serif 118px/800`), never the first `h1`, because a hidden or
|
||
fallback-styled heading reports whatever the cascade left there and will cheerfully claim an
|
||
awwwards winner ships Inter. The px figure is evidence too: this tier runs display type past 100px.
|
||
- **shots** — hero plus scroll stops at 1440. **Look at every hero. Look at the remaining stops only
|
||
for the 2–3 sites you actually take a steal from.** At `--limit 8 --shots 3` that is 23 images and
|
||
reading all of them is not triage, it is a context bonfire. The numbers tell you the machinery;
|
||
your eyes decide whether it is beautiful — but only for the references you are actually using.
|
||
|
||
### ⚠ "NO CAPTURE" entries
|
||
|
||
Some sites hand a headless browser the server-rendered HTML and then never deliver their CSS or JS
|
||
(edge-streamed pages, bot walls). Anything read off such a page — fonts, colours, stack — would be
|
||
Chrome's defaults dressed up as findings, so refscout reports **nothing** for them rather than
|
||
something false. Roughly 1 in 8 award sites lands here. When it does: open the URL yourself, or
|
||
describe it from the gallery write-up, or drop it. Never quote a fingerprint the tool refused to give.
|
||
|
||
### The steal rule
|
||
|
||
Every entry has a `**steal:**` line and it is not decoration — fill it in, one line, before you
|
||
close the file:
|
||
|
||
> "madewithgsap.com — the section title stays pinned while its cards scroll *through* it; we do this
|
||
> once, on the proof scene, with the product name instead of a title."
|
||
|
||
Rules, in order of how often they are broken:
|
||
|
||
1. **One idea per reference, named as a mechanic** — "pinned title, content scrolls through", not
|
||
"cool scroll effect", and never "the vibe".
|
||
2. **Adapted, or it is theft.** A reference is a starting camera position, not a set. Changing the
|
||
colours of a copied layout is not adaptation.
|
||
3. **Two references maximum feeding one scene.** Three is a collage, and collages read as slop.
|
||
4. **Never cite a reference you did not look at.** A fingerprint without eyes on the shots is half a
|
||
reference.
|
||
5. Named brand assets — logos, custom typefaces, photography, illustration — are theirs. Mechanics
|
||
and structure are free; identity is not.
|
||
|
||
### Feeding the commit-sheet
|
||
|
||
Recon changes what you write in the commit-sheet, especially field 6:
|
||
|
||
- The stacks and mechanics you saw five times ARE the first-order reflex (6a) for this category. If
|
||
your peak is the fifth pinned-WebGL-hero of the day, you found the mode, not an idea.
|
||
- The type and palette columns give you a real, dated map of what the category currently looks like
|
||
— much sharper than reasoning about it from memory.
|
||
- Any mechanic you take goes into the motion budget (field 5) as one of the ≤3 families, not on top
|
||
of it.
|
||
|
||
In the direct register, put the 2–3 references and their one-line steals in the STORYBOARD header
|
||
(`References taken`) so the decision survives into the build.
|
||
|
||
---
|
||
|
||
## B. moodboard — decide what it should feel like
|
||
|
||
```bash
|
||
node scripts/moodboard.mjs "editorial brutalist layout dark" "high contrast type poster" --limit 24
|
||
node scripts/moodboard.mjs "terracotta ceramic studio light" --source bing,arena --limit 16
|
||
```
|
||
|
||
Output lands in `design/moodboard/`: `contact-sheet*.png` (**look at these**), numbered `img/NN.jpg`,
|
||
and `MOODBOARD.md` mapping every tile number to its origin page. Twenty tiles arrive as one image,
|
||
so reading a moodboard costs one look, not twenty.
|
||
|
||
**Sources** (all no-auth, tried in this order and interleaved so none owns the sheet):
|
||
|
||
- `bing` — the workhorse. Bing's image index reaches into Pinterest, Dribbble and Behance CDNs and
|
||
serves originals that hotlink fine through a browser context.
|
||
- `pinterest` — logged-out search renders a partial grid behind the login wall: sometimes ~15 pins,
|
||
sometimes zero, day to day. Genuinely useful when it answers, never load-bearing; when it returns
|
||
nothing the script says so and bing has already covered it.
|
||
- `arena` — the public are.na search API. Lower volume, highest curation: these are blocks designers
|
||
saved for themselves.
|
||
|
||
### Query craft
|
||
|
||
The quality of a moodboard is decided entirely by the queries. Three rules:
|
||
|
||
1. **Two or three queries on different axes, never one.** A single query returns near-duplicates of
|
||
one template. Pick axes: *subject/medium* ("ceramic studio photography"), *treatment* ("hard rim
|
||
light, deep shadow"), *graphic language* ("swiss grid poster, red accent").
|
||
2. **Search the feeling, not the category.** `"coffee website"` returns other coffee websites — the
|
||
category reflex, delivered to your desk. `"steel and steam, industrial macro, warm shadow"`
|
||
returns material you can actually direct from.
|
||
3. **Check the anchor noun is not half of a fixed compound.** `"polished brass instrument macro"`
|
||
returns trumpets and saxophones, because *brass instrument* is one word to a search index. Same
|
||
trap: hard surface, light bulb, glass ceiling, sound board, steel drum. The noun is supposed to
|
||
ground the query, and an idiom hijacks it instead.
|
||
4. **Anchor a treatment query with a concrete noun.** Image search collapses an abstract phrase to
|
||
its most commercially indexed substring: `"hard rim light on dark glass, wet stone, near-black
|
||
macro"` came back as *hard surface* — hi-vis workers, gravel, granite pavers. `"wet black stone,
|
||
single hard light"` does not. When one query of three drifts, that is the mechanism.
|
||
5. **Never search a brand you intend to resemble.** That is the shortest path to a page that looks
|
||
like a competitor with the logo swapped.
|
||
|
||
### Reading the sheet
|
||
|
||
Fill the four lines at the bottom of `MOODBOARD.md` — the moodboard exists to produce these, and an
|
||
unfilled index means the sheet was decoration:
|
||
|
||
- **dominant palette** across the tiles you liked → commit-sheet field 2, converted to OKLCH. Take
|
||
the *relationship* (drenched single hue / near-mono with one accent / earthy midtones), not a
|
||
literal eyedropper.
|
||
- **light and contrast character** → the `lighting:` line of every scene-sheet and the literal
|
||
lighting parameter in generated-asset prompts (`assets.md` §1).
|
||
- **one composition move worth stealing** → commit-sheet field 4 (grid break).
|
||
- **what to explicitly avoid from these** → a real answer, because a sheet always contains the
|
||
category reflex too, and naming it is how you stop drifting into it.
|
||
|
||
Expect 10–20% junk per sheet. It usually is not spread evenly: one query drifts wholesale while the
|
||
others stay clean, so read the junk as a signal about that query, not about the sheet. Ignore the
|
||
strays; re-run only if a whole axis came back wrong, and re-run that axis with a concrete noun.
|
||
|
||
### Reference images are not assets
|
||
|
||
Downloaded images are direction only. They are other people's work, they are not licensed to you,
|
||
and none of them ships:
|
||
|
||
- never place a downloaded image in the page, not even as a placeholder that "we'll swap later";
|
||
- never reproduce one composition — the moodboard sets palette, light and energy, and the actual
|
||
frames get generated per `assets.md`;
|
||
- when the art direction is locked, the moodboard's job is done: it informs the generation prompts
|
||
and then stays in `design/`.
|
||
|
||
`design/moodboard/` and `design/refs/` are working artifacts. Ship them to no one and add them to
|
||
`.gitignore` if the repo is public.
|
||
|
||
---
|
||
|
||
## When recon fails
|
||
|
||
| symptom | what it means | do this |
|
||
|---|---|---|
|
||
| `awwwards listing returned no cards` | the gallery markup moved | fall back to `web_search` + positional URLs |
|
||
| most entries are `NO CAPTURE` | network or a broad bot wall | profile fewer, better-known sites; lean on the shots and your own eyes |
|
||
| `pinterest returned 0` | login wall, normal | ignore, bing covered it |
|
||
| the sheet is 20 variants of one image | single narrow query | re-run with 2–3 queries on different axes |
|
||
| one query's tiles are a different subject entirely | search collapsed an abstract phrase to a common substring | re-run that axis anchored to a concrete noun |
|
||
| a script looks hung for minutes | you piped it through `tail`/`head` | both stream progress to stderr; drop the pipe to watch it |
|
||
| references all look alike | you found the category mode | that IS the finding — write it into reflex-check 6a and deviate |
|
||
|
||
Recon is bounded. If it has not produced a usable read in one pass, stop and decide from
|
||
`taste.md` — a director who cannot find a reference still has to shoot the film.
|