AI 에이전트 Skill이란? SKILL.md 작성법

에이전트에게 같은 절차를 세 번째 설명하고 있다면 프롬프트를 늘릴 때가 아니라 작업 방식을 파일로 꺼낼 때입니다. “이 명령을 쓰고, 이 파일은 건드리지 말고, 완료 전에 이 검사를 해” 같은 규칙이 대표적입니다.

Agent Skill은 모델을 새로 학습시키는 기능이 아닙니다. 특정 업무를 수행하는 절차와 조직의 규칙을 폴더에 정리해 두고, 에이전트가 필요할 때 읽어 쓰게 하는 재사용 가능한 작업 패키지입니다. 핵심 파일은 SKILL.md이고, 필요하면 스크립트·참고 문서·템플릿도 함께 둡니다.

일반 프롬프트와 무엇이 다른가

일반 프롬프트는 한 대화에서 바로 효과를 내는 지시입니다. Skill은 그 지시를 이름 있는 파일과 폴더로 만들어 여러 작업에서 꺼내 쓰는 방식입니다. 그래서 Skill의 핵심 이점은 “더 똑똑한 답”이라는 보장보다, 같은 작업을 다시 설명하는 비용과 사람마다 다른 작업 순서를 줄이는 데 있습니다.

Agent Skills 표준은 SKILL.md의 name과 description을 최소 메타데이터로 요구합니다. 에이전트는 시작할 때 이 짧은 설명을 먼저 보고, 작업이 맞을 때 전체 지침을 읽습니다. 이 점진적 공개 덕분에 설치된 모든 Skill의 긴 본문을 매번 대화에 넣지 않아도 됩니다.

OpenAI의 Codex Skill 작성 문서도 같은 흐름을 전제로 합니다. Skill은 프로젝트·사용자·시스템 범위에 설치할 수 있고, 에이전트는 이름과 설명을 먼저 확인한 뒤 선택된 Skill의 SKILL.md와 필요한 참고 자료·스크립트를 읽습니다. 따라서 description은 검색어처럼 “무엇을 언제 쓰는가”를 드러내야 하고, 본문은 선택된 뒤 바로 실행할 수 있는 순서와 중단 조건에 집중해야 합니다.

작은 Skill 하나를 설계하는 법

처음부터 “개발 전부를 잘하는 Skill”을 만들면 설명이 길어지고 언제 발동해야 하는지도 흐려집니다. 한 사람이 반복해서 하는 좁은 업무 하나를 고르는 편이 좋습니다. 예를 들어 “Next.js 페이지 작성”보다 “새 페이지를 만들기 전에 기존 디자인 토큰과 접근성 검사를 확인하는 절차”가 더 좋은 출발점입니다.

최소 형태는 다음과 같습니다.

---
name: release-check
description: 배포 전 변경 범위와 검증 명령을 확인할 때 사용
---

# Release check

1. 변경 파일과 민감한 설정을 먼저 확인한다.
2. 프로젝트가 정한 lint와 test를 실행한다.
3. 실패를 숨기지 않고 원인과 남은 위험을 요약한다.
4. 배포나 외부 전송은 사람의 승인을 받은 뒤 실행한다.

좋은 description은 이름만 멋지게 쓰는 대신 “무엇을 하고 언제 쓰는가”를 함께 알려 줍니다. 본문에는 입력 조건, 작업 순서, 성공 조건, 중단 조건, 출력 형식을 넣습니다. “최선을 다한다”보다 “테스트가 실패하면 수정했다고 말하지 않는다”처럼 관찰 가능한 규칙이 낫습니다.

예시: 같은 요청인데 HTML이 어떻게 달라질까

다음은 실제 특정 에이전트의 실행 결과가 아니라, Skill이 무엇을 바꾸는지 보여 주는 개념 예시입니다. 같은 요청을 보내도 모델·클라이언트·프로젝트 파일에 따라 결과는 달라질 수 있습니다.

사용자 요청은 단순하게 두겠습니다.

상품 소개 카드를 HTML로 만들어 줘. 제목, 설명, 자세히 보기 버튼을 넣어 줘.

Skill 없이 바로 요청하면 다음처럼 기능만 충족하는 결과가 나올 수 있습니다.

<div class="card">
  <h2>상품 이름</h2>
  <p>상품 설명입니다.</p>
  <button>자세히 보기</button>
</div>

이 HTML이 틀렸다는 뜻은 아닙니다. 다만 프로젝트의 디자인 토큰, 키보드 초점, 제목 연결, 모바일 레이아웃, 버튼 동작을 에이전트가 알 방법은 요청에 적혀 있지 않습니다.

반대로 frontend-card라는 Skill에 “카드에는 의미론적 article을 쓰고, 제목과 본문을 연결하며, 기존 CSS 변수만 사용하고, 모바일에서도 버튼을 누를 수 있는지 확인한다”는 규칙이 있다면 결과는 다음 방향으로 달라질 수 있습니다.

<article class="card" aria-labelledby="product-card-title">
  <div class="card__body">
    <h2 id="product-card-title">상품 이름</h2>
    <p>상품 설명입니다.</p>
    <a class="card__link" href="/products/example">
      자세히 보기<span aria-hidden="true"> →</span>
    </a>
  </div>
</article>

Skill이 자동으로 아름다운 HTML을 보장하는 것은 아닙니다. 차이는 “카드 만들어 줘”라는 한 번의 지시가 “우리 프로젝트에서 카드를 만들 때 지켜야 할 구조와 검증 조건”으로 확장된다는 데 있습니다. 실제 CSS·링크·접근성 검사는 프로젝트의 도구와 Skill 내용에 달려 있습니다.

Skill 폴더의 한 작업을 끝까지 연결하기

Skill을 제대로 설계하려면 파일 목록을 나열하는 데서 멈추지 말고, 사용자 요청이 결과와 검증으로 이어지는 경로를 적어야 합니다.

1. 발견: 요청에 맞는지 판단할 수 있도록 name·description에 대상 작업과 제외 범위를 씁니다.
2. 입력 확인: 대상 파일, 버전, 권한, 산출물 형식처럼 작업 전에 모르면 안 되는 값을 정리합니다.
3. 자료 로드: 긴 정책과 API 설명은 references/에서 필요한 것만 읽고, 반복 로직은 scripts/를 호출합니다.
4. 실행: 각 단계에서 만든 파일과 명령을 기록하고, 외부 전송·삭제·배포는 승인 지점에서 멈춥니다.
5. 검증: 성공 조건뿐 아니라 실패 시 남겨야 할 로그와 되돌리기 방법을 확인합니다.
6. 출력: 변경 파일, 검증 결과, 남은 위험, 다음 사람이 이어서 할 일을 같은 형식으로 보고합니다.

이 흐름을 SKILL.md의 상위 단계로 두고 세부 API는 참고 문서로 내리면, 본문이 길어져도 에이전트가 중요한 순서를 놓치지 않습니다.

크게 보기

×확대 이미지 닫기

이 프로젝트의 콘텐츠 Skill을 예로 들면

ai-it-publisher처럼 글을 작성하는 Skill은 “한국어 글을 잘 써라”에서 끝나면 재사용하기 어렵습니다. 다음처럼 입력과 산출물을 좁히면 실제 작업 계약이 됩니다.

• 입력: 글의 검색 의도, 독자 수준, 정보 기준일, 공식 출처 후보, 재현 기록 유무
• 절차: content-depth.md로 질문과 종단 예시를 정한 뒤 source-and-testing.md로 주장·근거를 연결하고, 필요한 이미지만 생성·검수
• 중단: 가격·권한·보안 주장을 1차 출처로 확인하지 못했거나, 직접 테스트하지 않은 내용을 테스트 결과처럼 쓰려 할 때
• 산출물: MDX, 출처 목록, 시각 자료의 설명·권리 기록, 검증 명령과 실패 기록

이것은 현재 저장소의 문서 구조를 설명한 개념·문서 기반 예시입니다. 어떤 클라이언트가 해당 Skill을 자동으로 선택하거나 어떤 글의 품질이 보장된다는 실행 결과를 뜻하지 않습니다.

release-check 예시는 입력과 중단 조건까지 적는다

배포 전 release를 검사하는 Skill이라면 “release를 확인한다”는 설명만으로는 부족합니다. 정상 입력, 예상 보고, 멈춰야 할 입력을 한 묶음으로 둡니다.

• 정상 입력: releaseId=release-2026-09-08-01, expectedArticles=17, mode=verify-only
• 예상 보고: “상태 verified, article 17/17, content hash 17/17, source media hash 55/55, 누락 0, 배포 실행 안 함”처럼 검사 대상과 분모, 미실행 작업을 함께 적습니다.
• 중단 입력: release 상태가 building이거나 expectedArticles가 없거나 source hash가 하나라도 맞지 않으면 자료화·배포로 넘어가지 않고 실패 항목만 보고합니다.

이 예시는 입력·출력 계약을 보여 주는 가상 기록이며 실제 release 검사 결과가 아닙니다. Skill의 scripts/는 호스트가 이미 제공하고 허용한 CLI·SDK·HTTP 도구를 실행할 수 있습니다. MCP는 호스트와 외부 서비스를 표준 방식으로 연결할 때 유용하지만 외부 접근의 필수조건은 아닙니다. 어느 경로든 Skill 자체가 새 권한을 만들지는 않으며, 실제 실행 범위는 호스트의 도구와 승인 정책이 결정합니다. (Agent Skills 명세)

Skills.sh에서 찾고, 설치 전 확인하기

skills.sh는 Agent Skill을 검색하고, 전체·트렌딩·인기·공식·보안 감사 분류로 살펴볼 수 있는 디렉터리입니다. 공식 문서에 따르면 인기 순위는 skills CLI의 익명 설치 데이터로 집계됩니다. 따라서 인기순은 “많이 설치됐다”는 신호이지, 모든 프로젝트에 맞거나 안전하다는 보증은 아닙니다.

예를 들어 목록에서 필요한 Skill을 찾은 뒤 CLI로 추가하는 흐름은 다음과 같습니다. Node.js와 npm이 설치돼 있다면 Windows PowerShell·macOS zsh·Linux bash 공통으로 실행합니다.

npx skills add vercel-labs/agent-skills

실제 사용 전에는 다음 순서로 확인하세요.

1. Skill의 원본 저장소, 작성자, 라이선스와 최근 변경을 확인합니다.
2. SKILL.md뿐 아니라 scripts/, references/, assets/ 전체를 읽습니다.
3. 파일 삭제·네트워크 접속·패키지 설치·비밀정보 읽기 지시가 있는지 찾습니다.
4. 정상·경계·실패 입력을 별도 브랜치나 샌드박스에서 점검합니다.
5. 팀에 배포한다면 버전과 변경 기록을 고정하고 업데이트마다 다시 검토합니다.

Anthropic의 공개 Skill 저장소는 공식 예시를 살펴보는 출발점으로 좋고, 명세는 agentskills.io에서 확인할 수 있습니다. 디렉터리에서 찾은 Skill을 곧바로 신뢰하지 말고, 원본과 실행 범위를 확인하는 것이 핵심입니다.

크게 보기

×확대 이미지 닫기

Skill이 일반 프롬프트보다 나은 순간

• 반복성: 같은 업무를 주기적으로 수행해 지시를 매번 복사해야 할 때
• 일관성: 팀원이 달라도 같은 검사 순서와 결과 형식이 필요할 때
• 전문성: 프로젝트 고유의 구조·정책·실패 사례를 일반 모델 지식에 기대기 어려울 때
• 조합성: 한 업무를 여러 작은 Skill로 나누어 필요한 것만 켜고 싶을 때

OpenAI는 Codex 앱의 Skill을 도구·워크플로·팀 선호를 묶어 반복 가능한 위임을 돕는 방식으로 소개합니다. Anthropic도 Skill을 지침·스크립트·리소스가 들어 있는 폴더로 설명합니다. 공통점은 모델의 성격을 바꾸는 주문이 아니라, 실제 작업에 필요한 절차를 포장한다는 것입니다.

장점만 보고 설치하면 안 되는 이유

Skill은 권한 시스템 그 자체가 아닙니다. 에이전트가 읽는 지침이고, 선택적으로 실행하는 코드와 자료가 들어 있는 패키지입니다. 따라서 다음 문제가 생길 수 있습니다.

• 오래된 규칙이 현재 코드 구조와 충돌할 수 있습니다.
• 설명이 모호하면 Skill이 필요한 작업에서 발동하지 않거나 엉뚱한 작업에 적용될 수 있습니다.
• 번들 스크립트가 파일을 수정하거나 네트워크에 접속할 수 있습니다.
• 출처가 불분명한 Skill이 비밀정보를 외부로 보내거나 위험한 명령을 유도할 수 있습니다.

Anthropic은 신뢰할 수 있는 출처에서 Skill을 설치하고, 덜 신뢰하는 출처라면 파일·의존성·스크립트·외부 네트워크 지시를 먼저 감사하라고 권고합니다. allowed-tools 같은 설정이 있는 경우에도 제품마다 지원 범위가 다르므로 보안 경계를 대신한다고 가정하지 않는 편이 안전합니다.

Skill을 도입할지 판단하는 질문

• 같은 절차를 한 달에 여러 번 반복하는가? 그렇다면 프롬프트보다 파일 기반 패키지가 유지보수에 유리합니다.
• 외부 시스템의 최신 데이터가 필요한가? 그렇다면 Skill만으로 해결하려 하지 말고 MCP나 공식 API를 별도로 검토합니다.
• 실패를 자동으로 감지할 수 있는가? 성공 조건과 검사 명령이 없다면 Skill을 만들기 전에 작업 절차를 먼저 정리합니다.
• 실행 권한이 넓은가? 파일 삭제·네트워크·배포가 포함되면 읽기 전용 단계와 사람 승인 단계를 분리합니다.

이 질문은 Skill을 많이 설치하기보다, 실제로 반복되는 작업에만 작은 패키지를 남길 수 있게 합니다.

운영할 때 지키면 좋은 네 가지

1. 한 Skill은 한 결과에 집중합니다. 거대한 만능 지침은 필요한 맥락을 찾기 어렵게 만듭니다.
2. 규칙과 검증을 함께 적습니다. “이렇게 하라”뿐 아니라 “무엇으로 확인할지”가 있어야 합니다.
3. 코드와 함께 버전 관리합니다. 폴더 구조와 명령이 바뀌면 Skill도 리뷰 대상입니다.
4. 작은 샘플로 먼저 평가합니다. 정상 입력, 경계 입력, 실패 입력을 넣고 의도대로 멈추는지 확인합니다.

Skill을 잘 만들었다는 말은 본문이 길다는 뜻이 아닙니다. 에이전트가 언제 이 작업을 선택하고, 어떤 정보만 읽고, 어느 순간 사람에게 멈춰 서는지가 분명하다는 뜻입니다.

Skill을 고친 뒤에는 같은 입력을 다시 돌린다

Skill은 한 번 작성하고 끝내는 문서가 아닙니다. 규칙을 추가했을 때 정상 작업만 좋아졌는지, 원래 멈춰야 할 위험한 요청까지 통과하게 된 것은 아닌지 확인해야 합니다. 가장 간단한 방법은 대표 입력 세 개를 정해 변경 전후 결과를 같은 형식으로 비교하는 것입니다.

설명을 한 줄 고칠 때도 이 세 입력을 다시 보면 Skill이 점점 길어지기만 하는 일을 막을 수 있습니다. 필요 없는 규칙은 지우고, 반복해서 실패하는 조건만 구체화하는 편이 유지보수에 유리합니다.

최소 회귀 기록

변경 전후를 비교할 때는 “잘 됐다”는 인상 대신 다음 네 가지를 남기세요.

1. 요청 입력과 사용한 Skill 버전
2. 읽은 참고 문서와 실행한 스크립트
3. 생성·수정된 파일과 검증 명령의 결과
4. 차단했어야 하지만 통과한 위험 입력, 또는 예상과 달리 멈춘 정상 입력

이 기록이 쌓이면 description을 고칠지, 본문 순서를 바꿀지, 스크립트의 오류를 수정할지 구분할 수 있습니다.

좋은 Skill은 절차와 권한을 함께 남긴다

한 번성 작업에서는 직접 프롬프트가 가장 빠를 수 있습니다. 같은 개발 절차를 반복한다면 Skill은 설명·스크립트·참고 자료를 파일로 옮겨 재사용하고, 팀의 작업 기준을 대화 밖에서도 유지하게 해 줍니다.

외부 저장소·이슈·문서·API에 접근하는 경로는 하나가 아닙니다. 호스트가 이미 허용한 CLI나 SDK·HTTP 도구를 Skill의 절차에서 사용할 수도 있고, MCP 연결 가이드처럼 표준 연결을 구성할 수도 있습니다. 세 가지 확장 방식 비교편에서 반복 절차와 연결 수단을 나눠 판단하세요. 핵심은 Skill이 권한을 부여한다고 가정하지 않고, 입력·허용 도구·승인·중단 조건을 같은 작업 계약에 남기는 것입니다.