해커뉴스에 'AGENTS.md가 폴더 속 .md 파일들을 가리키게 하면 똑같은 것 아니냐'는 물음이 올라왔고, 붙은 답 7개 중 실제 차이를 짚은 건 하나였어요 — 스킬은 제목과 설명이 목록으로 떠 있어 모델이 골라 열지만, 그냥 문서는 어디 있는지 찾고 전부 읽을지 골라 읽을지까지 모델이 도구를 불러 정해야 한다는 거예요. 앤트로픽 공식 문서도 같은 구조를 명시해요 — 기본값은 '설명은 늘 컨텍스트에 있고 본문은 부를 때만 로드'이고, 늘 떠 있는 설명은 언제 쓸지 문구까지 합쳐 1,536자에서 잘려요. 다만 한 번 열린 본문은 다음 턴에도 계속 남아 매 줄이 되풀이되는 토큰 값이라, 절약은 '열리기 전까지'예요.
용어 풀이
- AGENTS.md
- 저장소에 두고 코딩 에이전트에게 프로젝트 규칙을 알려 주는 문서 파일
- CLAUDE.md
- 클로드 코드가 대화를 시작할 때 늘 읽어 들이는 프로젝트 지침 파일
- 훅
- 정해진 시점마다 자동 실행되는 검사·처리. 모델의 판단과 상관없이 걸림
운영자 인사이트
스킬은 '지키게 만드는 장치'가 아니라 '언제 읽을지 고르게 하는 장치'예요 — 공식 문서도 꼭 지켜야 할 규칙은 훅으로 강제하라고 하고, 젯브레인즈가 다시 잰 스킬들은 내건 절감치를 못 지켰어요. 사내에 깔 때 볼 곳은 '무엇을 아껴 주나'보다 '설명 한 줄이 제때 호출을 끌어오나'예요.
여러 관점으로 보기
- 공식 규격 — 세 단계로 나눠 여는 구조 시작할 때는 이름과 설명만 읽고, 과제가 맞으면 본문을, 필요하면 딸린 스크립트까지 순서대로 열어요. 앤트로픽이 만들어 공개 표준으로 풀어서 커서·코파일럿·코덱스도 같은 형식을 받아요. Agent Skills
- 아끼는 지점과 못 아끼는 지점 CLAUDE.md와 달리 스킬 본문은 쓸 때만 열려서 안 부르면 값이 거의 안 들어요. 대신 한 번 열리면 계속 남아 매 줄이 되풀이되는 값이 되고, 모델이 무시하면 훅으로 강제하라고 안내해요. Claude Code Docs
- 다시 재보니 내건 절감치와 달랐어요 젯브레인즈가 80개 과제로 재니 '코드 54% 줄여 준다'는 주장은 15%였고, 셸 출력을 줄여 준다는 스킬은 오히려 7.6% 비쌌어요. JetBrains Blog
- 새로 생긴 개념은 아니에요 앤트로픽이 2025년 10월 16일에 내놓은 형식이에요. 아홉 달 넘게 쓰인 뒤에도 '왜 필요하냐'는 물음이 남아 있는 셈이에요. Anthropic