새 글을 하나 추가하는 절차는 이 저장소에서 그렇게 복잡하지 않습니다. 그런데 매번 이런 걸 다시 설명하게 됩니다.

기존 글을 복사해서 front matter 를 채우고, ko/en 을 반드시 같이 만들고, date 는 양쪽 같은 값으로, 본문은 마크다운이 아니라 HTML 이고 posts.css 의 기존 클래스를 쓰고, 링크는 나보다 먼저 게시되는 글로만 걸고, 다 되면 npm run build 를 돌려서 통과하는지 보고...

세 번째쯤 되면 두 가지가 눈에 띕니다. 첫째, 매번 조금씩 빠집니다. 둘째, 빠지는 항목이 매번 다릅니다.

진짜 비용은 타이핑이 아니라 일관성입니다. 같은 작업인데 매번 다른 지시를 주면 결과도 매번 다릅니다.

1. 무엇을 스킬로 만들지

모든 반복이 스킬 감은 아닙니다. 기준은 이렇게 잡았습니다.

  • 세 번 이상 했는가. 두 번은 우연이고 세 번부터 패턴입니다.
  • 절차에 순서가 있는가. 단일 질문은 그냥 물으면 됩니다.
  • 빠뜨리기 쉬운 단계가 있는가. 이게 핵심입니다 — 잊어버리는 단계가 있어야 굳힐 값어치가 있습니다.

세 번째가 가장 중요합니다. 절차가 길어도 각 단계가 자명하면 스킬이 필요 없습니다. 반대로 짧아도 "이것도 같이 해야 한다"가 있으면 스킬로 만들 값어치가 있습니다.

애매할 때는 점수로 매긴다

세 기준 중 두 개만 걸리는 애매한 경우가 자주 나옵니다. 그럴 때 쓰는 배점입니다. 세 번째 기준에만 가중치를 더 줬습니다.

질문 아니오 약간 예 ──────────────────────────────────────────────────── 세 번 이상 했는가 0 1 2 단계에 순서가 있는가 0 1 2 빠뜨리면 한참 뒤에 드러나는 단계가 있는가 0 2 3 매번 같은 결과가 나와야 하는가 0 1 2 ──────────────────────────────────────────────────── 합계 0~3 그때그때 말로 시킨다 합계 4~6 규칙 문서에 한 줄 적으면 충분하다 합계 7 이상 스킬로 굳힌다

"빠뜨리면 한참 뒤에 드러나는가"라고 쓴 게 의도적입니다. 바로 티가 나는 실수는 어차피 그 자리에서 잡힙니다. 비싼 건 몇 주 뒤에 발견되는 누락입니다 — 리다이렉트를 안 걸어서 색인이 깨진 걸 한 달 뒤에 아는 식입니다.

이 저장소에서 실제로 굳힌 건 이런 것들입니다.

글 추가 ko/en 한 쌍 · front matter · 빌드 검증 페이지 추가 양쪽 로케일 · staticPages.js · vercel.json 리다이렉트 예약 게시 회차 큐 파일 · 항목별 커밋 · PR

두 번째가 좋은 예입니다. 새 페이지를 만드는 것 자체는 쉽습니다. 그런데 sitemap 목록과 리다이렉트를 같이 고쳐야 하고, 이건 빌드가 안 잡아줍니다. 매번 잊습니다.

2. 스킬 안에 무엇을 적나

처음에는 스킬을 "긴 프롬프트를 저장해둔 것"으로 썼습니다. 잘 안 됐습니다. 지금은 이 네 가지를 적습니다.

언제 쓰는지

스킬 설명은 선택을 위한 정보입니다. "글 추가"보다 "새 블로그 글을 ko/en 한 쌍으로 추가하고 빌드 검증까지 한다"가 낫습니다. 언제 안 쓰는지도 적으면 더 좋습니다.

순서가 있는 단계

순서가 중요한 곳만 번호를 매깁니다. 순서가 상관없는 걸 번호로 적으면 불필요한 직렬화가 생깁니다.

1. 기존 글을 복사해 두 로케일 파일을 만든다 2. front matter 를 채운다 — date 는 양쪽 같은 값 3. 본문을 쓴다 (HTML, posts.css 기존 클래스) 4. npm run build — 통과할 때까지 고친다 5. 통과하면 커밋한다. 통과 못 한 글은 커밋하지 않는다

빠뜨리기 쉬운 것

스킬이 존재하는 이유입니다. 여기가 제일 중요합니다.

- 페이지를 추가·이동했으면 _data/staticPages.js 를 같이 고친다. 빌드가 안 잡아준다. - 경로를 옮겼으면 vercel.json 에 리다이렉트를 추가한다. 기존 URL 이 검색 인덱스에 남아 있으므로 삭제만 하면 안 된다.

완료 조건

"다 됐다"의 기준입니다. 여기서는 npm run build 통과와, 빌드가 못 잡는 항목의 육안 확인입니다.

합치면 이런 골격이 된다

네 가지를 한 파일에 넣으면 이렇습니다. 실제로 쓰는 "글 추가" 스킬의 뼈대입니다.

# 언제 쓰는지 — 선택을 위한 정보 새 블로그 글을 ko/en 한 쌍으로 추가하고 빌드 검증까지 한다. 기존 글 수정·삭제에는 쓰지 않는다. # 순서 — 순서가 중요한 것만 번호 1. 기존 글을 복사해 ko/en 두 파일을 만든다 2. front matter 를 채운다 — date 는 양쪽 같은 값 3. 본문을 쓴다 (HTML · posts.css 기존 클래스) 4. npm run build # 빠뜨리기 쉬운 것 — 이 스킬이 존재하는 이유 - 페이지를 추가·이동했으면 _data/staticPages.js 를 같이 고친다 - 경로를 옮겼으면 vercel.json 에 리다이렉트를 추가한다 - 링크는 나보다 먼저 게시되는 글로만 건다 # 완료 조건 - npm run build 통과 - 통과 못 한 글은 커밋하지 않는다

길이는 이 정도가 상한입니다. 이보다 길어지면 대개 규칙 문서에 있어야 할 내용이 흘러들어온 것입니다.

3. 스킬 · 규칙 문서 · 빌드 가드의 역할 분담

셋 다 에이전트 동작에 영향을 주는데 성격이 다릅니다. 어디에 무엇을 둘지가 실제로 자주 헷갈립니다.

빌드 가드 항상 적용 · 위반 시 진행 불가 → 기계적으로 검사 가능한 불변식 규칙 문서 항상 적용 · 위반해도 진행됨 → 저장소 전체에 걸친 판단 기준 스킬 특정 작업에서만 · 호출해야 적용 → 순서 있는 절차, 빠뜨리기 쉬운 단계

구분선은 적용 범위입니다. "글 본문은 HTML이다"는 어떤 작업을 하든 참이니 규칙 문서에 갑니다. "글을 추가할 때는 이 순서로 한다"는 그 작업에서만 의미가 있으니 스킬에 갑니다.

그리고 기계적으로 검사 가능하면 셋 중 어디도 아니라 빌드로 갑니다. ko/en 대칭이 스킬 단계가 아니라 빌드 가드인 이유입니다. 스킬은 호출해야 적용되지만, 빌드 가드는 스킬을 안 써도 적용됩니다.

스킬 안의 단계가 "검사 가능한 규칙"이면 잘못된 위치입니다.

스킬은 놓치기 쉬운 절차를 안내하는 것이지, 불변식을 강제하는 수단이 아닙니다. 강제해야 하는 건 스킬을 우회해도 걸려야 합니다.

어디에 둘지 정하는 순서

새 규칙이 하나 생겼을 때 위에서부터 내려가며 답하면 위치가 정해집니다. 순서가 중요합니다 — 위쪽이 더 강한 보장입니다.

1. 기계적으로 검사할 수 있는가? 예 → 빌드 가드. 여기서 끝낸다. 아니오 → 2번 2. 특정 작업에서만 의미가 있는가? 아니오 → 규칙 문서 (저장소 전체에 걸친 판단 기준) 예 → 3번 3. 순서가 있거나 빠뜨리기 쉬운 단계가 있는가? 예 → 스킬 아니오 → 어디에도 두지 않는다 (자명한 건 적을 값어치가 없다)

1번에서 걸리는데도 규칙 문서에 적어둔 항목이 이 저장소에 꽤 있었습니다. ko/en 대칭, 글끼리 링크 방향, 두 로케일의 date 일치 — 셋 다 빌드로 옮기고 나서야 실제로 지켜졌습니다. 문서에 적혀 있는 동안에는 계속 어긋났습니다.

3번의 "아니오"도 실제로 자주 나옵니다. 적을 게 있어 보여서 스킬을 만들었는데 열어보면 자명한 한 줄뿐인 경우입니다. 그런 건 그냥 지웠습니다.

4. 자주 한 실수

스킬이 규칙 문서를 복사한다

처음에 스킬 안에 규칙을 그대로 옮겨 적었습니다. 그러다 규칙이 바뀌면 두 곳이 어긋납니다. 그리고 어느 쪽이 최신인지 아무도 모릅니다.

지금은 스킬에서 가리키기만 합니다. "front matter 필드는 CLAUDE.md의 표를 따른다." 규칙이 바뀌면 한 곳만 고칩니다.

스킬을 너무 크게 만든다

"블로그 관리" 같은 스킬을 만들면 글 추가·수정·삭제·목록 정리가 다 들어갑니다. 그러면 매번 절반이 무관한 내용이고, 언제 써야 할지도 애매해집니다. 작업 하나에 스킬 하나가 낫습니다.

결정을 스킬에 박아넣는다

스킬은 어떻게를 담고 무엇을은 담지 않는 편이 낫습니다. "글 추가" 스킬에 주제 목록까지 넣으면 그건 스킬이 아니라 계획입니다. 계획은 따로 남기는 편이 낫습니다.

5. 굳히지 않은 것

절차가 반복되는데도 일부러 스킬로 만들지 않은 것들이 있습니다.

  • 한 번만 하는 작업. 재사용이 없으면 굳힐 이유가 없습니다.
  • 매번 판단이 달라지는 작업. 절차가 아니라 결정이라면 스킬이 오히려 방해가 됩니다.
  • 단계가 하나뿐인 작업. 그냥 그렇게 말하면 됩니다.

두 번째가 미묘합니다. "글을 어떤 주제로 쓸지"는 반복되지만 매번 답이 달라야 합니다. 이걸 스킬로 굳히면 매번 비슷한 글이 나옵니다. 반복되는 것과 굳혀야 하는 것은 다릅니다.

스킬이 있는데도 안 지켜질 때

만들어 놓은 스킬이 실제로는 적용되지 않는 경우가 있습니다. 넷으로 나뉘었고, 증상이 서로 다릅니다.

증상 원인 고치는 곳 ────────────────────────────────────────────────────────── 스킬이 아예 안 불린다 설명이 "무엇을"만 적혀 description 에 있고 "언제"가 없다 언제 쓰는지 추가 절반이 무관한 단계다 스킬 하나가 여러 작업 단위로 쪼갠다 작업을 덮고 있다 문서와 다르게 동작한다 규칙을 스킬이 복사해 복사를 지우고 두고 원본이 바뀌었다 가리키기로 바꾼다 "다 됐다"의 기준이 매번 완료 조건이 없다 검증 명령을 명시 다르다 (여기서는 빌드)

가장 흔한 건 첫 줄입니다. 설명에 글 추가라고만 써두면 언제 골라야 할지가 없어서, 절차가 아무리 잘 적혀 있어도 열리지 않습니다. 스킬의 설명은 내용 요약이 아니라 호출 조건입니다.

세 번째 줄은 저장소 구조와도 얽힙니다. 규칙 문서가 여러 곳에 흩어져 있으면 스킬이 어느 쪽을 가리켜야 할지부터 애매해집니다. 문서를 어디에 둘지를 먼저 정해두면 이 문제가 절반은 사라집니다.

자주 묻는 질문

스킬과 슬래시 커맨드는 다른 건가요?

호출 방식이 다릅니다. 슬래시 커맨드는 사람이 직접 이름을 쳐서 부르고, 스킬은 설명을 보고 필요할 때 열립니다. 그래서 스킬은 설명이 곧 인터페이스입니다. 매번 사람이 부를 작업이면 커맨드로 충분하고, 에이전트가 알아서 골라야 하면 스킬이어야 합니다.

스킬을 몇 개까지 두는 게 좋나요?

개수보다 경계가 겹치는지가 문제입니다. 이름만 봐서 어느 걸 써야 할지 모르는 두 스킬이 있으면 개수가 적어도 이미 많은 겁니다. 이 저장소는 세 개인데, 셋의 대상(글·페이지·회차)이 서로 겹치지 않아 고르는 데 시간이 안 듭니다.

스킬이 호출되지 않으면 어떻게 하나요?

거의 항상 설명 문제입니다. 대상(무엇을)·시점(언제)·제외(언제 안 쓰는지) 세 가지가 설명에 다 들어가 있는지 봅니다. 그래도 안 열리면 그 작업은 애초에 매번 사람이 시작하는 작업일 가능성이 높습니다 — 그러면 커맨드로 바꾸는 게 맞습니다.

스킬 안에 스크립트를 넣어도 되나요?

넣을 수 있으면 대개 스크립트만 남기고 스킬은 지우는 편이 낫습니다. 절차 전체가 자동화된다면 그건 절차가 아니라 명령 하나입니다. 스킬은 자동화가 안 되는 판단이 사이사이 끼어 있을 때 값어치가 있습니다.

규칙 문서가 있으면 스킬이 필요 없지 않나요?

적용 범위가 다릅니다. 규칙 문서는 항상 적용되지만 항상 적용된다는 건 항상 읽힌다는 뜻이기도 합니다 — 무관한 작업에서도 컨텍스트를 차지합니다. 특정 작업에서만 필요한 20줄짜리 절차를 규칙 문서에 넣으면 나머지 모든 작업이 그 값을 냅니다. 스킬은 그 비용을 필요한 순간으로 미룹니다.

스킬이 자주 바뀌면 어떻게 관리하나요?

스킬이 자주 바뀐다면 대개 거기에 계획이 섞여 있는 것입니다. 절차는 잘 안 바뀌고 계획은 매번 바뀝니다. 이 저장소에서는 회차별로 달라지는 내용을 전부 예약 게시 큐 파일로 빼고 스킬에는 "큐 파일을 읽어서 미완료 항목부터 한다"만 남겼습니다. 그 뒤로는 스킬을 고칠 일이 없었습니다.

6. 정리

스킬로 얻은 건 시간 절약이 아니라 일관성이었습니다. 같은 작업이 매번 같은 순서로, 같은 검증을 거쳐 끝납니다.

  • 세 번째 같은 설명을 쓰고 있으면 굳힐 때입니다.
  • 빠뜨리기 쉬운 단계가 있는 절차만 굳힙니다. 자명한 절차는 스킬이 필요 없습니다.
  • 규칙은 규칙 문서에, 절차는 스킬에, 검사 가능한 건 빌드에.
  • 스킬은 규칙을 복사하지 말고 가리킵니다. 복사는 어긋납니다.
  • 어떻게는 담고 무엇을은 담지 않습니다. 결정은 계획에 남깁니다.

반복되는 작업을 매번 다시 설명하고 있다면, 그 설명을 한 번만 제대로 써서 저장소에 넣어보세요. 사라지는 건 타이핑이 아니라, 매번 조금씩 달랐던 결과입니다.