korean-report-skills
Claude가 쓴 글이 어딘가 이상할 때
내용은 올바르더라도 번역체, 모호한 수치, 들쭉날쭉한 페이지 배치가 남으면 문서는 아직 초안처럼 보입니다.
korean-report-style은 문체와 근거를 다듬고, korean-report-doc은 그 내용을
일관된 layout으로 구성한다. 이어서 HTML typesetting과 렌더 검사를 수행하고,
필요하면 PDF와 검수용 스크린샷까지 만듭니다.
여기서 layout은 페이지와 요소의 배치를, typesetting은 CSS·글꼴·수식을 반영해
최종 HTML을 만드는 처리 단계를 뜻한다.
글만 다듬을 때는 korean-report-style을 사용한다. HTML이나 PDF까지 필요할 때는
korean-report-doc을 함께 사용한다. Claude Code, Codex, Cursor, OpenCode에서
사용할 수 있다.
두 스킬의 역할
| 스킬 | 맡는 일 | 결과 |
|---|---|---|
korean-report-style | 문체, 프레이밍, 용어, 상태·근거 표기, 편집 후 정합성 검토 | 수정 원고와 lint 결과 |
korean-report-doc | 문서 구조, paper·deck 모드의 layout, 도해, 수식, HTML typesetting, 렌더 QA | 자립형 HTML과 선택적 PDF |
문체 스킬은 어미만 바꾸는 교정기가 아닙니다. 실측과 추정을 구분하고, 주장에 근거가 있는지 확인하며, 리스크와 대응이 함께 적혀 있는지도 살핍니다. 문서 스킬을 함께 쓰면 이 검토를 공통 디자인 시스템과 브라우저 렌더 검사까지 이어갑니다.
사용 예
설치한 뒤에는 평소처럼 작업을 요청하면 된다.
지난주 벤치 결과로 기술보고서를 작성해 줘.
이 문단을 외부 협력사에 전달할 보고 문체로 수정해 줘.
이 진행현황에서 미측정 수치와 근거가 없는 주장을 표시해 줘.
회의에서 검토할 쟁점과 결정 요청을 가로형 협의자료로 만들어 줘.
스킬 이름을 직접 적을 필요는 없다. 명시적으로 선택하려면 Codex에서는
$korean-report-doc, Claude Code에서는 /korean-report-doc처럼 요청할 수 있다.
설명이나 요약만 요청하면 대화 안에서 답하고, 별도의 문서 파일은 만들지 않는다. HTML이나 PDF처럼 완성된 산출물을 요청하면 문서 제작 절차를 시작한다.
결과물
문서의 목적에 따라 paper와 deck 중 하나를 선택한다.
| 항목 | paper | deck |
|---|---|---|
| 잘 맞는 문서 | 기술보고, 벤치마크, 진행현황, 연구노트 | 회의자료, 아젠다, 협의자료, 의사결정 요청 |
| 방향 | 세로 | 가로 |
| 페이지 흐름 | 내용이 이어지는 연속 문서 | 한 섹션을 한 페이지에 배치 |
두 모드는 글자 크기와 페이지 구조, 인쇄 규칙이 다릅니다. 하나의 문서 안에서는 두 모드를 섞지 않는다.
완성된 HTML은 CSS, 사용된 KaTeX CSS와 글꼴을 한 파일 안에 담는다. 실행할 때 외부 자원을 요청하지 않으므로 네트워크가 없는 환경에서도 열고 인쇄할 수 있다. PDF는 이 HTML을 자동화 브라우저로 인쇄해 만듭니다.
아래 이미지는 같은 가상 원고를 브라우저 기본 스타일로 저장한 HTML과 paper 모드로
typesetting한 결과를 나란히 보여준다.
| 브라우저 기본 스타일 | paper 모드 적용 |
|---|---|
 |  |
문체 규칙은 표현뿐 아니라 수치의 상태, 주장과 한계, 의사결정 요청의 근거에도 적용된다.
전후 원고와 규칙별 근거는 examples/before_after.md에서 볼 수 있다. 예시에 등장하는 기업, 공정, 인물, 수치는 모두 가상이다.
설치
| 환경 | 권장 설치 방식 | 설치 식별자 |
|---|---|---|
| Claude Code | GitHub marketplace 플러그인 | korean-report@korean-report-skills |
| Codex | GitHub marketplace 플러그인 | korean-report@korean-report-skills |
| OpenCode | npm 플러그인 | korean-report-skills |
| Cursor | npm 파일 복사 | korean-report-skills |
Claude Code
/plugin marketplace add JangHyun-bin/korean-report-skills
/plugin install korean-report@korean-report-skills
Codex
codex plugin marketplace add JangHyun-bin/korean-report-skills
codex plugin add korean-report@korean-report-skills
OpenCode
opencode.json의 plugin 배열에 npm 패키지를 등록한다.
{
"$schema": "https://opencode.ai/config.json",
"plugin": ["korean-report-skills"]
}
OpenCode를 다시 시작하면 package의 config hook이 두 스킬의 경로를 추가한다.
이 방식에는 별도의 npm i -g나 npx 복사가 필요하지 않는다.
Cursor와 파일 복사 설치
npx 설치기는 Claude Code, Codex, Cursor의 스킬 디렉터리에 두 스킬을 복사한다.
OpenCode의 npm 플러그인 등록과는 다른 설치 방식이다.
npx korean-report-skills # Claude Code · Codex · Cursor
npx korean-report-skills cursor # Cursor만 선택
npx korean-report-skills --project # 현재 프로젝트에 설치
npx korean-report-skills --remove # 복사한 스킬 제거
설치 후 새 세션을 시작하고 스킬 목록에서 korean-report-doc과
korean-report-style을 확인한다. 갱신, 제거, 프로젝트 설치, claude.ai 업로드 절차는
INSTALL.md에 정리되어 있다.
문서 제작과 검수
문서 파일은 다음 순서로 만들어집니다.
자료와 원고
→ Python 생성기와 문서 구조
→ 원시 HTML
→ Node와 KaTeX로 수식 렌더링, CSS 삽입, 자산 내장
→ 자립형 HTML
→ 브라우저 렌더 QA
→ 선택적 PDF와 검수용 스크린샷
문체 검사
korean-report-style의 lint는 Markdown과 HTML의 가시 텍스트를 검사한다.
치환 목록 118건과 제목, 문맥 의존 표현, 어미 규칙을 네 갈래로 구분한다.
| 갈래 | 의미 |
|---|---|
| 고침 | 검증된 어미 활용형이며 --fix로 수정 가능 |
| 검토 | 문맥을 확인한 뒤 선택해야 하는 표현 |
| 제목 | 명사구가 아닌 제목 |
| 의심 | --heuristic에서만 확인하는 문맥 의존 표현 |
검사 결과는 일반 텍스트뿐 아니라 JSON, GitHub annotation, SARIF로도 출력할 수 있다. 의미가 달라질 수 있는 용어나 문맥 의존 표현은 자동으로 수정하지 않는다.
렌더 검사
HTML을 브라우저로 렌더한 뒤에는 다음 항목을 확인한다.
- 수식 marker와 template token의 잔존 여부
- 문서와 표의 가로 넘침
- CSS token과 본문 글꼴 stack 적용
- SVG
viewBoxclipping과 캡션 누락 decksection의 인쇄 페이지 초과
페이지 분할, 과도한 빈 공간, 제목의 고립, 다크 타일의 인쇄 반전처럼 수치만으로 판정하기 어려운 항목은 스크린샷과 PDF를 함께 확인한다.
지원 범위와 현재 한계
문서 제작에는 진행현황, 중간보고, 기술보고, 연구노트, 벤치마크 보고, 협의자료, 회의 아젠다, 제안서가 포함된다. 문체 규칙은 코드베이스 인수인계, 아키텍처 문서, runbook, API reference, 모델 평가, 회의록, 컨소시엄 산출물에도 적용할 수 있다.
현재 범위는 다음과 같다.
- 한국어 기술·사업 문서를 대상으로 한다. 다른 언어의 문체와
layout규칙은 아직 포함하지 않는다. - 제공된 수치와 서술의 정합성은 검사하지만, 입력 자료에 없는 사실이나 근거를 새로 확정하지 않는다.
- 기준 결과물은 자립형 HTML이며, 필요하면 PDF를 함께 만듭니다. 네이티브
.docx와.pptx파일은 생성하지 않는다. - 법률·규제 적합성이나 외부 사실의 정확성을 보증하지 않는다. 기한, 의무, 책임이 포함된 문장은 사용자가 제공한 근거 문서와 대조해야 한다.
본문 글꼴은 사용 권한이 있는 WOFF2 파일을 --font로 지정한 경우에만 HTML에
내장된다. 글꼴을 지정하지 않아도 빌드는 완료되지만 시스템 글꼴을 사용하므로
기기마다 줄바꿈과 페이지 배치가 달라질 수 있다.
필요한 실행 환경
korean-report-style의 문체 규칙에는 추가 런타임 의존성이 없다.
korean-report-doc으로 HTML을 빌드하려면 Node 20 이상과 KaTeX가 필요한다.
렌더 QA, 스크린샷, PDF 출력에는 Python 3.11 이상, Playwright, Chromium이 필요한다.
npm install katex
python3 -m pip install playwright
python3 -m playwright install chromium
소스 저장소에서 직접 실행
이 절은 설치된 플러그인의 사용법이 아니라, 저장소에서 생성기와 빌드 도구를 직접 실행하려는 개발자를 위한 안내이다.
저장소의 Node 의존성은 npm install로 설치한다. 위의 Python 실행 환경을 준비한 뒤
다음 명령으로 문서 뼈대를 만들 수 있다.
npm install
python3 scripts/new-document.py --title "문서 제목" --mode paper
python3 문서_제목.py
생성된 Python 파일에서 본문, 표, 도해를 수정한다. 본문 글꼴을 HTML에 내장하려면 실행할 때 WOFF2 경로를 지정한다.
python3 문서_제목.py --font Pretendard-Regular.woff2 --font Pretendard-SemiBold.woff2
python3 scripts/qa.py 문서_제목.html --pdf --shot shots/
문체 검사와 저장소 회귀 검사는 다음 명령으로 실행할 수 있다.
python3 plugins/korean-report/skills/korean-report-style/assets/lint.py 초안.md
python3 plugins/korean-report/skills/korean-report-style/assets/lint.py 초안.md --fix
npm test
저장소 구조
plugins/korean-report/
skills/
korean-report-doc/
assets/ template, CSS, figures.py, mathbuild.js, qa.py
references/ design·figure 규칙
korean-report-style/
assets/lint.py 문체 검사기
references/ 치환 규칙·software handoff heuristic
.claude-plugin/ Claude Code·Codex marketplace 선언
.opencode/ OpenCode npm plugin adapter
bin/install.js Claude Code·Codex·Cursor file-copy 설치기
scripts/ 생성기, QA, 패키징, 이미지 생성
tests/ 정합성·회귀·end-to-end 검사
문체 규칙은 Markdown 표를 단일 원천으로 사용한다. base.css에는 공통 디자인 token,
paper.css와 deck.css에는 모드별 규칙이 있다. 도해의 SVG class도 같은 token을
사용한다.
새 문체 규칙과 문맥 heuristic은 현재 구조 안에서 추가할 수 있다. 새 출력 모드, 글꼴 정책, 언어 지원을 추가하려면 template, builder, QA, 회귀 검사를 함께 변경해야 한다.
기여와 보안
기여 절차와 회귀 검사 기준은 CONTRIBUTING.md에 있다. 보안 취약점은 공개 issue 대신 Security Advisory로 신고한다. 세부 정책은 SECURITY.md에서 확인할 수 있다.