SKILL.md 머리말에 들어가는 것들과 각각이 하는 일

스킬을 만들려면 결국 이 파일 하나를 쓰는 일입니다.

맨 위 머리말에 무엇을 적느냐로 그 스킬이 언제 불려 나올지가 정해집니다.

저희가 쓰면서 확인한 것들을 정리했습니다.

`SKILL.md` 파일 맨 위에 `---` 로 둘러싼 부분이 있습니다.

거기가 머리말입니다. 그 아래부터가 본문입니다.

머리말에는 설정이 들어가고, 본문에는 실제 절차를 적습니다.

두 부분의 역할이 완전히 다릅니다

머리말이 "언제 어떻게 불릴지"를 정하고, 본문이 "그때 무엇을 할지"를 정합니다.

머리말을 대충 쓰면 본문이 아무리 좋아도 불려 나오지 않습니다.

폴더 이름과 맞춰 두시는 편이 헷갈리지 않습니다.

한글보다 영문 소문자에 하이픈을 쓰는 형태가 다루기 편합니다.

이름을 나중에 바꿔도 되나요

바꿀 수 있지만 폴더 이름도 함께 맞추셔야 합니다.

부르는 이름이 달라지니 팀과 쓰고 있다면 미리 알리십시오.

이름은 짧고 무엇을 하는지 드러나게 짓는 것이 좋습니다.

나중에 슬래시 명령으로 부를 생각이라면 타자 치기 편한 길이인지도 보십시오.

description

여기가 가장 중요합니다.

이 스킬을 언제 쓰는지를 적는 자리입니다.

지금 하려는 일과 이 설명이 맞으면 알아서 불러 씁니다.

무엇을 하는지가 아니라 언제 쓰는지를 적으셔야 합니다

"보고서를 만든다"보다 "월간 보고서를 요청받았을 때"가 낫습니다.

상황을 적어야 그 상황에서 걸립니다.

user-invocable

이 값을 켜 두면 슬래시 명령처럼 직접 부를 수 있습니다.

`/스킬이름` 으로 부르는 방식입니다.

상황에 맡기지 않고 내가 원할 때 부르고 싶으면 이걸 켭니다.

켜 두면 직접 부르는 것도 되고 상황에 따라 불리는 것도 됩니다.

자주 쓰는 것은 켜 두시는 편이 편합니다.

반대로 특정 상황에서만 조용히 불려 나오길 원하면 꺼 두시면 됩니다.

allowed-tools

그 스킬이 쓸 수 있는 도구를 좁히는 자리입니다.

적어 두면 그 목록 밖의 도구는 쓰지 않습니다.

파일을 읽기만 하면 되는 스킬에 쓰기 도구를 열어 둘 이유가 없습니다

범위를 좁혀 두면 사고가 날 자리가 줄어듭니다.

저희는 조사만 하는 스킬에는 읽기와 검색만 열어 뒀습니다.

머리말 아래에는 실제 절차를 적습니다.

순서대로 번호를 매겨 적으면 그대로 따릅니다.

여기에 예시를 한두 개 넣으면 결과가 훨씬 안정적입니다.

말로 설명하는 것보다 예시 하나가 낫습니다

결과물의 형태를 보여 주는 것이 특히 효과가 큽니다.

원하는 형식이 있으면 그 형식 그대로 붙여 두십시오.

본문이 길어지면 그만큼 매번 읽습니다.

그러면 느려지고 핵심이 묻힙니다.

긴 참고 자료는 하위 폴더로 빼고 본문에서 가리키기만 합니다.

어느 정도면 빼야 하나요

한 화면을 넘어가면 빼는 것을 생각해 보십시오.

저희는 `reference` 폴더를 만들어 긴 문서를 그쪽에 둡니다.

만들었는데 안 불려 나오는 경우가 있습니다.

대부분 description이 원인입니다.

지금 하려는 일과 그 설명이 안 맞으면 그냥 지나갑니다.

그 상황에서 실제로 하는 말을 그대로 넣어 보십시오.

내가 쓰는 표현이 곧 걸림쇠가 됩니다

그래도 안 되면 직접 부를 수 있게 켜 두고 쓰시면 됩니다.

안 불려 나오는 문제는 대개 본문이 아니라 머리말에 있습니다.

본문을 고치기 전에 머리말부터 다시 보십시오.

우선 폴더를 하나 만드십시오. `.claude/skills/연습` 정도면 됩니다.

그 안에 `SKILL.md` 를 만들고 머리말에 name과 description만 적어 보십시오.

본문에는 오늘 반복했던 작업의 순서를 세 줄로 적으시면 됩니다.

그 상태로 한 번 돌려 보고 나서 늘리시면 됩니다.

처음부터 완성하려 하면 시작을 못 합니다.

잘못 만들면 뭔가 망가지나요

그냥 텍스트 파일 하나입니다. 폴더째 지우면 없던 일이 됩니다.

머리말 두 줄이면 스킬 하나가 이미 만들어집니다

#클로드코드 #클로드스킬 #SKILLmd #AI자동화 #업무자동화 아비컴퍼니 드림