This piece answers the natural follow-up: what is being scored, and how.

57 is not low because the rubric is harsh. It’s what falls out when you score a skill against twenty-five check categories assembled over five months from fourteen named sources. The methodology page documents all of it. This is the narrative version.

Phase I: foundation checks

I started building SkillCheck in December 2025. Ten check categories. Four trace directly to the agentskills.io specification: structure, body, naming, and token budget. The remaining six categories are mostly my own work, with narrow anchors in external standards where specific rules fit existing patterns.

Visual is half WCAG. Two of its four rules come from WCAG 2.2 (color contrast and alt-text requirements). The other two rules are mine: detecting AI-default purple gradients and generic-font usage. Technical (the category that catches secrets, injection risks, PII, version pinning, and a few other production hazards) borrows one rule from MCP best practices, specifically the protocol-version requirement. The other six technical rules are mine.

Semantic consistency, anti-slop pattern detection, quality patterns, and enterprise readiness are entirely mine. Together with the parts of visual and technical I wrote myself, that’s most of Phase I.

This was the version that caught the lowest-hanging fruit. A SKILL.md without a description field. A markdown body that ran past the recommended 5000-token mark. A naming collision with a built-in skill. The published spec said these were problems, and v1.0 said so deterministically.

That version did its job. What it didn’t do was catch the things I actually wanted it to catch.

Phase II: what production teaches you

Three months later, in March 2026, I added eight more categories based on what I was learning from running checks across my own portfolio. Quality Pro covered the deeper structural patterns that the spec didn’t name. Workflow covered what the skill actually does in production, which often differs from what its description claims. Reference integrity. Eval readiness. Orchestration safety. Autonomy boundaries. Composability. Observability.

These are the categories that nobody writes a spec for, because they only become visible after you’ve shipped a few skills and watched them collide. A skill that passes every Phase I check can still fail in production because its trigger words overlap with another skill, or because it claims to be deterministic and isn’t, or because it loads three reference files when one would do. Phase II is what showed up in audit logs after Phase I shipped clean skills into the wild.

Phase III: the field reports

In April 2026 I added three more categories from observed failures and two pieces of cross-lab methodology. Design pattern classification, because the same skills kept being miscategorized between “reviewer” and “generator,” and the wrong category leads to the wrong eval. The classification itself (Reviewer, Generator, Inversion, Pipeline, Tool Wrapper) is adapted from Google’s ADK agent-type hierarchy. Trigger collision detection, because skill libraries grow into namespace clashes the way directories grow into deep nesting. Eval kit completeness, because a skill without an eval is a vibe with confidence. The eval-kit category encodes OpenAI’s approach to systematic agent skill testing, which auto-generates should-trigger and should-NOT-trigger prompt pairs.

Each Phase III category was added because a specific failure mode showed up in a specific skill audit and I wanted to never see that failure again. The categories are field reports compressed into deterministic checks, anchored to lab-published methodology where I could find it.

Phase IV: the empirical anchor

Phase IV is one category, knowledge density, and it’s the most empirically grounded check in the whole tool. The principle behind it is simple: when an agent has a list of things to choose from, the words you wrote to describe each thing are what it reads to decide. Vague descriptions get skipped. Precise descriptions get picked. This holds whether the things are MCP tools or skills or anything else with a description field.

Two arXiv papers measured the effect at scale on MCP tools, which is the domain where thousands of measurable examples already exist.

Hasan et al. (arXiv:2602.14878) scanned 856 MCP tool descriptions across 103 servers and found that 97% of them contained at least one description smell, which the authors define as a pattern that makes a tool harder for an agent to select correctly. The paper’s findings shaped several of the rules in SkillCheck’s knowledge density check.

Wang et al. (arXiv:2602.18914) ran a different experiment across 10,831 MCP servers. They measured how often an agent picks the right tool when faced with a list of MCP tools to choose from. Descriptions that followed a standard schema (purpose, when-to-use, when-not-to-use, examples) got picked 72% of the time. Descriptions that didn’t got picked 20% of the time. The fifty-two-point gap is the entire reason knowledge density exists as a category of its own and not a subsection of the body check.

The same mechanism applies to skill descriptions. A SKILL.md whose description doesn’t tell the agent what the skill does and when to use it gets skipped, even when it’s the right skill for the job. Knowledge density is the check category that catches this.

I cite these papers in the methodology page and in the rule descriptions inside the tool itself, because the alternative is to claim I came up with knowledge density on my own. I did not. Hasan and Wang did the work; I encoded their findings.

Phase V: the marketplace year

Phase V arrived in April 2026 with three categories. Agent integration readiness, marketplace governance, memory governance. These are the categories that became relevant when Anthropic shipped plugin marketplaces and built-in memory in late April. Until those features existed, the categories were theoretical. The day they shipped, a thousand skills suddenly needed to declare things about themselves that they hadn’t previously needed to.

Each Phase V category leans on multiple sources. Agent integration readiness prices MCP servers along Sam Morrow’s four axes (token efficiency, security, unique unlocks, execution environment), populated with Anthropic’s six production patterns. Marketplace governance prices plugin marketplaces against Anthropic’s reference schema, with governance requirements (named maintainers, change-gate evals, deprecation paths) the reference itself doesn’t yet ship. Memory governance is design-locked against Anthropic’s managed-agents memory primitives.

Marketplace governance and memory governance will keep evolving for the rest of 2026. Phase V is the phase that will keep moving.

The scoring math

Every check fires at one of three severities. Critical issues subtract 20 points. Warnings subtract 5. Suggestions subtract 1. Every skill starts at 100.

The reason for the asymmetric weighting is calibration against a known reference. A skill with one critical and no warnings should score 80. A skill with four warnings and no criticals should score 80. The math says those skills are equally broken, and in practice that turns out to be approximately true.

The 57 from the opening is what falls out when you run this scoring across the 2,139 community skills SkillCheck scanned in May 2026. The corpus has three rough population shapes. Skills that don’t validate as agent-readable at all score low (multiple criticals, often missing the description field or the frontmatter that the spec requires). Skills that pass Phase I cleanly but break on Phase II categories score in the middle (many warnings about workflow, eval readiness, orchestration safety). Skills that nail the foundation and most of production score high but still drop points on knowledge density or reference integrity. Most of the corpus sits in the middle shape.

What v3.20 actually means in calendar time

The versioning isn’t decorative. Every minor bump corresponds to a category being added or a rule being refined. v3.18.0 was the version that started scanning the public Claude Code ecosystem. v3.20.0 added marketplace governance and memory governance because the marketplace and memory features had just shipped. By the time you read this, there will probably be a v3.21 or v3.22, because the spec landscape is moving fast and a tool that doesn’t move with it is just a snapshot.

The five months between December 2025 and April 2026 are not a long time. They are also not nothing. The categories that exist at v3.20 are the categories that survived being run against real skills, written by real people, in real codebases.

The methodology page is the audit trail

Every category traces back to something concrete. The agentskills.io spec for structure, body, naming, and token budget. WCAG 2.2 for accessibility rules inside the visual category. MCP best practices for protocol versioning inside the technical category. Hasan and Wang on description quality, measured across thousands of MCP tools. OpenAI’s approach to systematic agent skill evaluation. Google’s ADK agent-type hierarchy. Glama’s industry quality benchmark. Sam Morrow’s framework for pricing MCP servers. Anthropic’s production writeups and the memory and marketplace specs they shipped in late April. The audit logs from my own skills that broke in specific ways.

Fourteen named sources informing twenty-five categories. The categories that don’t have a public source (anti-slop, semantic conflict detection, quality patterns, enterprise readiness, and most of the visual and technical rules) come from my own work. The methodology page lists all of it, mapped to the categories it informed.

Skillcheck Methodology Carousel 17 05 2026 V3 Vector

190KB ∙ PDF file

Download

Download

The full version is at getskillcheck.com/methodology.

When you ship a new file format into a developer community, the early adopters tend to read the spec. The crowd that arrives a few months later read other people’s files. By the time the format is famous, half the corpus is cargo-culted off whatever shipped first.

SkillCheck has been scanning the public Claude Code ecosystem since v3.18.0. On 12-05-2026, we ran v3.20.0 against twelve community repos. The scan covers two artifact types that live side by side: the older SKILL.md files Anthropic introduced last year, and the plugin manifests added more recently. Same authors. Same repos. Two different specs.

The plugin layer is in much better shape than the skill layer. That’s the story.

The numbers

The skill scan covered 2,139 SKILL.md files. Average quality score: 57 out of 100. About 86% pass the no-critical-issues bar. About 3% score 81 or higher. The highest single score in the corpus is 92, which means zero skills score in the 93-to-100 band. The floor is 62 skills scoring 20 or below.

The plugin scan covered 178 manifests across seven of the same repos. 91% are clean. There are 17 total issues across the entire set, and they cluster on two checks: 12 plugins are missing the version field, and 5 keep their marketplace.json file in the wrong location.

Two artifact types. Same author pool. One scores 57 on average; the other scores 91% clean. That gap is the lens for everything else in this piece.

What the warnings actually say

A scan score by itself is thin signal. The shape of the story comes from which checks fire most.

On the skill side, the top warnings cluster around what the skill says about itself. About 1,817 skills present themselves as reviewer-pattern skills but never declare what they’re evaluating against. Another 1,557 have descriptions that don’t say what the skill does. Another 1,427 don’t say when to use it. Another 1,402 don’t declare a clear trigger condition. Another 1,384 omit success criteria.

The warnings rhyme. They’re all variants of the same problem: the skill’s description field is supposed to tell a coordinating agent what the skill is for, and most descriptions don’t do that work. They describe the topic instead of the trigger. They list what the skill contains instead of what calling it produces.

On the plugin side, the warnings are mechanical. The version field is missing or the marketplace.json file sits in .claude-plugin/ when it should sit at the plugin root. These are one-line fixes. They get caught by anyone who reads the spec once.

The contrast matters. A plugin issue is a structural problem with a known fix. A skill issue is a semantic problem with no single answer. To make a skill description say what the skill does and when to use it, the author has to know their own skill better than they currently do. That’s much harder.

Why the gap exists

The simplest explanation is spec age. Anthropic’s SKILL.md format has been public for quite some time at the time of writing. The plugin manifest spec is newer. Every author who ships a SKILL.md today is operating in a community where examples already exist, and most of those examples were written before the current SkillCheck rubric existed. People copy patterns that worked for shipping.

The plugin spec doesn’t have that drag yet. There hasn’t been time to grow a layer of pre-spec patterns underneath it. Everyone who ships a plugin manifest in May 2026 is reading the actual spec, because there isn’t yet a corpus of bad manifests to copy from.

This generalizes. Newer formats look healthier because there hasn’t been time for habits to ossify against them. Older formats look messier because the spec has drifted while the corpus stayed put.

The version-over-version data backs this up. The same scan a month ago, at v3.18.0, covered 1,950 skills with an average score of 58.8 and 90.5% no-critical. By v3.20.0, the corpus grew to 2,139 skills, the average fell to 57.1, and no-critical share dropped to 86.3%. The corpus is getting bigger and slightly worse. Each batch of new contributors arrives without having internalized the rubric, so the average sinks.

A portability footnote worth noticing

One repo in the scan does something unusual. The alirezarezvani-claude-skills repo ships 311 SKILL.md files under .gemini/skills/ paths, and 241 of those have an exact-named sibling somewhere else in the same repo. Same skill, two trees: one for Claude Code, one for Gemini’s agent runtime. The maintainer is shipping agent-portable skills, betting that the SKILL.md format outlives any single agent harness.

Worth flagging because it’s the one of community examples of explicit multi-runtime packaging in the corpus. The hypothesis is “the SKILL.md format will end up cross-vendor”.

What this means if you’re shipping skills today

Read the spec, then read your description back. The thing that gets your skill picked by a coordinating agent isn’t the body; it’s the description string. If yours doesn’t say what the skill does and when to use it, the agent has no signal to fire on.

If the description fits in one sentence that starts with “Use when…” and ends with what the skill produces, you’re already in the top 3% of the corpus. That bar is lower than it should be, which is the whole point of this piece.

Sources

• Full SKILL.md scan: 2,139 entries across 12 repos, v3.20.0, run 12-05-2026

• Plugin scan: 178 entries across 7 of those repos

• Reports landing page: https://getskillcheck.com/reports/

• Methodology: https://getskillcheck.com/methodology

I build MCP servers. I also enhance and use CLIs. And I write skills that wire them together. They solve different problems. This piece is about when each layer is the right call, with real examples from a setup that runs all three daily.

The thread that started this

Someone asked: “Why do some people feel so strongly against MCPs?”

The answers were sharp and specific. Token pre-loading: every MCP tool description sits in the agent’s working memory whether you call the tool or not, eating into the context window. No piping: there’s no native way to feed one MCP tool’s output into another the way you can with shell commands. Auth passthrough: if the agent has to construct API requests for you, your credentials risk passing through the model’s context. Multi-agent portability: an MCP server has to be configured in every agent that uses it. Dropped connections: networked MCP servers cut off mid-call.

These are real engineering problems with solvable designs. The thread framed MCP and CLI as competing philosophies. They’re different layers of the same stack, and both layers serve a third one most people forget about: the agent’s instruction sheet.

The three layers, briefly

Before the catalogue, the picture you need:

• MCP servers are tool surfaces with structure. The agent discovers what’s available from a typed list and calls each tool through a defined schema.

• CLIs (command-line interfaces) are tool surfaces with shell ergonomics. The agent invokes a command, reads the text output, optionally pipes it into the next command.

• Skills are short markdown documents the agent reads to know which surface to use, when, and how to call it well.

The agent is the only thing doing the calling. Skills don’t call MCP servers. MCP servers don’t manage CLIs. Each layer is independent. The three meet at the agent.

Layer 1: MCP servers

MCP servers are the structured interface layer. They expose typed tools with input schemas, descriptions, and discovery. The agent doesn’t need to know your API exists before it finds the right tool.

I run nine MCP servers in my personal portfolio. Eight in Go, one in TypeScript. (There’s a tenth I built for work that I’m not catalogue-ing here, but a few skills that depend on it show up later.) Each wraps a domain that benefits from structure:

• miro-mcp-server. 92 tools: 91 for canvas operations (stickies, shapes, frames, connectors, tags, groups, mindmaps, exports) and one miro_tool_search meta-tool that lets the agent search the rest by keyword. Many tools work here because Miro is a small world: every board object is one kind of item or another, and each kind supports the same four basic actions (create, read, change, delete). The meta-tool exists because loading 92 tool descriptions costs about 15K tokens of context, so clients can opt into a 15-tool essentials profile and reach the rest on demand through search.

• mediawiki-mcp-server. 42 tools for wiki authoring, search, link checking, and markdown conversion. The agent can read a page, edit it, check whether outbound links still resolve, find orphan pages, or convert markdown into wikitext before saving.

• tilbudstrolden-mcp. 18 TypeScript tools for cross-Nordic grocery shopping across Denmark, Norway, Sweden, and Finland. Search deals, compare unit prices, plan weekly meals around what’s on sale, build shopping lists grouped by store. The name is Danish for “the troll of deals,” but the troll roams Nordic-wide.

• ridge. 19 tools that reverse-engineer architecture from a directory tree. Point it at a Go, TypeScript, or Python codebase and it walks the source to build a structured graph of services, packages, databases, queues, caches, endpoints, and the relationships between them, with confidence scores on every edge. The same graph model works for markdown trees (Obsidian vaults, doc directories), where wiki-links and relative .md links become edges. Beyond the scan, ridge generates diagrams in nine formats (including a self-contained D3 force-directed HTML page), validates architecture rules (circular dependencies, layering violations, boundary crossings), and detects drift between any two git refs. The arch_drift_explain tool returns a paste-ready PR paragraph through pure templating, no LLM round-trip needed. Architecture diagrams normally go stale the day you commit them; ridge rebuilds them from source on demand.

• nordic-registry-mcp-server. 23 tools across the four Nordic government business registries (Norway’s Brønnøysundregistrene, Denmark’s CVR, Finland’s PRH, Sweden’s Bolagsverket) in one binary. Look up a company by name or organisation number, fetch board members and signing authority, list branch offices, monitor for changes since a given date.

• gleif-mcp-server. 12 tools for looking up Legal Entity Identifiers. An agent searching for “Apple Inc LEI” calls search_entity and gets a typed response, without ever needing to know the GLEIF API exists.

• productplan-mcp-server. 47 tools for product roadmap management. Read and update plans, bars, milestones, releases, and tags through typed schemas, so an agent drafting roadmap edits can’t malform the request.

• ratatoskr (currently private). 15 tools for searching a product help center from inside the editor: browse sections, search topics, read pages, view screenshots, extract PDFs, compare translations, audit links. Named after the Norse squirrel that runs up and down Yggdrasil carrying messages between the eagle in the crown and the dragon at the roots.

• diagram-insight-mcp (currently private). 10 tools for diagram comprehension through a vision-language model. Feed it an architecture, sequence, or flowchart diagram and the agent gets back a structured description of what the picture is saying.

That’s where the structure earns its keep: bounded domains where typed schemas catch malformed requests before they hit the API.

When MCP wins: the agent benefits from discovering what’s possible. The domain has a finite set of operations. Input validation matters (financial data, regulatory lookups, structured board manipulation). Auth is handled inside the server’s compiled code so credentials never travel through the model’s context.

That last point is worth pausing on. The thread raised auth passthrough as a criticism of MCP, but it’s actually the opposite. MCP servers handle authentication in code: the OAuth flow, the API key injection, the token refresh all happen server-side. The agent just calls search_entity and gets results. Compare that to a skill that tells the agent to construct raw HTTP requests with credentials in the prompt. Those credentials flow through inference and any observability the provider runs on the model.

Layer 2: CLIs

Some APIs are too big to wrap in MCP. Wrap a service that exposes hundreds of methods as MCP tools and the tool list alone crowds the agent’s context window before any actual work begins. CLIs are the cleaner answer for that case: one binary, one calling pattern, no per-method context cost.

I use two CLIs daily, both supported by skills and rules that explain how to call them.

gws is a CLI that covers everything in Google Workspace: Gmail, Calendar, Drive, Docs, Sheets, Slides, Tasks. Each of those services has dozens to hundreds of methods. Imagine listing every one as a separate MCP tool. The agent’s context window would be half-full of tool descriptions before it did anything useful.

Instead, gws handles login (browser-based OAuth, credentials stored in ~/.config/gws/), and the agent calls it through Bash:

gws calendar:v3 events list --params '{
  "calendarId": "primary",
  "timeMin": "2026-04-05T00:00:00+02:00",
  "timeMax": "2026-04-05T23:59:59+02:00",
  "singleEvents": true
}' --format json

The agent doesn’t need a tool schema for every Google API method. It needs to know the pattern: gws [service] [method] --params '{...}'. That pattern is taught through a rule file (more on this in Layer 3), not an MCP tool list.

li-cli is my Rust CLI for LinkedIn. It lets me run LinkedIn from the terminal without opening a browser: read and reply to messages, browse the feed, react and comment on posts, send and accept connection invitations, search for people, jobs, and posts, audit my own profile for staleness, and answer the daily “who do I know at this company?” question with one command. There are 44 subcommands across 11 domains, including the day-to-day ones (Profile, Feed, Messages, Connections, Search, Company, Events, Notifications) and a few composite commands like inbox for the morning check and who for network overlap.

It’s a fork of linkedin-rs by Mark Ruvald Pedersen, who built the core client, login flow, and protocol handling. I built the daily-driver shell on top of that: the additional commands, the inbox composite, the network-overlap queries, JSON output for piping into other tools, and shell completions.

LinkedIn’s public API is built on Rest.li, an open-source REST framework LinkedIn built and uses internally. Rest.li sits on top of HTTP but layers on custom conventions: required headers like X-RestLi-Protocol-Version, response wrapping (entities returned inside a CollectionResponse envelope), and projection rules for limiting fields. LinkedIn ships official Python and JavaScript clients that handle this; generic HTTP clients have to handle it manually. The Rust binary takes care of all of it. Login is a browser cookie (li_at) stored locally. The agent calls li feed list --count 20 and gets posts. It never sees the cookie, never constructs the protocol headers, never touches the transport layer.

li inbox                                    # morning check: messages, invitations, notifications
li feed list --count 20                     # browse the feed
li who Anthropic                            # who do I know there?
li search posts "AI engineering"            # search posts by topic
li messages reply <id> "thanks!"            # reply from terminal
li profile audit                            # check my own profile for staleness

When CLI wins: the API has too many methods to wrap each one as its own MCP tool (Google Workspace). The API uses a non-standard protocol that’s a pain to call directly (Rest.li). Login uses session cookies or browser cookies that shouldn’t travel through the model’s context. You want to chain commands together with shell pipes (li feed list --json | jq '.[] | select(.reactions > 50)' reads as “list my feed, then keep only posts with more than 50 reactions”). And one CLI installed on your machine works with every AI agent you have at once, no extra configuration per agent.

Layer 3: Skills (and rules)

Skills are short markdown documents the agent reads when relevant. They explain how to use a CLI or MCP server, give context about which tool to pick, and encode recurring workflows. Rules are the same idea at a different scope: they live alongside skills but load globally, attaching themselves whenever a matching context appears.

My skills divide into three rough groups, with rules sitting alongside as a fourth.

Rules that document CLI patterns. A gws-cli.md rule documents every Google Workspace service pattern, login setup, timezone handling (always Europe/Copenhagen, always include UTC offset), and the gotcha that Calendar’s table format silently drops events. The rule isn’t a skill; it’s a context document that loads automatically when the agent is doing calendar or Gmail work. Skills like today (daily standup prep) and dropcheck (catching dropped balls in Gmail and Calendar) read this rule to know how to call gws correctly.

Skills that wrap CLIs for specific outcomes. linkedin-sift is the discovery layer for my LinkedIn feed: it calls li to pull recent posts, filters out noise, and surfaces a shortlist of items worth deeper review. skillcheck-engage finds LinkedIn posts about MCP and Claude skills, drafts replies, and posts after my approval. Both rely on li for read access.

Skills that span both layers. These show why the three-layer model matters:

• sift is a content evaluation pipeline that handles several input types. For URLs, it extracts clean article content through a fallback chain: a reader API first, then trafilatura (a Python tool that strips ads and navigation off a webpage and returns just the article text), then curl as a last resort. For YouTube videos, it pulls transcripts via yt-dlp (a command-line tool that downloads subtitles and metadata from video sites). For GitHub repos, it uses the gh CLI. For my open Chrome tabs, it discovers each tab via AppleScript and then reads the page contents through the claude-in-chrome MCP server (a Chrome extension that exposes browser actions to Claude through MCP); pages in Chrome are already JS-rendered, so extraction works on sites where curl and trafilatura come back empty (LinkedIn Pulse, Medium, most single-page apps). It evaluates everything against seven lenses and routes the keepers to my Obsidian vault. The agent reads the skill, then picks the right tool for the input shape.

• lmwtfy answers colleague questions about a product I work on. It searches GitHub source code (via the gh CLI), the customer-facing 360 Online help center (via Ratatoskr, an MCP server I built that wraps the help-center search), Azure DevOps (Azure DevOps MCP server), and the internal wiki (mediawiki MCP server). Four data sources, two transport layers, one skill telling the agent how to weave them together.

• today runs daily standup prep: checks Azure DevOps (MCP), GitHub activity (gh CLI), Google Calendar (gws CLI), and Obsidian notes (file reads). Four systems, three layers, one prompt.

Skills that show up in customer work. I work in product management for a records management platform. A handful of skills do the heavy lifting on that side of my desk:

• release-prep generates release notes from Azure DevOps work items.

• bid-intel drafts bid and tender responses by searching the wiki, GitHub source, and existing intel folders.

• enhanced-edoc-update generates the weekly stakeholder progress report from Azure DevOps and GitHub activity.

Each of these calls the same kinds of tools the personal-knowledge skills do. The pattern repeats: the agent reads the skill, then calls into MCP servers and CLIs as the work requires.

Where each layer reaches

The decision matrix gets sharper if you pull back and ask which agent surfaces support which layer in the first place. Three tiers, each with different reach.

The chat web apps are the narrowest. Claude on the web and ChatGPT on the web can load MCP servers and read skill files. They can’t shell out to a CLI, and they can’t call arbitrary APIs. ChatGPT has one partial exception: Custom GPT Actions, a mechanism that lets a Custom GPT call your API if you describe it in an OpenAPI spec. The newer ChatGPT Apps SDK uses MCP rather than Actions.

Cloud-based development agents sit in the middle. Anthropic’s Cowork and OpenAI’s Codex (cloud) both run as managed cloud sandboxes that you talk to from a browser. They support CLIs, MCP servers, and skills out of the box. They support direct API calls too, but with restrictions: both sandboxes block outbound network traffic by default, so you have to whitelist specific domains and configure access before either can reach an external service.

The local developer tools have full reach. Codex CLI, Claude Code, and Cursor support all four delivery methods without restriction. CLIs run because the agent has a shell. APIs work because there’s no network sandbox. MCP and skills work because every modern agent loads them.

Two patterns are worth pulling out of that.

MCP and skills work everywhere. Every surface I just walked through can load an MCP server or read a skill file. Nothing else has that reach.

Chat surfaces have less reach than developer surfaces. The web chat apps, which are also the surfaces with the most users, have the narrowest set of options. The debate I see online treats MCP-vs-CLI as if every agent could pick freely. Most can’t.

If you’re a builder shipping a product to AI agents:

• Ship only an API and you’re invisible to chat users.

• Ship only a CLI and you’re invisible to web-based agents.

• Ship an MCP server and every surface can reach you.

When to pick which

Once you’re inside an agent surface that supports all three layers, the question becomes which layer fits which job. Here’s the heuristic I land on after building all three:

Below ~20 operations: MCP. The agent benefits from discovering what’s available. Diagram-insight has 10 tools. Ratatoskr has 15. Tool descriptions fit comfortably in context, and schemas catch malformed requests early.

Above ~50 operations: CLI plus a rule or skill. Token efficiency dominates. Google Workspace has hundreds of methods. LinkedIn has dozens of endpoints across nine domains. Enumerate those as MCP tools and you’ve spent your context budget before doing any work.

The gray zone (20-50): depends. TilbudsTrolden has 18 tools. Could be a CLI. But meal planning workflows need the agent to discover tools (”what can I do with recipes?”), and the input schemas for plan_and_shop are complex enough that free-form CLI args would produce errors. MCP wins here despite the tool count.

Three additional dimensions push the boundary in either direction:

• Who’s the consumer. Chat users with conversational, sporadic traffic want MCP: small responses, stateful turns, dynamic discovery. Backend services with high-volume programmatic traffic want a direct API. Power users running scripts or CI pipelines want a CLI.

• Auth complexity. A simple API key works in any layer. OAuth flows, browser cookies, and session tokens are easier to handle safely in a CLI (credentials stay in the binary or local config) or in MCP server code than in a skill that asks the agent to construct requests.

• Multi-agent reuse. A CLI installed once serves every agent on the machine. An MCP server has to be configured in each agent. Skills also carry across agents if you share your config repo.

Token cost is the single dimension most people underweight. MCP carries roughly a 4-32x overhead on tool listings and metadata compared to a direct API call. That’s not an argument against MCP; it’s an argument for not loading every server in every context.

What the thread got right

Token pre-loading is real. My nine MCP servers expose 278 tools combined. That’s a lot of tool descriptions sitting in context before any work happens. I make intentional choices about which servers to load in which context, and the Miro server’s miro_tool_search profile (15 essentials plus the meta search) shows what server-side mitigation can look like.

Composability is a real gap. When I want “find all Miro stickies in frame X, then create connectors between them,” the agent makes multiple round trips where a single piped command would suffice. Anthropic and others are working on solutions, but they’re not mature.

Connection instability is real for networked MCP servers. Less so for local ones, which run as processes on your machine talking to the agent through standard input/output. They don’t go over the network, so they don’t disconnect. Most of my Go servers run locally, and I can’t remember the last time one crashed.

Two things have changed since the thread that I’d weight against the criticisms.

Governance moved off Anthropic. On 9 December 2025, Anthropic donated MCP to the Agentic AI Foundation, a directed fund under the Linux Foundation. Two other projects joined as co-founders: OpenAI’s AGENTS.md (a vendor-neutral file format that lives at the root of a code repo and tells AI coding agents how to work in that codebase, similar in spirit to Anthropic’s CLAUDE.md) and Block’s goose, an open-source AI coding agent framework. Single-vendor risk was the most common reason enterprise architects hesitated to bet on MCP; the foundation arrangement removes it. The cross-vendor commitment matters too. Anthropic, OpenAI, and Block all betting on the same neutral home is a stronger signal than any single donation would have been. (announcement, Linux Foundation press release)

Adoption has compounded. As of early May 2026, the @modelcontextprotocol/sdk TypeScript SDK pulls roughly 143 million monthly downloads on npm, and the mcp Python package pulls another 244 million on PyPI: close to 400 million combined across the two official SDKs. (You can verify either number live: npm at api.npmjs.org/downloads/point/last-month/@modelcontextprotocol/sdk, PyPI via pypistats.org/api/packages/mcp/recent.) The criticisms in the thread are still valid; the question is whether they’re worth weighing against the alternatives, and the alternatives keep losing surface area.

What the thread missed

Nobody distinguished local from networked MCP servers. The “MCPs disconnect all the time” complaint applies to networked servers, not local ones.

Nobody pointed out the upside of input schemas. CLI arguments are just text strings the agent has to guess at. MCP tool schemas spell out which fields are required, what types they take, and which values are valid. For complex inputs (a Miro board with specific frame layout and tagged stickies), schemas catch errors before the call runs.

Nobody framed skills as a distinct layer. The thread treated it as MCP vs CLI: structured discovery vs lean invocation. Skills are the third piece. Without skills, a CLI is a binary the agent has to guess at. Without CLIs, an MCP server for a 200-method API eats your context window. Without either, an agent in a chat surface can’t reach your product at all.

Nobody mentioned security. Three things deserve more conversation than they get:

• Prompt injection through tool descriptions and tool outputs. Anything an MCP server returns can carry instructions the agent might follow. The defenses are still maturing.

• Knowing what you’re actually running. When you npx or go install an MCP server, there’s no built-in way to confirm that the binary you got matches the source code the README points to. Someone could publish a package, tag it v1.0, and quietly swap the contents, and you’d have no easy way to tell. The registry layer that would solve this is half-built.

• Token discipline. “MCP eats tokens” is a meme. It’s also true. The fix isn’t fewer servers; it’s the right servers in the right context.

And nobody talked about building both. That’s the part I find strange. Some domains want to be discovered (MCP). Some want to be invoked (CLI). Most want to be explained (skills). The stack is three layers deep. The interesting work happens at the seams.

Sixty-four Claude Code skills, accumulated since October. Product research, content publishing, MCP server development, sprint planning. Some run daily. Some I’d forgotten about until I opened them this week and found instructions addressed to a model that no longer exists.

Every skill is a snapshot

Anthropic published an engineering post this week about their managed agents architecture. Most of it is infrastructure plumbing. But one line stopped me: “context anxiety” — Claude wrapping up work prematurely near context limits — existed in Sonnet 4.5 and disappeared in Opus 4.5.

The workaround remained. Nobody removed it. It sat there, compensating for a problem the model had already solved.

Skills are scaffolding. Every skill wraps the model in assumptions about what it can and can’t do at the time of writing. When the model improves, those assumptions don’t update themselves. They sit there, consuming tokens and solving yesterday’s problems.

This is assumption debt. Tech debt’s quieter cousin. It doesn’t crash anything. It fills the context window with instructions nobody needs, crowding out the space where actual work happens. Across my library, that added up to roughly 18,000 tokens of dead instructions the model was dutifully reading on every invocation.

What it looks like

I ran an audit across all 64 skills. Eight parallel agents, each with its own worktree and a SKILL.md to evaluate — Claude Code auditing its own skill library. The signals were consistent:

Defensive instructions that restate native model behaviour. “Do NOT hallucinate.” “Do NOT skip steps.” “Make sure to check X.” Written when models actually did skip and hallucinate more. Noise now. The model equivalent of telling a senior engineer to remember to save their files.

Micro-step decomposition. Breaking a simple reasoning task into seven numbered steps because an earlier model couldn’t hold the full chain. Opus 4.6 handles multi-step reasoning without scaffolding. The steps become a straitjacket.

Negative instructions restating positive ones. A skill that says “Present scope options as genuine choices” in one section, then says “DON’T present Option A when a fixed customer deadline makes it risky” ten lines later. The second instruction adds zero information. It exists because an earlier model missed the implication.

And my personal favourite: motivational scaffolding. One skill contained the line “This is normal! Don’t be discouraged.” I was coaching a language model through its feelings.

The taxonomy

Not everything that looks like scaffolding is debt. Every guardrail falls into one of three categories:

Stale assumptions. Workarounds for model weaknesses that have been fixed. Safe to remove.

Earned constraints. Rules that exist because the skill failed without them, and the failure mode is still possible. My research skill has an Evidence Ledger step that forces the model to show sources before writing an answer. I added it after the model kept producing plausible-sounding answers with no verification. Opus 4.6 is smarter, but the verification step catches domain-specific traps the model can’t know about: incomplete wiki coverage, API quirks, search snippets that look like evidence but aren’t. The constraint earned its place.

Domain constraints. Knowledge the model genuinely can’t derive. “This API has specific operations; check the contract, not what seems reasonable.” No model improvement eliminates this.

Trim earned constraints because they look stale, and your skill regresses. Keep stale assumptions because they feel earned, and your skill wastes tokens for no reason.

I got this wrong during the audit. Pass 1 removed a deduplication check from my content evaluation skill. It forced the model to verify against existing notes before writing new ones. Looked like hand-holding for a model that should know better. Two days later, the skill produced a knowledge note that nearly duplicated one from the previous week. The guardrail wasn’t compensating for a weak model. It was compensating for a large vault where relevant context doesn’t always surface on the first pass. Back it went.

The obvious objection: guardrails are cheap insurance. Tokens cost fractions of a cent. Why risk it? Because stale guardrails don’t just waste tokens. They constrain behaviour. A skill full of “DO NOT” instructions produces cautious, hedged output — not because the model needs the reminder, but because the instructions set the tone. Assumption debt makes the model worse at the thing the skill is supposed to do.

The numbers

Before the audit, I ran the library through SkillCheck Pro, which validates 22 categories of skill quality. Several categories surface assumption debt directly. The railroading detector counts prescriptive phrases: “you must always,” “never deviate,” “follow these exact steps.” Five or more in a single skill and it fires. That’s the mechanical signal for what the assumption audit confirms through judgment: over-scaffolding. The token budget audit makes the cost visible. The anti-slop detector catches hedge stacking and sycophantic openers baked into skill instructions, teaching the model bad habits on every call.

SkillCheck tells you a skill is well-formed. The assumption audit tells you it’s well-calibrated for the current model. Different questions. Both necessary.

Then three passes across one afternoon.

Pass 1 cut 1,900 lines. Deleted two skills entirely (a pandoc wrapper the model handles natively, an incomplete stub). Trimmed five skills by 80%+ each. Merged one n8n skill into its parent.

Pass 2 cut 125 lines from the three worst offenders. My feature-scoping skill went from 314 lines to 226. The before/after:

BEFORE: 5 quality gates, each stated FIVE times
  - Inline in each phase (the actual rules)
  - Hard Gates Reference table (same 5 rules, tabular)
  - Evaluation Criteria section (same 5 rules, prose)
  - Success Criteria section (same 5 rules, conditional)
  - DO/DON'T section (same 5 rules, imperative)

AFTER: 5 quality gates, stated once
  - Inline in each phase (the actual rules)
  - Gotchas section (4 domain-specific items)

Four copies of the same five rules. Not variations. Not refinements. The same words in five different containers, like finding five identical corkscrews in a kitchen drawer, each bought because you forgot you already had one.

Pass 3 cut 377 lines across 16 skills. Smaller cuts accumulated between the formal passes as I noticed patterns the structured audit missed.

Total: roughly 2,700 lines, ~14% of the library.

Why this keeps happening

The creation pipeline has seven phases. The maintenance pipeline has zero.

Skills collect guardrails the way drawers collect utensils. You build one, it works mostly. Fails on an edge case, you add a guardrail. Different edge case, another guardrail. Model upgrade ships and half those edge cases vanish, but you don’t know which half. The guardrails stay. Six months later you have a 314-line skill where 135 lines are meta-commentary about the same five rules.

I wrote about the difference between a prompt and a skill. Turns out there’s also a difference between building one and keeping it honest.

The audit question

For each guardrail, ask: “Is this compensating for a model weakness, or encoding domain knowledge?”

If it’s a model weakness: has it been fixed? Remove the guardrail. Run the skill. If it still works, the guardrail was debt.

If it’s domain knowledge: keep it. No model improvement will teach the model that your internal wiki has coverage gaps or that your API has undocumented quirks.

If you’re not sure: it’s probably debt. Earned constraints are memorable. You remember the failure that created them. Stale assumptions are invisible — added as a precaution, never tested without.

When to audit: Every time a new model drops. A model upgrade is an assumption invalidation event. Half your guardrails may have just become dead weight, and you won’t know which half until you check.

Try this. Pick your most-used skill. Find one guardrail that talks to the model instead of about the domain. Remove it. Run the skill. Did anything change?

Beyond skills

Assumption debt lives wherever code wraps a language model. System prompts, RAG pipelines, agent workflows, retry loops, preprocessing steps — all of it encodes assumptions about the model’s capabilities at the time of writing. All of it goes stale at the same rate: one model release at a time. The taxonomy is the same everywhere. The audit question is the same. Most people discover this the way I did: not by looking, but by tripping over something that should have been obvious months ago.

The model improved. The harness didn’t notice.

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.