minorun-marp-skill이 하는 일
minorun-marp-skill은 Marp로 프레젠테이션 슬라이드를 만들기 위한 재사용 가능한 가이드와 검사 도구 모음입니다. 시각적으로 깔끔할 뿐 아니라 명확한 스토리, 유용한 다이어그램, 균형 잡힌 디자인을 갖춘 슬라이드를 AI 에이전트가 작성할 수 있도록 설계되었습니다.
이 프로젝트는 작성자인 Minoru Onda가 반복적으로 활용해 온 프레젠테이션 개선 방법을 정리하고, Claude Code와 같은 AI 에이전트가 읽을 수 있는 스킬로 패키징합니다. Marp Markdown을 직접 작성하는 사람도 이 자료를 바로 활용할 수 있습니다.
저장소 구조
저장소는 작성 가이드, 시각 디자인, 테마, 검증 도구, 예제를 분리해 구성합니다.
skills/slide-story는 도입부, 섹션 시작 슬라이드, 점진적 공개, 헤드라인 스타일, 마무리, 프레젠테이션 길이 추정을 다룹니다.skills/slide-figures는 다이어그램의 정보 밀도를 낮추고, SVG 도형을 그리고, 최소 텍스트 크기를 설정하며, 일러스트를 배치하는 방법을 설명합니다.skills/slide-design-dark는 여백 측정, 수직 균형, 어두운 배경, 표, 코드 블록, Marp 관련 주의 사항을 다룹니다.theme/minorun-dark.css는 청록색 포인트가 적용된 어두운 Marp 테마를 제공합니다.tools/에는 내보낸 PDF와 SVG 출력을 측정하는 스크립트가 들어 있습니다.examples/sample에는 샘플 덱이 들어 있으며,examples/broken에는 검사 도구가 문제를 감지하는지 확인할 수 있도록 의도적으로 문제가 포함되어 있습니다.
설치 및 설정
Claude Code용 스킬 복사
Claude Code를 사용할 때는 세 개의 스킬 디렉터리를 개인 Claude 스킬 디렉터리로 복사합니다.
cp -r skills/* ~/.claude/skills/이제 Claude Code는 슬라이드를 만들거나 수정할 때 저장소의 slide-story, slide-figures, slide-design-dark 가이드를 사용할 수 있습니다.
슬라이드 저장소에 테마와 도구 복사
theme/과 tools/ 디렉터리를 덱이 들어 있는 저장소로 복사합니다. 이렇게 하면 프레젠테이션에 사용하는 Markdown 및 에셋과 테마, 검증 스크립트를 함께 관리할 수 있습니다.
필수 도구 설치
검사 스크립트는 Marp CLI, Google Chrome, poppler, mupdf-tools, Python 3, Pillow에 의존합니다. 다음 명령으로 Marp CLI를 설치합니다.
npm i -g @marp-team/marp-climacOS에서는 다음 명령으로 PDF 유틸리티를 설치합니다.
brew install poppler mupdf-toolscheck-svg-box-fit.mjs는 Marp CLI에 포함된 puppeteer-core를 사용합니다. 해당 모듈이나 Chrome 실행 파일을 자동으로 찾지 못하는 경우 MARP_NODE_MODULES와 CHROME_PATH를 통해 위치를 지정합니다.
글꼴 준비
이 테마는 둥근 고딕 글꼴을 사용하도록 설계되었습니다. Zen Maru Gothic을 설치하면 권장되는 모양으로 표시됩니다. 사용할 수 없는 macOS 시스템에서는 테마가 Hiragino Maru Gothic으로 표시됩니다. 글꼴 사용 가능 여부에 따라 최종 덱의 모양이 달라질 수 있으므로 슬라이드를 내보내기 전에 글꼴을 설치하고 확인하세요.
덱 만들기 및 내보내기
deck.md와 같은 Marp Markdown 파일에 슬라이드를 작성합니다. 포함된 어두운 테마와 로컬 파일 지원을 사용해 PDF로 내보냅니다.
marp --no-stdin deck.md --pdf --theme theme/minorun-dark.css --allow-local-files--theme 옵션은 저장소의 어두운 청록색 포인트 디자인을 적용합니다. --allow-local-files 옵션을 사용하면 내보내는 동안 덱에서 참조하는 로컬 이미지와 기타 에셋을 불러올 수 있습니다.
내보낸 슬라이드 검증
내보낸 후에는 생성된 PDF와 모든 SVG 도형을 대상으로 검사를 실행합니다. 이 검사는 Markdown 소스에서는 놓치기 쉽지만 렌더링된 프레젠테이션에서는 분명하게 드러나는 문제를 찾기 위한 것입니다.
여백 확인
python3 tools/check-dark-margins.py deck.pdf이 검사는 슬라이드 콘텐츠의 아래쪽과 오른쪽 가장자리에 있는 빈 공간을 측정합니다.
요소 사이 간격 확인
python3 tools/check-dark-gaps.py deck.pdf이 검사를 사용하면 다이어그램이나 상자가 주변 텍스트와 지나치게 가까운지 찾을 수 있습니다.
도형 내부 텍스트 확인
python3 tools/check-figure-text.py deck.pdf이 검사는 도형 내부의 작은 텍스트와 상자 가장자리에 지나치게 밀착된 텍스트를 찾습니다.
SVG 상자 맞춤 확인
node tools/check-svg-box-fit.mjs images/*.svg이 검사는 SVG 상자 안의 텍스트가 상자 내부에 맞는지 확인합니다. 도형을 슬라이드 Markdown과 별도로 생성하거나 편집할 때 특히 유용합니다.
재사용 슬라이드 확인
python3 tools/check-reuse-diff.py new.md old.md슬라이드를 재사용할 때 이 비교를 실행합니다. 새 Markdown 파일과 기존 Markdown 파일에서 제목과 도형의 관계를 확인하므로, 재사용한 시각 콘텐츠가 주변 메시지와 더 이상 맞지 않는 경우를 파악하는 데 도움이 됩니다.
일러스트 추가
샘플 프레젠테이션은 Irasutoya의 일러스트를 자주 사용하지만, 해당 이미지는 저장소에 포함되어 있지 않습니다. 샘플 덱을 내보내기 전에 다음 명령으로 다운로드합니다.
sh examples/sample/fetch-illustrations.sh다운로드한 일러스트를 사용하기 전에 적용되는 이용 조건을 직접 확인하세요. 샘플 덱 개요에 표시된 일러스트는 Irasutoya의 저작권 보호를 받는 작품이며, 이 저장소의 Apache License 2.0 적용 대상이 아닙니다.
실용적인 AI 지원 워크플로
- 이야기부터 시작하세요. AI 에이전트에게
slide-story가이드를 사용해 도입부의 핵심, 섹션 전환, 아이디어의 점진적 제시, 헤드라인 스타일, 결말, 예상 발표 시간을 정의하도록 요청하세요. - 도표를 계획하세요.
slide-figures를 사용해 각 다이어그램을 청중에게 필요한 정보로만 축소하고, 읽기 쉬운 텍스트 크기를 선택하며, SVG와 일러스트레이션 중 어떤 방식이 적절한지 결정하세요. - 시각적 시스템을 적용하세요.
slide-design-dark와minorun-dark.css를 사용해 여백, 수직 균형, 어두운 배경과의 대비, 일관된 표 및 코드 스타일을 유지하세요. - 일찍 내보내세요. Markdown 원본이나 편집기 미리보기에만 의존하지 말고 Marp로 PDF를 생성하세요.
- 결과물을 점검하세요. PDF 및 SVG 검사 도구를 실행한 다음, 도표 레이블이 빽빽하거나 여백이 부족하거나 가장자리 사용이 과도한 문제처럼 실제 렌더링에서 발생한 문제를 바탕으로 슬라이드를 수정하세요.
- 발표 전체를 검토하세요. 덱이 일관된 흐름을 갖추었는지, 각 도표가 단순한 장식이 아니라 해당 슬라이드의 헤드라인을 뒷받침하는지 확인하세요.
고급 팁
문제가 있는 예제를 회귀 테스트로 사용하기
examples/broken 디렉터리에는 의도적으로 문제가 있는 덱이 들어 있습니다. 이를 사용해 검사 스크립트가 올바르게 설치되었는지, 그리고 스크립트가 탐지하도록 만들어진 레이아웃 문제에 제대로 대응하는지 확인하세요.
소스 Markdown뿐 아니라 PDF도 검증하기
Marp 렌더링은 소스 코드만으로는 알아채기 어려운 문제를 드러낼 수 있습니다. 글꼴 사용 가능 여부, 박스 크기 계산, 로컬 자산, 최종 페이지 레이아웃으로 인해 발생하는 변경도 여기에 포함됩니다. 내보낸 PDF를 검사해야 할 결과물로 취급하세요.
도표의 텍스트를 읽기 쉽게 유지하기
다이어그램에 정보가 너무 많다면 텍스트를 줄이기보다 먼저 세부 정보를 삭제하거나 나중에 제시하세요. 도표 가이드와 check-figure-text.py를 함께 사용하면 실제 발표 중에도 다이어그램을 읽기 쉽게 유지할 수 있습니다.
제목과 도표를 일치시키기
이전 슬라이드를 재사용한다면 제목과 시각적 설명을 모두 업데이트하세요. 재사용 차이 검사는 슬라이드의 메시지는 바뀌었지만 이전 도표가 그대로 남아 있는 경우를 찾는 데 도움이 됩니다.
라이선스 범위를 기억하기
이 저장소는 Apache License 2.0에 따라 배포되며 저작권자는 Minoru Onda로 표시되어 있습니다. 외부 글꼴과 일러스트레이션에는 별도의 조건이 적용될 수 있으므로 덱을 배포하기 전에 각각의 라이선스를 독립적으로 확인하세요.
결론
minorun-marp-skill은 Marp용 프레젠테이션 조언을 재사용 가능한 AI 에이전트 스킬, 어두운 테마, 예제, 구체적인 결과물 검사 도구로 전환합니다. 스킬을 Claude Code에 복사하고, 테마와 도구를 덱과 함께 배치한 다음, Marp로 내보내고 렌더링된 PDF 및 SVG 파일을 검사하세요. 이 워크플로를 사용하면 슬라이드 완성도를 마지막에 뒤늦게 다듬는 대신, 내러티브와 다이어그램, 시각적 디자인이 함께 작동하도록 유지할 수 있습니다.