Converts skill/framework documentation into compressed AGENTS.md indexes for AI coding agents
npm install skill-compilerbash
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