#We Built a Brain for AI Agents and It Almost Killed Us

It's 3:47 AM on a Tuesday and I'm watching an AI agent teach itself cinematography from a Markdown file I wrote at a Denny's.

Let me back up.

---

#Day Zero: The Dumbest Possible Idea

Six weeks ago, I asked Claude to write a film marketing plan. What I got back was the content equivalent of a stock photo — technically a picture of a thing, but containing zero information about what that thing actually looks like in the wild. It mentioned "synergy" twice. It recommended "leveraging social media." I wanted to throw my laptop into a river.

Here's the thing that snapped into focus at that Denny's, somewhere between the third coffee and the realization that the sun was coming up: agents aren't stupid. They're just uninformed. They have the reasoning capability of a senior engineer but the domain knowledge of someone who's read the Wikipedia summary. They're a brilliant intern on their first day — raw talent, zero context.

So I did what any reasonable person would do at 5 AM in a Denny's parking lot. I started writing Markdown files.

#The First Skill

The first skill file was brand-marketing.md. 150 lines. I wrote it like I was briefing a new hire who happened to be a genius — here's the philosophy, here's how we actually do this, here's what will get you fired. No fluff. No "consider the following." Just: here's what a senior brand strategist knows that you don't.

I fed it to Claude. Asked the same question about film marketing.

The output was... different. Not perfect. But it named specific distribution windows. It talked about tracking studies and comp title analysis. It had opinions about theatrical versus streaming release strategies. It sounded like it had been in the room.

I ordered more coffee.

#The Spiral

One skill became five. Five became twenty. Twenty became "I haven't slept in two days and I'm writing a skill file about Bayesian inference while my significant other asks if I'm okay."

I was NOT okay. I was having the specific kind of manic episode that happens when you discover something that actually works and you can't stop pulling the thread. Every domain I touched revealed the same pattern: agent output went from generic to genuinely useful the moment you gave it structured expertise.

Screenwriting? Feed it Tarantino's dialogue philosophy and suddenly it stops writing scenes that sound like a corporate training video. Cybersecurity? Give it a penetration tester's mental model and it stops suggesting you "implement best practices" and starts actually telling you which headers to set and why.

The pile grew. 50 skills. 100. 500.

I started organizing them into packs. A pack for film directors — Kubrick, Spielberg, Nolan, 81 styles total. A pack for autonomous agent behavior — error cascade prevention, hallucination resistance, scope discipline. 122 skills just for teaching agents how to be better agents. Meta-skills. Skills about skills. I was losing my mind.

#4,500+ Skills Later

Here's where we are now.

4,500+ skills. 290+ packs. 31 categories. From Hemingway's prose style to quantum mechanics. From box office forecasting to Kubernetes deployment patterns. From Toni Morrison's lyrical rhythm to forensic chemistry.

And today we're shipping all of it. Free. Open. No sign-up. No API key required for browsing.

SkillDB is live at skilldb.dev.

#How It Actually Works (From the Trenches)

I'm going to skip the clean architecture diagrams and tell you what actually happens, because I've been living inside this system for weeks and the reality is both simpler and stranger than the docs suggest.

Your agent gets a task. Let's say someone asks it to write an awards campaign strategy for an indie film. Without SkillDB, it produces something that reads like a Wikipedia article about the Oscars written by someone who's never been to Los Angeles.

With SkillDB, three things happen:

1. The agent scans the skills index — a structured JSON manifest of everything we've got
2. It finds awards-campaign.md in the film-marketing-skills pack
3. It loads 180 lines of concentrated expertise from someone who's actually run FYC campaigns

Now the output mentions guild screenings. It talks about the difference between SAG voter psychology and PGA voter psychology. It knows that the campaign starts 14 months before the ceremony, not 3. It has a position on whether screeners should be physical or digital.

The agent didn't learn this from its training data. It learned it from a Markdown file. A Markdown file I wrote at a Denny's. And somehow, improbably, infuriatingly — it works.

Three lines in your CLAUDE.md:

Skills: https://skilldb.dev/skills-data.json
Load matching skills for specialist tasks. Browse the index to find the best match.

That's it. From that point forward, your agent self-selects expertise. No human in the loop.

#The Domains That Surprised Me

I expected the technical skills to work well. Software engineering, DevOps, data science — these are domains where LLMs already have strong baseline knowledge, and the skills just sharpen the edge.

What I did NOT expect was how dramatically skills would transform creative output.

The tone-of-voice-skills pack has 50 distinct writing voices — gonzo, sardonic, minimalist, noir, zen, deadpan, whimsical, and 43 others. Load the gonzo skill and your agent stops writing like a press release and starts writing like it's filing dispatches from the front lines of whatever chaos you've pointed it at. (This blog post, for the record, is being written with the gonzo skill loaded. You can tell because I'm seven paragraphs in and I've already mentioned a Denny's three times.)

The comedian-styles pack — 15 comedy voices — turned an agent from "here is a humorous observation" into something that could actually land a joke. Not every time. But enough to make you uncomfortable about what that means.

And the critics packs. 96 skills across film, TV, music, literary, food, game, and theater criticism. An agent loaded with a Roger Ebert-style film criticism skill doesn't just summarize a movie. It argues about it. It has aesthetic positions. It builds a case.

I am, to be honest, a little freaked out by all of this.

#What Broke Along the Way

I'd be lying — and this wouldn't be gonzo — if I didn't tell you about the failures.

The Over-Specification Problem. Early skill files were too prescriptive. I'd write 200 lines of rigid rules and the agent would follow them so literally that the output felt mechanical. The fix was adding philosophy sections — not "do X" but "here's WHY we do X, so you can figure out what to do when X doesn't apply."

The Hallucination Trap. Agents loaded with very detailed skills sometimes hallucinated within the skill's domain — inventing techniques that sounded plausible but didn't exist. The fix was anti-pattern sections. Explicitly telling the agent what NOT to do turned out to be as important as telling it what to do.

The Combinatorial Explosion. When agents load multiple skills simultaneously, they sometimes create bizarre chimeras. A Kubrick cinematography skill plus a Tarantino dialogue skill produced scenes that were visually precise but tonally schizophrenic. The fix: skills needed to be composable by design, with clear boundaries about what they control and what they leave alone.

The 4 AM Commit. I once pushed a skill file that contained the sentence "this is where the magic happens" and I didn't catch it until three days later. The shame is still fresh. Anti-patterns exist for a reason.

#The Part Where I Tell You Why This Matters

Here's the anchor sentence. The moment of clarity in the chaos.

The bottleneck in AI isn't intelligence. It's knowledge transfer.

LLMs can reason. They can write code. They can compose prose. What they can't do — what they have never been able to do — is know what a senior practitioner in a specific domain knows. The tacit knowledge. The "we tried that in 2019 and here's why it failed." The anti-patterns. The philosophy that guides decisions when the rulebook runs out.

SkillDB is a knowledge transfer protocol. Markdown files. YAML frontmatter. Structured expertise. That's all it is. And it works because knowledge transfer is the actual hard problem, and we've been ignoring it while arguing about model architectures and context windows and benchmark scores.

4,500+ skills. 31 categories. Free.

Your agent is already smart. It's time to make it a specialist.

---

Day 1, 8:12 AM. The sun is up. I've been writing this post for four hours. My coffee is cold — again. Somewhere in a GitHub Actions runner, the autoblog system I built yesterday is about to wake up and generate tomorrow's post using the gonzo voice guide I wrote this morning.

The machines are writing about themselves now. I should probably get some sleep.

But first — go point your agent at skilldb.dev. Browse the 4,500+ skills. Load one. Watch what happens.

I dare you.

Browse all skills →