두 번 한 일은 스킬로 — AI에게 매뉴얼을 쥐여주는 법

2026-08-05임균영

어떤 절차를 세 번째로 설명하고 있는 저를 발견한 날이 있었습니다. 홈서버에 새 서비스를 배포할 때 순서, 조심할 점, 항상 걸리는 그 한 가지 함정. 저는 그걸 첫 세션에도, 둘째 세션에도, 셋째 세션에도 똑같이 타이핑하고 있었습니다. 그때 든 생각은 단순했습니다. "두 번 넘게 설명한 절차는, 저한테 남을 게 아니라 밖에 남아야 한다."

이전 편에서 저는 AI의 기억을 마크다운 파일에 두는 이야기를 했습니다. 이번 편은 그 확장입니다. 기억이 "무엇을 아는가"라면, 스킬은 "어떻게 하는가"입니다. 그리고 이 "어떻게"는 매 세션 다시 가르치는 순간, 곧바로 제 시간을 갉아먹는 부채가 됩니다.

정리하면 이렇습니다. 스킬은 외부화된 재사용 절차다. AI가 작업하다가 필요하면 스스로 읽어 재로딩하는 매뉴얼입니다. 이번 글에서는 언제 절차를 스킬로 승격하는지, 스킬이 어떻게 "가진 값은 싸고 쓸 때만 비싼" 구조로 작동하는지, 그리고 무엇을 스킬에 두고 무엇을 절대 스킬에 두면 안 되는지를 다룹니다.

왜 절차를 밖으로 꺼내야 하나

AI에게 매번 절차를 설명하는 건, 신입에게 매일 아침 같은 업무 매뉴얼을 구두로 읊어주는 것과 같습니다. 신입이 멍청해서가 아닙니다. 어제의 대화가 오늘로 이어지지 않기 때문입니다. 세션이 끝나면 맥락은 증발합니다.

문제는 단순한 비효율이 아닙니다. 반복 설명은 매번 미묘하게 달라진다는 데 진짜 위험이 있습니다. 오늘은 함정 하나를 빠뜨리고, 내일은 순서를 살짝 바꿉니다. 그렇게 같은 작업이 세션마다 다르게 실행되고, 결과가 흔들립니다.

제가 겪은 사례 하나. 병렬로 여러 에이전트를 돌리다가, 한 워커(작업을 나눠 맡는 하위 실행 단위)가 라이브 코드 트리에서 추적되지 않던 파일 수십 개를 지워버린 적이 있습니다. 커밋되지 않은 상태였다는 걸 그 워커는 몰랐고, 저는 그 절차에 "먼저 커밋해 상태를 고정하라"는 한 줄을 매번 넣어주지 않았습니다. 복구는 됐지만, 교훈은 분명했습니다.

교훈 — 사람의 기억에 의존하는 절차는, 사람이 한 번 깜빡하는 순간 사고가 된다. 절차는 외부에 못 박아 두어야 매번 같은 방식으로 실행된다.

두 번 이상 반복됐거나, 단 한 번이라도 '비자명한 함정'을 품은 절차라면 승격 후보입니다. 두 번이라는 숫자가 절대 기준은 아닙니다. 한 번만 겪어도 뼈아팠던 함정은 즉시 스킬로 박제하는 게 맞습니다.

스킬은 네 칸짜리 매뉴얼이다

제가 스킬을 쓸 때 지키는 형식은 고정된 네 섹션입니다. 화려할 필요가 없습니다. 오히려 칸이 정해져 있어야 빈틈이 드러납니다.

언제 쓰나 — 이 스킬이 발동해야 하는 상황. 여기가 부실하면 AI가 필요한 순간에 이 매뉴얼을 못 찾습니다.
절차 — 실제 단계. 순서와 명령을 구체적으로.
함정 — 겪어봐야만 아는 것들. 스킬의 진짜 값어치는 대부분 여기 있습니다.
검증 — 제대로 됐는지 확인하는 법.

검증 칸을 채울 때 저는 스스로 딱 하나만 묻습니다. "다음 세션에서 이 노트가 읽혀 실제로 답이 개선되는가? 같은 실수를 다시 안 하게 되는가?" 이 질문에 "그렇다"고 답할 수 없으면, 그건 스킬이 아니라 그냥 메모입니다.

가진 비용은 두 줄, 쓰는 비용은 본문 전체

스킬 설계에서 가장 아름다운 부분은 점진적 공개(필요할 때만 펼쳐 보이는 구조)입니다. 목차만 상시로 걸어두고, 본문은 그 순간에만 펼친다는 뜻입니다.

작동 방식은 이렇습니다. 스킬마다 한두 줄짜리 설명이 있고, 이 짧은 설명만 매 세션 상시로 떠 있습니다. 실제 본문은 그 스킬이 호출되는 순간에만 로드됩니다. 그러니까:

스킬 = [ 한두 줄 설명 ]  ← 매 세션 상주 (싸다)
        └ [ 본문 매뉴얼 ]  ← 실제 필요할 때만 로드 (여기가 비싸다)

가진 비용은 설명 한두 줄, 쓰는 비용은 본문. 그래서 스킬을 백 개 쌓아둬도 평소엔 가볍고, 딱 그 순간 필요한 하나만 무겁게 펼쳐집니다. 회사에 매뉴얼 캐비닛이 있어도 평소엔 목차만 훑고, 실제 작업할 때만 해당 매뉴얼을 꺼내 펼치는 것과 같습니다.

여기서 핵심은 트리거 방식입니다. 어떤 스킬을 언제 펼칠지는 단순 키워드 규칙 매칭이 아니라 모델의 의미적 판단으로 결정됩니다. "지금 하는 작업"과 "이 스킬의 설명"이 의미상 들어맞으면 펼칩니다. 그래서 설명 한두 줄을 잘 쓰는 게 스킬 전체의 명운을 가릅니다. 설명이 흐릿하면 좋은 본문을 써놓고도 영영 안 불려 나옵니다.

무엇을 어디에 둘 것인가 — 4계층

스킬을 하나둘 만들다 보면 다음 질문이 옵니다. "이건 항상 떠 있어야 하나, 필요할 때만 불러야 하나, 아니면 아예 강제로 실행돼야 하나?" 저는 이걸 네 층으로 나눠 판단합니다.

계층	무엇을 두나	로딩 방식
T0 항상	전역 규칙·보안 불변식(볼트 규칙 등)	매 세션 전량 상주 — 그래서 짧게 유지
T1 자동표면	안정 + 고빈도 + 여러 프로젝트 공통 절차만	하네스가 판단해 자동 호출
T2 볼트/수동	특정 프로젝트 지식·저빈도·드물게 쓰는 것	읽을 때만 비용 발생(평소 0)
T3 훅	반드시 지켜져야 하는 결정적 가드레일	발화 시점에 강제 주입

핵심은 승격 경로입니다. 모든 절차는 일단 볼트 노트(개인 지식 볼트에 적어두는 문서 조각)로 시작합니다(T2). 그게 안정적이고, 자주 쓰이고, 여러 프로젝트에 공통이라면 자동표면으로 얇게 브리지해 하네스가 알아서 부르게 합니다(T1). 그리고 그중 틀리면 안 되는, 반드시 강제해야 하는 것만 훅으로 내립니다(T3).

이 마지막 계단이 이 글에서 제일 하고 싶은 말입니다.

가드레일은 훅에 — 지시는 요청이고, 훅은 보장이다.

프롬프트에 적은 지시는 "지켜주길 바라는 것"입니다. 대개는 지켜지지만, "대개"라는 말 안에 사고가 숨습니다. 훅(특정 시점에 시스템이 강제로 실행하는 자동 개입)은 "반드시 실행되는 것"입니다. 이 차이가 실전에서 얼마나 큰지, 두 장면으로 말씀드리겠습니다.

하나는 발행처럼 실패하면 안 되는 결정적 작업입니다. 저는 에이전트가 브라우저를 자율로 클릭·입력하며 발행하게 뒀다가 몇 번을 데었습니다. 자율 조작은 대부분 실패합니다 — 버튼 하나가 밀리고, 팝업 하나에 막힙니다. 결론은 결정적인 작업은 에이전트에게 맡기지 말고 고정된 스크립트로 분리하라였습니다. 이게 정확히 "지시가 아니라 보장"의 철학입니다.

다른 하나는 백그라운드 워커의 완료를 어떻게 아느냐입니다. 저는 초기에 "다 됐어?"를 대화로 물었습니다. 이건 지시고, 흔들립니다. 지금은 비대화형으로 한 번 실행 → 종료 코드로 성공/실패 판정 → 끝나면 빈 파일 하나를 남기는 완료 마커로 봅니다. 마커 파일이 있으면 끝난 것, 없으면 안 끝난 것. 해석의 여지가 없습니다. 보장은 이렇게 생겼습니다.

반드시 챙길 함정 — 조용히 삼켜지는 스킬

여기까지가 이론이라면, 이제 제가 진짜로 시간을 헌납한 이야기입니다.

제가 처음 만든 스킬 세 개가 한동안 전혀 작동하지 않았습니다. 에러도 없었습니다. 경고 한 줄 없었습니다. 그냥 다음 세션에서 안 잡혔습니다. 저는 스킬이 안 좋아서 안 불리는 줄 알고 설명 문구만 애꿎게 계속 고쳤습니다.

원인은 어이없을 만큼 사소했습니다. 스킬 파일 맨 위에는 제목·설명을 적는 머리말 블록이 있는데, 이 블록은 구조화된 텍스트 형식(YAML — 설정을 사람이 읽기 좋게 적는 문법)을 따릅니다. 그 설명에 콜론 다음 공백(예: 키워드: 배포)이나 백슬래시가 들어가면, 그 한 줄은 문법상 깨진 문장이 됩니다. 그러면 로더가 그 스킬을 통째로 스킵합니다 — 그것도 에러 메시지 하나 없이 조용히. 파일은 멀쩡히 거기 있는데, 시스템은 그 스킬이 존재하지 않는 것처럼 굽니다.

이건 재귀 검색 명령어 하나로 서버 전체가 멈췄던 사고와 결이 같습니다. 겉으론 아무 문제 없어 보이는 한 글자가, 조용히 전체를 무너뜨립니다. 가장 위험한 실패는 요란하게 터지는 실패가 아니라, 아무 소리 없이 스킵되는 실패입니다.

처방은 두 줄로 끝납니다.

설명은 작은따옴표로 감싼다. '키워드: 배포'처럼. 그러면 콜론도 백슬래시도 문자로 취급됩니다.
작성한 직후에 파서로 검증한다. "다음 세션에 잘 되겠지"를 믿지 말고, 그 자리에서 문법 검사가 통과하는지 확인하세요.

여기서 얻은 습관 하나로 이 절을 닫겠습니다. 조용한 실패를 잡는 유일한 방법은 조용해지기 전에 검증하는 것입니다. 스킬 하나를 새로 만들 때마다, 저는 이제 문법 검사를 한 번 통과시키기 전에는 완성했다고 하지 않습니다.

정리

두 번 한 일은 스킬로. 반복 설명은 매번 미묘하게 달라지고, 그 미묘함 속에 사고가 숨습니다. 한 번만 겪어도 뼈아팠던 함정은 즉시 박제하세요.
스킬은 네 칸이다 — 언제·절차·함정·검증. 검증 질문은 하나: "다음 세션에 읽혀 답이 개선되는가."
가진 값은 두 줄, 쓰는 값은 본문. 점진적 공개 덕분에 많이 쌓아도 가볍고, 트리거는 규칙이 아니라 의미적 판단이라 설명 문구가 전부입니다.
4계층으로 배치하라 — 항상 뜨는 규칙(T0), 자동표면(T1), 볼트/수동(T2), 강제 훅(T3). 안정·고빈도·공통은 위로, 결정적인 것은 훅으로 내립니다.
가드레일은 훅에. 지시는 요청이고, 훅은 보장입니다. 결정적인 것은 스크립트로 분리하고, 완료는 대화가 아니라 종료 코드와 마커로 판정하세요.
조용한 실패를 조심하라. 머리말의 콜론·백슬래시가 스킬을 소리 없이 삼킵니다. 작은따옴표로 감싸고, 그 자리에서 문법 검사를 돌리세요.

이 네 계층에서 마지막 조각 — 여러 스킬과 여러 에이전트를 실제로 한 팀처럼 굴리는 이야기는 다음 편, 1인 에이전트 함대에서 이어가겠습니다. 매뉴얼을 쥐여준 다음은, 그 매뉴얼로 움직이는 손이 여러 개가 되는 순간이니까요.

결국 스킬을 만드는 일은 저를 위한 게 아니었습니다. 저를 대신할 다음 세션의 저, 그리고 저 대신 일할 에이전트가 같은 함정에서 두 번 넘어지지 않도록 미리 못 하나를 박아두는 일이었습니다.