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

어떤 절차를 세 번째로 설명하고 있는 저를 발견한 날이 있었습니다.

홈서버에 새 서비스를 배포할 때의 순서, 조심할 점, 항상 걸리는 그 한 가지 함정이었습니다. 저는 그걸 첫 세션에도, 다음 세션에도, 그다음 세션에도 똑같이 타이핑하고 있었습니다.

그때 든 생각은 단순했습니다. 두 번 넘게 설명한 절차는 밖에 적어 둬야 했습니다.

이전 편에서 저는 AI의 기억을 마크다운 파일에 두는 이야기를 했습니다. 이번 편은 그 확장입니다.

기억이 "무엇을 아는가"라면, 스킬은 "어떻게 하는가"입니다. 이 "어떻게"는 매 세션 다시 가르치는 순간 제 시간을 갉아먹는 부채가 됩니다.

스킬은 외부화된 재사용 절차입니다. AI가 작업하다가 필요하면 스스로 읽어 재로딩하는 매뉴얼입니다.

이번 글에서는 언제 절차를 스킬로 승격하는지, 스킬이 어떻게 "가진 값은 싸고 쓸 때만 비싼" 구조로 작동하는지를 다룹니다. 무엇을 스킬에 두고 무엇을 절대 스킬에 두면 안 되는지도 함께 적었습니다.

절차를 밖으로 꺼내는 이유

AI에게 매번 절차를 설명하는 건, 신입에게 매일 아침 같은 업무 매뉴얼을 구두로 읊어 주는 것과 같습니다.

원인은 어제의 대화가 오늘로 이어지지 않는 데 있습니다. 세션이 끝나면 맥락은 증발합니다.

비효율로 끝나지도 않습니다. 반복 설명은 매번 미묘하게 달라지고, 거기에 진짜 위험이 있습니다.

오늘은 함정 하나를 빠뜨리고, 내일은 순서를 살짝 바꿉니다. 그렇게 같은 작업이 세션마다 다르게 실행되고 결과가 흔들립니다.

제가 겪은 사례가 하나 있습니다. 병렬로 여러 에이전트를 돌리다가, 한 워커(작업을 나눠 맡는 하위 실행 단위)가 라이브 코드 트리에서 추적되지 않던 파일 수십 개를 지워 버렸습니다.

커밋되지 않은 상태였다는 걸 그 워커는 몰랐습니다. 저는 그 절차에 "먼저 커밋해 상태를 고정하라"는 한 줄을 매번 넣어 주지 않았습니다.

복구는 됐지만 남은 건 분명했습니다. 사람의 기억에 의존하는 절차는 사람이 한 번 깜빡하는 순간 사고가 됩니다.

절차는 외부에 못 박아 두어야 매번 같은 방식으로 실행됩니다.

두 번 이상 반복됐거나, 단 한 번이라도 비자명한 함정을 품은 절차라면 승격 후보입니다. 두 번이라는 숫자가 절대 기준은 아닙니다.

한 번만 겪어도 뼈아팠던 함정은 그 자리에서 스킬로 박제하는 게 맞습니다.

네 칸짜리 매뉴얼

제가 스킬을 쓸 때 지키는 형식은 고정된 네 섹션입니다. 화려할 필요는 없습니다.

오히려 칸이 정해져 있어야 빈틈이 드러납니다.

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

검증 칸을 채울 때 저는 스스로 하나만 묻습니다. "다음 세션에서 이 노트가 읽혀 실제로 답이 개선되는가? 같은 실수를 다시 안 하게 되는가?"

이 질문에 그렇다고 답할 수 없으면 그건 그냥 메모로 남깁니다.

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

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

작동 방식은 이렇습니다. 스킬마다 한두 줄짜리 설명이 있고, 이 짧은 설명만 매 세션 상시로 떠 있습니다.

실제 본문은 그 스킬이 호출되는 순간에만 로드됩니다. 그러니까:

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

가진 비용은 설명 한두 줄, 쓰는 비용은 본문입니다. 그래서 스킬을 백 개 쌓아 둬도 평소엔 가볍고, 딱 그 순간 필요한 하나만 무겁게 펼쳐집니다.

회사에 매뉴얼 캐비닛이 있어도 평소엔 목차만 훑고, 실제 작업할 때만 해당 매뉴얼을 꺼내 펼치는 것과 같습니다.

여기서 중요한 건 트리거 방식입니다. 어떤 스킬을 언제 펼칠지는 모델이 의미로 판단합니다.

"지금 하는 작업"과 "이 스킬의 설명"이 의미상 들어맞으면 펼칩니다. 그래서 설명 한두 줄을 잘 쓰는 게 스킬 전체의 명운을 가릅니다.

설명이 흐릿하면 좋은 본문을 써 놓고도 영영 안 불려 나옵니다.

무엇을 어디에 둘까

스킬을 하나둘 만들다 보면 다음 질문이 옵니다. 이건 항상 떠 있어야 하나, 필요할 때만 불러야 하나, 아니면 아예 강제로 실행돼야 하나.

저는 아래 표처럼 층을 나눠 판단합니다.

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

눈여겨볼 곳은 승격 경로입니다. 모든 절차는 일단 볼트 노트(개인 지식 볼트에 적어 두는 문서 조각)로 시작합니다(T2).

그게 안정적이고, 자주 쓰이고, 여러 프로젝트에 공통이라면 자동표면으로 얇게 브리지해 하네스가 알아서 부르게 합니다(T1).

그리고 그중 틀리면 안 되는 것, 반드시 강제해야 하는 것만 훅으로 내립니다(T3).

이 마지막 계단이 이 글에서 제일 하고 싶은 말입니다. 가드레일은 훅에 둡니다. 지시는 요청이고, 훅은 보장입니다.

프롬프트에 적은 지시는 지켜 주길 바라는 것입니다. 대개는 지켜지지만, "대개"라는 말 안에 사고가 숨습니다.

훅(특정 시점에 시스템이 강제로 실행하는 자동 개입)은 반드시 실행되는 것입니다. 이 차이가 실전에서 얼마나 큰지 두 장면으로 말씀드리겠습니다.

하나는 발행처럼 실패하면 안 되는 결정적 작업입니다. 저는 에이전트가 브라우저를 자율로 클릭·입력하며 발행하게 뒀다가 몇 번을 데었습니다.

자율 조작은 대부분 실패합니다. 버튼 하나가 밀리고, 팝업 하나에 막힙니다.

그래서 결정적인 작업은 고정된 스크립트로 분리했습니다. 보장으로 바꾼다는 게 바로 이런 일입니다.

다른 하나는 백그라운드 워커의 완료를 어떻게 아느냐입니다. 저는 초기에 "다 됐어?"를 대화로 물었습니다. 이건 지시고, 흔들립니다.

지금은 비대화형으로 한 번 실행하고, 종료 코드로 성공과 실패를 판정합니다. 끝나면 빈 파일 하나를 완료 마커로 남깁니다.

마커 파일이 있으면 끝난 것, 없으면 안 끝난 것입니다. 해석의 여지가 없습니다. 보장은 이렇게 생겼습니다.

첫 스킬 세 개가 조용히 사라진 일

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

제가 처음 만든 스킬 세 개가 한동안 전혀 작동하지 않았습니다. 에러도 없었고 경고 한 줄 없었습니다. 그냥 다음 세션에서 안 잡혔습니다.

저는 스킬이 안 좋아서 안 불리는 줄 알고 설명 문구만 애꿎게 계속 고쳤습니다.

원인은 어이없을 만큼 사소했습니다. 스킬 파일 맨 위에는 제목과 설명을 적는 머리말 블록이 있습니다.

이 블록은 구조화된 텍스트 형식(YAML, 설정을 사람이 읽기 좋게 적는 문법)을 따릅니다. 그 설명에 콜론 다음 공백(예: 키워드: 배포)이나 백슬래시가 들어가면, 그 한 줄은 문법상 깨진 문장이 됩니다.

그러면 로더가 그 스킬을 통째로 스킵합니다. 그것도 에러 메시지 하나 없이 조용히 넘어갑니다.

파일은 멀쩡히 거기 있는데, 시스템은 그 스킬이 존재하지 않는 것처럼 굽니다.

재귀 검색 명령어 하나로 서버 전체가 멈췄던 사고와 결이 같습니다. 겉으론 아무 문제 없어 보이는 한 글자가 조용히 전체를 무너뜨립니다.

요란하게 터지는 실패는 차라리 낫습니다. 아무 소리 없이 스킵되는 실패가 가장 위험합니다.

처방은 두 줄로 끝납니다.

• 설명은 작은따옴표로 감쌉니다. '키워드: 배포'처럼 감싸면 콜론도 백슬래시도 문자로 취급됩니다.
• 작성한 직후에 파서로 검증합니다. 그 자리에서 문법 검사가 통과하는지 확인하세요.

이 일로 습관 하나가 생겼습니다. 조용한 실패를 잡으려면 조용해지기 전에 검증해야 합니다.

스킬 하나를 새로 만들 때마다, 저는 이제 문법 검사를 한 번 통과시키기 전에는 완성했다고 하지 않습니다.

새 절차가 생기면 확인하는 것

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

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

돌아보면 스킬은 다음 세션의 저와 저 대신 일할 에이전트가 같은 함정에서 두 번 넘어지지 않게 박아 두는 못입니다.