상자 안의 부품 네 개
「에이전트 = 지침 + 스킬 + 도구 + 기억」은 교육용 비유예요. 실제로 일하는 건 Claude Code이고, 서브에이전트(도우미)는 그중 일부를 맡는 전문가예요.
CLAUDE.md · .claude/rules/세션을 열 때마다 먼저 참고하는 글. 권한을 막는 장치는 아님
.claude/skills/이름/SKILL.md필요할 때 꺼내 쓰는 작업 설명서.
/이름으로 부름도우미의
tools는 쓸 수 있게 열어 둔 도구 목록오늘은 CLAUDE.md에 직접 적어 두는 방식
조립된 로봇 = 도우미(서브에이전트) .claude/agents/이름.md — 입력창에 @agent-이름을 끝까지 쳐서 부릅니다(@만 치면 파일 · 폴더 목록이 떠요).
조립 전에 — 안전선
- 가상 자료만 씁니다. 이름을 지운 생기부 · 학생 답안 · 상담 기록도 넣지 않아요.
- Local은 실행 위치일 뿐, 입력한 내용과 읽은 파일 내용은 서비스로 넘어가 처리됩니다.
- 화면 공유 · 공유 zip · 노션 페이지도 마찬가지예요. 소속 학교나 기관의 지침을 따릅니다.
- 오늘은 활동지 · 형성평가 문항 · 수업 아이디어처럼 가상 자료로 할 수 있는 일만 맡깁니다.
내 출발선 고르기
1. 참가 경로
2. 내 폴더
3.2. 교과 트랙
내 교과 트랙: 준비해 온 파일을 자료/내교과/에 넣고, CLAUDE.md 맨 위 네 줄(학교급 · 학년 · 교과 · 적용 교육과정)만 내 교과로 고쳐요. 학생 정보는 넣지 않습니다.
내 교과 트랙: 준비해 온 내 단원 자료(.md)를 대화에 첨부해서 써요. 학생 정보는 넣지 않습니다.
칸 채우기 — 아래 프롬프트가 자동으로 바뀝니다
공통 트랙은 학교급 · 학년 · 교과 · 영문 이름 · 단원이 기술 사례로 고정돼요. 반복하는 일 세 가지는 내 실제 업무로 적어 주세요.
교과 영문 이름은 도우미 이름(영문-helper)이 됩니다. 영문 소문자 · 숫자 · 하이픈만 써요.
오늘의 조립 순서
| 시각 | 분 | 단계 |
|---|---|---|
| 20:00 | 10 | 안전선 · 접속 · 출발선 · 부품 네 개 |
| 20:10 | 10 | ① 설계지 |
| 20:20 | 25 | ②③ 도우미 만들고 불러 보기 |
| 20:45 | 5 | 쉬는 시간 |
| 20:50 | 25 | ④⑤ 스킬 두 개 · 도우미에 연결 |
| 21:15 | 10 | 도구 이야기 · MCP(설명) · ④⑤ 마무리 |
| 21:25 | 15 | ⑥ 상자에 담아 나누기 |
| 21:40 | 10 | 오류 해결 · 못 따라오신 분 합류 |
| 21:50 | 10 | ⑦ 기억 남기기 · 질의응답 |
폴더 열기
- 시작 폴더 zip을 짧은 경로에 풀기(예:
C:\ai\교과에이전트_시작) - Claude 데스크톱 앱 → Code → Local → Open folder… → 그 폴더
- 권한 모드가 Manual인지 확인(기본적으로 파일을 고치기 전에 허락을 물어요)
- 11/3
교수평설계폴더를 복사해 둡니다(원본은 그대로) - 추가 자료 zip을 복사본 안에 풀기 →
스킬틀/formative-quiz/·.claude/rules/gate-scope.md가 생겨요 - Claude 데스크톱 앱 → Code → Local → Open folder… → 복사본, 권한 모드 Manual
gate-scope.md는 「지침」 부품 가운데 rules 파일이 어떻게 쓰이는지 보여 주는 예시예요. 11/3에 만든 관문 규칙은 차시 흐름을 설계할 때만 거치게 하고, 활동지나 문항 같은 개별 차시 자료는 근거만 확인하고 바로 만들도록 해 줍니다.
- claude.ai → 설정 → 코드 실행(파일 만들기)을 켜 둡니다
- 자료 내려받기: 성취기준_예시.md · 평가계획_예시.md · 1_바라는결과.md · 2_평가설계.md (내 교과 트랙은 직접 준비해 오신 자료 사용)
- 스킬 내려받기: worksheet-maker.zip(claude.ai용)
설계지 — 어떤 일을 돕는 로봇인가
완성 예문: 「나는 중학교 3학년 기술 교사야. 매주 반복하는 일은 활동지 만들기, 확인 문항 만들기, 수행평가 안내문 쓰기이고, 오늘은 그중 「활동지 만들기」에 쓸 에이전트를 만들 거야.」
도우미(서브에이전트) 만들기
🔐 허락 창이 뜨면 「허용」: .claude/ 폴더는 보호 폴더라서, 편집 자동 허용 모드여도 도우미 · 스킬 파일을 저장할 때 따로 허락을 물어요. 「허용」을 누르지 않으면 파일이 만들어지지 않고 다음 단계가 막혀요. 허락 창에서 「이 세션 동안 이 프로젝트의 .claude 폴더 편집 허용」(Yes, and allow Claude to edit files in this project's .claude folder for this session)을 고르면 그 뒤로는 다시 묻지 않아요.
저장한 뒤 새 세션을 열고 「이 폴더에서 쓸 수 있는 서브에이전트 이름을 알려 줘」라고 물어 가 나오는지 확인해요. 파일을 읽기만 하는 검토관(review-assessor)과 달리, 이 도우미는 Write 권한이 있어서 새 파일을 만들고 저장할 수 있어요.
B 경로는 서브에이전트 대신 도우미 지침 글을 만들어 복사해 둡니다. ③부터 새 대화의 첫 메시지로 붙여 넣어요.
도우미 불러 보기
먼저 1 · 2단계 파일을 직접 열어서 읽어 보세요(11/3에 배운 교사 관문). 그래서 첫 줄이 「관문 통과」예요.
새 대화를 열고 성취기준_예시 · 1_바라는결과 · 2_평가설계준비해 온 내 교과 자료를 먼저 첨부한 뒤 아래를 보내요. 대괄호 자리에는 ②에서 만든 지침문을 붙여 넣어요.
복사한 글 맨 앞의 가 도우미를 직접 부르는 표기예요. 칠 때 파일 목록이 떠도 그대로 보내면 도우미가 불려요.
✔ 확인: 표에 적힌 「근거 자료 파일과 근거 문장」이 실제 파일 속 문장과 일치하는지 한 줄만 맞춰 보세요.
.claude/agents/에 넣고 새 세션스킬 1 · 활동지 — 스킬 먼저 만들고, 실행은 그다음
🔐 허락 창이 뜨면 「허용」: .claude/ 폴더는 보호 폴더라서, 편집 자동 허용 모드여도 도우미 · 스킬 파일을 저장할 때 따로 허락을 물어요. 「허용」을 누르지 않으면 파일이 만들어지지 않고 다음 단계가 막혀요. 허락 창에서 「이 세션 동안 이 프로젝트의 .claude 폴더 편집 허용」(Yes, and allow Claude to edit files in this project's .claude folder for this session)을 고르면 그 뒤로는 다시 묻지 않아요.
그다음 실행:
- claude.ai → Customize › Skills › Upload → worksheet-maker.zip 올리고 켜기
- 새 대화창에 근거 자료(성취기준)를 첨부하고 아래 내용을 보내요
스킬 2 · 형성평가 — 기본 틀을 복사해 고치고 도우미에 연결하기
🔐 스킬 폴더 복사 · 도우미 파일 수정 때도 허락 창이 떠요. 「허용」을 눌러 주세요.
실행한 뒤 정답과 해설이 맞는지 직접 확인:
연결 확인(도우미를 새로 불러야 바뀐 설정이 적용돼요):
✔ 정답 · 해설 · 성취기준 칸이 스킬 형식대로 나오면 연결 성공.
무료 채팅에서는 도우미를 연결하는 기능이 없어요. 이어지는 대화에서 원하는 형식을 직접 지정해 요청합니다.
노션 MCP — 바깥 도구 끼우기
- 연결 명령어는 터미널(데스크톱 앱 안의 터미널도 가능)에 입력해요:
claude mcp add --transport http notion https://mcp.notion.com/mcp→ Code에서/mcp로 노션 로그인 · 권한 허용 - 데스크톱 앱의 커넥터 설정 화면에서 연결해도 되고, claude.ai에 이미 연결해 둔 커넥터를 써도 돼요(같은 계정이면 Code에서도 그대로 보임)
- 기본 설정이 내 컴퓨터(local)에만 적용되므로 폴더를 공유해도 노션 연결 정보는 함께 넘어가지 않아요. 폴더를 받은 선생님이 본인 계정으로 다시 연결해야 합니다
- 연결해서 쓸 때는 도우미가 아니라 기본 Claude Code 대화창에 부탁해요(도우미의
tools목록에는 노션이 없기 때문) - 오늘은 설명만 하고 직접 연결하지는 않아요. 남는 시간에는 ④⑤를 마무리해요
상자에 담아 나누기 — 공유해도 되는 파일만
🔐 공유용/.claude/로 복사할 때도 허락 창이 떠요. 「허용」을 눌러야 도우미 · 스킬이 상자에 들어가요.
⑥-2 claude.ai용 스킬 사본 (강사 시연 · 후속 과제)
컴퓨터에서 만든 스킬은 CLAUDE.md 파일과 산출물/ 폴더가 있어야 작동하기 때문에, 그대로 웹에 올리면 작성 원칙이나 저장할 위치를 찾지 못해요. 웹용 사본을 따로 만듭니다.
웹업로드/worksheet-maker 폴더만 zip(zip 안에 worksheet-maker/SKILL.md). 파일 맨 위(머리말)에 적을 수 있는 설정 항목은 name · description · license · compatibility · metadata · allowed-tools뿐이에요.
SKILL.md 파일을 내 수업에 맞게 고쳤다면 worksheet-maker/SKILL.md 폴더 구조가 되도록 다시 압축해서 올려 보세요. 동료 선생님께도 그 압축 파일을 나눠 주시면 됩니다(학생 개인정보가 들어가지 않았는지 꼭 먼저 확인하세요).
기억 남기기 — 결정 기록 한 줄
새 세션을 열어 「이 폴더의 결정 기록을 요약해 줘」로 반영됐는지 확인 → 공유 zip은 다시 압축(이전 zip은 지우기).
내려받은 결정 기록 파일을 새 대화창에 첨부하고 「이 결정 기록을 요약해 줘」라고 입력해 확인해 보세요.
오늘 목표 달성 확인하기
연수 채팅에 「목표 · 만든 도우미 · 스킬 하나」「목표 · 도우미 지침 · 스킬 하나」를 남겨 주세요.
막힐 때
| 이럴 때 | 이렇게 |
|---|---|
| 2분 넘게 답이 안 와요 | 같은 요청을 여러 번 보내지 마시고 일단 강사 설명을 따라오세요. 해당 단계가 끝날 때까지 답이 없으면 실행을 멈춘 뒤 파일이 만들어졌는지 확인하고, 안 만들어졌다면 예비 파일을 내려받아 이어 가세요 |
| @를 치니 파일 · 폴더 목록만 떠요 | 정상이에요. @agent-도우미이름을 끝까지 쳐서(또는 붙여 넣어) 보내면 불려요 |
| 도우미가 안 불려요 | 파일 위치가 .claude/agents/이름.md인지, 맨 위 name:이 영문 소문자인지 확인 → 새 세션. 「도우미이름 서브에이전트에게 맡겨 줘」처럼 이름으로 부탁해도 돼요 |
| / 목록에 스킬이 없어요 | .claude/skills/이름/SKILL.md(폴더 안의 SKILL.md)인지 확인 → 새 세션 |
| 스킬만 만들라고 했는데 활동지까지 바로 만들어 버렸어요 | 괜찮아요. 만들어진 파일을 열어 한 번 확인하고 다음 단계로 넘어가세요. 다음부터는 첫 줄에 「지금은 ~만들지 말고」라는 문장을 꼭 넣어 주세요 |
| 「관문 통과 전에는 못 만든다」고 해요 | 11/3 폴더면 추가 자료의 .claude/rules/gate-scope.md가 들어갔는지 확인. 공통 트랙은 1 · 2단계 파일을 읽어 본 뒤 첫 줄에 「관문 통과」라고 적어 주세요 |
| 도우미가 스킬 형식을 안 따라요 | 도우미 파일 맨 위에 skills: [worksheet-maker, formative-quiz]가 있는지 → 새 세션에서 도우미를 다시 불러요 |
| 성취기준을 지어냈어요 | 「자료에 없는 성취기준은 [확인 필요]로 바꿔 줘」 |
| Code 탭이 없어요 | 오늘 쓰는 데스크톱 앱 Code 탭은 Pro · Max · Team · Enterprise 구독에서 쓸 수 있어요(Free 불가). 오늘은 무료 채팅(B 경로)으로 함께 실습해요 |