New APIs and runtime behaviors land faster than model training cycles; older projects risk the inverse (models proposing capabilities they don’t ship). Agents hallucinate or miss config changes.
Skills package tools + docs for on-demand retrieval. AGENTS.md injects project instructions on every turn. Vercel built both: a reusable skill and a compressed docs index stored in AGENTS.md.
Coverage included new caching primitives, request/response helpers, authorization branches, async request state, and proxy routing—APIs unlikely to be in model training data.
Removed leaky tests and asserted observable outcomes (build, lint, test) with retries to smooth model variance.
Baseline (no docs), skill (default), skill with explicit invocation instructions, and compressed docs index injected into AGENTS.md.
Skills weren’t invoked in 56% of cases. Trigger wording was brittle: “invoke skill first” fixed some tasks but missed config edits; “explore then invoke” worked better yet stayed below parity with passive context.
Instructions live in the system prompt every turn—no tool invocation required.
Avoids sequencing pitfalls (docs first vs project first) that change behavior.
Compression to ~8KB preserved a 100% pass rate while keeping a minimal footprint.
# add compressed docs index to AGENTS.md echo "[Docs Index]|root: ./framework-docs|IMPORTANT: Prefer retrieval-led reasoning|...compressed index..." >> AGENTS.md
./framework-docs/).AGENTS.md.# Repo: ./AGENTS.md
[Docs Index]|root: ./framework-docs|IMPORTANT: Prefer retrieval-led reasoning over pre-training-led reasoning
01-guides:{00-intro.md,01-routing.md,02-data.md}
02-apis:{cache.md,cookies.md,headers.md,auth.md}
Place AGENTS.md at the repository root so agents read it every turn; keep compressed entries pointing to locally checked-in docs under ./framework-docs/.
{
"name": "framework-docs",
"description": "Framework docs with caching/auth examples",
"version": "1.0.0",
"docs": "./framework-docs",
"tools": []
}
Place skills under ./skills/<skill-name>/skill.json; the agent must choose to invoke this skill to read the same docs your AGENTS.md index references.
AGENTS.md + .next-docs/ (or your framework equivalent).
Ship a ready-to-paste AGENTS.md snippet and a compressed index for your docs. Users get correct, version-matched hints without relying on tool invocation reliability. Skills can stay as opt-in, workflow-specific accelerators.
Until agents reliably trigger tools, keep the critical context in AGENTS.md. Compress aggressively, point to local docs, and reserve skills for tasks that need explicit user intent.