Lesson 02 Skills

Lesson 02 — 첫 SKILL.md 만들기

학습자가 끝나면 자주 하는 작업 1개를 자동화하는 SKILL.md를 만들고, 본인 에이전트에서 호출하는 법까지 익힌다.

이 스킬은 대화형 강의입니다. 단순히 SKILL.md를 대신 만들어주는 게 아니라, 학습자가 한 청크씩 따라오며 직접 손으로 만들도록 옆에서 가이드합니다. 가이드 실습 단계에서는 동봉된 _vendor/anthropic-skill-creator/(Apache 2.0)를 vibe 모드로 호출해 함께 작성합니다.

0. 시작하기 전에 — 반드시 따라야 할 공통 규칙

이 스킬은 강의 패키지의 공통 프로토콜 위에서 동작합니다.

위 규칙들이 모든 강의 출력의 기본입니다. 본 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]
     • 한 청크 = 설명 36문장 + 코드 01개 + 끝맺음(❓/🛠/🔀)
     • 학습자 답변 전까지 다음 청크 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강이 사용하는 draft 키

학습자가 답변을 수정하면 같은 키 덮어쓰기. 청크를 스킵하면 키는 빈 문자열/빈 배열로.

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를 만들어볼 시간이에요.

이론 때 적어주신 내용을 정리해 보여드릴게요.

📝 자동화할 작업: <draft.task>
📝 트리거 표현: "<draft.trigger>"
📝 핵심 단계:
   - <draft.steps[0]>
   - <draft.steps[1]>
   - <draft.steps[2]>
📝 이름: <draft.skill_name>
📝 설명: <draft.skill_description>

이걸 토대로 실제 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}}

# 글로벌 스킬 폴더 (Claude Code 기준 — 다른 도구는 INSTALL.md 참조)
mkdir -p ~/.claude/skills/<draft.skill_name>

# 만든 SKILL.md를 그 폴더로 이동/복사
mv <임시 위치>/SKILL.md ~/.claude/skills/<draft.skill_name>/SKILL.md

{{/os}}

{{os:win32}}

# 글로벌 스킬 폴더 (Claude Code 기준)
New-Item -ItemType Directory -Force -Path "$HOME\.claude\skills\<draft.skill_name>"

# 만든 SKILL.md를 그 폴더로 이동
Move-Item "<임시 위치>\SKILL.md" "$HOME\.claude\skills\<draft.skill_name>\SKILL.md"

{{/os}}

다른 도구(Codex/Cursor/Gemini/Antigravity) 사용자라면 INSTALL.md의 글로벌 스킬 폴더 안내를 참조하세요. 강의 패키지 폴더 안에 임시로 두고 학습자가 나중에 옮기는 것도 OK입니다.

4-6. 호출 한 번 시연 + 검증

저장이 끝나면 학습자에게:

이제 만든 스킬이 잘 동작하는지 확인해볼게요.
{{name}}님이 사용하시는 에이전트한테 트리거 표현으로 시켜보세요.

  👉 "<draft.trigger>"

답이 나오면 그대로 붙여넣어 주세요.
(만약 에이전트가 새 스킬을 인식 못 하면, 에이전트를 한 번 *재시작*해야
할 수도 있어요. 자주 있는 일이에요.)

검증 기준

학습자가 결과를 붙여넣으면 점검:

→ 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] 헤더가 있는가
• 한 청크만 출력했는가 (36 문장 + 코드 01개)
• 끝에 ❓/🛠/🔀 중 하나가 있는가
• 자리표시자를 모두 채웠는가 ({{example:...}}, {{os:...}}, {{name}} 등)
• 도구명을 본문에 노출하지 않았는가
• 학습자가 시도하기 전에 답을 보여주지 않았는가
• 청크 통과 시 progress["02-skills"]를 갱신했는가
• 2강 추가: skill-creator 호출 안내 시 학습자 환경에서 실제로 시도하라고 했는가 (대신 호출하지 않기)

이 체크리스트를 응답 전마다 머릿속으로 점검하세요. 한 항목이라도 누락되면 학습 흐름이 깨집니다.