All about Ken Hawkins

CADI: a prescriptive path for slop-free AI in content work

2026-06-09T00:00:00.000Z

Recently I was in a meeting with colleagues talking about how people across the organisation are using AI in their writing. What I heard:

"I just prompt it and ship. We don't have time to fuss."

"I use it for ideas, but I still write the piece myself."

"I rewrite every line. I'm honestly not sure I'm saving any time."

"It's infuriating."

"I see other people using it and I see the same repetitive AI tells bleeding through."

"I'm not convinced any of this is worth it. The old way was quieter and probably better."

"Other organisations are using it. We can't be the only ones not."

—

"Should I just get better at prompting?"

"Should I write a style guide?"

"Should I build an agent?"

"Should I document my preferences somewhere?"

"Should I upload my existing content?"

The honest answer is always some version of "yes, but in a specific order, and most of the value comes from the combination." Helping colleagues do better is frustrating as it's a repetitive conversation and it's far too conceptual for many to put in practice.

So I documented it. This is CADI — Collect, Analyze, Document, Iterate — a prescriptive path through the confusion.

The name nods to a caddie in golf: carries the load, doesn't take the swing. It's designed to be followed roughly in order, at least the first time through.

An experienced editor with access to your content can produce a first usable version of the guidance in a few hours by feeding curated examples to a language model and shaping what comes back. Then it's an editorial process: share it with colleagues, use it for a few days, fold their reactions in. Each round sharpens the guidance; the work doesn't get heavier, the picture gets clearer. It works for any content type or language, as long as you have enough of it to learn from.

The problem: every prompt starts from zero#

Most AI writing assistance starts cold every time. No memory of what worked last time. No sense of your voice, your standards, your audience. So it gives you something generic and confident, and you spend the rest of your time correcting it.

The fix isn't a better prompt. It's giving the AI a documented picture of what good looks like for you, and building a way to improve that picture as you learn what works. Done right, the AI gets more useful over time rather than requiring the same effort on every task.

There's a failure mode that persists even after you think you've solved this: confident wrongness + silent drift. The AI sounds authoritative but cites a source incorrectly. It hits approximately the right word count but adds a paragraph that subtly changes your meaning. These are harder to catch than obvious nonsense, and they accumulate faster.

Where you probably are: supervised co-writing#

Most people using AI for writing aren't doing "autonomous AI publishing." They're doing supervised co-writing: AI handles a first pass or a tedious task, a human reviews and corrects, a human publishes. That's normal; it's also where most of the real value is right now.

CADI is for teams who want to move from "AI is something we sometimes use" to "AI is something our editorial standards reliably shape." That transition doesn't happen through better prompting alone.

Before you start: five things to check#

This framework works best when you can answer yes to these:

You have ideally 50+ published items you consider high-quality (not just recent). 10–20 from a tight, high-quality domain still works; you'll overfit a little, but the discipline of running the loop is what compounds
You have some signal for quality: engagement data, editor picks, longevity tags, or even manual curation
At least one person has time to own the guidance doc and keep it current
You have some way to export content from your CMS in text form (Markdown, HTML, CSV)
Editors are willing to log failures rather than just silently fix them

You don't need a data science team, a custom CMS, or a formal AI strategy. But if no one will own the guidance document, the method breaks down.

Pick your tool#

Before you start, decide how you'll feed your content to an LLM. The choice shapes every step that follows.

NotebookLM or similar. Best if your content is web-accessible. Drop URLs or PDFs as sources; run prompts in the chat. Zero file handling.
A local agent (Claude Code, GitHub Copilot CLI, or similar). Best if you've exported your content as files. Point the agent at the directory and ask it to run the prompts. Handles iteration and cleanup for you.
Manual pipeline (browser-only). Fallback when the other two aren't options. You'll preprocess HTML, concatenate, and paste into a browser tool. The starter kit has the prompts.

The rest of the post assumes you've picked one. When a step says "run the Analyze prompt" or "feed the corpus to your model," substitute your chosen tool's mechanics.

The CADI framework: Collect → Analyze → Document → Iterate#

CADI is a four-phase loop. You build it once, then run the last phase continuously. Each cycle makes the guidance sharper, and the AI more useful.

The bit most AI-writing advice misses: the guidance document is something you test and revise. C, A, and D get you a first version. I is where it earns its keep.

I've arrived at this through practice, and written about the pieces separately. This is the first time I've named it.

C — Collect: Extract your best examples#

Your best content already embodies your patterns: word counts, title structures, tag usage, narrative flow. Don't grab the latest 50 published items; curate the exemplary 50.

Start with one content subtype, not a mix. Most organisations publish several things that look similar but follow different patterns: press releases, news briefs, feature reports, donor updates, blog posts. Each has its own voice and structure. Mixing them gives you average patterns that fit none of them. Pick the subtype that matters most to you right now and run CADI on that. Repeat for other subtypes later.

Don't default to top-traffic items. That's the obvious choice and the most common mistake. High traffic often correlates with topic timeliness, social-share luck, or audience reach, not with the qualities you'd want to reproduce. Three signals to combine instead:

Editorial investment — items your team spent the most time on. Effort is a quality signal even when the numbers aren't there.
Aspirational fit — items you'd want more of your output to look like.
Performance for type — a press release that did 5× the median for press releases tells you more than a feature that hit Hacker News.

Document the criteria you used. It will matter when you audit later.

Bring your existing reference materials too. Your best content shows the agent what good looks like by example. Your existing editorial handbook, brand guidelines, glossary, terminology and spelling lists, institutional style memos — these tell it the rules you want enforced. Add them as sources alongside the corpus. The agent should be able to cite them when producing drafts ("per our spelling guide, we use 'organization' with a z") and link to them when justifying its choices. If your handbook says "no Oxford comma," the corpus pattern alone might not surface that as a hard rule.

Getting the files to your tool. With NotebookLM, add the URLs or PDFs of your 50–100 best items as sources. With a local agent, export your content as HTML to a directory and point the agent there. With the manual pipeline, follow the four steps in the starter kit. One-time setup per content subtype.

👉 Ready to move on when: you have 50–100 items in a single consolidated, cleaned document; you've written down why they qualify; and an editor has spot-checked for obvious outliers.

For implementation detail, including Drupal export code and a worked UNDRR case study, see Improving AI chatbots with an editorial handbook from your best content.

A — Analyze: Find quantitative patterns#

Feed your curated examples to an LLM with a structured prompt to extract:

Average word counts (with ranges, by content type)
Title formats and syntactic shapes (% using colons or question marks; whether titles assert claims, ask questions, restate the source headline, or use first-person observation)
Heading and structural patterns (do longer pieces get H2s? At what word-count threshold? Lists vs. prose?)
Voice markers (first vs. third person, contractions, hedging language, sentence-length variance)
Source treatment (% linking sources inline, % using blockquotes from the source, whether the source is named in the first paragraph)
Opening and closing patterns (does the first paragraph name a topic, a scene, a source? Does the last forward-link or name a broader pattern?)
Cross-linking density (internal links per piece; what fraction connect to other content on the site)
Metadata usage (tag counts, co-occurrence patterns)

This list isn't exhaustive. Your subtype will have its own tells — repeated structural moves, signature phrasing, specific rhetorical positioning. Add the signals that matter for your content; document what you watched for. It'll be the first thing you revisit on the next cycle.

LLMs handle this extraction well; the interpretation is still yours. The output is not guidance yet; it's empirical description of what your best content actually looks like.

👉 Ready to move on when: you have a written summary of patterns with numbers, and at least one editor has reviewed it and flagged anything that looks wrong or unrepresentative.

D — Document: Turn patterns into working instructions#

Combine what the analysis found with your existing institutional knowledge (style guides, brand standards, domain constraints) into a single document your AI tool can use as its standing instructions. Link or embed any existing reference docs your team already maintains; the guidance doc should point at them rather than restate them, so editors and the agent can both trace any rule back to its source.

If your existing style guide already addresses this subtype, the Document step isn't to re-derive from scratch. It's to tighten the existing guidance with the numbers the Analyze step produced, and override only where you have evidence the guidance was wrong.

This step requires editorial judgment: observed patterns and existing style rules will sometimes conflict. If the analysis says your best titles average 8 words but house style caps them at 6, decide which wins and log why. Write it down; that decision belongs in your change log, not left implicit.

You end up with instructions concrete enough to act on ("180 words ± 10%") rather than vague ("be concise"). Bonus: the same document works for human editors too.

👉 Ready to move on when: the instructions have been reviewed by at least one editor who wasn't involved in writing them, and they've been uploaded or integrated with your AI tool.

I — Iterate: Build confidence over time#

Iteration done badly is just tweaking in the dark, which is how we started. Done well, it's hypothesis-driven:

"IF we add explicit numeric targets ('180 words ± 10%'), THEN first-pass acceptance rises from 40% to 70%" (illustrative)
"IF we show exemplars of title styles, THEN AI chooses appropriate titles 85% of the time" (illustrative)
"IF we run oppositional review (a second model critiques our guidance), THEN we catch biased rules 80% of the time" (illustrative)

Then test them: run a simple before/after comparison on real content, measure outcomes with a concrete metric, and document what changed and why.

For a small team (2–3 editors), 20–30 items per condition is enough for an honest qualitative comparison: better than tweaking blind, not a statistical signal. Anything closer to statistical rigour needs much larger samples and blinded review; most editorial teams won't reach that, and that's fine. The bar is qualitative honesty: what changed, and why.

Mid-cycle revision trigger: if more than 20% of outputs in a week fail the same check, don't wait for the quarterly audit. That's a pattern worth investigating now.

None of this is invented from scratch. Other disciplines have been at versions of this for decades:

Writer and Jasper will both reverse-engineer a voice profile from examples of your own content; worth knowing about, and worth using if they fit your stack.
ChainForge (CHI 2024) formalized treating prompts, and the evaluation criteria themselves, as testable hypotheses.
Medical guideline development (AGREE II and GRADE) assess whether guidelines are evidence-based and implementable. The Australian COVID-19 living guidelines went further: revised and republished weekly for 24 weeks as new evidence arrived, a continuously iterated guidance document running in production

But a software subscription isn't a method, and a research paper isn't a guide. What I haven't seen elsewhere is the connected discipline: deriving guidance from your own curated corpus, then keeping the failure log and test record that make that guidance revisable on evidence rather than vibes. That combination is what CADI names. If reading this sends you off to subscribe to one of those tools or build your own loop from the research, good; that's the point. Prior art still welcome.

👉 Ready to move on when: you have at least one completed hypothesis test, a documented decision (kept or rejected), and a failure log that someone is actually adding to.

CADI in practice: how it played out at UNDRR#

One case illustrates the full loop:

Collection: 122 publications flagged as "evergreen + high-engagement" in Drupal
Analysis: LLM extracted patterns. "169 words average; 56% use colons in title; all use 2–4 themes"
Documentation: Guidance doc drafted and uploaded as standing instructions in Microsoft 365 Copilot
Iteration: Quarterly audits checked whether new AI drafts matched patterns; a shared change log recorded what was adjusted and why

The honest version of the result: before CADI, none of these pieces (curation, pattern extraction, guidance docs, iteration) reliably produced anything usable on its own. They were ad-hoc, inconsistent, and each task started over. Running them as a connected loop turned a set of one-off attempts into a process that ran continuously and got better. The framework's value wasn't a single big number; it was making something repeatable that hadn't been. The longer case file (the original methodology, plus what the guidance doc looked like in practice) is in the UNDRR impact story.

And I'm not pretending what I have is rigorous yet. What would make the next version genuinely rigorous is a prospective A/B test that quantifies which guidance changes move which outcomes by how much. That's the piece most teams skip; writing this down, sharing it, and letting it be challenged is part of how I keep tightening the loop.

Using CADI in the writing workflow#

CADI gives you the guidance layer. The day-to-day writing that uses it has a shape of its own:

Ideation — what are we writing, for whom, why now? AI helps brainstorm; the editorial decision is yours.
Scaffolding — outline, key points, source material. CADI's guidance doc steers tone and structure; the agent helps assemble.
Drafting — produce the first pass with the guidance doc as the agent's standing context.
Review — apply role-based passes for the checks this piece needs.

The review step is where you pick agent roles that match the piece's risk and shape. The ones I've found useful:

Copy editor — grammar, flow, voice consistency against the guidance doc
Adversarial reviewer — does the argument hold? What's the strongest counter?
Legal / compliance check — for content with regulatory exposure
Copyright check — for content with quotation, imagery, or external sourcing
Technical reviewer — for content making claims about systems, code, or data
Sanity check — final read for "does this make sense, end to end?"

Not every piece needs every role; pick what fits the content type and its risk profile. The CADI guidance doc gets stronger when failure-log entries name which role would have caught the failure — that's how you learn which checks belong in which subtype's workflow.

A deeper walk-through, with prompts and examples for each role, is coming in a follow-up post.

Trust but verify: the publication gate#

The trust-but-verify gate sits between any CADI-assisted draft and publication. Don't skip it, even once you trust the system:

Verify factual claims and sources independently
Verify hard constraints (word/character counts, required fields). Don't trust the model's own count
Verify meaning hasn't drifted from source intent
Keep human sign-off as the final release gate

For many teams, a parallel run is the safest transition: keep your normal manual editorial review while running AI-assisted output alongside it. Compare decisions, measure drift, then scale what proves useful.

This is also the spirit of the editorial AI policies emerging in newsrooms, where Ars Technica and Fedora make "reviewed" a protected verb with the human review step explicit and named. CADI takes the same position: the loop doesn't replace the gate; it makes the gate cheaper to operate.

Where this breaks down#

Iteration goes blind again when:

Encoding bias without inspection: a pattern like "short sentences good" might just reflect that your exemplars targeted beginners; applying it universally infantilizes advanced content
Optimizing for fit, not truth: "this tag co-occurs 26% of the time, so ALWAYS pair them" (should be "consider pairing")
No quality gate on source: including mediocre content in your "best" set skews guidance toward mediocrity
Stopping too early: 10 examples isn't enough; 500 might over-fit
Expecting voice cloning in informal genres: the style-imitation research is encouraging for structured formats like news and email, and much weaker for informal, personal writing like blogs and forum posts. Corpus-derived guidance reliably reproduces structure and conventions; a distinctive personal voice still needs the human pass

Prevention: transparent curation criteria, documented assumptions, human review between cycles, oppositional analysis (ask a second model to critique your instructions), and built-in escape hatches ("usually X, unless Y").

Where CADI doesn't fit cleanly: high-volume newsrooms shipping dozens of pieces per week across many content subtypes. CADI assumes one primary subtype at a time and a corpus you can read in full. Sampling methodology and per-subtype parallel runs are needed there. Out of scope for this post, but the same loop applies once you've made those decisions.

What you maintain alongside the loop#

These four documents are what CADI actually leaves you with. The starter kit has templates for each: cadi-starter-kit.txt.

A curation criteria note — why these items qualified as exemplary, and not others
Your working AI instructions — the guidance doc the AI uses as its standing context
A failure log — the one document that's more valuable than the guidance doc itself; it's where the next iteration starts
A test record — what you tested, what changed, and why

If no one is keeping at least the failure log current, you're not iterating; you're just running C/A/D once and hoping.

After your first cycle, go deeper#

These earlier posts go deeper on individual phases. You don't need to read them to start.

Improving AI chatbots with an editorial handbook from your best content: the C and A phases in detail, with Drupal export code and the full UNDRR case study (updated June 2026)
The power of the pause: How planning beats prompt tuning: structure over tweaking, with PROJECT_BRIEF → PROJECT_PLAN → PATTERNS workflow
Thoughtful AI integration beats bolted-on Clippy: product thinking for AI integration, when to use it, not just how to prompt it
Why context engineering was always the job: where CADI sits in the broader move toward context as the work
The four phases of AI adoption: the Complement / Integrate / Delegate / Orchestrate taxonomy; CADI lives around Integrate and Delegate

CADI is the loop we run at UNDRR. Think of it as a forcing function more than a magic generator: most of the work is still you reading your own content carefully. The framework just makes sure you do it, and write down what you learn.

It works for us; it might work for you; or it might need reshaping for the volume, content type, or constraints you're in. I'd be curious how it lands once you try it: what you change, what breaks, what surprises.

One direction I'm exploring: packaging CADI as a guided Claude skill (or similar) that asks where your content lives, walks you through the curation criteria, runs the Analyze prompt for you, and hands you a draft guidance document ready for editorial review. If that'd be useful, drop me a note.

The first run of this framework on this site is preserved as a worked artifact: CADI cycle 1 — digesting posts (June 2026). Future cycles will build on it.

References#

Bsharat et al., "Principled Instructions Are All You Need" (arXiv:2312.16171): a preprint reporting an average 57.7% quality boost from 26 generic prompting principles on GPT-4. Small, author-judged benchmark; read it as directional support for structured prompts, not as evidence for corpus-derived guidance specifically
"Catch Me If You Can? Not Yet: LLMs Still Struggle to Imitate the Implicit Writing Styles of Everyday Authors" (EMNLP 2025 Findings): exemplar-based prompting consistently beats instruction-only prompting for style matching; strong in structured genres, weak in informal ones
Wu et al., "ScatterShot: Interactive In-context Example Curation for Text Transformation" (ACM IUI 2023): systematic example curation beats ad-hoc hand-picking, which tends to capture only the most obvious patterns
Arawjo et al., "ChainForge: A Visual Toolkit for Prompt Engineering and LLM Hypothesis Testing" (CHI 2024)
Tendal et al., "Weekly updates of national living evidence-based guidelines: methods for the Australian living guidelines for care of people with COVID-19" (J Clin Epidemiol 2020)
Wei et al., "Chain-of-Thought Prompting Elicits Reasoning" (2022)
Yao et al., "Tree of Thoughts: Deliberate Problem Solving with LLMs" (2023)
Kohavi, Longbotham et al., "Controlled experiments on the web: survey and practical guide" (2009, Data Mining and Knowledge Discovery)
AGREE II — instrument for appraising the quality of clinical practice guidelines (the discipline of judging whether your guidance itself is sound)
GRADE — framework for grading the certainty of evidence and the strength of recommendations (separating "we're sure" from "we think")
Diátaxis — documentation framework organising knowledge by user need (tutorials, how-tos, reference, explanation) rather than by topic
PRISMA — reporting standard for systematic reviews (a checklist for how to describe what you did, so others can trust or replicate it)

A data font, from the inside out

2026-05-12T00:00:00.000Z

Datatype, by Frank Tisellano, is a variable font that renders inline bar charts, sparklines, and pie charts straight out of OpenType ligatures. Write {b:30,70,50,90} and get ; no JavaScript, no SVG, no charting library involved. It's also a total inversion of a 2018 piece of mine, A web font for data.

tl;dr

Datatype turns text like {b:30,70,50,90} into inline charts via OpenType ligatures: bar, sparkline, and pie, with weight and width axes.

It rhymes with a 2018 piece of mine, What if: A web font for data, but inverts it: my version was a font for reading dense data, this is a font that is the data.

The upstream project ships zero accessibility guidance; for any serious use, pair each chart with aria-hidden on the glyph span and a visually-hidden data table. There's a copyable pattern below.

A data font and font for data#

Back in 2018, while at EMBL-EBI, I wrote a long piece called What if: A web font for data. My problem was that life-sciences researchers stare at strings like ENSMUST00000032717 all day, and the tools they were using rendered those strings in fonts that had not been designed with that kind of work in mind. Sequential zeros were ambiguous (is 20000001 six zeros or seven?). Lowercase l, uppercase I, and numeric 1 could be hard to tell apart in body widths. BuMpy caPitiLiSation patterns were brittle to read at a glance. My sketch was a font where the ligature feature did the same kind of work Fira Code does for code, but pointed at scientific identifiers: chunking long zero runs, disambiguating glyphs, giving the reader's eye better handles.

Datatype is also a data font, and it's also built on the OpenType ligature feature. But it inverts every part of the goal. The text isn't there to be read in the normal sense; it's there to be drawn. The ligature substitution doesn't help you decode the characters — it replaces them entirely with a chart. The font isn't a better tool for the reader. The font is the data.

Clearly the aims are different, but the mirror universe aspect tickles my brain.

Datatype also credits IBM Plex Mono as the source of some underlying glyphs, and IBM Plex was the typeface I wrote about back in 2017 when we were evaluating it for EMBL-EBI's scientific data work. Neat.

Accessibility gap#

Data viz accessibility is always a challenge. Left alone, a string like {b:18,21,12,12,15,0,0,0,100,94} gets read aloud verbatim, brace by digit by comma. That's worse than no alternative at all.

This is made a bit better by the WAI pattern for complex graphics. Mark the glyph span aria-hidden, and pair each chart with a visually-hidden data table that assistive technology can navigate as proper rows and cells:

<p>
  Posts per year, 2017–2020:
  <span class="chart" aria-hidden="true">{b:60,70,40,40}</span>
</p>
<table class="kh-u-sr-only">
  <caption class="kh-u-sr-only">Posts per year, 2017–2020</caption>
  <thead><tr><th scope="col">Year</th><th scope="col">Posts</th></tr></thead>
  <tbody>
    <tr><td>2017</td><td>6</td></tr>
    <tr><td>2018</td><td>7</td></tr>
    <tr><td>2019</td><td>4</td></tr>
    <tr><td>2020</td><td>4</td></tr>
  </tbody>
</table>

Posts per year, 2017–2020:

Posts per year, 2017–2020
Year	Posts
2017	6
2018	7
2019	4
2020	4

I want an excuse to use it#

My enthusiasm for variable fonts as an expressive runtime is sitting at about (roughly 85 percent), while my likelihood of actually reaching for Datatype on the next chart I ship is somewhere around (roughly 25 percent). The gap between those two pies is basically the whole post.

Frank's specimen site is worth a visit on its own; the variable-axis sliders and live examples are a small showcase of typographic care.

Try Datatype on the project site →

Building a virtual garage for hobby projects

2026-05-09T00:00:00.000Z

I've been building hobby projects for years. Normally I'll give the better ones a write-up here and a link to GitHub Pages, but the project itself lives at khawkins98.github.io/project-name/.

I wanted to bring them on-domain without the obvious headaches: dozens of subdomains is more infrastructure than any of these deserve, subdomains still confuse people, and copying build output into the main repo defeats the point of keeping them separate.

Could I just have my site do what GitHub Pages already does: proxy /repo-name/ to whatever GitHub is already serving?

Before: khawkins98.github.io/PDF-A-go-go
After: AllAboutKen.com/PDF-A-go-go

Same project, same deploy pipeline, better home.

See the garage

Keep reading if you want to see exactly how I wired it up.

tl;dr#

Vercel rewrites proxy /project-name/:path* to the GitHub Pages origin — no deploy changes required

A naive rewrite 404s on the project root; two redirects entries (bare path and trailing slash → /project-name/index.html) fix it

Each project keeps its GitHub Pages URL; a hostname-check script redirects those visitors to the canonical URL

CORS headers on proxied paths cover shared JS assets loaded via fetch()

A /garage/ index page on the main site ties all the projects together

What I didn't want to do#

The obvious path is a merge: monorepo, or move each project to Vercel as a separate deployment. Both mean real work per project: consolidated CI, shared dependency trees, combined issue trackers. Hobby projects earn their independence precisely because they're free to be messy and self-contained. The right fix is a smarter routing layer in front, not a restructuring underneath.

How the proxy works#

My site was already on Vercel and each project already served from https://khawkins98.github.io/repo-name/.

Vercel rewrite rules can proxy a path prefix to an external origin. Minimum viable vercel.json:

{
  "rewrites": [
    {
      "source": "/PDF-A-go-go/:path*",
      "destination": "https://khawkins98.github.io/PDF-A-go-go/:path*"
    }
  ]
}

Requests to allaboutken.com/PDF-A-go-go/anything forward to khawkins98.github.io/PDF-A-go-go/anything. The GitHub Pages deploy keeps working at its original URL unchanged.

This works for every path except the project root.

The trailing-slash problem#

Going to allaboutken.com/PDF-A-go-go/ still gave a 404, even with the rewrite in place. The reason is Vercel's processing order: filesystem matching (including a directory-index check for build/PDF-A-go-go/index.html) runs before rewrites. That file doesn't exist in the main site's build, so Vercel 404s before the rewrite ever fires.

Two redirects entries fix it. Redirects run before filesystem matching:

{
  "redirects": [
    { "source": "/PDF-A-go-go",  "destination": "/PDF-A-go-go/index.html", "permanent": false },
    { "source": "/PDF-A-go-go/", "destination": "/PDF-A-go-go/index.html", "permanent": false }
  ],
  "rewrites": [
    {
        "source": "/PDF-A-go-go/:path*",
        "destination": "https://khawkins98.github.io/PDF-A-go-go/:path*"
    }
  ]
}

Visiting /PDF-A-go-go/ now redirects (302) to /PDF-A-go-go/index.html. No directory-index ambiguity; the rewrite fires and proxies to GitHub Pages. The browser ends up at /PDF-A-go-go/index.html, where relative asset paths like ./app.js resolve correctly to /PDF-A-go-go/app.js.

Not burning the old address#

GitHub Pages keeps serving at khawkins98.github.io/project-name/. The Vercel setup is additive: the personal domain gains a route, the original URL stays live. Rolling back is two deleted lines in vercel.json.

For now I've only moved two projects across — PDF-A-go-go and pinment — while I confirm that existing embed links aren't affected. The redirect from khawkins98.github.io to the proxied URL could in theory break things for anyone who has embedded the old URL directly. Once it's clear nothing is breaking, adding the rest is a few lines in vercel.json.

But visitors arriving at the old URL should reach the canonical one. A small script at the top of each project's <head>:

<script>if(window.location.hostname==='khawkins98.github.io'){window.location.replace('https://www.allaboutken.com/PDF-A-go-go/')}</script>
<link rel="canonical" href="https://www.allaboutken.com/PDF-A-go-go/">

The hostname check is essential. Without it, the redirect fires on the proxied page too: allaboutken.com proxies to github.io, github.io redirects back to allaboutken.com, repeat. The check breaks the loop.

Don't forget: CORS for shared JS assets#

Pinment is a bookmarklet tool. Its install snippet builds a script URL from window.location.origin at runtime, so it always points to whichever domain the user is visiting from. Through the Vercel proxy, that becomes allaboutken.com/pinment/pinment-bookmarklet.js, which the rewrite proxies correctly to GitHub Pages.

<script src> tags don't trigger CORS, but fetch() does. A headers block in vercel.json covers it:

{
  "headers": [
    { "source": "/pinment/:path*", "headers": [{ "key": "Access-Control-Allow-Origin", "value": "*" }] }
  ]
}

Worth adding for any project that exposes public JS assets loaded programmatically from other pages.

The full configuration#

{
  "buildCommand": "yarn build",
  "outputDirectory": "build",
  "headers": [
    { "source": "/PDF-A-go-go/:path*", "headers": [{ "key": "Access-Control-Allow-Origin", "value": "*" }] },
    { "source": "/pinment/:path*", "headers": [{ "key": "Access-Control-Allow-Origin", "value": "*" }] }
  ],
  "redirects": [
    { "source": "/PDF-A-go-go",  "destination": "/PDF-A-go-go/index.html", "permanent": false },
    { "source": "/PDF-A-go-go/", "destination": "/PDF-A-go-go/index.html", "permanent": false },
    { "source": "/pinment",  "destination": "/pinment/index.html", "permanent": false },
    { "source": "/pinment/", "destination": "/pinment/index.html", "permanent": false }
  ],
  "rewrites": [
    { "source": "/PDF-A-go-go/:path*", "destination": "https://khawkins98.github.io/PDF-A-go-go/:path*" },
    { "source": "/pinment/:path*", "destination": "https://khawkins98.github.io/pinment/:path*" }
  ]
}

Adding another project#

Confirm GitHub Pages is enabled and serving at USERNAME.github.io/repo-name/.
Check asset paths: ./-relative or prefixed with the repo name. Bare /styles.css will break.
Add two redirects entries and one rewrite to vercel.json.
Add the hostname-check script and <link rel="canonical"> to the project's index.html.
Add the project to the garage page.

For SPAs with client-side routing: the project needs a 404.html on GitHub Pages that loads index.html. The proxy can't route to paths the GH Pages deploy doesn't know about.

The full configuration and checklist live in vercel.json and docs/DEPLOYMENT.md. Nothing about the project deploys has to change: GitHub Pages stays the origin, Vercel becomes the routing layer. See what it looks like in practice at the garage. If you've proxied projects this way — or found a cleaner approach — I'd be glad to hear about it. The projects just get to live at home.

I think this is a clean way to bring web projects back home without adding server complexity.

Eye-tracking heatmaps in your browser, no lab needed

2026-05-03T00:00:00.000Z

At some point in most design or content reviews you find yourself trying to answer a question you can't answer cleanly: not "is it pretty?" but "will users actually notice the call to action, or are they going to get distracted by the hero image first?"

The honest answer is usually "Based off my knowledge and experience: I think so." That only holds until a stakeholder who disagrees says the same thing.

Foveacast gives both of you something to look at instead. Drop a screenshot of a UI — a web page, an app screen, a mockup — and it produces a predicted attention heatmap: a color overlay showing where a typical user is likely to look, and how that attention evolves over time. Nothing leaves your machine; the model runs entirely in your browser.

Try Foveacast View on GitHub

tl;dr

Drop a UI screenshot, get a predicted attention heatmap with fixation sequence, attention zones, and centroid trajectory.

Three viewing durations: first glance (1 s), quick scan (3 s), full viewing (7 s) — modeled separately, so you can see how attention evolves as users spend more time on the page.

Runs entirely in your browser. The model (~57 MB per duration) downloads and caches on first use; nothing is ever uploaded.

Built on MSI-Net fine-tuned on real UI eye-tracking data. Not a natural-scene model that doesn't know what a button is.

It's a probabilistic estimate, not a user study. The reading-your-results guide in the tool covers what it can and can't tell you.

The analysis report#

The output is a scrollable analysis report.

Warm colors show where a typical user's attention is predicted to concentrate. Cool tones indicate lower predicted attention density.

The heatmap overlay uses the inferno colormap: warm colors where attention is predicted to concentrate. Three viewing durations (first glance, quick scan, full viewing) are each backed by a separate model.

Below the heatmap: a rule-of-thirds grid with attention shares per region, a fixation sequence showing the predicted scan path as numbered dots, attention zones with contour rings at 10%, 25%, and 50% attention mass, and a centroid trajectory tracking where the attention center moves from first glance to sustained viewing.

In a design review, "the CTA doesn't appear until fixation 5, and 42% of initial attention lands on the hero image" is a different kind of conversation than "I think users will miss it." It's not proof. But it's a concrete starting point, and it gets you past the stage where everyone is arguing from intuition.

It's also useful as a self-check before publishing. Before you ship a redesigned landing page and find out three weeks later that the primary action was invisible.

Fixation sequence (left) and attention zones (right). The numbered dots show the predicted scan path order; contour rings mark where the densest fraction of attention falls.

Trained on real UI gaze data, not natural scenes#

Most open-source saliency models are trained on the SALICON dataset: natural photographs scraped from Flickr. Those models have learned to predict attention on photos of mountains and faces and street scenes. Put a web page in front of them and they produce a diffuse centrality blob. They don't know that "Start free trial" is the most important element on the screen; they see a rectangular region with text and mild contrast and model it accordingly.

Same page, two models. SALICON — trained on natural photographs — produces a diffuse central blob that poorly "understands" content. Foveacast, fine-tuned on real UI eye-tracking data, concentrates predicted attention on the headline, navigation, and key text elements.

The foveacast-training pipeline fine-tuned MSI-Net (Kroner et al. 2020) on UEyes (Jiang et al. 2023). Much credit is due there: Jiang et al. collected 1,980 UI screenshots with real eye-tracking data from 62 participants across desktop, mobile, web, and poster UIs, then published the full dataset on Zenodo under CC BY 4.0. Without that open release, Foveacast wouldn't have been viable to build. Fixations were recorded at 1, 3, and 7 seconds of viewing time, which is why there are three separate models rather than one. The gaze pattern at one second ("where do my eyes go first?") and at seven seconds ("where does sustained attention end up?") are genuinely different questions with different answers.

Fine-tuning on UI content closes the gap. On a held-out test split, the fine-tuned model improves by +43% on correlation coefficient and cuts KL divergence by 44% compared to the stock SALICON-only baseline. The stock model produces diffuse blobs. The fine-tuned model picks up navigation elements, content headings, and interactive controls, matching where real users actually looked.

Limitations: what predicted attention can't tell you#

Foveacast shows a non-dismissible note in the UI that says this is a probabilistic estimate based on population-average gaze patterns. A few things worth keeping in mind:

It's not measured data. The heatmap is model output, not fixations from real users looking at your specific design.
Training distribution. UEyes is primarily Western-language desktop and mobile UI, collected prior to the 2023 publication. Right-to-left layouts, dark-mode UIs, and design patterns that weren't common then may produce less reliable estimates.
Not a click predictor. High predicted attention on an element doesn't mean users will interact with it.

If you need real eye-tracking data — measured fixations from real participants — there are commercial services: Attention Insight, Alpha.one (formerly expoze.io), Clueify. They're paid, and they send your screenshots to a third party.

Foveacast is great to quickly, freely and securely close the gap: faster than a study, more specific than the F-pattern heuristic, and more honest than "I think."

How it runs entirely in your browser#

Like SVGOMG-Font and PDF-A-go-slim, everything processes locally. Design screenshots often contain unreleased client work or internal materials. Uploading them to a third-party service to get a heatmap is friction many organisations can't accept.

Running ONNX inference in the browser at this scale had some practical problems. WASM threading needs cross-origin isolation, which requires a service worker injecting the right headers. ORT Web's WASM paths have to be pinned when the app serves from a GitHub Pages subpath. The model weights are gitignored and fetched from a GitHub Release at deploy time rather than committed to the repo (57 MB each across three duration variants; they'd bloat every clone). The full engineering log is in LEARNINGS.md if you want the details.

Training on consumer hardware: a personal note#

This was my first proper model training exercise. I'd worked with embeddings before, but never fine-tuned a vision model. A few things made it more approachable than expected.

The training ran entirely on a MacBook Air M4 — no cloud GPU, no cluster. About three hours per model, so roughly nine hours of compute total across the three duration variants. Slow in absolute terms, but not the data-centre job I'd assumed fine-tuning required.

The other difference was AI-assisted development. What I'd expected to be a multi-week slog — working through PyTorch docs, debugging ONNX export paths, figuring out why the WASM runtime was choking on FP16 weights — turned into a genuinely enjoyable weekend project. Claude and Copilot handled a lot of the "read the error and suggest a fix" loop that normally drains the fun out of this kind of work.

I learned a lot and I'd do it again. If you want to fine-tune a saliency model on your own domain-specific data, the training pipeline is open and the README documents what worked and what didn't.

Try Foveacast on your own UI#

If you're working on a UI and want something more specific than the F-pattern heuristic and faster than an eye-tracking study, Foveacast is a reasonable starting point. If you use it in a real design review — or find a case where the model is clearly wrong — I'd genuinely like to hear about it.

Foveacast is on GitHub Pages. The source is on GitHub, with the training pipeline in a companion repository.

Related posts:

Stop converting SVG text to outlines — another browser-only utility from the same build season
Your browser utility wants to be a floating palette — the "do one thing, entirely in the browser" design philosophy
Semantic search on a static site, no API keys required — the same pattern of ML inference running locally in the browser

Stop converting SVG text to outlines

2026-04-29T00:00:00.000Z

Check out SVGOMG-Font

Every so often I need to put an SVG with text on a website: an infographic, a diagram, a data visualisation with labels. Each time, I end up staring at the same bad choice.

Option A: Convert the text to outlines. The SVG renders identically everywhere. No font loading, no layout surprises. Done. But now the text is a pile of path data. Screen readers see nothing. Search engines see nothing. Language models see nothing. Translation is impossible.

Option B: Leave the text as text. Clean, accessible, editable. But on any device that doesn't have the font installed, the browser falls back to whatever comes first in the system stack, and your carefully spaced infographic turns into a broken layout that looks like someone used Times New Roman on a web 1.0 site.

I've been choosing Option A for years and feeling bad about it. Despite plenty of searching, nothing combined what I actually wanted: a tool that runs in the browser, doesn't upload anywhere, and is open source. The closest matches were CLIs or a paid cloud service. So I built SVGOMG-Font. Drop the SVG in, get the same file back with the font subsetted to the characters in use and embedded as a base64 data URI.

tl;dr

Drop an SVG in, get back a self-contained one with the font embedded. Runs entirely in the browser, nothing uploaded.

Converting SVG text to outlines makes it invisible to assistive tech, search, translation, and LLMs.

Leaving text as-is fails on devices without the font installed.

SVGOMG-Font subsets to only the glyphs you actually use, so file sizes stay sensible.

Works cleanly for general-purpose infographics, diagrams, and posters. Rich text layouts that lean on OpenType features (ligatures, contextual alternates, complex scripts) need a closer look.

Here's an SVG set in Playwrite DE SAS, a connected German school-handwriting script almost no reader will have installed:

Before. No font embedded. Most readers see a Times-like serif fallback.

After. Font subsetted and embedded as base64; about 30 KB total.

The text is still real text: selectable, searchable, translatable. The font travels with the file, so it renders the same wherever the SVG lands.

You can sort of sidestep this if you control the host page: load the font via the page's CSS, and the inline SVG inherits it. But that's another asset to manage, another caching layer, and it only holds while the SVG stays on that page. Once the file has to travel (attached to an email, dropped into someone else's CMS, sent over Slack) the font reference goes dead. Bake the font into the SVG itself, the way a PDF embeds fonts, and it just works wherever the file ends up.

The problem with outlines#

When you tell Illustrator or Figma to "create outlines," it replaces every character with the equivalent vector paths. The rendering is locked in. But you've also just destroyed everything that made the text text:

Accessibility: screen readers can't read paths. The text is gone from the accessibility tree.
Search: both on-page (Cmd+F) and crawlers. An SVG infographic full of outlined text is invisible to search engines.
Translation: auto-translate and localisation tools operate on text nodes. No text nodes, no translation.
LLMs: if a language model needs to understand what your diagram says, it now has to do OCR or get the content from somewhere else.
Editability: editing outlined text means going back to the design tool, making the change, re-exporting, re-optimising, re-deploying. Minor corrections become multi-step processes.

There's a file-size argument too. A few hundred outlined characters easily adds tens of kilobytes of path data. Subsetting the font is usually smaller than outlining it.

Try SVGOMG-Font

How it works#

The structural change is small. Before, an @font-face rule points at a remote URL the viewer may never load:

<style>
  @font-face {
    font-family: 'Playwrite DE SAS';
    src: url('https://fonts.example/playwritedesas-regular.woff2');
  }
</style>
<text font-family="Playwrite DE SAS" x="20" y="40">Hello, world</text>

After, the same rule, with the font subsetted and inlined as a data URI:

<style>
  @font-face {
    font-family: 'Playwrite DE SAS';
    src: url('data:font/woff2;base64,d09GMgABAAAA…') format('woff2');
  }
</style>
<text font-family="Playwrite DE SAS" x="20" y="40">Hello, world</text>

That's the whole shape of it. SVGOMG-Font scans your file for @font-face references, fetches each font, subsets it to the glyphs in use, and rewrites the rule. No installation, no account, no upload: it all runs in the browser.

Why browser-only matters#

SVGs with fonts are often used in sensitive contexts: client work, unreleased materials, internal tools. Uploading to a third-party service to fix font rendering is a non-starter in a lot of organisations.

SVGOMG-Font processes everything locally. Nothing leaves your machine. It's a single static page. Foveacast, my browser-only attention-heatmap tool, runs the same way for the same reasons (write-up coming).

Prior art#

To be fair, this isn't entirely new territory. A handful of tools cover the same ground:

svg-embed-font, Go CLI: base64-embeds the full font.
svg-buddy, Java CLI: WOFF2 embedding given a local font file.
svgfontembed, Python CLI: embeds and subsets.
Vecta.io Nano: browser drag-and-drop SVG compressor that also handles font subsetting and embedding, hosted as a cloud service.

The CLIs share the install gap. Vecta.io Nano is the closest match in spirit (same drop-the-SVG-in workflow) but it's closed-source freemium SaaS, processes your file server-side, and has free-tier limits on file count and size. SVGOMG-Font fills the gap I kept hitting: same drop-in workflow, but open source, fully client-side, no upload, no signup. It also auto-resolves fonts from Google Fonts and Fontsource URLs, and on Chromium can pull from installed system fonts via the Local Font Access API.

The subsetting part#

The naive approach (embed the whole font) works but produces large files. A single Latin-subset woff2 file is roughly 20 to 30 KB, base64-encoded to about 40 KB. Two weights, and you've added 80 KB to your SVG before doing anything else.

SVGOMG-Font subsets to the characters in the SVG's text nodes, plus a Basic Latin safety baseline (U+0020 to U+007E). For a typical infographic with a few hundred unique characters, the subset is usually 5 to 15 KB encoded. Often smaller than outlining the same text.

There's a toggle to skip subsetting, useful when text gets added or replaced after export.

What it handles#

Fonts referenced via Google Fonts CSS URLs
Fonts referenced via Fontsource CDN paths
Cases where the font can't be found automatically: it prompts you to drag the font file onto the relevant row
Local system fonts on Chromium-based browsers via the Local Font Access API (permission-gated)
SVGO optimisation (optional, off by default; SVGO's inlineStyles pass removes @font-face rules if you're not careful)
Stripping legacy <font> / <glyph> blocks that some editors still emit

Where it gets bumpy#

For the bulk of SVG-with-text use cases (infographics, charts, diagrams, posters, headlines exported from Illustrator or Figma) the workflow just works. Where it gets shakier is anything leaning on OpenType machinery or rich text layout:

CORS-blocked fonts: a font hosted without permissive headers can't be fetched from the browser.
Variable fonts: subsetting variable fonts is finicky in general. If your SVG depends on a custom axis, test the output before shipping.
OpenType features: ligatures, contextual alternates, and stylistic sets sometimes reach for glyphs that don't appear in the visible text. The Basic Latin baseline catches most cases; obscure feature-driven glyphs may still drop.
Complex shaping scripts: Arabic, Devanagari, and similar scripts depend on positional and contextual glyphs. If your SVG uses one, eyeball the output rendering before trusting it.

Try it#

The split-screen slider in the tool itself. Drag the divider to scrub between the broken fallback and the embedded version, with file sizes and font count surfaced in each panel's header.

SVGOMG-Font is live on GitHub Pages. Drop your SVG in; if its font references resolve, you'll get a fixed file back in a few seconds.

The source is on GitHub. Bug reports welcome; font name matching in the wild has a long tail.

Related posts:

Your browser utility wants to be a floating palette (same "do one thing, entirely in the browser" design philosophy)
Introducing Pinment (another tool from the same season)
PDF-A-go-slim: a browser-based PDF optimizer (stripping and compressing PDFs, no upload required)
Foveacast: predicted-attention heatmaps in the browser (another client-side tool, same do-one-thing philosophy; blog post coming)

Designing analytics infrastructure that measures audience quality, not just traffic

2026-04-22T00:00:00.000Z

Clarity | Audience Quality | Strategic Alignment

Context The United Nations Office for Disaster Risk Reduction (UNDRR) is the UN's focal point for disaster risk reduction, coordinating global policy and supporting Member States to reduce disaster risk and losses.

Traditional web analytics answers "how many people visited?" For a UN organization producing policy guidance, technical resources, and knowledge products, that's the wrong question. The right question: did the people who need this content actually find it?

I led the design and implementation of analytics infrastructure across UNDRR's web ecosystem (24+ domains spanning Drupal sites, Java applications, and static microsites) to answer that. The challenge wasn't primarily technical. It was conceptual: what does success mean for content where impact happens outside your analytics?

What was the actual problem?#

No analytics benchmarks exist for organizations like UNDRR. The widely-cited "16% social traffic" figure comes from fundraising nonprofits running emotional campaigns. For a technical policy organization where audiences search for "Sendai Framework implementation guidance," that benchmark steers you wrong. I needed to figure out what actually applied, and write down what didn't.

The measurement model was broken in a different way. A 50% bounce rate on a terminology definition often means the user found their answer. The same rate on a landing page means something failed. Without classifying content by type, aggregate metrics obscure more than they reveal.

Then there's the volume problem. 10,000 visits from random browsers isn't worth more than 100 visits from government ministries using the content to shape national policy. Traditional analytics gives you geography and device types. It doesn't tell you whether the right people showed up.

Some of the most important impact never touches analytics at all. A researcher downloads a dataset and cites it in a paper six months later. A ministry official reads guidance and it shapes a national strategy. Neither event shows up as a conversion.

How did I approach this?#

I started with benchmarks — or rather, with finding out they didn't exist for our context. I synthesized data from M+R Benchmarks, RKD Group studies (2,000+ nonprofits), First Page Sage, and Similarweb, then worked out which findings actually applied. One thing that came up: only 8% of nonprofit websites pass Core Web Vitals on mobile. I documented confidence levels for each benchmark category and noted the gaps: no UN-system analytics data exists anywhere.

Content-type classification underpins everything else. I established metatag conventions (vf:page-type) that tag every page by type. The tracking script reads these on page load and sends them to GA4 as a custom dimension, so you can apply different success criteria to different content. Reference pages get different expectations than landing pages, which get different expectations than event pages.

For audience quality, I built an ASN lookup: a server-side endpoint converts IP addresses to network categories (government, academic, intergovernmental, NGO, commercial) and sends the category to GA4. Not the specific organization, just the type, which keeps it GDPR-friendly while still answering the real question: are the visitors we're getting the visitors we're trying to reach?

I also classified 200+ referrer domain patterns into 14 strategic buckets (UN System, Government, Academic, DRR Community, Traditional Media, AI Chatbots, and others), each carrying a weight reflecting how much that traffic matters to the mission. An "impact score" multiplies sessions by weight. 100 government visits (5×) ranks higher than 400 unclassified visits (0.5×). Raw session counts stop being the main signal.

Topic-level analysis came from taxonomy metatags (vf:page-terms) covering hazards, themes, SDGs, and Sendai Framework priorities. The backend aggregates by topic, so you can ask "which hazards drive the most search demand?" rather than "which pages were popular last month?" A lightweight "Was this page helpful?" widget sends clicks to GA4 with page container context; it's most useful for low-traffic content where engagement metrics are too thin to read.

The architecture follows a three-layer model. Content layer: Drupal, Java apps, and static microsites all emit the same metatag conventions. Tracking layer: one shared script, one GA4 property, per-domain data streams. Consumption layer: dashboard, browser extension, and Looker Studio, all reading the same source. Adding a new site means implementing metatags. The infrastructure doesn't change.

The single-property decision took some defending. Separate GA4 properties per site would have been simpler to manage, but would have fragmented the data. With one property and hostname filtering, the same query answers "how's PreventionWeb doing?" or "how's the whole ecosystem doing?" Cross-site user journeys become visible for the first time.

What can we now answer?#

58% of traffic comes from identifiable institutions: government, academic, UN system, research networks. That answers "are the right people finding policy guidance?" in a way raw page views can't.

Topic aggregation surfaces patterns that page-level data hides. Flood content dominates hazard interest; Early Warning leads on themes. That feeds content planning decisions, not just retrospective reporting.

A terminology page with 40% engagement isn't "underperforming" — it's what quick-reference content looks like. Content-type benchmarks mean the dashboard compares each page against the right expectations, not a generic industry average.

On direct feedback: terminology pages run 78% helpful, publications 65%. Pages that drop below threshold get flagged. Not a perfect signal, but a real one for content where traffic is too low for engagement rates to tell you much.

What did I learn?#

I built 18 dashboard screens before asking which ones stakeholders would actually use. I should have done the user research first. That sequence mistake cost real time.

We also set targets before documenting baselines. Now we're establishing them retroactively. The order should have been: observe, then set expectations.

Some impact just isn't measurable through analytics. Download clicks don't tell you whether anyone read the PDF. Policy influence doesn't generate a GA4 event. I documented these gaps explicitly; better to set that expectation early than have people treat the dashboard as a universal answer.

I underestimated the research. Deciding which benchmarks apply, which don't, and writing down the reasoning became as useful as the tracking implementation itself. Without it, you're measuring against whatever number was easiest to find. That number is usually wrong for your context.

Links and resources#

Measuring success beyond the page view: the philosophy behind this approach
How to measure impact when analytics lie: implementing benchmarks, audience detection, and content-type classification for your own stack
UNDRR analytics overlay and MCP bridge, the next chapter: putting this data where the work happens, and making it queryable by AI agents

Let AI worry about the code, you worry about the work

2026-04-20T00:00:00.000Z

Early in 2026 I was in a hotel room during a team retreat, trying to work through a problem with all the context from our planning conversations still circling in my head. I had been using ChatGPT for coding help, then Cursor with the AI in the IDE sidebar; both useful, both essentially "AI helps me code." I was the one writing; the model filled in the gaps. What I realized in that hotel room was that holding the context in my head and passing it to the machine one chat turn at a time was not enough. I needed to put it somewhere the agent could read directly.

So I stopped asking an AI to help me code and started managing a project. I opened a fresh git repository, dropped in a short PRD of what I wanted, technical documents on the architecture of the data it would consume, and a folder of the business context behind it. I pointed Claude Code at the repo, described a bit how to begin, and let it stand up a local server. From there I worked through it the way you work through any project: branch, change, diff, commit, revise. My attention moved from the line and the function up to the project. The implementation work, which had been mine, became the agent's.

What changed was not the language model; it was the level of abstraction I was operating at.

tl;dr

The productive pattern: a coding agent working on a real project, primed with your business context via skill files, local MCP servers, and data on disk.

The literacy that matters: reading diffs, driving git, editing configs, judging what the agent produced, not writing code from scratch.

The dividing line: "do you work on a real project with a coding agent?" Chat windows and app-builders do not clear the bar yet.

Another thing I started doing in that session: dictating instructions instead of typing them. Speaking is looser and more narrative; when I type, I try to be concise, and concision turns out to be the wrong register for this. LLMs read people well: a messy paragraph of what you actually mean beats a tight sentence that asks the model to infer the rest.

That change in productivity is not from writing more code, and it is not from prompting a chatbot. It is the fusion of the two: a coding agent acting on a real project, with me operating one level of abstraction up from the code itself. A chat thread rewards turn-by-turn completion and quietly fights "step back and tell me what we are actually trying to build"; a project folder does not.

If you have comfort with the vernacular of code (reading a diff, trusting a commit, knowing what a repo looks like, noticing which file an MCP server is reaching into and why), the leverage is real and it compounds quickly. You do not need to write the code yourself; the agent is writing most of it now. If you do not have that comfort, most of the efficiency gains happening right now will pass you by, because they live where code lives: in a project folder, behind a git remote, wired to a handful of MCP servers you need to trust.

What this looks like in practice#

At UNDRR, our Google Analytics is, like many places, not generic. Twenty-two hostnames funnel into a property, download events are derived from URL patterns rather than clicks, engagement is tagged by page region, and referrers are bucketed by strategic category. I asked Copilot CLI to encode that business context in a local MCP server, so that a coding agent could reach GA4 already knowing what our data means. (The full write-up is in the UNDRR analytics overlay and MCP bridge piece.)

I also keep a local copy of our Drupal content database running on the same virtual machine. When the analytics are ambiguous about what a given URL is, the agent can cross-reference the content itself (taxonomy, body text, publication date) and resolve the question without asking me.

With that setup I can ask:

Tell me about the last ten news items we published on tropical cyclones and how they performed compared to a year ago.

In months past that investigation was an incredibly tedious cross-tool query: pull a filtered content list from Drupal, map each URL to its analytics row, compute year-on-year deltas by custom event, assemble the results into a table. The agent does all of it in one pass, because each of the pieces is reachable and each is already annotated with the context the agent needs to use them.

There is no off-the-shelf commercial tool that answers that question, and there probably never will be. The thing that makes the query answerable is the specific marriage of our content structure, our analytics configuration, and a coding agent fluent in both. The off-the-shelf option would only ever be one of the three. This is what priming an agent with business context looks like when it actually pays off.

Comfort with code, not fluency in it#

The people who benefit most from this moment are those comfortable around code, not necessarily those who write a lot of it. The agent is writing most of the JavaScript or Python now. What you need is enough fluency to read what it produced, point it at the right place, trust or push back on a proposed change, and know what is happening on your own machine. In practice that looks like: comfort with a filesystem and a project structure, comfort with git (commits, branches, diffs, PRs), comfort with a terminal, comfort editing a config file, comfort registering an MCP server. You may never stand one up from scratch yourself; you can ask the agent to, read what it did, and decide whether to keep it.

The floor used to be "can you create this code?" and is now closer to "can you direct what the agent writes?" That is a lower bar than before, and still not zero. The people on the wrong side of it will miss most of the leverage in this cycle, not because they cannot code, but because they will not open the terminal.

How to get there#

If you are already comfortable with code, build one project-attached workflow for something you do every week. Often that is just a folder with the right context files (a PRD, a few technical docs, a sample of your data) and a coding agent pointed at it with access to the tools you already use. A skill file or a tiny MCP server can help, but they are one path, not the only one. The first version will underperform the manual process; the second will surprise you.

If you are not comfortable with these tools yet, the investment is not "learn to code"; it is vocabulary. GitHub's introductory docs walk through commits, branches, and pull requests in plain language; GitHub Skills turns the same material into guided exercises. A week of either gives you enough to read what an agent is doing on your behalf.

From there, install a coding agent (Claude Code, Cursor, or GitHub Copilot CLI), point it at a real repo of yours or one you forked, and let it work. Watch the diffs. Register one MCP server. Edit one config file. You do not need to produce code yourself for any of this to pay off; you need to be a credible reader, director, and reviewer of what the agent produces.

If you are already running coding agents against real projects (with or without custom skills or MCP servers), I would like to hear what you have automated and what surprised you. Drop me a note; I am collecting examples for a follow-up.

Putting GA4 where the work happens: an in-browser analytics overlay and its MCP bridge

2026-04-20T00:00:00.000Z

Context | Self-service | Agent-queryable

Web analytics are most useful alongside the context of the pages you are reasoning about. Using AI agents to help also suffers as humans usually manually hand off data.

To help myself and the team, I built a Chromium extension that puts GA4 metrics on UNDRR pages as an overlay, and extended it with a local MCP server so humans can have agents query the same data through the Chromium extension's same authenticated session.

The overlay and the MCP bridge are the same tool wearing two faces: same auth, same config file, same measurement model. That is why neither had to be rebuilt to serve the other. This is the story of both pieces and why they belong together.

These are the three web pages I am responsible for. Can you tell me what links people are not clicking on?

Those sorts of questions used to take an age to answer, but now we have quicker, better and more understandable answers.

What was the actual problem?#

Context switching to Looker Studio is where curiosity dies. For editors wondering whether the policy page they just updated is getting traction, a five-step dashboard drill is slow enough that most of the time they skip it. The question gets answered only when the quarterly report lands, which is the wrong feedback loop for editorial decisions. We spent more time training editors on the tool than understanding the data.

UNDRR's analytics model is not generic. Twenty-two hostnames feed one GA4 property, downloads derive from URL patterns containing /media/, engagement is tagged by page region (main, header, footer, feedback widget), and referrers are classified into eighteen strategic buckets before query time. Off-the-shelf analytics tools either ignore that model or flatten it.

How did I approach this?#

Overlay first, where the work happens. The extension is a Manifest V3 Chromium extension. It authenticates through the Chrome Identity API, so there are no extra credentials. On any UNDRR page it can surface views, sessions, engagement rate, average duration, and a year-over-year comparison with an interactive daily chart. Tracked links and downloads get color-coded badges on the page itself; regions get rollups so editors can see which part of a page is actually doing the work.

Bridge second, on an auth boundary that already existed. The MCP server runs on a localhost port and talks to an offscreen document inside the extension over a persistent WebSocket. That offscreen document owns the OAuth session, so the MCP server never sees or stores a token. From the agent's side, fourteen tools are exposed: tactical ones (query_top_content, query_downloads, query_traffic_sources, query_geographic_reach, query_region_events), strategic composites (domain_overview, annual_report_extract), and a raw GA4 escape hatch (run_raw_ga4_query) for questions the composites do not anticipate.

One source of truth, shared three ways. domains.json holds the twenty-two hostnames, their measurement IDs, and the referrer bucket classifiers. The extension's content script, its popup, and the MCP server all read the same file, so there is no config drift between what editors see in the overlay and what an agent sees through MCP.

What were the outcomes?#

Context at the point of editing. Editors can now see how a page is performing while they are editing it. The question "is this working?" has a three-second answer instead of a five-step Looker Studio drill; editorial decisions close the loop on the same day rather than the next quarter.

Agent-speed analysis. "Extract the annual report for 2025" is a single agent turn instead of roughly a forty-click dashboard walk. Parallel GA4 query batching inside annual_report_extract roughly halves the wall-clock time on multi-section reports, which matters when a report spans a dozen sections.

One credential, not two. The agent reuses the overlay's OAuth session, so nobody is maintaining a second service account or rotating a separate key. For a small team inside a UN organisation, that is the difference between a tool that gets adopted and one that quietly stops being used.

Why did this work?#

A tailored solution made sense because the measurement model is non-generic. A general-purpose analytics MCP would expose GA4 as GA4. What editors and analysts actually need is GA4 shaped like UNDRR's referrer buckets, regions, and content types. Keeping the domain logic in domains.json rather than in prompts means every agent gets the same context for free.

The MCP was not a rewrite. It was a thin wrapper on an auth boundary that already existed. The extension already had an OAuth session, an offscreen document, and a query layer; MCP just made them addressable from outside the browser. Most of the hard decisions were security decisions: single-property lock, sender validation, passive failure modes.

The one thing that nearly broke it. A single bad Zod schema (valid in v3, rejected in v4) made tools/list throw at registration, and that error is global: all fourteen tools disappeared from the agent at once. A stdio smoke test calling tools/list as the first build step now catches this class of failure; without it, the MCP server would have shipped advertising capabilities it could not deliver.

What's next, and why this matters beyond UNDRR#

Self-service analytics inside the page is a familiar idea. Agent-queryable analytics that reuses an existing auth session is newer. This extension is one instance of the pattern I described in Let AI worry about the code, you worry about the work: a coding agent on a real project, primed with your business context. The MCP server is the specific shape that worked here; the shape that works for you might be simpler.

How to write one skill for both Claude Code and GitHub Copilot CLI

2026-04-08T00:00:00.000Z

Both Claude Code and GitHub Copilot CLI support skills (instruction files that load into the agent's context when you need them). The two tools share the same core file formats, so a single set of files can serve both. This guide covers how that works, the divergences, and the gotchas.

tl;dr

Write skills as SKILL.md files with name and description frontmatter; both tools require exactly this.

The description field is the auto-detection trigger. Write it as a trigger condition: "Use when the user asks to…"

Omit the skills field from plugin.json entirely: Claude Code will reject the file if it's present.

Copilot CLI supports agents, hooks, and MCP server config; Claude Code does not yet. These are safe to add for Copilot users without affecting Claude Code.

If you just want a single skill without a plugin wrapper, you can drop the folder into .github/skills/, .claude/skills/, or .agents/skills/ (project) or the equivalent under ~/ (personal) and Copilot CLI will find it without any manifest.

The specifics below reflect the state of things as of April 2026. The canonical references at the bottom are the authoritative source — if anything here conflicts with official docs, trust them, though even those can lag behind actual behavior.

Two ways to distribute skills#

Before getting into file structure, it helps to understand the two distribution models, because they look different even though the underlying SKILL.md format is the same.

Standalone skills are just a folder with a SKILL.md inside, dropped into a location the tool already watches. No manifest, no plugin wrapper. For Copilot CLI, the watched locations are:

.github/skills/, .claude/skills/, or .agents/skills/ inside the current repository (project skills)
~/.copilot/skills/, ~/.claude/skills/, or ~/.agents/skills/ in your home directory (personal skills)

This is the lightest-weight approach and the one GitHub's own docs emphasize. It works well when you have one or two skills and don't need to bundle them for distribution.

Plugin-bundled skills wrap one or more skills inside a structured plugin directory. This is the model you want when you're packaging skills for a team or publishing them for others to install. Both tools discover skills from the skills/ subdirectory inside the plugin root automatically.

The file structure both tools understand#

A plugin that works in both Claude Code and Copilot CLI looks like this:

my-plugin/
├── .claude-plugin/
│   ├── plugin.json
│   └── marketplace.json    # optional, for marketplace listing
├── skills/
│   ├── my-first-skill/
│   │   ├── SKILL.md
│   │   └── supplementary.md  # optional; both tools inject these into context
│   └── my-second-skill/
│       └── SKILL.md
└── CLAUDE.md               # both tools read this; write it for both audiences

The .claude-plugin/plugin.json path is Claude Code's default manifest location, and Copilot CLI also searches there, so if your manifest is already at .claude-plugin/plugin.json, no move is needed. Note that Copilot CLI checks this path last (after .plugin/plugin.json, plugin.json, and .github/plugin/plugin.json), so it's the right choice when you want Claude Code's default to work without restructuring, not for a Copilot-primary plugin.

The `plugin.json` gotcha#

This one will burn you. Do not add a skills field to plugin.json:

{
  "name": "my-plugin",
  "description": "What this plugin does",
  "version": "1.0.0"
}

Why: Copilot CLI defaults to the skills/ directory automatically when the field is absent. Claude Code, on the other hand, rejects plugin.json with a validation error if a skills field is present. Omit it and both tools work; add it and Claude Code breaks.

Writing `SKILL.md` frontmatter#

Both tools require name and description. The version field is Claude Code-specific but harmless to leave in:

---
name: my-skill           # required by both; lowercase, hyphens only
description: >           # required by both -- this is the auto-detection trigger
  Use when the user asks to convert SVG files to PNG.
version: 1.0.0           # Claude Code only; Copilot CLI ignores it safely
allowed-tools:           # optional; tool names are platform-specific
  - Read                 # Claude Code name; Copilot CLI equivalents differ (e.g. read_file, bash)
  - Edit
---

The description field is everything#

Both tools use the description to decide whether to load the skill at all: the agent scans the list of installed skills, finds any whose description matches the current request, and injects those into context. The instructions in the SKILL.md body only matter after the skill loads.

Write it as a trigger condition, not a label. Compare these two:

Weak	Strong
`"Code review skill"`	`"Use when the user asks to review, audit, or check code for issues"`
`"Commit messages"`	`"Use when the user asks to write, generate, or improve a git commit message"`

Vague descriptions mean the skill won't auto-load when you need it. Narrow descriptions miss variations. Cover the vocabulary someone might actually use when asking for the task.

A note on `allowed-tools`#

The allowed-tools field limits which tools the agent can invoke while the skill is active. This matters especially if you're distributing skills publicly: a shell or bash pre-approval in a skill from an untrusted source can allow it to run arbitrary commands without prompting you. GitHub's docs are explicit about this:

Only pre-approve the shell or bash tools if you have reviewed this skill and any referenced scripts, and you fully trust their source.

When in doubt, omit shell and bash from allowed-tools. The agent will still prompt for confirmation before running terminal commands.

Features specific to GitHub Copilot CLI#

These features are Copilot CLI-specific. They have no Claude Code equivalent, so you can safely add them for Copilot users without affecting Claude Code behavior:

Feature	How it works
Custom agents	`<name>.agent.md` files in an `agents/` directory; the filename prefix becomes the agent ID (e.g. `reviewer.agent.md`)
Hooks	`hooks.json`; event handlers that fire on lifecycle events like `PostToolUse` or `SessionStart`
MCP server config	`.mcp.json`; connects the plugin to external APIs or databases via MCP

What `CLAUDE.md` does in each context#

Both tools read CLAUDE.md, but with slightly different scope. Claude Code treats it as plugin-level instructions loaded alongside the skill. Copilot CLI treats it as project-level custom instructions, the equivalent of what you'd put in a .github/copilot-instructions.md. Write content that makes sense in both contexts: conventions, constraints, what the tool should and shouldn't do. Avoid content that's only meaningful in one tool.

Testing the install#

For Copilot CLI, install from a local directory and confirm in an interactive session:

# Install (re-run after each edit to refresh the cache)
copilot plugin install /path/to/your-plugin

# Confirm it loaded
copilot plugin list

# In an interactive session
/skills list

For Claude Code, pass --plugin-dir /path/to/your-plugin when launching, or install permanently with claude plugins install /path/to/your-plugin.

Key things to keep in sync#

If you change either of these, test both tools:

description in SKILL.md: The auto-detection trigger for both. If you update the skill's purpose, update the description to match or it won't load.
name in SKILL.md: Must be unique across installed plugins. Renaming is breaking: users of the old name will lose auto-detection silently.
name in plugin.json: Changing this is a breaking rename for anyone who has the plugin installed.

Using this as LLM context#

This post lives on GitHub as a Nunjucks file, syntactically close enough to Markdown that an LLM reads it fine. If you want an LLM to work from this guidance directly, here's a ready-to-paste prompt pointing at the raw source:

Please fetch https://raw.githubusercontent.com/khawkins98/allaboutken-11ty/main/src/site/posts/20260408-mini-guide-claude-copilot-skills.njk and use its guidance when helping me author skills compatible with both Claude Code and GitHub Copilot CLI.

I'll update this post as the tools evolve.

Canonical references

These are the authoritative sources. This post documents my own experience and cross-tool learnings; for the full specification, read these:

GitHub Copilot CLI

Creating skills for GitHub Copilot CLI: official how-to, covers standalone skills, scripts, and allowed-tools
Creating a plugin for GitHub Copilot CLI: plugin manifest, distribution, and install
GitHub Copilot CLI plugin reference: complete technical specification

Claude Code

Claude Code plugins overview: getting started with the plugin system
Claude Code plugins reference: complete specification for skills, agents, hooks, MCP, and LSP components
Claude Code plugin marketplaces: distribution and discovery

Community guides worth reading

How to Build Your Own Claude Code Skill: freeCodeCamp walkthrough, excellent on the description field and skill design heuristics
Claude Code Skills vs MCP vs Plugins: Complete Guide 2026: good overview of when to use each extensibility type

The overlap between the two ecosystems is real and growing. Know the three divergences, omit the skills field from plugin.json, and a single set of files will serve you in both tools. If you run into a case this guide doesn't cover, I'd like to hear about it.

If this sparked broader questions about how AI-assisted development actually works, my post on the four gears of AI-assisted development talks through the layers above and below this one — and why context engineering was always the job has more on why the description field matters so much.

The right answer has to be woven

2026-04-07T00:00:00.000Z

At a previous organisation, we syndicated content from Drupal across multiple downstream platforms through API feeds. Over the years, a recurring problem: a developer misspells a field name in the CMS, say summray instead of summary. A downstream JavaScript platform consumes that API and builds around the typo. Months later, someone fixes the typo in Drupal. Now the downstream platform breaks, because it was built against the misspelled field. So we add a translation layer to preserve the old typo alongside the fix. This happens again. And again. Each time, the downstream system absorbs more of the upstream system's historical mistakes, and the mapping between them gets more fragile.

The team solved this problem for years with what I variously called a "translation protocol" or a "data dictionary": ad hoc scripts and field-mapping spreadsheets, reinvented slightly differently each time. It wasn't until I started reading Eric Evans' Domain-Driven Design that I discovered the pattern had a name: the anticorruption layer. It's a deliberate translation boundary between two systems that prevents one system's model from leaking into another's. Instead of each downstream consumer adapting to whatever the upstream happens to expose (typos and all), you build an explicit layer that translates between the external model and your clean internal model. The upstream can change; your internal model stays coherent.

Knowing the pattern wouldn't have just saved time; it would have changed how I structured the integration from the start. An anticorruption layer is a design decision you make at the boundary, not a patch you apply after the damage compounds. I'd been solving a named problem with duct tape because the formalised solution lived in a tradition I'd never read.

The loose threads don't need to stay so.

tl;dr

Several traditions (among them software engineering's DDD, content strategy, and AI context engineering) each solved the problem of shared understanding across system boundaries

They developed in parallel partly because they operated on different substrates: human-readable meaning vs. machine-executable contracts

LLMs are dissolving that boundary; natural language is now a functional input to software

Specific patterns now transfer concretely, and the cross-pollination has barely started

Several traditions, one problem#

I wrote recently about how context was always the job. The more I've sat with that idea, the more I've noticed the same boundary-crossing problems showing up across fields, with solutions developed in parallel.

Software engineering. Evans published DDD in 2003, arguing that the hard problem of software is shared understanding of the domain, not the code. His prescription: build a "ubiquitous language" that domain experts and developers both use, draw explicit boundaries ("bounded contexts") around different models, and build translation layers where they meet. The primary artifact is the shared model, not the running system.

Content strategy. Daniel Jacobson at NPR built COPE (Create Once, Publish Everywhere) around content modelled as structured data with standardised interfaces. Karen McGrane's Content Strategy for Mobile sharpened the point: content trapped in a specific visual format can't travel across channels. You have to break it into meaningful chunks named by what they are, not how they look. "News item" survives a redesign; "featured card with sidebar layout" doesn't.

AI context engineering. An LLM has general knowledge of the universe but not your project's constraints, your team's vocabulary, or why the module is shaped the way it is. The bottleneck isn't the model; it's the context you provide. Practitioners are building agent instruction files (CLAUDE.md, AGENTS.md, .cursorrules), project briefs, scoped rules, and structured documentation for AI consumption. The discipline is new. The problem it's solving is not.

These are the traditions I can see from where I sit. My career moved through journalism, content strategy, information architecture, design systems, and software engineering, and I now spend most of my time on AI integration. This is shaped by my path, not a natural taxonomy. Knowledge management, library science, and information science all have deep roots here too. And these traditions aren't fully independent: content strategy grew out of information architecture, AI context engineering is practiced almost entirely by software engineers, DDD drew on earlier modelling traditions. They share intellectual ancestry even where they developed solutions separately.

At a high enough altitude, "decompose, name, and build explicit translation at boundaries" describes most of good engineering. The interesting question isn't whether the general principle holds. It's whether these traditions have produced specific patterns worth transferring, and whether there's a reason that transfer is newly practical.

Why the boundary is dissolving#

Before LLMs, these traditions operated on fundamentally different substrates. Content strategy dealt with human-readable meaning: editorial voice, reader comprehension, how a headline works in a news feed. Software engineering dealt with machine-executable contracts: type systems, APIs, interface boundaries. The abstract patterns rhymed, but the gap between "write so a human editor understands the content model" and "write so a compiler enforces the interface contract" was wide enough that cross-pollination rarely paid off in practice. You could admire the parallels. You couldn't easily import the other tradition's tools.

LLMs are collapsing that gap. An agent instruction file like CLAUDE.md is simultaneously human documentation and machine instruction. An editorial style guide that used to exist purely for human writers now directly shapes how an AI agent generates content. A content schema that used to govern what a CMS would accept now structures what context an agent receives. Natural language has become a functional input to software systems, and that changes which traditions have something to offer each other.

I don't want to overstate the collapse. These instruction files are natural language, but a very specific kind: structured, imperative, rule-based. Closer to a config file written in English than to a conversation. Content strategy's insights about editorial governance transfer well to this new substrate; its insights about reader comprehension transfer less cleanly, because the "reader" (an LLM) has very different failure modes than a human. The boundary is thinning, not gone.

But even a partial collapse changes what's practical. And AI has changed the cost of iteration enough to make context a designable variable. Before AI, context failures were slow and expensive to learn from: a misaligned contractor takes weeks to deliver the wrong thing; a content schema mismatch causes a slow bleed of broken syndication. You're not going to tear down a two-week pull request and rebuild it with a different briefing just to test whether the briefing was the problem.

With an LLM, you do exactly that. You give the agent one framing, watch it fail, adjust the context, and try again — and the cost of that cycle is minutes, not days. Because the iteration is cheap, you start to notice which context changes produce better outputs, which is how you discover that the problem was structural (missing bounded context, ambiguous vocabulary, no schema) rather than a one-off misunderstanding. Content strategists have always wanted to test whether restructuring content improves outcomes, but the feedback loop was too slow. Now it isn't.

Patterns that now transfer#

The anticorruption layer is one such transfer, from DDD to content architecture. Knowing the named pattern wouldn't have just saved me time; it would have changed how I structured the integration from the start. That's the cost of institutional silos: practitioners solve named problems with duct tape because the formalised solution lives in a tradition they've never read. Many IA practitioners have read Evans; many DDD practitioners use content modelling techniques without calling them that. But the conferences, journals, and canonical texts don't overlap. A small but growing group is connecting DDD to AI agent design, but it hasn't reached the mainstream AI tooling ecosystem, and almost none of these voices are looking further afield to content strategy.

There's a harder version of this objection: maybe content architects already build translation layers and just call them "field mapping" or "API adapters." If the vocabulary difference is the main barrier, that's a weaker claim than if the structural thinking is what's missing. The anticorruption layer example shows it's not just vocabulary: knowing the named pattern would have changed when and how I built the translation, not just what I called it. But not every parallel will cash out that concretely.

Here's a transfer running the other direction: from content strategy to AI context engineering.

Content strategists learned years ago that you define content types with required and optional fields, relationships to other types, and governance rules about who can create and edit them. This is the content schema: the structural backbone of any CMS at scale. A news article has a required headline, required body, optional teaser, required topic taxonomy, and a relationship to an author profile. These aren't suggestions; they're enforced by the CMS.

When I started structuring context for AI agents, I recognised the same problem. An agent working on a blog post in this site's codebase needs specific context: the editorial style guide, the image path conventions (which are non-obvious; the build rewrites them), the frontmatter schema, the CSS scoping rules. Some of that context is required for every task; some is optional enrichment. The relationships between context sources matter: the style guide references the frontmatter spec, which references the image conventions.

A content strategist would immediately think in terms of a content schema: define the required context per task type, make the relationships explicit, assign governance for who maintains each source. Most AI context engineering doesn't think this way yet. Agent instruction files tend to grow organically: someone hits a problem, adds a line, moves on. There's no schema, no required-vs-optional distinction, no governance. It's fair to ask whether this is a cross-pollination gap or just a maturity issue; these conventions are roughly a year old, and this is what every structured documentation system looks like in year one. Both are probably true. But content strategists have fifteen years of lessons about how to mature these structures, and now that these instruction files are natural language doing a machine's job, those lessons land in a way they couldn't when the substrates were different.

From where I sit#

I'm not arguing these traditions should merge. I'm noting that the barrier which kept them apart, the gap between human-readable meaning and machine-executable contracts, is narrower than it's ever been. Specific patterns now transfer concretely.

If you're working on context engineering for AI and you haven't read Evans on ubiquitous language, there are twenty years of lessons on formalising shared understanding that you're rediscovering from scratch. If you're doing DDD and haven't looked at how content strategists model structured content across platforms, you're missing a parallel tradition that solved the "how does this travel across boundaries" problem for editorial organisations.

The stable artifacts matter: a well-governed schema, a maintained instruction file, a shared vocabulary. But they only stay useful if someone is actively maintaining them. That's the common thread: Evans' domain models require ongoing collaboration with domain experts, McGrane's content schemas need governance to stay current, agent instruction files decay the moment the codebase moves on without them. None of these traditions own that insight. All of them arrived at it. The weaving has started, but it hasn't reached mainstream practice in any of these fields yet.

Why context engineering was always the job (Mar 2026): the personal evolution version of this argument
Content architecture: the delivery problem (Mar 2026): content structure as shared infrastructure
Developers are becoming context technical writers for AI (Sep 2025): the rise of context curation
Context engineering beats prompt tricks for AI agents (Oct 2025): framing the input is the real skill

Cross-tradition reading#

Duranti & Goodwin, Rethinking Context: Language as an Interactive Phenomenon (1992). The academic foundation: context is produced through interaction, not inherited as background.
Eric Evans, Domain-Driven Design (2003). Ubiquitous language and bounded contexts as software engineering's answer to the shared understanding problem.
Karen McGrane, Content Strategy for Mobile (2012). Blobs vs. chunks, and why content must be structured by meaning to travel across channels.
Rod Johnson, Context Engineering Needs Domain Understanding (2025). The strongest bridge between DDD and AI context engineering.
Russ Miles, Domain Driven Agent Design (2025). What happens when agents cross bounded contexts without translation layers.
Paul Dourish, What We Talk About When We Talk About Context (2004). The closest existing bridge between linguistic anthropology and computing; argues that context is interactional, not representational.
Lucy Suchman, Plans and Situated Actions (1987; 2nd ed. 2007). Suchman showed that people don't follow plans the way AI planners assumed — they improvise based on situated context. The modern agent community's discovery that rigid task decomposition fails without runtime context is the same finding.

All about Ken Hawkins

CADI: a prescriptive path for slop-free AI in content work

The problem: every prompt starts from zero#

Where you probably are: supervised co-writing#

Before you start: five things to check#

Pick your tool#

The CADI framework: Collect → Analyze → Document → Iterate#

C — Collect: Extract your best examples#

A — Analyze: Find quantitative patterns#

D — Document: Turn patterns into working instructions#

I — Iterate: Build confidence over time#

CADI in practice: how it played out at UNDRR#

Using CADI in the writing workflow#

Trust but verify: the publication gate#

Where this breaks down#

What you maintain alongside the loop#

After your first cycle, go deeper#

References#

A data font, from the inside out

A data font and font for data#

Accessibility gap#

I want an excuse to use it#

Building a virtual garage for hobby projects

tl;dr#

What I didn't want to do#

How the proxy works#

The trailing-slash problem#

Not burning the old address#

Don't forget: CORS for shared JS assets#

The full configuration#

Adding another project#

Eye-tracking heatmaps in your browser, no lab needed

The analysis report#

Trained on real UI gaze data, not natural scenes#

Limitations: what predicted attention can't tell you#

How it runs entirely in your browser#

Training on consumer hardware: a personal note#

Try Foveacast on your own UI#

Stop converting SVG text to outlines

The problem with outlines#

How it works#

Why browser-only matters#

Prior art#

The subsetting part#

What it handles#

Where it gets bumpy#

Try it#

Designing analytics infrastructure that measures audience quality, not just traffic

What was the actual problem?#

How did I approach this?#

What can we now answer?#

What did I learn?#

Links and resources#

Let AI worry about the code, you worry about the work

What this looks like in practice#

Comfort with code, not fluency in it#

How to get there#

Putting GA4 where the work happens: an in-browser analytics overlay and its MCP bridge

What was the actual problem?#

How did I approach this?#

What were the outcomes?#

Why did this work?#

What's next, and why this matters beyond UNDRR#

How to write one skill for both Claude Code and GitHub Copilot CLI

Two ways to distribute skills#

The file structure both tools understand#

The plugin.json gotcha#

Writing SKILL.md frontmatter#

The description field is everything#

A note on allowed-tools#

Features specific to GitHub Copilot CLI#

What CLAUDE.md does in each context#

Testing the install#

Key things to keep in sync#

Using this as LLM context#

Canonical references

The right answer has to be woven

Several traditions, one problem#

Why the boundary is dissolving#

Patterns that now transfer#

The `plugin.json` gotcha#

Writing `SKILL.md` frontmatter#

A note on `allowed-tools`#

What `CLAUDE.md` does in each context#