Agent Skills 직접 만들기: 인터뷰 메모를 기능 실험 카드로 바꾸는 SKILL.md

AI에게 일을 맡길 때마다 같은 설명을 반복한다면, 그 설명 중 일부는 스킬로 옮길 수 있습니다. 고객 인터뷰를 정리할 때마다 “실제 발언과 내 해석을 구분해줘”, “바로 개발할 기능으로 단정하지 마”, “다음에 물어볼 질문까지 써줘”라고 말하는 식입니다. 설명을 저장하는 데서 끝나면 평범한 프롬프트 모음입니다. 언제 불러야 하는지, 어떤 파일을 읽고 어떤 형식으로 끝내야 하는지까지 묶으면 다른 자료에도 다시 쓸 수 있습니다.

이 글에서는 interview-to-experiment라는 스킬을 직접 만듭니다. 가상의 과외 강사 인터뷰를 넣고, Claude Code가 실험 카드 파일을 만드는 데까지 실행했습니다. 입력은 학습을 위해 만든 메모이며 카드 본문은 실제 생성 결과입니다. 공식 스킬 규격과 명령은 2026년 10월 5일 기준으로 확인했습니다.

가상 인터뷰를 넣고 받은 실험 카드

카드는 학생 수와 결제 의향을 비워 두고, 파일을 찾는 데 걸리는 시간도 아직 모르는 정보로 남겼습니다. 대신 과외 강사 약 다섯 명에게 파일명 규칙을 보여주고, 파일을 찾는 시간과 열어보는 횟수를 보자는 제안이 나왔습니다. 즉시 앱을 만들기 전에 인터뷰를 한 번 더 진행할 수 있는 결과입니다.

찾아 설치하기 전에, 반복되는 판단 하나를 고릅니다

처음부터 “우리 회사 마케팅 전부”를 스킬 하나에 넣으면 어떤 요청에 적용해야 하는지 흐려집니다. 이번 예제의 시작점은 인터뷰 메모이고 끝점은 기능 실험 카드입니다. 고객 인터뷰를 예약하거나 이메일을 보내거나 개발까지 진행하지 않습니다. 실제 업무에서도 입력과 결과를 이렇게 좁히면 잘못 나온 부분을 고치기 쉽습니다. 결과 카드에서 발언이 자꾸 일반화된다면 발언을 다루는 규칙만 바꾸면 됩니다.

기성 스킬을 찾는 과정도 같습니다. skills.sh에서 product, research 같은 단어를 검색하되 이름만 보고 설치하지 마세요. 원본 GitHub에서 SKILL.md와 함께 들어 있는 scripts, references 폴더를 읽습니다. 인터뷰를 정리한다고 소개하면서 실제로는 외부 서비스 업로드가 필요한 스킬도 있을 수 있습니다. 설치 수는 사람들이 얼마나 설치했는지 보여주는 값이지, 내 자료에 맞는 결과를 보장하는 점수는 아닙니다.

npx skills add vercel-labs/agent-skills --list
npx skills add vercel-labs/agent-skills --skill web-design-guidelines --agent claude-code

첫 줄은 저장소의 스킬 목록을 확인하는 명령이고, 둘째 줄은 특정 스킬을 Claude Code에 설치하는 예입니다. web-design-guidelines는 인터뷰 스킬이 아니라 웹 인터페이스를 살펴보는 용도입니다. 명령 구조를 익히기 위한 사례로 넣었습니다. 계정 전체에 설치하는 --global을 붙이지 않았으므로 프로젝트 범위에서 시작합니다. 이미 같은 이름의 스킬이 있다면 새 파일을 덮어쓰기 전에 설치 위치를 확인하세요.

SKILL.md는 작업 설명서이고, 실행 환경은 따로 있습니다

Agent Skills 형식은 폴더 하나에 SKILL.md를 두는 구조를 사용합니다. 에이전트는 이름과 설명으로 쓸 만한 스킬을 찾고, 필요할 때 본문과 참고 파일을 읽습니다. 그래서 설명란에는 “훌륭한 결과를 만든다”보다 “고객 인터뷰 메모를 기능 실험 카드로 정리할 때 사용한다”가 낫습니다. 저장된 파일 자체가 AI 모델을 실행하거나 외부 계정을 연결하는 것은 아닙니다.

문법이 비슷해도 제품별 호출 방식과 권한 설정은 다릅니다. Claude Code 전용 옵션을 다른 에이전트가 똑같이 해석한다고 생각하면 곤란합니다. 아래 예제는 Claude Code에서 직접 호출하는 방식으로 만들고, 끝부분에서 OpenCode로 옮길 때 달라지는 점을 설명합니다. 스킬 내용과 호스트 설정을 구분해 두면 새 도구가 나와도 작업 규칙 전체를 다시 쓰지 않아도 됩니다.

첫 스킬을 프로젝트 안에 만듭니다

Claude Code를 실행할 연습 폴더를 하나 준비합니다. 그 폴더 아래에 .claude/skills/interview-to-experiment/SKILL.md를 만듭니다. 프로젝트 폴더에 둔 스킬은 그 프로젝트와 함께 관리하기 좋습니다. 모든 프로젝트에서 개인적으로 쓸 규칙이라면 ~/.claude/skills/ 아래에 둘 수 있지만, 첫 시도는 팀 자료와 섞이지 않는 연습 폴더가 편합니다. Windows에서도 경로의 폴더 이름은 같으며, 파일 탐색기나 편집기로 직접 만들어도 됩니다.

interview-lab/
├─ .claude/skills/interview-to-experiment/
│  ├─ SKILL.md
│  └─ references/card-example.md
├─ notes/interview-01.md
└─ outputs/

SKILL.md의 첫 줄은 ---로 시작합니다. 그 사이의 name은 호출 이름이고 description은 언제 사용할지 알려주는 설명입니다. 이번에는 직접 명령했을 때만 실행하도록 disable-model-invocation을 넣습니다. 이 옵션과 $ARGUMENTS는 아래 Claude Code 예제를 위한 설정입니다. 다른 호스트에 그대로 옮길 때는 해당 제품의 문서를 확인해야 합니다.

---
name: interview-to-experiment
description: 고객 인터뷰 메모를 읽어 실제 발언과 관찰을 분리하고, 다음에 시험할 기능과 질문을 담은 실험 카드를 만든다. 인터뷰 정리나 고객 문제 탐색을 요청할 때 사용한다.
disable-model-invocation: true
---

입력: $ARGUMENTS에 지정한 인터뷰 메모 파일.
경로가 없거나 파일을 읽을 수 없으면 필요한 파일 하나를 요청한다.

## 작업
1. 메모에서 화자, 사용 상황, 실제 발언을 읽는다.
2. 발언을 직접 인용할 때는 원문을 바꾸지 않는다. 없는 발언은 만들지 않는다.
3. 메모에 드러난 행동과 작성자의 추정을 다른 칸에 적는다.
4. 반복되는 불편 하나를 고른다. 메모 한 명을 전체 고객의 수요로 확대하지 않는다.
5. 그 불편을 확인할 작은 실험 하나를 제안한다. 완성품 개발을 바로 권하지 않는다.
6. references/card-example.md의 항목 순서로 결과를 작성한다.
7. outputs/<입력 파일명>-experiment.md에 저장하고 파일 경로를 알려준다.

## 결과에 포함할 항목
사용 상황 / 원문 발언 / 관찰 / 아직 모르는 점 / 작은 실험 / 다음 질문

자료가 부족한 칸은 “메모에 없음”이라고 적는다.
이 작업에서는 원본 메모를 수정하거나 외부 서비스로 보내지 않는다.

설명만 길게 쓰기보다 결과의 모양을 같이 주는 편이 수정하기 쉽습니다. references/card-example.md에는 아래 정도만 넣어도 됩니다. 이 파일은 모든 인터뷰에서 똑같은 결론을 내리라는 뜻이 아닙니다. 항목 이름과 근거를 적는 위치를 정해 둔 것입니다. 이후 팀에서 쓰는 용어가 생기면 본문을 길게 늘리는 대신 이 참고 파일을 고치면 됩니다.

# 실험 카드 형식

## 사용 상황
누가, 언제, 어떤 일을 하다가 불편을 겪었는지 쓴다.

## 원문 발언
원문에서 그대로 옮긴 짧은 발언과 입력 파일명을 적는다.

## 관찰
메모에서 실제로 확인되는 행동만 적는다.

## 아직 모르는 점
판단에 필요한데 메모에는 없는 정보를 적는다.

## 작은 실험
실험 대상, 보여줄 시제품, 관찰할 행동을 한 문단으로 적는다.

## 다음 질문
고객에게 실제 경험을 더 물어볼 질문을 두 개 적는다.

샘플 메모를 넣고 직접 호출합니다

먼저 실제 고객 정보가 없는 짧은 메모로 시작합니다. 입력이 길면 무엇 때문에 결과가 바뀌었는지 찾기 어렵습니다. 아래 메모는 기능을 만들어 달라는 요청이 아니라 사용자가 이미 한 행동을 적은 예입니다. 스킬이 “태그 기능을 원하는 사용자”처럼 원문에 없는 요구를 덧붙이는지 확인하기 좋습니다.

# 인터뷰 01 · 설명용 가상 메모

화자: 개인 과외를 운영하는 강사 A
상황: 수업 뒤 학부모에게 다음 과제를 전달한다.

“수업 끝나고 메신저에서 지난번 보낸 파일을 다시 찾아요.”
“이름이 다 비슷해서 열어봐야 어떤 학생 파일인지 알아요.”
“새 앱을 또 설치해 달라고 하기는 좀 그래요.”

관찰: 강사는 학생별 폴더가 아니라 메신저 검색으로 과제를 찾았다.
인터뷰에서 확인하지 못한 내용: 학생 수, 유료 서비스 사용 의향.

/interview-to-experiment notes/interview-01.md

이 명령은 터미널의 일반 셸 명령이 아니라 Claude Code 대화창에 입력합니다. 스킬을 찾지 못하면 이름을 추측해 여러 번 입력하기보다 파일 위치부터 확인하세요. 폴더 이름이 interview-to-experiment인지, 파일명이 대문자 SKILL.md인지, 현재 대화가 interview-lab 안에서 시작했는지 봅니다. 파일은 있는데 목록에 안 보인다면 /skills에서 해당 스킬의 표시 상태도 확인할 수 있습니다.

실제로 받은 카드에는 처음 기대했던 학생별 링크 앱 대신, 종이 목업이나 파일명 규칙을 먼저 보여주는 실험이 나왔습니다. 스킬이 정하는 것은 결과 형식과 판단 규칙이므로, 매번 같은 기능 제안이 나오는 것은 아닙니다. 아래는 생성 파일에서 그대로 가져온 결과입니다.

# 실험 카드: interview-01

## 사용 상황
개인 과외를 운영하는 강사 A가 수업이 끝난 뒤 메신저로 학부모에게 다음 과제를 전달한다. 이때 지난번에 보낸 파일을 다시 찾아야 하는 불편을 겪는다.

## 원문 발언
출처: notes/interview-01.md
- “수업 끝나고 메신저에서 지난번 보낸 파일을 다시 찾아요.”
- “이름이 다 비슷해서 열어봐야 어떤 학생 파일인지 알아요.”
- “새 앱을 또 설치해 달라고 하기는 좀 그래요.”

## 관찰
- 강사는 학생별 폴더가 아니라 메신저 검색으로 과제를 찾았다. (메모의 관찰 기록)
- 발언상 파일 이름만으로는 학생을 구분하지 못하고, 파일을 열어 확인한다.

작성자의 추정은 이 칸에 넣지 않았다. 메모에는 추정이 따로 적혀 있지 않다.

## 아직 모르는 점
- 학생 수: 메모에 없음
- 유료 서비스 사용 의향: 메모에 없음
- 강사 A 외 다른 강사도 같은 불편을 겪는지: 메모에 없음
- 파일을 찾는 데 걸리는 시간과 빈도: 메모에 없음
- 학부모가 새 앱 설치를 실제로 거부하는지: 메모에 없음. 강사 A의 우려 발언만 있다.

## 작은 실험
반복되는 불편으로 "보낸 과제 파일이 학생별로 구분되지 않아 다시 찾기 어렵다"를 골랐다. 강사 A 한 명의 사례이므로 전체 고객의 수요로 보지 않고 가설로만 둔다. 개인 과외 강사 5명 안팎을 대상으로, 새 앱 없이 쓰는 종이 목업 또는 파일명 규칙 예시("학생이름_날짜_과제")를 보여준다. 최근 보낸 과제 파일 하나를 찾아 달라고 요청하고, 찾는 데 걸린 시간, 파일을 열어 확인하는 횟수, 제안한 규칙을 실제로 쓰려는지를 관찰한다. 완성품은 만들지 않는다.

## 다음 질문
1. 가장 최근에 지난번 과제 파일을 다시 찾았던 때를 처음부터 끝까지 이야기해 주시겠어요?
2. 그때 파일을 찾지 못했거나 잘못된 학생 파일을 보냈던 적이 있었나요? 있었다면 어떻게 처리하셨나요?

실행 중에는 파일이 있는데도 스킬이 목록에 안 보이는 경우를 만났습니다. 처음 사용한 --restricted 실행에서는 프로젝트 스킬이 등록되지 않았고, 모델이 SKILL.md를 직접 읽는 방식으로 진행했습니다. 프로젝트 스킬을 읽는 일반 실행 환경으로 다시 열었더니 명령 목록에 interview-to-experiment가 나타났고, /interview-to-experiment notes/interview-01.md 호출로 카드를 다시 만들었습니다. 파일을 읽었다는 메시지와 스킬이 실제 등록됐다는 상태를 구분해서 확인하세요.

한 번 잘 나온 다음에, 다른 입력으로 고칩니다

첫 메모가 잘 정리됐다는 이유로 스킬을 완성했다고 판단하지는 않습니다. 실제로 자주 만나게 될 입력을 두 개 더 준비합니다. 하나는 관찰이 거의 없는 짧은 메모, 다른 하나는 서로 반대되는 발언이 섞인 메모입니다. 인터뷰에 “학생 수를 모름”이라고 썼는데 결과에는 “다수의 학생을 관리하는 강사”라고 나온다면 모델을 바꾸기 전에 스킬의 추정 규칙부터 손봐야 합니다.

규칙을 바꿀 때는 결과가 안 나온 이유와 새 문장을 함께 기록하세요. “더 꼼꼼하게 해”는 다음 결과를 비교하기 어렵습니다. “화자가 둘 이상이면 각 사람의 발언을 먼저 나누고, 같은 행동이 나온 경우에만 공통 문제로 묶어라”는 달라진 결과를 눈으로 볼 수 있습니다. 세 입력에 같은 명령을 다시 실행해 누락이 줄었는지 확인합니다. 자동 점수 도구를 붙이기 전에도 이 정도 반복은 할 수 있습니다.

추가로 두 메모를 넣었습니다. ‘불편하다고 전해 들었다’는 짧은 메모에서는 직접 인용할 발언이 없다고 적었고, 새 앱을 원하는 사람과 설치가 부담스럽다는 사람이 함께 있는 메모에서는 두 화자의 의견을 나눴습니다. 이 두 결과는 초기 실행에서 SKILL.md와 참고 파일을 직접 읽도록 한 결과입니다. 위의 등록된 슬래시 명령 재실행은 첫 메모에만 적용했으므로 세 건 모두 같은 호출 방식으로 시험했다고 볼 수는 없습니다.

팀과 공유하거나 다른 에이전트로 옮길 때

스킬 파일만 전달하고 card-example.md를 빠뜨리면 결과 형식이 달라질 수 있습니다. 폴더 전체를 공유하고, 샘플 입력과 기대 결과도 같이 남기세요. 팀 저장소에 프로젝트 스킬을 넣으면 수정 이력을 함께 볼 수 있습니다. 개인 인터뷰 원문은 예시 파일로 섞어 배포하지 말고, 가상 메모를 사용하면 팀원도 같은 조건으로 시험해볼 수 있습니다.

OpenCode v2는 .opencode/skills뿐 아니라 .claude/skills와 .agents/skills 경로도 읽습니다. disable-model-invocation도 인식하지만 호출과 인수 처리까지 Claude Code와 모두 같지는 않습니다. 옮길 때는 입력 부분의 $ARGUMENTS를 “사용자가 대화에서 지정한 메모 파일”로 바꿉니다. “interview-to-experiment 스킬을 불러 notes/interview-01.md를 정리해줘”라고 요청하고, 실제로 스킬을 불러왔는지 대화 기록에서 확인하세요. 파일 경로와 결과 형식은 그대로 유지할 수 있습니다.

스킬 폴더에 메모 읽기 규칙을 넣었다고 Notion이나 사내 드라이브가 저절로 연결되지는 않습니다. 그 자료가 필요해질 때 MCP 연결을 추가하거나 파일로 내보내 입력으로 주면 됩니다. 지금 만든 스킬이 로컬 메모 세 개에서 원하는 카드를 꾸준히 만드는지 먼저 보세요. 다음 인터뷰가 끝나면 같은 명령에 새 파일 경로를 넣고, 결과에서 불편했던 문장 하나를 스킬에 반영하면 됩니다.