chalk-talk: 그림으로 설명하기
손으로 그린 설명을 만듭니다: 짧은 텍스트(.chalk)로 된 레시피를 작성하면, 이 스킬의 플레이어가 획 하나하나, 챕터별로, 짧은 내레이션과 (실제 수량이 있을 경우) 사용자가 움직일 수 있는 값과 함께 그려줍니다. 여러분은 레시피만 작성하면 됩니다; scripts/build.mjs가 이를 검증하고 모든 것이 포함된 하나의 HTML 파일을 빌드합니다. 직접 플레이어를 작성하거나 복사하지 마십시오. 아래 경로는 이 스킬 폴더를 기준으로 한 상대 경로입니다.
1. 먼저 그리기
일반적인 요청("X를 그림으로 설명해줘", "Y가 어떻게 동작하는지 그려줘")의 경우 묻지 말고 개요도 보여주지 말고 그리세요. 그림에 필요한 세 가지를 스스로 결정하고, 전달할 때 말하세요:
- 후크(hook): 아이디어와 연결되는 일상적인 사물로, 청중이 보거나 해본 적 있고 몇 가지 도형으로 그릴 수 있는 것 (카드 청구서, 버스 정류장, 카페 줄);
- 대상: 요청이 명시하는 대로, 그 외에는 호기심 많은 성인;
- 사용자가 움직일 값: 아이디어 속 실제 수량 (월 이자율, 분당 도착하는 사람 수), 또는 없음.
발표, 설득, 결정, 문서화 또는 상황 설명을 위한 그림(피치, 클라이언트를 위한 아키텍처, 포스트모템)은 백오브냅킨(back-of-napkin) 스킬이 설치되어 있을 경우 그 스킬의 몫입니다; 이 스킬은 가르치는 용도입니다.
수업, 학생, 강연 또는 과정을 위한 것일 때 ("수업을 위해" 참조), 요청이 두 가지 다른 의미로 해석될 수 있을 때, 또는 사용자가 먼저 계획을 보고 싶어할 때만 한 번에, 모든 것을 함께, 그리고 빠진 것만 물어보세요.
그림은 각각 한 챕터씩, 네 부분으로 구성됩니다: 후크를 질문으로 ("왜 R$ 1,000이 R$ 1,974가 될까?"); 분해하기 (실제 사물을 간단히, 그리고 그 안에 숨겨진 것); 아이디어 (움직이는 값과 함께 규칙, 흐름 또는 논증); 마무리 (결과를 강조하고 비교가 멈추는 지점).
2. 레시피 작성하기
아래 줄로 <id>.chalk를 작성하세요 — 일반적인 그림을 다룹니다; 다른 것은 먼저 읽을 필요가 없습니다. 종이는 900 × 560입니다 (size 900x780은 더 높은 칠판을 만듭니다), x는 오른쪽으로 y는 아래로 증가하며, 소품의 at은 그것이 서 있는 위치(하단 중앙)입니다; 가장자리에서 30px 여백을 두세요. # Title은 챕터를 열고 > sentence는 내레이션입니다: 둘 다 다음 단계로 넘어갑니다. 점은 공백 없이 x,y입니다; 표현식은 따옴표로 묶고 매개변수와 변수를 사용할 수 있습니다.
하나의 칠판입니다: 챕터는 종이를 지우지 않습니다. 분필로 칠판에 그린 것처럼 그려진 모든 것은 남아 있으므로, 쓰기 전에 전체 칠판을 계획하고 각 부분에 고유한 위치를 지정하세요 — 제목은 맨 위에 한 번, 후크와 실제 사물은 위쪽 절반에, 아이디어는 그 아래나 옆에, 마무리는 남은 공간에. 같은 위치에 두 가지를 그리지 마세요; 보통 12~25단계면 충분합니다.
상단:
title Juros compostos ↔ a fatura do cartão
locale pt-BR
size 900x560
param taxa "juros ao mês (%)" 1..15 step=1 = 8
switch atraso "pagar com atraso" off
var f = "1 + taxa/100"
learning goal "Ver o juro sobre o juro crescer mês a mês."
learning 줄 네 개를 모두 작성하세요 — goal, question (생각해볼 질문 하나), answer (현실에 기반한 답), caveat (단순화한 점) — 그리고 locale을 사용자의 언어로 설정하고, 모든 텍스트를 그 언어로 작성하세요.
사람과 사물은 **소품(props)**입니다: person, person-sitting, person-pointing, house, car, bus, coin, phone, document, server, bank, cloud, queue, desk, computer, clock, lock, money-arrow, tree, school, hospital, factory, truck, cart, safe, bulb, gear, database, robot, ship, container, warehouse, box, pallet, shop, shelf, field, cup, function, api-gateway, cache, cluster, board, book, pencil. 사람은 mood= happy, sad, surprised, worried 또는 idea를 사용합니다.
person ana at 150,330 "Ana" mood=worried
text "R$ 1.000 viram quanto?" at 40,64 size=36
text "paga só o mínimo" right-of ana gap 16 align=start
ana thinks "e se eu atrasar?" side=above width=200
ana -> banco "paga" -> loja "repassa"
arrow 60,350 -> 840,350 color=#2E8F62 stroke=3
highlight 90,500 -> 810,500 thickness=24
좌표를 계산하지 않고 배치하기 — 조각들이 나란히 있거나 서로 이어질 때 선호합니다. chain은 무언가를 전달하는 것들입니다: 종이에 펼쳐지고, 각각 다음 것과 연결되며, 요청 시 긴 화살표가 추가됩니다:
chain at 40,190 forward="o café desce" back="pedidos sobem"
field fazenda "fazenda"
truck caminhao "transporte"
cup cafe "cafeteria"
person voce "você"
row at 470,150 gap 14
repeat 3: coin size 44
repeat 3: coin at "100 + i*60",400 size 40
그 단계부터 계속 그 자리에서 움직이는 것 — spin, drive, steam (위로 올라가는 김이나 증기), talk, pulse 또는 float, 그리고 stop. 움직임이 무언가를 말할 때만 사용하세요 (트럭이 떠나는 것, 컵 위의 김), 그림 하나당 한두 개:
animate caminhao drive
미리 만들어진 애니메이션 이모지 — 사용자가 요청할 때만, 그리고 수업당 최대 하나 (정교하고 분필 같지 않음): celebrate, think, surprised, ok, idea 또는 time, at에 중앙 정렬; 또는 ./file.json, 사용자가 제공한 Lottie 파일, 레시피 옆에. 빌드 시 파일 내부에 크레딧과 함께 넣습니다 — 파일 크기는 약 340KB에서 약 610KB로 증가합니다 (플레이어와 애니메이션):
lottie celebrate at 720,180 size=120
값을 따라가는 숫자:
counter at 470,270 "1000*f^6" "R$ {v:0} em seis meses" size=34
bars box 90,320,440,180 values 1000,"1000*f^3","1000*f^6" labels hoje,"3 meses","6 meses" format="R$ {v:0}"
plot "1000*(1+taxa/100)^x" domain 0..12 range 0..4000 box 480,120,360,240
when atraso:
text "multa de 2%" at 600,100 color=#C8442C
소품으로 그릴 수 없는 것: 0–100 그리드(정수, y는 아래; 50,100에 서 있음)로 만든 다음 이름을 사용하세요:
define xicara
polygon 24,48 76,48 70,90 30,90 fill=#FFFFFF
curve 74,56 90,62 72,80
xicara minha at 450,300 "minha xícara"
사용자 대기 및 퀴즈 (둘 다 수업용):
pause ask "Quanto vai virar a fatura em seis meses?"
quiz "Se a taxa dobra, a fatura em seis meses…"
* mais que dobra o juro -- é juro sobre juro
- só dobra -- isso seria juro simples
유지할 사항: 하나의 칠판에 840단계; 아이디어가 바뀔 때만 짧은 내레이션; 제목 3644, 레이블 24~34, 22 미만은 사용 금지; 색상은 흑연(기본값), #2F5BEA, #C8442C, #2E8F62, #8C8578, 마커 #FFE45C, 강조색은 최대 세 가지; 사실과 숫자는 정확하게 — 인용문이나 수치를 절대 지어내지 마세요. 다른 단계(원, 곡선, 카드, 표, 축, 타임라인, 브레이스, 노트, 이동…)는 references/text.md에 있습니다; 각각이 그리는 것은 references/recipe.md에 있습니다. 위에 없는 단계가 필요하거나 빌드 메시지가 오류를 해결하지 못할 때만 열어보세요.
사용자가 Mermaid 다이어그램을 제공하면 그대로 유지하고 %% title …, %% # chapter 및 %% > narration 줄을 추가하여 <id>.mmd로 저장하세요 (references/text.md에 방법이 나와 있습니다). 사용자가 작업 중인 폴더에 레시피를 저장하거나, 사용자가 파일을 다운로드하는 출력 폴더가 있을 경우 (claude.ai에서는 /mnt/user-data/outputs) 그곳에 저장하세요.
3. 빌드 및 확인
node scripts/build.mjs <id>.chalk
레시피 옆에 <id>.html을 쓰고 다음을 출력합니다:
✗ text: line N …또는✗ contract: …(exit 1, 아무것도 쓰지 않음): 메시지가 지시하는 대로 해당 줄을 수정하세요. 아래 예시를 참고하세요.! review …(exit 3): 그려졌지만, 무언가가 종이를 벗어나거나, 텍스트가 다른 텍스트를 덮거나, 선이 텍스트와 교차합니다. 수정하고--snapshots와 함께 다시 빌드하세요:<id>.snapshots/<id>.contact-sheet.png도 작성합니다 — 모든 값 설정에서 모든 챕터를 보여줍니다. 해당 그림을 열고 리뷰에서 지명한 것과 읽기 어려운 모든 것(알아보기 힘든 도형, 빽빽한 모서리, 너무 작은 텍스트)을 수정하세요.✓ review, 또는• review … the page checks itself when opened(여기에는 브라우저 없음): 완료.• figures … defined: 레시피가define으로 도형을 만들었고, 리뷰가 그것만 측정합니다 — 연락처 시트를 한 번 열고 도형이 의도한 대로 읽히는지 확인하세요.✗ review not checked: …: 완료되었지만, 그림이 확인되지 않았다고 사용자에게 알리세요.
최대 두 번의 수정만 허용됩니다; 그런 다음 전달하고 남은 문제를 평이한 말로 설명하세요 ("15%에서 레이블이 제목에 닿습니다").
여러 레슨 (과정): 각각 하나의 레시피, 함께 빌드 — node scripts/build.mjs one.chalk two.chalk --out course.html --title "The course". README용 (이미지만 들어가는 곳), 요청 시: node scripts/build.mjs <id>.chalk --svg는 스스로 그리는 그림인 <id>.svg를 작성합니다; 레슨은 여전히 .html입니다.
4. 전달
.html 파일의 경로(또는 사용자가 파일을 다운로드하는 경우 파일 자체)와 함께, 선택한 사항과 변경 제안을 한 줄로 알려주세요: "신용카드 청구서에 연결했고, 이자를 공부한 적 없는 사람을 대상으로, 월 이자율을 움직일 수 있게 했습니다 — 다른 후크, 다른 대상 또는 변경할 사항이 있나요?" 그런 다음 무엇을 볼지 한 문장으로 설명하세요 ("다음을 누르세요; 3장에서 이자율을 움직여보세요"). 파일은 오프라인에서 열리며, 챕터, 종이 옆의 값, PNG, SVG, GIF 및 WebM 다운로드를 지원합니다 — 이메일로 보내거나 프로젝터에 사용할 수 있습니다.
발표용 (강연, 프로젝터 수업): --present와 함께 빌드하세요 — 페이지가 한 번에 한 챕터씩, 전체 화면으로 열리고 첫 번째 키와 함께 발표자 노트가 표시됩니다; 클리커의 PageDown이 넘어갑니다. PowerPoint용, 요청 시: --pptx (챕터당 하나의 슬라이드; steps는 클릭마다 그림을 키우고, video는 각 챕터가 스스로 그려지는 것을 포함하며), 내레이션은 발표자 노트로 포함됩니다.
수업을 위해
그림이 수업, 학생, 강연 또는 과정을 위한 것일 때, 한 번에 물어보세요, 하나의 메시지로: 최대 세 개의 후크, 가장 좋은 것부터, 각각 그 대상에게 효과적인 이유(references/hooks.md), 정확히 누구를 위한 것인지, 학생들이 움직일 수 있는 숫자는 무엇인지 포함하여. 이미 말한 것은 묻지 마세요. 그런 다음 네 부분으로 된 개요를 몇 줄로 보여주고 진행 허가를 기다리세요 ("pode", "go"). 레시피에는 theme chalkboard, 그 질문에 답하는 부분을 여는 pause ask, 그리고 마지막에 quiz가 추가됩니다.
코드 실행 불가 (아티팩트 대신)
코드를 실행할 수 없지만 HTML 아티팩트를 표시할 수 있는 경우, 레시피를 이 작은 페이지에 넣고 — 다른 것은 넣지 말고 — 표시하세요. 플레이어가 CDN에서 로드되고 레시피 자체를 확인합니다:
<!doctype html>
<meta charset="utf-8">
<title>LESSON TITLE</title>
<script type="text/chalk-talk" id="chalk-recipe">
THE RECIPE AS TEXT
</script>
<script src="https://cdn.jsdelivr.net/npm/[email protected]/player.js"></script>
페이지가 레시피를 열 수 없다고 표시하면, 지명된 줄을 수정하세요.
나중에 변경하기
"화살표를 파란색으로", "사람 한 명 더 추가", "5% 사용" 등: 요청한 것만 변경하고 나머지는 유지한 후 다시 빌드하고 변경된 사항을 말하세요. 다른 후크나 대상은 새로운 그림입니다.
절대 하지 말 것
assets/또는scripts/contract.mjs를 절대 편집하지 마세요: 생성된 파일입니다.- 레시피에 HTML, 링크, 스크립트 또는 이미지를 절대 넣지 마세요: 텍스트는 일반 텍스트이고, 색상은 16진수 또는 이름입니다.
- 레시피를 생성하는 스크립트를 절대 작성하지 마세요: 직접 작성하세요 (표현식과
repeat가 산술을 처리합니다). - 코드 실행 없이, 플레이어, SVG 또는 그림 이미지를 절대 직접 작성하지 마세요: 위의 작은 페이지를 사용하세요. 코드를 실행할 수도 아티팩트를 표시할 수도 없다면, 그렇게 말하고 레시피를 제공하세요.