xonecas.io
5745
Sc

sacenox.github.io / files

sacenox.github.io / _posts / 2026-01-31-ditching-skills-for-agents-md.md

3.5 KB
1---
2layout: post
3title: agents-md-migration
4description: "A weekend migration from skill files to AGENTS.md, with focused docs, faster lookups, and lower token use."
5---
6
7# Ditching Skills for AGENTS.md: How I Restructured My AI Documentation
8
9I just finished a pretty big refactor of how my AI agents access their instructions. After reading Vercel's research showing AGENTS.md outperforms skills, I decided to test it myself. Spoiler: they're right.
10
11## What I Had Before
12
13I was using a skills-based system where agents would load specific skill files when they needed guidance. It worked, but it felt clunky. The systematic debugging skill was this massive file with everything crammed in. The writing skill mixed basic grammar with advanced patterns. Finding the right info took too long.
14
15## What Changed
16
17Here's the breakdown of my migration:
18
19- **Replaced skills with AGENTS.md** that points to a compressed docs index
20- **Split systematic debugging** into 21 focused files instead of one giant skill
21- **Condensed writing guidance** to essentials plus AI pattern avoidance
22- **Added programming principles** covering KISS, DRY, YAGNI, SOLID, and scope management
23- **Created .agent-docs folder** with 29 total files: 21 debugging, 6 programming, 2 writing
24- **Kept skills/ folder** but removed the content (for now)
25- **Updated README** to document the new structure
26
27The biggest change is retrieval-led reasoning. Instead of loading entire skills, agents now read specific sections based on what they actually need.
28
29## Why This Works Better
30
31The new system fixes several pain points:
32
33- **Faster lookups** - agents find relevant info without loading everything
34- **Better organization** - debugging phases are separate files, not buried in walls of text
35- **Reduced token usage** - only load what you need, when you need it
36- **Easier maintenance** - updating one concept doesn't require editing massive files
37- **More targeted guidance** - specific files for specific problems
38
39The debugging documentation especially benefits from this. Instead of hunting through a 5,000-word skill file, agents can jump straight to "Phase 2: Pattern Analysis" or "Red Flags to Watch For."
40
41## The Implementation
42
43The core insight from Vercel's research is that structured documentation with clear entry points beats monolithic skills. My AGENTS.md now includes a compressed docs index that maps topics to specific files. When an agent needs debugging help, it reads the overview first, then drills down to the relevant phase.
44
45I kept all the debugging content but broke it into logical chunks. The writing guidance got streamlined - just Strunk's essentials plus common AI patterns to avoid. Programming principles got their own section because code quality deserves focused attention.
46
47## Results So Far
48
49Early testing shows agents find answers faster and use fewer tokens. They're not loading irrelevant sections or getting lost in long files. The debugging workflow especially feels smoother - agents can follow the phases without getting overwhelmed.
50
51Don't forget to update your `opencode.json` like me - [here's the short cautionary tale](/posts/when-opencode-cant-see-your-docs) on why that matters.
52
53The migration took a few prompts and reviews, but the payoff is immediate. Sometimes the research is right: AGENTS.md with targeted docs really does work better than monolithic skills.
54
55_[EDIT]: Token usage is way down._
56
57## Sources
58
59- [Vercel's AGENTS.md research](https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals)
60- [Refactored AGENTS.md](https://github.com/sacenox/dotfiles/blob/main/opencode/AGENTS.md)