소프트웨어를 개발하다 보면 AI 도구마다 지침을 따로 써야 하는 번거로운 상황을 자주 마주하게 되는데요.

‘커서(Cursor)‘를 위해 ‘.cursorrules’에 정성껏 작성한 규칙을 ‘클로드 코드(Claude Code)‘를 쓸 때는 ‘CLAUDE.md’로, ‘깃허브 코파일럿(GitHub Copilot)‘에서는 또 다른 파일로 매번 다시 수정해야 했던 파편화 문제가 우리를 괴롭혀왔습니다.

하지만 최근 ‘앤스로픽(Anthropic)‘이 ‘SKILL.md’라는 오픈 사양을 공개하며 이 문제를 아주 명쾌하게 해결했거든요.

이건 거창한 SDK나 API가 아니라 단순히 특정 폴더에 담긴 마크다운 파일일 뿐이지만 이미 ‘커서’와 ‘제미나이(Gemini)’ 등 20개가 넘는 주요 도구들이 이 방식을 채택하기 시작했습니다.

이제 여러분은 에이전트의 능력을 한 번만 정의하면 어떤 도구에서든 그대로 사용할 수 있는 시대를 맞이하게 된 것이거든요.

SKILL.md의 정체와 구성 요소

‘SKILL.md’의 핵심은 AI 에이전트에게 부여하는 ‘재사용 가능한 온디맨드 능력’이라고 할 수 있는데요.

매번 똑같은 프롬프트를 복사해서 붙여넣는 대신 하나의 스킬로 저장해 두고 필요할 때마다 호출하는 방식입니다.

파일 구조는 슬래시 명령어가 될 ‘이름’과 에이전트가 언제 이 스킬을 쓸지 판단하는 ‘설명’이 담긴 ‘YAML 프론트매터’로 시작되거든요.

그 아래에는 에이전트가 따라야 할 목표와 제약 사항이 담긴 ‘마크다운 본문’이 이어지며 실행 가능한 코드를 담은 스크립트 폴더나 체크리스트를 담은 참조 폴더를 추가할 수도 있습니다.

이 마법의 핵심은 바로 ‘경로’에 있는데 스킬을 한 번만 작성해두면 사용하는 도구에 맞는 특정 경로에 폴더를 넣어주기만 하면 바로 작동하거든요.

‘클로드 코드’는 ‘.claude/skills/’ 경로를 사용하고 ‘커서’는 ‘.cursor/skills/’ 경로를, 그리고 ‘깃허브 코파일럿’은 ‘.github/skills/’ 경로를 통해 스킬을 인식합니다.

토큰을 획기적으로 아껴주는 점진적 노출 방식

모든 규칙을 하나의 거대한 설정 파일에 몰아넣으면 AI가 매번 그 긴 글을 처음부터 끝까지 읽느라 귀중한 토큰을 낭비하게 되는데요.

심지어 너무 많은 정보는 모델을 혼란스럽게 만들어 결과물의 품질을 떨어뜨리는 원인이 되기도 합니다.

하지만 ‘SKILL.md’는 ‘점진적 노출(Progressive Disclosure)’ 방식을 사용하여 이 문제를 우아하게 해결했거든요.

가장 낮은 단계인 시작 시점에는 에이전트가 오직 모든 스킬의 이름과 설명만 읽어 토큰 소모를 극단적으로 줄여줍니다.

그러다 사용자의 질문이 특정 스킬의 설명과 일치한다고 판단되는 순간에만 비로소 ‘SKILL.md’의 전체 본문을 불러오게 되거든요.

만약 더 깊이 있는 작업이 필요하여 지침에서 요구할 때만 추가적인 스크립트나 참조 폴더의 파일들을 온디맨드 방식으로 로드하게 됩니다.

덕분에 프로젝트에 수백 개의 스킬이 등록되어 있더라도 실제 필요하기 전까지는 컨텍스트가 무거워지는 일 없이 쾌적한 작업 환경을 유지할 수 있는 것이거든요.

실전에서 빛을 발하는 스킬 활용 사례

스킬은 일반적인 프로젝트 규칙보다는 반복 가능한 ‘워크플로우’를 정의할 때 가장 큰 위력을 발휘하는데요.

예를 들어 ‘PR 리뷰어’ 스킬을 만들어두고 설명에 ‘버그나 보안 이슈를 위해 풀 리퀘스트를 검토하라’고 적어두면 여러분만의 엄격한 검토 기준을 매번 자동으로 적용할 수 있습니다.

또한 ‘UI 컴포넌트 생성기’ 스킬을 만들어 항상 특정 프레임워크와 다크 모드 설정을 포함하도록 강제할 수도 있거든요.

심지어 실행 가능한 배시 스크립트를 포함한 ‘보안 스캐너’ 스킬을 등록해두면 AI가 스스로 취약점을 찾아내고 수정까지 마치는 놀라운 경험을 하실 수도 있습니다.

전문가가 전하는 스킬 작성 노하우

성공적인 스킬 작성을 위해서는 몇 가지 기술적인 전략이 필요한데요.

우선 ‘설명’ 필드는 사람이 읽기 위한 것이 아니라 AI의 라우팅 엔진을 위한 ‘트리거’로 작성해야 합니다.

단순히 ‘테스트에 관한 스킬’이라고 쓰기보다는 ‘사용자가 유닛 테스트 작성을 요청하거나 핵심 로직을 수정할 때 이 스킬을 사용하라’는 식으로 구체적인 상황을 명시해 주는 것이 좋거든요.

또한 AI에게 딱딱한 단계별 지침을 주기보다는 ‘최종 목표’와 ‘제약 사항’ 위주로 가이드를 주는 것이 훨씬 유연한 대처를 가능하게 합니다.

무엇보다 AI가 자주 빠지는 함정을 기록해두는 ‘주의 사항(Gotchas)’ 섹션을 추가하면 같은 실수를 반복하는 일을 완벽하게 방지할 수 있거든요.

우리가 흔히 놓치는 결정적인 차이점

많은 분이 ‘SKILL.md’가 기존의 설정 파일들을 완전히 대체한다고 생각하시지만 사실 이들은 서로 보완 관계에 있는데요.

‘.cursorrules’와 같은 설정 파일이 프로젝트 전반에 항상 적용되는 ‘도로 위의 규칙’이라면 스킬은 특정 상황에서만 꺼내 쓰는 ‘플레이북의 전술’과도 같습니다.

여기에 실시간 데이터베이스나 외부 도구에 접근할 수 있게 해주는 ‘모델 컨텍스트 프로토콜(MCP)‘까지 더해지면 진정한 의미의 AI 개발 환경이 완성되거든요.

여러분도 이제 단순한 프롬프트들을 하나씩 스킬로 옮기기 시작하면서 남들보다 앞서가는 개발 생산성을 직접 확인해 보시길 바랍니다.