팀에서 AI를 잘 쓰는 사람의 화면을 어깨너머로 보면 대개 긴 지시문이 먼저 눈에 들어옵니다. 어떤 형식으로 쓰고, 무엇은 빼고, 어떤 말투를 피하라는 문장이 열 줄쯤 이어집니다. 그 지시문은 그 사람의 메모장에 있고, 다른 사람에게는 없습니다. 같은 일을 다른 팀원이 시키면 결과가 달라지는 이유가 여기에 있습니다. 모델이 달라서가 아니라 일을 설명한 문서가 달라서입니다.
이 글은 특정 고객사의 구축 결과를 보고하는 글이 아닙니다. DMS.Labs가 다루는 AI 스킬 구축과 업무 자동화 설계 가운데, 일의 설명서를 어떻게 쓰고 어떻게 시험하면 좋은지를 공개 문서를 근거로 정리한 실무 가이드입니다. 한 가지만 먼저 말씀드립니다. 여기서 말하는 설명서는 프롬프트를 길게 쓰는 요령이 아닙니다. 사람 신입에게 건넬 인수인계 문서를 AI에게도 건네는 일에 가깝습니다.
에이전트 스킬이라는 형식이 알려 주는 것
Anthropic은 엔지니어링 블로그에서 에이전트 스킬(Agent Skills)을 소개했습니다. 설명에 따르면 스킬은 에이전트가 찾아서 불러 쓸 수 있도록 지침, 스크립트, 자료를 묶어 둔 폴더입니다. 가장 단순한 형태는 SKILL.md라는 파일 하나가 들어 있는 폴더이고, 이 파일은 name과 description이라는 두 항목으로 시작합니다. 글쓴이들은 스킬을 만드는 일을 새로 온 직원에게 줄 온보딩 가이드를 만드는 일에 비유합니다.
여기서 눈여겨볼 부분은 정보를 세 겹으로 나눠 불러온다는 설계입니다. 에이전트가 시작할 때는 설치된 모든 스킬의 이름과 설명만 읽습니다. 그 스킬이 지금 일에 필요하다고 판단하면 본문 전체를 읽습니다. 본문에서 가리키는 별도 파일은 정말 필요할 때만 열어 봅니다. Anthropic은 이 구조를 점진적 공개(progressive disclosure)라고 부르고, 목차에서 시작해 각 장을 거쳐 부록으로 가는 잘 짜인 매뉴얼에 견줍니다.
이 구조는 AI 도구에 한정된 이야기가 아닙니다. 업무 설명서를 쓰는 사람에게 세 가지를 알려 줍니다. 첫 줄 설명이 그 문서가 불려 나올지를 결정합니다. 본문에는 꼭 필요한 것만 둡니다. 드물게 필요한 예외 처리는 따로 뺍니다. 아래에서 이 세 가지를 설명서 한 장의 항목으로 풀어 보겠습니다.
나무 책상 위의 인쇄된 점검표 한 장과 연필을 쥔 손, 옆에 놓인 노트와 커피잔.원본 전체 보기
설명서 한 장에 들어가는 여섯 칸
설명서는 한 장이면 충분합니다. 한 장을 넘기면 대개 쓰는 사람도 처음 쓴 내용을 잊습니다. 아래 여섯 칸은 DMS.Labs가 정리한 구성이고, 공개 문서의 권고를 업무 문서에 맞게 옮긴 것입니다. 정답이 정해진 양식은 아닙니다.
1. 이름과 한 줄 설명. 무슨 일인지와 언제 쓰는지를 함께 적습니다. Anthropic의 모범 사례 문서는 설명(description)에 스킬이 하는 일과 언제 써야 하는지를 모두 넣으라고 하고, 도움을 줍니다나 데이터를 처리합니다 같은 막연한 설명은 피하라고 합니다. 설명이 에이전트가 수많은 스킬 가운데 하나를 고르는 근거가 되기 때문입니다. 사람이 쓰는 설명서도 같습니다. 월간 보고서 초안 작성이라고만 쓰기보다 매월 첫 영업일에 팀별 지표 파일을 받아 보고서 초안을 만들 때 사용이라고 쓰면, 이 문서를 펼칠 때를 헷갈리지 않습니다.
2. 받는 것. 어떤 파일이나 정보를 받는지, 빠지면 어떻게 하는지를 적습니다. 날짜 형식, 파일 이름 규칙, 반드시 있어야 하는 열이 여기에 들어갑니다. 필수 항목이 비었을 때 추측해서 채우게 둘지, 멈추고 물어보게 할지를 이 칸에서 정합니다.
3. 하는 순서. 일을 단계로 적습니다. 다만 모든 단계를 같은 강도로 적지 않습니다. 이 부분은 뒤에서 따로 다룹니다.
4. 좋은 결과의 모습. 설명보다 예시가 빠릅니다. 실제로 쓸 만했던 결과물 하나와 쓸 수 없었던 결과물 하나를 나란히 둡니다. 쓸 수 없었던 쪽에는 왜 안 되는지를 한 줄 붙입니다. 이 한 쌍이 형식에 대한 문장 열 줄보다 명확한 경우가 많습니다.
5. 멈추는 조건. 어떤 때 AI가 일을 멈추고 사람에게 넘기는지를 적습니다. 금액이 일정 기준을 넘을 때, 고객 이름이 포함될 때, 원본 자료끼리 수치가 맞지 않을 때처럼 구체적으로 적습니다. 이 칸은 AI 자동화, 권한을 세 단계로 나눠 주기에서 다룬 권한의 사다리와 직접 이어집니다. 어디까지 맡길지는 그 글에서, 맡긴 일이 선을 넘으려 할 때 어떻게 멈추는지는 이 칸에서 정합니다.
6. 확인하는 방법. 결과를 받은 사람이 무엇을 대조하는지 적습니다. 합계는 원본과 맞는지, 인용은 출처에 있는지, 빠진 항목은 없는지처럼 몇 가지만 둡니다. 검수 시간이 길어지면 자동화의 이득이 사라지므로, 확인 항목은 짧을수록 좋습니다.
시작은 문서가 아니라 실패 목록입니다
설명서를 처음부터 쓰려고 하면 막연한 문장만 늘어납니다. Anthropic의 글은 순서를 거꾸로 제안합니다. 먼저 대표적인 일을 에이전트에게 시켜 보고, 어디서 막히거나 추가 정보가 필요했는지 관찰한 뒤, 그 부족한 부분을 메우는 스킬을 조금씩 만들라고 합니다. 평가부터 시작하라는 뜻입니다.
이 순서를 업무에 옮기면 다음과 같습니다.
먼저 실제 일 다섯 건쯤을 모읍니다. 쉬운 것만 고르지 않고, 지난달에 사람이 고생했던 건을 한두 개 섞습니다. 고객 정보 같은 민감한 자료는 비식별 처리하거나 샘플로 바꿉니다.
설명서 없이 같은 지시문으로 다섯 건을 시킵니다. 결과를 사람이 평소 기준으로 읽고, 틀린 곳과 아쉬운 곳을 한 줄씩 적습니다. 이 목록이 설명서의 뼈대입니다. 서식을 자꾸 어긴다면 4번 칸의 예시가 필요하고, 근거 없는 수치를 만들어 낸다면 5번 칸의 멈추는 조건이 필요하다는 식으로 실패가 칸에 대응됩니다.
그다음 설명서를 쓰고 같은 다섯 건을 다시 시킵니다. 실패 목록이 줄었는지만 봅니다. 줄지 않은 항목은 설명서에 쓴 문장이 그 실패와 상관없었다는 뜻이니, 그 문장을 지웁니다.
이 방식은 문서를 짧게 유지하는 데도 도움이 됩니다. 일어나지 않을 실패를 대비한 문장은 처음부터 쓸 이유가 없기 때문입니다. Anthropic 모범 사례 문서도 에이전트가 이미 아는 내용은 설명하지 말고, 문서의 모든 단락이 그것을 읽히는 비용만큼 값을 하는지 따져 보라고 권합니다. 같은 문서는 SKILL.md 본문을 500줄 아래로 두고, 그에 가까워지면 별도 파일로 나누라고도 권합니다. 한 장이라는 제약은 이 권고의 업무 문서 버전입니다.
모든 단계를 똑같이 엄격하게 쓰지 않습니다
3번 칸에서 흔히 하는 실수는 모든 단계를 같은 강도로 적는 것입니다. Anthropic은 작업의 취약성에 따라 자유도를 다르게 두라고 합니다. 길이 하나뿐인 좁은 다리 위에서는 정확한 지시를, 사방이 열린 들판에서는 대략의 방향을 주라는 비유를 씁니다.
업무로 옮겨 보면 이렇게 나눌 수 있습니다.
- 자유도가 높은 단계: 보고서의 요점을 어떻게 풀어 쓸지, 어떤 순서로 설명할지. 여러 방법이 모두 맞을 수 있으니 방향과 기준만 줍니다.
- 중간 단계: 표의 열 구성처럼 선호하는 틀이 있지만 약간의 변형은 괜찮은 일. 템플릿을 주고 필요하면 조정하게 합니다.
- 자유도가 낮은 단계: 금액 계산, 승인 번호 입력, 파일 이름 규칙처럼 틀리면 곤란한 일. 정확한 절차를 적고, 가능하면 사람이 만든 계산 도구나 스크립트를 실행하게 합니다.
마지막 항목은 중요합니다. Anthropic 글은 목록 정렬 같은 일을 토큰을 생성해서 처리하면 일반 알고리즘을 실행하는 것보다 훨씬 비싸고, 결과의 일관성이 필요한 일에는 코드가 필요하다고 설명합니다. 합계와 날짜 계산을 문장으로 설명하며 AI에게 맡기기보다, 계산은 정해진 도구에 맡기고 AI는 그 결과를 읽어 문장으로 정리하게 하는 쪽이 안전합니다.
서로 두께가 다른 세 개의 종이 폴더와 색인 카드 더미, 연필이 연한 오크 탁자 위에 놓여 있다.원본 전체 보기
길어지면 나누고, 한 단계만 내려갑니다
일이 복잡해지면 한 장에 모든 것을 담을 수 없습니다. 이때는 본문을 개요로 두고, 드물게 필요한 내용을 별도 문서로 뺍니다. 예를 들어 월간 보고서 설명서에 환불 건 처리와 해외 지사 예외가 들어 있다면, 본문에는 환불 건은 환불 처리 문서를 보라는 한 줄만 두고 상세는 다른 문서에 적습니다. 그러면 환불이 없는 달에는 그 문서를 읽을 필요가 없습니다.
모범 사례 문서가 덧붙이는 주의가 하나 있습니다. 참조는 한 단계 깊이까지만 두라는 것입니다. 문서가 다른 문서를 가리키고 그 문서가 또 다른 문서를 가리키면, 에이전트가 파일 일부만 훑어보고 지나쳐 정보가 빠질 수 있다고 합니다. 100줄이 넘는 참조 문서에는 맨 위에 목차를 넣으라는 권고도 같은 이유입니다. 사람에게도 마찬가지입니다. 인수인계 문서를 펼쳤는데 링크를 세 번 타고 들어가야 답이 나온다면, 새로 온 사람은 두 번째에서 멈춥니다.
모델이 바뀌면 다시 시험합니다
같은 모범 사례 문서는 스킬이 모델에 더해지는 것이므로 효과가 바탕 모델에 달려 있다고 설명하고, 사용할 모든 모델로 시험하라고 합니다. 빠르고 가벼운 모델에는 충분한 안내가 들어 있는지, 가장 강력한 모델에는 지나치게 설명하지 않았는지를 확인하는 식입니다.
업무 현장에서 이 말은 간단한 규칙이 됩니다. 도구나 모델 버전이 바뀌면 설명서를 고치지 말고 먼저 같은 다섯 건을 다시 돌립니다. 결과가 그대로면 건드리지 않습니다. 달라진 곳이 있으면 그곳에 해당하는 칸만 고칩니다. 설명서는 한 번 쓰고 끝나는 문서가 아니라, 시험 결과와 함께 늘 한 세트로 보관하는 문서입니다. 이 시험 자료를 어떻게 성과 지표와 연결할지는 AI 도입 성과 측정에서 다뤘습니다.
남이 만든 설명서를 가져다 쓸 때
스킬이 공유되기 시작하면 외부에서 만든 것을 가져다 쓰고 싶어집니다. Anthropic은 같은 글에서 분명히 경고합니다. 스킬은 지침과 코드를 통해 에이전트에게 새 능력을 주므로, 악의적인 스킬이 환경에 취약점을 만들거나 데이터를 빼돌리게 할 수 있습니다. 신뢰할 수 있는 출처에서만 설치하고, 덜 믿을 만한 출처라면 먼저 포함된 파일을 직접 읽어 보라고 권합니다. 코드 의존성, 이미지나 스크립트 같은 번들 자원, 신뢰할 수 없는 외부 네트워크에 접속하라는 지시가 있는지를 특히 살펴보라고 합니다.
이는 사내 문서에도 그대로 적용됩니다. 누군가 공유한 설명서에 외부 주소로 파일을 보내라는 문장이 숨어 있지 않은지, 권한을 넓히라는 지시가 없는지 훑어보는 일은 설치 전에 한 번만 하면 됩니다. 이 과정을 거치지 않은 문서는 시험 대상에도 올리지 않습니다.
팀에 처음 적용해 보는 순서
한 번에 모든 일을 문서로 만들 필요는 없습니다. 아래 순서를 제안합니다. 모두 DMS.Labs의 제안이며, 연구나 공식 문서가 이 일정이나 횟수를 권한 것은 아닙니다.
첫째, 한 달에 한 번 이상 반복되고 결과를 사람이 바로 알아볼 수 있는 일 하나를 고릅니다. 일을 고르는 기준은 AI 교육은 도구 설명보다 이 일을 맡겨도 되나에서 시작합니다의 업무 경계표를 그대로 쓸 수 있습니다. 맡겨 볼 일 칸에 들어간 일이 첫 후보입니다.
둘째, 실제 사례 다섯 건으로 설명서 없이 먼저 시험합니다. 실패 목록을 만듭니다.
셋째, 여섯 칸을 채워 한 장으로 씁니다. 쓰는 사람은 일을 가장 자주 하는 사람이고, 읽는 사람은 그 일을 처음 맡는 사람입니다. 처음 맡는 사람이 이 문서만 보고 일을 시작할 수 있는지를 한 번 물어봅니다. 이 질문은 AI에게도 사람에게도 같은 시험이 됩니다.
넷째, 같은 다섯 건을 다시 돌려 실패 목록이 줄었는지 확인하고, 달라지지 않은 문장은 지웁니다.
다섯째, 몇 주 뒤 실제 업무에서 설명서가 어떻게 쓰이는지 봅니다. 읽는 사람이 건너뛰는 칸이 있다면 칸의 위치나 문장이 문제일 수 있습니다.
마치며
AI 활용이 개인의 요령에 머무는 팀과 팀의 자산이 되는 팀의 차이는 대개 지시문이 어디에 있느냐로 갈립니다. 한 사람의 메모장에 있으면 개인의 요령이고, 이름과 설명이 붙은 한 장짜리 문서로 팀이 같이 읽고 고치면 팀의 자산이 됩니다. 필요한 것은 거창한 플랫폼이 아니라 이름이 붙은 문서와, 그 문서를 시험하는 다섯 건의 사례입니다.
이 글의 내용은 공개된 문서를 바탕으로 정리한 일반 가이드이며, 특정 조직에서 얻은 결과가 아닙니다. 위 설명서 구성과 시험 순서는 DMS.Labs의 제안이고, 모든 업무에 맞는다고 보장하지 않습니다. 문서에 기록된 기능과 권고는 시간이 지나면 바뀔 수 있으므로, 적용 전에 최신 문서를 확인하시기 바랍니다.
참고 자료
- Zhang, B., Lazuka, K., & Murag, M. Equipping agents for the real world with Agent Skills. Anthropic Engineering.
- Anthropic. Skill authoring best practices. Claude Docs.
