Claude Code 스킬 디렉토리에 파일을 중첩해도 될까요?

Claude Code의 Skills를 처음 쓰기 시작하면 SKILL.md 하나에 모든 규칙을 때려넣게 됩니다. 그러다 보면 금방 파일이 길어지고, “이 부분은 따로 빼두면 좋겠는데” 하는 생각이 드는데요. 스킬 폴더 안에 하위 파일을 자유롭게 추가할 수 있냐는 질문을 받아서, 제가 실제로 사용하는 구조와 함께 정리해봤습니다.

짧은 답변: 네, 됩니다

.claude/skills/ 아래는 그냥 파일 시스템입니다. 서브폴더를 만들고, 추가 마크다운 파일을 넣고, JSON/YAML 설정 파일을 두어도 됩니다. Claude가 SKILL.md에서 Read 도구로 그 파일들을 읽도록 지시하면 실제로 로드해서 활용합니다.

이 블로그의 blog-draft 스킬이 그렇게 구성되어 있습니다:

.claude/skills/blog-draft/
├── SKILL.md              ← 메인 진입점, 모든 절차·규칙 정의
└── templates/
    └── works.md          ← works 카테고리 글 작성 시 참조하는 양식

SKILL.md 안에는 이런 지시가 들어 있습니다:

6. 양식 reference 로드 — .claude/skills/blog-draft/templates/{category}.md 가
   존재하면 본문 작성 전에 반드시 읽는다 (없으면 skip)

Claude는 작업 흐름 6단계에 도달하면 해당 경로의 파일을 Read 도구로 열고, 거기에 담긴 톤과 구조를 본문 작성에 반영합니다. SKILL.md가 참조 문서를 직접 가져다 쓰는 셈이죠.

어떤 파일을 분리하면 좋을까요

규칙이나 절차가 아니라 참조 자료로 쓰이는 것들은 별도 파일로 빼두는 편이 관리하기 편합니다.

카테고리별·케이스별 양식 (templates/)

글 카테고리마다 톤이나 구조가 다르면, SKILL.md에 전부 인라인으로 넣는 것보다 templates/programming.md, templates/works.md 식으로 나누는 게 훨씬 읽기 좋습니다. SKILL.md는 “이 조건이면 이 파일을 읽어라”만 명시하고, 실제 예시는 각 파일에 위임하는 구조입니다.

자주 업데이트되는 참고 데이터 (data/ 또는 별도 파일)

예를 들어 태그 허용 목록, 배포 환경 URL 목록처럼 주기적으로 바뀌는 값이 있다면, SKILL.md 본문을 건드리지 않고 한 파일만 수정하면 되도록 분리해두는 게 편합니다.

실제 발행 예시 (examples/)

톤 참고용 실제 글을 스킬 폴더 안에 복사해두고 “이 글의 문장 스타일을 흉내 내라”고 지시하는 방식도 효과적입니다. 긴 글을 SKILL.md에 직접 임베드하면 토큰 비용이 매번 발생하는 반면, 외부 파일로 두면 필요할 때만 로드됩니다.

스킬이 다른 스킬을 “호출”할 수 있나요

여기서부터는 한 가지 구분이 필요합니다.

파일 읽기로 간접 연결은 됩니다. SKILL.md 안에 “이 조건이면 .claude/skills/other-skill/SKILL.md를 읽고 그 지시를 따르라”고 적으면 Claude가 그 파일을 로드합니다. 완전한 메커니즘은 아니지만, 공통 규칙을 공유하거나 보조 절차를 위임하는 용도로는 충분히 씁니다.

/skill-name 슬래시 커맨드로 다른 스킬을 직접 호출하는 건 지원하지 않습니다. 슬래시 커맨드는 사용자가 명시적으로 입력해야 트리거되는 구조라서, 스킬 내부에서 자동으로 발화할 수 없습니다.

정리하면:

방식	가능 여부	비고
스킬 폴더 안에 하위 파일 추가	가능	서브폴더 포함
SKILL.md에서 하위 파일 Read	가능	지시문에 경로 명시 필요
다른 스킬의 SKILL.md를 Read로 참조	가능 (간접)	공통 절차 공유에 유용
스킬에서 /other-skill 자동 호출	불가	슬래시 커맨드는 사용자 입력 전용

실제로 구성해본 패턴

스킬이 커지기 시작할 때 저는 이렇게 나눕니다:

.claude/skills/my-skill/
├── SKILL.md         ← 작업 흐름, 규칙, 파일 참조 지시만
├── templates/
│   ├── case-a.md    ← 케이스 A 양식·예시
│   └── case-b.md
└── config.md        ← 허용 태그 목록, 경로 규칙 등 자주 바뀌는 값

SKILL.md는 가능한 한 얇게 유지하고, 실제 내용은 참조 파일에 위임하는 전략입니다. 작업 흐름을 따라가면서 필요한 파일만 그때그때 로드하니 토큰 낭비도 줄어들고, 파일별로 수정 범위도 명확해집니다.

처음에는 SKILL.md 하나로 시작해도 충분하지만, 케이스가 늘어나거나 참조 양식이 생기기 시작하면 이 패턴으로 분리해보시길 권합니다.