Skill 디버깅

어떤 Skill은 처음 시연할 때는 꽤 멋집니다. 딱 한 번 돌려 보면 그럴듯한 결과가 나오고, 팀원들도 "이제 자동화되겠네"라고 기대합니다. 그런데 운영에 들어가면 전혀 다른 얼굴을 보여줍니다. 분명 필요한 순간인데 Skill이 조용히 지나가 버리고, 다른 날에는 엉뚱한 Skill이 끼어들며, 지침을 써 두었는데도 중요한 규칙을 슬쩍 무시합니다. 심지어 스크립트는 멀쩡히 돌아갔는데 출력 형식이 산산조각 나는 일도 생깁니다.

이때 많은 팀이 가장 먼저 하는 실수는 문제를 한 덩어리로 보는 것입니다. "모델이 불안정하다", "AI가 말을 안 듣는다", "Skill 품질이 낮다" 같은 말은 답답함은 표현하지만 원인을 설명하지는 못합니다. 디버깅은 감정의 언어를 원인의 언어로 바꾸는 일입니다. 그리고 그 출발점은 단순합니다. 무엇이 망가졌는지보다, 정확히 어디서부터 어긋났는지를 먼저 구분하는 것입니다.

이번 장에서는 Skill 운영에서 자주 만나는 고장을 다룹니다. Skill이 아예 활성화되지 않는 문제, 잘못된 Skill이 선택되는 문제, 지침을 읽고도 따르지 않는 문제, 스크립트 실행 오류와 출력 포맷 붕괴, 그리고 여러 Skill이 서로 충돌하는 상황까지 차례로 살펴보겠습니다. 핵심은 하나입니다. Skill은 한 번 만들어 배포하고 끝나는 문서가 아니라, 관찰하고 수정하고 다시 다듬는 운영 자산이라는 점입니다.

디버깅은 고장 수리가 아니라 원인 분해다

Skill 디버깅은 코드를 고치는 일과 닮았지만, 완전히 같지는 않습니다. 코드에서는 오류가 비교적 명확하게 드러납니다. 문법 에러가 나거나, 예외가 터지거나, 테스트가 실패합니다. 하지만 Skill은 자연어 지침, 설명문, 참고 자료, 도구 호출, 실행 환경, 입력 맥락이 한데 얽혀 움직입니다. 그래서 겉으로는 비슷해 보이는 문제도 실제 원인은 크게 다를 수 있습니다.

예를 들어 회의록 정리 Skill이 필요한데 활성화되지 않았다고 해봅시다. 정말 원인이 Skill 미선택일 수도 있지만, 사실은 사용자의 요청이 너무 넓어서 다른 요약 Skill이 먼저 선택된 것일 수도 있습니다. 혹은 Skill은 선택되었지만 description이 약해서 에이전트가 적용 확신을 가지지 못한 것일 수도 있습니다. 겉으로 보면 모두 "왜 이 Skill이 안 나왔지?"라는 같은 불만처럼 보입니다. 그러나 고치는 방법은 전부 다릅니다.

그래서 디버깅은 수정부터 시작하면 안 됩니다. 먼저 문제를 다음 층위 중 어디에 놓을지 정해야 합니다. 선택의 문제인지, 이해의 문제인지, 실행의 문제인지, 출력의 문제인지, 충돌의 문제인지 분리해야 합니다. 원인을 분해하지 않으면 수정도 운에 맡기게 됩니다.

먼저 증상을 다섯 갈래로 나누어라

운영 중 만나는 Skill 문제는 대체로 다섯 부류로 정리할 수 있습니다.

• 활성화 문제: 써야 할 상황인데 Skill이 불리지 않는다.

• 선택 문제: 다른 Skill이 대신 선택되어 엉뚱한 절차가 실행된다.

• 준수 문제: Skill을 읽은 것 같은데 핵심 지침을 따르지 않는다.

• 실행 문제: 스크립트, 파일, 도구 호출 과정에서 오류가 난다.

• 출력 문제: 내용은 어느 정도 맞아도 형식, 구조, 길이, 톤이 무너진다.

여기에 하나를 더 붙이면 충돌 문제입니다. 여러 Skill이 동시에 관련 있어 보일 때 누가 우선권을 가져야 하는지 모호한 상태입니다. 실제로는 이 충돌 문제가 앞의 다섯 문제를 연쇄적으로 만들어내는 경우가 많습니다.

좋은 디버깅은 "무엇이 잘못됐는가"를 한 줄로 요약하지 않습니다. 대신 "어느 층위에서 처음 어긋났는가"를 찾습니다. 그 순간부터 수정 범위가 줄어들고, 재현도 쉬워집니다.

Skill이 활성화되지 않을 때는 description부터 의심하라

많은 팀은 Skill이 활성화되지 않으면 곧바로 본문 지침을 더 길게 씁니다. 하지만 실제로 에이전트가 Skill을 고르는 첫 관문은 대개 본문보다 description, 이름, 범위 신호입니다. 다시 말해, 안 읽히는 Skill은 대개 내용이 부족해서가 아니라 들어갈 문이 약해서 생깁니다.

이 문제를 볼 때 가장 먼저 확인해야 할 것은 description이 실제 업무 상황을 얼마나 또렷하게 가리키는지입니다. "문서 작성을 도와주는 Skill" 같은 설명은 너무 넓습니다. 이런 문장은 거의 모든 문서 작업에 적용될 수 있어서, 오히려 아무 상황에서도 결정적으로 선택되지 못합니다. 반대로 "사내 주간 경영회의용 1페이지 요약 보고서를 작성하며, 리스크·결정사항·다음 액션을 분리해 정리한다"처럼 쓰면 에이전트가 적용 시점을 훨씬 쉽게 판단합니다.

활성화 실패는 보통 세 가지 원인에서 나옵니다.

첫째, 설명이 너무 추상적입니다. 무슨 일을 하는지보다 좋은 말만 적혀 있습니다. 둘째, 범위가 너무 넓거나 너무 좁습니다. 넓으면 다른 Skill과 경쟁하다 흐려지고, 좁으면 실제 요청과 딱 맞지 않아 지나쳐집니다. 셋째, 사용자의 실제 표현과 Skill의 설명 언어가 어긋납니다. 사용자는 "회의 요약"이라고 말하는데 Skill은 "의사결정 기록 정리" 같은 내부 용어만 쓰고 있으면 연결이 약해집니다.

이럴 때는 description을 문학적으로 다듬기보다, 호출 단서를 늘리는 방향으로 고쳐야 합니다. 사용자가 실제로 쓰는 표현, 업무 문맥, 출력물 이름, 포함해야 할 핵심 항목을 description에 녹여 넣는 편이 좋습니다. 쉽게 말해 "이 Skill이 언제 필요한가"를 사람이 아니라 에이전트 입장에서 다시 써야 합니다.

활성화 문제는 컨텍스트 부족으로도 생긴다

description이 괜찮은데도 Skill이 잘 안 불리는 경우가 있습니다. 이때는 Skill 자체보다 입력 컨텍스트가 문제일 수 있습니다. 사용자의 요청이 지나치게 짧거나, 작업 목표가 숨겨져 있거나, 필요한 파일이 첨부되지 않은 상태라면 에이전트는 확신을 가지기 어렵습니다.

예를 들어 사용자가 "이거 정리해줘"라고만 말하면, 회의록 Skill인지, 요약 Skill인지, 보고서 Skill인지 결정하기 어렵습니다. 인간 동료라면 눈치로 맞출 수도 있지만, 운영 가능한 Skill 체계는 눈치에 기대면 안 됩니다. 디버깅 관점에서 중요한 것은 "이 Skill이 안 불렸다"는 사실만 보지 않고, "불릴 만큼 충분한 맥락이 주어졌는가"를 함께 보는 것입니다.

그래서 실무에서는 활성화 실패를 고칠 때 Skill만 수정하지 말고, 입력 템플릿도 같이 손보는 편이 좋습니다. 사용자 요청 양식을 조금만 구조화해도 선택 정확도가 크게 올라갑니다. 작업 유형, 기대 출력, 제약 조건 같은 최소 맥락을 넣어 주면 에이전트는 훨씬 안정적으로 Skill을 고릅니다.

엉뚱한 Skill이 선택될 때는 겹치는 설명을 찢어야 한다

Skill이 활성화되지 않는 문제보다 더 골치 아픈 것은 잘못된 Skill이 너무 자신 있게 선택되는 경우입니다. 이 문제는 대개 Skill이 부족해서 생기지 않습니다. 오히려 비슷한 Skill이 늘어나면서 생깁니다. 팀이 성장하고 자동화 범위가 넓어질수록 같은 단어를 쓰는 Skill이 많아지기 때문입니다.

예를 들어 "요약"이라는 말이 들어간 Skill이 세 개 있다고 해봅시다. 회의 요약 Skill, 임원 보고 요약 Skill, 리서치 요약 Skill입니다. 이 셋이 모두 description에서 "핵심 내용을 요약한다"는 문장을 쓰고 있다면, 에이전트 입장에서는 차이가 흐립니다. 사람은 폴더명을 보고 이해하지만, 선택 시스템은 더 작은 단서로 판단합니다.

이럴 때 필요한 것은 설명문을 예쁘게 정리하는 일이 아니라 역할 경계를 강제로 분리하는 일입니다. 가장 쉬운 방법은 각 Skill이 담당하는 입력, 목적, 출력물을 다르게 명시하는 것입니다. 회의 요약 Skill은 회의록, 참석자, 결정사항 중심이어야 하고, 임원 보고 요약 Skill은 의사결정 포인트와 리스크 중심이어야 하며, 리서치 요약 Skill은 출처와 불확실성 표시 중심이어야 합니다. 모두 "요약"을 하지만, 무엇을 요약하고 어떤 형식으로 끝내는지가 달라야 합니다.

겹침을 줄이는 데는 부정적 경계도 중요합니다. 즉, 이 Skill이 하지 않는 일을 함께 적는 방식입니다. "긴 보고서를 1페이지 임원 보고 형식으로 압축하는 작업에만 사용한다. 일반 회의록 정리에는 사용하지 않는다" 같은 문장은 선택 오류를 줄이는 데 꽤 강력합니다. 범위를 넓게 설명하는 것보다, 어디까지가 자기 일이 아닌지 못 박아 두는 편이 충돌을 줄입니다.

잘못된 선택은 Skill 개수가 아니라 계층이 없어서 생긴다

Skill이 많아질수록 충돌은 자연스럽습니다. 문제는 개수가 아니라, 그 Skill들 사이에 계층과 관문이 없는 데 있습니다. 비슷한 일을 하는 Skill이 여러 개 있다면, 누가 먼저 검토되고 어떤 조건에서 다른 Skill로 넘겨야 하는지 구조가 있어야 합니다.

예를 들어 팀 공통 문체 Skill과 문서별 작성 Skill은 서로 경쟁하면 안 됩니다. 하나는 전역 규칙에 가깝고, 다른 하나는 작업별 절차에 가깝습니다. 그런데 둘 다 같은 수준에서 "문서를 작성한다"라고 주장하면 충돌이 생깁니다. 이런 경우에는 역할 층위를 나눠야 합니다. 공통 문체 Skill은 모든 문서에 적용되는 상위 규칙이고, 회의록 작성 Skill은 특정 입력을 특정 형식으로 정리하는 하위 절차여야 합니다.

디버깅의 핵심은 "왜 저 Skill이 선택됐지?"라고 묻는 데서 끝나지 않습니다. "애초에 서로 경쟁하게 설계한 것이 문제 아닌가?"까지 올라가야 합니다. Skill이 늘어날수록 개별 문장을 고치는 일보다 체계의 계층을 잡는 일이 더 중요해집니다.

지침을 읽고도 따르지 않을 때는 헌법형 규칙을 따로 세워라

운영 중 가장 허탈한 순간은 이것입니다. Skill은 분명 선택됐고, 관련 파일도 읽은 것 같은데, 정작 가장 중요한 규칙을 안 지킵니다. 예를 들어 항상 출처를 붙이라고 했는데 빠뜨리고, 승인 없이 위험 작업을 하지 말라고 했는데 진행해 버리며, 회사 톤을 따르라고 했는데 엉뚱하게 과장된 문체를 씁니다.

이 문제를 해결하려고 많은 사람이 지침을 더 많이 씁니다. 하지만 지침을 길게 늘어놓는다고 준수율이 반드시 오르지는 않습니다. 오히려 중요한 규칙이 다른 설명 속에 파묻혀 버릴 수 있습니다. 이럴 때 필요한 것이 헌법형 규칙입니다. 즉, 모든 세부 지침보다 위에 놓이는 비타협적 규칙을 따로 분리하는 방식입니다.

헌법형 규칙은 성격이 분명해야 합니다. "가능하면", "되도록", "권장한다" 같은 표현은 피하는 편이 좋습니다. 대신 "반드시", "없으면 질문한다", "승인 전에는 실행하지 않는다", "모르면 추정하지 않는다"처럼 행동 기준이 분명해야 합니다. 또한 본문 중간 어딘가에 숨어 있으면 안 됩니다. Skill의 앞부분이나 별도 섹션에서 우선순위가 높은 규칙으로 보여야 합니다.

지침 불이행 문제의 상당수는 모델이 악의적으로 무시해서가 아니라, 규칙의 우선순위가 흐리기 때문에 생깁니다. 형식을 지키라는 말, 자연스럽게 쓰라는 말, 빠르게 끝내라는 말, 친절하게 설명하라는 말이 함께 있으면 에이전트는 매번 임기응변으로 균형을 잡습니다. 그러면 조직 입장에서는 "안정적이지 않다"는 느낌을 받게 됩니다. 중요한 원칙일수록 타협 가능한 스타일 지침과 섞지 말고, 먼저 못 박아야 합니다.

지침 불이행은 종종 모순된 지침에서 시작된다

Skill을 오래 운영하다 보면 이런 일이 생깁니다. 누군가 출력이 너무 짧다고 해서 길이를 늘리는 문장을 추가하고, 또 다른 누군가 장황하다고 해서 간결성을 강조하는 문장을 넣습니다. 형식을 더 엄격히 하자는 수정과 자연스러운 문장을 쓰라는 수정이 계속 쌓입니다. 결국 SKILL.md는 팀의 타협 기록이 되고, 에이전트는 그 안에서 무엇을 우선해야 할지 혼란스러워합니다.

이때는 문장을 더 보태지 말고, 서로 충돌하는 규칙을 정리해야 합니다. 규칙에는 우선순위가 있어야 합니다. 예를 들어 안전과 승인, 필수 포맷, 필수 항목, 그다음에 문체와 길이 최적화가 오는 식입니다. 상위 규칙이 하위 규칙보다 항상 우선한다는 구조를 분명히 하면, 에이전트가 모호한 상황에서도 덜 흔들립니다.

쉽게 말해 좋은 Skill은 친절한 설명서이기 전에 질서 있는 헌법입니다. 모든 것을 설명하려고 하기보다, 무엇을 절대 어기면 안 되는지를 먼저 세워야 합니다.

스크립트 실행 오류와 출력 포맷 붕괴는 따로 진단해야 한다

실무에서 자주 보이는 실수 중 하나는 스크립트 문제와 출력 문제를 한 덩어리로 보는 것입니다. 예를 들어 분석 Skill이 이상한 표를 내놓았다고 해서 곧바로 "스크립트가 잘못됐다"고 결론 내리기 쉽습니다. 그러나 실제로는 계산은 정확했는데, 마지막 정리 단계에서 표 템플릿이 깨졌을 수도 있습니다. 반대로 출력은 그럴듯한데, 중간 계산이 잘못되어 내용이 틀릴 수도 있습니다.

그래서 디버깅에서는 두 문제를 분리해야 합니다. 스크립트 실행 오류는 입력, 실행, 반환값의 계약 문제에 가깝고, 출력 포맷 붕괴는 최종 조립 문제에 가깝습니다.

스크립트 실행 오류를 볼 때는 먼저 아주 기계적으로 확인해야 합니다.

• 입력 형식이 스크립트가 기대한 구조와 일치하는가

• 파일 경로, 인코딩, 권한, 의존성 문제가 없는가

• 반환값이 자연어 후처리 단계에서 읽기 쉬운 형태인가

• 실패했을 때 에이전트가 오류 메시지를 이해할 수 있는가

많은 경우 스크립트 자체보다 계약이 문제입니다. 예를 들어 스크립트는 JSON을 반환하는데 Skill 지침은 표를 바로 만들라고만 적혀 있으면, 에이전트는 중간 산출물을 잘못 해석할 수 있습니다. 그래서 스크립트는 "무엇을 넣으면 무엇이 나온다"가 분명해야 하고, Skill은 그 반환값을 어떻게 사용할지 명확히 설명해야 합니다.

반면 출력 포맷 붕괴는 다른 관점으로 봐야 합니다. 여기서는 계산의 정확성보다 최종 형식 고정력이 중요합니다. 섹션 순서, 필수 헤더, 표의 열 수, 코드블록 여부, 톤과 길이 제한 같은 요소가 약하면, 중간 내용이 아무리 좋아도 결과물은 흔들립니다. 이때는 스크립트를 고치는 것이 아니라 출력 템플릿과 마지막 자기검토 규칙을 강화해야 합니다.

출력 붕괴는 마지막 한 문단 때문에 생기기도 한다

형식이 자주 무너지는 Skill을 보면, 대개 앞부분 지침은 길고 정교한데 마지막 출력 규칙은 짧고 추상적입니다. "최종 결과를 보기 좋게 정리하라" 같은 문장은 사람에게는 상식처럼 들리지만, 운영 안정성에는 별 도움이 되지 않습니다.

출력 포맷이 중요한 Skill이라면 마지막 단계는 매우 구체적이어야 합니다. 어떤 H2가 반드시 있어야 하는지, 표를 쓰는지, 목록을 쓰는지, 금지된 표현은 무엇인지, 분량 한계는 어디까지인지 선명해야 합니다. 그리고 가능하면 생성 직후 스스로 확인할 체크리스트를 붙이는 편이 좋습니다. 예를 들어 "결정사항, 리스크, 다음 액션 세 섹션이 모두 있는지 확인한 뒤 제출한다" 같은 문장은 포맷 안정성을 높이는 데 효과적입니다.

핵심은 출력 품질을 내용 문제로만 보지 않는 것입니다. 좋은 Skill 운영자는 마지막 조립 단계가 독립된 실패 지점이라는 사실을 압니다.

여러 Skill이 충돌할 때는 우선순위보다 역할 경계를 먼저 정하라

Skill 충돌이 생기면 사람들은 보통 우선순위부터 정하려고 합니다. 물론 필요합니다. 하지만 우선순위는 마지막 수단에 가깝습니다. 진짜 중요한 것은 왜 이 Skill들이 서로 같은 일을 한다고 주장하게 되었는지 보는 일입니다.

예를 들어 하나는 "기술 블로그 작성 Skill"이고 다른 하나는 "회사 문체 적용 Skill"이라면, 둘은 원래 경쟁 대상이 아닙니다. 전자는 작업 절차를 담당하고, 후자는 스타일 제약을 담당합니다. 그런데 둘 다 본문에서 "블로그 글을 작성한다"라고 말하고 있으면 역할이 겹쳐 보입니다. 이 상태에서 우선순위만 정하면 당장은 조용해질 수 있지만, 나중에 또 다른 문서 Skill이 들어오면 같은 문제가 반복됩니다.

충돌을 해결하는 기준은 의외로 단순합니다. 각 Skill이 맡는 책임을 하나의 문장으로 줄여 보았을 때, 서로 다른 문장이 나와야 합니다. 한 Skill은 절차를 담당하고, 다른 Skill은 도메인 규칙을 담당하며, 또 다른 Skill은 전역 스타일을 담당하는 식으로 역할이 나뉘어야 합니다. 만약 두 Skill의 한 줄 설명이 거의 비슷하다면, 둘은 분리할 이유가 약하거나 경계 재설계가 필요합니다.

그다음에야 우선순위를 둡니다. 보통은 전역 안전 규칙, 조직 공통 규칙, 작업별 절차, 출력별 특수 규칙 순서가 자연스럽습니다. 하지만 중요한 것은 순서 자체보다, 그 순서가 팀 안에서 일관되게 적용되도록 문서화되어 있는가입니다. 우선순위가 머릿속에만 있으면 충돌은 다시 돌아옵니다.

디버깅은 큰 개편보다 작은 가설 검증이 낫다

Skill이 흔들릴 때 가장 위험한 반응은 전면 재작성입니다. 답답한 마음에 SKILL.md를 처음부터 다시 쓰고, 폴더 구조를 갈아엎고, 스크립트를 통째로 바꾸고 싶어집니다. 하지만 이렇게 하면 무엇 때문에 좋아졌는지, 무엇 때문에 더 나빠졌는지 알기 어려워집니다.

실무에서는 작은 가설로 나누어 고치는 편이 훨씬 낫습니다. 예를 들어 활성화 실패가 많다면 description만 먼저 바꿔 보고, 잘못된 선택이 많다면 겹치는 설명을 분리해 보고, 지침 불이행이 심하다면 헌법형 규칙만 앞쪽으로 끌어올려 봅니다. 형식 붕괴가 문제라면 스크립트는 건드리지 않고 출력 템플릿만 고쳐 봅니다. 이렇게 수정 범위를 줄여야 효과를 비교할 수 있습니다.

디버깅은 창의적인 문장력보다 실험 설계에 가깝습니다. 한 번에 하나씩 바꾸고, 어떤 증상이 줄었는지 보고, 다시 다음 원인을 좁혀 가야 합니다. 그래야 Skill이 감각의 산물이 아니라 관리 가능한 자산이 됩니다.

운영 가능한 팀은 디버깅 기록을 남긴다

같은 문제가 반복되는 팀을 보면, 늘 비슷한 대화를 합니다. "이 Skill 지난번에도 이상했지?" "아마 출력 규칙 문제였던 것 같은데?" "아니, 그때는 스크립트였나?" 이런 대화는 기억에 의존하기 때문에 금방 흐려집니다.

그래서 Skill 디버깅에는 짧은 기록이 꼭 필요합니다. 거창한 장애 보고서까지는 아니어도 괜찮습니다. 어떤 입력에서, 어떤 Skill 버전이, 어떤 증상을 보였고, 원인을 어떻게 추정했으며, 무엇을 수정했는지 남겨 두면 됩니다. 중요한 것은 완벽한 문장이 아니라, 다음 사람이 같은 함정에 다시 빠지지 않게 하는 것입니다.

특히 팀 운영에서는 "증상"과 "수정"을 분리해 적는 습관이 유용합니다. 출력이 망가졌다는 증상과, description을 수정했다는 조치는 다릅니다. 이 둘을 구분해 두어야 나중에 수정이 적절했는지 판단할 수 있습니다. 문제를 남기는 일은 귀찮지만, 남기지 않으면 디버깅은 늘 처음부터 다시 시작됩니다.

디버깅의 목표는 완벽한 Skill이 아니라 예측 가능한 Skill이다

현실적으로 모든 입력에서 완벽한 Skill은 어렵습니다. 새로운 요청 방식이 계속 들어오고, 도구 환경도 바뀌며, 조직 규칙도 변합니다. 중요한 것은 한 번도 실패하지 않는 Skill이 아니라, 실패했을 때 어디를 고쳐야 할지 예측 가능한 Skill입니다.

활성화 문제는 description과 컨텍스트를 본다, 선택 문제는 겹치는 범위와 역할 경계를 본다, 준수 문제는 헌법형 규칙과 우선순위를 본다, 실행 문제는 스크립트 계약을 본다, 출력 문제는 템플릿과 마지막 검토 단계를 본다. 이 정도의 디버깅 언어만 팀에 자리 잡아도 Skill 운영의 난이도는 크게 낮아집니다.

결국 Skill은 한 번 잘 써서 끝나는 문서가 아닙니다. 반복 업무를 대신 맡기는 순간부터, 그것은 운영되고 관찰되고 다듬어져야 하는 시스템이 됩니다. 문제를 두려워할 필요는 없습니다. 오히려 문제를 구체적으로 분해하고 수정할 수 있다면, 그 Skill은 이미 조직의 자산이 될 준비를 마친 것입니다.

다음 장에서는 이 운영 자산을 더 안전하게 다루기 위해 무엇을 지켜야 하는지 살펴보겠습니다. Skill은 능력을 늘려 주는 도구이지만, 동시에 조직의 신뢰 경계이기도 합니다. 잘 설계된 디버깅이 품질을 지킨다면, 잘 설계된 보안은 그 품질이 위험해지지 않도록 막아 줍니다.