긴 프롬프트가 정답은 아니다: AI 에이전트의 Agent Skills 설계와 함정

 

AI 에이전트가 같은 실수를 반복할 때 가장 쉬운 대응은 프롬프트에 주의사항을 더 붙이는 것이다. 보고서 형식을 틀리면 서식을 추가하고, 날짜를 잘못 읽으면 날짜 규칙을 추가하고, 계산을 틀리면 검산 지시를 추가한다. 그렇게 만든 긴 프롬프트는 처음에는 든든해 보인다. 그러나 업무가 늘수록 지금 필요한 지침을 찾기 어렵고, 서로 다른 상황의 규칙까지 한꺼번에 들어가기 시작한다.

 

Agent Skills는 이 문제를 다루는 방법 중 하나다. AI 에이전트가 사용할 절차, 참고 자료, 실행 코드와 서식을 하나의 패키지로 정리하고, 작업에 맞는 내용을 필요할 때 읽도록 한다. 핵심은 프롬프트를 무조건 짧게 만드는 데 있지 않다. 무엇을 항상 보여 주고 무엇을 나중에 읽게 할지, 어떤 판단은 모델에 맡기고 어떤 검증은 코드로 고정할지를 나누는 데 있다.

 

이 글은 Agent Skills와 SKILL.md의 작동 원리, 점진적 공개, MCP와 RAG의 관계, 실제 업무에 적용할 때의 평가 방법을 설명한다. Anthropic 엔지니어링 글과 Agent Skills 공식 사양 및 작성 가이드를 확인하고, 국내 기술 블로그의 설명 방식도 비교했다. 자료 확인 기준일은 2026년 10월 23일이다. 아래의 업무 구성과 수치는 설계 설명을 위한 가상 예시이며, 자체 성능 실험 결과가 아니다.

 

미리 결론을 말하면 스킬 파일을 만들었다고 에이전트가 전문가처럼 정확하게 일하는 것은 아니다. 스킬은 지식을 전달하고 재사용하기 좋은 구조를 제공한다. 실제 품질은 적절한 스킬 선택, 명확한 절차, 유효한 도구, 실행 권한, 검증 기준이 함께 작동할 때 나온다. 긴 프롬프트를 여러 파일에 복사하는 것만으로 해결되지 않는 이유다.

Agent Skills는 모델을 재학습시키는 기술이 아니다

Agent Skills의 최소 형태는 SKILL.md 파일을 포함하는 폴더다. 공식 사양은 이 파일을 YAML 프런트매터와 마크다운 본문으로 구성하도록 한다. 필수 메타데이터는 name과 description이며, 본문에는 작업 지침을 작성한다. scripts, references, assets 같은 폴더에는 필요에 따라 실행 코드, 상세 문서, 템플릿을 둘 수 있다. 이러한 폴더 구성은 공통 관례이며 모든 폴더를 반드시 만들 필요는 없다.

 

이 구조는 모델의 가중치를 바꾸는 파인튜닝과 다르다. 에이전트가 요청을 처리하는 시점에 외부 지침과 자료를 읽어 행동에 반영하는 방식이다. 따라서 규정이 바뀌었을 때 스킬 파일을 수정해 배포할 수 있지만, 파일을 수정했다는 이유만으로 이미 실행 중인 모든 세션이 새 지침을 사용한다고 가정해서는 안 된다. 배포와 세션 갱신 방식은 사용하는 환경에서 확인해야 한다.

 

Anthropic은 2025년 10월 16일 엔지니어링 글에서 스킬을 지침, 스크립트, 리소스가 정리된 폴더로 설명했다. 같은 글에는 2025년 12월 18일 공개 표준으로 발표했다는 업데이트도 있다. 공개 형식은 패키지를 다른 환경으로 옮기기 쉽게 해 주지만, 모든 에이전트가 같은 도구와 운영체제와 권한을 갖는다는 뜻은 아니다. 형식 호환성과 실제 실행 호환성은 구분해야 한다.

예를 들어 특정 파이썬 라이브러리로 엑셀을 만드는 스킬은 파일 형식을 이해하는 것만으로 실행되지 않는다. 해당 패키지가 설치되어 있어야 하고, 입력 파일을 읽을 수 있어야 하며, 결과를 저장할 위치도 필요하다. 브라우저 도구를 사용하는 절차라면 그 도구가 제공되는지도 확인해야 한다. 지침의 휴대성이 실행 환경의 차이를 없애 주지는 않는다.

 

스킬을 업무 매뉴얼로 비유하면 이해하기 쉽다. 새 담당자에게 계산 규칙, 입력 양식, 검수 항목을 주는 것과 비슷하다. 다만 사람처럼 상식적으로 빈칸을 메울 것이라고 기대해서는 안 된다. 무엇을 확인하지 못했을 때 작업을 멈추고 어떤 정보를 더 받아야 하는지까지 매뉴얼에 포함해야 한다. 매끄럽게 작성된 문서와 실행 가능한 절차는 다른 기준으로 평가할 필요가 있다.

점진적 공개는 필요한 순간에 필요한 지침을 읽는 구조다

Agent Skills의 중요한 설계 원칙은 점진적 공개, 영어로 Progressive Disclosure다. 공식 사양에서 설명하는 첫 단계는 설치된 스킬의 이름과 설명을 먼저 제공하는 것이다. 에이전트는 전체 본문을 미리 읽는 대신 어떤 스킬이 존재하고 언제 쓰는지 파악한다. 두 번째 단계에서는 관련 있다고 판단한 스킬의 SKILL.md를 읽는다. 세 번째 단계에서는 작업에 필요한 참고 문서와 리소스를 추가로 사용한다.

 

공식 사양은 메타데이터를 스킬당 약 100토큰으로 설명하고, 본문은 5,000토큰 미만을 권장한다. 또한 SKILL.md를 500줄 미만으로 유지하도록 안내한다. 이 숫자는 설명과 작성 권고이지, 넘으면 모든 구현에서 실행이 차단되는 일괄 한도가 아니다. 특히 한국어 설명의 실제 토큰 수는 문장과 토크나이저에 따라 달라지므로 줄 수만으로 비용을 계산할 수 없다.

 

정보를 늦게 읽는다고 해서 그 정보가 공짜가 되는 것도 아니다. 참고 문서를 열면 그 내용이나 도구 출력이 문맥에 들어갈 수 있다. 실행 결과가 길면 다시 컨텍스트를 차지한다. 선택 과정에서 여러 스킬을 연달아 읽으면 기대했던 절약이 줄어들 수도 있다. 점진적 공개는 불필요한 선행 로딩을 줄이는 구조이며 총비용과 속도 개선의 보증서는 아니다.

 

간단한 가정으로 구조를 비교해 보자. 스킬 30개의 본문이 각각 2,000토큰이라면 본문을 모두 넣는 데만 60,000토큰이 필요하다. 메타데이터를 각각 100토큰으로 가정하고 이번 작업에서 본문 두 개만 읽는다면 해당 정보는 3,000토큰과 4,000토큰으로 나뉜다. 합계 7,000토큰이다. 여기에는 시스템 지침, 대화, 도구 정의, 참고 문서와 출력이 포함되지 않았다.

 

이 계산은 성능 벤치마크가 아니다. 어떤 정보를 아직 읽지 않았는지 보여 주는 예시다. 실제로는 스킬 선택의 정확성과 추가 조회 횟수, 모델별 요금, 캐시 적용 여부까지 고려해야 한다. 입력 토큰이 줄더라도 파일 조회와 판단 단계가 추가되면 응답 지연은 달라질 수 있다. 컨텍스트 사용량, 최종 성공률, 총비용을 따로 기록해야 한다.

설명문이 모호하면 훌륭한 스킬도 선택되지 않는다

첫 단계에서 에이전트가 보는 이름과 설명은 일종의 선택 인터페이스다. 본문 안에 아무리 훌륭한 업무 규칙이 있어도 관련 스킬이라는 사실을 알아보지 못하면 사용되지 않는다. 반대로 설명이 너무 넓으면 필요 없는 작업에도 자주 선택될 수 있다. 스킬 작성은 본문뿐 아니라 선택 조건을 설계하는 일이다.

“보고서를 잘 만든다”라는 description은 거의 모든 보고서 요청과 겹친다. “한국어 주간 운영 보고서를 작성할 때 사용한다. 집계 기간, 지표 정의, 전주 비교 기준을 확인하고 승인된 템플릿으로 초안을 만든다”처럼 무엇을 하고 언제 쓰는지 구체화하면 범위가 더 분명해진다. 실제로 어떤 문장이 더 잘 선택되는지는 대표 요청으로 확인해야 하며, 길게 썼다는 사실만으로 좋아지는 것은 아니다.

 

특정 표현 하나에만 맞춘 설명도 취약하다. 사용자가 “주간 리포트” 대신 “이번 주 운영 현황 정리”라고 말할 수 있기 때문이다. 반대로 키워드를 무작정 늘리면 무관한 요청까지 끌어들일 수 있다. 같은 의도를 다르게 표현한 요청과 단어는 비슷하지만 의도는 다른 요청을 함께 넣어 선택 품질을 점검하는 편이 좋다.

 

스킬을 써야 하는 경우만큼 쓰지 않아야 하는 경우도 중요하다. 주간 보고서 스킬이 월간 결산이나 개인 일정 요약까지 가져가면 잘못된 기간 규칙을 적용할 수 있다. description에는 핵심 범위를 담고 본문에는 중요한 제외 조건과 다른 절차로 넘길 기준을 둘 수 있다. 환경에 따라 수동 호출이 지원된다면 자동 선택과 수동 선택을 나누어 평가해야 한다.

 

이름에도 역할이 있다. report-helper처럼 넓은 식별자보다 weekly-ops-report처럼 업무를 드러내는 이름이 관리하기 쉽다. 공식 사양은 name의 길이를 최대 64자로 정하고 소문자, 숫자, 하이픈을 이용하는 규칙과 폴더 이름의 일치 조건을 제시한다. 형식 검사를 통과하는 이름과 사람이 유지보수하기 좋은 이름은 모두 필요하지만, 어느 쪽도 설명문의 품질을 대신하지 않는다.

SKILL.md에는 백과사전보다 판단 기준을 담아야 한다

공식 작성 가이드는 모델이 이미 아는 일반 지식보다 프로젝트의 구체적인 규칙과 비직관적인 예외에 집중하라고 안내한다. 보고서가 무엇인지 길게 설명하는 대신, 우리 팀이 한 주를 어떻게 나누고 어떤 원천 데이터를 사용하며 무엇을 누락하면 안 되는지 알려 주는 편이 실용적이다. 스킬이 없으면 틀릴 가능성이 있는 부분을 골라 담아야 한다.

 

예를 들어 “날짜를 정확하게 확인하라”는 지시보다 “집계 구간은 한국 시간 기준 월요일 00시부터 다음 월요일 00시 직전까지이며, 종료 경계는 포함하지 않는다”는 규칙이 구체적이다. 다만 이 규칙이 모든 회사에 맞는 것은 아니다. 실제 조직의 정의를 확인한 뒤 작성해야 한다. 가상의 규칙을 그대로 업무 표준으로 복사하면 정교한 오답을 자동화할 수 있다.

 

좋은 본문에는 시작 전에 확인할 입력, 수행 순서, 분기 조건, 출력 형식, 완료 판정이 연결되어 있다. 원본에 매출이 없으면 0으로 채울지, 결측으로 표시할지, 담당자에게 물을지 결정해야 한다. 통화가 섞이면 환율 기준일이 필요한지 확인해야 한다. 이러한 갈림길을 “적절히 처리하라”로 남겨 두면 실행마다 다른 결과가 나올 수 있다.

 

반대로 모든 판단을 고정 문장으로 통제하려 해도 유지보수가 어려워진다. 문장의 자연스러운 표현이나 설명 순서처럼 여러 답이 가능한 부분은 목적과 기준을 알려 주고 재량을 줄 수 있다. 금액 계산, 승인 여부, 데이터 삭제처럼 작은 차이가 큰 결과를 만드는 부분은 입력과 검증 절차를 더 엄격하게 정해야 한다. 하나의 스킬 안에서도 작업별로 통제 수준이 달라질 수 있다.

예시는 규칙을 이해하게 돕지만 정답 하나를 암기시키는 방식에 머물면 안 된다. 정상 입력과 함께 날짜 누락, 중복 행, 단위 불일치 같은 실패 예시를 짧게 보여 주자. 각 예시에서 어떤 규칙이 적용되는지 연결하면 새로운 입력에도 사용할 수 있다. 실제 고객 정보나 내부 비밀이 예시에 섞이지 않도록 가공하는 것도 작성 단계의 책임이다.

파일을 나누는 것만으로 컨텍스트가 가벼워지지는 않는다

SKILL.md를 짧게 만든 뒤 마지막 줄에 “참고 폴더의 모든 파일을 먼저 읽어라”라고 적으면 점진적 공개의 효과가 줄어든다. 파일 수는 늘었지만 작업마다 전체를 읽는 동작은 그대로이기 때문이다. 어떤 조건에서 어느 파일을 열어야 하는지 연결하는 것이 물리적으로 나누는 일보다 중요하다.

 

예를 들어 “지표의 정의가 불분명할 때 references/metrics.md를 확인한다”, “수정 보고서 요청이면 references/revision.md를 읽는다”처럼 조회 조건을 명시할 수 있다. 모든 작업에 필요한 핵심 조건은 본문에 남기고 특정 분기에만 필요한 상세 설명을 분리한다. 필수 경고를 깊은 부록에 숨기면 에이전트가 그 경고를 읽어야 한다는 사실 자체를 모를 수 있다.

 

공식 사양은 SKILL.md에서 상대 경로로 파일을 참조하고 깊게 이어지는 참조 사슬을 피하도록 권한다. A를 읽어야 B의 존재를 알고 B를 읽어야 C로 가는 구조는 탐색 비용과 누락 가능성을 높인다. 핵심 파일에서 필요한 참고 자료로 바로 갈 수 있게 만들고, 참고 파일 하나가 여러 주제를 떠안지 않게 정리하는 편이 낫다.

 

스킬의 단위도 조정해야 한다. 데이터베이스를 조회해 보고서로 만드는 일은 하나의 일관된 업무가 될 수 있지만, 여기에 서버 운영과 채용 평가까지 묶으면 선택 조건이 흐려진다. 지나치게 잘게 나누면 보고서 하나를 위해 많은 스킬을 읽고 서로 다른 지침을 조정해야 한다. 자주 함께 수행되며 입출력이 자연스럽게 이어지는 범위를 기준으로 나눠 보자.

 

분리는 토큰 절감뿐 아니라 변경 범위를 줄이는 목적도 있다. 지표 정의가 바뀔 때 모든 스킬의 복사본을 고치지 않도록 기준 문서의 소유자를 정해야 한다. 단, 공통 파일을 수정하면 여러 스킬이 동시에 영향을 받는다. 재사용을 늘릴수록 의존 관계와 검증 범위를 함께 관리해야 한다는 점을 잊기 쉽다.

계산과 검증을 스크립트로 옮길 때 달라지는 것

Agent Skills는 지시문 외에 실행 가능한 코드를 포함할 수 있다. Anthropic은 목록 정렬처럼 전통적인 코드 실행이 효율적인 작업과 PDF 양식 필드 추출 예시를 제시한다. 에이전트가 매번 산술 과정을 문장으로 생성하는 대신 검토된 계산 함수를 호출하면 같은 규칙을 재사용하기 쉬워진다. 모든 계산을 언어 모델의 설명 능력에 기대지 않아도 된다.

 

그러나 코드가 있다는 사실은 정확성의 보증이 아니다. 합계 함수가 잘못되었거나 반올림 기준을 틀렸다면 일관되게 잘못된 결과를 만든다. 외부 API나 현재 시각을 사용하는 코드라면 같은 실행이 같은 출력을 낸다고 단정하기도 어렵다. 코드로 옮기는 가치는 규칙을 명시하고 테스트하고 변경 이력을 추적할 수 있다는 데 있다.

실행 코드에는 입력 형식과 출력 형식을 정해 두는 편이 좋다. 필수 열이 없으면 조용히 추측하지 않고 오류를 반환하고, 지원하지 않는 통화나 잘못된 날짜를 만나면 어떤 항목을 수정해야 하는지 알려 주도록 한다. 에이전트가 오류 메시지를 읽고 입력을 수정할 수 있으려면 메시지도 구체적이어야 한다. 단순히 실패했다고만 알리면 같은 잘못된 호출을 반복할 수 있다.

 

검증 코드는 생성 결과와 별도로 두는 방법을 생각해 볼 수 있다. 보고서에 사용한 집계 기간과 원본 행 수, 합계, 누락 항목을 검사하고 통과하지 못하면 완료로 표시하지 않는 방식이다. 다만 생성 코드와 검증 코드가 같은 잘못된 전제를 공유하면 둘 다 통과할 수 있다. 중요한 규칙은 작은 수작업 검산 사례와 도메인 담당자의 확인도 필요하다.

 

스크립트 실행 여부와 소스 열람 여부도 구별해야 한다. 검토한 스크립트를 실행할 때 소스 전체를 모델의 문맥에 넣을 필요가 없는 경우가 있다. 반면 코드 검토나 수정이 목적이라면 내용을 읽어야 한다. 스킬에 이 목적을 명시하면 불필요한 소스 읽기를 줄일 수 있다. 어느 경우든 실행 결과와 오류 출력은 다시 문맥과 로그에 영향을 준다.

스킬과 MCP 그리고 RAG는 어떻게 함께 작동하는가

MCP는 AI 애플리케이션을 외부 도구와 데이터에 연결하는 데 사용하는 프로토콜이다. 스킬은 연결된 기능을 어떤 업무 절차에 따라 사용할지 안내하는 역할을 할 수 있다. 고객지원 시스템에서 주문 조회 도구는 MCP로 제공하고, 어떤 조건을 확인한 뒤 환불 초안을 만들어야 하는지는 스킬에 담는 식이다. 두 구조는 함께 사용될 수 있다.

 

RAG는 필요한 외부 자료를 검색해 모델에 제공하는 구성이다. 스킬이 “계약 체결 시점에 적용되는 약관을 찾아라”라는 절차를 안내하고, 검색 도구가 해당 약관을 가져올 수 있다. 따라서 RAG는 사실만 다루고 스킬은 절차만 다룬다고 완전히 선을 그을 수는 없다. 절차 문서도 검색할 수 있고 스킬에도 참고 정보가 들어갈 수 있다. 중요한 것은 각 정보의 역할과 갱신 경로다.

 

시스템 지침에는 공통 역할과 우선하는 제약을 두고, 스킬에는 특정 업무의 실행 방법을 두는 설계가 가능하다. 다만 구체적인 우선순위와 스킬의 위치는 호스트 구현에 달려 있다. 파일 이름만 보고 모든 지침보다 우선한다고 가정해서는 안 된다. 사용자의 현재 요청과 충돌할 때 어떤 규칙이 적용되는지는 실행 환경의 지침 체계를 따라야 한다.

 

스킬이 별도 에이전트를 항상 대체하는 것도 아니다. 업무별 권한과 책임을 분리해야 하거나 독립된 실행 환경이 필요한 경우에는 별도 구성의 의미가 있다. 반대로 같은 도구와 데이터 접근 범위 안에서 절차만 달라진다면 공통 실행 기반에 여러 스킬을 제공하는 방식이 단순할 수 있다. 구조 선택은 유행보다 권한 경계와 운영 조건에 맞춰야 한다.

 

이동 가능한 파일 형식을 사용하더라도 도구 이름, 호출 방식, 경로, 네트워크 제한은 달라질 수 있다. 공식 사양의 compatibility 필드에는 환경 요구 사항을 적을 수 있다. 그러나 요구 사항을 써 두었다고 환경이 자동으로 준비되지는 않는다. 새 호스트에서 실제 실행을 확인하고, 필요한 기능이 없으면 가능한 작업 범위를 명확하게 반환해야 한다.

한국어 주간 보고서 업무를 스킬로 바꾸는 예시

가상의 운영팀이 매주 CSV를 받아 한국어 보고서 초안을 만든다고 가정하자. 반복되는 문제는 집계 기간이 다르고, 취소 건의 포함 여부가 바뀌며, 매출 증가의 원인을 근거 없이 설명하는 것이다. 이 상황에서는 “훌륭한 분석가처럼 작성하라”보다 기간, 지표, 근거와 완료 조건을 명시하는 일이 먼저다. 보기 좋은 문장을 늘리는 것은 이후의 문제다.

 

스킬 폴더의 이름은 weekly-ops-report로 정할 수 있다. SKILL.md에는 요청 기간과 입력 파일 확인, 지표 정의 조회, 집계 실행, 숫자 검증, 초안 작성, 결과 확인 순서를 둔다. references/metrics.md에는 실제 조직에서 승인한 지표 정의를 보관하고 assets/report-template.md에는 제목과 필수 항목을 둔다. scripts/aggregate.py와 scripts/validate.py는 검토된 집계 및 검사 코드를 담는 예시다.

 

입력 확인에서는 CSV가 있다는 사실만 보지 않는다. 집계 대상 기간, 데이터의 시간대, 열 이름, 중복을 판단할 식별자, 데이터 추출 시점을 확인해야 한다. 전주와 비교하려면 두 기간의 집계 기준과 데이터 완결성도 같아야 한다. 이번 주는 월요일부터 목요일까지만 있는데 전주는 일주일 전체라면 변화율을 그대로 제시하기 어렵다.

 

지표 정의도 이름만으로 추측하지 않도록 한다. 예를 들어 “매출”이 결제 금액인지 환불을 제외한 순액인지에 따라 결과가 달라진다. 원본이 없는 항목은 0과 구분해 미확인으로 표시하고, 통화와 단위가 일치하는지 검증한다. 이런 조건이 조직마다 다르기 때문에 공개된 범용 스킬을 받아도 내부 정의를 연결하는 작업이 필요하다.

 

분석 문장에서는 관측과 해석을 나눈다. “전주 대비 주문 수가 감소했다”는 계산으로 확인할 수 있어도 “광고 성과 하락 때문이다”는 별도 근거가 필요하다. 관련 데이터가 없다면 원인을 단정하지 않고 확인이 필요한 가설로 표시하게 한다. 숫자 형식이 맞는 보고서와 설명까지 근거에 충실한 보고서는 다른 평가 항목이다.

 

완료 조건은 결과 파일이 생겼다는 수준을 넘어야 한다. 기간과 단위가 표시되었는지, 원본 집계와 합계가 맞는지, 결측을 숨기지 않았는지, 실제 근거가 없는 원인 설명이 없는지 확인한다. 이 예시는 설계 설명이며 실행 가능한 완성 패키지를 제공하는 것은 아니다. 실제 적용에서는 승인된 원본과 계산 규칙을 확보하고 샘플 입력으로 검증해야 한다.

지침 파일은 보안 경계가 될 수 없다

스킬은 지침과 코드를 함께 담을 수 있기 때문에 외부 패키지를 설치하는 것과 비슷한 검토가 필요하다. Anthropic의 원문도 신뢰할 수 있는 출처의 스킬을 사용하고, 신뢰가 낮은 경우 포함 파일과 의존성, 외부 네트워크 연결을 점검하라고 설명한다. 읽기 쉬운 마크다운 형식이라는 이유만으로 실행의 영향이 작아지는 것은 아니다.

 

SKILL.md가 평범해 보여도 함께 포함된 스크립트가 외부로 데이터를 전송할 수 있다. 반대로 코드는 안전해 보여도 본문이 에이전트에게 비밀 파일을 읽거나 불필요한 권한을 요청하도록 유도할 수 있다. 따라서 본문만 읽고 승인하거나 코드만 검사하는 방식 모두 부족할 수 있다. 참조 파일과 의존성, 실행 경로를 함께 살펴봐야 한다.

공식 사양의 allowed-tools는 선택 필드이며 실험적이다. 구현마다 지원이 다를 수 있다고 명시되어 있다. 이 필드를 적었다고 모든 호스트에서 동일한 권한 제한이 강제된다고 믿어서는 안 된다. 파일 접근, 네트워크, 실행 권한은 실제 런타임의 정책과 도구 권한으로 통제해야 한다. 지침에 적힌 요청이 사용자가 부여한 권한을 확대하지는 않는다.

 

또한 스킬이 읽는 문서나 웹페이지는 업무 데이터일 수 있다. 그 안에 “이전 지침을 무시하라”는 문장이 들어 있다고 해서 상위 실행 지시가 되는 것은 아니다. 외부 문서를 근거로 활용하는 것과 문서가 에이전트의 권한을 결정하도록 하는 것은 구별해야 한다. 조회 결과를 명령처럼 취급하면 잘 만든 업무 절차도 쉽게 흐트러진다.

 

금전 처리나 외부 발송처럼 영향이 큰 작업에서는 수행 대상과 범위를 검증하는 실행 제어가 필요하다. 모든 단계에 사람 확인을 넣자는 뜻은 아니다. 사전에 허용한 범위와 실제 요청을 연결하고, 초과하는 행동을 분리해서 다루자는 뜻이다. 스킬이 확인을 요구하는 문장을 담고 있는 것만으로 실제 시스템의 승인 경로가 구현되지는 않는다.

스킬을 많이 설치할수록 관리해야 할 충돌도 늘어난다

스킬 수가 늘어도 모든 본문을 미리 읽지 않는다는 점은 장점이다. 그러나 모든 스킬의 이름과 설명을 제공하는 기본 구조에서는 메타데이터 비용이 수에 따라 늘어난다. 비슷한 설명이 많아지면 선택이 어려워질 수도 있다. 본문을 늦게 읽는다는 사실이 스킬 목록을 무제한으로 늘려도 된다는 뜻은 아니다.

 

중복 기능도 점검해야 한다. 보고서 스킬과 문서 편집 스킬이 같은 결과물에 서로 다른 날짜 형식과 제목 규칙을 요구하면 에이전트가 조정해야 한다. 어떤 규칙을 공통 기준으로 삼을지 미리 정하거나, 한 스킬은 내용 구성만 맡고 다른 스킬은 서식 적용만 맡도록 입출력을 구분할 수 있다. 기능이 겹친다면 굳이 둘을 동시에 활성화할 필요가 있는지도 확인하자.

 

스킬 간 의존 관계는 이름으로만 남기지 않는 편이 좋다. 선행 작업의 산출물, 필수 필드, 버전, 실패 조건을 명시하면 다음 단계가 확인하기 쉽다. “다른 스킬이 알아서 처리한다”는 가정은 환경이 바뀌면 깨질 수 있다. 자동 선택에 의존하는지 명시적으로 연결하는지도 구현에서 확인해야 한다.

 

실행 환경의 차이는 시간이 지나면서 더 커진다. API가 바뀌고 패키지가 업데이트되고 템플릿의 필수 항목이 추가될 수 있다. 처음에는 잘 동작했던 스킬이 오래된 명령을 반복할 수 있으므로 마지막 검증 일자와 지원 환경을 남기는 것이 유용하다. 파일을 한 번 배포하고 끝내면 재사용은 쉽더라도 신뢰는 유지되기 어렵다.

좋아 보이는 결과보다 사용 전후의 차이를 측정하자

스킬 평가는 먼저 스킬 없이 수행한 기준선을 만드는 데서 시작할 수 있다. 같은 유형의 작업을 모델이 이미 잘 처리한다면 추가 지침이 실제 가치를 주는지 확인해야 한다. 본문이 길어졌는데 결과는 같고 지연만 늘어날 수도 있다. 공식 작성 가이드도 스킬이 없어도 잘 수행하는 작업이라면 필요성을 평가하라고 안내한다.

 

평가를 세 갈래로 나누면 원인이 잘 보인다. 첫째는 선택 품질이다. 필요한 요청에서 스킬이 선택되고 불필요한 요청에서는 선택되지 않는지 확인한다. 둘째는 수행 품질이다. 올바른 스킬을 활성화한 상태에서 절차와 결과가 맞는지 본다. 셋째는 운영 비용이다. 토큰, 도구 호출 수, 지연, 재시도와 사람의 수정량을 함께 기록한다.

이 구분을 하지 않으면 본문은 좋은데 선택이 안 되는 문제를 본문 수정으로 해결하려 할 수 있다. 반대로 선택은 잘되는데 입력 누락을 처리하지 못하는 문제를 description 확장으로 덮을 수 있다. 자동 선택 실행과 명시적으로 스킬을 지정한 실행을 비교하면 선택 문제와 수행 문제를 나눠 볼 단서를 얻을 수 있다.

 

평가 입력에는 정상 사례뿐 아니라 경계 사례와 무관한 사례를 넣자. 주간 보고서라면 일부 날짜 누락, 전주 데이터 부재, 통화 혼합, 빈 파일, 지표명 변경을 포함할 수 있다. 같은 용어가 나오지만 보고서를 만들라는 요청은 아닌 경우도 필요하다. 입력을 지원하지 않는 상황에서 적절히 질문하거나 보류하는 것도 성공 행동으로 정의해야 한다.

 

결과 파일만 읽는 평가로는 불필요한 실행을 놓칠 수 있다. 최종 보고서가 맞아도 중간에 필요 없는 개인정보를 읽거나 여러 번 같은 작업을 수행했을 수 있다. 공식 가이드는 최종 결과뿐 아니라 실행 궤적을 살펴보라고 설명한다. 어디서 시간을 쓰고 어떤 파일을 불필요하게 읽는지 확인해야 점진적 공개가 실제로 작동하는지도 알 수 있다.

 

한 번의 성공만으로 도입 효과를 확정하지 않는 편이 좋다. 같은 질문도 실행 경로가 달라질 수 있으므로 중요한 평가 항목은 여러 입력과 반복 실행으로 확인한다. 수정할 때 사용한 사례와 최종 확인 사례를 분리하고, 모델이나 도구 버전을 바꿨다면 다시 점검하자. 개선 수치를 제시할 때는 표본과 조건을 함께 적어야 다른 업무로 과장되지 않는다.

팀에서 재사용하려면 문서가 아니라 제품처럼 관리해야 한다

스킬의 실질적인 소유자는 파일을 처음 만든 사람만이 아니다. 업무 규칙을 책임지는 담당자와 실행 코드를 관리하는 담당자, 보안과 운영 환경을 관리하는 사람이 함께 연결되어야 한다. 업무 담당자가 규정을 바꾸었는데 스킬이 갱신되지 않거나 개발자가 코드를 고쳤는데 지표 정의가 달라지면 오류가 남는다.

 

버전 관리는 본문뿐 아니라 참고 문서와 스크립트, 템플릿을 함께 대상으로 삼는 편이 좋다. 결과물에 어떤 스킬 버전과 기준 문서가 사용되었는지 추적할 수 있으면 문제를 재현하기 쉽다. 다만 개인정보가 포함된 입력을 무기한 보관할 필요는 없다. 재현에 필요한 최소 정보와 보존 기간, 접근 권한을 별도로 정해야 한다.

 

수정 사항은 실행 가능한 기준과 연결하자. “더 친절하게 작성” 같은 변경은 평가가 애매하지만 “전주 데이터가 없을 때 변화율을 생성하지 않고 비교 불가로 표시”는 확인할 수 있다. 실무에서 사람이 고친 부분을 규칙으로 정리하되, 특정 고객의 예외를 전체 표준처럼 확대하지 않는 것이 중요하다. 개별 사례와 재사용 가능한 규칙을 구별해야 한다.

 

새 규칙이 들어갈 때마다 파일을 길게 만드는 대신 중복과 오래된 지침을 제거하는 과정도 필요하다. 충돌하는 문장을 덧붙이면 에이전트가 최신 의도를 추론해야 한다. 변경 이력은 유지하더라도 실행용 본문에는 현재 적용할 절차가 명확하게 보이도록 정리하자. 문서의 축적과 실행 지침의 품질은 같은 방향으로만 움직이지 않는다.

 

처음 도입할 때는 빈도가 높고 결과를 검증하기 쉬운 작업 하나가 적당하다. 정확한 입력과 완료 조건이 없는 복잡한 업무 전체를 한 번에 스킬화하면 실패 원인을 찾기 어렵다. 작은 업무에서 기준선과 개선을 확인한 뒤 범위를 넓히면 유지비도 판단하기 쉽다. 스킬이 늘어나는 속도보다 검증하고 갱신할 수 있는 속도를 기준으로 운영해야 한다.

자주 묻는 질문

Q. Agent Skills는 긴 프롬프트를 파일로 저장한 것과 무엇이 다른가요?

지침을 파일로 둔다는 점은 비슷하지만, 메타데이터로 관련 스킬을 찾고 본문과 참고 자료를 필요할 때 읽으며 실행 코드와 템플릿을 함께 구성할 수 있다는 점이 다르다. 다만 실제 호스트가 어떻게 로딩하고 실행하는지에 따라 효과가 달라진다. 모든 파일을 처음부터 읽게 만들면 구조의 장점이 줄어든다.

Q. 스킬을 쓰면 프롬프트 엔지니어링이 필요 없어지나요?

필요한 지시를 설계하는 일은 계속된다. 설명문의 선택 조건, 본문의 절차, 분기와 완료 기준이 모두 지시 설계다. 스킬은 이를 재사용하고 필요한 시점에 전달하기 쉽게 만드는 방식이다. 문장 한 덩어리의 최적화에서 정보 구조와 실행 검증으로 범위가 넓어진다고 이해하면 된다.

Q. SKILL.md가 500줄을 넘으면 사용할 수 없나요?

공식 사양의 500줄 미만과 5,000토큰 미만은 권고다. 모든 환경에 동일한 강제 오류 조건이 있다는 뜻은 아니다. 길이가 늘면 핵심 절차와 조건별 참고 자료를 나누고, 필요한 파일만 읽는지 실행 기록으로 확인하는 편이 좋다.

Q. 공개 스킬을 그대로 설치해도 되나요?

출처와 라이선스, 포함 코드와 의존성, 외부 연결, 요구 권한을 먼저 확인해야 한다. 특히 내부 데이터에 접근하는 환경에서는 공개된 패키지의 목적이 우리 업무와 맞는지도 점검해야 한다. 설치 가능하다는 사실과 조직에서 사용해도 된다는 판단은 다르다.

Q. 같은 스킬을 다른 에이전트에서도 그대로 쓸 수 있나요?

공통 형식은 이동과 재사용에 도움이 되지만 실제 도구, 경로, 패키지, 권한이 같다는 보장은 없다. compatibility 같은 환경 정보를 참고하고 새 환경에서 대표 작업을 실행해 봐야 한다. allowed-tools 등 구현 차이가 있는 항목도 별도로 확인해야 한다.

Q. RAG가 이미 있으면 스킬은 필요 없나요?

업무가 단순한 문서 질의라면 RAG만으로 충분할 수 있다. 반면 여러 도구를 어떤 순서로 사용하고 어떤 조건에서 멈추며 결과를 어떻게 검증할지 반복해서 안내해야 한다면 스킬 구조를 검토할 수 있다. 기존 구성에 추가했을 때 정확도와 운영 부담이 어떻게 달라지는지 평가하는 것이 먼저다.

좋은 스킬은 긴 설명보다 반복되는 실수를 줄인다

Agent Skills가 제안하는 변화는 모델에게 더 많은 문장을 읽히는 경쟁에서 벗어나, 필요한 절차를 찾고 실행하고 검증하는 구조를 만드는 것이다. 이름과 설명은 선택을 돕고, SKILL.md는 핵심 흐름을 안내하며, 참고 자료와 스크립트는 필요한 세부 작업을 지원한다. 이 역할이 분명할수록 규정 변경과 오류 수정도 다루기 쉬워진다.

 

결국 중요한 질문은 “우리 팀에 스킬이 몇 개 있는가”가 아니다. 스킬이 없을 때 반복되던 어떤 실수가 줄었는지, 불필요한 실행과 비용이 늘지는 않았는지, 환경이 바뀌어도 같은 기준으로 검증할 수 있는지다. 읽기 좋은 매뉴얼을 만드는 데서 멈추지 않고, 확인할 수 있는 업무 절차로 다듬을 때 AI 에이전트의 재사용 가능한 능력이 된다.

참고 자료

Anthropic, Equipping agents for the real world with Agent Skills. 2025년 10월 16일 게시, 2025년 12월 18일 공개 표준 관련 업데이트. 구조와 점진적 공개, 코드 실행, 평가와 보안 고려 사항을 설명한 원자료다. 원문: https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills

 

Agent Skills 공식 사양, Specification. SKILL.md 필드, 선택 폴더, 점진적 공개, 파일 참조와 작성 권고를 확인했다. 토큰 수와 줄 수 권고를 강제 실행 한도로 일반화하지 않았다. 원문: https://agentskills.io/specification

Specification - Agent Skills

 

Agent Skills 공식 작성 가이드, Best practices for skill creators. 실제 업무 지식, 적절한 범위, 조건별 참조, 검증 반복과 실행 기록을 활용하는 원칙을 참고했다. 원문: https://agentskills.io/skill-creation/best-practices

Best practices for skill creators - Agent Skills

 

코어닷투데이, 에이전트를 만들지 말고 스킬을 만들라. 2026년 9월 19일 게시. 국내 기업 기술 블로그가 개념과 업무 적용을 연결하는 전개를 비교했다. 이 글의 보고서 사례와 가정 계산은 별도로 구성했다. 원문: https://core.today/blog/dont-build-agents-build-skills-2026

에이전트를 만들지 말고 스킬을 만들라 — 앤트로픽 「Agent Skills」 완전 해부: 업무 매뉴얼로 범

 

DoubleS2's Story, Agent Skills 완전정복 첫 번째 글: 개념과 작동 원리. 2026년 7월 1일 게시. 국내 개발 블로그의 개념 설명과 단계별 서술 형식을 비교했다. 제품 간 동작은 공식 사양과 실제 실행 환경의 차이를 고려해 설명했다. 원문: https://doubles-won.tistory.com/133