왜 스킬이 졌을까?(feat. agent.md 의 비밀)

🖼️ 인포그래픽

왜 스킬이 졌을까?(feat. agent.md 의 비밀) 내용을 설명하는 본문 이미지

🖼️ 4컷 인포그래픽

💡 한 줄 결론

왜 스킬이 졌을까? 핵심은 AI에게 스킬 호출을 맡기기보다 agent.md처럼 최신 기준을 항상 보이게 두는 편이 더 안정적이라는 점이다.

📌 핵심 요점

Vercel 실험에서 Next.js 최신 기능 적용 과제를 비교한 결과, agent.md는 100점, 스킬은 강한 지시를 붙여도 79점에 머물렀다.
스킬은 필요한 순간에 AI가 직접 불러야 효과가 나지만, AI가 매뉴얼을 보지 않거나 호출 타이밍을 놓치면 성능 개선으로 이어지지 않았다.
아무 도움 없는 조건과 스킬을 알아서 쓰게 둔 조건이 모두 53점이었다는 점은 “도구가 있음”보다 “도구가 실제로 참조됨”이 중요하다는 사실을 보여준다.
agent.md는 프로젝트 안에 항상 놓인 짧은 기준 문서처럼 작동해, AI가 오래된 학습 기억보다 최신 프로젝트 문맥을 우선하게 만든다.
스킬은 사용자가 특정 시점에 호출하는 마이그레이션·구조 변경 같은 작업에 적합하고, agent.md는 평소 AI 작업의 기본 규칙과 최신 기준을 유지하는 용도에 더 가깝다.

🧩 배경과 문제 정의

이 영상은 Vercel의 실험을 바탕으로, AI에게 최신 프레임워크 지식을 적용시키는 방식 중 agent.md와 스킬이 왜 다른 성과를 냈는지 설명한다.
실험 결과는 agent.md가 100점, 스킬은 강하게 사용을 지시해도 79점에 머물렀다는 대비에서 출발한다.
문제의 핵심은 AI가 학습 이후 등장한 Next.js 16 같은 최신 기능을 모르는 상태에서, 기존 기억에 의존해 코드를 작성할 수 있다는 점이다.
스킬은 필요한 순간에 호출되면 유용하지만, AI가 스스로 호출 여부와 순서를 판단해야 하므로 자동 호출 실패와 프롬프트 민감성이 생긴다.
반면 agent.md는 프로젝트 안에 항상 놓여 있는 짧은 기준 문서처럼 작동해, AI가 최신 규칙과 프로젝트 맥락을 지속적으로 참조하도록 만든다.
따라서 영상의 문제의식은 “AI에게 더 똑똑한 도구를 주는 것”보다 “AI가 놓치지 않게 중요한 정보를 항상 눈앞에 두는 것”이 더 안정적인가에 맞춰져 있다.

🕒 시간순 섹션별 상세정리

1. Vercel 실험의 문제의식과 두 방식의 대비

Vercel은 AI에게 일을 시키는 방식으로 스킬과 agent.md를 비교했고, 결과는 agent.md 100점, 스킬 79점으로 갈렸다 [00:02]
이 비교는 AI가 최신 문서를 제대로 참고하지 못할 때, 같은 작업에서도 지시 방식에 따라 결과 품질이 크게 달라질 수 있음을 보여준다 [00:17]
AI는 학습 이후 등장한 Next.js 16의 새 기능을 모르는 상태라, 최신 기능을 요구받아도 과거 지식으로 코드를 작성할 위험이 커졌다 [01:08]
그래서 영상은 단순히 “AI가 코드를 잘 짜느냐”가 아니라, AI가 모르는 최신 정보를 어떤 방식으로 안정적으로 보게 만들 것인가를 문제로 제기한다 [01:23]

2. 실험 설계와 점수 차이

스킬은 필요할 때 꺼내 보는 전문 매뉴얼 묶음이고, agent.md는 프로젝트 폴더에 항상 놓인 텍스트 파일로 설정됐다 [01:43]
이 차이는 정보가 “필요할 때 호출되는가”와 “처음부터 작업 맥락 안에 들어와 있는가”의 차이로 압축된다 [01:58]
실험은 아무 도움 없는 상태, 스킬을 알아서 쓰게 둔 상태, 스킬 사용을 강하게 지시한 상태, agent.md를 둔 상태의 네 조건으로 구성됐다 [02:26]
점수 차이는 스킬 자체의 정보 품질만이 아니라, AI가 그 정보를 실제 작업 중에 얼마나 안정적으로 참조했는지가 성패를 갈랐음을 시사한다 [02:41]

3. 스킬이 실패한 이유와 자동 호출의 취약성

스킬의 첫 번째 실패 원인은 AI가 매뉴얼 존재를 알아도 열 번 중 거의 여섯 번은 펼쳐 보지 않는다는 점이며, 옛 기억으로 일을 처리하면 새 기능 문제에서 오류가 난다 [04:00]
즉 스킬은 존재하는 것만으로 충분하지 않고, AI가 “지금 이 문서를 열어야 한다”는 판단까지 정확히 해야 효과가 난다 [04:15]
자동으로 스킬을 불러야 하는 상황에서도 AI가 호출을 지나치는 경우가 많아, 수동으로 “지금 이 스킬을 써”라고 지정하는 방식이 더 확실해진다 [04:26]
이 대목에서 스킬의 약점은 내용 부족이 아니라 호출 타이밍과 사용 여부가 AI의 판단에 맡겨진다는 구조적 취약성으로 압축된다 [04:41]

4. agent.md가 강한 이유와 문서 압축 전략

agent.md는 볼지 말지 결정하는 순간을 없애고, AI가 일하는 모든 순간에 같은 문맥을 옆에 두기 때문에 호출 타이밍을 놓칠 가능성이 줄어든다 [05:27]
그래서 agent.md는 별도의 도구 호출보다, 작업 환경 안에 기본 규칙과 최신 지식을 상시 배치하는 방식에 가깝다 [05:42]
핵심 원리는 AI에게 선택을 시키지 않는 것이며, 똑똑한 도구를 능동적으로 쓰게 만드는 방식보다 필요한 정보를 항상 보이게 두는 방식이 안정적이다 [06:12]
이 관점에서 문서는 길고 방대한 매뉴얼보다, AI가 계속 참고할 수 있도록 압축된 기준과 목차 형태로 제공될 때 더 실용적이다 [06:27]

5. 스킬과 agent.md의 역할 분담과 적용 방법

스킬은 프로젝트 전체 마이그레이션이나 구조 변경처럼 사용자가 시점을 정해 호출하는 특별한 작업에 적합하고, agent.md는 평소 기본 지식을 항상 유지하는 안내문에 가깝다 [07:34]
따라서 두 방식은 어느 하나가 완전히 대체한다기보다, 상시 참조가 필요한 기본 규칙은 agent.md, 특정 시점에 필요한 절차적 작업은 스킬로 나누어 쓰는 편이 적절하다 [07:49]
Next.js 프로젝트에서는 npx next codemod@latest agent.md 한 줄로 프로젝트 버전 확인, 맞춤 문서 다운로드, 압축 목차 삽입까지 자동으로 처리할 수 있다 [08:28]
제공된 section-detail 기준으로는 08:28 이후의 구체 발언 내용이 충분히 제시되지 않았으므로, 영상 말미의 결론·마무리 논지는 원문 transcript 확인이 필요하다 [10:32]

🧾 결론

영상의 핵심 메시지는 AI에게 더 많은 도구를 주는 것보다, 헷갈릴 선택지를 줄이고 필요한 기준을 항상 눈앞에 두는 설계가 더 효과적이라는 것이다.
스킬이 완전히 무용하다는 뜻은 아니다. 다만 자동 호출에 의존하면 AI가 매뉴얼을 보지 않는 순간이 생기므로, 중요한 작업에서는 사용자가 직접 호출 시점과 순서를 지정하는 편이 더 안전하다.
agent.md의 강점은 거대한 문서를 모두 넣는 데 있지 않고, AI가 최신 문서와 프로젝트 규칙을 찾아갈 수 있도록 짧고 명확한 목차와 기준을 제공하는 데 있다.
Next.js 사례처럼 빠르게 바뀌는 기술 환경에서는 AI의 과거 학습 지식이 오히려 오류 원인이 될 수 있으므로, 프로젝트별 최신 기준 문서를 함께 관리하는 습관이 중요하다.

📈 투자·시사 포인트

AI 개발 도구의 경쟁력은 모델 성능뿐 아니라, 모델이 언제 어떤 문맥을 보게 만들지 설계하는 컨텍스트 운영 방식에서 갈릴 수 있다.
기업이나 팀이 AI 코딩을 도입할 때는 “좋은 프롬프트”보다 “항상 참조되는 짧은 프로젝트 규칙 문서”를 표준화하는 것이 생산성 향상에 더 직접적일 수 있다.
스킬·매뉴얼·문서 자동화 도구는 단독 제품 가치보다 워크플로 안에서 실제로 호출되고 참조되는 구조를 만들 때 가치가 커진다.
빠르게 변하는 프레임워크나 라이브러리를 쓰는 팀일수록, AI가 오래된 지식으로 판단하지 않도록 최신 문서 링크, 금지 패턴, 프로젝트 규칙을 루트 문서에 압축해 두는 전략이 유효하다.
검증이 필요한 부분은 영상에서 소개된 Vercel 실험의 원문 조건, 평가 기준, 점수 산정 방식이다. 이 영상만으로는 실험의 전체 샘플 수나 평가 세부 기준까지 독립적으로 확정할 수 없다.

⚠️ 불확실하거나 확인이 필요한 부분

Vercel 실험의 점수인 agent.md 100점, 스킬 79점, 무도움/자동 스킬 53점은 영상에서 인용된 수치이므로, 실제 실험 조건과 평가 기준은 Vercel 원문 자료로 확인이 필요하다.
“AI가 매뉴얼 존재를 알아도 열 번 중 거의 여섯 번은 펼쳐 보지 않는다”는 설명은 영상 내 해석으로 제시되며, 어떤 모델·프롬프트·작업 범위에서 나온 비율인지는 별도 검증이 필요하다.
npx next codemod@latest agent.md가 프로젝트 버전 확인, 맞춤 문서 다운로드, 압축 목차 삽입까지 자동 처리한다는 부분은 Next.js 환경과 버전에 따라 동작이 달라질 수 있으므로 실제 프로젝트에서 실행 전 공식 문서 확인이 필요하다.
자막 기반 정리: 타임스탬프가 있는 자막을 기준으로 정리했으며, 고유명사·수치·인용은 원문 확인 필요 시 별도 검증한다.
영상 속 주장: 발표자의 해석·전망·비교는 확인된 외부 사실이 아니라 영상 속 주장으로 분리해 읽는다.
검증 필요: 수치, 기업 실적, 정책·시장 전망은 발행 전 최신 자료로 별도 검증이 필요하다.

✅ 액션 아이템

현재 프로젝트 루트에 AI가 항상 참고해야 할 짧은 기준 문서가 있는지 확인한다.
기준 문서가 없다면 프로젝트 규칙, 폴더 구조, 스타일 가이드, 자주 틀리는 구현 기준을 짧게 정리한 agent.md를 만든다.
AI에게 맡기는 작업 중 “항상 알아야 하는 기본 지식”과 “특정 시점에만 호출할 전문 작업”을 구분해, 전자는 agent.md, 후자는 스킬이나 별도 매뉴얼로 분리한다.
문서가 너무 길다면 전체 설명을 넣기보다 목차, 핵심 규칙, 참조 위치 중심으로 압축한다.