클로드(Claude)에게 같은 요청을 반복하면 매번 다른 결과가 나옵니다. 톤, 구조, 어휘가 흔들립니다. 프롬프트를 아무리 정교하게 작성해도, 대화가 시작될 때마다 이전 맥락이 초기화되기 때문입니다. 클로드 스킬(Skill)은 문체 규칙, 글 구조, 작업 순서를 SKILL.md 파일에 저장하고, 클로드가 매번 이 파일을 읽어 동일한 기준을 적용하는 방식입니다. 프롬프트는 대화가 끝나면 사라지지만, 스킬에 저장된 규칙은 다음 대화에서도 그대로 작동합니다.
그래서 많은 사용자가 스킬을 만들기 시작합니다. 그런데 스킬이 2개, 3개로 늘어나면서 새로운 문제가 생깁니다. 결과물의 톤이 다시 흔들리고, 분명히 넣어둔 금지어가 뚫리고, 블로그 글을 요청했는데 엉뚱한 스킬이 호출됩니다. 원인은 스킬의 설계가 아니라 운영 규칙의 부재에 있습니다. 스킬을 안정적으로 유지하기 위해 반드시 지켜야 할 5가지 규칙을 정리합니다.
Contents
SKILL.md는 500줄을 넘기지 않습니다
SKILL.md가 길어지면 클로드는 후반부 규칙을 누락합니다. 앞부분에 적힌 워크플로우는 잘 따르면서, 뒤쪽에 적어둔 금지어나 출력 포맷은 무시하는 현상이 반복됩니다. 파일이 길수록 이 확률은 높아집니다.
500줄을 기준선으로 잡습니다. SKILL.md에는 워크플로우 흐름과 핵심 조건만 남기고, 세부 규칙은 보조 파일로 분리합니다.
분리 전 — SKILL.md에 모두 포함한 경우 (700줄 이상)
# 블로그 글쓰기 스킬
## 워크플로우
Step 1: 주제 설계 → Step 2: 구조 설계 → ...
## 문체 규칙
- 합니다체, 능동형, 한 문장 하나의 정보
...
## 금지어 목록
- 혁신적인, 획기적인, 매우, 쉽게, 완벽한
...
## 출력 템플릿
- 도입 15%, 본론 70%, 결론 15%
...
분리 후 — SKILL.md 300줄 + 보조 파일 3개
# 블로그 글쓰기 스킬
## 워크플로우
Step 1: 주제 설계 → Step 2: 구조 설계 → ...
## 참조 파일
- 문체·금지어 → writing-principles.md
- 톤·어휘 기준 → hongstyle.md
- 출력 구조 → output-template.md
SKILL.md는 전체 흐름을 관장하는 설계도 역할만 합니다. 세부 규칙은 보조 파일이 담당하는 구조가 안정적입니다.
보조 파일은 150줄 이내로 유지합니다
보조 파일도 길어지면 같은 문제가 발생합니다. writing-principles.md에 금지어, 문장 규칙, 문체 원칙, 안티패턴, 문장 예시까지 전부 넣으면 150줄을 넘깁니다. 이 시점부터 클로드가 뒷부분 규칙을 건너뛰기 시작합니다.
보조 파일 하나당 150줄 이내가 안정 범위입니다. 넘으면 역할을 더 쪼갭니다.
비대해진 보조 파일 (200줄 이상)
# writing-principles.md
## 금지어 목록 (50줄)
## 문장 규칙 (40줄)
## 안티패턴 (30줄)
## 좋은 문장 예시 20개 (60줄)
## 나쁜 문장 예시 20개 (40줄)
분리 후 (각 100줄 이내)
# writing-principles.md (100줄)
- 금지어 목록, 문장 규칙, 안티패턴
# examples.md (80줄)
- 좋은 문장 예시 10개, 나쁜 문장 예시 10개
파일 수가 늘어나는 것보다 파일 하나가 비대해지는 것이 더 위험합니다. 150줄을 넘는 순간 분리를 검토합니다.
같은 규칙을 두 곳에 쓰지 않습니다
블로그 스킬과 페이스북 스킬에 같은 금지어 목록을 각각 적어두면, 하나를 수정할 때 나머지를 빠뜨립니다. 스킬이 3개일 때는 기억으로 관리할 수 있지만, 5개를 넘으면 누락은 피할 수 없습니다.
금지어에 “효과적인”을 추가하는 상황을 예로 듭니다.
중복 구조 — 수정 필요 파일 5개
- writing-workflow/SKILL.md → 금지어 목록 수정
- blog-writing-workflow/SKILL.md → 금지어 목록 수정
- facebook-writing-workflow/SKILL.md → 금지어 목록 수정
- brunch-writing-workflow/SKILL.md → 금지어 목록 수정
- essay-workflow/SKILL.md → 금지어 목록 수정
→ 5개 중 1개라도 빠뜨리면 해당 스킬에서 "효과적인"이 그대로 출력됩니다
포인터 구조 — 수정 필요 파일 1개
- writing-principles.md → 금지어 목록에 "효과적인" 추가
→ 5개 스킬 모두 이 파일을 참조하므로 자동 반영됩니다
규칙은 한 파일에만 정의하고, 다른 스킬에서는 “writing-principles.md 참조”로 포인터만 남깁니다. 이 원칙이 무너지면 스킬이 늘어날수록 수정 누락이 쌓여 전체 품질이 무너집니다.
description에 경계를 반드시 명시합니다
스킬이 3개 이상이면 클로드가 어떤 스킬을 호출할지 혼동합니다. “글쓰기”라는 트리거 키워드가 일반 글쓰기, 블로그, 페이스북 스킬에 모두 들어가 있으면, 블로그 글을 요청했는데 일반 글쓰기 스킬이 작동하는 상황이 발생합니다.
경계가 없는 description
name: writing-workflow
description: "글쓰기 워크플로우. 트리거: 글쓰기, 글 작성, 콘텐츠 작성"
name: blog-writing-workflow
description: "블로그 글쓰기 워크플로우. 트리거: 글쓰기, 블로그 글, 포스트 작성"
→ “글쓰기”가 양쪽에 걸립니다. 클로드가 어느 스킬을 호출할지 예측할 수 없습니다.
경계가 명확한 description
name: writing-workflow
description: "칼럼, 뉴스레터, 기고문 등 단편 콘텐츠 전용.
트리거: 칼럼 글쓰기, 뉴스레터 작성, 기고문 작성.
이 스킬은 블로그·페이스북·브런치·책 집필에는 사용하지 않는다."
name: blog-writing-workflow
description: "워드프레스 블로그(sshong.com) 전용.
트리거: 블로그 글쓰기, 블로그 포스트, sshong 블로그.
이 스킬은 페이스북·브런치·일반 칼럼에는 사용하지 않는다."
트리거에 채널명을 붙이고, “사용하지 않는다” 경계를 명시합니다. 이 두 줄이 호출 충돌을 방지합니다.
스킬 수정 시 전체 폴더를 ZIP으로 관리합니다
SKILL.md에서 보조 파일명을 변경했는데 실제 파일명은 그대로인 경우, 클로드가 참조에 실패합니다. 파일 하나만 수정해도 다른 파일과의 연결이 끊어질 수 있습니다. 이런 문제는 수정 직후에는 발견되지 않고, 다음 작업에서 결과물이 이상해진 뒤에야 드러납니다.
참조 깨짐 시나리오
[수정 전]
SKILL.md → "문체 규칙은 tone-guide.md 참조"
tone-guide.md (실제 파일 존재)
→ 정상 작동
[수정 후 — 파일명 변경했으나 SKILL.md 미수정]
SKILL.md → "문체 규칙은 tone-guide.md 참조" ← 그대로
writing-principles.md (파일명 변경됨)
→ 클로드가 tone-guide.md를 찾지 못함 → 문체 규칙 무시
수정할 때마다 해당 스킬 폴더 전체를 ZIP으로 받아서 보관합니다.
blog-writing-workflow_v1.zip ← 최초 완성본
blog-writing-workflow_v2.zip ← 금지어 추가 후
blog-writing-workflow_v3.zip ← 출력 템플릿 변경 후
문제가 생기면 이전 버전으로 되돌릴 수 있고, ZIP을 열어 파일 간 참조가 정상인지 한눈에 확인할 수 있습니다. 파일 하나만 교체하는 방식보다 폴더 단위로 관리하는 것이 사고를 줄입니다.
스킬의 품질은 만드는 순간이 아니라 운영하는 동안 결정됩니다. SKILL.md 500줄, 보조 파일 150줄, 중복 금지, 경계 명시, ZIP 관리. 스킬을 새로 만들거나 수정할 때마다 이 5가지를 한 번씩 점검합니다. 이 습관이 스킬이 10개로 늘어나도 결과물이 흔들리지 않는 구조를 만듭니다.
