혼자 쓰던 판단을 남이 설치해 쓰게 만들기 — 스킬화와 패키징

앞 편은 운영에서 얻은 판단을 뽑아내는 데까지 왔다. 이 편은 뽑아낸 것을 남에게 건네는 방법을 다룬다.

건네는 방법은 둘뿐이다. 말로 설명하거나, 도구의 형태로 만들어 넘기거나. 앞의 것은 건넬 때마다 같은 설명을 되풀이해야 하고 받는 쪽이 얼마나 알아들었는지에 따라 결과가 달라진다. 뒤의 것은 한 번 만들어 두면 받는 사람이 자기 자리에 설치해 자기 소재로 돌린다. 이 편이 다루는 것은 뒤쪽이고, 그 도구의 이름이 에이전트 스킬(Agent Skills)이다.

여기서 다루는 것은 스킬 하나를 만드는 일부터 여럿을 묶어 내보내는 일까지이며, 그렇게 만든 것을 자기 이력으로 설명하는 방법은 다음 편의 몫이다.

정해진 자리에 놓인 파일 하나가 스킬이다

넷째 줄이 이 표에서 걸리기 쉬운 자리다. 파일을 아무리 잘 써도 자리를 벗어나 있으면 없는 것과 같다. 자리가 규약이기 때문이며, 규약을 지켰는지는 사람이 아니라 읽어 들이는 쪽이 판정한다.

「무엇을 하나」가 아니라 「언제 부르나」를 적는다

왼쪽 칸이 틀린 설명인 것은 아니다. 문제는 그 문장이 언제 이것을 꺼내야 하는지를 하나도 알려 주지 않는다는 데 있다. 스킬은 사람이 이름을 외워 두었다가 부르는 것이 아니라 상황을 만났을 때 저절로 걸려야 하는 것이고, 걸리게 만드는 정보는 기능 설명이 아니라 상황 묘사다. 그래서 오른쪽 칸에는 막막하다는 말과 뽑고 싶다는 말이 그대로 들어간다.

한 번 만들어 수천 번 쓰는 것은 손으로 짜지 않는다

세 번째 칸에서 두 번째로 돌아가는 화살표가 이 순서의 핵심이다. 시험은 통과 여부를 확인하는 절차가 아니라 정의 파일을 고쳐 쓰게 만드는 입력이다. 주제를 두셋 바꿔 넣어 보고도 출력의 골격이 유지되어야 비로소 묶을 수 있다.

한 번 쓰고 버릴 것이라면 이 순서를 밟을 이유가 없다. 스킬이 이 대접을 받는 것은 한 번 만들어 수백 번 수천 번 불리기 때문이고, 그 횟수만큼 초안의 결함도 되풀이되기 때문이다. 이 순서를 대신 밟아 주는 것이 스킬 생성기(skill-creator)다.

규약을 파일 안에 박아 둔다

---
name: discover
description: 새 주제나 시장이나 기능을 조사해야 하는데 무엇을 어디서
  어떻게 찾을지 막막할 때. 조사 방향과 후보 소스와 검색어와 검증 순서를 짤 때.
---

## 규약
   사실에는 출처를 붙인다. 확인 못 한 것에는 [리서치], 추정에는 [시뮬].
   단정하지 않는다. 모르면 되묻는다.

## 입력
   조사 주제 한 문단 — 무엇을, 왜, 결정에 무엇이 필요한지

## 처리
   1 질문 분해   주제를 핵심 질문 3~5개로 쪼갠다
   2 소스 지도   질문마다 후보 소스 유형을 붙인다
                 (논문 · 공식 통계 · 뉴스 · 경쟁사 · 커뮤니티)
   3 검색어      질문마다 구체적인 검색어 두셋을 한국어와 영어로
   4 검증 순서   먼저 볼 것 → 다음 → 교차 검증

## 출력
   질문맵 · 후보 소스표 · 검색어 · 다음 한 걸음

규약이 파일 안에 들어 있다는 점이 중요하다. 부를 때마다 「출처를 붙여라」를 덧붙이는 것과 파일에 박아 두는 것은 결과가 다르다. 앞의 것은 잊으면 사라지고 뒤의 것은 잊어도 걸린다. 되풀이되는 실수는 다음 셋이며, 고치는 자리는 전부 파일 안이다.

파일 하나로 줄 것인가 묶음으로 줄 것인가

둘은 어느 쪽이 낫고 못한 관계가 아니라 쓰임이 다르다. 옆자리에 한 번 건네는 데 카탈로그까지 만들 이유가 없고, 열 사람이 각자 설치해 쓸 것을 파일로 돌리면 누가 어떤 판을 들고 있는지 아무도 모르게 된다. 갈림길은 한 사람에게 한 번 건네고 마는가, 여럿이 각자 설치해 판을 따라가는가에 있다.

묶음의 뼈대는 매니페스트와 스킬 폴더다

my-pm/
├─ .claude-plugin/
│   ├─ plugin.json        매니페스트
│   └─ marketplace.json   배포용 카탈로그
└─ skills/
    ├─ discover/SKILL.md
    └─ prd-writer/SKILL.md

{
  "name": "my-pm",
  "version": "0.1.0",
  "description": "PM 스킬 묶음 — 조사(discover)와 기획(prd-writer)"
}

{
  "name": "my-pm",
  "owner": { "url": "github.com/<계정>" },
  "plugins": [{
    "name": "my-pm", "source": "./",
    "category": "product-management"
  }]
}

매니페스트와 카탈로그가 나뉘어 있는 것이 처음에는 번거롭게 보인다. 앞의 것은 이 묶음이 무엇인지를 밝히고 뒤의 것은 그것을 어디서 찾을 수 있는지를 밝힌다. 혼자 쓰는 동안에는 뒤의 것이 필요 없고, 남이 설치하는 순간부터는 그것이 없으면 찾지 못한다.

설치가 한 줄이 되게 만든다

# 1) 등록하고 설치한다
/plugin marketplace add <계정>/my-pm
# 로컬에서 시험할 때는 경로를 준다: /plugin marketplace add ./my-pm
/plugin install my-pm@my-pm      # 묶음이름@카탈로그이름

# 2) 나눠 준다
cd my-pm
git init && git add .
git commit -m "my-pm v0.1.0"
git remote add origin <계정>/my-pm
git push -u origin main

여기서 걸러야 할 것이 둘이다. 비밀키와 토큰은 커밋하지 않으며 제외 목록으로 막아 둔다. 그리고 저장소의 안내 문서에 설치 명령 한 줄을 반드시 적어 둔다. 받는 사람이 읽어야 할 문장이 한 줄을 넘어가는 순간 설치는 일이 되고, 일이 된 것은 대개 미뤄진다.

내보낼 수 있는지 자기가 먼저 센다

합격을 가르는 것은 분량이 아니라 항목이다. 아래 넷은 어느 하나가 비어 있으면 나머지가 아무리 충실해도 합격으로 치지 않는다.

남이 그대로 따라 할 수 있어야 남은 것이다

이 양식이 채워지면 묶음을 짧게 설명할 수 있게 된다. 설명에 들어가는 칸은 다섯이고, 앞의 넷이 만든 사람의 이야기라면 마지막 하나는 듣는 사람의 이야기다.

모범 사례(BP)라는 말이 잘한 일을 기리는 뜻으로 쓰이면 아무것도 남지 않는다. 남는 것은 칭찬받은 결과가 아니라 다른 사람이 그대로 따라 할 수 있는 절차다. 조직이 AI 를 다루는 역량도 잘 만든 스킬이 몇 개인지가 아니라 그것이 얼마나 공유되는지로 정해진다는 것이 이 단계가 서 있는 전제다. 앞 편에서 뽑아낸 암묵지(TK)가 파일로 굳는 자리가 여기다.

골격은 그대로 두고 소재만 바꾼다

오른쪽 두 열이 바뀌는 것처럼 보이지만 실제로 달라지는 것은 소재뿐이다. 조사 스킬의 골격은 질문을 쪼개고 소스를 붙이고 검색어를 만드는 순서이며, 그 순서는 시장을 보든 경쟁사를 보든 그대로다. 네 행 어디에도 자기 일이 없더라도 가장 가까운 것을 하나 잡아 소재만 갈아 끼우면 된다.

이 편이 쓴 용어

지도편의 어휘표에서 이 편이 실제로 기대어 쓴 여섯을 다시 싣는다.

정리

세 가지가 이 편에 남는다.

첫째, 스킬은 정해진 자리에 놓인 파일 한 장이고, 걸리게 만드는 것은 기능 설명이 아니라 상황 묘사다. 무엇을 하는지 아무리 잘 적어도 언제 부르는지가 없으면 불리지 않는다.

둘째, 파일 한 장으로 건네는 것과 묶음으로 배포하는 것은 쓰임이 다르다. 갈림길은 받는 사람의 수가 아니라 판을 올릴 일이 생기는가이며, 판을 관리해야 하는 순간부터는 매니페스트와 카탈로그가 필요해진다.

셋째, 남는 것은 잘한 일의 기록이 아니라 남이 그대로 따라 할 수 있는 절차다. 한 사람의 머릿속에서 나온 판단이 파일로 굳고, 그 파일이 설치 한 줄로 건너갈 때 비로소 개인의 것이 팀의 것이 된다.

여기까지가 다섯 단계와 그것을 도구로 굳히는 방법이다. 다음 편은 그 전부를 물음의 형태로 되짚는다. 하네스를 실제로 굴려 본 사람이 자기가 만든 것을 설명해야 하는 자리에서 어떤 질문을 받게 되는지, 그리고 그 하나하나에 어느 단계의 무엇으로 답하는지가 거기서 정리된다.