How I built a 577-file design knowledge graph

I turned a 17 KB landscape report into a queryable knowledge graph that any AI agent can read. It took 90 minutes to build and considerably longer to make safe to publish.

This is both halves. The fast build, and the slow curation that everyone skips when they write this kind of post.

The report

The session opened with one file. A markdown landscape report on the 2026 AI-coding-agent design ecosystem. 17 KB, 264 lines, 30-odd platforms synthesised into a readable narrative.

It was well organised. It was also inert.

The report could tell me what existed. It could not help me work. If I wanted to compare how three platforms describe glassmorphism, the report could only point me at three URLs.

A document you read is not the same thing as a system you use. That gap is the whole project.

Four decisions, locked before any code

I made four choices in writing before touching a file. Not because they were individually clever. Because rework is the expensive part.

Where it lives. Wrap the brain around the original report rather than start a new folder. The artifact that began it stays inside it.

How it is organised. Concept-first, not platform-first. When three platforms describe glassmorphism, that is one file with three sources, not three near-duplicates. Platform-first would have produced over 2,000 files and destroyed the dedup signal.

What goes in an empty file. Frontmatter plus a section scaffold. Queryable from the first minute, without looking finished before it is researched.

How thorough to be. Full live-fetched catalogs, not a curated subset. A half-built brain is a folder of documents.

The value was not in getting each one right. It was in fixing them early, in writing, before any code depended on them.

1,148 files in under a second

Eight research agents ran in parallel, each enumerating one platform cluster. Strict output format, word cap on every response. They returned catalogs, not HTML.

That mattered. Some of these sources span fifteen paginated views. Crawling them from the main thread would have filled the context window with markup and left no room to think.

One Python generator inlined every returned catalog as tuples and looped. It wrote 24 platform stubs and 1,124 skill files across 15 folders. 1,148 files, generated in under a second.

Not 1,148 individual write calls. One script with the data inside it. The difference is minutes against an afternoon.

Every file was a stub at this point. Frontmatter populated, body empty. The skeleton existed.

The only real adversary

One community source rate-limited hard. HTTP 429 after roughly twenty requests in a window.

My first attempt used a 0.3 second sleep between requests. It got 60 requests through before everything died.

The instinct is to sleep longer. That is patience, and patience does not scale.

What worked was engineering. A 60 second warmup before the run starts, so the window clears. 5 seconds between requests. Exponential backoff at 30, 60 and 90 seconds on consecutive failures. Three retries, then give up and mark the file.

The fetch took about 17 minutes. It ran in the background on a tracked process, so it never blocked anything else. While it ground through, I cloned another repo, processed 58 files from it, and fixed three slug mismatches elsewhere.

Rate limits demand engineering, not patience.

Audit first, and never synthesise

Halfway through, a constraint arrived that reshaped everything: do not pick skills that are half cooked.

That turned the pattern inside out. Instead of processing everything and hoping, every folder went through four steps. Audit. Report the audit. Process only the clean entries. Then inspect the rest by hand.

Styles is the clearest example. 4 files had two independent sources. 62 had one. 40 had a different one. 10 were light references. 7 were half cooked, with no canonical source at all.

None of the 7 were auto-filled. Three turned out to be slug mismatches and were renamed. Two were in the wrong folder and were moved. Two were real brand systems that had to be fetched explicitly.

Final state: 121 of 121 with real content. Zero half cooked.

An AI will happily write plausible content for a file that has no source.

That is the failure mode of this entire category of work. The only defence is a rule you do not break.

The part nobody writes about

A raw dump of 1,148 mixed-quality files is not publishable. Making a clean release took a second pass, and it took longer than the build.

A licence sweep audited every file. It found entries with no licence field at all. It found entries carrying vague non-licence strings. And it found 36 files under CC-BY-SA, which is sticky copyleft.

Those 36 are tagged license: CC-BY-SA and flagged composable: false, so copyleft can never silently contaminate composed output. Every one of them still carries both markers today.

Files with a missing licence were not assumed to be permissive. They traced to a single MIT-licensed source and were backfilled from verified provenance.

Eleven files were third-party clones with no verified redistribution right. One came from a repo with no LICENSE file at all. Cut, on principle, before release.

Six folders were excluded from the published set. Two of them are the largest folders in the tree: 365 brand systems and 140 vendor templates. They are real work. They are not mine to redistribute, so they stay local.

What is left is the number that matters. 577 files, across 9 categories, every one enriched, sourced and licence-declared. Styles 121, workflows 105, palettes 96, rules 95, typography 57, patterns 46, commands 27, charts 25, components 5.

Quality bar over coverage. That is the only reason the number went down.

The file

Every file carries the same header, whether it is enriched, downloaded or an honest gap:

---
name: glassmorphism
type: style
category: styles
platforms: [typeui, ui-ux-pro-max-skill]
url_sources:
  - https://github.com/bergside/awesome-design-skills/tree/main/skills/glassmorphism
license: MIT
fetched_at: 2026-05-13
status: enriched
---

The body varies by source. Sometimes a table derived from a CSV, sometimes a full SKILL.md from upstream, sometimes a quoted snippet. The frontmatter never varies. That is the whole trick.

The frontmatter is the index and the body is the content. Want everything sourced from one platform? Filter on platforms. Want to know what still needs work? Filter on status. An agent reads one file and has the rules, the tokens and the provenance together.

Honest annotation beats clever synthesis

Some things genuinely cannot be downloaded. Vendor presets and template galleries live inside product UIs and have no open file behind them.

I could have scraped marketing pages and called those folders complete. That would have produced 156 files of prose, each less useful than the stub that sits there now.

So the stub says what the thing is, links to where it lives, and marks itself status: vendor-only. More honest than filler, and more useful. The status field is queryable, so today's gaps are a work list rather than a lie.

What I would do differently

Check licences first, not last. I cloned a repo before looking for its LICENSE file. A 30 second check at the start would have let me decide upfront instead of cutting files at the end.

Pilot on 50 files before committing to 1,100. I went straight to full scale. Five platforms first, then inspect the output shape, then scale. That would have caught template problems while they were still cheap.

Budget for slug normalisation. Agents name things from display names. CSVs use slightly different display names. My generator used a third convention. Every folder carried 5 to 10 percent mismatches. There is no way to avoid this. There is a way to plan for it.

The method

Strip out the design specifics and the pattern is domain-independent.

Take a landscape, a taxonomy, or a survey you care about. Audit its sources. Decide a structure and lock it in writing. Write one generator that produces stubs at scale. Write small, focused scripts that enrich each stub from its own source. Audit before every merge. Refuse to fake completeness. Make every script re-runnable so the artifact moves when its ecosystem moves.

The collection is not the hard part. The standards made collection easy for everyone. SKILL.md landed in December 2025 and DESIGN.md in April 2026.

The hard part is deciding what to cut.

The graph you end up with is just the artifact. The pattern that built it is the durable asset.

If your design system needs to work with agents, here are the three ways in.