---
name: paper-report
description: 논문(arXiv ID/URL, DOI, PDF, 제목)을 한국 커뮤니티 정보글 스타일(음슴체, 짧은 호흡, 비속어 없음)의 해설로 만든다. 이야기꾼처럼 비약 없이 풀고 논문 그림·표·원문 문단을 인용 짤로 붙이며, 전작→이번 논문→후속작 계보와 저자·기관 맥락을 담는다. 모든 사실은 팩트 원장으로 검증한다. 결과는 폰 캡처 같은 파트 이미지, 흰 배경 게시글, X·스레드용 4:5 이미지로 뽑는다. "논문 해설", "논문 썰", "커뮤니티식으로 설명", "펨코식 정보글", "이 분야 계보 정리" 요청에 사용.
allowed-tools: Bash(uv run ${CLAUDE_SKILL_DIR}/scripts/*)
license: MIT
compatibility: Agent Skills를 지원하는 코딩 에이전트(Claude Code, Codex, Gemini CLI, Cursor 등)용. uv와 Chrome(또는 Chromium), 그리고 arXiv, Crossref, Semantic Scholar, OpenAlex에 접속할 네트워크가 필요하다.
---

# paper-report

입력은 사용자가 준 논문이다. arXiv ID나 URL, DOI, PDF 경로, 제목, 또는 `분야:주제`를 받는다. 아무것도 없으면 어떤 논문인지 묻는다.

논문 하나를 커뮤니티 정보글처럼 읽히는 해설로 만든다. 글에 들어가는 사실은 전부 원문과 팩트 원장으로 확인한다.

논문을 안 읽은 사람도 한 번에 따라오게 쓰는 게 목표다. 그러려면 설명에 빠진 단계가 없어야 한다. 논문이 결론만 말하고 건너뛴 곳은 그 단계를 채워 풀고, 어려운 개념은 장면으로 먼저 보여준 다음 이름을 붙인다. 형식은 한국 커뮤니티 베스트 정보글을 따른다. 한 줄에 한 호흡인 음슴체에 연도를 박은 연대기, 몇 줄마다 붙는 그림이 기본이다. 비속어는 쓰지 않는다.

## 좋은 레포트의 기준

일곱 가지를 모두 갖춰야 한다. 채점 기준은 `references/rubric.md`에 있다.

1. 정확성: 모든 사실이 원문에 근거한다. 원문의 확신 수준과 조건도 그대로 옮긴다.
2. 연계성: 질문 하나로 시작해 척추(질문 사슬)를 따라간다. 앞에서 깐 밑밥은 뒤에서 회수하고, 마지막엔 처음 질문으로 돌아와 답한 뒤 지금과 앞으로를 보여주며 닫는다.
3. 재미: 기대와 결과의 격차, 숨은 디테일, 인물 교차를 밑밥 뒤 펀치로 보여준다. 재미를 선언하지 않는다.
4. 설명력: 논문을 직관적으로 풀어낸다. 처음 보는 독자가 "왜?"라고 물을 곳마다 답이 페이지에 있어야 하고 비약은 걸음을 채워 설명한다. 괄호로 설명을 때우지 않는다.
5. 전문성: 쉬운 설명 옆에 정확한 설명을 짝으로 두고 논문 유형에 맞는 전문 재료(지표, 설정, 비교 실험, 측정 방법 등)를 다룬다.
6. 사회 맥락: 독자가 대상을 얼마나 아는지에 맞춰 도입하고 이 연구가 지금 어디쯤 와 있는지 날짜 박힌 사실로 짚는다.
7. 말투: 음슴체로 통일하고 한 줄에 한 호흡으로 쓴다. 커뮤니티 말투는 겉옷이고 바탕은 사람이 쓴 글이다. 틀로 찍은 나열, 정리 멘트, 공식 마무리 같은 AI 티를 남기지 않는다.

## 결과물

결과물은 작업 폴더 `reports/<slug>/`에 모인다.

| 파일 | 내용 |
|---|---|
| `paper.pdf`, `meta.json`, `text.txt` | 원문, 메타데이터, 페이지 표시가 붙은 본문 |
| `lineage.md` | 참고문헌 순위, 인용 문맥 문장, 후속작, 저자 정보 |
| `ledger.md` | 팩트 원장. 레포트의 모든 사실 주장의 근거 |
| `outline.md` | 기획서. 유형, 도입 질문, 척추, 밑밥과 회수, 파트 목록 |
| `figures/` | 원문 그림·표, 원문 문단 인용 크롭, 전작·후속작 그림, 앞부분 지도 1장 |
| `report.md` | 원고. 파트는 `---` 줄로 나눈다 |
| `viewer.html`, `post.html` | 흰 배경 게시글 |
| `gallery.html` | 파트 이미지를 한 장씩 넘겨 보는 짤 모드 |
| `social/NN_k.png` | X·스레드 공유용 4:5 이미지(1080×1350) |
| `cards/NN.png`, `post_NN.png` | 폰 캡처처럼 보이는 파트별 이미지(430px 폭, 3배율), 이어 붙인 긴 이미지 |

## 준비물과 스크립트

`uv`와 Chrome(또는 Chromium)이 필요하다. 선택으로 `S2_API_KEY`, `OPENALEX_API_KEY`, `CHROME_PATH`를 쓴다. 스크립트는 이 SKILL.md가 있는 폴더의 `scripts/`에 있다. 아래 명령의 `${CLAUDE_SKILL_DIR}`는 그 폴더다. Claude Code는 이 값을 자동으로 채운다. 다른 에이전트에서 `${CLAUDE_SKILL_DIR}`가 글자 그대로 보이면 스킬 폴더의 경로로 바꿔서 실행한다.

```bash
# 원문 PDF, 메타데이터, 텍스트
uv run ${CLAUDE_SKILL_DIR}/scripts/fetch_paper.py <입력> [--out reports] [--pdf 로컬PDF]
# 그림 자동 크롭 + 페이지 렌더 (기본 40쪽까지, --max-pages로 조정)
uv run ${CLAUDE_SKILL_DIR}/scripts/extract_figures.py <폴더>
# 수동 크롭. --bbox는 페이지 비율(0~1) x0,y0,x1,y1. --dest를 주면 그 폴더의 figures/에 저장
uv run ${CLAUDE_SKILL_DIR}/scripts/extract_figures.py <폴더> crop --page 3 --bbox 0.1,0.2,0.9,0.55 --name 이름 [--rotate 90] [--dest 본레포트폴더]
# 원문 문단 인용 크롭. --start 줄부터 --end 줄까지, 같은 단 안에서 줄 단위로 자름
uv run ${CLAUDE_SKILL_DIR}/scripts/extract_figures.py <폴더> quote --page 13 --start "첫 줄 구절" --end "끝 줄 구절" --name q_이름 [--full-width]
# 참고문헌 순위, 인용 문맥, 후속작, 저자
uv run ${CLAUDE_SKILL_DIR}/scripts/lineage.py <폴더> [--skip-s2] [--skip-openalex]
# 계보 타임라인이나 척추 지도 이미지 (레포트당 1장, 앞부분에만)
uv run ${CLAUDE_SKILL_DIR}/scripts/make_graphic.py <폴더> spec.json ...
# 말투, 그림, 팩트 추적 검사
uv run ${CLAUDE_SKILL_DIR}/scripts/check_report.py <폴더>
# 파트 PNG, 게시글, 짤 모드, 웹 게시용 파일
uv run ${CLAUDE_SKILL_DIR}/scripts/build_cards.py <폴더> --png --long --gallery --social [--artifact --artifact-title 이름]
```

## 절차

단계를 건너뛰지 않는다. 원장(4) 없이 기획(5)을, 기획 없이 집필(6)을 시작하지 않는다.

### 1. 원문 확보와 정독

제목만 받았으면 검색으로 arXiv ID나 DOI를 찾는다. `fetch_paper.py`로 받는다. PDF를 구할 수 없으면 사용자에게 요청하고 멈춘다. 초록만 보고 쓰지 않는다.

`text.txt`를 처음부터 끝까지 읽는다. 읽으면서 아래를 따로 적는다. 무엇을 찾을지는 `references/planning.md` 6절에 있다.
- 재미 재료: 숨은 디테일, 내부 불일치, 직관과 반대인 결과
- 전문성 재료: 설정, 비교 실험, 설계 이유
- 비약 지점: 논문이 결론만 말하고 이유는 부록·각주·참고문헌에 둔 곳. 집필 때 빠진 단계를 채운다.
- 구체 예시: 추상 개념마다 쓸 논문 속 예시나 실제 사례

### 2. 그림 준비

`extract_figures.py`로 원문 그림을 뽑고 쓸 그림은 열어서 확인한다. 그림은 논문 인용이 기본이다. 원문 그림·표, 설명하는 문장을 그대로 자른 인용 크롭(`quote`), 전작·후속작 그림, 수식, 제목부를 쓴다. 직접 만드는 정리 이미지는 글 앞부분의 지도 역할 1장까지다. `references/figures.md`를 따른다.

### 3. 계보와 사람 조사

`lineage.py`를 돌리고 `lineage.md`를 읽은 뒤 웹으로 보강한다. `references/lineage.md`와 `references/people-context.md`를 따른다. 전작·이번 논문·후속작의 저자 목록을 교차 비교하고 이 연구가 지금 사회에서 어디쯤 와 있는지(쓰임, 규모, 판도)도 조사한다. 갈래가 많으면 서브에이전트를 병렬로 띄워도 된다. 그 결과도 반드시 원장에 들어가야 한다.

### 4. 팩트 원장

`references/fact-check.md` 형식으로 `ledger.md`를 쓴다. 레포트에 들어갈 숫자, 날짜, 소속, 관계, 인용 수, 발언을 전부 ID(`F` 본문, `L` 계보, `P` 사람, `W` 웹)와 원문 인용, 위치로 적는다.

### 5. 기획

`references/planning.md`를 따라 결정하고 `outline.md`에 적는다.
1. 논문 유형을 고른다 (해결형, 발견형, 측정·데이터형, 이론형, 반박형, 정리형, 제안·관점형). 초록·서론이 첫 번째로 내세우는 주장으로 정한다.
2. 독자 친숙도와 이 연구가 지금 사회에서 어디쯤 와 있는지 판단하고 도입 질문을 정한다.
3. 유형에 맞는 척추를 세우고 마디마다 본문에서 부를 이름을 정한다. 예시 논문의 틀을 복제하지 않는다.
4. 밑밥과 회수 2~3쌍, 이 논문에 있는 재미 재료, 유형별 전문성 재료와 결정적 증거를 정한다.
5. 마무리를 정한다. 마지막 답 파트에서는 도입 질문에 더 정확히 답한다. 맺음 파트에서는 지금으로 연결하고 앞에서 쓴 장면 하나를 다시 꺼낸다. 다음에 확인될 일을 가리킨 뒤 3줄 요약으로 닫는다. 척추를 번호 순서대로 다시 나열하거나 매번 같은 전망 문구로 끝내지 않는다.
6. 파트 목록(첫 줄, 연결된 척추 마디나 밑밥, 요지, 그림, 원장 ID)을 짠다. 10~26파트. 소제목은 없고 첫 줄이 앞 파트를 받는다.

`outline.md`의 칸을 못 채우면 조사로 돌아간다.

### 6. 집필

`references/style-guide.md`를 다시 읽고 `outline.md`대로 쓴다. 특히 0절 "이야기꾼 원칙"을 따른다.
- 파트 안에 소제목을 쓰지 않는다. 각 파트의 첫 줄이 앞 파트의 마지막을 받아 이어간다.
- 사실을 말하는 줄 끝에 `<!-- F3 -->`처럼 원장 ID를 단다. 빌드할 때 지워진다.
- 그림은 `![무엇을 보여주는지 (출처)](figures/파일.png)`로 쓰고 앞 줄에 볼 곳을 적는다. 캡처 방식이나 사용 허락은 쓰지 않는다.
- 논문의 확신 수준과 조건을 그대로 옮긴다.

### 7. 검증과 채점

1. `check_report.py`로 ERROR를 0으로 만들고 WARN은 하나씩 판단한다.
2. 독립 팩트체크. 서브에이전트에게 `report.md`, `ledger.md`, `text.txt`, 전작 원문을 주고 `references/fact-check.md`의 지시문으로 검사시킨다. 서브에이전트를 쓸 수 없으면 파트별 원장 대조를 직접 다시 한다. 지적은 원문으로 확인한 뒤 고친다.
3. 흐름·설명 검토. `references/rubric.md`의 지시문으로, 처음 읽는 독자 입장에서 파트 경계의 연결과 비약·괄호 설명·밑밥 없는 라벨을 찾는다. "끊김"과 비약은 모두 고친다.
4. 윤문. 음슴체와 한 줄 한 호흡 줄바꿈은 그대로 두고 AI 티만 걷는다. `references/rubric.md`의 AI 티 검토 지시문으로 서브에이전트에게 원고를 읽힌 다음 걸린 줄을 `references/style-guide.md` 4절대로 고친다. 걸린 줄만 고친다. 유보를 단정으로 올리지 않고 새 비유를 심지 않는다. 사용자가 humanize-korean([im-not-ai](https://github.com/epoko77-ai/im-not-ai)) 스킬을 쓰고 싶어 하면 이 단계에서 돌려도 된다. 음슴체, 줄바꿈, `<!-- F3 -->` 태그를 지키라는 조건을 단다. 돌린 뒤에는 `check_report.py`를 다시 돌려 태그와 숫자 추적이 그대로인지 확인한다.
5. `references/rubric.md`로 일곱 항목을 채점한다. 정확성 3점, 나머지 2점 이상이 될 때까지 고친다.

### 8. 빌드

`build_cards.py <폴더> --png --long --gallery --social`을 돌리고 이미지 몇 장을 열어 확인한다. 웹으로 보여달라고 하면, Artifact 게시 도구가 있을 때 `--artifact --artifact-title "<짧은 이름>"`을 더해 `viewer_artifact.html`(게시글)이나 `gallery_artifact.html`(짤 모드)을 게시한다. 어느 쪽인지 말이 없으면 게시글을 올리고 짤 모드와 공유용 이미지도 있다고 알린다. 도구가 없으면 파일 경로를 알려준다.

### 9. 보고

제목, 파트 수, 결과물 위치, 채점 결과, 팩트체크에서 고친 것을 알린다. 확인하지 못해 뺀 내용이 있으면 맨 앞에 무엇을 왜 뺐는지 적는다. 결과물을 공개하려면 논문 그림의 라이선스를 확인하라고 알린다.

## 분야 모드 ("분야:주제")

1. 서베이 논문과 `lineage.py`로 랜드마크 논문 4~8편을 연도순으로 고른다.
2. 목록을 보여준 뒤 편마다 1~9단계를 반복한다. 편마다 폴더를 따로 만든다.
3. `reports/<분야>/series.md`에 편 순서, 한 줄 요약, 편 사이 관계(원장 L 항목)를 적는다. 편 사이에도 밑밥과 회수를 건다.

## 절대 규칙

- 원장에 없는 사실은 레포트에 없다.
- 비속어, 혐오 표현, 특정인 조롱을 쓰지 않는다. 비판은 원문에 적힌 한계와 출처 있는 반론으로만 한다.
- 음슴체로 통일한다.
- 인용 수, 소속처럼 변하는 정보에는 기준 날짜를 붙인다.

## 참고 문서

| 문서 | 언제 읽나 |
|---|---|
| `references/planning.md` | 정독할 때(재료 찾기), 기획할 때 |
| `references/style-guide.md` | 집필 직전, 윤문 직전 |
| `references/figures.md` | 그림 준비할 때 |
| `references/fact-check.md` | 원장 쓸 때, 검증할 때 |
| `references/lineage.md` | 계보 조사할 때 |
| `references/people-context.md` | 저자·기관·뒷얘기 쓸 때 |
| `references/rubric.md` | 집필 후 채점할 때 |
| `examples/transformer/` | 처음 쓸 때 한 번. 해결형 논문의 기획서, 원고, 원장 예시. 틀을 복제하지 않는다 |