AgentCompiler (skill-compiler)

> Converts skill/framework documentation into compressed AGENTS.md indexes for AI coding agents


📖 Background

This project is inspired by and based on Vercel's groundbreaking research: AGENTS.md outperforms skills in our agent evals.

$3

| Configuration | Pass Rate |
|--------------|-----------|
| Baseline (no docs) | 53% |
| Skills (default) | 53% |
| Skills with instructions | 79% |
| AGENTS.md docs index | 100% |

Why passive context wins:
1. No decision point - Agents don't need to decide "should I look this up?"
2. Consistent availability - Content is in system prompt for every turn
3. No ordering issues - Avoids sequencing decisions (read docs first vs explore first)

This tool automates the process of generating these compressed doc indexes for any project.

🚀 Quick Start

``bash

In your project directory

npx skill-compiler
`

This will:
1. 🔍 Detect frameworks from your package.json
2. 📥 Download version-matched documentation
3. 📦 Compress into <8KB indexes
4. ✅ Generate/update your AGENTS.md

Usage

`bash

One-time generation

npx skill-compiler

Watch mode (auto-update on dependency changes)

npx skill-compiler watch

Preview without writing

npx skill-compiler --dry-run

Only specific frameworks

npx skill-compiler --only nextjs,react

Force refresh cached docs

npx skill-compiler --refresh

Add custom skill

npx skill-compiler add ./my-skill-docs/

Run evaluation suite

npx skill-compiler eval
`

Supported Frameworks

| Framework | Package Match |
|-----------|--------------|
| Next.js | next |
| React | react |
| Vue.js | vue |
| Astro | astro |
| SvelteKit | @sveltejs/kit |
| Supabase | @supabase/supabase-js |
| Tailwind CSS | tailwindcss |
| Prisma | prisma, @prisma/client |
| Drizzle ORM | drizzle-orm |
| tRPC | @trpc/server, @trpc/client |
| Zod | zod |
| TanStack Query | @tanstack/react-query |

Generated Output

The tool generates a managed section in your AGENTS.md:

`markdown

Framework Documentation Indexes

[Next.js Docs Index]|root: ./.agent-docs/nextjs
|IMPORTANT: Prefer retrieval-led reasoning over pre-training-led reasoning for Next.js tasks.
|01-app\01-getting-started:{01-installation.mdx,02-project-structure.mdx,...}
|...


`

Your existing AGENTS.md content is preserved—only the managed section is updated.

Evaluation Suite

Run Vercel-methodology evals to verify improvements:

`bash
npx skill-compiler eval
`

Outputs Build, Lint, Test, and Pass Rate metrics comparing baseline vs AGENTS.md configurations.

How It Works

1. Scanner - Detects frameworks from package.json, .agent/skills/, and config files
2. Fetcher - Downloads version-matched docs from GitHub (cached for 7 days)
3. Compressor - Compresses to <8KB using pipe-delimited format
4. Injector - Merges into AGENTS.md while preserving user content

Configuration

Create .skill-compiler.json to customize behavior:

`json
{
"out": "./AGENTS.md",
"only": ["nextjs", "react"],
"conflicts": {
"hooks/*": "prefer:react"
}
}
`

Background Automation

$3

`json
{
"scripts": {
"postinstall": "skill-compiler --silent"
}
}
`

$3

`json
{
"scripts": {
"dev": "concurrently 'next dev' 'skill-compiler watch'"
}
}
`

$3

`bash

.husky/pre-commit

npx skill-compiler --check || exit 1
`

🙏 Acknowledgments

This project would not exist without the research and insights from:

- Vercel - For their comprehensive research on AGENTS.md vs skills, published in this blog post
- Jude Gao - Research and evals at Vercel
- Next.js Team - For the @next/codemod agents-md` implementation that inspired the compression format
- AGENTS.md Standard - For establishing the convention for agent context files
- Agent Skills - For the skills standard that drove the comparative research

🤝 Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

$3

- Add new framework registries
- Improve compression algorithms
- Enhance the eval suite
- Report bugs and suggest features
- Improve documentation

📄 License

MIT