SKILL.md 하나로 AI 에이전트가 알아서 스킬을 찾아 쓴다 — 커스텀 명령어는 이제 끝

헤드라인

Claude Code 쓰면서 `.claude/commands/` 폴더에 마크다운 파일 하나 만들어서 슬래시 명령어로 호출해본 적 있으실 거예요. 간단하고 직관적이었죠. 근데 이 사용자 지정 명령어(Custom Commands) 방식에는 구조적 한계가 꽤 있었어요.

사용자가 항상 `/` 명령어를 통해 수동으로만 호출해야 했고, AI가 스스로 판단해서 자동 실행하는 기능이 없었습니다. 명령어가 실행될 때마다 전체 프롬프트가 한 번에 로드되어 컨텍스트 윈도우를 크게 낭비했고요. 스크립트를 번들링하거나 복잡한 참조 문서를 분리해서 관리할 수 없다는 문제도 있었어요.

그래서 앤스로픽이 새로운 방식을 만들었습니다. 에이전트 스킬(Agent Skills). 단순한 단축 명령어에서 출발해서, 지금은 여러 AI 에이전트 제품이 채택하는 오픈 표준으로 발전한 녀석이에요.

0.1초 만에 의도를 파악하는 자동 호출

가장 큰 변화는 사용자가 `/` 명령어를 안 쳐도 된다는 거예요. AI 에이전트가 사용자의 의도를 파악해서 0.1초 만에 알아서 스킬을 활성화합니다. "더해줘"라고 말하면 계산기 스킬을 알아서 찾아 실행하는 식이죠.

근데 수십 개의 스킬이 설치되어 있으면 어떡하나? 매번 전부 읽을 수는 없잖아요. 여기서 점진적 정보 노출(Progressive Disclosure) 메커니즘이 핵심이에요. 에이전트가 한정된 컨텍스트 윈도우를 극도로 효율적으로 관리하기 위해 채택한 설계 원칙인데, 3단계로 나눠져 있어요.

발견(Discovery) — 세션 시작 시, 에이전트는 사용 가능한 모든 스킬의 이름(name)과 설명(description)만 카탈로그 형태로 읽어들여요. 스킬당 약 50~100개의 토큰만 소모됩니다. 이 최소한의 정보만으로 "어떤 스킬이 존재하는지", "언제 이 스킬을 써야 하는지"를 판단할 수 있어요.

활성화(Activation) — 사용자의 요청이 특정 스킬의 설명과 일치해서 에이전트가 "이거다" 싶으면, 그제야 SKILL.md 파일의 전체 본문을 컨텍스트로 읽어들입니다. 권장 크기는 5,000 토큰 이하. 사용되지 않는 스킬의 본문은 아예 무시되니까 토큰 낭비가 없어요.

실행(Execution) — SKILL.md 본문에 외부 참조 파일(scripts/, references/, assets/)의 경로가 있을 수 있는데, 에이전트는 이걸 한 번에 로드하지 않아요. 실행 과정에서 정말로 필요한 순간에만 개별적으로 로드합니다. 온디맨드.

한마디로, 목차만 훑고 → 필요한 장만 펴고 → 그 안에서도 필요한 문단만 읽는 거예요. (꽤 합리적이죠?)

SKILL.md 파일 구조 — 프론트매터 + 마크다운 본문

SKILL.md는 YAML 프론트매터와 마크다운 본문으로 나뉘어요. 프론트매터에는 메타데이터와 실행 환경을 통제하는 값들이 들어갑니다.

프론트매터 아래의 마크다운 본문은 에이전트가 읽고 따를 실제 지시사항이에요. 목적(Purpose), 명세(Specification), 리팩터링(Refinement) 3단계 구조로 나눠 작성하는 게 권장됩니다.

```yaml --- name: explain-code description: Use this skill when the user asks how a piece of code works, mentions "explain", "코드 설명", or wants to understand a complex function. disable-model-invocation: false allowed-tools: ["Read", "Bash"] context: fork agent: Explore model: sonnet --- ```

본문 작성할 때 중요한 팁이 몇 가지 있어요. 에이전트가 이미 아는 일반 지식(PDF 개념, HTTP 개념)은 과감히 빼세요. 프로젝트만의 규약, 엣지 케이스, 고유 API 패턴만 담아서 토큰을 절약해야 합니다. "users 테이블은 소프트 삭제를 하므로 항상 `where deleted_at is null` 조건을 넣어야 한다" 같은 실무적 예외 규칙이 훨씬 가치가 높아요.

복잡한 작업은 체크박스 형태의 단계별 워크플로우로 나누고, 결과물의 마크다운 구조나 데이터 포맷 템플릿을 본문에 제공하면 일관된 결과를 얻을 수 있습니다. "계획-검증-실행" 루프를 명시하는 것도 좋고요. 본문 길이는 가급적 500줄 이하로 유지하세요. 방대한 API 명세서는 references 디렉토리에 분리해두고 본문에서는 경로만 참조하는 식으로요.

고급 기능 — 동적 주입과 런타임 변수

스킬은 몇 가지 재미있는 기능을 지원해요. 본문 내에 백틱과 느낌표를 결합해서 쉘 명령어를 작성하면, 에이전트에게 프롬프트가 전달되기 전에 시스템이 해당 명령어를 먼저 실행하고 출력값을 본문에 실시간으로 주입합니다.

예를 들어 현재 PR 변경 사항을 반영하려면 본문에 `!`gh pr diff`` 같이 적어두면 돼요. 사용자가 전달한 인자도 `$ARGUMENTS`나 `$0`, `$1`로 가져올 수 있고, `${CLAUDE_SKILL_DIR}`로 스킬 폴더의 절대 경로를, `${CLAUDE_SESSION_ID}`로 현재 세션 ID를 참조할 수 있습니다.

디렉토리 구조 — 어디에 넣느냐가 범위를 결정한다

스킬을 어디에 저장하느냐에 따라 적용 범위가 달라져요.

모든 프로젝트에서 공통으로 쓰려면 `~/.claude/skills/`에, 오픈 표준 규약을 따르려면 `~/.agents/skills/`에 저장합니다. 특정 프로젝트에서만 쓸 거면 프로젝트 루트의 `.claude/skills/`나 `.agents/skills/`에 넣으면 돼요. 하위 폴더에서 작업해도 에이전트가 자동 탐색하니까, `packages/frontend/.claude/skills/` 같은 중첩 구조도 됩니다.

하나의 스킬 폴더 구조는 이렇게 모듈화하는 게 이상적이에요.

``` my-skill/ ├── SKILL.md # (필수) 메타데이터 + 핵심 지시사항 ├── scripts/ # (선택) 실행 가능한 스크립트 │ ├── analyze.py │ └── format.sh ├── references/ # (선택) API 명세서 등 부피 큰 문서 │ ├── schema.yaml │ └── guidelines.md ├── assets/ # (선택) 템플릿, 다이어그램 등 정적 리소스 │ └── report-template.md └── evals/ # (선택) 테스트 프롬프트 └── evals.json ```

scripts/에 Python이나 Bash를 분리해두면 에이전트가 매번 코드를 생성하지 않아도 되니까 일관되고 결정론적인 결과를 얻을 수 있어요. references/의 문서는 정말로 필요한 순간에만 로드되고요. evals/에는 스킬 동작 검증용 테스트 프롬프트를 넣어서 TDD 방식으로 품질을 관리할 수 있습니다.

이미 만들어진 스킬을 가져다 쓰기

skills.sh 스킬 마켓플레이스

직접 만드는 것도 좋지만, 이미 잘 만들어진 스킬이 많아요. skills.sh 사이트에 가면 검색해서 바로 설치할 수 있습니다. 가장 많이 설치된 스킬이 find-skills인데 — 스킬을 찾아주는 스킬이 인기 1위라는 게 좀 웃기긴 해요. (메타적이잖아요.)

`npx skills add vercel-labs/skills` 한 줄이면 설치 끝. 실제로 "extreme programming" 키워드로 검색해보니 `proffesor-for-testing/agentic-qe@xp-practices`라는 스킬을 찾아줬는데, TDD, Continuous Integration, Pair Programming 등 XP 핵심 실천법을 다루는 스킬이었어요. 설치 수가 60으로 인지도는 낮은 편이지만, 이런 식으로 필요한 스킬을 탐색하고 바로 쓸 수 있다는 게 포인트죠.

직접 만들어보기 — 더하기 계산기

간단한 예시로 감을 잡아볼게요. 더하기 계산 스킬입니다.

``` .agents/skills/calculator/ ├── SKILL.md └── scripts/ └── add.py ```

SKILL.md에 `description: 단순한 더하기 계산기. 사용자가 전달한 숫자들을 더한다. "더해줘", "더하기" 등의 명령어로 실행할 수 있다.`라고 적고, 본문에는 `${CLAUDE_SKILL_DIR}/scripts/add.py` 스크립트를 쓰라고 지시해두면 끝이에요.

에이전트에게 `1 2 3 4 5 더해줘`라고 프롬프트를 던지면? "더해줘"라는 키워드를 보고 calculator 스킬을 자동으로 찾아서 실행합니다. `python3 add.py 1 2 3 4 5` → 결과: 15.

`.claude/commands/`에 마크다운 파일 하나 만들고 `/` 명령어로 수동 호출하던 시절은 이제 끝인 셈이에요. SKILL.md 하나면 자동 호출, 토큰 절약, 스크립트 분리, 외부 스킬 재사용까지 전부 해결됩니다. 구조가 좀 더 복잡해진 대신 할 수 있는 것이 비교할 수 없이 많아졌죠.