이 글은 실제 사례인 「SEO 점검」 스킬이 탄생하기까지의 전 과정을 통해 SKILL을 만들 때 해야 할 작업, 사용한 명령어, 그리고 겪은 시행착오를 정리합니다. 반복적인 워크플로를 재사용 가능한 스킬로 고정하고 싶은 분께 적합합니다.
1. SKILL이란 무엇이며, 왜 생성해야 하는가
SKILL은 일련의다단계 워크플로우고정된 재사용 가능한 역량 패키지입니다. 한 번 잘 만들어두면 이후 한마디로 전체 프로세스를 트리거할 수 있어 매번 다시 설명할 필요가 없습니다.
하나의 SKILL은 본질적으로 하나의 폴더입니다:
skill-name/
├── SKILL.md ← 核心：流程说明 + 触发词 + 输入 + 经验
├── scripts/ ← 可选：可复用的代码脚本
│ └── *.py
└── evals/ ← 可选：测试用例
└── evals.json
SKILL로 만들기 적합한 신호: 반복적으로 하는 일, 단계 ≥2, 명확한 산출물 존재, 대상(URL/고객/프로젝트)을 바꿔도 사용 가능.
2. SKILL 생성의 전체 프로세스 (5단계)
스킬 생성 자체에도 이를 안내하는 "메타 스킬"이 있습니다. 핵심은 다음 5단계입니다:
| 단계 | 하는 일 | 사용 명령어/도구 |
|---|---|---|
| 1. 먼저 워크플로우를 실제로 한 번 완전히 실행 | 실제 작업으로 한 번 완전히 수행하여 실제 성과물 산출 | 일반 대화로 충분 |
| 2. 스킬 골격 확인 | 스킬 이름, 표시 이름, 트리거 단어, 입력 항목, 아이콘 정의 | AI와 확인 |
| 3. 세션 데이터 추출 | 사용한 도구 자동 추출, 골격 생성 | extract_session_data |
| 4. SKILL.md 작성 | 프로세스, 경험, 스크립트 보완 | AI 생성, 사람 검토 |
| 5. 저장 + 테스트 | 스킬 라이브러리에 저장, 테스트 케이스 생성 | save_skill + generate_skill_evals |
3. 단계별 분해: 각 단계에서 구체적으로 무엇을 하는가
단계 1: 먼저 워크플로를 검증하라 (가장 중요)
스킬부터 만들지 마라. 먼저 실제 요구사항 하나를 완전히 수행하라. 예: "이 웹페이지의 SEO를 점검해줘". 이 과정에서:
- 명확히 하라입력이 무엇인지 (URL 하나? URL 여러 개?)
- 명확히 하라산출물이 무엇인지 (보고서 하나? 어떤 형식?)
- 각 단계에서 어떤 능력을 사용했는지 기록하라 (웹페이지 열기, 코드 실행, Excel 생성……)
실전 교훈: 우리의 SEO 스킬은 특정 기업 공식 웹사이트의 여러 페이지를 실제로 꼼꼼히 검토하고 보고서 형식을 반복 조정한 후에야 스킬로 정제되었다. 중간에 사용자가 계속 요구사항을 추가했는데( Bing 기준 추가, 공식 출처 확인, 실행 매트릭스로 변경, 두 단계로 분리……), 이 모든 것이 스킬에서 가장 가치 있는 부분이 되었다.
단계 2: 스킬 골격 확인
AI에게 명확히 말하라 (또는 제안하게 하라):
| 프로젝트 | 설명 | 예시 |
|---|---|---|
| 스킬 이름 | 소문자 하이픈, 내부 식별자 | seo-audit-skill |
| 표시 이름 | 사람이 보는 이름 | 「SEO 점검」 |
| 트리거 단어 | 어떤 말이 이를 활성화해야 하는가 | "SEO 점검 / 웹사이트 최적화 / 페이지 SEO 확인" |
| 입력 항목 | 매번 달라지는 것 | page_url、audit_scope |
| 아이콘 | 이모지 하나 | 🔍 |
3단계: 세션 데이터 추출
이 단계는 도구가 자동으로 완료합니다. 방금 성공적으로 실행한 세션을 스캔하여 사용된 도구 목록을 추출하고, YAML frontmatter가 포함된 SKILL.md 뼈대를 생성합니다. 2단계에서 정한 것만 제공하면 됩니다: 스킬 이름, 트리거 단어, 입력 항목, 표시 이름, 아이콘.
지시:extract_session_data
4단계: SKILL.md 작성 (핵심 창작)
뼈대를 기반으로 다음 부분을 보완하세요:
① frontmatter (파일 헤더)
---
name: seo-audit-skill
display_name: 「SEO 体检」
description: "一句话说清楚它做什么、什么时候该触发"
icon: "🔍"
trigger: SEO体检 audit 网站优化 网站SEO
inputs:
- name: page_url
description: "要体检的页面网址"
required: true
scripts: [seo_audit.py, seo_matrix.py]
---
② Overview
2–3문장으로 무엇을 하는지, 언제 사용하는지 명확히 설명하세요.
③ Workflow (단계별)
각 단계에 모드(deterministic 고정 동작 / agentic 판단 필요), 입력, 출력, 검증 방법, 실패 시 대처를 표시하세요."왜"를 더 많이 설명하고, 딱딱한 "반드시/금지"는 줄이세요—— 스킬을 실행하는 AI는 "이치를 설명"하는 쪽을 더 잘 받아들입니다.
④ Output
최종 산출물이 어떤 형태인지, 형식을 명확히 정의하세요.
⑤ Lessons Learned (경험)
이것이 스킬 품질의 분수령이며, 네 부분으로 나뉩니다:
- Do: 어떤 방법이 효과적인지
- Don't: 어떤 함정을 피해야 하는지
- Common Failures: 흔한 오류 + 대응
- When to Ask the User: 언제 멈추고 사람에게 물어야 하는지
실전 교훈: 우리 스킬의 Lessons에는 실제로 겪은 함정이 가득합니다——중국어에는\uXXXX이스케이프를 쓰지 말 것, CSV 작성 시utf-8-sigExcel 깨짐 방지, 이미지 alt 누락률이 비정상적으로 높은 것은 대부분 지연 로딩 오탐(직접 누락 판정 대신 "확인 필요"로 표시), 일부 도메인은 대량 크롤링을 차단하므로 브라우저로 검증 필요…… 이런 "피눈물"이 스킬을 다음에 더 안정적으로 실행하게 만듭니다.
⑥ 스크립트 (선택 사항이지만 강력 권장)
워크플로에 반복 작성되는 코드가 있다면 스크립트로 추출하여 scripts/SKILL.md에서 참조합니다. 우리는 "페이지 신호 수집 JS"와 "다중 페이지 매트릭스 생성"을 두 개의 스크립트로 만들어 출력 형식이 매번 일관되도록 보장했습니다.
단계 5: 저장 + 테스트
- 저장 지시:
save_skill(스킬 이름 + 전체 SKILL.md + 스크립트) - 생성 테스트:
generate_skill_evals(자동으로 몇 가지 테스트 케이스 생성) - 그런 다음실제로 한 번 실행검증——우리는 단일 페이지, 다중 페이지 두 가지 시나리오로 각각 실측하여 실제 문제를 식별할 수 있는지 확인했습니다(예: 여러 404 깨진 링크를 찾아내고, 소셜 공유 제목과 페이지 제목이 일치하지 않는 것을 발견).
4. 생성 후 반복 및 배포 방법
반복 개선
지시:load_skill_for_improvement. 스킬은 한 번에 완성되지 않습니다. 몇 번 사용한 후 필요에 따라 개선하세요:
- 프로세스 변경, 출력 형식 추가, 트리거 단어 조정
- 저장 시같은 스킬 이름 사용하면 제자리에서 덮어쓰기 됩니다(이전 버전 자동 백업)
실전: 우리의 이 스킬은 여러 차례 반복했습니다——Bing 표준 추가, 실행 매트릭스 형식 변경, 두 단계로 분리, Excel+Markdown 이중 출력 추가, 열 이름 정렬 샘플 수정, 마지막으로 이름 변경. 매 라운드마다load_skill_for_improvement→ 수정 →save_skill덮어쓰기.
이름 변경
frontmatter의 name 와 display_name를 수정하고, 새 이름으로 save_skill, 그런 다음 이전 스킬 폴더를 삭제합니다.
패키징 배포
전체 스킬 폴더를 zip으로 압축하면 백업, 다른 컴퓨터로 마이그레이션, 또는 동료에게 공유(상대방의 skills 디렉토리에 넣기)할 수 있습니다.
크로스 도구 이식
다른 AI 도구(ChatGPT/Claude/Gemini)에서 사용하려면 "탈플랫폼화"가 필요합니다: 전용 도구 이름을 일반 능력 설명("웹페이지 열기""코드 실행")으로 바꾸고, 스크립트를 자체 포함 Markdown으로 내장하면 전체를 시스템 프롬프트/사용자 정의 지시로 붙여넣을 수 있습니다.
5. 자주 쓰는 지시 빠른 참조
| 지시 | 역할 | 사용 위치 |
|---|---|---|
extract_session_data | 세션에서 골격 추출 | 생성·3단계 |
save_skill | 스킬 저장/덮어쓰기 | 생성·5단계 / 반복 |
generate_skill_evals | 테스트 케이스 생성 | 생성·5단계 |
load_skill_for_improvement | 스킬을 불러와 개선 | 반복 |
6. 함정 회피 체크리스트 (실제 경험에서 나온 것)
- 먼저 돌려보고 나서 고정하라— 스킬을 허공에 대고 작성하지 마라.
- 입력에는 변하는 값만 넣어라— 고정값은 프로세스 안에 하드코딩하라.
- Lessons Learned에는 실제 경험을 빼곡히 적어라— 이것이 스킬이 "쓸수록 더 안정적"이 될 수 있는지를 좌우하는 핵심이다.
- 반복되는 코드는 스크립트로 추출하라— 출력 형식의 일관성을 보장하고 토큰을 절약한다.
- 저장 후 반드시 테스트하라— 단일 페이지 + 다중 페이지를 실제로 한 번 돌려, 실제 문제를 식별할 수 있는지 검증하라.
- 인코딩 함정(중국어/코드 생성이 관련된 경우): 파일 작성 시
encoding="utf-8", CSV는utf-8-sig, 사용하지 말 것:\uXXXX이스케이프, PDF 중국어는 내장 CID 폰트를 사용하라. - 반복 시 같은 이름으로 덮어쓰기——
name변경 없음, 이전 버전은 자동 백업된다.
맺음말
SKILL을 만드는 본질은:한 번 성공한 워크플로를 그 안의 판단과 교훈까지 함께 포장하여 "다음엔 한마디로 다시 시작할 수 있는" 역량으로 만드는 것이다. 잘 만든 스킬은 단계만 기록하는 것이 아니라, "이 일을 어떻게 올바르게 해내는가"에 대한 경험까지 기록한다.
먼저 일을 훌륭하게 해내고, 그다음 재사용 가능하게 만들어라 — 이것이 SKILL을 만드는 모든 요체다.
