Agent Skill 만들기: SKILL.md 작성 가이드

이전 글에서 Agent Skills가 무엇인지, 왜 필요한지 살펴보았습니다. 컨텍스트 파일이 “프로젝트 소개서”라면, Skills는 “업무 매뉴얼”이라고 했죠. 이번 글에서는 한 걸음 더 나아가 직접 Skill을 설계하고 SKILL.md로 작성하는 방법을 알아보겠습니다. 🛠️

좋은 Skill의 조건

Skill을 만들기 전에 어떤 Skill이 잘 동작하는지 생각해 볼 필요가 있습니다.

가장 중요한 건 범위가 명확해야 한다는 점입니다. “웹 개발하기” 같은 광범위한 Skill보다는 “Next.js API 라우트 작성하기”처럼 구체적인 작업에 집중하는 것이 좋습니다. AI가 언제 이 Skill을 활성화해야 하는지 명확해야 하거든요. “코드 작성”이라는 Skill은 사실상 모든 작업에 해당하니까 활성화 기준이 모호해집니다. 반면 “Prisma 스키마에서 마이그레이션 생성하기”처럼 좁히면 AI가 정확히 언제 꺼내 써야 하는지 판단할 수 있죠.

실행 가능한 지침을 담고 있어야 한다는 점도 빼놓을 수 없습니다. 추상적인 조언보다는 구체적인 단계와 예제를 제공해야 해요. “테스트를 잘 작성하세요” 대신 “이런 패턴으로 테스트를 작성하세요”가 훨씬 낫죠. AI에게 “좋은 코드를 작성해”라고 말하는 것과 “함수당 20줄 이내로, 파라미터는 3개 이하로”라고 말하는 것의 차이를 생각해 보면 됩니다.

적절한 크기를 유지하는 것도 신경 써야 합니다. SKILL.md는 5,000토큰 이하로 유지하는 것이 권장되는데요. 너무 길면 AI가 핵심을 놓칠 수 있고, 너무 짧으면 충분한 맥락을 제공하지 못합니다. 이전 글에서 살펴본 Progressive Disclosure 방식을 떠올려 보면, Activation 단계에서 전체 SKILL.md가 컨텍스트에 로드되기 때문에 크기 제한이 중요합니다.

Skill의 목적 정의하기

SKILL.md를 바로 작성하기 전에 이 Skill이 해결하려는 문제를 명확히 정의하는 단계가 필요합니다. 이 단계를 건너뛰면 작성 도중에 범위가 흐려지기 쉽거든요.

예를 들어 “데이터베이스 마이그레이션 Skill”을 만든다고 해보겠습니다. 목적은 “데이터베이스 스키마 변경을 안전하게 수행”하는 것이고, 백엔드 개발 작업에서 주로 사용될 것입니다. 해결하려는 핵심 문제는 마이그레이션 작성 시 롤백 누락, 테이블 잠금 이슈, 데이터 손실 같은 실수를 방지하는 것이죠.

이렇게 목적을 미리 정리해두면 SKILL.md를 작성할 때 “이 내용이 목적에 부합하는가?”를 기준으로 취사선택할 수 있습니다. Skill의 범위가 넓어질수록 각 지침의 구체성이 떨어지기 마련이니까요.

SKILL.md의 기본 구조

SKILL.md는 Skill의 핵심 파일입니다. YAML frontmatter와 마크다운 본문으로 구성되는데, 기본적인 뼈대를 먼저 살펴보겠습니다.

---
description: PostgreSQL 데이터베이스 마이그레이션 작성 가이드
---

# 데이터베이스 마이그레이션

PostgreSQL 데이터베이스 스키마를 변경하는 마이그레이션 스크립트를 작성합니다.

## 언제 사용하나요?

- 테이블 생성, 수정, 삭제
- 컬럼 추가, 변경, 제거
- 인덱스 추가 또는 제거

## 파일 명명 규칙

마이그레이션 파일은 `migrations/` 디렉토리에 저장하며,
`YYYYMMDD_HHMMSS_description.sql` 형식으로 작성합니다.

예: `20260123_143000_add_email_verified_column.sql`

## 필수 규칙

1. 모든 마이그레이션은 롤백(down) 스크립트를 함께 작성합니다
2. ALTER TABLE 작업 시 테이블 잠금 시간을 최소화합니다
3. 인덱스 생성은 CONCURRENTLY 옵션을 사용합니다
4. 대량 데이터 변경은 배치 처리로 나눕니다

## 주의사항

- NOT NULL 컬럼 추가 시 DEFAULT 값을 먼저 설정합니다
- 대용량 테이블의 컬럼 타입 변경은 새 컬럼 생성 후 데이터 이전을 권장합니다
- 프로덕션 적용 전 스테이징에서 반드시 테스트합니다

여기서 주목할 부분은 구조입니다. 제목(H1)으로 Skill의 이름을 선언하고, “언제 사용하나요?” 섹션으로 활성화 조건을 명시한 뒤, 구체적인 규칙과 주의사항을 나열하는 흐름이죠. 이 패턴은 대부분의 Skill에 적용할 수 있는 범용적인 구조입니다.

효과적인 description 작성법

frontmatter의 description은 Skill에서 가장 중요한 한 줄입니다. AI가 어떤 Skill을 활성화할지 결정할 때 이 설명을 참조하기 때문이죠. Discovery 단계에서 AI는 각 Skill의 이름과 description만 읽고 현재 작업에 적합한 Skill을 골라내야 하므로, 100토큰 이내로 간결하면서도 명확하게 작성해야 합니다.

좋은 description을 작성하려면 몇 가지를 기억하면 됩니다.

먼저 행동 지향적으로 써야 합니다. “마이그레이션에 대한 정보”보다 “마이그레이션 스크립트 작성 가이드”가 더 명확하죠. AI 입장에서 “이 Skill을 활성화하면 무엇을 할 수 있는가?”가 바로 드러나야 하니까요.

구체적인 기술 스택을 명시하는 것도 중요합니다. “데이터베이스 가이드”보다 “PostgreSQL 데이터베이스 마이그레이션”이 언제 이 Skill을 사용해야 하는지 훨씬 잘 알려줍니다. 사용자가 “PostgreSQL 마이그레이션 작성해줘”라고 요청했을 때 description에 “PostgreSQL”이 없으면 매칭이 어려워질 수 있거든요.

트리거 키워드를 포함하는 것도 잊지 마세요. 사용자가 요청할 때 흔히 사용할 단어들을 넣어두면 AI가 매칭하기 쉽습니다.

# 좋은 예
description: React Testing Library를 사용한 컴포넌트 테스트 작성 가이드

# 아쉬운 예
description: 테스트 관련 규칙

좋은 예를 보면 “React Testing Library”, “컴포넌트”, “테스트”, “작성”이라는 키워드가 모두 들어있어서 관련 요청에 매칭될 확률이 높습니다. 아쉬운 예는 너무 모호해서 어떤 테스트인지, 어떤 프레임워크인지 알 수 없죠.

본문 작성 패턴

description 다음으로 중요한 것은 본문의 지침 작성 방식입니다. 같은 내용이라도 어떻게 쓰느냐에 따라 AI가 따르는 정확도가 달라집니다.

가장 잘 먹히는 방식은 규칙을 명령문으로 작성하는 것입니다. “~하면 좋습니다”보다 “~합니다”가 더 명확하죠. AI는 제안보다 지시를 더 잘 따르거든요.

# 모호한 표현
에러 핸들링을 잘 하면 좋을 것 같습니다.
가능하면 타입을 명시하는 것이 좋겠습니다.

# 명확한 지시
모든 async 함수는 try-catch로 에러를 처리합니다.
함수 파라미터와 반환값에 TypeScript 타입을 명시합니다.

또 하나 중요한 패턴은 “하지 마세요” 규칙입니다. 어떤 행동을 해야 하는지뿐 아니라 어떤 행동을 하면 안 되는지를 함께 명시하면 AI가 흔한 실수를 피할 수 있어요. “any 타입을 사용하지 않습니다”, “console.log를 프로덕션 코드에 남기지 않습니다” 같은 금지 규칙이 예시입니다.

예제를 제공할 때는 “좋은 예”와 “나쁜 예”를 함께 보여주는 것도 잘 먹힙니다. AI는 대비를 통해 의도를 더 정확하게 파악할 수 있거든요.

## 네이밍 규칙

컴포넌트 파일명은 PascalCase를 사용합니다.

좋은 예: `UserProfile.tsx`, `SearchDialog.tsx`
나쁜 예: `userProfile.tsx`, `search-dialog.tsx`

예제와 스크립트 추가하기

SKILL.md만으로 충분한 경우도 있지만, 복잡한 Skill은 예제 파일과 헬퍼 스크립트를 함께 제공하면 훨씬 잘 동작합니다.

.agents/skills/react-testing/
├── SKILL.md
├── examples/
│   ├── component-test.md
│   ├── hook-test.md
│   └── async-test.md
└── scripts/
    └── generate-test-template.sh

예제 파일은 SKILL.md에서 참조할 수 있습니다:

## 예제

더 자세한 예제는 `examples/` 디렉토리를 참고하세요:

- `component-test.md` - 기본 컴포넌트 테스트
- `hook-test.md` - 커스텀 훅 테스트
- `async-test.md` - 비동기 동작 테스트

스크립트는 반복적인 작업을 자동화하는 데 유용합니다. 예를 들어 테스트 파일의 기본 구조를 생성하는 스크립트를 제공하면 AI가 이를 활용해 일관된 코드를 만들 수 있습니다.

여기서 한 가지 팁이 있는데요. 예제 파일을 작성할 때 단순히 완성된 코드만 보여주는 것보다, 왜 이렇게 작성했는지 주석으로 설명을 달아두면 AI가 패턴의 의도까지 이해할 수 있습니다. “이 부분은 컴포넌트가 언마운트된 후의 상태 업데이트를 방지하기 위한 것”처럼요.

실전 예제: 블로그 포스트 작성 Skill

이제 실제로 활용할 수 있는 Skill을 처음부터 끝까지 만들어 보겠습니다. 이전 글에서 코드 리뷰 Skill을 간단히 소개했었는데, 이번에는 좀 더 다른 예제로 “블로그 포스트 작성 Skill”을 만들어 보죠. 실제로 이 블로그에서 사용하고 있는 Skill이기도 합니다.

---
description: Astro 기반 엔지니어링 블로그의 한글 포스트 작성 가이드
---

# 블로그 포스트 작성

일관된 스타일과 구조를 따르는 한글 엔지니어링 블로그 포스트를 작성합니다.

## 파일명과 Front Matter

파일명은 소문자와 하이픈을 사용합니다 (예: `react-hooks-use-ref.md`).

모든 포스트는 YAML front matter로 시작합니다:
- title: 한글로 작성
- tags: 관련 기술/개념 키워드 3-5개
- date: YYYY-MM-DD 형식
- description: 한글 100-120자 SEO 설명

## 작성 스타일

한글 대화체("~인데요", "~까요?")로 작성합니다.
독자에게 직접 말을 거는 방식으로 친근한 톤을 유지합니다.

## 코드 블록

항상 언어를 지정합니다: js, py, rust, css, html, bash 등
타이틀이 필요하면 `언어 title="제목"` 형식을 사용합니다.

## 구조

1. 도입부 - 독자가 공감할 수 있는 맥락 제시
2. 본문 - H2 헤딩으로 섹션 구분, 기본에서 고급으로 진행
3. 마치며 - 핵심 요약과 다음 단계 제안

이 Skill에는 앞에서 살펴본 좋은 Skill의 조건이 반영되어 있습니다. description에 “Astro”, “엔지니어링 블로그”, “한글 포스트”라는 구체적인 키워드가 있어서 AI가 블로그 글 작성 요청을 받았을 때 정확히 이 Skill을 활성화할 수 있죠. 본문의 지침도 “~합니다”라는 명령문으로 작성되어 있고, 파일 명명 규칙부터 구조까지 바로 실행에 옮길 수 있는 구체적인 내용을 담고 있습니다.

Skill 테스트하기

Skill을 작성한 후에는 실제로 잘 동작하는지 테스트해 봐야 합니다.

제일 먼저 볼 것은 Skill이 올바르게 활성화되는지입니다. 관련 작업을 요청했을 때 AI가 이 Skill을 찾아서 사용하는지 봐야 해요. 만약 활성화되지 않는다면 description을 더 명확하게 수정해야 할 수 있습니다. 이때 흔한 함정이 있는데, description이 너무 일반적이면 엉뚱한 작업에서도 활성화되고, 너무 구체적이면 정작 필요할 때 활성화되지 않는 문제가 생기거든요. 적절한 균형점을 찾는 것이 중요합니다.

지침이 명확한지도 살펴봐야 합니다. AI가 Skill의 지침을 따라 올바른 결과물을 만들어내는지 확인하세요. 예상과 다른 결과가 나온다면 지침을 더 구체적으로 작성해야 합니다. 예를 들어 “적절한 에러 처리를 추가합니다”라는 지침이 있는데 AI가 모든 함수에 try-catch를 감싸버린다면, “외부 API 호출과 파일 I/O에만 try-catch를 적용합니다”처럼 범위를 좁혀야 합니다.

예제가 실제로 도움이 되는지도 확인해 보세요. AI가 생성한 코드가 예제의 패턴을 따르고 있나요? 예제가 너무 복잡하거나 특수한 경우만 다루고 있다면 일반적인 케이스를 추가하는 것이 좋습니다.

테스트 과정에서 발견한 문제는 바로 SKILL.md에 반영하는 것이 좋습니다. Skill은 한 번 쓰고 끝나는 것이 아니라 지속적으로 다듬어 나가야 하거든요.

Skill 관리 팁

Skill이 늘어나면 관리도 중요해집니다.

Skills는 .agents/skills/ 디렉토리에 저장되므로 Git으로 버전 관리할 수 있습니다. 팀원들과 공유하고, 변경 이력을 추적할 수 있죠. PR을 통해 Skill 변경사항을 리뷰하는 것도 좋은 방법입니다. 코드 컨벤션을 PR로 리뷰하듯이, Skill의 지침도 팀원들의 검토를 거치면 품질이 올라갑니다.

프로젝트가 발전하면 Skill도 업데이트해야 합니다. 라이브러리 버전이 올라가거나 팀의 컨벤션이 바뀌면 관련 Skill도 함께 수정해야 하는데, 이걸 깜빡하면 AI가 낡은 패턴으로 코드를 생성하게 됩니다. 분기마다 한 번씩 Skill들을 검토하고 최신 상태로 유지하면 좋습니다.

팀원들의 피드백도 귀중한 개선 소스입니다. “이 Skill을 적용했는데 AI가 이상한 코드를 만들었어요”라는 피드백은 지침이 모호하다는 신호죠. 반대로 “이 Skill 덕분에 작업이 빨라졌어요”라는 피드백에서는 어떤 지침이 특히 잘 먹혔는지 파악할 수 있습니다.

Skill 생성 도구 활용하기

Skill을 처음부터 직접 작성할 수도 있지만, 도구를 활용하면 더 빠르게 시작할 수 있어요.

가장 간단한 방법은 npx skills init 명령어입니다. 기본 폴더 구조와 SKILL.md 템플릿을 생성해 줍니다.

npx skills init my-skill

이 명령어를 실행하면 my-skill 디렉토리가 생성되고 그 안에 기본 SKILL.md 템플릿이 만들어집니다. 이름을 생략하면 현재 디렉토리에 템플릿이 생성됩니다. 기본 구조만 빠르게 잡고 싶을 때 유용하죠.

AI의 도움을 받고 싶다면 Anthropic에서 만든 skill-creator 스킬을 활용할 수 있습니다. 이름 그대로 “Skill을 만드는 Skill”인데요, AI에게 스킬 생성 자체를 위임할 수 있습니다:

npx skills add anthropics/skills --skill skill-creator

skill-creator를 설치하면 AI가 체계적인 과정을 따라 Skill을 생성합니다. 먼저 Skill의 사용 예시를 수집하고 이해한 뒤, 필요한 스크립트와 리소스를 계획합니다. 그다음 SKILL.md와 리소스 파일들을 작성하고, 실제 사용을 통해 반복 개선합니다.

AI에게 “PDF 편집 Skill을 만들어줘”라고 요청하면, skill-creator가 활성화되어 어떤 기능이 필요한지 질문하고, 예제를 분석해서 적절한 스크립트와 SKILL.md를 생성해 줍니다.

Skill 공유하기

만든 Skill을 팀 내에서만 사용할 수도 있지만, 더 많은 사람들과 공유하고 싶다면 skills.sh에 배포할 수 있습니다. skills.sh는 “AI 에이전트를 위한 npm”이라고 불리는 Skills 디렉토리로, 누구나 자신의 Skill을 등록하고 공유할 수 있습니다.

배포 방법은 간단합니다. Skill을 GitHub 저장소에 올리면 됩니다. 저장소의 루트 또는 적절한 디렉토리에 SKILL.md 파일을 포함시키고, 필요한 경우 scripts/, examples/, assets/ 같은 서브 디렉토리를 함께 구성합니다.

my-skill/
├── SKILL.md
├── scripts/
│   └── helper.sh
└── examples/
    └── basic-usage.md

저장소가 준비되면 다른 사람들이 다음 명령어로 Skill을 설치할 수 있습니다:

npx skills add 사용자(또는 조직명)/저장소

이 명령어를 실행하면 Skill이 로컬 프로젝트의 .agents/skills/ 디렉토리에 설치됩니다.

skills.sh의 재미있는 점은 리더보드 시스템입니다. Skill이 설치될 때마다 익명 텔레메트리 데이터가 수집되어 인기 순위에 반영됩니다. 많은 개발자가 사용하는 유용한 Skill을 만들면 리더보드 상위에 노출될 수 있죠. Stripe, Anthropic, Expo 같은 기업들도 공식 Skills를 배포하고 있으니, 한번 도전해 보는 것도 좋겠습니다.

텔레메트리를 원하지 않는 경우 SKILLS_NO_TELEMETRY=1 환경 변수를 설정하면 됩니다.

마치며

Skill을 만드는 것은 결국 “나만의 AI 전문가”를 훈련시키는 과정입니다. 처음에는 간단한 Skill부터 시작해서, 팀의 노하우가 쌓일수록 더 정교한 Skill로 발전시켜 나가면 됩니다.

좋은 Skill은 처음부터 완벽하게 만들어지지 않습니다. 실제로 사용해보고, 부족한 점을 발견하고, 조금씩 개선해 나가는 것이 중요합니다. 오늘 당장 반복적으로 설명하던 작업 하나를 Skill로 만들어 보는 건 어떨까요? 🚀

Agent Skills에 대한 기본 개념이 궁금하다면 Agent Skills: AI를 위한 업무 매뉴얼을 참고하고, 커뮤니티에서 공유되는 Skill을 찾아보고 싶다면 skills.sh: 공개 에이전트 스킬 생태계도 살펴보세요.