iterate-design-lab
Skill8 starsChanged 50 days agoMITView on GitHub
Maintain this lab (the design-skill-lab repository): add or fix catalogue resources, run the link check, refresh catalogue thumbnails, add or re-review a research source, digest usage feedback into skill changes (evolve), run an eval round, cut a release. Repo-local and invoked by the owner. Not for: design work in any project (use design-studio), design reviews (critique-design) or building a design in code (implement-design).
In this repository3 other files it gives its agents.
- critique-designSkill
- design-studioSkill
- implement-designSkill
The file
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 2 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 30
If subagents are used at all, few of them, a cheaper model, results written to disk early.
- Distinctive: line 31
Every row, digest and field note is dated.
- Very specific: line 81
Follow research/README.md (怎么加一份来源): pick a permanent id, fetch the primary source (structured APIs and pinned repo commits first), write …
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Iterate Design Lab
The maintenance counterpart of the shipped suite (skills/). Pick a mode, run its steps, finish with the
Definition of Done. Scripts do the mechanical work; this file says which one and when.
The lab in one table
| What | Source of truth (edit) | Generated (never edit) |
| Catalogue | catalog/resources.jsonl, catalog/taxonomy.json, catalog/shot-overrides.json | skills/design-studio/references/catalog/, docs/data/, the <!-- gen:* --> regions of docs/index.html and docs/catalog/index.html |
| Observations | written by scripts only: catalog/observed.jsonl, docs/assets/thumbs/manifest.json | |
| Evidence | research/sources/, research/topics/, research/field/, research/log.md | research/INDEX.md |
| Skills | skills/*/ (shipped), this file (repo-local) | |
| Feedback | feedback/inbox/, feedback/log.md, feedback/proposals.md | feedback/report.md |
| Evals | evals/ | evals/runs/<date>/ results |
Ground rules:
- Visit, never remember. Licences come from the licence page. An unreachable host is not a dead one.
- Scripts before subagents:
scripts/check-links.pychecks the whole catalogue in minutes at zero model cost. If subagents are used at all, few of them, a cheaper model, results written to disk early. - Every row, digest and field note is dated. One rule has one owner file; others link to it.
- Survey, propose, confirm: pre-fill domain, section, tier and the predicted version bump; ask only for a real choice.
Modes
add-resources
- Deduplicate:
grep -i <host> catalog/resources.jsonl, andpython3 skills/design-studio/scripts/catalog.py find <term>for near-duplicates under another name. - Visit each site (fetch, or a real browser for JavaScript sites) and write a v2 row from what is there:
id(kebab, permanent) ·name(+name_zh) ·url(https, canonical, no tracking parameters) ·domain+section(fromcatalog/taxonomy.json;alsofor a second home) ·kind(taxonomykinds) ·tags(≤ 6, kebab) ·best_for(one specific sentence, no praise) ·how_to_use(filters, deep-link patterns, API) ·zh(required Chinese one-liner;zh_howoptional) ·access·login·license(fonts, icons, assets, code) ·tier·status·lang·region·entry_points/api/caveatswhen useful ·origin(user-YYYY-MM-DDorresearch-YYYY-MM-DD) ·added. No|in text fields. Tier: S = the first place a senior designer looks (≤ 15% of a domain, and agent-reachable or withentry_points/api); A = strong and reliable; B = niche or with a stated weakness. Owner-supplied sites are always included; weak ones go to B with the reason inbest_for. scripts/check-links.py --ids a,b,cappends observations (verdict,agent_access) tocatalog/observed.jsonl.npm run shoot -- --ids a,b,c --sheet <scratch>/sheet.png, then look at the sheet (see refresh-thumbnails).scripts/build-catalog.py, thenscripts/check-lab-invariants.sh.- Release: PATCH (see release). Update a section note in
catalog/taxonomy.jsononly when it no longer describes its rows.
link-check
scripts/check-links.py --report <scratch>/links.md(full run; appends tocatalog/observed.jsonl).- Triage by verdict.
dead/soft404: find the new URL (a deep link that decayed to the home page counts), else setstatus: sunsetand keep the row as history. Redirected to another host: usually an acquisition or rename; update the URL and say so inbest_forwhen people search for the old name.parked: the domain lapsed; sunset or replace.blocked/js: true for this network, not a verdict on quality; an S row needsentry_pointsorapian agent can use (the build warns).unreachable: confirm with a web search or another network before touching the row; never delete on unreachable. - Re-read a sample of S rows for paywalls, decline and licence changes; demote or annotate.
- Rebuild, gates, one line in
research/log.md.
refresh-thumbnails
npm run shootshoots rows without an ok thumbnail; add--stale 90to refresh old ones,--only-failingto retry failures,--ids a,b --forceto reshoot specific rows. Always pass--sheet <scratch>/sheet.png.- Review the contact sheet by eye: bot walls, consent banners, loading states, blank or header-only frames, a generic page where a better deep link exists. Pixel QA catches most, not all.
- Fix a bad capture in
catalog/shot-overrides.json(url,hide,css,wait,ready,scroll,localStorage,force,image,fit,block, and always anotesaying why), then reshoot those ids. Placeholders are fine: the page draws a designed card; a wrong picture is worse than none. scripts/build-catalog.py(regeneratesdocs/data/thumbs.js), gates;npm run smokewhen the site changed.
add-source
- Follow
research/README.md(怎么加一份来源): pick a permanent id, fetch the primary source (structured APIs and pinned repo commits first), writeresearch/sources/<id>.mdwith the header block,## Key facts(exact numbers and rules with the URL fragment),## What it changes for the skills,## Not verified / open. Paraphrase; never mirror. A new version of a source gets a new id andsuperseded_byon the old one. - Edit the skill references it changes and add the id to their frontmatter
sources:; setreviewedandreview_by(+90 days perishable, +365 durable). Update theresearch/topics/file whose conclusion moved. python3 scripts/build-research-index.py, a line inresearch/log.md, gates.- Re-review (a
review_bypassed, so gates fail): re-fetch, correct the digest and say what changed, movefetchedandreview_by, rebuild the index.
evolve
Feedback arrives in feedback/inbox/ per skills/design-studio/references/feedback.md.
- Harvest (interactive, owner names a host project that logged little): read its
.design/decisions.md, critique reports, the round's commits and the session transcript; write one inbox entry per finding. Describe the host by its kind only (project: office-addin-web), never by product, customer or directory name. Show the owner the entries before triage. scripts/collect-feedback.py; readfeedback/report.md, then every raw entry (the entries are the evidence).- Cluster by root cause, not by skill. An entry that repeats a "won't fix" in
feedback/log.mdis archived with a pointer to it. - Tier each cluster. A: misleading wording, factual errors, dead paths, two files contradicting each other;
apply. B: new guidance inside an existing section or reference; apply interactively and list it in the
summary so the owner can veto. C: new sections, references, modes or skills, contract changes, conflicting
entries, a lone nit or preference; write to
feedback/proposals.mdwith evidence and a concrete plan. - Apply A/B in the file that owns the rule; stay inside the line budgets; judge the version bump (release).
- Append one section to
feedback/log.md(date, entries, per-cluster action), thenscripts/collect-feedback.py --archive, gates. - Unattended runs are
scripts/evolve.sh(launchd:scripts/com.design-skill-lab.evolve.plist): proposals and Tier A only, on anevolve/<date>branch the owner reviews. Check it withscripts/evolve.sh --dry-run.
Act only on logged evidence. Thin evidence (one minor entry) goes to proposals, not into a skill. A correction from the owner outweighs any inference.
eval
- Output eval: follow
evals/README.md(six fixed briefs × arms no-skill / previous suite / current suite, canonical renders byevals/render.mjs, measured facts, three blind judges perevals/judging.md). Trigger eval:evals/run_triggers.md; the set must passpython3 evals/tools/score_triggers.py --validate. - Results go to
evals/runs/<date>/(results.jsonvalidated againstevals/results.schema.json,report.md). - Summarise in
research/field/evals-<date>.md(Chinese) and add the rows todocs/assets/showcase/showcase.json(format:docs/assets/showcase/README.md) so/skills/shows them. - Report losses and "no clear difference" as prominently as wins; feed each loss into skill changes or proposals.
release
- Judge the bump at commit time, for every non-trivial commit; one closed loop = one version. SemVer on the
design-studio contract (modes, deliverables, output layout, reference paths): PATCH wording, catalogue rows,
routine re-reviews; MINOR new guidance, references, sources that change guidance, or a contract reshape while
at 0.x; MAJOR a removal or rename from 1.0 on (after two MINOR releases under
弃用登记in the CHANGELOG). - A suite release moves together:
skills/design-studio/SKILL.mdmetadata.version, the README literalsuite 当前 X.Y.Z, the top## [X.Y.Z] - YYYY-MM-DDentry ofCHANGELOG.md(Chinese; what changed and why, per file), andversionin.claude-plugin/plugin.jsonand.claude-plugin/marketplace.json(gate G7). Other skills bump their ownmetadata.versiononly when their content changes. - Gates pass;
npm run smokewhendocs/changed. The owner commits, one commit per logical step, staging named files (nevergit add -A); branch for anything beyond a catalogue patch; never push or merge unasked. - The site is GitHub Pages from
main:/docs. A page fix is done whengh api repos/caocong1/design-skill-lab/pages/builds/latestshowsbuiltfor that commit.
Definition of Done
scripts/check-lab-invariants.sh exits 0 (stdlib, no network, seconds; details in scripts/gates.py):
G1 catalogue schema + generated views fresh · G2 every catalogue id has a thumbnail record (ok with its file, or
placeholder) · G3 research source headers valid, cited ids exist, research/INDEX.md fresh (fails when a
review_by passes) · G4 skill frontmatter, line budgets (design-studio and this file 200, other SKILL.md 150,
references 300), reference frontmatter (sources resolve, review_by not past), links and backtick paths resolve ·
G5 feedback entries valid · G6 eval trigger set valid · G7 one version everywhere · G8 no hand-typed catalogue
counts or dead links in docs/ · G9 no stray files tracked. CI (.github/workflows/check.yml) runs the gates and
the site smoke test on every push. When a gate is wrong, fix the gate in the same change and say so.
Also: new rows were visited, licences read at the source, tiers defensible; digests say what was actually read; only intended files are staged.
Anti-patterns
- Editing a generated file, or committing
catalog/resources.jsonlwithout rebuilding. - A row without
zh, a thumbnail or a link-check observation; a site added from memory; a guessed licence. - Deleting a row because this network could not reach it.
- Tier inflation: if everything is S, the tier means nothing.
- Perishable specifics (pixel specs, library APIs, trend lists) in a SKILL.md instead of a dated reference.
- Host product or customer names in feedback, field notes or commits.
- Fanning out expensive subagents for verification a script can do.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

