beautify-github-readme

무엇인가

beautify-github-readme는 GitHub 저장소의 README를 '읽는 순서'와 '보이는 층위' 두 축에서 다시 설계하는 스킬이다. 규율 대상은 문장 교정이 아니라 정보 배치다. 저장소 안에는 대개 충분한 재료가 이미 있다는 전제에서 출발해, 실제 저장소를 먼저 읽고 가장 선명한 가치와 증거를 식별한 뒤에야 페이지의 형태를 결정한다. 산출물은 두 갈래로 갈린다. 전체 README 모드에서는 히어로, 섹션 전환, 비교 도표, 실제 채택 사례, 설치 안내를 하나의 흐름으로 재구성한다. 자산 전용 모드에서는 README 본문을 건드리지 않고 히어로·섹션 헤더·워크플로·배지·모션 그래픽 가운데 필요한 것만 만든다. 두 모드 모두 설명·명령·링크·설정은 Markdown으로 남겨 검색과 복사가 가능하게 유지한다. 즉 이 스킬이 다루는 것은 디자인 자산 생성과 문서 구조 편집이며, 그 둘의 경계를 명시적으로 분리하는 것이 핵심 규칙이다.

어떻게 동작하나

이 규칙이 없으면 에이전트는 README를 '있는 그대로 예쁘게' 만드는 쪽으로 간다. 결과는 대개 세 가지 실패로 나타난다. 첫째, 순서 실패다. 방문자가 프로젝트가 무엇인지 이해하기 전에 내부 용어, 설치 명령, 디렉터리 트리, 기여 절차가 먼저 나온다. 둘째, 템플릿 실패다. CLI 도구와 아이콘 세트와 연구 저장소가 같은 레이아웃을 받는다. 명령 리듬이 어울릴 프로젝트에 좌표·차트·증거 라벨이 붙고, 반대의 경우도 생긴다. 셋째, 이미지화 실패다. 페이지 전체를 한 장의 래스터 이미지로 굽는 방식은 검색도 복사도 유지보수도 불가능하게 만든다. 이 스킬은 세 실패를 각각 다른 규칙으로 막는다. 순서는 '먼저 읽고 나중에 결정한다'로, 템플릿은 '프로젝트 자체에서 타이포·색·구도·증거를 끌어낸다'로, 이미지화는 '시각 층과 내용 층을 분리한다'로 대응한다.

무엇과 다른가

설계 원리는 시각 층과 내용 층의 분리다. GitHub README는 웹사이트 같은 레이아웃 자유도가 없으므로, 각 형식에 역할을 하나씩 배정한다. SVG는 편집 가능한 히어로, 섹션 전환, 비교, 다이어그램, 아이덴티티를 맡는다. 하이브리드 SVG 구성은 결정적으로 배치 가능한 SVG 레이아웃에 선택적으로 AI 생성·배경 제거된 피사체를 얹어 캐릭터, 유기적 질감, 복잡한 재질, 영화적 조명을 처리한다. GIF는 승인된 모션만 담당하고, 정적 SVG는 편집 가능한 대체물로 남는다. 모션은 기본값이 아니라 명시적으로 켠 경우에만 생성된다. PNG/WebP는 스크린샷, 생성 아트워크, 복잡한 쇼케이스 월에 쓴다. Markdown은 설명, 명령, 링크, 설정, 기여 안내를 담당한다. 이 배정이 하드 제약인 이유는 형식이 바뀌는 순간 검색·복사·유지보수 가능성이 사라지기 때문이다. 프로세스 차원의 세 가지 약속도 같은 성격의 제약이다. 실제 프로젝트 재료만 사용하고, 없는 기능을 만들지 않으며, 명시적 승인 없이는 게시하지 않는다.

어떻게 쓰나

발동은 두 개의 명시적 모드로 갈린다. 요청에 범위가 이미 적혀 있으면 스킬은 곧바로 시작한다. 사용자가 '이 저장소 좀 예쁘게 해줘'라고만 하거나 저장소 URL만 주면 에이전트는 먼저 묻는다. 전체 README를 개선할지, 시각 자산만 만들지를 확인하고, 자산 전용이라면 히어로·섹션 헤더·워크플로·배지·모션 그래픽·조합 세트 중 무엇이 필요한지 되묻는다. 호출은 슬래시 형태의 스킬 참조로 이뤄진다. 전체 README 모드에서는 실제 프로젝트 테마를 기준으로 홈페이지를 재설계하고 로컬 미리보기를 먼저 보여주며 푸시하지 않는다. 자산 전용 모드에서는 README를 그대로 두고 SVG 원본과 함께 애니메이션 GIF 히어로 하나를 만들고 렌더링된 미리보기를 먼저 제시한다. 읽기 전용 감사 요청도 별도로 존재한다. 이때는 명확성·위계·신뢰·유지보수 비용만 점검하고 파일을 편집하지 않는다. 문맥 파악을 위해 README를 읽는 행위는 편집 권한을 부여하지 않는다는 점이 명시적 규칙이다. 자산 전용 모드에서 새 자산을 README에 삽입하려면 별도의 명시적 승인이 필요하다.

전제와 한계

내부 구성은 재사용 가능한 제작 지침 네 문서로 나뉜다. "Designing a project-native hero"는 프로젝트 고유의 히어로를 설계하는 절차를, "Writing GitHub-safe README SVGs"는 GitHub에서 깨지지 않는 SVG 작성 규칙을, "Composing SVG with generated raster material"은 결정적 SVG 레이아웃과 생성 래스터 재료를 합성하는 방법을, "Producing GitHub-safe README motion"은 GitHub에서 안전한 모션 제작을 담당한다. 전체 README 모드는 세 층위에 걸쳐 작동한다고 명시되어 있다. 산출물 목록도 모드별로 고정된다. 전체 모드는 로컬 미리보기, 시각 자산, README diff를 내놓고, 자산 전용 모드는 소스 자산, 렌더링된 미리보기, 선택적 GIF 파생물, 임베드 스니펫을 내놓는다. 저장소 자체의 README도 작업 예시로 기능하며, 프로젝트 고유 히어로와 테마 월, 실제 채택 증거, 섹션 전환을 조합해 보여준다.

프롬프트를 매번 직접 쓰는 방식과의 차이는 재현성이다. 일회성 지시는 저장소마다 다른 결과를 낳고, 어떤 순서 규칙이 적용됐는지 남지 않는다. CLAUDE.md 같은 일반 규칙 파일과 비교하면 이 스킬은 시각 층과 내용 층의 분리, 승인 게이트, 모드 분기를 규칙으로 고정한다는 점이 다르다. 고정 템플릿형 도구와는 반대 방향이다. 템플릿은 같은 레이아웃을 모든 저장소에 적용하지만, 이 스킬은 타이포·색·구도·증거를 프로젝트 자체에서 끌어낸다. 저장소가 제시하는 사례들이 이를 뒷받침한다. oil-ppt는 시각 시스템 하나로 방법·결과·첫 사용 경로를 묶고, draw-ui는 실제 UI 출력으로 브리프에서 HTML/CSS 재구성까지의 경로를 설명하며, oil-icon은 실제 아이콘 세트로 스타일 고정·배치 생성·슬라이싱·투명 전달을 다룬다. codex-dev-team은 캐릭터 팀 맵으로 위임 구조를, torqueDASH-Next는 OBD-II PID 데이터가 담긴 SVG 히어로와 실제 대시보드 스크린샷을 쓴다. summertown은 해안 지도 히어로를, Wolfcha는 SVG 타이포와 AI 생성 캐릭터 컷아웃을 결합한다. 하나의 하우스 스타일을 공유하지 않는다는 점이 명시되어 있다.

설치 경로는 두 가지다. 명령줄에서는 npx skills add oil-oil/beautify-github-readme를 실행한다. 또는 에이전트에 저장소 URL과 함께 설치를 요청하는 문장을 그대로 전달한다. 첫 사용에서 확인할 것은 세 가지다. 첫째, 요청에 범위가 없으면 에이전트가 전체 README와 자산 전용 중 무엇인지, 자산 전용이라면 어떤 종류가 필요한지 먼저 묻는지. 둘째, 편집 전에 로컬 미리보기가 먼저 제시되고 푸시가 일어나지 않는지. 셋째, 자산 전용 모드에서 새 자산을 README에 삽입할 때 별도 승인을 요구하는지다. 커밋, 푸시, PR, 게시는 어떤 모드에서도 항상 명시적 승인을 받아야 한다. 편집 없이 점검만 원하면 읽기 전용 감사를 요청할 수 있고, 이때는 명확성·위계·신뢰·유지보수 비용만 보고된다.

지원 대상은 Claude Code다. Markdown과 SVG 자체에는 계정이나 API 키가 필요 없다. 래스터 생성 단계의 조건은 README 하단의 의존성 절에서 따로 다룬다. 모션은 기본값이 아니며 명시적으로 요청한 경우에만 생성된다. 정적 SVG는 모션이 있는 경우에도 편집 가능한 대체물로 남는다. 명시적으로 안 되는 것도 분명하다. 없는 기능을 만들어 넣을 수 없고, 실제 프로젝트 재료가 아닌 것을 증거로 쓸 수 없으며, 승인 없이 게시할 수 없다. 문맥 파악을 위해 README를 읽는 행위는 편집 권한을 부여하지 않는다. 자산 전용 모드에서 README 본문은 그대로 유지되며, 임베드도 자동으로 일어나지 않는다. 저장소 목록에 사례를 제안하는 것은 선택 사항이고 유지관리자 검토를 거친다.

선택 기준은 조건으로 갈린다. 저장소에 재료는 충분한데 방문자가 가치를 이해하기 전에 내부 용어와 설치 명령을 먼저 만난다면 전체 README 모드가 맞다. 문서 구조는 그대로 두고 히어로나 섹션 헤더, 배지, 모션 그래픽만 필요하다면 자산 전용 모드가 맞다. 파일을 건드리지 않고 명확성과 유지보수 비용만 진단하고 싶다면 읽기 전용 감사가 맞다. 반대로 페이지 전체를 한 장의 이미지로 굽는 결과를 원한다면 이 스킬은 맞지 않는다. 검색과 복사가 불가능해지는 것을 규칙으로 막기 때문이다. 문장 표현만 다듬고 싶거나, 저장소에 증거로 쓸 실제 산출물이 아직 없다면 시각 재설계보다 먼저 그 재료를 만드는 편이 낫다. 프로젝트마다 다른 스타일이 나오는 것을 원하지 않고 하나의 고정 레이아웃을 원한다면 템플릿 쪽이 더 빠르다.