Same AI, Same Repo. This Time It Read the Playbook First.

Yesterday I ran Codex against our EDS web kit and got a solid solution design in 4 minutes. But there was a catch: a misconfigured AGENTS.md meant the AI never found the 15 development skills baked into the repo.

Today I fixed the config and ran it again. Same repo. Same model. Same prompt.

The difference was not subtle.

The Setup

Quick recap: our web kit repo contains 15 AI development skills in a .skills/ directory. These are structured instructions for how this specific project builds blocks, models content, runs tests, and handles imports. Think of them as a senior developer's brain, codified.

Skills like:

• content-driven-development — the master workflow: always start with content, not code
• building-blocks — how to create blocks following this project's patterns
• content-modeling — canonical model types (Configuration, Collection, Standalone)
• block-inventory — survey existing blocks before building new ones
• testing-blocks — Playwright visual tests, linting, Percy snapshots

Yesterday, Codex never read any of this. Today, I told it to start there.

What Changed

1. Content before code

This was the biggest shift. V1 jumped straight to block specifications. V2 started with:

"Execute Phase 1 first: create/confirm test content and metadata schema before writing post-list code."

That's the content-driven-development skill talking. It's the single most important principle in EDS: author the content first, see how it renders, then build the block. V1 missed this completely.

2. Project-specific patterns, not generic ones

V1 would have worked. V2 fits the project. A code reviewer would accept V2 without questions. V1 would trigger a rewrite request.

3. It surveyed existing blocks first

The block-inventory skill told Codex to check what already exists before designing new blocks. It found cards, cards-section, link-cards, hero, fragment — and explicitly noted which could be reused and where the gap was.

V1 proposed 4 new blocks. V2 proposed 1 new block (post-list) with variants, plus reuse of existing patterns. Less code, same functionality.

4. It knew about TemplateBlock

The repo has a custom TemplateBlock helper — an abstraction for blocks that render from templates. V1 didn't mention it. V2 specified it as the implementation pattern for post-list.

This is the kind of thing that takes a new developer days to discover by reading source code. The skill told the AI in seconds.

5. Testing and documentation were baked in

V1 mentioned testing as an afterthought in Phase 4. V2 included specific test requirements from Phase 1:

• Playwright visual test: tests/blocks/post-list.spec.js
• npm run lint must pass
• Sidekick block preview content under /tools/sidekick/blocks/post-list
• Unit tests for pure data transforms in scripts/helpers/utils/posts.js

The testing-blocks skill didn't just add testing — it told the AI exactly how this project tests, where test files go, and what tooling to use.

6. Localization was considered from day one

V2 included a language fallback strategy for the data source — try /{lang}/blog/posts-index.json, fall back to /blog/posts-index.json. It found this pattern in the existing Cloudflare worker code.

V1 mentioned i18n as a "decision to confirm." V2 just handled it.

The Meta Point

Here's what this experiment actually proved:

This has massive implications for how we think about AI-assisted development:

1. The model doesn't matter as much as you think. A better model with no project context produces worse results than a decent model with great context.
2. Skills are a compounding investment. Every skill you write makes every future AI interaction with your codebase better. It's like hiring a developer who gets smarter every time anyone on the team learns something.
3. Documentation has a new audience. Skills aren't just for humans anymore. They're training data for AI agents. The ROI on writing good development docs just went through the roof.

What This Means for Enterprise Teams

Most enterprise codebases have tribal knowledge — conventions that exist in people's heads, not in files. "We always use TemplateBlock for this." "Tests go here." "The config pattern looks like this."

That knowledge is invisible to AI agents. And to new hires. And to contractors.

Codifying it as skills solves all three problems at once.

The teams that invest in this now will have a structural advantage that compounds over time. Their AI agents will produce project-native code. Their competitors' AI agents will produce generic code that needs rewriting.

The Flywheel

This is the cycle we're building toward:

1. Humans build skills from hard-won project knowledge
2. AI agents use skills to produce project-native work
3. Humans review — faster, because the output already follows conventions
4. Review insights become new skills
5. The codebase gets smarter with every cycle

We're not replacing developers. We're giving them a junior that actually reads the docs.

Try It Yourself

If you have an EDS project:

1. Create a .skills/ directory in your repo
2. Write a SKILL.md for how you build blocks in this project
3. Write one for how you model content
4. Point your AGENTS.md to the skills directory
5. Run Codex or Claude Code with a feature request

Then run it again without the skills. Compare the output.

You'll see what I saw. The skills change everything.