teachme

name	teachme
description	Turn any topic into a searchable, themed handbook or full study material (reference, hands-on practice, narrative chapters, quiz/Q&A) written in the user's own language, quality-checked by a multi-agent review, and published to GitHub Pages as a static site. Detects topic and language from the user, proposes a structure that fits the topic, and deploys (private repo + public Pages; free accounts warned). Includes site-wide + in-page search, 6 color themes, optional SVG diagrams, per-language proofreading (strictest for Korean), and a pre-deploy secret scan. Use for requests like "/teachme", "make/build a handbook", "build a guide or docs site", "create study material", or in Korean "핸드북/가이드 사이트 만들어줘", "교재 만들어줘", "기술 문서 사이트 출판".
license	MIT
compatibility	Claude Code(권장) 또는 셸/`git`/`gh` 실행이 가능한 에이전트. 필요 도구 — git, gh(GitHub CLI, 로그인 필요), 네트워크(공식 문서 조회·배포). 산출물 비공개 저장소+공개 Pages는 GitHub Pro 가정(무료 계정은 공개 저장소로 안내). 대화형 질문 UI·멀티에이전트 오케스트레이션이 없는 환경에서는 옵션을 텍스트로 받고 검증이 단독 검토로 낮아질 수 있다.
metadata	{"version":"0.3.1","author":"beret21"}

Teach Me — 핸드북·교재 제작 스킬

주제 하나(TOPIC)와 작성 언어(LANG)를 받아, 일관된 품질·디자인·검색·배포로 핸드북/교재를 만들어 GitHub Pages에 출판하는 자립형 스킬이다. 콘텐츠만 갈아끼우면 어떤 주제·언어든 동일한 방식으로 제작된다. /teachme 로 호출하거나 "핸드북/교재 만들어줘" 같은 요청에 자동으로 동작한다.

명령 규격 — /teachme [서브커맨드] [옵션] "<주제>"

$ARGUMENTS를 다음 규칙으로 해석한다. 첫 토큰이 알려진 서브커맨드면 그것으로, 아니면 new로 간주하고 나머지를 주제로 본다.

서브커맨드

명령	하는 일
new "<주제>" (기본)	새 핸드북/교재 생성. 자료조사→구성제안→작성→검증→(테마)→배포. new는 생략 가능(/teachme "<주제>").
add <manual|examples|chapter|quiz> ["<주제>"]	기존 산출물에 섹션 추가.
theme <azure|graphite|ink|teal|amber|indigo>	기존 docs/에 테마 교체(apply-theme.sh 재적용) 후 재배포.
deploy	로컬 생성분 배포(계정/등급 확인 → §11.5 시크릿 스캔 → Pages).
verify	배포 사이트 검증(curl/Playwright) 또는 콘텐츠 재검수(§6/§7).
update [경로]	기존 docs/를 대상으로 대화식 수정·재검증·재배포(무거운 자동 재조회 아님 — 사용자가 고칠 곳을 말하면 반영).
doctor	환경 점검(아래 "환경 점검" 절).
help	이 명령 규격을 요약해 보여준다.

플래그(주로 new/add) — 미지정 값은 대화형(또는 텍스트)로 확인: --lang <ko|en|ja|…> · --theme <…> · --type <manual+examples|chapter|quiz|mixed> · --repo <slug>(미지정 시 폴더명 기본 제안) · --dir <PROJECT_DIR> · --owner <gh계정> · --private|--public · --deploy <github|local>(기본 github) · --no-verify(비권장·경고).

예: /teachme new "Vercel 사용법" --lang ko --theme teal --type manual+examples --owner beret21

인자 없이 /teachme만 오면 help처럼 간단 안내 후, 주제를 물어 new 흐름을 시작한다.

안전성 — 전체 권한(full access)으로 써도 되는 이유

이 스킬은 사용자의 파일·콘텐츠를 삭제하지 않는다. 하는 일은 생성·편집·배포뿐이다:

• 새 파일 생성(HTML·설정), 플레이스홀더 채우기, sed로 테마 색 치환(편집), git/gh/xattr로 저장소·Pages 배포. 검증 중 만드는 임시파일은 OS 임시 폴더의 스킬 자기 것뿐이다.
• 그래서 개입 없이 완주하려면 full access가 편하고, 그래도 되돌릴 수 없는 파괴가 없다.

참고: rm 차단·휴지통 이동 같은 정책은 개별 사용자 환경의 설정이지 이 스킬이 강제하는 것이 아니다. 원하면 스킬이 작업 폴더의 .claude/settings.json에 안전 가드를 넣어드릴 수 있다(옵트인):

{ "permissions": { "deny": ["Bash(rm:*)", "Bash(rmdir:*)"] } }

넣기 전에 사용자에게 물어보고, 넣었으면 알려 준다. 강제하지 않는다.

환경 점검 (/teachme doctor)

아래를 점검해 표로 보고하고, 문제마다 해결 명령을 제시한다(변경은 하지 않음):

• gh auth status — 로그인·활성 계정이 의도한 OWNER인지, 플랜 등급(gh api user --jq '.plan.name' → free면 "산출물 저장소가 공개됨" 안내).
• git 설치 여부, 클라우드 동기화 폴더면 .git 의 com.apple.fileprovider.ignore#P xattr 설정 여부.
• 스킬 자산 존재: references/BUILD_GUIDE.md, references/apply-theme.sh(실행권한), templates/*.html, assets/*.js.

시작하면 가장 먼저 할 일

1. 주제(TOPIC)를 확정받고, 언어(LANG)는 자동 인식한다. 주제는 스킬이 임의로 정하지 않는다. LANG은 사용자가 프롬프팅하는 언어를 자동 인식해 기본값으로 설정하고, "이 언어(예: 한국어)로 진행할게요 — 다른 언어로 원하면 알려 주세요" 정도로 가볍게만 확인한다(무거운 질문으로 막지 않는다. --lang이 오면 그대로). 함께 받을 파라미터: THEME(컬러 테마, 기본 azure), REPO(URL 슬러그 — 작업 폴더명에서 기본값 제안), OFFICIAL_SOURCES(공식 1차 자료), VERSION_TARGET, PROJECT_DIR(새 프로젝트 경로), OWNER(GitHub 계정 — 자동 고정 아님, 배포 전 gh auth status 확인).
2. 주제 성격에 맞는 구성안을 제안하고 승인받는다. 모든 섹션을 이론+실습으로 강요하지 않는다 — 실습이 무의미한 주제는 서술형 챕터로, 일부만 실습이면 혼합으로 제안한다. 교재라면 문제 풀이/Q&A(객관식·서술형·FAQ)를 선택적으로 덧붙인다(BUILD_GUIDE §2-A).
3. references/BUILD_GUIDE.md 를 끝까지 읽고 그대로 따른다. 제작·검증·보안·배포의 모든 절차가 거기 있다.

이 스킬에 동봉된 자산 (자립형 — 외부 의존 없음)

이 스킬/
├── SKILL.md                       이 파일
├── references/
│   ├── BUILD_GUIDE.md             범용 제작 지시서 (자료조사→제작→검증→보안→배포 전 과정)
│   ├── loanword-refinements.md    외래어 순화 판단 지침(한국어 검수 전용, §7)
│   └── apply-theme.sh             컬러 테마 적용기(배포 시 docs/ 의 브랜드 색 치환)
├── assets/                        docs/assets/ 로 복사할 검색 JS
│   ├── site-search.js             랜딩 전체검색 (DOCS 배열만 교체)
│   └── inpage-search.js           페이지 내 검색 (수정 없이 사용, SVG 라벨 보호 가드 포함)
└── templates/                     docs/ 로 복사할 HTML 골격 + 빈 파일
    ├── index.html                 랜딩(카드 그리드) 골격
    ├── Section_Manual.html        레퍼런스 매뉴얼 골격
    ├── Section_Examples.html      실습 예시 골격(초·중·고급 시나리오 카드)
    ├── Section_Chapter.html       서술형 챕터 골격(읽기 중심 — 실습 없는 주제용)
    ├── Section_Quiz.html          문제 풀이/Q&A 골격(객관식·단답·서술형·FAQ, 정답 클릭 토글 — 교재용 옵션)
    ├── .nojekyll                  (빈 파일)
    └── .gitignore                 시크릿(.env 등) 제외 + 미게시 파일 제외

모든 디자인 토큰·레이아웃·검색 스크립트 연결·홈 링크·검색 색인 전제는 템플릿에 이미 내장돼 있다. 새 핸드북은 템플릿을 복사한 뒤 {{플레이스홀더}}·[설명: …] 부분만 실제 내용으로 채우면 된다.

작업 흐름 요약 (상세는 BUILD_GUIDE.md)

1. 파라미터 확정 — TOPIC·LANG은 사용자 입력. REPO는 폴더명 기본 제안. 구성안(이론+실습/챕터/혼합)도 사용자 승인.
2. 공식 문서 조사 — 추측 금지. WebSearch/WebFetch로 OFFICIAL_SOURCES 확인, 버전·수집일 기록.
3. 자산 복사 — 이 스킬의 assets/·templates/를 PROJECT_DIR/docs/로 복사(BUILD_GUIDE §4).
4. 콘텐츠 작성 — LANG으로 서술(실습 코드는 영어, 고유명사는 원형 유지). 섹션 유형에 맞는 골격 사용.
5. 품질 검증(필수) — §6 내용 검증 하네스, §7.5 SVG 도식화(선별), §7 언어별 문법·표현 검수(한국어는 가장 엄격).
6. 컬러·검색·메타 마무리 — THEME 적용(apply-theme.sh), site-search.js의 DOCS 교체, 랜딩 날짜, CHANGELOG.md.
7. 보안·배포·검증 — 배포 전 시크릿 스캔(필수 관문, §11.5), 비공개 저장소 + 공개 Pages(main/docs), curl 200 + Playwright 렌더 검증.

핵심 원칙: 추측보다 확인(공식 문서에서 확인한 것만), 상대경로만(GitHub Pages base가 /<REPO>/), 검증 후 발행(§6·§7 통과 전 출판 금지), 보안 우선(시크릿이 없음을 확인하기 전 푸시 금지).