# Lesson 02 Skills > AI 에이전트 강의 패키지의 2강 — 비개발자가 본인의 첫 SKILL.md를 만들 때 사용하는 30분 대화형 강의. 학습자가 자주 하는 작업을 자동화하는 스킬을 *동봉된 skill-creator의 vibe 모드*로 함께 만들고, 본인 에이전트에서 호출하는 법까지 익힌다. 사용자가 "2강 시작", "skill 만들고 싶어요", "skill.md 어떻게 만들지", "내가 자주 하는 작업 자동화하고 싶어요", "에이전트한테 같은 부탁 매번 반복하기 귀찮아요", "스킬 만드는 법 알려줘", "1강 끝났어 다음" 같은 표현을 쓰거나, 1강을 마친 후 자연스럽게 이어지는 강의에 진입하려 할 때 반드시 이 스킬을 사용한다. 단순 SKILL.md 작성 도움이 아니라, 한 청크씩 게임처럼 진행되는 30분짜리 가이드형 학습 흐름이라는 점이 핵심이다. - Skill: `matthewoong/lesson-02-skills` (Agent Skill, multi-file: 10 files) - Install (CLI): `npx skillmds@latest add matthewoong/lesson-02-skills` - Raw SKILL.md: https://api.skillmd.com/api/skills/matthewoong/lesson-02-skills/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: Matthewoong (https://skillmd.com/u/matthewoong) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/matthewoong/lesson-02-skills --- # Lesson 02 — 첫 SKILL.md 만들기 > 학습자가 끝나면 *자주 하는 작업 1개를 자동화하는 SKILL.md*를 만들고, 본인 에이전트에서 호출하는 법까지 익힌다. 이 스킬은 *대화형 강의*입니다. 단순히 SKILL.md를 대신 만들어주는 게 아니라, 학습자가 한 청크씩 따라오며 *직접 손으로* 만들도록 옆에서 가이드합니다. 가이드 실습 단계에서는 동봉된 `_vendor/anthropic-skill-creator/`(Apache 2.0)를 *vibe 모드*로 호출해 함께 작성합니다. --- ## 0. 시작하기 전에 — 반드시 따라야 할 공통 규칙 이 스킬은 강의 패키지의 공통 프로토콜 위에서 동작합니다. | 문서 | 언제 참조하나 | |---|---| | `_shared/teaching-protocol.md` | 이론 lesson을 청크 단위로 진행할 때마다 | | `_shared/guided-practice-protocol.md` | 이론이 끝나고 가이드 실습 모드로 전환할 때 | | `_shared/learner-profile-schema.md` | 학습자 프로필을 읽고 갱신할 때 | | `_shared/style-guide.md` | 출력 톤·도구 비종속 표기·OS 분기·동적 예시 | | `_shared/menu-template.md` | 첫 진입 / 메뉴 / 트랙 분기 | 위 규칙들이 *모든 강의 출력의 기본*입니다. 본 SKILL.md는 그 위에 2강 고유 흐름만 얹습니다. --- ## 1. 진입 시 행동 1. **학습자 프로필 확인** - `_shared/learner-profile.json` 읽기. 없으면 `_shared/menu-template.md`의 첫 진입 흐름을 먼저 수행. 2. **이 강의의 진도 확인** - `progress["02-skills"].status` 값에 따라 분기: - `not_started` → 첫 청크부터 - `in_progress` → `current_chunk`부터 이어서 - `completed` 또는 `skipped` → "이미 들으신 강의예요. 다시 들으실래요?" 분기 3. **선행 강의 확인 + 짧은 인사** - `progress["01-agents-md"].status`가 `completed`/`skipped`가 아니면, 학습자에게 *권장 순서 안내* 한 번: > "1강(AGENTS.md)를 안 들으셨네요. 먼저 들으시면 더 자연스러운데, 그래도 2강 먼저 들으실래요?" - 학습자 답에 따라 진입 또는 1강으로 분기. - 첫 청크 출력 전에 *짧게* 인사: 학습자 이름 호명, 30분 분량, 한 청크씩 진행. 4. **이론 lesson 진입** - `lesson/01-*.md`부터 *순서대로 한 청크씩* 출력. - 모든 출력은 `_shared/teaching-protocol.md`의 청크 규칙을 따름: - 첫 줄에 `📘 [Lesson 2 · 청크 X/Y]` - 한 청크 = 설명 3~6문장 + 코드 0~1개 + 끝맺음(❓/🛠/🔀) - 학습자 답변 전까지 다음 청크 X - 자리표시자(`{{example:concept}}`, `{{os:darwin}}`)는 출력 *직전*에 학습자 프로필 값으로 채움. 5. **이론 마지막 청크 종료 후 → 가이드 실습 진입** - `practice/guided.md`의 흐름 시작. - `_shared/guided-practice-protocol.md`의 7단계 적용. - 2강 실습 옵션은 두 가지(인라인): - **옵션 ①** 본인 작업 자동화 (이론에서 적은 draft 그대로 활용) - **옵션 ②** 자유 입력 (draft 무시하고 새 작업) 6. **실습 종료 후 → 마무리** - 진도 갱신 (다음 절 참조) - 다음 강의 안내 (3강 — MCP) --- ## 2. 진도 갱신 + draft 키 명세 `_shared/learner-profile.json`을 직접 읽고 써서 다음 시점에 갱신합니다. | 시점 | 갱신 | |---|---| | 2강 첫 진입 | `progress["02-skills"].status = "in_progress"`, `current_chunk = 1`, `last_visited_at` | | 청크 통과 | `current_chunk += 1` | | 청크 4 답변 (자동화할 작업) | `progress["02-skills"].draft.task = <학습자 답변>` | | 청크 5 답변 (트리거 표현) | `draft.trigger = <학습자 답변>` | | 청크 6 답변 (핵심 단계) | `draft.steps = [<답변에서 추출한 단계 배열>]` | | 청크 7 답변 (이름·설명) | `draft.skill_name = <소문자·하이픈>`, `draft.skill_description = <첫 안>` | | 이론 마지막 청크 통과 | (아직 `completed`로 바꾸지 않음 — 실습까지 끝나야 ✅) | | 가이드 실습 진입 시 | `draft` 전체를 학습자에게 정리해 보여줌 (4-0절) | | 실습 통과 | `practice_status = "done"`, `status = "completed"`, `completed_at` | | 학습자가 lesson 스킵 | `status = "skipped"` | | 학습자가 실습만 스킵 / 포기 | `practice_status = "not_done"`, `status = "completed"` (수강은 완료, ⚠) | | 학습자가 강의 "리셋" | `draft = {}` 비우기 | | 모든 갱신 시 | `updated_at = 오늘 날짜` | ### 2강이 사용하는 `draft` 키 | 키 | 채워지는 시점 | 형식 | 비고 | |---|---|---|---| | `task` | 청크 4 | string (한 줄) | 자동화하고 싶은 작업의 *내용* | | `trigger` | 청크 5 | string | 학습자가 에이전트에게 부를 *표현* (예: "주간 회고 정리해줘") | | `steps` | 청크 6 | array of string | 작업의 핵심 단계 3~5개 | | `skill_name` | 청크 7 | string (소문자·하이픈) | SKILL.md의 `name` (예: `weekly-review-organizer`) | | `skill_description` | 청크 7 | string | SKILL.md의 `description` 첫 안 | > 학습자가 답변을 *수정*하면 같은 키 덮어쓰기. 청크를 스킵하면 키는 빈 문자열/빈 배열로. --- ## 3. 이론 lesson 흐름 (Phase 3에서 lesson/ 폴더에 채워짐) 이론 청크는 `lesson/` 폴더의 마크다운 파일들로 분리되어 있습니다. 파일명은 `01-*.md`, `02-*.md` 형식의 순서를 따르며, 각 파일이 한 묶음의 청크를 담습니다. ### 청크 출력 시 지킬 것 (요약) - 한 응답 = 한 청크 - 첫 줄에 `📘 [Lesson 2 · 청크 X/Y]` (Y = 2강 이론 전체 청크 수) - 학습자가 *시도하기 전*에 정답을 미리 보여주지 않기 - "넘어가" 등 명시적 스킵 입력 시에만 다음 청크로 점프 (`status = skipped` 처리) ### 2강에서 *왜* 한 청크씩 가는가 (학습자에게 설명할 때 도움) SKILL.md는 *재사용 가능한 자동화*입니다. "내 작업의 어디까지 자동화할 수 있을까?"를 매 항목마다 학습자가 직접 결정해야 진짜로 본인 도구가 됩니다. 그래서 한 번에 정답을 보여주는 대신, 한 청크씩 *질문 → 결정 → 다음*으로 가며 학습자만의 작업·트리거·단계를 누적합니다. --- ## 4. 가이드 실습 — 두 옵션 인라인 이론이 끝나면 `practice/guided.md`로 넘어가 가이드 실습 모드를 엽니다. 옵션이 2개라 인라인 분기로 처리합니다. ### 4-0. 진입 시 draft 정리 (필수, 옵션 제시 전에 먼저 수행) 학습자가 이론에서 적어둔 내용은 `progress["02-skills"].draft`에 자동 보관되어 있습니다. 옵션 제시 직전에 이 내용을 *정리해서 학습자에게 한 번 보여줍니다*. ``` 🎉 이론 끝! 이제 진짜 SKILL.md를 만들어볼 시간이에요. 이론 때 적어주신 내용을 정리해 보여드릴게요. 📝 자동화할 작업: 📝 트리거 표현: "" 📝 핵심 단계: - - - 📝 이름: 📝 설명: 이걸 토대로 실제 SKILL.md를 만들어볼게요. 다시 적으실 필요 없어요. 수정하고 싶은 항목이 있으시면 "작업 수정", "트리거 수정", "단계 수정", "이름 수정", "설명 수정"처럼 말씀해주세요. ``` ### 처리 규칙 - 비어 있는 키(스킵된 청크)는 "(아직 안 적으셨어요. 실습 중 같이 채워볼게요)" 표시 - 학습자가 "X 수정"이라고 답하면 → 해당 키만 다시 입력 받아 같은 키에 덮어쓰기 - 학습자가 "그대로 좋아요" 또는 별도 응답 없이 넘어가면 → 옵션 제시로 진행 ### 4-1. 옵션 제시 ``` 이제 SKILL.md를 만들어볼 거예요. 두 가지 길 중에 골라주세요. (1) 이론 때 적어주신 작업으로 진행 (가장 추천 — 적어주신 내용이 그대로 결과물이 됩니다) (2) 다른 걸 만들고 싶어요 (이론 draft는 잠시 두고, 새 작업으로 시작해요) 번호 또는 "1번", "2번"으로 답해주세요. ``` ### 4-2. 옵션 ① — 이론 작업 그대로 draft 그대로 사용. 곧장 4-4(skill-creator 호출 흐름)로. ### 4-3. 옵션 ② — 자유 입력 (새 작업) 학습자에게 새 작업·트리거·단계·이름·설명을 한 번에 또는 단계별로 입력 받음. 받은 값은 *임시*로 보관하고, 강의 종료 시 학습자에게 "이 새 작업을 draft에 덮어쓸까요?" 분기. ### 4-4. skill-creator 호출 흐름 (2강의 핵심) #### 1) 학습자 환경에서 skill-creator 사용 가능 여부 확인 학습자에게 다음을 안내: ``` 이제 동봉된 skill-creator를 호출해 함께 SKILL.md를 만들 거예요. {{name}}님이 사용하시는 에이전트한테 다음 표현으로 시켜보세요. 👉 "skill-creator 호출해서 vibe 모드로 같이 스킬 만들어줘" 만약 "skill-creator를 못 찾겠다"는 답이 오면, 동봉본 경로를 직접 가리켜주시면 됩니다. 다음 단계에서 알려드릴게요. ``` #### 2) 호출 안 되는 경우 — 동봉본 경로 안내 ``` 괜찮아요. 이 강의 패키지 안에 동봉본이 있어요. 다음 메시지를 그대로 에이전트한테 입력해주세요. 👉 "_vendor/anthropic-skill-creator/SKILL.md를 읽고 그 가이드대로 vibe 모드(평가 생략)로 스킬을 같이 만들어줘" ``` #### 3) skill-creator vibe 모드 진입 안내 skill-creator의 SKILL.md 본문은 평가·벤치마크·iteration loop 등 *고급 흐름*을 담고 있습니다. 비개발자 학습자는 이 부분이 부담스러울 수 있어, 학습자에게 다음을 명확히 알려주세요: ``` skill-creator는 평가/벤치마크 같은 고급 모드도 있지만, 우리는 *vibe 모드*만 쓸 거예요. 즉 evals 없이 같이 만들기만 하고, 평가 단계는 생략합니다. skill-creator가 질문하면 {{name}}님이 답하시면서 SKILL.md를 만들어가요. 이론 때 적어주신 내용(작업·트리거·단계·이름·설명)을 그대로 답으로 쓰시면 됩니다. ``` #### 4) 도구별 호출 방식 (부록 박스) ``` > 💡 도구별 호출 (참고) > > Claude Code: description 트리거 또는 스킬 자동 인식 > Codex CLI: 동일하게 description 트리거 또는 폴더 내 자동 인식 > Cursor: description 트리거 > Gemini CLI: 폴더 인식 후 호출, 또는 `gemini extensions` 활용 > Antigravity: description 자동 트리거 (점진적 공개) > > 정확한 명령은 도구마다 조금 달라요. 안 되면 동봉본 경로를 직접 가리키시면 OK. ``` ### 4-5. 학습자가 만든 SKILL.md를 *어디에 둘지* (OS 분기) skill-creator 흐름이 끝나면, 학습자가 만든 SKILL.md를 *본인 에이전트가 인식하는 위치*에 둡니다. 학습자 OS에 맞춰 안내: {{os:darwin}} ```bash # 글로벌 스킬 폴더 (Claude Code 기준 — 다른 도구는 INSTALL.md 참조) mkdir -p ~/.claude/skills/ # 만든 SKILL.md를 그 폴더로 이동/복사 mv <임시 위치>/SKILL.md ~/.claude/skills//SKILL.md ``` {{/os}} {{os:win32}} ```powershell # 글로벌 스킬 폴더 (Claude Code 기준) New-Item -ItemType Directory -Force -Path "$HOME\.claude\skills\" # 만든 SKILL.md를 그 폴더로 이동 Move-Item "<임시 위치>\SKILL.md" "$HOME\.claude\skills\\SKILL.md" ``` {{/os}} > 다른 도구(Codex/Cursor/Gemini/Antigravity) 사용자라면 `INSTALL.md`의 글로벌 스킬 폴더 안내를 참조하세요. 강의 패키지 폴더 안에 *임시*로 두고 학습자가 나중에 옮기는 것도 OK입니다. ### 4-6. 호출 한 번 시연 + 검증 저장이 끝나면 학습자에게: ``` 이제 만든 스킬이 잘 동작하는지 확인해볼게요. {{name}}님이 사용하시는 에이전트한테 트리거 표현으로 시켜보세요. 👉 "" 답이 나오면 그대로 붙여넣어 주세요. (만약 에이전트가 새 스킬을 인식 못 하면, 에이전트를 한 번 *재시작*해야 할 수도 있어요. 자주 있는 일이에요.) ``` ### 검증 기준 학습자가 결과를 붙여넣으면 점검: | 항목 | 통과 기준 | |---|---| | frontmatter `name` | 소문자·하이픈만 사용, 채워짐 | | frontmatter `description` | 한 문장 이상, "Use when..." 또는 비슷한 트리거 표현 포함 | | 본문 길이 | 5줄 이상 | | 도구 비종속 | 본문에 "Claude가" / "Codex가" 같은 도구명 노출 X | | 호출 동작 확인 | 학습자가 트리거로 호출했을 때 에이전트가 *그 스킬 흐름대로* 응답 | → 5개 중 4개 이상 통과 시 ✅. 부족한 항목은 *명확히 명시*하고, 채울 수 있게 안내(1강과 같은 패턴). --- ## 5. 자리표시자 처리 lesson/practice 파일 안에 다음 자리표시자가 등장합니다. 출력 *직전*에 학습자 프로필 값을 보고 채우세요. ### `{{example:concept-name}}` — 도메인 동적 예시 - 학습자 프로필 `domain` 값을 읽어 1~2문장으로 *학습자 도메인에 맞춘* 적용 예시 생성 - 예: `domain="블로그 운영"` + `concept="skill-task-example"` → "예를 들어 {{name}}님 블로그 환경이라면, 매주 발행한 글 목록을 정리해 다음 주 글감을 추천하는 스킬을 만들어볼 수 있어요." - *명령어, 사실관계, 코드*는 자리표시자로 만들지 마세요. - 도메인이 비어 있으면 일반 표현으로 대체하거나 자리표시자 통째 생략. ### `{{os:darwin}} ... {{/os}}` / `{{os:win32}} ... {{/os}}` — OS 분기 - 학습자 프로필 `os` 값에 *해당 블록만* 출력. 양쪽 동시 출력 X. ### `{{name}}`, `{{domain}}` - 단순 치환. 학습자 프로필의 해당 필드를 그대로 끼워 넣기. 비어 있으면 비워두거나 일반 표현으로 대체. --- ## 6. 도구 비종속 — 절대 잊지 않기 이 강의는 학습자가 어떤 에이전트(Claude Code · Codex CLI · Cursor · Gemini CLI · Antigravity)에서 열어도 같은 흐름이어야 합니다. - 본문에서 "Claude가" / "Codex가" 같은 도구명을 *드러내지 마세요.* 항상 "에이전트가"로 통칭. - 도구별 차이가 *반드시* 필요한 부분에서만 부록 박스로 분기. - skill-creator 자체는 Apache 2.0의 외부 자료. 본문에서 호출할 때도 도구명 없이 "에이전트한테 시켜보세요" 표현 사용. --- ## 7. 종료 시 행동 실습이 끝나면: 1. 진도 갱신 (`status = "completed"`, `practice_status` 결정). 2. 짧은 마무리 — 학습자가 만든 SKILL.md가 *어디 저장됐고, 어떻게 호출되는지* 한 번 더 안내. 3. 다음 강의 안내 — 3강(03-mcp)으로 자연스럽게 연결. ``` 🎉 2강 완주! {{name}}님이 만든 스킬은 이제 매번 에이전트에게 같은 부탁을 반복하지 않아도 되게 해줄 거예요. 다음 강의로 가시겠어요? (1) 네, 3강(MCP)으로 — 외부 도구 연결로 스킬을 더 강력하게 (2) 메뉴로 (3) 종료 ``` --- ## 8. 2강 강의 작성자 메타 정보 (학습자에게 출력 X) > 이 섹션은 강의 작성자(매튜) / 검토자가 참고하는 영역입니다. 학습자에게는 출력하지 마세요. - **트랙**: 기초 (basic) 2번 - **선행 조건**: 01-agents-md (권장이지만 강제는 X. 미수강 시 안내 후 진행 가능) - **분량**: 약 30분 (이론 청크 7~9개 + 가이드 실습 + skill-creator 호출 시간) - **외부 자료 의존**: `_vendor/anthropic-skill-creator/` (Apache 2.0) - **학습 목표**: - SKILL.md의 *기본 구조*(frontmatter + 본문)를 이해할 수 있다 - 본인이 *자주 하는 작업 1개*를 자동화할 SKILL.md를 한 번 만들어본다 - 만든 스킬을 *본인 에이전트에서 호출*하는 법을 안다 - 호출 결과를 보고 *어떤 부분이 부족한지* 스스로 판단할 수 있다 - **다음 강의**: `03-mcp` (MCP 서버 연결) — 학습자가 만든 스킬 안에서 *외부 도구*를 호출하는 흐름으로 자연스럽게 이어짐. --- ## 9. 빠른 자기 점검 (이 스킬을 호출한 에이전트가 매 응답마다 확인) - [ ] 학습자 프로필을 *읽었는가* (없으면 만들었는가) - [ ] 첫 줄에 `📘 [Lesson 2 · 청크 X/Y]` 헤더가 있는가 - [ ] 한 청크만 출력했는가 (3~6 문장 + 코드 0~1개) - [ ] 끝에 ❓/🛠/🔀 중 하나가 있는가 - [ ] 자리표시자를 모두 채웠는가 (`{{example:...}}`, `{{os:...}}`, `{{name}}` 등) - [ ] 도구명을 본문에 노출하지 않았는가 - [ ] 학습자가 *시도하기 전*에 답을 보여주지 않았는가 - [ ] 청크 통과 시 `progress["02-skills"]`를 갱신했는가 - [ ] *2강 추가*: skill-creator 호출 안내 시 학습자 환경에서 *실제로 시도*하라고 했는가 (대신 호출하지 않기) 이 체크리스트를 응답 전마다 머릿속으로 점검하세요. 한 항목이라도 누락되면 학습 흐름이 깨집니다.