좋은 Skill의 해부학: SKILL.md부터 폴더 구조까지

좋은 Skill은 번뜩이는 아이디어에서 시작하지 않습니다. 의외로 더 먼저 오는 것은 정리정돈입니다. 에이전트는 감동적인 철학보다, 어디에 무엇이 있는지 분명한 구조를 더 잘 따라갑니다.

사람도 처음 가는 부엌에서 칼은 서랍에, 접시는 찬장에, 레시피는 냉장고 문에 붙어 있으면 훨씬 덜 헤맵니다. Skill도 똑같습니다. SKILL.md는 정문이고, scripts/, references/, assets/는 각각 다른 역할을 맡는 방입니다. 좋은 Skill은 "똑똑한 글"이 아니라 "헷갈리지 않는 집"에 가깝습니다.

Skill은 폴더 하나로 시작된다

Agent Skills의 기본 단위는 폴더입니다. 그리고 그 안에는 최소한 SKILL.md가 있어야 합니다. 여기에 필요하면 실행 코드, 참고 문서, 템플릿 같은 파일을 곁들입니다.¹²

가장 기본적인 모양은 이렇습니다.

my-skill/
├── SKILL.md
├── scripts/
├── references/
└── assets/

여기서 중요한 점은 단순합니다. 파일이 많다고 좋은 Skill이 되는 것은 아니고, 역할이 분리되어 있어야 좋은 Skill이 됩니다.

SKILL.md는 에이전트가 따라야 할 핵심 지침을 담습니다. scripts/는 실제로 실행할 수 있는 코드가 들어가는 곳입니다. references/는 필요할 때 읽을 참고 문서 창고이고, assets/는 템플릿이나 정적 자료를 두는 곳입니다.¹²

좋은 Skill을 한 문장으로 정의하면 이렇습니다.

핵심은 앞에, 자세한 것은 옆방에, 실행은 따로.

SKILL.md는 Skill의 얼굴이자 브레인이다

SKILL.md는 두 부분으로 이루어집니다. 맨 위에는 YAML frontmatter가 있고, 그 아래에는 Markdown 본문이 이어집니다.¹

구조만 보면 아주 소박합니다.

---
name: my-skill
description: What this skill does and when to use it
---

# Skill Instructions

여기에 본문 지침이 들어간다.

이 단순한 구조가 중요한 이유는 분명합니다. 에이전트는 처음부터 긴 본문을 읽는 것이 아니라, 먼저 frontmatter에 적힌 정보를 보고 "이 Skill이 지금 필요한가?"를 판단하기 때문입니다. 그래서 SKILL.md는 단순한 문서가 아니라, 발견을 위한 표지판이면서 실행을 위한 절차서입니다.

YAML frontmatter: 짧지만 결정적인 머리말

YAML frontmatter에는 Skill의 핵심 메타데이터가 들어갑니다. 표준 스펙에서 중심이 되는 필드는 name과 description이고, 필요에 따라 license, compatibility, metadata, allowed-tools를 추가할 수 있습니다.¹²

아래 예시를 먼저 보겠습니다.

---
name: expense-report
description: File and validate employee expense reports according to company policy. Use when asked about expense submissions, reimbursement rules, receipts, or spending limits.
license: Apache-2.0
compatibility: Requires python3
metadata:
  author: finance-team
  version: "1.0"
allowed-tools: Read Bash
---

이제 각 필드를 쉽게 뜯어보겠습니다.

겉보기에는 단순하지만, 여기서 특히 초보자가 자주 실수하는 것은 name과 description입니다.

name은 멋보다 규칙이다

name은 예쁜 제목이 아니라 엄격한 식별자입니다. 보통 1~64자 사이여야 하고, 소문자·숫자·하이픈만 허용됩니다. 하이픈으로 시작하거나 끝나면 안 되고, 연속 하이픈도 피해야 하며, 보통 부모 디렉터리 이름과 정확히 맞아야 합니다.¹²³

예를 들면 이런 식입니다.

이 규칙이 귀찮아 보여도, 사실은 에이전트와 도구가 Skill을 안정적으로 찾게 하려는 안전장치입니다. 폴더 이름은 meeting-summary인데 frontmatter에는 meeting_notes라고 써 두면, 사람은 "대충 알겠지"라고 생각하지만 시스템은 그렇지 않습니다.

description은 소개문이 아니라 호출문이다

description은 많은 초보자가 가장 가볍게 쓰는 부분이지만, 실제로는 가장 무겁게 일하는 부분입니다. 이 문장이 Skill을 불러올지 말지를 좌우하기 때문입니다.¹²

좋은 description은 보통 세 가지를 담습니다.

• 이 Skill이 무엇을 하는지

• 언제 써야 하는지

• 에이전트가 작업을 연결할 수 있는 구체적인 키워드

예를 들어 이런 설명은 너무 약합니다.

description: Helps with documents.

문서와 관련된 무엇을 도와주는지, 언제 써야 하는지 알 수 없습니다. 반면 이런 설명은 훨씬 낫습니다.

description: Extracts text from PDF files and summarizes important sections. Use when the user asks to read PDFs, pull text from reports, or inspect multi-page documents.

이 설명은 "무엇을 하나"와 "언제 쓰나"가 함께 들어 있습니다. 에이전트 입장에서는 안개 속 표지판이 아니라, 화살표가 달린 표지판입니다.

실무에서는 한 걸음 더 나아가 "이럴 때는 쓰지 말라"는 힌트를 덧붙이기도 좋습니다. 예를 들어 React 전용 Skill이라면 Vue나 Svelte 작업에는 맞지 않는다고 밝혀 둘 수 있습니다. 이런 식의 경계선은 과한 오작동을 줄여 줍니다.⁵

선택 필드는 장식이 아니라 맥락이다

license는 배포나 공유 관점에서 중요합니다. 팀 안에서만 쓰는 Skill이든 공개 Skill이든, 사용 조건이 분명하면 나중에 덜 곤란해집니다.¹

compatibility는 환경 요구사항을 적는 자리입니다. 예를 들어 Python 3가 필요하다든지, 특정 패키지가 깔려 있어야 한다든지, 네트워크 접근이 필요하다는 점을 적을 수 있습니다.¹²

metadata는 자유도가 높습니다. 작성자, 버전, 카테고리 같은 정보를 넣을 수 있습니다.¹²

allowed-tools는 미리 허용된 도구를 적는 필드인데, 구현체마다 지원 여부가 다를 수 있는 실험적 성격이 있습니다.¹²

참고로 일부 제품은 표준 필드 외에 argument-hint, user-invocable, disable-model-invocation 같은 추가 frontmatter를 지원하기도 합니다. 다만 이런 항목은 공통 표준이라기보다 제품별 확장 기능에 가깝습니다.⁴

본문은 설명문이 아니라 절차서다

frontmatter 아래의 Markdown 본문은 형식이 꽤 자유롭습니다. 하지만 자유롭다고 해서 아무렇게나 써도 된다는 뜻은 아닙니다. 좋은 본문은 대개 에이전트가 바로 행동으로 옮길 수 있게 씁니다.¹³

권장되는 구성은 대체로 비슷합니다.

• 언제 이 Skill을 써야 하는지

• 어떤 순서로 진행해야 하는지

• 입력과 출력의 예시가 무엇인지

• 자주 만나는 예외 상황이 무엇인지

예를 들면 이런 뼈대를 생각하면 쉽습니다.

# PDF Processing

## When to use this skill
- PDF에서 텍스트를 뽑아야 할 때
- 여러 페이지 문서를 읽어야 할 때

## Instructions
1. 파일 경로를 확인한다.
2. `scripts/extract_text.py`를 실행한다.
3. 결과를 요약 형식으로 정리한다.

## Examples
입력: "이 PDF에서 핵심 내용만 뽑아줘"
출력: 문단별 요약

## Edge Cases
- 암호화된 PDF면 비밀번호를 요청한다.
- 스캔본이면 OCR 필요성을 알린다.

중요한 포인트는 두 가지입니다. 첫째, 행동이 보이는 문장으로 써야 합니다. 둘째, 핵심 절차는 위에, 세부 규칙은 바깥 파일로 빼야 합니다.

표준 가이드들은 SKILL.md가 너무 길어지지 않게 관리하라고 권합니다. 보통 500줄 이하를 권장하고, 자세한 자료는 다른 파일로 분리하는 편이 좋습니다.¹²

이유는 간단합니다. 본문이 지나치게 길면 에이전트는 필요한 핵심 단계를 놓치기 쉽습니다. 5쪽짜리 비상 매뉴얼은 쓸모가 있지만, 500쪽짜리 비상 매뉴얼은 비상시에 오히려 사람을 얼어붙게 만듭니다.

scripts, references, assets는 어떻게 나눌까

많은 초보자가 여기서 가장 오래 헤맵니다. "이 파일은 어디에 두지?"라는 질문입니다. 아주 간단하게 나누면 됩니다.

읽을 문서면 references/, 실행할 코드면 scripts/, 복사하거나 채워 넣을 재료면 assets/입니다.

아래 표로 보면 감이 빨리 옵니다.

scripts/: 반복 작업은 말보다 코드가 낫다

scripts/에는 에이전트가 실행할 수 있는 코드를 둡니다. Python, Bash, JavaScript 같은 스크립트가 대표적입니다.¹

이 폴더에 어울리는 작업은 이런 것들입니다.

• 형식 검증

• 복잡한 파싱

• 반복적인 변환

• 사람이 손으로 하면 실수하기 쉬운 처리

좋은 스크립트는 세 가지 특징이 있습니다. 작고, 자기완결적이고, 에러 메시지가 친절합니다.¹⁵

여기서 특히 중요한 점은, 스크립트가 거대한 라이브러리 역할을 하게 만들지 않는 것입니다. Skill의 scripts/는 작은 도우미여야지, 따로 프레임워크를 세운 듯한 거대한 세계가 되면 관리가 어려워집니다.⁵

references/: 설명은 여기로 보내라

references/는 추가 문서를 두는 곳입니다. 규정집, 스타일 가이드, 상세한 API 설명, FAQ, 분류 규칙 같은 것이 잘 어울립니다.¹⁶

좋은 reference 파일은 주제가 선명합니다. 예를 들어 아래처럼 나누면 읽기 쉽습니다.

references/
├── faq.md
├── policy-rules.md
└── output-format.md

반대로 everything-you-might-ever-need.md 같은 파일 하나에 다 쓸어 담으면, 에이전트는 결국 큰 종이 뭉치를 들고 필요한 문장을 찾느라 헤매게 됩니다.

문서가 길어질수록 잘게 나누는 것이 좋고, 100줄이 넘는 문서는 위쪽에 간단한 목차를 붙여 두면 도움이 됩니다.⁶

assets/: 읽기보다 활용하는 재료

assets/는 템플릿, 샘플 파일, 이미지, 스키마, 룩업 테이블 같은 정적 자원을 두는 곳입니다.¹⁶

예를 들어 이런 파일이 잘 어울립니다.

assets/
├── report-template.md
├── output-schema.json
└── diagram.png

여기서 핵심은 assets/가 "설명서 보관함"이 아니라 "재료 창고"라는 점입니다. 에이전트가 문서 규칙을 읽어야 한다면 references/가 더 어울리고, 그대로 가져다 쓰거나 구조를 따라야 하는 것이라면 assets/가 더 어울립니다.

쉽게 말해, references/는 읽는 책장이고 assets/는 꺼내 쓰는 서랍입니다.

파일 배치의 원칙: 찾기 쉬워야 하고, 덜 읽혀야 한다

좋은 Skill 폴더는 단순히 예쁘게 정리된 폴더가 아닙니다. 에이전트가 최소한만 읽고도 정확히 움직이게 만드는 구조여야 합니다. 그 원칙을 차례대로 보겠습니다.

1. SKILL.md에는 핵심 절차만 둡니다. 긴 규칙, 사례 모음, 표, 템플릿은 바깥 파일로 뺍니다.¹²

2. 파일 참조는 상대 경로로 씁니다. 예를 들어 references/REFERENCE.md, scripts/extract.py처럼 적습니다.¹

3. 너무 깊은 중첩은 피합니다. references/api/errors/http/v2/final.md처럼 깊게 들어가면 사람이든 에이전트든 길을 잃기 쉽습니다. 한 단계 깊이의 단순한 구조가 보통 더 낫습니다.¹⁵

4. 파일 이름은 역할이 드러나게 짓습니다. guide.md보다 output-format.md가 낫고, stuff.py보다 validate_receipt.py가 낫습니다.

5. 운영체제 경로 습관을 끌고 오지 말고, Skill 안에서는 일관된 상대 경로를 사용합니다. 특히 문서 안에서는 보통 슬래시(/) 기반 경로가 더 안정적입니다.¹⁵

6. 사람이 읽기 위한 부록을 잔뜩 넣지 않습니다. Skill은 에이전트를 위한 구조물입니다. README.md, CHANGELOG.md, 설치 안내서 같은 파일이 꼭 필요한 경우가 아니라면 Skill 안을 어지럽힐 수 있습니다.⁵

이 여섯 가지를 한마디로 줄이면 이렇습니다.

앞문은 짧게, 옆문은 분리해서, 길 찾기는 단순하게.

예제로 한 번 해부해 보자

가상의 Skill 하나를 만들어 보겠습니다. 이름은 meeting-summary라고 하겠습니다.

meeting-summary/
├── SKILL.md
├── scripts/
│   └── clean_transcript.py
├── references/
│   ├── summary-rules.md
│   └── tone-guide.md
└── assets/
    └── summary-template.md

이 구조를 보면 각 파일의 역할이 분명합니다.

SKILL.md에는 "언제 이 Skill을 쓸지", "먼저 무엇을 확인할지", "회의록을 어떤 순서로 정리할지"가 적혀 있습니다. scripts/clean_transcript.py는 잡음이 많은 전사본을 정리합니다. references/summary-rules.md는 어떤 내용을 요약에 반드시 넣어야 하는지 알려 줍니다. references/tone-guide.md는 문체 규칙을 설명합니다. assets/summary-template.md는 최종 결과의 골격이 됩니다.

이제 사용자가 "1시간짜리 회의 녹취를 깔끔한 결정사항 중심으로 정리해 줘"라고 요청했다고 해봅시다.

에이전트는 먼저 description을 보고 이 Skill이 맞는지 판단합니다. 맞다고 생각하면 SKILL.md를 읽습니다. 전사본이 지저분하면 scripts/clean_transcript.py를 실행할 수 있습니다. 결과를 어떤 형식으로 써야 할지 애매하면 references/summary-rules.md를 읽습니다. 마지막 출력은 assets/summary-template.md의 틀을 따라갑니다.

여기서 좋은 구조의 장점이 드러납니다. 하나의 큰 문서에 다 때려 넣지 않아도, 필요한 것만 찾아 쓸 수 있습니다. 마치 요리할 때 레시피, 계량스푼, 재료를 한 냄비에 넣어 끓이지 않는 것과 같습니다.

초보자가 자주 만드는 구조 실수

좋은 Skill은 대개 화려하지 않습니다. 대신 실수가 적습니다. 반대로 잘 안 되는 Skill은 묘하게 비슷한 곳에서 넘어집니다.

첫 번째 실수는 폴더 이름과 name이 다르는 것입니다. 사람 눈에는 비슷해 보여도 시스템은 정확히 맞춰야 안정적으로 동작합니다.¹²

두 번째 실수는 description을 너무 뭉뚱그려 쓰는 것입니다. "문서 작업을 도와줌", "코드 품질 향상" 같은 문장은 거의 아무 말도 하지 않은 것과 비슷합니다. 무엇을, 언제, 어떤 단어와 함께 떠올려야 하는지가 보이지 않기 때문입니다.²³

세 번째 실수는 모든 것을 SKILL.md 하나에 몰아넣는 것입니다. 처음에는 편해 보여도, 곧 덩치가 커지고 핵심이 묻힙니다. SKILL.md는 대장이고, 세부 규칙은 참모에게 보내야 합니다.¹²

네 번째 실수는 references/를 거대한 창고로 만드는 것입니다. 찾아 읽을 수 있어야 reference인데, 덤프 파일처럼 쌓아 두면 결국 아무도 제대로 활용하지 못합니다.⁶

다섯 번째 실수는 폴더의 의미를 섞어 버리는 것입니다. 읽어야 할 설명서를 assets/에 두고, 템플릿을 references/에 두고, 실행 코드를 docs/ 같은 임의 폴더에 흩뿌리면 Skill이 금세 미로가 됩니다.

바로 써먹는 배치 체크리스트

새 Skill을 만들 때 아래 질문에 모두 "예"라고 답할 수 있으면 구조가 꽤 건강한 편입니다.

• 폴더 이름과 name이 정확히 같은가?

• description만 읽어도 무엇을 하고 언제 쓰는지 알 수 있는가?

• SKILL.md에는 핵심 절차만 있고, 긴 규칙은 분리되어 있는가?

• 읽는 문서, 실행 코드, 템플릿이 각각 references/, scripts/, assets/에 자연스럽게 들어가 있는가?

• 파일 경로가 짧고 일관되며, 상대 경로로 참조되고 있는가?

• 파일 이름만 봐도 역할이 드러나는가?

이 체크리스트는 단순하지만 꽤 강력합니다. Skill 설계에서 많은 문제는 거대한 이론 부족이 아니라, 기본 배치의 어수선함에서 시작되기 때문입니다.

좋은 Skill은 결국 잘 설계된 작은 시스템이다

Skill을 처음 만들 때는 자꾸 "무슨 내용을 써야 하지?"에만 시선이 갑니다. 물론 내용은 중요합니다. 하지만 내용이 구조를 이기지는 못합니다.

SKILL.md가 엉뚱한 이름을 달고 있으면 찾히지 않습니다. description이 흐리면 불리지 않습니다. 본문이 너무 길면 읽혀도 핵심이 흐려집니다. 스크립트, 참고자료, 템플릿이 뒤섞이면 필요한 순간에 필요한 파일을 집어 들기 어렵습니다.

그래서 좋은 Skill은 멋진 아이디어의 모음이 아니라, 찾히고, 읽히고, 실행되기 쉬운 작은 시스템입니다.

아주 짧게 정리하면 이렇습니다.

좋은 Skill은 SKILL.md에서 시작하고, 좋은 frontmatter로 발견되며, 분리된 폴더 구조 덕분에 가볍고 정확하게 움직입니다. Skill의 품질은 글솜씨만으로 결정되지 않습니다. 파일을 어디에 두었는지, 무엇을 앞에 두고 무엇을 옆으로 뺐는지가 결과를 크게 바꿉니다.

이제 필요한 것은 이론보다 손입니다. 다음 단계는 직접 만들어 보는 것입니다. 작은 Skill 하나를 손으로 만들어 보면, 왜 좋은 구조가 반쯤 성공인지 금방 체감하게 됩니다.

참고

¹Specification - Agent Skills

²Agent Skills | Microsoft Learn

³Writing SKILL.md | Open Agent Skills

⁴Use Agent Skills in VS Code

⁶Skill Directory Organization | https-deeplearning-ai/sc-agent-skills-files | DeepWiki