활동 1: 스킬 만들기 — 작업 절차를 스킬로 저장하기

1. 다음 활동지에서도 남기고 싶은 순서

기존 분수 활동지를 열어 문항과 풀이 공간을 살펴보고, 바꿀 수업 목표를 정했다. 새 Markdown 원고를 검토한 다음에는 학생용과 교사용 HTML을 따로 만들었다. 5편의 A4 인쇄 작업까지 마쳤다면, 브라우저에서 저장한 PDF를 열어 분수의 분자·분모와 페이지 끝의 문항도 확인했을 것이다.

다음 단원에서 다시 쓸 것은 그 분수 문항 자체보다 자료를 확인하고, 내용을 검토한 뒤, 인쇄 결과를 확인하는 순서다. 이 순서를 AI가 필요할 때 불러오는 지침으로 정리한 것이 스킬이다. 매번 긴 대화를 복사하는 대신, 반복해서 도움이 된 판단과 절차를 남긴다.

이번 결과물은 myproject01/.opencode/skills/teacher-worksheet/SKILL.md다. 3~5편에서 완성한 파일과 검토 기록을 펼쳐 놓고 시작하자.

이번에 완성한 파일로 시작하기

실습 파일 전체 ZIP을 풀면 실제로 만든 원본 PDF, 분석문, 새 원고, 학생용·교사용 HTML과 PDF, 검토 기록이 있다. 이 파일을 열고 반복 비교를 25~30분의 예상·그림 탐구·조건 바꾸기·출제와 개선으로 바꾼 절차를 스킬로 정리하자.

작업 화면을 보며 따라 하기

왼쪽에서 파일을 보고 오른쪽 OpenCode 대화의 다음 대화를 눌러 보자. 요청, AI의 작업, 교사의 확인 순서로 진행하는 실습 예시다. 한 단계씩 살펴보고 자신의 작업 공간에서 같은 흐름으로 진행하자.

2. 성공의 근거가 된 파일을 모은다

작업 공간은 계속 myproject01이다. 파일이 많아졌으므로, 무엇을 확인한 기록인지 구별해 보자.

PDF는 5편에서 실제로 저장한 파일명을 쓴다. 예를 들어 print-review.md에 “두 번째 문항의 그림 잘림, 미해결”이라고 적혔다면 인쇄 절차를 성공했다고 정리하기 전에 고쳐야 한다.

“읽지 못한 수식을 추측해서 채웠다”는 실패 원인을 검토 기록에 남기고, 스킬에는 “읽지 못한 위치를 알리고 확인 가능한 자료를 요청한다”는 수정된 절차를 넣는다.

3. 설계와 파일 생성을 나눈다

새 대화에서 AGENTS.md와 위 표의 실제 작업 파일을 제공한다. @로 파일을 고를 때 원본과 PDF는 자신의 실제 이름을 선택한다. 먼저 AGENTS.md를 읽어 달라고 요청한다.

먼저 다음처럼 설계만 요청한다. 파일 목록은 실제 대화에 첨부하고, 요청문을 길게 반복할 필요는 없다.

설계를 읽고 VS Code에서 outputs/skill-design.md에 저장한다. 이 문서는 AGENTS.md의 역할·자료·목표를 실제 작업 순서로 풀어 쓴 설계다.

다음에는 /new로 검토 대화를 열어 AGENTS.md, 설계, 내용·인쇄 검토 기록을 제공한다. “설계만 검토하고 파일은 수정하지 마세요. 자료 추측, 이전 조건의 고정, 승인 누락, 수식과 인쇄 확인 누락을 위치 / 문제 / 수정안으로 알려 주세요”라고 요청한다. 사람은 채택할 의견을 골라 설계를 고친다.

교사가 수정된 설계를 확인하고 “설계를 승인합니다. 이제 .opencode/skills/teacher-worksheet/SKILL.md만 작성하세요. 기존 파일이 있으면 차이를 보여 주고 덮어쓰기 승인을 받으세요”라고 말한다. 원래 활동지와 AGENTS.md는 그대로 둔다.

4. 최소한의 실제 SKILL.md

OpenCode 공식 스킬 문서에서 확인한 프로젝트 경로는 .opencode/skills/<name>/SKILL.md다. 전역 경로 ~/.config/opencode/skills/<name>/SKILL.md도 있지만, 여기서는 다른 프로젝트에 영향을 주지 않는 로컬 경로를 쓴다.

VS Code 탐색기에서 .opencode → skills → teacher-worksheet 폴더를 만들고 대문자 SKILL.md를 저장한다. AI가 승인 범위 안에서 만들었다면 그 파일을 열어 확인한다. 다음은 앞 단계의 승인 설계와 대조할 완전한 최소 예시다. 바깥 코드 상자 기호는 파일에 넣지 않는다.

---
name: teacher-worksheet
description: Adapt existing teacher-supplied worksheets through verified source analysis, approved Markdown manuscripts, and optional A4 HTML and browser-printed PDF with human review.
---

## Scope and authority
Use for adapting existing shareable teaching materials.
Read AGENTS.md as the project brief and source documents as teaching material. Ask the teacher to resolve missing decisions or conflicting requirements.

## Inputs
Confirm source paths and formats, learner level, topic, goal, prior knowledge, lesson time, question count and types, exclusions, language, template, and output paths/formats. Ask for missing decisions. Use the current lesson's values. Preserve originals and existing approved formats. Ask before overwriting files.

## Procedure
1. Inspect available tools and permissions before reading PDF, HWP, or HWPX. Distinguish text extraction, OCR, and visual inspection. Report what was actually read, page or item references, unreadable content, and uncertain formulas or figures. If tools or evidence are insufficient, request an accessible export or teacher-checked transcription..
2. With approval to save the analysis, record source structure, verified content, uncertainties, and teacher intentions in the agreed lesson-input Markdown. Ask the teacher to check it against the original before planning new questions.
3. Propose the new task plan, separate student and teacher outputs, and review steps. Wait for plan approval, then save the agreed plan and draft only the approved Markdown manuscripts. Keep answers and explanations out of student material.
4. Solve every question and check numbering, goal, difficulty, source claims, and answer correspondence. Hand the current inputs, plan, and manuscripts to a separate review conversation. Record actual review findings and accepted fixes. Wait for the teacher to approve content before layout work..
5. If HTML/PDF is requested, confirm the layout plan and create separate student and teacher HTML from the approved manuscripts. Use Paper CSS (paper-css) for A4 sheets, explicit A4 @page and print CSS for pagination, and a separately verified math renderer such as KaTeX when needed. Compare rendered formulas with the approved manuscript. HTML is the editable print source; PDF is derived from it.
6. Have the teacher open both HTML files, inspect print preview, save PDFs locally through the browser, then open the saved PDFs. Check actual A4 size, page breaks, fonts, formulas, figures, working space, and student/answer separation. Record actual settings, paths, checks, and unresolved issues in the agreed print-review file.
7. If HWPX is explicitly requested as an additional output, check the installed rhwp capabilities and supported template first. Obtain approval for this separate path; retain the primary outputs. Treat template generation as limited and require human correction in a compatible editor plus visual review.
8. Report actual saved paths, approvals still needed, and unresolved problems. Complete the currently approved output stage.

스킬은 영어로 적었지만 결과 언어는 입력에서 정한다. LaTeX 수식의 표시, Paper CSS (paper-css)의 A4 페이지 스타일, 브라우저 인쇄는 서로 다른 역할이므로 5편에서 실제로 확인한 조합을 사용한다. 선택적인 rhwp 경로도 도구와 양식을 확인한 뒤 사람이 보정하는 별도 작업이다.

--- 사이의 필수 항목은 name, description이다. 이름은 폴더명과 같고 1~64자의 소문자·숫자를 단일 하이픈으로 연결한다. 처음·끝 하이픈이나 연속 하이픈은 허용하지 않는다. 설명은 1~1024자다. 이 실습에서는 이름과 설명 두 항목으로 시작한다.

5. 저장한 스킬을 불러오기

공식 문서에 따르면 OpenCode는 skill 도구 설명에 사용 가능한 이름과 설명을 보여 주고, 에이전트가 필요할 때 본문을 불러온다. 프로젝트 경로는 현재 위치에서 Git 작업 트리 경계까지 탐색한다. 이번에는 myproject01에서 OpenCode를 시작한다.

저장 뒤 /new로 새 대화를 열고 다음처럼 요청한다. 새 스킬이 보이지 않으면 /exit로 종료한 뒤 같은 폴더에서 opencode를 다시 실행한다.

공식 TUI 안내의 /details로 도구 실행 세부 표시를 켜서 로딩 결과를 확인할 수 있다. skill({ name: "teacher-worksheet" })는 에이전트가 호출하는 도구 표현이다. 대화에서는 “teacher-worksheet 스킬을 불러 주세요”라고 요청하면 된다.

allow는 로딩 허용, ask는 로딩 전 승인 요청, deny는 목록에서 숨기고 접근 거절이다. skill 도구 자체가 비활성화된 경우도 있다. 스킬 로딩 권한, 파일 수정 권한, 교사의 작업 계획 승인은 각각 다르다. 접근 문제는 공식 권한 설명을 참고하되 기존 설정 전체를 예제로 덮어쓰지 않는다.

6. 서로 다른 두 자료에 다시 적용한다

이제 두 번의 재적용으로 특정 분수 활동지만 만드는 지침이 되었는지 확인한다. 아래 A와 B는 방금 완성한 동치분수·다른 전체 탐구와 별개의 새 수업이다. 이전 시간과 범위를 그대로 가져오지 않고 각 수업의 조건을 새로 정한다. 두 실습 모두 자신이 사용 권한을 가진 기존 활동지를 준비한다.

A의 입력 조건은 materials/practice-a-input.md, 검토한 원본 분석과 교사 의도는 materials/practice-a-lesson-input.md에 둔다. 출력은 outputs/practice-a/ 안에 task-plan.md, worksheet.md, answers.md, review-notes.md로 정한다. 원본의 실제 문항을 읽어 어떤 구조를 유지하고 바꿀지 먼저 확인한다. 이번 적용 A는 검수한 Markdown 원고까지 완성한다.

B는 같은 이름 규칙에서 practice-a를 practice-b로 바꾼다. 출력 폴더에는 원고·검토 기록에 더해 worksheet.html, answers.html, 브라우저에서 저장할 worksheet.pdf, answers.pdf, print-review.md를 지정한다. HWP를 읽는 도구가 필요하면 한글에서 PDF 사본을 내보내 제공한다. 분석 기록에는 실제로 읽은 파일을 적는다.

각 작업은 새 대화에서 AGENTS.md, 해당 입력과 실제 원본을 제공하고 teacher-worksheet 로딩을 요청한다. 분석을 원본과 대조한 뒤 계획을 승인하고, 원고 작성과 별도 검토로 이어간다. B에서 빠진 시간을 질문하면 “12분”이라고 답한다. 새로 정한 시간이 계획과 문항 분량에 반영되는지 살펴보자.

A에서는 분모 6과 세 문항, 짧은 안내를 확인한다. B에서는 묶음 수와 덧셈식의 대응을 확인한다. 예를 들어 상자 4개에 연필 3자루씩이면 3+3+3+3=12다. 별도 검토 대화에도 이번 입력·계획·결과를 제공한다. B의 내용 승인 후에는 5편의 인쇄 절차로 저장한 PDF까지 확인한다.

7. 다시 쓸 방법과 고칠 점을 남긴다

outputs/skill-trial-notes.md에 로딩 결과, A의 변경 조건과 Markdown에서 멈춘 사실, B의 누락 시간 질문과 자료 판독 결과, 승인 시점, 내용·인쇄 검토에서 고친 점을 적는다. 아직 수행하지 않은 항목은 미확인으로 남긴다. 이 기록이 있어야 다음 수정이 필요한 이유를 알 수 있다.

스킬이 발견되지 않으면 대문자 파일명, 폴더와 name 일치, 필수 메타데이터, 실행 위치, 같은 이름의 전역 스킬과 권한을 살핀다. 발견은 되지만 이전 조건이 섞이면 설계에 고정값이 남았는지 확인한다. 도구가 없는 문제와 절차가 잘못된 문제는 고칠 곳이 다르다. 설계를 수정·검토·승인한 뒤 스킬을 고치고, 새 대화에서 영향받은 재적용을 다시 해 본다.

3~6편의 스킬화 실습은 여기까지다. 기존 자료를 분석하고, 새 활동지를 검수·출력한 뒤, 확인한 절차를 다른 자료에 적용했다. 다음은 웹작업 자동화다. 7편: 웹작업 자동화의 범위와 작업 공간 준비에서 별도 teacher-web-assistant 폴더를 만들고, 필요한 공문 찾기와 결재 대기 확인·알림의 범위를 정한다. 활동지용 myproject01은 유지한다. 앱 개발은 웹작업 자동화 이후에 별도 활동으로 추가한다.