스킬을 직접 만들어 보는 순서, 폴더부터 첫 실행까지

스킬은 폴더 하나와 SKILL.md 파일 하나로 시작합니다. 오늘은 그 폴더를 만드는 순간부터 첫 실행까지를 순서대로 적습니다.

스킬이 왜 필요한지부터 정한다

스킬을 만들기 전에 먼저 정할 게 있습니다. 어떤 작업을 매번 설명하고 있나, 입니다. 저는 블로그 글을 쓸 때마다 "제목은 30자 안에, 첫 문단은 세 문장으로, 사진은 다섯 장 이상" 같은 규칙을 반복해서 적고 있었습니다. 그게 스킬이 되면 한 줄로 끝납니다.

스킬은 절차를 묶어 둔 것입니다. 프롬프트와 다른 점은 파일로 남아서 어느 세션이든 꺼내 쓸 수 있다는 데 있습니다. 매번 같은 말을 붙여 넣는 대신, 스킬 하나를 불러내면 그 절차 전체가 적용됩니다.

스킬은 "이 작업은 이렇게 한다"를 파일로 고정해 두는 일입니다.

폴더부터 만든다, 이름이 곧 명령어다

프로젝트 폴더 안에 `.claude/skills/` 디렉터리를 만들고, 그 아래에 스킬 이름으로 폴더를 하나 둡니다. 예를 들어 `blog-post` 라고 하면 경로는 `.claude/skills/blog-post/` 가 됩니다. 이 이름은 나중에 `/blog-post` 처럼 부를 때 그대로 쓰입니다.

폴더 이름을 정할 때는 영어 소문자와 하이픈만 쓰는 것이 안전합니다. 띄어쓰기나 대문자가 들어가면 부를 때 헷갈립니다. 저는 처음에 `블로그 작성` 이라고 한글 폴더를 만들었다가 명령이 먹지 않아서 다시 지었습니다.

폴더 이름을 한글로 하면 안 되나요?

네, 동작은 할 수 있지만 슬래시 명령으로 부를 때 불편합니다. 영문 소문자로 통일하는 편이 낫습니다.

SKILL.md 파일을 만든다

폴더 안에 `SKILL.md` 라는 파일을 하나 둡니다. 이 파일이 스킬의 본체입니다. 맨 위에는 `---` 로 둘러싼 머리말이 들어가고, 그 안에 `name` 과 `description` 을 적습니다. `name` 은 스킬 이름, `description` 은 언제 쓰는지 설명하는 부분입니다.

이 화면은 SKILL.md 머리말을 작성한 모습입니다. `name` 과 `description` 이 보입니다.

머리말 아래에는 실제로 그 작업을 어떻게 수행할지 단계별로 적습니다. 이 본문이 길어지면 나중에 참고 문서로 분리하는 구조를 쓰기도 합니다. 처음에는 하나의 파일에 다 담아도 괜찮습니다.

description 을 어떻게 쓰는가

description 은 스킬이 언제 불려 나올지를 결정합니다. 클로드는 대화 중에 이 설명을 읽고 "지금 이 상황에 이 스킬이 필요하겠다"라고 판단합니다. 그러니까 "블로그 글을 쓸 때" 같은 넓은 표현보다는 "네이버 블로그에 마케팅 글을 쓸 때, 제목과 사진 배치 규칙이 필요할 때"처럼 구체적으로 쓰는 편이 좋습니다.

제가 처음 만든 스킬은 description 이 "블로그 글 작성" 이었습니다. 그런데 다른 작업 중에도 자꾸 튀어나와서 방해가 됐습니다. 조건을 더 좁히니 필요할 때만 나왔습니다.

description 은 스킬의 초인종입니다. 좁게 달아야 필요한 손님만 찾아옵니다.

이 화면은 description 을 수정한 뒤 다시 테스트하는 모습입니다.

user-invocable 로 직접 부르기

스킬이 알아서 나오게 할 수도 있지만, 필요할 때 직접 부르고 싶다면 머리말에 `user-invocable: true` 를 적습니다. 그러면 `/스킬이름` 으로 언제든 불러낼 수 있습니다. 저는 블로그 글쓰기 스킬을 이렇게 설정해 두고, 글을 시작할 때마다 `/blog-post` 를 입력합니다.

이 값이 없으면 스킬은 상황에 맞을 때만 자동으로 제안됩니다. 둘 다 쓸 수 있으니 작업 성격에 따라 정하면 됩니다. 반복적으로 쓰는 작업이라면 직접 부르는 방식이 더 확실합니다.

이 화면은 user-invocable 을 켠 뒤 슬래시 명령으로 스킬을 부르는 장면입니다.

첫 실행, 그리고 안 될 때 확인할 자리

파일을 저장하고 클로드 코드에서 `/스킬이름` 을 입력하면 스킬이 실행됩니다. 그런데 처음에는 잘 안 되는 경우가 많습니다. 제가 겪은 실수는 경로 오타와 머리말 형식 오류였습니다. `name` 이나 `description` 을 `---` 밖에 적어두면 인식되지 않습니다.

또 하나, 스킬을 고쳤는데도 옛날 내용이 나온다면 세션을 다시 시작해야 할 수 있습니다. 클로드 코드는 세션 시작 시 스킬 파일을 읽기 때문입니다. 이 글을 쓰는 시점 기준으로는, 파일을 수정한 뒤에는 새 세션을 여는 것이 확실합니다.

스킬이 실행이 안 되는데 어디를 봐야 하나요?

폴더 경로와 머리말 형식을 먼저 확인하세요. 그리고 세션을 새로 열어 보세요.

이 화면은 스킬이 정상적으로 실행된 결과입니다.

스킬을 한 번에 완벽하게 만들 필요는 없습니다. 첫 버전으로 실행해 보고, 결과가 마음에 안 들면 본문을 수정하면 됩니다. 저는 블로그 글쓰기 스킬을 만들고 나서도 "사진은 다섯 장 이상"이라는 조항을 넣었다가, 실제로 글을 쓰다 보니 너무 길어져서 "네 장 이상"으로 바꿨습니다.

이렇게 바꾸는 일이 잦다면, 긴 규칙은 스킬 본문이 아니라 `reference/` 폴더에 참고 문서로 빼 두는 편이 낫습니다. 스킬 본문은 절차만 남기고 세부 기준은 문서로 링크를 거는 구조입니다.

스킬은 처음부터 완벽할 필요가 없습니다. 쓰면서 고치는 것입니다.

이 화면은 스킬 폴더 안에 reference 문서를 추가한 구조입니다.

#클로드코드 #클로드스킬 #스킬만들기 #SKILL .md #클로드코드사용법 #AI업무자동화 #전주마케팅 #아비컴퍼니아비컴퍼니 드림