어려운 낱말을 읽는 그 자리에서 설명 — popup 스킬 사용법

무엇을 만들어 주나

글을 읽다 모르는 낱말 하나에 걸리면 그 문단 전체를 놓칩니다. popup 은 그 낱말 위에 작은 카드를 답니다. 마우스를 올리면(휴대폰은 탭, 키보드는 Tab) 카드가 열립니다. 모든 설명은 용어 사전 JSON 파일 한 곳에 있어서, 한 번 고치면 모든 페이지가 바뀝니다.

여기서 직접 해 보세요. 이 화면의 점선 밑줄 낱말(JSON, HTML, CSS 등)에 마우스를 올리면 SONUB 의 용어 팝업이 뜹니다. popup 스킬이 만드는 카드도 이런 모양입니다.

카드 한 장에 들어가는 것

1. 낱말 · 읽는 법 · 어느 분야의 말인지
2. 굵은 한 줄 뜻
3. 두세 문장의 설명
4. 쉽게 말하면 — 일상의 비유 하나
5. 예시 — 한 줄에 하나, 코드와 그 뜻
6. [복사] 단추가 있는 소스 코드 조각
7. 누르면 그 자리에서 카드가 바뀌는 관련 용어, 프로젝트의 더 깊은 페이지로 가는 "더 알아보기" 링크

설치

프로젝트 폴더의 터미널에서 실행하세요. 모든 프로젝트에서 쓰려면 -g 를 붙입니다. 설치한 뒤 에이전트의 새 세션을 시작해야 스킬을 읽습니다.

도구 popup.py 는 Python 3.8 이상만 있으면 됩니다(표준 라이브러리만 씁니다). 팝업 자체는 프레임워크도 빌드 단계도 없이 최신 브라우저 어디서나 돌아갑니다.

쓰는 법 — 에이전트에게 말로 부탁하기

Claude Code 에서는 /popup 뒤에 무엇에 집중할지 적고, 다른 에이전트에서는 "popup 스킬로 …"라고 말하면 됩니다. 요청이 좁을수록 그 부분만 정확하게 합니다.

에이전트가 하는 일 — 일곱 단계

1. 대상 찾기 어느 페이지·파일·부분인지 정하고, 프로젝트에 이미 있는 용어 사전이나 툴팁이 있는지 먼저 찾습니다. 있으면 그것을 넓히고 두 번째 팝업 체계를 만들지 않습니다.
2. 처음 한 번 준비 popup.py init 이 popup.js 와 popup.css 를 복사하고, 고른 언어의 빈 용어 사전과 설정 파일 .popup.json 을 만듭니다. 그다음 레이아웃에 두 줄을 넣습니다.
3. 점검 popup.py audit 이 문서마다 이미 사전에 있는 용어와, 설명이 없는 후보(약어·camelCase·코드 낱말)를 보여 줍니다. 내 언어의 낱말은 스크립트가 고르지 못하므로 에이전트가 글을 읽고 고릅니다.
4. 고르기 처음 보는 사람이 멈출 말, 모르면 문단 전체를 놓치는 말, 프로젝트 여러 곳에 되풀이되는 말을 고릅니다. 일상어와 본문이 바로 설명하는 말은 뺍니다.
5. 쓰기 프로젝트가 내놓는 모든 언어로, 확인한 사실만 씁니다. 항목을 파일 하나에 모아 popup.py add --dry-run 으로 미리 본 뒤 합칩니다. 이미 있는 항목은 --overwrite 없이는 덮어쓰지 않습니다.
6. 붙이기 main 과 article 안의 평문은 저절로 감쌉니다. 활용형과 문장은 data-term 으로 직접 표시하고, 링크·카드·제목 옆에는 ? 단추를 둡니다. GitHub 에서 읽는 Markdown 에는 GLOSSARY.md 와 링크를 붙입니다.
7. 확인 popup.py check 로 사전을 검사하고, 브라우저에서 마우스 올리기·떠나기·클릭·관련 용어·Esc·Tab·좁은 화면·다른 언어를 직접 봅니다. 확인하지 못한 것은 보고에 적습니다.

도구 popup.py — 직접 돌려도 됩니다

popup.py 는 설치한 스킬 폴더의 scripts 안에 있습니다(예: .claude/skills/popup/scripts/popup.py). 아래 상자에는 짧게 popup.py 로 적었습니다. 경로는 git 저장소 맨 위의 .popup.json 에서 읽습니다.

팝업 키트를 복사하고 용어 사전(팝업 단추 이름 17개 언어 내장)과 .popup.json 을 만들기

python3 popup.py init --locales en,ko 복사

문서가 쓰는 용어와, 설명이 없는 전문 용어를 쓰인 파일 수 순으로

python3 popup.py audit docs/guide.md 복사

용어를 사전에 합치기 — 검사를 통과하지 못하면 아무것도 쓰지 않고, 새것이 없으면 “nothing to change”

python3 popup.py add new-terms.json --dry-run 복사

모든 언어의 필드, 언어마다 같은 예시 코드, 관련 용어 id, 링크 대상, 용어끼리 겹치는 표기 검사(오류면 종료 코드 1)

python3 popup.py check 복사

항목 하나 보기(없으면 비슷한 id 를 제안)

python3 popup.py show api --locale ko 복사

사전을 Markdown 페이지(GLOSSARY.md)로 — 용어마다 앵커

python3 popup.py md 복사

Markdown 파일마다 용어의 첫 등장을 GLOSSARY.md 로 링크 — 마우스를 올리면 한 줄 뜻(--write 가 없으면 미리 보기만)

python3 popup.py link docs --write 복사

붙인 링크를 다시 걷어 내기

python3 popup.py link docs --unlink --write 복사

웹 페이지에 붙이기

빌드 단계가 없습니다. 페이지(또는 레이아웃)에 아래 두 줄을 넣으면 popup.js 가 용어 사전을 읽어 본문의 용어를 찾습니다.

<link rel="stylesheet" href="/popup/popup.css">
<script defer src="/popup/popup.js" data-glossary="/popup/glossary.json"></script>

용어 사전 JSON — 설명은 모두 여기에

페이지에는 용어 id 만 두고, 설명은 이 파일 한 곳에 씁니다. 언어마다 term·short·long 은 꼭 쓰고, easy·example·code·reading 은 선택입니다. id 는 한 번 쓰면 바꾸지 않습니다.

{
  "defaultLocale": "en", "locales": ["en", "ko"],
  "categories": { "web": { "en": "Web", "ko": "웹" } },
  "terms": {
    "api": {
      "category": "web", "aliases": ["API", "APIs"], "related": ["endpoint"], "href": "../docs/api.md",
      "text": {
        "en": { "term": "API", "short": "…", "long": "…", "easy": "…", "example": "`GET /users/42` asks for user 42" },
        "ko": { "term": "API", "reading": "에이피아이", "short": "…", "long": "…" }
      }
    }
  }
}

표시하는 방법

main · article · [data-popup-root]

저절로 — 이 영역 안 평문에서 각 용어의 첫 등장을 감쌉니다

<span data-term="api">APIs</span>

활용형, 그리고 저절로 찾으면 안 되는 구절·문장

<button class="popup-info" data-term="api"></button>

링크·카드·제목 옆의 ? 단추 — 휴대폰과 키보드용

<a href="/docs/api" data-term="api">

링크에 달면: 마우스를 400ms 머물면 미리 보기, 누르면 원래대로 이동

data-popup-scope="shell"

같은 낱말이 그 부분에서만 다른 뜻일 때

PopupGlossary.apply(element)

단일 페이지 앱이 다시 그린 뒤 새 내용 감싸기(두 번 감싸지 않음)

React·Vue·Svelte, MkDocs·Docusaurus·VitePress, 서버 템플릿, 앱에서도 씁니다. 스택마다 붙이는 법은 스킬의 references/integrate.md 에 있습니다.

GitHub 에서 — README 와 Markdown

GitHub 는 JavaScript 를 돌리지 않으므로 Markdown 에는 팝업 대신 링크를 씁니다. popup.py md 가 GLOSSARY.md 를 만들고, popup.py link 가 파일마다 용어의 첫 등장을 그 페이지로 잇습니다. 링크 제목이 한 줄 뜻이라 마우스를 올리면 뜻이 보입니다. 코드 블록·제목·앞머리는 건드리지 않고, 표 안의 | 는 \| 로 바꿔 표가 깨지지 않습니다.

Call the [API](../GLOSSARY.md#api "The agreed way one program asks another for something") with an API key.

읽는 사람은 이렇게 씁니다

• 마우스를 올리면 열리고 떠나면 닫힙니다. 낱말에서 카드로 옮겨 가는 동안은 닫히지 않습니다.
• 누르면 카드가 고정되어 코드를 복사하거나 링크를 누를 수 있고, 다시 누르면 닫힙니다.
• 관련 용어 칩을 누르면 카드가 그 자리에서 바뀝니다.
• Tab 으로 낱말에 가면 열리고, Enter 로 카드 안으로 들어가며, Esc 로 닫으면 포커스가 낱말로 돌아옵니다.
• 휴대폰(640px 이하)에서는 아래에서 올라오는 시트로 보이고, 큰 화면의 아래쪽 낱말에서는 카드가 위로 뒤집혀 열립니다.
• 오른쪽에서 왼쪽으로 쓰는 언어와 다크 모드를 따르고, 한국어 조사·아랍어 접두사·중국어와 일본어처럼 글자마다 맞는 방법으로 낱말을 찾습니다.