plannotator/effective-html 딥다이브
— 스킬 3개로 배우는 "HTML을 AI의 출력 포맷으로 쓰는 법"

1프로젝트 한줄 요약

이 레포가 무엇을 하는 물건인가.

effective-html은 html, html-diagram, html-plan 세 개의 에이전트 스킬을 담은 저장소다. 각 스킬은 에이전트(Claude Code 등)에게 "사용자가 원하는 것을 의존성 없는 단일 .html 파일로, 정해진 'effective HTML' 스타일에 맞춰 만들어라"라고 지시한다. 세 스킬의 차이는 의도다 — html은 범용(리포트·설명·비교·덱), html-diagram은 SVG 아키텍처 다이어그램 전용, html-plan은 계획서 페이지 전용.

이 레포의 진짜 자산은 각 스킬에 번들된 레퍼런스 코퍼스다. Thariq Shihipar가 쓴 글 "The unreasonable effectiveness of HTML(HTML의 비합리적 효과)"에 딸린 예제 20개(코드리뷰·디자인시스템·슬라이드덱·상태리포트·인시던트리포트·플로차트 등)를 통째로 넣어, 에이전트가 추상적 지시가 아니라 "잘된 결과물 20개를 보고 그 밀도·톤·정렬을 흉내"내도록 했다. 그래서 두 갈래로 읽힌다. ① 스킬 엔지니어링(에이전트 시대의 새로운 "코딩"), ② 프런트엔드 공예(빌드도 프레임워크도 없이 HTML·CSS·SVG만으로 완성도 내기).

2왜 주목받는가

트렌딩 이유 · 경쟁 접근 대비 장점.

2026년 들어 "에이전트가 마크다운으로만 답하는 건 손해다"라는 인식이 퍼졌다. 마크다운은 제목·목록·표까지가 한계지만, HTML은 같은 한 파일에 다이어그램·색·레이아웃·인터랙션·다크모드를 전부 담는다. 이 "HTML의 비합리적 효과"라는 밈을 실전 스킬로 떨어뜨린 게 effective-html이라서, 별·포크 규모(★30)는 작아도 에이전트 스킬 생태계에서 빠르게 회자됐다. 차별점은 넷이다.

3기술 스택 전체 지도

스킬 레포는 "산출물 스택 / 스킬 런타임 / 배포"의 3층으로 본다.

이 레포에는 서버도 DB도 없다. 그래서 흔한 "백엔드/프론트엔드/인프라" 대신, 스킬형 저장소에 맞는 3층으로 지도를 다시 그리는 게 정확하다.

① 산출물 스택 — "의존성 0"이 핵심

레퍼런스 예제와 모범 architecture-example.html은 전부 다음만 쓴다.

• HTML5 + 인라인 <style>/<script> — 한 파일에 전부. 빌드 없음.
• CSS 커스텀 프로퍼티(--bg, --ink, --clay…) — 라이트/다크 두 팔레트를 변수로만 스왑.
• SVG(인라인) — 다이어그램은 이미지가 아니라 코드. CSS 클래스로 스타일링해 테마를 따라감.
• Vanilla JS — 테마 토글, 노드 클릭, 흐름(flow) 애니메이션. 라이브러리 0개.

② 스킬 런타임 — frontmatter가 계약서

각 SKILL.md 맨 위 YAML이 에이전트와의 계약이다. name(스킬 ID), description(언제 쓰는지 — 매칭용 항상 로드), disable-model-invocation(자동발동 여부). 본문은 평소엔 안 읽히다가 스킬이 선택돼야 펼쳐진다(점진적 공개).

③ 배포 — 두 채널을 동시에 지원

skills.sh.json은 skills.sh 레지스트리용(그룹 "Effective HTML"로 3개 묶음), .claude-plugin/plugin.json은 Claude Code 플러그인용(스킬 경로 3개 등록). 같은 레포가 두 생태계에 동시에 설치된다.

# skills.sh로 설치 (npx 한 줄)
npx skills add plannotator/effective-html
npx skills add plannotator/effective-html --list
npx skills add plannotator/effective-html --skill html-diagram

4아키텍처 심화 분석

스킬이 발동되는 흐름 + 모범 다이어그램의 내부.

4-1. 스킬 발동 파이프라인

사용자가 스킬을 지목하면, 에이전트는 frontmatter→본문→레퍼런스 순으로 "필요한 만큼만" 읽어 HTML을 만든다.

4-2. 모범답안 architecture-example.html 해부

이 한 파일(462줄)이 html-diagram이 지향하는 "잘된 결과물"의 표본이다. 구조를 뜯어보면 4가지 기법이 보인다.

5디렉토리 구조 해부

파일이 적다 — 그래서 하나하나가 의미를 갖는다.

6학습 포인트 (기술별)

이 레포 하나로 두 분야를 동시에 챙긴다 — 스킬 설계 + HTML 공예.

① 스킬 엔지니어링

가장 큰 배움은 "기능을 코드가 아니라 frontmatter + 예시로 정의"하는 법이다. 좋은 description은 "무엇을 하는가"가 아니라 "언제 이걸 골라야 하는가"를 적는다(이 레포의 description들이 전부 "Use when the user wants…" 꼴인 이유). 본문은 짧게, 깊이는 references로 — 점진적 공개.

② 다크모드 3종 세트 (모든 산출물 공통 규칙)

세 SKILL.md가 똑같이 강제하는 패턴 — 이걸 손에 익히면 어떤 정적 HTML에도 쓸 수 있다.

<!-- (1) head 최상단: 그려지기 전에 테마 선적용 → FOUC 방지 -->
<script>
  (function(){
    const saved = localStorage.getItem('theme');
    const dark = saved ? saved==='dark'
                       : matchMedia('(prefers-color-scheme: dark)').matches;
    document.documentElement.classList.toggle('dark', dark);
  })();
</script>

/* (2) CSS: 두 팔레트를 변수로만 정의 */
:root      { --bg:#FAF9F5; --ink:#141413; }
html.dark  { --bg:#141413; --ink:#FAF9F5; }

// (3) 토글 버튼: 클래스 토글 + localStorage 저장
themeToggle.onclick = () => {
  const dark = document.documentElement.classList.toggle('dark');
  localStorage.setItem('theme', dark ? 'dark' : 'light');
};

③ SVG로 "코드인 다이어그램" 만들기

이미지 캡처가 아니라 viewBox 좌표계 위에 <g class="node">로 그리면, 텍스트 검색·테마 추종·클릭 인터랙션이 공짜로 따라온다. html-diagram의 핵심 학습 포인트.

④ 두 채널 배포(skills.sh + Claude Code plugin)

같은 디렉토리를 skills.sh.json과 .claude-plugin/plugin.json 두 매니페스트로 노출하는 법. 자작 스킬을 남들이 npx skills add 한 줄로 받게 하는 패키징 감각을 익힌다.

7시스템 요구사항 & 설치

무겁지 않다 — Node와 에이전트, 브라우저면 끝.

# 전체 설치
npx skills add plannotator/effective-html

# 먼저 어떤 스킬이 있는지 보기
npx skills add plannotator/effective-html --list

# 특정 스킬만 설치
npx skills add plannotator/effective-html --skill html-diagram
npx skills add plannotator/effective-html --skill html-plan

Claude Code 플러그인으로 쓸 땐 .claude-plugin/plugin.json이 ./skills/html, ./skills/html-diagram, ./skills/html-plan 세 경로를 등록하므로, 레포를 플러그인으로 추가하면 세 스킬이 한꺼번에 붙는다. 발동은 disable-model-invocation: true 때문에 항상 사용자가 명시해야 한다("html-diagram 스킬로 그려줘").

8직접 해볼 수 있는 실습 과제

읽기만 하지 말고, 난이도순으로 손을 움직여 보자.

9관련 기술 심화 학습 로드맵

4주 코스 — 스킬 설계와 HTML 공예를 번갈아 다진다.

10핵심 키워드 사전

이 레포를 읽다 마주치는 용어들.

11참고 링크

원본과 더 깊이 파고들 자료.

프로젝트 원본

· GitHub 저장소: github.com/plannotator/effective-html
· 제작자 사이트: plannotator.ai
· 설치: npx skills add plannotator/effective-html

지식의 출처

· Thariq Shihipar — html-effectiveness 갤러리: thariqs.github.io/html-effectiveness
· "The unreasonable effectiveness of HTML" — HTML을 AI 출력 포맷으로 쓰자는 원 아이디어의 출처

에이전트 스킬 배경

· Claude Code 스킬 문서: docs.claude.com/en/docs/claude-code/skills
· Anthropic — Agent Skills 소개: anthropic.com/news/skills
· skills.sh — 스킬 설치/배포 도구: skills.sh