스킬 설명: 호출 조건을 먼저 박기

2026년 5월 3일 | 바이브코딩 Tips

---

스킬 파일을 여러 개 두기 시작하면 제일 먼저 무너지는 곳은 의외로 본문이 아니라 description 한 줄이다. 나는 처음에는 스킬을 작은 매뉴얼처럼 생각해서, 본문에 절차와 예외를 잘 적어 두면 충분하다고 봤다. 그런데 실제 코딩 에이전트 세션에서는 본문을 읽기 전 단계가 더 중요했다. 에이전트가 어떤 스킬을 열지 고르는 순간에는 긴 설명을 아직 못 본다. 그래서 스킬 설명은 기능 소개가 아니라 호출 조건을 고정하는 계약에 가까워야 했다.

스킬 설명은 전체 매뉴얼의 요약이 아니라, 어떤 작업에서 그 매뉴얼을 열지 정하는 앞단 필터에 가깝다.

기능 자랑보다 먼저 적어야 할 것

스킬 설명에 "코드 리뷰를 잘한다", "테스트를 잘 돌린다", "문서를 잘 만든다" 같은 문장만 있으면 실제 호출 시점에서는 별 도움이 안 된다. 문제는 그 스킬이 유능한지가 아니라, 지금 이 작업에서 열어도 되는지다. 같은 코드 리뷰라도 보안 리뷰인지, 스타일 리뷰인지, 릴리스 직전 회귀 확인인지에 따라 첫 동작이 완전히 달라진다. 설명이 흐리면 에이전트는 비슷한 이름의 스킬을 아무거나 열고, 그 뒤에 본문에서 방향을 다시 맞추려고 한다. 이때 이미 첫 몇 분이 새어 나간다.

내가 요즘 더 믿는 설명은 짧지만 조건이 선명한 문장이다. 예를 들면 "PR diff가 이미 있고, 병합 전 위험을 찾을 때 사용한다"는 설명은 "코드 리뷰를 수행한다"보다 훨씬 낫다. 반대로 "아키텍처 변경 범위를 아직 정하지 못한 상태에서는 사용하지 않는다" 같은 금지 조건도 좋다. 이런 문장은 멋은 없지만, 에이전트가 첫 행동을 잘못 잡는 일을 줄인다.

스킬 본문은 두 번째 문맥

스킬 본문에는 절차, 체크리스트, 실패 패턴, 검증 명령이 들어간다. 하지만 본문은 어디까지나 두 번째 문맥이다. 첫 번째 문맥은 "이 스킬을 열어도 되는가"를 판단하는 얇은 표면이다. 이 순서를 놓치면 스킬 폴더가 많아질수록 오히려 세션이 산만해진다. 에이전트는 매번 비슷한 스킬을 뒤적이고, 사람은 "그 스킬 말고 이 스킬"이라고 다시 잡아 주게 된다.

그래서 나는 스킬을 만들 때 본문을 길게 쓰기 전에 설명 줄부터 다시 본다. 이 설명만 보고도 시작 행동이 떠오르는지 확인한다. 읽어야 할 파일이 먼저인지, 테스트를 먼저 고정해야 하는지, 외부 문서를 봐도 되는지, 질문하고 멈춰야 하는지 정도가 설명에서 암시돼야 한다. 스킬 본문은 그 다음에 열리는 세부 규칙이면 충분하다.

내가 쓰는 작은 작성 순서

실제로는 거창한 포맷이 필요하지 않았다. 나는 스킬 설명을 쓸 때 아래 네 칸을 먼저 채운다. 이 네 칸이 채워지지 않으면 아직 스킬이 아니라 긴 프롬프트 조각에 가깝다고 본다.

• 대상 작업: 어떤 종류의 작업에서 이 스킬을 열어야 하는지 한 문장으로 쓴다.
• 비대상 작업: 비슷해 보이지만 이 스킬을 쓰면 안 되는 경우를 함께 둔다.
• 첫 동작: 열리자마자 읽기, 검색, 테스트, 질문 중 무엇으로 시작해야 하는지 정한다.
• 종료 증거: 완료 보고 전에 남겨야 할 산출물이나 검증 신호를 적는다.

이 네 칸은 tool contract와도 닮았다. 도구 계약서가 이번 세션의 권한과 중단 조건을 묶는다면, 스킬 설명은 스킬 자체의 진입 조건과 첫 행동을 묶는다. 둘 다 에이전트를 더 자유롭게 만드는 장치라기보다, 처음부터 잘못된 자유도를 줄이는 장치에 가깝다.

좋지 않은 설명의 냄새

좋지 않은 스킬 설명에는 몇 가지 냄새가 있다. 첫째, "전문적으로", "효율적으로", "정확하게" 같은 부사만 많고 조건이 없다. 둘째, 대상이 너무 넓다. "프론트엔드 작업에 사용" 같은 설명은 거의 항상 넓다. 화면 diff를 볼 때인지, 컴포넌트 구조를 바꿀 때인지, 접근성 회귀를 볼 때인지가 빠져 있기 때문이다. 셋째, 실패했을 때 멈추는 기준이 없다. 이런 설명은 세션이 길어질수록 에이전트가 계속 고치기만 하는 쪽으로 기운다.

반대로 좋은 설명은 조금 딱딱하다. "로그가 이미 확보된 재현 가능한 버그에서, 원인 가설을 세 개 이하로 줄일 때 사용" 같은 문장은 블로그 제목처럼 예쁘지는 않지만 스킬 설명으로는 훨씬 안전하다. 에이전트가 이 문장을 보면 먼저 로그를 읽고, 재현 가능성을 확인하고, 수정 전에 가설을 좁히는 순서로 들어갈 가능성이 높다.

references와 scripts는 늦게 열리게 두기

스킬 본문 아래에 references와 scripts를 많이 붙일 수 있다는 점도 함정이 된다. 자료가 많아질수록 스킬이 좋아진다고 느끼지만, 실제 세션에서는 모든 자료를 매번 여는 순간 컨텍스트가 금방 흐려진다. 그래서 설명과 본문은 가능한 한 얇게 두고, references는 "정말 필요할 때만" 열리도록 나눠 두는 편이 낫다. 반복 검증은 scripts로 빼되, 그 스크립트를 언제 돌리는지도 설명이나 본문 초반에 박아 둬야 한다.

이 구조가 잘 잡히면 스킬은 프롬프트 묶음이 아니라 작은 라우터처럼 동작한다. metadata에서 고르고, 본문에서 순서를 잡고, reference에서 배경을 보강하고, script에서 검증한다. 각 층이 같은 일을 반복하지 않으면 컨텍스트가 덜 붓는다.

내가 남기는 예시 문장

요즘 내가 마음에 들어 하는 설명 문장은 이런 식이다. "릴리스 노트 초안을 쓸 때 사용한다. 이미 diff나 commit 목록이 있어야 하며, 기능 설계가 아직 열린 상태라면 사용하지 않는다." 이 정도만 있어도 에이전트는 릴리스 노트와 제품 설계를 섞을 가능성이 줄어든다. 또 "재현 로그가 있는 버그에서 사용한다. 로그가 없으면 먼저 재현 질문을 만들고 멈춘다"처럼 중단 조건을 넣어 두면, 추측성 수정으로 바로 뛰어드는 일을 막을 수 있다.

나는 스킬을 늘릴수록 설명을 더 짧게 쓰려고 한다. 짧게 쓰자는 말이 정보량을 줄이자는 뜻은 아니다. 오히려 반대다. 작업 대상, 금지 대상, 첫 동작, 종료 증거만 남기면 설명 한 줄의 밀도가 올라간다. 그 한 줄이 정확하면 본문은 조금 길어도 괜찮다. 반대로 그 한 줄이 흐리면 본문이 아무리 좋아도 에이전트는 엉뚱한 문을 먼저 열 수 있다.

팀에서 같이 쓰는 스킬이라면 이 차이가 더 커진다. 사람마다 "리팩터링", "리뷰", "정리"라는 말을 조금씩 다르게 쓰기 때문이다. 설명이 호출 조건을 품고 있으면 단어 해석이 흔들려도 첫 행동은 비슷해진다. 그래서 스킬 설명은 문서의 홍보 문구가 아니라, 여러 세션이 같은 출발선에 서게 만드는 작은 합의문에 가깝다.

작은 결론

스킬은 많이 만든다고 바로 좋아지지 않는다. 호출되는 순간이 정확해야 한다. 그래서 나는 새 스킬을 만들 때 "이 스킬은 무엇을 잘하나"보다 "어떤 장면에서 열려야 하나"를 먼저 묻는다. 이 질문 하나만 앞에 두어도, 바이브코딩 세션이 덜 흘러간다. 긴 프롬프트를 더 잘 쓰는 문제가 아니라, 열어야 할 플레이북을 처음부터 좁게 고르는 문제에 더 가깝다.