Six years ago, Stripe’s developer productivity team wrote comprehensive docs, blessed paths for common tasks, and robust CI/CD. When AI agents arrived, they followed the same documentation that human engineers use. No parallel infrastructure. No special prompts.

Steve Kaliski, the engineer behind Stripe’s Minions system, explains this in Lenny Rachitsky’s “How I AI” series like it’s the most boring observation in the world. Of course the agents use the same docs. What else would they use?

That “of course” is doing a lot of work. Because most organizations treat agent infrastructure as a separate problem from developer experience. Separate teams. Separate budgets. Separate docs. Stripe’s insight is that the separation is the problem.

The new hire who never leaves onboarding

The reason Stripe’s docs work for agents isn’t that they’re “good.” Plenty of companies have good docs. The reason is specific: Stripe’s docs were written for someone who knows nothing.

Every blessed path assumes the reader just joined. Here’s the repo. Here’s how you add an API field. Here’s what CI checks before your code ships. The docs don’t assume you were in the room when the architecture was decided. They don’t assume you know which Slack channel has the context. They externalize what most teams leave implicit.

AI agents are the extreme version of that new hire. Zero institutional memory. Zero hallway conversations. Zero sense of “we tried that in Q3 and it didn’t work.” An agent reads what you wrote down and nothing else.

Stripe’s docs passed the agent test because they’d already been passing the new-hire test for years. The investment that mattered most was made before agents existed in their workflow.

One detail from the same conversation that deserves its own paragraph. Every one of those 1,300 PRs still requires human review. The bottleneck didn’t vanish. It moved. Code production is cheap now. Judgment is the constraint. Good DX didn’t eliminate expensive work; it relocated it.

Where intent disappears

I build MCP servers. Each one exposes tools that AI agents discover and call. The agent never sees the Go code, the handler logic, or the tests. It sees a name, a description, and an input schema. That’s the entire relationship.

Here’s a tool description from my Miro MCP server:

Create a connector line between two items. Styles: straight, elbowed (default), curved. Caps: none, arrow, stealth, diamond, filled_diamond, oval, filled_oval, triangle, filled_triangle.

It used to be better. The original version had USE WHEN clauses, parameter guidance, the works. Then I trimmed it for token efficiency. Shorter descriptions, smaller payloads, faster tool loading. A reasonable trade-off, except I never measured what I lost. The knowledge that made the tool selectable disappeared into a git diff, and I didn’t notice because I still had it in my head.

When Claude encounters this description, it has a decision to make: connector or shape? The description doesn’t help. Both “draw a line” and “connect two boxes” are reasonable user requests. Both could plausibly map to either tool. So the agent guesses.

On my test board, there are three shapes in a row: “Start Test”, “Pass?”, and “Success.” I asked Claude to draw a line from Start Test to Success. The connector description says nothing about when to use it. The shape description, which already had USE WHEN clauses, explicitly mentioned “draw a...” requests. Claude picked miro_create_shape and placed a long, thin rectangle between the two boxes. Visually, it looked like a line. In the data model, it was a rectangle. Not a connector. Not part of the diagram’s logical structure. The board looked right. The data was wrong.

I blamed the model. The blame was misplaced. The description was technically correct and operationally useless.

Murphy Trueman, writing about design systems, identified the same pattern in a different domain. Designers create buttons in Figma and see buttons. The design system sees structured data. The designer’s intent is embedded in layers of implicit structure that only become visible when someone who wasn’t in the room tries to consume them.

MCP tools have the same hidden architecture. The server author sees a function call. The agent sees a data object: name as semantic label, description as intent signal, input schema as parameter contract, required-versus-optional as constraint boundary. Yes, the JSON schema contributes too; it constrains what’s valid. But the description determines whether the agent shows up at all. Selection happens before validation. The code behind the description might as well not exist.

The gap between what you know your tool does and what the description communicates to a consumer with zero context; that’s where agent failures live. I call it “intent doesn’t parse.” Your intent is real. It just didn’t survive the journey from your head to the description string.

Trueman has a D&D analogy for this: a Dungeon Master who shuts down player actions because “it’s not in the book” doesn’t just fail that session. Players learn to stop attempting anything creative. The documented world shrinks to the documented edges. Vague tool descriptions train agents the same way. Over a session, the agent learns which tools produce predictable results and avoids the rest. Ambiguity doesn’t just cause errors. It narrows the agent’s world.

What the agent reads when it gets it right

A different tool on the same server:

Create a shape on a Miro board.

USE WHEN: User says “add a rectangle”, “draw a circle”, “create a box for X”

SHAPE TYPES:

• Basic: rectangle, round_rectangle, circle, triangle, rhombus

• Flow: parallelogram, trapezoid, pentagon, hexagon, star

• Flowchart: flow_chart_predefined_process, wedge_round_rectangle_callout

PARAMETERS:

• board_id: Required. Get from list_boards or find_board

• shape: Shape type (required, default: rectangle)

• content: Text inside shape

• color: Fill color (e.g., “#FF5733” or color name)

• x, y: Position (default: 0, 0)

• width, height: Size (default: 200, 200)

RETURNS: Item ID, shape type, position, size, and view link.

RELATED: For flowchart-specific stencil shapes (experimental API), use miro_create_flowchart_shape instead.

These two tools sit in the same file, definitions.go, thirty-eight lines apart. The connector used to look like this too. I trimmed it for token efficiency and improved other tools in the same month without going back to restore it. Two weeks between commits. The gap between “I optimized this” and “I should fix that” is where selection debt accumulates.

The difference isn’t length. It’s explicitness. USE WHEN tells the agent which user utterances should route here. SHAPE TYPES tells it what’s legal. PARAMETERS tells it what to bring and where to find prerequisites. RELATED tells it where to go instead.

The shape description passes the new-hire test. Someone who has never seen the codebase can read it and act correctly. The connector description doesn’t. Both are mine.

The realization that changed how I write tool descriptions: I’m not documenting a function. I’m writing onboarding material for a colleague who will never ask a follow-up question. Every implicit assumption is a place where that colleague will guess. And guessing compounds. When you have dozens of tools across several servers, each ambiguous description makes every other tool slightly harder to choose correctly. That compound tax is what I’ve started calling selection debt: the accumulated cost of descriptions that are accurate but opaque.

Write for the reader who can’t ask

Stripe didn’t set out to build agent infrastructure. They set out to make their platform legible to someone who just walked in the door.

I didn’t set out to build agent-friendly tool descriptions. I set out to stop Claude from picking the wrong tool.

Same mechanism. Same fix. Write for the reader who has no context, and you accidentally write for every future consumer, including the ones that don’t exist yet.

Good DX = Good Agent DX. Not because agents are special. Because agents are the most demanding version of the reader you should have been writing for all along.

Pick one tool description. Read it as someone who has never seen your codebase, has infinite patience, and cannot ask a clarifying question. Does the intent survive? That’s your health check.

Every company has an onboarding doc. A wiki page or a shared Google Doc titled “Getting Started” or “New Developer Guide.” It was accurate when someone wrote it. That was eleven months ago. Three APIs have changed since then. The testing workflow section references a CI pipeline that was replaced in Q3. Nobody updated it because updating docs isn’t anyone’s KPI.

You know how this plays out. The new hire reads the doc, follows the steps, hits an error on step 4, asks a colleague, gets the current answer verbally, moves on. The doc stays wrong. The next new hire hits the same wall.

Onboarding docs don’t onboard people. People onboard people. The doc is a prop, a thing you hand someone so the handoff feels structured. The actual knowledge transfer happens over Slack, in pairing sessions, through the particular inflection a senior engineer uses when she says “oh, we don’t do it that way anymore.”

The inversion

When your AI coding assistant reads a CLAUDE.md file, it doesn’t skim and forget. It follows the instructions. Every session, without variance or fatigue. The instruction is the enforcement.

Most people see this and think: great, I can document my project conventions and Claude will follow them. True, but it misses the more interesting thing happening underneath.

You’re not onboarding the person. You’re onboarding the AI. The human benefits because they work through the AI. The new hire who clones a repo with a well-maintained CLAUDE.md doesn’t need to find the wiki page or extract tribal knowledge from a colleague. They type a natural language request and the AI already knows the conventions, the correct endpoints, the deployment sequence. The onboarding happened before the human arrived.

Brian Leven, a designer at Notion, built exactly this for his team. A committed CLAUDE.md with team-wide conventions, plus a gitignored claude.local.md for personal preferences. New designers clone the repo and their AI assistant knows the coding standards, component naming, deploy workflow from minute one.

His principle: “Anytime the AI asks you to do something, try your best to see if you could teach the AI to answer that question for itself.”

Every question a teammate asks becomes a slash command. Every recurring mistake becomes a rule. The onboarding surface shrinks with each encoding, like a coastline retreating under steady erosion, except what’s left behind is bedrock.

The expert system nobody planned

Scale this up and something unexpected happens. I now run 50 skills, 20 rule files, and 7 specialized agents in Claude Code (up from 38 skills when I first wrote about the system). Together they form something that behaves like an expert system, except it’s markdown files in a git repo. Brand routing by hostname and project path. Procurement response drafting from wiki and source code. Code review with hard gates the reviewer agent cannot skip.

The expert systems of the 1980s died because nobody could afford a full-time knowledge engineer to keep the rules current. These rules live in the same repo as the code. When the code changes, the developer who changed it updates the rules in the same commit. The maintenance problem that killed an entire field of computer science, solved by proximity.

The rot problem

Skills rot too. I wrote about this: after about thirty skills, quality drifted. Contradictory instructions, vague trigger phrases, empty sections. An executable onboarding system with contradictory instructions is worse than a stale wiki page. The wiki page is obviously wrong. The contradictory skill looks like it’s working and silently does the wrong thing. Quiet failure is always more dangerous than loud failure.

So I built SkillCheck. The free tier validates skills against the agentskills.io spec: structure, naming, semantic consistency. The pro tier adds anti-slop detection, security scanning, token budget analysis, and enterprise readiness checks. A linter for your AI’s curriculum.

Start with one rule

You don’t need fifty skills. You need one rule that solves a real problem.

Find the thing your team explains verbally to every new person. “Oh, we don’t use that endpoint anymore.” “Make sure you run linting before pushing.” “The staging URL changed last month.”

Write it as a CLAUDE.md instruction. Watch it enforce itself. Notice when the next person doesn’t need to ask. Then write the next one. Validate it.

Somewhere around skill thirty, you stop maintaining documentation and start curating an institution’s memory. The curious part is that the institution doesn’t notice. It just stops losing knowledge.

Brian Leven’s prototype playground for Notion’s design team was discussed on the How I AI podcast with Claire Vo. SkillCheck Free is open source. SkillCheck Pro adds anti-slop, security, and enterprise checks.

Subscribe now

I’ve built lots of tools across several MCP servers. The removals taught me more.

The Paradox

Here’s a number that shouldn’t exist: my Miro MCP server has 88 tools. It didn’t start that way.

The growth wasn’t planned. Each time Claude got smarter, it attempted more ambitious workflows, and more ambitious workflows hit more edges: authentication flows, proprietary JSON schemas, approval chains that require three calls in a specific order, agents that could only read data suddenly trying to write it, agents that handled one API trying to orchestrate five, each expansion creating new integration points that needed new bridges. Every edge needed a new tool.

But here’s what nobody in the MCP ecosystem talks about: of those 88 tools, some are excellent. Some are adequate. And some could disappear without anyone noticing.

The Invisible Problem: Selection Debt

Doug Turnbull, who led Search at Reddit and Shopify, replaced a sophisticated retrieval pipeline with BM25 and a reasoning loop. On public benchmarks (Wayfair WANDS, Amazon ESCI), search relevance went up 15-30% NDCG.

BM25 is a keyword matching algorithm from 1994. It counts terms. It doesn’t understand semantics. And it beat the sophisticated pipeline.

The punchline, from Hugo Bowne-Anderson’s Vanishing Gradients newsletter: the dumb tool won because the agent could understand it. When BM25 returns bad results, the agent knows exactly what happened. It searched for “bistro table” and got patio furniture. Keywords matched literally, so the agent can reformulate. When a vector search returns bad results, the agent has no idea why. The retrieval logic lives in embedding space. The agent can’t debug what it can’t observe.

This principle doesn’t stop at retrieval. It lives in your MCP tool descriptions.

Most MCP tool descriptions tell the LLM what a tool does. Accurate, and completely unhelpful. Here’s one from my own server:

The LLM knows the capability. It has no idea when to pick this over miro_create_shape when someone says “draw a line between these.” It can’t tell what happens when an item ID doesn’t exist on the board. The description is correct. It’s also opaque.

Selection debt accumulates when tool descriptions are technically correct but operationally ambiguous, causing LLMs to pick the wrong tool. Each misselection looks like an LLM mistake, not a tooling problem. You blame the model. You pile on system prompt instructions. The real fix was in the description the whole time.

The clearest evidence came from comparing two of my own servers. Same hands. Different maturity. The gleif-mcp-server has full USE WHEN and FAILS WHEN clauses on every tool:

The description doesn’t just describe a capability. It gives the agent a reasoning model: what to call the tool for, what to try when it fails, where to go instead.

The WHY dimension is the most underused. In my nordic-registry-mcp-server, the Danish CVR API returns exactly one company per search query. Searching “Tietoevry” returns TIETOEVRY DK A/S, a company with 11 employees. Searching “Tietoevry Denmark” returns TIETOEVRY DENMARK A/S, a completely different legal entity with 56 employees. Without knowing why, an agent accepts the first result. With WHY embedded in the description:

Three debugging strategies from one description. The agent that reads this knows the API is opaque by design, knows to try variations, and knows there’s a direct lookup if it has a CVR number.

The same principle operates at both layers. At retrieval: “this is BM25, it matches keywords literally” - the agent adjusts its query. At the tool layer: “this fails when the LEI is invalid; try search_entity instead” - the agent adjusts its strategy. Opacity kills reasoning. Transparency feeds it.

Five Dimensions of a Transparent Description

The examples above illustrate USE WHEN, WHY, and FAILS WHEN. Here are all five dimensions, distilled from rewriting descriptions across seven servers:

1. USE WHEN tells the LLM which user intents should trigger this tool. Natural language phrases, not technical jargon.

2. WHY tells the agent the mechanism behind the behavior, so it can debug failures instead of retrying blindly.

3. FAILS WHEN covers specific failure modes with specific recovery paths. Not generic errors; conditions with next steps.

4. INSTEAD routes the agent to sibling tools. Without explicit cross-references, the agent cycles randomly through your tool list.

5. Limitations states hard boundaries the agent can’t work around: batch sizes, rate limits, field constraints.

INSTEAD is the routing dimension. The mediawiki-mcp-server has mediawiki_edit_page, mediawiki_find_replace, and mediawiki_apply_formatting. Without routing, Claude used edit_page for everything, fetching and rewriting entire pages for a single text change. With explicit routing:

An opaque description gives the agent nothing to work with. It selects, fails, retries, fails again.

The Uncomfortable Audit: Tool-Shaped Objects

Will Manidis, the CEO of Benchling, coined a term that stopped me mid-scroll: “tool-shaped objects.” Things that look, feel, and are marketed as tools but don’t change reality. They produce the sensation of productivity.

I’ve built a few. Embarrassing to admit, but useful to know.

The test is simple. Remove the tool from the chain. Does the final output change? If not, it’s a tool-shaped object. I call this the subtraction test.

I ran it against the Miro server. Most tools passed. One failed outright. Thirteen sat in the middle.

The gradient category is the uncomfortable one. These are tools that sometimes change the output, sometimes don’t. miro_get_board_summary exists alongside miro_get_board. Both return board info. The summary exists “for convenience.” Does it change the final output? Depends on the caller. Depends on the workflow. These tools aren’t obviously broken. They aren’t obviously essential.

The single fail was miro_ungroup. I pruned it. No user complained. No workflow broke. It had been dead weight for months, riding along like a vestigial organ.

Tool-shaped objects and selection debt compound each other. Every tool-shaped object in the listing makes the real tools harder to find. The LLM spends tokens considering it. Sometimes selects it. The tool-shaped object didn’t just fail to help; it made every other tool slightly worse by existing.

Perfection by Subtraction

Dieter Rams shaped Braun products for decades and distilled his philosophy to four words: “Weniger, aber besser.” Less, but better.

The subtraction test operationalizes this for tool builders. The audit isn’t finding what to add. It’s finding what to remove until only the essential remains. The gradient tools from the Miro audit sit in the hardest territory: not obviously broken, not obviously essential. The design discipline is having the nerve to remove them anyway.

Pruning is the most underrated practice in tool-building. Removing tools is harder than adding them because every removal feels like losing capability. It’s not. It’s gaining signal. Anyone can add a tool. Knowing which to remove requires understanding the whole system: how tools interact, which ones the LLM reaches for first, where token budgets get wasted on tools that produce nothing.

Removal is where the taste lives.

The Craft Layer: Taste as Specification

Paul Graham defined taste as “intolerance for ugliness combined with the ability to fix it.” In 2026, when AI generates most of my code, taste isn’t about writing beautiful functions. It’s about writing beautiful specifications.

Your ToolSpec descriptions, your routing annotations, your CLAUDE.md constraints: these are your taste, expressed as text the machine reads. Not the handler code; that’s execution. Not the LLM; that’s following instructions. The person writing the description decides what “good” means for this tool.

Each NOT FOR clause is someone saying: “I’ve watched this agent fail fifty times, and here’s what I know about the right path.” Hard-earned judgment, encoded as text.

Pattern drift is the architectural version of losing taste. My miro-mcp-server has generics, panic recovery, and audit logging in its handler wrapper. My newer servers have none of those. Same hands, same year, different maturity. The improvement in one project didn’t flow back to the others. When you stop redesigning, you stop applying taste. The codebase drifts toward whatever shipped last, not toward what’s best.

Graham wrote that “good design is redesign.” The makeHandler wrapper in the Miro server has been rewritten three times. Each time because something broke or annoyed me, not because I had a grand plan.

The Bottleneck Rewards Craft

David Oks argues that AI capability isn’t what gates adoption. Regulations, office politics, API authentication, data format incompatibilities, security reviews: these are the actual constraints. They’re getting proportionally more important as AI gets smarter, not less. William Stanley Jevons saw the same dynamic in 1865: making steam engines more efficient didn’t reduce coal consumption. It increased it. Efficiency made steam power economical for new applications, and total demand grew.

One layer deeper, the same dynamic plays out. More capable AI agents create more demand for well-structured tools, not less. My Miro server didn’t grow to 88 tools because AI got dumber. It grew because smarter agents attempted more, hit more edges, and needed more bridges to cross them.

The people best positioned aren’t the ones building the smartest AI. They’re the ones who understand both the capability and the bottleneck. The Danish CVR API’s single-result limitation. The Norwegian business registry’s role data quirks. The mediawiki server’s routing logic, learned from watching Claude rewrite entire pages when it should have called find-and-replace. This knowledge is tacit, context-dependent, and earned through reps. No model upgrade gives you this.

Comparative advantage doesn’t require being better at everything. It requires being relatively better at the bottleneck.

The craft of tool-building appreciates as AI improves. Every time a model gets smarter, it attempts more, hits more edges, and needs better-described, better-pruned, better-designed tools.

The intelligence was never the bottleneck. I wonder how many tool-shaped objects are sitting in your server right now, quietly making every real tool a little harder to find.

References

• Doug Turnbull led Search at Reddit and Shopify. His BM25 + reasoning loop results appear in Hugo Bowne-Anderson’s Vanishing Gradients newsletter.

• David Oks, “Why I’m Not Worried About AI Job Loss.” Ricardian comparative advantage applied to AI.

• Dieter Rams, “Ten Principles of Good Design.” Principle 10: “Good design is as little design as possible.”

• Paul Graham, “Taste for Makers.”

• Will Manidis, “Tool-Shaped Objects” (X thread, Feb 2026).

• William Stanley Jevons, The Coal Question (1865). The paradox: efficiency increases total demand.

• Portfolio: miro-mcp-server, gleif-mcp-server, nordic-registry-mcp-server, mediawiki-mcp-server, productplan-mcp-server.
  

  This Substack is reader-supported. To receive new posts and support my work, consider becoming a free or paid subscriber.

I ran ls on my Claude Code skills directory last week. Fifty-one files. Each one a markdown document that turns a general-purpose AI into a domain expert for one specific job.

The number itself means nothing. What matters is the shape of the thing, the way 51 separate acts of laziness, frustration, and repetition crystallized into something that resembles a nervous system for an organism that didn’t exist six months ago.

What a skill actually is

A Claude Code skill is a markdown file. That’s it. A prompt with metadata: trigger phrases, reference files, constraints. When you type `/today`, Claude doesn’t wonder what you mean. It loads the prompt, reads your calendar, checks your Obsidian to-do file, and drafts your standup. Every time, the same way, without the five-minute preamble of explaining your daily workflow.

The official term is “custom slash command.” Muscle memory for a thing that has no muscles and no memory.

There’s something worth pausing on here. The file format is .md. Markdown. The same format people use for READMEs nobody reads and documentation nobody updates. Yet inside a SKILL.md, a few hundred words of precise instruction can turn a general-purpose language model into a domain expert that knows your wiki URL structure, your team’s formatting preferences, your brand’s exact hex values. The gap between the container’s humility and its contents’ power is almost comical.


The taxonomy nobody planned

I didn’t design a skill architecture. I solved a problem. Then another. Then I noticed clusters, the way you notice desire paths across a lawn only after the grass has already died.

Not all 51 are mine from scratch. Four were adopted or adapted from open-source repositories; several encode frameworks by people smarter than me. The rest grew out of specific irritations on specific afternoons.

Research & Investigation (5 skills)

lmwtfy (let me wiki that for you) answers colleagues’ questions about our products by searching the wiki, GitHub, and Azure DevOps. bid-intel drafts procurement responses. deep-research delegates to the OpenAI Deep Research API for topics that need real depth; originally from Gleb Kalinin’s skill library, adapted for my workflow. github-investigation does code archaeology across repos. investigate builds on lmwtfy and dispatches questions to an n8n agent that searches all three systems at once.

Content & Publishing (7 skills)

linkedin-viral-post-writer creates LinkedIn posts. Although I tend to argue with it and often rewrite things in my own way. publish sends Obsidian notes to LinkedIn and Substack. article-extractor strips the ads and navigation chrome from URLs, using Mozilla’s Readability algorithm under the hood. youtube-transcript downloads video transcripts. tapestry orchestrates three other skills into a single pipeline: extract content, transform it into a learning plan with ship-learn-next, ship an output. sift evaluates whether a piece of content is worth your time at all, before you commit to reading it.

Visual Design & Branding (8 skills)

Three separate brand systems (brand-agency, brand-adsoptimizer, brand-assets) because I work across multiple visual identities and the model will happily bleed one palette into another if you let it. brand-agency is adopted from Gleb Kalinin’s skill library and expanded. nano-banana generates images through Gemini, repackaged from Carl Vellotti’s course into a standalone skill. diagram produces Mermaid diagrams from natural language. d3js creates interactive data visualizations. `find-asset` locates logos and icons by description so nobody hallucinates a file path. `slide-deck` builds presentations.

n8n Automation (7 skills)

An entire knowledge base encoded as skills, built around Romuald Czlonkowski’s n8n-mcp server] and distilled from n8n’s documentation. Workflow patterns, JavaScript and Python code node syntax, expression validation, node configuration, MCP tool guidance, error interpretation. Seven skills that together form a domain expert for a platform I work with daily. Czlonkowski’s server provides the tools; the skills provide the judgement for when and how to use them. Without either layer, every n8n session starts from first principles.

DevOps & Releases (4 skills)

enhanced-edoc-update generates weekly stakeholder reports from Azure DevOps data. release-prep produces release notes. publish-docs syncs documentation to the team wiki. vercel-deploy deploys and returns a URL. (Full disclosure: vercel-deploy is adopted from Composio’s open-source skill library, used as-is.)

Product Strategy (4 skills)

feature-scoping estimates sprint work. triage-requests organizes feature requests for prioritization. edge-cases identifies error states before development starts. competitive runs competitive analysis.

Quality & Meta (4 skills)

SkillCheck - free version at https://github.com/olgasafonova/SkillCheck-Free - validates skills against Anthropic’s agent skill guidelines; it’s free and open source. SkillCheck Pro adds anti-slop detection, security scanning, and enterprise readiness checks. Skills that check skills. rhetoric-springs detects rhetorical bias in text, built on Jeremy Bentham’s 1817 taxonomy of persuasion mechanisms.
mcp-builder guides the creation of MCP servers; originally from Composio, rewritten to v2.0 with Golang support and hard validation gates.

Productivity (6 skills)

today preps daily standups. xlsx handles spreadsheets. md2word converts markdown to Word for stakeholders who live in Microsoft land. cv-from-job tailors a CV to a job description, drawing on Noam Segal’sinterview coaching framework. one-page-strategy structures strategy documents using the framework by Richard Russell, synthesized from Rumelt’s Good Strategy/Bad Strategy and Lafley & Martin’s Playing to Win. projects-index auto-generates an Obsidian project index by scanning repos.

The rest (6 skills)

deck-to-video converts HTML slides to MP4. repo-to-video generates a NotebookLM overview from a repository. pra-review handles Privacy Risk Assessments for GRC, cross-referencing PRA claims against actual source code so the compliance answers are grounded in something other than hope. revenue-dashboard produces financial dashboards from Power BI exports. linkedin-invite automates LinkedIn invites via browser.
steps builds implementation guides by executing commands live and capturing the output.

What the catalog doesn’t show

Numbers lie by omission. Fifty-one skills arranged into categories looks like a product roadmap. It wasn’t. The French have a better word for what actually happened: bricolage. You build with whatever’s at hand, solving the irritation in front of you, and the structure reveals itself only in retrospect.

Three properties of the collection surprised me.

Skills compose. tapestry contains no extraction logic. It calls youtube-transcript or article-extractor depending on the URL, then pipes the result through ship-learn-next. Three skills, a pipeline. They arrived separately over three different weeks for three different reasons. The seam between them turned out to be a single function call. Modularity as accident, not architecture.

The immune system grew unprompted. After about thirty skills, quality started to drift. Some had clear trigger phrases, others were vague enough to fire on the wrong input. Some followed Anthropic’s guidelines, others had quietly abandoned them. So I built SkillCheck - https://github.com/olgasafonova/SkillCheck-Free. Then SkillCheck Pro for stricter validation: anti-slop patterns, security scanning, token budget analysis. The system needed maintenance and grew the maintenance organ on its own, the way a coral reef builds its own substrate.

Context savings compound invisibly. The obvious value of a skill is time saved per invocation. Five minutes here, ten there. The hidden value is the context you *don’t* spend. Without /lmwtfy, every colleague question opens with “search the wiki for X, then check GitHub, then look at Azure DevOps work items, here’s the project name, here’s how our wiki URLs work.” That’s 200 tokens of setup, every single time. Multiply by frequency, multiply by sessions per week. The real return is in the tokens Claude never has to process. Nobody puts that on a dashboard.

The markdown file as métier

Most writing about AI tools fixates on the model. The model got smarter. The model hallucinates less. The model now supports images. This is like evaluating a pianist by the piano.

The interesting unit isn’t the model. It’s the skill file. A few hundred words of markdown that encode a working professional’s domain knowledge: what to search, where to look, which fields matter, what the output should look like, which mistakes to avoid. The model provides reasoning. The skill provides judgement.

Most people’s experience of AI coding assistants is a blank prompt and a prayer. They describe what they want, get something close, fix it, describe the next thing. Freehand, every time. It works. It’s also the least efficient mode of interaction, the way cooking from memory works but a recipe is faster and more consistent.

The entire “prompt engineering” discourse missed this. Prompts aren’t engineering. They’re ephemeral. Skills are engineering. They persist, they version-control, they compose, they get validated. A prompt is something you type. A skill is something you ship.

The count will be wrong by the time you read this

I have three half-finished skills open in other tabs. That’s how it goes. Every repeated frustration is a skill waiting to be extracted. The question isn’t whether 51 is a lot. The question is which of your daily rituals are still freehand sketches when they could be stencils.

Somewhere in my skills directory, there’s probably one I built in November and haven’t triggered since. Still there, loaded into Claude’s context at startup, patiently waiting for the right / command. I don’t remember what it does. It remembers what I taught it.

A caseworker in a Norwegian municipality receives a permit application from a Danish company. To verify the company exists and isn’t bankrupt, she opens data.brreg.no. Realizes this is a Danish company. Switches to datacvr.virk.dk. Navigates a Danish interface. Manually copies the company name, status, and address back into her case system. If the company also has a Finnish subsidiary, add ytj.fi to the tab count.

This happens thousands of times a day across Nordic public sector. Procurement officers validating vendor lists from multiple countries. Compliance teams running due diligence on cross-border contractors. Grant administrators checking whether an applicant is a legitimate non-profit or a dissolved shell company.

Nordic cross-border trade is massive. Denmark, Finland, Norway, and Sweden share labor markets, procurement frameworks, and regulatory traditions. Companies operate across these borders routinely. But the digital tools for verifying those companies act like national borders are concrete walls. Each country’s business registry is its own island: different URL, different API format, different language, different data model.

This isn’t a secret. The Nordic Council of Ministers spent 27 million DKK on the Nordic Smart Government & Business initiative between 2021 and 2024. Twenty-one organizations across all five Nordic countries participated. They produced OpenAPI specifications and a reference implementation on GitHub]. The program concluded in June 2024. The proof of concept covers Norway and Finland only and comes with ”no guarantees for stability.”

So the problem is validated at the highest Nordic political level. A production solution still doesn’t exist.

27 million DKK, 21 organizations, three years of work, and the result is a Java Spring Boot proof of concept covering two countries. I found it hard to accept that the same problem couldn’t be solved faster with a Go binary and four free government APIs.

What the vendors built (and what they didn’t)

The case management industry had 20+ years to solve cross-Nordic company lookup. It didn’t. Here’s what got built instead.

KMD (Denmark, now owned by NEC Corporation) dominates Danish public sector IT. The Danish Police, Defense, Tax Authority, and most municipalities run on KMD Nova ESDH. Their KMD WorkZone has CVR integration. Danish companies only.

cBrain* (Denmark, F2 platform) serves most Danish ministries, including the Prime Minister’s Office. They’re claim to be the AI leader in this space: F2 AI Assistant and F2 AI Expert run on-premises LLMs for document summaries, translations, and legal interpretation. Could be an impressive technology. But no documented company registry integration. The AI can summarize a case file; it can’t verify whether the company mentioned in it still exists.

Acos (Norway, WebSak) serves most Norwegian municipalities and ministries. They have a confirmed BRREG integration. Norwegian companies only.

Formpipe (Sweden, W3D3 and Platina) serves 400+ Swedish and Danish public sector organizations. No documented company registry integration at all.

Documaster (Norway) focuses on archiving. No registry integration.

Tieto (Public 360) and Visma operate across multiple Nordic countries but ship country-specific products. No cross-border registry solution documented from either.

See the pattern? Every vendor that has a registry integration built it for one country. KMD does CVR. Acos does BRREG. Nobody does both. Nobody does all four.

Commercial aggregators exist, of course. Roaring.io offers a unified Nordic API and it’s developer-friendly, but subscription-based. Proff API covers multiple Nordic countries, paid per request. Creditsafe and Bisnode/D&B target enterprise budgets and KYC workflows. All paid. None AI-native. None work with MCP.

Even in the MCP ecosystem, everything is fragmented. Norway has two single-country servers: brreg-mcp-server] (18 tools) and BRREG-MCP (13 tools). Denmark has mcp-danish-cvr with 2 tools and a 50-lookup daily limit via a third-party API. Sweden has a couple of servers using third-party data sources. Finland has zero MCP servers.

The gap is clear: no free, cross-Nordic, AI-native, vendor-agnostic solution exists.

What I built

Disclosure: I work at Tieto on Public 360. This MCP server is a personal open-source project, not a company product.

23 tools. Four countries. All from official government APIs. All free.

• Norway - Brønnøysundregistrene - 12 tools, no auth required

• Denmark - CVR - 5 tools, no auth required

• Finland - PRH - 2 tools, no auth required

• Sweden - Bolagsverket - 4 tools, OAuth2 (free registration)

You can search companies by name across four countries. Verify status, bankruptcy, employee count. Look up board members, CEOs, and auditors. Check who can legally sign on behalf of a company (signaturrett and prokura in Norwegian legal terms). Access Swedish annual reports (årsredovisningar). Batch-validate lists of up to 2,000 company IDs against official registries in a single call. Monitor registry changes in near real-time.

It ships as a single Go binary with zero runtime dependencies. No Node.js, no Python, no Docker required for basic use. Download the binary, point your MCP client at it, done. Works with Claude Desktop, Claude Code, Cursor, or any MCP client that speaks the protocol.

https://github.com/olgasafonova/nordic-registry-mcp-server | Apache 2.0 license

What each country’s API taught me

Building across four government APIs is an exercise in tolerating inconsistency.

Norway (Brønnøysundregistrene) is the gold standard. Clean REST API. HAL-formatted JSON responses. No authentication required. Comprehensive data: board members, signature rights, voluntary organizations register, branch offices, registry change feeds. If every Nordic country published APIs like this, the NSG&B program wouldn’t have been necessary.

Denmark (CVR) has what I call the one-result trap. The CVR API returns a single company per search query. Searching “Tietoevry” returns TIETOEVRY DK A/S (11 employees). Searching “Tietoevry Denmark” returns TIETOEVRY DENMARK A/S (56 employees). A completely different legal entity. Also, speaking of Tietoevry - it became Tieto recently. I had to embed guidance directly in tool descriptions so the AI knows to try variations: “Company A/S,” “Company Denmark,” “Company Holding,” pre-merger names. The API works; the UX for an AI consumer is hostile.

Finland (PRH) is the flood. Searching “Nokia” returns 900+ results. Nokia Oyj is in there somewhere, buried among Nokia-branded subsidiaries, dissolved entities, and unrelated companies with Nokia in their address. Added filtering by company form (OY for private, OYJ for public), location, and exact legal name. Pagination defaults to 20 results because LLM context windows aren’t infinite.

Sweden (Bolagsverket) is the OAuth2 wall. The API is free, but you register by submitting a form on a government website and waiting for credentials. OAuth2 token management, automatic refresh. No name search available in this API. You need the 10-digit organization number upfront. I made Swedish tools conditional: if OAuth2 credentials aren’t configured, the tools simply don’t register. Users who only need Norway, Denmark, and Finland never see them.

Four countries, four completely different API philosophies. Norway is open-data progressive. Denmark returns one result and calls it a search. Finland floods you with everything matching a substring. Sweden makes you fill out a government form before you can start. This inconsistency is exactly why nobody built the cross-Nordic tool before. It’s not hard technically; it’s tedious across four sets of documentation, four response formats, and four sets of edge cases.

The infrastructure that makes it hold together:

A circuit breaker per country opens after five consecutive failures and recovers after 30 seconds. If the Danish CVR API goes down, Norwegian lookups keep working. Request deduplication ensures that five concurrent tool calls for the same company result in a single API request; the others wait and share the result. An LRU cache with per-endpoint TTLs (searches: 2 minutes, company details: 15 minutes, reference data: 24 hours) keeps responses fast without serving stale data.

Each tool description includes a “USE WHEN” clause with explicit trigger phrases. “Who is on the board of company X?” routes to norway_get_roles, not norway_get_company. This matters because LLMs choose tools based on description text, and vague descriptions lead to wrong tool selection.

The uncomfortable question

Why didn’t the vendors build this? The APIs have been available for years. Brønnøysundregistrene has been publicly queryable since at least 2014. CVR opened up years ago. PRH publishes open data. Bolagsverket launched their free API tier.

I see three structural reasons:

Single-country procurement. Vendors build for one government contract at a time. When a Norwegian municipality writes an RFP for case management, it asks for BRREG integration. It doesn’t ask for Danish CVR lookup because the procurement process is national. The requirement specifications are written country by country. The demand signal for cross-Nordic doesn’t appear in any single tender document.

Revenue model. Registry integration is a paid add-on in most case management systems. KMD charges for CVR integration. Acos charges for BRREG. Building one cross-Nordic module would cannibalize four separate country-specific add-on sales into one. From a product management perspective, four smaller products bill better than one bigger product. The incentive structure actively works against consolidation.

Adapted behavior. Caseworkers adapted years ago. They open four browser tabs. It takes five minutes instead of thirty seconds, but the workaround is functional. Nobody files a support ticket saying “I need all four registries in one place” because the pain doesn’t feel like a bug. It feels like how things are. The friction is real but diffuse enough that it never reaches a product backlog as a prioritized item.

Technical fragmentation. Even a motivated vendor would face the same inconsistency I faced: four different API architectures, four sets of documentation, four response formats, four sets of ID validation rules. The integration cost scales linearly with countries, and each country adds its own edge cases. It’s not glamorous product work. It’s plumbing.

The MCP model breaks this pattern. An MCP server isn’t locked to one vendor’s case management system. It works wherever AI works. A caseworker in Acos WebSak, a compliance officer using Claude Desktop, a developer in Cursor, an n8n workflow running overnight batch validation: the same 23 tools serve all of them. The vendor doesn’t need to build it. The ecosystem builds it.

This is the part that excites me most. MCP decouples the data access layer from the application layer. The government APIs are public goods. The MCP server is open source. The case management system doesn’t need a proprietary integration module; it needs an AI assistant with the right tools connected. That shift makes cross-Nordic company verification a solved problem rather than a product roadmap item waiting for prioritization.

What’s next

The free government APIs cover the basics: company details, status, some role information. Premium data layers exist for Sweden and Finland. Virre (Finland) and Bolagsverket’s premium tier offer board members, authorized signatories, and financial documents that the free APIs don’t expose. Adding these would give consistent governance data across all four countries.

Sanctions cross-referencing is the obvious due diligence extension. Verify a company exists, then check it against EU and national sanctions lists in the same conversation. One query that answers “is this company real, active, and not sanctioned?” instead of three separate manual checks.

Iceland and the Faroe Islands are the missing pieces. Iceland’s official registry Skatturinn has no public API; the data is only available through Já Gagnatorg, a commercial reseller charging ~$110/month. The API itself is excellent: 41 fields including industry codes, parent company structure, bankruptcy status, and geocoded addresses. But it breaks the “all free” constraint. The Faroe Islands registry Skráseting Føroya has no API at all, only a web search interface, and is completely separate from Danish CVR. If either country publishes a free open data API, the implementation pattern is ready; the code follows the same structure as the existing four countries.

The bigger unlock is connecting registry verification with case management through AI. Verify the company. Check the signer’s authority. Update the case record. All in one conversation instead of four tabs and a copy-paste workflow. That’s where this is heading. Not a standalone lookup tool, but a verification layer that plugs into whatever system the caseworker already uses.

I’m watching the NSG&B OpenAPI specifications for signs of adoption by individual countries. If Norway or Finland starts serving production data through a unified spec, the MCP server can consume it as another backend. Competition from government infrastructure is the best possible outcome; it means the problem got solved at scale.

Try it

The government APIs are free. The code is at https://github.com/olgasafonova/nordic-registry-mcp-server. The only thing that costs money is the time your team spends switching between four browser tabs.

Install it, point it at your MCP client, and ask: “Is company 923609016 active and who can sign for them?”

GitHub | Issues | MCP Registry

Tell me what’s missing.

Subscribe now

Miro shipped a significant update to their official MCP server on February 2nd. I’ve been building a community one since December - and recently added a few tools as well. Both connect AI coding tools to Miro boards. Both use the Model Context Protocol. And they solve completely different problems.

This isn’t a “which one wins” comparison. It’s a “why you might want both” analysis.

What Miro is becoming

To understand the two servers, you need to understand where Miro is going.

Miro stopped being a whiteboard tool a while ago. At Canvas 25 (October 2025), they rebranded the AI layer as the “Innovation Workspace” and announced a Product Acceleration suite: Portfolios, Insights, Prototypes, Specs, and Goals. The pitch shifted from “collaborate on a canvas” to “accelerate product development with AI.”

The AI features already shipped tell the story. Sidekicks are conversational AI agents that live on the canvas and see whatever you select. Flows are multi-step AI workflows where each step ingests the previous step’s canvas output. Visual Context Processing serializes spatial relationships (positions, groupings, connections) alongside content and feeds everything to a multimodal LLM. “Create with AI” generates stickies, docs, tables, mind maps, flowcharts, ERD, and UML from natural language.

The common thread: Miro is building AI that understands boards. Not just the text on stickies, but how items relate spatially. Where clusters form. What a group of connected shapes represents.

This direction shaped official Miro MCP server.

Two different philosophies

The official Miro MCP server has 13 tools and 2 prompts as of today. That’s not a limitation; it’s a design choice. Every tool serves their core narrative: boards as context for code.

context_explore maps a board’s structure. context_get extracts deep context from specific sections. code_create_from_board and code_explain_on_board are prompts purpose-built for turning visual designs into working software. The diagram tools use a custom DSL (not Mermaid) that supports flowcharts, UML, and ER diagrams natively. Doc and table tools round out the structured content operations.

It’s cloud-hosted. One URL in your MCP config, OAuth 2.1 handles auth, no binary to install. If you’re a developer who designs in Miro and codes in Cursor or Claude Code, this is the shortest path from whiteboard to implementation.

My community server has 89 tools. That’s also a design choice, just a different one. It wraps the full Miro REST API: every item type, every CRUD operation, every management endpoint. Sticky notes, shapes, cards, app cards, connectors, frames, mindmaps, tags, groups, bulk operations, export, audit logging. It runs as a 14MB Go binary with stdio and HTTP transport. You can run it locally, in Docker, behind a firewall, or air-gapped.

The official server asks: “What does this board mean?” My server asks: “What do you want to do to this board?”

Where they overlap (and don’t)

The overlap is small: diagrams, documents, tables, and reading board content. Everything else is exclusive to one server or the other. This is what makes “use both” a real option.

The synergy case

MCP servers register independently. You can configure both in the same AI tool under different names. One client, two servers, same boards.

Here’s where that gets interesting.

Workshop facilitation + synthesis. Use the community server to run a workshop: bulk-create stickies from a participant list, organize them into frames, tag them by theme, group related ideas. After the session, switch to the official server. Its AI context tools summarize what happened, extract action items, and generate specs from the visual output.

Build the board, then generate code. Use the community server to construct a technical architecture on a board: shapes for services, connectors for data flow, cards for requirements, tags for priority. Then use the official server’s code_create_from_board prompt to turn that visual architecture into implementation scaffolding.

CI/CD + developer workflow. Run the community server in Docker as part of your pipeline. It creates boards from build results, updates status cards, manages release tracking boards. Developers interact with those boards through the official server’s AI features in their IDE.

These aren’t theoretical. They’re natural consequences of one server being good at doing things and the other being good at understanding things.

What v1.14 of community MCP added

The community server just hit 89 tools. Six new additions in v1.14:

- Markdown documents on boards (create, read, delete via Miro’s doc format API)

- Local file uploads for images via multipart form

- Flowchart shapes using Miro’s experimental stencil API

- Tag queries to find all items with a specific tag

- API change tracking that diffs Miro’s OpenAPI spec weekly and opens GitHub issues on changes

- Cross-referenced tool descriptions so LLMs pick the right tool more often

The server also upgraded to go-sdk v1.3.0 and Go 1.24.

Looking ahead

Miro’s investment in spatial AI is significant. They’re the only visual collaboration platform showing public research signals in graph-based canvas understanding. And that’s extremely intersting and promising direction. Figma has template generation and Figma Make (powered by Claude). Lucid has diagram generation and its own MCP server. Neither appears to be modeling the canvas as a graph.

As Miro’s AI gets better at understanding boards, the tools that operate on boards become more useful, not less. AI agents that can comprehend a board still need tools that can create, modify, and organize what’s on it. The comprehension layer and the operations layer are complementary.

Two servers. Different strengths. Same boards. Use both.

The community Miro MCP server is open source and MIT-licensed: https://github.com/olgasafonova/miro-mcp-server

The official Miro MCP server: https://miro.com/ai/mcp/

Share

Everyone's writing "How to set up CLAUDE.md" guides. They cover the basics: add your project context, define a few workflows, maybe set a tone preference. These guides are fine for getting started. They stop exactly where things get interesting.

I've been running Claude Code as my primary working environment for a year. What started as a CLAUDE.md file turned into something different: 38 custom skills, 7 specialized agents, 20 MCP servers, a rules engine that routes decisions automatically, and quality gates that block substandard output before it ships.

This post is about what happens after you've been doing this for a while. Not the setup. The system that emerges.

Skills are not prompts

The beginner articles treat skills like saved prompts. Write a good instruction, save it in a file, call it with a slash command. That's the surface.

A skill is a composable expert mode with its own activation logic, supporting resources, and success criteria. The SKILL.md file has YAML frontmatter that tells Claude when to activate, and a markdown body that tells it how to behave. The description field in the frontmatter is the most important line you'll write; it's what Claude reads when deciding which skill matches your request.

Here's what that looks like at scale - as of today. My skill categories:

• Research (4): Wiki lookup, bid response drafting, deep research, GitHub investigation

• Content (5): LinkedIn posts, publishing pipeline, article extraction, learning frameworks

• Visuals (6): Brand asset generation, diagrams, data visualization, image generation

• DevOps (4): Weekly stakeholder reports, release notes, wiki publishing, deployment

• Quality (4): Skill validation, rhetoric analysis, MCP server builder guide

• Productivity (7): Daily standup prep, spreadsheets, strategy documents

Each skill has trigger phrases embedded in its description. When I say "bid response," Claude loads the bid-intel skill. When I say "publish docs," it loads the wiki publishing skill. I don't need to remember which skill does what; Claude matches my intent to the right expert mode.

The interesting part is composition. I have a skill that orchestrates three other skills into a single workflow: it detects whether a URL points to YouTube, an article, or a PDF, extracts the content using the appropriate skill, then feeds it into a learning framework that turns insights into action steps. One command, three skills working together.

The meta-skill is skill-check: a skill that validates other skills against quality guidelines. It reads a SKILL.md file and flags problems with trigger phrases, missing success criteria, or security issues. Tooling that audits your tooling. That's when the system starts maintaining itself.

Multi-agent teams

Most people use Claude Code as a single agent. One conversation, one context, one task at a time. That works for most things. Some tasks need parallel processing.

I run 7 specialized agents:

• backend-architect: API design, database schemas, scalability decisions

• error-detective: Log analysis, debugging, error pattern detection

• go-mcp-reviewer: Handler safety, tool description quality, cross-project consistency

• mcp-expert: MCP server patterns, handler design, transport configuration

• technical-researcher: Code analysis, documentation review, implementation research

• technical-writer: User guides, README files, architecture documentation

• wiki-researcher: Fast wiki lookups using our internal MediaWiki

Each agent has its own tool permissions, model selection, and behavioral rules. The wiki-researcher runs on Haiku (fast, cheap) with read-only wiki access. The go-mcp-reviewer runs on Sonnet with code review prompts loaded. They coordinate through a shared task list.

The best use case for teams: cross-repository pattern drift reviews. I maintain 7 Go MCP servers. Each follows similar patterns for handler registration, error handling, and tool descriptions. But patterns drift over time. One server adds panic recovery, another doesn't. One improves its error messages, the others stay behind.

A team review works like this: the team lead creates tasks ("review handler patterns in miro-mcp-server," "review handler patterns in gleif-mcp-server"), assigns one agent per repository, and they run in parallel. Each agent reads the handlers, compares against the reference implementation, and reports drift. What would take me hours of manual cross-referencing finishes in minutes.

The cost reality: agent teams consume roughly 7x the tokens of a single agent. Using Opus for teammates would be prohibitively expensive; Sonnet works well enough for specialized tasks. Teams are worth it for specific, parallelizable work. For sequential tasks, a single agent is cheaper and often better.

Rules that scale

CLAUDE.md is the entrypoint. (I wrote about how this config syncs across machines as a git repo in a previous post.) The real power is in the rules directory.

I have 11 rule files, each loaded when its context applies:

• writing-style.md: Short sentences, active voice, no LLM patterns, specific evidence

• visual-design.md: Routes to the correct brand system by project path or hostname

• code-review-prompts.md: 6 structured review prompts targeting specific risk surfaces

• knowledge-loop.md: Auto-proposes wiki entries when skills produce reusable answers

• go-development.md: Go-specific conventions, linting rules, test patterns

• spatial-systems.md: 8pt grid system, layout principles for visual work

• azure-devops.md: Work item formatting, HTML comments, mention conventions

The brand router in visual-design.md is a good example of rules doing work that would otherwise require manual decisions. It checks the project path, hostname, and content type, then selects the right brand system. Working on a Tieto project at work? Load the Tieto brand (deep blue, specific logo variants, official template). Working on a personal MCP server at home? Load the Agency brand (neobrutalism, hard shadows, flat colors). Building something for AdsOptimizer? Load that brand system instead.

I don't think about which brand to use. The rules handle it.

The knowledge loop is subtler but more valuable over time. When a research skill (like the one that answers colleague questions about our products) produces a verified, high-confidence answer, the loop checks the team wiki. If the topic isn't covered, it drafts a wiki entry and asks for approval before publishing. The skill that answers one person's question feeds knowledge back into the system where everyone can find it.

Quality gates

Skills and agents can produce bad output. The question is where you catch it.

I use hooks: shell commands that execute in response to Claude Code events. When a teammate agent completes a task, a quality check script runs automatically. If the output doesn't meet standards, the hook blocks the completion with an exit code and the agent has to revise.

The go-mcp-reviewer agent has hard gates baked into its prompt. Before it can approve a handler, it must verify: does the handler validate arguments before passing them to the API? Does it respect the tool's safety annotations? Could error messages leak API tokens or internal URLs? These aren't suggestions. They're requirements the agent can't skip.

This layered approach (prompt-level enforcement plus tooling-level enforcement) catches different categories of problems. The prompt catches logical issues. The hooks catch process issues. Neither is sufficient alone.

The decision architecture

Here's the thing nobody talks about in the CLAUDE.md guides: the tools are commoditizing. Every month, more people set up CLAUDE.md, create a few skills, connect some MCP servers. The setup is getting easier. The barrier to entry is dropping.

What doesn't commoditize is the judgment layer.

Knowing when to use an agent team vs a single agent. Knowing which MCP patterns to apply to a new integration. Knowing when a skill should compose with other skills vs stay standalone. Knowing when to build an MCP server vs use an existing one. Knowing that 7x token cost for teams is worth it for pattern drift reviews but wasteful for sequential tasks.

Cassie Kozyrkov, Google's former Chief Decision Scientist, argues that as AI handles more execution, human decision-making becomes the bottleneck. The most valuable skill isn't tool mastery; it's the judgment about how to deploy tools effectively.

I think about my setup the same way. The 38 skills are artifacts. The 7 agents are artifacts. The rules and hooks are artifacts. The decision framework that produced them; the reasoning about what to build, how to structure it, when to automate and when to stay manual; that's the part that took a year to develop and can't be copied from a tutorial.

What this means for you

If you're reading CLAUDE.md setup guides, keep reading them. They're a real starting point. But notice when you outgrow them. Notice when you start solving the same problem twice and think "I should make this a skill." Notice when you want two things happening in parallel and think "I need another agent." Notice when a brand decision keeps requiring manual thought and think "I should encode this as a rule."

The system doesn't arrive fully formed. It emerges from paying attention to friction and encoding solutions.

Start with one skill that solves a real annoyance. Build from there. The compound interest of encoded decisions is the part nobody warned you about.

A few months ago, I rarely touched git. Then a patient colleague named David explained why Linus Torvalds called it “the stupid content tracker” — and something clicked. As Lille My puts it: “I’ll always manage.”

So I did what any infrastructure-minded person would do: I put it all in git:

The core trick: symlinks + git

Here’s the clever bit. Claude Code looks for its config in a specific folder (~/.claude/). Instead of editing files there directly, I created a Git repository and used symlinks (shortcuts that make files appear in two places at once) to connect them.

Claude Code sees its config folder. Git sees a normal repository. I get version history, sync across machines, and can roll back mistakes.

The same approach works for any tool that reads from a config directory.

Keeping secrets safe

API keys and tokens can’t go in git. But I still want them to sync between machines.

The solution: template expansion. My git repo contains config files with placeholders like ${MIRO_ACCESS_TOKEN}. A script reads actual secrets from my Obsidian vault (which syncs via a different, encrypted channel) and fills in the blanks.

The gith repo stays portable and safe to share. Secrets stay local.

For engineers: this is the same pattern as .env files and environment variable substitution, but applied to AI tool configuration. Simple, composable, works everywhere.

What I’m actually versioning

Skills are like recorded macros for AI workflows. I have 30+ of them. Type /brand-assets and Claude knows exactly how to generate social graphics using HTML and headless Chrome. Type /github-investigation and it runs a specific code archaeology workflow with timeline tables and impact analysis.

Each skill is a markdown file that captures a workflow I’d otherwise explain from scratch every time.

Agents are like specialized personas with domain expertise baked in. I have an mcp-expert, a technical-writer, an error-detective, a product-strategist, and a few more. Each is a markdown file describing how to think about problems in that domain.

Rules trigger automatically based on context. Working on Go code? Go conventions apply. Writing prose? My writing style rules activate (no em-dashes, use contractions, avoid LLM-sounding phrases). It’s like .editorconfig, but for AI behavior.

MCP servers connect Claude to external tools. I have 15 integrations: Azure DevOps for work items, Miro for whiteboarding, Playwright for browser automation, plus custom servers I built for domain-specific APIs.

The automation layer

A script runs at login: pull latest config, rebuild any servers if source changed. A hook warns me when I have uncommitted changes.

I open my laptop and everything’s current. Make a change, commit, push. The other machine gets it automatically.

Why this matters

Or as Lille My also says: “Hope for the best and prepare for the worst.”

Consistency - Same Claude experience on every machine. Same skills, same rules, same integrations.

History - I can see how my writing-style rules evolved over six months. I can trace when I added a skill and why.

Portability - New machine setup is two commands: clone the repo, run the install script.

Composability - Skills can reference other skills. Rules layer on top of each other. Everything is plain text, diffable, reviewable.

The unexpected benefit

Treating AI configuration like infrastructure forced me to articulate what I actually want from my tools.

Writing rules made me think about writing style. Building skills made me document workflows I’d been doing intuitively. Creating agents made me define what expertise actually looks like in different domains.

The configuration became a form of reflection on how I work.

The specific implementation uses Claude Code, but the patterns transfer to any AI tool with configuration files. Symlinks, template expansion, and git aren’t new. Applying them to AI assistants is.

After building SkillCheck and running it against over a hundred real-world Claude Code skills, clear patterns emerged. The same issues appear again and again, even in well-crafted skills from experienced developers.

Skills are how you extend Claude’s capabilities. A skill is a folder with a SKILL.md file containing instructions that Claude loads when relevant. The format follows the agentskills.io specification, an open standard that works across Claude Code, Codex CLI, and other AI agents.

Here’s what I found validating skills against the spec, and how to fix each issue.

1. Missing the WHEN trigger in descriptions

The problem: Skills describe what they do, but not when Claude should activate them.

The agentskills spec requires descriptions to include activation triggers. Without them, Claude doesn’t know when your skill is relevant.

Why it matters: The description is Claude’s primary signal for deciding whether to invoke your skill. No WHEN clause = your skill sits unused even when it would help.

Trigger phrases that work:

• “Use when...”

• “Triggers on...”

• “Activate when...”

• “Use for...”

• “Applies to...”

Real example from https://github.com/glebis/claude-skills:

The `telegram` skill gets this right:

Specific keywords (”show my Telegram messages”) give Claude exact phrases to match.

2. Missing the WHAT verb

The problem: Descriptions explain the domain but don’t state the action.

Per the spec, descriptions need an action verb explaining what the skill does.

Why it matters: Action verbs tell Claude what the skill does. “Generation” is a concept; “Generate” is actionable.

Strong action verbs:

• Create, Generate, Build

• Convert, Transform, Extract

• Analyze, Validate, Process

• Search, Find, Fetch

Weak alternatives to avoid:

• “A tool for...” (what does it do?)

• “Handles...” (vague)

• “Helps with...” (still vague)

Vague or generic names

The problem: Single-word or overly generic names that don’t convey purpose.

The naming rules require lowercase letters, numbers, and hyphens only. But beyond format, names should be self-documenting.

Why it matters: When scanning ~/.claude/skills/, you should know what each skill does without opening the file.

Reserved words to avoid: skill, skills, claude, anthropic, mcp, tool, tools, agent, ai, assistant, bot

Vague terms to avoid: helper, utils, misc, stuff, manager, handler

Good pattern: [domain]-[action] or [action]-[object]

• github-pr-reviewer

• weekly-report-generator

• code-quality-checker

4. Empty sections after headings

The problem: Creating structure without content.

That empty Overview section wastes tokens and suggests incomplete documentation.

Why it matters: Every heading should deliver value. Empty sections are noise in Claude’s context window.

Fix options:

1. Add content to the section

2. Remove the heading entirely

3. Merge with the next section

Before:

After:

5. Wordy trigger phrases

The problem: Unnecessarily verbose descriptions that waste tokens.

Why it matters: Skills load into Claude’s context on every activation. Across thousands of uses, wordier descriptions add up to real token costs.

Common bloat to cut:

• “This skill should be used when” → “Use when”

• “The purpose of this skill is to” → just state what it does

• “In order to” → “to”

• “It is important to note that” → delete entirely

Token impact: A 100-word description vs 50-word description might seem trivial. But if the skill activates 1000 times, that’s 50,000 extra tokens processed.

6. No output format specification

The problem: Skills that produce output but don’t define the format.

What format? JSON? Markdown? Plain text? Claude has to guess.

Why it matters: Without format examples, output is inconsistent. Users end up reformatting every response.

Fix: Include concrete examples with code blocks.

Good examples from real skills:

The deep-research skill documents output clearly:

• Markdown report saved to `research_report_YYYYMMDD_HHMMSS.md`

• Numbered source citations

• Metadata footer with date and model used

7. Contradictory Instructions

The problem: Instructions that simultaneously require and forbid the same thing.

Timestamps are metadata. Which instruction wins?

Why it matters: Claude will follow one instruction and violate the other, leading to unpredictable behavior.

Real contradiction patterns I’ve seen:

• “Be concise” + later “Include comprehensive details”

• “Always use JSON output” + “Return plain text for simple queries”

• “Never modify user files” + “Auto-save results to the project directory”

Fix: Read your skill end-to-end looking for conflicts. Better yet, have someone else review it. Fresh eyes catch contradictions you’ve become blind to.

Pattern to use instead: Be explicit about conditions.

The Skills that got it right

Not everything I validated had issues. Here’s what well-crafted skills have in common.

Clear Activation Triggers

Three specific trigger phrases. No ambiguity.

Structured Workflows

Numbered steps. Clear sequence. Easy to follow.

Concrete examples

From telegram skill:

Troubleshooting

Users know what to do when things break.

Anti-slop writing style

The best skills avoid AI writing patterns:

Bad:

“Furthermore, it’s important to note that the team has potentially made progress on the authentication feature, which may help us move forward.”

Good:

“Authentication feature: 4 of 6 tasks complete. Remaining work blocked on API access; escalated to Platform team.”

No hedge stacking. No filler phrases. Just facts.

Skills with badges

Skills that pass SkillCheck validation can display a badge in their README, like this Planning with Files skill:

Examples of validated skills:

• [SawyerHood/dev-browser] - Browser automation with persistent page state. 3.1K stars. Created by ex-Figma, ex-Facebook engineer.

• [mrgoonie/claudekit-skills]() - ClaudeKit collection. The `code-review` skill’s principle: “Technical correctness over social comfort.” 1.4K stars.

• [glebis/claude-skills] - Collection of productivity skills (Telegram, PDF generation, deep research)

• [SkillCheck] - The validator itself, eating its own dogfood

• [anthropics/skills] - Anthropic’s official skill examples

I also repackaged/remixed Carl Vellotti’s Nano Banana course into a Claude Code skill for my own workflow. It wraps Gemini’s image generation with style libraries and multi-turn refinement. If you’re looking to build image generation skills, Carl’s course is a great starting point!

Try it yourself

I built SkillCheck to catch these issues automatically.

Free tier

Validates against the agentskills.io specification:

• Frontmatter structure (name, description, required fields)

• Naming conventions (format, reserved words, specificity)

  Semantic consistency (contradictions, output format, clarity)

Install by copying to your skills directory:

bash

git clone https://github.com/olgasafonova/SkillCheck-Free.git

cp -r SkillCheck-Free/skill-check ~/.claude/skills/

Then say “skillcheck my skill” in Claude Code.

GitHub: github.com/olgasafonova/SkillCheck-Free

Pro tier

Adds deeper analysis via MCP server:

• Anti-slop detection - Catches AI writing patterns (em-dash abuse, hedge stacking, filler phrases)

• Security scanning - Detects hardcoded secrets, PII in examples, unsafe paths

• Token budget analysis - Warns when skills exceed optimal size

• WCAG accessibility - Validates color contrast for visual-output skills

• Enterprise readiness - Checks for hardcoded paths, env configuration

Get it at getskillcheck.com

Turns out, Tove Jansson’s characters map perfectly to agentic AI architecture.

Claude Code ships with six primitives. The documentation explains the syntax. It doesn’t explain the behavior. And behavior is what matters when you’re building workflows. Each primitive has a personality. Once you understand the personality, you stop fighting the tool.

Skills

Skills are Moominmamma. Markdown files Claude loads automatically based on context. Two locations: ~/.claude/skills/ for global, .claude/skills/ for project-specific.

No explicit invocation. Claude scans available skills and injects relevant ones. The matching happens through semantic similarity, not keywords. A skill about “database migrations” might activate when you mention “schema changes.”

Inside a skill file you put coding standards, API patterns, decision trees, domain terminology, code snippets. Whatever you’d normally have to repeat every conversation.

The trap: skills consume context window. Load too many and you crowd out room for actual work. Keep them focused.

Moominmamma is always present with the right knowledge at the right time. She never needs to be asked. Her handbag contains everything you might need; bandages when someone falls, warm blankets when guests arrive. You reach for something and it’s already there. Stock your skills/ directory well. Claude surfaces the right knowledge without prompting.

Subagents

Subagents are The Snork. Spawned Claude instances with isolated context windows. Created via the `Task` tool:

The subagent gets its own context. Doesn’t see your full conversation history. You pass specific inputs; it returns structured outputs. Parent conversation stays clean.

Why this matters: context windows are finite. A long debugging session pollutes context with stack traces, failed attempts, dead ends. Subagents let you offload deep work without the residue.

Tool scoping works here too. A “research” subagent might only get web search and file reading. A “refactor” subagent gets file editing but no shell access. Control the blast radius. Built-in types include `Explore` for codebase navigation, `Plan` for architecture design, `Bash` for command execution.

The Snork works on specific inventions and technical problems. Has his own workshop (isolated context). You give him a problem: “Build something that flies.” He disappears into his workshop, works independently, returns with a working solution. Task-oriented isolation beats philosophical isolation. The Snork actually ships thgs.

Hooks

Hooks are The Hemulen. Shell commands that execute deterministically on lifecycle events. Zero LLM involvement. Pure automation. Configured in .claude/settings.json:

Events: PreToolUse, PostToolUse, Notification, Stop. Execution is synchronous; blocks until complete.

Use cases I’ve found useful: audit logging for compliance, secret scanning before commits (saved me twice already), auto-formatting after file edits, notifications when long tasks finish.

The trap: over-hooking kills velocity. Every hook adds latency. Every validation adds friction. Use them for genuine guardrails, not bureaucratic checkboxes.

The Hemulen is obsessive, rule-following, deterministic. Collector of stamps, plants, butterflies. Tell him “sort these by date” and he will, perfectly, every time. Ask him to “use your judgment” and he freezes. Essential for order. Exhausting in excess.

Slash Commands

Slash Commands are Little My. User-triggered actions via /command. Defined as markdown files in .claude/commands/:

Invocation: /deploy staging

Key distinction from skills: skills activate automatically based on context. Commands activate explicitly based on user intent. Skills are background knowledge. Commands are foreground actions.

I have commands for /today, /weekly-update, /create-test-plan. A 10-word invocation expands into a 500-word instruction set. Huge time saver.

Little My is explicit, direct, invoked on purpose. Smallest but fiercest. She doesn’t hover in the background; you call her name and she acts immediately. Sharp, effective, no-nonsense. Won’t act unless asked. But when asked, acts without hesitation.

MCP Servers

MCP Servers split into two personalities. Model Context Protocol connects Claude to external tools and data sources. Configured in .claude/settings.json:

Local (stdio) is Sniff. Local process, stdin/stdout communication. Millisecond latency, no network dependency. File system operations, local database queries, system scripts. Security note: local MCP servers run with your user permissions. They can access anything you can access. Vet your servers.

Sniff never leaves Moominvalley. Eager fetcher, quick data lookups, always nearby sniffing for treasure. Quick fetches, immediate returns, no network delay.

Remote (HTTP/SSE) is Snufkin. Network calls with optional Server-Sent Events for streaming. 100ms-2s latency typical. GitHub, Notion, Slack, Stripe. Any REST/GraphQL API with an MCP wrapper. The Azure DevOps MCP server has become my go-to for work item management. No more context-switching to the browser. Moreover, I’ve built a few extra open source MCP servers for myself and my teams - MediaWiki MCP, ProductPlan MCP and Miro MCP server.

Snufkin wanders far from Moominvalley, returns seasonally. Worldly connector, brings rich experiences from distant lands. You wait a bit longer, but he returns with treasures from places you’ll never visit yourself.

Plugins

Plugins are Moominpappa. Distribution bundles combining skills, commands, hooks, and MCP configs:

One install, complete functionality. Instead of documenting “install these 5 things and configure them this way,” you ship one artifact. Onboarding drops from an hour to a minute. Teams share workflows: everyone gets the same coding conventions, deployment commands, guardrails.

Moominpappa packages adventures into memoirs and expeditions into shareable formats. His “Memoirs” are essentially a plugin manifest: curated, versioned, ready for others to install.

Claude Code

Claude Code itself is Moomintroll. The runtime orchestrating all primitives. Loads skills based on context, spawns subagents, fires hooks, routes commands, maintains MCP connections.

Without it, primitives are inert. Config files waiting for execution.

Moomintroll is the protagonist; everyone orbits around him. Curious, kind, occasionally anxious. He doesn’t have a single special power. He brings characters together, mediates their quirks, makes the valley feel like home. Without him, the characters are scattered individuals. Without Claude Code, the primitives are just config files waiting for someone to run them.

One more character: The Groke is prompt injection.

Attacks that attempt to override Claude’s instructions through malicious input. An attacker embeds commands in user-supplied data; files, API responses, form fields. The OWASP LLM Top 10 lists it as the #1 vulnerability for LLM applications.

The Groke freezes everything she touches. Lonely, desperate for warmth, but destructive. She doesn’t mean to destroy. But her nature makes her dangerous. The Groke is why you don’t trust arbitrary input blindly.

Stock Moominmamma’s handbag with domain knowledge. Give The Snork problems worth isolating. Let The Hemulen enforce your actual rules, not imaginary ones. Make Little My’s commands worth calling. Watch for The Groke.

The primitives are just config files until you understand their personalities. Now you do.

Share

I wish I was joking. Classic “let me google that for you” moment, except it’s 2025 and that wiki has 6500+ pages and a decent search.

So I did what any reasonable person would do: I spent a week building an MCP server so Claude Code could search the wiki instead of me. Problem solved. Colleagues can ask Claude Code now. I’m free.

This is my second MCP server in two weeks. December is officially “connect everything to AI” month. I might need an intervention. Or a Claude Code Max subscription as a Christmas present. Or both!

What I actually built

MediaWiki MCP servers already exist. I checked. But none of them did what I needed:

• ProfessionalWiki (⭐45) - TypeScript, ~12 tools, CRUD operations, OAuth2, npm install > https://github.com/ProfessionalWiki/MediaWiki-MCP-Server

• shiquda (⭐15) - Python, 3 tools, Search + read (archived), https://github.com/shiquda/mediawiki-mcp-server

• punkpeye/wikimedia (⭐9) - Python, 6 tools, Wikimedia APIs only, https://github.com/punkpeye/wikimedia

• entanglr (⭐1) - Python, 10 tools, Bot user auth, basic ops, https://github.com/entanglr/mediawiki-api-mcp

• Mine (⭐0 🥲 - so far?) - Go, 40+ tools, Everything below 👇, https://github.com/olgasafonova/mediawiki-mcp-server

I wanted broken link detection. Terminology checking against our brand glossary. Orphaned page finder. Markdown conversion with company colors. HTTP transport so it works with ChatGPT and n8n, not just Claude.

None of the existing servers had that all. So I built one. In Go. Because when a language is literally named “go,” the universe is telling you something. go build and off you go.

The security rabbit hole I didn’t expect

Here’s something that didn’t make it into my ProductPlan MCP article: security.

ProductPlan’s API is well-behaved. You authenticate, you get data, done. MediaWiki is... different. It’s a 20-year-old platform that powers Wikipedia. The API surface is massive. And my link checker tool needed to fetch arbitrary URLs to verify they still work.

Day 3, Claude Code flagged this: “Your link checker has no SSRF protection. Someone could use it to scan internal networks.”

Oh.

I’d built a tool that could be tricked into hitting http://192.168.1.1 or http://localhost:8080. Not great.

So I went down the security rabbit hole:

• SSRF protection: Link checker now blocks private IP ranges, localhost and link-local addresses

• Request size limits: Bodies capped at 2MB. No memory bombs.

• Input validation: Page titles get sanitized. No injection attempts getting through.

• Rate limiting per IP: HTTP transport won’t let one client hammer the server

• Security headers: CSP, X-Frame-Options, the whole paranoid checklist

Claude Code caught issues I would’ve shipped. Security scanning tools (gosec, govulncheck) caught more. Not glamorous work. But shipping a tool that could scan someone’s internal network? Not an option.

40 tools, one decision tree

With ProductPlan, I learned that too many tools confuse the AI. Started with 58, consolidated to 15. Lesson learned.

MediaWiki was different. I actually needed 40+ tools. The API is that complex. But I couldn’t just dump them on Claude and hope for the best.

So I spent hours in the garden on decision trees:

Plus example mappings, common mistakes to avoid, and our company wiki’s editing guidelines embedded directly in the server instructions.

This is what made the difference. Without guidance, Claude used the heavy mediawiki_edit_page for simple text changes, fetching and rewriting entire pages. With guidance, it picks surgical tools first. Neat!

Context engineering isn’t an afterthought. With ProductPlan, I learned this by breaking things. With MediaWiki, I applied it from day one.

What’s actually in those 40+ tools

Here’s the breakdown:

• Read operations (12 tools): search, get_page, get_sections, get_related, get_images, list_pages, list_categories, get_category_members, get_page_info, get_wiki_info, list_users, parse

• Link analysis (5 tools): get_external_links, get_external_links_batch, check_links, find_broken_internal_links, get_backlinks

• Content quality (3 tools): check_terminology, check_translations, find_orphaned_pages

• Content discovery (2 tools): find_similar_pages, compare_topic

• History (4 tools): get_revisions, compare_revisions, get_user_contributions, get_recent_changes

• Quick edit tools (5 tools): find_replace, apply_formatting, bulk_replace, search_in_page, resolve_title

• Write operations (2 tools): edit_page, upload_file

• File search (1 tool): search_in_file (PDFs and text files)

• Conversion (1 tool): convert_markdown

Each tool has specific parameters, validation, and error handling. The find_replace tool alone has: page title, find text, replace text, preview mode, replace_all flag, regex support, and edit summary.

The README problem (17 rewrites later)

Two audiences: developers who want go build commands, and everyone else who wants it to “just work and read my mind too, thank you very much!”

The README went through seventeen rewrites. Seventeen. Each version got simpler. Or so I hope.

Rewrite 1: “Clone the repository, install Go 1.21+, run go build...”

Rewrite 17: Download. Paste three lines. Restart Claude.

Pre-built binaries for Mac (Intel + Apple Silicon), Windows, Linux. Platform-specific config examples. Troubleshooting section for the three things that actually go wrong.

The goal: someone who’s never opened a terminal should have this running in 5 minutes. I tested this on a colleague. Timed it. 4 minutes 23 seconds. Success.

(The irony of spending more time on docs than on several features combined isn’t lost on me - reminds me of a quote from old soviet cartoon “Wings, legs & tails“ - “it’s better to loose one day and then fly over in 5 minutes”).

What’s different from ProductPlan MCP

Two MCP servers in two weeks. Same tools, same approach, different lessons:

ProductPlan taught me: Context engineering matters. Too many tools break AI reasoning. Consolidate ruthlessly.

MediaWiki taught me: Security can’t be an afterthought. Corporate wikis handle sensitive data. SSRF protection, input validation, rate limiting. The unsexy stuff that keeps you out of trouble.

ProductPlan: 58 tools → 15 tools. Subtraction.

MediaWiki: 40+ tools, but with surgical decision trees. Addition with guidance.

ProductPlan: API is modern, predictable, well-documented.

MediaWiki: API is 20 years old, sprawling, occasionally surprising. Required more defensive approach.

Same pattern though: identify tool I use daily, get frustrated with context-switching, build a solution. Ship fast. Iterate based on real feedback.

The stuff I repurposed

The Markdown-to-MediaWiki converter? I built that three weeks ago as a CLI tool - https://github.com/olgasafonova/md-to-mediawiki-plus. Different project entirely. But when I needed wiki conversion in the MCP server, I just... ported it over. Added theme support (Tieto brand colors for internal docs, neutral for clean output, dark mode for wikis that support it).

Building things compounds. Today’s side project becomes next month’s feature.

7 days, 17 releases, 50 commits

Every commit co-authored with Claude Code.

Claude handled Go syntax I didn’t remember (or didn’t know - yet!), MediaWiki API lookups, security recommendations, test generation, and README rewrites 1 through 17.

I handled deciding what to build, testing against our actual wiki, prioritizing UX, writing the AI guidance, and hitting “publish release” way too many times.

I’ve written maybe 200 lines of Go before this project. All of it was copying examples from documentation and hoping they worked.

Claude Code made Go feel accessible. Not easy - I still don’t fully understand channels or goroutines - but accessible enough to build something real.

The pattern was always the same:

1. Describe what I wanted in plain English

2. Claude Code generates Go code

3. I read the code, ask questions about parts I don’t understand

4. Make adjustments based on testing

5. Commit

By day 7, I could read most Go code without help. Writing it from scratch? Still no. But reading, modifying, debugging? Yes.

That’s the real story of “AI pair programming.” Not that the AI writes everything. But that it lowers the barrier enough to actually ship. Like a pair programming with a very fast developer who’s read every API doc ever written and never needs coffee breaks. Still feels surreal.

Try it

Open source, MIT license: https://github.com/olgasafonova/mediawiki-mcp-server

Works with any MediaWiki wiki: Wikipedia, Fandom, corporate installations. Claude Code, Claude Desktop, Cursor, VS Code + Cline, ChatGPT, n8n, Google ADK.

Setup: 5 minutes. Reading is free. Editing needs a bot password from your wiki admin.

If you have a wiki you’re tired of navigating manually - this might help. And if your colleagues keep asking you to “just search the wiki” for them - definitely try it. Redirect them to Claude or Cursor. Reclaim your time.

If you’ve worked in analytics or product for more than a decade, you’ll remember Omniture. That thing was so infamously slow, I still say “Ommmm-niture” when I’m forced to wait for any tool to load - part meditation, part desperation. Adobe’s 2009 acquisition didn’t make things much faster, but it gave us something to chant while staring at spinning wheels and watching our patience evaporate - Tobias Johansson , Max Sayganov , Shakhboz Sidikov might even still remember that from our Saxo Bank times together ;)

For years, bad performance was a running joke, and for good reason. Who hasn’t shared the “skeleton at the computer” meme or muttered about the “World Wide Wait” as another progress bar froze at 99%?

But somewhere between web 1.0 and now, product teams, UX designers developers, and even Google got tired of this. Enter the Core Web Vitals initiative - Google‘s push to turn that shared suffering into measurable, enforceable standards. LCP (Largest Contentful Paint), CLS (Cumulative Layout Shift), and INP (Interaction to Next Paint) became our new commandments, their numbers tied directly to SEO, conversions, and (let’s be honest) annual reviews. Viktor Petersson and I even been writing some blog posts back then - oh what a trip down to a memory lane at Siteimprove! :)

Yet, as soon as these standards dropped, we discovered that not only did most of the web fail - including Google’s own products - but that slow, unresponsive, or visually janky pages would still haunt us, regardless of what metric we chased.

And just when we thought we were getting a handle on it, #AI happened - and waiting got even more complicated.

The new AI waiting game: Perplexity, TTFT, & the Generative UI tsunami

Let’s talk about what’s happening right now with AI-native interfaces and why “perceived speed” has become more complex, fragile, and - if you’re not careful - meme-worthy than ever.

Let’s just have a look at some recent stuff - Perplexity introduced a new browser Comet. You open a site, and before the “real” page even loads, the browser’s built-in LLM is already summarizing content or suggesting next steps. This is the first mainstream “browser” that’s as much an AI agent as it is a window to the web. Now, instead of LCP (or FCP, First Contentful Print), the key experience is: how fast does the AI give me something useful? That’s where TTFT (Time to First Token) comes in - essentially, how quickly the AI can generate the first sign of intelligence on the page.

It’s early days for Comet - meaning the thingie is rough at the edges (sorry, Microsoft, no pun intended!) - but here’s one of the first reviews at The Verge (note “Comet can buy stuff for me on Amazon and declutter my inbox - but it takes a minute“ there ;))

If TTFT is high, you’re staring at a blank AI box or, worse, a blinking “thinking…” indicator, reminiscent of the old loading spinners but with a side of artificial anticipation.

Users don’t separate “web loading” from “AI thinking.” If there’s a pause, it’s just “waiting” - and if there’s enough waiting, it quickly becomes “rage clicking,” a term firstly introduced by Heap | by Contentsquare (i believe), but now widely adopted by tooling like Sentry or Amplitude

But it gets even trickier. With tools like Vercel v0 or Lovable , we’ve entered the world of on-demand UI generation. Now, the UI itself doesn’t even exist until an LLM spits out the code in real-time.

It goes kinda like this: the user asks for a dashboard, the model has to understand, compose, and generate components on the fly, then stream them to the browser where React (or whatever framework you’re using) renders them as they arrive. The “first contentful paint” for the user is now a direct function of the LLM’s inference pipeline.

Here’s where the pain starts:

• Inference delay: Large models are heavy. If you’re running in the cloud, you hit batching, queuing, and cold starts. If you’re running locally (say, on a shiny Copilot+ PC with a new NPU or using Ollama for edge LLMs, you’re suddenly worried about device heat, battery life, and whether your AI is hogging the GPU, leaving no cycles for actual UI rendering.

• Prompt-to-paint becomes a UX battleground: You can no longer just optimize the frontend in isolation; you need to monitor, trace, and accelerate everything from the LLM’s prefill time, to token streaming, to how quickly the browser can render partial UI as it arrives.

• Streaming ≠ Solved: Even if you stream tokens or UI components as soon as they’re generated, you’re back to classic progress-bar psychology. If users can’t interact or see real feedback almost instantly, you’re on the wrong side of the “World Wide Wait” meme.

Users’ expectations haven’t gotten more patient - if anything, they’re even higher. If AI can write code and summarize documents, why does it take so long for a simple answer or UI to show up?

I’ve heard jokes in like “Is my AI re-reading the entire internet before it tells me how to center a div?”

Why Product, UX, and Engineers all need to care (and more than ever, really)

The old rules - track bounce rates, measure FCP, optimize image size - are now only half the story. Now, you have to combine your Core Web Vitals monitoring with deep LLM observability: TTFT, tokens-per-second, model prefill latency, and the “prompt-to-interactive” time that users actually feel. If you’re not careful, you’ll optimize your Lighthouse score but still deliver a laggy AI interface and leave users hammering away in frustration.

What’s wild is that rage clicks and waiting memes are now cross-context. we can track rage clicks in our product analytics dashboards, but we have to diagnose why these rage clicks are happening: Is the AI slow? Is the UI blocked by inference? Did something just break? Is the user left staring at a blank chat window? All of it counts.

Some teams are actually designing clever “AI is thinking…” loaders, or playful messages (“Aligning quantum neurons…,” “Bribing the GPU…”) - but let’s be honest, if the user has time to read them all, you’ve already lost. That’s why you now you might see companies benchmarking “prompt-to-paint” as a composite metric, merging TTFT, LCP, INP, and more - because only the end-to-end speed matters.

What’s next: building for speed (and sanity) in the AI world

If you want your product to avoid becoming the next meme, you can’t just chant Ommmm-niture and hope for the best. You need a practical, cross-functional approach:

• Look at your data: Combine Core Web Vitals with new AI performance telemetry. If you don’t know your TTFT, streaming latency, and “user-visible” times, you’re flying blind.

• Design for progressive feedback: Show partial results, use real streaming, and never let the user feel lost. The moment you leave them staring at a blank box, you’re inviting a rage click (and possibly a joke at your expense).

• Fast isn’t always better, unless it feels trustworthy: There’s still a fine line; some tests show users mistrust instant payment approvals, but for everything else, slow is just slow. Sometimes healthy friction is by design.

• Be humble If you think you’ve solved performance, check your rage clicks. Get real people use your product and observe them in the “wild”. The skeleton meme might be closer than you think.

So yes, the stack got more complicated. But the basics - respect the user’s time, optimize for real perceived speed, and don’t become a running joke - are more relevant than ever.

I still meditate with “Ommmm-niture” in the back of my mind. But today, I’m chanting for faster inference, smoother UI streaming, and analytics that catch rage before it goes viral. Let’s build the kind of experience that users don’t need to laugh at - unless we’re all just laughing at how fast it is now.

That model just died.

Why the old way fails

The relay-race approach worked when you were building deterministic features. You could spec everything upfront because you knew exactly how it would behave. Click button A, get result B. Every time.

AI changed that equation completely.

Trying to spec AI behavior upfront is like writing a script for a conversation that hasn’t happened yet. AI models learn patterns from training data. What they do emerges from that learning, not from specifications you write. You won’t actually know how your AI feature responds until you build it and watch it run with real data (and do your evals). No amount of upfront planning gives you that clarity.

The interface isn’t the experience anymore. Many successful AI products have minimal UI, sometimes just a text box and output. A Figma mockup can’t capture an LLM’s personality, the nuance of its responses, or the flexibility of an AI agent’s decision-making. The “how it works” is the UX now.

Waiting for perfect requirements means never shipping. With AI, clarity only comes from building and observing. If you insist on complete specifications before coding, you’ll be stuck in planning while competitors ship, learn, and iterate.

What happens when you try anyway

Here’s what the traditional process looks like in practice:

Research discovers something, design interprets it, PM documents it, dev implements it.

By the end, what you built bears little resemblance to what anyone started with. Like that party game where “His heart stopped when she walked in” becomes “Video killed the radio star” after passing through five people.

Each handoff introduces noise. Details disappear. Assumptions change. Nobody remembers the original point.

Here’s what’s actually happening in your brain: every context switch costs you 20% of your cognitive capacity. When someone interrupts you, it takes 23 minutes to get back to where you were.

Multiply that across a relay race of handoffs.

The researcher who talked to users has moved on to the next study. The designer translating research into screens is recreating the problem from notes. The PM writing specs is working from screenshots and memory. The developer building it is interpreting interpretations.

Nobody’s brain contains the original problem anymore. Everyone’s working from fragments, burning energy just trying to reload context. You’re not losing information because people are careless. You’re losing it because human working memory can’t survive four handoffs.

The team isn’t thinking. They’re context-switching.

A PM coach I spoke with recently, Richard Russell, put it perfectly: “Teams have ADHD.” Not the clinical diagnosis, but the same pattern. Constantly switching focus, never finishing, chasing the next shiny thing.

One day you’re building the AI feature. Next day there’s an urgent customer request. The day after that, leadership wants a prototype of something else. By Friday, you’ve touched five things and finished none of them. Every switch resets the clock. Every restart burns energy reloading context.

The backlog grows. The team gets slower. Everyone’s busy but nothing ships.

Traditional management makes it worse. More meetings to “align.” More updates to “stay coordinated.” More process to “ensure quality.” Each one is another context switch. Another interruption. Another 23 minutes lost.

Then there’s the admin theater. Teams chase vanity metrics like ticket throughput, closing and reopening the same work sprint after sprint. The original ticket didn’t get finished, so someone creates a new one. “Copy of Sprint 47 ticket.” Then “Copy of Copy of Sprint 47 ticket.” The chain grows longer. The original context disappears.

Nobody remembers why you started building this feature. The ticket says “implement user authentication” but the reasoning, the customer problem, the constraints? Gone. Lost somewhere in the chain of copies.

Call it what it is: busywork pretending to be process.

(Worth noting: Richard Russell is running something interesting for PMs dealing with exactly this problem. If you’re curious, speak with Richard - and check this out.)

The final product becomes a convenient fiction rather than what users actually need. Everyone points fingers when it fails because nobody owned the whole thing.

Even worse, when you lead with mockups, users can only comment on what they see. The AI behavior, the part that actually matters, stays invisible. You’re asking them to choose wallpaper colors while the building collapses around them. They’ll give you opinions about colors, but they can’t tell you anything about whether the structure underneath actually works.

Research becomes theater. Validating the trivial, ignoring the critical.

The isolation problem

Your developers are working hard. Building the wrong thing.

Isolated teams become their own Death Star. Sealed off from everyone else. Ideas can’t get in, usable software can’t get out, and sooner or later the whole thing blows up in spectacular fashion.

Devs optimize scores. Designers polish pixels. Nobody asks if it solves the problem. In AI products, the experience and the implementation are the same thing. You can’t design one without building the other. Everyone on the team needs to understand enough context to ask the right questions.

The numbers tell the story: studies show 80%+ of AI projects fail, twice the failure rate of non-AI technology projects. Recent research from S&P Global Market Intelligence found that 42% of companies abandoned most of their AI initiatives in 2025, up from just 17% in 2024. The average organization scrapped 46% of AI proof-of-concepts before they reached production.

Look at the expensive disasters:

IBM’s Watson for Oncology burned through $3 billion to produce unsafe, incorrect treatment recommendations. The system was trained on hypothetical patient data rather than real cases. Doctors on the project called it unusable for most patients, and MD Anderson spent $62 million without achieving their goals.

McDonald’s AI drive-thru was abandoned in 2024 after three years of working with IBM. The system couldn’t reliably take orders, leading to frustrated customers and employees.

Air Canada’s chatbot cost the airline over $800 in damages (and significant reputational harm) when it gave a passenger false information about bereavement fares. A court ruled the airline was responsible for what its chatbot told customers.

New York City’s MyCity chatbot falsely claimed that business owners could take workers’ tips, fire employees who complained of sexual harassment, and that landlords could discriminate based on income. The chatbot remains online despite the errors.

Same root cause every time: teams applied siloed, sequential thinking to AI problems. They designed in isolation, built in isolation, tested too late. By the time real users touched the product, it was too late to fix fundamental issues.

A different approach

So what actually works?

Everyone (PM, designer, developer, data scientist) works together from the start. Build something that works. Test it with real people. Learn. Repeat.

Think of it like building in layers around a core. You start with a solid core and add layers around it. The product grows with each addition, shaped by what actually works in users’ hands.

In AI products, the experience and the implementation are the same thing. You can’t design one without building the other.

Start with the core: data structures, not decoration

Here’s where you build the core: with your data.

Your first prototype shouldn’t have traditional UI at all. Instead of starting with visual design, start with the data structure itself.

Ravi Mehta, former CPO at Tinder, demonstrated this approach on the How I AI podcast by Claire Vo. Define your data as JSON first, then let AI generate the interface around it. Not the other way around.

When you start with a JSON data model, you’re forcing yourself to think about what information actually matters. What fields does a user profile need? What properties does each product have? What relationships exist between entities?

The process looks like this:

First, define your data structure, eg in JSON. If you’re building a case management system:

{
  “case”: {
    “case_id”: “SOC-2025-4721”,
    “citizen_cpr”: “010185-****”,
    “case_type”: “Hjemmehjælp”,
    “status”: “under_behandling”,
    “caseworker”: “Mette Hansen”,
    “submitted”: “2025-09-28”,
    “assessment_deadline”: “2025-10-12”,
    “municipality”: “København”,
    “priority”: “normal”
  }
} 

Then use Claude or another LLM to generate realistic sample data based on that structure. Not just one record, but dozens with realistic variations. Different case types, varying deadlines, multiple municipalities, different priority levels.

Finally, feed that JSON into a prototyping tool like Lovable , Cursor or even just Claude itself to generate a working interface. Now you’re testing with data that actually reflects reality: case IDs that need proper formatting, deadlines that test your date handling, status values that challenge your workflow logic.

This approach has three major advantages over traditional prototyping:

You’re working with real data patterns, not lorem ipsum. Designers and PMs can see immediately how their concepts hold up against actual content variations.

You can adjust and regenerate in minutes. “Actually, we need to track which documents are missing for each case... let me add that field and see how it changes the UI.” Try doing that with static mockups.

You get something functional you can test with users immediately. Not opinions about wallpaper colors but actual feedback on whether the data structure supports their needs and whether the AI outputs are useful.

Companies using this approach have validated concepts with hundreds of users before creating a single mockup. One example from Mehta’s work: using Claude with an existing FAQ database to prototype a customer service solution, then testing it with users to validate the core concept before investing in custom UI. Another case involved using GPT-4 with a company’s product catalog to prototype a shopping assistant that generated pre-orders before any interface design work began.

Before you touch the visual design, you’ve already answered the hard questions: Does this solve the problem? Do users find it useful? Does the flow work? You can adjust the data model and regenerate the prototype in minutes.

You nail down the things that matter (what data you need, what the AI should do with it, what “good” looks like) while competitors are still arguing over button colors and playing telephone with requirements.

Building the layers

Once you have that data-first core validated, you start adding layers around it:

Layer 1: Get it in front of users immediately. As soon as you have something that runs, show it to real people. Their feedback shapes the next layer.

Layer 2: Keep artifacts lightweight. Skip the 50-page spec. Make quick sketches, simple diagrams, one-page summaries. Document just enough to keep everyone aligned, then get back to building.

Layer 3: Build in testing as you go. Every time you add data or tweak a model, add evaluation metrics to track it. Don’t bolt quality on later.

Layer 4: Iterate for clarity. Every requirement is a hypothesis until you test it. Questions about behavior? Build something and watch what happens.

The key is that everyone stays together through this process. No handoffs. Work as one team. Assign tasks by skills, not titles. When something fails, you all own it. There’s no “hole on the other side of the boat.”

Keep everything balanced. Don’t let data race ahead of the interface, or vice versa. They need to inform each other continuously.

Decide fast, adjust often. If you can reverse a decision, make it now. If it’s truly one-way, get input, decide, and commit fully.

Each iteration builds on what you learned from the last one. Keep what works, fix what doesn’t, move forward.

What this means for your job

You still need designers, PMs, developers, and data scientists. But the work looks different now.

For designers: understanding JSON doesn’t require becoming a developer. You need to understand the building blocks your designs will work with. When a developer says “this is what the API returns” and shows you a JSON structure, being able to read it immediately improves your collaboration. With AI prototyping tools, designers can translate vision directly into functional prototypes. The market is already responding. Designers who can work across the stack command higher salaries and bigger roles.

For product managers: your PRDs and requirements docs are becoming prototypes themselves. Instead of writing lengthy specifications that get misinterpreted, you’re building working examples that demonstrate exactly what you mean. You’re still defining what to build and why, but now you’re showing it rather than just describing it. The fastest PMs are using AI to turn their product ideas into clickable prototypes in hours, not weeks.

For developers: you’re no longer isolated waiting for perfect specs that never come. You’re involved from day one, shaping the data structures and technical approach while the product concept is still forming. Your expertise in what’s actually feasible with AI isn’t locked away until implementation. It’s informing decisions from the start. You’re building alongside everyone else, not after everyone else.

For data scientists: your work isn’t bolted on at the end to “add AI” to a finished product. You’re at the table from the beginning, helping define what data you need, what’s realistic to achieve, and how to evaluate whether the AI is actually working. Your models aren’t developed in isolation. They’re shaped by real user feedback from the first prototype onwards.

The common thread: everyone needs to understand enough about the other disciplines to have informed conversations. You don’t need to be an expert in everything, but you can’t hide behind role boundaries anymore.

Teams that make this shift are shipping products 10× faster than those clinging to the old model. They’re creating working prototypes, testing with real users, and iterating in hours instead of weeks.

None of this applies to my org

Maybe your situation looks nothing like the clean scenarios above. Maybe you don’t have researchers. Your “requirements” come from sales calls, tender documents, and a backlog of customer requests from five years ago. Your codebase is a patchwork of custom solutions built by developers who have long since left. Nobody knows what half of it does anymore.

This is where most organizations actually are.

Here’s the hard truth: you can’t build AI products on top of chaos. You can’t add “AI features” to a system nobody understands. You can’t ship fast when every change risks breaking something else.

The impulse is to add more process. Write better requirements. Document everything. Create governance frameworks. Hire consultants to map your technical debt.

That makes it worse.

What you actually need is radical simplification. Start by admitting three things:

First: your backlog is lying to you. Those five-year-old feature requests aren’t requirements. They’re artifacts of conversations nobody remembers with customers who may not even be customers anymore. The context is gone. The problem has changed. Delete most of it.

Second: your legacy code is an anchor. Every line of code you don’t understand is a liability. Every custom solution built for a specific customer five years ago is slowing you down today. You can’t “modernize” it. You need to replace it, piece by piece, with something simple enough that your whole team can understand it.

Third: tender specifications aren’t product strategy. When your product direction comes from whatever customers put in RFPs, you’re not building a product. You’re building custom solutions one at a time. That doesn’t scale and it definitely doesn’t work with AI.

So what do you do?

Stop starting new things. Pick one actual problem (not a feature request, a problem) that matters to multiple customers. Build the simplest possible solution. Get it in front of users. Learn from it. Only then move to the next thing.

Start with data, not features. Before you add AI to anything, understand what data you actually have. Not what you wish you had. What’s actually there, what quality it’s in, whether it’s even useful. Most legacy systems are drowning in data they can’t use and missing the data they need.

Kill the handoffs in one place first. You can’t transform your whole organization overnight. Pick one small team, one small problem. Let them work together from start to finish. No throwing requirements over the wall. No “waiting for dev capacity.” Just let them build something simple that works. When it succeeds, others will notice.

Make decisions reversible. Your legacy codebase is full of irreversible decisions. Every new thing you build should be easy to undo, easy to replace, easy to understand. Small, simple, modular. If it takes more than a week to explain how something works, it’s too complicated.

The goal isn’t to fix everything. The goal is to stop making it worse while you build new things the right way.

Leaders in organizations like this face a choice: keep adding complexity to manage complexity, or start cutting through it. The first path is comfortable and leads nowhere. The second path is uncomfortable and works.

Most of your competitive advantage is buried under accumulated cruft. The companies that will win are the ones willing to dig it out.

So what now

The traditional relay-race model is dead. Teams that work in silos will keep shipping products nobody wants.

Teams that build together (starting with real data structures, working as one unit, testing constantly, and focusing on actual working software) will win.

You win by having data nobody else has and learning from users faster than anyone else can.

The choice isn’t whether this shift happens. It’s whether you adapt to it or get left behind.

Working code beats bullshit. Every time.

Start tomorrow: Pick one team. One problem. Let them work together for two weeks with no handoffs. See what happens.