agentleFS
caocong1caocong1/design-skill-lab/.claude/skills/iterate-design-lab/SKILL.md

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).

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
  1. Distinctive:

    If subagents are used at all, few of them, a cheaper model, results written to disk early.

    line 30
  2. Distinctive:

    Every row, digest and field note is dated.

    line 31
  3. Very specific:

    Follow research/README.md (怎么加一份来源): pick a permanent id, fetch the primary source (structured APIs and pinned repo commits first), write …

    line 81

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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

WhatSource of truth (edit)Generated (never edit)
Cataloguecatalog/resources.jsonl, catalog/taxonomy.json, catalog/shot-overrides.jsonskills/design-studio/references/catalog/, docs/data/, the <!-- gen:* --> regions of docs/index.html and docs/catalog/index.html
Observationswritten by scripts only: catalog/observed.jsonl, docs/assets/thumbs/manifest.json
Evidenceresearch/sources/, research/topics/, research/field/, research/log.mdresearch/INDEX.md
Skillsskills/*/ (shipped), this file (repo-local)
Feedbackfeedback/inbox/, feedback/log.md, feedback/proposals.mdfeedback/report.md
Evalsevals/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.py checks 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

  1. Deduplicate: grep -i <host> catalog/resources.jsonl, and python3 skills/design-studio/scripts/catalog.py find <term> for near-duplicates under another name.
  2. 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 (from catalog/taxonomy.json; also for a second home) · kind (taxonomy kinds) · tags (≤ 6, kebab) · best_for (one specific sentence, no praise) · how_to_use (filters, deep-link patterns, API) · zh (required Chinese one-liner; zh_how optional) · access · login · license (fonts, icons, assets, code) · tier · status · lang · region · entry_points / api / caveats when useful · origin (user-YYYY-MM-DD or research-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 with entry_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 in best_for.
  3. scripts/check-links.py --ids a,b,c appends observations (verdict, agent_access) to catalog/observed.jsonl.
  4. npm run shoot -- --ids a,b,c --sheet <scratch>/sheet.png, then look at the sheet (see refresh-thumbnails).
  5. scripts/build-catalog.py, then scripts/check-lab-invariants.sh.
  6. Release: PATCH (see release). Update a section note in catalog/taxonomy.json only when it no longer describes its rows.

link-check

  1. scripts/check-links.py --report <scratch>/links.md (full run; appends to catalog/observed.jsonl).
  2. Triage by verdict. dead / soft404: find the new URL (a deep link that decayed to the home page counts), else set status: sunset and keep the row as history. Redirected to another host: usually an acquisition or rename; update the URL and say so in best_for when 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 needs entry_points or api an agent can use (the build warns). unreachable: confirm with a web search or another network before touching the row; never delete on unreachable.
  3. Re-read a sample of S rows for paywalls, decline and licence changes; demote or annotate.
  4. Rebuild, gates, one line in research/log.md.

refresh-thumbnails

  1. npm run shoot shoots rows without an ok thumbnail; add --stale 90 to refresh old ones, --only-failing to retry failures, --ids a,b --force to reshoot specific rows. Always pass --sheet <scratch>/sheet.png.
  2. 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.
  3. Fix a bad capture in catalog/shot-overrides.json (url, hide, css, wait, ready, scroll, localStorage, force, image, fit, block, and always a note saying why), then reshoot those ids. Placeholders are fine: the page draws a designed card; a wrong picture is worse than none.
  4. scripts/build-catalog.py (regenerates docs/data/thumbs.js), gates; npm run smoke when the site changed.

add-source

  1. Follow research/README.md (怎么加一份来源): pick a permanent id, fetch the primary source (structured APIs and pinned repo commits first), write research/sources/<id>.md with 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 and superseded_by on the old one.
  2. Edit the skill references it changes and add the id to their frontmatter sources:; set reviewed and review_by (+90 days perishable, +365 durable). Update the research/topics/ file whose conclusion moved.
  3. python3 scripts/build-research-index.py, a line in research/log.md, gates.
  4. Re-review (a review_by passed, so gates fail): re-fetch, correct the digest and say what changed, move fetched and review_by, rebuild the index.

evolve

Feedback arrives in feedback/inbox/ per skills/design-studio/references/feedback.md.

  1. 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.
  2. scripts/collect-feedback.py; read feedback/report.md, then every raw entry (the entries are the evidence).
  3. Cluster by root cause, not by skill. An entry that repeats a "won't fix" in feedback/log.md is archived with a pointer to it.
  4. 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.md with evidence and a concrete plan.
  5. Apply A/B in the file that owns the rule; stay inside the line budgets; judge the version bump (release).
  6. Append one section to feedback/log.md (date, entries, per-cluster action), then scripts/collect-feedback.py --archive, gates.
  7. Unattended runs are scripts/evolve.sh (launchd: scripts/com.design-skill-lab.evolve.plist): proposals and Tier A only, on an evolve/<date> branch the owner reviews. Check it with scripts/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

  1. Output eval: follow evals/README.md (six fixed briefs × arms no-skill / previous suite / current suite, canonical renders by evals/render.mjs, measured facts, three blind judges per evals/judging.md). Trigger eval: evals/run_triggers.md; the set must pass python3 evals/tools/score_triggers.py --validate.
  2. Results go to evals/runs/<date>/ (results.json validated against evals/results.schema.json, report.md).
  3. Summarise in research/field/evals-<date>.md (Chinese) and add the rows to docs/assets/showcase/showcase.json (format: docs/assets/showcase/README.md) so /skills/ shows them.
  4. 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.md metadata.version, the README literal suite 当前 X.Y.Z, the top ## [X.Y.Z] - YYYY-MM-DD entry of CHANGELOG.md (Chinese; what changed and why, per file), and version in .claude-plugin/plugin.json and .claude-plugin/marketplace.json (gate G7). Other skills bump their own metadata.version only when their content changes.
  • Gates pass; npm run smoke when docs/ changed. The owner commits, one commit per logical step, staging named files (never git 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 when gh api repos/caocong1/design-skill-lab/pages/builds/latest shows built for 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.jsonl without 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.