에이전트 스킬 완벽 가이드: 재사용 설계와 보안

2026년 8월 17일 기준 공식 규격에서 스킬 이름은 최대 64자, 설명은 최대 1024자로 제한됩니다. 이 구조가 보여주듯 에이전트 스킬 완벽 가이드의 핵심은 긴 프롬프트를 계속 늘리는 것이 아니라, 필요한 순간에 불러올 지식과 절차를 독립된 능력 묶음으로 분리하는 것입니다. 안정적인 업무 규칙은 스킬에 넣고, 자주 바뀌는 사실은 지식원에 두며, 파일 수정이나 외부 서비스 호출은 별도 도구와 권한으로 통제해야 합니다.

마지막 업데이트: 2026년 8월 17일. 규격 필드와 호출 방식은 공식 에이전트 스킬 규격, 공식 스킬 저장소, 클로드 코드 스킬 문서를 기준으로 확인했습니다.

이 글은 처음 SKILL.md를 작성하는 개발자, 팀의 표준 절차를 재사용하려는 클로드 코드 사용자, 내부 스킬 저장소의 보안과 변경 이력을 관리해야 하는 기술 책임자를 위한 안내서입니다. 책이나 PDF를 스킬로 변환하는 상세 과정은 별도 주제이므로 여기서는 다루지 않습니다.

첫 단계: 프롬프트가 아니라 스킬로 분리해야 하는 이유

전문 지식을 시스템 프롬프트나 대화창에 계속 붙여 넣으면 세 가지 문제가 생깁니다.

첫째, 모든 작업에 필요하지 않은 규칙까지 매번 문맥에 들어갑니다. 코드 검토 규칙, 배포 절차, 문서 양식이 한곳에 쌓이면 실제 요청과 무관한 정보가 모델의 판단 공간을 차지합니다. 일반적인 프로젝트 규칙은 항상 읽는 설정에 두고, 반복 절차와 분야 지식은 필요할 때 불러오는 스킬로 분리하는 편이 효율적입니다.

둘째, 변경 범위가 불명확해집니다. 한 문장을 고치기 위해 거대한 프롬프트를 수정하면 어느 업무에 영향이 생겼는지 추적하기 어렵습니다. 반면 스킬은 폴더 단위로 버전 관리할 수 있어 변경 책임자와 검토 기록을 남기기 쉽습니다.

셋째, 작업의 재현성이 떨어집니다. 사람이 대화마다 다른 표현으로 지시하면 같은 요청도 결과 형식과 검증 순서가 달라질 수 있습니다. 스킬은 입력 조건, 실행 순서, 예외 처리, 완료 기준을 함께 묶어 결과 편차를 줄이는 데 적합합니다.

다만 스킬은 독립적으로 실행되는 서버나 권한 관리자가 아닙니다. 스킬은 에이전트가 읽고 따르는 지침과 선택적 자료를 제공할 뿐입니다. 외부 시스템에 접근하려면 해당 에이전트가 가진 도구와 허용 권한이 별도로 필요합니다.

두 번째 단계: 최소 구조부터 설계하기

공식 규격의 최소 단위는 폴더와 SKILL.md입니다. scripts, references, assets는 선택 항목입니다. 처음부터 모든 자료를 넣기보다 호출 조건과 실행 절차가 분명한 최소 스킬을 만든 뒤, 실제 사용 중 반복되는 자료만 분리하는 편이 관리하기 좋습니다.

code-review/
├── SKILL.md
├── references/
│   └── review-rules.md
├── scripts/
│   └── collect-diff.py
└── assets/
    └── review-template.md

각 구성 요소의 역할은 다음과 같습니다.

구성 요소	담당 역할	넣기 좋은 내용	넣지 말아야 할 내용
폴더 이름	스킬 식별과 호출 이름	짧고 고유한 소문자 이름	여러 업무를 뜻하는 모호한 이름
`SKILL.md`	호출 조건과 핵심 실행 지침	단계, 입력, 예외, 완료 기준	장기간 변하는 사실의 전체 목록
`references`	필요할 때 읽는 참고 지식	규정, 표준, 세부 설명	매번 반드시 읽어야 하는 핵심 절차
`scripts`	반복 계산과 파일 처리를 자동화	검증, 변환, 수집 코드	검토되지 않은 설치 명령과 삭제 명령
`assets`	결과물 제작에 쓰는 정적 자료	템플릿, 예시, 양식	비밀키, 개인 자료, 불명확한 실행 파일

SKILL.md의 앞부분에는 보통 메타 정보와 지침이 들어갑니다. 규격상 name과 description은 필수이며, name은 부모 폴더 이름과 일치해야 합니다. description은 무엇을 하는지와 언제 사용하는지를 함께 설명해야 합니다. 설명이 “개발을 돕는다”처럼 넓으면 인접 스킬과 호출이 겹치거나 필요한 순간에 불리지 않을 수 있습니다. 세부 규칙은 공식 규격의 필드 설명에서 확인할 수 있습니다.

`SKILL.md`에는 무엇을 넣어야 하나요?

실무에서 필요한 내용은 다음 다섯 묶음입니다.

역할: 이 스킬이 해결하는 작업을 한 문장으로 정의합니다.
호출 조건: 어떤 요청, 파일 유형, 작업 상태에서 사용해야 하는지 적습니다.
실행 단계: 자료 확인, 처리, 검증, 결과 보고 순서를 적습니다.
예외 처리: 입력이 없거나 권한이 부족하거나 결과가 불완전할 때의 중단 조건을 적습니다.
완료 기준: 어떤 파일, 보고서, 테스트 결과가 있어야 끝난 것으로 볼지 정합니다.

예를 들어 코드 검토 스킬이라면 “변경 파일을 읽고 위험한 변경을 분류한다”에서 끝내지 말고, 테스트 실행 여부, 비밀정보 노출 확인, 결과 보고 형식까지 지정해야 합니다. 단순한 지식 안내와 실제 작업 지시를 한 문서에 섞을 때에는 먼저 참고 규칙을 읽게 하고, 그다음 실행 순서를 제시하면 모델의 행동 범위를 줄일 수 있습니다.

공식 규격은 본문에 단계별 지침, 입력과 출력 예시, 예외 사례를 넣을 수 있다고 설명합니다. 긴 자료는 별도 참고 파일로 옮기는 편이 좋으며, 세부 자료를 분리하면 핵심 지침의 검토 범위도 줄어듭니다.

주의: 스킬 본문에 “항상 모든 파일을 읽는다”처럼 범위가 넓은 지시를 넣으면 작은 요청에도 불필요한 파일 접근이 발생할 수 있습니다. 먼저 필요한 파일의 조건을 적고, 조건을 충족할 때만 참고 자료를 읽도록 설계해야 합니다.

세 번째 단계: 호출 설명을 좁고 검증 가능하게 만들기

Agent Skills의 호출은 보통 이름과 설명을 먼저 확인한 뒤, 작업이 설명과 맞을 때 전체 지침을 읽는 방식으로 진행됩니다. 공식 개요는 이를 발견, 활성화, 실행의 세 단계로 설명합니다. 따라서 설명은 단순한 소개 문구가 아니라 스킬 선택을 위한 분류 기준입니다.

좋은 설명은 다음 두 질문에 답합니다.

이 스킬은 무엇을 처리합니까?
어떤 표현이나 상황에서 사용해야 합니까?

예를 들어 다음과 같은 차이가 있습니다.

description: 코드 검토를 지원합니다.

description: 변경된 소스 코드를 검토하고 보안 위험, 테스트 누락, 호환성 문제를 정리합니다. 사용자가 코드 리뷰, 변경 검토, 병합 전 점검을 요청하거나 비교된 변경 내역을 제공했을 때 사용합니다.

두 번째 설명은 작업과 호출 조건을 함께 제시합니다. 반대로 배포 스킬과 운영 점검 스킬이 모두 “서버를 관리한다”고 적혀 있으면 호출 중복이 생깁니다. 실제 저장소에서는 다음과 같이 시험하는 것이 좋습니다.

정답 예시: 스킬이 반드시 불려야 하는 요청
오답 예시: 비슷하지만 다른 스킬이 처리해야 하는 요청
경계 예시: 두 스킬의 설명이 겹칠 수 있는 짧은 요청
직접 호출 예시: 자동 선택을 거치지 않고 특정 절차를 실행하는 요청

설명이 모호하면 모델이 잘못된 스킬을 선택할 수 있습니다. 작업에 부작용이 있는 경우에는 자동 호출을 막고 사용자가 직접 실행하도록 설정하는 방식도 검토해야 합니다. 클로드 코드에서는 스킬을 사용자의 직접 호출로만 제한하는 설정을 제공하며, 세부 동작은 클로드 코드의 스킬 호출 설정에서 확인할 수 있습니다.

네 번째 단계: 지식, 절차, 도구의 경계를 나누기

스킬 설계에서 가장 흔한 오류는 모든 것을 하나의 폴더에 넣고 스킬 자체가 외부 작업을 수행한다고 생각하는 것입니다. 다음 기준으로 나누면 판단이 쉬워집니다.

스킬: 변하지 않는 방법, 팀 규칙, 판단 순서, 결과 형식을 담습니다.
지식원: 최신 가격, 현재 장애 상태, 변경 가능한 제품 문서처럼 갱신이 필요한 사실을 담습니다.
도구: 데이터베이스 조회, 저장소 변경, 외부 서비스 등록처럼 권한이 필요한 행위를 담당합니다.
일반 프롬프트: 특정 대화에서만 필요한 일회성 요청을 전달합니다.
MCP: 외부 서비스와 에이전트를 연결하는 통로입니다. 어떤 자료를 어떤 순서로 조회할지는 스킬이 설명할 수 있지만, 연결과 권한은 MCP와 실행 환경이 결정합니다.

따라서 “고객 정보를 조회하고 삭제한다”는 문장을 스킬에 넣는 것만으로 실제 권한이 생기지 않습니다. 스킬은 “삭제 전 본인 확인, 대상 식별, 승인 기록 확인, 실행 후 검증”이라는 절차를 제공하고, 실제 삭제 기능은 제한된 도구가 수행해야 합니다.

Agent Skills와 프롬프트의 차이도 같은 기준으로 설명할 수 있습니다. 프롬프트는 현재 대화의 지시문이고, 스킬은 폴더와 파일로 저장되어 여러 작업과 프로젝트에서 불러올 수 있는 버전 관리 단위입니다. 프롬프트가 즉석 지시에 가깝다면, 스킬은 호출 조건과 실행 절차를 갖춘 운영 자산에 가깝습니다.

Agent Skills와 MCP의 결합에서는 역할을 섞지 않아야 합니다. 스킬은 MCP 도구를 언제 어떤 순서로 사용할지 설명할 수 있지만, MCP가 제공하지 않는 권한을 만들어 내지는 않습니다. 도구 목록, 계정 권한, 승인 방식은 실행 환경에서 별도로 관리해야 합니다.

다섯 번째 단계: 스크립트 호출은 가능하지만 권한을 먼저 제한하기

Agent Skill은 scripts 폴더에 실행 코드를 넣을 수 있습니다. 공식 규격은 스크립트가 독립적으로 실행되거나 필요한 의존성을 명확히 설명해야 하며, 오류 메시지와 예외 처리를 제공해야 한다고 안내합니다. 다만 실제 지원 언어와 실행 방식은 에이전트 제품마다 다를 수 있습니다.

스크립트형 스킬은 다음 작업에 적합합니다.

반복되는 형식 변환
입력 파일의 구조 검사
테스트 결과 수집
정해진 템플릿에 맞춘 보고서 생성
변경 내역이나 로그의 제한적 요약

반대로 다음 작업은 별도 승인 없이는 피해야 합니다.

사용자 홈이나 프로젝트 바깥의 대량 파일 변경
인터넷에서 내려받은 파일의 즉시 실행
비밀키와 환경 변수의 자동 수집
데이터베이스 삭제와 권한 변경
출처와 라이선스가 불명확한 제삼자 코드 실행

설치 전 보안 점검

[ ] 저장소의 작성자와 변경 이력을 확인합니다.
[ ] 라이선스와 재배포 조건을 확인합니다.
[ ] SKILL.md에서 실행 명령과 파일 접근 경로를 모두 읽습니다.
[ ] scripts 안의 네트워크 요청, 파일 삭제, 셸 호출을 검색합니다.
[ ] 필요한 패키지가 어디에서 설치되는지 확인합니다.
[ ] 실제 업무 자료가 없는 격리 폴더에서 먼저 실행합니다.
[ ] 읽기 전용 계정과 제한된 환경 변수로 동작을 시험합니다.
[ ] 정상 결과뿐 아니라 실패와 중단 조건도 기록합니다.
[ ] 자동 호출이 적절한지, 직접 호출만 허용할지 결정합니다.
[ ] 검증된 버전을 내부 저장소에 고정합니다.

운영 경험상 중요한 지점: 제삼자 스킬은 SKILL.md만 읽고 안전하다고 판단하면 안 됩니다. 참고 파일의 경로 이동, 스크립트의 하위 명령, 설치 과정의 네트워크 접근까지 확인해야 실제 실행 범위를 파악할 수 있습니다.

여섯 번째 단계: 하나의 스킬을 팀 자산으로 운영하기

개인용 스킬은 파일 하나로 시작할 수 있지만, 팀에서 공유하는 순간 운영 규칙이 필요합니다. 최소한 다음 항목은 저장소에 함께 관리하는 편이 좋습니다.

소유 팀과 담당자
지원하는 에이전트와 실행 환경
버전과 변경 날짜
자동 호출 테스트와 직접 호출 테스트
정상 입력, 경계 입력, 금지 입력
스크립트와 외부 도구의 권한 범위
변경 기록과 이전 버전의 호환성
폐기 조건과 대체 스킬

클로드 코드에서는 개인, 프로젝트, 확장 기능 등 여러 범위에서 스킬을 둘 수 있으며, 프로젝트 스킬은 버전 관리 저장소에 넣어 팀과 공유할 수 있습니다. 다만 제품마다 검색 위치와 추가 기능이 다르므로 한 제품의 발견 규칙을 모든 호환 에이전트에 그대로 적용해서는 안 됩니다.

스킬 수를 늘리는 것보다 우선순위를 정하는 것이 중요합니다. 호출 빈도가 높고, 결과를 자동 또는 수동으로 확인할 수 있으며, 실패 비용이 명확한 절차부터 등록해야 합니다. 예를 들면 코드 검토, 릴리스 전 점검, 문서 형식 검사처럼 완료 조건이 분명한 작업이 적합합니다. 반대로 “팀의 모든 개발 지식을 알려주는 스킬”은 범위가 넓어 호출 조건과 품질 기준을 만들기 어렵습니다.

내부 저장소를 운영할 때에는 새 스킬을 등록하기 전에 작은 검증 묶음을 실행해야 합니다. 정상 요청, 유사 요청, 금지된 요청, 입력 파일이 없는 요청을 각각 시험하고 결과를 기록합니다. 이후 스킬 설명이나 실행 절차가 바뀌면 같은 검증 묶음을 다시 실행해야 합니다. 호출이 잘되는지만 보지 말고, 호출되지 않아야 할 때 호출되지 않는지도 확인해야 합니다.

원격 개발 환경을 검토할 때에는 제공 업체의 지원 범위와 접속 방식을 먼저 확인해야 합니다. Vuncloud의 서비스 소개를 확인하면 원격 맥 환경이 실제 스킬 운영 조건에 맞는지 판단하는 데 도움이 됩니다. 스킬 자체의 권한 설계와 원격 장비의 접속 권한은 별도로 점검해야 하며, 둘을 하나의 보안 경계로 간주해서는 안 됩니다.

마무리: 현재 환경과 원격 맥 환경을 비교할 때

로컬 환경에서 스킬을 시험하는 방식은 빠르지만, 장시간 실행 시 개발자의 컴퓨터 자원을 점유하고, 팀원마다 운영체제와 패키지 상태가 달라지며, 외부 협업이나 반복 검증을 위해 같은 환경을 다시 만들어야 하는 부담이 생깁니다. 사내 서버는 고정된 환경을 만들 수 있지만 초기 설정과 유지 관리, 접근 권한, 원격 접속 구성이 추가됩니다.

일회성 검증이나 임시 개발 환경이 필요한 경우에는 원격 맥 환경을 별도로 확보하는 선택지가 있습니다. 특히 클로드 코드 기반 작업을 여러 환경에서 시험하거나 팀원이 같은 프로젝트 환경에 접속해야 한다면 한국 지역의 맥 미니 대여 환경을 검토할 수 있습니다. 다만 장기간 같은 장비를 계속 사용하는 고정형 업무, 물리 장치 연결이 필수인 작업, 높은 수준의 로컬 저장 장치 통제가 필요한 경우에는 직접 구매나 전용 서버가 더 적합할 수 있습니다. 원격 환경의 접속 조건이나 지원 범위는 별도로 확인한 뒤 도입하는 편이 안전합니다.

에이전트 스킬을 처음 도입하는 개발자는 먼저 작은 스킬 하나를 격리 환경에서 검증하고, 이후 원격 개발 환경과 연결하는 순서가 안전합니다. 제삼자 스크립트형 스킬을 바로 팀 전체에 배포하기보다, 호출 조건과 권한 범위를 확인한 뒤 승인된 버전만 내부 저장소에 편입하는 것이 장기 운영에 유리합니다.