스킬2026-02-019분 읽기

스킬 크리에이터: AI에게 전문 능력을 붙이는 설계 가이드

먼저 결론

스킬은 "AI에게 더 많은 지식을 넣는 파일"이 아닙니다. 반복되는 작업을 더 안정적으로 수행하게 만드는 작업 절차 패키지입니다.

좋은 스킬은 길지 않습니다. 필요한 순간에만 읽히고, 읽히면 바로 행동을 바꾸고, 반복 작업의 실수를 줄입니다. 반대로 나쁜 스킬은 설명은 많지만 언제 써야 하는지 흐리고, 이미 모델이 아는 일반론을 길게 반복하고, 검증 기준이 없습니다.

이 글은 스킬을 만들 때 반드시 봐야 할 기준을 정리합니다.

어떤 사용자 요청에서 트리거될지 먼저 정한다.
SKILL.md에는 핵심 절차만 둔다.
긴 참고자료는 references/로 분리한다.
반복 코드는 scripts/로 만든다.
결과물이 쓰는 파일은 assets/로 둔다.
검증 기준과 실패 사례를 반드시 남긴다.

스킬의 한 문장 정의

스킬은 특정 도메인이나 작업을 위해 AI가 따라야 할 절차, 판단 기준, 도구 사용법, 참고 리소스를 묶은 독립 폴더입니다.

프롬프트와 다른 점은 재사용성입니다. 프롬프트는 한 번의 요청에 붙는 경우가 많고, 스킬은 여러 세션에서 반복해서 로드됩니다.

왜 스킬이 필요한가

AI는 일반 지식은 넓게 압니다. 하지만 내 작업 환경의 세부 규칙은 모릅니다.

이 프로젝트는 UTF-8 부트스트랩을 먼저 로드해야 한다.
문서 초안은 DB 반영 전 docs/treasure-rewrites에 만든다.
의료 글은 진단 프롬프트가 아니라 상담 준비 도구로 써야 한다.
배포 전에는 untracked 파일을 커밋에 섞지 않는다.
특정 파일 형식은 정해진 스크립트로 처리해야 한다.

이런 정보는 매번 대화로 설명하면 누락됩니다. 스킬로 만들면 AI가 특정 작업에서 같은 기준을 반복해서 적용할 수 있습니다.

공식 skill-creator 지침도 스킬을 특정 도메인의 온보딩 가이드처럼 설명합니다. 핵심은 모델이 이미 똑똑하다는 전제에서, 모델이 모르는 절차와 로컬 지식만 넣는 것입니다.

좋은 스킬과 나쁜 스킬

구분	나쁜 스킬	좋은 스킬
설명	"글을 잘 써라" 같은 일반론	어떤 글에서 어떤 절차를 따를지 명확
트리거	너무 넓거나 애매함	사용자 발화와 작업 조건이 구체적
본문	긴 강의식 설명	단계별 실행 절차
참고자료	전부 `SKILL.md`에 넣음	필요한 파일만 `references/`로 분리
자동화	매번 코드를 새로 씀	반복 작업은 `scripts/`로 제공
검증	없음	성공/실패 기준 포함

기본 구조

skill-name/
├── SKILL.md
├── agents/
│   └── openai.yaml
├── scripts/
│   └── repeatable-task.py
├── references/
│   └── domain-rules.md
└── assets/
    └── template.docx

항상 모든 폴더가 필요한 것은 아닙니다. 작은 스킬은 SKILL.md 하나로 충분합니다. 하지만 아래 조건이면 분리하는 편이 좋습니다.

설명이 길어져 SKILL.md가 무거워진다.
자주 실행하는 코드가 있다.
템플릿, 폰트, 이미지, 샘플 파일이 결과물에 필요하다.
도메인 문서가 많아 상황별로 골라 읽어야 한다.

`SKILL.md`의 핵심

SKILL.md에서 가장 중요한 것은 description입니다. AI는 이 설명을 보고 스킬 사용 여부를 판단합니다.

약한 description

description: 글쓰기 도움을 주는 스킬

너무 넓습니다. 언제 써야 하는지 알 수 없습니다.

좋은 description

description: 사용자가 블로그 글, 에세이, 칼럼, 소개글의 초안에 대해 문장 교정, 구조 개선, 피드백, 빨간펜 검토를 요청할 때 사용한다. 두괄식, 논리 비약, 표현 밀도, 감정선, 삭제 대상까지 점검하고 수정 제안을 제공한다.

좋은 description은 트리거 발화와 작업 범위를 함께 담습니다.

스킬 작성 템플릿

---
name: my-skill
description: 사용자가 {{상황}}에서 {{목표}}를 요청할 때 사용한다. {{해야 할 일}}을 수행하고, {{피해야 할 일}}을 피한다.
---

# My Skill

## 목적

이 스킬은 {{반복 작업}}을 안정적으로 처리하기 위해 사용한다.

## 사용 조건

- 사용자가 {{trigger_1}}을 요청할 때
- 입력 파일이 {{file_type}}일 때
- {{domain}} 판단 기준이 필요할 때

## 하지 말 것

- {{dont_1}}
- {{dont_2}}

## 작업 절차

1. 입력을 확인한다.
2. 필요한 참고자료만 읽는다.
3. 결과물을 만든다.
4. 검증한다.
5. 변경 내용을 요약한다.

## 검증 기준

- [ ] {{success_condition_1}}
- [ ] {{success_condition_2}}
- [ ] {{success_condition_3}}

## 참고 리소스

- 자세한 규칙은 `references/rules.md`를 읽는다.
- 반복 변환은 `scripts/convert.py`를 실행한다.

점진적 노출 설계

스킬은 컨텍스트를 아껴야 합니다. 모든 지식을 한 번에 넣으면 다른 작업 컨텍스트를 잡아먹습니다.

점진적 노출은 세 단계로 생각하면 됩니다.

단계	언제 읽히는가	넣을 내용
메타데이터	항상 후보로 노출	이름과 description
`SKILL.md` 본문	스킬이 트리거될 때	핵심 절차와 선택 기준
번들 리소스	필요할 때만	긴 문서, 스크립트, 템플릿

좋은 SKILL.md는 목차처럼 작동합니다. 모든 지식을 본문에 때려 넣지 않고, "이 경우에는 이 파일을 읽어라"라고 안내합니다.

자유도 조절

스킬은 작업의 위험도에 따라 자유도를 다르게 줘야 합니다.

높은 자유도

글쓰기, 아이디어 정리, 기획처럼 정답이 하나가 아닌 작업에 맞습니다.

독자와 목적에 맞춰 구조를 제안하되, 기존 톤을 유지한다.
필요하면 2~3개 방향을 비교한다.

중간 자유도

반복 패턴은 있지만 상황에 따라 조정이 필요한 작업에 맞습니다.

기본 출력은 표로 작성한다.
단, 입력이 서술형이면 먼저 항목을 추출한 뒤 표로 변환한다.

낮은 자유도

파일 변환, 배포, 데이터 정리처럼 순서가 틀리면 사고가 나는 작업에 맞습니다.

반드시 scripts/validate.py를 먼저 실행한다.
검증이 실패하면 변환을 진행하지 않는다.
출력 경로는 사용자가 지정한 폴더 안으로 제한한다.

스크립트를 넣어야 하는 경우

반복해서 같은 코드를 작성하고 있다면 스크립트로 빼야 합니다.

스크립트가 필요한 신호:

매번 같은 파싱 코드를 다시 쓴다.
파일 포맷이 까다롭다.
사람이 실수하면 원본이 손상된다.
실행 결과가 결정적이어야 한다.
많은 파일을 일괄 처리한다.

예:

scripts/
├── validate-frontmatter.js
├── convert-md-to-html.py
└── render-preview.ps1

SKILL.md에는 스크립트 전체 코드를 붙이지 말고, 언제 어떤 명령으로 실행하는지만 씁니다.

references를 넣어야 하는 경우

긴 문서는 references/로 분리합니다.

예:

references/
├── safety-policy.md
├── api-schema.md
├── writing-style.md
└── examples.md

중요한 것은 SKILL.md가 reference의 존재를 알려야 한다는 점입니다.

의료 관련 질문이면 `references/medical-safety.md`를 먼저 읽는다.
API 필드 검증이 필요하면 `references/api-schema.md`에서 해당 엔드포인트만 확인한다.

assets를 넣어야 하는 경우

결과물에 직접 쓰는 파일은 assets/에 둡니다.

PPT 템플릿
DOCX 양식
이미지
폰트
샘플 CSV
HTML 보일러플레이트

assets는 읽기 위한 문서가 아니라 사용하기 위한 재료입니다.

스킬 제작 절차

1단계: 반복 작업을 찾는다

아래 질문에 답합니다.

이 작업을 한 번이 아니라 여러 번 할 것인가
매번 같은 설명을 반복하고 있는가
실수하면 비용이 큰가
특정 도구나 파일 형식을 다루는가
기존 모델 지식만으로는 부족한 로컬 규칙이 있는가

2단계: 트리거 문장을 모은다

사용자가 실제로 할 말을 적습니다.

이 원고 빨간펜 해줘
이 PDF에서 표 뽑아줘
이 프로젝트 배포해줘
이 PPT 템플릿으로 제안서 만들어줘

이 문장이 description에 반영되어야 합니다.

3단계: 실패 사례를 쓴다

스킬은 성공 절차보다 실패 방지가 중요합니다.

실패 사례:
- 의료 질문에 진단처럼 답함
- 한글 인코딩이 깨진 문자열을 그대로 복사함
- 배포할 때 untracked 문서를 같이 올림
- 긴 reference 전체를 읽어 컨텍스트를 낭비함

4단계: 최소 `SKILL.md`를 만든다

처음부터 완벽하게 만들지 않습니다. description, 목적, 절차, 검증만 넣고 실제 사용 후 보강합니다.

5단계: 테스트한다

테스트 질문을 3개 이상 만듭니다.

정상 요청:
경계 요청:
스킬을 쓰면 안 되는 요청:

스킬이 너무 자주 발동하면 description을 좁힙니다. 너무 안 발동하면 트리거 표현을 추가합니다.

6단계: 개선 로그를 남긴다

스킬은 한 번 만들고 끝이 아닙니다. 실제 사용에서 실패한 케이스를 반영해야 합니다.

스킬 검수 체크리스트

description만 읽어도 언제 쓰는지 명확한가
모델이 이미 아는 일반론을 길게 반복하지 않는가
작업 절차가 순서대로 되어 있는가
위험한 작업의 중단 조건이 있는가
긴 자료는 reference로 분리했는가
반복 코드는 script로 뺐는가
결과물 검증 기준이 있는가
스킬을 쓰면 안 되는 경우도 적었는가
예시 입력과 예시 출력이 있는가

예시: 콘텐츠 리서치 스킬 설계

name: content-research-writer
description: 사용자가 블로그, 뉴스레터, 기술문서, 리서치 글의 초안 작성이나 보강을 요청하고, 출처 조사, 아웃라인, 인용, 훅 개선, 섹션별 피드백이 필요할 때 사용한다.

핵심 절차:

글의 목적과 독자를 확인한다.
공식 문서 또는 1차 자료를 우선 조사한다.
아웃라인을 만든다.
초안을 작성한다.
섹션별로 근거와 흐름을 검수한다.
마지막에 참고 문헌을 정리한다.

이 스킬의 핵심은 글쓰기 재능이 아니라 리서치와 편집 순서입니다.

예시: qmd 운영 스킬 설계

name: qmd-windows
description: Windows PowerShell 환경에서 qmd를 직접 실행해 프로젝트 문서와 코드를 검색, 인덱싱, 조회해야 할 때 사용한다. UTF-8 부트스트랩, Bun 직접 실행 경로, OneDrive 경로 주의사항을 포함한다.

핵심 절차:

UTF-8 부트스트랩을 로드한다.
qmd.ts 직접 실행 경로를 확인한다.
status로 인덱스 상태를 본다.
search 또는 query로 후보를 좁힌다.
필요한 파일만 읽는다.

이런 식으로 스킬은 특정 환경의 반복 실수를 줄이는 데 강합니다.

흔한 실수

1. 스킬에 모든 지식을 넣는다

스킬은 백과사전이 아닙니다. SKILL.md는 실행 절차, reference는 세부 지식입니다.

2. description이 마케팅 문구다

"최고의 생산성을 제공하는 강력한 스킬" 같은 문장은 트리거에 도움이 안 됩니다. 사용자가 어떤 요청을 할 때 쓰는지 써야 합니다.

3. 검증이 없다

검증 기준이 없으면 스킬은 그냥 긴 프롬프트입니다.

4. 너무 많은 자유도를 준다

파일 삭제, 배포, 결제, 의료, 금융 같은 작업은 자유도를 낮춰야 합니다.

5. 스킬을 쓰면 안 되는 경우가 없다

좋은 스킬은 경계가 있습니다. 예를 들어 이미지 생성 스킬은 SVG 로고 수정처럼 코드로 고치는 편이 나은 작업에는 쓰지 않아야 합니다.

마무리

스킬은 AI를 더 똑똑하게 만드는 장식이 아닙니다. 작업을 더 덜 잊게 만들고, 덜 위험하게 만들고, 더 반복 가능하게 만드는 운영 문서입니다.

좋은 스킬은 읽자마자 행동이 바뀝니다. 나쁜 스킬은 읽어도 "그래서 뭘 하라는 거지?"가 남습니다.

스킬을 만들 때는 이 질문 하나로 시작하면 됩니다.

이 스킬이 없을 때 AI가 반복해서 저지르는 실수는 무엇인가?

그 실수를 막는 절차가 바로 스킬의 본문입니다.

참고 문헌

로컬 skill-creator 지침: C:\Users\mouse\.codex\skills\.system\skill-creator\SKILL.md