visual-explainer
무엇인가
터미널 출력물을 읽을 수 있는 시각 자료로 바꾸는 출력 형식을 규율한다. 에이전트가 시스템 아키텍처 설명, 디프 리뷰, 요구사항 대비 계획 비교, 프로젝트 회고를 요청받았을 때 박스 문자·모노스페이스 정렬·텍스트 화살표 대신 자체 완결형 HTML 페이지나 슬라이드 덱을 생성하도록 강제한다. 다이어그램, 디프 리뷰, 계획 감사, 데이터 표, 회고라는 다섯 가지 산출 유형이 규칙의 적용 대상이다.
어떻게 동작하나
구성은 정본 SKILL.md와 commands 디렉터리의 슬래시 명령 템플릿이다. /diff-review, /plan-review, /generate-web-diagram, /fact-check, /generate-slides, /generate-visual-plan, /project-recap이 번들로 제공된다. Pi 확장은 네이티브 visual_explainer 도구 하나를 등록하며 action: "prepare"로 시각 설명 계획을 세우고, action: "render"로 완성된 HTML을 ~/.agent/diagrams/에 기록하며, opt-in action: "render_quick"은 압축 JSON 스펙을 검증해 번들 로컬 렌더러로 그린다. 렌더 시 viewer: "browser"가 기본이고 glimpseui 설치 시 "glimpse", "auto"는 Glimpse를 시도한 뒤 브라우저로 폴백한다. MCP 서버는 visual_explainer_prepare, visual_explainer_render_html, visual_explainer_render_quick 세 도구와 명령 템플릿 프롬프트, SKILL.md·명령 마크다운·quick README·quick 스키마 리소스를 노출한다.
무엇과 다른가
프롬프트를 직접 쓰거나 CLAUDE.md·AGENTS.md에 규칙 문장을 넣는 방식과 구조적으로 다르다. 그쪽은 출력 형식을 문장으로 지시할 뿐 렌더러·템플릿·출력 경로를 함께 주지 않지만, 이 스킬은 명령 템플릿과 로컬 렌더러, stdio MCP 서버를 패키지로 배포해 생성·검증·열기 단계를 고정한다. 일반 사용에는 빌드 단계가 없고 브라우저 외 의존성이 없으며, MCP와 PPTX 유틸리티만 소규모 Node 의존성을 쓴다.
어떻게 쓰나
설치는 Claude Code 마켓플레이스에서 /plugin marketplace add nicobailon/visual-explainer 후 /plugin install visual-explainer@visual-explainer-marketplace로 한다. Claude Code는 명령을 /visual-explainer:command-name으로 네임스페이스화한다. Pi는 pi install git:github.com/nicobailon/visual-explainer 또는 로컬 체크아웃에 pi install ./visual-explainer를 쓴다. MCP 호스트는 visual-explainer-mcp 바이너리나 체크아웃의 plugins/visual-explainer/mcp/server.mjs 절대 경로를 지정한다. Antigravity CLI는 플러그인 디렉터리를 ~/.gemini/antigravity-cli/skills/visual-explainer로 복사한다. 첫 사용은 "draw a diagram of our authentication flow" 같은 요청이나 /diff-review, /plan-review ~/docs/refactor-plan.md 호출이다.
전제와 한계
브라우저가 있어야 렌더 결과를 확인할 수 있다. MCP 서버는 로컬 stdio 전용이며 LLM을 호출하지 않고 HTTP 리스너를 열지 않으며 자격증명을 다루지 않고 설정된 출력 디렉터리 밖에 쓰지 않는다. VISUAL_EXPLAINER_OUTPUT_DIR로 출력 jail을 같은 머신의 다른 디렉터리로 옮길 수 있고, 심볼릭 링크로 해석되는 jail 경로는 거부되며 기존 심볼릭 링크를 가리키는 렌더 대상도 거부되고 임시 파일 rename으로 기록된다. 이전 curl 수동 설치본을 지우지 않고 pi install을 쓰면 사용자 레벨 복사본이 패키지 리소스를 가려 스킬·프롬프트 충돌이 보고된다.