AGENTS.md가 Skills보다 에이전트 평가에서 앞서는 이유

AI 코딩 에이전트에게 프레임워크 지식을 전달하는 방법으로 'Skills(패키징된 도구)'와 'AGENTS.md(프로젝트 루트 마크다운)'를 Next.js 16 API 기준으로 평가한 실험이다. 결과는 AGENTS.md가 100% 통과율을 달성한 반면 Skills는 최대 79%에 머물렀다. 에이전트가 도구를 '호출할지 결정'하는 단계 자체가 병목이었음을 수치로 보여준다.

핵심 포인트

기준선(문서 없음) 53% → Skills(명시 지시 없음) 53% → Skills(명시 지시) 79% → AGENTS.md 100%: 컨텍스트 상시 제공이 도구 호출 판단보다 압도적으로 효과적이다.
Skills는 56% 케이스에서 에이전트가 아예 호출하지 않았다 — '언제 써야 하는지' 판단 자체가 실패 포인트였다.
AGENTS.md는 매 턴마다 자동으로 컨텍스트를 주입해 에이전트의 결정 지점 자체를 없앴다.
40KB 원본 Next.js 16 문서를 파이프 구분 포맷으로 8KB까지(80%) 압축해 AGENTS.md에 담았다.
`npx @next/codemod@canary agents-md` 명령 하나로 AGENTS.md를 생성할 수 있다.

상세 정리

실험 배경: Next.js 16의 신규 API(`connection()`, `'use cache'`, `forbidden()`, 비동기 `cookies()`/`headers()` 등)를 에이전트가 얼마나 올바르게 사용하는지 테스트했다.
기준선 53%: 문서 없이 에이전트가 Next.js 16 API를 올바르게 사용한 비율 — 학습 데이터 기반 추측.
Skills 실험: Claude Code의 skills 기능으로 Next.js 16 지식을 패키징해 제공. 명시적 지시 없이는 56%의 경우 에이전트가 skills 자체를 호출하지 않아 기준선과 동일하게 53%.
Skills + 명시 지시: '이 skills를 사용해라'고 명시 지시해도 79% — 일부 케이스에서 여전히 실패했다.
AGENTS.md 결과: 모든 테스트 케이스에서 100% 통과 — 에이전트가 매 턴마다 컨텍스트를 받아 판단할 필요가 없어졌다.
압축 전략: `.next-docs/` 디렉터리에 원본 문서를 두고, AGENTS.md에는 파이프 구분(`|`) 형식의 색인만 넣어 40KB를 8KB로 줄임. 필요시 `.next-docs/`에서 파일을 검색하게 했다.
생성 명령: `npx @next/codemod@canary agents-md` — Next.js 프로젝트 루트에서 실행하면 최신 API 기반 AGENTS.md와 `.next-docs/` 구조를 자동 생성.
사용처 구분: AGENTS.md는 '지속적으로 필요한 일반 지식'에, Skills는 '버전 마이그레이션·특정 작업 플로우처럼 수직 액션'에 더 적합하다는 결론.
프레임워크 저자 시사점: 에이전트가 API를 올바르게 사용하게 하려면 docs를 AGENTS.md 형태로 배포하는 게 도구 등록보다 효과적이다.