xonecas.io
5745
Sc

sacenox.github.io / commit 19a4421

feat: add blog post on AGENTS.md migration and regenerate site

xonecas2026-01-31 19a4421fe2a2905199f042f4b9cfbee8b59f6b17 parent 40b341f

3 files changed

_posts/2026-01-30-ditching-skills-for-agents-md.md+55−0
@@ -0,0 +1,55 @@
1+---
2+layout: post
3+title: "agents.md migration"
4+description: "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+
9+I 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+
13+I 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+
17+Here'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+
27+The 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+
31+The 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+
39+The 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+
43+The 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+
45+I 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+
49+Early 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+
51+The migration took a weekend, but the payoff is immediate. Sometimes the research is right: AGENTS.md with targeted docs really does work better than monolithic skills.
52+
53+## Sources
54+
55+- [Vercel's AGENTS.md research](https://vercel.com/blog/ai-agents-with-agents-md)
_site/index.html+5−0
@@ -65,6 +65,11 @@
6565 <a href="/posts/hello-world/">hello world</a>
6666 </li>
6767
68+ <li>
69+ <span class="post-date">2026-01-30</span>
70+ <a href="/posts/ditching-skills-for-agents-md/">agents.md migration</a>
71+ </li>
72+
6873 </ul>
6974
7075 </div>
_site/sitemap.xml+4−0
@@ -1,6 +1,10 @@
11 <?xml version="1.0" encoding="UTF-8"?>
22 <urlset xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.sitemaps.org/schemas/sitemap/0.9 http://www.sitemaps.org/schemas/sitemap/0.9/sitemap.xsd" xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
33 <url>
4+<loc>http://0.0.0.0:4000/posts/ditching-skills-for-agents-md/</loc>
5+<lastmod>2026-01-30T00:00:00-06:00</lastmod>
6+</url>
7+<url>
48 <loc>http://0.0.0.0:4000/posts/hello-world/</loc>
59 <lastmod>2026-01-30T00:00:00-06:00</lastmod>
610 </url>